syndai 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to the `syndai` npm package. Versions follow semver.
+
+## 0.4.0
+
+Every published API operation, and a project's recurring runs.
+
+- `api <operationId>` calls any operation in the live API description (`/openapi.json`,
+  cached for 24 hours). `api` lists them; `api <operationId> --help` shows the parameters
+  and body. Fields come gh-style: `-f key=value` (string), `-F key=value` (true, false,
+  null, a number, or `@file`), `key[]=value` for a list. `--input FILE|-` sends a whole
+  body. `--paginate` follows `next_cursor` and prints one list. The workspace and this
+  directory's project fill required path parameters. `api <METHOD> <path>` still works.
+- `schedule list|show|add|edit|pause|resume|run-now|delete`: a project's recurring runs,
+  with cadence presets (`--every hourly|daily|weekdays|weekly` and `--at`, or a cron),
+  `--tz`, and a per-run cap (`--budget`).
+- `repeat <run> --every ...` repeats a run you liked. The server copies its original
+  prompt and project; the first run is the next scheduled time.
+- `login --scope S` asks for more access. A command that needs a scope the stored key
+  lacks asks once, on a terminal, to approve it in the browser and then retries.
+  `SYNDAI_API_KEY` never does this. Re-login now revokes the key it replaces.
+
+Breaking:
+
+- `--json` is machine output on every command. The request body on `api` and `answer`
+  is now `--input FILE|-` (the old string `--json` body is gone).
+
+## 0.3.0
+
+The package becomes the Syndai owner CLI.
+
+- `login` (browser approval, RFC 8628 device flow), `login --with-token`, `logout`, `whoami`.
+  Keys live in `$XDG_CONFIG_HOME/syndai/credentials.json` (0600), one per workspace;
+  `SYNDAI_API_KEY` wins. There is no `--api-key` flag.
+- `change` creates a change and follows it to the outcome. Its request id is saved before
+  the request, so a retry or a rerun after a crash never makes a second change.
+- `watch` (with `--logs`), `answer`, `review`, `go-live`, `revert`, `cancel`, `status`,
+  `edit-text`, `link`, `settings`, `api`.
+- `mcp install claude|cursor|codex` writes the Syndai MCP server into that tool's user
+  config with its own key.
+- Exit codes 0-7 and 130 are a stable contract; `--json` (or a non-terminal stdout) prints
+  machine-readable results.
+- Node 22 or newer. Zero dependencies. No telemetry.
+
+Removed: the 0.2.0 `connect` pointer (connecting a Claude or ChatGPT plan happens in the
+portal, under Connections).
+
+## 0.2.0
+
+Never published. `connect` printed a pointer to the portal.
+
+## 0.1.1
+
+Published from the `solozerolabs/syndai-connect` mirror: the retired `connect` pairing flow.

package/README.md

@@ -1,62 +1,107 @@
-# syndai connect
+# syndai
 
-Connect your **Claude** and **ChatGPT** plans to a Syndai workspace with one
-command:
+The Syndai owner CLI. Say what to change; Syndai builds it, runs every check, puts
+it live and tells you the URL. Nobody babysits.
 
 ```bash
-npx -y syndai connect <code>
+npx -y syndai@latest login
+npx -y syndai@latest change "make the header blue"
+# Changing bakery.syndai.app · goes live when checks pass
 ```
 
