@usenaive-sdk/cli 0.12.5 → 0.13.1

package/dist/lib/brain-select.js

@@ -0,0 +1,403 @@
+/**
+ * MULTI-BRAIN ADDRESSING FOR THE CLI.
+ *
+ * ── the model this reconciles toward ────────────────────────────────────────
+ * `brain_knowledge_bases` (packages/db/src/product/brain.ts:50-92) is
+ * `(company_id, name, is_default, …)` with a PARTIAL unique index on ONE default
+ * per company. The database has always supported N brains per company; so has
+ * the API (`GET /v1/brain` lists, `POST /v1/brain` creates, and every content
+ * verb takes `knowledge_base_id`). What neither supports is addressing a brain
+ * by NAME: `resolveKnowledgeBase` (platform/brain/src/brain.ts:318-330) rejects
+ * a non-UUID with `resource_not_found` before it ever looks at the row.
+ *
+ * So the naming layer lives here, in the client, where it costs no route and no
+ * governance decision: `--brain <name|id>` is resolved against `GET /v1/brain`
+ * and only ever a UUID reaches the wire.
+ *
+ * ── what does NOT change ────────────────────────────────────────────────────
+ * `--kb <uuid>` is the shipped spelling and stays byte-identical: a value that
+ * already looks like a UUID is passed straight through with ZERO extra
+ * requests, exactly as before. The list is fetched only for a value that could
+ * not have worked before (a non-UUID, which the API refused) or for `--brain`,
+ * which is new. See __tests__/brain-multi.test.ts.
+ */
+import { apiRequest, handleApiError } from "../client.js";
+import { agentError } from "../output.js";
+/**
+ * THE BINDING KEY, and it is deliberately NOT a new word.
+ *
+ * `brain_knowledge_base_id` is the exact spelling `POST /v1/runs` already
+ * accepts to point a run's reflexive-brain attach at a knowledge base
+ * (platform/brain/src/contracts/brain-ops.ts:98, packages/api/src/routes/runs.ts:104).
+ * Binding an AGENT to a brain records the value that surface already consumes
+ * under the name it already uses, rather than minting a second one.
+ */
+export const BRAIN_BINDING_KEY = "brain_knowledge_base_id";
+/**
+ * THE COMPANION KEY, written by the brain surface and by nothing else.
+ *
+ * `brain_connected_at` is stamped by `connectBrainToAgent`
+ * (packages/api/src/routes/brain.ts:1121-1131) in the same atomic jsonb merge as
+ * the binding, and removed by `disconnectBrainFromAgent`. It is what
+ * `GET /v1/brain/connections` reports as `connected_at`, so a binding written
+ * without it reads back as `connected_at: null` — or, worse, carries the
+ * timestamp of an EARLIER binding to a DIFFERENT brain, which is what the roster
+ * PATCH used to leave behind here.
+ */
+export const BRAIN_CONNECTED_AT_KEY = "brain_connected_at";
+/**
+ * THE BRAIN BINDING SURFACE — the routes that carry the brain gate.
+ *
+ * 🔴 THESE REPLACED A ROSTER PATCH, AND THAT IS THE WHOLE POINT. This CLI used
+ * to write the binding with `PATCH {@link ROSTER_PATH}/:id {metadata:{…}}`, which
+ * is mounted on the ROSTER's own primitive gate rather than the brain's.
+ * `packages/api/src/routes/brain.ts:17-22`
+ * says exactly why that must not exist — "a second mount is how a route reaches
+ * the same data without the same gate" — and it was measured live on one tenant,
+ * one agent, one field: `POST /v1/users/{tu}/brain/connect` → 403
+ * `subprocessor_consent_required`, while the roster PATCH of
+ * `metadata.brain_knowledge_base_id` on the same agent → 200. The shipped
+ * `naive brain connect` was the caller of the ungated door.
+ *
+ * Three things came back with the move, none of which the roster PATCH did:
+ *   1. the `brain` primitive gate, so a company with brain disabled is refused
+ *      here the way it is refused everywhere else;
+ *   2. the `brain.agent.connected` `activity_events` row — the ledger entry that
+ *      makes a binding auditable;
+ *   3. `brain_connected_at`, stamped in the same statement as the binding.
+ * And one hazard went away: the roster PATCH read-modify-wrote the whole
+ * metadata bag, so two concurrent writers lost each other's keys. `connect` is a
+ * single `COALESCE(metadata,'{}') || {…}` merge in Postgres.
+ */
+export const BRAIN_CONNECT_PATH = "/v1/brain/connect";
+export const BRAIN_CONNECTIONS_PATH = "/v1/brain/connections";
+/**
+ * THE ROSTER SURFACE, NAMED ONCE — READ-ONLY FROM HERE.
+ *
+ * This is the only place in the multi-brain code that spells the retired noun,
+ * and it is spelled because it is a WIRE NAME: the route and the key of the
+ * array it answers with. `ci/vocabulary.test.ts` §3.1 retires the word for
+ * every other use — one governed worker identity is an AGENT — so everything
+ * downstream of these two constants says `agent`, including the errors a user
+ * reads. The surface is also DEPRECATED (its router carries a deprecation id).
+ *
+ * 🔴 IT IS NOW ONLY EVER READ. Nothing in this CLI PATCHes it: the one write
+ * that used to go here — the brain binding — moved to
+ * {@link BRAIN_CONNECT_PATH}. `__tests__/brain-multi.test.ts` asserts the roster
+ * sees no PATCH, so a future edit cannot quietly put the write back.
+ *
+ * TWO constants, not three. There was a third, `ROSTER_ITEM_KEY`, naming the
+ * envelope key of the SINGLE-agent response — and the only thing that ever read
+ * it was the PATCH's own reply. With the write gone it had no reader, and a dead
+ * constant spelling a retired noun is the shape a future edit reaches for when it
+ * wants to write here again. Deleted with the write. The list read below uses
+ * {@link ROSTER_LIST_KEY}; nothing in this CLI reads a single roster row.
+ */
+export const ROSTER_PATH = "/v1/employees";
+export const ROSTER_LIST_KEY = "employees";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** True when a reference is already the id the API wants — no lookup needed. */
+export function looksLikeId(ref) {
+    return UUID_RE.test(ref.trim());
+}
+/** `GET /v1/brain`. Exits via handleApiError on a non-2xx, like every other command. */
+export async function listBrains(action) {
+    const resp = await apiRequest("GET", "/v1/brain");
+    handleApiError(action, resp);
+    const data = resp.data;
+    return data.knowledge_bases ?? [];
+}
+/** A one-line rendering of a brain for an error message's recovery steps. */
+function brainLabel(b) {
+    return `${b.name}${b.is_default ? " (default)" : ""} — ${b.id}`;
+}
+function shellQuote(arg) {
+    return /[\s"'$`\\]/.test(arg) ? `"${arg.replace(/(["\\$`])/g, "\\$1")}"` : arg;
+}
+/**
+ * THE RECOVERY STEP IS THE USER'S OWN COMMAND, REPAIRED.
+ *
+ * A recovery step whose `command` is a bare fragment like `--brain "Support"`
+ * is not runnable, and the whole point of the envelope is that a model can
+ * execute the next step without reconstructing anything. So the failing
+ * argument is substituted back into the argv the caller actually typed.
+ */
+function rerunWith(wrong, right) {
+    const argv = process.argv.slice(2);
+    const i = argv.lastIndexOf(wrong);
+    const repaired = i >= 0 ? [...argv.slice(0, i), right, ...argv.slice(i + 1)] : [...argv, right];
+    return `naive ${repaired.map(shellQuote).join(" ")}`;
+}
+/**
+ * Name (or id) -> id. THE HELPFUL-ERROR PATH: naming a brain that does not
+ * exist lists the ones that do, in the envelope AND in the recovery steps, so
+ * an agent recovers from the response instead of guessing a second time.
+ */
+export async function resolveBrainId(action, ref) {
+    if (looksLikeId(ref))
+        return ref.trim();
+    const brains = await listBrains(action);
+    const wanted = ref.trim().toLowerCase();
+    const matches = brains.filter((b) => (b.name ?? "").trim().toLowerCase() === wanted);
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1) {
+        // Names are NOT unique in the schema — `brain_knowledge_bases` has a unique
+        // index on the DEFAULT flag and on the provider db, never on the name. Two
+        // brains may legitimately share one. Refusing with both ids is the only
+        // answer that cannot pick the wrong brain on the user's behalf.
+        agentError({
+            action,
+            error: {
+                code: "invalid_input",
+                message: `${matches.length} knowledge bases are named "${ref}". Name is not unique — pass an id.`,
+                available_brains: matches.map((b) => ({ id: b.id, name: b.name, is_default: b.is_default ?? false })),
+            },
+            recovery_steps: matches.map((b) => ({
+                command: rerunWith(ref, b.id),
+                description: brainLabel(b),
+            })),
+        });
+    }
+    agentError({
+        action,
+        error: {
+            code: "resource_not_found",
+            message: brains.length === 0
+                ? `No knowledge base named "${ref}" — this company has none yet.`
+                : `No knowledge base named "${ref}". This company has ${brains.length}: ${brains.map((b) => b.name).join(", ")}.`,
+            hint: "Brains are addressed by name or id. `naive brain list` shows both.",
+            available_brains: brains.map((b) => ({ id: b.id, name: b.name, is_default: b.is_default ?? false })),
+        },
+        recovery_steps: [
+            { command: "naive brain list", description: "List this company's knowledge bases" },
+            ...brains.slice(0, 5).map((b) => ({ command: rerunWith(ref, b.name), description: brainLabel(b) })),
+            { command: `naive brain create "${ref}"`, description: "Create a knowledge base with this name" },
+        ],
+    });
+    throw new Error("unreachable"); // agentError exits; this keeps the return type honest.
+}
+/**
+ * Resolve a command's brain selection to a `knowledge_base_id`, or `undefined`
+ * to mean "say nothing and let the server use the company default" — which is
+ * exactly what every one of these commands did before when no flag was passed.
+ *
+ * THE DEFAULT PATH IS UNTOUCHED: no selector -> `undefined` -> no
+ * `knowledge_base_id` in the body -> `resolveKnowledgeBase(companyId)` ->
+ * `ensureDefaultKnowledgeBase`. No extra request is made.
+ */
+export async function selectBrainId(action, sel) {
+    const given = [
+        sel.brain !== undefined && "--brain",
+        sel.kb !== undefined && "--kb",
+        sel.agent !== undefined && "--agent",
+    ].filter(Boolean);
+    if (given.length > 1) {
+        agentError({
+            action,
+            error: {
+                code: "invalid_input",
+                message: `A call reads ONE brain. Pass one of ${given.join(", ")}, not ${given.length}.`,
+                hint: "`--kb` is the id-only spelling of `--brain`; `--agent` means 'the brain that agent is bound to'.",
+            },
+            recovery_steps: [
+                { command: "naive brain list", description: "See the brains and what is bound to each" },
+            ],
+        });
+    }
+    if (sel.brain !== undefined)
+        return resolveBrainId(action, sel.brain);
+    if (sel.kb !== undefined)
+        return resolveBrainId(action, sel.kb);
+    if (sel.agent !== undefined) {
+        const agent = await resolveAgent(action, sel.agent);
+        const bound = boundBrainId(agent);
+        if (!bound) {
+            agentError({
+                action,
+                error: {
+                    code: "resource_not_found",
+                    message: `Agent "${agent.name}" is not connected to a brain, so there is no brain to read from.`,
+                    agent: { id: agent.id, name: agent.name },
+                },
+                recovery_steps: [
+                    { command: `naive brain connect <brain> --agent ${agent.id}`, description: "Connect this agent to a brain" },
+                    { command: "naive brain list", description: "See the brains and what is bound to each" },
+                ],
+            });
+        }
+        // A BINDING CAN OUTLIVE ITS BRAIN. `DELETE /v1/brain/:id` cannot reach into
+        // the roster, so deleting a knowledge base leaves every agent connected to
+        // it pointing at a row that is gone. Sending the stale id would come back as
+        // a bare `Knowledge base not found` naming an id the caller never typed;
+        // resolving it here costs one GET on a NEW flag and names the actual fault.
+        const brains = await listBrains(action);
+        if (!brains.some((b) => b.id === bound)) {
+            agentError({
+                action,
+                error: {
+                    code: "resource_not_found",
+                    message: `Agent "${agent.name}" is connected to knowledge base ${bound}, which no longer exists.`,
+                    hint: "The brain was deleted after the agent was connected to it. Connect the agent to a brain that exists.",
+                    agent: { id: agent.id, name: agent.name },
+                    knowledge_base_id: bound,
+                    available_brains: brains.map((b) => ({ id: b.id, name: b.name, is_default: b.is_default ?? false })),
+                },
+                recovery_steps: [
+                    ...brains.slice(0, 5).map((b) => ({
+                        command: `naive brain connect "${b.name}" --agent ${agent.id}`,
+                        description: brainLabel(b),
+                    })),
+                    { command: `naive brain disconnect --agent ${agent.id}`, description: "Clear the stale binding and fall back to the company default" },
+                ],
+            });
+        }
+        return bound;
+    }
+    return undefined;
+}
+/* ══════════════════════════════════════════════════════════════════════════
+ * THE AGENT SIDE
+ * ════════════════════════════════════════════════════════════════════════ */
+/**
+ * The roster, WITHOUT exiting on failure.
+ *
+ * `naive brain list` reports bindings as an ENRICHMENT of the brain list. The
+ * roster lives behind a different primitive, and a deprecated one, so a company
+ * that has it switched off must still get its brains
+ * listed — with the reason the bindings column is absent, not a silent empty
+ * one. An empty list and an unreadable roster are different facts.
+ */
+export async function tryListAgents() {
+    const resp = await apiRequest("GET", ROSTER_PATH);
+    if (resp.status >= 400) {
+        const err = resp.data?.error;
+        return {
+            ok: false,
+            because: `the agent roster could not be read (GET ${ROSTER_PATH} -> ${resp.status}${err?.code ? ` ${err.code}` : ""}${err?.message ? `: ${err.message}` : ""})`,
+        };
+    }
+    const data = (resp.data ?? {});
+    return { ok: true, agents: data[ROSTER_LIST_KEY] ?? [] };
+}
+/** The roster, exiting on failure — for the commands that cannot proceed without it. */
+export async function listAgents(action) {
+    const roster = await tryListAgents();
+    if (!roster.ok) {
+        agentError({
+            action,
+            error: { code: "upstream_error", message: `Cannot resolve an agent because ${roster.because}.` },
+            recovery_steps: [{ command: "naive brain list", description: "See the brains and what is bound to each" }],
+        });
+    }
+    return roster.agents;
+}
+/** The brain an agent is connected to, or undefined. */
+export function boundBrainId(agent) {
+    const raw = (agent.metadata ?? {})[BRAIN_BINDING_KEY];
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+function agentLabel(a) {
+    return `${a.name}${a.role ? ` (${a.role})` : ""} — ${a.id}`;
+}
+/**
+ * Reference (id | display name | hermes profile slug) -> the roster row. Same
+ * helpful-error contract as `resolveBrainId`: an unknown agent lists the known
+ * ones.
+ */
+export async function resolveAgent(action, ref) {
+    const agents = await listAgents(action);
+    const wanted = ref.trim().toLowerCase();
+    const byId = agents.find((a) => a.id === ref.trim());
+    if (byId)
+        return byId;
+    const matches = agents.filter((a) => (a.name ?? "").trim().toLowerCase() === wanted ||
+        (a.hermesProfileName ?? "").trim().toLowerCase() === wanted);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        agentError({
+            action,
+            error: {
+                code: "invalid_input",
+                message: `${matches.length} agents answer to "${ref}". Pass an id.`,
+                available_agents: matches.map((a) => ({ id: a.id, name: a.name })),
+            },
+            recovery_steps: matches.map((a) => ({ command: rerunWith(ref, a.id), description: agentLabel(a) })),
+        });
+    }
+    agentError({
+        action,
+        error: {
+            code: "resource_not_found",
+            message: agents.length === 0
+                ? `No agent named "${ref}" — this company's roster is empty.`
+                : `No agent named "${ref}". This company has ${agents.length}: ${agents.map((a) => a.name).join(", ")}.`,
+            hint: "An agent is addressed by id, display name, or runtime profile name. All three are listed below.",
+            available_agents: agents.map((a) => ({ id: a.id, name: a.name })),
+        },
+        recovery_steps: [
+            ...agents.slice(0, 5).map((a) => ({ command: rerunWith(ref, a.id), description: agentLabel(a) })),
+        ],
+    });
+    throw new Error("unreachable");
+}
+/**
+ * Write (or clear) an agent's brain binding, THROUGH THE BRAIN SURFACE.
+ *
+ * 🔴 NOT THE ROSTER PATCH. See {@link BRAIN_CONNECT_PATH} for the measurement:
+ * `PATCH {@link ROSTER_PATH}/:id` reaches `metadata.brain_knowledge_base_id`
+ * behind the ROSTER's primitive gate rather than the `brain` gate, so it wrote a
+ * binding on a company whose brain primitive was OFF. It also read-modify-wrote the whole
+ * metadata bag (lost-update racy), skipped the `brain.agent.connected` ledger
+ * event, and never stamped `brain_connected_at` — which is why
+ * `GET /v1/brain/connections` reported a `connected_at` belonging to an earlier
+ * binding to a different brain.
+ *
+ * `POST /v1/brain/connect` and `DELETE /v1/brain/connections/:agentId` do all
+ * four correctly and are the routes `naive brain list` already reads back. This
+ * function no longer sends `metadata` at all: it sends two ids, and the merge
+ * happens in one Postgres statement on the server.
+ *
+ * The returned `agent` carries the metadata as it now stands — the caller's row
+ * with the two brain-owned keys applied — so callers that print `metadata` keep
+ * printing something true without a second round trip. The authority is
+ * `connection`.
+ */
+export async function setAgentBrain(action, agent, knowledgeBaseId) {
+    const before = { ...(agent.metadata ?? {}) };
+    if (knowledgeBaseId === null) {
+        const resp = await apiRequest("DELETE", `${BRAIN_CONNECTIONS_PATH}/${encodeURIComponent(agent.id)}`);
+        handleApiError(action, resp);
+        delete before[BRAIN_BINDING_KEY];
+        delete before[BRAIN_CONNECTED_AT_KEY];
+        return { agent: { ...agent, metadata: before }, connection: null };
+    }
+    const resp = await apiRequest("POST", BRAIN_CONNECT_PATH, {
+        agent_id: agent.id,
+        knowledge_base_id: knowledgeBaseId,
+    });
+    handleApiError(action, resp);
+    const connection = (resp.data ?? {});
+    before[BRAIN_BINDING_KEY] = knowledgeBaseId;
+    // Only when the route said so. A CLI that invented a timestamp the server did
+    // not write would reintroduce, in the client, the exact drift the roster PATCH
+    // caused on the server.
+    if (typeof connection.connected_at === "string") {
+        before[BRAIN_CONNECTED_AT_KEY] = connection.connected_at;
+    }
+    return { agent: { ...agent, metadata: before }, connection };
+}
+/** The `next_steps` every binding command ends with. */
+export function bindingNextSteps(brain, agentId) {
+    return [
+        { command: "naive brain list", description: "See every brain and what is bound to each" },
+        {
+            command: `naive brain attach "<goal>" --agent ${agentId}`,
+            description: brain
+                ? `Read a capsule from "${brain.name}" as this agent`
+                : "Read a capsule from this agent's brain",
+        },
+    ];
+}
+//# sourceMappingURL=brain-select.js.map

package/dist/lib/brain-select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-select.js","sourceRoot":"","sources":["../../src/lib/brain-select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAiB,MAAM,cAAc,CAAC;AA6BzD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACtD,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC;AAC3C,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAElF,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc;IAC7C,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAClD,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAwC,CAAC;IAC3D,OAAO,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,6EAA6E;AAC7E,SAAS,UAAU,CAAC,CAAW;IAC7B,OAAO,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC;AAClE,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AACjF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,KAAa,EAAE,KAAa;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;IAChG,OAAO,SAAS,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc,EAAE,GAAW;IAC9D,IAAI,WAAW,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;IAExC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAC;IAErF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IAEhD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,4EAA4E;QAC5E,2EAA2E;QAC3E,wEAAwE;QACxE,gEAAgE;QAChE,UAAU,CAAC;YACT,MAAM;YACN,KAAK,EAAE;gBACL,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,+BAA+B,GAAG,qCAAqC;gBACjG,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,EAAE,CAAC,CAAC;aACtG;YACD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;gBAC7B,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;aAC3B,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC;QACT,MAAM;QACN,KAAK,EAAE;YACL,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EACL,MAAM,CAAC,MAAM,KAAK,CAAC;gBACjB,CAAC,CAAC,4BAA4B,GAAG,gCAAgC;gBACjE,CAAC,CAAC,4BAA4B,GAAG,uBAAuB,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YACrH,IAAI,EAAE,oEAAoE;YAC1E,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,EAAE,CAAC,CAAC;SACrG;QACD,cAAc,EAAE;YACd,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,qCAAqC,EAAE;YACnF,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnG,EAAE,OAAO,EAAE,uBAAuB,GAAG,GAAG,EAAE,WAAW,EAAE,wCAAwC,EAAE;SAClG;KACF,CAAC,CAAC;IACH,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,uDAAuD;AACzF,CAAC;AAYD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc,EAAE,GAAkB;IACpE,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS;QACpC,GAAG,CAAC,EAAE,KAAK,SAAS,IAAI,MAAM;QAC9B,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS;KACrC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;IAE9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,UAAU,CAAC;YACT,MAAM;YACN,KAAK,EAAE;gBACL,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,uCAAuC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG;gBACxF,IAAI,EAAE,kGAAkG;aACzG;YACD,cAAc,EAAE;gBACd,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,0CAA0C,EAAE;aACzF;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACtE,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAChE,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,UAAU,CAAC;gBACT,MAAM;gBACN,KAAK,EAAE;oBACL,IAAI,EAAE,oBAAoB;oBAC1B,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,mEAAmE;oBAChG,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;iBAC1C;gBACD,cAAc,EAAE;oBACd,EAAE,OAAO,EAAE,uCAAuC,KAAK,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,+BAA+B,EAAE;oBAC5G,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,0CAA0C,EAAE;iBACzF;aACF,CAAC,CAAC;QACL,CAAC;QAED,4EAA4E;QAC5E,2EAA2E;QAC3E,6EAA6E;QAC7E,yEAAyE;QACzE,4EAA4E;QAC5E,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE,CAAC;YACxC,UAAU,CAAC;gBACT,MAAM;gBACN,KAAK,EAAE;oBACL,IAAI,EAAE,oBAAoB;oBAC1B,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,oCAAoC,KAAK,2BAA2B;oBACjG,IAAI,EAAE,sGAAsG;oBAC5G,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;oBACzC,iBAAiB,EAAE,KAAK;oBACxB,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,EAAE,CAAC,CAAC;iBACrG;gBACD,cAAc,EAAE;oBACd,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wBAChC,OAAO,EAAE,wBAAwB,CAAC,CAAC,IAAI,aAAa,KAAK,CAAC,EAAE,EAAE;wBAC9D,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;qBAC3B,CAAC,CAAC;oBACH,EAAE,OAAO,EAAE,kCAAkC,KAAK,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,8DAA8D,EAAE;iBACvI;aACF,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;8EAE8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IAGjC,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAI,IAAI,CAAC,IAA+D,EAAE,KAAK,CAAC;QACzF,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,2CAA2C,WAAW,OAAO,IAAI,CAAC,MAAM,GAC/E,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAC/B,GAAG,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;SAC7C,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAA2C,CAAC;IACzE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC;AAC3D,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAc;IAC7C,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,UAAU,CAAC;YACT,MAAM;YACN,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,mCAAmC,MAAM,CAAC,OAAO,GAAG,EAAE;YAChG,cAAc,EAAE,CAAC,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,0CAA0C,EAAE,CAAC;SAC3G,CAAC,CAAC;IACL,CAAC;IACD,OAAQ,MAA2C,CAAC,MAAM,CAAC;AAC7D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,KAAe;IAC1C,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACtD,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACrE,CAAC;AAED,SAAS,UAAU,CAAC,CAAW;IAC7B,OAAO,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc,EAAE,GAAW;IAC5D,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACrD,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAC3B,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM;QAC9C,CAAC,CAAC,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAC9D,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,CAAC,CAAE,CAAC;IAE7C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,UAAU,CAAC;YACT,MAAM;YACN,KAAK,EAAE;gBACL,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,sBAAsB,GAAG,gBAAgB;gBACnE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;aACnE;YACD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACpG,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC;QACT,MAAM;QACN,KAAK,EAAE;YACL,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EACL,MAAM,CAAC,MAAM,KAAK,CAAC;gBACjB,CAAC,CAAC,mBAAmB,GAAG,qCAAqC;gBAC7D,CAAC,CAAC,mBAAmB,GAAG,uBAAuB,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC5G,IAAI,EAAE,iGAAiG;YACvG,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;SAClE;QACD,cAAc,EAAE;YACd,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SAClG;KACF,CAAC,CAAC;IACH,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;AACjC,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,KAAe,EACf,eAA8B;IAE9B,MAAM,MAAM,GAAG,EAAE,GAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAA6B,EAAE,CAAC;IAE1E,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,MAAM,UAAU,CAC3B,QAAQ,EACR,GAAG,sBAAsB,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAC5D,CAAC;QACF,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;QACtC,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,kBAAkB,EAAE;QACxD,QAAQ,EAAE,KAAK,CAAC,EAAE;QAClB,iBAAiB,EAAE,eAAe;KACnC,CAAC,CAAC;IACH,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7B,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAoB,CAAC;IACxD,MAAM,CAAC,iBAAiB,CAAC,GAAG,eAAe,CAAC;IAC5C,8EAA8E;IAC9E,+EAA+E;IAC/E,wBAAwB;IACxB,IAAI,OAAO,UAAU,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,CAAC,sBAAsB,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC;IAC3D,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC;AAC/D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,gBAAgB,CAAC,KAA2B,EAAE,OAAe;IAC3E,OAAO;QACL,EAAE,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,2CAA2C,EAAE;QACzF;YACE,OAAO,EAAE,uCAAuC,OAAO,EAAE;YACzD,WAAW,EAAE,KAAK;gBAChB,CAAC,CAAC,wBAAwB,KAAK,CAAC,IAAI,iBAAiB;gBACrD,CAAC,CAAC,wCAAwC;SAC7C;KACF,CAAC;AACJ,CAAC"}

package/dist/lib/cli-validation.d.ts

@@ -0,0 +1,12 @@
+import { type Command } from "commander";
+export declare function isTenantUserRef(value: string): boolean;
+/**
+ * Fail-closed for malformed `--user` before any HTTP call.
+ * Mirrors API subject-resolver: non-uuid ids never match → not_found (never a DB 500 / rate-limit burn).
+ */
+export declare function assertTenantUserRef(user: string | undefined): void;
+export declare function configureStructuredValidation(command: Command): void;
+export declare function parseIntegerOption(value: string, name: string, min: number, max?: number): number;
+export declare function commandAction(args: readonly string[]): string;
+export declare function cleanCommanderMessage(message: string): string;
+export declare function helpCommand(args: readonly string[]): string;

package/dist/lib/cli-validation.js

@@ -0,0 +1,46 @@
+import { InvalidArgumentError } from "commander";
+/** Same shape the API accepts for `:user_id` / `--user` (uuid or default/me aliases). */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const USER_ALIASES = new Set(["default", "me"]);
+export function isTenantUserRef(value) {
+    return USER_ALIASES.has(value) || UUID_RE.test(value);
+}
+/**
+ * Fail-closed for malformed `--user` before any HTTP call.
+ * Mirrors API subject-resolver: non-uuid ids never match → not_found (never a DB 500 / rate-limit burn).
+ */
+export function assertTenantUserRef(user) {
+    if (user === undefined || user === "")
+        return;
+    if (isTenantUserRef(user))
+        return;
+    throw Object.assign(new Error("User not found"), {
+        code: "not_found",
+        hint: "The user_id does not exist in your workspace.",
+    });
+}
+export function configureStructuredValidation(command) {
+    command.exitOverride();
+    command.configureOutput({ writeErr: () => { } });
+    for (const child of command.commands)
+        configureStructuredValidation(child);
+}
+export function parseIntegerOption(value, name, min, max = Number.MAX_SAFE_INTEGER) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+        throw new InvalidArgumentError(`${name} must be an integer between ${min} and ${max}`);
+    }
+    return parsed;
+}
+export function commandAction(args) {
+    const words = args.filter((arg) => !arg.startsWith("-")).slice(0, 2);
+    return words.length > 0 ? words.join(".") : "cli.validation";
+}
+export function cleanCommanderMessage(message) {
+    return message.replace(/^error:\s*/i, "").trim() || "Invalid command options";
+}
+export function helpCommand(args) {
+    const command = args.filter((arg) => !arg.startsWith("-")).slice(0, 2).join(" ");
+    return command ? `naive ${command} --help` : "naive --help";
+}
+//# sourceMappingURL=cli-validation.js.map

