@neta-art/cohub-cli 3.12.0 → 5.0.0

package/dist/commands/boards/examples.js

@@ -0,0 +1,224 @@
+import { json } from "../../output.js";
+const frame = { x: 120, y: 80, width: 320, height: 48, rotation: 0 };
+const templates = {
+    "create": {
+        items: [{
+                id: "title",
+                type: "text",
+                frame,
+                props: { text: "Launch plan", fontSize: 32 },
+                style: { color: "brand" },
+            }],
+        connections: [],
+        effects: [],
+        compositions: [],
+    },
+    "item:text": {
+        id: "title",
+        type: "text",
+        frame,
+        props: { text: "Launch plan", fontSize: 32 },
+        style: { color: "brand" },
+    },
+    "item:image": {
+        id: "hero",
+        type: "image",
+        frame: { x: 120, y: 160, width: 640, height: 360, rotation: 0 },
+        source: { kind: "space-file", path: "assets/hero.webp" },
+        props: {},
+    },
+    "item:geo": {
+        id: "goal",
+        type: "geo",
+        frame: { x: 120, y: 160, width: 280, height: 140, rotation: 0 },
+        props: { shape: "rounded", text: "Ship" },
+        style: { color: "green", fillOpacity: 0.12 },
+    },
+    "item:frame": {
+        id: "scene",
+        type: "frame",
+        frame: { x: 80, y: 60, width: 960, height: 540, rotation: 0 },
+        props: { label: "Scene 1" },
+        style: { color: "neutral" },
+    },
+    "item:draw": {
+        id: "stroke",
+        type: "draw",
+        frame: { x: 100, y: 100, width: 180, height: 100, rotation: 0 },
+        props: { points: [{ x: 0, y: 80, p: 0.5 }, { x: 90, y: 10, p: 0.8 }, { x: 180, y: 70, p: 0.5 }] },
+        style: { color: "violet", strokeWidth: 4 },
+    },
+    "item:arrow": {
+        id: "arrow",
+        type: "arrow",
+        frame: { x: 100, y: 100, width: 260, height: 100, rotation: 0 },
+        props: { start: { x: 116, y: 150 }, end: { x: 344, y: 150 }, bend: 0, arrowStart: false, arrowEnd: true, label: "next" },
+        style: { color: "brand", strokeWidth: 2.5 },
+    },
+    "item:video": {
+        id: "demo-video",
+        type: "video",
+        frame: { x: 120, y: 160, width: 640, height: 360, rotation: 0 },
+        source: { kind: "space-file", path: "assets/demo.mp4" },
+        props: {},
+    },
+    "item:audio": {
+        id: "soundtrack",
+        type: "audio",
+        frame: { x: 120, y: 540, width: 480, height: 96, rotation: 0 },
+        source: { kind: "space-file", path: "assets/soundtrack.mp3" },
+        props: {},
+    },
+    "item:file": {
+        id: "brief",
+        type: "file",
+        frame: { x: 120, y: 160, width: 360, height: 220, rotation: 0 },
+        source: { kind: "space-file", path: "docs/brief.md" },
+        props: {},
+    },
+    "item:task": {
+        id: "task",
+        type: "task",
+        frame: { x: 120, y: 160, width: 420, height: 240, rotation: 0 },
+        props: { taskRunId: "task-run-id", snapshot: { taskType: "generation", status: "running", title: "Generate concept", artifactCount: 0, artifacts: [] } },
+    },
+    "effect:pulse": {
+        id: "pulse-title",
+        target: { type: "item", itemId: "title" },
+        kind: "effects.pulse",
+        kindVersion: 1,
+        enabled: true,
+        lifecycle: "when-visible",
+        timeOrigin: "visible",
+        layer: "front",
+        seed: "pulse-title",
+        params: { amount: 0.04, period: 1600 },
+        assetRefs: [],
+        metadata: {},
+    },
+    "effect:float": {
+        id: "float-hero",
+        target: { type: "item", itemId: "hero" },
+        kind: "effects.float",
+        kindVersion: 1,
+        enabled: true,
+        lifecycle: "when-visible",
+        timeOrigin: "visible",
+        layer: "front",
+        seed: "float-hero",
+        params: { distance: 8, period: 2200 },
+        assetRefs: [],
+        metadata: {},
+    },
+    "composition:fade": {
+        id: "intro",
+        name: "Intro",
+        timeline: {
+            duration: 800,
+            tracks: [{
+                    id: "title-opacity",
+                    target: { type: "item", itemId: "title" },
+                    channel: "style.opacity",
+                    channelVersion: 1,
+                    interpolation: "linear",
+                    fill: "both",
+                    keyframes: [
+                        { time: 0, value: 0 },
+                        { time: 800, value: 1, easing: "ease-out-cubic" },
+                    ],
+                    metadata: {},
+                }],
+            clips: [],
+            markers: [],
+        },
+        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
+        metadata: {},
+    },
+    "composition:reveal": {
+        id: "reveal",
+        name: "Reveal",
+        timeline: {
+            duration: 900,
+            tracks: [{ id: "title-opacity", target: { type: "item", itemId: "title" }, channel: "style.opacity", channelVersion: 1, interpolation: "linear", fill: "both", keyframes: [{ time: 0, value: 0 }, { time: 600, value: 1 }], metadata: {} }],
+            clips: [{ id: "reveal-title", kind: "text.reveal", kindVersion: 1, target: { type: "item", itemId: "title" }, start: 0, duration: 600, layer: "content", fill: "both", easing: "ease-out-cubic", params: { mode: "words" }, assetRefs: [], seed: "reveal-title", metadata: {} }],
+            markers: [],
+        },
+        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
+        metadata: {},
+    },
+    "composition:motion-path": {
+        id: "motion",
+        name: "Motion path",
+        timeline: {
+            duration: 1200,
+            tracks: [],
+            clips: [{ id: "move-hero", kind: "motion.path", kindVersion: 1, target: { type: "item", itemId: "hero" }, start: 0, duration: 1200, layer: "content", fill: "both", easing: "ease-in-out-cubic", params: { points: [{ x: 0, y: 0 }, { x: 160, y: -40 }, { x: 320, y: 0 }], orient: true }, assetRefs: [], seed: "move-hero", metadata: {} }],
+            markers: [],
+        },
+        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
+        metadata: {},
+    },
+    "composition:particles": {
+        id: "celebrate",
+        name: "Celebrate",
+        timeline: {
+            duration: 1000,
+            tracks: [],
+            clips: [{ id: "particles", kind: "effects.particles", kindVersion: 1, target: { type: "board" }, start: 0, duration: 1000, layer: "front", fill: "none", easing: "linear", params: { count: 420, bounds: { x: 0, y: 0, width: 800, height: 600 } }, assetRefs: [], seed: "particles", metadata: {} }],
+            markers: [],
+        },
+        playback: { loop: false, endBehavior: "reset", reducedMotion: { mode: "base" } },
+        metadata: {},
+    },
+    "composition:camera-focus": {
+        id: "tour",
+        name: "Tour",
+        timeline: {
+            duration: 1000,
+            tracks: [],
+            clips: [{
+                    id: "focus-title",
+                    kind: "camera.focus",
+                    kindVersion: 1,
+                    target: { type: "camera" },
+                    start: 0,
+                    duration: 700,
+                    layer: "screen",
+                    fill: "forwards",
+                    easing: "ease-out-cubic",
+                    params: { focus: { type: "item", itemId: "title" }, fit: "contain", padding: 32 },
+                    assetRefs: [],
+                    seed: "focus-title",
+                    metadata: {},
+                }],
+            markers: [],
+        },
+        playback: { loop: false, endBehavior: "hold", reducedMotion: { mode: "base" } },
+        metadata: {},
+    },
+};
+export const BOARD_EXAMPLE_KEYS = Object.keys(templates);
+export function boardExample(kind, type) {
+    const key = type ? `${kind}:${type}` : kind;
+    const template = templates[key];
+    if (!template)
+        throw new Error(`Unknown Board example: ${key}`);
+    return template;
+}
+export function registerBoardExampleCommands(boards) {
+    boards.command("examples <kind> [type]")
+        .description("Print editable semantic JSON templates")
+        .addHelpText("after", `
+Kinds:
+  create
+  item text|image|video|audio|file|task|geo|frame|draw|arrow
+  effect pulse|float
+  composition fade|reveal|motion-path|particles|camera-focus
+
+Examples:
+  cohub boards examples item text > item.json
+  cohub boards examples composition fade > intro.json`)
+        .action((kind, type) => {
+        json(boardExample(kind, type));
+    });
+}

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,140 @@
+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.summary();
+    const mutation = {
+        mutationId: options.mutationId?.trim() || randomUUID(),
+        baseVersion: baseVersion(options.baseVersion, snapshot.board.version),
+        dryRun: Boolean(options.dryRun),
+        commands: [command],
+    };
+    // Server-side validation: schema, version, references, cascade rules — the
+    // same checks the real write would run, just without persisting anything.
+    const receipt = await board.mutateSemantic(mutation);
+    if (jsonRequested(options))
+        return json(receipt);
+    if (options.dryRun) {
+        ok(`Validated against Board version ${receipt.board.version}; no changes written`);
+        return;
+    }
+    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", "Validate on the server (references, version, cascade) without 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();
+            const items = snapshot.items ?? [];
+            if (jsonRequested(options))
+                return json(items);
+            table(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);
+        }
+    });
+}

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

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
 export declare function registerBoardNodeCommands(boards: Command): void;

