monday-cli 0.7.1 → 0.8.0

package/dist/api/error-decoration.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Mutation-path catch-arm error decoration helpers
+ * (`docs/v0.8-plan.md` §3 "v0.8 refactor cluster" + §22 R-v0.7-NEW-5 /
+ * R-v0.8-NEW-6; full pattern detail in `docs/v0.7-plan.md` §22
+ * R-v0.7-NEW-5).
+ *
+ * **Status: SHIPPED at the v0.8 refactor-cluster IMPL.** Both runtime
+ * bodies below replace the pre-flight c8-ignored stub throws; the 7
+ * inline sites (4 `reThrowDecorated`, 3 `projectCauseForEnvelope`) now
+ * delegate the lifted surface, and the focused unit suite
+ * (`tests/unit/api/error-decoration.test.ts`) drives the coverage
+ * ratchet (the conditional-spread arms that previously dragged
+ * `item/update.ts` to ~80%). This was a pure internal lift — no probe,
+ * no new ERROR_CODES, no cli-design section, no new command,
+ * byte-for-byte behaviour-preserving at every site. The pre-flight
+ * shape mirrored v0.6-M38 `file-column-set.ts` (stub-then-IMPL, minus
+ * the wire/argv surface); R-NEW-76's parseArgv-BEFORE-c8 boundary rule
+ * did NOT apply here because the helpers have no argv surface.
+ *
+ * **Why a dedicated cluster (not folded into a feature milestone).**
+ * `reThrowDecorated` spans 4 unrelated mutation paths (item-clear-bulk
+ * / JSON-bulk / M42 file-bulk / M46 file-bulk-multi) — too broad to
+ * ride one feature's IMPL, and 3 of the 4 are unrelated to M47/M48's
+ * feature work. The lift landed ahead of M47 specifically so the
+ * fail-fast scaffold was consolidated BEFORE M47 would add a 5th touch.
+ *
+ * ---
+ *
+ * ## R-v0.7-NEW-5 — `reThrowDecorated` (fail-fast-scaffold lift)
+ *
+ * The post-`foldAndRemap` typed split-and-rebuild is byte-identical
+ * across **4 consumers**:
+ *
+ *   1. item-clear-bulk     `src/commands/item/clear.ts`  (the c8-ignored arms)
+ *   2. JSON-bulk           `src/commands/item/update.ts` (per-item fail-fast)
+ *   3. M42 file-bulk       `src/commands/item/update.ts` (`runItemUpdateBulkFileDispatch`)
+ *   4. M46 file-bulk-multi `src/commands/item/update.ts` (multi-file bulk)
+ *
+ * **LIFTED (the invariant):** the typed split —
+ *   `if (remapped.code === 'usage_error') → new UsageError(...)`
+ *   `else → new ApiError(remapped.code, ...)` — with the 5
+ *   conditional-spread metadata arms (`cause` on both arms;
+ *   `httpStatus` / `mondayCode` / `requestId` / `retryAfterSeconds`
+ *   plus the unconditional `retryable: remapped.retryable` on the
+ *   ApiError arm). These spreads were the uncovered branches that
+ *   dragged `item/update.ts` to 79.42% — consolidating them into ONE
+ *   helper + ONE focused unit test recovered the margin (the 4-path
+ *   ratchet; `item/update.ts` branches 79.42% → 87.27%).
+ *
+ * **STAYS INLINE (the over-fit boundary — each site's own work):** the
+ *   `foldAndRemap` call, `const existing = remapped.details ?? {}`, and
+ *   the per-site decoration object built from `existing` + the
+ *   site-specific slots (`applied_count` / `applied_to` /
+ *   `failed_at_item` / `matched_count` shared by all 4; plus
+ *   `applied_file_columns_per_item` / `failed_file_column` /
+ *   `file_count` / `file_column_ids` on the M46-multi site). Each site
+ *   assembles its own `details` record, then delegates the typed split.
+ *
+ * ## R-v0.8-NEW-6 — `projectCauseForEnvelope` (cause-projection builder)
+ *
+ * Adjacent, bundled (both live in mutation-path catch arms) but a
+ * SEPARATE helper — NOT merged into `reThrowDecorated`. Recurs across
+ * **3 orphan-warn sites**:
+ *
+ *   1. M43 create-time leg-2 `src/commands/item/create.ts` (`create_then_file_upload_partial_failure`)
+ *   2. M46 create-time multi  `src/commands/item/create.ts` (same + `applied_file_columns`)
+ *   3. M46 single-item multi  `src/commands/item/update.ts` (`multi_file_update_partial_failure`)
+ *
+ * **LIFTED:** ONLY the ~4-line projection builder — seed
+ *   `{ code, message }` from the (already-remapped, or raw-`MondayCliError`)
+ *   error, then conditionally attach `details`. (At the two create
+ *   sites the `if (err.details !== undefined)` arm was c8-ignored as
+ *   defensive while inlined; the builder's own unit test now drives
+ *   both a details-present and a details-absent error, so this lift
+ *   dropped those c8-ignore directives and genuinely covers both arms.)
+ *
+ * **STAYS INLINE (why this is structurally distinct from
+ *   `reThrowDecorated`, not the same lift):** the surrounding
+ *   orphan-warn decoration diverges per site — the outer code is ALWAYS
+ *   `internal_error` (not the preserved remapped code), the
+ *   `details.reason` literal differs, the decoration slots differ
+ *   (`created_item_id` vs `item_id`; `applied_file_columns` present on
+ *   the M46 sites), and the hint text differs. The genuinely-shared
+ *   surface is JUST the projection builder. Merging the two helpers
+ *   would force parameterising outer-code policy + decoration shape +
+ *   cause-projection-vs-in-place-merge, collapsing each helper's value
+ *   to "shared `foldAndRemap` call site" (already factored). See
+ *   `docs/v0.7-plan.md` §22 R-v0.7-NEW-5 "M43 IMPL outcome" for the
+ *   full distinctness argument.
+ */
+import { type MondayCliError } from '../utils/errors.js';
+/**
+ * Re-throws a `foldAndRemap`-decorated bulk/fail-fast error, rebuilding
+ * it as the right typed class with its wire metadata preserved.
+ *
+ * The caller has already folded resolver-warnings + applied the
+ * `validation_failed → column_archived` stale-cache remap, and has
+ * assembled the full `details` decoration (its `...existing` spread
+ * plus the per-site progress slots). This helper owns ONLY the typed
+ * split: `usage_error` rebuilds as {@link UsageError}; any other code
+ * rebuilds as {@link ApiError} preserving the wire metadata
+ * (`httpStatus` / `mondayCode` / `requestId` / `retryAfterSeconds` /
+ * `retryable`) via conditional spreads. Always throws — return type is
+ * `never` so callers don't need a trailing unreachable statement.
+ *
+ * @param remapped the post-`foldAndRemap` error whose typed code +
+ *   wire metadata drive the rebuild
+ * @param details the fully-assembled decoration record (already
+ *   including the `...existing` spread of `remapped.details`)
+ */
+export declare function reThrowDecorated(remapped: MondayCliError, details: Record<string, unknown>): never;
+/**
+ * Builds the JSON `details.cause` projection for an orphan-warn
+ * envelope: a `{ code, message }` seed plus an optional `details`
+ * passthrough. The surrounding always-`internal_error` wrap +
+ * `details.reason` discriminator + hint text stay inline at each call
+ * site (they diverge); this owns only the shared projection shape.
+ *
+ * @param err the (remapped, or raw) `MondayCliError` whose surface is
+ *   projected into the agent-inspectable `details.cause` slot
+ * @returns the projection record for embedding under `details.cause`
+ */
+export declare function projectCauseForEnvelope(err: MondayCliError): Record<string, unknown>;
+//# sourceMappingURL=error-decoration.d.ts.map

package/dist/api/error-decoration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-decoration.d.ts","sourceRoot":"","sources":["../../src/api/error-decoration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AAEH,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,KAAK,CAwBP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,cAAc,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/api/error-decoration.js

@@ -0,0 +1,161 @@
+/**
+ * Mutation-path catch-arm error decoration helpers
+ * (`docs/v0.8-plan.md` §3 "v0.8 refactor cluster" + §22 R-v0.7-NEW-5 /
+ * R-v0.8-NEW-6; full pattern detail in `docs/v0.7-plan.md` §22
+ * R-v0.7-NEW-5).
+ *
+ * **Status: SHIPPED at the v0.8 refactor-cluster IMPL.** Both runtime
+ * bodies below replace the pre-flight c8-ignored stub throws; the 7
+ * inline sites (4 `reThrowDecorated`, 3 `projectCauseForEnvelope`) now
+ * delegate the lifted surface, and the focused unit suite
+ * (`tests/unit/api/error-decoration.test.ts`) drives the coverage
+ * ratchet (the conditional-spread arms that previously dragged
+ * `item/update.ts` to ~80%). This was a pure internal lift — no probe,
+ * no new ERROR_CODES, no cli-design section, no new command,
+ * byte-for-byte behaviour-preserving at every site. The pre-flight
+ * shape mirrored v0.6-M38 `file-column-set.ts` (stub-then-IMPL, minus
+ * the wire/argv surface); R-NEW-76's parseArgv-BEFORE-c8 boundary rule
+ * did NOT apply here because the helpers have no argv surface.
+ *
+ * **Why a dedicated cluster (not folded into a feature milestone).**
+ * `reThrowDecorated` spans 4 unrelated mutation paths (item-clear-bulk
+ * / JSON-bulk / M42 file-bulk / M46 file-bulk-multi) — too broad to
+ * ride one feature's IMPL, and 3 of the 4 are unrelated to M47/M48's
+ * feature work. The lift landed ahead of M47 specifically so the
+ * fail-fast scaffold was consolidated BEFORE M47 would add a 5th touch.
+ *
+ * ---
+ *
+ * ## R-v0.7-NEW-5 — `reThrowDecorated` (fail-fast-scaffold lift)
+ *
+ * The post-`foldAndRemap` typed split-and-rebuild is byte-identical
+ * across **4 consumers**:
+ *
+ *   1. item-clear-bulk     `src/commands/item/clear.ts`  (the c8-ignored arms)
+ *   2. JSON-bulk           `src/commands/item/update.ts` (per-item fail-fast)
+ *   3. M42 file-bulk       `src/commands/item/update.ts` (`runItemUpdateBulkFileDispatch`)
+ *   4. M46 file-bulk-multi `src/commands/item/update.ts` (multi-file bulk)
+ *
+ * **LIFTED (the invariant):** the typed split —
+ *   `if (remapped.code === 'usage_error') → new UsageError(...)`
+ *   `else → new ApiError(remapped.code, ...)` — with the 5
+ *   conditional-spread metadata arms (`cause` on both arms;
+ *   `httpStatus` / `mondayCode` / `requestId` / `retryAfterSeconds`
+ *   plus the unconditional `retryable: remapped.retryable` on the
+ *   ApiError arm). These spreads were the uncovered branches that
+ *   dragged `item/update.ts` to 79.42% — consolidating them into ONE
+ *   helper + ONE focused unit test recovered the margin (the 4-path
+ *   ratchet; `item/update.ts` branches 79.42% → 87.27%).
+ *
+ * **STAYS INLINE (the over-fit boundary — each site's own work):** the
+ *   `foldAndRemap` call, `const existing = remapped.details ?? {}`, and
+ *   the per-site decoration object built from `existing` + the
+ *   site-specific slots (`applied_count` / `applied_to` /
+ *   `failed_at_item` / `matched_count` shared by all 4; plus
+ *   `applied_file_columns_per_item` / `failed_file_column` /
+ *   `file_count` / `file_column_ids` on the M46-multi site). Each site
+ *   assembles its own `details` record, then delegates the typed split.
+ *
+ * ## R-v0.8-NEW-6 — `projectCauseForEnvelope` (cause-projection builder)
+ *
+ * Adjacent, bundled (both live in mutation-path catch arms) but a
+ * SEPARATE helper — NOT merged into `reThrowDecorated`. Recurs across
+ * **3 orphan-warn sites**:
+ *
+ *   1. M43 create-time leg-2 `src/commands/item/create.ts` (`create_then_file_upload_partial_failure`)
+ *   2. M46 create-time multi  `src/commands/item/create.ts` (same + `applied_file_columns`)
+ *   3. M46 single-item multi  `src/commands/item/update.ts` (`multi_file_update_partial_failure`)
+ *
+ * **LIFTED:** ONLY the ~4-line projection builder — seed
+ *   `{ code, message }` from the (already-remapped, or raw-`MondayCliError`)
+ *   error, then conditionally attach `details`. (At the two create
+ *   sites the `if (err.details !== undefined)` arm was c8-ignored as
+ *   defensive while inlined; the builder's own unit test now drives
+ *   both a details-present and a details-absent error, so this lift
+ *   dropped those c8-ignore directives and genuinely covers both arms.)
+ *
+ * **STAYS INLINE (why this is structurally distinct from
+ *   `reThrowDecorated`, not the same lift):** the surrounding
+ *   orphan-warn decoration diverges per site — the outer code is ALWAYS
+ *   `internal_error` (not the preserved remapped code), the
+ *   `details.reason` literal differs, the decoration slots differ
+ *   (`created_item_id` vs `item_id`; `applied_file_columns` present on
+ *   the M46 sites), and the hint text differs. The genuinely-shared
+ *   surface is JUST the projection builder. Merging the two helpers
+ *   would force parameterising outer-code policy + decoration shape +
+ *   cause-projection-vs-in-place-merge, collapsing each helper's value
+ *   to "shared `foldAndRemap` call site" (already factored). See
+ *   `docs/v0.7-plan.md` §22 R-v0.7-NEW-5 "M43 IMPL outcome" for the
+ *   full distinctness argument.
+ */
+import { ApiError, UsageError } from '../utils/errors.js';
+/**
+ * Re-throws a `foldAndRemap`-decorated bulk/fail-fast error, rebuilding
+ * it as the right typed class with its wire metadata preserved.
+ *
+ * The caller has already folded resolver-warnings + applied the
+ * `validation_failed → column_archived` stale-cache remap, and has
+ * assembled the full `details` decoration (its `...existing` spread
+ * plus the per-site progress slots). This helper owns ONLY the typed
+ * split: `usage_error` rebuilds as {@link UsageError}; any other code
+ * rebuilds as {@link ApiError} preserving the wire metadata
+ * (`httpStatus` / `mondayCode` / `requestId` / `retryAfterSeconds` /
+ * `retryable`) via conditional spreads. Always throws — return type is
+ * `never` so callers don't need a trailing unreachable statement.
+ *
+ * @param remapped the post-`foldAndRemap` error whose typed code +
+ *   wire metadata drive the rebuild
+ * @param details the fully-assembled decoration record (already
+ *   including the `...existing` spread of `remapped.details`)
+ */
+export function reThrowDecorated(remapped, details) {
+    // usage_error rebuilds as UsageError — the only metadata it carries
+    // is the optional `cause` chain. Every other code rebuilds as
+    // ApiError preserving the wire metadata via conditional spreads
+    // (each `?? :` attaches a field only when the source error carried
+    // it; the per-Monday-error permutations of httpStatus / mondayCode /
+    // requestId / retryAfterSeconds set-or-unset aren't all exercised by
+    // any single call site, which is why they lived as uncovered branches
+    // before this lift folded them into one tested helper).
+    if (remapped.code === 'usage_error') {
+        throw new UsageError(remapped.message, {
+            ...(remapped.cause === undefined ? {} : { cause: remapped.cause }),
+            details,
+        });
+    }
+    throw new ApiError(remapped.code, remapped.message, {
+        ...(remapped.cause === undefined ? {} : { cause: remapped.cause }),
+        ...(remapped.httpStatus === undefined ? {} : { httpStatus: remapped.httpStatus }),
+        ...(remapped.mondayCode === undefined ? {} : { mondayCode: remapped.mondayCode }),
+        ...(remapped.requestId === undefined ? {} : { requestId: remapped.requestId }),
+        retryable: remapped.retryable,
+        ...(remapped.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: remapped.retryAfterSeconds }),
+        details,
+    });
+}
+/**
+ * Builds the JSON `details.cause` projection for an orphan-warn
+ * envelope: a `{ code, message }` seed plus an optional `details`
+ * passthrough. The surrounding always-`internal_error` wrap +
+ * `details.reason` discriminator + hint text stay inline at each call
+ * site (they diverge); this owns only the shared projection shape.
+ *
+ * @param err the (remapped, or raw) `MondayCliError` whose surface is
+ *   projected into the agent-inspectable `details.cause` slot
+ * @returns the projection record for embedding under `details.cause`
+ */
+export function projectCauseForEnvelope(err) {
+    const projection = {
+        code: err.code,
+        message: err.message,
+    };
+    // `details` is optional on MondayCliError; attach it only when the
+    // source error carried one. Both arms are driven by the helper's
+    // focused unit test, so the two create-site call sites can drop the
+    // c8-ignore that previously masked the details-absent arm.
+    if (err.details !== undefined) {
+        projection.details = err.details;
+    }
+    return projection;
+}
+//# sourceMappingURL=error-decoration.js.map

