@datumos/datum-cli 0.0.0 → 0.588.0

package/cli/help.js

@@ -0,0 +1,509 @@
+/**
+ * Help rendering for `datum` — every line here is DERIVED from the OpenAPI
+ * spec (summaries, parameter/field descriptions, enums, required flags),
+ * so `--help` stays current with zero CLI maintenance. If a help page reads
+ * poorly, fix the spec (server/src/openapi/spec.ts), not this file.
+ */
+/** ANSI styling, disabled when stdout is not a TTY (pipes stay clean). */
+export function createStyle(colors) {
+    const wrap = (code) => (s) => colors ? `\x1b[${code}m${s}\x1b[0m` : s;
+    return {
+        bold: wrap("1"),
+        dim: wrap("2"),
+        cyan: wrap("36"),
+        yellow: wrap("33"),
+        green: wrap("32"),
+    };
+}
+/**
+ * The hand-written commands — the CLI's own and the person sign-in
+ * (docs/developer-access.md). They are not in the OpenAPI-derived command
+ * tree, so `renderCommandHelp` never sees them: the root help, `datum
+ * commands` and `datum <cmd> --help` all read THIS table.
+ */
+export const BUILTIN_COMMANDS = [
+    {
+        tokens: ["login"],
+        usage: "datum login [--base-url <url>]",
+        summary: "sign in with your Microsoft account (device code)",
+        detail: "Runs the OAuth device-code flow against the deployment's Entra app registration and stores the\n" +
+            "tokens in credentials.json (0600). The login becomes the default --base-url. Note: an API key\n" +
+            "(--api-key / DATUM_API_KEY / MCA_API_KEY) always wins over the sign-in — `datum whoami` tells\n" +
+            "you which credential the next API call will use.",
+    },
+    {
+        tokens: ["update"],
+        usage: "datum update [--check | --to <version|package> | --auto on|off]",
+        summary: "update the CLI to the release the server runs (it also updates itself in the background)",
+        detail: "Asks the server (GET /api/cli/latest) for the release it runs and installs that CLI bundle next to the\n" +
+            "current one (verified by sha512, smoke-tested with --version); the NEXT `datum` runs it. Without this\n" +
+            "command the CLI checks at most every 6 h in the background, and updates in the foreground when it is\n" +
+            "older than the server's minimum. A failed install of the same bundle is retried automatically after\n" +
+            "15 min, 6 h, then daily; this command tries at once. --check prints what runs here, what the server\n" +
+            "offers and the last failed install; --to switches to an installed version (rollback), `--to package`\n" +
+            "back to the npm-installed one; --auto off opts this user out. DATUM_AUTOUPDATE=on|off|min-only and\n" +
+            "DATUM_NO_AUTOUPDATE=1 win; CI=true means off.",
+    },
+    {
+        tokens: ["whoami"],
+        usage: "datum whoami [--space <slug>]",
+        summary: "who the server says you are, your role, and which credential the next call uses",
+        detail: "GET /api/me with your sign-in on the org host (or the space host with --space / DATUM_SPACE):\n" +
+            "identity, effective role (the same as in the panel), role source. `nextCallUses` says whether API\n" +
+            "commands would ride your sign-in (/api) or an API key found in the flags/environment (/public/api).",
+    },
+    {
+        tokens: ["logout"],
+        usage: "datum logout [--base-url <url>]",
+        summary: "forget the local sign-in",
+        detail: "Deletes the stored tokens for that origin; the Microsoft session itself is untouched.",
+    },
+    {
+        tokens: ["a2a"],
+        usage: "datum a2a <card get | send \"…\" | task get|list|cancel …> [a2a flags] [--space <slug>] [--agent <nick>]",
+        summary: "delegate a task to the space's agent (or a named one) over A2A — the official a2a CLI, as you, token never shown",
+        detail: "Runs the official a2a CLI (github.com/a2aproject/a2a-cli) against the space's A2A channel (#1382) with\n" +
+            "your sign-in: the space host comes from --space (or the host of the login), the access token goes only\n" +
+            "into the a2a process, the nearest .env is replaced by an empty config, and flags that would move the\n" +
+            "destination or the credential (-a, --agent-card, --endpoint, --auth, --svc-param, --config, --tenant,\n" +
+            "--insecure) are refused. The verb comes first: card, send or task.\n" +
+            "--agent <nick> (env DATUM_A2A_AGENT) addresses that agent of the space instead of its default one\n" +
+            "(#1647) — same host, same sign-in; datum consumes the flag, a2a never sees it.\n" +
+            '  datum a2a send --space adops --stream "Czemu das-bidder ma wzrost 5xx od 14:00?"\n' +
+            '  datum a2a send --space adops --agent bidder-doctor --async "Zbadaj 5xx das-biddera"\n' +
+            "  datum a2a task get <taskId> --wait --timeout 30m --space adops",
+    },
+    {
+        tokens: ["mcp", "serve"],
+        usage: "datum mcp serve [--space <slug>]",
+        summary: "stdio MCP server for Claude Code — the space's agent tools",
+        detail: "Proxies Claude Code (stdio) to POST <space host>/api/mcp with your sign-in. Not signed in?\n" +
+            "It serves `datum_login` whose result carries the device code. Logs go to stderr (stdout is the\n" +
+            "protocol). Registered by the `datum` Claude Code plugin's .mcp.json; a project pins its space with\n" +
+            '`"args": ["mcp", "serve", "--space", "<slug>"]`.',
+    },
+    {
+        tokens: ["artifacts", "publish"],
+        usage: "datum artifacts publish <dir> [--key <k>] [--title <t>] [--description <d>] [--entry <file>] [--space <slug>]",
+        summary: "publish a directory (a page plus its assets) as an artifact version",
+        detail: "Walks <dir> by the collector's rules (no dotfiles, no node_modules, no symlinks, at most 200 files),\n" +
+            "reads <dir>/manifest.json when it is there ({ key, title, description, entry }; the flags win), then\n" +
+            "picks the transport: up to 8 MiB the files ride ONE request body, above it the two-step direct upload\n" +
+            "(plan → a presigned PUT per file → commit), which is how the runtime ships a run's outputs. The `key`\n" +
+            "is the artifact's identity in the space — the same key appends a version to the SAME link.\n" +
+            "Visibility is never set here: a new artifact is space-private until a human climbs the ladder in the\n" +
+            "panel, and a new version of an artifact ALREADY shared beyond its space comes back as a draft awaiting\n" +
+            "an operator's approval (#589, docs/artifacts.md). Hand-written because it is a walk plus several calls;\n" +
+            "`datum artifacts publish plan` / `… commit` are the derived commands for the raw two-step endpoints.",
+    },
+    {
+        tokens: ["outputs", "download"],
+        usage: "datum outputs download <id> [--out <file>] [--space <slug>]",
+        summary: "download an output file's bytes (to --out, or to stdout)",
+        detail: "Reads the output's metadata (GET /api/outputs/<id>) and fetches its bytes from /outputs/<id>/<name> with\n" +
+            "the same credential (#570, #2680) — the only way a run gets a file an earlier run made without touching\n" +
+            "storage. Without --out the bytes go to stdout. Find the id with a search:\n" +
+            "  datum outputs list --name Adserver_koszty --limit 5\n" +
+            "  datum outputs download <id> --out prognoza.xlsx\n" +
+            "The size and sha256 are checked against the metadata; a mismatch fails and leaves no file.",
+    },
+    {
+        tokens: ["preview", "up"],
+        usage: "datum preview up --port <port> [--vhost <vhost>] [--machine <name>] [--space <slug>]",
+        summary: "preview a port of your own machine through the Accelerator gateway (Ctrl+C closes it)",
+        detail: "The gateway's `cde app start` (#2928): the platform routes the vhost's gateway variant to 127.0.0.1:<port>\n" +
+            "of your personal machine, and its satellite holds the machine's preview link — run `datum satellite up --pair`\n" +
+            "once on this computer and keep the daemon running. Prints the link to open and the headers your own requests\n" +
+            "(curl, Playwright) send through the edge, then follows the preview until Ctrl+C (or a closed terminal),\n" +
+            "which closes it. The preview lives on a 3-minute lease this command renews: if it dies, the port leaves\n" +
+            "the edge within minutes. --vhost may be left out when the space has one vhost; without --machine the\n" +
+            "machine is THIS computer (another computer of yours is previewed only by name).\n" +
+            "Needs `datum login` in person (an API key or \"Login as\" is refused).",
+    },
+    {
+        tokens: ["preview", "down"],
+        usage: "datum preview down <id> [--space <slug>]",
+        summary: "close one of your terminal previews",
+        detail: "Removes the route (the id from `datum previews`). The machine's preview link ends with its last preview.",
+    },
+    {
+        tokens: ["preview", "trace"],
+        usage: "datum preview trace <id> [--follow] [--limit <n>] [--space <slug>]",
+        summary: "the gateway's last requests to a preview (the gateway's `cde trace`)",
+        detail: "One line per request the gateway routed: time, method (WS for a WebSocket), path WITHOUT the query, status\n" +
+            "(no answer = the link failed or the machine refused the port), time and size. --follow keeps printing new\n" +
+            "ones (a request shows up within a few seconds). The path keeps its segments — `;jsessionid=…` or a token IN\n" +
+            "the path (/reset/<token>) is recorded as typed; the query string never is. For a preview of yours or one\n" +
+            "that ends on your machine.",
+    },
+    {
+        tokens: ["previews"],
+        usage: "datum previews [--json] [--space <slug>]",
+        summary: "your previews and every route on your machines, with their links (the gateway's `cde interfaces`)",
+        detail: "Lists your `datum preview up` previews and the gateway routes a session opened on your machines: id, vhost,\n" +
+            "machine, port, state, owner, expiry and the link to open — then your machines and whether their daemon\n" +
+            "offers the preview link. --json prints the API's answer.",
+    },
+    {
+        tokens: ["space-manifest", "pull"],
+        usage: "datum space-manifest pull <dir> [--space <slug>]",
+        summary: "write the space's live configuration into <dir> as reviewable files (space admin)",
+        detail: "GET /api/space-manifest, split into files (#1809, docs/space-admin/space-repository.md): <dir>/space.json\n" +
+            "(apiVersion + scalar kinds), <dir>/<kind>.json for map kinds, <dir>/<kind>/<entry>.json per list entry,\n" +
+            "prompts as <entry>.prompt.md and schemas / flow definitions as <entry>.<field>.json referenced with\n" +
+            '{ "$file": … }. Organisation-tier kinds (features, budget, members, grants) and empty kinds are left out.\n' +
+            "<dir> must be empty or one pull wrote before: its layout files are replaced, so an entry gone from the\n" +
+            "space disappears; other files are never touched. Needs the operator role in the space (#1833) — a\n" +
+            "member's `datum login` sign-in, or a key bound to the space (the CI).",
+    },
+    {
+        tokens: ["space-manifest", "push"],
+        usage: "datum space-manifest push <dir> [--dry-run] [--prune] [--expect-empty] [--markdown <file>] [--raw] [--space <slug>]",
+        summary: "assemble <dir> into the space manifest and plan it (--dry-run, operator) or apply it (space admin)",
+        detail: "Reads the files `pull` writes, refuses organisation-tier kinds and anything that looks like key\n" +
+            "material, then PUT /api/space-manifest: --dry-run plans against the live space, without it the plan\n" +
+            "is applied. Prints the plan as Markdown (the diff of a prompt as changed lines) — --markdown also\n" +
+            "writes it to a file for a pull-request comment, --raw prints the server's JSON answer instead.\n" +
+            "--prune deletes list entries <dir> does not name, within the kinds it declares (default: orphans, left\n" +
+            "alone). A dry run always goes first and must answer for the space <dir>/.space-id names (pull writes it).\n" +
+            "--expect-empty fails (exit 1) when the plan would write anything — the convergence check after an apply.",
+    },
+    {
+        tokens: ["space-manifest", "init"],
+        usage: "datum space-manifest init <dir> --space <slug> [--refresh]",
+        summary: "turn <dir> into a space repository: CI plan/apply, daily sync, AGENTS.md (offline)",
+        detail: "Writes .github/workflows/datum-space.yml (plan on a pull request, apply + convergence on main; a manual\n" +
+            "run can prune), .github/workflows/datum-space-sync.yml (import, then panel edits back as a pull request),\n" +
+            "AGENTS.md, CLAUDE.md and README.md for the space. An existing file is kept — except the block Datum owns\n" +
+            "in AGENTS.md / CLAUDE.md (between the datum:managed markers), refreshed on every run so the rules follow\n" +
+            "the Datum release; --refresh also replaces the workflows with the current version. The workflows read\n" +
+            "the repository variable DATUM_BASE_URL and the secret DATUM_SPACE_API_KEY (a key bound to the space,\n" +
+            "role admin). No call to the server.",
+    },
+    {
+        tokens: ["space-manifest", "validate"],
+        usage: "datum space-manifest validate <dir> [--space <slug>]",
+        summary: "check the files of <dir> against the manifest's shape before a pull request (any member)",
+        detail: "Assembles <dir> the way `push` does ($file references, the local refusal of key material and\n" +
+            "organisation-tier kinds), then POST /api/space-manifest/validate on the space's host. For a space admin:\n" +
+            "exactly the checks of the dry run (every kind's validator against the live space — a bad cron, an unknown\n" +
+            "credential), without the plan. Below admin: the schema, closed vocabularies and duplicate keys only, and\n" +
+            "the CLI says \"shape only\" — the kind validators read data a member may not see; a space admin's\n" +
+            "`push <dir> --dry-run` (or the pull request's CI) gives the full check. Nothing is written; any member may\n" +
+            "run it, with a sign-in (`datum login`) or a key. Exit 1 lists the\n" +
+            "issues with their document paths.",
+    },
+    {
+        tokens: ["space-manifest", "schema"],
+        usage: "datum space-manifest schema [kind] [--space <slug>]",
+        summary: "the manifest's JSON Schema — whole, or one kind's fields with their descriptions (any member)",
+        detail: "GET /api/space-manifest/schema on the space's host: one property per manifest kind this instance\n" +
+            "offers, with field descriptions and the x-datum-tier / x-datum-key / x-datum-file-fields metadata.\n" +
+            "With a kind (routines, flows, agents, queues, …) prints only that kind — the shape to write before\n" +
+            "creating a new entry. An unknown kind lists the kinds.",
+    },
+    {
+        tokens: ["satellite"],
+        usage: "datum satellite <up|pair|lint|try> [...]",
+        summary: "the satellite daemon on THIS machine (pass-through to the installed `satellite` binary)",
+        detail: "Runs the installed @datum/datum-satellite CLI with the remaining arguments. The personal path (#504):\n" +
+            "`datum satellite up --pair <token> --server <url>` redeems the one-time token from Account →\n" +
+            "Development → \"Register my machine\", writes the key and starts the daemon — your own machine\n" +
+            "becomes an execution target of your sessions. Install the daemon first:\n" +
+            "`npm i -g @datum/datum-satellite` (from your organisation's npm registry).",
+    },
+];
+/** `datum <builtin> --help`: usage, summary and the longer note. */
+export function renderBuiltinHelp(cmd, style) {
+    const lines = [style.bold(cmd.usage), `  ${cmd.summary}`];
+    if (cmd.detail)
+        lines.push("", ...cmd.detail.split("\n").map((l) => `  ${l}`));
+    lines.push("", `Global options: ${style.dim("datum --help")}`);
+    return lines.join("\n");
+}
+export const GLOBAL_OPTIONS = [
+    {
+        flag: "--base-url <url>",
+        description: "Server origin (env DATUM_BASE_URL; default http://localhost:3001)",
+    },
+    {
+        flag: "--api-key <key>",
+        description: "API key datum_… (env DATUM_API_KEY). Without one, the CLI uses the " +
+            "sign-in from `datum login` (your Microsoft account). A key rides the " +
+            "public surface and pins your identity for audit (panel: Settings → " +
+            "API keys)",
+    },
+    {
+        flag: "--space <slug>",
+        description: "Address a SPACE (env DATUM_SPACE): the call goes to " +
+            "https://<slug>.<base-url host>, the space's own host",
+    },
+    {
+        flag: "--env <variant>",
+        description: "Target deployment variant (env DATUM_ENV): PROD, STAGE, TEST or a " +
+            "personal dev variant — pins the Ring Accelerator route via " +
+            "x-oa-variant",
+    },
+    {
+        flag: "--data <json|@file|->",
+        description: "Full JSON request body (like curl -d): inline JSON, @path to a " +
+            "file, or - for stdin. Field flags override matching body keys",
+    },
+    {
+        flag: "--fields <a,b,c>",
+        description: "Keep only these top-level keys of the JSON response (per element " +
+            "for arrays) — tames huge list responses",
+    },
+    {
+        flag: "--curl",
+        description: "Print the equivalent curl instead of calling. A body over 2 KB is " +
+            "named (-d @file), not expanded",
+    },
+    { flag: "--raw", description: "Raw response body (no pretty-printing)" },
+    {
+        flag: "--full",
+        description: "Print an oversized response instead of parking it in a file, and " +
+            "expand a large --curl body instead of naming it — off by default, " +
+            "because printing costs more than reading does",
+    },
+    { flag: "--help, -h", description: "Help for the command (or this overview)" },
+    { flag: "--version", description: "CLI/app version" },
+];
+function columns(rows, indent, style, leftStyle = style.cyan) {
+    const width = Math.max(0, ...rows.map(([l]) => l.length));
+    return rows.map(([l, r]) => `${indent}${leftStyle(l.padEnd(width))}${r ? `  ${r}` : ""}`);
+}
+function flagLabel(f) {
+    if (f.type === "boolean")
+        return `--${f.flag}[=false]`;
+    const hint = f.enum
+        ? f.enum.join("|")
+        : f.type === "array"
+            ? `${f.flag}…`
+            : f.type === "object"
+                ? "json"
+                : f.type === "string"
+                    ? f.flag
+                    : f.type;
+    return `--${f.flag} <${hint}>`;
+}
+function flagDescription(f, style) {
+    const parts = [];
+    if (f.description)
+        parts.push(f.description);
+    const meta = [];
+    if (f.required)
+        meta.push("required");
+    if (f.type === "array")
+        meta.push("repeatable; a {…}/[…] value is parsed as JSON");
+    if (f.type === "number" || f.type === "integer")
+        meta.push(f.type);
+    if (f.type === "object")
+        meta.push("JSON value");
+    if (meta.length > 0)
+        parts.push(style.yellow(`(${meta.join(", ")})`));
+    return parts.join(" ");
+}
+function exampleValue(f) {
+    if (f.enum?.length)
+        return f.enum[0];
+    if (f.type === "boolean")
+        return "";
+    if (f.type === "number" || f.type === "integer")
+        return "10";
+    if (f.type === "object")
+        return "'{…}'";
+    return `<${f.flag}>`;
+}
+/** `datum` / `datum --help`: overview + command groups. */
+export function renderRootHelp(spec, commands, style) {
+    const groups = new Map();
+    for (const c of commands) {
+        const g = c.tokens[0] ?? c.verb;
+        groups.set(g, (groups.get(g) ?? 0) + 1);
+    }
+    const rows = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([g, n]) => [g, `${n} command${n === 1 ? "" : "s"}`]);
+    const lines = [
+        `${style.bold("datum")} — ${spec.info.title} CLI`,
+        "",
+        "Every command is derived live from the server's OpenAPI contract",
+        "(openapi.json) — this help is always in sync with the API.",
+        "",
+        style.bold("Usage"),
+        `  datum <group> [subgroup] <verb> [positionals] [flags]`,
+        `  datum <group> --help           commands in a group`,
+        `  datum <command…> --help        full help for one command`,
+        `  datum commands                 flat list of every command`,
+        `  datum spec                     the OpenAPI spec (over 1 MB — written to a file; --full to print)`,
+        "",
+        // The hand-written commands: the sign-in (developer access), the
+        // satellite pass-through and `artifacts publish` (#589). They are not
+        // derived from the contract, so they are named here or nowhere.
+        style.bold("Hand-written commands (sign-in, this machine, publishing)"),
+        ...columns(BUILTIN_COMMANDS.map((c) => [c.usage, c.summary]), "  ", style),
+        "",
+        style.bold("Command groups"),
+        ...columns(rows, "  ", style),
+        "",
+        style.bold("Global options"),
+        ...columns(GLOBAL_OPTIONS.map((o) => [o.flag, o.description]), "  ", style),
+        "",
+        style.bold("Verbs"),
+        "  list/get read, create adds, update patches fields, set replaces,",
+        "  delete removes; other verbs are actions (escalate, sync, publish…).",
+        "",
+        `Docs: docs/cli.md · docs/public-api.md`,
+    ];
+    return lines.join("\n");
+}
+/**
+ * Closest existing commands for a mistyped prefix, by token overlap with
+ * command names (hyphens split too, so `status-page incident` still finds
+ * `status-systems incidents …`). Agents guess names like `status-page
+ * incident create` — pointing at the real command beats a bare error.
+ */
+function suggestCommands(words, commands) {
+    const tokens = [
+        ...new Set(words
+            .flatMap((w) => w.toLowerCase().split("-"))
+            .filter((t) => t.length >= 3)),
+    ];
+    if (tokens.length === 0)
+        return [];
+    const scored = commands
+        .map((c) => ({
+        command: c,
+        score: tokens.filter((t) => c.name.includes(t)).length,
+    }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.command.name.length - b.command.name.length);
+    if (scored.length === 0)
+        return [];
+    const best = scored[0].score;
+    return scored
+        .filter((s) => s.score === best)
+        .slice(0, 5)
+        .map((s) => s.command);
+}
+/** `datum cases --help` (or bare `datum cases`): every command in the group. */
+export function renderGroupHelp(group, commands, style) {
+    const prefix = group.join(" ");
+    const matching = commands.filter((c) => c.name === prefix || c.name.startsWith(`${prefix} `));
+    if (matching.length === 0) {
+        const groups = [...new Set(commands.map((c) => c.tokens[0] ?? c.verb))];
+        const suggestions = suggestCommands(group, commands);
+        return [
+            `Unknown command: ${style.bold(prefix)}`,
+            "",
+            ...(suggestions.length > 0
+                ? [
+                    "Did you mean:",
+                    ...columns(suggestions.map((c) => [
+                        [c.name, ...c.positionals.map((p) => `<${p.name}>`)].join(" "),
+                        c.summary,
+                    ]), "  ", style),
+                    "",
+                ]
+                : []),
+            `Groups: ${groups.sort().join(", ")}`,
+            `Try ${style.cyan("datum --help")} or ${style.cyan("datum commands")}.`,
+        ].join("\n");
+    }
+    // A hand-written command under this prefix (`datum artifacts publish
+    // <dir>`) belongs in the group's listing too — it is the one a person
+    // actually reaches for, and the derived siblings would otherwise be the
+    // only thing `datum artifacts` names.
+    const builtins = BUILTIN_COMMANDS.filter((b) => b.tokens.length > group.length && group.every((g, i) => b.tokens[i] === g));
+    const rows = [
+        ...builtins.map((b) => 
+        // Tokens and positionals only — the optional flags belong on the
+        // command's own --help, not in a group listing's column.
+        [b.usage.replace(/^datum /, "").split(" [")[0], b.summary]),
+        ...matching.map((c) => [
+            [c.name, ...c.positionals.map((p) => `<${p.name}>`)].join(" "),
+            c.summary,
+        ]),
+    ];
+    const total = matching.length + builtins.length;
+    return [
+        `${style.bold(`datum ${prefix}`)} — ${total} command${total === 1 ? "" : "s"}`,
+        "",
+        ...columns(rows, "  ", style),
+        "",
+        `Run ${style.cyan(`datum ${matching[0].name} --help`)} for flags and examples.`,
+    ].join("\n");
+}
+/** Full help page for one command — the "phenomenal --help". */
+export function renderCommandHelp(command, style) {
+    const usage = [
+        "datum",
+        command.name,
+        ...command.positionals.map((p) => `<${p.name}>`),
+        ...(command.queryFlags.length + command.bodyFlags.length > 0
+            ? ["[flags]"]
+            : []),
+    ].join(" ");
+    const lines = [
+        `${style.bold(`datum ${command.name}`)} — ${command.summary}`,
+        style.dim(`${command.method} ${command.path}`),
+    ];
+    if (command.description)
+        lines.push("", command.description);
+    lines.push("", style.bold("Usage"), `  ${usage}`);
+    if (command.positionals.length > 0) {
+        lines.push("", style.bold("Arguments"), ...columns(command.positionals.map((p) => [`<${p.name}>`, p.description || `path parameter`]), "  ", style));
+    }
+    if (command.queryFlags.length > 0) {
+        lines.push("", style.bold("Query flags"), ...columns(command.queryFlags.map((f) => [flagLabel(f), flagDescription(f, style)]), "  ", style));
+    }
+    if (command.bodyFlags.length > 0) {
+        const header = command.bodyDescription
+            ? `Body flags ${style.dim(`— ${command.bodyDescription}`)}`
+            : "Body flags";
+        lines.push("", style.bold(header), ...columns([...command.bodyFlags]
+            .sort((a, b) => Number(b.required) - Number(a.required))
+            .map((f) => [flagLabel(f), flagDescription(f, style)]), "  ", style));
+        if (command.bodyOpen) {
+            lines.push(style.dim("  The body accepts additional fields — pass them via --data."));
+        }
+    }
+    else if (command.hasBody) {
+        lines.push("", style.bold("Body"), `  ${command.bodyDescription || "JSON body"} — pass it via --data '<json>'.`);
+    }
+    if (command.responses.length > 0) {
+        lines.push("", style.bold("Responses"), ...columns(command.responses.map((r) => [r.status, r.description]), "  ", style, style.green));
+    }
+    const exampleFlags = [
+        ...command.queryFlags.filter((f) => f.required),
+        ...command.bodyFlags.filter((f) => f.required),
+    ]
+        .slice(0, 3)
+        .map((f) => f.type === "boolean" ? `--${f.flag}` : `--${f.flag} ${exampleValue(f)}`);
+    const example = [
+        "datum",
+        command.name,
+        ...command.positionals.map((p) => `<${p.name}>`),
+        ...exampleFlags,
+    ].join(" ");
+    if (command.examples.length > 0) {
+        lines.push("", style.bold("Examples"), ...command.examples.map((e) => `  ${e}`));
+    }
+    else {
+        lines.push("", style.bold("Example"), `  ${example}`);
+    }
+    lines.push("", style.dim("Global options: datum --help · equivalent curl: add --curl"));
+    return lines.join("\n");
+}
+/** `datum commands`: the flat list (grep-friendly). */
+export function renderCommandList(commands, style) {
+    // The hand-written commands first — they are the ones a developer looks
+    // for when the plugin's MCP server is not starting.
+    const rows = [
+        ...BUILTIN_COMMANDS.map((c) => [c.usage, c.summary]),
+        ...commands.map((c) => [[c.name, ...c.positionals.map((p) => `<${p.name}>`)].join(" "), c.summary]),
+    ];
+    return columns(rows, "", style).join("\n");
+}
+//# sourceMappingURL=help.js.map