@neta-art/cohub-cli 3.12.0 → 5.0.0

package/README.md

@@ -157,72 +157,44 @@ cohub -s <spaceId> boards capabilities <boardId>
 cohub -s <spaceId> boards watch <boardId> --json
 ```
 
-Pass nodes, effects, and sequences as JSON when creating a Board. The path and
-title stay explicit in the command. Inspect `boards capabilities --json` for the
-supported node types, enums, and coordinate spaces.
-
-```json
-{
-  "nodes": [
-    {
-      "nodeId": "goal",
-      "type": "geo",
-      "parentId": null,
-      "orderKey": null,
-      "x": 80,
-      "y": 80,
-      "width": 240,
-      "height": 120,
-      "rotation": 0,
-      "refKind": null,
-      "refPath": null,
-      "refUrl": null,
-      "view": {},
-      "style": {},
-      "data": {
-        "geo": "rectangle",
-        "text": "Ship",
-        "color": "green",
-        "fillOpacity": 0.12
-      }
-    }
-  ]
-}
+Pass semantic items, effects, and compositions as JSON when creating a Board. The path and title stay explicit in the command. Generate editable templates instead of guessing fields:
+
+```bash
+cohub boards examples create > board-content.json
+cohub boards examples item geo > item.json
+cohub boards examples effect pulse > effect.json
+cohub boards examples composition fade > intro.json
 ```
 
+Inspect `boards capabilities --json` for supported Item types, animation channels, effect kinds, and coordinate spaces.
+
 ```bash
 cohub -s <spaceId> boards create boards/plan.board \
   --title "Plan" \
   --input board-content.json
 ```
 
-Transactions are JSON objects without `boardId`; the bound Board supplies it.
-`txId` is generated when omitted, while `baseVersion` must be provided in the
-input or with `--base-version`:
-
-```json
-{
-  "baseVersion": 3,
-  "operations": [
-    {
-      "type": "board.patch",
-      "payload": { "patch": { "title": "Updated plan" } }
-    }
-  ]
-}
+Generate editable semantic JSON templates instead of authoring storage transactions:
+
+```bash
+cohub boards examples item text > item.json
+cohub boards items create <boardId> --input item.json
+
+cohub boards examples composition fade > intro.json
+cohub boards compositions apply <boardId> --input intro.json
+
+cohub boards examples effect pulse > effect.json
+cohub boards effects apply <boardId> --input effect.json
 ```
 
+Use `--mutation-id` or `--command-id` when a script needs a stable idempotency key across retries.
+
 ```bash