-Get `<code>` from your Syndai portal → **Connections → Connect a plan**. It is a
-single-use code with a 15-minute TTL.
-
-## What it does
-
-1. **Claims** the code and shows you where it will connect:
-   `Connect to workspace "Acme" (s••@acme.com)? Phrase: amber-falcon-42 [y/N]` —
-   default **No**, no `--yes` flag. Confirm the phrase matches what the portal
-   shows, then the portal owner clicks **Approve**.
-2. **Claude:** if `claude` is on your PATH, mints a fresh plan token with
-   `claude setup-token` (under a PTY, so its full-screen UI works) and verifies it
-   with the official CLI before uploading. If `claude` is not installed, it tells
-   you to run `claude setup-token` yourself and paste the `sk-ant-oat01-…` value —
-   the paste is hidden.
-3. **ChatGPT:** if `codex` is on your PATH, runs `codex login` into a throwaway
-   `CODEX_HOME` (Syndai keeps its own login lineage — copying your laptop's
-   `auth.json` would log one of you out), captures the resulting `auth.json`, and
-   deletes the temp directory.
-4. **Uploads** whatever it collected in exactly one call. The portal flips to
-   **Connected ✓**.
-
-One code connects both providers if both CLIs are present.
-
-## It stores nothing, and echoes no token
-
-The tool holds your token only in memory for the single upload. It never writes it
-to disk, never puts it on the clipboard, and never prints it to your terminal or
-scrollback. Pasted tokens are read with terminal echo off.
-
-## Configuration
-
-- `SYNDAI_API_URL` — override the API base (default `https://api.syndai.ai`).
-
-## Requirements
-
-- Node.js **>= 18** (dependency-free — Node builtins only).
-- `claude` and/or `codex` on your PATH for the one-command path; otherwise the
-  Claude paste fallback still works.
-
-## Source & provenance
-
-This package is developed in the Syndai monorepo under `tools/syndai-connect/`
-and **mirrored to the public repo
-[`solozerolabs/syndai-connect`](https://github.com/solozerolabs/syndai-connect)**
-for the npm provenance publish (owner action **O1**) — a private monorepo cannot
-publish with sigstore provenance. Published as `syndai` with
-`publishConfig.provenance`.
+Node 22 or newer, zero dependencies, no telemetry. The customer guide is the docs
+site's **CLI** page, https://syndai.ai/docs/cli (`web/content/docs/cli.mdx`); this
+README is for whoever works on the package.
+
+## Commands
+
+| command | does |
+|---|---|
+| `login [--with-token] [--scope S]...`, `logout`, `whoami` | browser-approved key (device flow); `--scope` asks for access on top of the key's current scopes; `--with-token` reads a key from stdin. Re-login saves the new key, then revokes the old one |
+| `link [project]` | remember which project this directory changes (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo) |
+| `change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome |
+| `new "<what>" [--no-learn] [--no-wait] [--timeout D]` | start a New project; a product URL in the text builds your own version of it (its feature pick is asked inline, Enter keeps the pre-checked core) |
+| `edit-text [--app A] [--page /] --from "..." --to "..."` / `--undo <sha>` | instant, free, undoable text swap on a live site |
+| `watch <run> [--timeout D] [--logs]` | follow any change; `--logs` tails its events |
+| `answer <run> [--input FILE\|-]` | answer an open question (`--input`: `{"entries":[...]}` from a file or stdin) |
+| `review <run> [--retry \| --close]` | see why a change is held, then approve it in the browser |
+| `go-live`, `revert`, `cancel <run>` | land actions |
+| `status [--app A]` | what is running, and everything that needs you |
+| `settings [--app A] [get \| set k=v...]` | `autonomy`, `feature_requests`, `bug_scan`, `protected_paths` (`+=` adds) |
+| `mcp install claude\|cursor\|codex` | add the Syndai MCP server to that tool's user config, with its own key |
+| `schedule list [--app A \| --all]`, `show <id>` | a project's recurring runs: cadence, next fires, History |
+| `schedule add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]` | create one; `E` is `hourly` (`--at :MM`), `daily`/`weekdays` (`--at HH:MM`), `weekly` (`--at "mon HH:MM"`) or a 5-field cron |
+| `schedule edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD\|none]` | change only what differs |
+| `schedule pause \| resume \| run-now \| delete <id> [--yes]` | manage one (`delete` asks on a terminal, needs `--yes` off one) |
+| `repeat <run> --every E [--at T] [--tz Z] [--budget USD]` | repeat a run you liked; the server copies its prompt and project; the first run is the next scheduled time |
+| `api` / `api <operationId> --help` | list every published operation / show one's parameters and body |
+| `api <operationId> \| <METHOD> <path> [-f k=v]... [-F k=v]... [--input FILE\|-] [--paginate] [--app A]` | call it with your key (`-f` string, `-F` typed, `k[]=v` lists) |
+
+A 403 that names a missing scope asks, on a terminal with a stored login, to approve
+it in the browser and retries once. `SYNDAI_API_KEY` never steps up; off a terminal the
+error names `syndai login --scope <scope>`. Members, keys and unpublish are portal-only.
+
+Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs you,
+4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
+unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
+
+## Layout
+
+- `bin/syndai.js`: the entrypoint; wires SIGINT to an AbortSignal.
+- `src/main.js`: the command table, argument parsing (`util.parseArgs`), the one error report.
+- `src/routes.js`: every REST route the CLI calls. Code builds paths only through it.
+- `src/http.js`: `fetch`, retries (GETs and keyed POSTs only), `User-Agent: syndai-cli/<v>`.
+- `src/errors.js`: exit codes; a problem+json `code` becomes one sentence plus the next command.
+- `src/auth.js`, `src/store.js`: credentials (0600, by workspace), links, pending change ids.
+- `src/projects.js`: which project a command acts on.
+- `src/watch.js`: the ChangeState long-poll loop, questions, `--logs`.
+- `src/openapi.js`: the live `/openapi.json` (cached 24h per host in `$XDG_CACHE_HOME/syndai`).
+- `src/api.js`: `syndai api` (operations by id, fields, `--paginate`).
+- `src/schedules.js`: `schedule` and `repeat` (the preset to cron mapping of `apps/portal-v2/src/lib/cadence.ts`).
+- `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development
 
 ```bash
-node --test test/     # pure-helper unit tests (no network, no subprocess)
+cd tools/syndai-connect && node --test
 ```
