monday-cli 0.7.1 → 0.8.0

package/dist/commands/item/update.js

@@ -52,9 +52,10 @@ import { parseArgv } from '../parse-argv.js';
 import { ApiError, MondayCliError, UsageError } from '../../utils/errors.js';
 import { selectMutation, } from '../../api/column-values.js';
 import { executeItemMutation } from '../../api/item-mutation-execute.js';
-import { executeFileColumnSet, fileColumnSetOutputSchema, preCheckM38FileDispatch, } from '../../api/file-column-set.js';
-import { precheckLocalFile } from '../../utils/file-source.js';
+import { executeFileColumnSet, dispatchFileLegsSequentially, fileColumnSetOutputSchema, fileColumnSetMultiOutputSchema, preCheckM38FileDispatch, } from '../../api/file-column-set.js';
+import { precheckLocalFile, isStdinFileSetSource, readStdinFileSource, resolveStdinFilename, STDIN_FILE_SENTINEL, } from '../../utils/file-source.js';
 import { invalidateBoard } from '../../api/cache.js';
+import { addFileToColumn } from '../../api/assets.js';
 import { dispatchSequential, } from '../../api/partial-success-mutation.js';
 import { dispatchParallel } from '../../api/parallel-dispatch.js';
 import { parseSetRawExpression, } from '../../api/raw-write.js';
@@ -64,6 +65,7 @@ import { resolveBoardId } from '../../api/item-board-lookup.js';
 import { SourceAggregator, mergeCacheAge, mergeSource, } from '../../api/source-aggregator.js';
 import { resolveAndTranslate } from '../../api/resolution-pass.js';
 import { foldAndRemap, mergeResolverWarningsIntoError, } from '../../api/resolver-error-fold.js';
+import { projectCauseForEnvelope, reThrowDecorated, } from '../../api/error-decoration.js';
 import { planChanges } from '../../api/dry-run.js';
 import { buildQueryParams } from '../../api/filters.js';
 import { loadBoardMetadata, refreshBoardMetadata, } from '../../api/board-metadata.js';
