@neta-art/cohub-cli 9.0.0 → 9.1.0

package/README.md

@@ -115,6 +115,13 @@ cohub runtime down
 cohub runtime up -n --name another-project
 ```
 
+On macOS and Linux X11, a new Runtime offers screen sharing by default. The prompt
+explains that collaborators and agents can see and control the screen; Enter accepts,
+and `n` declines. Use `--no-display` to skip sharing, or `--display xvfb[:WIDTHxHEIGHT]`
+for a virtual screen. `--yes` also authorizes default screen sharing. Headless and
+Wayland-only Linux sessions skip the default offer; an existing Runtime keeps its
+screen configuration unless explicitly overridden (configuration changes require a restart).
+
 Runtime diagnostics stay as redacted JSONL under the local Runtime state directory and
 are never uploaded automatically. Use `runtime logs --json` to export a failure report;
 events carry the local `runtimeId` plus server `requestId` / `traceparent` when a turn has
@@ -225,57 +232,63 @@ cohub -s <spaceId> spaces activity 365 --json
 
 ## Boards
 
-Board targets accept a Board ID or a `.board` path. Every command supports `-h` and `--json`:
+A Board is one JSON document with three collections — `board` settings, `items`,
+and `animations`. Board targets accept a Board ID or a `.board` path. Every
+command supports `-h`, and the global `--json` makes the output machine-readable:
 
 ```bash
 cohub boards -h
-cohub -s <spaceId> boards inspect boards/plan.board --json
-cohub -s <spaceId> boards items list <boardId>
-cohub -s <spaceId> boards connections list <boardId>
-cohub -s <spaceId> boards capabilities <boardId>
+cohub -s <spaceId> boards get boards/plan.board --json
+cohub -s <spaceId> boards get <boardId> --only items
+cohub -s <spaceId> boards get <boardId> --only board
+cohub -s <spaceId> boards schema
+cohub -s <spaceId> boards history <boardId> --json
 cohub -s <spaceId> boards watch <boardId> --json
 ```
 
-Use targeted reads for large Boards:
+Use the filters so a large Board is not read whole:
 
 ```bash
-cohub -s <spaceId> boards items get <boardId> <itemId> --json
-cohub -s <spaceId> boards connections get <boardId> <connectionId> --json
-cohub -s <spaceId> boards effects get <boardId> <effectId> --json
-cohub -s <spaceId> boards compositions get <boardId> <compositionId> --json
+cohub -s <spaceId> boards get <boardId> --items title,note
+cohub -s <spaceId> boards get <boardId> --within s1
+cohub -s <spaceId> boards get <boardId> --rect 0,0,1600,900
 ```
 
-Create semantic JSON from an example, then apply it to one resource:
+Start from an example and write it with `apply`, a JSON Merge Patch where fields
+merge, `null` deletes, and unmentioned fields stay:
 
 ```bash
-cohub boards examples item text > item.json
-cohub -s <spaceId> boards items create <boardId> --input item.json
+cohub boards examples workflow > seed.json
+cohub -s <spaceId> boards create boards/plan.board --title "Plan" -i seed.json
 
-cohub boards examples composition fade > intro.json
-cohub -s <spaceId> boards compositions apply <boardId> --input intro.json
+cohub -s <spaceId> boards apply <boardId> '{"items":{"title":{"props":{"text":"Updated"}}}}'
+cohub -s <spaceId> boards apply <boardId> -i changes.json
 ```
 
-Apply related changes atomically with one request. The batch contains semantic commands, not a full Board snapshot:
+Group a whole change into one patch so it lands as one version. `--replace` makes
+the document equal to the patch instead of merging; `--cascade` also deletes
+children and the tracks targeting a deleted item:
 
-```json
-{"commands":[
-  {"type":"item.patch","itemId":"title","patch":{"props":{"text":"Updated"}}},
-  {"type":"connection.create","connection":{"id":"title-agent","source":{"itemId":"title"},"target":{"itemId":"agent"}}}
-]}
+```bash
+cohub -s <spaceId> boards apply <boardId> -i changes.json --dry-run
+cohub -s <spaceId> boards apply <boardId> -i changes.json --base-version 12 --mutation-id deploy-1
 ```
 
