@usenaive-sdk/cli 0.12.2 → 0.13.0

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;

package/dist/lib/deprecation.js

@@ -0,0 +1,140 @@
+import { agentError, setPendingDeprecation } from "../output.js";
+/**
+ * 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 const LEGACY_RUNTIME_ALIASES = [
+    "orchestration",
+    "warm pool",
+    "instance pool",
+    "Hermes",
+    "sidecar",
+    "container runtime",
+    "hosted runtime",
+    "runtime.pool",
+];
+const MIGRATION_GUIDE = "https://usenaive.ai/docs/migration-guides/legacy-orchestration-to-durable-teams";
+/** Build the full record from the commander command plus its spec. */
+export function deprecationRecord(cmd, spec) {
+    return { ...spec, subject: `naive ${cmd.name()}` };
+}
+/** The machine half — what rides the stdout envelope. */
+export function deprecationNotice(rec, status) {
+    return {
+        id: rec.id,
+        subject: rec.subject,
+        status,
+        replacement: rec.replacement,
+        since: rec.since,
+        sunset: rec.sunset.kind === "frozen" ? "frozen" : { on: rec.sunset.date },
+        guide: rec.guide,
+    };
+}
+function sunsetLine(rec) {
+    return rec.sunset.kind === "frozen"
+        ? "frozen, no sunset date"
+        : `sunset ${rec.sunset.date}`;
+}
+function replacementLines(rec) {
+    if (rec.replacement.kind === "use") {
+        return [`  Use instead:  ${rec.replacement.what}`];
+    }
+    // The honest row. There is no replacement, and the reason is mandatory.
+    return [
+        "  Use instead:  nothing — this capability has no replacement.",
+        `  Because:      ${rec.replacement.because}`,
+    ];
+}
+/**
+ * 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 function renderDeprecationBanner(rec) {
+    const lines = [];
+    lines.push(`⚠ \`${rec.subject}\` is DEPRECATED and will keep working.        [${rec.id}]`);
+    lines.push(`  It drives ${rec.drives}`);
+    if (rec.alsoCalled.length > 0) {
+        lines.push(`  (also called: ${rec.alsoCalled.join(", ")})`);
+    }
+    lines.push(...replacementLines(rec));
+    lines.push(`  Why:          ${rec.why}`);
+    for (const gap of rec.gaps ?? []) {
+        lines.push(`  No replacement for \`${rec.subject} ${gap.sub}\`: ${gap.because}`);
+    }
+    lines.push(`  Since ${rec.since} · ${sunsetLine(rec)} · migration guide:`);
+    lines.push(`  ${rec.guide}`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Emitted ids, so the banner appears ONCE per process even when a group's hook
+ * and a future subcommand's hook both fire. Exported for tests only.
+ */
+const _emitted = new Set();
+export function _resetDeprecationBannersForTest() {
+    _emitted.clear();
+}
+/**
+ * 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 function markDeprecated(cmd, spec) {
+    const rec = deprecationRecord(cmd, spec);
+    cmd.hook("preAction", () => {
+        setPendingDeprecation(deprecationNotice(rec, "deprecated"));
+        if (!_emitted.has(rec.id)) {
+            _emitted.add(rec.id);
+            process.stderr.write(renderDeprecationBanner(rec));
+        }
+        // and then nothing. The action runs.
+    });
+    return rec;
+}
+/**
+ * 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 const CLI_LOCAL_ERROR_CODES = [
+    "cli_outdated",
+    "unknown_subcommand",
+    "upstream_error",
+    "deprecated_command",
+];
+export function retiredCommand(opts) {
+    if (opts.notice)
+        setPendingDeprecation(opts.notice);
+    // A retired command's notice cannot ride a success envelope — there isn't one —
+    // so in machine mode the id travels on the error object instead.
+    agentError({
+        action: opts.action,
+        error: {
+            code: "deprecated_command",
+            message: opts.message,
+            ...(opts.notice && { deprecation: opts.notice }),
+        },
+        recovery_steps: opts.recovery_steps,
+    });
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/lib/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","sourceRoot":"","sources":["../../src/lib/deprecation.ts"],"names":[],"mappings":"AAwCA,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAyC,MAAM,cAAc,CAAC;AA6DxG;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,eAAe;IACf,WAAW;IACX,eAAe;IACf,QAAQ;IACR,SAAS;IACT,mBAAmB;IACnB,gBAAgB;IAChB,cAAc;CACN,CAAC;AAEX,MAAM,eAAe,GACnB,iFAAiF,CAAC;AAEpF,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,IAAqB;IACnE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,SAAS,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC;AACrD,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,iBAAiB,CAAC,GAAsB,EAAE,MAAgC;IACxF,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM;QACN,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;QACzE,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,GAAsB;IACxC,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ;QACjC,CAAC,CAAC,wBAAwB;QAC1B,CAAC,CAAC,UAAU,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAsB;IAC9C,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACnC,OAAO,CAAC,mBAAmB,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,wEAAwE;IACxE,OAAO;QACL,+DAA+D;QAC/D,mBAAmB,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE;KAC7C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAsB;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,mDAAmD,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3F,KAAK,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,0BAA0B,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,GAAG,OAAO,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,MAAM,UAAU,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;AACnC,MAAM,UAAU,+BAA+B;IAC7C,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,IAAqB;IAChE,MAAM,GAAG,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;QACzB,qBAAqB,CAAC,iBAAiB,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,qCAAqC;IACvC,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,cAAc;IACd,oBAAoB;IACpB,gBAAgB;IAChB,oBAAoB;CACZ,CAAC;AAEX,MAAM,UAAU,cAAc,CAAC,IAK9B;IACC,IAAI,IAAI,CAAC,MAAM;QAAE,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,gFAAgF;IAChF,iEAAiE;IACjE,UAAU,CAAC;QACT,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE;YACL,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;SACjD;QACD,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/duration.d.ts

@@ -0,0 +1,8 @@
+export type DurationParse = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseDurationArg(raw: string): DurationParse;

package/dist/lib/duration.js

@@ -0,0 +1,11 @@
+export function parseDurationArg(raw) {
+    const n = Number(raw);
+    if (raw.trim() === "" || !Number.isFinite(n) || n <= 0) {
+        return {
+            ok: false,
+            message: `--duration must be a positive number of seconds (e.g. 5 or 10); got "${raw}"`,
+        };
+    }
+    return { ok: true, value: n };
+}
+//# sourceMappingURL=duration.js.map

package/dist/lib/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.js","sourceRoot":"","sources":["../../src/lib/duration.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACtB,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,wEAAwE,GAAG,GAAG;SACxF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAChC,CAAC"}

package/dist/lib/http-response.d.ts

@@ -0,0 +1,11 @@
+export interface ParsedHttpResponse {
+    status: number;
+    data: unknown;
+}
+/**
+ * Parse an API response without assuming every proxy/error page is JSON.
+ * Empty successful responses remain valid; every other non-JSON response is
+ * converted to the same structured error shape the CLI already understands.
+ */
+export declare function parseHttpResponse(response: Response): Promise<ParsedHttpResponse>;
+export declare function networkErrorResponse(error: unknown): ParsedHttpResponse;

