monday-cli 0.2.0

package/dist/api/walk-pages.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Page-based pagination walker shared by every M3 list command
+ * (workspace / board / user / update). Codex M3 pass-1 §1 caught
+ * the original per-command walkers all looped without an upper
+ * bound — `--all` against a misbehaving fixture or proxy that kept
+ * returning a full page would burn quota until timeout.
+ *
+ * The walker:
+ *   - always issues at least one request (the bare `monday X list`
+ *     case calls this with `all: false` and `page: 1`);
+ *   - on a short page (`< limit`) terminates with `hasMore: false`;
+ *   - on a full page with `all: true`, increments and continues;
+ *   - on hitting `maxPages`, stops and reports `hasMore: true` —
+ *     the caller raises a `pagination_cap_reached` warning so the
+ *     agent knows the result is truncated.
+ *
+ * Cursor-based pagination (M4 `item list`) gets its own walker —
+ * §5.6 calls out the stale-cursor contract and the silent-retry
+ * forbid that doesn't apply to page-based reads.
+ */
+import type { MondayResponse } from './client.js';
+export interface WalkPagesInputs<T, R> {
+    /**
+     * Per-page request executor. Receives the 1-indexed page number,
+     * returns the typed `MondayResponse<R>` of one page. The walker
+     * accumulates the projection.
+     */
+    readonly fetchPage: (page: number) => Promise<MondayResponse<R>>;
+    /**
+     * Extracts the array of items from one page's response. Returning
+     * an empty array signals exhaustion (no further pages).
+     */
+    readonly extractItems: (response: MondayResponse<R>) => readonly T[];
+    /** Page size the caller passed to the GraphQL query. Used to
+     *  tell whether a returned page is "full" (= maybe more) vs
+     *  "short" (= terminal). */
+    readonly pageSize: number;
+    /** Honour the `--all` flag. */
+    readonly all: boolean;
+    /**
+     * 1-indexed starting page. When `all: false` and `startPage`
+     * is set, the walker fetches exactly that page. Default 1.
+     */
+    readonly startPage?: number;
+    /**
+     * Hard cap on pages to walk under `--all`. Per Codex M3 pass-1 §1,
+     * every list command must cap; the caller propagates this through
+     * `--limit-pages`. Default in caller, surfaced as a usage option.
+     */
+    readonly maxPages: number;
+    /**
+     * Streaming hook for the NDJSON output mode (§6.3). Called once
+     * per emitted item, in the per-page arrival order returned by
+     * `extractItems` (page-walked queries don't sort — Monday's
+     * server-side ordering wins). `await`ed so a slow downstream
+     * consumer (a piped `jq`) backpressures the walker — same shape
+     * as `paginate.onItem`. Mirrors `pagination.ts:369` push-then-
+     * await ordering exactly: the item lands in `collected` before
+     * the hook awaits, so a hook throwing mid-page leaves a
+     * deterministic prefix in `result.items` (Codex M18 pre-flight
+     * P3-1).
+     */
+    readonly onItem?: (item: T) => void | Promise<void>;
+}
+export interface WalkPagesResult<T, R> {
+    /** All items collected across walked pages, in arrival order. */
+    readonly items: readonly T[];
+    /** The final response — used for `meta.complexity` etc. */
+    readonly lastResponse: MondayResponse<R>;
+    /**
+     * `true` when the walker stopped early (cap hit on a still-full
+     * page). Drives a `pagination_cap_reached` warning at the caller;
+     * also lands on `meta.has_more`.
+     */
+    readonly hasMore: boolean;
+    /** How many pages the walker actually fetched. */
+    readonly pagesFetched: number;
+}
+export declare const walkPages: <T, R>(inputs: WalkPagesInputs<T, R>) => Promise<WalkPagesResult<T, R>>;
+export interface PaginationCapWarning {
+    readonly code: 'pagination_cap_reached';
+    readonly message: string;
+    readonly details: {
+        readonly pages_walked: number;
+        readonly hint: string;
+    };
+}
+export declare const buildCapWarning: (pagesWalked: number, flagName?: string) => PaginationCapWarning;
+/** Default cap shared by every M3 list command's `--all` walk. */
+export declare const DEFAULT_MAX_PAGES = 50;
+//# sourceMappingURL=walk-pages.d.ts.map

