monday-cli 0.5.0 → 0.7.0

package/dist/api/file-column-set.js

@@ -0,0 +1,568 @@
+/**
+ * Files-shaped friendly `--set` dispatch (`cli-design.md` §5.3
+ * writer-expansion roadmap "files" row + §13 v0.6 entry,
+ * `v0.6-plan.md` §3 M38).
+ *
+ * **Status: runtime bodies shipped at v0.6-M38 IMPL.** The dispatch
+ * type signatures + the per-mutex-rejection error shape + the
+ * fetcher wrapping M31's `addFileToColumn` all landed at pre-flight;
+ * IMPL swaps the c8-ignored stub bodies for runtime logic. No new
+ * wire fetcher (M38 reuses the v0.4-M31 multipart wire verbatim);
+ * no new transport seam.
+ *
+ * **Wire surface.** Zero net change. When `monday item set <iid>
+ * <file-col>=<path>` OR `monday item update <iid> --set
+ * <file-col>=<path>` resolves to a `file`-typed column, the
+ * command action body branches OFF the standard JSON-translator
+ * path INTO M31's multipart `addFileToColumn` fetcher via
+ * `executeFileColumnSet` below. The translator
+ * (`translateColumnValueAsync` in `column-values.ts`) stays
+ * JSON-output-shaped for the 13 existing writable types — the
+ * file-column dispatch is a SIBLING leg routed at the command
+ * action body level, NOT a new payload format inside the
+ * translator union.
+ *
+ * **Why a sibling leg, not a translator widening.** Three reasons
+ * pin the design (cli-design §5.3 step 4 + step 5 prose):
+ *
+ *   1. The wire surface is fundamentally different — multipart
+ *      `add_file_to_column` vs JSON `change_column_value` /
+ *      `change_multiple_column_values`. Folding the file payload
+ *      into `ColumnValuePayload` would require a `format: 'file'`
+ *      union variant that `selectMutation` can't bundle into the
+ *      multi-mutation (each `add_file_to_column` is a single
+ *      per-column multipart round-trip; bundling N file uploads
+ *      into one mutation isn't a Monday wire shape).
+ *   2. The atomicity contract differs — the 13 existing types
+ *      bundle atomically via `change_multiple_column_values` when
+ *      ≥2 columns target the same item. File-column writes are
+ *      single-column-per-call only on Monday's wire; mixing a
+ *      file-column `--set` with any value `--set` / `--set-raw` /
+ *      `--name` in the same call would force a multi-leg dispatch
+ *      that breaks the existing atomicity guarantee. M38 enforces
+ *      single-file-only via the mutex rules below (D2 closure) —
+ *      the existing atomicity contract stays intact.
+ *   3. The translator's input contract is "value-string-to-JSON-
+ *      payload" — file columns take a file path, not a value
+ *      string. Path validation + `fs.stat` + `fs.access(R_OK)` +
+ *      Blob construction don't fit the translator's pure-function
+ *      shape; routing the path through the sibling leg keeps each
+ *      helper focused.
+ *
+ * **Reuse from v0.4-M31.** The wire dispatch reuses
+ * `addFileToColumn` from `src/api/assets.ts` verbatim — same
+ * `MultipartTransport.request(...)` round-trip, same `withRetry`
+ * shape, same `file_too_large` rewrap-inside-retry-thunk pattern
+ * (R-v0.4-W2 axis 7 "non-retryable rewrap placement" carries
+ * through safely-by-construction since the dispatch goes through
+ * the existing fetcher rather than a re-implementation).
+ *
+ * **Consumer counts post v0.6-M38 IMPL close** (runtime bodies
+ * shipped at `e749931` + the R-v0.6-NEW-1 lift at `3c2a9b0`;
+ * pre-flight stubs collapsed):
+ *
+ *   - `addFileToColumn` (M31): 2 consumers (M31's `item upload`
+ *     action body + M38's `executeFileColumnSet` runtime body).
+ *   - `MultipartTransport` via `ResolvedClient.multipart`: 2
+ *     consumers (the same test seam pattern; M31's two upload
+ *     verbs + M38's dispatch share the slot).
+ *   - `sniffContentType` from `src/utils/mime.ts`: 2 consumers
+ *     post-lift (M31's `item upload` + M31's `update upload` —
+ *     both via {@link buildBlobFromPath}; M38 routes through
+ *     `buildBlobFromPath` rather than calling `sniffContentType`
+ *     directly).
+ *   - **R-v0.6-NEW-1 SHIPPED at IMPL kickoff**: the file-pre-check
+ *     + Blob-construction pattern lifted to `src/utils/file-source
+ *     .ts` (`precheckLocalFile` + `buildBlobFromPath` — 3 consumers
+ *     post-lift: M31's `item upload`, M31's `update upload`, M38's
+ *     `executeFileColumnSet`).
+ *
+ * **Mutex rules (D2 closure).** Enforced at the column-resolution
+ * boundary (parse-time can't know — column types only resolve
+ * after metadata loads). When any resolved column has `type ===
+ * 'file'`:
+ *
+ *   - Exactly ONE file `--set` entry allowed per call (single-
+ *     file scope; multi-file dispatch defers to v0.7.x — Monday's
+ *     `add_file_to_column` is single-column per call on the wire
+ *     regardless of how many items the dispatch fans out across,
+ *     so this rule is universal).
+ *   - NO other value `--set` / `--set-raw` / `--name` flags
+ *     allowed (mixing would force non-atomic multi-leg dispatch
+ *     across the multipart + JSON wire surfaces).
+ *   - Bulk `item update --where ... --set <file-col>=<path>` —
+ *     **CARVED OUT at v0.7-M42** (D5 fold). At v0.6-M38 this was
+ *     REJECTED with `'file_set_on_bulk_unsupported'`; v0.7-M42's
+ *     pre-flight contract diff returns
+ *     `{ kind: 'file_bulk', columnId, rawValue }` from
+ *     {@link enforceSingleFileColumnSet} on the clean dispatch
+ *     path so the action body can branch into the per-item
+ *     multipart fan-out. Multi-file / mixed mutex rules STILL
+ *     apply on bulk (those are universal).
+ *   - `item create --set <file-col>=<path>` — **CARVED OUT at
+ *     v0.7-M43** (D6 fold). At v0.6-M38 this was REJECTED with
+ *     `'file_set_on_create_unsupported'`; v0.7-M43's pre-flight
+ *     contract diff returns
+ *     `{ kind: 'file_create', columnId, rawValue }` from
+ *     {@link enforceSingleFileColumnSet} on the clean dispatch
+ *     path so the action body can branch into the two-leg
+ *     dispatch (`create_item` then `add_file_to_column`).
+ *     Multi-file mutex rule STILL applies on create (universal).
+ *     The mixed rule is callShape-aware: on `'item_create'` the
+ *     `--name` arm + non-file value `--set` / `--set-raw` arms
+ *     are SUPPRESSED (leg-1 `create_item` natively bundles
+ *     `column_values` atomically + `item_name` is required on
+ *     create); the D3 `--set-raw <file-col>=<json>` rejection
+ *     at `raw-write.ts:translateRawColumnValue` stays in force
+ *     (separate enforcement layer).
+ *
+ * Rejection surfaces share the `usage_error.details.reason`
+ * discriminator pattern from M14 / M27 / M31:
+ *
+ *   - `'mixed_file_and_value_sets'` — file `--set` + any value
+ *     `--set` / `--set-raw` / `--name` in same call. Applies on
+ *     single-item AND bulk call shapes (universal mutex rule).
+ *   - `'multi_file_set_unsupported'` — 2+ file `--set` entries
+ *     in same call. Applies on single-item AND bulk call shapes
+ *     (universal mutex rule).
+ *   - `'file_set_on_bulk_unsupported'` — **NO LONGER SURFACES**
+ *     at v0.7-M42 onwards. Historical reference only; the
+ *     discriminator literal stays reserved across the codebase
+ *     (do not reuse for a different rejection reason).
+ *   - `'file_set_on_create_unsupported'` — **NO LONGER SURFACES**
+ *     at v0.7-M43 onwards. Historical reference only; the
+ *     discriminator literal stays reserved across the codebase
+ *     (do not reuse for a different rejection reason).
+ *
+ * **D3 closure — `--set-raw <file-col>=<json>` STAYS REJECTED.**
+ * Files have no JSON wire shape Monday's `change_column_value`
+ * accepts; the escape-hatch contract "user supplies the JSON
+ * `change_column_value` accepts" doesn't compose with the
+ * multipart wire. The existing rejection at
+ * `raw-write.ts:translateRawColumnValue` stays unchanged; the
+ * prose enumerates every shipped friendly write path (v0.6-M38
+ * single-item, v0.7-M42 bulk, v0.7-M43 create-time, v0.4-M31
+ * verb-shaped upload) so agents reading the `--set-raw`
+ * rejection see the full set of working alternatives rather
+ * than just the M38 single-item form.
+ *
+ * **D7 closure — `<path>='-'` stdin support OUT OF SCOPE.**
+ * Mirrors M31 `monday item upload`'s rejection rationale — no
+ * clean `--filename` companion shape pinned for `--set
+ * <file-col>=-` syntax (stdin reads byte-anonymously; the
+ * filename is the load-bearing handle for Monday's wire
+ * `Asset.name` slot). Carry-forward candidate for v0.7.x once a
+ * `--filename` companion shape is pinned.
+ *
+ * **No new ERROR_CODE (D8 closure; registry stays at 29).** All
+ * M38-specific rejections route through existing `usage_error`
+ * with `details.reason` discrimination.
+ *
+ * **R-NEW-41 4th supporting site filed at M38 pre-flight.** The
+ * `--set` syntax is type-uniform from the agent's view
+ * (`<col>=<value>`), but for file columns the value is a path
+ * and the dispatch transitions silently from JSON to multipart at
+ * the translator boundary. The asymmetry is at the AGENT-INPUT
+ * boundary, NOT at the wire boundary (M31's multipart-vs-JSON
+ * asymmetry #3 is wire-boundary-only). See `docs/architecture.md`
+ * "Wire-vs-CLI semantics documentation conventions" for the
+ * canonical cross-link.
+ */
+import { z } from 'zod';
+import { ApiError } from '../utils/errors.js';
+import { buildBlobFromPath } from '../utils/file-source.js';
+import { addFileToColumn, assetSchema } from './assets.js';
+import { resolveColumnWithRefresh } from './columns.js';
+import { foldResolverWarningsIntoError } from './resolver-error-fold.js';
+import { buildColumnArchivedError } from './resolution-pass.js';
+import { mergeSource, mergeCacheAge } from './source-aggregator.js';
+/**
+ * Output envelope shape for the file-column `--set` dispatch leg.
+ * Mirrors `itemUploadOutputSchema` from `src/api/assets.ts` so the
+ * envelope shape is byte-equivalent to M31 `monday item upload` for
+ * an agent reading the result — the dispatch source differs
+ * (`monday item set` / `monday item update` vs `monday item upload`)
+ * but the envelope payload structure is identical.
+ *
+ * The `operation` slot pins `'add_file_to_column'` literally
+ * (mirroring M31's envelope discriminator); agents reading
+ * `data.operation` can branch uniformly on the wire mutation
+ * regardless of which CLI verb routed there.
+ */
+export const fileColumnSetOutputSchema = z
+    .object({
+    operation: z.literal('add_file_to_column'),
+    item_id: z.string().min(1),
+    column_id: z.string().min(1),
+    filename: z.string().min(1),
+    file_size_bytes: z.number().int().nonnegative(),
+    asset: assetSchema,
+})
+    .strict();
+/**
+ * Reads the local file at `inputs.entry.filePath`, constructs a Blob
+ * via {@link buildBlobFromPath} (with `Content-Type` sniffed from the
+ * filename), and dispatches the multipart upload through M31's
+ * {@link addFileToColumn} fetcher (cli-design §5.3 step 5 + the
+ * module docstring above pin the load-bearing design).
+ *
+ * **Status: runtime body shipped at v0.6-M38 IMPL.** Wraps M31's
+ * fetcher verbatim — same `operationName: 'AddFileToColumn'`, same
+ * `withRetry(...)` retry semantics, same rewrap-inside-retry-thunk
+ * pattern for `file_too_large` (R-v0.4-W2 axis 7 carries through
+ * safely-by-construction since the dispatch goes through the
+ * existing fetcher rather than a re-implementation).
+ *
+ * The action-body caller (in `item set` / `item update`) is
+ * responsible for:
+ *
+ *   1. Parsing argv + collecting `--set` / `--set-raw` / `--name`
+ *      entries.
+ *   2. Resolving columns via `resolveColumnWithRefresh`.
+ *   3. Calling {@link enforceSingleFileColumnSet} to detect the
+ *      file-column dispatch leg + enforce the mutex rules.
+ *   4. Running {@link precheckLocalFile} from
+ *      `src/utils/file-source.ts` on the agent-supplied path to
+ *      build a {@link FileColumnSetEntry} (the precheck surfaces
+ *      `usage_error.details.reason: 'file_not_readable'` /
+ *      `'file_empty'` before any wire activity per the M31
+ *      ordering invariant).
+ *   5. Calling this fetcher for the wire dispatch.
+ *   6. Emitting the envelope per `fileColumnSetOutputSchema`
+ *      (mirrors M31 `item upload` envelope verbatim).
+ */
+export const executeFileColumnSet = async (inputs) => {
+    const blob = await buildBlobFromPath({
+        filePath: inputs.entry.filePath,
+        filename: inputs.entry.filename,
+        fileSizeBytes: inputs.entry.fileSizeBytes,
+    });
+    const result = await addFileToColumn({
+        client: inputs.client,
+        multipart: inputs.multipart,
+        itemId: inputs.itemId,
+        columnId: inputs.entry.columnId,
+        file: blob,
+        filename: inputs.entry.filename,
+        signal: inputs.signal,
+        retries: inputs.retries,
+    });
+    return {
+        asset: result.asset,
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: result.complexity,
+    };
+};
+/**
+ * Iterates `inputs.setEntries`, identifies entries with
+ * `columnType === 'file'`, applies the mutex rules per D2 / D5 / D6
+ * closures, and returns either `{ kind: 'json' }` (no file entries),
+ * `{ kind: 'file', columnId, rawValue }` (clean dispatch path), or
+ * throws `ApiError('usage_error', ...)` on a mutex violation.
+ *
+ * Mutex priority (ratified at M38 pre-flight; updated at v0.7-M42
+ * + v0.7-M43 pre-flights to fold the D5 bulk + D6 create carve-outs):
+ *
+ *   1. **callShape gate — NONE remaining post-v0.7-M43** — both
+ *      `'item_update_bulk'` (D5 fold at v0.7-M42) and `'item_create'`
+ *      (D6 fold at v0.7-M43) short-circuit-throws have been removed.
+ *      Every callShape falls through to the universal multi-file
+ *      gate + a callShape-aware mixed gate, then returns a per-
+ *      callShape `kind` on the clean path.
+ *   2. **multi-file leg** — 2+ file `--set` entries (any callShape)
+ *      surface `'multi_file_set_unsupported'`. Universal rule:
+ *      Monday's `add_file_to_column` is single-column per call on
+ *      the wire regardless of fan-out shape.
+ *   3. **mixed leg** — 1 file `--set` + any value `--set` /
+ *      `--set-raw` / `--name` surfaces `'mixed_file_and_value_sets'`
+ *      on `'item_set'` / `'item_update_single'` / `'item_update_bulk'`.
+ *      Universal rule on those callShapes: mixing forces non-atomic
+ *      multi-leg dispatch across the multipart + JSON wire surfaces.
+ *      **SUPPRESSED on `'item_create'`** per v0.7-M43 D6 mixed-rule
+ *      asymmetry — `create_item` natively bundles non-file
+ *      `column_values` atomically into leg-1, and `--name` is
+ *      required on create.
+ *   4. **clean leg** — 1 file `--set`, no mutex violation:
+ *      - `'item_update_single'` / `'item_set'` → return
+ *        `{ kind: 'file', columnId, rawValue }` for downstream
+ *        {@link precheckLocalFile} + {@link executeFileColumnSet}
+ *        (M38 path; unchanged).
+ *      - `'item_update_bulk'` → return `{ kind: 'file_bulk',
+ *        columnId, rawValue }` for the action body's per-item
+ *        multipart fan-out (v0.7-M42 D5 carve-out fold).
+ *      - `'item_create'` → return `{ kind: 'file_create', columnId,
+ *        rawValue }` for the action body's two-leg `create_item`
+ *        then `add_file_to_column` helper (v0.7-M43 D6 carve-out
+ *        fold).
+ *
+ * The function is sync + pure. No I/O. Path validation lives at a
+ * SEPARATE step (`precheckLocalFile` from `src/utils/file-source.ts`)
+ * that the caller runs AFTER this function returns a `kind: 'file'`
+ * result.
+ */
+export const enforceSingleFileColumnSet = (inputs) => {
+    const fileSetEntries = inputs.setEntries.filter((e) => e.columnType === 'file');
+    if (fileSetEntries.length === 0) {
+        return { kind: 'json' };
+    }
+    // callShape gate — NO callShape short-circuits at this layer
+    // post v0.7-M43. The v0.6-M38 `'item_create'` short-circuit-throw
+    // (`'file_set_on_create_unsupported'`) FOLDED at v0.7-M43 (D6):
+    // create-time file `--set` falls through to the universal multi-
+    // file gate + a callShape-aware mixed gate, then returns
+    // `{ kind: 'file_create', ... }` on the clean path. The discriminator
+    // literal `'file_set_on_create_unsupported'` stays RESERVED in
+    // docstrings + regression-guard tests; do not re-introduce it as a
+    // runtime rejection without a fresh contract decision. (Parallels
+    // the v0.7-M42 fold of `'file_set_on_bulk_unsupported'` for
+    // `'item_update_bulk'`.)
+    // Multi-file leg (D2 multi). 2+ file `--set` entries on any
+    // callShape — applies universally (single-item AND bulk) because
+    // Monday's `add_file_to_column` is single-column per call on the
+    // wire regardless of how many items the dispatch fans out across.
+    // Multi-file dispatch carries forward as a v0.7.x candidate.
+    if (fileSetEntries.length > 1) {
+        throw new ApiError('usage_error', `Multi-file \`--set <file-col>=<path>\` is not supported ` +
+            `(${String(fileSetEntries.length)} file \`--set\` entries ` +
+            `detected; deferred to v0.7.x per cli-design §5.3 + v0.6-plan ` +
+            `§3 M38 D2 closure — carry-forward from v0.6 unchanged at ` +
+            `v0.7-M42). Monday's \`add_file_to_column\` mutation is ` +
+            `single-column per call on the wire; multi-file dispatch + ` +
+            `concurrent multipart over the shared transport carry design ` +
+            `dimensions worth their own milestone. Pass exactly one ` +
+            `\`--set <file-col>=<path>\` per call; for multiple uploads, ` +
+            `run separate calls.`, {
+            details: {
+                reason: 'multi_file_set_unsupported',
+                file_count: fileSetEntries.length,
+                file_column_ids: fileSetEntries.map((e) => e.columnId),
+                deferred_to: 'v0.7.x',
+                hint: 'pass exactly one `--set <file-col>=<path>` per call; ' +
+                    'run separate calls for multiple file uploads.',
+            },
+        });
+    }
+    // Mixed leg (D2). 1 file `--set` + any value `--set` / `--set-raw`
+    // / `--name` — surfaces because Monday's wire has no atomic combo
+    // of multipart `add_file_to_column` + JSON `change_column_value` /
+    // `change_multiple_column_values` (mixing forces non-atomic
+    // multi-leg dispatch that breaks the §5.3 atomicity contract).
+    //
+    // v0.7-M43 callShape carve-out (D6 mixed-rule asymmetry): on
+    // `'item_create'` the two-leg dispatch (`create_item` with bundled
+    // non-file column_values then `add_file_to_column`) absorbs the
+    // mixed scenarios into leg-1 atomicity for the non-file values +
+    // leg-2 atomicity for the file. `--name` is REQUIRED on create
+    // (not an opt-in rename like on update), so the universal `hasName`
+    // arm would auto-reject every M43 path; suppress on `'item_create'`.
+    // Non-file value `--set` + `--set-raw` entries are ALSO allowed on
+    // create-time mixed (they bundle into leg-1's `column_values`); the
+    // separate D3 `--set-raw <file-col>=<json>` rejection still applies
+    // at `raw-write.ts:translateRawColumnValue` for `file`-typed raw
+    // tokens, so the action-body path stays safe. The non-create
+    // callShapes ('item_set' / 'item_update_single' / 'item_update_bulk')
+    // keep the universal mixed rule unchanged.
+    const nonFileSetCount = inputs.setEntries.length - fileSetEntries.length;
+    const setRawCount = inputs.setRawEntries.length;
+    const mixedApplies = inputs.callShape !== 'item_create' &&
+        (nonFileSetCount > 0 || setRawCount > 0 || inputs.hasName);
+    if (mixedApplies) {
+        const fe = fileSetEntries[0];
+        /* c8 ignore next 3 */
+        if (fe === undefined) {
+            throw new ApiError('internal_error', 'enforceSingleFileColumnSet: file entry narrowing failed (mixed)');
+        }
+        throw new ApiError('usage_error', `Mixing a file \`--set <file-col>=<path>\` with value \`--set\` / ` +
+            `\`--set-raw\` / \`--name\` in the same call is not supported at ` +
+            `v0.6-M38 (per cli-design §5.3 + v0.6-plan §3 M38 D2 closure). ` +
+            `Monday's wire has no atomic combo of multipart ` +
+            `\`add_file_to_column\` + JSON \`change_column_value\` / ` +
+            `\`change_multiple_column_values\`; mixing would force a non-` +
+            `atomic multi-leg dispatch that breaks the existing atomicity ` +
+            `contract. Run the file dispatch in its own call.`, {
+            details: {
+                reason: 'mixed_file_and_value_sets',
+                column_id: fe.columnId,
+                non_file_set_count: nonFileSetCount,
+                set_raw_count: setRawCount,
+                has_name: inputs.hasName,
+                hint: 'run the file `--set` alone (e.g., `monday item set <iid> ' +
+                    '<file-col>=<path>`); apply value writes / rename in a ' +
+                    'separate call (e.g., `monday item update <iid> --set ' +
+                    'status=Done --name "..."`).',
+            },
+        });
+    }
+    // Clean dispatch leg. Single file `--set`, no mutex violation.
+    // Discriminators:
+    //   - `'item_update_single'` / `'item_set'` → `kind: 'file'`
+    //     (M38 single-item path; unchanged).
+    //   - `'item_update_bulk'` → `kind: 'file_bulk'` (v0.7-M42 D5
+    //     carve-out fold; action body's per-item multipart fan-out).
+    //   - `'item_create'` → `kind: 'file_create'` (v0.7-M43 D6
+    //     carve-out fold; action body's two-leg `create_item` then
+    //     `add_file_to_column` dispatch with orphan-warn atomicity
+    //     envelope per D1 closure).
+    const fe = fileSetEntries[0];
+    /* c8 ignore next 3 */
+    if (fe === undefined) {
+        throw new ApiError('internal_error', 'enforceSingleFileColumnSet: file entry narrowing failed (clean)');
+    }
+    if (inputs.callShape === 'item_update_bulk') {
+        return { kind: 'file_bulk', columnId: fe.columnId, rawValue: fe.rawValue };
+    }
+    if (inputs.callShape === 'item_create') {
+        return { kind: 'file_create', columnId: fe.columnId, rawValue: fe.rawValue };
+    }
+    return { kind: 'file', columnId: fe.columnId, rawValue: fe.rawValue };
+};
+/**
+ * Resolves `setEntries` column types and runs the v0.6-M38 mutex
+ * check (per cli-design §5.3 step 5 "File-column dispatch leg —
+ * mutex rules"). The discipline: **enforce mutex at the column-
+ * resolution boundary**, not at the translator-rejection boundary.
+ * Pre-flight P2-1 + IMPL round-1 P2-2 both surfaced the
+ * translator-order-dependent priority drift that this resolution-
+ * boundary check fixes.
+ *
+ * **Why the pre-check fires at the action-body level rather than
+ * inside `resolveAndTranslate`.** The shared resolver helper is
+ * used by 5 sites (item set, item update single + bulk, item
+ * create); the M38 dispatch only applies to 3 (item update single
+ * + bulk + item create — item set has its own column resolution at
+ * the action body level for the single-positional shape). Folding
+ * M38 dispatch into `resolveAndTranslate` would couple the
+ * resolver helper to the file-dispatch leg; the action-body level
+ * pre-check keeps `resolveAndTranslate` translator-only.
+ *
+ * **Discriminating friendly `--set` vs `--set-raw`** — the
+ * pre-check operates on setEntries only. `--set-raw <file-col>=<json>`
+ * rejections come from `translateRawColumnValue` (D3 permanent
+ * rejection); the pre-check returns `kind: 'json'` for `--set-raw`
+ * file paths and the standard path's `resolveAndTranslate` /
+ * `planChanges` then surfaces the D3 `unsupported_column_type`
+ * rejection. The pre-check NEVER hijacks `--set-raw` paths into
+ * M38 dispatch.
+ *
+ * **Source aggregation contract.** Each resolveColumnWithRefresh
+ * call returns its own `source` / `cacheAgeSeconds`; the pre-check
+ * aggregates across `setEntries`. On the `'json'` branch the
+ * downstream `resolveAndTranslate` will re-resolve setEntries
+ * (cache hit) and produce another aggregation leg — the action
+ * body merges both aggregations so the final envelope reflects
+ * every wire / cache leg that fired. The `meta.source` of a
+ * non-file path with a single `--set` may surface as `'mixed'`
+ * (live pre-check + cache downstream) rather than `'live'`; this
+ * is correct per §6.1 source-aggregation rules — the second leg
+ * IS a cache hit.
+ */
+export const preCheckM38FileDispatch = async (inputs) => {
+    const resolved = [];
+    let aggregateSource;
+    let aggregateCacheAge = null;
+    const warnings = [];
+    for (const entry of inputs.setEntries) {
+        const r = await resolveColumnWithRefresh({
+            client: inputs.client,
+            boardId: inputs.boardId,
+            token: entry.token,
+            includeArchived: true,
+            ...(inputs.env === undefined ? {} : { env: inputs.env }),
+            ...(inputs.noCache === undefined ? {} : { noCache: inputs.noCache }),
+        });
+        aggregateSource = mergeSource(aggregateSource, r.source);
+        aggregateCacheAge = mergeCacheAge(aggregateCacheAge, r.cacheAgeSeconds);
+        warnings.push(...r.warnings);
+        // Archived-column guard (mirrors `resolveAndTranslate`'s
+        // pass-(a) check). `includeArchived: true` above surfaces
+        // archived columns via the resolver rather than dropping them;
+        // the M38 dispatch must reject archived file columns with the
+        // stable `column_archived` error so agents key on the canonical
+        // shape regardless of write path. Round-2 P2-1 surfacing event:
+        // without this guard, `--set <archived_file_col>=<path>` on
+        // item update / create reached the M38 dispatch (emitting a
+        // successful file `planned_change` on dry-run, or local
+        // precheck + multipart dispatch on live) instead of the
+        // `column_archived` rejection.
+        if (r.match.column.archived === true) {
+            throw foldResolverWarningsIntoError(buildColumnArchivedError({
+                columnId: r.match.column.id,
+                columnTitle: r.match.column.title,
+                columnType: r.match.column.type,
+                boardId: inputs.boardId,
+            }), warnings);
+        }
+        resolved.push({
+            columnId: r.match.column.id,
+            columnType: r.match.column.type,
+            rawValue: entry.value,
+            token: entry.token,
+        });
+    }
+    // Synthesize setRawEntries inputs from the count — only length
+    // matters for the mutex check; columnId / columnType slots are
+    // unused on the mixed-set discriminator path.
+    const setRawEntries = Array.from({ length: inputs.setRawCount }, () => ({ columnId: '', columnType: '' }));
+    const enforcement = enforceSingleFileColumnSet({
+        callShape: inputs.callShape,
+        setEntries: resolved.map((r) => ({
+            columnId: r.columnId,
+            columnType: r.columnType,
+            rawValue: r.rawValue,
+        })),
+        setRawEntries,
+        hasName: inputs.hasName,
+    });
+    if (enforcement.kind === 'json') {
+        return {
+            kind: 'json',
+            warnings,
+            source: aggregateSource,
+            cacheAgeSeconds: aggregateCacheAge,
+        };
+    }
+    // enforcement.kind is `'file'` (single-item) OR `'file_bulk'`
+    // (v0.7-M42 D5 carve-out fold). Find the matching resolved entry
+    // for the file-column token (echo into resolved_ids downstream).
+    const fileResolved = resolved.find((r) => r.columnType === 'file' &&
+        r.columnId === enforcement.columnId &&
+        r.rawValue === enforcement.rawValue);
+    /* c8 ignore next 5 — defensive: enforcement returned the same
+       entry the pre-check passed in; the find must succeed. */
+    if (fileResolved === undefined) {
+        throw new ApiError('internal_error', 'preCheckM38FileDispatch: file entry not found in resolved set after enforcement');
+    }
+    if (enforcement.kind === 'file_bulk') {
+        return {
+            kind: 'file_bulk',
+            columnId: enforcement.columnId,
+            rawValue: enforcement.rawValue,
+            token: fileResolved.token,
+            warnings,
+            source: aggregateSource,
+            cacheAgeSeconds: aggregateCacheAge,
+        };
+    }
+    if (enforcement.kind === 'file_create') {
+        return {
+            kind: 'file_create',
+            columnId: enforcement.columnId,
+            rawValue: enforcement.rawValue,
+            token: fileResolved.token,
+            warnings,
+            source: aggregateSource,
+            cacheAgeSeconds: aggregateCacheAge,
+        };
+    }
+    return {
+        kind: 'file',
+        columnId: enforcement.columnId,
+        rawValue: enforcement.rawValue,
+        token: fileResolved.token,
+        warnings,
+        source: aggregateSource,
+        cacheAgeSeconds: aggregateCacheAge,
+    };
+};
+//# sourceMappingURL=file-column-set.js.map

