monday-cli 0.2.0

package/dist/api/column-values.js

@@ -0,0 +1,795 @@
+/**
+ * Column-value writer (`cli-design.md` §5.3, `v0.1-plan.md` §3 M5a).
+ *
+ * The write half of the column-value abstraction: takes a resolved
+ * column + a raw user-supplied string and produces the Monday wire
+ * payload Monday's `change_simple_column_value` /
+ * `change_column_value` / `change_multiple_column_values` mutations
+ * accept.
+ *
+ * **Two entry points.** Nine of the ten allowlisted types translate
+ * purely locally — no network, no clock dependency beyond the date
+ * module's injectable clock — and live behind the sync
+ * `translateColumnValue`. `people` is the exception: email→ID
+ * resolution can hit the network. Rather than forcing a
+ * `Promise<TranslatedColumnValue>` on every call site for the nine
+ * sync types, `translateColumnValueAsync` is the unified async entry
+ * point the command layer always calls. It delegates to the sync
+ * version for non-people types and dispatches to `parsePeopleInput`
+ * for `people`. M5b's write surface goes through async exclusively
+ * (people may appear in any `--set` bundle).
+ *
+ * **Scope.** All ten allowlisted types translate:
+ * `text` / `long_text` / `numbers` (simple-string payloads, M5a
+ * skeleton); `status` / `dropdown` (rich-object payloads); `date`
+ * (rich, with relative-token resolution against the profile
+ * timezone); `people` (rich, with `me`-token + email resolution via
+ * the M3 `userByEmail` directory cache); and the M8 firm additions
+ * `link` / `email` / `phone` (pipe-form parsers in `links.ts` /
+ * `emails.ts` / `phones.ts`; same `change_column_value` wire path
+ * as the v0.1 rich types).
+ *
+ * **Date resolution context** (cli-design §5.3 step 3 + the
+ * "Relative dates and timezone" subsection). Relative tokens
+ * (`today`, `+3d`, `+2h`) need a clock + a timezone; both come
+ * from `TranslateColumnValueInputs.dateResolution`. Defaults to
+ * the system clock + system tz when omitted — M5b's command
+ * layer plumbs `MONDAY_TIMEZONE` env override through this slot.
+ * Tests inject a deterministic clock for DST-boundary coverage.
+ * The actual resolution machinery lives in `dates.ts`; this
+ * module just delegates and packages the result alongside the
+ * other column types.
+ *
+ * **People resolution context** (cli-design §5.3 step 3 line
+ * 728-734 + the `me` token rule line 704-707). Email lookups +
+ * `me` resolution come through
+ * `TranslateColumnValueAsyncInputs.peopleResolution`, which
+ * carries `resolveMe` (mirroring `filters.ts`'s slot, so the
+ * same M5b wiring resolves `me` for both filter reads and
+ * `--set` writes) and `resolveEmail` (M5b wires this to
+ * `resolvers.userByEmail`). Required for people columns; ignored
+ * for everything else. The actual parsing machinery lives in
+ * `people.ts`.
+ *
+ * **Mutation selection** (`cli-design.md` §5.3 step 5) lives in
+ * `selectMutation` below — single simple → `change_simple_column_value`;
+ * single rich → `change_column_value`; N (any combo) →
+ * `change_multiple_column_values` (atomic on Monday's side). The
+ * multi form re-wraps `long_text`'s simple bare string as
+ * `{ text: <value> }` because Monday's per-column blob inside
+ * `change_multiple_column_values` requires the object form for
+ * `long_text` (a wire-shape divergence from
+ * `change_simple_column_value`'s bare-string acceptance — pinned
+ * via fixture in the unit suite, logged as a spec gap in
+ * `v0.1-plan.md` §3 M5a for cli-design backfill).
+ *
+ * **No CLI-side label-to-index lookup.** Per `cli-design.md` §5.3
+ * step 3: the CLI emits `{ "label": ... }` for label input and
+ * `{ "index": N }` for numeric input on `status`; it does *not*
+ * traverse `column.settings_str` to resolve labels to their stable
+ * indexes. Same shape for `dropdown` — `{ "labels": [...] }` for
+ * label input, `{ "ids": [...] }` for all-numeric input. Monday is
+ * the validator of last resort; the translator's contract is
+ * "produce the documented wire shape, let Monday reject typos as
+ * `validation_failed`".
+ *
+ * **Monday `JSON` scalar discipline** (`cli-design.md` §5.3 step 4).
+ * Every payload is a plain JS value (string for the simple form,
+ * plain object for the rich form). The SDK / fetch layer is
+ * responsible for stringifying at the wire boundary — this module
+ * never `JSON.stringify`s. The unit tests in
+ * `tests/unit/api/column-values.test.ts` pin the exact wire shape
+ * per type as a fixture so M5b and v0.2's bulk surface inherit the
+ * rule unchanged.
+ *
+ * **`--set-raw` escape hatch (M8).** v0.1 had no escape hatch;
+ * v0.2's M8 milestone added `--set-raw <col>=<json>` (see
+ * `src/api/raw-write.ts`) for column types that don't have a
+ * friendly translator yet. Non-allowlisted column types still
+ * surface `unsupported_column_type` keyed by roadmap category per
+ * `column-types.ts getColumnRoadmapCategory`: tentative writer-
+ * expansion types (`tags` / `board_relation` / `dependency`) slipped
+ * to v0.3 at M18 close — they get `deferred_to: "v0.3"` plus a
+ * `--set-raw` hint, read-only-forever types get
+ * `read_only: true`, anything else gets `deferred_to: "future"`
+ * with a `--set-raw` hint when the underlying mutation is shaped
+ * like `change_column_value`. The M8 contract is "we translate the
+ * ten allowlisted types and reject everything else with
+ * category-accurate guidance, pointing tentative + future-shaped
+ * targets at `--set-raw`."
+ */
+import { ApiError, UsageError } from '../utils/errors.js';
+import { getColumnRoadmapCategory, isFilesShapedType, isWritableColumnType, } from './column-types.js';
+import { parseDateInput, } from './dates.js';
+import { parsePeopleInput, } from './people.js';
+import { parseLinkInput } from './links.js';
+import { parseEmailInput } from './emails.js';
+import { parsePhoneInput } from './phones.js';
+/**
+ * Translates a single `<column>=<value>` pair into the Monday wire
+ * payload. **Sync entry point — handles the nine types whose
+ * translation is purely local computation** (`text` / `long_text` /
+ * `numbers` / `status` / `dropdown` / `date` / `link` / `email` /
+ * `phone`). For `people` columns, use `translateColumnValueAsync`:
+ * people resolution can hit the network (email→ID lookup) and is
+ * therefore async-only.
+ *
+ * **Throws** `ApiError`:
+ *   - `unsupported_column_type` — type not in the friendly
+ *     allowlist. Carries `column_id` + `type` plus per-category
+ *     details: `deferred_to: "v0.3"` for the tentative writer-
+ *     expansion row that slipped from v0.2 (`tags` /
+ *     `board_relation` / `dependency`), `read_only: true` for
+ *     read-only-forever types (mirror / formula / auto_number /
+ *     creation_log / last_updated / item_id), `deferred_to:
+ *     "future"` for anything else. The `--set-raw` escape hatch
+ *     (M8) accepts most non-allowlisted types.
+ *   - `internal_error` — sync entry was called on a `people`
+ *     column. Programmer error: the write surface always uses
+ *     `translateColumnValueAsync`. The check exists so a future
+ *     contributor doesn't accidentally regress to a sync code
+ *     path that silently mis-translates people input.
+ *
+ * **Throws** `UsageError`:
+ *   - `usage_error` — for status / dropdown numeric input that
+ *     exceeds `Number.MAX_SAFE_INTEGER`, dropdown input that
+ *     contains no labels and no IDs after trim + filter, `date`
+ *     input that does not match any supported form (ISO date,
+ *     ISO date+time, or relative token), invalid URL / email /
+ *     phone in the link / email / phone translators, or
+ *     pipe-form input with empty leader/trailer in those types.
+ *     See `unsafeIntegerError`, the dropdown empty-input branch,
+ *     `dates.parseDateInput`, `links.parseLinkInput`,
+ *     `emails.parseEmailInput`, and `phones.parsePhoneInput` for
+ *     the documented messages.
+ */
+export const translateColumnValue = (inputs) => {
+    const { column, value, dateResolution } = inputs;
+    if (!isWritableColumnType(column.type)) {
+        throw unsupportedColumnTypeError(column.id, column.type);
+    }
+    switch (column.type) {
+        case 'text':
+            return simple(column.id, 'text', value);
+        case 'long_text':
+            return simple(column.id, 'long_text', value);
+        case 'numbers':
+            return simple(column.id, 'numbers', value);
+        case 'status':
+            return rich(column.id, 'status', value, translateStatus(value, column.id));
+        case 'dropdown':
+            return rich(column.id, 'dropdown', value, translateDropdown(column.id, value));
+        case 'date': {
+            const parsed = parseDateInput(value, column.id, dateResolution);
+            return {
+                columnId: column.id,
+                columnType: 'date',
+                rawInput: value,
+                payload: { format: 'rich', value: parsed.payload },
+                resolvedFrom: parsed.resolvedFrom,
+                peopleResolution: null,
+            };
+        }
+        case 'link': {
+            // LinkPayload's `{url, text}` literal type is structurally a
+            // JsonObject (both fields are JsonValues) but TypeScript treats
+            // closed object types as not implicitly satisfying the open
+            // index signature. Same cast pattern the people translator
+            // uses; see src/types/json.ts for the documented trade.
+            const parsed = parseLinkInput(value, column.id);
+            return {
+                columnId: column.id,
+                columnType: 'link',
+                rawInput: value,
+                payload: { format: 'rich', value: parsed },
+                resolvedFrom: null,
+                peopleResolution: null,
+            };
+        }
+        case 'email': {
+            const parsed = parseEmailInput(value, column.id);
+            return {
+                columnId: column.id,
+                columnType: 'email',
+                rawInput: value,
+                payload: { format: 'rich', value: parsed },
+                resolvedFrom: null,
+                peopleResolution: null,
+            };
+        }
+        case 'phone': {
+            const parsed = parsePhoneInput(value, column.id);
+            return {
+                columnId: column.id,
+                columnType: 'phone',
+                rawInput: value,
+                payload: { format: 'rich', value: parsed },
+                resolvedFrom: null,
+                peopleResolution: null,
+            };
+        }
+        case 'people':
+            // People translation is async (email→ID lookup hits the
+            // directory cache or the `users(emails:)` GraphQL endpoint).
+            // Surface as `internal_error` so a future contributor who
+            // accidentally routes a people column through the sync entry
+            // point sees a loud programmer-error message rather than a
+            // silent payload corruption. M5b's command layer always uses
+            // `translateColumnValueAsync` for write paths.
+            throw new ApiError('internal_error', `translateColumnValue (sync) called on people column "${column.id}". ` +
+                `People resolution is async — use translateColumnValueAsync.`, {
+                details: {
+                    column_id: column.id,
+                    column_type: column.type,
+                    hint: 'use translateColumnValueAsync from src/api/column-values.ts',
+                },
+            });
+    }
+};
+/**
+ * Async entry point — handles every type in `WRITABLE_COLUMN_TYPES`.
+ * Delegates to `translateColumnValue` (sync) for non-people columns;
+ * dispatches to `parsePeopleInput` for `people`.
+ *
+ * The `peopleResolution` slot is required when `column.type ===
+ * 'people'`. Omitting it for a people column raises `internal_error`
+ * (programmer wiring bug) — agents see this as a loud failure
+ * rather than a silent fallback to the unsupported-type path.
+ *
+ * **Throws** every error `translateColumnValue` throws (delegated
+ * unchanged for non-people types), plus:
+ *   - `ApiError(user_not_found)` — bubbled from `peopleResolution.
+ *     resolveEmail` for unknown emails. cli-design.md §5.3 step 3
+ *     line 733 pins the contract.
+ *   - `UsageError(usage_error)` — empty / numeric people input.
+ *     See `parsePeopleInput` for the per-branch messages.
+ *   - `ApiError(internal_error)` — `peopleResolution` was omitted
+ *     for a people column.
+ */
+/**
+ * Builds the per-type "clear" payload for `monday item clear`. The
+ * dedicated verb keeps `--set <col>=<value>` and the clear path
+ * non-overlapping (cli-design §5.3 step 3 explicitly notes that
+ * empty-string input on `status` is `{label: ""}`, NOT a clear; the
+ * translator is value-shaping, not intent-disambiguating).
+ *
+ * Per-type clear shapes:
+ *   - `text` / `long_text` / `numbers` → simple bare empty string
+ *     (`change_simple_column_value(value: "")` clears the cell).
+ *   - `status` / `dropdown` / `date` / `people` → empty JSON object
+ *     `{}` via `change_column_value(value: JSON!)`. Monday's
+ *     official "clear all column values" pattern.
+ *
+ * **Throws** `unsupported_column_type` for types outside the v0.1
+ * writable allowlist — same code path the value translator uses,
+ * keyed by roadmap category (`deferred_to: "v0.3"` /
+ * `read_only: true` / `deferred_to: "future"`). Agents see the
+ * same per-category surface across `item set` / `item update` /
+ * `item clear`, so a wrapper that triages on the error details
+ * doesn't need a per-verb branch.
+ *
+ * Sync entry — `people` clear doesn't need email resolution (the
+ * payload is `{}` regardless of who's currently assigned). Reused
+ * by the `item clear` dry-run + live paths.
+ */
+export const translateColumnClear = (column) => {
+    if (!isWritableColumnType(column.type)) {
+        throw unsupportedColumnTypeError(column.id, column.type);
+    }
+    switch (column.type) {
+        case 'text':
+        case 'long_text':
+        case 'numbers':
+            return {
+                columnId: column.id,
+                columnType: column.type,
+                rawInput: '',
+                payload: { format: 'simple', value: '' },
+                resolvedFrom: null,
+                peopleResolution: null,
+            };
+        case 'status':
+        case 'dropdown':
+        case 'date':
+        case 'people':
+        case 'link':
+        case 'email':
+        case 'phone':
+            // Rich types clear to `{}` via change_column_value per
+            // cli-design §5.3 "Clearing column values" table. M8 firm row
+            // (link / email / phone) extends the table verbatim — same
+            // payload, same mutation, same dispatch.
+            return {
+                columnId: column.id,
+                columnType: column.type,
+                rawInput: '',
+                payload: { format: 'rich', value: {} },
+                resolvedFrom: null,
+                peopleResolution: null,
+            };
+    }
+};
+export const translateColumnValueAsync = async (inputs) => {
+    if (inputs.column.type !== 'people') {
+        return translateColumnValue(inputs);
+    }
+    const { peopleResolution } = inputs;
+    if (peopleResolution === undefined) {
+        throw new ApiError('internal_error', `translateColumnValueAsync requires a peopleResolution context for ` +
+            `people column "${inputs.column.id}". M5b's command layer wires ` +
+            `resolveMe + resolveEmail through this slot.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: 'people',
+                hint: 'pass { peopleResolution: { resolveMe, resolveEmail } } when ' +
+                    'calling translateColumnValueAsync.',
+            },
+        });
+    }
+    const parsed = await parsePeopleInput(inputs.value, inputs.column.id, peopleResolution);
+    return {
+        columnId: inputs.column.id,
+        columnType: 'people',
+        rawInput: inputs.value,
+        // PeoplePayload is structurally a JsonObject — it has one
+        // declared key (`personsAndTeams`) whose value is a readonly
+        // array of plain objects with `id: number` and `kind:
+        // 'person'` (both JsonValues). TypeScript treats closed
+        // object types as not implicitly satisfying open index
+        // signatures even when their values all line up, so the cast
+        // is structural-typing-only. Runtime shape is unchanged; the
+        // wire-shape fixture in the unit suite is the load-bearing
+        // pin. See `src/types/json.ts` for the JsonObject definition
+        // and the closed-type-literal note that documents this trade.
+        payload: {
+            format: 'rich',
+            value: parsed.payload,
+        },
+        resolvedFrom: null,
+        peopleResolution: parsed.resolution,
+    };
+};
+const simple = (columnId, columnType, rawInput) => ({
+    columnId,
+    columnType,
+    payload: { format: 'simple', value: rawInput },
+    rawInput,
+    // Only the date / people translators populate resolution echoes;
+    // every other type emits null so the dry-run engine has one shape
+    // to read per slot.
+    resolvedFrom: null,
+    peopleResolution: null,
+});
+const rich = (columnId, columnType, rawInput, value) => ({
+    columnId,
+    columnType,
+    payload: { format: 'rich', value },
+    rawInput,
+    resolvedFrom: null,
+    peopleResolution: null,
+});
+/**
+ * Status payload per `cli-design.md` §5.3 step 3:
+ *   - Non-negative integer input → `{ index: N }` (number, not
+ *     string — Monday's status indexes are integers and the
+ *     `change_*_column_value` JSON scalar serialises a number as
+ *     a number).
+ *   - Anything else → `{ label: <verbatim> }`. No NFC / case-fold
+ *     here: the resolver upstream normalised the *column* token,
+ *     not the *value* — Monday matches the label against the
+ *     board's settings server-side, and a label like " Done "
+ *     with surrounding whitespace would be agent-side noise we
+ *     should preserve so Monday's `validation_failed` points at
+ *     the right input.
+ *
+ * Empty string emits `{ label: "" }` and is *not* treated as a
+ * "clear" intent — `monday item clear` is the dedicated verb for
+ * that. Pinned in tests so future contributors don't add silent
+ * fall-through-to-clear behaviour.
+ *
+ * **Safe-integer bound.** Numeric input larger than
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1) silently rounds via
+ * `Number(raw)`; very long digit strings yield `Infinity`,
+ * which `JSON.stringify` serialises as `null`. Either case
+ * would corrupt the wire shape. We throw `usage_error` rather
+ * than silently routing to the label path because the input
+ * was unambiguously the index path (all digits, no signs / no
+ * decimals) — sending `{label: "999999999999999999999"}` to
+ * Monday would be a worse surprise than a local error.
+ */
+const translateStatus = (raw, columnId) => {
+    if (NON_NEGATIVE_INTEGER.test(raw)) {
+        const parsed = Number(raw);
+        if (!Number.isSafeInteger(parsed)) {
+            throw unsafeIntegerError(columnId, 'status', raw);
+        }
+        return { index: parsed };
+    }
+    return { label: raw };
+};
+/**
+ * Dropdown payload per `cli-design.md` §5.3 step 3:
+ *   - Comma-split, per-segment trimmed, empty segments dropped.
+ *   - All remaining segments numeric → `{ ids: [N1, N2, ...] }`
+ *     (numbers, not strings — dropdown IDs from Monday's
+ *     `settings_str.labels[].id` are integers).
+ *   - Any non-numeric segment → `{ labels: [s1, s2, ...] }`
+ *     (strings, verbatim post-trim).
+ *
+ * **Disambiguation rule, pinned.** A label literally named `"1"`
+ * cannot be set via `--set tags=1` — that input parses as the
+ * `id` path. The M8 `--set-raw tags='{"labels":["1"]}'` escape
+ * hatch is the workaround. Surfaced in the module header as a
+ * known limitation; documented via unit test rather than runtime
+ * warning because it's a corner case (Monday-generated dropdown
+ * labels are strings the user typed; integer-only labels are
+ * vanishingly rare).
+ *
+ * **Empty-after-filter throws `usage_error`.** Inputs like
+ * `--set tags=""` or `--set tags=" , "` carry no labels and no
+ * IDs — there's nothing to translate. Throwing `usage_error`
+ * (rather than emitting `{ labels: [] }`) keeps `--set` and
+ * `monday item clear` non-overlapping: the only way to clear
+ * a dropdown is the dedicated verb. Pinned via test.
+ */
+const translateDropdown = (columnId, raw) => {
+    const parts = raw
+        .split(',')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (parts.length === 0) {
+        throw new UsageError(`Dropdown column "${columnId}" needs at least one label or numeric ID. ` +
+            `Got "${raw}". To clear a dropdown column, use ` +
+            `\`monday item clear <iid> ${columnId} [--board <bid>]\` instead.`, {
+            details: {
+                column_id: columnId,
+                column_type: 'dropdown',
+                raw_input: raw,
+                hint: 'pass a comma-separated list of labels (e.g. --set ' +
+                    `${columnId}='Backend,Frontend') or numeric IDs (--set ` +
+                    `${columnId}=1,2). The --set-raw escape hatch accepts the ` +
+                    `literal Monday wire shape if neither form fits.`,
+            },
+        });
+    }
+    if (parts.every((part) => NON_NEGATIVE_INTEGER.test(part))) {
+        const ids = parts.map((part) => {
+            const parsed = Number(part);
+            if (!Number.isSafeInteger(parsed)) {
+                throw unsafeIntegerError(columnId, 'dropdown', part);
+            }
+            return parsed;
+        });
+        return { ids };
+    }
+    return { labels: parts };
+};
+/**
+ * Builds the `usage_error` for numeric input that exceeds
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1). Shared by status (index)
+ * and dropdown (id) because the failure mode is identical: the
+ * input parsed as an integer-shaped number but `Number(raw)`
+ * lost precision (or yielded `Infinity` for digit strings ~310+
+ * chars long). Either case would land at Monday as the wrong
+ * integer or as `null` after `JSON.stringify`. The error carries
+ * the raw input so an agent's debug log shows exactly what they
+ * sent, and a hint nudging them toward the label path. The M8
+ * `--set-raw` escape hatch is the paste-ready alternative when
+ * the friendly translator can't accept the input.
+ */
+const unsafeIntegerError = (columnId, columnType, raw) => {
+    const titled = columnType === 'status' ? 'Status' : 'Dropdown';
+    // status uses indexes ("first label is index 0"); dropdown uses
+    // numeric IDs from settings_str.labels[].id. Different word in
+    // the message so an agent doesn't see "smaller ID" on a status
+    // column where the concept is "index", not "ID".
+    const noun = columnType === 'status' ? 'indexes' : 'IDs';
+    const smaller = columnType === 'status' ? 'a smaller index' : 'a smaller ID';
+    // Hints interpolate the actual `columnId` so an agent can
+    // paste-and-edit. Status hint uses the literal word "label"
+    // because the label-vs-index split lives in cli-design.md §5.3
+    // step 3; dropdown hint shows both the labels and IDs forms.
+    const hint = columnType === 'status'
+        ? `use a status label (e.g. --set ${columnId}=Done) or an index < 2^53`
+        : `use dropdown labels (e.g. --set ${columnId}=Backend,Frontend) ` +
+            `or IDs < 2^53`;
+    return new UsageError(`${titled} column "${columnId}" got numeric input "${raw}" that ` +
+        `exceeds JavaScript's safe-integer range (2^53 - 1, i.e. ` +
+        `9007199254740991). Number(raw) would lose precision or yield ` +
+        `Infinity, corrupting the wire shape. Monday's ${columnType} ` +
+        `${noun} are small non-negative integers — pass a label or ` +
+        `${smaller}, or use --set-raw <col>=<json> with the literal ` +
+        `Monday wire shape.`, {
+        details: {
+            column_id: columnId,
+            column_type: columnType,
+            raw_input: raw,
+            hint,
+        },
+    });
+};
+/**
+ * Non-negative integer: matches `0`, `42`, `1234567` but not `-1`,
+ * `0.5`, `1e3`, or `42 ` (with trailing whitespace). Used to gate
+ * `status` index input and `dropdown` ID input. Negatives go to
+ * the label / labels path because Monday status indexes are >= 0
+ * and dropdown IDs are auto-incremented positive integers.
+ */
+const NON_NEGATIVE_INTEGER = /^\d+$/u;
+/**
+ * Picks the right Monday mutation for a list of translated column
+ * values per `cli-design.md` §5.3 step 5.
+ *
+ * Dispatch:
+ *   - 1 translated value, simple → `change_simple_column_value`
+ *     (bare-string `value`).
+ *   - 1 translated value, rich → `change_column_value` (object
+ *     `value`).
+ *   - N translated values (any combo of simple / rich) →
+ *     `change_multiple_column_values`. Atomic on Monday's side —
+ *     either every column update lands or none do.
+ *
+ * **Duplicate column IDs throw `usage_error`.** Bundling two
+ * `--set status=Done --set status=Doing` would have last-write-wins
+ * semantics inside `change_multiple_column_values`'s map and the
+ * agent has no way to know which one won. Surfacing as a typed
+ * error at the bundling boundary keeps mutations deterministic;
+ * the command layer (M5b) can catch + reframe with the literal
+ * `--set` flags it received.
+ *
+ * **Empty input throws `usage_error`.** Defensive — the command
+ * layer is supposed to validate `--set` was supplied, but the
+ * helper shouldn't return a malformed `change_multiple_column_values`
+ * with an empty map.
+ *
+ * **`long_text` re-wrap, spec gap.** Monday's
+ * `change_multiple_column_values(column_values: JSON!)` accepts a
+ * map where each value is either a string or a per-type object.
+ * For `long_text` specifically, the per-type object is `{text:
+ * <value>}` — so the bare string that `change_simple_column_value`
+ * accepts is *not* the right shape inside the multi mutation.
+ * `text` / `numbers` stay as bare strings. This wire-shape
+ * divergence isn't called out in cli-design.md §5.3 step 5; logged
+ * as a spec gap in v0.1-plan.md §3 M5a for backfill. Pinned via
+ * fixture in the unit suite.
+ */
+export const selectMutation = (translated) => {
+    if (translated.length === 0) {
+        throw new UsageError('selectMutation requires at least one translated column value. ' +
+            'The command layer should reject the no-`--set` case before ' +
+            'reaching this helper.', { details: { translated_count: 0 } });
+    }
+    if (translated.length === 1) {
+        const only = translated[0];
+        /* c8 ignore next 4 — defensive: length === 1 was just checked,
+           so `only` cannot be undefined. The guard exists for
+           `noUncheckedIndexedAccess` narrowing. */
+        if (only === undefined) {
+            throw new UsageError('selectMutation: unreachable indexing guard');
+        }
+        if (only.payload.format === 'simple') {
+            return {
+                kind: 'change_simple_column_value',
+                columnId: only.columnId,
+                value: only.payload.value,
+            };
+        }
+        return {
+            kind: 'change_column_value',
+            columnId: only.columnId,
+            value: only.payload.value,
+        };
+    }
+    // Multi: bundle every translated value into the column_values map.
+    // Delegates to `bundleColumnValues` so the long_text re-wrap rule
+    // and the duplicate-id gate stay shared with M9's create_item /
+    // create_subitem bundling — one source of truth for the
+    // `column_values: JSON!` wire shape across every Monday mutation
+    // that accepts it.
+    const columnValues = bundleColumnValues(translated);
+    return { kind: 'change_multiple_column_values', columnValues };
+};
+/**
+ * Projects one translated column value into the per-column blob
+ * `change_multiple_column_values` accepts. Three cases:
+ *
+ *   - rich payload → pass the object through unchanged.
+ *   - simple payload, type `long_text` → wrap as `{ text: <value> }`.
+ *     Monday's multi-mutation blob for `long_text` requires the
+ *     object form (spec gap; see `selectMutation` JSDoc).
+ *   - simple payload, any other type → bare string.
+ */
+const projectForMulti = (t) => {
+    if (t.payload.format === 'rich') {
+        return t.payload.value;
+    }
+    if (t.columnType === 'long_text') {
+        return { text: t.payload.value };
+    }
+    return t.payload.value;
+};
+/**
+ * Bundles a list of translated column values into Monday's
+ * `column_values: JSON!` map shape — the input parameter
+ * `change_multiple_column_values`, `create_item`, and `create_subitem`
+ * all accept. Per-column projection routes through `projectForMulti`,
+ * so the `long_text` re-wrap (`{ text: <value> }` inside the map)
+ * applies uniformly across every wire surface that takes a
+ * `column_values` map.
+ *
+ * **Why a shared helper.** `selectMutation` builds this map for the
+ * multi-update case (M5b); M9's `item create` needs the same shape
+ * to bundle `--set` values into `create_item.column_values` /
+ * `create_subitem.column_values`. The single-round-trip exit gate
+ * (cli-design §5.8) requires the create payload bundles every
+ * translated value into one map — and the shape rule should not
+ * drift between update and create. The fixture pin in
+ * `tests/unit/api/column-values.test.ts` covers both consumers.
+ *
+ * **Duplicate-column-ID throws `usage_error`.** Same rule as
+ * `selectMutation`'s multi case — bundling two values for the same
+ * column would silently keep one. The cli-design §5.3 step 2
+ * mutual-exclusion contract enforces this resolution-time; the
+ * helper duplicates the gate so misuse from a non-command caller
+ * still surfaces a typed error.
+ */
+export const bundleColumnValues = (translated) => {
+    const out = {};
+    const seen = new Set();
+    for (const t of translated) {
+        if (seen.has(t.columnId)) {
+            // Wording matches the historical `selectMutation` message
+            // because existing tests assert on the `Multiple --set values
+            // target column` regex; keeping it stable preserves those
+            // assertions across both consumers (multi-update + create).
+            throw new UsageError(`Multiple --set values target column "${t.columnId}". ` +
+                `change_multiple_column_values is a map keyed by column ID; ` +
+                `bundling two values for the same column would silently keep ` +
+                `only one. Pass at most one --set per column.`, {
+                details: {
+                    column_id: t.columnId,
+                    duplicate_count: translated.filter((other) => other.columnId === t.columnId).length,
+                },
+            });
+        }
+        seen.add(t.columnId);
+        out[t.columnId] = projectForMulti(t);
+    }
+    return out;
+};
+/**
+ * Builds the canonical `unsupported_column_type` error (`cli-design.md`
+ * §5.3 step 4 + §6.5). Branches on the type's roadmap category so
+ * agents get accurate guidance instead of a blanket "wait for the
+ * next version" hint.
+ *
+ * Three categories per `column-types.ts getColumnRoadmapCategory`:
+ *
+ *   - **v0.3 writer-expansion candidates** (`tags` / `board_relation`
+ *     / `dependency` — slipped from v0.2 tentative at M18 close)
+ *     get `deferred_to: "v0.3"`. The M8 firm row (`link` / `email`
+ *     / `phone`) shipped friendly translators in v0.2 and goes
+ *     through the writable-allowlist branch, not this error path.
+ *   - **read-only forever** (`mirror` / `formula` / `auto_number` /
+ *     `creation_log` / `last_updated` / `item_id`) — Monday-computed
+ *     columns that are not writable via the API regardless of CLI
+ *     version. `read_only: true`, hint points at the underlying
+ *     source column. cli-design.md §5.3 writer-expansion roadmap
+ *     "read-only forever" row says this explicitly.
+ *   - **future** (anything else) — `deferred_to: "future"`, generic
+ *     message. Examples include `battery`, `item_assignees`,
+ *     `time_tracking`, `files`, `rating`. The roadmap doesn't
+ *     promise these for v0.2 or v0.3, so over-promising would be
+ *     the same drift Codex M5b cleanup re-review caught.
+ *
+ * Exported for unit coverage.
+ */
+export const unsupportedColumnTypeError = (columnId, type) => {
+    const category = getColumnRoadmapCategory(type);
+    if (category === 'read_only_forever') {
+        return new ApiError('unsupported_column_type', `Column "${columnId}" has type "${type}", which Monday computes ` +
+            `server-side and does not make writable via the API. This is ` +
+            `not a v0.1 limitation — Monday's API rejects write attempts ` +
+            `against this type regardless of CLI version, so no future ` +
+            `release will lift the restriction. Set the underlying source ` +
+            `column instead (e.g. for a mirror column, write to the column ` +
+            `the mirror reflects on the linked board).`, {
+            details: {
+                column_id: columnId,
+                type,
+                read_only: true,
+                hint: 'this column type is computed by Monday and is permanently ' +
+                    'read-only via the API. Do not attempt --set / --set-raw — ' +
+                    'identify the underlying source column (the column the ' +
+                    'mirror / formula / auto_number / etc. reflects) and write ' +
+                    'to that instead. See cli-design.md §5.3 writer-expansion ' +
+                    'roadmap (read-only-forever row) for the full type list.',
+            },
+        });
+    }
+    if (category === 'v0_2_writer_expansion') {
+        return new ApiError('unsupported_column_type', `Column "${columnId}" has type "${type}", which is not yet in the ` +
+            `friendly --set translator allowlist. The v0.2 writer-expansion ` +
+            `tentative row (tags / board_relation / dependency) slipped to ` +
+            `v0.3 at M18 close — friendly translators land then once the ` +
+            `per-account directory + linked-board enumeration design clears. ` +
+            `Use --set-raw <col>=<json> with the documented Monday wire shape ` +
+            `in the meantime.`, {
+            details: {
+                column_id: columnId,
+                type,
+                deferred_to: 'v0.3',
+                hint: `use --set-raw <col>=<json> with the Monday wire shape (e.g. ` +
+                    `--set-raw ${columnId}='{"tag_ids":[1,2]}' for tags). ` +
+                    `See https://developer.monday.com/api-reference/reference/` +
+                    `column-types-reference for per-type wire shapes.`,
+            },
+        });
+    }
+    // category === 'future'
+    // Files-shaped types are pinned to `deferred_to: "v0.4"` per
+    // cli-design.md §5.3 writer-expansion roadmap (the "files" row).
+    // Monday writes these via `add_file_to_column` (multipart upload)
+    // rather than `change_column_value`, so the friendly translator
+    // can't translate them at all and `--set-raw` also rejects them
+    // (different code path; raw-write.ts emits the same v0.4
+    // deferral). Without this branch, files-shaped types would fall
+    // through to the generic `future` branch and contradict the
+    // contract — Codex M18 round-2 P2.
+    if (isFilesShapedType(type)) {
+        return new ApiError('unsupported_column_type', `Column "${columnId}" has type "${type}", which Monday writes ` +
+            `via add_file_to_column (multipart upload) rather than ` +
+            `change_column_value. The friendly --set translator can't ` +
+            `reach this surface; --set-raw <col>=<json> can't either. ` +
+            `Asset upload is pinned to v0.4 per cli-design.md §13.`, {
+            details: {
+                column_id: columnId,
+                type,
+                deferred_to: 'v0.4',
+                hint: 'asset upload is a v0.4 deferral; the underlying mutation ' +
+                    '(add_file_to_column) requires multipart wire shape that ' +
+                    'the column-value path does not model.',
+            },
+        });
+    }
+    // `time_tracking` is pinned to `deferred_to: "v0.3"` per
+    // cli-design.md §5.3 writer-expansion roadmap row. It's a v0.3
+    // deferral because the semantics are start/stop verbs (not value
+    // writes), so the friendly translator can't represent it without
+    // a verb-shaped extension. `--set-raw` rejects similarly.
+    if (type === 'time_tracking') {
+        return new ApiError('unsupported_column_type', `Column "${columnId}" has type "time_tracking", which Monday ` +
+            `mutates via start/stop verbs rather than column-value writes. ` +
+            `The friendly --set translator and --set-raw both target ` +
+            `change_column_value-shaped types; time_tracking needs a ` +
+            `verb-shaped extension pinned for v0.3.`, {
+            details: {
+                column_id: columnId,
+                type,
+                deferred_to: 'v0.3',
+                hint: 'time_tracking uses start/stop verbs, not column-value ' +
+                    'writes. v0.3 plans a dedicated surface; until then there ' +
+                    'is no friendly or raw write path.',
+            },
+        });
+    }
+    return new ApiError('unsupported_column_type', `Column "${columnId}" has type "${type}", which is not in the ` +
+        `friendly --set translator allowlist (text, long_text, numbers, ` +
+        `status, dropdown, date, people, link, email, phone) and is not ` +
+        `pinned to a specific roadmap version. Try --set-raw <col>=<json> ` +
+        `with the documented Monday wire shape — that path accepts any ` +
+        `type Monday writes via change_column_value. Files-shaped types ` +
+        `(file) and read-only-forever types (mirror / formula / etc.) are ` +
+        `the exception; --set-raw rejects those at column-resolution time.`, {
+        details: {
+            column_id: columnId,
+            type,
+            deferred_to: 'future',
+            hint: 'use --set-raw <col>=<json> with the Monday wire shape if the ' +
+                'type accepts change_column_value. Examples in this bucket ' +
+                '(battery, rating) are not yet scoped on the writer-expansion ' +
+                'roadmap. See cli-design.md §5.3.',
+        },
+    });
+};
+//# sourceMappingURL=column-values.js.map