@usenaive-sdk/cli 0.12.2 → 0.13.0

package/dist/lib/teams-catalog.js

@@ -0,0 +1,765 @@
+/**
+ * THE ONE DECLARATION SITE for the `naive teams` surface (06 §1.4).
+ *
+ * Two design notes shipped two `teams` command sets and neither was a superset of
+ * the other. Two hand-written lists is exactly the drift a one-declaration rule
+ * exists to catch, so both are deleted and the union is declared once, here, as
+ * DATA. `commands/teams.ts` builds the commander tree by walking this array; it
+ * writes no subcommand of its own. A row added here is a working command, and a
+ * command that is not a row here does not exist.
+ *
+ * ── WHY THIS IS A .ts FILE IN THIS PACKAGE AND NOT A GENERATED ARTIFACT ─────
+ *
+ * 06 §1.4 puts the declaration in `@usenaive/agent-contract/capabilities` and has
+ * a generator emit `packages/cli/src/generated/teams-commands.ts` from it, so the
+ * CLI subcommand, the MCP tool, the REST path and the openapi operation are all
+ * one statement. MEASURED: there is no `packages/agent-contract` directory in
+ * this tree and no generator to run, and this task owns `packages/cli` only. A
+ * hand-written file that IMITATES a generated one — committed under `generated/`,
+ * with nothing that regenerates it — is worse than an honest source file: the
+ * next person edits it and their edit is silently the truth.
+ *
+ * So this is the honest intermediate: ONE declaration, inside the package that
+ * consumes it, shaped so a future generator emits exactly this array. The fields
+ * a generator would need and the CLI does not (`action`, `rest`, `mcp`,
+ * `because`, `fenced`, `write`) are carried anyway, so the day the contract
+ * package exists this file is deleted rather than reconciled.
+ *
+ * ── WHY IT MUST BE ONE LIST AND NOT 28 `.command()` CALLS ───────────────────
+ *
+ * `src/index.ts` calls `findUnknownSubcommand` BEFORE `parseAsync` and hard-fails
+ * on an unrecognised subcommand even with `--help` appended. A subcommand list
+ * that can drift from the thing that answers it therefore makes VALID commands
+ * fail with `cli_outdated`, rather than degrading. One array, walked once, cannot
+ * drift from itself.
+ */
+/* -------------------------------------------------------------------------- */
+/* shared flag groups — declared once so two ops cannot spell the same filter  */
+/* two ways                                                                    */
+/* -------------------------------------------------------------------------- */
+const CURSOR = {
+    flag: "--cursor <seq>",
+    key: "cursor",
+    describe: "Resume from this position (a cursor is a POSITION, not a time)",
+    in: "query",
+};
+const LIMIT = { flag: "--limit <n>", key: "limit", describe: "Maximum rows", in: "query", int: true };
+const STATUS = { flag: "--status <status>", key: "status", describe: "Filter by status", in: "query" };
+const ROLE = { flag: "--role <role>", key: "role", describe: "Filter by the declared role of the agent", in: "query" };
+const TASK = { flag: "--task <id>", key: "task", describe: "Filter to one task", in: "query" };
+/**
+ * `--because` is a `requiredOption`, never a positional, on every op that widens
+ * authority or destroys state. A positional reason is unquotable in practice and
+ * invisible in `--help`; and because commander validates required options before
+ * any action hook runs, a missing one already produces the CLI's structured
+ * `invalid_input` envelope for free (index.ts's CommanderError catch).
+ */
+const BECAUSE = {
+    flag: "--because <why>",
+    key: "because",
+    describe: "Why you are doing this. Recorded on the decision. REQUIRED",
+    in: "body",
+    required: true,
+};
+/**
+ * 🔴 THIS TEXT SAID "HERMES ONLY" AFTER THAT STOPPED BEING TRUE, AND THE HELP IS
+ * THE ONLY ACCOUNT MOST OPERATORS EVER READ.
+ *
+ * `unverified` is written by naive's own completion adjudicator onto
+ * `tasks_mirror`. A durable tenant's board used to come straight from the runtime,
+ * whose six states (`todo ready doing review done blocked`) carry no such value,
+ * so exit 3 really was unreachable there — and `naive teams tasks` announced that
+ * on stderr rather than let a CI job read exit 0 as "attested".
+ *
+ * The verification join removed the cause: `durableCard` joins `tasks_mirror` and
+ * the terminal column is naive's verdict. `commands/teams.ts` deleted the banner
+ * on exactly that ground and `legacy-commands-still-work.test.ts` asserts exit 3
+ * on a durable board. This string was left behind, so one binary shipped two
+ * contradictory accounts of one flag — and the one in `--help` said the gate
+ * cannot fire, which is the reading that makes an operator stop trusting it.
+ *
+ * WHAT IT SAYS NOW IS THE FLAG'S OWN CONTRACT AND NOTHING ABOUT THE LANE. The
+ * gate asks one question of one field, deliberately (see `teams.ts`: a CLI that
+ * branched on which runtime answered would be a second place the two lanes could
+ * diverge). So the caveat that belongs here is the one that is true on BOTH
+ * lanes: exit 0 means no card on this board reads `unverified`, which is not the
+ * same claim as "every card was adjudicated" — a board naive never scored reports
+ * no `unverified` for want of a verdict, not for want of a problem.
+ */
+const FAIL_ON_UNVERIFIED = {
+    flag: "--fail-on-unverified",
+    key: "failOnUnverified",
+    describe: "Exit 3 when a task's terminal state is `unverified` (a THIRD terminal state, not a success). " +
+        "Both lanes. Exit 0 means no card on this board reads `unverified` — NOT that every card was adjudicated",
+    in: "client",
+};
+const BOARD_FILTERS = [STATUS, ROLE, LIMIT, CURSOR];
+const TEAM_ARG = { arg: "<team>", name: "team", describe: "The declared team", in: "path" };
+/** The base every tenant-scoped path is built on. R-4: the addressing tuple is
+ *  `(company, tenant, team)`, and the tuple is IN THE PATH rather than inferred. */
+const BASE = "/v1/teams/{team}/tenants/{tenant}";
+export const TEAM_OPS = [
+    {
+        cli: "list",
+        describe: "List the declared teams (the only subcommand that does not take --tenant)",
+        action: "teams.list",
+        method: "GET",
+        path: "/v1/teams",
+        tenant: false,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "GET /v1/teams answers 501, so a tool over it could only ever refuse",
+        args: [],
+        flags: [{ flag: "--runtime <kind>", key: "runtime", describe: "durable | hermes", in: "query" }],
+    },
+    {
+        cli: "show",
+        describe: "Show one team's status for one tenant",
+        action: "teams.status",
+        method: "GET",
+        path: BASE,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; a model reads the board, not the team header",
+        args: [TEAM_ARG],
+        flags: [],
+    },
+    {
+        cli: "plan",
+        describe: "The honesty report for one (team, tenant): digests, fence, caps, attestation parity",
+        action: "teams.plan",
+        method: "GET",
+        path: `${BASE}/plan`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; the honesty report is an operator artifact, and its central field (the manifest digest) has no source",
+        args: [TEAM_ARG],
+        flags: [
+            {
+                flag: "--detailed-exitcode",
+                key: "detailedExitcode",
+                describe: "Exit 2 when a diff exists (terraform's convention; exit 1 stays a real error)",
+                in: "client",
+            },
+        ],
+    },
+    {
+        cli: "roster",
+        describe: "The declared agents of a team, and optionally the edges between them",
+        action: "teams.roster",
+        method: "GET",
+        path: `${BASE}/roster`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; can/approve/view are all null on this build, so it would report an authority it cannot see",
+        args: [TEAM_ARG],
+        flags: [{ flag: "--edges", key: "edges", describe: "Include the declared edges", in: "query" }],
+    },
+    {
+        cli: "board",
+        describe: "The team's board for one tenant",
+        action: "teams.board",
+        method: "GET",
+        path: `${BASE}/board`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: "naive_teams_board",
+        args: [TEAM_ARG],
+        flags: BOARD_FILTERS,
+    },
+    {
+        cli: "submit",
+        describe: "Send work to a team. THE verb — one ActionId, one fence, every surface",
+        action: "teams.submit",
+        method: "POST",
+        path: `${BASE}/submit`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; POST …/submit answers 501, and a submit tool is the one verb that must not exist before the route does",
+        args: [TEAM_ARG, { arg: "<goal>", name: "goal", describe: "What you want done", in: "body" }],
+        flags: [
+            { flag: "--task <id>", key: "task", describe: "Attach this goal to an existing task", in: "body" },
+            {
+                flag: "--brief <file>",
+                key: "brief",
+                describe: "Read the prose brief from a file, or `-` for stdin (prose on argv is mangled by every shell)",
+                in: "body",
+            },
+            { flag: "--attest <claim>", key: "attest", describe: "The claim the result must attest to", in: "body" },
+            { flag: "--parent <id>", key: "parent", describe: "Parent task id", in: "body" },
+            {
+                flag: "--idempotency-key <k>",
+                key: "idempotencyKey",
+                describe: "Forwarded as Idempotency-Key. Best-effort today — see `naive teams plan`",
+                in: "client",
+            },
+        ],
+    },
+    {
+        cli: "say",
+        describe: "Say something into a team session",
+        action: "teams.say",
+        method: "POST",
+        path: `${BASE}/sessions/{channel}/messages`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the CLI `say` posts a SESSION message (…/sessions/{channel}/messages, 501 today); the MCP tool of the nearest name, naive_teams_comment, posts a TASK comment — a different operation, not this one",
+        args: [TEAM_ARG, { arg: "<text>", name: "text", describe: "What to say", in: "body" }],
+        flags: [
+            { flag: "--channel <channel>", key: "channel", describe: "The session channel (default: main)", in: "path" },
+            { flag: "--as <role>", key: "as", describe: "Speak as a declared role", in: "body" },
+        ],
+    },
+    {
+        cli: "tasks",
+        describe: "The board as a task list",
+        action: "teams.board",
+        method: "GET",
+        path: `${BASE}/board`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "an alias of `board`; naive_teams_board is the tool",
+        args: [TEAM_ARG],
+        flags: [...BOARD_FILTERS, FAIL_ON_UNVERIFIED],
+    },
+    {
+        cli: "task",
+        describe: "One card on the board",
+        action: "teams.board",
+        method: "GET",
+        path: `${BASE}/board/{card}`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; a model reads one card through naive_teams_board",
+        args: [TEAM_ARG, { arg: "<id>", name: "card", describe: "The card id", in: "path" }],
+        flags: [FAIL_ON_UNVERIFIED],
+    },
+    {
+        cli: "unblock",
+        describe: "Unblock a card",
+        action: "teams.unblock",
+        method: "POST",
+        path: `${BASE}/board/{card}/unblock`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: "naive_teams_unblock",
+        args: [TEAM_ARG, { arg: "<id>", name: "card", describe: "The card id", in: "path" }],
+        flags: [BECAUSE],
+    },
+    {
+        cli: "runs",
+        describe: "The team's runs",
+        action: "teams.runs",
+        method: "GET",
+        path: `${BASE}/runs`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; naive_teams_run reads ONE run by id, it does not list them",
+        args: [TEAM_ARG],
+        // NOT [TASK, STATUS, …]. The runs handler reads exactly `limit` and
+        // `cursor`; `?task=` and `?status=` were declared as query flags, sent, and
+        // silently ignored, so filtering a busy tenant's runs returned the
+        // unfiltered list with no signal. openapi declares no such parameters
+        // either. They come back when the route supports them.
+        flags: [LIMIT, CURSOR],
+    },
+    {
+        cli: "watch",
+        describe: "Watch a run's transcript as NDJSON — one object per line, resumable",
+        action: "teams.runs",
+        method: "GET",
+        path: `${BASE}/runs/{run}/stream`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; …/runs/{id}/stream answers 501 and MCP has no streaming response",
+        streams: true,
+        args: [TEAM_ARG],
+        flags: [
+            { flag: "--run <id>", key: "run", describe: "The run to watch (required)", in: "path", required: true },
+            {
+                flag: "--follow",
+                // What it decides is what happens at a TERMINAL frame, not how much
+                // of the stream is read: without it the command stops at the first
+                // `stream.end`, with it the connection stays open past it. Both
+                // modes drain the body — the old behaviour stopped after one
+                // network chunk, which truncated the transcript at an arbitrary
+                // point and still exited 0.
+                key: "follow",
+                describe: "Keep watching past a terminal frame (default: stop at the first stream.end)",
+                in: "client",
+            },
+            { ...CURSOR, in: "client", describe: "Resume from this seq — sent as Last-Event-ID" },
+            {
+                flag: "--fail-on-terminal",
+                key: "failOnTerminal",
+                // Of the three, only `failed` is reachable on the durable runtime: a
+                // durable run's status vocabulary is `running | completed | failed`
+                // (`runState` in the runtime's naive.ts), so `unverified` and `blocked`
+                // are hermes states. The flag is not hermes-only the way
+                // `--fail-on-unverified` is — it keeps a real reach on both — so it is
+                // narrowed in the text rather than announced at runtime.
+                describe: "Exit 3 when the final status is unverified, failed or blocked (on the durable runtime only `failed` occurs)",
+                in: "client",
+            },
+            {
+                flag: "--show-args",
+                key: "showArgs",
+                describe: "Print tool arguments instead of args_digest. Requires an interactive terminal",
+                in: "client",
+            },
+        ],
+    },
+    {
+        cli: "events",
+        describe: "The team's event log",
+        action: "teams.events",
+        method: "GET",
+        path: `${BASE}/events`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool",
+        args: [TEAM_ARG],
+        flags: [TASK, CURSOR, LIMIT],
+    },
+    {
+        cli: "cost",
+        describe: "What the team spent",
+        action: "teams.cost",
+        method: "GET",
+        path: `${BASE}/cost`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; spend is an operator surface",
+        args: [TEAM_ARG],
+        flags: [
+            // `action` IS THE ONLY ACCEPTED VALUE. The route throws
+            // `invalid_input: by must be "action" (the only bucketing this build can
+            // compute)` for anything else (routes/teams.ts), so the three the describe
+            // string used to advertise — task | day | role — all 400.
+            {
+                flag: "--by <dimension>",
+                key: "by",
+                describe: 'action (the only value this build accepts)',
+                in: "query",
+            },
+            // `--period` IS NOT SENT. The route never reads `req.query.period`; the
+            // window comes from `spendWindow(accountKit.budget)`. A query flag the
+            // server ignores is the worst shape available — the response looks right
+            // and answers a different question — so it is `client` and the CLI prints
+            // the window the server actually used.
+            {
+                flag: "--period <period>",
+                key: "period",
+                describe: "IGNORED — the window is fixed by the account kit's budget period",
+                in: "client",
+            },
+        ],
+    },
+    {
+        cli: "diagnose",
+        describe: "Diagnostics for a team that is not behaving",
+        action: "teams.diagnostics",
+        method: "GET",
+        path: `${BASE}/diagnostics`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool",
+        args: [TEAM_ARG],
+        flags: [{ flag: "--kind <kind>", key: "kind", describe: "Restrict to one diagnostic kind", in: "query" }],
+    },
+    {
+        cli: "sessions",
+        describe: "The team's sessions",
+        action: "teams.sessions",
+        method: "GET",
+        path: `${BASE}/sessions`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; both session reads answer 501",
+        args: [TEAM_ARG],
+        flags: [CURSOR, LIMIT],
+    },
+    {
+        cli: "read",
+        describe: "Read one session channel",
+        action: "teams.sessions",
+        method: "GET",
+        path: `${BASE}/sessions/{channel}`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; both session reads answer 501",
+        args: [TEAM_ARG, { arg: "<channel>", name: "channel", describe: "The channel to read", in: "path" }],
+        flags: [CURSOR, LIMIT],
+    },
+    {
+        cli: "approvals",
+        describe: "Approvals this team is waiting on",
+        action: "teams.approvals",
+        method: "GET",
+        path: `${BASE}/approvals`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "naive_approvals_list is the tool, and it is not a teams tool",
+        args: [TEAM_ARG],
+        flags: [STATUS],
+    },
+    {
+        cli: "decide",
+        describe: "Allow or deny one approval",
+        action: "teams.approval_decide",
+        method: "POST",
+        path: `${BASE}/approvals/{approval}/decide`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "an agent may not resolve the gate meant to constrain it — assertHumanResolver refuses an agent key",
+        args: [TEAM_ARG, { arg: "<id>", name: "approval", describe: "The approval id", in: "path" }],
+        flags: [
+            { flag: "--allow", key: "allow", describe: "Allow it", in: "body", field: "decision", value: "approve" },
+            { flag: "--deny", key: "deny", describe: "Deny it", in: "body", field: "decision", value: "deny" },
+            BECAUSE,
+        ],
+    },
+    {
+        cli: "effects",
+        describe: "Outstanding effects",
+        action: "teams.effects",
+        method: "GET",
+        path: `${BASE}/effects`,
+        tenant: true,
+        fenced: false,
+        write: false,
+        mcp: false,
+        because: "the MCP surface declares no such tool; the effects routes answer 501",
+        args: [TEAM_ARG],
+        flags: [{ flag: "--state <state>", key: "state", describe: "Filter by effect state", in: "query" }],
+    },
+    {
+        cli: "settle",
+        describe: "Settle one effect — done, compensated or rejected",
+        action: "teams.effect_settle",
+        method: "POST",
+        path: `${BASE}/effects/{effect}/settle`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; the effects routes answer 501",
+        args: [TEAM_ARG, { arg: "<id>", name: "effect", describe: "The effect id", in: "path" }],
+        flags: [
+            // Same selector shape as `decide`. openapi declares `{decision, because,
+            // receipt}` here too, with `decision` an unconstrained string — the route
+            // is a 501 refusal, so nothing narrows the value set yet. The values are
+            // therefore spelled exactly like their flags, so `--help` and the wire
+            // cannot drift into two names for one choice.
+            { flag: "--done", key: "done", describe: "It completed", in: "body", field: "decision", value: "done" },
+            { flag: "--compensate", key: "compensate", describe: "It was compensated", in: "body", field: "decision", value: "compensate" },
+            { flag: "--reject", key: "reject", describe: "It was rejected", in: "body", field: "decision", value: "reject" },
+            { flag: "--receipt <file>", key: "receipt", describe: "Read the receipt from a file, or `-` for stdin", in: "body" },
+            BECAUSE,
+        ],
+    },
+    {
+        cli: "schedule",
+        describe: "Schedule recurring work for a team",
+        action: "teams.schedule",
+        method: "POST",
+        path: `${BASE}/schedule`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; the schedule routes answer 501",
+        args: [
+            TEAM_ARG,
+            { arg: "<cron>", name: "cron", describe: "Cron expression", in: "body" },
+            { arg: "<goal>", name: "goal", describe: "What to submit on each tick", in: "body" },
+        ],
+        flags: [
+            { flag: "--brief <file>", key: "brief", describe: "Read the prose brief from a file, or `-` for stdin", in: "body" },
+            { flag: "--timezone <tz>", key: "timezone", describe: "IANA timezone for the cron expression", in: "body" },
+        ],
+    },
+    {
+        cli: "unschedule",
+        // 06 §1.4 gives `schedule / unschedule` ONE row, one arg list and the path
+        // glob `…/schedule*`. A DELETE carrying a body to identify its own target is
+        // the shape that makes a proxy drop the request, so the id is in the path.
+        describe: "Remove a schedule",
+        action: "teams.schedule",
+        method: "DELETE",
+        path: `${BASE}/schedule/{schedule}`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; the schedule routes answer 501",
+        args: [TEAM_ARG, { arg: "<id>", name: "schedule", describe: "The schedule id", in: "path" }],
+        flags: [],
+    },
+    {
+        // 🔴 THIS ROW WAS MISSING, AND IT IS A STEP OF THE CORE LOOP.
+        //
+        // `POST /v1/teams/{team}/tenants/{tenant}/apply` has been mounted the whole
+        // time and no CLI verb reached it — so "declare a team, apply it, submit
+        // work" had a hole in the middle that only a hand-written curl could cross.
+        // The other 26 rows were derived from the route table; this one was not,
+        // because a route with no CLI verb is invisible to a reader checking the CLI
+        // against itself.
+        //
+        // `--expected-digest` is REQUIRED and has no default. Apply exists to raise
+        // `409 stale_expected_digest` — to refuse when the compiled company has
+        // moved since you last looked — and an apply that sends whatever digest is
+        // current cannot ever raise it. A flag defaulted to "whatever you have"
+        // turns a concurrency check into a rubber stamp. `naive teams plan` prints
+        // the digest to pass.
+        cli: "apply",
+        describe: "Record that an operator applied this exact manifest digest. Refuses a stale one",
+        action: "teams.apply",
+        method: "POST",
+        path: `${BASE}/apply`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "applying a manifest is the act that makes a capability change something a human reviewed; an agent applying its own manifest reviews nothing",
+        args: [TEAM_ARG],
+        flags: [
+            {
+                flag: "--expected-digest <digest>",
+                key: "expectedDigest",
+                describe: "REQUIRED. The digest you are applying, from `naive teams plan`. A stale one is refused",
+                in: "body",
+                field: "expected_digest",
+                required: true,
+            },
+            // NO `--because`, deliberately, and it is the one fenced op without one.
+            // The published contract for this operation declares exactly one body
+            // property — `expected_digest` — and the CLI may not send a key the
+            // contract does not declare (the gate below enforces that, and it caught
+            // this row). More importantly the reason would be redundant: the artefact
+            // that records what an operator approved is the DIGEST, which names the
+            // exact compiled manifest, and a free-text sentence beside it adds a
+            // second, weaker account of the same decision.
+        ],
+    },
+    {
+        cli: "model",
+        describe: "Change the model a team runs on",
+        action: "teams.model",
+        method: "POST",
+        path: `${BASE}/model`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; a model must not choose its own model",
+        args: [TEAM_ARG, { arg: "<modelId>", name: "modelId", describe: "The model id", in: "body", field: "model_id" }],
+        flags: [BECAUSE],
+    },
+    {
+        cli: "stop",
+        describe: "Stop a team",
+        action: "teams.stop",
+        method: "POST",
+        path: `${BASE}/stop`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "the MCP surface declares no such tool; naive_teams_run reads a run, it does not stop one",
+        args: [TEAM_ARG],
+        flags: [BECAUSE],
+    },
+    {
+        cli: "migrate",
+        describe: "Move this tenant onto the durable runtime",
+        action: "teams.migrate",
+        method: "POST",
+        path: `${BASE}/migrate`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        // An agent must not move its own tenant between runtimes: the cutover
+        // destroys the legacy coordinates irreversibly. Declared, not omitted, so a
+        // four-way parity check sees an exemption rather than a hole.
+        mcp: false,
+        because: "an agent must not move its own tenant between runtimes; the cutover is irreversible",
+        args: [TEAM_ARG],
+        flags: [{ flag: "--dry-run", key: "dryRun", describe: "Report what would move; change nothing", in: "body" }, BECAUSE],
+    },
+    {
+        cli: "rollback",
+        describe: "Move this tenant back off the durable runtime. DESTROYS the workspace",
+        action: "teams.rollback",
+        method: "POST",
+        path: `${BASE}/rollback`,
+        tenant: true,
+        fenced: true,
+        write: true,
+        mcp: false,
+        because: "an agent must not move its own tenant between runtimes; the rollback destroys /data",
+        args: [TEAM_ARG],
+        flags: [
+            {
+                // A flag a script cannot accidentally satisfy is the honest interlock:
+                // the rollback re-claims the slot, so /data is gone with it.
+                flag: "--i-understand-data-loss",
+                key: "iUnderstandDataLoss",
+                describe: "Required. The workspace is destroyed by this operation and is not recoverable",
+                in: "body",
+            },
+            BECAUSE,
+        ],
+    },
+];
+/* -------------------------------------------------------------------------- */
+/* pure builders — everything the runner needs, testable without a network     */
+/* -------------------------------------------------------------------------- */
+export class TeamOpError extends Error {
+}
+/** Every `{placeholder}` this op's path expects. */
+export function pathPlaceholders(op) {
+    return [...op.path.matchAll(/\{([a-zA-Z]+)\}/g)].map((m) => m[1]);
+}
+/**
+ * Fill the path. Every value is `encodeURIComponent`'d — a team name or a card id
+ * that contains a slash must not be able to reach a different route, and an
+ * absent value is an error rather than the literal string "undefined" in a URL.
+ */
+export function buildPath(op, values) {
+    return op.path.replace(/\{([a-zA-Z]+)\}/g, (_m, name) => {
+        const v = values[name];
+        if (v === undefined || v === "") {
+            throw new TeamOpError(`naive teams ${op.cli}: missing value for path segment {${name}}`);
+        }
+        return encodeURIComponent(v);
+    });
+}
+/** The query string, including its leading `?`, or `""`. */
+export function buildQuery(op, opts) {
+    const params = new URLSearchParams();
+    for (const f of op.flags) {
+        if (f.in !== "query")
+            continue;
+        const raw = opts[f.key];
+        if (raw === undefined || raw === false || raw === null)
+            continue;
+        params.set(f.field ?? f.key, raw === true ? "true" : String(raw));
+    }
+    const s = params.toString();
+    return s ? `?${s}` : "";
+}
+/**
+ * The request body: positional args declared `in: "body"`, then flags declared
+ * `in: "body"`. A GET has no body at all — a GET that carries one is a request
+ * some proxy will strip and some server will ignore, which is a silent wrong
+ * answer rather than an error.
+ */
+export function buildBody(op, args, opts) {
+    if (op.method === "GET")
+        return undefined;
+    const body = {};
+    for (const a of op.args) {
+        if (a.in !== "body")
+            continue;
+        const v = args[a.name];
+        if (v !== undefined)
+            body[a.field ?? a.name] = v;
+    }
+    for (const f of op.flags) {
+        if (f.in !== "body")
+            continue;
+        const v = opts[f.key];
+        if (v === undefined || v === false || v === null)
+            continue;
+        // A selector flag sends its declared VALUE under a shared field, not `true`
+        // under its own name. See `FlagSpec.value`.
+        body[f.field ?? snake(f.key)] = f.value !== undefined ? f.value : v;
+    }
+    return body;
+}
+/**
+ * The mutually exclusive selector groups on this op, keyed by the wire field
+ * they share. DERIVED from the flags rather than listed, so a third member added
+ * to a group joins the exclusion without anyone remembering to widen a list.
+ */
+export function selectorGroups(op) {
+    const groups = new Map();
+    for (const f of op.flags) {
+        if (f.value === undefined)
+            continue;
+        if (f.field === undefined) {
+            throw new TeamOpError(`teams-catalog: ${op.cli} --${f.key} declares a value with no field`);
+        }
+        const g = groups.get(f.field) ?? [];
+        g.push(f);
+        groups.set(f.field, g);
+    }
+    return groups;
+}
+/**
+ * Refuse an ambiguous or absent decision BEFORE the request leaves the process.
+ *
+ * A selector group is a CHOICE: exactly one member must be given. Neither branch
+ * can be left to the server. `--allow --deny` would otherwise resolve by flag
+ * order in this file — an approval decided by declaration order — and giving
+ * neither would send a body with no `decision`, which `settle` (whose openapi
+ * marks nothing required) would accept as a well-formed request that settles an
+ * effect no particular way.
+ */
+export function assertSelectors(op, opts) {
+    for (const [field, flags] of selectorGroups(op)) {
+        const chosen = flags.filter((f) => opts[f.key] === true);
+        const spellings = flags.map((f) => `--${f.key}`).join(" or ");
+        if (chosen.length === 0) {
+            throw new TeamOpError(`naive teams ${op.cli}: ${spellings} is required (it is the \`${field}\` this sends).`);
+        }
+        if (chosen.length > 1) {
+            throw new TeamOpError(`naive teams ${op.cli}: ${chosen.map((f) => `--${f.key}`).join(" and ")} are mutually exclusive — pass exactly one.`);
+        }
+    }
+}
+/** `failOnTerminal` -> `fail_on_terminal`. Flags are camelCase in commander and
+ *  snake_case on this API's wire; converting in one place keeps the two apart. */
+export function snake(key) {
+    return key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+export function findOp(cli) {
+    return TEAM_OPS.find((o) => o.cli === cli);
+}
+//# sourceMappingURL=teams-catalog.js.map