@cuna_labs/cli 0.1.0

package/dist/core/observation-budget.d.ts

@@ -0,0 +1,185 @@
+import { CunaError, type SafeErrorDetails } from "./errors.js";
+/**
+ * THE ONE PLACE THE CLI IS ALLOWED TO SAY "I STOPPED LOOKING".
+ *
+ * WHY THIS FILE EXISTS. Measured 2026-08-19 against Fly release v93 from the
+ * installed `cuna 0.1.0`: `cuna machines create --yes` returned
+ * `cuna.network.timeout` with `retryable: false` while the machine reached
+ * `running` about five seconds later, and `cuna machines delete <id> --yes`
+ * returned `cuna.remote.postcondition_unverified` with
+ * `observed_state: "present"` while `cuna machines list` six seconds later
+ * showed the machine gone. Neither detector detected what its code named. The
+ * first detected THIS PROCESS'S OWN `setTimeout` firing — the network was fine.
+ * The second detected THIS PROCESS reading back once, immediately, before a
+ * durable accept could become visible — the postcondition was not unverifiable,
+ * it was unwaited.
+ *
+ * So the rule this file enforces is not "wait longer". Raising a default moves
+ * the boundary without naming it and the next slower operation reproduces the
+ * bug identically. The rule is: **a refusal caused by the client's own budget
+ * is a different KIND of answer from a refusal caused by the operation**, and it
+ * gets its own codes, its own retryability and its own sentence.
+ *
+ * THREE PROPERTIES, AND THEY ARE STRUCTURAL RATHER THAN CONVENTIONAL.
+ *
+ *  1. `retryable` is written `true` at exactly one site — below. A caller cannot
+ *     mint a budget refusal that denies retry, because the field is not a
+ *     parameter. `retryable: false` was the worst available answer: it told the
+ *     user not to try again AND implied the mutation had not landed, and both
+ *     halves were false.
+ *  2. The refusal names the read-only command that resolves the unknown. A
+ *     refusal that says "unknown" and stops has handed the user a dead end,
+ *     which is the specific failure this repository already closed on the
+ *     credential path. `settleWith` is optional in the TYPE and never optional
+ *     in practice for the commands that mutate: the alternative — a required
+ *     field with a default — would put a confidently WRONG command in front of
+ *     users of every operation that forgot to declare one, and a false
+ *     instruction is worse than a general one. The declarations live beside the
+ *     paths in `api/client.ts`, and `test/observation-budget.test.mjs` asserts
+ *     the exact command for the two operations this was measured on.
+ *  3. The message never asserts the mutation did not apply, and `details`
+ *     carries `remote_outcome: "unobserved"` so a machine reader sees the same
+ *     limit the human sentence states.
+ *
+ * WHAT THIS FILE IS NOT. It is not a place for genuine remote failures. A
+ * connection that was refused, a TLS error or a DNS failure is a network fault
+ * and keeps `cuna.network.failed`, including its fail-closed retryability for
+ * mutations: there the network really did fail, and the CLI has no evidence the
+ * request was ever dispatched. A read-back that returns a value which CONTRADICTS
+ * the write — a rename that observed a different name, a create that observed a
+ * different id — is a real postcondition violation that no amount of waiting
+ * repairs, and keeps `cuna.remote.postcondition_unverified`. The discriminator
+ * is the one this file is named after: did the operation answer wrongly, or did
+ * we stop asking?
+ */
+/**
+ * The per-request observation budget when the caller passes no `--timeout-ms`
+ * and the operation declares no budget of its own.
+ *
+ * This used to be the literal `15_000` written twice — once in `cli/run.ts` as
+ * the flag default and once in `api/http.ts` as the transport default — which is
+ * the one-concept-two-homes shape this repository keeps closing. It is read from
+ * here in both places now.
+ */
+export declare const DEFAULT_REQUEST_BUDGET_MS = 15000;
+/**
+ * `POST /v1/sessions` waits for the provider, so it is not bounded by the same
+ * budget as a list.
+ *
+ * DERIVATION, because a constant without one cannot be confirmed or refuted.
+ * Measured 2026-08-19T00:17Z against Fly release v93: the CLI aborted at the
+ * 15 s default and the machine reached `state=running` roughly five seconds
+ * after a 24 s wall-clock invocation, so the server-side create is at least
+ * ~50 s [owner-measured, not re-measured here — re-measuring costs a real
+ * machine]. 90 000 ms is that duration with an 80% margin, and it stays inside
+ * the documented `--timeout-ms` ceiling of 120 000 so a user can still widen it
+ * by hand.
+ *
+ * This is deliberately NOT the global default. Raising the global default would
+ * make every unrelated failure take six times longer to surface.
+ */
+export declare const MACHINE_CREATE_REQUEST_BUDGET_MS = 90000;
+/**
+ * `POST /v1/sessions/{id}/{start|resume}` boots a VM and waits for its
+ * supervisor to accept control before it answers, so it is not bounded by the
+ * same budget as a list either.
+ *
+ * DERIVATION. Measured 2026-09-02 against edge v148 on Machine fceaf633: the
+ * answer came at 24 s from `cuna machines start` (which the caller had widened
+ * by hand with `--timeout-ms`), while the same transition inside `cuna
+ * opencode` aborted at the 15 s default and told the user the operation "may
+ * have completed" — for the step the journey itself had just decided to take.
+ * 60 000 ms is that duration with a 150% margin; it stays well inside the
+ * `--timeout-ms` ceiling of 120 000, and it is deliberately lower than the
+ * create budget because starting an existing VM does not provision one.
+ */
+export declare const MACHINE_LIFECYCLE_REQUEST_BUDGET_MS = 60000;
+/**
+ * `POST /v1/sessions/{id}/supervisor/live-update` replaces a RUNNING Machine's
+ * supervisor in place, and it does five bounded remote steps before it answers.
+ *
+ * DERIVATION, summed from the producer's own declared timeouts rather than from
+ * a wall-clock sample, because no live run of this operation has been observed
+ * from this CLI yet and a constant invented from nothing cannot be refuted:
+ *
+ *   30 s  pre-install session-custody observation
+ *           (`MACHINE_SUPERVISOR_LIVE_CONTINUITY_TIMEOUT_SECONDS`)
+ *   10 s  exec-readiness probe (`MACHINE_SUPERVISOR_EXEC_READY_TIMEOUT_MS`)
+ *   90 s  the installer itself, on the live-process path
+ *           (`MACHINE_SUPERVISOR_LIVE_EXEC_TIMEOUT_SECONDS`)
+ *   15 s  waiting for the exact new control to acknowledge
+ *           (`MACHINE_SUPERVISOR_ACK_TIMEOUT_MS`)
+ *   30 s  the post-install custody re-read, same bound as the first
+ *   ----
+ *  175 s  before the provider read, the Machine reads and the edge's own work.
+ *
+ * 240 000 ms is that sum with a ~37% margin. It is deliberately ABOVE the
+ * `--timeout-ms` ceiling of 120 000: a caller who passes that flag overrides
+ * this budget downward and will abort a dispatch that is still in flight, which
+ * this command must then report as an unknown outcome rather than a failure.
+ * That is why the budget lives here with its derivation instead of being the
+ * lifecycle constant reused one command too far.
+ */
+export declare const SUPERVISOR_LIVE_UPDATE_REQUEST_BUDGET_MS = 240000;
+/**
+ * How long the CLI reads back before it stops judging a postcondition.
+ *
+ * DERIVATION. Measured 2026-08-19: a deleted machine was still `present` on an
+ * immediate read and absent from `cuna machines list` six seconds later. The
+ * pre-existing AgentSession termination budget in `commands/commands.ts` was
+ * 15 000 ms and was the only convergence budget in the tree. 30 000 ms is the
+ * larger of the two doubled, and one constant replaces both so the two cannot
+ * drift apart again.
+ *
+ * Re-measured 2026-09-02 on production: `agent-sessions terminate` was
+ * accepted and the row read `exited` about 36 s later, so a 30 s read-back
+ * reported a false failure (exit 5) for a termination that completed. The
+ * read-back is a cheap poll; 120 s covers a supervisor that has to fence and
+ * flush a live PTY without turning a completed operation into an error.
+ */
+export declare const REMOTE_CONVERGENCE_BUDGET_MS = 120000;
+/** Interval between read-backs while converging. */
+export declare const REMOTE_CONVERGENCE_POLL_INTERVAL_MS = 500;
+/**
+ * Every error code the CLI can mint because ITS OWN budget elapsed.
+ *
+ * This record is the authority. Consumers that need to ask "is this refusal one
+ * of ours?" — the workspace sync retry policy, the journey's uncertain-dispatch
+ * recovery — read `isObservationBudgetCode` rather than comparing literals, so
+ * adding a third kind cannot leave a consumer behind.
+ *
+ * `test/observation-budget.test.mjs` holds a hand-written floor of these exact
+ * strings in both directions, so neither deleting an entry nor adding one
+ * silently is possible. A test parametrized over this record alone would narrow
+ * along with it.
+ */
+export declare const OBSERVATION_BUDGET_CODES: Readonly<{
+    /** The CLI stopped waiting for a single HTTP response. */
+    readonly response: "cuna.client.response_budget_elapsed";
+    /** The CLI stopped reading back before an accepted change became visible. */
+    readonly convergence: "cuna.client.convergence_budget_elapsed";
+}>;
+export type ObservationBudgetKind = keyof typeof OBSERVATION_BUDGET_CODES;
+export declare function isObservationBudgetCode(code: string): boolean;
+export interface ObservationBudgetElapsedInput {
+    readonly kind: ObservationBudgetKind;
+    /** What was being observed, e.g. `machine deletion` or `POST /v1/sessions`. */
+    readonly operation: string;
+    /** The read-only command that settles the question, e.g. `cuna machines list`. */
+    readonly settleWith?: string;
+    /** The budget that elapsed, in milliseconds. */
+    readonly budgetMs: number;
+    readonly details?: SafeErrorDetails;
+    readonly cause?: unknown;
+}
+/**
+ * Mint the refusal that says "the CLI stopped observing", and nothing stronger.
+ *
+ * The exit code is `network` (5), whose published meaning is already "no
+ * authoritative answer arrived", which is exactly this. It is deliberately NOT
+ * `conflict` (6): `conflict` means current state contradicts the change and
+ * repeating it unchanged repeats the answer, and telling a script that about an
+ * operation which probably succeeded is worse than saying nothing.
+ */
+export declare function observationBudgetElapsed(input: ObservationBudgetElapsedInput): CunaError;
+//# sourceMappingURL=observation-budget.d.ts.map