+
+CI runs it in its own **CLI Checks** job (`pr-ci.yml`, `main-ci.yml`) whenever
+`tools/syndai-connect/**`, `docs/api/**` or the portal's `cadence.ts` changes; it is
+part of **PR Gate** and deploys nothing.
+
+The suite runs a fake API on 127.0.0.1 (serving `/openapi.json` from the snapshot) and
+drives the CLI in-process (plus two child-process tests for Ctrl-C and a clean exit).
+`test/schedule.test.js` imports `apps/portal-v2/src/lib/cadence.ts` to prove the
+`--every` presets give the portal's cron; that needs a Node that strips TypeScript
+types (23.6+, as `.nvmrc`), and is skipped on Node 22. `test/contract.test.js` checks
+every route in `src/routes.js` against the published OpenAPI,
+`docs/api/external-coding-v1.openapi.json`. It goes red when a backend route the
+CLI uses is renamed or not yet published; regenerate the snapshot with
+`cd backend && uv run python scripts/dump_external_openapi.py`, or check a fresh
+render without touching it:
+`SYNDAI_OPENAPI_JSON=/tmp/dump.json node --test test/contract.test.js`.
+
+## Publishing (maintainers)
+
+Never `npm publish` by hand. `.github/workflows/publish-cli.yml` publishes on a
+`cli-v<version>` tag, with the same trust boundary as `publish-sync.yml`:
+
+1. Bump `version` in `package.json` and add a `CHANGELOG.md` entry in a gated commit.
+2. Once that commit is on `main` and CI is green, push a lightweight tag on exactly
+   that commit: `git tag cli-v<version> <sha> && git push Syndai refs/tags/cli-v<version>`.
+3. The `build` job (no publish credential) checks the tag matches the version and
+   sits on `main`, skips a version already on npm, runs `node --test`, packs with
+   `npm pack` and checks the tarball. The `publish` job only downloads that tarball
+   and publishes it tokenlessly (npm trusted publishing). No provenance: npm does
+   not generate it from a private repository.
+
+One-time owner setup (this retires the `solozerolabs/syndai-connect` mirror, which
+published 0.1.1):
+
+1. GitHub: add `cli-v*` to the `npm-publish` environment's deployment rule, and a
+   tag ruleset on `refs/tags/cli-v*` restricting create, update and delete (admins
+   bypass), as for `sync-v*`.
+2. npm: on the `syndai` package, replace the trusted publisher with
+   `solozerolabs/Syndai`, workflow `publish-cli.yml`, environment `npm-publish`,
+   and keep "disallow tokens".

package/bin/syndai.js

@@ -1,33 +1,17 @@
 #!/usr/bin/env node
-// Entrypoint for the `syndai` CLI. One subcommand today: `connect <code>`.
+// Entrypoint for the `syndai` owner CLI (`npx -y syndai@latest <command>`).
+//
+// Ctrl-C aborts the current wait and the command exits 130 after printing how to resume;
+// it never cancels a change. A second Ctrl-C exits at once.
 
-import { runConnect } from "../src/connect.js";
+import { main, processIo } from "../src/main.js";
 
-async function main(argv) {
-  const [subcommand, ...rest] = argv;
-  switch (subcommand) {
-    case "connect":
-      return runConnect(rest[0]);
-    case undefined:
-    case "-h":
-    case "--help":
-    case "help":
-      console.log("syndai — connect your Claude and ChatGPT plans to a Syndai workspace");
-      console.log("");
-      console.log("usage: npx -y syndai connect <code>");
-      console.log("");
-      console.log("Get <code> from your Syndai portal: Connections → Connect a plan.");
-      return subcommand ? 0 : 2;
-    default:
-      console.error(`syndai: unknown command "${subcommand}"`);
-      console.error("usage: npx -y syndai connect <code>");
-      return 2;
-  }
-}
+const interrupt = new AbortController();
+process.once("SIGINT", () => {
+  interrupt.abort();
+  process.once("SIGINT", () => process.exit(130));
+});
 