-cohub -s <spaceId> boards validate <boardId> --input transaction.json
-cat transaction.json | cohub -s <spaceId> boards apply <boardId> --input - --json
-cohub -s <spaceId> boards play <boardId> <sequenceId>
+cohub -s <spaceId> boards play <boardId> <compositionId>
 cohub -s <spaceId> boards seek <boardId> <playbackId> 400
 cohub -s <spaceId> boards stop <boardId> <playbackId>
 ```
 
-Pass `--tx-id` or `--command-id` when a script needs a stable idempotency key
-across retries.
-
 ## Search
 
 Search Spaces, Chats, and prior turns:

package/dist/board-export.js

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+import { boardAuthoringSnapshotToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 import { createBoardHeadlessRenderer, exportBoardImageBytes, } from "@neta-art/cohub/board/headless";
 import { resolveBoardId } from "./board-command-support.js";
 import { createClient } from "./client.js";
@@ -64,11 +64,11 @@ export function resolveBundledFonts() {
 export async function loadBoardDocument(spaceId, target) {
     const client = createClient();
     const boardId = await resolveBoardId(spaceId, target);
-    const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
+    const snapshot = await client.space(spaceId).board(boardId).authoring({ include: ["items", "connections"] });
     return {
-        document: boardBootstrapToDocument(bootstrap),
-        boardId: bootstrap.board.id,
-        title: bootstrap.board.title ?? null,
+        document: boardAuthoringSnapshotToDocument(snapshot),
+        boardId: snapshot.board.id,
+        title: snapshot.board.title ?? null,
     };
 }
 /**

package/dist/commands/board-domain.js

@@ -1,8 +1,12 @@
 import { registerBoardAnimationCommands } from "./boards/animation.js";
 import { registerBoardAppearanceCommands } from "./boards/appearance.js";
+import { registerBoardExampleCommands } from "./boards/examples.js";
+import { registerBoardItemCommands } from "./boards/items.js";
 import { registerBoardNodeCommands } from "./boards/nodes.js";
 export function registerBoardDomainCommands(boards) {
+    registerBoardExampleCommands(boards);
     registerBoardAppearanceCommands(boards);
     registerBoardNodeCommands(boards);
+    registerBoardItemCommands(boards);
     registerBoardAnimationCommands(boards);
 }

package/dist/commands/boards/animation.js

@@ -1,28 +1,18 @@
-import { randomUUID } from "node:crypto";
-import { BoardCameraFocusParamsSchema, boardEffectDeleteOperation, boardEffectUpsertOperation, boardSequenceDeleteOperation, boardSequenceUpsertOperation, } from "@neta-art/cohub/board";
+import { parseBoardEffectInput, parseBoardCompositionInput, } from "@neta-art/cohub";
 import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
 import { handleHttp, json, jsonRequested, table } from "../../output.js";
-import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
-function rect(value) {
-    const parts = value.split(",").map(Number);
-    if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) {
-        throw new Error("--rect must be x,y,width,height");
-    }
-    const [x, y, width, height] = parts;
-    if (width <= 0 || height <= 0)
-        throw new Error("--rect width and height must be positive");
-    return { x, y, width, height };
-}
+import { mutateSemantic, resolvedBoard, showUpdated, withJson, } from "./context.js";
 export function registerBoardAnimationCommands(boards) {
     const effects = boards.command("effects").description("Manage Board effects");
     withJson(effects.command("list <board>").alias("ls").description("List effects"))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["effects"] });
+            const result = await board.authoring({ include: ["effects"] });
+            const effects = result.effects ?? [];
             if (jsonRequested(options))
-                return json(result.effects);
-            table(result.effects, [
+                return json(effects);
+            table(effects, [
                 { key: "id", label: "ID" },
                 { key: "kind", label: "KIND" },
                 { key: "enabled", label: "ENABLED" },
@@ -33,19 +23,21 @@ export function registerBoardAnimationCommands(boards) {
             handleHttp(cause);
         }
     });
-    withJson(effects.command("upsert <board>")
-        .description("Create or replace an effect")
+    withJson(effects.command("apply <board>")
+        .description("Atomically create or replace an effect")
         .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin")
         .addHelpText("after", `
-Minimal pulse effect:
-  {"id":"pulse-title","target":{"type":"node","nodeId":"title"},"kind":"effects.pulse","kindVersion":1,"lifecycle":"when-visible","timeOrigin":"visible","seed":"pulse-title"}
+Create a template:
+  cohub boards examples effect pulse > effect.json
 
