monday-cli 0.2.0

package/dist/api/pagination.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Cursor-based pagination walker (`cli-design.md` §2.4 / §5.6,
+ * `v0.1-plan.md` §3 M4).
+ *
+ * The cursor walker is fundamentally different from `walk-pages.ts`'s
+ * page-based shape: Monday issues a 60-minute cursor on the *initial*
+ * `items_page` call and a stale cursor returns
+ * `INVALID_CURSOR_EXCEPTION` (mapped to `stale_cursor` by
+ * `api/errors.ts`). The §5.6 contract is **fail-fast on expiry —
+ * never silently re-issue the initial query**, because a re-issue
+ * between page N and the resumed walk can duplicate or skip items
+ * (board mutated, item archived, etc.). That's silent corruption;
+ * the design rejects it explicitly.
+ *
+ * **Result-type discipline (§14 M3 lesson, prophylactic adoption).**
+ * `PaginationWalkResult` carries every §6.1 + §6.3 meta slot from
+ * day one — `source`, `cacheAgeSeconds`, `complexity`, `warnings`,
+ * `nextCursor`, `hasMore`, `totalReturned`. M3's
+ * `BoardMetadataLoadResult` and `ResolveColumnWithRefreshResult`
+ * both under-budgeted their meta surface and grew during review;
+ * M4 starts complete. Cursor-paginated reads always run live
+ * (`source: 'live'`, `cacheAgeSeconds: null`) — the fields are
+ * present anyway so callers spread them without thinking about the
+ * branch.
+ *
+ * **Streaming hook (`onItem`).** Required for `item list --output
+ * ndjson` per §6.3 — items emit per-arrival, not after the whole
+ * walk collects. The walker calls `onItem` once per item *in
+ * per-page-sorted order* (the sort-by-ID pass per §3.1 #8 happens
+ * before the callback fires), then the trailer (the §6.3 `_meta`
+ * line) carries `next_cursor` / `has_more` / `total_returned`. If
+ * a stale cursor fires mid-walk, `onItem` has already emitted the
+ * pre-failure items; the caller produces the error envelope on
+ * stderr as documented in §6.3 / §6.5.
+ *
+ * **Cursor lifetime tracking.** The walker reads `now: () => Date`
+ * from inputs — production wires `ctx.clock`, tests inject a
+ * deterministic clock. The age is measured from the `now()` value
+ * captured *before* the initial request fires (so the test clock
+ * controls expiry deterministically; no wall-clock waits). On a
+ * mid-walk `stale_cursor` from Monday, the walker enriches the
+ * error's `details` with `cursor_age_seconds` /
+ * `items_returned_so_far` / `last_item_id` per §5.6.
+ */
+import type { MondayResponse } from './client.js';
+import type { Complexity, Warning } from '../utils/output/envelope.js';
+/**
+ * Monday's cursor lifetime per `cli-design.md` §2.4 / §5.6.
+ * Exported so a `--cursor-lifetime-seconds` flag (if ever added)
+ * can shadow it; for v0.1 it's a constant.
+ */
+export declare const CURSOR_LIFETIME_SECONDS: number;
+/**
+ * Default page size — Monday caps at 500 (§2.4). Most agent queries
+ * fit well under this; the walker's caller can override via
+ * `pageSize` to reduce per-request payload size when items carry a
+ * lot of column-value data.
+ */
+export declare const DEFAULT_PAGE_SIZE = 100;
+/**
+ * One page response from either `items_page` (initial) or
+ * `next_items_page` (subsequent). Caller's projector returns this
+ * shape from the GraphQL response; the walker doesn't know the
+ * specific GraphQL field path so the inputs decouple the two
+ * concerns.
+ */
+export interface PaginatedPage<T> {
+    readonly items: readonly T[];
+    /**
+     * `null` when the cursor walk is exhausted; a non-empty string
+     * otherwise. Monday's contract: the cursor returned alongside a
+     * page is the cursor for the *next* page, not a token covering
+     * the page just returned.
+     */
+    readonly cursor: string | null;
+}
+export interface PaginateInputs<T, R> {
+    /**
+     * Issues the initial `items_page` request with the supplied
+     * effective limit. Variables shape is the caller's concern;
+     * `effectiveLimit` is the per-request `limit:` to send on the
+     * GraphQL query. Codex M4 pass-2 §1: when `--limit < pageSize`
+     * the walker shrinks the request to the remaining budget so
+     * Monday's cursor doesn't advance past un-emitted rows.
+     */
+    readonly fetchInitial: (effectiveLimit: number) => Promise<MondayResponse<R>>;
+    /**
+     * Issues a `next_items_page(cursor:, limit:)` request with the
+     * supplied effective limit. Same rationale as `fetchInitial`.
+     */
+    readonly fetchNext: (cursor: string, effectiveLimit: number) => Promise<MondayResponse<R>>;
+    /**
+     * Projects a Monday response into the items + next cursor for one
+     * page. Returns `cursor: null` to terminate the walk.
+     */
+    readonly extractPage: (response: MondayResponse<R>) => PaginatedPage<T>;
+    /**
+     * Sort key for the per-page §3.1 #8 ascending-by-ID rule. The
+     * walker calls this once per item; small projector, runs in
+     * memory only.
+     */
+    readonly getId: (item: T) => string;
+    /**
+     * Honour the `--all` flag. False → fetch the first page only and
+     * return its cursor on the result (caller surfaces `next_cursor`
+     * on `meta`).
+     */
+    readonly all: boolean;
+    /**
+     * `--limit N` cap on total items collected across the walk. The
+     * walker stops mid-page when the cap is reached; the in-flight
+     * cursor is preserved on the result so the caller still surfaces
+     * `next_cursor` accurately. Undefined / 0 / negative → no cap.
+     */
+    readonly limit?: number;
+    /**
+     * Page size used for the GraphQL request — surfaced so the walker
+     * can apply the §2.4 ≤500 ceiling once and leave callers passing
+     * any value through. Defaults to {@link DEFAULT_PAGE_SIZE}.
+     */
+    readonly pageSize?: number;
+    /**
+     * Streaming hook for the NDJSON output mode (§6.3). Called once
+     * per emitted item, in the per-page sorted order. `await`ed so
+     * a slow downstream consumer (a piped `jq`) backpressures the
+     * walker — same shape as Node's writable stream.
+     */
+    readonly onItem?: (item: T) => void | Promise<void>;
+    /**
+     * Clock source for cursor-age tracking. Defaults to `Date.now()`
+     * via `() => new Date()`; tests inject a deterministic clock to
+     * exercise the 60-min expiry boundary without wall-clock waits.
+     */
+    readonly now?: () => Date;
+}
+export interface PaginationWalkResult<T, R> {
+    readonly items: readonly T[];
+    /**
+     * The final response — used for `meta.complexity`. Always present
+     * (even if the walk fetched a single page). Null only when the
+     * walk fetched zero pages, which the walker doesn't produce: at
+     * least the initial request runs.
+     */
+    readonly lastResponse: MondayResponse<R>;
+    /**
+     * Carries the cursor for the *next* page when more remains; null
+     * when the walk has run to exhaustion (Monday returned `null`) or
+     * stopped early on `--limit`. The walker does *not* pre-eject a
+     * cursor when `--all` ran to completion — agents reading
+     * `meta.next_cursor: null` know the walk is exhausted.
+     */
+    readonly nextCursor: string | null;
+    /**
+     * `true` when `--limit` short-circuited the walk on a still-full
+     * page, OR when `--all` was off and the initial page returned a
+     * non-null cursor. `false` when the walk ran to exhaustion.
+     */
+    readonly hasMore: boolean;
+    /** Pages actually fetched (1 = initial only). */
+    readonly pagesFetched: number;
+    /** §6.1 source — always `'live'` for cursor walks. */
+    readonly source: 'live';
+    /** Always null for cursor walks (no cache hits). */
+    readonly cacheAgeSeconds: number | null;
+    /**
+     * `meta.complexity` from the *last* response that came back —
+     * picks the freshest budget snapshot. Null when --verbose wasn't
+     * set (Monday only includes complexity when the operation
+     * selects it).
+     */
+    readonly complexity: Complexity | null;
+    /**
+     * Warnings the walker may surface. Empty in v0.1; reserved so
+     * future cap-style truncation (e.g. an aggregate per-walk hour
+     * limit) can fold a warning in without changing the result type.
+     */
+    readonly warnings: readonly Warning[];
+    /**
+     * Total items returned to the caller (after `--limit`). Mirrors
+     * `items.length` when streaming isn't used, but kept as an
+     * explicit slot so a future per-item filter (skipping malformed
+     * rows) can report a smaller surface than `items.length` would
+     * imply.
+     */
+    readonly totalReturned: number;
+}
+/**
+ * Walks a cursor-paginated Monday endpoint. See module header for
+ * the §5.6 contract. Throws on the first response that maps to a
+ * `stale_cursor` error; the thrown `ApiError` has `details` enriched
+ * with `cursor_age_seconds`, `items_returned_so_far`, and
+ * `last_item_id`.
+ */
+export declare const paginate: <T, R>(inputs: PaginateInputs<T, R>) => Promise<PaginationWalkResult<T, R>>;
+/**
+ * Whether the cursor age has exceeded the 60-min lifetime. Exposed
+ * as a pure helper so tests can pin the threshold without driving
+ * the full walker.
+ */
+export declare const isCursorExpired: (ageSeconds: number) => boolean;
+//# sourceMappingURL=pagination.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/api/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAU,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAeD,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC;IACxE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAID;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EACjC,QAAQ,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,KAC3B,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CA6HpC,CAAC;AAgGF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,MAAM,KAAG,OACd,CAAC"}

