MCP App Clinic — API

export API="https://api.skillsafe.ai/v1/app-api"
export TOKEN="YOUR_TOKEN"      # see step 1

# every call looks like:
#   curl -s "$API/..." -H "Authorization: Bearer $TOKEN" [-d '{json}']
# jq is used below to pull fields out of the {"data": ...} envelope

import json, requests

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"  # see step 1 — read it from your shell environment in real code

def api(method, path, body=None, **headers):
    res = requests.request(method, API + path, json=body,
                           headers={"Authorization": f"Bearer {TOKEN}", **headers})
    payload = res.json()
    if not res.ok:
        raise RuntimeError(payload.get("error", {}).get("message", res.reason))
    return payload["data"]

// Node 18+ (built-in fetch)
const API = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN"; // see step 1 — read it from your shell environment in real code

async function api(method, path, body, extraHeaders = {}) {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json", ...extraHeaders },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? res.statusText);
  return json.data;
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const API = "https://api.skillsafe.ai/v1/app-api"

var token = os.Getenv("SKILLSAFE_TOKEN") // see step 1

func call(method, path string, body, out any) error {
	var buf bytes.Buffer
	if body != nil {
		json.NewEncoder(&buf).Encode(body)
	}
	req, _ := http.NewRequest(method, API+path, &buf)
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	var env struct {
		Data  json.RawMessage `json:"data"`
		Error *struct{ Message string `json:"message"` } `json:"error"`
	}
	json.NewDecoder(res.Body).Decode(&env)
	if res.StatusCode >= 400 {
		return fmt.Errorf("api %s %s: %s", method, path, env.Error.Message)
	}
	if out == nil {
		return nil
	}
	return json.Unmarshal(env.Data, out)
}

// Java 17+, no dependencies. Pair with your JSON library (Jackson, Gson…)
// to read fields out of the returned envelope.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SkillSafe {
    static final String API = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = System.getenv("SKILLSAFE_TOKEN"); // see step 1
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String api(String method, String path, String jsonBody) throws Exception {
        var req = HttpRequest.newBuilder(URI.create(API + path))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method(method, jsonBody == null
                ? HttpRequest.BodyPublishers.noBody()
                : HttpRequest.BodyPublishers.ofString(jsonBody))
            .build();
        var res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) throw new RuntimeException(res.body());
        return res.body(); // envelope: {"data": …}
    }
}

require "net/http"
require "json"

API = "https://api.skillsafe.ai/v1/app-api"
TOKEN = ENV.fetch("SKILLSAFE_TOKEN") # see step 1

def api(method, path, body = nil)
  uri = URI(API + path)
  req = Net::HTTP.const_get(method.capitalize).new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"] = "application/json"
  req.body = body.to_json if body
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
  payload = JSON.parse(res.body)
  raise (payload.dig("error", "message") || res.message) unless res.is_a?(Net::HTTPSuccess)
  payload["data"]
end

<?php
const API = "https://api.skillsafe.ai/v1/app-api";
$TOKEN = getenv("SKILLSAFE_TOKEN"); // see step 1

function api(string $method, string $path, ?array $body = null): mixed {
    global $TOKEN;
    $ch = curl_init(API . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer $TOKEN",
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS     => $body === null ? null : json_encode($body),
    ]);
    $payload = json_decode(curl_exec($ch), true);
    $status  = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);
    if ($status >= 400) {
        throw new Exception($payload["error"]["message"] ?? "HTTP $status");
    }
    return $payload["data"];
}

// .NET 8+
using System.Net.Http.Json;
using System.Text.Json;

static class SkillSafe
{
    const string Api = "https://api.skillsafe.ai/v1/app-api";
    static readonly HttpClient Http = new();

    static SkillSafe() =>
        Http.DefaultRequestHeaders.Authorization =
            new("Bearer", Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN")); // see step 1

    public static async Task<JsonElement> ApiAsync(HttpMethod method, string path, object? body = null)
    {
        var req = new HttpRequestMessage(method, Api + path);
        if (body != null) req.Content = JsonContent.Create(body);
        var res = await Http.SendAsync(req);
        var json = await res.Content.ReadFromJsonAsync<JsonElement>();
        if (!res.IsSuccessStatusCode)
            throw new Exception(json.GetProperty("error").GetProperty("message").GetString());
        return json.GetProperty("data");
    }
}

curl -s -X POST "$API/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"mcp-app-clinic"}' | jq -r '.data.token'

token = api("POST", "/guest", {"slug": "mcp-app-clinic"})["token"]

const { token } = await api("POST", "/guest", { slug: "mcp-app-clinic" });

var guest struct{ Token string `json:"token"` }
err := call("POST", "/guest", map[string]string{"slug": "mcp-app-clinic"}, &guest)

String envelope = api("POST", "/guest", """
    {"slug":"mcp-app-clinic"}""");
// token is at data.token in the returned JSON

token = api("POST", "/guest", { slug: "mcp-app-clinic" })["token"]

$token = api("POST", "/guest", ["slug" => "mcp-app-clinic"])["token"];

var guest = await SkillSafe.ApiAsync(HttpMethod.Post, "/guest",
    new { slug = "mcp-app-clinic" });
var token = guest.GetProperty("token").GetString();

curl -s "$API/me" -H "Authorization: Bearer $TOKEN" | jq '.data'

me = api("GET", "/me")
print(me["subject_type"], me["credits"])

const me = await api("GET", "/me");
console.log(me.subject_type, me.credits);

var me struct {
	SubjectType string `json:"subject_type"`
	Credits     int64  `json:"credits"`
}
err := call("GET", "/me", nil, &me)

String envelope = api("GET", "/me", null);
// data.subject_type, data.credits

me = api("GET", "/me")
puts "#{me["subject_type"]}: #{me["credits"]} credits"

$me = api("GET", "/me");
echo "{$me['subject_type']}: {$me['credits']} credits\n";

var me = await SkillSafe.ApiAsync(HttpMethod.Get, "/me");
Console.WriteLine($"{me.GetProperty("subject_type")}: {me.GetProperty("credits")} credits");

cat > app.ts <<'CODE'
// file: server.ts
server.registerTool("show_board", {
  _meta: { "openai/outputTemplate": "ui://widget/board.html" },
}, showBoard);

// file: web/src/widget.ts
const board = window.openai.toolOutput;
render(board);
CODE

jq -n --rawfile code app.ts \
  '{code: $code,
    mode: "openai-migration",
    concern: "general",
    context: "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
    prescan_facts: {resources: [], flags: []}}' > input.json

