@neta-art/cohub-cli 3.11.0 → 4.0.0

package/dist/board-command-support.d.ts

@@ -0,0 +1,7 @@
+export declare const BOARD_TRANSACTION_INPUT_MAX_BYTES: number;
+export declare const BOARD_CREATE_INPUT_MAX_BYTES: number;
+export declare const BOARD_DOMAIN_INPUT_MAX_BYTES: number;
+export declare function parseBoardJsonObject(text: string, source?: string): Record<string, unknown>;
+export declare function readBoardJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;
+export declare function resolveBoardId(spaceId: string, target: string): Promise<string>;
+export declare function writeBoardOutput(path: string, bytes: Uint8Array, force?: boolean): Promise<void>;

package/dist/board-command-support.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, link, open, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { isBoardPath, parseBoardManifest, } from "@neta-art/cohub/board";
+import { createClient } from "./client.js";
+export const BOARD_TRANSACTION_INPUT_MAX_BYTES = 16 * 1024 * 1024;
+export const BOARD_CREATE_INPUT_MAX_BYTES = 32 * 1024 * 1024;
+export const BOARD_DOMAIN_INPUT_MAX_BYTES = 1024 * 1024;
+export function parseBoardJsonObject(text, source = "input") {
+    if (!text.trim())
+        throw new Error(`${source} is empty`);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new Error(`${source} must contain valid JSON`, { cause });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${source} must contain a JSON object`);
+    }
+    return value;
+}
+async function readStdinBounded(maxBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.byteLength;
+        if (size > maxBytes)
+            throw new Error(`stdin exceeds the ${maxBytes} byte input limit`);
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readBoardJsonObject(source, maxBytes = BOARD_DOMAIN_INPUT_MAX_BYTES) {
+    if (source === "-")
+        return parseBoardJsonObject(await readStdinBounded(maxBytes), "stdin");
+    const handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error(`${source} must be a regular file`);
+        if (info.size > maxBytes)
+            throw new Error(`${source} exceeds the ${maxBytes} byte input limit`);
+        const chunks = [];
+        const buffer = Buffer.allocUnsafe(Math.max(1, Math.min(64 * 1024, maxBytes + 1)));
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+            if (size > maxBytes)
+                throw new Error(`${source} exceeds the ${maxBytes} byte input limit`);
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+        return parseBoardJsonObject(Buffer.concat(chunks).toString("utf8"), source);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function resolveBoardId(spaceId, target) {
+    if (!isBoardPath(target))
+        return target;
+    const file = await createClient().space(spaceId).files.read(target);
+    if (!("content" in file) || typeof file.content !== "string") {
+        throw new Error(`${target} is not a readable Board manifest`);
+    }
+    return parseBoardManifest(file.content).boardId;
+}
+export async function writeBoardOutput(path, bytes, force = false) {
+    if (!force) {
+        await access(path).then(() => { throw new Error(`Output already exists: ${path}; use --force to replace it`); }, () => undefined);
+    }
+    const temp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temp, "wx");
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (force)
+            await rename(temp, path);
+        else {
+            await link(temp, path);
+            await unlink(temp);
+        }
+    }
+    catch (cause) {
+        await unlink(temp).catch(() => undefined);
+        throw cause;
+    }
+}

package/dist/board-export.js

@@ -9,9 +9,11 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, isBoardPath, parseBoardManifest, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+import { boardBootstrapToDocument, 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";
+import { downloadPublicImage } from "./safe-remote-image.js";
 export const BOARD_EXPORT_FORMATS = ["png", "jpeg", "webp"];
 /** Infer the output format from the file extension, defaulting to PNG. */
 export function formatFromPath(path) {
@@ -61,9 +63,7 @@ export function resolveBundledFonts() {
  */
 export async function loadBoardDocument(spaceId, target) {
     const client = createClient();
-    const boardId = isBoardPath(target)
-        ? await resolveManifestBoardId(spaceId, target)
-        : target;
+    const boardId = await resolveBoardId(spaceId, target);
     const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
     return {
         document: boardBootstrapToDocument(bootstrap),
@@ -71,13 +71,6 @@ export async function loadBoardDocument(spaceId, target) {
         title: bootstrap.board.title ?? null,
     };
 }
-async function resolveManifestBoardId(spaceId, path) {
-    const file = await createClient().space(spaceId).files.read(path);
-    if (!("content" in file) || typeof file.content !== "string") {
-        throw new Error(`${path} is not a readable board manifest.`);
-    }
-    return parseBoardManifest(file.content).boardId;
-}
 /**
  * Fetch every image in `items`, keyed the way the renderers ask for it.
  *
@@ -92,7 +85,7 @@ export async function loadBoardTextures(headless, spaceId, items, options = {})
     const textures = new Map();
     const failed = [];
     const pending = [...selection.keys];
-    const concurrency = Math.max(1, Math.min(options.concurrency ?? 6, 16));
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 4, 16));
     const client = createClient();
     async function worker() {
         for (;;) {
@@ -107,7 +100,7 @@ export async function loadBoardTextures(headless, spaceId, items, options = {})
             try {
                 const { bytes, mimeType } = source.kind === "file"
                     ? await readSpaceFileBytes(client, spaceId, source.value)
-                    : await readUrlBytes(source.value);
+                    : await downloadPublicImage(source.value);
                 const texture = await headless.decodeImage(bytes, mimeType);
                 textures.set(key, texture);
             }
@@ -123,15 +116,6 @@ async function readSpaceFileBytes(client, spaceId, path) {
     const { blob, mimeType } = await client.space(spaceId).files.download(path);
     return { bytes: new Uint8Array(await blob.arrayBuffer()), mimeType };
 }
-async function readUrlBytes(url) {
-    const response = await fetch(url);
-    if (!response.ok)
-        throw new Error(`HTTP ${response.status}`);
-    return {
-        bytes: new Uint8Array(await response.arrayBuffer()),
-        mimeType: response.headers.get("content-type") ?? "image/png",
-    };
-}
 /** Render a board to image bytes. Returns null when the region is empty. */
 export async function runBoardExport(options) {
     const { document } = await loadBoardDocument(options.spaceId, options.target);
@@ -149,6 +133,7 @@ export async function runBoardExport(options) {
     try {
         const warnings = [];
         let textures;
+        let backgroundTexture;
         let omittedKeys = new Set();
         if (options.withImages) {
             const loaded = await loadBoardTextures(headless, options.spaceId, plan.items);
@@ -161,6 +146,19 @@ export async function runBoardExport(options) {
                 warnings.push(`${loaded.omitted.length} previews were drawn as placeholders to stay within the export texture limit.`);
             }
         }
+        const declaredBackground = document.appearance.background;
+        if (options.withImages &&
+            options.background === "paper" &&
+            declaredBackground.kind === "image" &&
+            declaredBackground.imageUrl) {
+            try {
+                const { bytes, mimeType } = await downloadPublicImage(declaredBackground.imageUrl);
+                backgroundTexture = await headless.decodeImage(bytes, mimeType);
+            }
+            catch {
+                warnings.push("The board background image could not be loaded; the fallback color was exported.");
+            }
+        }
         const videoCount = plan.items.filter((item) => item.type === "video").length;
         if (videoCount > 0) {
             warnings.push(`${videoCount} video preview${videoCount === 1 ? " was" : "s were"} drawn as placeholders; headless video decoding is unavailable.`);
@@ -172,6 +170,14 @@ export async function runBoardExport(options) {
             colorScheme: options.colorScheme,
             background: options.background,
             textures,
+            backgroundImage: backgroundTexture
+                ? {
+                    texture: backgroundTexture,
+                    fit: declaredBackground.fit ?? "cover",
+                    position: declaredBackground.position ?? "center",
+                    opacity: declaredBackground.opacity ?? 1,
+                }
+                : undefined,
             ...(options.withImages
                 ? {
                     assetKey: (item) => {

package/dist/commands/board-domain.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardDomainCommands(boards: Command): void;

package/dist/commands/board-domain.js

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

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

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardAnimationCommands(boards: Command): void;

package/dist/commands/boards/animation.js

@@ -0,0 +1,145 @@
+import { boardCompositionApplyOperation, boardCompositionDeleteOperation, boardEffectDeleteOperation, boardEffectUpsertOperation, } from "@neta-art/cohub/board";
+import { BoardEffectSchema, 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 { 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"] });
+            if (jsonRequested(options))
+                return json(result.effects);
+            table(result.effects, [
+                { key: "id", label: "ID" },
+                { key: "kind", label: "KIND" },
+                { key: "enabled", label: "ENABLED" },
+                { key: "layer", label: "LAYER" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(effects.command("apply <board>")
+        .description("Atomically create or replace an effect")
+        .requiredOption("-i, --input <file>", "Board effect JSON; use - for stdin"))
+        .action(async (target, options) => {
+        try {
+            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            const effect = BoardEffectSchema.omit({ boardId: true, revision: true }).parse(input);
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardEffectUpsertOperation(effect)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(effects.command("delete <board> <effect-id>").alias("rm").description("Delete an effect"))
+        .action(async (target, effectId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardEffectDeleteOperation(effectId)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    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: ["compositions"] });
+            if (jsonRequested(options))
+                return json(result.compositions);
+            table(result.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" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    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: ["compositions"] });
+            const composition = result.compositions.find((item) => item.id === compositionId);
+            if (!composition)
+                throw new Error(`Composition not found: ${compositionId}`);
+            if (jsonRequested(options))
+                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" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(compositions.command("apply <board>")
+        .description("Atomically create or replace a composition")
+        .requiredOption("-i, --input <file>", "BoardComposition JSON; use - for stdin")
+        .addHelpText("after", `
+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.
+
+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: () => [boardCompositionApplyOperation(composition)],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    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: () => [boardCompositionDeleteOperation(compositionId)],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardAppearanceCommands(boards: Command): void;

package/dist/commands/boards/appearance.js

@@ -0,0 +1,92 @@
+import { BoardAppearanceSchema, DEFAULT_BOARD_APPEARANCE, boardAppearanceOperation, boardPlaybackPolicyOperation, boardTitleOperation, patchBoardAppearance, } from "@neta-art/cohub/board";
+import { handleHttp } from "../../output.js";
+import { finite, resolvedBoard, showUpdated, withJson, } from "./context.js";
+function appearanceFrom(metadata) {
+    const parsed = BoardAppearanceSchema.safeParse(metadata.appearance);
+    return parsed.success ? parsed.data : DEFAULT_BOARD_APPEARANCE;
+}
+export function registerBoardAppearanceCommands(boards) {
+    withJson(boards.command("rename <board> <title>").description("Rename a Board"))
+        .action(async (target, title, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({ build: () => [boardTitleOperation(title)] }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("background <board>")
+        .description("Configure the Board background")
+        .option("--color <color>", "Solid CSS color")
+        .option("--image <url>", "Public image URL")
+        .option("--fit <mode>", "cover, contain, or repeat", "cover")
+        .option("--position <position>", "center, top, bottom, left, or right", "center")
+        .option("--opacity <value>", "Image opacity from 0 to 1", "1")
+        .option("--reset", "Restore the default background")
+        .addHelpText("after", `
+Examples:
+  cohub boards background plan.board --color "#123456"
+  cohub boards background plan.board --image https://example.com/bg.webp --fit cover --opacity 0.8`))
+        .action(async (target, options) => {
+        try {
+            const selected = [options.color, options.image, options.reset ? "reset" : undefined].filter(Boolean);
+            if (selected.length !== 1)
+                throw new Error("Choose one of --color, --image, or --reset");
+            if (!["cover", "contain", "repeat"].includes(options.fit))
+                throw new Error("--fit must be cover, contain, or repeat");
+            if (!["center", "top", "bottom", "left", "right"].includes(options.position))
+                throw new Error("--position must be center, top, bottom, left, or right");
+            const opacity = finite(options.opacity, "opacity");
+            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 }))];
+                },
+            });
+            showUpdated(result, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("playback-policy <board>")
+        .description("Configure automatic Board playback")
+        .option("--composition <id>", "Composition to play")
+        .option("--delay <ms>", "Delay before playback", "0")
+        .option("--clear", "Remove the playback policy"))
+        .action(async (target, options) => {
+        try {
+            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
+                : { compositionId: options.composition, delayMs };
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                build: (current) => [boardPlaybackPolicyOperation(current.board.metadata, policy)],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

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

@@ -0,0 +1,12 @@
+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 showUpdated(result: {
+    board: {
+        version: number;
+    };
+}, options: JsonOptions): void;

package/dist/commands/boards/context.js

@@ -0,0 +1,25 @@
+import { createClient } from "../../client.js";
+import { resolveBoardId } from "../../board-command-support.js";
+import { json, jsonRequested, ok } from "../../output.js";
+import { resolveSpace } from "../../space.js";
+export function withJson(command) {
+    return command.option("--json", "Output as JSON");
+}
+export function finite(value, name, fallback) {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    const result = Number(value);
+    if (!Number.isFinite(result))
+        throw new Error(`${name} must be a finite number`);
+    return result;
+}
+export async function resolvedBoard(boards, target) {
+    const spaceId = resolveSpace(boards);
+    const boardId = await resolveBoardId(spaceId, target);
+    return createClient().space(spaceId).board(boardId);
+}
+export function showUpdated(result, options) {
+    if (jsonRequested(options))
+        return json(result);
+    ok(`Board updated to version ${result.board.version}`);
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerBoardItemCommands(boards: Command): void;

package/dist/commands/boards/items.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { BoardAuthoringItemSchema, BoardItemPatchSchema, } from "@neta-art/cohub";
+import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { handleHttp, json, jsonRequested, ok, table } from "../../output.js";
+import { resolvedBoard, withJson, } from "./context.js";
+const baseVersion = (value, fallback) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new Error("base version must be a non-negative integer");
+    }
+    return parsed;
+};
+async function execute(boards, target, command, options) {
+    const board = await resolvedBoard(boards, target);
+    const snapshot = await board.authoring();
+    const mutation = {
+        mutationId: options.mutationId?.trim() || randomUUID(),
+        baseVersion: baseVersion(options.baseVersion, snapshot.board.version),
+        commands: [command],
+    };
+    if (options.dryRun) {
+        const result = {
+            mutationId: mutation.mutationId,
+            status: "prepared",
+            board: { id: snapshot.board.id, version: snapshot.board.version },
+            commands: mutation.commands,
+        };
+        if (jsonRequested(options))
+            return json(result);
+        ok(`Prepared against Board version ${snapshot.board.version}; no server validation or write performed`);
+        return;
+    }
+    const receipt = await board.mutateSemantic(mutation);
+    if (jsonRequested(options))
+        return json(receipt);
+    ok(`${receipt.replayed ? "Replayed" : "Applied"} mutation at Board version ${receipt.board.version}`);
+}
+function mutationOptions(command) {
+    return withJson(command)
+        .option("--base-version <version>", "Expected Board version; defaults to latest")
+        .option("--mutation-id <id>", "Stable id for safe retries")
+        .option("--dry-run", "Prepare locally without server validation or writing");
+}
+export function registerBoardItemCommands(boards) {
+    const items = boards.command("items").description("Author Board items with semantic JSON");
+    withJson(items.command("list <board>").alias("ls").description("List semantic Board items"))
+        .action(async (target, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            const snapshot = await board.authoring();
+            if (jsonRequested(options))
+                return json(snapshot.items);
+            table(snapshot.items.map((item) => ({
+                id: item.id,
+                type: item.type,
+                x: item.frame.x,
+                y: item.frame.y,
+                width: item.frame.width,
+                height: item.frame.height,
+            })), [
+                { key: "id", label: "ID" },
+                { key: "type", label: "TYPE" },
+                { key: "x", label: "X" },
+                { key: "y", label: "Y" },
+                { key: "width", label: "WIDTH" },
+                { key: "height", label: "HEIGHT" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("create <board>")
+        .description("Create one item")
+        .requiredOption("-i, --input <file>", "Board Item JSON; use - for stdin")
+        .addHelpText("after", `
+Minimal text item:
+  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48,"rotation":0},"props":{"text":"Launch plan","fontSize":32},"style":{"color":"brand"}}`))
+        .action(async (target, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.create",
+                item: BoardAuthoringItemSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("patch <board> <item-id>")
+        .description("Recursively merge item fields")
+        .requiredOption("-i, --input <file>", "Board Item patch JSON; use - for stdin")
+        .addHelpText("after", `
+Objects merge recursively, arrays replace, and null clears optional fields.
+Move and rename a text item without replacing its size or font:
+  {"frame":{"x":160,"y":120},"props":{"text":"Updated"}}`))
+        .action(async (target, itemId, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.patch",
+                itemId,
+                patch: BoardItemPatchSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("replace <board> <item-id>")
+        .description("Replace one complete item")
+        .requiredOption("-i, --input <file>", "Complete Board Item JSON; use - for stdin"))
+        .action(async (target, itemId, options) => {
+        try {
+            const value = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
+            await execute(boards, target, {
+                type: "item.replace",
+                itemId,
+                item: BoardAuthoringItemSchema.parse(value),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    mutationOptions(items.command("delete <board> <item-id>").alias("rm")
+        .description("Delete one item")
+        .option("--cascade", "Atomically remove relations, effects, and animation references"))
+        .action(async (target, itemId, options) => {
+        try {
+            await execute(boards, target, {
+                type: "item.delete",
+                itemId,
+                cascade: Boolean(options.cascade),
+            }, options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}