+Use `--base-version` and `--mutation-id` for controlled, retry-safe scripts, and
+`--dry-run` to validate without writing. `boards preset` prints a preset motion as
+tracks — an apply-ready patch with `--animation`, bare tracks without it:
+
 ```bash
-cohub boards examples batch basic > changes.json
-cohub -s <spaceId> boards batch <boardId> --input changes.json --dry-run
-cohub -s <spaceId> boards batch <boardId> --input changes.json
+cohub -s <spaceId> boards preset rise --targets a,b --animation intro | cohub boards apply <boardId> -i -
+cohub -s <spaceId> boards preset float --targets ship > idle-tracks.json
 ```
 
-Use `--base-version` and `--mutation-id` for controlled, retry-safe scripts. Use `--dry-run` to validate without writing. Playback is grouped under `playback`:
+Playback commands sit on `boards` directly:
 
 ```bash
-cohub -s <spaceId> boards playback play <boardId> <compositionId>
-cohub -s <spaceId> boards playback seek <boardId> <playbackId> 400
-cohub -s <spaceId> boards playback stop <boardId> <playbackId>
+cohub -s <spaceId> boards play <boardId> <animationId> --at 2.5s
+cohub -s <spaceId> boards seek <boardId> 12.5s
+cohub -s <spaceId> boards stop <boardId>
 ```
 
 ## Search

package/dist/commands/boards.js

@@ -145,7 +145,7 @@ function registerExportCommand(boards) {
         .option("--scale <factor>", "Output pixels per board unit", "2")
         .option("--padding <units>", "Padding around the content in board units")
         .option("--theme <mode>", "dark or light", "dark")
-        .option("--background <mode>", "paper or transparent", "paper")
+        .option("--paper <mode>", "Output paper: paper or transparent", "paper")
         .option("--format <format>", `Override the format (${BOARD_EXPORT_FORMATS.join(", ")}, ${BOARD_VIDEO_FORMATS.join(", ")})`)
         .option("--quality <q>", "JPEG/WebP quality from 0 to 1", "0.92")
         .option("--fps <rate>", "Video frame rate; defaults to the --at step")
@@ -189,7 +189,7 @@ Examples:
                     scale: parseNumber(options.scale ?? "2", "--scale", { min: 0.01, max: 16 }),
                     ...(options.padding === undefined ? {} : { padding: parseNumber(options.padding, "--padding", { min: 0 }) }),
                     colorScheme: parseChoice(options.theme, "--theme", ["dark", "light"]),
-                    background: parseChoice(options.background, "--background", ["paper", "transparent"]),
+                    background: parseChoice(options.paper, "--paper", ["paper", "transparent"]),
                     format: videoFormat,
                     fps,
                     output: out,
@@ -213,7 +213,7 @@ Examples:
                 scale: parseNumber(options.scale ?? "2", "--scale", { min: 0.01, max: 16 }),
                 ...(options.padding === undefined ? {} : { padding: parseNumber(options.padding, "--padding", { min: 0 }) }),
                 colorScheme: parseChoice(options.theme, "--theme", ["dark", "light"]),
-                background: parseChoice(options.background, "--background", ["paper", "transparent"]),
+                background: parseChoice(options.paper, "--paper", ["paper", "transparent"]),
                 format: parseExportFormat(options, out),
                 quality: parseNumber(options.quality ?? "0.92", "--quality", { min: 0, max: 1 }),
                 withImages: options.images !== false,
@@ -252,6 +252,9 @@ A Board is one JSON document: { board, items, animations }.
   get      read it
   apply    write it with a JSON Merge Patch; null deletes
   schema   the schema of any part, and what tracks can animate
+  preset   tracks for a preset motion, ready to apply
+  history  list versions, or restore one
+  export   render an image, a frame sequence or a video
   examples starter documents
 Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     withJson(boards.command("create <path>")
@@ -288,7 +291,7 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     });
     boards.command("get <board>")
         .description("Print the Board document as JSON")
