syndai 0.1.0 → 0.3.0

package/src/main.js

@@ -0,0 +1,212 @@
+// Command table, argument parsing and the one error report. `main(argv, io)` takes all
+// process I/O as `io`, so tests drive it in-process with a fake server and fake clocks.
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { createContext, login, logout, whoami } from "./auth.js";
+import { answer, cancel, change, editText, goLive, review, revert, status, watch } from "./changes.js";
+import { CliError, EXIT, explain } from "./errors.js";
+import { VERSION } from "./http.js";
+import { mcp } from "./mcp.js";
+import { link } from "./projects.js";
+import { api, settings } from "./settings.js";
+import { closeInput, openBrowser, page } from "./ui.js";
+
+const str = { type: "string" };
+const bool = { type: "boolean" };
+const COMMON = { json: bool, "no-input": bool, help: { type: "boolean", short: "h" } };
+
+const COMMANDS = {
+  change: {
+    usage: 'change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]',
+    summary: "Make a change; it goes live when its checks pass (--review: open a PR instead).",
+    options: {
+      app: str,
+      review: bool,
+      image: { type: "string", multiple: true },
+      "no-wait": bool,
+      timeout: str,
+    },
+    run: (ctx, args) => change(ctx, args),
+  },
+  watch: {
+    usage: "watch <run> [--timeout D] [--logs]",
+    summary: "Follow a change to its outcome (Ctrl-C detaches; the change keeps going).",
+    options: { timeout: str, logs: bool },
+    run: (ctx, [run]) => watch(ctx, run),
+  },
+  answer: {
+    usage: "answer <run> [--json '{\"entries\":[...]}']",
+    summary: "Answer a change's open question.",
+    options: { json: str },
+    run: (ctx, [run]) => answer(ctx, run),
+  },
+  review: {
+    usage: "review <run> [--retry | --close]",
+    summary: "See why a change is held, then approve it in your browser.",
+    options: { retry: bool, close: bool },
+    run: (ctx, [run]) => review(ctx, run),
+  },
+  "go-live": {
+    usage: "go-live <run> [--timeout D]",
+    summary: "Put a ready change live.",
+    options: { timeout: str },
+    run: (ctx, [run]) => goLive(ctx, run),
+  },
+  revert: {
+    usage: "revert <run> [--force] [--timeout D]",
+    summary: "Undo a change that went live.",
+    options: { force: bool, timeout: str },
+    run: (ctx, [run]) => revert(ctx, run),
+  },
+  cancel: {
+    usage: "cancel <run>",
+    summary: "Stop a change.",
+    options: {},
+    run: (ctx, [run]) => cancel(ctx, run),
+  },
+  status: {
+    usage: "status [--app A]",
+    summary: "What is running, and everything that needs you.",
+    options: { app: str },
+    run: (ctx) => status(ctx),
+  },
+  "edit-text": {
+    usage: 'edit-text [--app A] [--page /] --from "Old" --to "New" [--all] | --undo <sha>',
+    summary: "Swap exact text on a live site in seconds, free and undoable (--all: every match in its file).",
+    options: { app: str, page: str, from: str, to: str, all: bool, undo: str },
+    run: (ctx) => editText(ctx),
+  },
+  login: {
+    usage: "login [--with-token]",
+    summary: "Log in by approving this computer in your browser (--with-token reads a key from stdin).",
+    options: { "with-token": bool },
+    run: (ctx) => login(ctx),
+  },
+  logout: {
+    usage: "logout",
+    summary: "Revoke and forget the stored key.",
+    options: {},
+    run: (ctx) => logout(ctx),
+  },
+  whoami: {
+    usage: "whoami",
+    summary: "Show the workspace and key in use.",
+    options: {},
+    run: (ctx) => whoami(ctx),
+  },
+  link: {
+    usage: "link [project]",
+    summary: "Remember which project this directory changes (stored outside the repo).",
+    options: { app: str },
+    run: (ctx, [ref]) => link(ctx, ref),
+  },
+  settings: {
+    usage: "settings [--app A] [get | set key=value...]",
+    summary: "autonomy, feature_requests, bug_scan, protected_paths (a key can only tighten them).",
+    options: { app: str },
+    run: (ctx, args) => settings(ctx, args),
+  },
+  mcp: {
+    usage: "mcp install claude|cursor|codex",
+    summary: "Add Syndai to an AI coding tool, with its own key.",
+    options: {},
+    run: (ctx, args) => mcp(ctx, args),
+  },
+  api: {
+    usage: "api <METHOD> <path> [--json body]",
+    summary: "Call any Syndai API route with your key.",
+    options: { json: str },
+    run: (ctx, args) => api(ctx, args),
+  },
+};
+
+export function helpText() {
+  const rows = Object.values(COMMANDS).map((c) => `  syndai ${c.usage}\n      ${c.summary}`);
+  return [
+    `syndai ${VERSION}: tell Syndai what to change; it builds it, checks it and puts it live.`,
+    "",
+    ...rows,
+    "",
+    "Every command: --json (machine output; also when stdout is not a terminal),",
+    "--no-input (never prompt), -h/--help.",
+    "Environment: SYNDAI_API_KEY (wins over `syndai login`), SYNDAI_APP, SYNDAI_API_URL, NO_COLOR.",
+    "Exit codes: 0 done, 1 failed, 2 usage or no project, 3 needs you, 4 live but unverified,",
+    "5 auth/scope/plan, 6 --timeout reached, 7 service unavailable, 130 interrupted.",
+    "",
+  ].join("\n");
+}
+
+/** The real process as `io` (the bin passes the SIGINT AbortSignal). */
+export function processIo(signal) {
+  return {
+    env: process.env,
+    cwd: process.cwd(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    signal,
+    now: () => Date.now(),
+    sleep: (ms, abortSignal) => sleep(ms, undefined, { signal: abortSignal }),
+    openUrl: openBrowser,
+    page: (text) => page(process, text),
+  };
+}
+
+export async function main(argv, io) {
+  const [command, ...rest] = argv;
+  if (!command || ["help", "--help", "-h"].includes(command)) {
+    io.stdout.write(helpText());
+    return EXIT.OK;
+  }
+  if (["--version", "-v", "version"].includes(command)) {
+    io.stdout.write(`${VERSION}\n`);
+    return EXIT.OK;
+  }
+  const spec = COMMANDS[command];
+  if (!spec) {
+    io.stderr.write(`error: unknown command "${command}"\n\n${helpText()}`);
+    return EXIT.USAGE;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: { ...COMMON, ...spec.options }, allowPositionals: true });
+  } catch (err) {
+    io.stderr.write(`error: ${err.message}\n  usage: syndai ${spec.usage}\n`);
+    return EXIT.USAGE;
+  }
+  if (parsed.values.help) {
+    io.stdout.write(`usage: syndai ${spec.usage}\n${spec.summary}\n`);
+    return EXIT.OK;
+  }
+  const ctx = createContext(io, parsed.values);
+  try {
+    return await spec.run(ctx, parsed.positionals);
+  } catch (err) {
+    return report(ctx, err);
+  } finally {
+    closeInput(io);
+  }
+}
+
+/** One error line (plus the next command) on stderr; a JSON error on stdout for machines. */
+function report(ctx, err) {
+  const { ui, io } = ctx;
+  const { exitCode, message, next } = explain(err);
+  if (io.env.SYNDAI_DEBUG && err?.stack) io.stderr.write(`${err.stack}\n`);
+  const extra = err instanceof CliError ? err.result : null;
+  if (exitCode === EXIT.INTERRUPTED) {
+    ui.progress(message);
+  } else {
+    ui.progress(`${ui.red("error:")} ${message}`);
+    if (extra?.human) ui.progress(extra.human);
+    if (ui.json) {
+      const code = err?.code ?? null;
+      io.stdout.write(
+        `${JSON.stringify({ error: { exit_code: exitCode, code, message, next }, ...(extra?.data ?? {}) })}\n`,
+      );
+    }
+  }
+  if (next) ui.progress(`  next: ${next}`);
+  return exitCode;
+}