package/dist/api/pagination.js

@@ -0,0 +1,223 @@
+/**
+ * Cursor-based pagination walker (`cli-design.md` §2.4 / §5.6,
+ * `v0.1-plan.md` §3 M4).
+ *
+ * The cursor walker is fundamentally different from `walk-pages.ts`'s
+ * page-based shape: Monday issues a 60-minute cursor on the *initial*
+ * `items_page` call and a stale cursor returns
+ * `INVALID_CURSOR_EXCEPTION` (mapped to `stale_cursor` by
+ * `api/errors.ts`). The §5.6 contract is **fail-fast on expiry —
+ * never silently re-issue the initial query**, because a re-issue
+ * between page N and the resumed walk can duplicate or skip items
+ * (board mutated, item archived, etc.). That's silent corruption;
+ * the design rejects it explicitly.
+ *
+ * **Result-type discipline (§14 M3 lesson, prophylactic adoption).**
+ * `PaginationWalkResult` carries every §6.1 + §6.3 meta slot from
+ * day one — `source`, `cacheAgeSeconds`, `complexity`, `warnings`,
+ * `nextCursor`, `hasMore`, `totalReturned`. M3's
+ * `BoardMetadataLoadResult` and `ResolveColumnWithRefreshResult`
+ * both under-budgeted their meta surface and grew during review;
+ * M4 starts complete. Cursor-paginated reads always run live
+ * (`source: 'live'`, `cacheAgeSeconds: null`) — the fields are
+ * present anyway so callers spread them without thinking about the
+ * branch.
+ *
+ * **Streaming hook (`onItem`).** Required for `item list --output
+ * ndjson` per §6.3 — items emit per-arrival, not after the whole
+ * walk collects. The walker calls `onItem` once per item *in
+ * per-page-sorted order* (the sort-by-ID pass per §3.1 #8 happens
+ * before the callback fires), then the trailer (the §6.3 `_meta`
+ * line) carries `next_cursor` / `has_more` / `total_returned`. If
+ * a stale cursor fires mid-walk, `onItem` has already emitted the
+ * pre-failure items; the caller produces the error envelope on
+ * stderr as documented in §6.3 / §6.5.
+ *
+ * **Cursor lifetime tracking.** The walker reads `now: () => Date`
+ * from inputs — production wires `ctx.clock`, tests inject a
+ * deterministic clock. The age is measured from the `now()` value
+ * captured *before* the initial request fires (so the test clock
+ * controls expiry deterministically; no wall-clock waits). On a
+ * mid-walk `stale_cursor` from Monday, the walker enriches the
+ * error's `details` with `cursor_age_seconds` /
+ * `items_returned_so_far` / `last_item_id` per §5.6.
+ */
+import { ApiError } from '../utils/errors.js';
+import { sortByIdAsc } from './sort.js';
+/**
+ * Monday's cursor lifetime per `cli-design.md` §2.4 / §5.6.
+ * Exported so a `--cursor-lifetime-seconds` flag (if ever added)
+ * can shadow it; for v0.1 it's a constant.
+ */
+export const CURSOR_LIFETIME_SECONDS = 60 * 60;
+/**
+ * Default page size — Monday caps at 500 (§2.4). Most agent queries
+ * fit well under this; the walker's caller can override via
+ * `pageSize` to reduce per-request payload size when items carry a
+ * lot of column-value data.
+ */
+export const DEFAULT_PAGE_SIZE = 100;
+const wallClock = () => new Date();
+/**
+ * Walks a cursor-paginated Monday endpoint. See module header for
+ * the §5.6 contract. Throws on the first response that maps to a
+ * `stale_cursor` error; the thrown `ApiError` has `details` enriched
+ * with `cursor_age_seconds`, `items_returned_so_far`, and
+ * `last_item_id`.
+ */
+export const paginate = async (inputs) => {
+    const now = inputs.now ?? wallClock;
+    const startedAt = now();
+    const limit = (inputs.limit ?? 0) > 0 ? inputs.limit : undefined;
+    // Use the page size for diagnostics only — the actual request body
+    // is the caller's concern (it lives on `fetchInitial` / `fetchNext`).
+    // We still cap at 500 here as a forward-looking sanity check; if a
+    // future caller passes 1000, we want a deterministic crash, not a
+    // silent Monday-side rejection that's harder to debug.
+    const pageSize = Math.min(inputs.pageSize ?? DEFAULT_PAGE_SIZE, 500);
+    if (pageSize <= 0) {
+        throw new ApiError('internal_error', `paginate: pageSize must be positive, got ${String(pageSize)}`);
+    }
+    const collected = [];
+    let pagesFetched;
+    let lastResponse;
+    let cursor;
+    /**
+     * Per-call effective limit = `min(pageSize, remainingBudget)` so
+     * Monday's cursor advances over exactly the rows the walker emits.
+     * Without this, `--limit 2 --page-size 100` fetches 100 items,
+     * emits 2, and reports a cursor pointing past row 100 — agents
+     * resuming would skip rows 3-100 (Codex M4 pass-2 §1).
+     */
+    const callLimit = (collectedSoFar) => {
+        if (limit === undefined)
+            return pageSize;
+        const remaining = limit - collectedSoFar;
+        return remaining < pageSize ? remaining : pageSize;
+    };
+    // Initial request always runs. Wrap so a stale_cursor on the
+    // *initial* request still gets the standard envelope (Monday is
+    // unlikely to return that here — you'd have to re-use a cursor
+    // across processes — but the contract is symmetric).
+    try {
+        const first = await fetchPage(() => inputs.fetchInitial(callLimit(0)), inputs.extractPage);
+        lastResponse = first.response;
+        pagesFetched = 1;
+        const sorted = sortByIdAsc(first.page.items, inputs.getId);
+        const firstOutcome = await emitItems(sorted, collected, limit, inputs.onItem);
+        cursor = first.page.cursor;
+        // Caller asked for one page only. Surface the cursor verbatim;
+        // hasMore reflects whether Monday says there's more to read OR
+        // whether `--limit` truncated the page.
+        if (!inputs.all) {
+            return finish(collected, lastResponse, cursor, cursor !== null || firstOutcome.truncated, pagesFetched);
+        }
+        // `--limit` short-circuited mid-page (or exactly at boundary).
+        // Surface the in-flight cursor so the caller can resume; emit
+        // `hasMore: true` even when `next_cursor` is null because the
+        // truncation itself means more rows exist on this page.
+        if (limit !== undefined && collected.length >= limit) {
+            return finish(collected, lastResponse, cursor, cursor !== null || firstOutcome.truncated, pagesFetched);
+        }
+        // Walk until cursor exhaustion or limit hit.
+        while (cursor !== null) {
+            const cursorAt = cursor;
+            try {
+                const next = await fetchPage(() => inputs.fetchNext(cursorAt, callLimit(collected.length)), inputs.extractPage);
+                lastResponse = next.response;
+                pagesFetched++;
+                const sortedNext = sortByIdAsc(next.page.items, inputs.getId);
+                const outcome = await emitItems(sortedNext, collected, limit, inputs.onItem);
+                cursor = next.page.cursor;
+                if (limit !== undefined && collected.length >= limit) {
+                    return finish(collected, lastResponse, cursor, cursor !== null || outcome.truncated, pagesFetched);
+                }
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.code === 'stale_cursor') {
+                    throw enrichStaleCursor(err, {
+                        startedAt,
+                        now,
+                        collected,
+                        getId: inputs.getId,
+                    });
+                }
+                throw err;
+            }
+        }
+        return finish(collected, lastResponse, null, false, pagesFetched);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.code === 'stale_cursor') {
+            throw enrichStaleCursor(err, {
+                startedAt,
+                now,
+                collected,
+                getId: inputs.getId,
+            });
+        }
+        throw err;
+    }
+};
+const fetchPage = async (fetcher, extract) => {
+    const response = await fetcher();
+    return { response, page: extract(response) };
+};
+const emitItems = async (pageItems, collected, limit, onItem) => {
+    for (let i = 0; i < pageItems.length; i++) {
+        if (limit !== undefined && collected.length >= limit) {
+            // Items past index i are unconsumed — page had more than the
+            // remaining budget allowed.
+            return { truncated: i < pageItems.length };
+        }
+        const item = pageItems[i];
+        collected.push(item);
+        if (onItem !== undefined) {
+            await onItem(item);
+        }
+    }
+    return { truncated: false };
+};
+const finish = (items, lastResponse, nextCursor, hasMore, pagesFetched) => ({
+    items,
+    lastResponse,
+    nextCursor,
+    hasMore,
+    pagesFetched,
+    source: 'live',
+    cacheAgeSeconds: null,
+    complexity: lastResponse.complexity,
+    warnings: [],
+    totalReturned: items.length,
+});
+const enrichStaleCursor = (err, ctx) => {
+    const ageMs = ctx.now().getTime() - ctx.startedAt.getTime();
+    const cursor_age_seconds = Math.max(0, Math.floor(ageMs / 1000));
+    const last = ctx.collected[ctx.collected.length - 1];
+    const last_item_id = last === undefined ? null : ctx.getId(last);
+    const merged = {
+        ...(err.details ?? {}),
+        cursor_age_seconds,
+        cursor_lifetime_seconds: CURSOR_LIFETIME_SECONDS,
+        items_returned_so_far: ctx.collected.length,
+        last_item_id,
+    };
+    // Re-throw with the same code/message but enriched details.
+    // Keeping the original message verbatim so agents key off `code`
+    // and humans see Monday's prose.
+    return new ApiError('stale_cursor', err.message, {
+        ...(err.httpStatus === undefined ? {} : { httpStatus: err.httpStatus }),
+        ...(err.mondayCode === undefined ? {} : { mondayCode: err.mondayCode }),
+        ...(err.requestId === undefined ? {} : { requestId: err.requestId }),
+        retryable: false,
+        details: merged,
+        cause: err,
+    });
+};
+/**
+ * Whether the cursor age has exceeded the 60-min lifetime. Exposed
+ * as a pure helper so tests can pin the threshold without driving
+ * the full walker.
+ */
+export const isCursorExpired = (ageSeconds) => ageSeconds >= CURSOR_LIFETIME_SECONDS;
+//# sourceMappingURL=pagination.js.map