package/dist/core/observation-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-budget.d.ts","sourceRoot":"","sources":["../../src/core/observation-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,wCAAwC,SAAU,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,oDAAoD;AACpD,eAAO,MAAM,mCAAmC,MAAM,CAAC;AAMvD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB;IACnC,0DAA0D;;IAE1D,6EAA6E;;EAEpE,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAM1E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAMD,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,6BAA6B,GAAG,SAAS,CA2BxF"}

package/dist/core/observation-budget.js

@@ -0,0 +1,209 @@
+import { EXIT_CODES, CunaError } from "./errors.js";
+/**
+ * THE ONE PLACE THE CLI IS ALLOWED TO SAY "I STOPPED LOOKING".
+ *
+ * WHY THIS FILE EXISTS. Measured 2026-08-19 against Fly release v93 from the
+ * installed `cuna 0.1.0`: `cuna machines create --yes` returned
+ * `cuna.network.timeout` with `retryable: false` while the machine reached
+ * `running` about five seconds later, and `cuna machines delete <id> --yes`
+ * returned `cuna.remote.postcondition_unverified` with
+ * `observed_state: "present"` while `cuna machines list` six seconds later
+ * showed the machine gone. Neither detector detected what its code named. The
+ * first detected THIS PROCESS'S OWN `setTimeout` firing — the network was fine.
+ * The second detected THIS PROCESS reading back once, immediately, before a
+ * durable accept could become visible — the postcondition was not unverifiable,
+ * it was unwaited.
+ *
+ * So the rule this file enforces is not "wait longer". Raising a default moves
+ * the boundary without naming it and the next slower operation reproduces the
+ * bug identically. The rule is: **a refusal caused by the client's own budget
+ * is a different KIND of answer from a refusal caused by the operation**, and it
+ * gets its own codes, its own retryability and its own sentence.
+ *
+ * THREE PROPERTIES, AND THEY ARE STRUCTURAL RATHER THAN CONVENTIONAL.
+ *
+ *  1. `retryable` is written `true` at exactly one site — below. A caller cannot
+ *     mint a budget refusal that denies retry, because the field is not a
+ *     parameter. `retryable: false` was the worst available answer: it told the
+ *     user not to try again AND implied the mutation had not landed, and both
+ *     halves were false.
+ *  2. The refusal names the read-only command that resolves the unknown. A
+ *     refusal that says "unknown" and stops has handed the user a dead end,
+ *     which is the specific failure this repository already closed on the
+ *     credential path. `settleWith` is optional in the TYPE and never optional
+ *     in practice for the commands that mutate: the alternative — a required
+ *     field with a default — would put a confidently WRONG command in front of
+ *     users of every operation that forgot to declare one, and a false
+ *     instruction is worse than a general one. The declarations live beside the
+ *     paths in `api/client.ts`, and `test/observation-budget.test.mjs` asserts
+ *     the exact command for the two operations this was measured on.
+ *  3. The message never asserts the mutation did not apply, and `details`
+ *     carries `remote_outcome: "unobserved"` so a machine reader sees the same
+ *     limit the human sentence states.
+ *
+ * WHAT THIS FILE IS NOT. It is not a place for genuine remote failures. A
+ * connection that was refused, a TLS error or a DNS failure is a network fault
+ * and keeps `cuna.network.failed`, including its fail-closed retryability for
+ * mutations: there the network really did fail, and the CLI has no evidence the
+ * request was ever dispatched. A read-back that returns a value which CONTRADICTS
+ * the write — a rename that observed a different name, a create that observed a
+ * different id — is a real postcondition violation that no amount of waiting
+ * repairs, and keeps `cuna.remote.postcondition_unverified`. The discriminator
+ * is the one this file is named after: did the operation answer wrongly, or did
+ * we stop asking?
+ */
+/* -------------------------------------------------------------------------- */
+/* Budgets                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * The per-request observation budget when the caller passes no `--timeout-ms`
+ * and the operation declares no budget of its own.
+ *
+ * This used to be the literal `15_000` written twice — once in `cli/run.ts` as
+ * the flag default and once in `api/http.ts` as the transport default — which is
+ * the one-concept-two-homes shape this repository keeps closing. It is read from
+ * here in both places now.
+ */
+export const DEFAULT_REQUEST_BUDGET_MS = 15_000;
+/**
+ * `POST /v1/sessions` waits for the provider, so it is not bounded by the same
+ * budget as a list.
+ *
+ * DERIVATION, because a constant without one cannot be confirmed or refuted.
+ * Measured 2026-08-19T00:17Z against Fly release v93: the CLI aborted at the
+ * 15 s default and the machine reached `state=running` roughly five seconds
+ * after a 24 s wall-clock invocation, so the server-side create is at least
+ * ~50 s [owner-measured, not re-measured here — re-measuring costs a real
+ * machine]. 90 000 ms is that duration with an 80% margin, and it stays inside
+ * the documented `--timeout-ms` ceiling of 120 000 so a user can still widen it
+ * by hand.
+ *
+ * This is deliberately NOT the global default. Raising the global default would
+ * make every unrelated failure take six times longer to surface.
+ */
+export const MACHINE_CREATE_REQUEST_BUDGET_MS = 90_000;
+/**
+ * `POST /v1/sessions/{id}/{start|resume}` boots a VM and waits for its
+ * supervisor to accept control before it answers, so it is not bounded by the
+ * same budget as a list either.
+ *
+ * DERIVATION. Measured 2026-09-02 against edge v148 on Machine fceaf633: the
+ * answer came at 24 s from `cuna machines start` (which the caller had widened
+ * by hand with `--timeout-ms`), while the same transition inside `cuna
+ * opencode` aborted at the 15 s default and told the user the operation "may
+ * have completed" — for the step the journey itself had just decided to take.
+ * 60 000 ms is that duration with a 150% margin; it stays well inside the
+ * `--timeout-ms` ceiling of 120 000, and it is deliberately lower than the
+ * create budget because starting an existing VM does not provision one.
+ */
+export const MACHINE_LIFECYCLE_REQUEST_BUDGET_MS = 60_000;
+/**
+ * `POST /v1/sessions/{id}/supervisor/live-update` replaces a RUNNING Machine's
+ * supervisor in place, and it does five bounded remote steps before it answers.
+ *
+ * DERIVATION, summed from the producer's own declared timeouts rather than from
+ * a wall-clock sample, because no live run of this operation has been observed
+ * from this CLI yet and a constant invented from nothing cannot be refuted:
+ *
+ *   30 s  pre-install session-custody observation
+ *           (`MACHINE_SUPERVISOR_LIVE_CONTINUITY_TIMEOUT_SECONDS`)
+ *   10 s  exec-readiness probe (`MACHINE_SUPERVISOR_EXEC_READY_TIMEOUT_MS`)
+ *   90 s  the installer itself, on the live-process path
+ *           (`MACHINE_SUPERVISOR_LIVE_EXEC_TIMEOUT_SECONDS`)
+ *   15 s  waiting for the exact new control to acknowledge
+ *           (`MACHINE_SUPERVISOR_ACK_TIMEOUT_MS`)
+ *   30 s  the post-install custody re-read, same bound as the first
+ *   ----
+ *  175 s  before the provider read, the Machine reads and the edge's own work.
+ *
+ * 240 000 ms is that sum with a ~37% margin. It is deliberately ABOVE the
+ * `--timeout-ms` ceiling of 120 000: a caller who passes that flag overrides
+ * this budget downward and will abort a dispatch that is still in flight, which
+ * this command must then report as an unknown outcome rather than a failure.
+ * That is why the budget lives here with its derivation instead of being the
+ * lifecycle constant reused one command too far.
+ */
+export const SUPERVISOR_LIVE_UPDATE_REQUEST_BUDGET_MS = 240_000;
+/**
+ * How long the CLI reads back before it stops judging a postcondition.
+ *
+ * DERIVATION. Measured 2026-08-19: a deleted machine was still `present` on an
+ * immediate read and absent from `cuna machines list` six seconds later. The
+ * pre-existing AgentSession termination budget in `commands/commands.ts` was
+ * 15 000 ms and was the only convergence budget in the tree. 30 000 ms is the
+ * larger of the two doubled, and one constant replaces both so the two cannot
+ * drift apart again.
+ *
+ * Re-measured 2026-09-02 on production: `agent-sessions terminate` was
+ * accepted and the row read `exited` about 36 s later, so a 30 s read-back
+ * reported a false failure (exit 5) for a termination that completed. The
+ * read-back is a cheap poll; 120 s covers a supervisor that has to fence and
+ * flush a live PTY without turning a completed operation into an error.
+ */
+export const REMOTE_CONVERGENCE_BUDGET_MS = 120_000;
+/** Interval between read-backs while converging. */
+export const REMOTE_CONVERGENCE_POLL_INTERVAL_MS = 500;
+/* -------------------------------------------------------------------------- */
+/* The authority                                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * Every error code the CLI can mint because ITS OWN budget elapsed.
+ *
+ * This record is the authority. Consumers that need to ask "is this refusal one
+ * of ours?" — the workspace sync retry policy, the journey's uncertain-dispatch
+ * recovery — read `isObservationBudgetCode` rather than comparing literals, so
+ * adding a third kind cannot leave a consumer behind.
+ *
+ * `test/observation-budget.test.mjs` holds a hand-written floor of these exact
+ * strings in both directions, so neither deleting an entry nor adding one
+ * silently is possible. A test parametrized over this record alone would narrow
+ * along with it.
+ */
+export const OBSERVATION_BUDGET_CODES = Object.freeze({
+    /** The CLI stopped waiting for a single HTTP response. */
+    response: "cuna.client.response_budget_elapsed",
+    /** The CLI stopped reading back before an accepted change became visible. */
+    convergence: "cuna.client.convergence_budget_elapsed",
+});
+const OBSERVATION_BUDGET_CODE_SET = new Set(Object.values(OBSERVATION_BUDGET_CODES));
+export function isObservationBudgetCode(code) {
+    return OBSERVATION_BUDGET_CODE_SET.has(code);
+}
+/**
+ * Mint the refusal that says "the CLI stopped observing", and nothing stronger.
+ *
+ * The exit code is `network` (5), whose published meaning is already "no
+ * authoritative answer arrived", which is exactly this. It is deliberately NOT
+ * `conflict` (6): `conflict` means current state contradicts the change and
+ * repeating it unchanged repeats the answer, and telling a script that about an
+ * operation which probably succeeded is worse than saying nothing.
+ */
+export function observationBudgetElapsed(input) {
+    const settle = input.settleWith === undefined
+        ? "Re-read the resource with a read-only `cuna` command before re-issuing this mutation."
+        : `Run \`${input.settleWith}\` to see the current state.`;
+    return new CunaError({
+        code: OBSERVATION_BUDGET_CODES[input.kind],
+        message: input.kind === "response"
+            ? `The CLI stopped waiting for Cuna to answer ${input.operation} after ${input.budgetMs} ms.`
+            : `Cuna accepted ${input.operation}; the CLI stopped reading back after ${input.budgetMs} ms, before the change became visible.`,
+        exitCode: EXIT_CODES.network,
+        hint: input.kind === "response"
+            ? `This is the CLI's own limit, not a Cuna failure, and the operation may have completed. ${settle} Raise --timeout-ms to wait longer.`
+            : `This is the CLI's own limit, not a Cuna failure, and the change may still be settling. ${settle}`,
+        // Written once, here, and not reachable as a parameter. A budget refusal
+        // that denied retry is the defect this module exists to make unspellable.
+        retryable: true,
+        details: Object.freeze({
+            ...input.details,
+            budget_ms: input.budgetMs,
+            ...(input.settleWith === undefined ? {} : { settle_with: input.settleWith }),
+            // Stated for machine readers in the same record as the sentence: the CLI
+            // observed nothing, which is not the same as observing that nothing
+            // happened.
+            remote_outcome: "unobserved",
+        }),
+        ...(input.cause === undefined ? {} : { cause: input.cause }),
+    });
+}
+//# sourceMappingURL=observation-budget.js.map

