monday-cli 0.2.0

package/dist/api/column-mutation-result.js

@@ -0,0 +1,130 @@
+/**
+ * Live-mutation null-result projection for the M16 column lifecycle
+ * cluster (`v0.2-plan.md` §22 R45 lift).
+ *
+ * Three M16 verbs share a near-verbatim shape: null-check the wire
+ * payload, throw a typed ApiError on null carrying both
+ * `details.board_id` and `details.column_id` (the column-mutation
+ * wire signature is two-tuple — `create_column` carries
+ * `board_id` only pre-id, but the read-side projection always pairs
+ * the two), then parse through `columnProjectionSchema` to surface
+ * the §6.4 mutation envelope's `data: <projected snapshot>`.
+ *
+ * Lifted alongside the first M16 column verb commit (mirroring R39's
+ * "ship the projection helper alongside the first new mutation
+ * rather than as a follow-up R-class" precedent — the three M16
+ * verbs land in the same milestone, so adopting the helper from day
+ * one avoids three parallel inline implementations of the same
+ * shape). cf. R28 (`projectMutationItem`), R37 (`projectMutationUpdate`),
+ * R43 (`projectMutationBoard`); R45 ships the fourth per-noun
+ * helper at the same 3-consumer threshold.
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** Like R28 /
+ * R37 / R43, the M16 verbs diverge in error semantics:
+ *   - `column-create` chose `internal_error` (every successful call
+ *     returns a Column — a null payload means Monday glitched server-
+ *     side, abnormal); the `details` carry `board_id` + `title` (no
+ *     column_id yet).
+ *   - `column-update` and `column-delete` chose `not_found`
+ *     (Monday's idiomatic null-for-missing-or-no-access response —
+ *     a typed agent-recovery story); both carry `board_id` +
+ *     `column_id`.
+ * The helper owns the boilerplate (null check, `details: { board_id,
+ * [columnIdKey]: columnIdValue }` envelope, the `unwrapOrThrow`
+ * schema parse); each call site supplies its own typed error parts.
+ *
+ * **`COLUMN_FIELDS_FRAGMENT` + `columnProjectionSchema` co-ship.**
+ * Mirrors R39's `WORKSPACE_FIELDS_FRAGMENT` + `workspaceProjection
+ * Schema` and R43's `BOARD_FIELDS_FRAGMENT` + `boardProjectionSchema`
+ * pattern. The schema mirrors the `columnSchema` already in
+ * `src/api/board-metadata.ts` (the read-side cache projection) but
+ * exists as an exported strict projection schema so M16's three
+ * mutation verbs share one source of truth for the on-the-wire
+ * Column shape.
+ *
+ * **What stays at the call site.** The wire-shape parse of the full
+ * mutation response (`responseSchema.safeParse(response.data)`) stays
+ * inline because each verb's response root key (`create_column` /
+ * `change_column_title` / `change_column_metadata` / `delete_column`)
+ * is per-verb. The missing-root-key check (schema-drift →
+ * `internal_error` with a `hint`) stays inline too — that's Codex
+ * M15 implementation round-2 F1's distinction between schema-drift
+ * and null-payload, deliberately preserved at each site. R42 would
+ * unify the missing-root-key check across all pre-M14 mutation verbs
+ * once scheduled.
+ */
+import { z } from 'zod';
+import { ApiError } from '../utils/errors.js';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+/**
+ * Shared GraphQL selection set for the M16 column projection. 6-space
+ * continuation indent matches the column every consumer interpolates
+ * `${COLUMN_FIELDS_FRAGMENT}` at, so rendered query bytes stay
+ * stable across consumers. Mirrors `BOARD_FIELDS_FRAGMENT` (R43) and
+ * `WORKSPACE_FIELDS_FRAGMENT` (R39).
+ *
+ * Field set tracks `boardMetadataSchema.columns[*]` (the read-side
+ * cache projection) so a `board describe` after a successful column
+ * mutation returns the same JSON shape the mutation envelope did.
+ */
+export const COLUMN_FIELDS_FRAGMENT = `id
+      title
+      type
+      description
+      archived
+      settings_str
+      width`;
+/**
+ * Strict zod schema for the column projection — the exact shape
+ * `COLUMN_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * M16's `column-create` / `column-update` / `column-delete`; each
+ * verb's `CommandModule.outputSchema` aliases this so the schema-
+ * export pipeline emits one canonical shape.
+ *
+ * Mirrors `boardMetadataSchema.columns[*]` in `board-metadata.ts`
+ * verbatim — same fields, same nullability — so a `board describe`
+ * after a successful column mutation reads the same JSON shape the
+ * mutation envelope wrote.
+ */
+export const columnProjectionSchema = z
+    .object({
+    id: z.string().min(1),
+    title: z.string(),
+    type: z.string().min(1),
+    description: z.string().nullable(),
+    archived: z.boolean().nullable(),
+    settings_str: z.string().nullable(),
+    width: z.number().nullable(),
+})
+    .strict();
+/**
+ * Parses + projects a live-mutation `Column` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code
+ * + message so create's `internal_error` / "no column payload from
+ * create_column for board <X> title <Y>" and update's / delete's
+ * `not_found` / "no column payload from <op> for board <X> column
+ * <Y>" both survive the lift byte-for-byte.
+ *
+ * `details: { board_id, [columnIdKey]: columnIdValue }` is supplied
+ * by the helper so every consumer carries the same envelope shape —
+ * agents key off `details.board_id` + `details.column_id` (or
+ * `details.title` on create's pre-id path) regardless of which verb
+ * threw (cli-design §6.5).
+ */
+export const projectMutationColumn = ({ raw, errorCode, errorMessage, boardId, columnIdKey, columnIdValue, }) => {
+    const details = {
+        board_id: boardId,
+        [columnIdKey]: columnIdValue,
+    };
+    if (raw === null || raw === undefined) {
+        throw new ApiError(errorCode, errorMessage, { details });
+    }
+    const subjectPhrase = columnIdKey === 'title'
+        ? `board ${boardId} title ${JSON.stringify(columnIdValue)}`
+        : `board ${boardId} column ${columnIdValue}`;
+    return unwrapOrThrow(columnProjectionSchema.safeParse(raw), {
+        context: `Monday returned a malformed column payload for ${subjectPhrase}`,
+        details,
+    });
+};
+//# sourceMappingURL=column-mutation-result.js.map