package/dist/api/file-column-set.js.map

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

package/dist/api/raw-write.d.ts

@@ -22,12 +22,24 @@
  *         from CLI-time to Monday-time with no new information.
  *       * **`files`-shaped** (`file`, anything else where Monday
  *         uses `add_file_to_column` rather than `change_column_value`)
- *         → `unsupported_column_type` with `deferred_to: "v0.6"`.
- *         The `--set-raw` payload reaches `change_column_value` /
- *         `change_multiple_column_values` only; files-shaped types
- *         can't be written through that wire surface. Hint points
- *         at `monday item upload` (v0.4-M31 — the verb-shaped
- *         alternative path).
+ *         → `unsupported_column_type` rejection STAYS per D3
+ *         closure (permanent). The `--set-raw` payload reaches
+ *         `change_column_value` / `change_multiple_column_values`
+ *         only; files-shaped types can't be written through that
+ *         wire surface (Monday's wire has no JSON-shape for
+ *         `change_column_value` on file columns). The friendly
+ *         `--set <file-col>=<path>` form ships across three
+ *         shipped paths (v0.6-M38 single-item + v0.7-M42 bulk +
+ *         v0.4-M31 verb-shaped upload — all dispatching into the
+ *         multipart wire at the command action body) but keeps
+ *         `--set-raw` rejected — the escape-hatch contract
+ *         "user supplies JSON `change_column_value` accepts"
+ *         doesn't compose with multipart. Hint enumerates every
+ *         shipped multipart write path: v0.6-M38 single-item
+ *         friendly `--set` form on `monday item set` + `monday
+ *         item update <iid>`; v0.7-M42 bulk friendly `--set`
+ *         form on `monday item update --where ...` (per-item
+ *         fan-out); v0.4-M31 verb-shaped `monday item upload`.
  *     Otherwise builds a `TranslatedColumnValue` with `payload:
  *     { format: 'rich', value: <parsed> }` so the existing
  *     `selectMutation` dispatcher handles it uniformly.