@@ -77,19 +79,25 @@ import { MIN_CONCURRENCY, MAX_CONCURRENCY, } from '../../api/parallel-dispatch.j
 /**
  * Output envelope union — projected-item for the JSON translator
  * path (text / status / dropdown / date / people / etc.) +
- * file-dispatch envelope for the friendly `--set <file-col>=<path>`
- * path. The file-dispatch shape ships across v0.6-M38 (single-item
- * — `operation: 'add_file_to_column'`) and v0.7-M42 (bulk —
- * `operation: 'item_update_bulk_file_set'`; the per-item fan-out's
- * `data.results[i].asset` slots wrap M31's `Asset` projection). The
- * union below admits only the single-item shape because the bulk
- * variant is emitted via its own `bulkFileSetDataSchema` at the
- * `runItemUpdateBulkFileDispatch` helper; agents discriminate on
- * `operation` (present + literal value identifies the variant).
+ * single-item file-dispatch envelopes for the friendly `--set
+ * <file-col>=<path>` path: v0.6-M38 single-file (`operation:
+ * 'add_file_to_column'`) + v0.8-M46 single-item multi-file
+ * (`operation: 'add_files_to_columns'`; `assets[]` wraps M31's
+ * `Asset` projection per file column).
+ *
+ * The union admits only the SINGLE-ITEM shapes. The BULK file
+ * variants — v0.7-M42 (`item_update_bulk_file_set`) + v0.8-M46
+ * (`item_update_bulk_file_set_multi`) — are emitted via their own
+ * `bulkFileSet*DataSchema` at the `runItemUpdateBulk*FileDispatch`
+ * helpers and stay OUT of this union (the bulk per-item-results
+ * shape is structurally distinct from the single-resource `data`
+ * payload this schema describes); agents discriminate on `operation`
+ * (present + literal value identifies the variant).
  */
 export const itemUpdateOutputSchema = z.union([
     projectedItemSchema,
     fileColumnSetOutputSchema,
+    fileColumnSetMultiOutputSchema,
 ]);
 /**
  * Input shape — supports both single-item and bulk shapes.
@@ -112,6 +120,17 @@ const inputSchema = z
     // cli-design §5.3 line 961-972 (resolution-time, not parse-time).
     setRaw: z.array(z.string()).default([]),
     name: z.string().min(1).optional(),
+    // v0.8-M47 (D7 fold): companion to a stdin file `--set
+    // <file-col>=-` source — sets Monday's wire `Asset.name`. OPTIONAL
+    // (probe: `add_file_to_column` accepts any non-empty filename;
+    // only an EMPTY one `500`s — `.min(1)` rejects `--filename ""` at
+    // the parse boundary as `usage_error`). Default when omitted on a
+    // stdin source: `DEFAULT_STDIN_FILENAME` (`"blob"`). Consulted ONLY
+    // on a `<file-col>=-` stdin dispatch; ignored otherwise (whether a
+    // stdin source exists is only knowable after column resolution, so
+    // a no-stdin `--filename` is a harmless no-op rather than a
+    // resolution-coupled reject).
+    filename: z.string().min(1).optional(),
     board: BoardIdSchema.optional(),
     where: z.array(z.string()).default([]),
     // Empty `--filter-json ''` would slip through `buildQueryParams`
@@ -259,6 +278,7 @@ export const itemUpdateCommand = {
             .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('--filename <name>', "Asset.name for a stdin file `--set <file-col>=-` source (default \"blob\")")
             .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')
@@ -332,6 +352,29 @@ export const itemUpdateCommand = {
                 // the pre-check's resolver warnings + source aggregation
                 // into the final envelope (P3-1 — IMPL round-1 fix).
                 await runItemUpdateSingleFileDispatch({
+                    client,
+                    multipart,
+                    ctx,
+                    programOpts: program.opts(),
+                    apiVersion,
+                    boardId,
+                    itemId: dispatch.itemId,
+                    m38,
+                    isDryRun: globalFlags.dryRun,
+                    retries: globalFlags.retry,
+                    filename: parsed.filename,
+                    toEmit,
+                });
+                return;
+            }
+            if (m38.kind === 'file_multi') {
+                // v0.8-M46 D2 carve-out fold — single-item multi-file
+                // dispatch path. argv parse + pre-check (which returned
+                // `kind: 'file_multi'` here) have already run as live
+                // contract; the per-item multi-leg fan-out body runs N
+                // sequential `add_file_to_column` legs against the single
+                // item (runtime body shipped at v0.8-M46 IMPL).
+                await runItemUpdateSingleFileMultiDispatch({
                     client,
                     multipart,
                     ctx,
@@ -641,10 +684,18 @@ const runBulk = async (inputs) => {
     //      boundary, BEFORE the items_page walker + confirmation
     //      gate. The pre-check resolves setEntries against the now-
     //      warm metadata cache and runs
-    //      `enforceSingleFileColumnSet({callShape: 'item_update_bulk'})`:
+    //      `routeFileColumnDispatch({callShape: 'item_update_bulk'})`:
     //
-    //        - Multi-file `--set` → throws `'multi_file_set_unsupported'`
-    //          (universal rule; single-column-per-wire-call).
+    //        - Multi-file `--set` with distinct file columns →
+    //          returns `kind: 'file_bulk_multi'` (v0.8-M46 D2
+    //          carve-out fold; action body branches into the
+    //          per-item multi-leg fan-out helper
+    //          `runItemUpdateBulkFileMultiDispatch` — runtime body
+    //          shipped at v0.8-M46 IMPL).
+    //        - Multi-file `--set` with duplicate resolved file
+    //          columns → throws `'duplicate_resolved_file_columns'`
+    //          (mirrors JSON path's cross-token duplicate-resolved-
+    //          ID contract; M46 R1 P2-1 fix).
     //        - File `--set` + value `--set` / `--set-raw` / `--name`
     //          → throws `'mixed_file_and_value_sets'` (universal rule;
     //          mixing forces non-atomic multi-leg dispatch).
@@ -668,6 +719,7 @@ const runBulk = async (inputs) => {
     //      unchanged).
     let m38Warnings = [];
     let m38FileBulk;
+    let m38FileBulkMulti;
     if (setEntries.length > 0) {
         const m38 = await preCheckM38FileDispatch({
             client,
@@ -693,6 +745,14 @@ const runBulk = async (inputs) => {
             // `executeFileColumnSet` across matched items.
             m38FileBulk = m38;
         }
+        if (m38.kind === 'file_bulk_multi') {
+            // v0.8-M46 D2 carve-out fold. Hold the file_bulk_multi slot
+            // for the multi-leg per-item fan-out below. items_page walker
+            // + confirmation gate still apply; the dispatch helper fans N
+            // sequential file legs per matched item (runtime body shipped
+            // at v0.8-M46 IMPL).
+            m38FileBulkMulti = m38;
+        }
     }
     const onColumnNotFound = meta.source === 'cache'
         ? async () => {
@@ -848,6 +908,34 @@ const runBulk = async (inputs) => {
         });
         return;
     }
+    // v0.8-M46 D2 carve-out fold — bulk multi-file `--set` dispatch.
+    // The per-item multi-leg fan-out body runs N sequential file legs
+    // per matched item (cross-item parallel under `--concurrency` ×
+    // within-item sequential; runtime body shipped at v0.8-M46 IMPL).
+    // Fires AFTER the items_page walker + confirmation gate (so an
+    // agent sees the matched-count via `confirmation_required` before
+    // any dispatch fans out) and BEFORE the JSON translator path's
+    // `resolveAndTranslate` call.
+    if (m38FileBulkMulti !== undefined) {
+        await runItemUpdateBulkFileMultiDispatch({
+            parsed,
+            client,
+            multipart,
+            ctx,
+            programOpts,
+            apiVersion,
+            boardId,
+            matchedItemIds,
+            m38: m38FileBulkMulti,
+            metaSource: meta.source,
+            metaCacheAgeSeconds: meta.cacheAgeSeconds,
+            filterWarnings: filterResult.warnings,
+            retries: globalFlags.retry,
+            isDryRun: globalFlags.dryRun,
+            noCache: globalFlags.noCache,
+        });
+        return;
+    }
     const { dateResolution, peopleResolution, tagResolution, relationResolution } = 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
@@ -1143,34 +1231,16 @@ const runBulk = async (inputs) => {
                     resolutionSource: remapSource,
                 });
                 // Decorate with bulk-progress details so agents can see how
-                // many items mutated successfully before the failure.
+                // many items mutated successfully before the failure, then
+                // delegate the typed split + wire-metadata spreads to the
+                // shared `reThrowDecorated` helper (R-v0.7-NEW-5).
                 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,
-                    },
+                reThrowDecorated(remapped, {
+                    ...existing,
+                    applied_count: appliedItems.length,
+                    applied_to: appliedItems.map((i) => i.id),
+                    failed_at_item: itemId,
+                    matched_count: matchedItemIds.length,
                 });
             }
             throw err;
@@ -1210,6 +1280,79 @@ const runBulk = async (inputs) => {
     });
 };
 const runItemUpdateSingleFileDispatch = async (inputs) => {
+    // v0.8-M47 (D7 fold): stdin file `--set <file-col>=-` source. The
+    // pre-check (`routeFileColumnDispatch` stdin scope gate) already
+    // confirmed this is the sole file entry on the single-item callShape;
+    // source the Blob from stdin (via `readStdinFileSource`) instead of a
+    // local path. Dry-run emits the D4 size-less echo WITHOUT consuming
+    // stdin; live buffers stdin once + dispatches the pre-built Blob via
+    // M31's `addFileToColumn` fetcher (the path leg's
+    // `executeFileColumnSet` builds its Blob from a path — stdin's is
+    // already in hand) + emits the same M31-shaped envelope.
+    if (isStdinFileSetSource(inputs.m38.rawValue)) {
+        const filename = resolveStdinFilename(inputs.filename);
+        if (inputs.isDryRun) {
+            emitDryRun({
+                ctx: inputs.ctx,
+                programOpts: inputs.programOpts,
+                plannedChanges: [
+                    {
+                        operation: 'add_file_to_column',
+                        item_id: inputs.itemId,
+                        column_id: inputs.m38.columnId,
+                        file_path: STDIN_FILE_SENTINEL,
+                        filename,
+                    },
+                ],
+                source: 'none',
+                cacheAgeSeconds: null,
+                warnings: inputs.m38.warnings,
+                apiVersion: inputs.apiVersion,
+            });
+            return;
+        }
+        const stdinSource = await readStdinFileSource(inputs.ctx.stdin, filename);
+        const stdinResult = await addFileToColumn({
+            client: inputs.client,
+            multipart: inputs.multipart,
+            itemId: inputs.itemId,
+            columnId: inputs.m38.columnId,
+            file: stdinSource.blob,
+            filename: stdinSource.filename,
+            signal: inputs.ctx.signal,
+            retries: inputs.retries,
+        });
+        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+        const stdinData = {
+            operation: 'add_file_to_column',
+            item_id: inputs.itemId,
+            column_id: inputs.m38.columnId,
+            filename: stdinSource.filename,
+            file_size_bytes: stdinSource.fileSizeBytes,
+            asset: stdinResult.asset,
+        };
+        emitMutation({
+            ctx: inputs.ctx,
+            data: stdinData,
+            schema: fileColumnSetOutputSchema,
+            programOpts: inputs.programOpts,
+            warnings: inputs.m38.warnings.map((w) => ({
+                code: w.code,
+                message: w.message,
+                details: w.details,
+            })),
+            ...inputs.toEmit({
+                data: stdinResult.asset,
+                complexity: stdinResult.complexity,
+                stats: { attempts: 1, totalBackoffMs: 0 },
+            }),
+            source: 'live',
+            cacheAgeSeconds: null,
+            complexity: stdinResult.complexity,
+            resolvedIds: { [inputs.m38.token]: inputs.m38.columnId },
+        });
+        return;
+    }
     const precheck = await precheckLocalFile(inputs.m38.rawValue);
     if (inputs.isDryRun) {
         emitDryRun({
@@ -1361,13 +1504,15 @@ const runItemUpdateSingleFileDispatch = async (inputs) => {
 //   - R-NEW-72 (post-fix-up cross-doc grep) — apply at every
 //     Codex IMPL fix-up round that flips a contract surface.
 //
-// **Future lift candidate.** The fail-fast error-decoration block
-// (`if (err.code === 'usage_error') { throw new UsageError(...) } else
-// { throw new ApiError(...) }`) is byte-equivalent across this
-// helper and the JSON-bulk action body (R-NEW-58 2-consumer
-// trigger). Lift candidate fires at the 3rd consumer (M43 create-
-// time fold may add one if its rollback / orphan-warn shape
-// re-uses the same decoration).
+// **R-v0.7-NEW-5 — SHIPPED (v0.8 refactor cluster).** The fail-fast
+// error-decoration block (the `usage_error → UsageError` / else →
+// `ApiError` typed split + the conditional wire-metadata spreads)
+// reached 4 consumers (this helper + the JSON-bulk action body + the
+// M46 file-bulk-multi path + bulk clear) and was lifted to
+// `reThrowDecorated` in `src/api/error-decoration.ts`. Each site now
+// assembles its own `details` decoration and delegates the typed
+// split; the helper carries the focused unit test that recovers the
+// conditional-spread branch coverage.
 // ============================================================
 /**
  * Per-item dispatch result for v0.7-M42 bulk file `--set` carve-out
@@ -1422,6 +1567,95 @@ export const bulkFileSetDataSchema = z.object({
     }),
     results: z.array(bulkFileSetResultSchema),
 });
+/**
+ * v0.8-M46 bulk multi-file `--set` per-item result schema (D6
+ * closure — separate envelope shape from M42's single-file
+ * `bulkFileSetResultSchema`). Per-item record carries the
+ * per-leg asset projections + an `applied_file_columns` echo
+ * slot (length 1..N reflecting which file columns landed
+ * successfully on this item). On per-item partial failure mid-
+ * multi-leg under `--continue-on-error`, `applied_file_columns`
+ * length is 0..N-1 (reflecting columns that landed before the
+ * failing leg) + `failed_file_column` carries the failing
+ * column ID + `error` carries the leg's underlying error.
+ *
+ * **Status: schema landed at v0.8-M46 pre-flight contract diff
+ * (Codex R1 P2-2 fix); runtime emit shipped at v0.8-M46 IMPL.**
+ * `runItemUpdateBulkFileMultiDispatch` (below) emits against this
+ * schema. Mirrors M42's per-item partial-success shape extended
+ * with the multi-leg slots.
+ */
+export const bulkFileSetMultiResultSchema = z.object({
+    item_id: z.string().min(1),
+    ok: z.boolean(),
+    /**
+     * Per-leg asset projections — one per file column that landed
+     * on this item. Length N on success; length 0..N-1 on per-item
+     * partial failure (`ok: false` with `error` populated). Each
+     * entry carries the column ID + asset shape (mirrors M31's
+     * Asset projection inside a per-leg context).
+     */
+    assets: z
+        .array(z
+        .object({
+        column_id: z.string().min(1),
+        filename: z.string().min(1),
+        file_size_bytes: z.number().int().nonnegative(),
+        asset: z
+            .object({
+            id: z.string().min(1),
+            name: z.string().min(1),
+        })
+            .loose(),
+    })
+        .strict())
+        .optional(),
+    /**
+     * Echo of file column IDs that landed successfully on this
+     * item, in dispatch order. Length 1..N on success; length
+     * 0..N-1 on per-item partial failure (reflecting columns that
+     * landed before the failing leg).
+     */
+    applied_file_columns: z.array(z.string().min(1)).optional(),
+    /** Column ID of the failing leg on per-item partial failure. */
+    failed_file_column: z.string().min(1).optional(),
+    error: z
+        .object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+    })
+        .optional(),
+});
+/**
+ * v0.8-M46 bulk multi-file `--set` envelope `data` shape.
+ * Discriminate from M42's single-file `bulkFileSetDataSchema`
+ * via `operation: 'item_update_bulk_file_set_multi'` (plural).
+ * Agents reading `data.operation` branch uniformly across
+ * single + multi shapes. Aggregate `summary` extends M42's
+ * shape with `file_count: number` (the N file columns per item
+ * the call attempted).
+ *
+ * Invariant: `matched_count === applied_count + failed_count`
+ * (per-item rollup; mirrors M42 + M25 invariant). Per-item
+ * partial failure mid-multi-leg counts toward `failed_count`
+ * with the per-item record's `applied_file_columns` reflecting
+ * the partial-leg success.
+ *
+ * **Status: schema landed at v0.8-M46 pre-flight contract diff
+ * (Codex R1 P2-2 fix); runtime emit shipped at v0.8-M46 IMPL.**
+ */
+export const bulkFileSetMultiDataSchema = z.object({
+    operation: z.literal('item_update_bulk_file_set_multi'),
+    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),
+        file_count: z.number().int().min(2),
+        file_column_ids: z.array(z.string().min(1)).min(2),
+    }),
+    results: z.array(bulkFileSetMultiResultSchema),
+});
 /**
  * Bulk file `--set` per-item dispatch helper (v0.7-M42 D5 carve-out
  * fold).
@@ -1622,9 +1856,9 @@ export const runItemUpdateBulkFileDispatch = async (inputs) => {
                     // fail-fast error so a follow-up read doesn't serve stale
                     // metadata. Mirrors the M38 single-item invalidate-on-
                     // success pattern; the JSON-bulk fail-fast path has the
-                    // same gap (unchanged by this commit — separate lift
-                    // candidate per the future-lift-candidate note in the
-                    // module docstring).
+                    // same cache-invalidation gap (still-open lift candidate,
+                    // unrelated to the now-shipped R-v0.7-NEW-5 error-decoration
+                    // lift).
                     if (appliedAssets.length > 0) {
                         await invalidateBoard(inputs.boardId, inputs.ctx.env);
                     }
@@ -1647,10 +1881,11 @@ export const runItemUpdateBulkFileDispatch = async (inputs) => {
                         noCache: inputs.noCache,
                         resolutionSource: remapSource,
                     });
-                    // Same decoration shape as the JSON-bulk fail-fast path
-                    // (lines ~1334-1361 above). Preserves the existing error
-                    // class' fields and grafts `applied_count` / `applied_to`
-                    // / `failed_at_item` / `matched_count` onto `details`.
+                    // Same decoration shape as the JSON-bulk fail-fast path in
+                    // `runBulk` above. Grafts `applied_count` / `applied_to` /
+                    // `failed_at_item` / `matched_count` onto `details`, then
+                    // delegates the typed split to `reThrowDecorated` (which
+                    // preserves the existing error class' wire-metadata fields).
                     const existing = remapped.details ?? {};
                     const decoration = {
                         ...existing,
@@ -1659,33 +1894,7 @@ export const runItemUpdateBulkFileDispatch = async (inputs) => {
                         failed_at_item: itemId,
                         matched_count: inputs.matchedItemIds.length,
                     };
-                    if (remapped.code === 'usage_error') {
-                        throw new UsageError(remapped.message, {
-                            ...(remapped.cause === undefined
-                                ? {}
-                                : { cause: remapped.cause }),
-                            details: decoration,
-                        });
-                    }
-                    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: decoration,
-                    });
+                    reThrowDecorated(remapped, decoration);
                 }
                 // Non-CliError programmer bug — re-throw to the runner's
                 // catch-all (surfaces as `internal_error` whole-call;
@@ -1879,4 +2088,497 @@ export const runItemUpdateBulkFileDispatch = async (inputs) => {
         resolvedIds,
     });
 };
+/**
+ * Single-item multi-file `--set` dispatch helper (v0.8-M46 D2
+ * carve-out fold). Runtime body shipped at v0.8-M46 IMPL.
+ *
+ * **Execution shape:**
+ *
+ *   1. Single upfront `precheckLocalFile` per file path (N pre-checks
+ *      in argv order; D3 closure). Any pre-check failure aborts the
+ *      whole call with `usage_error` (`file_not_readable` /
+ *      `file_empty`) BEFORE any wire round-trip fires — atomicity-
+ *      before-wire per cli-design §5.8.
+ *   2. Dry-run branch — N `add_file_to_column` planned_changes,
+ *      `source: 'none'` (pure-local, mirrors M38 single-item
+ *      dry-run); no multipart wire fires.
+ *   3. Live branch — sequential N legs via
+ *      {@link dispatchFileLegsSequentially} (R-v0.8-NEW-1 shared
+ *      helper) against the single `inputs.itemId`. On partial
+ *      failure, `invalidateBoard` (any landed legs mutated the
+ *      board's asset state wire-side) then `internal_error` with
+ *      `details.reason: 'multi_file_update_partial_failure'` +
+ *      `details.item_id` + `details.applied_file_columns` (length
+ *      0..N-1) + `details.failed_file_column` + `details.cause`
+ *      (M31 wire-failure surface, JSON projection) + `details.hint`.
+ *      Unlike the bulk + create paths, the single-item path does NOT
+ *      run `foldAndRemap` on the failing leg's cause — it mirrors the
+ *      M38 single-item precedent (`runItemUpdateSingleFileDispatch`
+ *      doesn't remap either); an archived file column is already
+ *      rejected at the pre-check's `includeArchived` archived-column
+ *      guard before dispatch.
+ *   4. Full success — single `invalidateBoard` then envelope emit
+ *      per `fileColumnSetMultiOutputSchema`
+ *      (`operation: 'add_files_to_columns'` + `assets: [...]` +
+ *      `applied_file_columns: [...]`, both length N).
+ */
+const runItemUpdateSingleFileMultiDispatch = async (inputs) => {
+    // 1) Upfront pre-check per file path, in argv order. A bad path
+    //    surfaces `usage_error` (exit 1) whole-call-abort before any
+    //    multipart wire leg fires (cli-design §5.8). R-v0.6-NEW-1
+    //    `precheckLocalFile` called N times (one per file column).
+    const legEntries = [];
+    for (const entry of inputs.m38.entries) {
+        const precheck = await precheckLocalFile(entry.rawValue);
+        legEntries.push({
+            columnId: entry.columnId,
+            rawValue: entry.rawValue,
+            filePath: precheck.filePath,
+            filename: precheck.filename,
+            fileSizeBytes: precheck.fileSizeBytes,
+        });
+    }
+    const warnings = inputs.m38.warnings.map((w) => ({
+        code: w.code,
+        message: w.message,
+        details: w.details,
+    }));
+    const resolvedIds = Object.fromEntries(inputs.m38.entries.map((e) => [e.token, e.columnId]));
+    // 2) Dry-run branch — N planned_changes; pure-local, `source: 'none'`
+    //    (mirrors M38 single-item dry-run).
+    if (inputs.isDryRun) {
+        emitDryRun({
+            ctx: inputs.ctx,
+            programOpts: inputs.programOpts,
+            plannedChanges: legEntries.map((leg) => ({
+                operation: 'add_file_to_column',
+                item_id: inputs.itemId,
+                column_id: leg.columnId,
+                file_path: leg.rawValue,
+                filename: leg.filename,
+                file_size_bytes: leg.fileSizeBytes,
+            })),
+            source: 'none',
+            cacheAgeSeconds: null,
+            warnings,
+            apiVersion: inputs.apiVersion,
+        });
+        return;
+    }
+    // 3) Live branch — sequential N-leg fan-out against the single item.
+    const dispatch = await dispatchFileLegsSequentially({
+        client: inputs.client,
+        multipart: inputs.multipart,
+        itemId: inputs.itemId,
+        entries: legEntries,
+        signal: inputs.ctx.signal,
+        retries: inputs.retries,
+    });
+    if (dispatch.failure !== undefined) {
+        // Partial failure. If any leg landed, the board's asset state
+        // mutated wire-side — invalidate before re-throwing so a
+        // follow-up read doesn't serve stale metadata (mirrors M42's
+        // fail-fast invalidate-on-partial-apply).
+        if (dispatch.appliedColumns.length > 0) {
+            await invalidateBoard(inputs.boardId, inputs.ctx.env);
+        }
+        const cause = dispatch.failure.cause;
+        const causeProjection = projectCauseForEnvelope(cause);
+        throw new ApiError('internal_error', `Multi-file \`--set\` on item ${inputs.itemId} partially failed: ` +
+            `${String(dispatch.appliedColumns.length)} of ` +
+            `${String(legEntries.length)} file column(s) landed before column ` +
+            `${dispatch.failure.failedColumn} failed ` +
+            `(${cause.code}: ${cause.message}). The applied file columns ` +
+            `persist on Monday; retry only the unfailed columns with ` +
+            `\`monday item set ${inputs.itemId} <file-col>=<path>\`, or reissue ` +
+            `all ${String(legEntries.length)} \`--set\` entries.`, {
+            cause,
+            details: {
+                reason: 'multi_file_update_partial_failure',
+                item_id: inputs.itemId,
+                applied_file_columns: dispatch.appliedColumns,
+                failed_file_column: dispatch.failure.failedColumn,
+                cause: causeProjection,
+                hint: `${String(dispatch.appliedColumns.length)} file column(s) ` +
+                    `already landed on item ${inputs.itemId}; retry the unfailed ` +
+                    `columns alone with \`monday item set ${inputs.itemId} ` +
+                    `<file-col>=<path>\`, or reissue every \`--set\` entry (the ` +
+                    `landed columns will be overwritten with the same files).`,
+            },
+        });
+    }
+    // 4) Full success — single board-cache invalidate before emit
+    //    (mirrors M38 single-leg invalidate timing; one board covers
+    //    every leg's mutated asset slot).
+    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+    const data = {
+        operation: 'add_files_to_columns',
+        item_id: inputs.itemId,
+        assets: dispatch.assets.map((a) => ({
+            column_id: a.column_id,
+            filename: a.filename,
+            file_size_bytes: a.file_size_bytes,
+            asset: a.asset,
+        })),
+        applied_file_columns: [...dispatch.appliedColumns],
+    };
+    emitMutation({
+        ctx: inputs.ctx,
+        data,
+        schema: fileColumnSetMultiOutputSchema,
+        programOpts: inputs.programOpts,
+        warnings,
+        ...inputs.toEmit({
+            data: dispatch.assets,
+            complexity: dispatch.lastComplexity,
+            stats: { attempts: 1, totalBackoffMs: 0 },
+        }),
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: dispatch.lastComplexity,
+        resolvedIds,
+    });
+};
+/**
+ * Bulk multi-file `--set` per-item dispatch helper (v0.8-M46 D2
+ * carve-out fold). Runtime body shipped at v0.8-M46 IMPL.
+ *
+ * **Execution shape (extends M42's `runItemUpdateBulkFileDispatch`
+ * single-file bulk path to N file legs per item):**
+ *
+ *   1. Single upfront `precheckLocalFile` pass over ALL N file paths
+ *      (D3 — N pre-checks total, shared across the M matched items,
+ *      NOT N×M). Any failure aborts the whole call with `usage_error`
+ *      regardless of `--continue-on-error` per cli-design §5.8.
+ *   2. Dry-run branch — N×M `add_file_to_column` planned_changes
+ *      (one per (item, file column) pair); source aggregates the
+ *      upstream metadata + items_page legs per M42's pattern.
+ *   3. Live branch — cross-item parallel via M42's `dispatchParallel`
+ *      / `dispatchSequential` (under `--concurrency`) × within-item
+ *      sequential N legs via {@link dispatchFileLegsSequentially}
+ *      (D1). Two shapes per `parsed.continueOnError`:
+ *      - **Fail-fast (default)** — sequential over matched items;
+ *        first per-item failure aborts whole-call with
+ *        `details.applied_to` (items where ALL legs landed) +
+ *        `details.applied_file_columns_per_item` (the failed item's
+ *        partial-leg map) + `details.failed_at_item` +
+ *        `details.failed_file_column`.
+ *      - **`--continue-on-error`** — per-item failures land as
+ *        `data.results[i].error` extended with
+ *        `applied_file_columns` + `failed_file_column`; partially-
+ *        landed assets carry on `data.results[i].assets`.
+ *   4. Post-dispatch `invalidateBoard` + emit per
+ *      `bulkFileSetMultiDataSchema`
+ *      (`operation: 'item_update_bulk_file_set_multi'` +
+ *      `summary.{file_count, file_column_ids}`).
+ *
+ * Per-item failures route through `foldAndRemap` BEFORE the per-item
+ * record / fail-fast decoration so the stable-code rule (cli-design
+ * §6.5) surfaces `column_archived` for cache-served file-column
+ * resolution against an archived column — mirrors M42's bulk
+ * single-file remap.
+ */
+const runItemUpdateBulkFileMultiDispatch = async (inputs) => {
+    // 1) Single upfront pre-check pass over ALL N file paths (D3).
+    //    Shared across the M matched items — N pre-checks, NOT N×M.
+    //    Whole-call abort regardless of `--continue-on-error` per
+    //    cli-design §5.8 (`precheckLocalFile` throws `usage_error`
+    //    with `file_not_readable` / `file_empty`).
+    const legEntries = [];
+    for (const entry of inputs.m38.entries) {
+        const precheck = await precheckLocalFile(entry.rawValue);
+        legEntries.push({
+            columnId: entry.columnId,
+            rawValue: entry.rawValue,
+            filePath: precheck.filePath,
+            filename: precheck.filename,
+            fileSizeBytes: precheck.fileSizeBytes,
+        });
+    }
+    const fileColumnIds = legEntries.map((leg) => leg.columnId);
+    const combinedWarnings = dedupeWarnings([
+        ...inputs.filterWarnings,
+        ...inputs.m38.warnings,
+    ]);
+    const resolvedIds = Object.fromEntries(inputs.m38.entries.map((e) => [e.token, e.columnId]));
+    // Source aggregator — mirrors M42's bulk single-file pattern.
+    // Seeds the metadata leg, folds the M38 pre-check leg + a synthetic
+    // 'live' leg for the items_page walker (always fired upstream).
+    const sourceAgg = new SourceAggregator({
+        source: inputs.metaSource,
+        cacheAgeSeconds: inputs.metaCacheAgeSeconds,
+    });
+    if (inputs.m38.source !== undefined) {
+        sourceAgg.record(inputs.m38.source, inputs.m38.cacheAgeSeconds);
+    }
+    sourceAgg.record('live', null);
+    // 2) Dry-run branch — N×M planned_changes (one `add_file_to_column`
+    //    per (item, file column) pair). No file bytes loaded, no
+    //    multipart wire. Source carries the aggregated upstream legs
+    //    (mirrors M42's bulk dry-run, which is NOT pure-local).
+    if (inputs.isDryRun) {
+        const plannedChanges = inputs.matchedItemIds.flatMap((itemId) => legEntries.map((leg) => ({
+            operation: 'add_file_to_column',
+            item_id: itemId,
+            column_id: leg.columnId,
+            file_path: leg.rawValue,
+            filename: leg.filename,
+            file_size_bytes: leg.fileSizeBytes,
+        })));
+        const dryRunAgg = sourceAgg.result();
+        emitDryRun({
+            ctx: inputs.ctx,
+            programOpts: inputs.programOpts,
+            plannedChanges,
+            source: dryRunAgg.source,
+            cacheAgeSeconds: dryRunAgg.cacheAgeSeconds,
+            warnings: combinedWarnings,
+            apiVersion: inputs.apiVersion,
+        });
+        return;
+    }
+    // 3) Live dispatch. Record the dispatch leg as 'live'.
+    sourceAgg.record('live', null);
+    const liveAgg = sourceAgg.result();
+    const remapSource = inputs.m38.source ?? 'live';
+    const fileCount = legEntries.length;
+    const continueOnError = inputs.parsed.continueOnError === true;
+    if (!continueOnError) {
+        // Fail-fast bulk multi-file dispatch. Sequential over matched
+        // items (M30 D2: `--concurrency requires --continue-on-error`).
+        // Each item fans out N sequential file legs; first per-item
+        // failure aborts whole-call.
+        const fullyApplied = [];
+        for (const itemId of inputs.matchedItemIds) {
+            const dispatch = await dispatchFileLegsSequentially({
+                client: inputs.client,
+                multipart: inputs.multipart,
+                itemId,
+                entries: legEntries,
+                signal: inputs.ctx.signal,
+                retries: inputs.retries,
+            });
+            if (dispatch.failure !== undefined) {
+                // Any prior item fully applied OR this item landed ≥1 leg →
+                // the board's asset state mutated wire-side; invalidate
+                // before re-throwing (mirrors M42 fail-fast invalidate).
+                if (fullyApplied.length > 0 || dispatch.appliedColumns.length > 0) {
+                    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+                }
+                const remapped = await foldAndRemap({
+                    err: dispatch.failure.cause,
+                    warnings: inputs.m38.warnings,
+                    client: inputs.client,
+                    boardId: inputs.boardId,
+                    columnIds: fileColumnIds,
+                    env: inputs.ctx.env,
+                    noCache: inputs.noCache,
+                    resolutionSource: remapSource,
+                });
+                const existing = remapped.details ?? {};
+                const decoration = {
+                    ...existing,
+                    applied_count: fullyApplied.length,
+                    applied_to: fullyApplied.map((a) => a.itemId),
+                    applied_file_columns_per_item: {
+                        [itemId]: dispatch.appliedColumns,
+                    },
+                    failed_at_item: itemId,
+                    failed_file_column: dispatch.failure.failedColumn,
+                    matched_count: inputs.matchedItemIds.length,
+                    file_count: fileCount,
+                    file_column_ids: fileColumnIds,
+                };
+                reThrowDecorated(remapped, decoration);
+            }
+            fullyApplied.push({ itemId, assets: dispatch.assets });
+        }
+        // Every item applied all N legs — single board-cache invalidate
+        // before emit.
+        await invalidateBoard(inputs.boardId, inputs.ctx.env);
+        const results = fullyApplied.map(({ itemId, assets }) => ({
+            item_id: itemId,
+            ok: true,
+            assets: assets.map((a) => ({
+                column_id: a.column_id,
+                filename: a.filename,
+                file_size_bytes: a.file_size_bytes,
+                asset: a.asset,
+            })),
+            applied_file_columns: [...fileColumnIds],
+        }));
+        const data = {
+            operation: 'item_update_bulk_file_set_multi',
+            summary: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: fullyApplied.length,
+                failed_count: 0,
+                board_id: inputs.boardId,
+                file_count: fileCount,
+                file_column_ids: [...fileColumnIds],
+            },
+            results,
+        };
+        emitMutation({
+            ctx: inputs.ctx,
+            data,
+            schema: bulkFileSetMultiDataSchema,
+            programOpts: inputs.programOpts,
+            warnings: combinedWarnings,
+            source: liveAgg.source,
+            cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+            apiVersion: inputs.apiVersion,
+            resolvedIds,
+        });
+        return;
+    }
+    // `--continue-on-error` path. Per-item failures land as per-record
+    // slots; the envelope is `ok: true` regardless of how many items
+    // failed (universal partial-success rule). Each item's within-item
+    // fan-out is sequential; a partial mid-multi-leg failure records
+    // the landed assets + applied_file_columns + failed_file_column on
+    // the per-item record. `internal_error` (or non-CliError) re-throws
+    // whole-call via the shared dispatcher's escape hatch.
+    const successById = new Map();
+    const partialById = new Map();
+    const perTargetDispatch = async ({ targetId, }) => {
+        const dispatch = await dispatchFileLegsSequentially({
+            client: inputs.client,
+            multipart: inputs.multipart,
+            itemId: targetId,
+            entries: legEntries,
+            signal: inputs.ctx.signal,
+            retries: inputs.retries,
+        });
+        if (dispatch.failure !== undefined) {
+            // Record the partial state (landed assets + applied columns +
+            // failing column) keyed by item_id, then re-throw the remapped
+            // error so the shared dispatcher captures it as `ok: false` +
+            // `error: {code, message}`. `foldAndRemap` NEVER converts a
+            // non-`internal_error` into `internal_error`, so the
+            // dispatcher's `internal_error` escape hatch stays intact.
+            partialById.set(targetId, {
+                assets: dispatch.assets,
+                appliedColumns: dispatch.appliedColumns,
+                failedColumn: dispatch.failure.failedColumn,
+            });
+            const remapped = await foldAndRemap({
+                err: dispatch.failure.cause,
+                warnings: inputs.m38.warnings,
+                client: inputs.client,
+                boardId: inputs.boardId,
+                columnIds: fileColumnIds,
+                env: inputs.ctx.env,
+                noCache: inputs.noCache,
+                resolutionSource: remapSource,
+            });
+            throw remapped;
+        }
+        successById.set(targetId, dispatch.assets);
+    };
+    let dispatchResults;
+    if (inputs.parsed.concurrency !== undefined &&
+        inputs.parsed.concurrency > 1) {
+        dispatchResults = await dispatchParallel(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.parsed.concurrency, inputs.ctx.signal);
+    }
+    else {
+        dispatchResults = await dispatchSequential(inputs.matchedItemIds, 'item_id', perTargetDispatch, inputs.ctx.signal);
+    }
+    // Single post-dispatch invalidate (fires even when every item
+    // failed — wire calls still fired against Monday).
+    await invalidateBoard(inputs.boardId, inputs.ctx.env);
+    const results = dispatchResults.map((row) => {
+        const itemIdSlot = row.item_id;
+        /* c8 ignore next 8 — dispatcher contract: every result row carries
+           the id-field slot; this guard catches a contract violation that
+           would surface as a programmer bug, not a Monday-side failure. */
+        if (typeof itemIdSlot !== 'string' || itemIdSlot.length === 0) {
+            throw new ApiError('internal_error', 'bulk multi-file dispatch result row is missing the `item_id` field — dispatcher contract violation.', { details: { record_keys: Object.keys(row) } });
+        }
+        if (row.ok) {
+            const assets = successById.get(itemIdSlot);
+            /* c8 ignore next 8 — side-map invariant: every successful
+               per-target dispatch records its assets; this guard catches a
+               wrapper-layer miss (programmer bug). */
+            if (assets === undefined) {
+                throw new ApiError('internal_error', `bulk multi-file dispatch result row for item_id ${itemIdSlot} reported ok: true but no assets were captured — wrapper-layer side-map miss.`, { details: { item_id: itemIdSlot } });
+            }
+            return {
+                item_id: itemIdSlot,
+                ok: true,
+                assets: assets.map((a) => ({
+                    column_id: a.column_id,
+                    filename: a.filename,
+                    file_size_bytes: a.file_size_bytes,
+                    asset: a.asset,
+                })),
+                applied_file_columns: [...fileColumnIds],
+            };
+        }
+        /* c8 ignore next 8 — dispatcher contract: every `ok: false` row
+           carries the `error` slot (populated by the shared dispatcher's
+           per-target error decoration). */
+        if (row.error === undefined) {
+            throw new ApiError('internal_error', `bulk multi-file dispatch result row for item_id ${itemIdSlot} reported ok: false but no error payload was captured — dispatcher contract violation.`, { details: { item_id: itemIdSlot } });
+        }
+        const partial = partialById.get(itemIdSlot);
+        /* c8 ignore next 8 — side-map invariant: every per-target failure
+           routes through `perTargetDispatch`'s `partialById.set` before
+           re-throwing; a miss is a wrapper-layer programmer bug. */
+        if (partial === undefined) {
+            throw new ApiError('internal_error', `bulk multi-file dispatch result row for item_id ${itemIdSlot} reported ok: false but no partial-leg state was captured — wrapper-layer side-map miss.`, { details: { item_id: itemIdSlot } });
+        }
+        return {
+            item_id: itemIdSlot,
+            ok: false,
+            assets: partial.assets.map((a) => ({
+                column_id: a.column_id,
+                filename: a.filename,
+                file_size_bytes: a.file_size_bytes,
+                asset: a.asset,
+            })),
+            applied_file_columns: [...partial.appliedColumns],
+            failed_file_column: partial.failedColumn,
+            error: { code: row.error.code, message: row.error.message },
+        };
+    });
+    const appliedCount = results.filter((r) => r.ok).length;
+    const failedCount = results.filter((r) => !r.ok).length;
+    /* c8 ignore next 11 — invariant: every matched item produces exactly
+       one result row under both dispatchers; mismatch indicates a
+       programmer bug in the dispatcher or the fold. */
+    if (appliedCount + failedCount !== inputs.matchedItemIds.length) {
+        throw new ApiError('internal_error', `bulk multi-file dispatch summary invariant violated — matched_count (${String(inputs.matchedItemIds.length)}) !== applied_count (${String(appliedCount)}) + failed_count (${String(failedCount)}).`, {
+            details: {
+                matched_count: inputs.matchedItemIds.length,
+                applied_count: appliedCount,
+                failed_count: failedCount,
+                board_id: inputs.boardId,
+            },
+        });
+    }
+    const data = {
+        operation: 'item_update_bulk_file_set_multi',
+        summary: {
+            matched_count: inputs.matchedItemIds.length,
+            applied_count: appliedCount,
+            failed_count: failedCount,
+            board_id: inputs.boardId,
+            file_count: fileCount,
+            file_column_ids: [...fileColumnIds],
+        },
+        results,
+    };
+    emitMutation({
+        ctx: inputs.ctx,
+        data,
+        schema: bulkFileSetMultiDataSchema,
+        programOpts: inputs.programOpts,
+        warnings: combinedWarnings,
+        source: liveAgg.source,
+        cacheAgeSeconds: liveAgg.cacheAgeSeconds,
+        apiVersion: inputs.apiVersion,
+        resolvedIds,
+    });
+};
 //# sourceMappingURL=update.js.map