monday-cli 0.2.0

package/dist/commands/item/update.js

@@ -0,0 +1,884 @@
+/**
+ * `monday item update <iid> [--name <n>] [--set <col>=<val>]...` —
+ * multi-column atomic update + optional rename.
+ * (`cli-design.md` §4.3 line 490, §5.3, `v0.1-plan.md` §3 M5b).
+ *
+ * Two argv shapes:
+ *
+ *   1. **Single-item** (this commit): positional `<itemId>` +
+ *      repeatable `--set <col>=<val>` + optional `--name <n>`.
+ *      Multi-`--set` (≥2) bundles into one
+ *      `change_multiple_column_values` mutation (atomic on Monday's
+ *      side per §5.3 step 5). `--name` rolls into the same multi
+ *      mutation when columns are also present, otherwise fires a
+ *      dedicated `change_simple_column_value(column_id: "name", ...)`.
+ *
+ *   2. **Bulk** (next commit): `--where <expr>` repeatable + no
+ *      positional `<itemId>` — applies the same `--set` / `--name`
+ *      bundle to every matching item via Monday's `items_page`
+ *      walker. `confirmation_required` fires without `--yes` (and
+ *      without `--dry-run`) per cli-design §10.2.
+ *
+ * **`--name` + `--set` atomicity.** Per cli-design §5.3 step 5, the
+ * design promises atomicity for multi-column updates. Bundling the
+ * name into the multi mutation keeps the same atomicity guarantee
+ * for `--name + --set`. Monday's
+ * `change_multiple_column_values(column_values: JSON!)` accepts
+ * `name` as a special key in the map. The dry-run engine produces
+ * a single `PlannedChange` whose `diff` includes both column keys
+ * and a `name` key when both are passed.
+ *
+ * **`--name` only.** Single field → `change_simple_column_value(
+ * column_id: "name", value: <n>)`. Atomic by default (single
+ * mutation).
+ *
+ * **`--create-labels-if-missing`** (cli-design §4.3) — passes
+ * through to Monday's `change_*_column_value(create_labels_if_missing:
+ * true)`. Tells Monday to auto-create unknown status / dropdown
+ * labels rather than rejecting with `validation_failed`. Off by
+ * default; agents who want labels-on-demand pass the flag
+ * explicitly.
+ *
+ * Idempotent: yes — `change_*` mutations are idempotent. Multi-set
+ * is also idempotent (re-running with the same args produces the
+ * same item state).
+ */
+import { z } from 'zod';
+import { ensureSubcommand } from '../types.js';
+import { emitDryRun, emitMutation } from '../emit.js';
+import { resolveClient } from '../../api/resolve-client.js';
+import { BoardIdSchema, ItemIdSchema } from '../../types/ids.js';
+import { parseArgv } from '../parse-argv.js';
+import { ApiError, MondayCliError, UsageError } from '../../utils/errors.js';
+import { selectMutation, } from '../../api/column-values.js';
+import { parseSetRawExpression, } from '../../api/raw-write.js';
+import { splitSetExpression } from '../../api/set-expression.js';
+import { buildResolutionContexts } from '../../api/resolution-context.js';
+import { resolveBoardId } from '../../api/item-board-lookup.js';
+import { SourceAggregator } from '../../api/source-aggregator.js';
+import { resolveAndTranslate } from '../../api/resolution-pass.js';
+import { foldAndRemap } from '../../api/resolver-error-fold.js';
+import { planChanges } from '../../api/dry-run.js';
+import { buildQueryParams } from '../../api/filters.js';
+import { loadBoardMetadata, refreshBoardMetadata, } from '../../api/board-metadata.js';
+import { DEFAULT_PAGE_SIZE, paginate, } from '../../api/pagination.js';
+import { fetchItemsPage, fetchNextItemsPage, } from '../../api/items-page-walker.js';
+import { ConfirmationRequiredError, } from '../../utils/errors.js';
+import { ITEM_FIELDS_FRAGMENT, resolveMeFactory, } from '../../api/item-helpers.js';
+import { projectMutationItem as projectMutationItemShared } from '../../api/item-mutation-result.js';
+import { projectedItemSchema, } from '../../api/item-projection.js';
+const CHANGE_SIMPLE_COLUMN_VALUE_MUTATION = `
+  mutation ItemUpdateSimple(
+    $itemId: ID!
+    $boardId: ID!
+    $columnId: String!
+    $value: String!
+    $createLabelsIfMissing: Boolean
+  ) {
+    change_simple_column_value(
+      item_id: $itemId
+      board_id: $boardId
+      column_id: $columnId
+      value: $value
+      create_labels_if_missing: $createLabelsIfMissing
+    ) {
+      ${ITEM_FIELDS_FRAGMENT}
+    }
+  }
+`;
+const CHANGE_COLUMN_VALUE_MUTATION = `
+  mutation ItemUpdateRich(
+    $itemId: ID!
+    $boardId: ID!
+    $columnId: String!
+    $value: JSON!
+    $createLabelsIfMissing: Boolean
+  ) {
+    change_column_value(
+      item_id: $itemId
+      board_id: $boardId
+      column_id: $columnId
+      value: $value
+      create_labels_if_missing: $createLabelsIfMissing
+    ) {
+      ${ITEM_FIELDS_FRAGMENT}
+    }
+  }
+`;
+const CHANGE_MULTIPLE_COLUMN_VALUES_MUTATION = `
+  mutation ItemUpdateMulti(
+    $itemId: ID!
+    $boardId: ID!
+    $columnValues: JSON!
+    $createLabelsIfMissing: Boolean
+  ) {
+    change_multiple_column_values(
+      item_id: $itemId
+      board_id: $boardId
+      column_values: $columnValues
+      create_labels_if_missing: $createLabelsIfMissing
+    ) {
+      ${ITEM_FIELDS_FRAGMENT}
+    }
+  }
+`;
+export const itemUpdateOutputSchema = projectedItemSchema;
+/**
+ * Input shape — supports both single-item and bulk shapes.
+ *
+ *   - Single-item: `itemId` positional required; `where` empty.
+ *   - Bulk:        `itemId` positional omitted; `where` non-empty
+ *                  AND `board` required.
+ *
+ * The split lives in `validateInputShape` (action body) so the zod
+ * schema captures the union without the per-shape conditional logic
+ * — the action layer reads the discriminator and dispatches.
+ */
+const inputSchema = z
+    .object({
+    itemId: ItemIdSchema.optional(),
+    set: z.array(z.string()).default([]),
+    // M8: --set-raw <col>=<json>... repeatable raw escape hatch.
+    // Mutually exclusive per-column with --set; the duplicate-ID
+    // check fires in the dry-run engine + selectMutation per
+    // cli-design §5.3 line 961-972 (resolution-time, not parse-time).
+    setRaw: z.array(z.string()).default([]),
+    name: z.string().min(1).optional(),
+    board: BoardIdSchema.optional(),
+    where: z.array(z.string()).default([]),
+    // Empty `--filter-json ''` would slip through `buildQueryParams`
+    // as "no filter" (`hasFilterJson` is gated on `length > 0`) while
+    // still tripping `validateInputShape`'s "bulk mode" discriminator
+    // (`filterJson !== undefined`) — net effect, a whole-board mutation
+    // an agent likely thought was filtered. Reject at the schema
+    // boundary so no network call fires. Codex pass-3 of the §10.2
+    // backfill PR caught this — see v0.1-plan §3 M5b session 4.
+    //
+    // `.refine(trim)` rather than `.min(1)` so a whitespace-only
+    // `--filter-json '   '` is also caught at the schema boundary;
+    // pre-fix it slipped past `.min(1)` and only failed inside
+    // `parseFilterJson` AFTER board metadata loaded — same
+    // ultimate `usage_error`, but a wasted network call (Codex
+    // pass-1 of this fix).
+    filterJson: z
+        .string()
+        .refine((s) => s.trim().length > 0, '--filter-json must be a non-empty JSON object')
+        .optional(),
+    createLabelsIfMissing: z.boolean().optional(),
+})
+    .strict()
+    // At least one of --set / --set-raw / --name must be provided. An
+    // empty call (`monday item update 12345`) is meaningless and would
+    // produce a zero-mutation envelope that surprises agents. M8 widens
+    // the rule to include --set-raw.
+    .refine((v) => v.set.length > 0 || v.setRaw.length > 0 || v.name !== undefined, {
+    message: 'item update requires at least one of --set / --set-raw / --name',
+    path: ['set'],
+});
+const validateInputShape = (parsed) => {
+    const hasItemId = parsed.itemId !== undefined;
+    const hasFilter = parsed.where.length > 0 || parsed.filterJson !== undefined;
+    if (hasItemId && hasFilter) {
+        throw new UsageError('item update accepts either a positional <itemId> OR --where / ' +
+            '--filter-json (bulk shape), not both. Pick one.', { details: { item_id: parsed.itemId, where_count: parsed.where.length } });
+    }
+    if (!hasItemId && !hasFilter) {
+        throw new UsageError('item update requires either a positional <itemId> or --where / ' +
+            '--filter-json for the bulk shape.', { details: {} });
+    }
+    if (hasFilter && parsed.board === undefined) {
+        throw new UsageError('item update --where / --filter-json requires --board <bid>. The ' +
+            'bulk shape walks Monday\'s items_page on the named board.', { details: { where_count: parsed.where.length } });
+    }
+    if (hasItemId) {
+        /* c8 ignore next 4 — defensive: hasItemId === true means
+           parsed.itemId is non-undefined; the type guard exists for TS. */
+        if (parsed.itemId === undefined) {
+            throw new UsageError('item update: itemId narrowing failed');
+        }
+        return { kind: 'single', itemId: parsed.itemId };
+    }
+    return { kind: 'bulk' };
+};
+export const itemUpdateCommand = {
+    name: 'item.update',
+    summary: 'Update one or more columns on an item (atomic)',
+    examples: [
+        'monday item update 12345 --set status=Done',
+        'monday item update 12345 --set status=Done --set owner=alice@example.com',
+        'monday item update 12345 --name "New title"',
+        'monday item update 12345 --name "New title" --set status=Done',
+        'monday item update 12345 --set tags=Backend,Frontend --create-labels-if-missing',
+        'monday item update 12345 --set status=Done --dry-run --json',
+        "monday item update 12345 --set-raw status='{\"label\":\"Done\"}'",
+        "monday item update 12345 --set status=Done --set-raw tags_1='{\"tag_ids\":[1,2]}'",
+    ],
+    idempotent: true,
+    inputSchema,
+    outputSchema: itemUpdateOutputSchema,
+    attach: (program, ctx) => {
+        const noun = ensureSubcommand(program, 'item', 'Item commands');
+        noun
+            .command('update [itemId]')
+            .description(itemUpdateCommand.summary)
+            .option('--set <expr>', 'repeatable <col>=<val> column write', (value, prev) => [...prev, value], [])
+            .option('--set-raw <expr>', 'repeatable <col>=<json> raw write (escape hatch — bypasses friendly translator)', (value, prev) => [...prev, value], [])
+            .option('--name <n>', 'rename the item')
+            .option('--board <bid>', 'board ID (required for bulk; skip lookup for single-item)')
+            .option('--where <expr>', 'repeatable bulk filter (cli-design §10.2): <col><op><val>', (value, prev) => [...prev, value], [])
+            .option('--filter-json <json>', 'literal Monday query_params for bulk')
+            // `--yes` is a GLOBAL flag (`src/cli/program.ts`); read it via
+            // `globalFlags.yes` rather than redeclaring on this subcommand
+            // so the flag stays single-source-of-truth across every M5b /
+            // M6 mutation surface (and so commander doesn't dispatch the
+            // value to a per-subcommand slot that diverges from the
+            // global one).
+            .option('--create-labels-if-missing', 'auto-create unknown status / dropdown labels (Monday flag)')
+            .addHelpText('after', ['', 'Examples:', ...itemUpdateCommand.examples.map((e) => `  ${e}`), ''].join('\n'))
+            .action(async (itemId, opts) => {
+            const parsed = parseArgv(itemUpdateCommand.inputSchema, {
+                ...(itemId === undefined ? {} : { itemId }),
+                ...opts,
+            });
+            const { client, globalFlags, apiVersion, toEmit } = resolveClient(ctx, program.opts());
+            const dispatch = validateInputShape(parsed);
+            if (dispatch.kind === 'bulk') {
+                await runBulk({
+                    parsed,
+                    client,
+                    globalFlags,
+                    apiVersion,
+                    ctx,
+                    programOpts: program.opts(),
+                });
+                return;
+            }
+            // Argv-parse-time failures fire BEFORE board lookup / metadata
+            // fetch. Splits + JSON parse run on pure strings; surfacing here
+            // means a malformed --set or --set-raw fails fast without
+            // burning an `ItemBoardLookup` round-trip when `--board` was
+            // omitted (Codex M8 finding #4 — pre-fix this parse ran AFTER
+            // resolveBoardId, contradicting the argv-boundary contract used
+            // by `item set` and the bulk path).
+            const setEntries = parsed.set.map(splitSetExpression);
+            const rawEntries = parsed.setRaw.map(parseSetRawExpression);
+            const boardId = await resolveBoardId({
+                client,
+                itemId: dispatch.itemId,
+                explicit: parsed.board,
+            });
+            const { dateResolution, peopleResolution } = buildResolutionContexts({ client, ctx, globalFlags });
+            if (globalFlags.dryRun) {
+                const result = await planChanges({
+                    client,
+                    boardId,
+                    itemId: dispatch.itemId,
+                    setEntries,
+                    ...(rawEntries.length === 0 ? {} : { rawEntries }),
+                    ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
+                    dateResolution,
+                    peopleResolution,
+                    env: ctx.env,
+                    noCache: globalFlags.noCache,
+                });
+                emitDryRun({
+                    ctx,
+                    programOpts: program.opts(),
+                    plannedChanges: result.plannedChanges,
+                    source: result.source,
+                    cacheAgeSeconds: result.cacheAgeSeconds,
+                    warnings: result.warnings,
+                    apiVersion,
+                });
+                return;
+            }
+            // Live update path — three-pass resolution + translation
+            // through the shared helper (R20 lift).
+            const resolutionResult = await resolveAndTranslate({
+                client,
+                boardId,
+                setEntries,
+                rawEntries,
+                dateResolution,
+                peopleResolution,
+                env: ctx.env,
+                noCache: globalFlags.noCache,
+            });
+            const collectedWarnings = [
+                ...resolutionResult.warnings,
+            ];
+            const resolvedIds = resolutionResult.resolvedIds;
+            const sourceAgg = new SourceAggregator();
+            if (resolutionResult.source !== undefined) {
+                sourceAgg.record(resolutionResult.source, resolutionResult.cacheAgeSeconds);
+            }
+            const translated = resolutionResult.translated;
+            // Build the final SelectedMutation. When `--name` is set,
+            // a synthetic translated value (columnId: "name",
+            // columnType: "text") joins the array so `selectMutation`
+            // dispatches uniformly: name-only → simple; columns + name
+            // (or ≥2 columns) → multi.
+            const allTranslated = parsed.name === undefined
+                ? translated
+                : [
+                    {
+                        columnId: 'name',
+                        columnType: 'text',
+                        rawInput: parsed.name,
+                        payload: { format: 'simple', value: parsed.name },
+                        resolvedFrom: null,
+                        peopleResolution: null,
+                    },
+                    ...translated,
+                ];
+            let mutationResult;
+            try {
+                const mutation = selectMutation(allTranslated);
+                mutationResult = await executeMutation(client, {
+                    mutation,
+                    itemId: dispatch.itemId,
+                    boardId,
+                    createLabelsIfMissing: parsed.createLabelsIfMissing,
+                });
+            }
+            catch (err) {
+                if (err instanceof MondayCliError) {
+                    // F4 remap: cache-sourced resolution + Monday rejecting
+                    // as validation_failed → check live archived state.
+                    // Codex M5b finding #3: pass every translated column ID so
+                    // a multi-column update where a LATER target was archived
+                    // (post stale-cache read) still remaps.
+                    // Codex pass-1 F2: pass the actual aggregated resolution
+                    // source (live / cache / mixed) so plain cache hits
+                    // without `stale_cache_refreshed` warnings still trigger
+                    // the remap.
+                    throw await foldAndRemap({
+                        err,
+                        warnings: collectedWarnings,
+                        client,
+                        boardId,
+                        columnIds: translated.map((t) => t.columnId),
+                        env: ctx.env,
+                        noCache: globalFlags.noCache,
+                        resolutionSource: resolutionResult.source ?? 'live',
+                    });
+                }
+                throw err;
+            }
+            const warnings = collectedWarnings;
+            // The mutation leg is always live — fold it into the
+            // aggregator so a cache-served resolution + live mutation
+            // surfaces as `mixed`. Mirrors the bulk path's terminal
+            // `record('live', null)` (Codex M5b finding #2; the
+            // warning-only inference pre-fix missed plain cache hits).
+            sourceAgg.record('live', null);
+            emitMutation({
+                ctx,
+                data: mutationResult.projected,
+                schema: itemUpdateCommand.outputSchema,
+                programOpts: program.opts(),
+                warnings,
+                ...toEmit(mutationResult.response),
+                ...sourceAgg.result(),
+                // resolved_ids — same shape as `item set`. The synthetic
+                // `name` field doesn't appear here because the slot only
+                // echoes RESOLVED tokens (those that went through the
+                // column resolver); `name` skipped that step.
+                resolvedIds,
+            });
+        });
+    },
+};
+const executeMutation = async (client, inputs) => {
+    const { mutation, itemId, boardId, createLabelsIfMissing } = inputs;
+    const labelsFlag = createLabelsIfMissing ?? false;
+    if (mutation.kind === 'change_simple_column_value') {
+        const response = await client.raw(CHANGE_SIMPLE_COLUMN_VALUE_MUTATION, {
+            itemId,
+            boardId,
+            columnId: mutation.columnId,
+            value: mutation.value,
+            createLabelsIfMissing: labelsFlag,
+        }, { operationName: 'ItemUpdateSimple' });
+        return {
+            projected: projectMutationItem(response.data.change_simple_column_value, itemId),
+            response,
+        };
+    }
+    if (mutation.kind === 'change_column_value') {
+        const response = await client.raw(CHANGE_COLUMN_VALUE_MUTATION, {
+            itemId,
+            boardId,
+            columnId: mutation.columnId,
+            value: mutation.value,
+            createLabelsIfMissing: labelsFlag,
+        }, { operationName: 'ItemUpdateRich' });
+        return {
+            projected: projectMutationItem(response.data.change_column_value, itemId),
+            response,
+        };
+    }
+    // change_multiple_column_values — multi-`--set` or `--set + --name`.
+    const response = await client.raw(CHANGE_MULTIPLE_COLUMN_VALUES_MUTATION, {
+        itemId,
+        boardId,
+        columnValues: mutation.columnValues,
+        createLabelsIfMissing: labelsFlag,
+    }, { operationName: 'ItemUpdateMulti' });
+    return {
+        projected: projectMutationItem(response.data.change_multiple_column_values, itemId),
+        response,
+    };
+};
+// Thin wrapper around `api/item-mutation-result.ts projectMutationItem`
+// (R28). M5b's `internal_error` + "no item payload" semantics for an
+// empty-payload mutation success are preserved; the wrapper keeps the
+// existing `(raw, itemId)` call signature so the executeMutation arms
+// + the bulk per-item dispatch site stay untouched.
+const projectMutationItem = (raw, itemId) => projectMutationItemShared({
+    raw,
+    itemId,
+    errorCode: 'internal_error',
+    errorMessage: `Monday returned no item payload from the mutation for id ${itemId}.`,
+});
+/**
+ * Bulk dry-run aggregates per-item resolver warnings — the same
+ * `stale_cache_refreshed` / `column_token_collision` signals fire
+ * once per item the first time they're triggered (subsequent items
+ * hit the now-warm cache). De-duplicates by `code + message +
+ * details.token` so an agent reading the dry-run envelope sees
+ * each unique warning once rather than N copies. Order-preserving:
+ * the first occurrence wins.
+ */
+const dedupeWarnings = (warnings) => {
+    const seen = new Set();
+    const out = [];
+    for (const w of warnings) {
+        const tokenKey = typeof w.details?.token === 'string'
+            ? w.details.token
+            : '';
+        const key = `${w.code}|${w.message}|${tokenKey}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(w);
+    }
+    return out;
+};
+// ============================================================
+// Bulk path (cli-design §10.2 — `--where` / `--filter-json`).
+// items_page walker lifted into `api/items-page-walker.ts` per §18
+// R34 (post-M12) — the helper builds the GraphQL queries inline +
+// parses the response with the per-row schema below, surfacing
+// schema drift as `internal_error` with the failing field path on
+// `details.issues` rather than collapsing to a silent "0 matched,
+// 0 applied" success (the F6 pass-2 hardening lifts to all four
+// items_page consumers automatically).
+// ============================================================
+const bulkItemSchema = z.object({ id: ItemIdSchema }).loose();
+/**
+ * Wrapped data shape for the bulk-live success envelope. cli-design
+ * §10.2 doesn't pin a specific shape for `data`, so we fold the
+ * matched / applied counts into a `summary` slot alongside the
+ * per-item projected list. Agents read `data.applied_count` for the
+ * "did it work?" probe and `data.items` for the post-mutation state.
+ */
+const bulkLiveDataSchema = z.object({
+    summary: z.object({
+        matched_count: z.number().int().nonnegative(),
+        applied_count: z.number().int().nonnegative(),
+        board_id: z.string(),
+    }),
+    items: z.array(projectedItemSchema),
+});
+/**
+ * Bulk path orchestrator (cli-design §10.2). Walks `items_page` to
+ * collect every matched item, then dispatches:
+ *
+ *   1. Without `--yes` AND without `--dry-run` → throw
+ *      `confirmation_required` with the matched count. Per
+ *      cli-design §3.1 #7: "destructive ops without `--yes` fail
+ *      fast." Bulk multi-item mutations qualify.
+ *   2. With `--dry-run` → per-item `planChanges` → emit N-element
+ *      `planned_changes`. cli-design §10.2 line 1456-1457: "both
+ *      single-item and bulk forms use the same envelope".
+ *   3. With `--yes` (and not `--dry-run`) → per-item live mutation
+ *      via `executeMutation`. Fail-fast on first error; the error
+ *      envelope's `details.applied_to` lists IDs of items that
+ *      successfully mutated before the failure.
+ *
+ * **Why per-item planChanges / executeMutation rather than a
+ * single bulk mutation.** Monday has no true bulk-update mutation
+ * in 2026-01; the CLI walks items + fires N `change_*` calls. The
+ * column resolution + translation work is done once, then reused
+ * across every per-item mutation.
+ *
+ * **Sequential execution.** cli-design §9.3 mandates one-at-a-time
+ * requests in v0.1-v0.3; the per-item loop respects that. v0.4's
+ * `--concurrency` flag is the future extension point.
+ */
+const runBulk = async (inputs) => {
+    const { parsed, client, globalFlags, apiVersion, ctx, programOpts } = inputs;
+    /* c8 ignore next 6 — defensive: validateInputShape guarantees
+       parsed.board is non-undefined when shape is bulk; the type
+       guard exists for TS. */
+    if (parsed.board === undefined) {
+        throw new UsageError('item update bulk path: --board is required');
+    }
+    const boardId = parsed.board;
+    // 0) Argv-parse-time failures before any network call. Splits +
+    //    JSON parse run on pure strings; surfacing here means a
+    //    malformed --set or malformed --set-raw fails fast without
+    //    burning a board-metadata fetch + items_page walk + the
+    //    confirmation prompt. M8 finding from review pass: pre-fix the
+    //    parse ran AFTER the walk, so a malformed JSON paid two
+    //    GraphQL round-trips before the agent saw the parse error.
+    const setEntries = parsed.set.map(splitSetExpression);
+    const rawEntries = parsed.setRaw.map(parseSetRawExpression);
+    // 1) Load board metadata (cache-aware, refresh on column-not-found
+    //    during filter parsing per §5.3 step 5).
+    const meta = await loadBoardMetadata({
+        client,
+        boardId,
+        env: ctx.env,
+        noCache: globalFlags.noCache,
+    });
+    const onColumnNotFound = meta.source === 'cache'
+        ? async () => {
+            const refreshed = await refreshBoardMetadata({
+                client,
+                boardId,
+                env: ctx.env,
+            });
+            return refreshed.metadata;
+        }
+        : undefined;
+    const filterResult = await buildQueryParams({
+        metadata: meta.metadata,
+        resolveMe: resolveMeFactory(client),
+        whereClauses: parsed.where,
+        filterJson: parsed.filterJson,
+        ...(onColumnNotFound === undefined ? {} : { onColumnNotFound }),
+    });
+    // 2) Walk items_page collecting matched item IDs. The §18 R34
+    //    helper (`fetchItemsPage` / `fetchNextItemsPage`) supplies the
+    //    GraphQL + parse boundary; `paginate.ts` keeps the §3.1 #8
+    //    per-page sort + §5.6 `stale_cursor` enrichment.
+    const matchedItemIds = [];
+    await paginate({
+        fetchInitial: () => fetchItemsPage({
+            client,
+            operationName: 'ItemsPage',
+            boardId,
+            limit: DEFAULT_PAGE_SIZE,
+            queryParams: filterResult.queryParams,
+            itemFields: 'id',
+            itemSchema: bulkItemSchema,
+        }),
+        fetchNext: (cursor) => fetchNextItemsPage({
+            client,
+            operationName: 'NextItemsPage',
+            cursor,
+            limit: DEFAULT_PAGE_SIZE,
+            itemFields: 'id',
+            itemSchema: bulkItemSchema,
+        }),
+        now: ctx.clock,
+        extractPage: (r) => r.data,
+        getId: (item) => item.id,
+        all: true,
+        onItem: (item) => {
+            matchedItemIds.push(item.id);
+        },
+    });
+    // 3) Empty match set — both dry-run and live are clean no-ops.
+    //    Emit a success envelope before the confirmation gate fires
+    //    (Codex pass-1 F1: `--yes` shouldn't be required to confirm
+    //    "no items matched"). Filter warnings still surface so the
+    //    agent sees `column_token_collision` / `stale_cache_refreshed`
+    //    if the empty result was filter-resolved post-refresh.
+    //
+    // Codex pass-2: source / cacheAgeSeconds aggregate from the metadata
+    // load + the items_page walk (always live). Cache-sourced metadata
+    // + live walk → `mixed`; pure-cache metadata stays `cache` only on
+    // the impossible no-walk path. The live items_page walk forces the
+    // aggregate to `mixed` when metadata was cache-served.
+    const emptyEnvelopeSource = meta.source === 'cache' ? 'mixed' : 'live';
+    if (matchedItemIds.length === 0) {
+        if (globalFlags.dryRun) {
+            emitDryRun({
+                ctx,
+                programOpts,
+                plannedChanges: [],
+                source: emptyEnvelopeSource,
+                cacheAgeSeconds: meta.cacheAgeSeconds,
+                warnings: filterResult.warnings,
+                apiVersion,
+            });
+            return;
+        }
+        emitMutation({
+            ctx,
+            data: {
+                summary: { matched_count: 0, applied_count: 0, board_id: boardId },
+                items: [],
+            },
+            schema: bulkLiveDataSchema,
+            programOpts,
+            warnings: filterResult.warnings,
+            source: emptyEnvelopeSource,
+            cacheAgeSeconds: meta.cacheAgeSeconds,
+            apiVersion,
+        });
+        return;
+    }
+    // 4) Confirmation gate. Bulk mutations without --yes (and without
+    //    --dry-run) surface `confirmation_required` per §3.1 #7 +
+    //    §6.5. Agents read the matched-item count and re-run with
+    //    --yes after reviewing. `--yes` is a global flag (program.ts).
+    if (!globalFlags.dryRun && !globalFlags.yes) {
+        throw new ConfirmationRequiredError(`Bulk item update would mutate ${String(matchedItemIds.length)} ` +
+            `matched item(s). Re-run with --yes to confirm, or --dry-run to ` +
+            `preview.`, {
+            details: {
+                board_id: boardId,
+                matched_count: matchedItemIds.length,
+                where_clauses: parsed.where,
+                ...(parsed.filterJson === undefined
+                    ? {}
+                    : { filter_json: parsed.filterJson }),
+                hint: 'Use --dry-run to inspect the planned_changes for every ' +
+                    'matched item before applying.',
+            },
+        });
+    }
+    // setEntries + rawEntries pre-parsed at the top of runBulk for the
+    // fail-fast invariant. (See step 0 above — moving the parse there
+    // means a malformed --set / --set-raw doesn't pay for the metadata
+    // load + items_page walk first.)
+    const { dateResolution, peopleResolution } = buildResolutionContexts({ client, ctx, globalFlags });
+    // 5) Dry-run path: per-item planChanges. Column resolution is
+    //    cached after the first call; per-item state read fires per
+    //    item (no item-state cache in v0.1).
+    //
+    // Codex pass-1 F4: aggregate per-item warnings + source + cache
+    // age across the batch. Pre-fix, bulk dry-run dropped per-item
+    // results' `warnings` and hardcoded `source: 'mixed'`, losing
+    // `column_token_collision` / `stale_cache_refreshed` signals
+    // the resolver-warning preservation pattern is meant to keep.
+    if (globalFlags.dryRun) {
+        const allPlanned = [];
+        const aggregatedWarnings = [...filterResult.warnings];
+        const sourceAgg = new SourceAggregator({
+            source: meta.source,
+            cacheAgeSeconds: meta.cacheAgeSeconds,
+        });
+        for (const itemId of matchedItemIds) {
+            const result = await planChanges({
+                client,
+                boardId,
+                itemId,
+                setEntries,
+                ...(rawEntries.length === 0 ? {} : { rawEntries }),
+                ...(parsed.name === undefined ? {} : { nameChange: parsed.name }),
+                dateResolution,
+                peopleResolution,
+                env: ctx.env,
+                noCache: globalFlags.noCache,
+            });
+            for (const plan of result.plannedChanges) {
+                allPlanned.push(plan);
+            }
+            // Resolver warnings can fire per item (the cache-miss-refresh
+            // dance is per-token). Most fire on the first item only (cache
+            // populated for subsequent items), but the helper deduplicates
+            // by code+message+token below for compactness.
+            for (const w of result.warnings) {
+                aggregatedWarnings.push(w);
+            }
+            sourceAgg.record(result.source, result.cacheAgeSeconds);
+        }
+        emitDryRun({
+            ctx,
+            programOpts,
+            plannedChanges: allPlanned,
+            ...sourceAgg.result(),
+            warnings: dedupeWarnings(aggregatedWarnings),
+            apiVersion,
+        });
+        return;
+    }
+    // 5) Live path: per-item mutation. Resolve columns once, translate
+    //    once, then fire the same SelectedMutation against every
+    //    matched item.
+    //
+    // Three-pass resolution (Codex M8 finding #2): resolve every token
+    // first, run the cross-token duplicate-resolved-ID check, then
+    // translate. Pre-fix, translation ran inline, so a `--set X=bad`
+    // alongside a `--set-raw X={...}` could surface the translation
+    // `usage_error` instead of the mutual-exclusion `usage_error` per
+    // cli-design §5.3 line 961-972.
+    //
+    // Three-pass resolution + translation through the shared helper
+    // (R20 lift). The board-metadata leg's source / cacheAge seed the
+    // aggregator so a cache-served metadata fetch promotes the final
+    // envelope source to `mixed` when subsequent resolution legs hit
+    // live (Codex M8 finding #3).
+    //
+    // `collectedWarnings` is the union of filter warnings + resolver
+    // warnings, surfaced on the success envelope. `resolverWarnings`
+    // is the narrowed subset used by foldResolverWarningsIntoError —
+    // the helper's contract is to fold collision / stale_cache_refreshed
+    // signals, not generic Warning types.
+    const resolutionResult = await resolveAndTranslate({
+        client,
+        boardId,
+        setEntries,
+        rawEntries,
+        dateResolution,
+        peopleResolution,
+        env: ctx.env,
+        noCache: globalFlags.noCache,
+        initialSource: meta.source,
+        initialCacheAgeSeconds: meta.cacheAgeSeconds,
+    });
+    const collectedWarnings = [
+        ...filterResult.warnings,
+        ...resolutionResult.warnings,
+    ];
+    const resolverWarnings = [...resolutionResult.warnings];
+    const resolvedIds = resolutionResult.resolvedIds;
+    // resolveAndTranslate was seeded with meta.source / meta.cacheAge
+    // above, so resolutionResult.source is always defined post-helper.
+    // The `?? meta.source` fallback preserves the pre-R30 c8-ignored
+    // defensive widening; flow then folds the per-item mutation legs
+    // (always live) at emit time via `sourceAgg.record('live', null)`.
+    const sourceAgg = new SourceAggregator();
+    /* c8 ignore next 3 — defensive: initialSource seeded above so
+       resolutionResult.source is always defined post-helper. */
+    const remapSource = resolutionResult.source ?? meta.source;
+    sourceAgg.record(remapSource, resolutionResult.cacheAgeSeconds);
+    const translated = resolutionResult.translated;
+    const allTranslated = parsed.name === undefined
+        ? translated
+        : [
+            {
+                columnId: 'name',
+                columnType: 'text',
+                rawInput: parsed.name,
+                payload: { format: 'simple', value: parsed.name },
+                resolvedFrom: null,
+                peopleResolution: null,
+            },
+            ...translated,
+        ];
+    const mutation = selectMutation(allTranslated);
+    const appliedItems = [];
+    // Codex pass-1 F3: F4's `validation_failed` → `column_archived`
+    // remap must fire on bulk per-item failures too — agents key off
+    // the stable `column_archived` code regardless of whether the
+    // mutation came from item set / item update single / item update
+    // bulk. Pre-fix, bulk failures only ran the resolver-warning
+    // fold + bulk-progress decoration; the remap was missing.
+    // Codex M5b finding #3: probe every translated column id, not
+    // just the first, so a multi-column bulk update where a LATER
+    // target was archived after a stale cache read still surfaces
+    // `column_archived`. Single-column bulk passes a one-element
+    // array, same as before.
+    const remapColumnIds = translated.map((t) => t.columnId);
+    for (const itemId of matchedItemIds) {
+        try {
+            const result = await executeMutation(client, {
+                mutation,
+                itemId,
+                boardId,
+                createLabelsIfMissing: parsed.createLabelsIfMissing,
+            });
+            appliedItems.push(result.projected);
+        }
+        catch (err) {
+            if (err instanceof MondayCliError) {
+                // Apply fold + F4 remap before bulk-progress decoration. The
+                // remap returns the original error unchanged when its
+                // preconditions aren't met (non-validation_failed, live
+                // source, refresh failure, post-refresh column still
+                // active). When it DOES fire, the remapped error keeps the
+                // resolver_warnings slot we just folded in.
+                const remapped = await foldAndRemap({
+                    err,
+                    warnings: resolverWarnings,
+                    client,
+                    boardId,
+                    columnIds: remapColumnIds,
+                    env: ctx.env,
+                    noCache: globalFlags.noCache,
+                    resolutionSource: remapSource,
+                });
+                // Decorate with bulk-progress details so agents can see how
+                // many items mutated successfully before the failure.
+                const existing = remapped.details ?? {};
+                if (remapped.code === 'usage_error') {
+                    throw new UsageError(remapped.message, {
+                        ...(remapped.cause === undefined ? {} : { cause: remapped.cause }),
+                        details: {
+                            ...existing,
+                            applied_count: appliedItems.length,
+                            applied_to: appliedItems.map((i) => i.id),
+                            failed_at_item: itemId,
+                            matched_count: matchedItemIds.length,
+                        },
+                    });
+                }
+                throw new ApiError(remapped.code, remapped.message, {
+                    ...(remapped.cause === undefined ? {} : { cause: remapped.cause }),
+                    ...(remapped.httpStatus === undefined ? {} : { httpStatus: remapped.httpStatus }),
+                    ...(remapped.mondayCode === undefined ? {} : { mondayCode: remapped.mondayCode }),
+                    ...(remapped.requestId === undefined ? {} : { requestId: remapped.requestId }),
+                    retryable: remapped.retryable,
+                    ...(remapped.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: remapped.retryAfterSeconds }),
+                    details: {
+                        ...existing,
+                        applied_count: appliedItems.length,
+                        applied_to: appliedItems.map((i) => i.id),
+                        failed_at_item: itemId,
+                        matched_count: matchedItemIds.length,
+                    },
+                });
+            }
+            throw err;
+        }
+    }
+    // Codex pass-2: aggregate `meta.source` + `cache_age_seconds`
+    // properly per cli-design §6.1. Pre-fix, source was inferred from
+    // warning presence — a plain cache hit (no warning) on metadata
+    // would surface as `live` even though the resolver served from
+    // cache. M4 pinned this exact regression for read commands; the
+    // bulk write path replicated the bug.
+    //
+    // The items_page walk and per-item mutations always fire live —
+    // record one terminal `live` leg so a fully-cached metadata +
+    // column-resolution path still surfaces as `mixed` (cache-served
+    // metadata + live wire calls). N per-item mutations collapse to
+    // one `record('live', null)` because mergeSource is idempotent
+    // for a constant second leg. Mirrors the empty-match no-op
+    // path's `emptyEnvelopeSource` derivation.
+    sourceAgg.record('live', null);
+    emitMutation({
+        ctx,
+        data: {
+            summary: {
+                matched_count: matchedItemIds.length,
+                applied_count: appliedItems.length,
+                board_id: boardId,
+            },
+            items: appliedItems,
+        },
+        schema: bulkLiveDataSchema,
+        programOpts,
+        warnings: collectedWarnings,
+        ...sourceAgg.result(),
+        apiVersion,
+        resolvedIds,
+    });
+};
+//# sourceMappingURL=update.js.map