monday-cli 0.2.0

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

@@ -0,0 +1,162 @@
+/**
+ * Board metadata loader (`v0.1-plan.md` §3 M3, `cli-design.md` §8).
+ *
+ * Single source of truth for "what columns / groups / kind does this
+ * board have?" — the shape every M3+ command that resolves a column
+ * token, prints `board describe`, or maps a `--where` clause needs.
+ * The data is cached on disk via `api/cache.ts` (5-minute default TTL,
+ * `--no-cache` bypasses) and the cache miss path issues a single
+ * GraphQL call against the raw `client.raw<T>` escape hatch — the
+ * SDK's typed `boards` query doesn't expose `hierarchy_type` /
+ * `is_leaf`, both of which the design's "describe" output requires
+ * (`cli-design.md` §2.8).
+ *
+ * The cache layer holds Monday-shape JSON; this module is the *only*
+ * place that reshapes Monday's response into the projected
+ * `BoardMetadata` form. Keeping the shape stable here means a future
+ * SDK bump that adds optional fields doesn't ripple into 14 commands —
+ * `boardMetadataSchema.parse` is the parse boundary, and the cache
+ * envelope's `schema_version` (cache.ts) gates older payloads.
+ *
+ * **Auto-refresh-on-failure semantics.** Two cache-miss-style paths:
+ *
+ *   1. Cache absent / expired → fetch live, write cache, return.
+ *   2. Cache present but caller's lookup against it failed (e.g.
+ *      column token didn't match anything) → refresh once, return
+ *      the new metadata. Callers (`columns.ts`) decide whether the
+ *      second lookup succeeded; this module just promises that
+ *      `loadBoardMetadata({ refresh: true })` bypasses the cache.
+ *
+ * `--no-cache` is a stronger signal — it skips the on-disk read
+ * entirely *and* skips the post-fetch write. Useful for `monday board
+ * describe --no-cache <bid>` when the agent suspects on-disk drift.
+ */
+import { z } from 'zod';
+import type { MondayClient } from './client.js';
+import { type BoardId } from '../types/ids.js';
+import type { Complexity } from '../utils/output/envelope.js';
+declare const groupSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    color: z.ZodNullable<z.ZodString>;
+    position: z.ZodNullable<z.ZodString>;
+    archived: z.ZodNullable<z.ZodBoolean>;
+    deleted: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const columnSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    archived: z.ZodNullable<z.ZodBoolean>;
+    settings_str: z.ZodNullable<z.ZodString>;
+    width: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const boardMetadataSchema: 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>;
+    hierarchy_type: z.ZodNullable<z.ZodString>;
+    is_leaf: z.ZodNullable<z.ZodBoolean>;
+    items_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    permissions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    groups: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        color: z.ZodNullable<z.ZodString>;
+        position: z.ZodNullable<z.ZodString>;
+        archived: z.ZodNullable<z.ZodBoolean>;
+        deleted: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        type: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        archived: z.ZodNullable<z.ZodBoolean>;
+        settings_str: z.ZodNullable<z.ZodString>;
+        width: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type BoardMetadata = z.infer<typeof boardMetadataSchema>;
+export type BoardColumn = z.infer<typeof columnSchema>;
+export type BoardGroup = z.infer<typeof groupSchema>;
+export interface LoadBoardMetadataInputs {
+    readonly client: MondayClient;
+    readonly boardId: BoardId | string;
+    /** Source for the cache root — defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * `--no-cache`: skip the on-disk read + write entirely. Live fetch
+     * always happens; the result is returned unchanged. Defaults to
+     * false.
+     */
+    readonly noCache?: boolean;
+    /**
+     * Force a live fetch even when the cache holds a fresh entry; the
+     * fresh response is written back to cache. `columns.ts` uses this
+     * to retry once on `column_not_found` before surfacing the error.
+     */
+    readonly refresh?: boolean;
+    /**
+     * Override TTL in seconds. Defaults to the cache module's 5-minute
+     * baseline. Passed through to `readEntry` only.
+     */
+    readonly ttlSeconds?: number;
+    /**
+     * Now provider, threaded through to the cache module so age
+     * calculations are deterministic in tests.
+     */
+    readonly now?: () => Date;
+}
+/**
+ * Result of a `loadBoardMetadata` call. `source` agrees with the
+ * envelope's `meta.source` rule: `cache` for a hit, `live` for a
+ * fetch (whether the cache was bypassed, expired, or refreshed).
+ *
+ * `cacheAgeSeconds` is the on-disk age of the served payload when
+ * source is `cache` — used by command actions to populate
+ * `meta.cache_age_seconds`. `null` for live fetches.
+ */
+export interface BoardMetadataLoadResult {
+    readonly metadata: BoardMetadata;
+    readonly source: 'live' | 'cache';
+    readonly cacheAgeSeconds: number | null;
+    /**
+     * `meta.complexity` payload from the live request when one ran;
+     * `null` for cache hits and for non-`--verbose` live calls (Monday
+     * doesn't include `complexity` unless the operation selects it).
+     * Surfacing this here is what lets cache-backed commands report
+     * accurate complexity in `--verbose` mode (Codex M3 pass-1 §3 —
+     * the original projection threw the value away).
+     */
+    readonly complexity: Complexity | null;
+}
+/**
+ * Loads board metadata, preferring a fresh on-disk cache entry over
+ * a live fetch. Cache writes are best-effort — if writing fails (disk
+ * full, permission flip), the live data still returns and a warning
+ * is suppressed (callers can opt in via the future `warnings`
+ * channel; v0.1 keeps cache-write errors local). Read errors raise.
+ */
+export declare const loadBoardMetadata: (inputs: LoadBoardMetadataInputs) => Promise<BoardMetadataLoadResult>;
+/**
+ * Convenience used by `columns.ts`'s "refresh once before surfacing
+ * column_not_found" path. Idempotent; the cache write happens via
+ * `loadBoardMetadata({refresh:true})`.
+ */
+export declare const refreshBoardMetadata: (inputs: Omit<LoadBoardMetadataInputs, "refresh">) => Promise<BoardMetadataLoadResult>;
+/**
+ * Drops the on-disk metadata for a board. Used by tests and by future
+ * `cache clear --board <bid>` flows; M3 doesn't change the existing
+ * cache CLI surface.
+ */
+export declare const evictBoardMetadata: (boardId: BoardId | string, env?: NodeJS.ProcessEnv) => Promise<void>;
+export {};
+//# sourceMappingURL=board-metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board-metadata.d.ts","sourceRoot":"","sources":["../../src/api/board-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAuC9D,QAAA,MAAM,WAAW;;;;;;;kBASN,CAAC;AAEZ,QAAA,MAAM,YAAY;;;;;;;;kBAUP,CAAC;AAEZ,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAuBrB,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAUrD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AAkED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,uBAAuB,KAC9B,OAAO,CAAC,uBAAuB,CAsDjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,IAAI,CAAC,uBAAuB,EAAE,SAAS,CAAC,KAC/C,OAAO,CAAC,uBAAuB,CACe,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,OAAO,GAAG,MAAM,EAEzB,MAAK,MAAM,CAAC,UAAwB,KACnC,OAAO,CAAC,IAAI,CAId,CAAC"}