package/dist/api/pagination.js.map

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

package/dist/api/partial-success-mutation.d.ts

@@ -0,0 +1,28 @@
+/** A per-target result inside `data.results: [...]`. */
+export interface PartialSuccessResult {
+    readonly ok: boolean;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly [key: string]: unknown;
+}
+export interface PartialSuccessEnvelopeData {
+    readonly results: readonly PartialSuccessResult[];
+}
+/**
+ * Sequential per-target dispatch with shared error decoration. Each
+ * dispatch failure is captured into the result record's `error: {code,
+ * message}` slot rather than thrown — a per-target failure doesn't
+ * abort the loop. The whole-call contract: if dispatch ran, the
+ * envelope is `ok: true` regardless of per-target outcomes.
+ *
+ * Errors thrown that aren't `MondayCliError` propagate up — those are
+ * programmer bugs, not Monday-side failures, and the runner's catch-
+ * all maps them to `internal_error`.
+ */
+export interface DispatchOneTargetInputs<TargetId extends string> {
+    readonly targetId: TargetId;
+}
+export declare const dispatchSequential: <TargetId extends string>(targets: readonly TargetId[], idField: string, dispatch: (inputs: DispatchOneTargetInputs<TargetId>) => Promise<void>) => Promise<readonly PartialSuccessResult[]>;
+//# sourceMappingURL=partial-success-mutation.d.ts.map

