monday-cli 0.2.0

package/dist/api/source-aggregator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `meta.source` + `meta.cache_age_seconds` merge rules per cli-design
+ * §6.1 — first leg seeds; `mixed` is contagious; `cache + live → mixed`;
+ * for cache age the aggregate is the OLDEST cache age across legs (the
+ * worst-case staleness).
+ *
+ * Lifted from four sites — see v0.2-plan §12 R21:
+ *   - `api/dry-run.ts` (`mergeSource` + `mergeCacheAge`, private)
+ *   - `commands/item/update.ts` (`mergeSourceForRemap`)
+ *   - `commands/item/create.ts` (`mergeSourceLeg` +
+ *     `mergeSourceWithPreflight` + `mergeCacheAgeWithPreflight`)
+ *   - inline `Math.max` cache-age folds
+ *
+ * The local copies all left a "If a third consumer arrives, lift to
+ * a shared module then" comment; create.ts was the third+fourth, so
+ * the lift fired post-M9.
+ */
+export type EnvelopeSource = 'live' | 'cache' | 'mixed';
+/**
+ * Planner/mutation surfaces that may claim `'none'` (no API call
+ * fired). The dry-run engine + create.ts surface this; once any
+ * leg fires it collapses to a real source via
+ * `mergeSourceWithPreflight`.
+ */
+export type EnvelopeSourceOrNone = EnvelopeSource | 'none';
+/**
+ * Merges a new leg's source into the running aggregate. First leg
+ * seeds (`undefined → next`); any `mixed` is contagious; otherwise
+ * `cache + live → mixed`; otherwise the unanimous value.
+ */
+export declare const mergeSource: (current: EnvelopeSource | undefined, next: EnvelopeSource) => EnvelopeSource;
+/**
+ * Folds a pre-planner preflight source ('live' / 'cache' / 'mixed' /
+ * `undefined` when no preflight leg fired) into a planner source
+ * ('live' / 'cache' / 'mixed' / 'none'). Used by create.ts's dry-run
+ * + live envelopes so `meta.source` reflects every wire leg that
+ * fired (Codex M9 P2 #1). When the planner is `'none'` and any
+ * preflight leg fired, the preflight source wins; otherwise the
+ * `mergeSource` rule applies.
+ */
+export declare const mergeSourceWithPreflight: (planner: EnvelopeSourceOrNone, preflight: EnvelopeSource | undefined) => EnvelopeSourceOrNone;
+/**
+ * Merges a new leg's `cacheAgeSeconds` into the running aggregate.
+ * Per cli-design §6.1, the envelope's `cache_age_seconds` is the
+ * **oldest** age across legs that hit cache — worst-case staleness.
+ * `null` legs (live fetches) don't update; if all legs are live the
+ * aggregate stays `null`.
+ */
+export declare const mergeCacheAge: (current: number | null, next: number | null) => number | null;
+/**
+ * Stateful accumulator wrapping `mergeSource` + `mergeCacheAge` for
+ * the multi-leg orchestrators in `commands/item/*` that fold per-leg
+ * `meta.source` / `cacheAgeSeconds` contributions into one aggregate
+ * before emitting the envelope. Lifted post-M11 (§16 R30) — five
+ * sites duplicated the same `let aggregate; record(source, cacheAge)`
+ * closure pattern (move's `runCrossBoardMove`, create's live path,
+ * update single, update bulk dry-run + live).
+ *
+ * The standalone `mergeSource` / `mergeCacheAge` exports stay — the
+ * `mergeSourceWithPreflight` shape in `create.ts` dry-run doesn't
+ * collapse cleanly into the class (it folds a `'none'`-claiming
+ * planner source against a preflight `EnvelopeSource | undefined`,
+ * not the class's per-leg `EnvelopeSource` shape).
+ */
+export declare class SourceAggregator {
+    private source;
+    private cacheAge;
+    /**
+     * Optional seed for callers that already have a first leg's source
+     * + cacheAge in hand (e.g. update bulk's metadata leg). Equivalent
+     * to `new SourceAggregator()` followed by `.record(seed.source,
+     * seed.cacheAgeSeconds)`, but keeps the call site one line.
+     */
+    constructor(seed?: {
+        readonly source: EnvelopeSource;
+        readonly cacheAgeSeconds: number | null;
+    });
+    /**
+     * Folds a leg's `source` + `cacheAgeSeconds` into the running
+     * aggregate. First call seeds; subsequent calls apply the
+     * `mergeSource` / `mergeCacheAge` rules.
+     */
+    record(source: EnvelopeSource, cacheAgeSeconds: number | null): void;
+    /**
+     * Snapshot of the current aggregate. `fallback` (default `'live'`)
+     * is returned when no leg has been recorded — matches the
+     * `aggregate ?? 'live'` pattern every call site used pre-lift.
+     */
+    result(fallback?: EnvelopeSource): {
+        readonly source: EnvelopeSource;
+        readonly cacheAgeSeconds: number | null;
+    };
+}
+//# sourceMappingURL=source-aggregator.d.ts.map

