monday-cli 0.2.0

package/dist/api/item-helpers.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared item-command helpers (R9, surfaced post-M4 in
+ * `v0.1-plan.md` §17; lifted as the M5b opening move).
+ *
+ * The five M4 item-read commands (`get` / `list` / `find` / `search`
+ * / `subitems`) and M5a's dry-run engine all spell the same item
+ * GraphQL projection and the same per-command scaffolding:
+ *
+ *  - The `column_values { id type text value column { title } }`
+ *    selection appeared 10× across the five item commands plus once
+ *    in `api/dry-run.ts`. A future contract change (a new column-
+ *    side field landing on `cli-design.md` §6.2) would otherwise
+ *    require a 12-touch sweep.
+ *  - The full item-shape selection (id / name / state / url /
+ *    created_at / updated_at / board { id } / group { id title } /
+ *    parent_item { id } / column_values { ... }) appears in `get`,
+ *    `list` (3×), `find` (3×), `search` (2×), `subitems`, and
+ *    `dry-run.ts`. Same one-touch contract argument.
+ *  - `resolveMeFactory`, `collectColumnHeads`, `titleMap`, and the
+ *    parse-then-project closure for collection commands were each
+ *    duplicated verbatim across `list.ts` and `search.ts`.
+ *
+ * Lifting them here gives M5b's mutation surface (`item set` / `item
+ * clear` / `item update`) and any future bulk path one place to
+ * import from instead of copy-pasting from `commands/item/list.ts`.
+ *
+ * **Contract surface.** Adding a field to `COLUMN_VALUES_FRAGMENT`
+ * (or `ITEM_FIELDS_FRAGMENT`) widens what `cli-design.md` §6.2 /
+ * §6.3 surface — bumps the envelope shape across every consumer in
+ * lockstep, which is the point. Do not introduce per-command
+ * divergence; if a single command needs more fields, extend the
+ * fragment and accept the cross-consumer change.
+ */
+import type { ColumnHead } from '../utils/output/envelope.js';
+import { type ProjectedItem, type RawItem } from './item-projection.js';
+import type { MondayClient } from './client.js';
+/**
+ * The `column_values { ... }` selection Monday returns under every
+ * item shape in the v0.1 read surface. Inlined as a string because
+ * Monday's GraphQL surface accepts only inline expansion at the
+ * points the v0.1 commands use it (no `fragment ... on Item`
+ * registration is necessary).
+ *
+ * Indentation matches the spots every existing consumer interpolated
+ * — keeping the rendered query bytes identical post-lift means
+ * cassettes that hash on the query text continue to match without
+ * re-recording.
+ */
+export declare const COLUMN_VALUES_FRAGMENT = "column_values {\n            id\n            type\n            text\n            value\n            column { title }\n          }";
+/**
+ * The full item-shape selection — every scalar field the v0.1
+ * `cli-design.md` §6.2 contract surfaces, plus the
+ * `COLUMN_VALUES_FRAGMENT` expansion. Used by `item get` / `list` /
+ * `find` / `search` / `subitems` and by the M5a dry-run engine.
+ *
+ * Indentation lands at the column the hand-rolled queries used so
+ * cassette / query-text diffs stay clean post-lift.
+ */
+export declare const ITEM_FIELDS_FRAGMENT = "id\n          name\n          state\n          url\n          created_at\n          updated_at\n          board { id }\n          group { id title }\n          parent_item { id }\n          column_values {\n            id\n            type\n            text\n            value\n            column { title }\n          }";
+/**
+ * Builds the `meta.columns` consolidation slot per `cli-design.md`
+ * §6.3 from board metadata. Same shape every collection-list
+ * command emits — the per-row `title` lands in the consolidated
+ * map, so per-cell title repeats drop from each row.
+ *
+ * Pure / synchronous; no I/O.
+ */
+export declare const collectColumnHeads: (metadata: {
+    readonly columns: readonly {
+        readonly id: string;
+        readonly type: string;
+        readonly title: string;
+    }[];
+}) => Readonly<Record<string, ColumnHead>>;
+/**
+ * Builds a title-by-id map for the `projectItem` projector — the
+ * canonical fallback when `column.title` on the wire could drift
+ * (M3 metadata loader's NFC + cache rules are the source of truth).
+ *
+ * Pure / synchronous; no I/O.
+ */
+export declare const titleMap: (metadata: {
+    readonly columns: readonly {
+        readonly id: string;
+        readonly title: string;
+    }[];
+}) => ReadonlyMap<string, string>;
+/**
+ * Builds the `me`-token resolver every people-aware filter / search
+ * command needs. The factory closes over the client; the returned
+ * function fires `client.whoami()` on demand. Callers memo-cache the
+ * resolved ID per build call to keep `--where Owner=me` cheap.
+ *
+ * Throws `UsageError` when the token is not associated with a
+ * Monday user (guest token, etc.). Defensive — the transport layer
+ * surfaces token-association failures as `unauthorized` before this
+ * resolver runs.
+ */
+export declare const resolveMeFactory: (client: MondayClient) => (() => Promise<string>);
+/**
+ * Parses a raw GraphQL item-shape into a `RawItem` with the R18
+ * parse-boundary wrap: malformed payloads surface as
+ * `ApiError(internal_error)` with `details.issues` rather than a
+ * bare ZodError that loses the failing field path.
+ *
+ * Per `validation.md` "Never bubble raw ZodError out of a parse
+ * boundary". Mirrors the dry-run engine's per-id wrap (`api/dry-
+ * run.ts fetchItem`) and `userByEmail` (`api/resolvers.ts`) — same
+ * pattern across every parse boundary.
+ *
+ * Optional `details` are merged into the error envelope (e.g.
+ * `{ item_id: '123' }`) so consumers in `item get` / `find` /
+ * `subitems` can scope the failure to the specific item being
+ * parsed.
+ */
+export declare const parseRawItem: (raw: unknown, details?: Readonly<Record<string, unknown>>) => RawItem;
+/**
+ * Parses one raw GraphQL item-shape and projects it into the §6.2 /
+ * §6.3 `ProjectedItem`. A thin wrapper around
+ * `parseRawItem + projectItem` so the collection commands (`list`,
+ * `search`) spell the same call once.
+ *
+ * `omitColumnTitles: true` is the §6.3 same-board-collection rule —
+ * per-cell `title` drops out of each column entry (consolidated
+ * into `meta.columns`). Single-resource paths (`item get`) skip
+ * this helper because they keep titles inline (`item-projection.ts`
+ * `projectItem` directly).
+ */
+export declare const projectFromRaw: (raw: unknown, titles: ReadonlyMap<string, string>, options: {
+    readonly omitColumnTitles: boolean;
+}) => ProjectedItem;
+export type { RawItem, ProjectedItem };
+//# sourceMappingURL=item-helpers.d.ts.map

package/dist/api/item-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-helpers.d.ts","sourceRoot":"","sources":["../../src/api/item-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,OAAO,EACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,sIAMvB,CAAC;AAEb;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,oUASG,CAAC;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,UAAU;IACR,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACrG,KACA,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAMrC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,GACnB,UAAU;IACR,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9E,KACA,WAAW,CAAC,MAAM,EAAE,MAAM,CAM5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,YAAY,KACnB,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAexB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,OAAO,EACZ,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAC1C,OAQC,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,KAAK,OAAO,EACZ,QAAQ,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,SAAS;IAAE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;CAAE,KAC9C,aAOF,CAAC;AAEF,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/api/item-helpers.js

@@ -0,0 +1,139 @@
+import { UsageError } from '../utils/errors.js';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+import { projectItem, rawItemSchema, } from './item-projection.js';
+/**
+ * The `column_values { ... }` selection Monday returns under every
+ * item shape in the v0.1 read surface. Inlined as a string because
+ * Monday's GraphQL surface accepts only inline expansion at the
+ * points the v0.1 commands use it (no `fragment ... on Item`
+ * registration is necessary).
+ *
+ * Indentation matches the spots every existing consumer interpolated
+ * — keeping the rendered query bytes identical post-lift means
+ * cassettes that hash on the query text continue to match without
+ * re-recording.
+ */
+export const COLUMN_VALUES_FRAGMENT = `column_values {
+            id
+            type
+            text
+            value
+            column { title }
+          }`;
+/**
+ * The full item-shape selection — every scalar field the v0.1
+ * `cli-design.md` §6.2 contract surfaces, plus the
+ * `COLUMN_VALUES_FRAGMENT` expansion. Used by `item get` / `list` /
+ * `find` / `search` / `subitems` and by the M5a dry-run engine.
+ *
+ * Indentation lands at the column the hand-rolled queries used so
+ * cassette / query-text diffs stay clean post-lift.
+ */
+export const ITEM_FIELDS_FRAGMENT = `id
+          name
+          state
+          url
+          created_at
+          updated_at
+          board { id }
+          group { id title }
+          parent_item { id }
+          ${COLUMN_VALUES_FRAGMENT}`;
+/**
+ * Builds the `meta.columns` consolidation slot per `cli-design.md`
+ * §6.3 from board metadata. Same shape every collection-list
+ * command emits — the per-row `title` lands in the consolidated
+ * map, so per-cell title repeats drop from each row.
+ *
+ * Pure / synchronous; no I/O.
+ */
+export const collectColumnHeads = (metadata) => {
+    const out = {};
+    for (const c of metadata.columns) {
+        out[c.id] = { id: c.id, type: c.type, title: c.title };
+    }
+    return out;
+};
+/**
+ * Builds a title-by-id map for the `projectItem` projector — the
+ * canonical fallback when `column.title` on the wire could drift
+ * (M3 metadata loader's NFC + cache rules are the source of truth).
+ *
+ * Pure / synchronous; no I/O.
+ */
+export const titleMap = (metadata) => {
+    const out = new Map();
+    for (const c of metadata.columns) {
+        out.set(c.id, c.title);
+    }
+    return out;
+};
+/**
+ * Builds the `me`-token resolver every people-aware filter / search
+ * command needs. The factory closes over the client; the returned
+ * function fires `client.whoami()` on demand. Callers memo-cache the
+ * resolved ID per build call to keep `--where Owner=me` cheap.
+ *
+ * Throws `UsageError` when the token is not associated with a
+ * Monday user (guest token, etc.). Defensive — the transport layer
+ * surfaces token-association failures as `unauthorized` before this
+ * resolver runs.
+ */
+export const resolveMeFactory = (client) => {
+    return async () => {
+        const response = await client.whoami();
+        const me = response.data.me;
+        /* c8 ignore next 5 — defensive: Monday's me field is null only
+           when the token is invalid / belongs to a guest, which the
+           transport layer surfaces as `unauthorized` before this
+           resolver runs. The guard exists for type narrowing. */
+        if (me === null) {
+            throw new UsageError('cannot resolve `me` — token is not associated with a Monday user');
+        }
+        return me.id;
+    };
+};
+/**
+ * Parses a raw GraphQL item-shape into a `RawItem` with the R18
+ * parse-boundary wrap: malformed payloads surface as
+ * `ApiError(internal_error)` with `details.issues` rather than a
+ * bare ZodError that loses the failing field path.
+ *
+ * Per `validation.md` "Never bubble raw ZodError out of a parse
+ * boundary". Mirrors the dry-run engine's per-id wrap (`api/dry-
+ * run.ts fetchItem`) and `userByEmail` (`api/resolvers.ts`) — same
+ * pattern across every parse boundary.
+ *
+ * Optional `details` are merged into the error envelope (e.g.
+ * `{ item_id: '123' }`) so consumers in `item get` / `find` /
+ * `subitems` can scope the failure to the specific item being
+ * parsed.
+ */
+export const parseRawItem = (raw, details) => unwrapOrThrow(rawItemSchema.safeParse(raw), {
+    context: 'Monday returned a malformed item response',
+    ...(details === undefined ? {} : { details }),
+    hint: 'this is a data-integrity error in Monday\'s response (or a ' +
+        'rawItemSchema drift); verify the response shape and update ' +
+        'the schema if Monday\'s contract has changed.',
+});
+/**
+ * Parses one raw GraphQL item-shape and projects it into the §6.2 /
+ * §6.3 `ProjectedItem`. A thin wrapper around
+ * `parseRawItem + projectItem` so the collection commands (`list`,
+ * `search`) spell the same call once.
+ *
+ * `omitColumnTitles: true` is the §6.3 same-board-collection rule —
+ * per-cell `title` drops out of each column entry (consolidated
+ * into `meta.columns`). Single-resource paths (`item get`) skip
+ * this helper because they keep titles inline (`item-projection.ts`
+ * `projectItem` directly).
+ */
+export const projectFromRaw = (raw, titles, options) => {
+    const parsed = parseRawItem(raw);
+    return projectItem({
+        raw: parsed,
+        columnTitles: titles,
+        omitColumnTitles: options.omitColumnTitles,
+    });
+};
+//# sourceMappingURL=item-helpers.js.map

package/dist/api/item-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-helpers.js","sourceRoot":"","sources":["../../src/api/item-helpers.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,GAGd,MAAM,sBAAsB,CAAC;AAG9B;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;YAM1B,CAAC;AAEb;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;YASxB,sBAAsB,EAAE,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,QAEC,EACqC,EAAE;IACxC,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACjC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,QAEC,EAC4B,EAAE;IAC/B,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACjC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,MAAoB,EACK,EAAE;IAC3B,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QACvC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B;;;iEAGyD;QACzD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAChB,MAAM,IAAI,UAAU,CAClB,kEAAkE,CACnE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,GAAY,EACZ,OAA2C,EAClC,EAAE,CACX,aAAa,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;IAC1C,OAAO,EAAE,2CAA2C;IACpD,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;IAC7C,IAAI,EACF,6DAA6D;QAC7D,6DAA6D;QAC7D,+CAA+C;CAClD,CAAC,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,GAAY,EACZ,MAAmC,EACnC,OAA+C,EAChC,EAAE;IACjB,MAAM,MAAM,GAAY,YAAY,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,WAAW,CAAC;QACjB,GAAG,EAAE,MAAM;QACX,YAAY,EAAE,MAAM;QACpB,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/api/item-mutation-result.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Live-mutation null-result projection — every item-shaped mutation
+ * (M5b's `change_simple_column_value` / `change_column_value` /
+ * `change_multiple_column_values` plus M10's `archive_item` /
+ * `delete_item` / `duplicate_item`) returns the post-mutation `Item`
+ * directly, and every consumer guards against a null result with the
+ * same shape: a typed throw carrying `details.item_id`, then
+ * `parseRawItem + projectItem` to surface the §6.4 mutation
+ * envelope's `data: <projected snapshot>`.
+ *
+ * Lifted from six sites — see v0.2-plan §14 R28:
+ *   - `commands/item/set.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/clear.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/update.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/archive.ts` (M10 — inline)
+ *   - `commands/item/delete.ts` (M10 — inline)
+ *   - `commands/item/duplicate.ts` (M10 — inline)
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** The two
+ * cohorts diverge in error semantics. M5b chose `internal_error` with
+ * "Monday returned no item payload from the mutation for id ..."
+ * (the mutation succeeded server-side but Monday returned an empty
+ * payload — server-side glitch, abnormal). M10 chose `not_found` with
+ * "Monday returned no item from <op_name> for id ..." (Monday's
+ * idiomatic null-for-missing-or-no-access response — a typed agent-
+ * recovery story). Both are correct for their semantics, both are
+ * pinned by integration tests, and both must survive the lift
+ * byte-for-byte. The helper owns the boilerplate (null check,
+ * `details: { item_id }` envelope, `parseRawItem + projectItem` chain);
+ * each call site supplies its own typed error parts.
+ *
+ * **What stays at the call site.** The post-projection error
+ * decoration (resolver-warning fold, validation_failed → column_
+ * archived remap, bulk `applied_count` / `applied_to` /
+ * `failed_at_item` attachment in update.ts's bulk path) lives at the
+ * call site. The helper's null-throw bubbles into the surrounding
+ * try/catch unchanged; callers compose the helper with their own
+ * `foldAndRemap` arms exactly as before. M11's `item move` + M14/M15
+ * board archive / delete will inherit this seam too.
+ */
+import { type ErrorCode } from '../utils/errors.js';
+import { type ProjectedItem } from './item-projection.js';
+/**
+ * Parses + projects a live-mutation `Item` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code +
+ * message so M5b's `internal_error` / "no item payload" and M10's
+ * `not_found` / "no item from <op_name>" both survive the lift
+ * byte-for-byte.
+ *
+ * `details: { item_id }` is supplied by the helper so every consumer
+ * carries the same envelope shape — agents key off `details.item_id`
+ * regardless of which verb threw (cli-design §6.5).
+ */
+export declare const projectMutationItem: ({ raw, itemId, errorCode, errorMessage, }: {
+    readonly raw: unknown;
+    readonly itemId: string;
+    readonly errorCode: ErrorCode;
+    readonly errorMessage: string;
+}) => ProjectedItem;
+//# sourceMappingURL=item-mutation-result.d.ts.map

package/dist/api/item-mutation-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-mutation-result.d.ts","sourceRoot":"","sources":["../../src/api/item-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,2CAKjC;IACD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,KAAG,aAOH,CAAC"}

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

@@ -0,0 +1,63 @@
+/**
+ * Live-mutation null-result projection — every item-shaped mutation
+ * (M5b's `change_simple_column_value` / `change_column_value` /
+ * `change_multiple_column_values` plus M10's `archive_item` /
+ * `delete_item` / `duplicate_item`) returns the post-mutation `Item`
+ * directly, and every consumer guards against a null result with the
+ * same shape: a typed throw carrying `details.item_id`, then
+ * `parseRawItem + projectItem` to surface the §6.4 mutation
+ * envelope's `data: <projected snapshot>`.
+ *
+ * Lifted from six sites — see v0.2-plan §14 R28:
+ *   - `commands/item/set.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/clear.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/update.ts` (M5b — local `projectMutationItem`)
+ *   - `commands/item/archive.ts` (M10 — inline)
+ *   - `commands/item/delete.ts` (M10 — inline)
+ *   - `commands/item/duplicate.ts` (M10 — inline)
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** The two
+ * cohorts diverge in error semantics. M5b chose `internal_error` with
+ * "Monday returned no item payload from the mutation for id ..."
+ * (the mutation succeeded server-side but Monday returned an empty
+ * payload — server-side glitch, abnormal). M10 chose `not_found` with
+ * "Monday returned no item from <op_name> for id ..." (Monday's
+ * idiomatic null-for-missing-or-no-access response — a typed agent-
+ * recovery story). Both are correct for their semantics, both are
+ * pinned by integration tests, and both must survive the lift
+ * byte-for-byte. The helper owns the boilerplate (null check,
+ * `details: { item_id }` envelope, `parseRawItem + projectItem` chain);
+ * each call site supplies its own typed error parts.
+ *
+ * **What stays at the call site.** The post-projection error
+ * decoration (resolver-warning fold, validation_failed → column_
+ * archived remap, bulk `applied_count` / `applied_to` /
+ * `failed_at_item` attachment in update.ts's bulk path) lives at the
+ * call site. The helper's null-throw bubbles into the surrounding
+ * try/catch unchanged; callers compose the helper with their own
+ * `foldAndRemap` arms exactly as before. M11's `item move` + M14/M15
+ * board archive / delete will inherit this seam too.
+ */
+import { ApiError } from '../utils/errors.js';
+import { parseRawItem } from './item-helpers.js';
+import { projectItem } from './item-projection.js';
+/**
+ * Parses + projects a live-mutation `Item` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code +
+ * message so M5b's `internal_error` / "no item payload" and M10's
+ * `not_found` / "no item from <op_name>" both survive the lift
+ * byte-for-byte.
+ *
+ * `details: { item_id }` is supplied by the helper so every consumer
+ * carries the same envelope shape — agents key off `details.item_id`
+ * regardless of which verb threw (cli-design §6.5).
+ */
+export const projectMutationItem = ({ raw, itemId, errorCode, errorMessage, }) => {
+    if (raw === null || raw === undefined) {
+        throw new ApiError(errorCode, errorMessage, {
+            details: { item_id: itemId },
+        });
+    }
+    return projectItem({ raw: parseRawItem(raw, { item_id: itemId }) });
+};
+//# sourceMappingURL=item-mutation-result.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"item-mutation-result.js","sourceRoot":"","sources":["../../src/api/item-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,QAAQ,EAAkB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAsB,MAAM,sBAAsB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,EAClC,GAAG,EACH,MAAM,EACN,SAAS,EACT,YAAY,GAMb,EAAiB,EAAE;IAClB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE;YAC1C,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;SAC7B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,WAAW,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC,CAAC"}

package/dist/api/item-projection.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Shared item projection helpers (`v0.1-plan.md` §3 M4,
+ * `cli-design.md` §6.2).
+ *
+ * Every M4 read command (`item get` / `list` / `find` / `search` /
+ * `subitems`) emits the same single-resource Item shape. Centralising
+ * here means the projection lives in one file and the per-command
+ * action body stays focused on the GraphQL call + envelope mapping.
+ *
+ * Column-value projection notes:
+ *
+ *   - Each column carries `{id, type, title, text, value}` per §6.2.
+ *     `value` is the *parsed* JSON Monday stored — Monday returns it
+ *     as a JSON-encoded string on the wire and we decode at this
+ *     boundary so JSON consumers can read structured payloads
+ *     without re-parsing.
+ *   - For known-write column types (status / date / people), a
+ *     handful of *typed* fields are surfaced inline (matching the
+ *     §6.2 worked example). Unknown / read-only types only carry
+ *     the base shape; agents inspect `value` for structured access.
+ *   - The richer per-type projection is deferred to M5a's
+ *     `column-values.ts` (the writer needs the same shape and the
+ *     reader can reuse it). Until then, this module hosts the
+ *     read-only inline projection so the v0.1 contract surface is
+ *     stable.
+ */
+import { z } from 'zod';
+export declare const rawColumnValueSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    text: z.ZodNullable<z.ZodString>;
+    value: z.ZodNullable<z.ZodString>;
+    column: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        title: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strict>;
+export type RawColumnValue = z.infer<typeof rawColumnValueSchema>;
+export declare const rawItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    state: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    board: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    group: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    parent_item: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    creator_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    column_values: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        text: z.ZodNullable<z.ZodString>;
+        value: z.ZodNullable<z.ZodString>;
+        column: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            title: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RawItem = z.infer<typeof rawItemSchema>;
+/**
+ * Single-column projected shape per §6.2. Carries the base shape
+ * (`id, type, title, text, value`) plus a few typed fields for the
+ * v0.1-writable status / date / people types. Mirror / formula /
+ * dependency columns surface as the base shape — `text` is the
+ * source of truth there because the typed payload isn't writable
+ * and Monday's wire shape varies.
+ */
+export declare const projectedColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodNullable<z.ZodString>;
+    value: z.ZodUnknown;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    index: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    time: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    people: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type ProjectedColumn = z.infer<typeof projectedColumnSchema>;
+export declare const projectedItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    board_id: z.ZodNullable<z.ZodString>;
+    group_id: z.ZodNullable<z.ZodString>;
+    parent_item_id: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    columns: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        text: z.ZodNullable<z.ZodString>;
+        value: z.ZodUnknown;
+        label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        index: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        time: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        people: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$strict>;
+export type ProjectedItem = z.infer<typeof projectedItemSchema>;
+/**
+ * Parses a Monday `value` string. Monday encodes structured column
+ * values as JSON strings; the projector decodes once at the boundary
+ * so consumers can read the structured field without re-parsing.
+ *
+ * Errors are swallowed: a malformed JSON string surfaces as `null`
+ * (with `text` still carrying the human form). Defensive — Monday
+ * occasionally returns an unparseable string for read-only column
+ * types, and we don't want one weird column to fail the whole emit.
+ */
+export declare const parseColumnValue: (raw: string | null) => unknown;
+/**
+ * Projects one column-value into the §6.2 shape. Pure — no I/O.
+ * The board-metadata `title` is preferred over the wire-side
+ * `column.title` because the metadata loader's NFC + cache rules
+ * are the canonical source; `column.title` is only the fallback for
+ * cross-board lists where a single board metadata isn't loaded.
+ */
+export declare const projectColumnValue: (raw: RawColumnValue, fallbackTitle: string | undefined) => ProjectedColumn;
+/**
+ * Reads `id` off a raw GraphQL item shape — the cursor walker
+ * needs a string for the per-page sort. Production cassettes always
+ * carry a string id (Monday's schema guarantees it); the
+ * structural-typing read keeps the walker honest if a future
+ * fixture drifts.
+ */
+export declare const idFromRawItem: (item: unknown) => string;
+export interface ProjectItemInputs {
+    readonly raw: RawItem;
+    /**
+     * Per-board column titles, keyed by column ID. When supplied, the
+     * projector uses these in preference to the wire-side
+     * `column.title` (per §6.3 — the per-board view is canonical).
+     * Cross-board lists (`item find` walking multiple boards in
+     * theory) leave this undefined and fall back to the wire title.
+     */
+    readonly columnTitles?: ReadonlyMap<string, string>;
+    /**
+     * §6.3 title de-duplication for same-board collections. When
+     * `true`, per-cell `title` is dropped from each column-value
+     * payload — the caller carries the canonical titles in
+     * `meta.columns` instead. Default `false` so single-resource calls
+     * (`item get`) keep titles inline (§6.2).
+     */
+    readonly omitColumnTitles?: boolean;
+}
+export declare const projectItem: (inputs: ProjectItemInputs) => ProjectedItem;
+//# sourceMappingURL=item-projection.d.ts.map

package/dist/api/item-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-projection.d.ts","sourceRoot":"","sources":["../../src/api/item-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,oBAAoB;;;;;;;;kBAWtB,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoBf,CAAC;AAEZ,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBA0BxB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;kBAarB,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,GAAG,IAAI,KAAG,OAOrD,CAAC;AAsCF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,cAAc,EACnB,eAAe,MAAM,GAAG,SAAS,KAChC,eAqBF,CAAC;AAEF;;;;;;GAMG;AAIH,eAAO,MAAM,aAAa,GAAI,MAAM,OAAO,KAAG,MAI7C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,eAAO,MAAM,WAAW,GAAI,QAAQ,iBAAiB,KAAG,aA0BvD,CAAC"}