@neta-art/cohub-cli 2.7.0 → 3.0.0

package/README.md

@@ -121,6 +121,55 @@ cohub -s <spaceId> spaces sessions rename <sessionId> "<new title>"
 
 Use `spaces prompt --session <sessionId>` to send to a Chat.
 
+## Boards
+
+Board commands use the selected Space and support `-h` at every level:
+
+```bash
+cohub boards -h
+cohub boards inspect -h
+cohub -s <spaceId> boards create boards/plan.board --title "Plan"
+cohub -s <spaceId> boards inspect <boardId> --json
+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:
+
+```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" } }
+    }
+  ]
+}
+```
+
+```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 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/client.d.ts

@@ -1,2 +1,3 @@
-import { CohubHttpClient } from "@neta-art/cohub";
+import { CohubClient, CohubHttpClient } from "@neta-art/cohub";
 export declare function createClient(): CohubHttpClient;
+export declare function createRealtimeClient(): CohubClient;

package/dist/client.js

@@ -1,11 +1,15 @@
-import { CohubHttpClient, readRequestSourceFromEnv } from "@neta-art/cohub";
+import { CohubClient, CohubHttpClient, readRequestSourceFromEnv } from "@neta-art/cohub";
 import { clearAuthSession, resolveAccessToken } from "./auth.js";
+const clientOptions = () => ({
+    getAccessToken: resolveAccessToken,
+    onUnauthorized: clearAuthSession,
+    requestSource: () => readRequestSourceFromEnv(process.env, { via: "cli" }) ?? {
+        via: "cli",
+    },
+});
 export function createClient() {
-    return new CohubHttpClient({
-        getAccessToken: resolveAccessToken,
-        onUnauthorized: clearAuthSession,
-        requestSource: () => readRequestSourceFromEnv(process.env, { via: "cli" }) ?? {
-            via: "cli",
-        },
-    });
+    return new CohubHttpClient(clientOptions());
+}
+export function createRealtimeClient() {
+    return new CohubClient(clientOptions());
 }

package/dist/commands/boards.d.ts

@@ -0,0 +1,14 @@
+import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
+import type { Command } from "commander";
+declare const INSPECT_SECTIONS: readonly ["nodes", "effects", "sequences", "clips", "playback"];
+type InspectSection = (typeof INSPECT_SECTIONS)[number];
+export declare function parseJsonObject(text: string, source?: string): Record<string, unknown>;
+export declare function readJsonObject(source: string): 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 registerBoards(program: Command): Command;
+export {};

package/dist/commands/boards.js

