monday-cli 0.2.0 → 0.3.0

package/dist/api/column-values.js

@@ -7,27 +7,39 @@
  * `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
+ * **Two entry points.** Most 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:
+ * `translateColumnValue`. The four async types — `people`,
+ * `tags`, `board_relation`, `dependency` — hit the network during
+ * resolution (email→ID lookup, tag-name→tag-id lookup against the
+ * per-account directory, item-allowed-board membership check via
+ * batched `items(ids: [...])`). Rather than forcing a
+ * `Promise<TranslatedColumnValue>` on every call site for the
+ * sync types, `translateColumnValueAsync` is the unified async
+ * entry point the command layer always calls. It delegates to the
+ * sync version for non-async types and dispatches to
+ * `translatePeople` / `translateTags` / `translateRelation` for
+ * the async ones. M5b's write surface goes through async
+ * exclusively (any of those four types may appear in a `--set`
+ * bundle).
+ *
+ * **Scope.** Thirteen allowlisted types translate (post-M19 close):
  * `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
+ * the M3 `userByEmail` directory cache); 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).
+ * as the v0.1 rich types); and the M19 row — `tags` (rich, with
+ * tag-name→tag-id resolution via the per-account directory cache
+ * in `tag-directory.ts`), `board_relation` and `dependency`
+ * (rich, with `{item_ids: [N1, N2]}` wire shape and per-item
+ * allowed-boards validation via
+ * `validateBoardRelationItems` in `board-relation-validation.ts`;
+ * `board_relation` reads `column.settings.boardIds`, `dependency`
+ * reads `column.settings.dependencyBoards`).
  *
  * **Date resolution context** (cli-design §5.3 step 3 + the
  * "Relative dates and timezone" subsection). Relative tokens
@@ -99,12 +111,13 @@
  * targets at `--set-raw`."
  */
 import { ApiError, UsageError } from '../utils/errors.js';