package/dist/api/walk-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-pages.d.ts","sourceRoot":"","sources":["../../src/api/walk-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,EAAE,CAAC;IACrE;;gCAE4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAmBD,eAAO,MAAM,SAAS,GAAU,CAAC,EAAE,CAAC,EAClC,QAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,KAC5B,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CA4C/B,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,GAC1B,aAAa,MAAM,EACnB,iBAA0B,KACzB,oBAOD,CAAC;AAEH,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,KAAK,CAAC"}

package/dist/api/walk-pages.js

@@ -0,0 +1,84 @@
+/**
+ * Page-based pagination walker shared by every M3 list command
+ * (workspace / board / user / update). Codex M3 pass-1 §1 caught
+ * the original per-command walkers all looped without an upper
+ * bound — `--all` against a misbehaving fixture or proxy that kept
+ * returning a full page would burn quota until timeout.
+ *
+ * The walker:
+ *   - always issues at least one request (the bare `monday X list`
+ *     case calls this with `all: false` and `page: 1`);
+ *   - on a short page (`< limit`) terminates with `hasMore: false`;
+ *   - on a full page with `all: true`, increments and continues;
+ *   - on hitting `maxPages`, stops and reports `hasMore: true` —
+ *     the caller raises a `pagination_cap_reached` warning so the
+ *     agent knows the result is truncated.
+ *
+ * Cursor-based pagination (M4 `item list`) gets its own walker —
+ * §5.6 calls out the stale-cursor contract and the silent-retry
+ * forbid that doesn't apply to page-based reads.
+ */
+const emitPageItems = async (items, collected, onItem) => {
+    // Push-then-await ordering — same as `paginate.emitItems` at
+    // pagination.ts:369. The item lands in `collected` before the
+    // hook awaits, so a hook throwing mid-page leaves a deterministic
+    // prefix in `result.items` (Codex M18 pre-flight P3-1).
+    for (const item of items) {
+        collected.push(item);
+        if (onItem !== undefined) {
+            await onItem(item);
+        }
+    }
+};
+export const walkPages = async (inputs) => {
+    const { fetchPage, extractItems, pageSize, all, maxPages, onItem } = inputs;
+    const startPage = inputs.startPage ?? 1;
+    // First request always runs. Page count includes this attempt.
+    let lastResponse = await fetchPage(startPage);
+    const collected = [];
+    let pagesFetched = 1;
+    const firstPage = extractItems(lastResponse);
+    await emitPageItems(firstPage, collected, onItem);
+    // No-walk case: caller asked for one page only.
+    if (!all) {
+        return {
+            items: collected,
+            lastResponse,
+            hasMore: firstPage.length === pageSize,
+            pagesFetched,
+        };
+    }
+    // Walk while pages are full and we're under the cap. Empty page or
+    // short page terminates the walk; cap hit on a full page surfaces
+    // hasMore=true so the caller can warn.
+    if (firstPage.length === 0 || firstPage.length < pageSize) {
+        return { items: collected, lastResponse, hasMore: false, pagesFetched };
+    }
+    let page = startPage + 1;
+    while (pagesFetched < maxPages) {
+        lastResponse = await fetchPage(page);
+        pagesFetched++;
+        const pageData = extractItems(lastResponse);
+        if (pageData.length === 0) {
+            return { items: collected, lastResponse, hasMore: false, pagesFetched };
+        }
+        await emitPageItems(pageData, collected, onItem);
+        if (pageData.length < pageSize) {
+            return { items: collected, lastResponse, hasMore: false, pagesFetched };
+        }
+        page++;
+    }
+    // Cap hit on a full page — more might exist.
+    return { items: collected, lastResponse, hasMore: true, pagesFetched };
+};
+export const buildCapWarning = (pagesWalked, flagName = '--limit-pages') => ({
+    code: 'pagination_cap_reached',
+    message: `--all stopped after ${String(pagesWalked)} pages; more results may exist`,
+    details: {
+        pages_walked: pagesWalked,
+        hint: `Increase ${flagName} or narrow the query (e.g. --workspace, --state).`,
+    },
+});
+/** Default cap shared by every M3 list command's `--all` walk. */
+export const DEFAULT_MAX_PAGES = 50;
+//# sourceMappingURL=walk-pages.js.map

