predictable-ai 0.1.0

package/dist/generated/csv-safety.js

@@ -0,0 +1,181 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Source of truth: dashboard/src/lib/exa-agent/csv-safety.ts
+ * Regenerate:      npm run generate:agent-surface   (from dashboard/)
+ * Guard:           npm run guard:agent-surface      (CI re-derives and diffs)
+ *
+ * §5.1a requires ONE serializer for every CSV egress. The CLI is a separate
+ * npm package that publishes only dist/, so it cannot import across the
+ * repo; it gets a generated mirror instead, on the same terms as
+ * commands.json. Edit the source above, never this file.
+ */
+/**
+ * THE CANONICAL CSV SAFETY LIB — one hazard probe, one serializer (spec §5.1
+ * step 3 and §5.1a; ticket ga-mfacl.8 / T7, ACs 2 and 2b).
+ *
+ * ONE IMPLEMENTATION. Everything that emits CSV out of this product imports
+ * from here: this epic's routes, T8's egress re-cuts (the live exporter, the
+ * unresolved-suppression export, the campaign-bundle writers) and the CLI's
+ * bundle assembly. Nothing re-implements it. The spec's reason is measured
+ * history, not tidiness — three separate censuses of "who writes CSV" each
+ * missed a writer, and the mayor's own pass found a FOURTH local quoting helper
+ * (`dashboard/src/lib/suppression/import-preview.ts:77`) after the gate had
+ * finished counting. T8 replaces census with construction: a static audit that
+ * fails any non-test file emitting CSV without importing this module.
+ *
+ * ── DETECT AT INGEST, NEUTRALIZE AT EGRESS ─────────────────────────────────
+ *
+ * The r1 F1 ruling reversed an earlier design that neutralized on the way IN.
+ * Two things killed it. It corrupted legitimate data (the stored cell stopped
+ * being what the client uploaded), and it was bypassable: promotion `btrim`s
+ * the staged title before the global write
+ * (`20260820000017_exa_agent_email_claim_and_dispatch.sql:894`), so any
+ * ingest-time FIRST-CHARACTER rule dies to one leading space. Hence:
+ *
+ *   - ingest stores the cell BYTE-IDENTICAL and records `formula_hazard` as
+ *     metadata beside it (T7-AC2);
+ *   - that stored flag is INFORMATIONAL ONLY — the review report, counts, a UI
+ *     cue. It is never an enforcement input, because a stored flag goes stale
+ *     the moment anything transforms the value (r1 F3 ruling);
+ *   - enforcement is always a FRESH probe of the FINAL value at the boundary,
+ *     which is what `serializeCsvRows` does and what T8's provider-payload
+ *     refusal will do.
+ *
+ * ── THE PROBE TABLE LIVES IN JSON, NOT IN THIS FILE ────────────────────────
+ *
+ * `csv-hazard.fixture.json` is the one address for the case table. vitest
+ * drives this implementation from it; T8's Python mirror inside
+ * `exabase/scripts/crm_push.py` drives the Python implementation from the SAME
+ * file. Two runtimes, one table. A second copy of the table would be a
+ * duplicated live fact and the two probes would diverge on the first case
+ * anyone added.
+ */
+/**
+ * The four characters a spreadsheet treats as "this cell is a formula".
+ * `@` is the Lotus-compatible lead-in Excel still honours; `-` and `+` are the
+ * signed-number lead-ins that also start an expression.
+ */
+const TRIGGERS = new Set(['=', '+', '-', '@']);
+/**
+ * The characters stripped off the FRONT before the trigger test, as one maximal
+ * run over the UNION of the classes — not one class at a time.
+ *
+ * Each class is here because it is invisible to (or skipped by) a spreadsheet
+ * while hiding a trigger behind it, and each was measured rather than assumed
+ * (see the probe-class table in `csv-safety.test.ts`):
+ *
+ *   \p{White_Space}  every Unicode space, plus U+0085 which `\s` misses.
+ *   \p{Cc}           C0 (U+0000-U+001F), DEL and C1 (U+007F-U+009F).
+ *   \p{Cf}           format characters: BOM U+FEFF, the zero-width family
+ *                    U+200B-U+200D, the bidi marks and overrides
+ *                    U+200E/U+200F/U+202A-U+202E and the isolates
+ *                    U+2066-U+2069, soft hyphen U+00AD.
+ *   ' " ‘ ’ “ ”      apostrophes and quotes. AN UPLOADED APOSTROPHE IS DATA,
+ *                    NOT OUR NEUTRALIZATION: honouring it would let whoever
+ *                    wrote the cell decide whether their own cell gets defanged.
+ *                    The serializer always adds its own.
+ *
+ * STRIPPING MORE CAN ONLY FLAG MORE. No character in this class is a trigger,
+ * so widening it never turns a hazard into a pass — the failure direction is
+ * false positives, which the spec accepts by name (see `serializeCsvRows`).
+ */
+const LEADING_RUN = /^[\p{White_Space}\p{Cc}\p{Cf}'"‘’“”]+/u;
+/** C0/DEL/C1 — the second clause of the rule tests the ORIGINAL against this. */
+const CONTROL = /\p{Cc}/u;
+/**
+ * Is this value a CSV formula hazard?
+ *
+ * THE RULE, verbatim from spec §5.1 step 3: NFKC-fold full-width ＝＋－＠;
+ * strip the maximal leading run above; hazard iff the next code point is one of
+ * the four triggers, OR the ORIGINAL begins with a C0/C1 control.
+ *
+ * NFKC IS INSPECTION ONLY. It folds ＝ (U+FF1D) to `=`, ＋ to `+`, － to `-`
+ * and ＠ to `@` — measured, not assumed — so a full-width payload cannot walk
+ * past a test written against ASCII. The folded string is never stored,
+ * exported or returned; callers keep their own value.
+ *
+ * WHY THE CONTROL CLAUSE TESTS THE ORIGINAL. It is a claim about the bytes the
+ * client actually uploaded. Folding first would let a future Unicode revision
+ * that maps some code point onto a control decide it, and "the value starts
+ * with a control character" is a fact about the input, not about a normal form
+ * of it.
+ */
+export function isFormulaHazard(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    // Clause 2 first: it reads the ORIGINAL, so no folding may have happened yet.
+    const first = String.fromCodePoint(value.codePointAt(0));
+    if (CONTROL.test(first))
+        return true;
+    const rest = value.normalize('NFKC').replace(LEADING_RUN, '');
+    if (rest.length === 0)
+        return false;
+    return TRIGGERS.has(String.fromCodePoint(rest.codePointAt(0)));
+}
+/**
+ * Coerce any value a caller holds into the string that will be written.
+ *
+ * ONE COERCION, DEFINED ONCE. Every adopter needs it, and an adopter-local
+ * version is how two exports come to disagree about what `null` looks like.
+ * The rules match the live exporter's `escapeCsv`
+ * (`api/export/[icpId]/route.ts:10-17`) exactly, so T8's swap changes what a
+ * hazardous cell looks like and nothing else.
+ */
+export function toCsvValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * Serialize ONE cell: always quoted, embedded quotes doubled, a
+ * serializer-owned apostrophe inside the quotes when the FINAL value is
+ * hazardous.
+ *
+ * ALWAYS QUOTED, not "quoted when it contains a delimiter". A conditional
+ * quote is a second decision that can disagree with the first, and RFC 4180
+ * permits quoting every field. It also means a cell can never grow a delimiter
+ * meaning through a later edit.
+ *
+ * THE APOSTROPHE GOES INSIDE THE QUOTES AND IS NOT DOUBLED. It is the
+ * serializer's own character, not part of the value: `'` then the escaped
+ * value, all inside one pair of quotes. A reader that strips it gets the
+ * original back.
+ */
+export function serializeCsvCell(value) {
+    const str = toCsvValue(value);
+    const prefix = isFormulaHazard(str) ? "'" : '';
+    return `"${prefix}${str.replace(/"/g, '""')}"`;
+}
+/**
+ * Serialize a whole document: comma delimiter, CRLF records, every cell through
+ * `serializeCsvCell`.
+ *
+ * HEADERS SERIALIZE AS DATA. There is no header parameter. A header row is
+ * `rows[0]`, quoted and probed exactly like any other row — a header is a cell
+ * an attacker can often choose (a merge-var name, a column label), and a
+ * serializer with a privileged header path is a serializer with an unprobed
+ * one.
+ *
+ * TRAILING CRLF ON EVERY RECORD, including the last. RFC 4180 allows either;
+ * emitting it unconditionally means there is no last-row branch to get wrong.
+ *
+ * THE ACCEPTED COST, stated where it is paid: benign leading `-`/`+` data
+ * (phone numbers, "-5 Main St") gains an apostrophe in the export. That is the
+ * OWASP-documented integrity cost of CSV hazard handling, ruled acceptable in
+ * §5.1 step 3, and it costs nothing in the database — the stored value stays
+ * byte-identical either way.
+ *
+ * THE HONESTY BOUNDARY, also from the spec: neutralization is best-effort
+ * across spreadsheet consumers. LibreOffice import options can still evaluate.
+ * If "cannot execute anywhere" ever becomes a hard requirement, the answer is
+ * XLSX with explicit string cells, which v2 excludes by ruling.
+ */
+export function serializeCsvRows(rows) {
+    return rows.map((row) => row.map(serializeCsvCell).join(',') + '\r\n').join('');
+}
+//# sourceMappingURL=csv-safety.js.map