-        .option("--only <sections>", "items, animations, or both (comma-separated)")
+        .option("--only <sections>", "board, items, animations (comma-separated)")
         .option("--items <ids>", "Only these items")
         .option("--within <frame-id>", "A frame and everything inside it")
         .option("--rect <rect>", "Items intersecting x,y,width,height")
@@ -298,14 +301,15 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
         .addHelpText("after", `
   cohub boards get plan.board
   cohub boards get plan.board --within s2
-  cohub boards get plan.board --only animations`)
+  cohub boards get plan.board --only board`)
         .action(async (target, options) => {
         try {
             const only = list(options.only);
-            if (only?.some((section) => section !== "items" && section !== "animations"))
-                throw new Error("--only takes items, animations, or both.");
+            if (only?.some((section) => section !== "board" && section !== "items" && section !== "animations"))
+                throw new Error("--only takes board, items, animations, or a combination.");
+            const sections = only ? new Set(only) : null;
             const input = {
-                ...(only ? { only: only } : {}),
+                ...(only ? { only: only.filter((section) => section !== "board") } : {}),
                 ...(list(options.items) ? { items: list(options.items) } : {}),
                 ...(options.within ? { within: options.within } : {}),
                 ...(options.rect ? { rect: parseRect(options.rect) } : {}),
@@ -313,7 +317,20 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
                 ...(options.limit ? { limit: parseNumber(options.limit, "--limit", { min: 1, integer: true }) } : {}),
                 ...(options.cursor ? { cursor: options.cursor } : {}),
             };
-            outJson(await (await boardClient(boards, target)).get(input));
+            const result = await (await boardClient(boards, target)).get(input);
+            if (!sections)
+                return outJson(result);
+            outJson({
+                id: result.id,
+                title: result.title,
+                version: result.version,
+                updatedAt: result.updatedAt,
+                playback: result.playback,
+                ...(sections.has("board") ? { board: result.board } : {}),
+                ...(sections.has("items") && result.items ? { items: result.items } : {}),
+                ...(sections.has("animations") && result.animations ? { animations: result.animations } : {}),
+                ...(result.next ? { next: result.next } : {}),
+            });
         }
         catch (cause) {
             handleHttp(cause);
@@ -393,6 +410,7 @@ Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     boards.command("schema [target]")
         .description("Print JSON Schema for a part of a Board")
         .addHelpText("after", `
+With a target: one item type, or animation, track, or camera.
 Targets: ${BOARD_SCHEMA_TARGETS.join(", ")}
 Without a target: units, item types, colors and every animatable property.`)
         .action((target) => {
@@ -411,14 +429,15 @@ Without a target: units, item types, colors and every animatable property.`)
     boards.command("preset <name>")
         .description("Print tracks for a preset motion as a patch for apply")
         .requiredOption("--targets <ids>", "Comma-separated item ids")