package/dist/api/error-decoration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-decoration.js","sourceRoot":"","sources":["../../src/api/error-decoration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AAEH,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAuB,MAAM,oBAAoB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAwB,EACxB,OAAgC;IAEhC,oEAAoE;IACpE,8DAA8D;IAC9D,gEAAgE;IAChE,mEAAmE;IACnE,qEAAqE;IACrE,qEAAqE;IACrE,sEAAsE;IACtE,wDAAwD;IACxD,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACpC,MAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE;YACrC,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClE,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE;QAClD,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;QACjF,GAAG,CAAC,QAAQ,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC;QACjF,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC9E,SAAS,EAAE,QAAQ,CAAC,SAAS;QAC7B,GAAG,CAAC,QAAQ,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QACtG,OAAO;KACR,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CACrC,GAAmB;IAEnB,MAAM,UAAU,GAA4B;QAC1C,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,CAAC,OAAO;KACrB,CAAC;IACF,mEAAmE;IACnE,iEAAiE;IACjE,oEAAoE;IACpE,2DAA2D;IAC3D,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,UAAU,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACnC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/api/fetch-transport-helpers.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared fetch-transport helpers (R-v0.8-NEW-11, v0.8). Both transport
+ * seams — the JSON `client.request`-over-`fetch` seam in
+ * `transport.ts` and the multipart `add_file_to_column`-over-`/v2/file`
+ * seam in `multipart-transport.ts` — need the same four primitives:
+ * a URL-/token-free fetch-error descriptor, an abort-vs-real-error
+ * discriminator, a `Headers` → record flattener, and an N-way
+ * `AbortSignal` combiner. Before this lift each module carried a
+ * verbatim-or-near-verbatim private copy; the multipart docstrings
+ * literally read "Mirrors `transport.ts:describeFetchError`" /
+ * "Mirrors `transport.ts:combineSignals`".
+ *
+ * **Why consolidate — not just tidy-up dedupe:**
+ *
+ *   1. **One test set covers the shared defensive branches once.** The
+ *      `describeFetchError` TLS `UNABLE_TO_*` arm + `combineSignals`'s
+ *      empty-input guard were uncovered in BOTH copies — duplicated
+ *      uncovered branches that dragged global branch coverage below the
+ *      95.45% floor (R-v0.8-NEW-10, CI red). A single direct unit test
+ *      on the shared module exercises every arm once instead of
+ *      relying on two transports to drive each copy through `fetch`.
+ *   2. **The two `combineSignals` had already DRIFTED.**
+ *      `transport.ts` hedged behind `typeof AbortSignal.any ===
+ *      'function'` + a legacy Node-<19 controller fallback;
+ *      `multipart-transport.ts` assumed `AbortSignal.any` exists. The
+ *      lift keeps `transport.ts`'s fallback — the safer SUPERSET — so a
+ *      downstream embedder on an older Node still gets correct signal
+ *      combination (R-v0.8-NEW-11 over-fit watch: the divergence is
+ *      real, not cosmetic; do NOT collapse to multipart's narrower
+ *      form).
+ *   3. **The fetch-error vocabulary is a contract surface.** Agents
+ *      reading either transport's `error.message` see the SAME
+ *      `connection refused` / `dns lookup failed` / `tls error`
+ *      strings regardless of which seam issued the call — convergence
+ *      was already an explicit goal in the old multipart docstring
+ *      ("keep messaging stable across the JSON + multipart paths").
+ *
+ * This is helper-sharing, NOT a merge of the two transport seams —
+ * they keep separate modules + separate `Transport` /
+ * `MultipartTransport` interfaces per their different bodies (JSON
+ * `body: JSON.stringify(...)` vs `FormData` multipart). See
+ * `docs/architecture.md` "Wire-vs-CLI semantics documentation
+ * conventions" (R-NEW-41) for why the seams stay split.
+ */
+/**
+ * True for `fetch` rejections that mean "the request was aborted"
+ * (caller cancellation OR `AbortSignal.timeout`) rather than a real
+ * network failure. Callers use it to discriminate timeout from
+ * network_error: the timeout signal won iff the caller's own signal
+ * didn't fire first.
+ */
+export declare const isAbortError: (err: unknown) => boolean;
+/**
+ * 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`
+ */
+export declare const describeFetchError: (err: unknown) => string;
+/**
+ * Flattens a `fetch` `Headers` instance into a plain record so the
+ * transport's `TransportResponse` / `MultipartTransportResponse` carry
+ * an inert snapshot (not a live `Headers` object) past the transport
+ * boundary.
+ */
+export declare const headersToRecord: (headers: Headers) => Readonly<Record<string, string>>;
+/**
+ * Combines N optional `AbortSignal`s into one. The repo's Node 22+ pin
+ * always provides the platform `AbortSignal.any`, so that is the live,
+ * tested path; a legacy controller fallback ({@link combineSignalsLegacy})
+ * is kept for hypothetical downstream embedders on Node < 19.
+ *
+ * The fallback is `transport.ts`'s original — the safer SUPERSET kept
+ * deliberately over `multipart-transport.ts`'s narrower "assume
+ * `AbortSignal.any` exists" form (R-v0.8-NEW-11 over-fit watch). Only
+ * the feature-detect guard + the unreachable fallback are c8-ignored;
+ * the reachable `AbortSignal.any(real)` path stays counted so a
+ * regression in the multi-signal combination surfaces in coverage
+ * (Codex R1 P2-1).
+ */
+export declare const combineSignals: (...signals: readonly (AbortSignal | undefined)[]) => AbortSignal;
+//# sourceMappingURL=fetch-transport-helpers.d.ts.map