package/dist/lib/cli-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-validation.js","sourceRoot":"","sources":["../../src/lib/cli-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAgB,MAAM,WAAW,CAAC;AAE/D,yFAAyF;AACzF,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAClF,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;AAEhD,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAwB;IAC1D,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO;IAC9C,IAAI,eAAe,CAAC,IAAI,CAAC;QAAE,OAAO;IAClC,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB,CAAC,EAAE;QAC/C,IAAI,EAAE,WAAoB;QAC1B,IAAI,EAAE,+CAA+C;KACtD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,OAAgB;IAC5D,OAAO,CAAC,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC,CAAC;IAChD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ;QAAE,6BAA6B,CAAC,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,IAAY,EACZ,GAAW,EACX,GAAG,GAAG,MAAM,CAAC,gBAAgB;IAE7B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;QAClE,MAAM,IAAI,oBAAoB,CAAC,GAAG,IAAI,+BAA+B,GAAG,QAAQ,GAAG,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,yBAAyB,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAuB;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC,CAAC,CAAC,SAAS,OAAO,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC;AAC9D,CAAC"}

package/dist/lib/deprecation.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The one deprecation experience for the CLI (06 §1.9 / §1.10.1).
+ *
+ * THE RULE THIS FILE EXISTS TO KEEP: a deprecated command KEEPS WORKING. Nothing
+ * here refuses, gates, or short-circuits — `markDeprecated` installs a commander
+ * `preAction` hook that writes a banner to STDERR and then returns, and the
+ * action runs exactly as it did before. Existing users must not break.
+ *
+ * WHY A preAction HOOK AND NOT A CALL INSIDE EACH HANDLER. A hook on the GROUP
+ * fires for every subcommand of that group, including subcommands added later by
+ * someone who has never read this file. A per-handler call is a convention, and a
+ * convention is a thing that is true until the next PR.
+ *
+ * WHY STDERR. The CLI's contract is that stdout is `JSON.parse`-able. The banner
+ * is for a human; the machine half is `deprecation` on the stdout envelope, set
+ * here through `setPendingDeprecation` and consumed by `agentOutput` exactly the
+ * way `update` already is.
+ *
+ * ── THE THREE LOAD-BEARING DETAILS OF THE TEXT ──────────────────────────────
+ *
+ *  1. THE `[dep.…]` ID is printed because it is the one word an operator can grep
+ *     across every rendering of the same fact — the CLI banner, the JSON
+ *     envelope, and (when they land) the openapi extension, the MCP tool
+ *     description and the dashboard notice. Renderings drift; an id does not.
+ *
+ *  2. THE "also called" LINE is not decoration. The legacy orchestration runtime
+ *     has EIGHT in-tree names. A notice that names one leaves seven ways to keep
+ *     talking about the thing it is retiring.
+ *
+ *  3. "frozen, no sunset date" is rendered from a CLOSED two-member `Sunset`
+ *     union. There is no "removal TBD", because a date nobody can keep is how a
+ *     banner becomes furniture.
+ *
+ * And `Replacement` is closed for the same reason: a capability that is simply
+ * GONE renders as `{kind:"gap", because}`. It cannot be rendered as an empty
+ * string, and the reason is required by the type rather than by review. A notice
+ * that invents a replacement for a capability that no longer exists is worse than
+ * no notice at all.
+ */
+import type { Command } from "commander";
+import { type DeprecationNotice, type NextStep } from "../output.js";
+/** A replacement is a real symbol or an admitted gap. Closed on purpose (R-7). */
+export type Replacement = {
+    readonly kind: "use";
+    readonly what: string;
+} | {
+    readonly kind: "gap";
+    readonly because: string;
+};
+/** Frozen, or a date. There is no third member and no "TBD". */
+export type Sunset = {
+    readonly kind: "frozen";
+} | {
+    readonly kind: "on";
+    readonly date: string;
+};
+/** One subcommand of a deprecated group whose capability has no replacement. */
+export interface SubcommandGap {
+    readonly sub: string;
+    readonly because: string;
+}
+export interface DeprecationSpec {
+    /**
+     * THE REGISTER'S id, not a derived one.
+     *
+     * This used to be computed as `dep.${cmd.name()}` — `dep.tasks`, `dep.ceo` —
+     * while `packages/api/src/routes/deprecations.ts` mints `dep.primitive.tasks`
+     * and emits it in the `X-Naive-Deprecation-Id` response header, whose own
+     * comment calls it "the grep handle … the SAME id the openapi operation
+     * carries". The dashboard uses the API's spelling too. So the one thing the
+     * machine channel exists for — correlating a CLI warning with the HTTP header
+     * for the same retirement — matched nothing.
+     *
+     * Declared rather than derived because the mapping is not a function of the
+     * command name: a future group may retire to a `dep.surface.*` row.
+     *
+     * TWO NAMESPACES, and the difference is real:
+     *   `dep.primitive.*` / `dep.surface.*`  the REST register's own ids. These
+     *       MUST exist there — `ci/docs-deprecation-parity.mjs` asserts it — so a
+     *       CLI warning and an `X-Naive-Deprecation-Id` header correlate.
+     *   `dep.cli.*`  a retirement with no REST twin, because the endpoints are
+     *       gone rather than deprecated (`naive verify`). There is no operation to
+     *       mark and no header to match, and saying so in the id is better than
+     *       pointing at a register row that cannot exist.
+     */
+    readonly id: string;
+    /** One sentence: what this command drives. Rendered after the header. */
+    readonly drives: string;
+    /** Every other in-tree name for the thing being retired (detail 2 above). */
+    readonly alsoCalled: readonly string[];
+    readonly replacement: Replacement;
+    /** Why the replacement is better. Rendered on the "Why:" line. */
+    readonly why: string;
+    /** `YYYY-MM` — when the deprecation was declared. */
+    readonly since: string;
+    readonly sunset: Sunset;
+    readonly guide: string;
+    /** Subcommands of this group whose capability is gone, with the reason. */
+    readonly gaps?: readonly SubcommandGap[];
+}
+export interface DeprecationRecord extends DeprecationSpec {
+    /** `naive tasks` — derived from the commander command, never retyped. */
+    readonly subject: string;
+}
+/**
+ * The eight names the legacy orchestration runtime answers to in this tree.
+ * Exported so a staleness check can hold it against the source rather than
+ * against memory — a list like this becomes folklore the moment nothing reads it.
+ */
+export declare const LEGACY_RUNTIME_ALIASES: readonly ["orchestration", "warm pool", "instance pool", "Hermes", "sidecar", "container runtime", "hosted runtime", "runtime.pool"];
+/** Build the full record from the commander command plus its spec. */
+export declare function deprecationRecord(cmd: Command, spec: DeprecationSpec): DeprecationRecord;
+/** The machine half — what rides the stdout envelope. */
+export declare function deprecationNotice(rec: DeprecationRecord, status: "deprecated" | "retired"): DeprecationNotice;
+/**
+ * The banner, as a string. Pure, so the wording is a test rather than a habit.
+ * The first line carries the two facts an operator needs before anything else:
+ * it is deprecated, and it KEEPS WORKING.
+ */
+export declare function renderDeprecationBanner(rec: DeprecationRecord): string;
+export declare function _resetDeprecationBannersForTest(): void;
+/**
+ * Mark a command group deprecated. The group keeps working; every invocation
+ * writes the banner to stderr (once per process) and attaches the machine notice
+ * to the next stdout envelope.
+ *
+ * Returns the record so the caller can assert on it — the registry in index.ts is
+ * built from the return values, which is what makes the set of deprecations a
+ * value a test can read instead of a side effect it has to observe.
+ */
+export declare function markDeprecated(cmd: Command, spec: DeprecationSpec): DeprecationRecord;
+/**
+ * A RETIRED command: it no longer does anything, and saying so is the whole
+ * behaviour. Distinct from `markDeprecated`, which never refuses.
+ *
+ * ── WHY THE CODE IS `deprecated_command` AND WHY IT IS NOT IN THE SERVER UNION ──
+ *
+ * `platform/kernel/src/errors.ts` holds a 25-member `ErrorCode` union typed as
+ * `Record<ErrorCode, number>` in `STATUS_MAP` — it is the set of codes an HTTP
+ * RESPONSE can carry, and every member owes a status. `deprecated_command` is
+ * minted here, by the CLI, for a command that makes no request at all: there is
+ * no response and therefore no status to map. Adding it to that union would put
+ * a code the server can never emit into the type that says what the server emits.
+ *
+ * It is instead the fourth member of the CLI-LOCAL code namespace that already
+ * exists in this package and is already relied on by callers:
+ * `cli_outdated` and `unknown_subcommand` (lib/unknown-command.ts:8) and
+ * `upstream_error` (client.ts:97). All three are minted client-side and none is
+ * in the server union. `CLI_LOCAL_ERROR_CODES` below names the set so it stays a
+ * declared four rather than a habit.
+ */
+export declare const CLI_LOCAL_ERROR_CODES: readonly ["cli_outdated", "unknown_subcommand", "upstream_error", "deprecated_command"];
+export declare function retiredCommand(opts: {
+    action: string;
+    message: string;
+    recovery_steps: NextStep[];
+    notice?: DeprecationNotice;
+}): void;