monday-cli 0.2.0

package/dist/api/board-mutation-invalidation.js

@@ -0,0 +1,136 @@
+/**
+ * Eager-invalidation post-success projection wrappers for board-
+ * structure mutations (`v0.2-plan.md` §22 R46 lift).
+ *
+ * Lifts the cli-design §8 eager-invalidation timing rule from six
+ * inline call sites into two helpers that pin the timing in the
+ * type system. The §8 contract splits by leg-count:
+ *
+ *   - **Single-leg verbs** (`column-create` / `column-delete` +
+ *     M15-retrofit `board archive` / `board delete`). Invalidate
+ *     AFTER the success envelope's `data` projection completes,
+ *     never before the wire mutation, never between mutation and
+ *     projection. Skip on the error path — a failed single-leg
+ *     call didn't change board state.
+ *   - **Fan-out verbs** (`column-update` per-attribute +
+ *     M15-retrofit `board update` per-attribute). Issue all per-
+ *     attribute wire calls first; AFTER the loop ends, invalidate
+ *     IF at least one per-attribute call succeeded (the wire-
+ *     state high-water mark). On whole-call success this is the
+ *     same trigger as the single-leg case (every leg succeeded);
+ *     on whole-call partial-application failure (call N+1 fails
+ *     after call N succeeded) invalidation still fires because
+ *     the cache must reflect partially-applied server state.
+ *     Zero-legs-succeeded skips invalidation — server state didn't
+ *     change.
+ *
+ * Both helpers order invalidation BEFORE returning so the consumer's
+ * `emitMutation` lands AFTER the cache is invalidated; a cache-unlink
+ * failure (permission flip, disk loss) surfaces through the runner's
+ * catch-all error envelope rather than double-emitting after a
+ * success envelope already hit stdout (Codex M16 round-1 F1 ordering
+ * pin).
+ *
+ * **Why a `recordLegSuccess()` callback rather than a returned
+ * `{succeededLegs, ...}` object** (the §22 R46 spec's draft shape).
+ * The fan-out's high-water-mark counter MUST survive a thrown
+ * `runFanOut` — if the closure throws partway through the loop,
+ * the helper still needs to know how many legs landed before the
+ * throw to decide on partial-application invalidation. Returning
+ * the counter would force every consumer to wrap its own
+ * try/catch to push the count out before re-throwing; routing it
+ * through a closure-captured callback owned by the helper hides
+ * the counter from the consumer's data flow entirely. The
+ * consumer just calls `recordLegSuccess()` after each successful
+ * leg; the helper owns the counter, the catch boundary, and the
+ * §8 invalidation gate.
+ *
+ * **Why a single `perform` callback for single-leg rather than a
+ * split `{runMutation, projectData}` (the §22 R46 spec draft).**
+ * Splitting "fire the wire call" from "project the response" was
+ * artificial in practice — the missing-root-key check + null-
+ * payload guard sit between the two and don't belong cleanly to
+ * either side. A single callback that owns wire-call + parse +
+ * missing-root + projection lets each consumer keep its existing
+ * structure, returning whatever shape it needs (typically
+ * `{data, response}` so `emitMutation` can take both `data` and
+ * `toEmit(response)` post-helper).
+ *
+ * **Six consumer sites (4 single-leg + 2 fan-out):**
+ *   - `commands/board/column-create.ts` — single-leg.
+ *   - `commands/board/column-delete.ts` — single-leg.
+ *   - `commands/board/archive.ts` — single-leg (M15 retrofit).
+ *   - `commands/board/delete.ts` — single-leg (M15 retrofit).
+ *   - `commands/board/column-update.ts` — fan-out (per-attribute
+ *     across two wire surfaces; trailing per-attribute response
+ *     is authoritative).
+ *   - `commands/board/update.ts` — fan-out (M15 retrofit; per-
+ *     attribute loop + final force-live read; final-read response
+ *     is authoritative). The `runFanOut` closure wraps loop +
+ *     final read + projection so a final-read failure with
+ *     succeededLegs > 0 still triggers invalidation per §8.
+ *
+ * **M17 trajectory.** The §8 contract is leg-count-shaped, not
+ * noun-shaped — M17's five group verbs (`group-create` /
+ * `group-update` / `group-archive` / `group-duplicate` /
+ * `group-delete`) adopt the helpers verbatim from day one
+ * (mirrors R29's M14-close-then-M15-adopts pattern). Site count
+ * projects to 9 by M17 close (4 + 5), well above the typical
+ * 3-consumer trigger threshold.
+ */
+import { invalidateBoard } from './cache.js';
+/**
+ * Single-leg eager-invalidation wrapper per cli-design §8. Runs
+ * `perform()` to completion, then calls `invalidateBoard(boardId,
+ * env)` before returning the perform result. On the error path
+ * (perform throws) invalidation is skipped — bypass-by-throw is
+ * the timing contract: a failed single-leg call didn't change
+ * server state, so the cache stays valid.
+ */
+export const withBoardInvalidationSingleLeg = async ({ boardId, env, perform, }) => {
+    const result = await perform();
+    await invalidateBoard(boardId, env);
+    return result;
+};
+/**
+ * Fan-out eager-invalidation wrapper per cli-design §8. Runs
+ * `runFanOut(tracker)` and applies the high-water-mark rule:
+ *
+ *   - Whole-call success → invalidate iff any leg succeeded
+ *     (recordLegSuccess called at least once); return the result.
+ *   - Whole-call partial-application failure → catch the throw;
+ *     invalidate iff any leg succeeded; re-throw.
+ *   - Whole-call zero-legs-succeeded failure (the very first leg
+ *     threw before recordLegSuccess fired) → skip invalidation;
+ *     re-throw. Server state didn't change, so the cache stays
+ *     valid.
+ *
+ * The counter lives in this helper's closure — `runFanOut` cannot
+ * read or write it directly, only signal increments via
+ * `tracker.recordLegSuccess()`. This pins the §8 contract in the
+ * type system (the consumer can't accidentally invalidate before
+ * the wire call or skip invalidation on partial-application
+ * failure).
+ */
+export const withBoardInvalidationFanOut = async ({ boardId, env, runFanOut, }) => {
+    let succeededLegs = 0;
+    const tracker = {
+        recordLegSuccess: () => {
+            succeededLegs += 1;
+        },
+    };
+    try {
+        const result = await runFanOut(tracker);
+        if (succeededLegs > 0) {
+            await invalidateBoard(boardId, env);
+        }
+        return result;
+    }
+    catch (err) {
+        if (succeededLegs > 0) {
+            await invalidateBoard(boardId, env);
+        }
+        throw err;
+    }
+};
+//# sourceMappingURL=board-mutation-invalidation.js.map

