Run PowerShell Clinic from your own code

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

Runs on: <Windows PowerShell 5.1|PowerShell 7|both 5.1 and 7>.
Prescan verdict: <ship|refactor|rework> (<n> errors, <n> warnings, <n> notes).
Review findings (PW-): <n> errors, <n> warnings. Security findings (PS-): <n> errors, <n> warnings.
Interface to keep: parameters <$Name, ...|(none)>; functions <Name, ...|(none)>.
Clipped: <only when the code was clipped>
Findings (rule | severity | line | text):
- <rule id> | <error|warn|info> | line <n> | <title>< (note)> | <the source line>

Runs on: Windows PowerShell 5.1.
Prescan verdict: rework (1 error, 3 warnings, 2 notes).
Review findings (PW-): 1 error, 3 warnings. Security findings (PS-): 0 errors, 0 warnings.
Interface to keep: parameters $Source, $Target; functions (none).
Findings (rule | severity | line | text):
- PW-OPPAREN | error | line 7 | Cmdlet call not in parentheses next to -and / -or | if (Test-Path $Source -and Test-Path $Target) {
- PW-STRICT | warn | line 1 | No Set-StrictMode | param(
- PW-NULLRIGHT | warn | line 10 | $null on the right of a comparison | if ($items -eq $null) { exit 0 }
- PW-JSONDEPTH | warn | line 11 | ConvertTo-Json without -Depth | $items | Select-Object Name, Length | ConvertTo-Json | Out-File (Join-Path $Target manifest.json)
- PS-NOVALIDATE | info | line 1 | Parameters without validation | param(
- PW-OUTENC | info | line 11 | File written without -Encoding | $items | Select-Object Name, Length | ConvertTo-Json | Out-File (Join-Path $Target manifest.json)

{
  "task": "review",
  "verdict": "refactor",
  "summary": "",
  "findings": [ { "rule": "PW-OPPAREN", "severity": "high", "title": "", "where": "line 10", "why": "", "fix": "" } ],
  "prescan": [ { "rule": "PW-OPPAREN", "call": "agree", "note": "" } ],
  "rewrite": { "name": "backup.ps1", "code": "" },
  "kept": [ { "rule": "", "what": "", "why": "" } ],
  "caveats": [ "" ]
}

{
  "task": "harden",
  "verdict": "rework",
  "summary": "",
  "findings": [ { "rule": "PS-PLAINCRED", "severity": "high", "title": "", "where": "line 9", "why": "", "fix": "" } ],
  "prescan": [ { "rule": "PS-PLAINCRED", "call": "agree", "note": "" } ],
  "rewrite": { "name": "provision.ps1", "code": "" },
  "secrets": [ { "name": "", "for": "" } ],
  "run": "",
  "kept": [ { "rule": "", "what": "", "why": "" } ],
  "caveats": [ "" ]
}

{
 "task": "review",
 "code": "param(\n    [string]$Source,\n    [string]$Target\n)\n\n$items = Get-ChildItem $Source -Recurse\nif (Test-Path $Source -and Test-Path $Target) {\n    Copy-Item $Source $Target -Recurse\n}\nif ($items -eq $null) { exit 0 }\n$items | Select-Object Name, Length | ConvertTo-Json | Out-File (Join-Path $Target manifest.json)",
 "shell": "5.1",
 "facts": "Runs on: Windows PowerShell 5.1.\nPrescan verdict: rework (1 error, 3 warnings, 2 notes).\nReview findings (PW-): 1 error, 3 warnings. Security findings (PS-): 0 errors, 0 warnings.\nInterface to keep: parameters $Source, $Target; functions (none).\nFindings (rule | severity | line | text):\n- PW-OPPAREN | error | line 7 | Cmdlet call not in parentheses next to -and / -or | if (Test-Path $Source -and Test-Path $Target) {\n- PW-STRICT | warn | line 1 | No Set-StrictMode | param(\n- PW-NULLRIGHT | warn | line 10 | $null on the right of a comparison | if ($items -eq $null) { exit 0 }\n- PW-JSONDEPTH | warn | line 11 | ConvertTo-Json without -Depth | $items | Select-Object Name, Length | ConvertTo-Json | Out-File (Join-Path $Target manifest.json)\n- PS-NOVALIDATE | info | line 1 | Parameters without validation | param(\n- PW-OUTENC | info | line 11 | File written without -Encoding | $items | Select-Object Name, Length | ConvertTo-Json | Out-File (Join-Path $Target manifest.json)",
 "focus": ""
}

{
 "task": "review",
 "verdict": "rework",
 "summary": "The script copies Source to Target and writes a JSON manifest of the copied items. Verdict rework: Test-Path $Source -and Test-Path $Target is parsed as one Test-Path call with -and as an argument, so the copy guard does not test what it reads as. Fix that first with ((Test-Path $Source) -and (Test-Path $Target)) ...",
 "findings": [
  {
   "rule": "PW-OPPAREN",
   "severity": "high",
   "title": "Cmdlet calls next to -and without parentheses",
   "where": "line 7",
   "why": "Without parentheses the second Test-Path and -and become arguments of the first call ...",
   "fix": "if ((Test-Path $Source) -and (Test-Path $Target)) {"
  },
  {
   "rule": "PW-NULLRIGHT",
   "severity": "medium",
   "title": "$null on the right of -eq",
   "where": "line 10",
   "why": "With an array on the left, -eq filters the array instead of testing it ...",
   "fix": "if ($null -eq $items) { exit 0 }"
  },
  {
   "rule": "PW-JSONDEPTH",
   "severity": "medium",
   "title": "ConvertTo-Json without -Depth",
   "where": "line 11",
   "why": "The default depth of 2 flattens nested values to type names ...",
   "fix": "ConvertTo-Json -Depth 5 | Out-File (Join-Path $Target manifest.json) -Encoding UTF8"
  },
  {
   "rule": "PW-STRICT",
   "severity": "low",
   "title": "No strict mode",
   "where": "line 1",
   "why": "A typo in a variable name reads as $null instead of failing ...",
   "fix": "Set-StrictMode -Version Latest"
  }
 ],
 "prescan": [
  {
   "rule": "PW-OPPAREN",
   "call": "agree",
   "note": "Line 7 passes -and and the second Test-Path to the first call ..."
  },
  {
   "rule": "PW-STRICT",
   "call": "agree",
   "note": "Nothing turns on strict mode ..."
  },
  {
   "rule": "PW-NULLRIGHT",
   "call": "agree",
   "note": "Line 10 compares with $null on the right ..."
  },
  {
   "rule": "PW-JSONDEPTH",
   "call": "agree",
   "note": "Line 11 serializes without -Depth ..."
  }
 ],
 "rewrite": {
  "name": "copy.ps1",
  "code": "param(\n    [string]$Source,\n    [string]$Target\n)\nSet-StrictMode -Version Latest\n$ErrorActionPreference = 'Stop'\n\n$items = Get-ChildItem $Source -Recurse\nif ((Test-Path $Source) -and (Test-Path $Target)) {\n..."
 },
 "kept": [
  {
   "rule": "PS-NOVALIDATE",
   "what": "The parameters have no validation attributes.",
   "why": "A harden-lane note; the harden pass is the place for it ..."
  }
 ],
 "caveats": [
  "Nothing was run; try it with -WhatIf on Copy-Item first ..."
 ]
}

const S = PwScan, R = PwReply;
const st = { code: fs.readFileSync("copy.ps1", "utf8"), shell: "5.1", focus: "" };
const scan = S.scan(st);                        // findings, counts, byLane, verdict, shape (params, functions)
const b = S.buildInput(st, "review");           // or "harden"; clips long files and writes the facts
const wire = S.toWire(b.input);                 // every field a string - POST this to /estimate and /run
// then: const reply = R.normalize(R.parseReply(job.output.output), "review");
// R.check(reply, b)                            // {notes, warn}: anything the reply missed or got wrong

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"   # from https://pwsh-clinic.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"pwsh-clinic"}' | jq -r '.data.token')

api GET /me | jq '.data | {subject_type, credits}'

# input.json: the run input object - {"task": "review", "code": "param( ...", "shell": "5.1", "facts": "Runs on: Windows PowerShell 5.1. ...", "focus": ""}
# - see the input table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="pwsh-clinic:$(jq -r .task input.json):$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'
jq -r '"verdict: \(.verdict)", .summary, (.findings[] | "[\(.severity)] \(.title)"),
  (if .task == "harden" then (.secrets[]? | "Set-Secret -Name \(.name)   # \(.for)"), "run: \(.run)" else empty end)' reply.json

# SSE: tick/delta messages while the job runs, then a final message with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: pwsh-clinic:$(jq -r .task input.json):$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json