package/dist/api/source-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-aggregator.d.ts","sourceRoot":"","sources":["../../src/api/source-aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AACxD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,MAAM,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,SAAS,cAAc,GAAG,SAAS,EACnC,MAAM,cAAc,KACnB,cAKF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,oBAAoB,EAC7B,WAAW,cAAc,GAAG,SAAS,KACpC,oBAIF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,MAAM,GAAG,IAAI,EACtB,MAAM,MAAM,GAAG,IAAI,KAClB,MAAM,GAAG,IAIX,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAgB;IAEhC;;;;;OAKG;gBAED,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KACzC;IAMH;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAKpE;;;;OAIG;IACH,MAAM,CAAC,QAAQ,GAAE,cAAuB,GAAG;QACzC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;QAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KACzC;CAMF"}

package/dist/api/source-aggregator.js

@@ -0,0 +1,111 @@
+/**
+ * `meta.source` + `meta.cache_age_seconds` merge rules per cli-design
+ * §6.1 — first leg seeds; `mixed` is contagious; `cache + live → mixed`;
+ * for cache age the aggregate is the OLDEST cache age across legs (the
+ * worst-case staleness).
+ *
+ * Lifted from four sites — see v0.2-plan §12 R21:
+ *   - `api/dry-run.ts` (`mergeSource` + `mergeCacheAge`, private)
+ *   - `commands/item/update.ts` (`mergeSourceForRemap`)
+ *   - `commands/item/create.ts` (`mergeSourceLeg` +
+ *     `mergeSourceWithPreflight` + `mergeCacheAgeWithPreflight`)
+ *   - inline `Math.max` cache-age folds
+ *
+ * The local copies all left a "If a third consumer arrives, lift to
+ * a shared module then" comment; create.ts was the third+fourth, so
+ * the lift fired post-M9.
+ */
+/**
+ * Merges a new leg's source into the running aggregate. First leg
+ * seeds (`undefined → next`); any `mixed` is contagious; otherwise
+ * `cache + live → mixed`; otherwise the unanimous value.
+ */
+export const mergeSource = (current, next) => {
+    if (current === undefined)
+        return next;
+    if (current === 'mixed' || next === 'mixed')
+        return 'mixed';
+    if (current === next)
+        return current;
+    return 'mixed';
+};
+/**
+ * Folds a pre-planner preflight source ('live' / 'cache' / 'mixed' /
+ * `undefined` when no preflight leg fired) into a planner source
+ * ('live' / 'cache' / 'mixed' / 'none'). Used by create.ts's dry-run
+ * + live envelopes so `meta.source` reflects every wire leg that
+ * fired (Codex M9 P2 #1). When the planner is `'none'` and any
+ * preflight leg fired, the preflight source wins; otherwise the
+ * `mergeSource` rule applies.
+ */
+export const mergeSourceWithPreflight = (planner, preflight) => {
+    if (preflight === undefined)
+        return planner;
+    if (planner === 'none')
+        return preflight;
+    return mergeSource(planner, preflight);
+};
+/**
+ * Merges a new leg's `cacheAgeSeconds` into the running aggregate.
+ * Per cli-design §6.1, the envelope's `cache_age_seconds` is the
+ * **oldest** age across legs that hit cache — worst-case staleness.
+ * `null` legs (live fetches) don't update; if all legs are live the
+ * aggregate stays `null`.
+ */
+export const mergeCacheAge = (current, next) => {
+    if (next === null)
+        return current;
+    if (current === null)
+        return next;
+    return Math.max(current, next);
+};
+/**
+ * Stateful accumulator wrapping `mergeSource` + `mergeCacheAge` for
+ * the multi-leg orchestrators in `commands/item/*` that fold per-leg
+ * `meta.source` / `cacheAgeSeconds` contributions into one aggregate
+ * before emitting the envelope. Lifted post-M11 (§16 R30) — five
+ * sites duplicated the same `let aggregate; record(source, cacheAge)`
+ * closure pattern (move's `runCrossBoardMove`, create's live path,
+ * update single, update bulk dry-run + live).
+ *
+ * The standalone `mergeSource` / `mergeCacheAge` exports stay — the
+ * `mergeSourceWithPreflight` shape in `create.ts` dry-run doesn't
+ * collapse cleanly into the class (it folds a `'none'`-claiming
+ * planner source against a preflight `EnvelopeSource | undefined`,
+ * not the class's per-leg `EnvelopeSource` shape).
+ */
+export class SourceAggregator {
+    source;
+    cacheAge;
+    /**
+     * Optional seed for callers that already have a first leg's source
+     * + cacheAge in hand (e.g. update bulk's metadata leg). Equivalent
+     * to `new SourceAggregator()` followed by `.record(seed.source,
+     * seed.cacheAgeSeconds)`, but keeps the call site one line.
+     */
+    constructor(seed) {
+        this.source = seed?.source;
+        this.cacheAge = seed?.cacheAgeSeconds ?? null;
+    }
+    /**
+     * Folds a leg's `source` + `cacheAgeSeconds` into the running
+     * aggregate. First call seeds; subsequent calls apply the
+     * `mergeSource` / `mergeCacheAge` rules.
+     */
+    record(source, cacheAgeSeconds) {
+        this.source = mergeSource(this.source, source);
+        this.cacheAge = mergeCacheAge(this.cacheAge, cacheAgeSeconds);
+    }
+    /**
+     * Snapshot of the current aggregate. `fallback` (default `'live'`)
+     * is returned when no leg has been recorded — matches the
+     * `aggregate ?? 'live'` pattern every call site used pre-lift.
+     */
+    result(fallback = 'live') {
+        return {
+            source: this.source ?? fallback,
+            cacheAgeSeconds: this.cacheAge,
+        };
+    }
+}
+//# sourceMappingURL=source-aggregator.js.map