package/dist/api/board-mutation-invalidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-mutation-invalidation.js","sourceRoot":"","sources":["../../src/api/board-mutation-invalidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA+B7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,EAAK,EACtD,OAAO,EACP,GAAG,EACH,OAAO,GACiC,EAAc,EAAE;IACxD,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC;IAC/B,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAkBF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,EAAK,EACnD,OAAO,EACP,GAAG,EACH,SAAS,GAC4B,EAAc,EAAE;IACrD,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,MAAM,OAAO,GAAuB;QAClC,gBAAgB,EAAE,GAAG,EAAE;YACrB,aAAa,IAAI,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC,CAAC"}

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

@@ -0,0 +1,97 @@
+/**
+ * Live-mutation null-result projection for the M15 board lifecycle
+ * cluster (`v0.2-plan.md` §22 R43 lift). Five verbs share a near-
+ * verbatim shape: null-check the wire payload, throw a typed
+ * ApiError on null carrying `details.board_id` (or `details.
+ * board_name` for create), then parse through `boardProjection
+ * Schema` to surface the §6.4 mutation envelope's
+ * `data: <projected snapshot>`.
+ *
+ * Lifted from five sites — see v0.2-plan §22 R43:
+ *   - `commands/board/create.ts` (M15 — local `projectCreatedBoard`,
+ *     `errorCode: 'internal_error'`, `detailKey: 'board_name'`).
+ *   - `commands/board/archive.ts` (M15 — local
+ *     `projectArchivedBoard`, `errorCode: 'not_found'`,
+ *     `detailKey: 'board_id'`).
+ *   - `commands/board/delete.ts` (M15 — local `projectDeletedBoard`,
+ *     `errorCode: 'not_found'`, `detailKey: 'board_id'`).
+ *   - `commands/board/update.ts` (M15 — inline final-read parse,
+ *     `errorCode: 'internal_error'` for the defensive empty-`boards`
+ *     guard).
+ *   - `commands/board/duplicate.ts` (M15 — inline wrapped-board
+ *     parse, `errorCode: 'internal_error'` for the inner-board
+ *     null guard; the outer `BoardDuplication { board, is_async }`
+ *     wrapper parse stays at the call site since R43 only covers
+ *     the inner-board projection, not the wrapped-envelope shape
+ *     unique to duplicate).
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** The five
+ * sites diverge in error semantics. Create (every successful call
+ * returns a Board) + update's defensive final-read guard +
+ * duplicate's inner-board guard chose `internal_error` (the
+ * mutation succeeded server-side but Monday returned an empty
+ * payload — server-side glitch, abnormal). Archive + delete chose
+ * `not_found` (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
+ * (`tests/integration/commands/board.test.ts` asserts on
+ * `error.code`), and both must survive the lift byte-for-byte.
+ * The helper owns the boilerplate (null check, `details: {
+ * [detailKey]: detailValue }` envelope, the `unwrapOrThrow`
+ * schema parse); each call site supplies its own typed error parts.
+ *
+ * **Why `detailKey` is parameterised.** Create's mutation runs
+ * before the new board has an id, so the typed-error envelope
+ * carries `details.board_name` (the agent-supplied name) instead.
+ * Every other verb operates on an existing `boardId` and carries
+ * `details.board_id`. Mirrors R28's `projectMutationItem` keying
+ * on `details.item_id` uniformly because every item-mutation
+ * surface knows the id ahead of the call.
+ *
+ * **Mirrors R28** (`projectMutationItem` in
+ * `src/api/item-mutation-result.ts`, four consumers) and **R37**
+ * (`projectMutationUpdate` in `src/api/update-mutation-result.ts`,
+ * five consumers) — both per-noun helpers landed at the same 4–5
+ * consumer trigger. R43 ships the third per-noun helper at the
+ * same threshold.
+ *
+ * **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_board` / `archive_board` / etc.) 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 { type ErrorCode } from '../utils/errors.js';
+import { type BoardProjection } from './board-projection.js';
+export type BoardMutationDetailKey = 'board_id' | 'board_name';
+export interface ProjectMutationBoardInputs {
+    readonly raw: unknown;
+    readonly errorCode: ErrorCode;
+    /** Full caller-formatted message for the null-payload throw —
+     * e.g. `"Monday returned no board payload from archive_board for
+     * id 12345"`. Per-verb phrasing is preserved verbatim because
+     * agents key off the message text in error logs. */
+    readonly errorMessage: string;
+    readonly detailKey: BoardMutationDetailKey;
+    readonly detailValue: string;
+}
+/**
+ * Parses + projects a live-mutation `Board` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code +
+ * message so create's `internal_error` / "no board payload from
+ * create_board for name <X>" and archive/delete's `not_found` /
+ * "no board payload from <op> for id <X>" both survive the lift
+ * byte-for-byte.
+ *
+ * `details: { [detailKey]: detailValue }` is supplied by the
+ * helper so every consumer carries the same envelope shape — agents
+ * key off `details.board_id` (or `details.board_name` on create's
+ * pre-id path) regardless of which verb threw (cli-design §6.5).
+ */
+export declare const projectMutationBoard: ({ raw, errorCode, errorMessage, detailKey, detailValue, }: ProjectMutationBoardInputs) => BoardProjection;
+//# sourceMappingURL=board-mutation-result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board-mutation-result.d.ts","sourceRoot":"","sources":["../../src/api/board-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEpF,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,YAAY,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;wDAGoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,2DAMlC,0BAA0B,KAAG,eAc/B,CAAC"}

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