package/src/mcp.js

@@ -0,0 +1,93 @@
+// `syndai mcp install claude|cursor|codex`: the same browser approval as `syndai login`,
+// but it mints a SEPARATE key per client (audit rows say which door acted; one door can be
+// revoked alone) and writes it into that client's USER-scope config only. Never a project
+// file such as `.mcp.json`: a repo is shared, and `.syndai/**`-style paths are protected.
+//
+// Config locations (checked against each client's docs, 2026-10):
+//   Claude Code  $CLAUDE_CONFIG_DIR/.claude.json or ~/.claude.json, top-level "mcpServers"
+//   Cursor       ~/.cursor/mcp.json, "mcpServers"
+//   Codex        $CODEX_HOME/config.toml or ~/.codex/config.toml, [mcp_servers.<name>]
+
+import fs from "node:fs";
+import path from "node:path";
+import { deviceApproval } from "./auth.js";
+import { CliError, EXIT } from "./errors.js";
+import { MCP_PATH } from "./routes.js";
+import { readJson, writeFileAtomic, writeJson } from "./store.js";
+
+const SERVER_NAME = "syndai";
+
+export const CLIENTS = {
+  claude: {
+    label: "Claude Code",
+    file: (env, home) => path.join(env.CLAUDE_CONFIG_DIR || home, ".claude.json"),
+    write: (file, url, key) =>
+      upsertJsonServer(file, { type: "http", url, headers: { Authorization: `Bearer ${key}` } }),
+  },
+  cursor: {
+    label: "Cursor",
+    file: (_env, home) => path.join(home, ".cursor", "mcp.json"),
+    write: (file, url, key) => upsertJsonServer(file, { url, headers: { Authorization: `Bearer ${key}` } }),
+  },
+  codex: {
+    label: "Codex",
+    file: (env, home) => path.join(env.CODEX_HOME || path.join(home, ".codex"), "config.toml"),
+    write: (file, url, key) => upsertTomlServer(file, url, key),
+  },
+};
+
+export async function mcp(ctx, [action, clientName]) {
+  const target = CLIENTS[clientName];
+  if (action !== "install" || !target) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai mcp install claude|cursor|codex");
+  }
+  const token = await deviceApproval(ctx, `MCP · ${target.label}`);
+  const file = target.file(ctx.io.env, ctx.paths.home);
+  target.write(file, ctx.baseUrl + MCP_PATH, token.api_key);
+  ctx.ui.result(
+    {
+      client: clientName,
+      config_file: file,
+      customer_id: token.customer_id,
+      key_id: token.key_id,
+      expires_at: token.expires_at,
+    },
+    `Syndai is set up in ${target.label} (${file}). Restart ${target.label} to load it.`,
+  );
+  return EXIT.OK;
+}
+
+/** Set `mcpServers.syndai` in a JSON config, keeping everything else. 0600: it holds a key. */
+export function upsertJsonServer(file, entry) {
+  const data = readJson(file, {});
+  data.mcpServers = { ...(data.mcpServers ?? {}), [SERVER_NAME]: entry };
+  writeJson(file, data, 0o600);
+}
+
+/** Replace (or append) the `[mcp_servers.syndai]` table in a TOML config. */
+export function upsertTomlServer(file, url, key) {
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const kept = [];
+  let inOurs = false;
+  for (const line of text.split("\n")) {
+    const header = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(line);
+    if (header) {
+      const name = header[1].replace(/"/g, "");
+      inOurs = name === `mcp_servers.${SERVER_NAME}` || name.startsWith(`mcp_servers.${SERVER_NAME}.`);
+    }
+    if (!inOurs) kept.push(line);
+  }
+  const rest = kept.join("\n").replace(/\s+$/, "");
+  // JSON string escaping is valid TOML basic-string escaping for these ASCII values.
+  const table = [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `url = ${JSON.stringify(url)}`,
+    `http_headers = { Authorization = ${JSON.stringify(`Bearer ${key}`)} }`,
+  ].join("\n");
+  writeFileAtomic(file, `${rest ? `${rest}\n\n` : ""}${table}\n`, 0o600);
+}

package/src/projects.js

@@ -0,0 +1,168 @@
+// Which project a command acts on. Order (docs: cli.mdx "Choosing the project"):
+// --app, SYNDAI_APP, the link for this directory or a parent, a git remote that matches a
+// connected repo, the only project, a picker on a terminal. Otherwise exit 2 with the list.
+//
+// A project is a connected repository, joined with its app (live URL, slug) when it has one.
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { CliError, EXIT } from "./errors.js";
+import { findLink, saveLink } from "./store.js";
+import { ask, hostOf } from "./ui.js";
+
+export async function listProjects(ctx) {
+  const customerId = await ctx.customerId();
+  const [{ repos }, { items }] = await Promise.all([
+    ctx.client.call("listRepos"),
+    ctx.client.call("listApps", { params: { customer_id: customerId } }),
+  ]);
+  const appByRepo = new Map(items.map((app) => [app.repository_id, app]));
+  return repos.map((repo) => {
+    const app = appByRepo.get(repo.id);
+    return {
+      id: repo.id,
+      name: repo.display_name || app?.repository_name || repo.full_name,
+      full_name: repo.full_name,
+      live_url: app?.url ?? null,
+      slug: app?.publication?.slug ?? null,
+      repo_urls: [repo.repo_url, repo.clone_url, repo.html_url].filter(Boolean),
+      protected_paths: repo.protected_paths ?? [],
+      customer_id: customerId,
+    };
+  });
+}
+
+export function projectLabel(project) {
+  const host = project.live_url ? hostOf(project.live_url) : null;
+  return host && host !== project.name ? `${project.name} (${host})` : project.name;
+}
+
+/** The project's live host for "Changing <host>", or its name before it is live. */
+export function projectHost(project) {
+  return (project.live_url && hostOf(project.live_url)) || project.name;
+}
+
+/** Projects matching a ref: id, slug, live host, name or repo name (case-insensitive). */
+export function matchRef(projects, ref) {
+  const wanted = ref.trim().toLowerCase();
+  const wantedHost = hostOf(wanted.includes("://") ? wanted : `https://${wanted}`);
+  return projects.filter((p) => {
+    const names = [p.id, p.slug, p.name, p.full_name, p.full_name.split("/").pop()];
+    if (names.some((n) => n?.toLowerCase() === wanted)) return true;
+    return Boolean(p.live_url && wantedHost && hostOf(p.live_url)?.toLowerCase() === wantedHost);
+  });
+}
+
+/**
+ * @param {object} ctx
+ * @param {{app?: string, required?: boolean, picker?: boolean, useLink?: boolean}} options
+ */
+export async function resolveProject(ctx, { app, required = true, picker = true, useLink = true } = {}) {
+  const { io, ui, paths } = ctx;
+  const projects = await listProjects(ctx);
+  const pick = (ref, source) => {
+    const hits = matchRef(projects, ref);
+    if (hits.length === 1) return hits[0];
+    throw noProject(
+      projects,
+      hits.length
+        ? `"${ref}" (${source}) matches ${hits.length} projects; use the id.`
+        : `No project matches "${ref}" (${source}).`,
+    );
+  };
+  if (app) return pick(app, "--app");
+  if (io.env.SYNDAI_APP) return pick(io.env.SYNDAI_APP, "SYNDAI_APP");
+  if (useLink) {
+    const link = findLink(paths, io.cwd);
+    if (link) {
+      const linked = projects.find((p) => p.id === link.project_id);
+      if (linked) return linked;
+      throw noProject(projects, `The project linked to ${link.dir} is no longer in this workspace.`);
+    }
+  }
+  const remotes = gitRemotes(io.cwd);
+  const byRemote = projects.filter((p) => p.repo_urls.some((u) => remotes.has(normalizeRemote(u))));
+  if (byRemote.length === 1) return byRemote[0];
+  if (projects.length === 1) return projects[0];
+  if (picker && ui.interactive && projects.length > 1) return pickInteractively(ctx, projects);
+  if (!required) return null;
+  throw noProject(
+    projects,
+    projects.length
+      ? "Which project? Pass --app or link this directory."
+      : "This workspace has no projects yet.",
+  );
+}
+
+function noProject(projects, message) {
+  const human = projects.length
+    ? ["Projects:", ...projects.map((p) => `  ${projectLabel(p)}  ${p.id}`)].join("\n")
+    : "Start one at https://app.syndai.ai";
+  return new CliError(EXIT.USAGE, message, {
+    next: projects.length ? "syndai link <project>" : null,
+    result: {
+      data: { projects: projects.map(({ id, name, live_url }) => ({ id, name, live_url })) },
+      human,
+    },
+  });
+}
+
+async function pickInteractively(ctx, projects) {
+  for (const [i, p] of projects.entries()) ctx.ui.progress(`  ${i + 1}. ${projectLabel(p)}`);
+  for (;;) {
+    const answer = await ask(ctx.io, `Which project? [1-${projects.length}] `);
+    const index = Number(answer) - 1;
+    if (Number.isInteger(index) && projects[index]) return projects[index];
+  }
+}
+
+/** Normalised remotes of the git checkout at `cwd` (empty outside one). */
+export function gitRemotes(cwd) {
+  let out = "";
+  try {
+    out = execFileSync("git", ["remote", "-v"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    });
+  } catch {
+    return new Set();
+  }
+  return new Set(
+    out
+      .split("\n")
+      .map((line) => line.split(/\s+/)[1])
+      .filter(Boolean)
+      .map(normalizeRemote),
+  );
+}
+
+/** `git@host:o/r.git`, `ssh://git@host:22/o/r`, `https://tok@host/o/r.git` -> `host/o/r`. */
+export function normalizeRemote(url) {
+  const text = url.trim().toLowerCase();
+  const scp = /^(?:[\w.-]+@)?([\w.-]+):(?!\/\/)(.+)$/.exec(text);
+  let normal = text;
+  if (scp && !text.includes("://")) {
+    normal = `${scp[1]}/${scp[2]}`;
+  } else {
+    try {
+      const parsed = new URL(text);
+      normal = parsed.hostname + parsed.pathname;
+    } catch {
+      // Not a URL: compare as typed.
+    }
+  }
+  return normal.replace(/\.git$/, "").replace(/\/+$/, "");
+}
+
+export async function link(ctx, ref) {
+  const project = await resolveProject(ctx, { app: ref ?? ctx.flags.app, useLink: false });
+  const dir = path.resolve(ctx.io.cwd);
+  saveLink(ctx.paths, dir, { project_id: project.id, name: project.name, customer_id: project.customer_id });
+  ctx.ui.result(
+    { dir, project_id: project.id, name: project.name },
+    `Linked ${dir} to ${projectLabel(project)}.`,
+  );
+  return EXIT.OK;
+}

package/src/routes.js

@@ -0,0 +1,56 @@
+// Every REST route the CLI calls, in one table. Code builds paths only through `path()`,
+// so `test/contract.test.js` can prove each one exists, with the same method, in the
+// published OpenAPI (`docs/api/external-coding-v1.openapi.json`). `syndai api` is the one
+// escape hatch that bypasses this table.
+
+const EXT = "/api/v1/external/coding";
+
+export const ROUTES = Object.freeze({
+  deviceStart: ["POST", "/api/v1/cli/device"],
+  deviceToken: ["POST", "/api/v1/cli/device/token"],
+  me: ["GET", `${EXT}/me`],
+  revokeMe: ["DELETE", `${EXT}/me`],
+  listRepos: ["GET", `${EXT}/repos`],
+  updateRepo: ["PATCH", `${EXT}/repos/{coding_repository_id}`],
+  textEdit: ["POST", `${EXT}/repos/{coding_repository_id}/text-edits`],
+  undoTextEdit: ["POST", `${EXT}/repos/{coding_repository_id}/text-edits/{sha}/undo`],
+  listApps: ["GET", `${EXT}/customers/{customer_id}/apps`],
+  getPublication: ["GET", `${EXT}/customers/{customer_id}/repositories/{coding_repository_id}/publication`],
+  updatePublication: [
+    "PATCH",
+    `${EXT}/customers/{customer_id}/repositories/{coding_repository_id}/publication`,
+  ],
+  getBugScan: ["GET", `${EXT}/repositories/{repository_id}/bug-scan`],
+  setBugScan: ["PUT", `${EXT}/repositories/{repository_id}/bug-scan`],
+  getPolicy: ["GET", `${EXT}/policy/defaults`],
+  putPolicy: ["PUT", `${EXT}/policy/defaults`],
+  imageIngest: ["POST", `${EXT}/runs/image-ingest`],
+  createRun: ["POST", `${EXT}/runs`],
+  listRuns: ["GET", `${EXT}/runs`],
+  changeState: ["GET", `${EXT}/runs/{run_id}/change`],
+  runEvents: ["GET", `${EXT}/runs/{run_id}/events`],
+  respond: ["POST", `${EXT}/runs/{run_id}/responses`],
+  cancel: ["POST", `${EXT}/runs/{run_id}/cancel`],
+  revert: ["POST", `${EXT}/runs/{run_id}/revert`],
+  landRetry: ["POST", `${EXT}/runs/{run_id}/land/retry`],
+  landClose: ["POST", `${EXT}/runs/{run_id}/land/close`],
+  goLive: ["POST", `${EXT}/runs/{run_id}/land/go-live`],
+  heldDiff: ["GET", `${EXT}/runs/{run_id}/land/held-diff`],
+});
+
+/** The MCP endpoint `syndai mcp install` points clients at (JSON-RPC, not REST). */
+export const MCP_PATH = "/api/v1/coding/mcp";
+
+/** `[method, path]` for a route, with `{name}` placeholders filled and URL-encoded. */
+export function route(name, params = {}) {
+  const entry = ROUTES[name];
+  if (!entry) throw new Error(`unknown route ${name}`);
+  const [method, template] = entry;
+  const path = template.replace(/\{(\w+)\}/g, (_, key) => {
+    if (params[key] === undefined || params[key] === null) {
+      throw new Error(`route ${name} needs ${key}`);
+    }
+    return encodeURIComponent(String(params[key]));
+  });
+  return [method, path];
+}

package/src/settings.js

@@ -0,0 +1,160 @@
+// `syndai settings` (one project's owner settings) and `syndai api` (the escape hatch).
+//
+// Settings live in four places server-side:
+//   autonomy          repo-scoped policy default       GET/PUT policy/defaults
+//   feature_requests  the app's publication            GET/PATCH .../publication
+//   bug_scan          the repo's Bug Finder schedule   GET/PUT repositories/{id}/bug-scan
+//   protected_paths   the repo row                     PATCH repos/{id} (a key may only tighten)
+
+import { ApiError, CliError, EXIT, explain } from "./errors.js";
+import { projectLabel, resolveProject } from "./projects.js";
+
+const VALUES = {
+  autonomy: ["gated", "auto", "merge"],
+  feature_requests: ["off", "members", "public"],
+  bug_scan: ["on", "off"],
+};
+
+export async function settings(ctx, args) {
+  const { flags, ui } = ctx;
+  const [action = "get", ...pairs] = args;
+  if (!["get", "set"].includes(action) || (action === "set" && pairs.length === 0)) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai settings [get | set key=value...]", {
+      next: "syndai settings set autonomy=auto",
+    });
+  }
+  const project = await resolveProject(ctx, { app: flags.app });
+  for (const pair of pairs) await apply(ctx, project, parsePair(pair));
+  const current = await read(ctx, project);
+  const show = (value) =>
+    value === null ? "-" : Array.isArray(value) ? value.join(", ") || "(none)" : value;
+  const lines = [ui.bold(projectLabel(project))];
+  for (const key of ["autonomy", "feature_requests", "bug_scan", "protected_paths"]) {
+    const why = current.unavailable[key];
+    lines.push(`  ${key.padEnd(17)}${why ? ui.dim(why) : show(current[key])}`);
+  }
+  ui.result({ project_id: project.id, ...current }, lines.join("\n"));
+  return EXIT.OK;
+}
+
+function parsePair(pair) {
+  const match = /^([a-z_]+)(\+?=)(.*)$/.exec(pair);
+  const known = match && (match[1] in VALUES || match[1] === "protected_paths");
+  if (!known || (match[2] === "+=" && match[1] !== "protected_paths")) {
+    throw new CliError(
+      EXIT.USAGE,
+      `Cannot set "${pair}". Keys: autonomy, feature_requests, bug_scan, protected_paths (= or +=).`,
+    );
+  }
+  const [, key, op, value] = match;
+  if (VALUES[key] && !VALUES[key].includes(value)) {
+    throw new CliError(EXIT.USAGE, `${key} is one of ${VALUES[key].join(", ")}.`);
+  }
+  return { key, op, value };
+}
+
+async function apply(ctx, project, { key, op, value }) {
+  const { client } = ctx;
+  if (key === "autonomy") {
+    const current = await orNull(client.call("getPolicy", { query: { coding_repository_id: project.id } }));
+    await client.call("putPolicy", {
+      body: { coding_repository_id: project.id, config: { ...(current?.config ?? {}), autonomy: value } },
+    });
+  } else if (key === "feature_requests") {
+    await client.call("updatePublication", {
+      params: { customer_id: project.customer_id, coding_repository_id: project.id },
+      body: { feature_requests: value },
+    });
+  } else if (key === "bug_scan") {
+    await client.call("setBugScan", {
+      params: { repository_id: project.id },
+      body: { enabled: value === "on" },
+    });
+  } else {
+    const added = value
+      .split(",")
+      .map((p) => p.trim())
+      .filter(Boolean);
+    const next = op === "+=" ? [...project.protected_paths, ...added] : added;
+    // The server refuses a loosening from a key with HUMAN_APPROVAL_REQUIRED + review_url.
+    const repo = await client.call("updateRepo", {
+      params: { coding_repository_id: project.id },
+      body: { protected_paths: next },
+    });
+    project.protected_paths = repo.protected_paths ?? next;
+  }
+}
+
+async function read(ctx, project) {
+  const { client } = ctx;
+  const ids = { customer_id: project.customer_id, coding_repository_id: project.id };
+  const [policy, publication, bugScan] = await Promise.all([
+    settle(client.call("getPolicy", { query: { coding_repository_id: project.id } })),
+    settle(client.call("getPublication", { params: ids })),
+    settle(client.call("getBugScan", { params: { repository_id: project.id } })),
+  ]);
+  const unavailable = {};
+  for (const [key, got] of [
+    ["autonomy", policy],
+    ["feature_requests", publication],
+    ["bug_scan", bugScan],
+  ]) {
+    if (got.error) unavailable[key] = got.error;
+  }
+  return {
+    autonomy: policy.value?.config?.autonomy ?? null,
+    feature_requests: publication.value?.feature_requests ?? null,
+    bug_scan: bugScan.value ? (bugScan.value.enabled ? "on" : "off") : null,
+    protected_paths: project.protected_paths,
+    unavailable,
+  };
+}
+
+/** A read that may be missing (404 -> null) or not allowed for this key or plan (-> error). */
+async function settle(promise) {
+  try {
+    return { value: await promise };
+  } catch (err) {
+    if (!(err instanceof ApiError)) throw err;
+    return err.status === 404 ? { value: null } : { error: explain(err).message };
+  }
+}
+
+async function orNull(promise) {
+  try {
+    return await promise;
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) return null;
+    throw err;
+  }
+}
+
+export async function api(ctx, [method, target]) {
+  const { client, flags, io, ui } = ctx;
+  const verb = method?.toUpperCase();
+  if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(verb) || !target) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai api <METHOD> <path> [--json body]", {
+      next: "syndai api GET /runs",
+    });
+  }
+  const full = target.startsWith("/api/") ? target : `/api/v1/external/coding/${target.replace(/^\/+/, "")}`;
+  const [pathOnly, search = ""] = full.split("?");
+  let body;
+  if (typeof flags.json === "string") {
+    try {
+      body = JSON.parse(flags.json);
+    } catch {
+      throw new CliError(EXIT.USAGE, "--json must be valid JSON.");
+    }
+  }
+  const res = await client.send(verb, pathOnly, {
+    query: Object.fromEntries(new URLSearchParams(search)),
+    body,
+    raw: true,
+  });
+  io.stdout.write(`${JSON.stringify(res.body, null, ui.json ? 0 : 2)}\n`);
+  if (res.status < 400) return EXIT.OK;
+  const { exitCode, message } = explain(new ApiError(res.status, res.body, res.headers));
+  ui.progress(`error: ${message}`);
+  return exitCode;
+}