package/dist/api/column-mutation-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mutation-result.js","sourceRoot":"","sources":["../../src/api/column-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAkB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;YAM1B,CAAC;AAEb;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,MAAM,EAAE,CAAC;AAmCZ;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,EACpC,GAAG,EACH,SAAS,EACT,YAAY,EACZ,OAAO,EACP,WAAW,EACX,aAAa,GACe,EAAoB,EAAE;IAClD,MAAM,OAAO,GAAsC;QACjD,QAAQ,EAAE,OAAO;QACjB,CAAC,WAAW,CAAC,EAAE,aAAa;KAC7B,CAAC;IACF,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,aAAa,GACjB,WAAW,KAAK,OAAO;QACrB,CAAC,CAAC,SAAS,OAAO,UAAU,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE;QAC3D,CAAC,CAAC,SAAS,OAAO,WAAW,aAAa,EAAE,CAAC;IACjD,OAAO,aAAa,CAAC,sBAAsB,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;QAC1D,OAAO,EAAE,kDAAkD,aAAa,EAAE;QAC1E,OAAO;KACR,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/api/column-types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * v0.1 column-type allowlist + a defensive `settings_str` parser
+ * (`cli-design.md` §5.3 step 3 + step 4, `v0.1-plan.md` §3 M5a).
+ *
+ * Two consumers share this surface:
+ *   - `commands/board/describe.ts` — populates `writable: bool` and
+ *     `example_set: string[] | null` on every column it surfaces, so
+ *     an agent reading one `board describe` payload knows exactly
+ *     which columns `--set` will accept.
+ *   - `api/column-values.ts` (M5a writer) — gates the friendly
+ *     translation paths and surfaces `unsupported_column_type` for
+ *     anything else.
+ *
+ * Owning the allowlist here (not in either consumer) means the
+ * "writable types contract" has one source of truth: the v0.2 author
+ * who wants to add `world_clock` flips one entry and both `describe`
+ * and the writer pick it up. R8 in `v0.1-plan.md` §15 / §17.
+ */
+/**
+ * Writable column types per `cli-design.md` §5.3.3 + the v0.2 writer-
+ * expansion roadmap (M8). Order is frozen — not because Sets are
+ * ordered, but because tests iterate the array form and the snapshot
+ * is part of the contract surface. v0.1 entries appear first (they
+ * shipped first); M8 firm additions follow in roadmap order.
+ *
+ * Categories baked into the same allowlist:
+ *   - **simple** (`text` / `long_text` / `numbers`) — translate to a
+ *     bare string and use `change_simple_column_value`.
+ *   - **rich (v0.1)** (`status` / `dropdown` / `date` / `people`) —
+ *     translate to a JSON object and use `change_column_value` /
+ *     `change_multiple_column_values`.
+ *   - **rich (v0.2 firm)** (`link` / `email` / `phone`) — pipe-form
+ *     `<value>|<text>` parsers in `links.ts` / `emails.ts` /
+ *     `phones.ts`; same `change_column_value` wire path.
+ *
+ * The split lives in `column-values.ts`; here we just enumerate the
+ * full allowlist. Tentative v0.2 types (`tags` / `board_relation` /
+ * `dependency`) stay in `V0_2_WRITER_EXPANSION_TYPES` until their
+ * fixture work clears — they ship firm via the same array's expansion
+ * once translators land, or slip to v0.3 in the M8 post-mortem.
+ */
+export declare const WRITABLE_COLUMN_TYPES: readonly ["text", "long_text", "numbers", "status", "dropdown", "date", "people", "link", "email", "phone"];
+export type WritableColumnType = (typeof WRITABLE_COLUMN_TYPES)[number];
+/**
+ * Membership test for the v0.1 writable allowlist. Narrows the input
+ * type to `WritableColumnType` so downstream switches don't need to
+ * re-cast.
+ */
+export declare const isWritableColumnType: (type: string) => type is WritableColumnType;
+/**
+ * Defensive parse for Monday's `settings_str` field. Monday returns
+ * a JSON-encoded string for status / dropdown / etc. column settings,
+ * but the value can be `null`, an empty string, or a malformed blob
+ * on legacy boards. Callers want a parsed object or `null` — never a
+ * thrown `SyntaxError`.
+ *
+ * Returns `null` when the input is missing / empty / unparseable.
+ * Returns the parsed value (typed `unknown` — caller validates the
+ * shape) when JSON.parse succeeds. The caller is the boundary that
+ * narrows the result to a typed shape.
+ */
+export declare const parseColumnSettings: (raw: string | null) => unknown;
+/**
+ * Column types still pending in the v0.2 writer-expansion milestone
+ * (`cli-design.md` §5.3 writer-expansion roadmap table). M8 shipped
+ * `link` / `email` / `phone` firm — those moved to
+ * `WRITABLE_COLUMN_TYPES` and are no longer surfaced here. The
+ * remaining three are M8's tentative row; their fixture work decides
+ * whether they ship firm in v0.2 (move to `WRITABLE_COLUMN_TYPES`) or
+ * slip to v0.3 (move to a v0.3 deferral surfaced via the same
+ * roadmap-category branch).
+ *
+ * Source-of-truth alongside `WRITABLE_COLUMN_TYPES` so the
+ * `unsupported_column_type` error builder can give per-type-accurate
+ * guidance instead of blanket-deferring every non-allowlisted type.
+ */
+export declare const V0_2_WRITER_EXPANSION_TYPES: readonly ["tags", "board_relation", "dependency"];
+export type V0_2WriterExpansionType = (typeof V0_2_WRITER_EXPANSION_TYPES)[number];
+/**
+ * Column types Monday computes server-side and **never makes
+ * writable via the API** (`cli-design.md` §5.3 writer-expansion
+ * roadmap table — "read-only forever" row). cli-design says
+ * explicitly:
+ *
+ *   > The "read-only forever" row matters for agents: trying `--set`
+ *   > on a mirror/formula/etc. surfaces `unsupported_column_type`
+ *   > and will *always* surface that, regardless of version. The
+ *   > hint should point at the underlying source column, not at
+ *   > `--set-raw`.
+ *
+ * The error builder branches on this set to emit `read_only: true`
+ * (no `deferred_to`) and a hint that names the underlying-source
+ * pattern instead of advertising a future flag.
+ */
+export declare const READ_ONLY_FOREVER_TYPES: readonly ["mirror", "formula", "auto_number", "creation_log", "last_updated", "item_id", "item_assignees"];
+export type ReadOnlyForeverType = (typeof READ_ONLY_FOREVER_TYPES)[number];
+/**
+ * Membership test for the read-only-forever row. Used by `--set-raw`
+ * (M8) to reject these types post-resolution per cli-design §5.3
+ * escape-hatch contract — Monday's API never makes them writable
+ * regardless of payload, so accepting a raw payload would just shift
+ * the failure from CLI-time to Monday-time.
+ */
+export declare const isReadOnlyForeverType: (type: string) => type is ReadOnlyForeverType;
+/**
+ * Column types Monday writes via `add_file_to_column` (file upload
+ * via multipart) rather than `change_column_value` / `change_multiple_
+ * column_values` (`cli-design.md` §5.3 writer-expansion roadmap "files"
+ * row + the escape-hatch contract).
+ *
+ * The friendly translator and `--set-raw` both go through
+ * `change_column_value` / `change_multiple_column_values`, so a
+ * `--set-raw` raw payload cannot reach the right wire surface for
+ * these types — `--set-raw` rejects them with `unsupported_column_
+ * type` carrying `deferred_to: "v0.4"` (asset upload pinned to v0.4
+ * per cli-design §13).
+ *
+ * Currently one entry (`file`); the slot is plural because Monday may
+ * surface other multipart-upload-shaped types in future API versions
+ * and the contract should accommodate adding rows without touching
+ * the consumer.
+ */
+export declare const FILES_SHAPED_TYPES: readonly ["file"];
+export type FilesShapedType = (typeof FILES_SHAPED_TYPES)[number];
+/**
+ * Membership test for the files-shaped row. Used by `--set-raw` (M8)
+ * to reject these types post-resolution per cli-design §5.3 escape-
+ * hatch contract — the underlying mutation isn't `change_column_value`
+ * so a raw payload can't reach the right wire surface.
+ */
+export declare const isFilesShapedType: (type: string) => type is FilesShapedType;
+/**
+ * Roadmap category for an unsupported column type. The
+ * `unsupported_column_type` error builder uses this to pick a
+ * per-category message + details slot.
+ *
+ *   - `'v0_2_writer_expansion'` — tentative-row writer-expansion
+ *     types (`tags` / `board_relation` / `dependency`) that
+ *     **slipped from v0.2 to v0.3 at M18 close**. Surfaces
+ *     `deferred_to: "v0.3"` and points at the v0.3 writer-expansion
+ *     work. The category constant name retains its M8-era spelling
+ *     for stability — renaming would churn every consumer with no
+ *     wire-shape change. M8 shipped `link` / `email` / `phone`
+ *     firm so the branch no longer fires for those types — they
+ *     resolve through the friendly translator.
+ *   - `'read_only_forever'` — Monday-computed columns (mirror /
+ *     formula / auto_number / creation_log / last_updated /
+ *     item_id). Surfaces `read_only: true` and points at the
+ *     underlying source column. `--set-raw` rejects these too —
+ *     the read-only-forever check fires after column resolution
+ *     but before mutation.
+ *   - `'future'` — any other unsupported type (battery /
+ *     item_assignees / time_tracking / rating / files / etc.).
+ *     Surfaces `deferred_to: "future"` with a generic message that
+ *     doesn't commit to a specific version. The friendly translator
+ *     rejects; `--set-raw` accepts when the underlying mutation is
+ *     `change_column_value` (files-shaped types like `file` are a
+ *     v0.4 deferral and `--set-raw` rejects them too).
+ *
+ * Codex M5b cleanup re-review #1: pre-fix `unsupportedColumnType
+ * Error` blanket-deferred every non-allowlisted type to v0.2, which
+ * over-promised for the read-only-forever row and the v0.3+ rows.
+ * Codex M18 pre-flight P2-4: tentative row slipped to v0.3 at M18
+ * close per cli-design §13 + §5.3 line 2172 — runtime + tests +
+ * comments aligned.
+ */
+export type ColumnRoadmapCategory = 'v0_2_writer_expansion' | 'read_only_forever' | 'future';
+export declare const getColumnRoadmapCategory: (type: string) => ColumnRoadmapCategory;
+/**
+ * Categorisation for the M16 `column-create` `noncanonical_column_
+ * type` warning (cli-design §4.3 column-create + §6 stable warning-
+ * code registry). Distinct from `getColumnRoadmapCategory` (which
+ * powers the `unsupported_column_type` write-time error builder)
+ * because the warning's audience is "agent created a column of a
+ * non-canonical type — here's how to write to it later", not
+ * "agent tried to write and Monday rejected it".
+ *
+ * The three categories — chosen to match the §6 warning shape's
+ * `category` enum verbatim — are:
+ *   - `'raw_writable'`: Monday accepts `change_column_value` against
+ *     the type, but the v0.2 friendly translator (§5.3) doesn't
+ *     model it. Agents reach for the `--set-raw <col>=<json>`
+ *     escape hatch. Default for any non-writable, non-read-only-
+ *     forever, non-files-shaped type (covers `country`, `hour`,
+ *     `timeline`, `tags`, `board_relation`, `dependency`, etc.).
+ *   - `'read_only_forever'`: Monday computes the type server-side
+ *     and never makes it writable via the API. `suggested_write_
+ *     path` is `null` (agents can't write at all; the column
+ *     exists for read-side display / mirror sources only).
+ *   - `'files_shaped'`: Monday writes the type via `add_file_to_
+ *     column` (multipart upload), pinned to v0.4 (asset upload).
+ *     Currently `file` only.
+ *
+ * Returns `null` for canonical types (membership in `WRITABLE_COLUMN_
+ * TYPES`) — `column-create` skips emitting the warning when the type
+ * is canonical.
+ *
+ * The `category` enum value is part of the §6 stable warning-code
+ * registry — adding a category is SemVer-minor; removing or renaming
+ * is SemVer-major.
+ */
+export type NoncanonicalColumnTypeCategory = 'raw_writable' | 'read_only_forever' | 'files_shaped';
+export interface NoncanonicalColumnTypeDetails {
+    readonly category: NoncanonicalColumnTypeCategory;
+    /**
+     * The path agents should use to write to the column post-creation,
+     * matching cli-design §5.3 escape-hatch contract — `--set-raw
+     * <col>=<json>` for raw-writable types, `add_file_to_column
+     * (deferred to v0.4)` for files-shaped types, `null` for read-
+     * only-forever types (no write path exists).
+     */
+    readonly suggestedWritePath: string | null;
+}
+export declare const categorizeNoncanonicalColumnType: (type: string) => NoncanonicalColumnTypeDetails | null;
+//# sourceMappingURL=column-types.d.ts.map