-import { getColumnRoadmapCategory, isFilesShapedType, isWritableColumnType, } from './column-types.js';
+import { isFilesShapedType, isReadOnlyForeverType, isV0_2WriterExpansionType, isWritableColumnType, parseColumnSettings, } 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';
+import { parseRelationItemIds, } from './board-relation-validation.js';
 /**
  * Translates a single `<column>=<value>` pair into the Monday wire
  * payload. **Sync entry point — handles the nine types whose
@@ -168,6 +181,9 @@ export const translateColumnValue = (inputs) => {
                 payload: { format: 'rich', value: parsed.payload },
                 resolvedFrom: parsed.resolvedFrom,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
         }
         case 'link': {
@@ -184,6 +200,9 @@ export const translateColumnValue = (inputs) => {
                 payload: { format: 'rich', value: parsed },
                 resolvedFrom: null,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
         }
         case 'email': {
@@ -195,6 +214,9 @@ export const translateColumnValue = (inputs) => {
                 payload: { format: 'rich', value: parsed },
                 resolvedFrom: null,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
         }
         case 'phone': {
@@ -206,6 +228,9 @@ export const translateColumnValue = (inputs) => {
                 payload: { format: 'rich', value: parsed },
                 resolvedFrom: null,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
         }
         case 'people':
@@ -224,6 +249,36 @@ export const translateColumnValue = (inputs) => {
                     hint: 'use translateColumnValueAsync from src/api/column-values.ts',
                 },
             });
+        case 'tags':
+            // Tag translation is async (tag-name→tag-id resolution hits
+            // the per-account directory cache or the `account.tags`
+            // GraphQL endpoint). Surface as `internal_error` for the same
+            // reason as `people` — a future contributor who accidentally
+            // routes a tags column through the sync entry point sees a
+            // loud programmer-error message rather than a silent payload
+            // corruption.
+            throw new ApiError('internal_error', `translateColumnValue (sync) called on tags column "${column.id}". ` +
+                `Tag resolution is async — use translateColumnValueAsync.`, {
+                details: {
+                    column_id: column.id,
+                    column_type: column.type,
+                    hint: 'use translateColumnValueAsync from src/api/column-values.ts',
+                },
+            });
+        case 'board_relation':
+        case 'dependency':
+            // Relation translation is async (the validator hits live
+            // `items(ids: [...])` against Monday). Same programmer-error
+            // shape as people / tags. board_relation lands at Commit 3,
+            // dependency at Commit 4 — both share the same sync guard.
+            throw new ApiError('internal_error', `translateColumnValue (sync) called on ${column.type} column "${column.id}". ` +
+                `Relation validation is async — use translateColumnValueAsync.`, {
+                details: {
+                    column_id: column.id,
+                    column_type: column.type,
+                    hint: 'use translateColumnValueAsync from src/api/column-values.ts',
+                },
+            });
     }
 };
 /**
@@ -287,6 +342,9 @@ export const translateColumnClear = (column) => {
                 payload: { format: 'simple', value: '' },
                 resolvedFrom: null,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
         case 'status':
         case 'dropdown':
@@ -295,10 +353,14 @@ export const translateColumnClear = (column) => {
         case 'link':
         case 'email':
         case 'phone':
+        case 'tags':
+        case 'board_relation':
+        case 'dependency':
             // 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.
+            // (link / email / phone) and M19 row (tags / board_relation /
+            // dependency) extend the table verbatim — same payload, same
+            // mutation, same dispatch.
             return {
                 columnId: column.id,
                 columnType: column.type,
@@ -306,13 +368,28 @@ export const translateColumnClear = (column) => {
                 payload: { format: 'rich', value: {} },
                 resolvedFrom: null,
                 peopleResolution: null,
+                tagResolution: null,
+                relationResolution: null,
+                translatorResolution: null,
             };
     }
 };
 export const translateColumnValueAsync = async (inputs) => {
-    if (inputs.column.type !== 'people') {
-        return translateColumnValue(inputs);
+    if (inputs.column.type === 'people') {
+        return translatePeople(inputs);
     }
+    if (inputs.column.type === 'tags') {
+        return translateTags(inputs);
+    }
+    if (inputs.column.type === 'board_relation') {
+        return translateRelation(inputs, 'board_relation');
+    }
+    if (inputs.column.type === 'dependency') {
+        return translateRelation(inputs, 'dependency');
+    }
+    return translateColumnValue(inputs);
+};
+const translatePeople = async (inputs) => {
     const { peopleResolution } = inputs;
     if (peopleResolution === undefined) {
         throw new ApiError('internal_error', `translateColumnValueAsync requires a peopleResolution context for ` +
@@ -347,18 +424,348 @@ export const translateColumnValueAsync = async (inputs) => {
         },
         resolvedFrom: null,
         peopleResolution: parsed.resolution,
+        tagResolution: null,
+        relationResolution: null,
+        // M19→M20 cleanup-window parity fix: thread the people
+        // resolution's aggregated source/age into translatorResolution
+        // so envelope-level meta.source reflects cache-hit email
+        // lookups. Pre-fix this slot was `null` and cache hits silently
+        // dropped from the aggregate (v0.3-plan §11 post-mortem).
+        translatorResolution: {
+            source: parsed.source,
+            cacheAgeSeconds: parsed.cacheAgeSeconds,
+        },
+    };
+};
+/**
+ * Async translator for the M19 `tags` column type. Resolves a
+ * comma-split tag-name list against the per-account directory
+ * (cache-then-live via `tagResolution.resolveTags`), surfaces the
+ * wire payload `{ tag_ids: [N1, N2] }`, populates the per-tag
+ * `tagResolution` echo for dry-run rendering, and threads
+ * source/cache-age provenance through `translatorResolution` for
+ * envelope-level aggregation.
+ *
+ * **Empty input rejected** — mirrors the dropdown / people empty-
+ * input contract per cli-design §5.3 lines 2375–2386 (`--set
+ * <col>=""` is value-shaping, not clear-intent; `monday item clear`
+ * is the dedicated clear surface). Surfaces `usage_error` with
+ * `details.hint` pointing at `monday item clear`.
+ *
+ * **Misses surface as `tag_not_found`** — single error envelope
+ * with `details: { tags: misses[] }` per cli-design §6.5 +
+ * Decision 1 (`4c652d5`). Multi-miss `--set tags=foo,bar,baz` where
+ * two tags are absent surfaces ONE error with `tags: ["foo", "bar"]`,
+ * NOT two separate errors.
+ */
+const translateTags = async (inputs) => {
+    const { tagResolution } = inputs;
+    if (tagResolution === undefined) {
+        throw new ApiError('internal_error', `translateColumnValueAsync requires a tagResolution context for tags ` +
+            `column "${inputs.column.id}". M19's command layer wires resolveTags ` +
+            `through this slot via buildResolutionContexts.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: 'tags',
+                hint: 'pass { tagResolution: { resolveTags } } when calling ' +
+                    'translateColumnValueAsync. The resolveTags callback closes ' +
+                    'over MondayClient + env + noCache.',
+            },
+        });
+    }
+    // Empty input boundary: split + trim + filter — if nothing is left
+    // after the split, the user passed `--set tags=""` or `--set
+    // tags=" , "`. Reject with usage_error pointing at `monday item
+    // clear` (mirror dropdown/people empty-input contract).
+    const tokens = inputs.value
+        .split(',')
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    if (tokens.length === 0) {
+        throw new UsageError(`Tags column "${inputs.column.id}" needs at least one tag name. ` +
+            `Got "${inputs.value}". To clear a tags column, use ` +
+            `\`monday item clear <iid> ${inputs.column.id} [--board <bid>]\` instead.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: 'tags',
+                raw_input: inputs.value,
+                hint: 'pass a comma-separated list of tag names (e.g. --set ' +
+                    `${inputs.column.id}=launch,priority). To clear, use ` +
+                    '`monday item clear` — `--set tags=""` is value-shaping, ' +
+                    'not clear-intent (cli-design §5.3 lines 2375–2386).',
+            },
+        });
+    }
+    const resolved = await tagResolution.resolveTags(inputs.value);
+    if (resolved.misses.length > 0) {
+        const missList = resolved.misses.map((m) => JSON.stringify(m)).join(', ');
+        const noun = resolved.misses.length === 1 ? 'tag' : 'tags';
+        throw new ApiError('tag_not_found', `${resolved.misses.length.toString()} ${noun} not in the account directory: ${missList}`, {
+            details: {
+                tags: resolved.misses,
+                hint: 'Run `monday account tags` to list available tags.',
+            },
+        });
+    }
+    // Build the per-token echo. resolveTags returns ids in input-token
+    // order (post-dedup); zip with the dedup'd token list to surface
+    // the verbatim input alongside each resolved id.
+    const dedup = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        const key = token
+            .normalize('NFC')
+            .trim()
+            .replace(/\s+/gu, ' ')
+            .toLocaleLowerCase('und');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        dedup.push(token);
+    }
+    const echoTokens = dedup.map((token, i) => ({
+        input: token,
+        /* c8 ignore next 5 — defensive: resolveTags returns ids parallel
+           to the dedup'd input order (length-matched), so `id` is always
+           present at index `i`. The String() guard exists for
+           noUncheckedIndexedAccess narrowing only. */
+        resolved_id: String(resolved.ids[i] ?? ''),
+    }));
+    return {
+        columnId: inputs.column.id,
+        columnType: 'tags',
+        rawInput: inputs.value,
+        payload: {
+            format: 'rich',
+            value: { tag_ids: [...resolved.ids] },
+        },
+        resolvedFrom: null,
+        peopleResolution: null,
+        tagResolution: { tokens: echoTokens },
+        relationResolution: null,
+        translatorResolution: {
+            source: resolved.source,
+            cacheAgeSeconds: resolved.cacheAgeSeconds,
+        },
+    };
+};
+/**
+ * Async translator for the M19 `board_relation` and `dependency`
+ * column types. Both share the same wire shape
+ * (`{ item_ids: [N1, N2] }`) and the same per-item allowed-boards
+ * validator; the divergence is the settings field the per-translator
+ * arm reads (`column.settings.boardIds` for `board_relation` /
+ * `column.settings.dependencyBoards` for `dependency`).
+ *
+ * **Five-step resolution.**
+ *
+ *   1. Require `relationResolution` context (programmer-error guard
+ *      mirroring `tags` / `people`).
+ *   2. Require `column.settingsStr` (the field the resolver-pass
+ *      threads through). Surfacing this as `internal_error` rather
+ *      than `usage_error` because the resolver-pass always supplies
+ *      the field; reaching this branch is a wiring bug.
+ *   3. Parse `parseRelationItemIds(value, columnId, context)` for
+ *      input validation — empty / over-cap / non-decimal /
+ *      unsafe-integer / duplicate inputs reject pre-network.
+ *   4. Derive `allowedBoards` from the parsed settings shape per
+ *      `context` discriminant. Empty `allowedBoards` (no boards
+ *      configured on the column) surfaces `usage_error` — the
+ *      validator can't validate against an empty allowed set.
+ *   5. Call `relationResolution.validateItems({ ... })`. On
+ *      mismatch, surface `usage_error` with per-item details. On
+ *      success, build the wire payload + per-item echo.
+ *
+ * **`translatorResolution`** carries `{ source: 'live',
+ * cacheAgeSeconds: null }` for symmetry with the tags translator's
+ * cache-aware path. The relation validator is always live (item
+ * board membership can change cross-call), but threading the slot
+ * keeps the post-translate aggregation pass's shape uniform.
+ */
+const translateRelation = async (inputs, context) => {
+    const { relationResolution } = inputs;
+    if (relationResolution === undefined) {
+        throw new ApiError('internal_error', `translateColumnValueAsync requires a relationResolution context for ` +
+            `${context} column "${inputs.column.id}". M19's command layer wires ` +
+            `validateItems through this slot via buildResolutionContexts.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: context,
+                hint: 'pass { relationResolution: { validateItems } } when calling ' +
+                    'translateColumnValueAsync. The validateItems callback closes ' +
+                    'over MondayClient.',
+            },
+        });
+    }
+    if (inputs.column.settingsStr === undefined ||
+        inputs.column.settingsStr === null) {
+        throw new ApiError('internal_error', `translateColumnValueAsync requires column.settingsStr for ${context} ` +
+            `column "${inputs.column.id}" — the translator reads ` +
+            `${context === 'board_relation' ? 'boardIds' : 'dependencyBoards'} from settings to derive allowed boards.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: context,
+                hint: 'the resolver-pass threads settings_str through ResolvedSet; ' +
+                    'verify the call site passes column.settingsStr (R20 lift, ' +
+                    'M19 widening).',
+            },
+        });
+    }
+    const itemIds = parseRelationItemIds(inputs.value, inputs.column.id, context);
+    const settings = parseColumnSettings(inputs.column.settingsStr);
+    const allowedBoards = deriveAllowedBoards(settings, context);
+    if (allowedBoards.length === 0) {
+        throw new UsageError(`${context === 'board_relation' ? 'Board-relation' : 'Dependency'} column "${inputs.column.id}" has no ${context === 'board_relation' ? 'allowed boards' : 'dependency boards'} configured. Configure the column's linked-board list in Monday's ` +
+            `UI before linking items via --set, or use --set-raw with the ` +
+            `literal Monday wire shape.`, {
+            details: {
+                column_id: inputs.column.id,
+                column_type: context,
+                raw_input: inputs.value,
+                hint: `${context === 'board_relation' ? 'board_relation' : 'dependency'} columns scope item links to a configured set of boards; the ` +
+                    `translator can't validate item membership against an empty ` +
+                    `allowed set.`,
+            },
+        });
+    }
+    const result = await relationResolution.validateItems({
+        itemIds,
+        allowedBoards,
+        columnId: inputs.column.id,
+        context,
+    });
+    if (!result.ok) {
+        throw new UsageError(buildRelationMismatchMessage(inputs.column.id, context, result.mismatches), {
+            details: {
+                column_id: inputs.column.id,
+                column_type: context,
+                raw_input: inputs.value,
+                allowed_boards: allowedBoards,
+                mismatches: result.mismatches.map((m) => ({
+                    item_id: m.itemId,
+                    actual_board: m.actualBoard,
+                })),
+                hint: `each item must belong to one of the column's allowed boards ` +
+                    `[${allowedBoards.join(', ')}]. Items missing from the response ` +
+                    `(actual_board: null) were not visible to the caller's token, ` +
+                    `archived, or deleted.`,
+            },
+        });
+    }
+    // Build per-item echo from the validator's items array. The
+    // validator preserves input-token order (parseRelationItemIds
+    // rejects duplicates so order-preservation is straightforward).
+    const echoItems = result.items.map((item) => ({
+        input: item.itemId.toString(),
+        /* c8 ignore next 5 — defensive: validateItems only returns items
+           in result.items when the per-item check passes (boardId is
+           present + allowed). String() guard for noUncheckedIndexedAccess
+           narrowing. */
+        resolved_board_id: item.boardId === null ? '' : item.boardId.toString(),
+    }));
+    return {
+        columnId: inputs.column.id,
+        // Type-cast: at Commit 3 only `'board_relation'` is in
+        // WRITABLE_COLUMN_TYPES; Commit 4 adds `'dependency'` and the
+        // cast becomes structurally identity. The dispatcher only
+        // routes the matching column types here, so the cast is safe.
+        columnType: context,
+        rawInput: inputs.value,
+        payload: {
+            format: 'rich',
+            value: { item_ids: [...itemIds] },
+        },
+        resolvedFrom: null,
+        peopleResolution: null,
+        tagResolution: null,
+        relationResolution: {
+            context,
+            allowed_boards: allowedBoards,
+            items: echoItems,
+        },
+        translatorResolution: {
+            source: 'live',
+            cacheAgeSeconds: null,
+        },
     };
 };