package/dist/generated/csv-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-safety.js","sourceRoot":"","sources":["../../src/generated/csv-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;GAIG;AACH,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,GAAG,wCAAwC,CAAA;AAE5D,iFAAiF;AACjF,MAAM,OAAO,GAAG,SAAS,CAAA;AAEzB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEjE,8EAA8E;IAC9E,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAW,CAAC,CAAA;IAClE,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEpC,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACnC,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAW,CAAC,CAAC,CAAA;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACpD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3D,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAC7B,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;IAC9C,OAAO,IAAI,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAA;AAChD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAqC;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACjF,CAAC"}

package/dist/generated/csv-safety.ts

@@ -0,0 +1,184 @@
+/**
+ * GENERATED FILE — DO NOT EDIT.
+ *
+ * Source of truth: dashboard/src/lib/exa-agent/csv-safety.ts
+ * Regenerate:      npm run generate:agent-surface   (from dashboard/)
+ * Guard:           npm run guard:agent-surface      (CI re-derives and diffs)
+ *
+ * §5.1a requires ONE serializer for every CSV egress. The CLI is a separate
+ * npm package that publishes only dist/, so it cannot import across the
+ * repo; it gets a generated mirror instead, on the same terms as
+ * commands.json. Edit the source above, never this file.
+ */
+
+/**
+ * THE CANONICAL CSV SAFETY LIB — one hazard probe, one serializer (spec §5.1
+ * step 3 and §5.1a; ticket ga-mfacl.8 / T7, ACs 2 and 2b).
+ *
+ * ONE IMPLEMENTATION. Everything that emits CSV out of this product imports
+ * from here: this epic's routes, T8's egress re-cuts (the live exporter, the
+ * unresolved-suppression export, the campaign-bundle writers) and the CLI's
+ * bundle assembly. Nothing re-implements it. The spec's reason is measured
+ * history, not tidiness — three separate censuses of "who writes CSV" each
+ * missed a writer, and the mayor's own pass found a FOURTH local quoting helper
+ * (`dashboard/src/lib/suppression/import-preview.ts:77`) after the gate had
+ * finished counting. T8 replaces census with construction: a static audit that
+ * fails any non-test file emitting CSV without importing this module.
+ *
+ * ── DETECT AT INGEST, NEUTRALIZE AT EGRESS ─────────────────────────────────
+ *
+ * The r1 F1 ruling reversed an earlier design that neutralized on the way IN.
+ * Two things killed it. It corrupted legitimate data (the stored cell stopped
+ * being what the client uploaded), and it was bypassable: promotion `btrim`s
+ * the staged title before the global write
+ * (`20260820000017_exa_agent_email_claim_and_dispatch.sql:894`), so any
+ * ingest-time FIRST-CHARACTER rule dies to one leading space. Hence:
+ *
+ *   - ingest stores the cell BYTE-IDENTICAL and records `formula_hazard` as
+ *     metadata beside it (T7-AC2);
+ *   - that stored flag is INFORMATIONAL ONLY — the review report, counts, a UI
+ *     cue. It is never an enforcement input, because a stored flag goes stale
+ *     the moment anything transforms the value (r1 F3 ruling);
+ *   - enforcement is always a FRESH probe of the FINAL value at the boundary,
+ *     which is what `serializeCsvRows` does and what T8's provider-payload
+ *     refusal will do.
+ *
+ * ── THE PROBE TABLE LIVES IN JSON, NOT IN THIS FILE ────────────────────────
+ *
+ * `csv-hazard.fixture.json` is the one address for the case table. vitest
+ * drives this implementation from it; T8's Python mirror inside
+ * `exabase/scripts/crm_push.py` drives the Python implementation from the SAME
+ * file. Two runtimes, one table. A second copy of the table would be a
+ * duplicated live fact and the two probes would diverge on the first case
+ * anyone added.
+ */
+
+/**
+ * The four characters a spreadsheet treats as "this cell is a formula".
+ * `@` is the Lotus-compatible lead-in Excel still honours; `-` and `+` are the
+ * signed-number lead-ins that also start an expression.
+ */
+const TRIGGERS = new Set(['=', '+', '-', '@'])
+
+/**
+ * The characters stripped off the FRONT before the trigger test, as one maximal
+ * run over the UNION of the classes — not one class at a time.
+ *
+ * Each class is here because it is invisible to (or skipped by) a spreadsheet
+ * while hiding a trigger behind it, and each was measured rather than assumed
+ * (see the probe-class table in `csv-safety.test.ts`):
+ *
+ *   \p{White_Space}  every Unicode space, plus U+0085 which `\s` misses.
+ *   \p{Cc}           C0 (U+0000-U+001F), DEL and C1 (U+007F-U+009F).
+ *   \p{Cf}           format characters: BOM U+FEFF, the zero-width family
+ *                    U+200B-U+200D, the bidi marks and overrides
+ *                    U+200E/U+200F/U+202A-U+202E and the isolates
+ *                    U+2066-U+2069, soft hyphen U+00AD.
+ *   ' " ‘ ’ “ ”      apostrophes and quotes. AN UPLOADED APOSTROPHE IS DATA,
+ *                    NOT OUR NEUTRALIZATION: honouring it would let whoever
+ *                    wrote the cell decide whether their own cell gets defanged.
+ *                    The serializer always adds its own.
+ *
+ * STRIPPING MORE CAN ONLY FLAG MORE. No character in this class is a trigger,
+ * so widening it never turns a hazard into a pass — the failure direction is
+ * false positives, which the spec accepts by name (see `serializeCsvRows`).
+ */
+const LEADING_RUN = /^[\p{White_Space}\p{Cc}\p{Cf}'"‘’“”]+/u
+
+/** C0/DEL/C1 — the second clause of the rule tests the ORIGINAL against this. */
+const CONTROL = /\p{Cc}/u
+
+/**
+ * Is this value a CSV formula hazard?
+ *
+ * THE RULE, verbatim from spec §5.1 step 3: NFKC-fold full-width ＝＋－＠;
+ * strip the maximal leading run above; hazard iff the next code point is one of
+ * the four triggers, OR the ORIGINAL begins with a C0/C1 control.
+ *
+ * NFKC IS INSPECTION ONLY. It folds ＝ (U+FF1D) to `=`, ＋ to `+`, － to `-`
+ * and ＠ to `@` — measured, not assumed — so a full-width payload cannot walk
+ * past a test written against ASCII. The folded string is never stored,
+ * exported or returned; callers keep their own value.
+ *
+ * WHY THE CONTROL CLAUSE TESTS THE ORIGINAL. It is a claim about the bytes the
+ * client actually uploaded. Folding first would let a future Unicode revision
+ * that maps some code point onto a control decide it, and "the value starts
+ * with a control character" is a fact about the input, not about a normal form
+ * of it.
+ */
+export function isFormulaHazard(value: string): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+
+  // Clause 2 first: it reads the ORIGINAL, so no folding may have happened yet.
+  const first = String.fromCodePoint(value.codePointAt(0) as number)
+  if (CONTROL.test(first)) return true
+
+  const rest = value.normalize('NFKC').replace(LEADING_RUN, '')
+  if (rest.length === 0) return false
+  return TRIGGERS.has(String.fromCodePoint(rest.codePointAt(0) as number))
+}
+
+/**
+ * Coerce any value a caller holds into the string that will be written.
+ *
+ * ONE COERCION, DEFINED ONCE. Every adopter needs it, and an adopter-local
+ * version is how two exports come to disagree about what `null` looks like.
+ * The rules match the live exporter's `escapeCsv`
+ * (`api/export/[icpId]/route.ts:10-17`) exactly, so T8's swap changes what a
+ * hazardous cell looks like and nothing else.
+ */
+export function toCsvValue(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'string') return value
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+/**
+ * Serialize ONE cell: always quoted, embedded quotes doubled, a
+ * serializer-owned apostrophe inside the quotes when the FINAL value is
+ * hazardous.
+ *
+ * ALWAYS QUOTED, not "quoted when it contains a delimiter". A conditional
+ * quote is a second decision that can disagree with the first, and RFC 4180
+ * permits quoting every field. It also means a cell can never grow a delimiter
+ * meaning through a later edit.
+ *
+ * THE APOSTROPHE GOES INSIDE THE QUOTES AND IS NOT DOUBLED. It is the
+ * serializer's own character, not part of the value: `'` then the escaped
+ * value, all inside one pair of quotes. A reader that strips it gets the
+ * original back.
+ */
+export function serializeCsvCell(value: unknown): string {
+  const str = toCsvValue(value)
+  const prefix = isFormulaHazard(str) ? "'" : ''
+  return `"${prefix}${str.replace(/"/g, '""')}"`
+}
+
+/**
+ * Serialize a whole document: comma delimiter, CRLF records, every cell through
+ * `serializeCsvCell`.
+ *
+ * HEADERS SERIALIZE AS DATA. There is no header parameter. A header row is
+ * `rows[0]`, quoted and probed exactly like any other row — a header is a cell
+ * an attacker can often choose (a merge-var name, a column label), and a
+ * serializer with a privileged header path is a serializer with an unprobed
+ * one.
+ *
+ * TRAILING CRLF ON EVERY RECORD, including the last. RFC 4180 allows either;
+ * emitting it unconditionally means there is no last-row branch to get wrong.
+ *
+ * THE ACCEPTED COST, stated where it is paid: benign leading `-`/`+` data
+ * (phone numbers, "-5 Main St") gains an apostrophe in the export. That is the
+ * OWASP-documented integrity cost of CSV hazard handling, ruled acceptable in
+ * §5.1 step 3, and it costs nothing in the database — the stored value stays
+ * byte-identical either way.
+ *
+ * THE HONESTY BOUNDARY, also from the spec: neutralization is best-effort
+ * across spreadsheet consumers. LibreOffice import options can still evaluate.
+ * If "cannot execute anywhere" ever becomes a hard requirement, the answer is
+ * XLSX with explicit string cells, which v2 excludes by ruling.
+ */
+export function serializeCsvRows(rows: readonly (readonly unknown[])[]): string {
+  return rows.map((row) => row.map(serializeCsvCell).join(',') + '\r\n').join('')
+}