package/dist/commands/boards/nodes.js

@@ -1,68 +1,12 @@
 import { randomUUID } from "node:crypto";
-import { boardNodeCreateOperation, boardNodeDeleteOperations, boardNodePatchOperation, createBoardConnection, createBoardNode, } from "@neta-art/cohub/board";
-import { BOARD_DOMAIN_INPUT_MAX_BYTES, readBoardJsonObject, } from "../../board-command-support.js";
+import { createBoardConnection } from "@neta-art/cohub/board";
+import { mutateSemantic } from "./context.js";
 import { handleHttp } from "../../output.js";
 import { resolvedBoard, showUpdated, withJson, } from "./context.js";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
 export function registerBoardNodeCommands(boards) {
-    const nodes = boards.command("nodes").description("Create and update Board nodes");
-    withJson(nodes.command("add <board>")
-        .description("Add a node")
-        .requiredOption("-i, --input <file>", "BoardNodeSpec JSON; use - for stdin")
-        .addHelpText("after", `
-Frame x/y/width/height use Board world units. Draw points and arrow endpoints are also world input.
-Minimal text node:
-  {"id":"title","type":"text","frame":{"x":120,"y":80,"width":320,"height":48},"text":"Launch plan"}`))
-        .action(async (target, options) => {
-        try {
-            const input = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            const node = createBoardNode(input);
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({ build: () => [boardNodeCreateOperation(node)] }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(nodes.command("patch <board> <node-id>")
-        .description("Patch a node")
-        .requiredOption("-i, --input <file>", "BoardNodeInput field patch; use - for stdin")
-        .addHelpText("after", `
-x/y are absolute Board world coordinates.
-Move a node without changing its content:
-  {"x":160,"y":120}
-
-Nested view, style, and data fields replace their complete stored object.`))
-        .action(async (target, nodeId, options) => {
-        try {
-            const patch = await readBoardJsonObject(options.input, BOARD_DOMAIN_INPUT_MAX_BYTES);
-            if ("nodeId" in patch)
-                throw new Error("node patch must not contain nodeId");
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [boardNodePatchOperation(nodeId, patch)],
-            }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-    withJson(nodes.command("remove <board> <node-id>")
-        .alias("rm")
-        .description("Remove a node and its connections"))
-        .action(async (target, nodeId, options) => {
-        try {
-            const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                include: ["connections"],
-                build: (current) => boardNodeDeleteOperations(nodeId, current.connections),
-            }), options);
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
     withJson(boards.command("connect <board> <source> <target>")
-        .description("Connect two Board nodes")
+        .description("Connect two Board items")
         .option("--id <id>", "Connection id")
         .option("--relation <relation>", "Relation type")
         .option("--direction <direction>", "none, forward, backward, or both", "forward")
@@ -78,17 +22,15 @@ Nested view, style, and data fields replace their complete stored object.`))
             const board = await resolvedBoard(boards, target);
             const connection = createBoardConnection({
                 id: options.id ?? randomUUID(),
-                sourceNodeId: source,
-                targetNodeId: destination,
+                sourceItemId: source,
+                targetItemId: destination,
                 relation: options.relation,
                 direction: direction,
                 label: options.label,
                 sourcePortId: options.sourcePort,
                 targetPortId: options.targetPort,
             });
-            showUpdated(await board.mutate({
-                build: () => [{ type: "connection.create", payload: { connection } }],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "connection.create", connection }]), options);
         }
         catch (cause) {
             handleHttp(cause);
@@ -99,9 +41,7 @@ Nested view, style, and data fields replace their complete stored object.`))
         .action(async (target, connectionId, options) => {
         try {
             const board = await resolvedBoard(boards, target);
-            showUpdated(await board.mutate({
-                build: () => [{ type: "connection.delete", payload: { connectionId } }],
-            }), options);
+            showUpdated(await mutateSemantic(board, [{ type: "connection.delete", connectionId }]), options);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/boards.d.ts

@@ -1,15 +1,10 @@
-import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
 import type { Command } from "commander";
 import { parseBoardJsonObject } from "../board-command-support.js";
-declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "sequences", "clips", "playback"];
-type InspectSection = (typeof INSPECT_SECTIONS)[number];
 export declare const parseJsonObject: typeof parseBoardJsonObject;
-export declare function readJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;
-export declare function parseInspectSections(value?: string): InspectSection[] | undefined;
-export declare function parseViewport(value?: string): BoardInspectInput["viewport"];
-export declare function createTransactionInput(input: Record<string, unknown>, options: {
-    txId?: string;
-    baseVersion?: string;
-}): BoardTransactionInput;
+export declare function parseViewport(value?: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | undefined;
 export declare function registerBoards(program: Command): Command;
-export {};