+/**
+ * Derives the column's allowed-board list from its parsed
+ * `settings_str`. `board_relation` reads `settings.boardIds`
+ * (falling back to `[settings.boardId]` for legacy single-target
+ * shape Monday occasionally returns); `dependency` reads
+ * `settings.dependencyBoards` per Monday's distinct settings shape.
+ *
+ * Returns `readonly number[]` after filtering to safe integers — a
+ * malformed settings entry surfaces as an empty list, which the
+ * caller branches on via the no-allowed-boards usage_error.
+ */
+const deriveAllowedBoards = (settings, context) => {
+    if (settings === null || typeof settings !== 'object')
+        return [];
+    const obj = settings;
+    let candidates = [];
+    if (context === 'board_relation') {
+        if (Array.isArray(obj.boardIds)) {
+            candidates = obj.boardIds;
+        }
+        else if (obj.boardId !== undefined) {
+            // Codex post-Commit-5 P1-2 fix: legacy singular `boardId` may
+            // be a decimal string (Monday occasionally returns string IDs
+            // in legacy boards) — route through the same parse path as the
+            // array entries below rather than gating on `typeof === number`.
+            // The shared filter below tolerates non-matching shapes.
+            candidates = [obj.boardId];
+        }
+    }
+    else if (Array.isArray(obj.dependencyBoards)) {
+        candidates = obj.dependencyBoards;
+    }
+    const out = [];
+    for (const candidate of candidates) {
+        if (typeof candidate === 'number' && Number.isSafeInteger(candidate)) {
+            out.push(candidate);
+        }
+        else if (typeof candidate === 'string' &&
+            /^(?:0|[1-9]\d*)$/u.test(candidate)) {
+            const parsed = Number(candidate);
+            if (Number.isSafeInteger(parsed))
+                out.push(parsed);
+        }
+    }
+    return out;
+};
+/**
+ * Builds the human-readable `usage_error` message for one or more
+ * relation mismatches. Mirrors the per-noun wording the
+ * `parseRelationItemIds` errors use ("Board-relation column…",
+ * "Dependency column…") so an agent reading two consecutive errors
+ * sees consistent wording.
+ */
+const buildRelationMismatchMessage = (columnId, context, mismatches) => {
+    const titled = context === 'board_relation' ? 'Board-relation' : 'Dependency';
+    const noun = mismatches.length === 1 ? 'item' : 'items';
+    const detail = mismatches
+        .map((m) => m.actualBoard === null
+        ? `${m.itemId.toString()} (not visible / deleted)`
+        : `${m.itemId.toString()} (board ${m.actualBoard.toString()})`)
+        .join(', ');
+    return (`${titled} column "${columnId}" rejected ${mismatches.length.toString()} ` +
+        `${noun} not in the column's allowed-board set: ${detail}.`);
+};
 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.