package/dist/api/partial-success-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-success-mutation.d.ts","sourceRoot":"","sources":["../../src/api/partial-success-mutation.ts"],"names":[],"mappings":"AAuBA,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;IAIF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACnD;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB,CAAC,QAAQ,SAAS,MAAM;IAC9D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,eAAO,MAAM,kBAAkB,GAAU,QAAQ,SAAS,MAAM,EAC9D,SAAS,SAAS,QAAQ,EAAE,EAC5B,SAAS,MAAM,EACf,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,KACrE,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAqCzC,CAAC"}

package/dist/api/partial-success-mutation.js

@@ -0,0 +1,68 @@
+/**
+ * Partial-success mutation envelope builder (`cli-design.md` §6.4 +
+ * `v0.2-plan.md` §1 universal partial-success rule).
+ *
+ * Multi-target mutations (M13 `update clear-all`; M14 `workspace
+ * add-users` / `remove-users`; M15 `board add-users`) dispatch one
+ * wire call per target inside a sequential loop. The CLI emits **one
+ * success envelope** (`ok: true`) with per-target outcomes in
+ * `data.results: [...]`; each per-target record carries
+ * `{<target_id_field>: string, ok: true | false, error?: { code,
+ * message }}`. The id-field name is verb-specific (parameterised here
+ * via `idField`) so the JSON is self-documenting — `update_id` for
+ * `update clear-all`, `user_id` for the add/remove-users family.
+ *
+ * **Universal rule**: the envelope is always `ok: true` when dispatch
+ * ran. Top-level `ok: false` is reserved for whole-call failure
+ * (couldn't reach API, couldn't resolve any target before the loop
+ * began, an unrecoverable validation error before dispatch). All-
+ * failed-but-each-call-attempted is still `ok: true` — the agent
+ * reads `data.results` to determine outcomes.
+ */
+import { MondayCliError } from '../utils/errors.js';
+export const dispatchSequential = async (targets, idField, dispatch) => {
+    const results = [];
+    for (const targetId of targets) {
+        try {
+            await dispatch({ targetId });
+            // Build the result with the dynamic id-field name. Property
+            // assignment preserves insertion order (`<idField>` first, then
+            // `ok`) so the JSON shape stays stable across runs.
+            const ok = {
+                [idField]: targetId,
+                ok: true,
+            };
+            results.push(ok);
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                // Codex M14 round-2 F1: `internal_error` codes signal CLI
+                // bugs or Monday-side schema drift (e.g. response missing
+                // the mutation root key). Those are whole-call failures
+                // — papering over them with a per-record slot would hide
+                // the malformed-response signal that agents need to know
+                // about. Re-throw so the runner's catch-all surfaces it
+                // as the documented internal_error envelope.
+                if (err.code === 'internal_error')
+                    throw err;
+                const failed = {
+                    [idField]: targetId,
+                    ok: false,
+                    error: { code: err.code, message: err.message },
+                };
+                results.push(failed);
+                continue;
+            }
+            // Non-CLI errors are programmer bugs — let the runner catch-all
+            // surface as `internal_error`.
+            throw err;
+        }
+    }
+    return results;
+};
+// The output schema lives per-verb because the id-field key (`update_
+// id` / `user_id` / etc.) is dynamic and zod doesn't synthesise
+// per-call object keys cleanly. M14 will re-evaluate whether a schema
+// factory pulls weight; today each consumer writes a 6-line zod
+// schema and pays nothing for the duplication.
+//# sourceMappingURL=partial-success-mutation.js.map