package/dist/api/walk-pages.js.map

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

package/dist/api/workspace-projection.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Workspace projection schema + GraphQL field-fragment, lifted from
+ * the four M14 mutation verbs and `workspace get` (v0.2-plan §22
+ * R39).
+ *
+ * **R39 — `WORKSPACE_FIELDS_FRAGMENT`.** The shared GraphQL selection
+ * set every with-settings workspace verb uses appeared in five query
+ * strings: `workspace get` (M14), `workspace create` (M14), `workspace
+ * update`'s preflight read + mutation (M14), `workspace delete` (M14).
+ * Five consumers; well above the §17 R-timing trigger. Mirrors
+ * `ITEM_FIELDS_FRAGMENT` (M5b lift in `item-helpers.ts`) and
+ * `UPDATE_FIELDS_FRAGMENT` (R38 lift in `update-mutation-result.ts`).
+ * 6-space continuation indent matches the column every consumer
+ * interpolates `${WORKSPACE_FIELDS_FRAGMENT}` at, so rendered query
+ * bytes are unchanged post-lift.
+ *
+ * **R39 — `workspaceProjectionSchema`.** The matching strict zod
+ * projection schema. Pre-lift it lived at
+ * `src/commands/workspace/get.ts:50` as `workspaceGetOutputSchema`,
+ * and the four mutation verbs each imported it from there — the
+ * file colocation was incidental rather than intentional. Lifting
+ * the schema next to the fragment keeps the projection's two halves
+ * (wire-shape selector + parser) in one place.
+ *
+ * **`workspace list` stays distinct.** Its narrower output (no
+ * `settings.icon`) and parallel narrower GraphQL string serve a
+ * different surface; extending it to share this fragment would
+ * surface `settings.icon` on `workspace list`'s output as a
+ * SemVer-minor additive change. R39's minimal scope keeps list
+ * untouched.
+ */
+import { z } from 'zod';
+/**
+ * Shared GraphQL selection set for the workspace shape — every M14
+ * mutation verb plus M14's `workspace get` (the with-settings path)
+ * select these fields. 6-space continuation indent matches the
+ * column every consumer interpolates `${WORKSPACE_FIELDS_FRAGMENT}`
+ * at, so rendered query bytes are unchanged post-lift.
+ */
+export declare const WORKSPACE_FIELDS_FRAGMENT = "id\n      name\n      description\n      kind\n      state\n      is_default_workspace\n      created_at\n      settings {\n        icon {\n          color\n          image\n        }\n      }";
+/**
+ * Strict zod schema for the workspace projection — the exact shape
+ * `WORKSPACE_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * `workspace get` / `create` / `update` / `delete`; each verb's
+ * `CommandModule.outputSchema` aliases this so the schema-export
+ * pipeline emits one canonical shape.
+ */
+export declare const workspaceProjectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    kind: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    is_default_workspace: z.ZodNullable<z.ZodBoolean>;
+    created_at: z.ZodNullable<z.ZodString>;
+    settings: z.ZodNullable<z.ZodObject<{
+        icon: z.ZodNullable<z.ZodObject<{
+            color: z.ZodNullable<z.ZodString>;
+            image: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkspaceProjection = z.infer<typeof workspaceProjectionSchema>;
+//# sourceMappingURL=workspace-projection.d.ts.map

package/dist/api/workspace-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-projection.d.ts","sourceRoot":"","sources":["../../src/api/workspace-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,qMAY9B,CAAC;AAeT;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;kBAW3B,CAAC;AAEZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/api/workspace-projection.js

@@ -0,0 +1,83 @@
+/**
+ * Workspace projection schema + GraphQL field-fragment, lifted from
+ * the four M14 mutation verbs and `workspace get` (v0.2-plan §22
+ * R39).
+ *
+ * **R39 — `WORKSPACE_FIELDS_FRAGMENT`.** The shared GraphQL selection
+ * set every with-settings workspace verb uses appeared in five query
+ * strings: `workspace get` (M14), `workspace create` (M14), `workspace
+ * update`'s preflight read + mutation (M14), `workspace delete` (M14).
+ * Five consumers; well above the §17 R-timing trigger. Mirrors
+ * `ITEM_FIELDS_FRAGMENT` (M5b lift in `item-helpers.ts`) and
+ * `UPDATE_FIELDS_FRAGMENT` (R38 lift in `update-mutation-result.ts`).
+ * 6-space continuation indent matches the column every consumer
+ * interpolates `${WORKSPACE_FIELDS_FRAGMENT}` at, so rendered query
+ * bytes are unchanged post-lift.
+ *
+ * **R39 — `workspaceProjectionSchema`.** The matching strict zod
+ * projection schema. Pre-lift it lived at
+ * `src/commands/workspace/get.ts:50` as `workspaceGetOutputSchema`,
+ * and the four mutation verbs each imported it from there — the
+ * file colocation was incidental rather than intentional. Lifting
+ * the schema next to the fragment keeps the projection's two halves
+ * (wire-shape selector + parser) in one place.
+ *
+ * **`workspace list` stays distinct.** Its narrower output (no
+ * `settings.icon`) and parallel narrower GraphQL string serve a
+ * different surface; extending it to share this fragment would
+ * surface `settings.icon` on `workspace list`'s output as a
+ * SemVer-minor additive change. R39's minimal scope keeps list
+ * untouched.
+ */
+import { z } from 'zod';
+/**
+ * Shared GraphQL selection set for the workspace shape — every M14
+ * mutation verb plus M14's `workspace get` (the with-settings path)
+ * select these fields. 6-space continuation indent matches the
+ * column every consumer interpolates `${WORKSPACE_FIELDS_FRAGMENT}`
+ * at, so rendered query bytes are unchanged post-lift.
+ */
+export const WORKSPACE_FIELDS_FRAGMENT = `id
+      name
+      description
+      kind
+      state
+      is_default_workspace
+      created_at
+      settings {
+        icon {
+          color
+          image
+        }
+      }`;
+const iconSchema = z
+    .object({
+    color: z.string().nullable(),
+    image: z.string().nullable(),
+})
+    .strict();
+const settingsSchema = z
+    .object({
+    icon: iconSchema.nullable(),
+})
+    .strict();
+/**
+ * Strict zod schema for the workspace projection — the exact shape
+ * `WORKSPACE_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * `workspace get` / `create` / `update` / `delete`; each verb's
+ * `CommandModule.outputSchema` aliases this so the schema-export
+ * pipeline emits one canonical shape.
+ */
+export const workspaceProjectionSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    description: z.string().nullable(),
+    kind: z.string().nullable(),
+    state: z.string().nullable(),
+    is_default_workspace: z.boolean().nullable(),
+    created_at: z.string().nullable(),
+    settings: settingsSchema.nullable(),
+})
+    .strict();
+//# sourceMappingURL=workspace-projection.js.map

