@neta-art/cohub-cli 8.4.1 → 9.0.0

package/README.md

@@ -72,12 +72,15 @@ cohub -s <spaceId> spaces invites revoke <code> --yes
 cohub -s <spaceId> run -- git status
 ```
 
-Many space-scoped commands need a target Space. Without an explicit target, commands
-also use the Space remembered for the current directory before falling back to Home:
+Space-scoped commands use `-s`, then `COHUB_SPACE_ID`, then the Space remembered for
+the current directory. `<space>` is a Space ID, a slug you own such as `home`, or
+`username/slug`. Only `prompt`, `completion`, `generate`, `apps`, and `public` fall
+back to your Home Space; other commands exit with an error when no target is given:
 
 ```bash
 cohub -s <spaceId> spaces prompt "message" --json
 COHUB_SPACE_ID=<spaceId> cohub spaces prompt "message" --json
+cohub -s home spaces files ls
 ```
 
 ## Local Runtime
@@ -349,12 +352,32 @@ Pass generation parameters with `--param key=value` or `--parameters '<json>'`.
 ```bash
 cohub -s <spaceId> spaces files ls [path] --json
 cohub -s <spaceId> spaces files cat <path>
+cohub -s <spaceId> spaces files cat <path> > <local-file>
 cohub -s <spaceId> spaces files write <path> -c "<content>"
 cohub -s <spaceId> spaces files upload <files...> --dir <dir>