package/dist/api/column-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-types.d.ts","sourceRoot":"","sources":["../../src/api/column-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,6GAWxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAIxE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,kBAC/B,CAAC;AAE9B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,GAAG,IAAI,KAAG,OAOxD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,mDAI9B,CAAC;AAEX,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAM/C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,4GAe1B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAM3E;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,mBAC5B,CAAC;AAElC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,mBAAoB,CAAC;AAEpD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMlE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,IAAI,IAAI,eAC7B,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,qBAAqB,GAC7B,uBAAuB,GACvB,mBAAmB,GACnB,QAAQ,CAAC;AAEb,eAAO,MAAM,wBAAwB,GACnC,MAAM,MAAM,KACX,qBAIF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,8BAA8B,GACtC,cAAc,GACd,mBAAmB,GACnB,cAAc,CAAC;AAEnB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED,eAAO,MAAM,gCAAgC,GAC3C,MAAM,MAAM,KACX,6BAA6B,GAAG,IAelC,CAAC"}

package/dist/api/column-types.js

@@ -0,0 +1,195 @@
+/**
+ * v0.1 column-type allowlist + a defensive `settings_str` parser
+ * (`cli-design.md` §5.3 step 3 + step 4, `v0.1-plan.md` §3 M5a).
+ *
+ * Two consumers share this surface:
+ *   - `commands/board/describe.ts` — populates `writable: bool` and
+ *     `example_set: string[] | null` on every column it surfaces, so
+ *     an agent reading one `board describe` payload knows exactly
+ *     which columns `--set` will accept.
+ *   - `api/column-values.ts` (M5a writer) — gates the friendly
+ *     translation paths and surfaces `unsupported_column_type` for
+ *     anything else.
+ *
+ * Owning the allowlist here (not in either consumer) means the
+ * "writable types contract" has one source of truth: the v0.2 author
+ * who wants to add `world_clock` flips one entry and both `describe`
+ * and the writer pick it up. R8 in `v0.1-plan.md` §15 / §17.
+ */
+/**
+ * Writable column types per `cli-design.md` §5.3.3 + the v0.2 writer-
+ * expansion roadmap (M8). Order is frozen — not because Sets are
+ * ordered, but because tests iterate the array form and the snapshot
+ * is part of the contract surface. v0.1 entries appear first (they
+ * shipped first); M8 firm additions follow in roadmap order.
+ *
+ * Categories baked into the same allowlist:
+ *   - **simple** (`text` / `long_text` / `numbers`) — translate to a
+ *     bare string and use `change_simple_column_value`.
+ *   - **rich (v0.1)** (`status` / `dropdown` / `date` / `people`) —
+ *     translate to a JSON object and use `change_column_value` /
+ *     `change_multiple_column_values`.
+ *   - **rich (v0.2 firm)** (`link` / `email` / `phone`) — pipe-form
+ *     `<value>|<text>` parsers in `links.ts` / `emails.ts` /
+ *     `phones.ts`; same `change_column_value` wire path.
+ *
+ * The split lives in `column-values.ts`; here we just enumerate the
+ * full allowlist. Tentative v0.2 types (`tags` / `board_relation` /
+ * `dependency`) stay in `V0_2_WRITER_EXPANSION_TYPES` until their
+ * fixture work clears — they ship firm via the same array's expansion
+ * once translators land, or slip to v0.3 in the M8 post-mortem.
+ */
+export const WRITABLE_COLUMN_TYPES = [
+    'text',
+    'long_text',
+    'numbers',
+    'status',
+    'dropdown',
+    'date',
+    'people',
+    'link',
+    'email',
+    'phone',
+];
+const WRITABLE_TYPE_SET = new Set(WRITABLE_COLUMN_TYPES);
+/**
+ * Membership test for the v0.1 writable allowlist. Narrows the input
+ * type to `WritableColumnType` so downstream switches don't need to
+ * re-cast.
+ */
+export const isWritableColumnType = (type) => WRITABLE_TYPE_SET.has(type);
+/**
+ * Defensive parse for Monday's `settings_str` field. Monday returns
+ * a JSON-encoded string for status / dropdown / etc. column settings,
+ * but the value can be `null`, an empty string, or a malformed blob
+ * on legacy boards. Callers want a parsed object or `null` — never a
+ * thrown `SyntaxError`.
+ *
+ * Returns `null` when the input is missing / empty / unparseable.
+ * Returns the parsed value (typed `unknown` — caller validates the
+ * shape) when JSON.parse succeeds. The caller is the boundary that
+ * narrows the result to a typed shape.
+ */
+export const parseColumnSettings = (raw) => {
+    if (raw === null || raw.length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Column types still pending in the v0.2 writer-expansion milestone
+ * (`cli-design.md` §5.3 writer-expansion roadmap table). M8 shipped
+ * `link` / `email` / `phone` firm — those moved to
+ * `WRITABLE_COLUMN_TYPES` and are no longer surfaced here. The
+ * remaining three are M8's tentative row; their fixture work decides
+ * whether they ship firm in v0.2 (move to `WRITABLE_COLUMN_TYPES`) or
+ * slip to v0.3 (move to a v0.3 deferral surfaced via the same
+ * roadmap-category branch).
+ *
+ * Source-of-truth alongside `WRITABLE_COLUMN_TYPES` so the
+ * `unsupported_column_type` error builder can give per-type-accurate
+ * guidance instead of blanket-deferring every non-allowlisted type.
+ */
+export const V0_2_WRITER_EXPANSION_TYPES = [
+    'tags',
+    'board_relation',
+    'dependency',
+];
+const V0_2_WRITER_EXPANSION_SET = new Set(V0_2_WRITER_EXPANSION_TYPES);
+/**
+ * Column types Monday computes server-side and **never makes
+ * writable via the API** (`cli-design.md` §5.3 writer-expansion
+ * roadmap table — "read-only forever" row). cli-design says
+ * explicitly:
+ *
+ *   > The "read-only forever" row matters for agents: trying `--set`
+ *   > on a mirror/formula/etc. surfaces `unsupported_column_type`
+ *   > and will *always* surface that, regardless of version. The
+ *   > hint should point at the underlying source column, not at
+ *   > `--set-raw`.
+ *
+ * The error builder branches on this set to emit `read_only: true`
+ * (no `deferred_to`) and a hint that names the underlying-source
+ * pattern instead of advertising a future flag.
+ */
+export const READ_ONLY_FOREVER_TYPES = [
+    'mirror',
+    'formula',
+    'auto_number',
+    'creation_log',
+    'last_updated',
+    'item_id',
+    // M16 pre-flight pin (cli-design §4.3 column-create): item_assignees
+    // is computed server-side from the board's people columns and has
+    // no direct write surface. M16 column-create's noncanonical_column_
+    // type warning categorises it as `read_only_forever`; the same
+    // membership check gates `--set-raw item_assignees=<json>` so the
+    // CLI rejects it ahead of Monday's server-side rejection rather
+    // than waiting for `validation_failed` to come back.
+    'item_assignees',
+];
+const READ_ONLY_FOREVER_SET = new Set(READ_ONLY_FOREVER_TYPES);
+/**
+ * Membership test for the read-only-forever row. Used by `--set-raw`
+ * (M8) to reject these types post-resolution per cli-design §5.3
+ * escape-hatch contract — Monday's API never makes them writable
+ * regardless of payload, so accepting a raw payload would just shift
+ * the failure from CLI-time to Monday-time.
+ */
+export const isReadOnlyForeverType = (type) => READ_ONLY_FOREVER_SET.has(type);
+/**
+ * Column types Monday writes via `add_file_to_column` (file upload
+ * via multipart) rather than `change_column_value` / `change_multiple_
+ * column_values` (`cli-design.md` §5.3 writer-expansion roadmap "files"
+ * row + the escape-hatch contract).
+ *
+ * The friendly translator and `--set-raw` both go through
+ * `change_column_value` / `change_multiple_column_values`, so a
+ * `--set-raw` raw payload cannot reach the right wire surface for
+ * these types — `--set-raw` rejects them with `unsupported_column_
+ * type` carrying `deferred_to: "v0.4"` (asset upload pinned to v0.4
+ * per cli-design §13).
+ *
+ * Currently one entry (`file`); the slot is plural because Monday may
+ * surface other multipart-upload-shaped types in future API versions
+ * and the contract should accommodate adding rows without touching
+ * the consumer.
+ */
+export const FILES_SHAPED_TYPES = ['file'];
+const FILES_SHAPED_SET = new Set(FILES_SHAPED_TYPES);
+/**
+ * Membership test for the files-shaped row. Used by `--set-raw` (M8)
+ * to reject these types post-resolution per cli-design §5.3 escape-
+ * hatch contract — the underlying mutation isn't `change_column_value`
+ * so a raw payload can't reach the right wire surface.
+ */
+export const isFilesShapedType = (type) => FILES_SHAPED_SET.has(type);
+export const getColumnRoadmapCategory = (type) => {
+    if (V0_2_WRITER_EXPANSION_SET.has(type))
+        return 'v0_2_writer_expansion';
+    if (READ_ONLY_FOREVER_SET.has(type))
+        return 'read_only_forever';
+    return 'future';
+};
+export const categorizeNoncanonicalColumnType = (type) => {
+    if (isWritableColumnType(type))
+        return null;
+    if (isReadOnlyForeverType(type)) {
+        return { category: 'read_only_forever', suggestedWritePath: null };
+    }
+    if (isFilesShapedType(type)) {
+        return {
+            category: 'files_shaped',
+            suggestedWritePath: 'add_file_to_column (deferred to v0.4)',
+        };
+    }
+    return {
+        category: 'raw_writable',
+        suggestedWritePath: '--set-raw <col>=<json>',
+    };
+};
+//# sourceMappingURL=column-types.js.map

package/dist/api/column-types.js.map

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