@@ -0,0 +1,336 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createClient, createRealtimeClient } from "../client.js";
+import { handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
+import { resolveSpace } from "../space.js";
+const INSPECT_SECTIONS = ["nodes", "effects", "sequences", "clips", "playback"];
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export function parseJsonObject(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 (!isObject(value))
+        throw new Error(`${source} must contain a JSON object`);
+    return value;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readJsonObject(source) {
+    const text = source === "-" ? await readStdin() : await readFile(source, "utf8");
+    return parseJsonObject(text, source === "-" ? "stdin" : source);
+}
+function parseNumber(value, name, options = {}) {
+    if (!value.trim())
+        throw new Error(`${name} must be a finite number`);
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${name} must be a finite number`);
+    if (options.integer && !Number.isSafeInteger(parsed))
+        throw new Error(`${name} must be an integer`);
+    if (options.min !== undefined && parsed < options.min)
+        throw new Error(`${name} must be at least ${options.min}`);
+    if (options.max !== undefined && parsed > options.max)
+        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;
+    const parts = value.split(",").map((part) => part.trim());
+    if (parts.length !== 4)
+        throw new Error("viewport must be x,y,width,height");
+    const [xValue, yValue, widthValue, heightValue] = parts;
+    if (xValue === undefined || yValue === undefined || widthValue === undefined || heightValue === undefined) {
+        throw new Error("viewport must be x,y,width,height");
+    }
+    const x = parseNumber(xValue, "viewport x");
+    const y = parseNumber(yValue, "viewport y");
+    const width = parseNumber(widthValue, "viewport width");
+    const height = parseNumber(heightValue, "viewport height");
+    if (width <= 0 || height <= 0)
+        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,
+            effects: result.effects.length,
+            sequences: result.sequences.length,
+            clips: result.clips.length,
+        },
+    ], [
+        { key: "id", label: "ID" },
+        { key: "title", label: "Title" },
+        { key: "version", label: "Version" },
+        { key: "nodes", label: "Nodes" },
+        { key: "effects", label: "Effects" },
+        { key: "sequences", label: "Sequences" },
+        { key: "clips", label: "Clips" },
+    ]);
+}
+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: "status", label: "Status" },
+        { key: "position", label: "Position" },
+        { key: "timeScale", label: "Time Scale" },
+    ]);
+}
+function withJson(command) {
+    return command.option("--json", "Output as JSON");
+}
+function registerTransactionCommand(boards, name) {
+    withJson(boards.command(`${name} <board-id>`)
+        .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"))
+        .action(async (boardId, options) => {
+        try {
+            const transaction = createTransactionInput(await readJsonObject(options.input), options);
+            const board = createClient().space(resolveSpace(boards)).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();
+}
+export function registerBoards(program) {
+    const boards = program
+        .command("boards")
+        .description("Inspect and update Boards")
+        .hook("preAction", () => { resolveSpace(boards); });
+    withJson(boards.command("create <path>")
+        .description("Create a Board")
+        .option("--title <title>", "Board title")
+        .option("-i, --input <file>", "Board content JSON file; use - for stdin"))
+        .action(async (path, options) => {
+        try {
+            const content = options.input ? await readJsonObject(options.input) : {};
+            if ("path" in content || "title" in content) {
+                throw new Error("create input must not contain path or title; use the command argument and --title");
+            }
+            const input = { ...content, path, ...(options.title ? { title: options.title } : {}) };
+            const result = await createClient().space(resolveSpace(boards)).boards.create(input);
+            if (jsonRequested(options))
+                return outJson(result);
+            ok(`Board created: ${result.board.id}`);
+            showBoard(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("inspect <board-id>")
+        .alias("get")
+        .description("Inspect a Board")
+        .option("--include <sections>", "Comma-separated nodes,effects,sequences,clips,playback")
+        .option("--viewport <rect>", "Viewport as x,y,width,height"))
+        .action(async (boardId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).inspect({
+                include: parseInspectSections(options.include),
+                viewport: parseViewport(options.viewport),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showBoard(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("capabilities <board-id>")
+        .description("Show supported capabilities"))
+        .action(async (boardId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).capabilities();
+            if (jsonRequested(options))
+                return outJson(result);
+            table(result.capabilities.map((capability) => ({
+                ...capability,
+                renderers: capability.renderers?.join(", ") ?? "",
+            })), [
+                { key: "kind", label: "Kind" },
+                { key: "id", label: "ID" },
+                { key: "version", label: "Version" },
+                { key: "renderers", label: "Renderers" },
+                { key: "digest", label: "Digest" },
+            ]);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    registerTransactionCommand(boards, "validate");
+    registerTransactionCommand(boards, "apply");
+    withJson(boards.command("play <board-id> <sequence-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 (boardId, sequenceId, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).play({
+                commandId: commandId(options),
+                type: "play",
+                sequenceId,
+                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 }) }),
+                ...(options.seed ? { seed: options.seed } : {}),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    const playbackAction = (type) => async (boardId, playbackId, options) => {
+        try {
+            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const id = commandId(options);
+            const result = type === "pause"
+                ? await board.pause({ commandId: id, type: "pause", playbackId })
+                : await board.stop({ commandId: id, type: "stop", playbackId });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    };
+    withJson(boards.command("pause <board-id> <playback-id>")
+        .description("Pause playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(playbackAction("pause"));
+    withJson(boards.command("seek <board-id> <playback-id> <position>")
+        .description("Seek playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(async (boardId, playbackId, position, options) => {
+        try {
+            const result = await createClient().space(resolveSpace(boards)).board(boardId).seek({
+                commandId: commandId(options),
+                type: "seek",
+                playbackId,
+                position: parseNumber(position, "position", { min: 0 }),
+            });
+            if (jsonRequested(options))
+                return outJson(result);
+            showPlayback(result);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("stop <board-id> <playback-id>")
+        .description("Stop playback")
+        .option("--command-id <id>", "Idempotency command ID"))
+        .action(playbackAction("stop"));
+    withJson(boards.command("watch <board-id>")
+        .description("Stream Board events"))
+        .action((boardId, options) => {
+        try {
+            const board = createRealtimeClient().space(resolveSpace(boards)).board(boardId);
+            if (!jsonRequested(options))
+                process.stderr.write(`Listening for Board ${boardId} events...\n`);
+            board.subscribe({
+                event(event) {
+                    if (jsonRequested(options)) {
+                        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`);
+                    }
+                    else {
+                        process.stdout.write(`${event.payload.status}  sequence ${event.payload.sequenceId}  position ${event.payload.position}\n`);
+                    }
+                },
+            });
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    return boards;
+}