package/dist/lib/http-response.js

@@ -0,0 +1,96 @@
+const MAX_RESPONSE_PREVIEW = 240;
+function redactSecrets(value) {
+    return value
+        .replace(/\b((?:nv|dr)_sk_)[A-Za-z0-9._-]+/gi, "$1[redacted]")
+        .replace(/\b(Bearer\s+)[A-Za-z0-9._~-]+/gi, "$1[redacted]");
+}
+function safePreview(value) {
+    const preview = redactSecrets(value)
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, MAX_RESPONSE_PREVIEW);
+    return preview || undefined;
+}
+function codeForStatus(status) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "resource_not_found";
+    if (status === 429)
+        return "rate_limited";
+    if (status >= 500)
+        return "internal_error";
+    return "invalid_input";
+}
+/**
+ * Parse an API response without assuming every proxy/error page is JSON.
+ * Empty successful responses remain valid; every other non-JSON response is
+ * converted to the same structured error shape the CLI already understands.
+ */
+export async function parseHttpResponse(response) {
+    const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim() || undefined;
+    const text = await response.text();
+    const jsonText = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (!text.trim()) {
+        if (response.ok || response.status === 204)
+            return { status: response.status, data: {} };
+        return {
+            status: response.status,
+            data: {
+                error: {
+                    code: codeForStatus(response.status),
+                    message: `Naive API returned an empty error response (HTTP ${response.status}).`,
+                    hint: "Retry once; if this persists, the API route or upstream proxy may be unavailable.",
+                    upstream_status: response.status,
+                    ...(contentType && { content_type: contentType }),
+                },
+            },
+        };
+    }
+    const looksJson = /(?:^|[+/])json$/i.test(contentType ?? "") || /^[\[{]/.test(jsonText.trim());
+    if (looksJson) {
+        try {
+            return { status: response.status, data: JSON.parse(jsonText) };
+        }
+        catch {
+            // Fall through to the structured invalid-response envelope below.
+        }
+    }
+    const normalizedStatus = response.ok ? 502 : response.status;
+    const preview = safePreview(text);
+    return {
+        status: normalizedStatus,
+        data: {
+            error: {
+                code: codeForStatus(normalizedStatus),
+                message: `Naive API returned ${contentType ?? "a non-JSON response"} instead of JSON (HTTP ${response.status}).`,
+                hint: response.status === 404
+                    ? "The requested API route may not be deployed yet. Check the target environment and retry."
+                    : "Retry once; if this persists, check API or upstream-provider health.",
+                upstream_status: response.status,
+                ...(contentType && { content_type: contentType }),
+                ...(preview && { response_preview: preview }),
+            },
+        },
+    };
+}
+export function networkErrorResponse(error) {
+    return {
+        status: 503,
+        data: {
+            error: {
+                code: "network_error",
+                message: "Could not reach the Naive API.",
+                hint: "Check your connection and NAIVE_BASE_URL, then retry.",
+                cause: error instanceof Error ? error.message : String(error),
+            },
+        },
+    };
+}
+//# sourceMappingURL=http-response.js.map

package/dist/lib/http-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-response.js","sourceRoot":"","sources":["../../src/lib/http-response.ts"],"names":[],"mappings":"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"}

package/dist/lib/pricing.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Fixed public prices mirrored from the API meters, so CLI copy cannot silently
+ * drift from billing. Keep dynamic model costs out of this table.
+ *
+ * The source of truth is `FIXED_CREDIT_COSTS` in platform/billing/src/pricing.ts
+ * and `pricing-parity.test.ts` holds the two equal. This header used to name
+ * packages/api/src/lib/pricing.ts — a path the #497 restructure deleted — and
+ * to promise a "dogfood contract test" that no file in the repo implemented.
+ */
+export declare const FIXED_CREDIT_COSTS: {
+    readonly emailSend: 0.016;
+    readonly webSearch: 0.2;
+    readonly urlRead: 0.05;
+    readonly researchQuick: 0.5;
+    readonly researchThorough: 1;
+    readonly researchExhaustive: 1.6;
+    readonly brainQuery: 0.08;
+    readonly brainIngestBase: 0.1;
+    readonly brainIngestPerKb: 0.0002;
+    readonly brainIngestMaxCredits: 10;
+    readonly socialPost: 2.5;
+    readonly socialXPost: 0.5;
+    readonly socialXPostWithLink: 5;
+};
+/**
+ * The DataForSEO-backed data primitives (seo / aeo / app-data / business /
+ * ecommerce), mirrored from `DATA_API_CREDIT_COSTS` in
+ * platform/billing/src/pricing.ts, which is where the reasoning, the vendor list
+ * price behind each number and the market anchor live. Held equal to it by
+ * packages/api/src/__tests__/credit-price-parity.test.ts.
+ *
+ * These are LIST prices. A charge is additionally floored at 1.2× what the call
+ * cost us upstream, so a row-heavy response can settle above the figure quoted
+ * here — which is why every CLI hint renders the response's own `credits_used`
+ * and only the `--help` epilogues quote this table.
+ */
+export declare const DATA_API_CREDIT_COSTS: {
+    readonly seoKeywordsAdsLive: 2;
+    readonly seoKeywordsAdsStandard: 1.5;
+    readonly seoKeywordsTrendsLive: 0.25;
+    readonly seoKeywordsTrendsStandard: 0.2;
+    readonly seoBacklinksStandard: 1.8;
+    readonly seoBacklinksBulk: 17;
+    readonly seoLabsStandard: 0.75;
+    readonly seoLabsBulk: 5.4;
+    readonly seoLabsHistorical: 10;
+    readonly aeoLlmResponsesLive: 1.2;
+    readonly aeoLlmResponsesStandard: 1.2;
+    readonly aeoLlmScraperLive: 0.16;
+    readonly aeoLlmScraperStandard: 0.08;
+    readonly appDataAppSearches: 0.85;
+    readonly appDataAppList: 0.85;
+    readonly appDataAppInfo: 0.05;
+    readonly appDataAppReviews: 6;
+    readonly businessGoogleInfoLive: 0.13;
+    readonly businessGoogleInfoStandard: 0.09;
+    readonly businessGoogleUpdatesStandard: 3;
+    readonly businessGoogleReviewsStandard: 1.5;
+    readonly businessGoogleQaLive: 0.3;
+    readonly businessGoogleQaStandard: 0.18;
+    readonly businessGoogleHotelLive: 0.1;
+    readonly businessGoogleHotelStandard: 0.07;
+    readonly businessTrustpilotSearchStandard: 0.34;
+    readonly businessTrustpilotReviewsStandard: 0.85;
+    readonly businessTripadvisorSearchStandard: 0.85;
+    readonly businessTripadvisorReviewsStandard: 1.25;
+    readonly businessSocialLive: 0.1;
+    readonly ecommerceGoogleProducts: 0.15;
+    readonly ecommerceGoogleProductInfo: 0.14;
+    readonly ecommerceGoogleSellers: 0.24;
+    readonly ecommerceGoogleReviews: 2.2;
+    readonly ecommerceAmazonProducts: 0.14;
+    readonly ecommerceAmazonAsin: 0.04;
+    readonly ecommerceAmazonSellers: 0.14;
+};
+/**
+ * The two row-metered families, whose price is a base plus a per-row rate rather
+ * than a flat figure. Mirrored from the same module; `appListingsCredits` /
+ * `aeoLlmMentionsCredits` there are the functions that bill.
+ */
+export declare const METERED_DATA_API_CREDITS: {
+    readonly llmMentionsBase: 2.4;
+    readonly llmMentionsPerRow: 0.024;
+    readonly llmMentionsMaxRows: 1000;
+    readonly llmMentionsDefaultRows: 100;
+    readonly appListingsBase: 2.4;
+    readonly appListingsPerItem: 0.024;
+    readonly aiKeywordsBase: 0.4;
+    readonly aiKeywordsPerKeyword: 0.004;
+};
+/** `2.4 + 0.024 × rows`, the LLM Mentions price the API charges for `rows` rows. */
+export declare function llmMentionsCredits(rows: number): number;
+/** `2.4 + 0.024 × limit`, the live app-listings price for a given `--limit`. */
+export declare function appListingsCredits(limit: number): number;
+export declare function reportedCreditsUsed(data: unknown, fallback: number): number;
+export interface CreditPack {
+    id: string;
+    credits: number;
+    priceInCents: number;
+    badge?: string;
+}
+/**
+ * The one-time credit packs, mirrored field-for-field from `CREDIT_PACKS` in
+ * platform/billing/src/billing.ts — the table `createTopupCheckout` bills
+ * Stripe from. The CLI ships to npm with five runtime dependencies and cannot
+ * import the billing package, so this is a mirror; `pricing-parity.test.ts`
+ * imports both and fails on any divergence.
+ *
+ * 🔴 EVERY pack figure the CLI prints must come from here. The `--help`
+ * epilogue and the `--pack` option description used to carry two independent
+ * hand-typed copies, and one of them drifted to a tenth of the real price.
+ */
+export declare const CREDIT_PACKS: readonly CreditPack[];
+/** `$23` — whole dollars, matching how the API renders `getCreditPacks().price`. */
+export declare function packPrice(pack: CreditPack): string;
+/** `medium (500 credits, $23)` — the inline form for an option description. */
+export declare function packInline(pack: CreditPack): string;
+/** One column-aligned row of the pack table in `naive billing --help`. */
+export declare function packRow(pack: CreditPack): string;
+/**
+ * The flat 9:16 vertical-reframe / face-tracking fee, in credits, mirrored from
+ * `usdToBillableCredits(REFRAME_FEE_USD_PER_JOB)` in
+ * platform/billing/src/pricing.ts — the value clipCost() adds to a reframed
+ * job's subtotal. Charged once per job, not per clip.
+ *
+ * The CLI used to advertise this as "typically $0.05–$0.30 per job", which is
+ * the band clip-job-cost-audit.md records the CLI advertising while the code
+ * charged nothing at all. It is now a flat fee, billed in credits like every
+ * other driver, and this constant is held equal to the meter by
+ * packages/api/src/__tests__/credit-price-parity.test.ts.
+ */
+export declare const REFRAME_FEE_CREDITS = 4;