@neta-art/cohub-cli 3.12.0 → 5.0.0

package/dist/commands/boards.js

@@ -1,15 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
+import { BOARD_CREATE_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
 import { registerBoardDomainCommands } from "./board-domain.js";
 import { createClient, createRealtimeClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
-const INSPECT_SECTIONS = ["nodes", "connections", "effects", "sequences", "clips", "playback"];
 export const parseJsonObject = parseBoardJsonObject;
-export async function readJsonObject(source, maxBytes = BOARD_TRANSACTION_INPUT_MAX_BYTES) {
-    return readBoardJsonObject(source, maxBytes);
-}
 function parseNumber(value, name, options = {}) {
     if (!value.trim())
         throw new Error(`${name} must be a finite number`);
@@ -24,15 +20,6 @@ function parseNumber(value, name, options = {}) {
         throw new Error(`${name} must be at most ${options.max}`);
     return parsed;
 }
-export function parseInspectSections(value) {
-    if (!value)
-        return undefined;
-    const sections = value.split(",").map((item) => item.trim()).filter(Boolean);
-    const unknown = sections.filter((section) => !INSPECT_SECTIONS.includes(section));
-    if (unknown.length > 0)
-        throw new Error(`Unknown Board section: ${unknown.join(", ")}`);
-    return [...new Set(sections)];
-}
 export function parseViewport(value) {
     if (!value)
         return undefined;
@@ -51,47 +38,11 @@ export function parseViewport(value) {
         throw new Error("viewport width and height must be greater than zero");
     return { x, y, width, height };
 }
-export function createTransactionInput(input, options) {
-    if ("boardId" in input)
-        throw new Error("transaction input must not contain boardId");
-    if (!Array.isArray(input.operations))
-        throw new Error("transaction input must contain an operations array");
-    const rawBaseVersion = options.baseVersion ?? input.baseVersion;
-    if (rawBaseVersion === undefined)
-        throw new Error("baseVersion is required in input or --base-version");
-    const baseVersion = parseNumber(String(rawBaseVersion), "baseVersion", { min: 0, integer: true });
-    const rawTxId = options.txId ?? input.txId;
-    if (rawTxId !== undefined && (typeof rawTxId !== "string" || !rawTxId.trim())) {
-        throw new Error("txId must be a non-empty string");
-    }
-    return {
-        ...input,
-        txId: typeof rawTxId === "string" ? rawTxId : randomUUID(),
-        baseVersion,
-        operations: input.operations,
-    };
-}
-function showBoard(result) {
-    table([
-        {
-            id: result.board.id,
-            title: result.board.title,
-            version: result.board.version,
-            nodes: result.nodes.length,
-            connections: result.connections.length,
-            effects: result.effects.length,
-            sequences: result.sequences.length,
-            clips: result.clips.length,
-        },
-    ], [
+function showCreated(result) {
+    table([result.board], [
         { key: "id", label: "ID" },
         { key: "title", label: "Title" },
         { key: "version", label: "Version" },
-        { key: "nodes", label: "Nodes" },
-        { key: "connections", label: "Connections" },
-        { key: "effects", label: "Effects" },
-        { key: "sequences", label: "Sequences" },
-        { key: "clips", label: "Clips" },
     ]);
 }
 function showSummary(result) {
@@ -107,35 +58,18 @@ function showSummary(result) {
         { key: "id", label: "ID" },
         { key: "title", label: "TITLE" },
         { key: "version", label: "VERSION" },
-        { key: "nodes", label: "NODES" },
+        { key: "items", label: "ITEMS" },
         { key: "connections", label: "CONNECTIONS" },
         { key: "effects", label: "EFFECTS" },
-        { key: "sequences", label: "SEQUENCES" },
+        { key: "compositions", label: "COMPOSITIONS" },
         { key: "background", label: "BACKGROUND" },
         { key: "updatedAt", label: "UPDATED" },
     ]);
 }
-function showValidation(result) {
-    table([{ valid: result.valid, diagnostics: result.diagnostics.length }], [
-        { key: "valid", label: "Valid" },
-        { key: "diagnostics", label: "Diagnostics" },
-    ]);
-    if (result.diagnostics.length > 0) {
-        console.log();
-        table(result.diagnostics, [
-            { key: "severity", label: "Severity" },
-            { key: "code", label: "Code" },
-            { key: "path", label: "Path" },
-            { key: "message", label: "Message" },
-        ]);
-    }
-    console.log();
-    table([result.peakCost], Object.keys(result.peakCost).map((key) => ({ key, label: key })));
-}
 function showPlayback(result) {
     table([result], [
         { key: "playbackId", label: "Playback ID" },
-        { key: "sequenceId", label: "Sequence" },
+        { key: "compositionId", label: "Composition" },
         { key: "status", label: "Status" },
         { key: "position", label: "Position" },
         { key: "timeScale", label: "Time Scale" },
@@ -158,38 +92,6 @@ function capabilityUnits(schema) {
         return detail ? [`${field}:${detail}`] : [];
     }).join(", ");
 }
-function registerTransactionCommand(boards, name) {
-    withJson(boards.command(`${name} <board>`)
-        .description(name === "validate" ? "Validate a transaction" : "Apply a transaction")
-        .requiredOption("-i, --input <file>", "Transaction JSON file; use - for stdin")
-        .option("--tx-id <id>", "Override txId; generated when omitted")
-        .option("--base-version <version>", "Override baseVersion")
-        .addHelpText("after", `
-Input example:
-  {"baseVersion":12,"operations":[{"type":"board.patch","payload":{"patch":{"title":"Launch plan"}}}]}
-
-Prefer semantic commands such as boards background, nodes, effects, or sequences for common edits.`))
-        .action(async (target, options) => {
-        try {
-            const transaction = createTransactionInput(await readJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES), options);
-            const spaceId = resolveSpace(boards);
-            const boardId = await resolveBoardId(spaceId, target);
-            const board = createClient().space(spaceId).board(boardId);
-            const result = await board[name](transaction);
-            if (jsonRequested(options))
-                return outJson(result);
-            if (name === "validate")
-                showValidation(result);
-            else {
-                ok(`Board updated to version ${result.board.version}`);
-                showBoard(result);
-            }
-        }
-        catch (cause) {
-            handleHttp(cause);
-        }
-    });
-}
 function commandId(options) {
     return options.commandId?.trim() || randomUUID();
 }
@@ -315,14 +217,16 @@ export function registerBoards(program) {
         .description("Create a Board")
         .option("--title <title>", "Board title")
         .option("--mutation-id <id>", "Stable id for safe retries")
-        .option("-i, --input <file>", "BoardCreateInput fields; use - for stdin")
+        .option("-i, --input <file>", "Semantic Board seed JSON; use - for stdin")
         .addHelpText("after", `
-For normal use, create an empty Board and add content with boards nodes, effects, and sequences.
---input is intended for bulk creation and accepts BoardCreateInput fields except path and title.`))
+Create an empty Board, or provide items, connections, effects, compositions, and metadata in --input.
+Generate an editable seed:
+  cohub boards examples create > board.json
+  cohub boards create plan.board -i board.json`))
         .action(async (path, options) => {
         try {
             const content = options.input
-                ? await readJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
+                ? await readBoardJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
                 : {};
             if ("path" in content || "title" in content) {
                 throw new Error("create input must not contain path or title; use the command argument and --title");
@@ -338,7 +242,7 @@ For normal use, create an empty Board and add content with boards nodes, effects
             if (jsonRequested(options))
                 return outJson(result);
             ok(`Board created: ${result.board.id}`);
-            showBoard(result);
+            showCreated(result);
         }
         catch (cause) {
             handleHttp(cause);
@@ -346,31 +250,30 @@ For normal use, create an empty Board and add content with boards nodes, effects
     });
     withJson(boards.command("inspect <board>")
         .alias("get")
-        .description("Inspect a Board")
-        .option("--include <sections>", "Comma-separated nodes,connections,effects,sequences,clips,playback")
-        .option("--viewport <rect>", "Viewport as x,y,width,height"))
+        .description("Show Board metadata and semantic resource counts")
+        .addHelpText("after", `
+Inspect content with:
+  cohub boards items list <board> --json
+  cohub boards effects list <board> --json
+  cohub boards compositions list <board> --json`))
         .action(async (target, options) => {
         try {
             const spaceId = resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
-            const board = createClient().space(spaceId).board(boardId);
-            if (!jsonRequested(options) && !options.include && !options.viewport) {
-                return showSummary(await board.summary());
-            }
-            const result = await board.inspect({
-                include: parseInspectSections(options.include),
-                viewport: parseViewport(options.viewport),
-            });
+            const result = await createClient().space(spaceId).board(boardId).summary();
             if (jsonRequested(options))
                 return outJson(result);
-            showBoard(result);
+            showSummary(result);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
     withJson(boards.command("capabilities <board>")
-        .description("Show supported capabilities"))
+        .description("Show authoring schemas and runtime capabilities")
+        .addHelpText("after", `
+Use --json for complete Item, patch, mutation, effect, Composition, and create JSON Schemas.
+Use boards examples for editable starter JSON.`))
         .action(async (target, options) => {
         try {
             const spaceId = resolveSpace(boards);
@@ -390,46 +293,41 @@ For normal use, create an empty Board and add content with boards nodes, effects
                 { key: "coordinates", label: "Coordinates / units" },
                 { key: "digest", label: "Digest" },
             ]);
-            const nodes = result.nodes;
-            if (nodes) {
-                console.log();
-                table([{
-                        types: nodes.types.join(", "),
-                        colors: nodes.colors.join(", "),
-                        geos: nodes.geos.join(", "),
-                        drawPoints: nodes.coordinates.drawPoints,
-                        arrowEndpoints: nodes.coordinates.arrowEndpoints,
-                    }], [
-                    { key: "types", label: "Node types" },
-                    { key: "colors", label: "Colors" },
-                    { key: "geos", label: "Geo kinds" },
-                    { key: "drawPoints", label: "Draw points" },
-                    { key: "arrowEndpoints", label: "Arrow endpoints" },
-                ]);
-            }
+            console.log();
+            table([{
+                    types: result.items.types.join(", "),
+                    colors: result.items.colors.join(", "),
+                    shapes: result.items.shapes.join(", "),
+                    drawPoints: result.items.coordinates.drawPoints,
+                    arrowEndpoints: result.items.coordinates.arrowEndpoints,
+                }], [
+                { key: "types", label: "Item types" },
+                { key: "colors", label: "Colors" },
+                { key: "shapes", label: "Shapes" },
+                { key: "drawPoints", label: "Draw points" },
+                { key: "arrowEndpoints", label: "Arrow endpoints" },
+            ]);
         }
         catch (cause) {
             handleHttp(cause);
         }
     });
-    registerTransactionCommand(boards, "validate");
-    registerTransactionCommand(boards, "apply");
     registerBoardDomainCommands(boards);
     registerExportCommand(boards);
-    withJson(boards.command("play <board> <sequence-id>")
+    withJson(boards.command("play <board> <composition-id>")
         .description("Start shared playback")
         .option("--position <time>", "Initial position in milliseconds")
         .option("--time-scale <scale>", "Playback speed from 0 to 4")
         .option("--seed <seed>", "Deterministic playback seed")
         .option("--command-id <id>", "Idempotency command ID"))
-        .action(async (target, sequenceId, options) => {
+        .action(async (target, compositionId, options) => {
         try {
             const spaceId = resolveSpace(boards);
             const boardId = await resolveBoardId(spaceId, target);
             const result = await createClient().space(spaceId).board(boardId).play({
                 commandId: commandId(options),
                 type: "play",
-                sequenceId,
+                compositionId,
                 shared: true,
                 ...(options.position === undefined ? {} : { position: parseNumber(options.position, "position", { min: 0 }) }),
                 ...(options.timeScale === undefined ? {} : { timeScale: parseNumber(options.timeScale, "timeScale", { min: Number.EPSILON, max: 4 }) }),
@@ -516,13 +414,13 @@ For normal use, create an empty Board and add content with boards nodes, effects
                         process.stdout.write(`${JSON.stringify(event)}\n`);
                         return;
                     }
-                    if (event.type === "board.transaction.applied") {
-                        process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
+                    if (event.type === "board.changed") {
+                        process.stdout.write(`version ${event.payload.version}  mutation ${event.payload.mutationId}\n`);
                     }
                     else if (event.type === "board.playback.changed") {
-                        process.stdout.write(`${event.payload.status}  sequence ${event.payload.sequenceId}  position ${event.payload.position}\n`);
+                        process.stdout.write(`${event.payload.status}  composition ${event.payload.compositionId}  position ${event.payload.position}\n`);
                     }
-                    else {
+                    else if (event.type === "board.awareness.updated") {
                         process.stdout.write(`awareness ${event.payload.actorName}  ${event.payload.update.type}\n`);
                     }
                 },

package/dist/commands/cron-jobs.js

@@ -9,7 +9,7 @@ function readJsonObject(pathOrJson) {
     return parsed;
 }
 export function registerCronJobs(program) {
-    const cmd = program.command("cron-jobs", { hidden: true }).description("Scheduled jobs");
+    const cmd = program.command("cron-jobs").description("Scheduled jobs");
     cmd
         .command("ls [spaceId]")
         .alias("list")

package/dist/commands/tasks.js

@@ -2,7 +2,7 @@ import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, handleHttp } from "../output.js";
 export function registerTasks(program, dependencies = {}) {
     const getClient = dependencies.createClient ?? createClient;
-    const cmd = program.command("tasks", { hidden: true }).description("Task runs");
+    const cmd = program.command("tasks").description("Task runs");
     cmd
         .command("ls")
         .alias("list")

package/dist/commands/works.js

@@ -259,7 +259,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--meta <json>", "Work metadata as a JSON object")
         .option("--hide-cohub-bar", "Hide the Cohub footer bar on the public work page")
         .option("--show-cohub-bar", "Show the Cohub footer bar on the public work page")
@@ -338,7 +338,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--clear-work-scopes", "Clear work runtime scopes")
         .option("--clear-viewer-scopes", "Clear viewer-requestable scopes")
         .option("--meta <json>", "Work metadata as a JSON object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.12.0",
+  "version": "5.0.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.19.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "5.10.0"
+    "@neta-art/cohub": "7.0.0"
   },
   "publishConfig": {
     "access": "public"