+    // Only the date / people / tags / relation 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,
+    tagResolution: null,
+    relationResolution: null,
+    translatorResolution: null,
 });
 const rich = (columnId, columnType, rawInput, value) => ({
     columnId,
@@ -367,6 +774,9 @@ const rich = (columnId, columnType, rawInput, value) => ({
     rawInput,
     resolvedFrom: null,
     peopleResolution: null,
+    tagResolution: null,
+    relationResolution: null,
+    translatorResolution: null,
 });
 /**
  * Status payload per `cli-design.md` §5.3 step 3:
@@ -663,133 +1073,150 @@ export const bundleColumnValues = (translated) => {
  * agents get accurate guidance instead of a blanket "wait for the
  * next version" hint.
  *
- * Three categories per `column-types.ts getColumnRoadmapCategory`:
+ * **5-way classifier** (M19 fold of v0.2-plan §22 / v0.3-plan §22
+ * non-R-class quality refactor — collapses the prior 5-branch
+ * if/else chain into a single category-table dispatch).
+ * Categories, in precedence order:
  *
- *   - **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.
+ *     `creation_log` / `last_updated` / `item_id` / `item_assignees`)
+ *     — Monday-computed columns that are not writable via the API
+ *     regardless of CLI version. Carry `read_only: true` (no
+ *     `deferred_to`); hint points at the underlying source column.
+ *     cli-design.md §5.3 writer-expansion roadmap "read-only forever"
+ *     row says this explicitly.
+ *   - **v0.2 writer-expansion** (`tags` / `board_relation` /
+ *     `dependency` — slipped from v0.2 tentative at M18 close;
+ *     graduated into the friendly allowlist at M19 close so this
+ *     row is unreachable post-M19 but stays as documented dead code
+ *     for stability + future tentative-row revival). Carry
+ *     `deferred_to: "v0.3"`; hint nudges agents at `--set-raw`.
+ *   - **`files`-shaped** (currently `file` only) — Monday writes via
+ *     `add_file_to_column` (multipart upload) rather than
+ *     `change_column_value`, so neither friendly translator nor
+ *     `--set-raw` can reach the wire surface. Carry
+ *     `deferred_to: "v0.4"`; hint flags the multipart-upload nature.
+ *   - **`time_tracking`** — verb-shaped extension (start/stop, not
+ *     value writes); v0.3-deferred. Carry `deferred_to: "v0.3"`;
+ *     hint points at the upcoming verb surface.
+ *   - **future** (anything else — `battery`, `rating`, etc.) —
+ *     `deferred_to: "future"`, generic message pointing at
+ *     `--set-raw` provided the type accepts `change_column_value`.
  *
  * 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 ` +
+    const category = classifyUnsupported(type);
+    const row = UNSUPPORTED_TABLE[category];
+    return new ApiError('unsupported_column_type', row.message(columnId, type), {
+        details: {
+            column_id: columnId,
+            type,
+            ...row.details(columnId),
+        },
+    });
+};
+const classifyUnsupported = (type) => {
+    if (isReadOnlyForeverType(type))
+        return 'read_only_forever';
+    if (isV0_2WriterExpansionType(type))
+        return 'v0_2_writer_expansion';
+    if (isFilesShapedType(type))
+        return 'files_shaped';
+    if (type === 'time_tracking')
+        return 'time_tracking';
+    return 'future';
+};
+const UNSUPPORTED_TABLE = {
+    read_only_forever: {
+        message: (columnId, 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 ` +
+            `the mirror reflects on the linked board).`,
+        details: () => ({
+            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.',
+        }),
+    },
+    v0_2_writer_expansion: {
+        message: (columnId, 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 ` +
+            `in the meantime.`,
+        details: (columnId) => ({
+            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.`,
+        }),
+    },
+    files_shaped: {
+        message: (columnId, 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 ` +
+            `Asset upload is pinned to v0.4 per cli-design.md §13.`,
+        details: () => ({
+            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: {
+        message: (columnId) => `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,
+            `change_column_value-shaped types; time_tracking surfaces ` +
+            `as the verb-shaped \`monday item time-track start/stop\` ` +
+            `pair (v0.3 M20, cli-design §5.2 carve-out 2).`,
+        details: () => ({
+            // v0.3 ships the verb names as documentation-only — empirical
+            // probe (2026-05-10, API version 2026-01) confirmed Monday's
+            // public API does not currently support time_tracking writes
+            // via either change_simple_column_value or change_column_value.
+            // The `deferred_to` slot tracks the milestone the verb pair
+            // landed at, not the milestone the wire mutation will ship at
+            // (which is on Monday's roadmap, not ours).
+            deferred_to: 'v0.3',
+            hint: 'time_tracking uses start/stop verbs, not column-value ' +
+                'writes. The verbs `monday item time-track start <iid>` / ' +
+                '`monday item time-track stop <iid>` are registered for ' +
+                'forward-compatibility but currently throw `usage_error` — ' +
+                "Monday's public API does not yet expose a write path for " +
+                'time_tracking columns (probed 2026-05-10). Use Monday\'s ' +
+                'UI to start/stop time-tracking sessions until API support ' +
+                'ships.',
+        }),
+    },
+    future: {
+        message: (columnId, 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: () => ({
             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