curl -s -X POST "$API/estimate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d @input.json | jq '.data.hold_credits'

CODE = """// file: server.ts
server.registerTool("show_board", {
  _meta: { "openai/outputTemplate": "ui://widget/board.html" },
}, showBoard);

// file: web/src/widget.ts
const board = window.openai.toolOutput;
render(board);
"""

payload = {
    "code": CODE,
    "mode": "openai-migration",
    "concern": "general",
    "context": "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
    "prescan_facts": {"resources": [], "flags": []},
}

est = api("POST", "/estimate", payload)
print("worst case:", est.get("hold_credits", est.get("credits")), "credits")

const code = [
  '// file: server.ts',
  'server.registerTool("show_board", {',
  '  _meta: { "openai/outputTemplate": "ui://widget/board.html" },',
  '}, showBoard);',
  '',
  '// file: web/src/widget.ts',
  'const board = window.openai.toolOutput;',
  'render(board);',
].join("\n");

const payload = {
  code,
  mode: "openai-migration",
  concern: "general",
  context: "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
  prescan_facts: { resources: [], flags: [] },
};

const est = await api("POST", "/estimate", payload);
console.log("worst case:", est.hold_credits ?? est.credits, "credits");

const code = `// file: server.ts
server.registerTool("show_board", {
  _meta: { "openai/outputTemplate": "ui://widget/board.html" },
}, showBoard);

// file: web/src/widget.ts
const board = window.openai.toolOutput;
render(board);`

payload := map[string]any{
	"code":    code,
	"mode":    "openai-migration",
	"concern": "general",
	"context": "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
	"prescan_facts": map[string]any{
		"resources": []any{}, "flags": []any{},
	},
}

var est struct{ HoldCredits int64 `json:"hold_credits"` }
err := call("POST", "/estimate", payload, &est)

String code = """
    // file: server.ts
    server.registerTool("show_board", {
      _meta: { "openai/outputTemplate": "ui://widget/board.html" },
    }, showBoard);

    // file: web/src/widget.ts
    const board = window.openai.toolOutput;
    render(board);
    """;

String jsonPayload = """
    {"code": %s,
     "mode": "openai-migration",
     "concern": "general",
     "context": "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
     "prescan_facts": {"resources": [], "flags": []}}
    """.formatted(toJsonString(code));

String envelope = api("POST", "/estimate", jsonPayload);
// worst-case cost is at data.hold_credits

CODE = <<~TS
  // file: server.ts
  server.registerTool("show_board", {
    _meta: { "openai/outputTemplate": "ui://widget/board.html" },
  }, showBoard);

  // file: web/src/widget.ts
  const board = window.openai.toolOutput;
  render(board);
TS

payload = { code: CODE,
            mode: "openai-migration",
            concern: "general",
            context: "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
            prescan_facts: { resources: [], flags: [] } }

est = api("POST", "/estimate", payload)
puts "worst case: #{est["hold_credits"] || est["credits"]} credits"

$code = <<<'TS'
// file: server.ts
server.registerTool("show_board", {
  _meta: { "openai/outputTemplate": "ui://widget/board.html" },
}, showBoard);

// file: web/src/widget.ts
const board = window.openai.toolOutput;
render(board);
TS;

$payload = [
    "code"          => $code,
    "mode"          => "openai-migration",
    "concern"       => "general",
    "context"       => "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
    "prescan_facts" => ["resources" => [], "flags" => []],
];

$est = api("POST", "/estimate", $payload);
echo "worst case: " . ($est["hold_credits"] ?? $est["credits"]) . " credits\n";

var code = """
    // file: server.ts
    server.registerTool("show_board", {
      _meta: { "openai/outputTemplate": "ui://widget/board.html" },
    }, showBoard);

    // file: web/src/widget.ts
    const board = window.openai.toolOutput;
    render(board);
    """;

var payload = new {
    code,
    mode = "openai-migration",
    concern = "general",
    context = "Porting a tldraw board widget off the OpenAI Apps SDK; target host is Claude Desktop.",
    prescan_facts = new {
        resources = Array.Empty<object>(), flags = Array.Empty<object>(),
    },
};

var est = await SkillSafe.ApiAsync(HttpMethod.Post, "/estimate", payload);
Console.WriteLine($"worst case: {est.GetProperty("hold_credits")} credits");

JOB_ID=$(curl -s -X POST "$API/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mac-$(date +%s)" \
  -d @input.json | jq -r '.data.job_id')