package/dist/api/source-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-aggregator.js","sourceRoot":"","sources":["../../src/api/source-aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,OAAmC,EACnC,IAAoB,EACJ,EAAE;IAClB,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,OAAO,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5D,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,OAA6B,EAC7B,SAAqC,EACf,EAAE;IACxB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC5C,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,OAAsB,EACtB,IAAmB,EACJ,EAAE;IACjB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IAClC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAA6B;IACnC,QAAQ,CAAgB;IAEhC;;;;;OAKG;IACH,YACE,IAGC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,eAAe,IAAI,IAAI,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAsB,EAAE,eAA8B;QAC3D,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAChE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,WAA2B,MAAM;QAItC,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,QAAQ;YAC/B,eAAe,EAAE,IAAI,CAAC,QAAQ;SAC/B,CAAC;IACJ,CAAC;CACF"}

package/dist/api/transport.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Transport interface (`v0.1-plan.md` §2 pre-flight, §5.2).
+ *
+ * Sits between `commands/*` and the network. The injected
+ * `Transport` is what `run({ transport })` swaps under tests — a
+ * `FixtureTransport` substitutes for `FetchTransport` so the same
+ * commands → api → transport stack runs in tests as in production
+ * (header injection, abort handling, timeout, retry mapping). The
+ * alternative — `vi.spyOn`'ing the SDK's `request` method — was
+ * the original plan and got rejected in the Codex review because
+ * it bypasses too many layers.
+ *
+ * The transport does **not** map GraphQL errors to CLI error codes;
+ * that's `api/errors.ts` in M2. Network-level failures (refused
+ * connection, timeout, malformed JSON) become `ApiError`s here so
+ * the runner never sees a raw `fetch` exception.
+ */
+export interface TransportRequest {
+    readonly query: string;
+    readonly variables?: Readonly<Record<string, unknown>>;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+    readonly operationName?: string;
+}
+export interface TransportResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    /**
+     * Parsed JSON body. GraphQL responses are JSON; if the upstream
+     * returns something else (HTML error page, etc.) the transport
+     * surfaces an `ApiError(network_error)` rather than a partially-
+     * decoded payload.
+     */
+    readonly body: unknown;
+}
+export interface Transport {
+    readonly request: (req: TransportRequest) => Promise<TransportResponse>;
+}
+export interface FetchTransportConfig {
+    readonly endpoint: string;
+    readonly apiToken: string;
+    readonly apiVersion: string;
+    readonly timeoutMs: number;
+    /** Override for tests; defaults to global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Builds a `Transport` over `fetch`. Owns:
+ *  - `Authorization: <token>` (no `Bearer ` prefix per Monday's API).
+ *  - `API-Version: <pinned>` per `cli-design.md` §2.
+ *  - `Content-Type: application/json`.
+ *  - Per-request timeout via `AbortSignal.timeout` chained with the
+ *    caller's signal so external cancellation still wins.
+ *
+ * The token never reaches an error message, log line, or URL.
+ */
+export declare const createFetchTransport: (config: FetchTransportConfig) => Transport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/api/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/api/transport.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,oBAAoB,KAC3B,SAoGF,CAAC"}

package/dist/api/transport.js

@@ -0,0 +1,190 @@
+import { ApiError } from '../utils/errors.js';
+/**
+ * Builds a `Transport` over `fetch`. Owns:
+ *  - `Authorization: <token>` (no `Bearer ` prefix per Monday's API).
+ *  - `API-Version: <pinned>` per `cli-design.md` §2.
+ *  - `Content-Type: application/json`.
+ *  - Per-request timeout via `AbortSignal.timeout` chained with the
+ *    caller's signal so external cancellation still wins.
+ *
+ * The token never reaches an error message, log line, or URL.
+ */
+export const createFetchTransport = (config) => {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    return {
+        request: async ({ query, variables, headers, signal, operationName, }) => {
+            // Header lockdown: caller-supplied headers spread first so the
+            // transport-owned set (`Authorization`, `API-Version`,
+            // `Content-Type`) always wins. The previous order let any
+            // caller — including a buggy command or an injected
+            // `FixtureTransport` request — override auth or the API
+            // version pin silently. We also strip any case-variant of
+            // those names from the caller bag so a lowercase
+            // `authorization` can't sneak past the literal-key spread.
+            const reservedHeaderLowerNames = new Set([
+                'authorization',
+                'api-version',
+                'content-type',
+            ]);
+            const callerHeaders = headers ?? {};
+            const safeCallerHeaders = {};
+            for (const [key, value] of Object.entries(callerHeaders)) {
+                if (!reservedHeaderLowerNames.has(key.toLowerCase())) {
+                    safeCallerHeaders[key] = value;
+                }
+            }
+            const requestHeaders = {
+                ...safeCallerHeaders,
+                Authorization: config.apiToken,
+                'API-Version': config.apiVersion,
+                'Content-Type': 'application/json',
+            };
+            const body = { query };
+            if (variables !== undefined) {
+                body.variables = variables;
+            }
+            if (operationName !== undefined) {
+                body.operationName = operationName;
+            }
+            const combinedSignal = combineSignals(signal, AbortSignal.timeout(config.timeoutMs));
+            let response;
+            try {
+                response = await fetchImpl(config.endpoint, {
+                    method: 'POST',
+                    headers: requestHeaders,
+                    body: JSON.stringify(body),
+                    signal: combinedSignal,
+                });
+            }
+            catch (err) {
+                // Don't ever interpolate the token into the error string —
+                // `requestHeaders` stays out of the message; `cause` carries
+                // the raw error (which the redactor will scrub before emit).
+                if (isAbortError(err) && combinedSignal.reason !== signal?.reason) {
+                    throw new ApiError('timeout', `request timed out after ${String(config.timeoutMs)}ms`, { cause: err, details: { timeout_ms: config.timeoutMs } });
+                }
+                throw new ApiError('network_error', describeFetchError(err), {
+                    cause: err,
+                });
+            }
+            const responseHeaders = headersToRecord(response.headers);
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch (err) {
+                // Don't interpolate `config.endpoint` into the message —
+                // a misconfigured URL containing the token (e.g. someone
+                // setting MONDAY_API_URL=...?token=...) would land here.
+                // The redactor would catch it on emit, but security.md
+                // explicitly forbids putting the token into Error.message
+                // in the first place. (Codex M2 review §4.)
+                throw new ApiError('network_error', `non-JSON response (status ${String(response.status)})`, { cause: err, httpStatus: response.status });
+            }
+            return {
+                status: response.status,
+                headers: responseHeaders,
+                body: parsed,
+            };
+        },
+    };
+};
+const isAbortError = (err) => {
+    if (err instanceof Error) {
+        return err.name === 'AbortError' || err.name === 'TimeoutError';
+    }
+    return false;
+};
+/**
+ * Builds a generic, URL-free message for a thrown `fetch` exception.
+ *
+ * Why not `err.message`. Node's undici embeds the request URL into
+ * the messages of common transport errors — `ECONNREFUSED https://
+ * api.example/v2?token=...`, `getaddrinfo ENOTFOUND
+ * api.example`, etc. If `MONDAY_API_URL` is misconfigured to carry
+ * the token (or any other secret), the literal token lands in
+ * `ApiError.message`. The runner's redactor would catch it on emit,
+ * but `security.md` forbids the token entering `Error.message` in
+ * the first place — the rule is defence-in-depth, not "we'll fix it
+ * downstream". The original error is still attached via `cause`,
+ * which a future debug log surfaces through `redact()` (key + value
+ * scan) rather than verbatim.
+ *
+ * Maps the common shapes to short, stable codes:
+ *  - DNS / hostname unresolvable  → `dns lookup failed`
+ *  - ECONNREFUSED / ECONNRESET    → `connection refused`
+ *  - SSL/TLS issue                → `tls error`
+ *  - generic Error                → `fetch failed`
+ *  - non-Error throw              → `fetch failed`
+ */
+const describeFetchError = (err) => {
+    if (err instanceof Error) {
+        const code = err.code;
+        if (typeof code === 'string') {
+            if (code.startsWith('ENOTFOUND') || code.startsWith('EAI_')) {
+                return 'fetch failed: dns lookup failed';
+            }
+            if (code === 'ECONNREFUSED' || code === 'ECONNRESET') {
+                return 'fetch failed: connection refused';
+            }
+            if (code === 'CERT_HAS_EXPIRED' || code.startsWith('UNABLE_TO_')) {
+                return 'fetch failed: tls error';
+            }
+        }
+        // Sniff the message for the same common shapes when err.code
+        // isn't surfaced (older fetch impls, wrapped TypeErrors).
+        const lower = err.message.toLowerCase();
+        if (lower.includes('econnrefused') || lower.includes('connection refused')) {
+            return 'fetch failed: connection refused';
+        }
+        if (lower.includes('enotfound') ||
+            lower.includes('eai_again') ||
+            lower.includes('getaddrinfo')) {
+            return 'fetch failed: dns lookup failed';
+        }
+        return 'fetch failed';
+    }
+    return 'fetch failed';
+};
+const headersToRecord = (headers) => {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+};
+/**
+ * Mirrors `AbortSignal.any` in environments that don't have it yet.
+ * Prefers the platform implementation when available so tests
+ * exercise the real path.
+ */
+const combineSignals = (...signals) => {
+    const real = signals.filter((s) => s !== undefined);
+    const [first, ...rest] = real;
+    if (first === undefined) {
+        return new AbortController().signal;
+    }
+    if (rest.length === 0) {
+        return first;
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(real);
+    }
+    /* c8 ignore start — legacy fallback for runtimes without
+       `AbortSignal.any` (Node < 19). Repo's engines pin to Node 22+,
+       so this path is never hit in CI or dev. Kept for safety in case
+       a downstream embedder runs an older Node. */
+    const ctrl = new AbortController();
+    for (const s of real) {
+        if (s.aborted) {
+            ctrl.abort(s.reason);
+            break;
+        }
+        s.addEventListener('abort', () => {
+            ctrl.abort(s.reason);
+        }, { once: true });
+    }
+    return ctrl.signal;
+    /* c8 ignore stop */
+};
+//# sourceMappingURL=transport.js.map

package/dist/api/transport.js.map

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

package/dist/api/update-mutation-result.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Update-mutation projection + GraphQL field-fragment, lifted from
+ * five M13 mutation verbs and two M3 / M5b read-or-write call sites
+ * (v0.2-plan §20 R37 + R38).
+ *
+ * **R37 — `projectMutationUpdate`.** Every M13 mutation verb (`update
+ * reply` / `edit` / `delete` plus the four toggle verbs `like` /
+ * `unlike` / `pin` / `unpin`) returns the post-mutation `Update` and
+ * guards a null payload with the same shape: a typed throw carrying
+ * `details.update_id` (or `parent_id` for reply, which keys errors
+ * off the parent the agent passed on argv), then a strict zod parse
+ * to surface the §6.4 mutation envelope's `data: <projected
+ * snapshot>`. Mirrors R28's `projectMutationItem` exactly with
+ * `Update` substituted for `Item`.
+ *
+ * Lifted from five sites — see v0.2-plan §20 R37:
+ *   - `commands/update/reply.ts` (M13 — local `projectReply`,
+ *     `idKey: 'parent_id'` because the argv input is the parent,
+ *     not the new update).
+ *   - `commands/update/edit.ts` (M13 — local `projectEdited`).
+ *   - `commands/update/delete.ts` (M13 — local `projectDeleted`).
+ *   - `commands/update/toggle.ts` (M13 — local `projectToggle`,
+ *     consumed by four toggle verbs via per-verb `mutationName`).
+ *   - `commands/update/clear-all.ts` (M13 — uses the null-check-only
+ *     variant; see "Why two exports" below).
+ *
+ * **Why two exports.** Four of the five lift sites parse the wire
+ * payload against the full `updateProjectionSchema`. Clear-all's
+ * `DELETE_UPDATE_MUTATION` deliberately selects only `{ id }` (per-
+ * target round-trip; no projection is emitted in `data.results[i]`),
+ * so the strict schema would fail on every successful delete. The
+ * lift therefore exposes two seams:
+ *
+ *   - `projectMutationUpdate({raw, updateId, mutationName, idKey?})`
+ *     — null-check + strict parse + projection. Used by reply / edit
+ *     / delete / toggle.
+ *   - `assertUpdateMutationPresent({raw, updateId, mutationName,
+ *     idKey?})` — null-check + typed throw, no projection. Used by
+ *     clear-all's per-target dispatch.
+ *
+ * Both share `buildNotFoundError` so the typed throw's shape (code,
+ * message format, `details.<idKey>`) is identical across all five
+ * sites — agents key off `error.code` + `error.details.update_id`
+ * (or `parent_id`) without caring which verb threw.
+ *
+ * **R38 — `UPDATE_FIELDS_FRAGMENT`.** The GraphQL selection set every
+ * Update-shape mutation + the M3 `update get` read share. Mirrors
+ * `ITEM_FIELDS_FRAGMENT` (M5b lift in `item-helpers.ts`); a future
+ * §6.4 wire-shape addition is a one-touch fragment edit instead of
+ * a six-touch sweep across `update create` / `reply` / `edit` /
+ * `delete` / `toggle` / `get`. Indentation matches the 6-space
+ * continuation each consumer interpolates at, so rendered query
+ * bytes are unchanged post-lift.
+ *
+ * **What stays at the call site.** Reply's `parent_id` echo from
+ * argv (`{...projected, parent_id: parentId}`) is a caller-side
+ * extension — the helper returns the base `UpdateProjection` and
+ * reply spreads onto it before emit. Mirrors R28's handling of
+ * `item duplicate`'s `duplicated_from_id` extension. `update get`'s
+ * extra `edited_at` + `replies` slots are likewise composed at the
+ * call site (`${UPDATE_FIELDS_FRAGMENT}\n  edited_at\n  replies
+ * {...}`); the fragment is the shared subset, callers compose extras
+ * on top — same shape `item subitems` uses against
+ * `ITEM_FIELDS_FRAGMENT`.
+ */
+import { z } from 'zod';
+/**
+ * Shared GraphQL selection set for the Update shape — every M13
+ * mutation verb plus M5b's `update create` and M3's `update get`
+ * select these fields. 6-space continuation indent matches the
+ * column every consumer interpolates `${UPDATE_FIELDS_FRAGMENT}` at,
+ * so rendered query bytes are unchanged post-lift.
+ */
+export declare const UPDATE_FIELDS_FRAGMENT = "id\n      body\n      text_body\n      creator_id\n      creator { id name email }\n      item_id\n      created_at\n      updated_at";
+/**
+ * Strict zod schema for the post-mutation `Update` projection — the
+ * exact shape `UPDATE_FIELDS_FRAGMENT` selects from the wire. Reply's
+ * output extends this with `parent_id` at the call site.
+ */
+export declare const updateProjectionSchema: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "UpdateId", "out">;
+    body: z.ZodString;
+    text_body: z.ZodNullable<z.ZodString>;
+    creator_id: z.ZodNullable<z.ZodString>;
+    creator: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        email: z.ZodString;
+    }, z.core.$strict>>;
+    item_id: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "ItemId", "out">>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type UpdateProjection = z.infer<typeof updateProjectionSchema>;
+/** `'update_id'` for the M13 verbs; `'parent_id'` for `update reply`
+ *  (the argv input is the parent, not the new update). */
+export type UpdateMutationIdKey = 'update_id' | 'parent_id';
+export interface UpdateMutationContext {
+    readonly updateId: string;
+    /** Mutation root-field name for the not_found message
+     *  (`create_update` / `edit_update` / `delete_update` /
+     *  `like_update` / `unlike_update` / `pin_to_top` /
+     *  `unpin_from_top`). */
+    readonly mutationName: string;
+    /** Defaults to `'update_id'`. */
+    readonly idKey?: UpdateMutationIdKey;
+}
+export interface ProjectMutationUpdateInputs extends UpdateMutationContext {
+    readonly raw: unknown;
+}
+/**
+ * Null-check-only variant for sites whose GraphQL selection is too
+ * narrow to parse against `updateProjectionSchema` (currently just
+ * `update clear-all`'s per-target `delete_update` round-trip, which
+ * selects only `{ id }`). Throws the same typed `not_found` shape
+ * the projecting helper does so agents see one error contract across
+ * every M13 mutation verb.
+ */
+export declare const assertUpdateMutationPresent: (raw: unknown, ctx: UpdateMutationContext) => void;
+/**
+ * Parses + projects a post-mutation `Update` payload, throwing the
+ * typed `not_found` on null/undefined and `internal_error` (via the
+ * R18 parse-boundary wrap) on a malformed shape. The helper owns
+ * both error envelopes; callers compose post-projection extras
+ * (reply's `parent_id` echo) at the call site.
+ *
+ * `details: { <idKey>: updateId }` is supplied by the helper so
+ * every consumer carries the same envelope shape — agents key off
+ * `details.update_id` (or `details.parent_id` for reply's not_found
+ * path) regardless of which mutation verb threw.
+ */
+export declare const projectMutationUpdate: (inputs: ProjectMutationUpdateInputs) => UpdateProjection;
+//# sourceMappingURL=update-mutation-result.d.ts.map

package/dist/api/update-mutation-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-mutation-result.d.ts","sourceRoot":"","sources":["../../src/api/update-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,0IAOlB,CAAC;AAUlB;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;kBAWxB,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;0DAC0D;AAC1D,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;6BAGyB;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED,MAAM,WAAW,2BAA4B,SAAQ,qBAAqB;IACxE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAaD;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACtC,KAAK,OAAO,EACZ,KAAK,qBAAqB,KACzB,IAIF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,2BAA2B,KAClC,gBASF,CAAC"}