package/dist/api/workspace-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-projection.js","sourceRoot":"","sources":["../../src/api/workspace-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;;;;;;;QAYjC,CAAC;AAET,MAAM,UAAU,GAAG,CAAC;KACjB,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE;CAC5B,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC;KACvC,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE;CACpC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/cli/envelope-out.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Envelope emission helpers (M2.5 R2).
+ *
+ * Pulled out of `cli/run.ts` so the runner stays focused on argv
+ * parsing, signal handling, and command registration.
+ *
+ * **Two paths, two channels, one source of truth.** The success and
+ * error envelopes report the same `api_version` and `source`, but
+ * they get there through different channels:
+ *
+ *   - **Success path.** `emit.ts` builds the success envelope from
+ *     options the action passed through `emitSuccess({apiVersion,
+ *     source, complexity, cacheAgeSeconds, ...})` — usually via the
+ *     `...toEmit(result)` splat returned by `resolveClient` (M2.5 R3).
+ *   - **Error path.** `writeErrorEnvelope` (this file) builds the
+ *     error envelope from `MetaBuilder.snapshot()` after the action
+ *     has thrown. The action commits values via
+ *     `ctx.meta.setApiVersion(v)` / `ctx.meta.setSource('live')`
+ *     before the network call goes out, so a thrown `ApiError` on
+ *     HTTP 401 still produces an envelope with the right meta.
+ *
+ * The two paths agree because `resolveClient` writes the *same*
+ * `apiVersion` / `source` into both: the `MetaBuilder` (for error
+ * fallback) and the `toEmit` closure (for success). An M3 command
+ * that calls `resolveClient` gets both for free; an M3 command that
+ * builds its own client must commit to both channels manually if it
+ * wants the same guarantee.
+ *
+ * **Why a builder, not a setter callback.** The M2-era `setMetaHint`
+ * pattern (commit `5e211bc`) worked but coupled the action body to a
+ * mutable `MetaHint` record on `ctx`; tracing "what `meta` will the
+ * error envelope carry" required grepping every `setMetaHint` call
+ * site for shape drift. The builder closes that loop:
+ *
+ *   - typed setters (`setApiVersion`, `setSource`) enumerate exactly
+ *     what the error path can carry — adding a new field means adding
+ *     a new typed method + extending `MetaSnapshot`, not stuffing
+ *     another optional key into a shared record;
+ *   - the public surface is closed (no `set(key, value)` escape
+ *     hatch), so the only way to widen what the error envelope can
+ *     report is to extend this module deliberately;
+ *   - the M2 Codex review §2 incident — `--api-version 2026-04
+ *     account whoami` claiming `api_version: "2026-01"` on HTTP 401 —
+ *     was structurally caused by the two paths reading different
+ *     state. The builder is the error-side half of the fix; the
+ *     `toEmit` closure (R3) is the success-side half.
+ *
+ * Action sites stay terse: `ctx.meta.setApiVersion(v)` /
+ * `ctx.meta.setSource('live')` is the same shape the M2 callback
+ * had, just typed per-field rather than via a record literal.
+ */
+import { type DataSource, type Meta } from '../utils/output/envelope.js';
+import { MondayCliError } from '../utils/errors.js';
+export interface MetaSnapshot {
+    readonly apiVersion: string | undefined;
+    readonly source: DataSource | undefined;
+}
+export interface MetaBuilder {
+    /**
+     * Commit the resolved `API-Version` value the request will carry
+     * (or did carry, if the call already went out). The same value
+     * lands on `meta.api_version` in both the success envelope (via
+     * emit.ts) and the error envelope (via `writeErrorEnvelope`) —
+     * an HTTP 401 for `monday --api-version 2026-04 account whoami`
+     * reports `meta.api_version: "2026-04"`, not the SDK pin.
+     */
+    setApiVersion: (version: string) => void;
+    /**
+     * Commit the data-source the response came from — `live` for a
+     * fresh API call, `cache` for a hit, `mixed` for a partially-
+     * served response, `none` for local-only commands. Network
+     * commands set `live` before the wire goes out so an error
+     * envelope on the sad path still reports `source: live`.
+     */
+    setSource: (source: DataSource) => void;
+    /** Frozen view of every value committed so far. */
+    snapshot: () => MetaSnapshot;
+}
+export declare const createMetaBuilder: () => MetaBuilder;
+/**
+ * Collects literal secret values to scrub from emitted bytes. Read
+ * lazily — `loadConfig()` populates `MONDAY_API_TOKEN` from `.env`
+ * *after* the runner builds its context, so a snapshot at runner
+ * construction time would miss tokens that exist only in the `.env`
+ * file (Codex review §1 follow-up). `env` is shared by reference
+ * with the runner; re-reading at emit time observes any side-
+ * effecting load.
+ */
+export declare const collectSecrets: (env: NodeJS.ProcessEnv) => readonly string[];
+export interface BuildBaseMetaInputs {
+    readonly snapshot: MetaSnapshot;
+    readonly env: NodeJS.ProcessEnv;
+    readonly cliVersion: string;
+    readonly requestId: string;
+    readonly retrievedAt: string;
+}
+/**
+ * Constructs `meta` for an envelope where no action-resolved
+ * complexity / cache-age is in scope (the error path; commands that
+ * never reached emit.ts). `api_version` falls back to
+ * `MONDAY_API_VERSION` env / SDK pin when the action didn't commit
+ * one through the builder.
+ */
+export declare const buildBaseMeta: (inputs: BuildBaseMetaInputs) => Meta;
+export interface WriteErrorEnvelopeOptions {
+    readonly stderr: NodeJS.WritableStream;
+    readonly env: NodeJS.ProcessEnv;
+    readonly meta: Meta;
+}
+/**
+ * Renders the error envelope to `stderr` with two-layer redaction
+ * (key-based + value-scan over the live token). Re-reads `env` for
+ * the value-scan layer so a token loaded from `.env` mid-run is
+ * still scrubbed (security.md "Redaction in output").
+ */
+export declare const writeErrorEnvelope: (err: MondayCliError, options: WriteErrorEnvelopeOptions) => void;
+/**
+ * Maps an arbitrary thrown value into the `MondayCliError` family the
+ * envelope path expects. `MondayCliError` instances pass through;
+ * commander parsing failures become `UsageError`; unknown thrown
+ * values become `InternalError` with the original cause attached.
+ *
+ * Lives here (not in `errors.ts`) because the conversion is part of
+ * the runner-→-envelope path: it's the precondition for
+ * `writeErrorEnvelope`.
+ */
+export declare const toMondayError: (err: unknown) => MondayCliError;
+//# sourceMappingURL=envelope-out.d.ts.map