-        .requiredOption("--animation <id>", "Animation to add the tracks to")
+        .option("--animation <id>", "Wrap the tracks in this animation; omit to get bare tracks")
         .option("--at <time>", "Start of the first target", "0")
         .option("--stagger <time>", "Delay added per target", "0")
         .option("--duration <time>", "Length of each target's motion")
         .option("--ease <ease>", "CSS easing, e.g. ease-out or cubic-bezier(.2,.8,.2,1)")
         .addHelpText("after", `
 Presets: ${BOARD_PRESET_NAMES.join(", ")}
-  cohub boards preset rise --targets a,b,c --animation intro --stagger 120ms | cohub boards apply plan.board -i -`)
+  cohub boards preset rise --targets a,b,c --animation intro --stagger 120ms | cohub boards apply plan.board -i -
+  cohub boards preset float --targets ship | jq -c '{animations:{idle:.}}' | cohub boards apply plan.board -i -`)
         .action((name, options) => {
         try {
             if (!isBoardPresetName(name))
@@ -433,7 +452,7 @@ Presets: ${BOARD_PRESET_NAMES.join(", ")}
                 ...(options.duration ? { duration: parseBoardTime(options.duration, "--duration") } : {}),
                 ...(options.ease ? { ease: options.ease } : {}),
             });
-            outJson({ animations: { [options.animation]: { tracks } } });
+            outJson(options.animation ? { animations: { [options.animation]: { tracks } } } : { tracks });
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/runtime.js

@@ -41,8 +41,9 @@ export function registerRuntime(program) {
         .option("--harness <name>", "Pi or Codex; repeatable", (value, previous) => [...previous, value], [])
         .option("--pi <path>", "Pi executable")
         .option("--codex <path>", "Codex executable")
-        .option("--display [screen]", "Share a screen: auto (this computer), or xvfb[:WIDTHxHEIGHT] for a virtual one")
-        .option("-y, --yes", "Accept defaults and authorize local execution and native sync")
+        .option("--display [screen]", "Share a screen (default: auto when available), or xvfb[:WIDTHxHEIGHT] for a virtual one")
+        .option("--no-display", "Disable screen sharing and skip its confirmation")
+        .option("-y, --yes", "Accept defaults and authorize local execution, native sync, and screen sharing")
         .option("--verbose", "Show diagnostic details")
         .option("--json", "JSON output")
         .action(async (dir, options) => {

package/dist/commands/sandboxd-binary.d.ts

@@ -1,4 +1,4 @@
-export declare const SANDBOXD_VERSION = "v2.55.0";
+export declare const SANDBOXD_VERSION = "v2.61.1";
 export declare class SandboxdDownloadError extends Error {
     name: string;
 }

package/dist/commands/sandboxd-binary.js

@@ -6,29 +6,8 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
-// The sandboxd binary version is pinned independently of the CLI package: it
-// only needs to change when apps/sandbox changes, and the agent-sandbox wire
-// protocol ("1") guarantees backward compatibility.
-//
-// IMPORTANT: this must point at a tag whose CDN artifacts have already been
-// published by .github/workflows/sandbox-binaries-build.yml. Only bump it AFTER
-// that tag's publish-cdn job has succeeded, otherwise `runtime up` 404s on the
-// default download.
-//
-// v2.54.0 is the first published tag with the private managed Runtime control
-// pipe (`COHUB_RUNTIME_MANAGED` over fd 3), so `runtime up` reads connection
-// state from the daemon instead of polling the API every five seconds. It also
-// carries the optional workspace-search runner download. v2.53.1 already has
-// the native FSEvents backends and the `runtimeId` control frame, and older
-// releases stay usable through the compatibility readiness/restart path.
-//
-// v2.54.1 keeps the same wire protocol and adds relay diagnostics: data-channel
-// pairing outlives the runner's dial timeout, dial failures distinguish a
-// timeout from an explicit rejection, and teardown-time websocket write
-// failures log at debug instead of warn. v2.55.0 republishes that compatible
-// runner alongside the matching platform release; no new runner capability is
-// required.
-export const SANDBOXD_VERSION = "v2.55.0";
+// Pin only after all platform artifacts are published to the public CDN.
+export const SANDBOXD_VERSION = "v2.61.1";
 const BINARY_NAME = "cohub-sandboxd";
 // Public CDN prefix hosting the release archives (the repo is private, so the
 // GitHub Release assets are not publicly downloadable). Overridable for staging

package/dist/index.js

@@ -56,7 +56,7 @@ Common commands:
   cohub runtime up ./my-project
   cohub runtime logs --follow
   cohub search "release notes"
-  cohub -s <space-id> boards inspect <board-id>
+  cohub -s <space-id> boards get <board-id>
   cohub -s <space-id> spaces turns ls --author others
   cohub -s <space-id> spaces sessions turns ls <session-id>
   cohub -s home spaces files ls

package/dist/runtime/launch.d.ts

@@ -16,7 +16,7 @@ export type RuntimeUpOptions = {
 };
 export declare const resolveLocalSpaceName: (root: string, name?: string) => string;
 export declare function parseRuntimeHarnesses(values: string[]): ("pi" | "codex")[];
-export declare function parseRuntimeDisplay(value: string | boolean | undefined): string | undefined;
+export declare function parseRuntimeDisplay(value: string | boolean | undefined, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string | undefined;
 export declare function resolveRuntimeTarget(program: Command, target?: string): Promise<string>;
 export declare function startBackgroundRuntime(config: RuntimeLaunch): Promise<RuntimeSummary>;
 export declare function runtimeUp(program: Command, dir: string | undefined, options: RuntimeUpOptions): Promise<void>;

package/dist/runtime/launch.js

@@ -20,15 +20,17 @@ export function parseRuntimeHarnesses(values) {
         throw new Error("Harness must be pi or codex");
     return [...new Set(names.length ? names : ["pi"])];
 }
-export function parseRuntimeDisplay(value) {
-    if (value === undefined || value === false)
+export function parseRuntimeDisplay(value, platform = process.platform, env = process.env) {
+    if (value === false)
         return undefined;
-    const spec = value === true ? "auto" : value.trim();
+    if (value === undefined && platform !== "darwin" && (platform !== "linux" || !env.DISPLAY))
+        return undefined;
+    const spec = value === undefined || value === true ? "auto" : value.trim();
     if (!/^(auto|macos|x11(:[\w.:-]+)?|xvfb(:\d{3,4}x\d{3,4})?)$/.test(spec)) {
         throw new Error("Display must be auto, macos, x11[:display] or xvfb[:WIDTHxHEIGHT]");
     }
-    if (process.platform === "linux" && spec === "auto" && !process.env.DISPLAY) {
-        throw new Error(process.env.WAYLAND_DISPLAY
+    if (platform === "linux" && spec === "auto" && !env.DISPLAY) {
+        throw new Error(env.WAYLAND_DISPLAY
             ? "Wayland sessions cannot be shared yet: log in with an X11 session, or use --display xvfb for a virtual screen"
             : "No X11 session to share (DISPLAY is unset): use --display xvfb for a virtual screen");
     }
@@ -106,11 +108,11 @@ export async function runtimeUp(program, dir, options) {
     const binding = await getRuntimeSpaceBinding(root, identity);
     const existingId = requested || binding?.spaceId;
     let harnesses = parseRuntimeHarnesses(options.harness);
-    let display = parseRuntimeDisplay(options.display);
+    let display = options.display === undefined ? undefined : parseRuntimeDisplay(options.display);
     if (existingId && !options.new) {
         const existing = await requestRuntimeInstance(runtimeInstanceDirectory(identity, existingId));
         if (existing) {
-            if (existing.root !== root || options.harness.length && [...existing.harnesses].sort().join() !== [...harnesses].sort().join() || options.pi || options.codex || display && display !== existing.display) {
+            if (existing.root !== root || options.harness.length && [...existing.harnesses].sort().join() !== [...harnesses].sort().join() || options.pi || options.codex || options.display !== undefined && display !== existing.display) {
                 throw new Error("Runtime is running with a different configuration. Use down first");
             }
             // `up` is the single idempotent entry: a reused instance adopts its running
@@ -125,6 +127,7 @@ export async function runtimeUp(program, dir, options) {
             return;
         }
     }
+    display = parseRuntimeDisplay(options.display);
     if (!options.harness.length)
         harnesses = await installedHarnesses(root, options);
     if (!harnesses.length)
@@ -157,8 +160,8 @@ export async function runtimeUp(program, dir, options) {
             if (/^n(o)?$/i.test(answer.trim()))
                 return;
             if (display && !isVirtualDisplay(display)) {
-                const share = await rl.question("Collaborators and agents can see and control this screen. Share it? [y/N] ");
-                if (!/^y(es)?$/i.test(share.trim()))
+                const share = await rl.question("Collaborators and agents can see and control this screen. Share it? [Y/n] ");
+                if (!/^(y(es)?)?$/i.test(share.trim()))
                     display = undefined;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "engines": {