while :; do
  JOB=$(curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN")
  STATUS=$(echo "$JOB" | jq -r '.data.status')
  [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ] && break
  sleep 2
done

# unwrap the review once, then read it
echo "$JOB" | jq -r '.data.output.output' > review.json

jq -r '
  "\(.review_name) [\(.posture)]: \(.verdict)",
  "",
  "INVENTORY",
  (.inventory[] | "  \(.kind)/\(.name) in \(.scope) - \(.role)"),
  "",
  "FINDINGS",
  (.findings[] | "  [\(.priority)] \(.id) \(.category) \(.resource): \(.problem)"),
  "",
  "MIGRATION MAP",
  (.migration_map[] | "  \(.pattern) -> \(.replacement)"),
  "",
  "QUICK WINS",
  (.quick_wins[] | "  - \(.)"),
  "",
  "FOCUS AREAS",
  (.focus_areas[] | "  \(.area) - \(.why)"),
  "",
  "COVERAGE",
  (.coverage_check[] | "  \(.id): \(if .addressed then "ok" else "SET ASIDE" end) - \(.note)")' \
  review.json

# fail the pipeline on anything critical
jq -e '[.findings[] | select(.priority == "critical")] | length == 0' review.json > /dev/null \
  || { echo "critical findings present"; exit 1; }

import time

job_id = api("POST", "/run", payload,
             **{"Idempotency-Key": "mac-001"})["job_id"]

while True:
    job = api("GET", f"/jobs/{job_id}")
    if job["status"] in ("succeeded", "failed"):
        break
    time.sleep(1.5)

if job["status"] == "failed":
    raise RuntimeError(job.get("error", "run failed"))

raw = job["output"]
if isinstance(raw, dict) and "output" in raw:
    raw = raw["output"]
review = json.loads(raw) if isinstance(raw, str) else raw

print(f'{review["review_name"]} [{review["posture"]}]: {review["verdict"]}')
for r in review["inventory"]:
    print(f'  {r["kind"]}/{r["name"]:<24} in={r["scope"] or "-":<16} {r["role"]}')
for f in review["findings"]:
    print(f'  [{f["priority"]:>8}] {f["id"]} {f["category"]} {f["resource"]}')
    print(f'      L:{f["likelihood"]}/S:{f["severity"]} {f["problem"]}')
    print(f'      fix: {f["fix"]}')
    if f["snippet"]:
        print("      snippet:", f["snippet"].splitlines()[0], "...")
for m in review["migration_map"]:
    print(f'  {m["pattern"]} -> {m["replacement"]}')
for w in review["quick_wins"]:
    print("  win:", w)
for a in review["focus_areas"]:
    print(f'  focus {a["area"]} {a["finding_ids"]} - {a["why"]}')
for c in review["coverage_check"]:
    print(f'  {c["id"]}: {"ok" if c["addressed"] else "SET ASIDE"} - {c["note"]}')

with open("review.json", "w", encoding="utf-8") as fh:
    json.dump(review, fh, indent=2)

critical = [f for f in review["findings"] if f["priority"] == "critical"]
if critical:
    raise SystemExit(f"{len(critical)} critical finding(s)")

import { writeFileSync } from "node:fs";

const { job_id } = await api("POST", "/run", payload,
  { "Idempotency-Key": crypto.randomUUID() });

let job;
do {
  await new Promise((r) => setTimeout(r, 1500));
  job = await api("GET", `/jobs/${job_id}`);
} while (job.status !== "succeeded" && job.status !== "failed");

if (job.status === "failed") throw new Error(job.error ?? "run failed");

const raw = job.output?.output ?? job.output;
const review = typeof raw === "string" ? JSON.parse(raw) : raw;

console.log(`${review.review_name} [${review.posture}]: ${review.verdict}`);
for (const r of review.inventory) {
  console.log(`  ${r.kind}/${r.name} (${r.scope || "-"}): ${r.role}`);
}
for (const f of review.findings) {
  console.log(`  [${f.priority}] ${f.id} ${f.category} ${f.resource}`);
  console.log(`      L:${f.likelihood}/S:${f.severity} - ${f.fix}`);
}
for (const m of review.migration_map) {
  console.log(`  ${m.pattern} -> ${m.replacement}`);
}
for (const w of review.quick_wins) console.log(`  win: ${w}`);
for (const a of review.focus_areas) {
  console.log(`  focus ${a.area} (${a.finding_ids.join(", ")}): ${a.why}`);
}
for (const c of review.coverage_check) {
  console.log(`  ${c.id}: ${c.addressed ? "ok" : "SET ASIDE"} - ${c.note}`);
}

writeFileSync("review.json", JSON.stringify(review, null, 2));

const critical = review.findings.filter((f) => f.priority === "critical");
if (critical.length) process.exitCode = 1;

var started struct{ JobID string `json:"job_id"` }
if err := call("POST", "/run", payload, &started); err != nil {
	log.Fatal(err)
}

var job struct {
	Status string          `json:"status"`
	Error  string          `json:"error"`
	Output json.RawMessage `json:"output"`
}
for {
	if err := call("GET", "/jobs/"+started.JobID, nil, &job); err != nil {
		log.Fatal(err)
	}
	if job.Status == "succeeded" || job.Status == "failed" {
		break
	}
	time.Sleep(1500 * time.Millisecond)
}

// job.Output is {"output": "<json string>"} — unwrap, then unmarshal:
type Review struct {
	ReviewName string `json:"review_name"`
	Posture    string `json:"posture"`
	Verdict    string `json:"verdict"`
	ExecSummary string `json:"exec_summary"`
	Assumptions   []string `json:"assumptions"`
	OpenQuestions []string `json:"open_questions"`
	Inventory []struct {
		Kind, Name, Scope, Role string
	} `json:"inventory"`
	Findings []struct {
		ID, Category, Severity, Likelihood, Priority string
		Resource, Problem, Impact, Fix, Snippet      string
	} `json:"findings"`
	MigrationMap []struct {
		Pattern, Note, Replacement string
	} `json:"migration_map"`
	CoverageCheck []struct {
		ID, Note  string
		Addressed bool
	} `json:"coverage_check"`
	QuickWins  []string `json:"quick_wins"`
	FocusAreas []struct {
		Area, Why  string
		FindingIDs []string `json:"finding_ids"`
	} `json:"focus_areas"`
	Summary string `json:"summary"`
}
var wrapper struct{ Output string `json:"output"` }
json.Unmarshal(job.Output, &wrapper)
var review Review
json.Unmarshal([]byte(wrapper.Output), &review)

fmt.Printf("%s [%s]: %s\n", review.ReviewName, review.Posture, review.Verdict)
for _, r := range review.Inventory {
	fmt.Printf("  %s/%s (%s): %s\n", r.Kind, r.Name, r.Scope, r.Role)
}
for _, f := range review.Findings {
	fmt.Printf("  [%s] %s %s %s: %s\n", f.Priority, f.ID, f.Category, f.Resource, f.Problem)
}
for _, m := range review.MigrationMap {
	fmt.Printf("  %s -> %s\n", m.Pattern, m.Replacement)
}
for _, a := range review.FocusAreas {
	fmt.Printf("  focus %s %v: %s\n", a.Area, a.FindingIDs, a.Why)
}
os.WriteFile("review.json", []byte(wrapper.Output), 0o644)

String envelope = api("POST", "/run", jsonPayload);
String jobId = /* data.job_id via your JSON library */;

while (true) {
    String job = api("GET", "/jobs/" + jobId, null);
    String status = /* data.status */;
    if (status.equals("succeeded") || status.equals("failed")) break;
    Thread.sleep(1500);
}
// The review is at data.output.output as a JSON string — parse it again, then read
// review_name, posture, verdict, exec_summary, assumptions[], open_questions[],
// inventory[] (kind/name/scope/role),
// findings[] (id/category/severity/likelihood/priority/resource/problem/impact/fix/snippet),
// migration_map[] (pattern/note/replacement), coverage_check[] (id/addressed/note),
// quick_wins[], focus_areas[] (area/why/finding_ids[]) and summary.
// Finally keep the review on disk:
//   Files.writeString(Path.of("review.json"), reviewJson);

started = api("POST", "/run", payload)

job = nil
loop do
  job = api("GET", "/jobs/#{started["job_id"]}")
  break if %w[succeeded failed].include?(job["status"])
  sleep 1.5
end
raise (job["error"] || "run failed") if job["status"] == "failed"

raw = job["output"].is_a?(Hash) ? job["output"].fetch("output", job["output"]) : job["output"]
review = raw.is_a?(String) ? JSON.parse(raw) : raw

puts "#{review["review_name"]} [#{review["posture"]}]: #{review["verdict"]}"
review["inventory"].each { |r| puts "  #{r["kind"]}/#{r["name"]} (#{r["scope"]}): #{r["role"]}" }
review["findings"].each do |f|
  puts "  [#{f["priority"]}] #{f["id"]} #{f["category"]} #{f["resource"]}"
  puts "      L:#{f["likelihood"]}/S:#{f["severity"]} - #{f["fix"]}"
end
review["migration_map"].each { |m| puts "  #{m["pattern"]} -> #{m["replacement"]}" }
review["quick_wins"].each { |w| puts "  win: #{w}" }
review["focus_areas"].each { |a| puts "  focus #{a["area"]} #{a["finding_ids"].join(", ")}" }
review["coverage_check"].each { |c| puts "  #{c["id"]}: #{c["addressed"] ? "ok" : "SET ASIDE"}" }

File.write("review.json", JSON.pretty_generate(review))
exit 1 if review["findings"].any? { |f| f["priority"] == "critical" }

$started = api("POST", "/run", $payload);

do {
    sleep(2);
    $job = api("GET", "/jobs/" . $started["job_id"]);
} while (!in_array($job["status"], ["succeeded", "failed"]));

if ($job["status"] === "failed") {
    throw new Exception($job["error"] ?? "run failed");
}

$raw = is_array($job["output"]) ? ($job["output"]["output"] ?? $job["output"]) : $job["output"];
$review = is_string($raw) ? json_decode($raw, true) : $raw;

echo "{$review['review_name']} [{$review['posture']}]: {$review['verdict']}\n";
foreach ($review["inventory"] as $r) {
    echo "  {$r['kind']}/{$r['name']} ({$r['scope']}): {$r['role']}\n";
}
foreach ($review["findings"] as $f) {
    echo "  [{$f['priority']}] {$f['id']} {$f['category']} {$f['resource']}\n";
    echo "      L:{$f['likelihood']}/S:{$f['severity']} - {$f['fix']}\n";
}
foreach ($review["migration_map"] as $m) {
    echo "  {$m['pattern']} -> {$m['replacement']}\n";
}
foreach ($review["quick_wins"] as $w) {
    echo "  win: $w\n";
}
foreach ($review["focus_areas"] as $a) {
    echo "  focus {$a['area']}: " . implode(", ", $a["finding_ids"]) . "\n";
}
foreach ($review["coverage_check"] as $c) {
    echo "  {$c['id']}: " . ($c["addressed"] ? "ok" : "SET ASIDE") . "\n";
}

file_put_contents("review.json", json_encode($review, JSON_PRETTY_PRINT));

var started = await SkillSafe.ApiAsync(HttpMethod.Post, "/run", payload);
var jobId = started.GetProperty("job_id").GetString();

JsonElement job;
while (true)
{
    job = await SkillSafe.ApiAsync(HttpMethod.Get, $"/jobs/{jobId}");
    var status = job.GetProperty("status").GetString();
    if (status is "succeeded" or "failed") break;
    await Task.Delay(1500);
}

var rawText = job.GetProperty("output").GetProperty("output").GetString();
using var doc = JsonDocument.Parse(rawText!);
var review = doc.RootElement;

Console.WriteLine($"{review.GetProperty("review_name")} " +
                  $"[{review.GetProperty("posture")}]: {review.GetProperty("verdict")}");
foreach (var r in review.GetProperty("inventory").EnumerateArray())
{
    Console.WriteLine($"  {r.GetProperty("kind")}/{r.GetProperty("name")}: {r.GetProperty("role")}");
}
foreach (var f in review.GetProperty("findings").EnumerateArray())
{
    Console.WriteLine($"  [{f.GetProperty("priority")}] {f.GetProperty("id")} " +
                      $"{f.GetProperty("category")} {f.GetProperty("resource")} " +
                      $"(L:{f.GetProperty("likelihood")}/S:{f.GetProperty("severity")})");
}
foreach (var m in review.GetProperty("migration_map").EnumerateArray())
{
    Console.WriteLine($"  {m.GetProperty("pattern")} -> {m.GetProperty("replacement")}");
}
foreach (var a in review.GetProperty("focus_areas").EnumerateArray())
{
    Console.WriteLine($"  focus {a.GetProperty("area")}: {a.GetProperty("why")}");
}

await File.WriteAllTextAsync("review.json", rawText!);

# -N disables buffering so events print as they arrive
curl -N -s -X POST "$API/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mac-$(date +%s)" \
  -d @input.json

# event: job
# data: {"job_id":"job_...","status":"running"}
#
# event: delta
# data: {"text":"{\"review_name\":\"board"}
# ...
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":734,"output":{"output":"{...}"}}

import json, requests

result = None
with requests.post(
    API + "/run-stream",
    headers={"Authorization": f"Bearer {TOKEN}",
             "Idempotency-Key": "mac-001"},
    json=payload,
    stream=True,
) as r:
    r.raise_for_status()
    event = None
    for line in r.iter_lines(decode_unicode=True):
        if not line:
            continue
        if line.startswith("event:"):
            event = line[len("event:"):].strip()
        elif line.startswith("data:"):
            data = json.loads(line[len("data:"):].strip())
            if event == "delta":
                print(".", end="", flush=True)          # live progress
            elif event == "done":
                result = data
            elif event == "error":
                raise RuntimeError(data.get("message", "run failed"))

review = json.loads(result["output"]["output"])          # authoritative
print("charged:", result["charged_credits"], "-", review["review_name"])
print("posture:", review["posture"])
for f in review["findings"]:
    print(f'  [{f["priority"]}] {f["id"]} {f["resource"]}: {f["problem"]}')
with open("review.json", "w", encoding="utf-8") as fh:
    json.dump(review, fh, indent=2)

const res = await fetch(API + "/run-stream", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify(payload),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = "", done = null;

for (;;) {
  const chunk = await reader.read();
  if (chunk.done) break;
  buf += decoder.decode(chunk.value, { stream: true });
  const frames = buf.split("\n\n");
  buf = frames.pop();
  for (const frame of frames) {
    const name = /^event:\s*(.+)$/m.exec(frame)?.[1];
    const body = /^data:\s*(.+)$/m.exec(frame)?.[1];
    if (!name || !body) continue;
    const data = JSON.parse(body);
    if (name === "delta") process.stdout.write(".");   // live progress
    if (name === "done") done = data;
    if (name === "error") throw new Error(data.message ?? "run failed");
  }
}

const review = JSON.parse(done.output.output);
console.log(`\n${done.charged_credits} credits - ${review.review_name} [${review.posture}]`);
for (const f of review.findings) console.log(`  [${f.priority}] ${f.id} ${f.resource}`);
writeFileSync("review.json", JSON.stringify(review, null, 2));

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", API+"/run-stream", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "mac-001")

res, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()

var event string
var final map[string]any
sc := bufio.NewScanner(res.Body)
sc.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
for sc.Scan() {
	line := sc.Text()
	switch {
	case strings.HasPrefix(line, "event:"):
		event = strings.TrimSpace(strings.TrimPrefix(line, "event:"))
	case strings.HasPrefix(line, "data:"):
		var data map[string]any
		json.Unmarshal([]byte(strings.TrimPrefix(line, "data:")), &data)
		switch event {
		case "delta":
			fmt.Print(".") // live progress
		case "done":
			final = data
		case "error":
			log.Fatal(data["message"])
		}
	}
}
// final["output"].(map[string]any)["output"].(string) is the review JSON —
// unmarshal it into the Review struct from step 4, then write it to review.json.

// Java 17+ — read the stream line by line instead of buffering the body.
var req = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "mac-001")
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();

var res = HTTP.send(req, HttpResponse.BodyHandlers.ofLines());
String event = null, done = null;
for (String line : (Iterable<String>) res.body()::iterator) {
    if (line.startsWith("event:")) {
        event = line.substring(6).trim();
    } else if (line.startsWith("data:")) {
        String data = line.substring(5).trim();
        if ("delta".equals(event)) System.out.print(".");   // live progress
        else if ("done".equals(event)) done = data;
        else if ("error".equals(event)) throw new RuntimeException(data);
    }
}
// parse `done`, then parse data.output.output again — it is a JSON string holding
// review_name, posture, verdict, inventory[], findings[], migration_map[],
// coverage_check[], quick_wins[], focus_areas[] and the rest.

require "net/http"
require "json"

uri = URI(API + "/run-stream")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{TOKEN}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "mac-001"
req.body = payload.to_json

event = nil
done = nil
Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(req) do |res|
    res.read_body do |chunk|
      chunk.each_line do |line|
        line = line.strip
        if line.start_with?("event:")
          event = line.delete_prefix("event:").strip
        elsif line.start_with?("data:")
          data = JSON.parse(line.delete_prefix("data:").strip)
          case event
          when "delta" then print "."           # live progress
          when "done"  then done = data
          when "error" then raise (data["message"] || "run failed")
          end
        end
      end
    end
  end
end

review = JSON.parse(done["output"]["output"])
puts "\n#{done["charged_credits"]} credits - #{review["review_name"]} [#{review["posture"]}]"
review["findings"].each { |f| puts "  [#{f["priority"]}] #{f["id"]} #{f["resource"]}" }
File.write("review.json", JSON.pretty_generate(review))

$event = null;
$done  = null;

$ch = curl_init(API . "/run-stream");
curl_setopt_array($ch, [
    CURLOPT_POST       => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $TOKEN",
        "Content-Type: application/json",
        "Idempotency-Key: mac-001",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_WRITEFUNCTION => function ($ch, $chunk) use (&$event, &$done) {
        foreach (explode("\n", $chunk) as $line) {
            $line = trim($line);
            if (str_starts_with($line, "event:")) {
                $event = trim(substr($line, 6));
            } elseif (str_starts_with($line, "data:")) {
                $data = json_decode(trim(substr($line, 5)), true);
                if ($event === "delta") { echo "."; }        // live progress
                elseif ($event === "done") { $done = $data; }
                elseif ($event === "error") { throw new Exception($data["message"] ?? "run failed"); }
            }
        }
        return strlen($chunk);
    },
]);
curl_exec($ch);
curl_close($ch);

$review = json_decode($done["output"]["output"], true);
echo "\n{$done['charged_credits']} credits - {$review['review_name']} [{$review['posture']}]\n";
foreach ($review["findings"] as $f) {
    echo "  [{$f['priority']}] {$f['id']} {$f['resource']}\n";
}
file_put_contents("review.json", json_encode($review, JSON_PRETTY_PRINT));

var req = new HttpRequestMessage(HttpMethod.Post, Api + "/run-stream") {
    Content = JsonContent.Create(payload),
};
req.Headers.Add("Idempotency-Key", "mac-001");

using var res = await Http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());