package/dist/help.js

@@ -0,0 +1,133 @@
+import { BASE_URL_ENV_VAR, DEFAULT_BASE_URL, TOKEN_ENV_VAR, CONFIG_DIR_NAME, CONFIG_FILE_NAME } from './config.js';
+/**
+ * Help text.
+ *
+ * NO EXAMPLE HERE EVER PUTS A TOKEN ON A COMMAND LINE (ticket AC5). The
+ * authentication note names the environment variable and the config file and
+ * stops there; `test/hygiene.test.ts` renders every command's help and asserts
+ * it. Writing `--token` into a single example would ship the habit to every
+ * user who copies it.
+ */
+const AUTH_NOTE = [
+    'Authentication:',
+    `  Set ${TOKEN_ENV_VAR} in your environment, or put {"token": "<your token>"} in`,
+    `  ~/${CONFIG_DIR_NAME}/${CONFIG_FILE_NAME} with mode 600. The token is never read from the`,
+    '  command line — anything you type is visible in your shell history and in ps.',
+].join('\n');
+const BASE_URL_NOTE = [
+    'Deployment:',
+    `  ${DEFAULT_BASE_URL} by default; set ${BASE_URL_ENV_VAR} to talk to a preview.`,
+].join('\n');
+const EXIT_NOTE = [
+    'Exit codes:',
+    '  0 ok · 1 usage or a rejected request · 2 credential refused · 3 rate limited',
+    '  4 server error or a verb this deployment does not serve yet · 5 quote required',
+].join('\n');
+/**
+ * Soft-wrap a paragraph to `width`, so a long line of coaching does not run off
+ * an 80-column terminal. Word boundaries only; a single word longer than the
+ * width is left whole rather than cut.
+ */
+function wrapAt(text, width) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line === '')
+            line = word;
+        else if (line.length + 1 + word.length <= width)
+            line += ` ${word}`;
+        else {
+            out.push(line);
+            line = word;
+        }
+    }
+    if (line !== '')
+        out.push(line);
+    return out.join('\n');
+}
+function flagLine(name, placeholder, describe) {
+    const left = placeholder ? `--${name} ${placeholder}` : `--${name}`;
+    return `  ${left.padEnd(24)}${describe}`;
+}
+export function renderCommandHelp(spec) {
+    const lines = [];
+    lines.push(`predictable ${spec.name} — ${spec.summary}`);
+    lines.push('');
+    lines.push(`Usage: predictable ${spec.name}${spec.params.length > 0 ? ' [flags]' : ''}`);
+    if (spec.params.length > 0) {
+        lines.push('');
+        lines.push('Flags:');
+        for (const param of spec.params) {
+            const suffix = param.required ? ' (required)' : '';
+            lines.push(flagLine(param.name, param.boolean ? '' : param.placeholder, `${param.describe}${suffix}`));
+        }
+    }
+    const actions = [...new Set(spec.routes.filter((r) => r.action).map((r) => r.action))];
+    if (actions.length > 1) {
+        lines.push(flagLine('action', `<${actions.join('|')}>`, `Which call to make. Default: ${spec.defaultAction}.`));
+    }
+    // THE COACHING GOES ABOVE THE FLAGS, not below the routes (T15 §15.1, AC2).
+    // A reader who has typed `--help` because they are about to run the verb sees
+    // it before the mechanics, which is the only position where guidance about
+    // WHAT to ask for can still change what they type.
+    //
+    // The text is the MANIFEST's — `buildRegistry` copies it off the artifact and
+    // nothing here writes one. `cli/test/guide.test.ts` plants a divergence and
+    // requires it to go red.
+    if (spec.guidance) {
+        lines.push('');
+        lines.push(wrapAt(spec.guidance, 76));
+    }
+    lines.push('');
+    lines.push('Common flags:');
+    lines.push(flagLine('json', '', "Print the server's response body verbatim."));
+    lines.push(flagLine('help', '', 'Show this message.'));
+    if (spec.mode === 'paid') {
+        lines.push('');
+        lines.push('This verb spends credits, and it is two steps:');
+        lines.push(`  1. predictable ${spec.name} --preview [flags]     prints a quote id, its credits and its expiry`);
+        lines.push(`  2. predictable ${spec.name} --quote <id> [flags]  spends against that quote`);
+        lines.push('  Without --quote, step 2 refuses locally and sends nothing.');
+    }
+    if (spec.routes.length > 0) {
+        lines.push('');
+        lines.push('Routes:');
+        for (const route of spec.routes)
+            lines.push(`  ${route.method} ${route.path}`);
+    }
+    lines.push('');
+    lines.push(AUTH_NOTE);
+    lines.push('');
+    lines.push(BASE_URL_NOTE);
+    return lines.join('\n');
+}
+export function renderRootHelp(specs, version, surfaceVersion) {
+    const lines = [];
+    lines.push(`predictable ${version} — the Predictable agent surface, on the command line.`);
+    lines.push(`Agent surface ${surfaceVersion}.`);
+    lines.push('');
+    lines.push('Usage: predictable <command> [flags]');
+    lines.push('       predictable <command> --help');
+    lines.push('');
+    const packs = [...new Set(specs.map((s) => s.pack))];
+    for (const pack of packs) {
+        lines.push(`${pack} commands:`);
+        for (const spec of specs.filter((s) => s.pack === pack)) {
+            const paid = spec.mode === 'paid' ? ' [spends credits]' : '';
+            lines.push(`  ${spec.name.padEnd(22)}${spec.summary}${paid}`);
+        }
+        lines.push('');
+    }
+    lines.push('Global:');
+    lines.push(flagLine('version', '', 'Print this client and the deployment surface version.'));
+    lines.push(flagLine('json', '', "Print the server's response body verbatim."));
+    lines.push(flagLine('help', '', 'Show this message.'));
+    lines.push('');
+    lines.push(AUTH_NOTE);
+    lines.push('');
+    lines.push(BASE_URL_NOTE);
+    lines.push('');
+    lines.push(EXIT_NOTE);
+    return lines.join('\n');
+}
+//# sourceMappingURL=help.js.map