package/dist/api/fetch-transport-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-transport-helpers.d.ts","sourceRoot":"","sources":["../../src/api/fetch-transport-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,OAAO,KAAG,OAK3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,MA8BjD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,OAAO,KACf,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMjC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GACzB,GAAG,SAAS,SAAS,CAAC,WAAW,GAAG,SAAS,CAAC,EAAE,KAC/C,WAkBF,CAAC"}

package/dist/api/fetch-transport-helpers.js

@@ -0,0 +1,175 @@
+/**
+ * Shared fetch-transport helpers (R-v0.8-NEW-11, v0.8). Both transport
+ * seams — the JSON `client.request`-over-`fetch` seam in
+ * `transport.ts` and the multipart `add_file_to_column`-over-`/v2/file`
+ * seam in `multipart-transport.ts` — need the same four primitives:
+ * a URL-/token-free fetch-error descriptor, an abort-vs-real-error
+ * discriminator, a `Headers` → record flattener, and an N-way
+ * `AbortSignal` combiner. Before this lift each module carried a
+ * verbatim-or-near-verbatim private copy; the multipart docstrings
+ * literally read "Mirrors `transport.ts:describeFetchError`" /
+ * "Mirrors `transport.ts:combineSignals`".
+ *
+ * **Why consolidate — not just tidy-up dedupe:**
+ *
+ *   1. **One test set covers the shared defensive branches once.** The
+ *      `describeFetchError` TLS `UNABLE_TO_*` arm + `combineSignals`'s
+ *      empty-input guard were uncovered in BOTH copies — duplicated
+ *      uncovered branches that dragged global branch coverage below the
+ *      95.45% floor (R-v0.8-NEW-10, CI red). A single direct unit test
+ *      on the shared module exercises every arm once instead of
+ *      relying on two transports to drive each copy through `fetch`.
+ *   2. **The two `combineSignals` had already DRIFTED.**
+ *      `transport.ts` hedged behind `typeof AbortSignal.any ===
+ *      'function'` + a legacy Node-<19 controller fallback;
+ *      `multipart-transport.ts` assumed `AbortSignal.any` exists. The
+ *      lift keeps `transport.ts`'s fallback — the safer SUPERSET — so a
+ *      downstream embedder on an older Node still gets correct signal
+ *      combination (R-v0.8-NEW-11 over-fit watch: the divergence is
+ *      real, not cosmetic; do NOT collapse to multipart's narrower
+ *      form).
+ *   3. **The fetch-error vocabulary is a contract surface.** Agents
+ *      reading either transport's `error.message` see the SAME
+ *      `connection refused` / `dns lookup failed` / `tls error`
+ *      strings regardless of which seam issued the call — convergence
+ *      was already an explicit goal in the old multipart docstring
+ *      ("keep messaging stable across the JSON + multipart paths").
+ *
+ * This is helper-sharing, NOT a merge of the two transport seams —
+ * they keep separate modules + separate `Transport` /
+ * `MultipartTransport` interfaces per their different bodies (JSON
+ * `body: JSON.stringify(...)` vs `FormData` multipart). See
+ * `docs/architecture.md` "Wire-vs-CLI semantics documentation
+ * conventions" (R-NEW-41) for why the seams stay split.
+ */
+import { errorCode } from '../utils/errors.js';
+/**
+ * True for `fetch` rejections that mean "the request was aborted"
+ * (caller cancellation OR `AbortSignal.timeout`) rather than a real
+ * network failure. Callers use it to discriminate timeout from
+ * network_error: the timeout signal won iff the caller's own signal
+ * didn't fire first.
+ */
+export 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`
+ */
+export const describeFetchError = (err) => {
+    if (err instanceof Error) {
+        const code = errorCode(err);
+        if (code !== undefined) {
+            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';
+};
+/**
+ * Flattens a `fetch` `Headers` instance into a plain record so the
+ * transport's `TransportResponse` / `MultipartTransportResponse` carry
+ * an inert snapshot (not a live `Headers` object) past the transport
+ * boundary.
+ */
+export const headersToRecord = (headers) => {
+    const out = {};
+    headers.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+};
+/**
+ * Combines N optional `AbortSignal`s into one. The repo's Node 22+ pin
+ * always provides the platform `AbortSignal.any`, so that is the live,
+ * tested path; a legacy controller fallback ({@link combineSignalsLegacy})
+ * is kept for hypothetical downstream embedders on Node < 19.
+ *
+ * The fallback is `transport.ts`'s original — the safer SUPERSET kept
+ * deliberately over `multipart-transport.ts`'s narrower "assume
+ * `AbortSignal.any` exists" form (R-v0.8-NEW-11 over-fit watch). Only
+ * the feature-detect guard + the unreachable fallback are c8-ignored;
+ * the reachable `AbortSignal.any(real)` path stays counted so a
+ * regression in the multi-signal combination surfaces in coverage
+ * (Codex R1 P2-1).
+ */
+export 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;
+    }
+    // Node 22+ always has `AbortSignal.any`; the feature-detect guard +
+    // its legacy branch are unreachable on the pin, so the guard line is
+    // c8-ignored — but `AbortSignal.any(real)` below is NOT, so the
+    // multi-signal path is still coverage-counted.
+    /* c8 ignore next 3 */
+    if (typeof AbortSignal.any !== 'function') {
+        return combineSignalsLegacy(real);
+    }
+    return AbortSignal.any(real);
+};
+/**
+ * Pre-`AbortSignal.any` controller fallback (Node < 19). Unreachable on
+ * the repo's Node 22+ pin — kept as the safer superset for downstream
+ * embedders and c8-ignored as a block (testing.md block-wrap rule).
+ */
+/* c8 ignore start */
+const combineSignalsLegacy = (real) => {
+    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=fetch-transport-helpers.js.map

package/dist/api/fetch-transport-helpers.js.map

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