@@ -0,0 +1,99 @@
+/**
+ * Live-mutation null-result projection for the M15 board lifecycle
+ * cluster (`v0.2-plan.md` §22 R43 lift). Five verbs share a near-
+ * verbatim shape: null-check the wire payload, throw a typed
+ * ApiError on null carrying `details.board_id` (or `details.
+ * board_name` for create), then parse through `boardProjection
+ * Schema` to surface the §6.4 mutation envelope's
+ * `data: <projected snapshot>`.
+ *
+ * Lifted from five sites — see v0.2-plan §22 R43:
+ *   - `commands/board/create.ts` (M15 — local `projectCreatedBoard`,
+ *     `errorCode: 'internal_error'`, `detailKey: 'board_name'`).
+ *   - `commands/board/archive.ts` (M15 — local
+ *     `projectArchivedBoard`, `errorCode: 'not_found'`,
+ *     `detailKey: 'board_id'`).
+ *   - `commands/board/delete.ts` (M15 — local `projectDeletedBoard`,
+ *     `errorCode: 'not_found'`, `detailKey: 'board_id'`).
+ *   - `commands/board/update.ts` (M15 — inline final-read parse,
+ *     `errorCode: 'internal_error'` for the defensive empty-`boards`
+ *     guard).
+ *   - `commands/board/duplicate.ts` (M15 — inline wrapped-board
+ *     parse, `errorCode: 'internal_error'` for the inner-board
+ *     null guard; the outer `BoardDuplication { board, is_async }`
+ *     wrapper parse stays at the call site since R43 only covers
+ *     the inner-board projection, not the wrapped-envelope shape
+ *     unique to duplicate).
+ *
+ * **Why parameterised on `errorCode` + `errorMessage`.** The five
+ * sites diverge in error semantics. Create (every successful call
+ * returns a Board) + update's defensive final-read guard +
+ * duplicate's inner-board guard chose `internal_error` (the
+ * mutation succeeded server-side but Monday returned an empty
+ * payload — server-side glitch, abnormal). Archive + delete chose
+ * `not_found` (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
+ * (`tests/integration/commands/board.test.ts` asserts on
+ * `error.code`), and both must survive the lift byte-for-byte.
+ * The helper owns the boilerplate (null check, `details: {
+ * [detailKey]: detailValue }` envelope, the `unwrapOrThrow`
+ * schema parse); each call site supplies its own typed error parts.
+ *
+ * **Why `detailKey` is parameterised.** Create's mutation runs
+ * before the new board has an id, so the typed-error envelope
+ * carries `details.board_name` (the agent-supplied name) instead.
+ * Every other verb operates on an existing `boardId` and carries
+ * `details.board_id`. Mirrors R28's `projectMutationItem` keying
+ * on `details.item_id` uniformly because every item-mutation
+ * surface knows the id ahead of the call.
+ *
+ * **Mirrors R28** (`projectMutationItem` in
+ * `src/api/item-mutation-result.ts`, four consumers) and **R37**
+ * (`projectMutationUpdate` in `src/api/update-mutation-result.ts`,
+ * five consumers) — both per-noun helpers landed at the same 4–5
+ * consumer trigger. R43 ships the third per-noun helper at the
+ * same threshold.
+ *
+ * **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_board` / `archive_board` / etc.) 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 { ApiError } from '../utils/errors.js';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+import { boardProjectionSchema } from './board-projection.js';
+/**
+ * Parses + projects a live-mutation `Board` payload, throwing the
+ * supplied typed error on null/undefined. Caller owns the error code +
+ * message so create's `internal_error` / "no board payload from
+ * create_board for name <X>" and archive/delete's `not_found` /
+ * "no board payload from <op> for id <X>" both survive the lift
+ * byte-for-byte.
+ *
+ * `details: { [detailKey]: detailValue }` is supplied by the
+ * helper so every consumer carries the same envelope shape — agents
+ * key off `details.board_id` (or `details.board_name` on create's
+ * pre-id path) regardless of which verb threw (cli-design §6.5).
+ */
+export const projectMutationBoard = ({ raw, errorCode, errorMessage, detailKey, detailValue, }) => {
+    if (raw === null || raw === undefined) {
+        throw new ApiError(errorCode, errorMessage, {
+            details: { [detailKey]: detailValue },
+        });
+    }
+    const subjectPhrase = detailKey === 'board_name'
+        ? `name ${JSON.stringify(detailValue)}`
+        : `id ${detailValue}`;
+    return unwrapOrThrow(boardProjectionSchema.safeParse(raw), {
+        context: `Monday returned a malformed board payload for ${subjectPhrase}`,
+        details: { [detailKey]: detailValue },
+    });
+};
+//# sourceMappingURL=board-mutation-result.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board-mutation-result.js","sourceRoot":"","sources":["../../src/api/board-mutation-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,OAAO,EAAE,QAAQ,EAAkB,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAwB,MAAM,uBAAuB,CAAC;AAgBpF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,EACnC,GAAG,EACH,SAAS,EACT,YAAY,EACZ,SAAS,EACT,WAAW,GACgB,EAAmB,EAAE;IAChD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,IAAI,QAAQ,CAAC,SAAS,EAAE,YAAY,EAAE;YAC1C,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,aAAa,GACjB,SAAS,KAAK,YAAY;QACxB,CAAC,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE;QACvC,CAAC,CAAC,MAAM,WAAW,EAAE,CAAC;IAC1B,OAAO,aAAa,CAAC,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE;QACzD,OAAO,EAAE,iDAAiD,aAAa,EAAE;QACzE,OAAO,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,WAAW,EAAE;KACtC,CAAC,CAAC;AACL,CAAC,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * Board projection schema + GraphQL field-fragment for the M15 board
+ * lifecycle cluster (`v0.2-plan.md` §3 M15, mirrors R39's
+ * workspace-projection lift).
+ *
+ * **`BOARD_FIELDS_FRAGMENT`.** The shared GraphQL selection set
+ * every M15 board-shape verb uses. `board create` / `update` /
+ * `archive` / `duplicate` all return the full Board projection;
+ * `update`'s preflight read uses the same fragment too. Five of
+ * the M15 cluster's GraphQL strings interpolate this fragment.
+ * 6-space continuation indent matches the column every consumer
+ * interpolates `${BOARD_FIELDS_FRAGMENT}` at, so rendered query
+ * bytes stay stable across consumers. Mirrors
+ * `WORKSPACE_FIELDS_FRAGMENT` (R39 workspace-projection lift) and
+ * `ITEM_FIELDS_FRAGMENT` (M5b item-helpers lift).
+ *
+ * **`boardProjectionSchema`.** The matching strict zod projection
+ * schema. The field set matches `board/get.ts`'s
+ * `boardGetOutputSchema` so a successful `board create` /
+ * `update` / `duplicate` returns the exact JSON shape a follow-
+ * up `board get <bid>` would return — agents see one canonical
+ * Board shape across read and mutation envelopes. `board get`
+ * itself migrates to this fragment + schema in this M15 commit
+ * so the projection stays single-sourced from day one (the same
+ * R39-pattern bundling the §22 recommendation calls out: ship
+ * the projection helper alongside the first new mutation rather
+ * than as a follow-up R-class).
+ *
+ * **Distinct from `boardMetadataSchema`.** `board describe` /
+ * column-resolution paths use the heavier `boardMetadataSchema`
+ * in `api/board-metadata.ts` (carries `groups: [...]` and
+ * `columns: [...]`). The lifecycle cluster doesn't need those
+ * arrays — `board describe` stays the documented path for
+ * column / group inspection, and the cache layer in
+ * board-metadata is kept untouched by M15 (the eager-
+ * invalidation contract that ties post-mutation cache state to
+ * the metadata cache is M16's scope).
+ */
+import { z } from 'zod';
+/**
+ * Shared GraphQL selection set for the M15 board lifecycle
+ * projection. 6-space continuation indent matches the column
+ * every consumer interpolates `${BOARD_FIELDS_FRAGMENT}` at, so
+ * rendered query bytes are unchanged post-lift.
+ */
+export declare const BOARD_FIELDS_FRAGMENT = "id\n      name\n      description\n      state\n      board_kind\n      board_folder_id\n      workspace_id\n      url\n      items_count\n      updated_at\n      permissions";
+/**
+ * Strict zod schema for the board projection — the exact shape
+ * `BOARD_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * `board get` / `create` / `update` / `archive` / `duplicate`;
+ * each verb's `CommandModule.outputSchema` aliases this so the
+ * schema-export pipeline emits one canonical shape.
+ */
+export declare const boardProjectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    board_kind: z.ZodNullable<z.ZodString>;
+    board_folder_id: z.ZodNullable<z.ZodString>;
+    workspace_id: z.ZodNullable<z.ZodString>;
+    url: z.ZodNullable<z.ZodString>;
+    items_count: z.ZodNullable<z.ZodNumber>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    permissions: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type BoardProjection = z.infer<typeof boardProjectionSchema>;
+//# sourceMappingURL=board-projection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board-projection.d.ts","sourceRoot":"","sources":["../../src/api/board-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,mLAUhB,CAAC;AAEnB;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;kBAcvB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/api/board-projection.js

@@ -0,0 +1,79 @@
+/**
+ * Board projection schema + GraphQL field-fragment for the M15 board
+ * lifecycle cluster (`v0.2-plan.md` §3 M15, mirrors R39's
+ * workspace-projection lift).
+ *
+ * **`BOARD_FIELDS_FRAGMENT`.** The shared GraphQL selection set
+ * every M15 board-shape verb uses. `board create` / `update` /
+ * `archive` / `duplicate` all return the full Board projection;
+ * `update`'s preflight read uses the same fragment too. Five of
+ * the M15 cluster's GraphQL strings interpolate this fragment.
+ * 6-space continuation indent matches the column every consumer
+ * interpolates `${BOARD_FIELDS_FRAGMENT}` at, so rendered query
+ * bytes stay stable across consumers. Mirrors
+ * `WORKSPACE_FIELDS_FRAGMENT` (R39 workspace-projection lift) and
+ * `ITEM_FIELDS_FRAGMENT` (M5b item-helpers lift).
+ *
+ * **`boardProjectionSchema`.** The matching strict zod projection
+ * schema. The field set matches `board/get.ts`'s
+ * `boardGetOutputSchema` so a successful `board create` /
+ * `update` / `duplicate` returns the exact JSON shape a follow-
+ * up `board get <bid>` would return — agents see one canonical
+ * Board shape across read and mutation envelopes. `board get`
+ * itself migrates to this fragment + schema in this M15 commit
+ * so the projection stays single-sourced from day one (the same
+ * R39-pattern bundling the §22 recommendation calls out: ship
+ * the projection helper alongside the first new mutation rather
+ * than as a follow-up R-class).
+ *
+ * **Distinct from `boardMetadataSchema`.** `board describe` /
+ * column-resolution paths use the heavier `boardMetadataSchema`
+ * in `api/board-metadata.ts` (carries `groups: [...]` and
+ * `columns: [...]`). The lifecycle cluster doesn't need those
+ * arrays — `board describe` stays the documented path for
+ * column / group inspection, and the cache layer in
+ * board-metadata is kept untouched by M15 (the eager-
+ * invalidation contract that ties post-mutation cache state to
+ * the metadata cache is M16's scope).
+ */
+import { z } from 'zod';
+/**
+ * Shared GraphQL selection set for the M15 board lifecycle
+ * projection. 6-space continuation indent matches the column
+ * every consumer interpolates `${BOARD_FIELDS_FRAGMENT}` at, so
+ * rendered query bytes are unchanged post-lift.
+ */
+export const BOARD_FIELDS_FRAGMENT = `id
+      name
+      description
+      state
+      board_kind
+      board_folder_id
+      workspace_id
+      url
+      items_count
+      updated_at
+      permissions`;
+/**
+ * Strict zod schema for the board projection — the exact shape
+ * `BOARD_FIELDS_FRAGMENT` selects from the wire. Shared by
+ * `board get` / `create` / `update` / `archive` / `duplicate`;
+ * each verb's `CommandModule.outputSchema` aliases this so the
+ * schema-export pipeline emits one canonical shape.
+ */
+export const boardProjectionSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string(),
+    description: z.string().nullable(),
+    state: z.string().nullable(),
+    board_kind: z.string().nullable(),
+    board_folder_id: z.string().nullable(),
+    workspace_id: z.string().nullable(),
+    url: z.string().nullable(),
+    items_count: z.number().int().nullable(),
+    updated_at: z.string().nullable(),
+    permissions: z.string().nullable(),
+})
+    .strict();
+//# sourceMappingURL=board-projection.js.map