@@ -101,17 +113,26 @@ export declare const parseSetRawExpression: (raw: string) => ParsedSetRawExpress
  *   - **Read-only-forever** → `unsupported_column_type` with
  *     `read_only: true`. Monday computes these server-side; no
  *     payload (raw or friendly) is ever accepted.
- *   - **`files`-shaped** → `unsupported_column_type` with
- *     `deferred_to: "v0.6"`. Monday writes via `add_file_to_column`
- *     (multipart upload), not `change_column_value`; the raw
- *     payload can't reach the right wire surface. Hint points at
- *     `monday item upload` (shipped v0.4-M31; multipart wire — the
- *     alternative path agents should use today). The `deferred_to`
- *     slot tracks the `--set-raw <file-col>=<json>` form
- *     specifically; v0.4 shipped the verb-shaped path; v0.5 didn't
- *     pick up the raw-payload-into-multipart-wire wiring either
- *     (no escape-hatch-to-multipart dispatch landed); slot slipped
- *     from v0.5 to v0.6 at v0.5 release-prep.
+ *   - **`files`-shaped** → `unsupported_column_type` rejection
+ *     STAYS per D3 closure (permanent). Monday writes via
+ *     `add_file_to_column` (multipart upload), not
+ *     `change_column_value`; the raw payload can't reach the
+ *     right wire surface (Monday's wire has no JSON-shape for
+ *     `change_column_value` on file columns). The friendly
+ *     `--set <file-col>=<path>` form ships across four paths
+ *     reaching the multipart wire: v0.6-M38 single-item friendly
+ *     (`monday item set` + `monday item update <iid>`); v0.7-M42
+ *     bulk friendly (`monday item update --where ...` per-item
+ *     fan-out under `--concurrency` / `--continue-on-error`);
+ *     v0.7-M43 create-time friendly (`monday item create --set
+ *     <file-col>=<path>` two-leg `create_item` + `add_file_to_
+ *     column` dispatch under the §5.8 orphan-warn atomicity
+ *     envelope); v0.4-M31 verb-shaped (`monday item upload <iid>
+ *     --column <col> <file>`). The escape-hatch contract "user
+ *     supplies JSON `change_column_value` accepts" doesn't
+ *     compose with multipart, so `--set-raw <file-col>=<json>`
+ *     stays rejected regardless. Hint enumerates every shipped
+ *     path.
  *
  * Anything else (writable + tentative-slipped + future where the API
  * accepts `change_column_value`) is accepted — the user took the

package/dist/api/raw-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raw-write.d.ts","sourceRoot":"","sources":["../../src/api/raw-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,sBA+DnD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,UAAU,EACjB,SAAS,MAAM,KACd,qBAwEF,CAAC;AAsBF,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"raw-write.d.ts","sourceRoot":"","sources":["../../src/api/raw-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,sBA+DnD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,UAAU,EACjB,SAAS,MAAM,KACd,qBAwFF,CAAC;AAsBF,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}