package/dist/commands/spaces.js

@@ -381,16 +381,30 @@ export function registerSpaces(program) {
         .command("ls")
         .alias("list")
         .description("List all spaces")
+        .option("--mine", "Only spaces you own")
+        .option("--pinned", "Only pinned spaces")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
         const client = createClient();
         try {
-            const items = await client.spaces.list();
+            const [items, me] = await Promise.all([
+                client.spaces.list(),
+                opts.mine ? client.user.getMe() : Promise.resolve(null),
+            ]);
+            const myUuid = me?.uuid ?? null;
+            const filtered = items.filter((item) => {
+                if (opts.mine && myUuid && item.userUuid !== myUuid)
+                    return false;
+                if (opts.pinned && !item.isPinned)
+                    return false;
+                return true;
+            });
             if (jsonRequested(opts))
-                return outJson(items);
-            table(items, [
+                return outJson(filtered);
+            table(filtered, [
                 { key: "id", label: "ID" },
                 { key: "name", label: "Name" },
+                { key: "isPinned", label: "Pinned" },
                 { key: "createdAt", label: "Created" },
             ]);
         }
@@ -605,6 +619,33 @@ export function registerSpaces(program) {
     registerMods(spacesCmd);
     // ── spaces labels ──
     registerLabels(spacesCmd);
+    // ── spaces pin / unpin (user-scope label convenience) ──
+    spacesCmd
+        .command("pin <id>")
+        .description("Pin a space (add the Pinned user label)")
+        .action(async (id) => {
+        const client = createClient();
+        try {
+            await client.user.labels.patchResourceLabels("space", id.trim(), { addLabelRefs: ["Pinned"] });
+            ok("Space pinned");
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+    spacesCmd
+        .command("unpin <id>")
+        .description("Unpin a space (remove the Pinned user label)")
+        .action(async (id) => {
+        const client = createClient();
+        try {
+            await client.user.labels.patchResourceLabels("space", id.trim(), { removeLabelRefs: ["Pinned"] });
+            ok("Space unpinned");
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
     // ── spaces commerce ──
     registerSpaceCommerce(spacesCmd);
     // ── spaces usage ──

package/dist/index.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { registerAuth } from "./commands/auth.js";
+import { registerBoards } from "./commands/boards.js";
 import { registerChannels } from "./commands/channels.js";
 import { registerCronJobs } from "./commands/cron-jobs.js";
 import { registerGenerations } from "./commands/generations.js";
@@ -48,6 +49,7 @@ Common commands:
   cohub -s <space-id> run -- git status
   cohub sandbox up ./my-project
   cohub search "release notes"
+  cohub -s <space-id> boards inspect <board-id>
   cohub -s <space-id> spaces sessions turns ls <session-id>
   cohub -s <space-id> spaces files ls
   cohub -s <space-id> works publish demo --file dist/index.html
@@ -61,6 +63,7 @@ Environment:
   ENV=dev                Use the development Cohub environment
 `);
 registerAuth(program);
+registerBoards(program);
 registerProfile(program);
 registerMe(program);
 registerPrompt(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -18,7 +18,7 @@
     "@neta-art/generation": "^0.1.16",
     "commander": "^15.0.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "2.15.0"
+    "@neta-art/cohub": "3.0.0"
   },
   "publishConfig": {
     "access": "public"