-main(process.argv.slice(2))
-  .then((code) => process.exit(code || 0))
-  .catch((e) => {
-    console.error(`syndai: ${e && e.message ? e.message : e}`);
-    process.exit(1);
-  });
+process.exitCode = await main(process.argv.slice(2), processIo(interrupt.signal));
+// Idle keep-alive sockets or a stray child must not hold the result back.
+setTimeout(() => process.exit(), 1000).unref();

package/package.json

@@ -1,30 +1,25 @@
 {
   "name": "syndai",
-  "version": "0.1.1",
-  "description": "Connect your Claude and ChatGPT plans to a Syndai workspace with one command. Stores nothing locally; never echoes a token.",
+  "version": "0.4.0",
+  "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {
     "syndai": "bin/syndai.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/solozerolabs/syndai-connect.git"
-  },
-  "homepage": "https://github.com/solozerolabs/syndai-connect#readme",
+  "homepage": "https://syndai.ai",
   "license": "MIT",
   "files": [
     "bin/",
     "src/",
-    "README.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test"
   },
   "publishConfig": {
-    "provenance": true,
     "access": "public"
   }
 }

package/src/api.js

@@ -1,70 +1,202 @@
-// Minimal JSON-over-HTTPS client for the pairing routes, built on node:https so
-// the package stays dependency-free. Every helper returns { status, body } where
-// body is the parsed JSON (or the raw string when it isn't JSON) — callers decide
-// what a non-2xx means, per route.
+// `syndai api`: every published operation, by operationId (from the live OpenAPI, see
+// openapi.js) or as a raw `METHOD path`. Fields come gh-style: `-f key=value` is a string,
+// `-F key=value` is typed (true, false, null, a number, or @file for a file's text), and
+// `key[]=value` builds a list. A path-parameter field fills the path; any other field goes to
+// the query on GET and DELETE and to the JSON body otherwise. `--input FILE|-` is the whole
+// body instead. The step-up on a missing scope happens in http.js, so it covers this too.
 
-import https from "node:https";
-import http from "node:http";
-import { URL } from "node:url";
+import fs from "node:fs";
+import path from "node:path";
+import { ApiError, CliError, EXIT, explain } from "./errors.js";
+import { findOperation, HTTP_METHODS, loadOperations, matchPath, shortPath } from "./openapi.js";
+import { resolveProject } from "./projects.js";
+import { readJsonInput } from "./ui.js";
 