package/dist/core/observation-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-budget.js","sourceRoot":"","sources":["../../src/core/observation-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAyB,MAAM,aAAa,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAM,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,OAAO,CAAC;AAEhE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AAEpD,oDAAoD;AACpD,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AAEvD,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,EAAE,qCAAqC;IAC/C,6EAA6E;IAC7E,WAAW,EAAE,wCAAwC;CAC7C,CAAC,CAAC;AAIZ,MAAM,2BAA2B,GAAwB,IAAI,GAAG,CAC9D,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAC,CACxC,CAAC;AAEF,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAkBD;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAoC;IAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,KAAK,SAAS;QAC3C,CAAC,CAAC,uFAAuF;QACzF,CAAC,CAAC,SAAS,KAAK,CAAC,UAAU,8BAA8B,CAAC;IAC5D,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,wBAAwB,CAAC,KAAK,CAAC,IAAI,CAAC;QAC1C,OAAO,EAAE,KAAK,CAAC,IAAI,KAAK,UAAU;YAChC,CAAC,CAAC,8CAA8C,KAAK,CAAC,SAAS,UAAU,KAAK,CAAC,QAAQ,MAAM;YAC7F,CAAC,CAAC,iBAAiB,KAAK,CAAC,SAAS,wCAAwC,KAAK,CAAC,QAAQ,wCAAwC;QAClI,QAAQ,EAAE,UAAU,CAAC,OAAO;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,UAAU;YAC7B,CAAC,CAAC,0FAA0F,MAAM,qCAAqC;YACvI,CAAC,CAAC,0FAA0F,MAAM,EAAE;QACtG,yEAAyE;QACzE,0EAA0E;QAC1E,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC;YACrB,GAAG,KAAK,CAAC,OAAO;YAChB,SAAS,EAAE,KAAK,CAAC,QAAQ;YACzB,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;YAC5E,yEAAyE;YACzE,oEAAoE;YACpE,YAAY;YACZ,cAAc,EAAE,YAAY;SAC7B,CAAC;QACF,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;KAC7D,CAAC,CAAC;AACL,CAAC"}