string? evt = null, done = null;
while (await reader.ReadLineAsync() is { } line)
{
    if (line.StartsWith("event:")) evt = line[6..].Trim();
    else if (line.StartsWith("data:"))
    {
        var data = line[5..].Trim();
        if (evt == "delta") Console.Write(".");            // live progress
        else if (evt == "done") done = data;
        else if (evt == "error") throw new Exception(data);
    }
}

using var final = JsonDocument.Parse(done!);
var text = final.RootElement.GetProperty("output").GetProperty("output").GetString();
using var reviewDoc = JsonDocument.Parse(text!);
var review = reviewDoc.RootElement;
Console.WriteLine($"{review.GetProperty("review_name")} [{review.GetProperty("posture")}]");
foreach (var f in review.GetProperty("findings").EnumerateArray())
    Console.WriteLine($"  [{f.GetProperty("priority")}] {f.GetProperty("id")} {f.GetProperty("resource")}");
await File.WriteAllTextAsync("review.json", text!);

# ci-review.sh — exits non-zero when the app is not host-ready enough to merge
set -euo pipefail

# 1. build the input from the tree
{ for f in server.ts web/src/*.ts vite.config.ts; do
    printf '// file: %s\n' "$f"; cat "$f"; printf '\n\n'
  done; } > app-bundle.ts

jq -n --rawfile code app-bundle.ts \
  '{code: $code, mode: "review", concern: "general",
    context: "CI gate on '"$GITHUB_REF_NAME"'; hosts: Claude Desktop.",
    prescan_facts: {resources: [], flags: []}}' > input.json

# 2. an input-derived key: same tree, same key, replay instead of re-bill
KEY="mcp-app-clinic:ci:$(jq -r '[.code,.mode,.concern,.context] | join(" ")' input.json \
  | shasum -a 256 | cut -c1-16)"

# 3. run
JOB_ID=$(curl -s -X POST "$API/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d @input.json | jq -r '.data.job_id')

until [ "$(curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data.status')" != "running" ]; do sleep 2; done

curl -s "$API/jobs/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data.output.output' > review.json

# 4. gate
POSTURE=$(jq -r '.posture' review.json)
CRIT=$(jq '[.findings[] | select(.priority == "critical")] | length' review.json)

jq -r '.findings[] | select(.priority == "critical" or .priority == "high")
       | "::error title=\(.id) \(.category)::\(.resource): \(.problem)"' review.json

echo "posture=$POSTURE critical=$CRIT"
if [ "$POSTURE" = "host-breaking" ] || [ "$CRIT" -gt 0 ]; then
  jq -r '.verdict' review.json
  exit 1
fi

import glob, hashlib, json, sys, time

def bundle(paths):
    out = []
    for p in paths:
        with open(p, encoding="utf-8") as fh:
            out.append(f"// file: {p}\n{fh.read()}")
    return "\n\n".join(out)

payload = {
    "code": bundle(["server.ts", *sorted(glob.glob("web/src/*.ts")), "vite.config.ts"]),
    "mode": "review",
    "concern": "general",
    "context": "CI gate on the default branch; target host is Claude Desktop.",
    "prescan_facts": {"resources": [], "flags": []},
}

# Same tree, same key: a retried job replays the first review instead of buying a second.
digest = hashlib.sha256(
    " ".join(payload[k] for k in ("code", "mode", "concern", "context")).encode()
).hexdigest()[:16]
key = f"mcp-app-clinic:ci:{digest}"

job_id = api("POST", "/run", payload, **{"Idempotency-Key": key})["job_id"]
while (job := api("GET", f"/jobs/{job_id}"))["status"] == "running":
    time.sleep(2)
if job["status"] == "failed":
    sys.exit(job.get("error", "run failed"))

raw = job["output"]["output"] if isinstance(job["output"], dict) else job["output"]
review = json.loads(raw)

blocking = [f for f in review["findings"] if f["priority"] == "critical"]
for f in review["findings"]:
    if f["priority"] in ("critical", "high"):
        print(f'{f["priority"]:>8} {f["id"]} {f["category"]} {f["resource"]}: {f["fix"]}')

print(f'\n{review["review_name"]}: {review["posture"]} — {review["verdict"]}')
if review["posture"] == "host-breaking" or blocking:
    sys.exit(f'blocked: posture={review["posture"]}, {len(blocking)} critical finding(s)')
print("ok — nothing host-breaking, nothing critical")

import { createHash } from "node:crypto";
import { readFileSync, writeFileSync, globSync } from "node:fs";

const files = ["server.ts", ...globSync("web/src/*.ts").sort(), "vite.config.ts"];
const code = files
  .map((f) => `// file: ${f}\n${readFileSync(f, "utf8")}`)
  .join("\n\n");

const payload = {
  code,
  mode: "review",
  concern: "general",
  context: "CI gate on the default branch; target host is Claude Desktop.",
  prescan_facts: { resources: [], flags: [] },
};

// Same tree, same key: a retried job replays the first review instead of buying a second.
const digest = createHash("sha256")
  .update([payload.code, payload.mode, payload.concern, payload.context].join(" "))
  .digest("hex")
  .slice(0, 16);

const { job_id } = await api("POST", "/run", payload,
  { "Idempotency-Key": `mcp-app-clinic:ci:${digest}` });

let job;
do {
  await new Promise((r) => setTimeout(r, 2000));
  job = await api("GET", `/jobs/${job_id}`);
} while (job.status === "running");
if (job.status === "failed") throw new Error(job.error ?? "run failed");

const review = JSON.parse(job.output?.output ?? job.output);
writeFileSync("review.json", JSON.stringify(review, null, 2));

for (const f of review.findings) {
  if (f.priority === "critical" || f.priority === "high") {
    console.log(`::error title=${f.id} ${f.category}::${f.resource}: ${f.problem}`);
  }
}

const blocking = review.findings.filter((f) => f.priority === "critical");
console.log(`${review.review_name}: ${review.posture} - ${review.verdict}`);
if (review.posture === "host-breaking" || blocking.length) {
  console.error(`blocked: ${blocking.length} critical finding(s)`);
  process.exitCode = 1;
}

files := []string{"server.ts", "web/src/widget.ts", "vite.config.ts"}
var b strings.Builder
for _, f := range files {
	src, err := os.ReadFile(f)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Fprintf(&b, "// file: %s\n%s\n\n", f, src)
}

code := b.String()
mode, concern := "review", "general"
ctx := "CI gate on the default branch; target host is Claude Desktop."

payload := map[string]any{
	"code": code, "mode": mode, "concern": concern, "context": ctx,
	"prescan_facts": map[string]any{"resources": []any{}, "flags": []any{}},
}

// Same tree, same key: a retried job replays the first review instead of buying a second.
sum := sha256.Sum256([]byte(strings.Join([]string{code, mode, concern, ctx}, " ")))
key := "mcp-app-clinic:ci:" + hex.EncodeToString(sum[:])[:16]

body, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", API+"/run", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", key)
// ... send, read data.job_id, then poll /jobs/{id} as in step 4 ...

// review is the parsed Review struct from step 4:
blocking := 0
for _, f := range review.Findings {
	if f.Priority == "critical" {
		blocking++
	}
	if f.Priority == "critical" || f.Priority == "high" {
		fmt.Printf("::error title=%s %s::%s: %s\n", f.ID, f.Category, f.Resource, f.Problem)
	}
}
fmt.Printf("%s: %s - %s\n", review.ReviewName, review.Posture, review.Verdict)
if review.Posture == "host-breaking" || blocking > 0 {
	os.Exit(1)
}

// Java 17+ — build the bundle, derive the key, run, then gate.
var files = List.of("server.ts", "web/src/widget.ts", "vite.config.ts");
var sb = new StringBuilder();
for (String f : files) {
    sb.append("// file: ").append(f).append('\n')
      .append(Files.readString(Path.of(f))).append("\n\n");
}
String code = sb.toString();
String mode = "review", concern = "general";
String ctx = "CI gate on the default branch; target host is Claude Desktop.";

// Same tree, same key: a retried job replays the first review instead of buying a second.
var md = MessageDigest.getInstance("SHA-256");
byte[] sum = md.digest(String.join(" ", code, mode, concern, ctx)
    .getBytes(StandardCharsets.UTF_8));
String key = "mcp-app-clinic:ci:" + HexFormat.of().formatHex(sum).substring(0, 16);

var req = HttpRequest.newBuilder(URI.create(API + "/run"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", key)
    .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
    .build();
// ... send, read data.job_id, poll /jobs/{id} as in step 4, parse data.output.output ...

// With the review parsed: block the build on the posture and on critical findings.
//   boolean blocked = "host-breaking".equals(posture)
//       || findings.stream().anyMatch(f -> "critical".equals(f.priority()));
//   if (blocked) { System.err.println(verdict); System.exit(1); }

require "digest"

files = ["server.ts", *Dir["web/src/*.ts"].sort, "vite.config.ts"]
code = files.map { |f| "// file: #{f}\n#{File.read(f)}" }.join("\n\n")

payload = { code: code,
            mode: "review",
            concern: "general",
            context: "CI gate on the default branch; target host is Claude Desktop.",
            prescan_facts: { resources: [], flags: [] } }

# Same tree, same key: a retried job replays the first review instead of buying a second.
digest = Digest::SHA256.hexdigest(
  [payload[:code], payload[:mode], payload[:concern], payload[:context]].join(" ")
)[0, 16]

started = api("POST", "/run", payload) # add the header in your helper:
                                       #   req["Idempotency-Key"] = "mcp-app-clinic:ci:#{digest}"

job = nil
loop do
  job = api("GET", "/jobs/#{started["job_id"]}")
  break unless job["status"] == "running"
  sleep 2
end
abort(job["error"] || "run failed") if job["status"] == "failed"

review = JSON.parse(job["output"]["output"])
File.write("review.json", JSON.pretty_generate(review))

review["findings"].each do |f|
  next unless %w[critical high].include?(f["priority"])
  puts "::error title=#{f["id"]} #{f["category"]}::#{f["resource"]}: #{f["problem"]}"
end

blocking = review["findings"].count { |f| f["priority"] == "critical" }
puts "#{review["review_name"]}: #{review["posture"]} - #{review["verdict"]}"
abort("blocked: #{blocking} critical finding(s)") if review["posture"] == "host-breaking" || blocking > 0

<?php
$files = array_merge(["server.ts"], glob("web/src/*.ts"), ["vite.config.ts"]);
$code = implode("\n\n", array_map(
    fn ($f) => "// file: $f\n" . file_get_contents($f),
    $files
));

$payload = [
    "code"          => $code,
    "mode"          => "review",
    "concern"       => "general",
    "context"       => "CI gate on the default branch; target host is Claude Desktop.",
    "prescan_facts" => ["resources" => [], "flags" => []],
];

// Same tree, same key: a retried job replays the first review instead of buying a second.
$digest = substr(hash("sha256", implode(" ", [
    $payload["code"], $payload["mode"], $payload["concern"], $payload["context"],
])), 0, 16);
$key = "mcp-app-clinic:ci:$digest"; // pass this as the Idempotency-Key header

$started = api("POST", "/run", $payload);
do {
    sleep(2);
    $job = api("GET", "/jobs/" . $started["job_id"]);
} while ($job["status"] === "running");

if ($job["status"] === "failed") {
    fwrite(STDERR, ($job["error"] ?? "run failed") . "\n");
    exit(1);
}

$review = json_decode($job["output"]["output"], true);
file_put_contents("review.json", json_encode($review, JSON_PRETTY_PRINT));

$blocking = 0;
foreach ($review["findings"] as $f) {
    if ($f["priority"] === "critical") { $blocking++; }
    if (in_array($f["priority"], ["critical", "high"], true)) {
        echo "::error title={$f['id']} {$f['category']}::{$f['resource']}: {$f['problem']}\n";
    }
}

echo "{$review['review_name']}: {$review['posture']} - {$review['verdict']}\n";
if ($review["posture"] === "host-breaking" || $blocking > 0) {
    exit(1);
}

using System.Security.Cryptography;
using System.Text;

var files = new[] { "server.ts" }
    .Concat(Directory.GetFiles("web/src", "*.ts").OrderBy(p => p))
    .Append("vite.config.ts");
var code = string.Join("\n\n", files.Select(f => $"// file: {f}\n{File.ReadAllText(f)}"));

const string mode = "review", concern = "general";
const string ctx = "CI gate on the default branch; target host is Claude Desktop.";

var payload = new {
    code, mode, concern, context = ctx,
    prescan_facts = new { resources = Array.Empty<object>(), flags = Array.Empty<object>() },
};

// Same tree, same key: a retried job replays the first review instead of buying a second.
var sum = SHA256.HashData(Encoding.UTF8.GetBytes(string.Join(" ", code, mode, concern, ctx)));
var key = "mcp-app-clinic:ci:" + Convert.ToHexString(sum).ToLowerInvariant()[..16];

var req = new HttpRequestMessage(HttpMethod.Post, "https://api.skillsafe.ai/v1/app-api/run") {
    Content = JsonContent.Create(payload),
};
req.Headers.Add("Idempotency-Key", key);
// ... send, read data.job_id, poll /jobs/{id} as in step 4 ...

var review = JsonDocument.Parse(rawText!).RootElement;
var blocking = 0;
foreach (var f in review.GetProperty("findings").EnumerateArray())
{
    var priority = f.GetProperty("priority").GetString();
    if (priority == "critical") blocking++;
    if (priority is "critical" or "high")
        Console.WriteLine($"::error title={f.GetProperty("id")} {f.GetProperty("category")}::" +
                          $"{f.GetProperty("resource")}: {f.GetProperty("problem")}");
}

var posture = review.GetProperty("posture").GetString();
Console.WriteLine($"{review.GetProperty("review_name")}: {posture}");
if (posture == "host-breaking" || blocking > 0)
{
    Console.Error.WriteLine(review.GetProperty("verdict").GetString());
    Environment.Exit(1);
}