-// Production API host. Overridable with SYNDAI_API_URL for staging/dev. Matches
-// tools/syndai-pickup (_DEFAULT_API_BASE) and apps/portal (NEXT_PUBLIC_API_BASE).
-export function apiBase() {
-  return (process.env.SYNDAI_API_URL || "https://api.syndai.ai").replace(/\/+$/, "");
+const EXT = "/api/v1/external/coding";
+const MAX_PAGES = 50;
+const USAGE = "syndai api [<operationId> | <METHOD> <path>] [-f k=v]... [-F k=v]... [--input F] [--paginate]";
+
+export async function api(ctx, args) {
+  const { flags } = ctx;
+  const [first, second, ...extra] = args;
+  if (!first) return listOperations(ctx);
+  const raw = HTTP_METHODS.includes(first.toUpperCase());
+  if (extra.length || (raw && !second) || (!raw && second)) {
+    throw new CliError(EXIT.USAGE, `Usage: ${USAGE}`, { next: "syndai api" });
+  }
+
+  let op = null;
+  let method;
+  let template;
+  const query = {};
+  if (raw) {
+    method = first.toUpperCase();
+    const full = second.startsWith("/api/") ? second : `${EXT}/${second.replace(/^\/+/, "")}`;
+    const [pathOnly, search = ""] = full.split("?");
+    template = pathOnly;
+    Object.assign(query, Object.fromEntries(new URLSearchParams(search)));
+    if (flags.help) {
+      ctx.io.stdout.write(`usage: ${USAGE}\n`);
+      return EXIT.OK;
+    }
+    if (flags.paginate) op = matchPath((await loadOperations(ctx)).operations, method, pathOnly);
+  } else {
+    op = await findOperation(ctx, first);
+    if (flags.help) return describeOperation(ctx, op);
+    method = op.method;
+    template = op.path;
+  }
+
+  const pathParams = new Set(
+    op && !raw ? op.params.filter((p) => p.in === "path").map((p) => p.name) : [],
+  );
+  const filled = {};
+  const body = {};
+  for (const [key, value] of Object.entries(collectFields(ctx))) {
+    if (pathParams.has(key)) filled[key] = value;
+    else if (method === "GET" || method === "DELETE") query[key] = value;
+    else body[key] = value;
+  }
+  let payload = Object.keys(body).length ? body : undefined;
+  if (flags.input !== undefined) {
+    if (payload) throw new CliError(EXIT.USAGE, "--input is the whole body; drop the body fields or --input.");
+    payload = await readJsonInput(ctx.io, flags.input);
+  }
+  for (const name of pathParams) {
+    if (filled[name] === undefined) filled[name] = await autoFill(ctx, op, name);
+  }
+  const target = template.replace(/\{(\w+)\}/g, (_, key) => encodeURIComponent(String(filled[key])));
+
+  if (flags.paginate) return paginate(ctx, op, method, target, query);
+  const res = await ctx.client.send(method, target, { query, body: payload, raw: true });
+  return printResponse(ctx, res);
 }
 
-function request(method, path, payload) {
-  const url = new URL(apiBase() + path);
-  const body = payload === undefined ? undefined : JSON.stringify(payload);
-  const transport = url.protocol === "http:" ? http : https;
-  const options = {
-    method,
-    hostname: url.hostname,
-    port: url.port || undefined,
-    path: url.pathname + url.search,
-    headers: {
-      accept: "application/json",
-      "user-agent": "syndai-connect",
-    },
+/** `-f`/`-F` pairs as one object; a repeated key without `[]` is a usage error. */
+function collectFields(ctx) {
+  const fields = {};
+  const add = (pair, typed) => {
+    const eq = pair.indexOf("=");
+    if (eq < 1) throw new CliError(EXIT.USAGE, `Fields are key=value, not "${pair}".`);
+    let key = pair.slice(0, eq);
+    const value = typed ? typedValue(ctx, pair.slice(eq + 1)) : pair.slice(eq + 1);
+    const list = key.endsWith("[]");
+    if (list) key = key.slice(0, -2);
+    if (list && (fields[key] === undefined || Array.isArray(fields[key]))) {
+      fields[key] = [...(fields[key] ?? []), value];
+    } else if (key in fields) {
+      throw new CliError(EXIT.USAGE, `${key} is given twice; use ${key}[]=... for a list.`);
+    } else {
+      fields[key] = value;
+    }
   };
-  if (body !== undefined) {
-    options.headers["content-type"] = "application/json";
-    options.headers["content-length"] = Buffer.byteLength(body);
+  for (const pair of ctx.flags["raw-field"] ?? []) add(pair, false);
+  for (const pair of ctx.flags.field ?? []) add(pair, true);
+  return fields;
+}
+
+function typedValue(ctx, text) {
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  if (text.startsWith("@")) {
+    try {
+      return fs.readFileSync(path.resolve(ctx.io.cwd, text.slice(1)), "utf8");
+    } catch (err) {
+      throw new CliError(EXIT.USAGE, `Cannot read ${text.slice(1)} (${err.code ?? err.message}).`);
+    }
   }
-  return new Promise((resolve, reject) => {
-    const req = transport.request(options, (res) => {
-      const chunks = [];
-      res.on("data", (c) => chunks.push(c));
-      res.on("end", () => {
-        const text = Buffer.concat(chunks).toString("utf8");
-        let parsed = text;
-        try {
-          parsed = text ? JSON.parse(text) : {};
-        } catch {
-          /* leave as raw text */
-        }
-        resolve({ status: res.statusCode || 0, body: parsed });
-      });
-    });
-    req.on("error", reject);
-    if (body !== undefined) req.write(body);
-    req.end();
-  });
+  return text;
 }
 
-export function post(path, payload) {
-  return request("POST", path, payload);
+/** Only required path parameters fill themselves: the workspace, and this directory's project. */
+async function autoFill(ctx, op, name) {
+  if (name === "customer_id") return ctx.customerId();
+  if (name === "coding_repository_id" || name === "repository_id") {
+    return (await resolveProject(ctx, { app: ctx.flags.app, picker: false })).id;
+  }
+  throw new CliError(EXIT.USAGE, `${op.id} needs ${name}.`, { next: `syndai api ${op.id} -f ${name}=...` });
+}
+
+async function paginate(ctx, op, method, target, query) {
+  if (method !== "GET") throw new CliError(EXIT.USAGE, "--paginate works on GET operations only.");
+  const names = new Set((op?.params ?? []).map((p) => p.name));
+  const cursorParam = ["cursor", "after"].find((name) => names.has(name));
+  if (!cursorParam) {
+    throw new CliError(EXIT.USAGE, `${op?.id ?? target} does not page (no cursor or after parameter).`);
+  }
+  const items = [];
+  for (let page = 1; ; page++) {
+    const res = await ctx.client.send(method, target, { query, raw: true });
+    if (res.status >= 400) return printResponse(ctx, res);
+    const arrays = Object.entries(res.body ?? {}).filter(([, value]) => Array.isArray(value));
+    if (arrays.length !== 1) {
+      throw new CliError(EXIT.FAILED, `${op.id} does not answer with one list, so it cannot be paged.`);
+    }
+    items.push(...arrays[0][1]);
+    const next = res.body.next_cursor;
+    if (!next) break;
+    if (page >= MAX_PAGES) {
+      ctx.ui.progress(ctx.ui.yellow(`Stopped after ${MAX_PAGES} pages; narrow the query to see the rest.`));
+      break;
+    }
+    query[cursorParam] = next;
+  }
+  ctx.io.stdout.write(`${JSON.stringify(items, null, ctx.ui.json ? 0 : 2)}\n`);
+  return EXIT.OK;
 }
 
-/** True for any 2xx status. */
-export function ok(status) {
-  return status >= 200 && status < 300;
+/** The body as JSON on stdout (problem bodies too); an error line and its next step on stderr. */
+function printResponse(ctx, res) {
+  const { io, ui } = ctx;
+  if (res.body !== null && res.body !== undefined) {
+    io.stdout.write(`${JSON.stringify(res.body, null, ui.json ? 0 : 2)}\n`);
+  }
+  if (res.status < 400) return EXIT.OK;
+  const { exitCode, message, next } = explain(new ApiError(res.status, res.body, res.headers));
+  ui.progress(`${ui.red("error:")} ${message}`);
+  if (next) ui.progress(`  next: ${next}`);
+  return exitCode;
 }
 
-/** Best-effort human message out of a JSON error body. */
-export function errorMessage(body) {
-  if (body && typeof body === "object") {
-    return body.detail || body.message || body.error || JSON.stringify(body);
+async function listOperations(ctx) {
+  const { ui } = ctx;
+  const { operations } = await loadOperations(ctx);
+  const sorted = [...operations].sort((a, b) => a.group.localeCompare(b.group) || a.id.localeCompare(b.id));
+  const width = Math.max(...sorted.map((op) => op.id.length));
+  const lines = [];
+  let group = null;
+  for (const op of sorted) {
+    if (op.group !== group) {
+      group = op.group;
+      lines.push(`${lines.length ? "\n" : ""}${ui.bold(group)}`);
+    }
+    lines.push(`  ${op.id.padEnd(width)}  ${op.method.padEnd(6)} ${shortPath(op.path)}`);
+  }
+  lines.push(
+    "",
+    `usage: ${USAGE}`,
+    "Details of one: syndai api <operationId> --help. Paths are relative to /api/v1/external/coding.",
+  );
+  ui.result(
+    { operations: sorted.map(({ id, method, path: opPath, summary }) => ({ operation_id: id, method, path: opPath, summary })) },
+    lines.join("\n"),
+  );
+  return EXIT.OK;
+}
+
+function describeOperation(ctx, op) {
+  const lines = [`${ctx.ui.bold(op.id)}  ${op.method} ${op.path}`];
+  if (op.summary) lines.push(op.summary);
+  if (op.params.length) {
+    lines.push("", "Parameters (-f name=value):");
+    for (const p of op.params) lines.push(`  ${p.name}  ${p.in}${p.required ? ", required" : ""}`);
+  }
+  if (op.body) {
+    lines.push("", `Body${op.body.schema ? ` (${op.body.schema})` : ""}: fields, or --input FILE`);
+    for (const f of op.body.fields) lines.push(`  ${f.name}  ${f.type}${f.required ? ", required" : ""}`);
   }
-  return String(body || "unknown error");
+  ctx.ui.result(op, lines.join("\n"));
+  return EXIT.OK;
 }