+cohub spaces files cp [-r] [-n] [-p] <source>... <destination>
 cohub -s <spaceId> spaces files mv <from> <to>
 cohub -s <spaceId> spaces files rm <path>
 ```
 
+`cat` streams raw bytes, so redirecting it saves binary files intact.
+
+`cp` works like `scp` with `cp` semantics: the last path is the destination,
+directories need `-r`, existing files are overwritten and directories merged
+(`-n` keeps existing files, `-p` keeps modification times). `<space>:<path>`
+addresses a Space by id, `username/slug`, or the slug of a Space you own. Bare
+paths address the current Space when one is declared with `-s` or
+`COHUB_SPACE_ID` (as inside a Cohub sandbox) and local files otherwise;
+absolute paths outside `/workspace` are always local:
+
+```bash
+cohub spaces files cp -r alice/templates:starter ./starter    # download
+cohub spaces files cp report.pdf <spaceId>:inbox/             # upload
+cohub -s <spaceId> spaces files cp -r other:docs docs         # Space to Space
+```
+
+Copies between Spaces run server-side and never pass file content through the CLI.
+
 `upload` places each file under `--dir`; a directory argument contributes its
 contents directly (like `aws s3 cp dir remote:path`), so `upload dist --dir apps/demo`
 lands at `apps/demo/index.html`, not `apps/demo/dist/index.html`. Upload adds or

package/dist/board-export.d.ts

@@ -1,45 +1,13 @@
-/**
- * Board image export for the CLI.
- *
- * The CLI and web editor share canonical Board geometry and card semantics. Each
- * host selects the renderer primitive suited to its backend; this path uses
- * Canvas2D. Everything platform-specific
- * lives here: fetching the document over HTTP, pulling image bytes out of the
- * space, and locating fonts on disk.
- */
-import type { BoardDocument, BoardExportRegion, BoardItem } from "@neta-art/cohub/board";
+import type { BoardDocument, BoardExportRegion, BoardSceneItem } from "@neta-art/cohub/board";
 import type { BoardHeadlessExportFormat, BoardHeadlessFont, BoardHeadlessRenderer, BoardHeadlessTexture } from "@neta-art/cohub/board/headless";
-/**
- * Geist, as shipped to the browser.
- *
- * The board asks for the "Geist" family; registering the exact same font files
- * the web app loads is what makes CLI output match the editor rather than
- * substituting whatever sans-serif the host happens to have. A source checkout
- * falls back to the dev packages.
- */
 export declare function resolveBundledFonts(): BoardHeadlessFont[];
 export type BoardExportSource = {
     document: BoardDocument;
     boardId: string;
     title: string | null;
 };
-/**
- * Load a board document by board id or by the path of its `.board` file.
- *
- * A `.board` file is a manifest holding a board id, so both forms converge on
- * the same inspect call — which is also what the web client does.
- */
 export declare function loadBoardDocument(spaceId: string, target: string): Promise<BoardExportSource>;
-/**
- * Fetch every image in `items`, keyed the way the renderers ask for it.
- *
- * Takes the planned items rather than the whole document so a partial export
- * does not download the rest of the board. Failures are collected rather than
- * thrown: one unreadable image should cost a placeholder and a warning, not the
- * whole export. Downloads run concurrently but bounded, so a board with hundreds
- * of images does not open hundreds of sockets.
- */
-export declare function loadBoardTextures(headless: BoardHeadlessRenderer, spaceId: string, items: BoardItem[], options?: {
+export declare function loadBoardTextures(headless: BoardHeadlessRenderer, spaceId: string, items: readonly BoardSceneItem[], options?: {
     concurrency?: number;
 }): Promise<{
     textures: Map<string, BoardHeadlessTexture>;
@@ -50,6 +18,8 @@ export type BoardExportRunOptions = {
     spaceId: string;
     target: string;
     region: BoardExportRegion;
+    times?: number[];
+    animation?: string;
     scale: number;
     padding?: number;
     colorScheme: "dark" | "light";
@@ -58,14 +28,29 @@ export type BoardExportRunOptions = {
     quality?: number;
     withImages: boolean;
 };
-export type BoardExportRunResult = {
+export type BoardExportFrame = {
+    time: number | null;
     bytes: Uint8Array;
     width: number;
     height: number;
     scale: number;
     itemCount: number;
     format: BoardHeadlessExportFormat;
+};
+export type BoardExportRunResult = {
+    frames: BoardExportFrame[];
     warnings: string[];
 };
-/** Render a board to image bytes. Returns null when the region is empty. */
+export type BoardVideoExportFormat = "mp4" | "webm";
+export type BoardVideoExportOptions = Omit<BoardExportRunOptions, "format"> & {
+    format: BoardVideoExportFormat;
+    fps: number;
+    output: string;
+};
+export declare function runBoardVideoExport(options: BoardVideoExportOptions): Promise<{
+    width: number;
+    height: number;
+    frames: number;
+    warnings: string[];
+}>;
 export declare function runBoardExport(options: BoardExportRunOptions): Promise<BoardExportRunResult | null>;

package/dist/board-export.js

@@ -1,29 +1,17 @@
-/**
- * Board image export for the CLI.
- *
- * The CLI and web editor share canonical Board geometry and card semantics. Each
- * host selects the renderer primitive suited to its backend; this path uses
- * Canvas2D. Everything platform-specific
- * lives here: fetching the document over HTTP, pulling image bytes out of the
- * space, and locating fonts on disk.
- */
 import { existsSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { boardAuthoringSnapshotToDocument, boardImageKeySource, createBoardHeadlessRenderer, exportBoardImageBytes, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
+import { tmpdir } from "node:os";
+const execFile = promisify(execFileCallback);
+import { boardDocumentAt, boardImageKeySource, buildBoardScene, createBoardHeadlessRenderer, createBoardHeadlessSketchHost, exportBoardImageBytes, imageAssetKey, parseBoardDocument, planBoardExport, selectBoardExportAssets, } from "./board-kernel.js";
 import { resolveBoardId } from "./board-command-support.js";
 import { BOARD_EXPORT_FONTS } from "./board-fonts.js";
 import { createClient } from "./client.js";
 import { downloadPublicImage } from "./safe-remote-image.js";
-/**
- * Geist, as shipped to the browser.
- *
- * The board asks for the "Geist" family; registering the exact same font files
- * the web app loads is what makes CLI output match the editor rather than
- * substituting whatever sans-serif the host happens to have. A source checkout
- * falls back to the dev packages.
- */
 export function resolveBundledFonts() {
     const require = createRequire(import.meta.url);
     const bundled = fileURLToPath(new URL("./fonts/", import.meta.url));
@@ -44,33 +32,21 @@ export function resolveBundledFonts() {
         return path ? [{ path, family: font.family }] : [];
     });
 }
-/**
- * Load a board document by board id or by the path of its `.board` file.
- *
- * A `.board` file is a manifest holding a board id, so both forms converge on
- * the same inspect call — which is also what the web client does.
- */
 export async function loadBoardDocument(spaceId, target) {
-    const client = createClient();
-    const boardId = await resolveBoardId(spaceId, target);
-    const snapshot = await client.space(spaceId).board(boardId).authoring({ include: ["items", "connections"] });
-    return {
-        document: boardAuthoringSnapshotToDocument(snapshot),
-        boardId: snapshot.board.id,
-        title: snapshot.board.title ?? null,
-    };
+    const board = createClient().space(spaceId).board(await resolveBoardId(spaceId, target));
+    let result = await board.get();
+    const items = { ...result.items };
+    while (result.next) {
+        result = await board.get({ only: ["items"], cursor: result.next });
+        Object.assign(items, result.items);
+    }
+    const parsed = parseBoardDocument({ board: result.board, items, animations: result.animations ?? {} });
+    if (!parsed.ok)
+        throw new Error(`Board ${result.id} could not be read: ${parsed.diagnostics[0]?.path}: ${parsed.diagnostics[0]?.message}`);
+    return { document: parsed.document, boardId: result.id, title: result.title };
 }
-/**
- * Fetch every image in `items`, keyed the way the renderers ask for it.
- *
- * Takes the planned items rather than the whole document so a partial export
- * does not download the rest of the board. Failures are collected rather than
- * thrown: one unreadable image should cost a placeholder and a warning, not the
- * whole export. Downloads run concurrently but bounded, so a board with hundreds
- * of images does not open hundreds of sockets.
- */
 export async function loadBoardTextures(headless, spaceId, items, options = {}) {
-    const selection = selectBoardExportAssets(items, imageAssetKey);
+    const selection = selectBoardExportAssets([...items], imageAssetKey);
     const textures = new Map();
     const failed = [];
     const pending = [...selection.keys];
@@ -105,13 +81,80 @@ async function readSpaceFileBytes(client, spaceId, path) {
     const { blob, mimeType } = await client.space(spaceId).files.download(path);
     return { bytes: new Uint8Array(await blob.arrayBuffer()), mimeType };
 }
-/** Render a board to image bytes. Returns null when the region is empty. */
+export async function runBoardVideoExport(options) {
+    if (!options.animation)
+        throw new Error("Video export needs --animation.");
+    if (!options.times || options.times.length < 2)
+        throw new Error("Video export needs an --at range with at least two frames.");
+    const times = options.times;
+    const step = times[1] - times[0];
+    if (!Number.isFinite(step) || step <= 0)
+        throw new Error("Video export needs an increasing --at range.");
+    const derivedFps = 1000 / step;
+    if (Math.abs(options.fps - derivedFps) > 0.01)
+        throw new Error(`--fps must match the --at step (${derivedFps.toFixed(3)} fps).`);
+    const result = await runBoardExport({ ...options, format: "png" });
+    if (!result)
+        throw new Error("Nothing to export: the region contains no items.");
+    const tempDir = await mkdtemp(join(tmpdir(), "cohub-board-export-"));
+    try {
+        for (const [index, frame] of result.frames.entries())
+            await writeFile(join(tempDir, `${String(index + 1).padStart(6, "0")}.png`), frame.bytes);
+        const document = (await loadBoardDocument(options.spaceId, options.target)).document;
+        const audioDocument = boardDocumentAt(document, options.animation, times[0]).document;
+        const audio = Object.values(audioDocument.items).filter((item) => item.type === "audio");
+        const audioInputs = [];
+        for (const [index, item] of audio.entries()) {
+            const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, item.props.src);
+            const path = join(tempDir, `audio-${index}-${item.props.src.split("/").pop() ?? "track"}`);
+            await writeFile(path, bytes);
+            audioInputs.push({ path, offset: Math.max(0, item.props.time ?? 0) / 1000 });
+        }
+        const duration = Math.max(0.001, result.frames.length / options.fps);
+        const args = ["-y", "-f", "image2", "-framerate", String(options.fps), "-i", join(tempDir, "%06d.png")];
+        for (const input of audioInputs) {
+            if (input.offset > 0)
+                args.push("-ss", input.offset.toFixed(3));
+            args.push("-i", input.path);
+        }
+        if (audioInputs.length > 1) {
+            const inputs = audioInputs.map((_, index) => `[${index + 1}:a]`).join("");
+            args.push("-filter_complex", `${inputs}amix=inputs=${audioInputs.length}:duration=longest:dropout_transition=0[aout]`, "-map", "0:v:0", "-map", "[aout]");
+        }
+        else {
+            args.push("-map", "0:v:0");
+            if (audioInputs.length === 1)
+                args.push("-map", "1:a:0");
+        }
+        if (options.format === "mp4")
+            args.push("-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-movflags", "+faststart", "-f", "mp4");
+        else
+            args.push("-c:v", "libvpx-vp9", "-crf", "32", "-b:v", "0", "-c:a", "libopus", "-f", "webm");
+        args.push("-t", duration.toFixed(3), options.output);
+        try {
+            await execFile("ffmpeg", args, { encoding: "utf8", maxBuffer: 2 * 1024 * 1024 });
+        }
+        catch (error) {
+            const cause = error;
+            if (cause.code === "ENOENT")
+                throw new Error("Video export needs ffmpeg. Install ffmpeg and try again.");
+            throw new Error(`ffmpeg could not encode the video: ${(cause.stderr ?? cause.message ?? "unknown error").trim().split("\n").slice(-6).join("\n")}`);
+        }
+        return { width: result.frames[0]?.width ?? 0, height: result.frames[0]?.height ?? 0, frames: result.frames.length, warnings: result.warnings };
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
 export async function runBoardExport(options) {
     const { document } = await loadBoardDocument(options.spaceId, options.target);
-    // Plan before fetching: a --frame / --items / --rect export should only pull
-    // the images it will actually draw, and an empty region should pull none.
+    if (options.animation && !document.animations[options.animation]) {
+        throw new Error(`Animation ${options.animation} does not exist.`);
+    }
+    const times = options.times?.length ? options.times : [null];
+    const documentAt = (time) => time === null ? document : boardDocumentAt(document, options.animation ?? null, time).document;
     const plan = planBoardExport({
-        document,
+        scene: buildBoardScene(documentAt(times[0] ?? null)),
         region: options.region,
         scale: options.scale,
         ...(options.padding === undefined ? {} : { padding: options.padding }),
@@ -119,6 +162,7 @@ export async function runBoardExport(options) {
     if (!plan)
         return null;
     const headless = await createBoardHeadlessRenderer({ fonts: resolveBundledFonts() });
+    let sketchHost = null;
     try {
         const warnings = [];
         let textures;
@@ -135,7 +179,7 @@ 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;
+        const declaredBackground = document.board.background;
         if (options.withImages &&
             options.background === "paper" &&
             declaredBackground.kind === "image" &&
@@ -149,54 +193,85 @@ export async function runBoardExport(options) {
             }
         }
         const videoCount = plan.items.filter((item) => item.type === "video").length;
+        sketchHost = createBoardHeadlessSketchHost(headless, {
+            readModule: async (src) => {
+                const { bytes } = await readSpaceFileBytes(createClient(), options.spaceId, src);
+                return new TextDecoder().decode(bytes);
+            },
+        });
+        const region = times.length > 1 ? { kind: "rect", rect: plan.world } : options.region;
+        const host = sketchHost;
+        if (!host)
+            throw new Error("Headless sketch host could not be created.");
+        const sketchVariants = new Map();
+        for (const time of times) {
+            const sketchPlan = planBoardExport({
+                scene: buildBoardScene(documentAt(time)),
+                region,
+                scale: options.scale,
+                ...(times.length > 1 ? { padding: 0 } : options.padding === undefined ? {} : { padding: options.padding }),
+            });
+            for (const item of sketchPlan?.items.filter((entry) => entry.type === "sketch") ?? []) {
+                const key = `${item.id}:${item.frame.width}:${item.frame.height}:${item.props.src}:${item.props.seed ?? ""}:${JSON.stringify(item.props.params)}`;
+                const variant = sketchVariants.get(key) ?? { item, times: [] };
+                variant.times.push(time ?? 0);
+                sketchVariants.set(key, variant);
+            }
+        }
+        await Promise.all([...sketchVariants.values()].map((variant) => host.prepare([variant.item], variant.times, plan.scale)));
         if (videoCount > 0) {
             warnings.push(`${videoCount} video preview${videoCount === 1 ? " was" : "s were"} drawn as placeholders; headless video decoding is unavailable.`);
         }
-        const result = exportBoardImageBytes(headless, document, {
-            region: options.region,
-            scale: options.scale,
-            padding: options.padding,
-            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) => {
-                        const key = imageAssetKey(item);
-                        return key && omittedKeys.has(key) ? null : key;
-                    },
-                }
-                : {}),
-            format: options.format,
-            quality: options.quality,
-        });
-        if (!result)
-            return null;
-        for (const warning of result.warnings) {
-            // Missing-image warnings are already reported above with their paths.
-            if (warning.kind === "images-missing" && options.withImages)
+        const backgroundImage = backgroundTexture
+            ? { texture: backgroundTexture, fit: declaredBackground.fit ?? "cover", position: "center", opacity: declaredBackground.opacity ?? 1 }
+            : undefined;
+        const assetKey = options.withImages
+            ? (item) => {
+                const key = imageAssetKey(item);
+                return key && omittedKeys.has(key) ? null : key;
+            }
+            : undefined;
+        const frames = [];
+        const reported = new Set();
+        for (const time of times) {
+            const result = exportBoardImageBytes(headless, document, {
+                ...(time === null ? {} : { at: { ...(options.animation ? { animation: options.animation } : {}), time } }),
+                region,
+                scale: options.scale,
+                padding: times.length > 1 ? 0 : options.padding,
+                colorScheme: options.colorScheme,
+                background: options.background,
+                textures,
+                sketches: sketchHost ?? undefined,
+                backgroundImage,
+                ...(assetKey ? { assetKey } : {}),
+                format: options.format,
+                quality: options.quality,
+            });
+            if (!result)
                 continue;
-            warnings.push(describeWarning(warning));
+            for (const warning of result.warnings) {
+                if (warning.kind === "images-missing" && options.withImages)
+                    continue;
+                const text = describeWarning(warning);
+                if (!reported.has(text))
+                    warnings.push(text);
+                reported.add(text);
+            }
+            frames.push({
+                time,
+                bytes: result.bytes,
+                width: result.plan.width,
+                height: result.plan.height,
+                scale: result.plan.scale,
+                itemCount: result.plan.items.length,
+                format: result.format,
+            });
         }
-        return {
-            bytes: result.bytes,
-            width: result.plan.width,
-            height: result.plan.height,
-            scale: result.plan.scale,
-            itemCount: result.plan.items.length,
-            format: result.format,
-            warnings,
-        };
+        return frames.length ? { frames, warnings } : null;
     }
     finally {
+        sketchHost?.destroy();
         headless.destroy();
     }
 }

package/dist/board-kernel.d.ts

@@ -1,3 +1,2 @@
-/** The Board renderer for `boards export`, bundled with PixiJS by `tsdown.config.ts`. */
-export { boardAuthoringSnapshotToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
-export { createBoardHeadlessRenderer, exportBoardImageBytes } from "@neta-art/cohub/board/headless";
+export { boardDocumentAt, boardImageKeySource, buildBoardScene, imageAssetKey, parseBoardDocument, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+export { createBoardHeadlessRenderer, createBoardHeadlessSketchHost, exportBoardImageBytes } from "@neta-art/cohub/board/headless";