package/dist/core/product-web.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The product's public web destinations, and the sentences that point at them.
+ *
+ * WHY THIS FILE EXISTS. Measured on the installed build: `cuna --help` contained
+ * ZERO matches for `https?://`, and the credential hint said "Set CUNA_API_KEY to
+ * a Cuna automation credential" without saying where a credential comes from.
+ * Both exits from the first-run wall were closed — `login` and `signup` fail on
+ * this platform, and the automation path named no source. A user who has never
+ * seen the console had nowhere to go.
+ *
+ * WHY IT IS ONE AUTHORITY AND NOT A STRING PER SITE. Four independent places
+ * already told the user about the automation credential:
+ *
+ *   - `api/http.ts`            "Replace CUNA_API_KEY with a valid automation credential."
+ *   - `auth/human-session.ts`  the `AUTOMATION_CREDENTIAL_HINT` constant
+ *   - `commands/commands.ts`   "Run `cuna login` … or set CUNA_API_KEY …"
+ *   - `cli/help.ts`            the Authentication block
+ *
+ * Four spellings of one fact, compared by nobody. That is the exact recurring
+ * defect this repository has closed four times in other namespaces: a value is
+ * minted in one place and repeated in another, one side is edited, and the two
+ * drift. Adding the URL to one of the four would have created a fifth variant
+ * rather than closing the hole, so the sentence itself moved here.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. No marketing apex, no docs URL, no social
+ * link. A CLI that prints product URLs everywhere is its own defect; each
+ * destination below exists because a specific, measured message dead-ends
+ * without it, and for no other reason.
+ */
+/** The console origin. Verified 2026-08-10: 200 after its sign-in redirect. */
+export declare const CONSOLE_ORIGIN: "https://app.getcuna.com";
+/**
+ * Where an automation credential is created.
+ *
+ * Verified 2026-08-10 from this machine: `GET https://app.getcuna.com/api-keys`
+ * answers `307` to `https://getcuna.com/login?next=…%2Fapi-keys` when
+ * unauthenticated, and `200 text/html` after following it. That is a real page
+ * behind sign-in, not a 404 — which is the only property a hint may promise.
+ */
+export declare const API_KEYS_URL: "https://app.getcuna.com/api-keys";
+/**
+ * Where "contact Cuna support" actually goes.
+ *
+ * Two shipped hints told the user to contact support and named no destination.
+ * This is the CLI's published `bugs.url`; `test/product-web.test.mjs` asserts it
+ * is byte-identical to `package.json`, so the two cannot drift.
+ */
+export declare const SUPPORT_URL: "https://github.com/Cuna-Labs/cuna-cli/issues";
+/**
+ * The one sentence that tells a user how to authenticate without a browser.
+ *
+ * The variable name is read from `brandedEnvironmentNames`, the same authority
+ * the resolver reads, so a change to the accepted set cannot leave this
+ * sentence naming a variable nothing reads. The URL is a literal because it is
+ * not derived from anything in this tree — it is a fact about a deployed site,
+ * and `test/product-web.test.mjs` pins it with a literal oracle.
+ */
+export declare function automationCredentialHint(): string;
+/**
+ * The one sentence for "the server answered, but not within its own contract".
+ *
+ * Deliberately not "retry". Nothing the caller can do locally changes the
+ * outcome — the deployed API is behind its published contract and the CLI is
+ * correct to refuse the body — so the honest remedy is to say that plainly and
+ * name a destination. Four mint sites emit this class
+ * (`api/client.ts`, `api/http.ts`, `auth/human-contracts.ts`,
+ * `commands/commands.ts`); they share this constant so they cannot drift into
+ * four different degrees of helpfulness, which is exactly what had happened to
+ * `details` before this change.
+ */
+export declare const OFF_CONTRACT_RESPONSE_HINT: string;
+/**
+ * The one sentence for a guard that can only fire on a CLI bug.
+ *
+ * Four `cuna.internal.*` guards and the four request-encoding guards are
+ * unreachable from any invocation: they assert the CLI's own construction of a
+ * request. Shipping them with no hint told the user their command was at fault.
+ * Naming the CLI as the defective party is the actionable content.
+ */
+export declare const INTERNAL_DEFECT_HINT: string;
+//# sourceMappingURL=product-web.d.ts.map