package/dist/api/partial-success-mutation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-success-mutation.js","sourceRoot":"","sources":["../../src/api/partial-success-mutation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAkCpD,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,OAA4B,EAC5B,OAAe,EACf,QAAsE,EAC5B,EAAE;IAC5C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC7B,4DAA4D;YAC5D,gEAAgE;YAChE,oDAAoD;YACpD,MAAM,EAAE,GAAyB;gBAC/B,CAAC,OAAO,CAAC,EAAE,QAAQ;gBACnB,EAAE,EAAE,IAAI;aACT,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,0DAA0D;gBAC1D,0DAA0D;gBAC1D,wDAAwD;gBACxD,yDAAyD;gBACzD,yDAAyD;gBACzD,wDAAwD;gBACxD,6CAA6C;gBAC7C,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB;oBAAE,MAAM,GAAG,CAAC;gBAC7C,MAAM,MAAM,GAAyB;oBACnC,CAAC,OAAO,CAAC,EAAE,QAAQ;oBACnB,EAAE,EAAE,KAAK;oBACT,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE;iBAChD,CAAC;gBACF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,gEAAgE;YAChE,+BAA+B;YAC/B,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,sEAAsE;AACtE,gEAAgE;AAChE,sEAAsE;AACtE,gEAAgE;AAChE,+CAA+C"}