package/dist/api/board-metadata.js

@@ -0,0 +1,238 @@
+/**
+ * Board metadata loader (`v0.1-plan.md` §3 M3, `cli-design.md` §8).
+ *
+ * Single source of truth for "what columns / groups / kind does this
+ * board have?" — the shape every M3+ command that resolves a column
+ * token, prints `board describe`, or maps a `--where` clause needs.
+ * The data is cached on disk via `api/cache.ts` (5-minute default TTL,
+ * `--no-cache` bypasses) and the cache miss path issues a single
+ * GraphQL call against the raw `client.raw<T>` escape hatch — the
+ * SDK's typed `boards` query doesn't expose `hierarchy_type` /
+ * `is_leaf`, both of which the design's "describe" output requires
+ * (`cli-design.md` §2.8).
+ *
+ * The cache layer holds Monday-shape JSON; this module is the *only*
+ * place that reshapes Monday's response into the projected
+ * `BoardMetadata` form. Keeping the shape stable here means a future
+ * SDK bump that adds optional fields doesn't ripple into 14 commands —
+ * `boardMetadataSchema.parse` is the parse boundary, and the cache
+ * envelope's `schema_version` (cache.ts) gates older payloads.
+ *
+ * **Auto-refresh-on-failure semantics.** Two cache-miss-style paths:
+ *
+ *   1. Cache absent / expired → fetch live, write cache, return.
+ *   2. Cache present but caller's lookup against it failed (e.g.
+ *      column token didn't match anything) → refresh once, return
+ *      the new metadata. Callers (`columns.ts`) decide whether the
+ *      second lookup succeeded; this module just promises that
+ *      `loadBoardMetadata({ refresh: true })` bypasses the cache.
+ *
+ * `--no-cache` is a stronger signal — it skips the on-disk read
+ * entirely *and* skips the post-fetch write. Useful for `monday board
+ * describe --no-cache <bid>` when the agent suspects on-disk drift.
+ */
+import { z } from 'zod';
+import { clearEntry, readEntry, resolveCacheRoot, writeEntry, DEFAULT_CACHE_TTL_SECONDS, } from './cache.js';
+import { BoardIdSchema } from '../types/ids.js';
+import { ApiError } from '../utils/errors.js';
+import { unwrapOrThrow } from '../utils/parse-boundary.js';
+const BOARD_METADATA_QUERY = `
+  query BoardMetadata($ids: [ID!]!) {
+    boards(ids: $ids) {
+      id
+      name
+      description
+      state
+      board_kind
+      board_folder_id
+      workspace_id
+      url
+      hierarchy_type
+      is_leaf
+      items_count
+      permissions
+      updated_at
+      groups {
+        id
+        title
+        color
+        position
+        archived
+        deleted
+      }
+      columns {
+        id
+        title
+        type
+        description
+        archived
+        settings_str
+        width
+      }
+    }
+  }
+`;
+const groupSchema = z
+    .object({
+    id: z.string().min(1),
+    title: z.string(),
+    color: z.string().nullable(),
+    position: z.string().nullable(),
+    archived: z.boolean().nullable(),
+    deleted: z.boolean().nullable(),
+})
+    .strict();
+const columnSchema = 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();
+export const boardMetadataSchema = 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(),
+    hierarchy_type: z.string().nullable(),
+    is_leaf: z.boolean().nullable(),
+    // Optional+nullable so existing pre-M15 cache entries (which
+    // didn't carry these fields) parse cleanly post-bump. New
+    // BOARD_METADATA_QUERY runs include the fields; the M15 board
+    // archive + duplicate dry-run snapshots project them through
+    // `?? null` to preserve the §6.2 board projection shape.
+    items_count: z.number().int().nullable().optional(),
+    permissions: z.string().nullable().optional(),
+    updated_at: z.string().nullable(),
+    groups: z.array(groupSchema),
+    columns: z.array(columnSchema),
+})
+    .strict();
+const responseSchema = z.looseObject({
+    boards: z.array(z.unknown()).nullable(),
+});
+const projectBoard = (raw, boardId) => 
+// R18 parse-boundary wrap. Live-fetch projection: a malformed
+// Monday response (schema drift, future field rename) surfaces as
+// `internal_error` with `details.issues` rather than a bare
+// ZodError that the runner's catch-all maps to `internal_error`
+// but loses the failing field path. Per validation.md "Never
+// bubble raw ZodError out of a parse boundary".
+unwrapOrThrow(boardMetadataSchema.safeParse(raw), {
+    context: `Monday returned a malformed board metadata response for id ${boardId}`,
+    details: { board_id: boardId },
+    hint: 'this is a data-integrity error in Monday\'s response (or a ' +
+        'boardMetadataSchema drift); verify the response shape and ' +
+        'update the schema if Monday\'s contract has changed.',
+});
+// Cache-read parse callback. ZodError here is intentionally
+// swallowed by the surrounding `loadBoardMetadata` try/catch (cache-
+// miss path) — a corrupt cache file is treated as a miss and a live
+// fetch follows. Wrapping with unwrapOrThrow would be a change in
+// behaviour. Kept as a thin parse so corrupt-cache → cache-miss
+// stays the established contract.
+const parseCacheEntry = (raw) => boardMetadataSchema.parse(raw);
+const fetchLive = async (client, boardId) => {
+    const response = await client.raw(BOARD_METADATA_QUERY, { ids: [boardId] }, { operationName: 'BoardMetadata' });
+    // Pre-validate the loose response shape so a missing `boards` key
+    // surfaces a clear error rather than tripping the projection
+    // parser on an undefined entry. R18 parse-boundary wrap: malformed
+    // top-level shape (e.g. response without a `boards` key, or
+    // `boards` not an array) surfaces with `details.issues` rather
+    // than a bare ZodError.
+    const validated = unwrapOrThrow(responseSchema.safeParse(response.data), {
+        context: `Monday returned a malformed BoardMetadata response for id ${boardId}`,
+        details: { board_id: boardId },
+        hint: 'this is a data-integrity error in Monday\'s response (or a ' +
+            'BoardMetadata response-shape drift); verify the response and ' +
+            'update responseSchema if Monday\'s contract has changed.',
+    });
+    const first = validated.boards?.[0];
+    if (first === undefined || first === null) {
+        throw new ApiError('not_found', `Monday returned no board for id ${boardId}`, { details: { board_id: boardId } });
+    }
+    return { metadata: projectBoard(first, boardId), complexity: response.complexity };
+};
+/**
+ * Loads board metadata, preferring a fresh on-disk cache entry over
+ * a live fetch. Cache writes are best-effort — if writing fails (disk
+ * full, permission flip), the live data still returns and a warning
+ * is suppressed (callers can opt in via the future `warnings`
+ * channel; v0.1 keeps cache-write errors local). Read errors raise.
+ */
+export const loadBoardMetadata = async (inputs) => {
+    /* c8 ignore next — defensive fallback; tests always pass `env`. */
+    const env = inputs.env ?? process.env;
+    const boardId = BoardIdSchema.parse(inputs.boardId);
+    const root = resolveCacheRoot({ env });
+    const ttlSeconds = inputs.ttlSeconds ?? DEFAULT_CACHE_TTL_SECONDS;
+    const now = inputs.now;
+    if (inputs.noCache !== true && inputs.refresh !== true) {
+        let hit;
+        try {
+            hit = await readEntry(root, { kind: 'board', boardId }, parseCacheEntry, {
+                ttlSeconds,
+                ...(now === undefined ? {} : { now }),
+            });
+        }
+        catch {
+            // A corrupt or unreadable cache file is non-fatal — fall through
+            // to a live fetch. The on-disk error is surfaced separately by
+            // `cache list` / `cache stats`; an end-user metadata fetch
+            // shouldn't fail because of stale local state.
+            hit = undefined;
+        }
+        if (hit !== undefined) {
+            return {
+                metadata: hit.data,
+                source: 'cache',
+                cacheAgeSeconds: hit.ageSeconds,
+                complexity: null,
+            };
+        }
+    }
+    const live = await fetchLive(inputs.client, boardId);
+    if (inputs.noCache !== true) {
+        try {
+            await writeEntry(root, { kind: 'board', boardId }, live.metadata);
+        }
+        catch {
+            // Cache-write failures don't block the user — the live data is
+            // good and a future call will simply re-fetch.
+        }
+    }
+    return {
+        metadata: live.metadata,
+        source: 'live',
+        cacheAgeSeconds: null,
+        complexity: live.complexity,
+    };
+};
+/**
+ * Convenience used by `columns.ts`'s "refresh once before surfacing
+ * column_not_found" path. Idempotent; the cache write happens via
+ * `loadBoardMetadata({refresh:true})`.
+ */
+export const refreshBoardMetadata = async (inputs) => loadBoardMetadata({ ...inputs, refresh: true });
+/**
+ * Drops the on-disk metadata for a board. Used by tests and by future
+ * `cache clear --board <bid>` flows; M3 doesn't change the existing
+ * cache CLI surface.
+ */
+export const evictBoardMetadata = async (boardId, 
+/* c8 ignore next — defensive default; callers pass an explicit env. */
+env = process.env) => {
+    const id = BoardIdSchema.parse(boardId);
+    const root = resolveCacheRoot({ env });
+    await clearEntry(root, { kind: 'board', boardId: id });
+};
+//# sourceMappingURL=board-metadata.js.map

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

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

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

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+/**
+ * Tracker handed to the `runFanOut` closure so consumer loops can
+ * record successful per-attribute legs without owning the counter.
+ * The helper observes `recordLegSuccess()` calls to gate §8
+ * invalidation on the high-water-mark rule.
+ */
+export interface BoardFanOutTracker {
+    /**
+     * Call once per successfully-committed per-attribute wire call.
+     * Drives the §8 fan-out invalidation gate: invalidation fires
+     * iff this is called at least once before `runFanOut` returns
+     * or throws.
+     */
+    readonly recordLegSuccess: () => void;
+}
+export interface WithBoardInvalidationSingleLegInputs<T> {
+    readonly boardId: string;
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * Performs the wire mutation, parses + projects the response,
+     * and returns whatever the consumer needs post-helper (typically
+     * `{data, response}` so `emitMutation` can take both `data` and
+     * `toEmit(response)`). If `perform` throws, invalidation is
+     * skipped — a failed single-leg call didn't change board state.
+     */
+    readonly perform: () => Promise<T>;
+}
+/**
+ * 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 declare const withBoardInvalidationSingleLeg: <T>({ boardId, env, perform, }: WithBoardInvalidationSingleLegInputs<T>) => Promise<T>;
+export interface WithBoardInvalidationFanOutInputs<T> {
+    readonly boardId: string;
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * Runs the per-attribute wire-call loop (and any trailing read /
+     * projection legs). Calls `tracker.recordLegSuccess()` after each
+     * successful leg so the helper can apply the §8 high-water-mark
+     * invalidation rule. Returns whatever the consumer needs post-
+     * helper (typically `{data, response}` for `emitMutation` +
+     * `toEmit(response)`). When `runFanOut` throws after recording
+     * one or more leg successes, the helper invalidates BEFORE
+     * re-throwing so the cache reflects partially-applied state.
+     */
+    readonly runFanOut: (tracker: BoardFanOutTracker) => Promise<T>;
+}
+/**
+ * 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 declare const withBoardInvalidationFanOut: <T>({ boardId, env, runFanOut, }: WithBoardInvalidationFanOutInputs<T>) => Promise<T>;
+//# sourceMappingURL=board-mutation-invalidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"board-mutation-invalidation.d.ts","sourceRoot":"","sources":["../../src/api/board-mutation-invalidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,oCAAoC,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAAU,CAAC,EAAE,4BAIrD,oCAAoC,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAIrD,CAAC;AAEF,MAAM,WAAW,iCAAiC,CAAC,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,2BAA2B,GAAU,CAAC,EAAE,8BAIlD,iCAAiC,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAmBlD,CAAC"}