package/dist/core/product-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-web.d.ts","sourceRoot":"","sources":["../../src/core/product-web.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,cAAc,EAAG,yBAAkC,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,oCAAwC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAG,8CAAuD,CAAC;AAEnF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAGjD;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,QAEgD,CAAC;AAExF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAEgD,CAAC"}

package/dist/core/product-web.js

@@ -0,0 +1,87 @@
+import { brandedEnvironmentNames } from "./namespace.js";
+/**
+ * The product's public web destinations, and the sentences that point at them.
+ *
+ * WHY THIS FILE EXISTS. Measured on the installed build: `cuna --help` contained
+ * ZERO matches for `https?://`, and the credential hint said "Set CUNA_API_KEY to
+ * a Cuna automation credential" without saying where a credential comes from.
+ * Both exits from the first-run wall were closed — `login` and `signup` fail on
+ * this platform, and the automation path named no source. A user who has never
+ * seen the console had nowhere to go.
+ *
+ * WHY IT IS ONE AUTHORITY AND NOT A STRING PER SITE. Four independent places
+ * already told the user about the automation credential:
+ *
+ *   - `api/http.ts`            "Replace CUNA_API_KEY with a valid automation credential."
+ *   - `auth/human-session.ts`  the `AUTOMATION_CREDENTIAL_HINT` constant
+ *   - `commands/commands.ts`   "Run `cuna login` … or set CUNA_API_KEY …"
+ *   - `cli/help.ts`            the Authentication block
+ *
+ * Four spellings of one fact, compared by nobody. That is the exact recurring
+ * defect this repository has closed four times in other namespaces: a value is
+ * minted in one place and repeated in another, one side is edited, and the two
+ * drift. Adding the URL to one of the four would have created a fifth variant
+ * rather than closing the hole, so the sentence itself moved here.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. No marketing apex, no docs URL, no social
+ * link. A CLI that prints product URLs everywhere is its own defect; each
+ * destination below exists because a specific, measured message dead-ends
+ * without it, and for no other reason.
+ */
+/** The console origin. Verified 2026-08-10: 200 after its sign-in redirect. */
+export const CONSOLE_ORIGIN = "https://app.getcuna.com";
+/**
+ * Where an automation credential is created.
+ *
+ * Verified 2026-08-10 from this machine: `GET https://app.getcuna.com/api-keys`
+ * answers `307` to `https://getcuna.com/login?next=…%2Fapi-keys` when
+ * unauthenticated, and `200 text/html` after following it. That is a real page
+ * behind sign-in, not a 404 — which is the only property a hint may promise.
+ */
+export const API_KEYS_URL = `${CONSOLE_ORIGIN}/api-keys`;
+/**
+ * Where "contact Cuna support" actually goes.
+ *
+ * Two shipped hints told the user to contact support and named no destination.
+ * This is the CLI's published `bugs.url`; `test/product-web.test.mjs` asserts it
+ * is byte-identical to `package.json`, so the two cannot drift.
+ */
+export const SUPPORT_URL = "https://github.com/Cuna-Labs/cuna-cli/issues";
+/**
+ * The one sentence that tells a user how to authenticate without a browser.
+ *
+ * The variable name is read from `brandedEnvironmentNames`, the same authority
+ * the resolver reads, so a change to the accepted set cannot leave this
+ * sentence naming a variable nothing reads. The URL is a literal because it is
+ * not derived from anything in this tree — it is a fact about a deployed site,
+ * and `test/product-web.test.mjs` pins it with a literal oracle.
+ */
+export function automationCredentialHint() {
+    const primary = brandedEnvironmentNames("API_KEY")[0];
+    return `Create an automation credential at ${API_KEYS_URL}, then set ${primary} to it.`;
+}
+/**
+ * The one sentence for "the server answered, but not within its own contract".
+ *
+ * Deliberately not "retry". Nothing the caller can do locally changes the
+ * outcome — the deployed API is behind its published contract and the CLI is
+ * correct to refuse the body — so the honest remedy is to say that plainly and
+ * name a destination. Four mint sites emit this class
+ * (`api/client.ts`, `api/http.ts`, `auth/human-contracts.ts`,
+ * `commands/commands.ts`); they share this constant so they cannot drift into
+ * four different degrees of helpfulness, which is exactly what had happened to
+ * `details` before this change.
+ */
+export const OFF_CONTRACT_RESPONSE_HINT = "The deployed Cuna API is behind its published contract, so this cannot be fixed from the CLI. " +
+    `Run \`cuna version --json\` and report it with the details above at ${SUPPORT_URL}.`;
+/**
+ * The one sentence for a guard that can only fire on a CLI bug.
+ *
+ * Four `cuna.internal.*` guards and the four request-encoding guards are
+ * unreachable from any invocation: they assert the CLI's own construction of a
+ * request. Shipping them with no hint told the user their command was at fault.
+ * Naming the CLI as the defective party is the actionable content.
+ */
+export const INTERNAL_DEFECT_HINT = "This is a defect in the Cuna CLI, not in your invocation. " +
+    `Run \`cuna version --json\` and report it with that record at ${SUPPORT_URL}.`;
+//# sourceMappingURL=product-web.js.map

package/dist/core/product-web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-web.js","sourceRoot":"","sources":["../../src/core/product-web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,yBAAkC,CAAC;AAEjE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,cAAc,WAAoB,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,8CAAuD,CAAC;AAEnF;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB;IACtC,MAAM,OAAO,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,sCAAsC,YAAY,cAAc,OAAO,SAAS,CAAC;AAC1F,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACrC,gGAAgG;IAChG,uEAAuE,WAAW,GAAG,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,4DAA4D;IAC5D,iEAAiE,WAAW,GAAG,CAAC"}