-Run boards capabilities <board> to discover supported effect kinds.`))
+Discover supported effect kinds:
+  cohub boards capabilities <board> --json`))
         .action(async (target, options) => {
         try {
-            const effect = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const effect = parseBoardEffectInput(input);
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardEffectUpsertOperation(effect)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "effect.apply", effect }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -55,24 +47,36 @@ Run boards capabilities <board> to discover supported effect kinds.`))
         .action(async (target, effectId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardEffectDeleteOperation(effectId)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "effect.delete", effectId }]), options);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    const sequences = boards.command("sequences").description("Manage Board sequences");
-    withJson(sequences.command("list <board>").alias("ls").description("List sequences"))
+    const compositions = boards
+        .command("compositions")
+        .description("Manage atomic Board animation compositions");
+    withJson(compositions.command("list <board>").alias("ls").description("List compositions"))
         .action(async (target, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["sequences"] });
+            const result = await board.authoring({ include: ["compositions"] });
+            const compositions = result.compositions ?? [];
             if (jsonRequested(options))
-                return json(result.sequences);
-            table(result.sequences, [
+                return json(compositions);
+            table(compositions.map((composition) => ({
+                id: composition.id,
+                name: composition.name,
+                duration: composition.timeline.duration,
+                tracks: composition.timeline.tracks.length,
+                clips: composition.timeline.clips.length,
+                revision: composition.revision,
+            })), [
                 { key: "id", label: "ID" },
                 { key: "name", label: "NAME" },
                 { key: "duration", label: "DURATION" },
+                { key: "tracks", label: "TRACKS" },
+                { key: "clips", label: "CLIPS" },
                 { key: "revision", label: "REVISION" },
             ]);
         }
@@ -80,145 +84,64 @@ Run boards capabilities <board> to discover supported effect kinds.`))
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("get <board> <sequence-id>").description("Get a sequence and its clips"))
-        .action(async (target, sequenceId, options) => {
+    withJson(compositions.command("get <board> <composition-id>").description("Get one complete composition"))
+        .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            const result = await board.inspect({ include: ["sequences", "clips"] });
-            const sequence = result.sequences.find((item) => item.id === sequenceId);
-            if (!sequence)
-                throw new Error(`Sequence not found: ${sequenceId}`);
-            const output = {
-                sequence,
-                clips: result.clips.filter((clip) => clip.sequenceId === sequenceId),
-            };
+            const result = await board.authoring({ include: ["compositions"] });
+            const composition = (result.compositions ?? []).find((item) => item.id === compositionId);
+            if (!composition)
+                throw new Error(`Composition not found: ${compositionId}`);
             if (jsonRequested(options))
-                return json(output);
-            table([sequence], [
+                return json(composition);
+            table([{
+                    id: composition.id,
+                    name: composition.name,
+                    duration: composition.timeline.duration,
+                    tracks: composition.timeline.tracks.length,
+                    clips: composition.timeline.clips.length,
+                    revision: composition.revision,
+                }], [
                 { key: "id", label: "ID" },
                 { key: "name", label: "NAME" },
                 { key: "duration", label: "DURATION" },
+                { key: "tracks", label: "TRACKS" },
+                { key: "clips", label: "CLIPS" },
                 { key: "revision", label: "REVISION" },
             ]);
-            table(output.clips, [
-                { key: "id", label: "CLIP" },
-                { key: "kind", label: "KIND" },
-                { key: "start", label: "START" },
-                { key: "duration", label: "DURATION" },
-            ]);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("upsert <board>")
-        .description("Create or replace a sequence and clips")
-        .requiredOption("-i, --input <file>", "{ sequence, clips } JSON; use - for stdin")
+    withJson(compositions.command("apply <board>")
+        .description("Atomically create or replace a composition")
+        .requiredOption("-i, --input <file>", "BoardComposition JSON; use - for stdin")
         .addHelpText("after", `
-Minimal sequence with one clip:
-  {"sequence":{"id":"intro","name":"Intro","duration":1200,"seed":"intro"},"clips":[{"id":"reveal-title","kind":"text.reveal","kindVersion":1,"target":{"type":"node","nodeId":"title"},"start":0,"duration":600,"seed":"reveal-title"}]}
-
-Coordinate rules:
-  node motion x/y and path points are Board-world offsets; camera.pan x/y are screen-pixel offsets.
+Property changes use timeline.tracks with registered channels and keyframes.
+Procedural behavior such as text reveal, particles, and camera focus uses timeline.clips.
+Run boards capabilities to discover channels and clip schemas.
+Create an editable template with:
+  cohub boards examples composition fade > intro.json
 
-Edit an existing sequence:
-  cohub boards sequences get <board> intro --json > intro.json
-  cohub boards sequences upsert <board> -i intro.json`))
+Minimal fade composition:
+  {"id":"intro","name":"Intro","timeline":{"duration":800,"tracks":[{"id":"title-opacity","target":{"type":"item","itemId":"title"},"channel":"style.opacity","fill":"both","keyframes":[{"time":0,"value":0},{"time":800,"value":1,"easing":"ease-out-cubic"}]}],"clips":[],"markers":[]},"playback":{"loop":false,"endBehavior":"hold","reducedMotion":{"mode":"base"}}}`))
         .action(async (target, options) => {
         try {
             const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const composition = parseBoardCompositionInput(input);
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardSequenceUpsertOperation(input)] }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(sequences.command("camera-focus <board> <sequence-id>")
-        .description("Add or replace a semantic camera focus clip")
-        .option("--id <id>", "Stable clip id")
-        .option("--node <id>", "Focus one node")
-        .option("--nodes <ids>", "Focus comma-separated nodes")
-        .option("--frame <id>", "Focus a frame")
-        .option("--rect <rect>", "Board world rect as x,y,width,height")
-        .requiredOption("--at <ms>", "Clip start time")
-        .option("--duration <ms>", "Transition duration", "700")
-        .option("--padding <px>", "Screen padding in CSS pixels", "32")
-        .option("--fit <mode>", "contain or cover", "contain")
-        .option("--min-zoom <zoom>", "Minimum zoom multiplier")
-        .option("--max-zoom <zoom>", "Maximum zoom multiplier")
-        .option("--easing <name>", "Easing", "ease-out-cubic")
-        .addHelpText("after", `
-Examples:
-  cohub boards sequences camera-focus plan.board intro --node hero --at 1200
-  cohub boards sequences camera-focus plan.board intro --rect 120,80,640,360 --at 2000 --duration 800`))
-        .action(async (target, sequenceId, options) => {
-        try {
-            const selected = [options.node, options.nodes, options.frame, options.rect].filter(Boolean);
-            if (selected.length !== 1)
-                throw new Error("Choose one of --node, --nodes, --frame, or --rect");
-            const focus = options.node
-                ? { type: "node", nodeId: options.node }
-                : options.nodes
-                    ? { type: "nodes", nodeIds: options.nodes.split(",").map((id) => id.trim()).filter(Boolean) }
-                    : options.frame
-                        ? { type: "frame", frameId: options.frame }
-                        : { type: "rect", rect: rect(options.rect) };
-            const params = BoardCameraFocusParamsSchema.parse({
-                focus,
-                fit: options.fit,
-                padding: finite(options.padding, "padding"),
-                ...(options.minZoom === undefined ? {} : { minZoom: finite(options.minZoom, "min zoom") }),
-                ...(options.maxZoom === undefined ? {} : { maxZoom: finite(options.maxZoom, "max zoom") }),
-            });
-            const start = finite(options.at, "start");
-            const duration = finite(options.duration, "duration");
-            if (start < 0 || duration <= 0)
-                throw new Error("start must be non-negative and duration must be positive");
-            const clipId = options.id ?? randomUUID();
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                include: ["sequences", "clips"],
-                build(current) {
-                    const currentSequence = current.sequences.find((sequence) => sequence.id === sequenceId);
-                    if (!currentSequence)
-                        throw new Error(`Sequence not found: ${sequenceId}`);
-                    const { boardId: _boardId, revision: _revision, ...sequence } = currentSequence;
-                    const clips = current.clips
-                        .filter((clip) => clip.sequenceId === sequenceId && clip.id !== clipId)
-                        .map(({ sequenceId: _sequenceId, ...clip }) => clip);
-                    clips.push({
-                        id: clipId,
-                        kind: "camera.focus",
-                        kindVersion: 1,
-                        target: { type: "camera" },
-                        start,
-                        duration,
-                        layer: "screen",
-                        fill: "forwards",
-                        easing: options.easing,
-                        params,
-                        keyframes: [],
-                        assetRefs: [],
-                        seed: clipId,
-                        metadata: {},
-                    });
-                    return [boardSequenceUpsertOperation({
-                            sequence: { ...sequence, duration: Math.max(sequence.duration, start + duration) },
-                            clips,
-                        })];
-                },
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "composition.apply", composition }]), options);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    withJson(sequences.command("delete <board> <sequence-id>").alias("rm").description("Delete a sequence and its clips"))
-        .action(async (target, sequenceId, options) => {
+    withJson(compositions.command("delete <board> <composition-id>").alias("rm").description("Delete a composition"))
+        .action(async (target, compositionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardSequenceDeleteOperation(sequenceId)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "composition.delete", compositionId }]), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards/appearance.js

@@ -1,6 +1,6 @@
-import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, boardAppearanceOperation, boardPlaybackPolicyOperation, boardTitleOperation, patchBoardAppearance, } from "@neta-art/cohub/board";
+import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, patchBoardAppearance, } from "@neta-art/cohub/board";
 import { handleHttp } from "../../output.js";
-import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
+import { finite, mutateSemantic, resolvedBoard, showUpdated, withJson, } from "./context.js";
 function appearanceFrom(metadata) {
     const parsed = BoardAppearanceSchema.safeParse(metadata.appearance);
     return parsed.success ? parsed.data : DEFAULT_BOARD_APPEARANCE;
@@ -10,7 +10,7 @@ export function registerBoardAppearanceCommands(boards) {
         .action(async (target, title, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardTitleOperation(title)] }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "board.patch", patch: { title } }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -41,24 +41,24 @@ Examples:
             if (opacity < 0 || opacity > 1)
                 throw new Error("opacity must be between 0 and 1");
             const board = await resolvedBoard(boards, target);
-            const result = await board.mutate({
-                build(current) {
-                    const appearance = appearanceFrom(current.board.metadata);
-                    const background = options.reset
-                        ? { kind: "solid" }
-                        : options.color
-                            ? { kind: "solid", color: options.color }
-                            : {
-                                kind: "image",
-                                imageUrl: options.image,
-                                fit: options.fit,
-                                position: options.position,
-                                opacity,
-                                color: appearance.background.color,
-                            };
-                    return [boardAppearanceOperation(patchBoardAppearance(appearance, { background }))];
-                },
-            });
+            const current = await board.summary();
+            const appearance = appearanceFrom(current.board.metadata);
+            const background = options.reset
+                ? { kind: "solid" }
+                : options.color
+                    ? { kind: "solid", color: options.color }
+                    : {
+                        kind: "image",
+                        imageUrl: options.image,
+                        fit: options.fit,
+                        position: options.position,
+                        opacity,
+                        color: appearance.background.color,
+                    };
+            const result = await mutateSemantic(board, [{
+                    type: "board.patch",
+                    patch: { metadataPatch: { appearance: patchBoardAppearance(appearance, { background }) } },
+                }], { baseVersion: current.board.version });
             showUpdated(result, options);
         }
         catch (cause) {
@@ -67,24 +67,27 @@ Examples:
     });
     withJson(boards.command("playback-policy <board>")
         .description("Configure automatic Board playback")
-        .option("--sequence <id>", "Sequence to play")
+        .option("--composition <id>", "Composition to play")
         .option("--delay <ms>", "Delay before playback", "0")
-        .option("--loop", "Loop the sequence")
         .option("--clear", "Remove the playback policy"))
         .action(async (target, options) => {
         try {
-            if (options.clear === Boolean(options.sequence))
-                throw new Error("Use --sequence or --clear");
+            if (options.clear === Boolean(options.composition))
+                throw new Error("Use --composition or --clear");
             const delayMs = finite(options.delay, "delay");
             if (delayMs < 0)
                 throw new Error("delay must be non-negative");
             const policy = options.clear
                 ? null
-                : { sequenceId: options.sequence, delayMs, loop: Boolean(options.loop) };
+                : { compositionId: options.composition, delayMs };
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: (current) => [boardPlaybackPolicyOperation(current.board.metadata, policy)],
-            }), options);
+            const current = await board.summary();
+            const patch = policy
+                ? { metadataPatch: { playback: policy } }
+                : { metadata: { ...current.board.metadata, playback: undefined } };
+            if (!policy)
+                delete patch.metadata.playback;
+            showUpdated(await mutateSemantic(board, [{ type: "board.patch", patch }], { baseVersion: current.board.version }), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards/context.d.ts

@@ -1,12 +1,28 @@
+import type { BoardClient, BoardSemanticCommand } from "@neta-art/cohub";
 import type { Command } from "commander";
 export type JsonOptions = {
     json?: boolean;
 };
 export declare function withJson(command: Command): Command;
 export declare function finite(value: string | undefined, name: string, fallback?: number): number;
-export declare function resolvedBoard(boards: Command, target: string): Promise<import("@neta-art/cohub").BoardClient>;
+export declare function resolvedBoard(boards: Command, target: string): Promise<BoardClient>;
+/**
+ * Send semantic commands with one automatic version-conflict retry: a racing
+ * edit between our version read and the submit is transparently rebased (same
+ * commands, fresh baseVersion, same id — a retry that lands is idempotent).
+ * `options.baseVersion` lets an agent chain mutations without re-reading the
+ * board between writes.
+ */
+export declare function mutateSemantic(board: BoardClient, commands: BoardSemanticCommand[], options?: {
+    baseVersion?: number;
+    mutationId?: string;
+    dryRun?: boolean;
+}): Promise<import("@neta-art/cohub").BoardMutationReceipt>;
 export declare function showUpdated(result: {
     board: {
         version: number;
     };
+    status?: string;
+    outcome?: string;
+    replayed?: boolean;
 }, options: JsonOptions): void;

package/dist/commands/boards/context.js

@@ -18,8 +18,45 @@ export async function resolvedBoard(boards, target) {
     const boardId = await resolveBoardId(spaceId, target);
     return createClient().space(spaceId).board(boardId);
 }
+/**
+ * Send semantic commands with one automatic version-conflict retry: a racing
+ * edit between our version read and the submit is transparently rebased (same
+ * commands, fresh baseVersion, same id — a retry that lands is idempotent).
+ * `options.baseVersion` lets an agent chain mutations without re-reading the
+ * board between writes.
+ */
+export async function mutateSemantic(board, commands, options = {}) {
+    const baseVersion = options.baseVersion ?? (await board.summary()).board.version;
+    const send = (version) => board.mutateSemantic({
+        mutationId: options.mutationId,
+        baseVersion: version,
+        dryRun: options.dryRun ?? false,
+        commands,
+    });
+    try {
+        return await send(baseVersion);
+    }
+    catch (cause) {
+        if (options.dryRun || !isVersionConflict(cause))
+            throw cause;
+        const retry = (await board.summary()).board.version;
+        return send(retry);
+    }
+}
+function isVersionConflict(error) {
+    return Boolean(error && typeof error === "object" &&
+        error.code === "VERSION_CONFLICT");
+}
 export function showUpdated(result, options) {
     if (jsonRequested(options))
         return json(result);
-    ok(`Board updated to version ${result.board.version}`);
+    if (result.outcome === "dry-run") {
+        ok(`Validated against Board version ${result.board.version}; no changes written`);
+        return;
+    }
+    if (result.outcome === "noop" || result.status === "validated") {
+        ok(`Board already matches the requested state at version ${result.board.version}`);
+        return;
+    }
+    ok(`Board updated to version ${result.board.version}${result.replayed ? " (replayed)" : ""}`);
 }

package/dist/commands/boards/examples.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const BOARD_EXAMPLE_KEYS: string[];
+export declare function boardExample(kind: string, type?: string): unknown;
+export declare function registerBoardExampleCommands(boards: Command): void;