package/dist/help.js.map

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

package/dist/http.js

@@ -0,0 +1,146 @@
+import { CliError, EXIT } from './errors.js';
+/**
+ * Join the deployment's base URL and a route path.
+ *
+ * The base URL may carry a PATH of its own — a preview served under a prefix,
+ * or a proxy that mounts the API somewhere other than the root. `new URL(path,
+ * base)` with an absolute `/api/...` path discards that prefix silently and
+ * sends the request to the wrong place, so the prefix is joined explicitly.
+ */
+export function buildUrl(baseUrl, path, query) {
+    const base = new URL(baseUrl);
+    const prefix = base.pathname.replace(/\/+$/, '');
+    // Rebuilt from the base URL itself, not from its origin: an origin drops any
+    // userinfo the base carried, and dropping half a URL is the failure this is
+    // fixing, not a smaller version of it. Assigning `pathname` leaves the
+    // caller's percent-escapes alone.
+    const url = new URL(base.toString());
+    // ga-paal4 item 2: SPLIT THE PATH FROM ITS QUERY FIRST. Assigning `pathname`
+    // says "all of this is a path", so a `?` inside `path` is percent-encoded to
+    // %3F and the request goes to a literal segment ending `...%3Ftarget=5` while
+    // the server sees no query at all — a silently dropped parameter on a client
+    // whose whole job is calling parameterized routes.
+    //
+    // Split on the FIRST unescaped `?` only. An already-escaped %3F is pathname
+    // data the caller asked for and stays escaped; everything after the first `?`
+    // is the query, including any later `?` characters, which is what a URL parser
+    // does. Assigning `pathname` still leaves the caller's other percent-escapes
+    // alone.
+    const split = path.indexOf('?');
+    const pathPart = split === -1 ? path : path.slice(0, split);
+    const embeddedQuery = split === -1 ? '' : path.slice(split + 1);
+    url.pathname = `${prefix}/${pathPart.replace(/^\/+/, '')}`;
+    url.search = '';
+    url.hash = '';
+    // The embedded query goes on FIRST so an explicit `query` entry overrides it:
+    // the caller passing a parameter by name is the more specific statement, and
+    // leaving the precedence to whichever assignment happened to run second is how
+    // two sources for one parameter become a coin flip.
+    for (const [key, value] of new URLSearchParams(embeddedQuery)) {
+        if (value !== '')
+            url.searchParams.set(key, value);
+    }
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined && value !== '')
+            url.searchParams.set(key, value);
+    }
+    return url.toString();
+}
+function serverErrorCode(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.error === 'string')
+            return parsed.error;
+        if (typeof parsed.reason === 'string')
+            return parsed.reason;
+    }
+    catch {
+        /* a non-JSON body has no code to name */
+    }
+    return undefined;
+}
+/** Send one request. Transport failures become a server-class CliError. */
+export async function send(ctx, call) {
+    // A supplied transport replaces the network entirely — no base URL is joined
+    // and no bearer is attached, because an in-process caller has neither and
+    // must not be handed a credential it did not present.
+    if (ctx.transport)
+        return ctx.transport(call);
+    const headers = { accept: 'application/json', ...ctx.extraHeaders };
+    if (ctx.token)
+        headers.authorization = `Bearer ${ctx.token}`;
+    if (call.body !== undefined)
+        headers['content-type'] = 'application/json';
+    let response;
+    try {
+        response = await fetch(buildUrl(ctx.baseUrl, call.path, call.query), {
+            method: call.method,
+            headers,
+            ...(call.body !== undefined ? { body: call.body } : {}),
+        });
+    }
+    catch (cause) {
+        throw new CliError(EXIT.SERVER, `could not reach ${ctx.baseUrl}`, cause instanceof Error ? cause.message : String(cause));
+    }
+    return { status: response.status, headers: response.headers, text: await response.text() };
+}
+/**
+ * Turn a non-2xx into the CliError its status calls for.
+ *
+ * `unavailable` is set when the deployment's own manifest says this route is
+ * pending or gated: a 404 then means "your client is newer than this
+ * deployment", which is a different fact from "that id does not exist", and
+ * saying so is the difference between a usable message and a raw 404.
+ */
+export function classify(response, call, unavailable) {
+    if (response.status >= 200 && response.status < 300)
+        return undefined;
+    const code = serverErrorCode(response.text);
+    const where = `${call.method} ${call.template ?? call.path}`;
+    if (response.status === 401 || response.status === 403) {
+        return new CliError(EXIT.AUTH, `error: ${code ?? 'unauthorized'}`, `${where} → ${response.status}`);
+    }
+    if (response.status === 429) {
+        const retry = response.headers.get('retry-after');
+        return new CliError(EXIT.RATE_LIMITED, `error: ${code ?? 'rate_limited'}`, retry ? `retry after ${retry}s (${where})` : where);
+    }
+    if (response.status === 404 && unavailable) {
+        return new CliError(EXIT.SERVER, 'not available on this deployment yet', unavailable);
+    }
+    if (response.status >= 500) {
+        return new CliError(EXIT.SERVER, `error: ${code ?? `server ${response.status}`}`, where);
+    }
+    return new CliError(EXIT.USAGE, `error: ${code ?? `request rejected (${response.status})`}`, where);
+}
+/**
+ * Ask the deployment whether it serves a route yet.
+ *
+ * Best effort by design: it needs a token and a reachable server, and it runs
+ * only after a 404 has already happened, so a failure here just means the
+ * caller gets the plain 404 message it would have got anyway.
+ */
+export async function routeUnavailableReason(ctx, route) {
+    if (!ctx.token)
+        return undefined;
+    let manifest;
+    try {
+        const response = await send(ctx, { method: 'GET', path: '/api/agent/manifest' });
+        if (response.status !== 200)
+            return undefined;
+        manifest = JSON.parse(response.text);
+    }
+    catch {
+        return undefined;
+    }
+    const key = `${route.method} ${route.path}`;
+    if (manifest.pending?.includes(key)) {
+        return `${key} has no route file on this deployment yet (manifest version ${manifest.version}).`;
+    }
+    const gated = manifest.gated ?? [];
+    const hit = gated.find((g) => g.method === route.method && g.path === route.path);
+    if (hit) {
+        return `${key} is held out of this deployment's allowlist until ${hit.gatedUntil ?? 'a later slice'}.`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=http.js.map