monday-cli 0.2.0 → 0.4.0

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

@@ -0,0 +1,436 @@
+/**
+ * Bulk per-item partial-success path for the v0.3-M25
+ * `item update --continue-on-error` flag (`cli-design.md` §6.4
+ * "Bulk per-item partial-success" sub-section).
+ *
+ * **What this module owns.** A thin wrapper around the selected
+ * per-target dispatcher — {@link dispatchSequential} from
+ * `src/api/partial-success-mutation.ts` (default / M25 path) OR
+ * {@link dispatchParallel} from `src/api/parallel-dispatch.ts`
+ * (v0.4-M30 `--concurrency > 1` path) — that drives the matched-
+ * item-ID list through one wire call per item, capturing per-
+ * item failures into the result records rather than aborting
+ * the loop. The wrapper sits BETWEEN the bulk command-action
+ * orchestrator (`src/commands/item/update.ts:runBulk`) and the
+ * shared dispatcher — the action body owns the matched-item-
+ * walk + column-resolution pre-pass + confirmation gate, then
+ * hands the resolved `SelectedMutation` + matched-item IDs to
+ * this wrapper, which fans them out + projects the partial-
+ * success envelope's `data.results[]` records.
+ *
+ * **Why a separate module rather than folding into update.ts.**
+ * Three reasons:
+ *
+ *   1. **Single-source-of-truth for the partial-success contract
+ *      surface.** M13 `update clear-all`, M14 `workspace
+ *      add-users` / `remove-users`, M15 `board add-users`, and
+ *      M25 `item update --continue-on-error` all share the
+ *      `{<id_field>, ok, error?}` per-record shape backed by
+ *      `dispatchSequential`. Keeping M25's wrapper next to its
+ *      family in `src/api/` (rather than buried in a command
+ *      file) keeps the family discoverable + makes future M27
+ *      bulk-write extensions (notification fan-out?) lift
+ *      cleanly into the same module.
+ *
+ *   2. **Action-body size budget.** `src/commands/item/update.ts`
+ *      already runs ~1100 LOC carrying both single-item +
+ *      v0.1 fail-fast bulk paths; adding the partial-success
+ *      branch inline would push it past 1300 and bury the
+ *      `dispatchSequential` integration. The action layer
+ *      branches on `parsed.continueOnError` and dispatches into
+ *      this module's `runPartialSuccessBulkUpdate` instead.
+ *
+ *   3. **Test surface ergonomics.** Per-item partial-success
+ *      tests (mock `client.raw` with a routing predicate that
+ *      flips success/failure per item-ID) read cleaner against
+ *      the wrapper's seam than against the action body's
+ *      branched control flow.
+ *
+ * **What stays at the action layer.** Argv-parse, column
+ * resolution, items_page walk, confirmation gate, dry-run path,
+ * source aggregation seed, and the universal-partial-success
+ * `ok: true` envelope assembly (via `emitMutation`). The
+ * wrapper returns the `data.results[]` array + the per-item
+ * source-leg fold; the action body wires that into the
+ * envelope it would have emitted on the v0.1 fail-fast bulk
+ * path's success branch.
+ *
+ * **Shipped at M25 IMPL (`fe15181`).** Pre-flight contract
+ * diff (`d5839a9`) pinned the module signatures + per-item
+ * result schema + pure-helper bodies; the M25 IMPL feat fills
+ * the runtime body of `runPartialSuccessBulkUpdate` + drops
+ * the `c8 ignore start/stop` block-wraps that surrounded both
+ * the wrapper body and the action-body routing branch at
+ * `src/commands/item/update.ts:runBulk`. The `executeMutation`
+ * lift to `src/api/item-mutation-execute.ts` (renamed
+ * `executeItemMutation`) shipped ahead at `78889df` (R-NEW-29
+ * 3-consumer trigger: single-item + fail-fast bulk + M25
+ * partial-success bulk).
+ *
+ * **v0.4-M30 extension.** Adds the `concurrency` input slot +
+ * the routing branch to {@link dispatchParallel} (new module
+ * `src/api/parallel-dispatch.ts` — runtime body landed at M30
+ * IMPL). When the caller passes `concurrency > 1`, the runtime
+ * fans out per-target dispatches via a bounded async-pool;
+ * absent or `concurrency === 1` preserves the M25 sequential
+ * path verbatim. The per-target dispatch closure is hoisted to
+ * a named local so both routes share the same
+ * `executeItemMutation` + `foldAndRemap` body — keeps the
+ * R-NEW-28 6-axis behavioral-equivalence audit straightforward.
+ * The M30 IMPL also threads an optional `signal?: AbortSignal`
+ * through both dispatchers (axis-6 scheduler short-circuit).
+ *
+ * **Per-item dispatch wiring.** Runtime body routes between
+ * {@link dispatchSequential} (default — `concurrency` absent /
+ * `=== 1`) and {@link dispatchParallel} (v0.4-M30 —
+ * `concurrency > 1`) over `matchedItemIds` with id-field
+ * `'item_id'`. The per-target dispatch callback (shared between
+ * routes verbatim) fires one `executeItemMutation` call.
+ * Successes populate `results[i].item` with the `ProjectedItem`
+ * via a side-map fold; failures land in
+ * `results[i].error: {code, message}` via the dispatcher's
+ * built-in error decoration. `internal_error` codes re-throw
+ * as whole-call (M14 round-2 F1 precedent — schema-drift in
+ * the response MUST NOT be papered over as a per-item failure).
+ *
+ * **`data.summary.failed_count` invariant.** The action body
+ * derives `failed_count` from the result records
+ * (`results.filter((r) => !r.ok).length`); the wrapper does
+ * NOT compute it directly because the summary slot also
+ * carries `matched_count` + `applied_count` + `board_id` —
+ * shapes the action body already owns from the walker + the
+ * matched-item-walk + the argv. Keeping the summary
+ * assembly at the action layer prevents wrapper-vs-action
+ * drift on the partial-success contract's per-summary shape.
+ */
+import { z } from 'zod';
+import { ApiError, MondayCliError } from '../utils/errors.js';
+import { projectedItemSchema } from './item-projection.js';
+import { dispatchSequential, } from './partial-success-mutation.js';
+import { dispatchParallel } from './parallel-dispatch.js';
+import { executeItemMutation } from './item-mutation-execute.js';
+import { foldAndRemap } from './resolver-error-fold.js';
+/**
+ * Per-item result schema for the partial-success bulk envelope's
+ * `data.results[]` slot. Each record carries `item_id` + `ok` +
+ * either `item` (on success) or `error` (on failure). The two
+ * branches share the discriminator `ok: boolean` — agents read
+ * `r.ok ? r.item : r.error` to dispatch on outcome.
+ *
+ * The `item` slot on success records is the §6.2 `ProjectedItem`
+ * shape (same projection single-item `item update` emits as
+ * `data`). The `error` slot on failure records carries
+ * `{code, message}` populated from the selected dispatcher's
+ * per-target error decoration (`dispatchSequential` or
+ * `dispatchParallel` — same shape per the R-NEW-28 axis-1
+ * equivalence).
+ *
+ * `z.discriminatedUnion` would be the natural shape but the
+ * dispatchers' result records carry a dynamic id-field key
+ * (`{item_id: ..., ok, error?}`) — modelling that as a
+ * per-record union complicates the schema and downstream
+ * consumers' type-narrowing. The flatter shape below carries
+ * `item` + `error` as optionals; the action body's projection
+ * + the wrapper's per-item dispatch enforce the
+ * mutual-exclusion invariant at runtime.
+ */
+export const partialSuccessBulkUpdateResultSchema = z.object({
+    item_id: z.string().min(1),
+    ok: z.boolean(),
+    item: projectedItemSchema.optional(),
+    error: z
+        .object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+/**
+ * Output `data` shape for the partial-success bulk envelope.
+ * `data.operation` is the literal `"item_update"` (mirrors M14's
+ * add-users / remove-users discriminator at `data.operation`;
+ * agents switch on it to confirm which verb produced the
+ * envelope).
+ *
+ * `data.summary` extends the v0.1 fail-fast bulk-summary with
+ * `failed_count` — items whose per-item dispatch failed under
+ * the `--continue-on-error` path. The invariant
+ * `matched_count === applied_count + failed_count` holds for
+ * every M25 success envelope.
+ */
+export const partialSuccessBulkUpdateDataSchema = z.object({
+    operation: z.literal('item_update'),
+    summary: z.object({
+        matched_count: z.number().int().nonnegative(),
+        applied_count: z.number().int().nonnegative(),
+        failed_count: z.number().int().nonnegative(),
+        board_id: z.string().min(1),
+    }),
+    results: z.array(partialSuccessBulkUpdateResultSchema),
+});
+/**
+ * Constant source signal the partial-success bulk dispatch
+ * contributes to the action layer's `SourceAggregator`. Always
+ * `'live'` post-dispatch — every Monday mutation counts as a
+ * `live` leg. Exported so the action layer's
+ * `sourceAgg.record(...)` call site reads against a named
+ * constant rather than a bare string literal.
+ */
+export const PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE = 'live';
+/**
+ * Drives the per-item dispatch loop under `--continue-on-error`.
+ *
+ * Implementation (M25 impl `78889df` refactor + this commit;
+ * extended at v0.4-M30 pre-flight with the `concurrency` routing
+ * branch):
+ *
+ *   1. Loop {@link dispatchSequential} (default / M25 path) OR
+ *      {@link dispatchParallel} (v0.4-M30 `--concurrency > 1`
+ *      path; runtime body landed at M30 IMPL) over
+ *      `matchedItemIds` with id-field `'item_id'`.
+ *   2. Per-item dispatch callback fires
+ *      {@link executeItemMutation} against the resolved
+ *      `SelectedMutation`. On a {@link MondayCliError} catch,
+ *      run {@link foldAndRemap} with `resolverWarnings` +
+ *      `remapColumnIds` + `env` + `noCache` + `resolutionSource`
+ *      from the inputs BEFORE re-throwing into the selected
+ *      dispatcher (`dispatchSequential` or `dispatchParallel`).
+ *      This makes the per-record `error.code` in
+ *      `data.results[]` carry the SAME stable code
+ *      (`column_archived` after a stale-cache
+ *      `validation_failed` remap) that the v0.1 fail-fast
+ *      path would have surfaced at the top level — Codex
+ *      round-1 P1-1 contract requirement (cli-design §6.5
+ *      stable-code rule applies uniformly across the bulk
+ *      fail-modes).
+ *   3. On success, capture the `ProjectedItem` into a side
+ *      map keyed by `item_id`.
+ *   4. After the loop, walk the result rows (from whichever
+ *      dispatcher fired — `dispatchSequential` by default;
+ *      {@link dispatchParallel} when `concurrency > 1`) and
+ *      fold the per-item `ProjectedItem` from the side
+ *      map into each `results[i].item` slot via
+ *      {@link foldPartialSuccessBulkResult}. Failure records
+ *      already carry `error: {code, message}` (with the
+ *      foldAndRemap-applied code) via the dispatcher's built-in
+ *      error decoration (both routes share the same per-target
+ *      error capture contract).
+ *   5. Return `{results}` — the action layer folds the
+ *      constant `'live'` dispatch source via
+ *      `sourceAgg.record(PARTIAL_SUCCESS_BULK_DISPATCH_SOURCE,
+ *      null)` and emits the envelope.
+ *
+ * **`internal_error` re-throw escape hatch.** Per M14 round-2
+ * F1 / round-3 F1, both dispatchers re-throw `internal_error`
+ * whole-call so schema-drift in the response surfaces as
+ * top-level `ok: false` rather than per-record — papering over
+ * `internal_error` would hide the malformed-response signal
+ * agents need to know about. The wrapper inherits this
+ * behaviour by NOT wrapping the dispatcher's re-throw —
+ * `foldAndRemap` only ever runs against {@link MondayCliError}
+ * instances, and it NEVER converts a non-internal_error into
+ * internal_error, so the re-throw path through the selected
+ * dispatcher remains the canonical schema-drift surface (axis
+ * 2 of the R-NEW-28 6-axis equivalence — identical between
+ * `dispatchSequential` and `dispatchParallel`).
+ *
+ * **Non-`MondayCliError` re-throw.** Programmer-bug exceptions
+ * (TypeError, RangeError, etc.) raised by the executor or by
+ * `foldAndRemap`'s refresh probe propagate through the selected
+ * dispatcher's non-CliError re-throw branch unchanged, surfacing
+ * as whole-call `internal_error` via the runner's catch-all
+ * (mirrors M14's pattern at `users-fan-out-mutation.ts` and the
+ * documented behaviour at `partial-success-mutation.ts` —
+ * R-NEW-28 axis 3, also identical across both routes).
+ */
+export const runPartialSuccessBulkUpdate = async (inputs) => {
+    const { client, boardId, matchedItemIds, mutation, createLabelsIfMissing, resolverWarnings, remapColumnIds, env, noCache, resolutionSource, concurrency, signal, } = inputs;
+    const projectedById = new Map();
+    // Per-target dispatch closure shared between the sequential
+    // (v0.3-M25 default) and parallel (v0.4-M30 `--concurrency > 1`)
+    // routes. Both dispatch helpers contract on the same
+    // {@link DispatchOneTargetInputs}-shaped callback so the closure
+    // body is byte-equivalent across routes — only the OUTER call
+    // (dispatchSequential vs dispatchParallel) changes. This keeps the
+    // R-NEW-28 6-axis behavioral-equivalence audit straightforward:
+    // every per-target outcome (success projection capture; `MondayCliError`
+    // foldAndRemap + re-throw; non-CliError re-throw) is shared verbatim.
+    const perTargetDispatch = async ({ targetId }) => {
+        try {
+            const result = await executeItemMutation(client, {
+                mutation,
+                itemId: targetId,
+                boardId,
+                createLabelsIfMissing,
+            });
+            projectedById.set(targetId, result.projected);
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                // Codex pre-flight round-1 P1-1: thread the remap
+                // context through so per-item failures inherit the
+                // SAME `validation_failed` → `column_archived`
+                // stale-cache remap the v0.1 fail-fast path applies.
+                // Without this, archived-column failures would
+                // surface as `validation_failed` in `data.results[]`
+                // even though the v0.1 path surfaces `column_archived`
+                // for the same root cause (cli-design §6.5 stable-
+                // code rule). foldAndRemap NEVER converts a non-
+                // internal_error into internal_error, so the selected
+                // dispatcher's internal_error re-throw escape hatch
+                // (M14 round-2 F1) stays intact across both routes.
+                const remapped = await foldAndRemap({
+                    err,
+                    warnings: resolverWarnings,
+                    client,
+                    boardId,
+                    columnIds: remapColumnIds,
+                    env,
+                    noCache,
+                    resolutionSource,
+                });
+                throw remapped;
+            }
+            // Non-MondayCliError — programmer bug. Re-throw through
+            // dispatchSequential / dispatchParallel's non-CliError branch
+            // so the runner's catch-all surfaces it as internal_error
+            // (whole-call, not per-record). Mirrors users-fan-out-mutation.ts
+            // and is the documented partial-success contract.
+            throw err;
+        }
+    };
+    // v0.4-M30 routing: `--concurrency <N>` with N > 1 routes through
+    // {@link dispatchParallel} (bounded async-pool); absent / N === 1
+    // routes through the unchanged {@link dispatchSequential} path.
+    // Both dispatchers thread the optional `signal` so SIGINT-aware
+    // callers see consistent cooperative abort semantics across routes
+    // (R-NEW-28 axis 6).
+    let dispatchResults;
+    if (concurrency !== undefined && concurrency > 1) {
+        dispatchResults = await dispatchParallel(matchedItemIds, 'item_id', perTargetDispatch, concurrency, signal);
+    }
+    else {
+        dispatchResults = await dispatchSequential(matchedItemIds, 'item_id', perTargetDispatch, signal);
+    }
+    const results = dispatchResults.map((row) => {
+        // Side-map lookup requires the item_id string from the row;
+        // foldPartialSuccessBulkResult also enforces the same
+        // invariant + throws internal_error if the id-field is
+        // missing or non-string (both dispatchers populate the
+        // id-field slot for every result row per the partial-
+        // success contract).
+        const itemIdSlot = row.item_id;
+        const projected = typeof itemIdSlot === 'string'
+            ? projectedById.get(itemIdSlot)
+            : undefined;
+        return foldPartialSuccessBulkResult(row, projected);
+    });
+    return { results };
+};
+/**
+ * Pure helper — folds a per-target result row produced by the
+ * selected dispatcher (`dispatchSequential` or
+ * `dispatchParallel`) + a `ProjectedItem` side-map entry into
+ * the partial-success-bulk per-item record shape this module
+ * emits to the action layer. Both dispatchers populate the row
+ * with the same `{item_id, ok, error?}` shape (axis 1 of the
+ * R-NEW-28 6-axis equivalence) so the fold is route-agnostic.
+ *
+ * The helper is **shipped as a real implementation** (not a
+ * stub) so the pre-flight Codex review can verify the
+ * projection shape against the contract pinned in cli-design
+ * §6.4 inline. M25 implementation reuses the helper unchanged.
+ *
+ * `record` is the row produced by the selected dispatcher with
+ * id-field `'item_id'` — carries `{item_id, ok, error?}` per
+ * the partial-success contract. `projectedItem` is the
+ * `ProjectedItem` the per-item dispatch callback captured on
+ * success (`undefined` on failure).
+ *
+ * Returns the per-item shape with `item` populated only when
+ * the dispatch succeeded; `error` populated only when it
+ * failed. The mutual-exclusion invariant is enforced at the
+ * boundary: success records never carry `error`, failure
+ * records never carry `item`.
+ */
+export const foldPartialSuccessBulkResult = (record, projectedItem) => {
+    // Dot-access: the selected dispatcher (`dispatchSequential` or
+    // `dispatchParallel`) builds the record with the dynamic
+    // id-field key (`'item_id'`) carrying the target ID. The
+    // dot-access narrows the unknown index-signature value to a
+    // string via the runtime guard below; the helper throws
+    // `internal_error` if the shape doesn't match (which would be
+    // a programmer bug — both dispatchers contract on populating
+    // the id-field slot for every result row).
+    const itemIdSlot = record.item_id;
+    if (typeof itemIdSlot !== 'string' || itemIdSlot.length === 0) {
+        throw new ApiError('internal_error', 'partial-success bulk result row is missing the `item_id` field — dispatcher contract violation.', {
+            details: {
+                record_keys: Object.keys(record),
+            },
+        });
+    }
+    if (record.ok) {
+        if (projectedItem === undefined) {
+            throw new ApiError('internal_error', `partial-success bulk result row for item_id ${itemIdSlot} reported ok: true but no ProjectedItem was captured — wrapper-layer side-map miss.`, {
+                details: {
+                    item_id: itemIdSlot,
+                },
+            });
+        }
+        return {
+            item_id: itemIdSlot,
+            ok: true,
+            item: projectedItem,
+        };
+    }
+    // Failure path — both dispatchers populate `error` on every
+    // non-`ok` row (R-NEW-28 axis 1); the schema's `.optional()`
+    // declarations narrow defensively here.
+    if (record.error === undefined) {
+        throw new ApiError('internal_error', `partial-success bulk result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatcher contract violation.`, {
+            details: {
+                item_id: itemIdSlot,
+            },
+        });
+    }
+    return {
+        item_id: itemIdSlot,
+        ok: false,
+        error: {
+            code: record.error.code,
+            message: record.error.message,
+        },
+    };
+};
+/**
+ * Pure helper — derives the `data.summary` slot from the
+ * matched-item count + the per-item results array. The
+ * `matched_count === applied_count + failed_count` invariant
+ * is enforced here; a mismatch throws `internal_error` since
+ * it would indicate a wrapper-layer bug (some matched item
+ * neither succeeded nor failed). Shipped as a real
+ * implementation so the pre-flight Codex review can verify the
+ * shape against cli-design §6.4 inline.
+ */
+export const buildPartialSuccessBulkSummary = ({ matchedCount, boardId, results, }) => {
+    const appliedCount = results.filter((r) => r.ok).length;
+    const failedCount = results.filter((r) => !r.ok).length;
+    if (appliedCount + failedCount !== matchedCount) {
+        throw new ApiError('internal_error', `partial-success bulk summary invariant violated — matched_count (${String(matchedCount)}) !== applied_count (${String(appliedCount)}) + failed_count (${String(failedCount)}).`, {
+            details: {
+                matched_count: matchedCount,
+                applied_count: appliedCount,
+                failed_count: failedCount,
+                board_id: boardId,
+            },
+        });
+    }
+    return {
+        matched_count: matchedCount,
+        applied_count: appliedCount,
+        failed_count: failedCount,
+        board_id: boardId,
+    };
+};
+//# sourceMappingURL=partial-success-bulk.js.map

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

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

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

@@ -20,9 +20,21 @@ export interface PartialSuccessEnvelopeData {
  * 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`.
+ *
+ * **v0.4-M30 — optional `signal` parameter.** When the caller passes
+ * an `AbortSignal`, the loop checks `signal.aborted` between
+ * iterations and re-throws the signal's reason whole-call (mirrors
+ * `dispatchParallel`'s axis-6 behaviour for the R-NEW-28
+ * behavioural-equivalence audit). In-flight wire calls abort via the
+ * existing `MondayClient.signal` configured at construction time
+ * (the client threads its signal into every fetch); the dispatcher-
+ * level check stops the loop from scheduling NEW work after the
+ * abort fires. Omitting the signal preserves the v0.3-M25 behaviour
+ * verbatim — existing callers that don't pass a signal are
+ * byte-equivalent to pre-M30.
  */
 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[]>;
+export declare const dispatchSequential: <TargetId extends string>(targets: readonly TargetId[], idField: string, dispatch: (inputs: DispatchOneTargetInputs<TargetId>) => Promise<void>, signal?: AbortSignal) => Promise<readonly PartialSuccessResult[]>;
 //# sourceMappingURL=partial-success-mutation.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"partial-success-mutation.d.ts","sourceRoot":"","sources":["../../src/api/partial-success-mutation.ts"],"names":[],"mappings":"AAwBA,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;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,EACtE,SAAS,WAAW,KACnB,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAwCzC,CAAC"}

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

@@ -20,9 +20,13 @@
  * reads `data.results` to determine outcomes.
  */
 import { MondayCliError } from '../utils/errors.js';
-export const dispatchSequential = async (targets, idField, dispatch) => {
+import { extractSignalReason } from '../utils/signal.js';
+export const dispatchSequential = async (targets, idField, dispatch, signal) => {
     const results = [];
     for (const targetId of targets) {
+        if (signal?.aborted === true) {
+            throw extractSignalReason(signal);
+        }
         try {
             await dispatch({ targetId });
             // Build the result with the dynamic id-field name. Property

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

@@ -1 +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"}
+{"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;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA8CzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,OAA4B,EAC5B,OAAe,EACf,QAAsE,EACtE,MAAoB,EACsB,EAAE;IAC5C,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7B,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,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"}

package/dist/api/people.d.ts

@@ -56,6 +56,7 @@
  * passes; consolidating the source of truth prevents the next
  * drift outright.
  */
+import { type EnvelopeSource } from './source-aggregator.js';
 /**
  * Wire payload shape for a `people` column. Matches Monday's
  * `change_column_value(value: JSON!)` JSON scalar:
@@ -105,8 +106,34 @@ export interface PeopleResolutionContext {
      * translator forwards the verbatim email so the unmatched-email
      * detail in any thrown `user_not_found` echoes what the agent
      * typed.
+     *
+     * **M19→M20 cleanup-window widening.** Pre-widening the callback
+     * returned just the `id` string and the people translator emitted
+     * `translatorResolution: null`, which meant `--set Owner=alice@x`
+     * against a cache-hit user-directory lookup surfaced
+     * `meta.source: "live"` because the email-resolution leg's source
+     * never reached the envelope-level aggregate. Post-widening, the
+     * callback returns the full `userByEmail` provenance (`source` +
+     * `cacheAgeSeconds`) and the translator threads it into
+     * `translatorResolution` for envelope-level merge — same shape the
+     * M19 tags translator uses for its `resolveTags` callback (see
+     * `TagResolutionContext.resolveTags` in `column-values.ts`).
      */
-    readonly resolveEmail: (email: string) => Promise<string>;
+    readonly resolveEmail: (email: string) => Promise<ResolveEmailResult>;
+}
+/**
+ * Per-email resolution result returned by `PeopleResolutionContext.
+ * resolveEmail`. Mirrors `userByEmail`'s public shape one-for-one
+ * (same field names, same union for `source`) so the
+ * `buildResolutionContexts` closure is a transparent passthrough.
+ */
+export interface ResolveEmailResult {
+    /** Resolved Monday user ID (decimal non-negative integer string). */
+    readonly id: string;
+    /** `'cache'` when the directory cache served the email; `'live'` after a network refresh. */
+    readonly source: 'cache' | 'live';
+    /** Cache age in seconds for `source: 'cache'`; `null` after a live refresh. */
+    readonly cacheAgeSeconds: number | null;
 }
 /**
  * Token-by-token resolution echo the dry-run engine renders as
@@ -144,6 +171,32 @@ export interface ParsedPeopleInput {
      * a v0.1-plan §3 M5a spec gap for cli-design backfill.
      */
     readonly resolution: PeopleResolution;
+    /**
+     * Aggregated source across every resolution leg this call fired —
+     * one leg per non-empty token. `me` tokens record `'live'` (the
+     * `me { id }` query is always a network call; the per-call
+     * `cachedMe` memo amortises N `me` tokens to one network round-
+     * trip but the leg itself is live). Email tokens record the
+     * `userByEmail` callback's `source` verbatim. `mergeSource`'s rule
+     * promotes `cache` + `live` → `mixed`. Always populated; empty
+     * input throws before this slot is built.
+     *
+     * Threaded into `translatorResolution.source` by `translatePeople`
+     * so the envelope-level `meta.source` aggregate reflects the
+     * email-resolution leg (M19→M20 cleanup-window parity fix per
+     * v0.3-plan §11 post-mortem).
+     */
+    readonly source: EnvelopeSource;
+    /**
+     * Worst-case staleness across legs that hit cache (the OLDEST
+     * `cacheAgeSeconds` seen). `null` when no leg hit cache (every
+     * email resolved live AND no leg contributed an age). Threaded
+     * into `translatorResolution.cacheAgeSeconds` by `translatePeople`
+     * so the envelope-level `meta.cache_age_seconds` reflects the
+     * worst-case staleness across the column-resolution leg + the
+     * people-resolution leg.
+     */
+    readonly cacheAgeSeconds: number | null;
 }
 /**
  * Parses a `people` column input per cli-design.md §5.3 step 3.

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

@@ -1 +1 @@
-{"version":3,"file":"people.d.ts","sourceRoot":"","sources":["../../src/api/people.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,UAAU,MAAM,EAChB,KAAK,uBAAuB,KAC3B,OAAO,CAAC,iBAAiB,CAuC3B,CAAC"}
+{"version":3,"file":"people.d.ts","sourceRoot":"","sources":["../../src/api/people.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,UAAU,MAAM,EAChB,KAAK,uBAAuB,KAC3B,OAAO,CAAC,iBAAiB,CA6D3B,CAAC"}

package/dist/api/people.js

@@ -59,6 +59,7 @@
 import { ApiError, UsageError } from '../utils/errors.js';
 import { DECIMAL_USER_ID_PATTERN } from '../types/ids.js';
 import { isMeToken } from './me-token.js';
+import { SourceAggregator } from './source-aggregator.js';
 /**
  * Parses a `people` column input per cli-design.md §5.3 step 3.
  *
@@ -107,6 +108,15 @@ export const parsePeopleInput = async (raw, columnId, ctx) => {
         cachedMe ??= await ctx.resolveMe();
         return cachedMe;
     };
+    // Source/cache-age aggregator for the envelope-level meta.source
+    // pathway (M19→M20 cleanup-window parity fix). Each token records
+    // one leg: `me` always 'live' (`me { id }` is a network call —
+    // the per-call cachedMe memo amortises duplicates but the leg is
+    // still live), email tokens forward the userByEmail callback's
+    // {source, cacheAgeSeconds} verbatim. Translated downstream by
+    // translatePeople into translatorResolution; the envelope-level
+    // mergeSource rule promotes cache + live → mixed.
+    const sourceAgg = new SourceAggregator();
     const entries = [];
     const resolutionTokens = [];
     for (const token of tokens) {
@@ -117,15 +127,29 @@ export const parsePeopleInput = async (raw, columnId, ctx) => {
             // gap in v0.1-plan.md §3 M5a.
             throw numericPeopleTokenError(columnId, token, raw);
         }
-        const id = isMeToken(token)
-            ? await resolveMeOnce()
-            : await ctx.resolveEmail(token);
+        let id;
+        if (isMeToken(token)) {
+            id = await resolveMeOnce();
+            sourceAgg.record('live', null);
+        }
+        else {
+            const resolved = await ctx.resolveEmail(token);
+            id = resolved.id;
+            sourceAgg.record(resolved.source, resolved.cacheAgeSeconds);
+        }
         entries.push({ id: idStringToNumber(id, columnId, token), kind: 'person' });
         resolutionTokens.push({ input: token, resolved_id: id });
     }
+    // tokens.length > 0 guaranteed (empty input throws above), so the
+    // aggregator always has at least one leg recorded; `result()`'s
+    // fallback is unreachable here but the default ('live') stays as
+    // a defensive seed for the type narrowing.
+    const aggregate = sourceAgg.result();
     return {
         payload: { personsAndTeams: entries },
         resolution: { tokens: resolutionTokens },
+        source: aggregate.source,
+        cacheAgeSeconds: aggregate.cacheAgeSeconds,
     };
 };
 /**