@usenaive-sdk/cli 0.12.2 → 0.13.0

package/dist/lib/pricing.js

@@ -0,0 +1,148 @@
+/**
+ * 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 const FIXED_CREDIT_COSTS = {
+    emailSend: 0.016,
+    webSearch: 0.2,
+    urlRead: 0.05,
+    researchQuick: 0.5,
+    researchThorough: 1,
+    researchExhaustive: 1.6,
+    brainQuery: 0.08,
+    brainIngestBase: 0.1,
+    brainIngestPerKb: 0.0002,
+    brainIngestMaxCredits: 10,
+    socialPost: 2.5,
+    socialXPost: 0.5,
+    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 const DATA_API_CREDIT_COSTS = {
+    seoKeywordsAdsLive: 2,
+    seoKeywordsAdsStandard: 1.5,
+    seoKeywordsTrendsLive: 0.25,
+    seoKeywordsTrendsStandard: 0.2,
+    seoBacklinksStandard: 1.8,
+    seoBacklinksBulk: 17,
+    seoLabsStandard: 0.75,
+    seoLabsBulk: 5.4,
+    seoLabsHistorical: 10,
+    aeoLlmResponsesLive: 1.2,
+    aeoLlmResponsesStandard: 1.2,
+    aeoLlmScraperLive: 0.16,
+    aeoLlmScraperStandard: 0.08,
+    appDataAppSearches: 0.85,
+    appDataAppList: 0.85,
+    appDataAppInfo: 0.05,
+    appDataAppReviews: 6,
+    businessGoogleInfoLive: 0.13,
+    businessGoogleInfoStandard: 0.09,
+    businessGoogleUpdatesStandard: 3,
+    businessGoogleReviewsStandard: 1.5,
+    businessGoogleQaLive: 0.3,
+    businessGoogleQaStandard: 0.18,
+    businessGoogleHotelLive: 0.1,
+    businessGoogleHotelStandard: 0.07,
+    businessTrustpilotSearchStandard: 0.34,
+    businessTrustpilotReviewsStandard: 0.85,
+    businessTripadvisorSearchStandard: 0.85,
+    businessTripadvisorReviewsStandard: 1.25,
+    businessSocialLive: 0.1,
+    ecommerceGoogleProducts: 0.15,
+    ecommerceGoogleProductInfo: 0.14,
+    ecommerceGoogleSellers: 0.24,
+    ecommerceGoogleReviews: 2.2,
+    ecommerceAmazonProducts: 0.14,
+    ecommerceAmazonAsin: 0.04,
+    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 const METERED_DATA_API_CREDITS = {
+    llmMentionsBase: 2.4,
+    llmMentionsPerRow: 0.024,
+    llmMentionsMaxRows: 1000,
+    llmMentionsDefaultRows: 100,
+    appListingsBase: 2.4,
+    appListingsPerItem: 0.024,
+    aiKeywordsBase: 0.4,
+    aiKeywordsPerKeyword: 0.004,
+};
+/** `2.4 + 0.024 × rows`, the LLM Mentions price the API charges for `rows` rows. */
+export function llmMentionsCredits(rows) {
+    const capped = Math.min(Math.max(rows, 1), METERED_DATA_API_CREDITS.llmMentionsMaxRows);
+    return Math.ceil((METERED_DATA_API_CREDITS.llmMentionsBase + METERED_DATA_API_CREDITS.llmMentionsPerRow * capped) * 100) / 100;
+}
+/** `2.4 + 0.024 × limit`, the live app-listings price for a given `--limit`. */
+export function appListingsCredits(limit) {
+    return Math.ceil((METERED_DATA_API_CREDITS.appListingsBase + METERED_DATA_API_CREDITS.appListingsPerItem * Math.max(limit, 1)) * 100) / 100;
+}
+export function reportedCreditsUsed(data, fallback) {
+    const value = data?.credits_used;
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+/**
+ * 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 const CREDIT_PACKS = [
+    { id: "small", credits: 200, priceInCents: 1000 },
+    { id: "medium", credits: 500, priceInCents: 2300, badge: "Popular" },
+    { id: "large", credits: 1000, priceInCents: 4400, badge: "Best Value" },
+    { id: "xl", credits: 2500, priceInCents: 10000 },
+];
+/** `$23` — whole dollars, matching how the API renders `getCreditPacks().price`. */
+export function packPrice(pack) {
+    return `$${(pack.priceInCents / 100).toFixed(0)}`;
+}
+/** `medium (500 credits, $23)` — the inline form for an option description. */
+export function packInline(pack) {
+    return `${pack.id} (${pack.credits} credits, ${packPrice(pack)})`;
+}
+/** One column-aligned row of the pack table in `naive billing --help`. */
+export function packRow(pack) {
+    const credits = `${pack.credits} credits`.padEnd(15);
+    const price = pack.badge ? `${packPrice(pack).padEnd(6)}(${pack.badge})` : packPrice(pack);
+    return `  ${pack.id.padEnd(10)}${credits}${price}`;
+}
+/**
+ * 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 const REFRAME_FEE_CREDITS = 4;
+//# sourceMappingURL=pricing.js.map

package/dist/lib/pricing.js.map

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

package/dist/lib/stream-frames.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `naive teams watch` — the pure half (06 §1.6).
+ *
+ * Everything here is a function of its input, so the framing, the resume
+ * position, the redaction and the termination rule are tests rather than
+ * behaviour you have to run a server to observe.
+ *
+ * THE OUTPUT IS NDJSON, ONE OBJECT PER LINE — not a JSON array. A stream has no
+ * closing bracket, so an array can only be completed by a client that already
+ * knows the stream ended, which is the one thing a consumer of a live stream
+ * does not know.
+ *
+ * TERMINATION IS `{"type":"stream.end"}` WITH A REASON, NEVER `[DONE]`. That
+ * token belongs to the OpenAI-compatible lane; reusing it here would make one
+ * word mean two protocols.
+ */
+/**
+ * Secrets that must never reach a transcript.
+ *
+ * `nv_sk_…` is the platform api key — the same shape `output.ts` already guards
+ * in `next_steps`. `vt_<company>_<hex>` is the per-team runtime credential, which
+ * `output.ts` has never seen because nothing else prints one. A transcript prints
+ * TOOL ARGUMENTS, so it is the one surface where either can arrive inside an
+ * arbitrary payload rather than in a field with a known name.
+ */
+export declare const SECRET_PATTERNS: readonly RegExp[];
+/**
+ * Redact a decoded frame in place-free fashion.
+ *
+ * `showArgs` is false by default and the frame's `args` are replaced by whatever
+ * `args_digest` the server sent. That is the honest default: a digest still lets
+ * a reader correlate two frames, and it cannot leak a value nobody audited.
+ * `commands/teams.ts` additionally refuses `--show-args` outside an interactive
+ * terminal, so a pipe or a CI job cannot turn it on.
+ */
+export declare function redactFrame(frame: unknown, opts: {
+    showArgs: boolean;
+}): unknown;
+export interface SseEvent {
+    /** The `id:` field, which is what a resume sends back as `Last-Event-ID`. */
+    readonly id?: string;
+    /** The concatenated `data:` lines. */
+    readonly data: string;
+}
+/**
+ * Split a buffer into complete SSE events, returning the unconsumed tail.
+ *
+ * The tail matters: a chunk boundary lands mid-event far more often than test
+ * fixtures suggest, and a parser that discards a partial event drops exactly the
+ * frames that arrive under load.
+ */
+export declare function parseSse(buffer: string): {
+    events: SseEvent[];
+    rest: string;
+};
+/** The terminal states that are NOT success. `unverified` is the reason exit 3
+ *  exists at all: a CI script reading exit 0 as "the work is done" would count an
+ *  unattested task as a pass. */
+export declare const NON_SUCCESS_TERMINAL: readonly ["unverified", "failed", "blocked"];
+export type StreamEndReason = "run_terminal" | "client_closed" | "timeout" | "fence_closed";
+/**
+ * The exit code for a finished stream. `--fail-on-terminal` is opt-in because
+ * changing the exit code of an existing command is a wire break; without it a
+ * watch always exits 0 and the caller reads `status` itself.
+ */
+export declare function watchExitCode(finalStatus: string | undefined, failOnTerminal: boolean): 0 | 3;
+/**
+ * One board card, in the three fields this gate is allowed to read.
+ *
+ * Deliberately structural and deliberately narrow: `extractCards` hands over
+ * whatever the wire said, and a gate that reads more of a card than it needs is
+ * a gate that breaks when an unrelated field is renamed.
+ */
+export type GateCard = {
+    status?: string;
+    /** `durableCard`: naive adjudicated and the verdict never reached the runtime. */
+    verdict_delivery_failed?: unknown;
+    /** `durableCard`: naive granted a terminal the runtime does not hold. */
+    boards_disagree?: unknown;
+};
+/**
+ * Is this card's verification state anything other than SETTLED AND AGREED?
+ *
+ * 🔴 A CARD THE TWO BOARDS DISAGREE ABOUT IS NOT A VERIFIED CARD, and this gate
+ * used to say it was. It read one field -- `status === "unverified"` -- and the
+ * durable lane has two more that mean the verification did not conclude:
+ *
+ *   - `verdict_delivery_failed`. naive REJECTED the card and the verdict did not
+ *     reach the runtime, so the runtime still holds its own terminal. The board
+ *     row carries the failure and says, in its own `meaning` field, that "the two
+ *     boards disagree about it".
+ *   - `boards_disagree`. naive granted a terminal the runtime does not hold, with
+ *     no delivery to fail -- an accept is written on naive's own row and is never
+ *     delivered, so this is the ONLY signal that case has. Its own text calls it
+ *     "the disagreement that bills for work the runtime says did not finish".
+ *
+ * Measured on staging: card A carried `verdict_delivery_failed` and
+ * `naive teams tasks … --fail-on-unverified` exited 0 on it. A CI job reading
+ * that exit code as "attested" is the exact failure this flag exists to prevent,
+ * and the file's own history records it happening once already through a
+ * different field (see `extractCards`).
+ *
+ * PRESENCE, not shape. Both fields are objects the server composes and neither is
+ * ever emitted as a negative -- `durableCard` omits them entirely for a card with
+ * nothing to report -- so asking whether one is there is the whole test, and it
+ * cannot go stale when their contents change.
+ */
+export declare function cardIsUnverified(card: GateCard): boolean;
+/** The same rule for a single board card, used by `tasks`/`task --fail-on-unverified`. */
+export declare function unverifiedExitCode(cards: readonly GateCard[], failOnUnverified: boolean): 0 | 3;
+/** The highest `seq` printed so far — the position a reconnect resumes from.
+ *  `sequence >` is strict on the server, so nothing is lost and nothing is
+ *  duplicated. */
+export declare function highestSeq(current: number | undefined, frame: unknown): number | undefined;

package/dist/lib/stream-frames.js

@@ -0,0 +1,169 @@
+/**
+ * `naive teams watch` — the pure half (06 §1.6).
+ *
+ * Everything here is a function of its input, so the framing, the resume
+ * position, the redaction and the termination rule are tests rather than
+ * behaviour you have to run a server to observe.
+ *
+ * THE OUTPUT IS NDJSON, ONE OBJECT PER LINE — not a JSON array. A stream has no
+ * closing bracket, so an array can only be completed by a client that already
+ * knows the stream ended, which is the one thing a consumer of a live stream
+ * does not know.
+ *
+ * TERMINATION IS `{"type":"stream.end"}` WITH A REASON, NEVER `[DONE]`. That
+ * token belongs to the OpenAI-compatible lane; reusing it here would make one
+ * word mean two protocols.
+ */
+/**
+ * Secrets that must never reach a transcript.
+ *
+ * `nv_sk_…` is the platform api key — the same shape `output.ts` already guards
+ * in `next_steps`. `vt_<company>_<hex>` is the per-team runtime credential, which
+ * `output.ts` has never seen because nothing else prints one. A transcript prints
+ * TOOL ARGUMENTS, so it is the one surface where either can arrive inside an
+ * arbitrary payload rather than in a field with a known name.
+ */
+export const SECRET_PATTERNS = [
+    /nv_sk_[A-Za-z0-9_-]+/g,
+    /vt_[A-Za-z0-9-]+_[A-Fa-f0-9]{8,}/g,
+];
+/** Field names whose VALUE is a secret whatever it looks like. */
+const SECRET_FIELDS = new Set(["api_key", "session_token", "token", "credential", "secret"]);
+const REDACTED = "[redacted]";
+function scrubString(s) {
+    let out = s;
+    for (const re of SECRET_PATTERNS)
+        out = out.replace(new RegExp(re.source, re.flags), REDACTED);
+    return out;
+}
+/**
+ * Redact a decoded frame in place-free fashion.
+ *
+ * `showArgs` is false by default and the frame's `args` are replaced by whatever
+ * `args_digest` the server sent. That is the honest default: a digest still lets
+ * a reader correlate two frames, and it cannot leak a value nobody audited.
+ * `commands/teams.ts` additionally refuses `--show-args` outside an interactive
+ * terminal, so a pipe or a CI job cannot turn it on.
+ */
+export function redactFrame(frame, opts) {
+    const seen = new WeakSet();
+    const walk = (v, key) => {
+        if (typeof v === "string") {
+            if (key !== undefined && SECRET_FIELDS.has(key))
+                return REDACTED;
+            return scrubString(v);
+        }
+        if (Array.isArray(v))
+            return v.map((e) => walk(e));
+        if (typeof v === "object" && v !== null) {
+            if (seen.has(v))
+                return "[circular]";
+            seen.add(v);
+            const out = {};
+            for (const [k, val] of Object.entries(v)) {
+                if (k === "args" && !opts.showArgs) {
+                    out.args = REDACTED;
+                    continue;
+                }
+                out[k] = walk(val, k);
+            }
+            return out;
+        }
+        return v;
+    };
+    return walk(frame);
+}
+/**
+ * Split a buffer into complete SSE events, returning the unconsumed tail.
+ *
+ * The tail matters: a chunk boundary lands mid-event far more often than test
+ * fixtures suggest, and a parser that discards a partial event drops exactly the
+ * frames that arrive under load.
+ */
+export function parseSse(buffer) {
+    const events = [];
+    // An event ends at a blank line. \r\n is legal per the spec and some proxies
+    // rewrite line endings, so both are accepted.
+    const parts = buffer.split(/\r?\n\r?\n/);
+    const rest = parts.pop() ?? "";
+    for (const block of parts) {
+        let id;
+        const data = [];
+        for (const line of block.split(/\r?\n/)) {
+            if (line.startsWith(":"))
+                continue; // a comment / keep-alive
+            const colon = line.indexOf(":");
+            const field = colon === -1 ? line : line.slice(0, colon);
+            const value = colon === -1 ? "" : line.slice(colon + 1).replace(/^ /, "");
+            if (field === "data")
+                data.push(value);
+            else if (field === "id")
+                id = value;
+        }
+        if (data.length > 0)
+            events.push({ ...(id !== undefined && { id }), data: data.join("\n") });
+    }
+    return { events, rest };
+}
+/** The terminal states that are NOT success. `unverified` is the reason exit 3
+ *  exists at all: a CI script reading exit 0 as "the work is done" would count an
+ *  unattested task as a pass. */
+export const NON_SUCCESS_TERMINAL = ["unverified", "failed", "blocked"];
+/**
+ * The exit code for a finished stream. `--fail-on-terminal` is opt-in because
+ * changing the exit code of an existing command is a wire break; without it a
+ * watch always exits 0 and the caller reads `status` itself.
+ */
+export function watchExitCode(finalStatus, failOnTerminal) {
+    if (!failOnTerminal || finalStatus === undefined)
+        return 0;
+    return NON_SUCCESS_TERMINAL.includes(finalStatus) ? 3 : 0;
+}
+/**
+ * Is this card's verification state anything other than SETTLED AND AGREED?
+ *
+ * 🔴 A CARD THE TWO BOARDS DISAGREE ABOUT IS NOT A VERIFIED CARD, and this gate
+ * used to say it was. It read one field -- `status === "unverified"` -- and the
+ * durable lane has two more that mean the verification did not conclude:
+ *
+ *   - `verdict_delivery_failed`. naive REJECTED the card and the verdict did not
+ *     reach the runtime, so the runtime still holds its own terminal. The board
+ *     row carries the failure and says, in its own `meaning` field, that "the two
+ *     boards disagree about it".
+ *   - `boards_disagree`. naive granted a terminal the runtime does not hold, with
+ *     no delivery to fail -- an accept is written on naive's own row and is never
+ *     delivered, so this is the ONLY signal that case has. Its own text calls it
+ *     "the disagreement that bills for work the runtime says did not finish".
+ *
+ * Measured on staging: card A carried `verdict_delivery_failed` and
+ * `naive teams tasks … --fail-on-unverified` exited 0 on it. A CI job reading
+ * that exit code as "attested" is the exact failure this flag exists to prevent,
+ * and the file's own history records it happening once already through a
+ * different field (see `extractCards`).
+ *
+ * PRESENCE, not shape. Both fields are objects the server composes and neither is
+ * ever emitted as a negative -- `durableCard` omits them entirely for a card with
+ * nothing to report -- so asking whether one is there is the whole test, and it
+ * cannot go stale when their contents change.
+ */
+export function cardIsUnverified(card) {
+    return (card.status === "unverified" ||
+        card.verdict_delivery_failed != null ||
+        card.boards_disagree != null);
+}
+/** The same rule for a single board card, used by `tasks`/`task --fail-on-unverified`. */
+export function unverifiedExitCode(cards, failOnUnverified) {
+    if (!failOnUnverified)
+        return 0;
+    return cards.some(cardIsUnverified) ? 3 : 0;
+}
+/** The highest `seq` printed so far — the position a reconnect resumes from.
+ *  `sequence >` is strict on the server, so nothing is lost and nothing is
+ *  duplicated. */
+export function highestSeq(current, frame) {
+    const seq = frame?.seq;
+    if (typeof seq !== "number" || !Number.isFinite(seq))
+        return current;
+    return current === undefined || seq > current ? seq : current;
+}
+//# sourceMappingURL=stream-frames.js.map

package/dist/lib/stream-frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-frames.js","sourceRoot":"","sources":["../../src/lib/stream-frames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAsB;IAChD,uBAAuB;IACvB,mCAAmC;CACpC,CAAC;AAEF,kEAAkE;AAClE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7F,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B,SAAS,WAAW,CAAC,CAAS;IAC5B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,EAAE,IAAI,eAAe;QAAE,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC/F,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAA2B;IACrE,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,CAAU,EAAE,GAAY,EAAW,EAAE;QACjD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1B,IAAI,GAAG,KAAK,SAAS,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,QAAQ,CAAC;YACjE,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO,YAAY,CAAC;YACrC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,MAAM,GAAG,GAA4B,EAAE,CAAC;YACxC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;gBACpE,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACnC,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;oBACpB,SAAS;gBACX,CAAC;gBACD,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACxB,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;AACrB,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,6EAA6E;IAC7E,8CAA8C;IAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,EAAsB,CAAC;QAC3B,MAAM,IAAI,GAAa,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS,CAAC,yBAAyB;YAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACzD,MAAM,KAAK,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1E,IAAI,KAAK,KAAK,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;iBAClC,IAAI,KAAK,KAAK,IAAI;gBAAE,EAAE,GAAG,KAAK,CAAC;QACtC,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;iCAEiC;AACjC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,YAAY,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAIjF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,WAA+B,EAAE,cAAuB;IACpF,IAAI,CAAC,cAAc,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC3D,OAAQ,oBAA0C,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO,CACL,IAAI,CAAC,MAAM,KAAK,YAAY;QAC5B,IAAI,CAAC,uBAAuB,IAAI,IAAI;QACpC,IAAI,CAAC,eAAe,IAAI,IAAI,CAC7B,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,KAA0B,EAAE,gBAAyB;IACtF,IAAI,CAAC,gBAAgB;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;kBAEkB;AAClB,MAAM,UAAU,UAAU,CAAC,OAA2B,EAAE,KAAc;IACpE,MAAM,GAAG,GAAI,KAAkC,EAAE,GAAG,CAAC;IACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACrE,OAAO,OAAO,KAAK,SAAS,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AAChE,CAAC"}

package/dist/lib/teams-catalog.d.ts

@@ -0,0 +1,141 @@
+/**
+ * THE ONE DECLARATION SITE for the `naive teams` surface (06 §1.4).
+ *
+ * Two design notes shipped two `teams` command sets and neither was a superset of
+ * the other. Two hand-written lists is exactly the drift a one-declaration rule
+ * exists to catch, so both are deleted and the union is declared once, here, as
+ * DATA. `commands/teams.ts` builds the commander tree by walking this array; it
+ * writes no subcommand of its own. A row added here is a working command, and a
+ * command that is not a row here does not exist.
+ *
+ * ── WHY THIS IS A .ts FILE IN THIS PACKAGE AND NOT A GENERATED ARTIFACT ─────
+ *
+ * 06 §1.4 puts the declaration in `@usenaive/agent-contract/capabilities` and has
+ * a generator emit `packages/cli/src/generated/teams-commands.ts` from it, so the
+ * CLI subcommand, the MCP tool, the REST path and the openapi operation are all
+ * one statement. MEASURED: there is no `packages/agent-contract` directory in
+ * this tree and no generator to run, and this task owns `packages/cli` only. A
+ * hand-written file that IMITATES a generated one — committed under `generated/`,
+ * with nothing that regenerates it — is worse than an honest source file: the
+ * next person edits it and their edit is silently the truth.
+ *
+ * So this is the honest intermediate: ONE declaration, inside the package that
+ * consumes it, shaped so a future generator emits exactly this array. The fields
+ * a generator would need and the CLI does not (`action`, `rest`, `mcp`,
+ * `because`, `fenced`, `write`) are carried anyway, so the day the contract
+ * package exists this file is deleted rather than reconciled.
+ *
+ * ── WHY IT MUST BE ONE LIST AND NOT 28 `.command()` CALLS ───────────────────
+ *
+ * `src/index.ts` calls `findUnknownSubcommand` BEFORE `parseAsync` and hard-fails
+ * on an unrecognised subcommand even with `--help` appended. A subcommand list
+ * that can drift from the thing that answers it therefore makes VALID commands
+ * fail with `cli_outdated`, rather than degrading. One array, walked once, cannot
+ * drift from itself.
+ */
+/** Where a flag's value goes on the wire. `client` never leaves the process. */
+export type FlagIn = "query" | "body" | "path" | "client";
+export interface FlagSpec {
+    /** Commander syntax, verbatim: `--status <status>` or `--follow`. */
+    readonly flag: string;
+    /** The key commander puts on the options object. */
+    readonly key: string;
+    readonly describe: string;
+    readonly in: FlagIn;
+    /** Wire field name. Defaults to `key`. */
+    readonly field?: string;
+    /** `requiredOption` rather than `option` — see `--because` below. */
+    readonly required?: boolean;
+    /** Parse the value as an integer before sending it. */
+    readonly int?: boolean;
+    /**
+     * A boolean flag that SELECTS a value for a shared wire field instead of
+     * sending its own name as a field.
+     *
+     * `--allow` is not a field this API has. The field is `decision` and `--allow`
+     * is one of its two values (`POST …/approvals/:id/decide` throws
+     * `invalid_input: decision must be "approve" or "deny"` on anything else). The
+     * first spelling of this catalog declared `--allow` and `--deny` as ordinary
+     * body flags, so the CLI sent `{"allow":true,"because":"…"}` and the one
+     * mounted write on the whole `/v1/teams` surface could not be invoked at all.
+     *
+     * A flag declaring `value` MUST also declare `field`; flags sharing a `field`
+     * form a mutually exclusive group, and `selectorGroups()` derives that group
+     * rather than listing it, so a third value cannot be added without joining the
+     * exclusion.
+     */
+    readonly value?: string;
+}
+export interface ArgSpec {
+    /** Commander syntax, verbatim: `<team>` or `[channel]`. */
+    readonly arg: string;
+    /** The bare name, for path substitution and body keys. */
+    readonly name: string;
+    readonly describe: string;
+    readonly in: "path" | "body";
+    /** Wire field name. Defaults to `name`. */
+    readonly field?: string;
+}
+export interface TeamOp {
+    /** The subcommand name under `naive teams`. */
+    readonly cli: string;
+    readonly describe: string;
+    /** The governance ActionId this op is evaluated as. */
+    readonly action: string;
+    readonly method: "GET" | "POST" | "DELETE";
+    /** `{name}` placeholders are filled from `{team}`, `{tenant}` and path args. */
+    readonly path: string;
+    /** Does this op need `--tenant`? True for all 28 except `list` (R-4). */
+    readonly tenant: boolean;
+    /** Does it pass through the write fence? Printed in `--help`, not enforced here. */
+    readonly fenced: boolean;
+    readonly write: boolean;
+    /** The MCP tool name, or `false` with a mandatory `because`. */
+    readonly mcp: string | false;
+    readonly because?: string;
+    readonly args: readonly ArgSpec[];
+    readonly flags: readonly FlagSpec[];
+    /** Reads a stream rather than a JSON body. Exactly one op does. */
+    readonly streams?: true;
+}
+export declare const TEAM_OPS: readonly TeamOp[];
+export declare class TeamOpError extends Error {
+}
+/** Every `{placeholder}` this op's path expects. */
+export declare function pathPlaceholders(op: TeamOp): string[];
+/**
+ * Fill the path. Every value is `encodeURIComponent`'d — a team name or a card id
+ * that contains a slash must not be able to reach a different route, and an
+ * absent value is an error rather than the literal string "undefined" in a URL.
+ */
+export declare function buildPath(op: TeamOp, values: Readonly<Record<string, string | undefined>>): string;
+/** The query string, including its leading `?`, or `""`. */
+export declare function buildQuery(op: TeamOp, opts: Readonly<Record<string, unknown>>): string;
+/**
+ * The request body: positional args declared `in: "body"`, then flags declared
+ * `in: "body"`. A GET has no body at all — a GET that carries one is a request
+ * some proxy will strip and some server will ignore, which is a silent wrong
+ * answer rather than an error.
+ */
+export declare function buildBody(op: TeamOp, args: Readonly<Record<string, unknown>>, opts: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
+/**
+ * The mutually exclusive selector groups on this op, keyed by the wire field
+ * they share. DERIVED from the flags rather than listed, so a third member added
+ * to a group joins the exclusion without anyone remembering to widen a list.
+ */
+export declare function selectorGroups(op: TeamOp): Map<string, FlagSpec[]>;
+/**
+ * Refuse an ambiguous or absent decision BEFORE the request leaves the process.
+ *
+ * A selector group is a CHOICE: exactly one member must be given. Neither branch
+ * can be left to the server. `--allow --deny` would otherwise resolve by flag
+ * order in this file — an approval decided by declaration order — and giving
+ * neither would send a body with no `decision`, which `settle` (whose openapi
+ * marks nothing required) would accept as a well-formed request that settles an
+ * effect no particular way.
+ */
+export declare function assertSelectors(op: TeamOp, opts: Readonly<Record<string, unknown>>): void;
+/** `failOnTerminal` -> `fail_on_terminal`. Flags are camelCase in commander and
+ *  snake_case on this API's wire; converting in one place keeps the two apart. */
+export declare function snake(key: string): string;
+export declare function findOp(cli: string): TeamOp | undefined;