package/dist/cli/envelope-out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-out.d.ts","sourceRoot":"","sources":["../../src/cli/envelope-out.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAGH,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,IAAI,EACV,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAEL,cAAc,EAEf,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,YAAY,CAAC;CAC9B;AAED,eAAO,MAAM,iBAAiB,QAAO,WAYpC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,KAAK,MAAM,CAAC,UAAU,KACrB,SAAS,MAAM,EAOjB,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,mBAAmB,KAAG,IAWxD,CAAC;AAEL,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,cAAc,EACnB,SAAS,yBAAyB,KACjC,IAMF,CAAC;AAKF;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,cAoB5C,CAAC"}

package/dist/cli/envelope-out.js

@@ -0,0 +1,146 @@
+/**
+ * Envelope emission helpers (M2.5 R2).
+ *
+ * Pulled out of `cli/run.ts` so the runner stays focused on argv
+ * parsing, signal handling, and command registration.
+ *
+ * **Two paths, two channels, one source of truth.** The success and
+ * error envelopes report the same `api_version` and `source`, but
+ * they get there through different channels:
+ *
+ *   - **Success path.** `emit.ts` builds the success envelope from
+ *     options the action passed through `emitSuccess({apiVersion,
+ *     source, complexity, cacheAgeSeconds, ...})` — usually via the
+ *     `...toEmit(result)` splat returned by `resolveClient` (M2.5 R3).
+ *   - **Error path.** `writeErrorEnvelope` (this file) builds the
+ *     error envelope from `MetaBuilder.snapshot()` after the action
+ *     has thrown. The action commits values via
+ *     `ctx.meta.setApiVersion(v)` / `ctx.meta.setSource('live')`
+ *     before the network call goes out, so a thrown `ApiError` on
+ *     HTTP 401 still produces an envelope with the right meta.
+ *
+ * The two paths agree because `resolveClient` writes the *same*
+ * `apiVersion` / `source` into both: the `MetaBuilder` (for error
+ * fallback) and the `toEmit` closure (for success). An M3 command
+ * that calls `resolveClient` gets both for free; an M3 command that
+ * builds its own client must commit to both channels manually if it
+ * wants the same guarantee.
+ *
+ * **Why a builder, not a setter callback.** The M2-era `setMetaHint`
+ * pattern (commit `5e211bc`) worked but coupled the action body to a
+ * mutable `MetaHint` record on `ctx`; tracing "what `meta` will the
+ * error envelope carry" required grepping every `setMetaHint` call
+ * site for shape drift. The builder closes that loop:
+ *
+ *   - typed setters (`setApiVersion`, `setSource`) enumerate exactly
+ *     what the error path can carry — adding a new field means adding
+ *     a new typed method + extending `MetaSnapshot`, not stuffing
+ *     another optional key into a shared record;
+ *   - the public surface is closed (no `set(key, value)` escape
+ *     hatch), so the only way to widen what the error envelope can
+ *     report is to extend this module deliberately;
+ *   - the M2 Codex review §2 incident — `--api-version 2026-04
+ *     account whoami` claiming `api_version: "2026-01"` on HTTP 401 —
+ *     was structurally caused by the two paths reading different
+ *     state. The builder is the error-side half of the fix; the
+ *     `toEmit` closure (R3) is the success-side half.
+ *
+ * Action sites stay terse: `ctx.meta.setApiVersion(v)` /
+ * `ctx.meta.setSource('live')` is the same shape the M2 callback
+ * had, just typed per-field rather than via a record literal.
+ */
+import { CommanderError } from 'commander';
+import { buildError, buildMeta, } from '../utils/output/envelope.js';
+import { redact } from '../utils/redact.js';
+import { InternalError, MondayCliError, UsageError, } from '../utils/errors.js';
+export const createMetaBuilder = () => {
+    let apiVersion;
+    let source;
+    return {
+        setApiVersion: (v) => {
+            apiVersion = v;
+        },
+        setSource: (s) => {
+            source = s;
+        },
+        snapshot: () => ({ apiVersion, source }),
+    };
+};
+/**
+ * Collects literal secret values to scrub from emitted bytes. Read
+ * lazily — `loadConfig()` populates `MONDAY_API_TOKEN` from `.env`
+ * *after* the runner builds its context, so a snapshot at runner
+ * construction time would miss tokens that exist only in the `.env`
+ * file (Codex review §1 follow-up). `env` is shared by reference
+ * with the runner; re-reading at emit time observes any side-
+ * effecting load.
+ */
+export const collectSecrets = (env) => {
+    const out = [];
+    const token = env.MONDAY_API_TOKEN;
+    if (token !== undefined && token.length > 0) {
+        out.push(token);
+    }
+    return out;
+};
+/**
+ * Constructs `meta` for an envelope where no action-resolved
+ * complexity / cache-age is in scope (the error path; commands that
+ * never reached emit.ts). `api_version` falls back to
+ * `MONDAY_API_VERSION` env / SDK pin when the action didn't commit
+ * one through the builder.
+ */
+export const buildBaseMeta = (inputs) => buildMeta({
+    api_version: inputs.snapshot.apiVersion ??
+        inputs.env.MONDAY_API_VERSION ??
+        '2026-01',
+    cli_version: inputs.cliVersion,
+    request_id: inputs.requestId,
+    source: inputs.snapshot.source ?? 'none',
+    retrieved_at: inputs.retrievedAt,
+    cache_age_seconds: null,
+});
+/**
+ * Renders the error envelope to `stderr` with two-layer redaction
+ * (key-based + value-scan over the live token). Re-reads `env` for
+ * the value-scan layer so a token loaded from `.env` mid-run is
+ * still scrubbed (security.md "Redaction in output").
+ */
+export const writeErrorEnvelope = (err, options) => {
+    const envelope = buildError(err, options.meta);
+    const redacted = redact(envelope, {
+        secrets: collectSecrets(options.env),
+    });
+    options.stderr.write(`${JSON.stringify(redacted, null, 2)}\n`);
+};
+const isCommanderError = (err) => err instanceof CommanderError;
+/**
+ * Maps an arbitrary thrown value into the `MondayCliError` family the
+ * envelope path expects. `MondayCliError` instances pass through;
+ * commander parsing failures become `UsageError`; unknown thrown
+ * values become `InternalError` with the original cause attached.
+ *
+ * Lives here (not in `errors.ts`) because the conversion is part of
+ * the runner-→-envelope path: it's the precondition for
+ * `writeErrorEnvelope`.
+ */
+export const toMondayError = (err) => {
+    if (err instanceof MondayCliError) {
+        return err;
+    }
+    if (isCommanderError(err)) {
+        // Commander surfaces both --help/--version and parsing failures
+        // as CommanderError. The success-style ones carry exitCode 0;
+        // those aren't errors and we never reach this function with one.
+        if (err.code === 'commander.helpDisplayed' ||
+            err.code === 'commander.version') {
+            return new InternalError(`unexpected commander success: ${err.code}`);
+        }
+        return new UsageError(err.message);
+    }
+    if (err instanceof Error) {
+        return new InternalError(err.message, { cause: err });
+    }
+    return new InternalError('unknown error', { cause: err });
+};
+//# sourceMappingURL=envelope-out.js.map

package/dist/cli/envelope-out.js.map

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

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}