package/dist/api/board-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-projection.js","sourceRoot":"","sources":["../../src/api/board-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;kBAUnB,CAAC;AAEnB;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC;KACnC,MAAM,CAAC;IACN,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACtC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACxC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/api/cache.d.ts

@@ -0,0 +1,150 @@
+export declare const CACHE_FILE_MODE = 384;
+export declare const DEFAULT_CACHE_TTL_SECONDS = 300;
+export type CacheKey = {
+    readonly kind: 'board';
+    readonly boardId: string;
+} | {
+    readonly kind: 'users';
+} | {
+    readonly kind: 'schemaVersion';
+};
+export interface CacheRootOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly home?: string;
+}
+/**
+ * Resolves the cache root per `cli-design.md` §8 and the XDG Base
+ * Directory spec. Order:
+ *  1. `$XDG_CACHE_HOME/monday-cli` when set and non-empty.
+ *  2. `<home>/.cache/monday-cli` otherwise.
+ *
+ * The return is always absolute. We don't create the directory here —
+ * `writeEntry` does that lazily so a read-only path (`cache list` on a
+ * fresh install) doesn't side-effect.
+ */
+export declare const resolveCacheRoot: (options?: CacheRootOptions) => string;
+/**
+ * Maps a typed cache key to its on-disk relative path. Centralised so
+ * every consumer (read/write/clear, plus the M1 commands) agrees on
+ * the layout.
+ */
+export declare const cacheKeyToRelativePath: (key: CacheKey) => string;
+export interface CacheReadResult<T> {
+    readonly data: T;
+    readonly ageSeconds: number;
+    readonly path: string;
+    readonly sizeBytes: number;
+}
+export interface CacheReadOptions {
+    /** Override the default 5-minute TTL. */
+    readonly ttlSeconds?: number;
+    /**
+     * Source of "now" for age calculation. Injectable so tests can
+     * advance time deterministically without `vi.useFakeTimers()`
+     * spreading into other tests.
+     */
+    readonly now?: () => Date;
+}
+/**
+ * Reads and parses a cache entry. Returns `undefined` on cache miss
+ * (file not present or expired). Throws `CacheError` on any other
+ * failure (permission too loose, malformed JSON, decode mismatch).
+ */
+export declare const readEntry: <T>(root: string, key: CacheKey, parse: (raw: unknown) => T, options?: CacheReadOptions) => Promise<CacheReadResult<T> | undefined>;
+/**
+ * Writes a cache entry atomically. Sequence:
+ *  1. Ensure the parent directory exists with mode `0700`.
+ *  2. Write to a tmp sibling with mode `0600`.
+ *  3. `rename` over the final path. Atomic on the same filesystem.
+ *
+ * On any failure the tmp file is best-effort cleaned up so a half-
+ * written `.tmp` doesn't accumulate on the next call.
+ */
+export declare const writeEntry: (root: string, key: CacheKey, data: unknown) => Promise<{
+    readonly path: string;
+    readonly sizeBytes: number;
+}>;
+export interface CacheEntryInfo {
+    readonly path: string;
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+    readonly modifiedAt: string;
+    readonly ageSeconds: number;
+    /**
+     * Best-effort kind classification. `boards`/`users`/`schema` reflect
+     * the layout in §8; an entry that doesn't match any known prefix is
+     * surfaced as `other` rather than dropped — agents see exactly what
+     * `cache clear` would remove.
+     */
+    readonly kind: 'boards' | 'users' | 'schema' | 'other';
+    readonly id: string | undefined;
+}
+interface ListOptions {
+    readonly now?: () => Date;
+}
+/**
+ * Walks the cache root and reports every JSON entry. Returns an empty
+ * array (not an error) when the root doesn't exist — `cache list` on
+ * a fresh install is a normal state, not a failure.
+ */
+export declare const listEntries: (root: string, options?: ListOptions) => Promise<readonly CacheEntryInfo[]>;
+export interface ClearResult {
+    readonly removed: number;
+    readonly bytesFreed: number;
+}
+/**
+ * Removes a single entry. Missing → no-op; reports zero removals so
+ * `cache clear --board <bid>` against an unknown board doesn't fail.
+ */
+export declare const clearEntry: (root: string, key: CacheKey) => Promise<ClearResult>;
+/**
+ * Eager invalidation of a board's metadata cache entry per
+ * `cli-design.md` §8 eager-invalidation contract (M16). Thin wrapper
+ * over `clearEntry(root, { kind: 'board', boardId })` that owns the
+ * cache-root resolution so call sites — every M16 column-mutation
+ * verb plus the M15 retrofit cluster (`board update` / `archive` /
+ * `delete`) — read as `invalidateBoard(boardId)` rather than
+ * `clearEntry(resolveCacheRoot({env}), {kind:'board',boardId})`.
+ *
+ * **Idempotent.** Invalidating an already-absent entry is a no-op
+ * (matches `clearEntry`'s missing-file semantics) — callers don't
+ * need to gate the call on "is this board cached?". Errors during
+ * unlink (permission flip, disk loss) bubble as `CacheError` per the
+ * underlying primitive.
+ *
+ * **Process-local.** The on-disk cache file IS shared across
+ * processes (same `$XDG_CACHE_HOME/monday-cli/boards/<bid>.json`
+ * path), so this `unlink` does remove peer processes' cache entries;
+ * the missing primitive is inter-process locking. Cross-process
+ * coordination is explicitly deferred to v0.3 per cli-design §8 —
+ * this helper does NOT add inter-process locking.
+ *
+ * Mirrors `evictBoardMetadata` in `board-metadata.ts` (the M3-era
+ * helper that predates the eager-invalidation contract); the two
+ * helpers are intentionally parallel — `evictBoardMetadata` lives
+ * next to the metadata loader and is consumed by tests + potential
+ * future `cache clear --board <bid>` flows; `invalidateBoard` lives
+ * here next to the underlying `clearEntry` primitive and is consumed
+ * by every M16+ board-structure mutation per the §8 contract. Lifting
+ * one over the other was rejected during M16 pre-flight to keep the
+ * existing test surface unchanged.
+ */
+export declare const invalidateBoard: (boardId: string, env?: NodeJS.ProcessEnv) => Promise<ClearResult>;
+/**
+ * Removes the entire cache root. Used by `monday cache clear` (no
+ * flag) and tests. Counts removed JSON files for reporting; the
+ * directory tree itself goes too so a follow-up `cache list` reports
+ * an empty cache, not phantom directories.
+ */
+export declare const clearAll: (root: string) => Promise<ClearResult>;
+export interface CacheStats {
+    readonly root: string;
+    readonly exists: boolean;
+    readonly entries: number;
+    readonly bytes: number;
+    readonly oldestAgeSeconds: number | null;
+    readonly newestAgeSeconds: number | null;
+}
+export declare const stats: (root: string, options?: ListOptions) => Promise<CacheStats>;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/api/cache.d.ts.map

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