@neta-art/cohub-cli 10.1.0 → 10.3.0

package/dist/command-input.d.ts

@@ -0,0 +1,4 @@
+export declare function collectOption(value: string, previous?: string[]): string[];
+export declare function readPromptContent(words: string[], options?: {
+    allowEmpty?: boolean;
+}): Promise<string>;

package/dist/command-input.js

@@ -0,0 +1,16 @@
+import { error } from "./output.js";
+export function collectOption(value, previous = []) {
+    return [...previous, value];
+}
+export async function readPromptContent(words, options = {}) {
+    let content = words.join(" ");
+    if (!content && !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        content = Buffer.concat(chunks).toString().trim();
+    }
+    if (!content && !options.allowEmpty)
+        return error("No content", "Pass as argument or pipe via stdin");
+    return content;
+}

package/dist/commands/app-commerce.js

@@ -1,9 +1,7 @@
 import { resolveExecutionAppId, } from "@neta-art/cohub";
 import { createClient } from "../client.js";
+import { collectOption } from "../command-input.js";
 import { error, formatLocalDateTime, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
-function collectOption(value, previous = []) {
-    return [...previous, value];
-}
 function requireText(value, label, flag) {
     const text = value?.trim();
     if (text)

package/dist/commands/boards.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
-import { BOARD_PRESET_NAMES, BOARD_SCHEMA_TARGETS, boardJsonSchema, boardPresetTracks, boardSchemaOverview, isBoardPresetName, listBoardPresets, } from "@neta-art/cohub/board";
+import { BOARD_PRESET_NAMES, BOARD_SCHEMA_TARGETS, BOARD_SCRIPT_API, boardJsonSchema, boardPresetTracks, boardSchemaOverview, isBoardPresetName, listBoardPresets, } from "@neta-art/cohub/board";
 import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { formatBoardTime, parseBoardTime, parseBoardTimes } from "../board-time.js";
 import { createClient, createRealtimeClient } from "../client.js";
@@ -283,13 +283,18 @@ export function registerBoards(program) {
         .description("Read, write, animate and export Boards (by id or .board path)")
         .addHelpText("after", `
 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
+  get       read it
+  apply     write it with a JSON Merge Patch; null deletes
+  schema    the fields of any part and what they mean; also the script API
+  examples  starter documents and a custom script module
+  preset    tracks for a preset motion, ready to apply
+  sequence  join chapter animations into one timeline
+  path      sample a polyline into a position track
+  inspect   measure items and report layout hints
+  export    render an image, a frame sequence or a video
+  play      shared playback; also pause, resume, next, seek, stop
+  watch     stream changes and playback
+  history   list versions, or restore one
 Times are milliseconds; 500ms, 12.5s and 2m also work on the command line.`);
     withJson(boards.command("create <path>")
         .description("Create a Board file, optionally with an initial document")
@@ -444,9 +449,9 @@ 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.`)
+Without a target: units, item types, colors and every animatable property.
+With a target: its fields and what they mean; script also lists the module API.
+Targets: ${BOARD_SCHEMA_TARGETS.join(", ")}`)
         .action((target) => {
         try {
             if (!target)
@@ -454,7 +459,7 @@ Without a target: units, item types, colors and every animatable property.`)
             const schema = boardJsonSchema(target);
             if (!schema)
                 throw new Error(`Unknown target ${target}; expected ${BOARD_SCHEMA_TARGETS.join(", ")}.`);
-            outJson(schema);
+            outJson(target === "script" ? { ...schema, api: BOARD_SCRIPT_API } : schema);
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/decision.d.ts

@@ -0,0 +1,4 @@
+import type { DecisionStateImage } from "@neta-art/cohub";
+import type { Command } from "commander";
+export declare function mergeDecisionState(state: unknown, text: string, images: DecisionStateImage[]): unknown;
+export declare function registerDecisionCommand(parent: Command): void;

package/dist/commands/decision.js

@@ -0,0 +1,113 @@
+import { readFile } from "node:fs/promises";
+import { uploadChatImageAsset } from "../avatar.js";
+import { createClient } from "../client.js";
+import { collectOption, readPromptContent } from "../command-input.js";
+import { error, handleHttp, json as outJson, jsonRequested, table } from "../output.js";
+import { resolveSpace } from "../space.js";
+const REMOTE_URL = /^https?:\/\//i;
+async function readJsonObject(source, label) {
+    const text = source.trim().startsWith("{")
+        ? source
+        : await readFile(source, "utf-8").catch(() => error(`Cannot read ${label}`, source));
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return error(`Invalid ${label}`, "Expected a JSON object or a path to a JSON file");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return error(`Invalid ${label}`, "Expected a JSON object");
+    }
+    return value;
+}
+export function mergeDecisionState(state, text, images) {
+    if (!text && images.length === 0)
+        return state;
+    if (state !== undefined && typeof state !== "string" && !Array.isArray(state)) {
+        throw new Error("Cannot combine a JSON object state with text or --image; use a text/image array in --input instead.");
+    }
+    const parts = [
+        ...(Array.isArray(state) ? state : typeof state === "string" ? [state] : []),
+        ...(text ? [text] : []),
+        ...images,
+    ];
+    return parts.length === 1 && typeof parts[0] === "string" ? parts[0] : parts;
+}
+function formatAnswer(answer) {
+    if (answer.type === "noul")
+        return (answer.noul ?? 0).toFixed(2);
+    if (answer.type === "choice")
+        return answer.choice ?? "";
+    const top = Object.entries(answer.probabilities ?? {}).sort(([, a], [, b]) => b - a)[0]?.[0];
+    const label = top === undefined ? undefined : answer.legend?.[top];
+    return `${(answer.score ?? 0).toFixed(2)}${label ? ` ${label}` : ""}`;
+}
+function printResult(result) {
+    table(Object.entries(result.answers).map(([key, answer]) => ({
+        question: key,
+        type: answer.type,
+        answer: formatAnswer(answer),
+        confidence: answer.confidence,
+    })), [
+        { key: "question", label: "QUESTION" },
+        { key: "type", label: "TYPE" },
+        { key: "answer", label: "ANSWER" },
+        { key: "confidence", label: "CONFIDENCE", format: (value) => (typeof value === "number" ? value.toFixed(2) : "") },
+    ]);
+    const cost = result.usage.cost?.total;
+    process.stderr.write(`\n  ${result.provider}/${result.model}${typeof cost === "number" ? `  cost: $${cost}` : ""}\n`);
+}
+async function runDecisionCommand(command, words, opts) {
+    const base = opts.input ? await readJsonObject(opts.input, "input") : {};
+    const questions = opts.questions ? await readJsonObject(opts.questions, "questions") : base.questions;
+    if (!questions)
+        return error("Questions required", "Pass --questions or --input");
+    const spaceId = await resolveSpace(command, { home: true });
+    const client = createClient();
+    try {
+        const images = opts.image ?? [];
+        const text = words.length > 0 || base.state === undefined
+            ? await readPromptContent(words, { allowEmpty: images.length > 0 })
+            : "";
+        const imageParts = images.map((url) => ({ type: "image_url", image_url: { url } }));
+        const state = mergeDecisionState(base.state, text, imageParts);
+        await Promise.all(imageParts.map(async (part) => {
+            if (!REMOTE_URL.test(part.image_url.url)) {
+                part.image_url.url = (await uploadChatImageAsset({ client, spaceId, path: part.image_url.url })).publicUrl;
+            }
+        }));
+        const input = {
+            ...base,
+            provider: opts.provider ?? base.provider,
+            model: opts.model ?? base.model,
+            state,
+            questions,
+        };
+        const result = await client.space(spaceId).decision(input);
+        if (jsonRequested(opts))
+            return outJson(result);
+        printResult(result);
+    }
+    catch (e) {
+        handleHttp(e);
+    }
+}
+export function registerDecisionCommand(parent) {
+    parent
+        .command("decision [state...]")
+        .description("Answer yes/no, choice and score questions about text or images")
+        .option("-q, --questions <json|path>", "Questions as inline JSON or a JSON file")
+        .option("--input <path>", "Full request JSON file (state, questions, model)")
+        .option("--image <path-or-url>", "Attach an image to the state", collectOption, [])
+        .option("-m, --model <model>", "Decision model ID")
+        .option("-p, --provider <provider>", "Provider name")
+        .option("--json", "Output as JSON")
+        .addHelpText("after", `
+Examples:
+  cohub decision "I was charged twice" -q '{"refund":{"type":"noul","instructions":"Refund?"}}'
+  cat ticket.txt | cohub decision -q questions.json --json
+  cohub decision "Duplicate charge?" --image receipt.png -q questions.json
+  cohub decision --input request.json`)
+        .action((words, opts) => runDecisionCommand(parent, words, opts));
+}

package/dist/commands/rooms-connect.d.ts

@@ -0,0 +1,17 @@
+import type { Readable } from "node:stream";
+type Input = {
+    op: "publish" | "send";
+    type: string;
+    data: unknown;
+} | {
+    op: "presence";
+    presence: Record<string, unknown> | null;
+};
+export declare function parseRoomInput(line: string): Input;
+export declare function readRoomLines(input: Readable, maxBytes?: number): AsyncGenerator<string>;
+export declare function connectToRoom(roomId: string, options: {
+    after?: string;
+    input?: boolean;
+    json: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/rooms-connect.js

@@ -0,0 +1,140 @@
+import { createRealtimeClient } from "../client.js";
+const MAX_LINE_BYTES = 20 * 1024;
+const MAX_OUTPUT_BUFFER_BYTES = 1024 * 1024;
+export function parseRoomInput(line) {
+    if (Buffer.byteLength(line) > MAX_LINE_BYTES)
+        throw new Error("Room input line is too large");
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        throw new Error("Room input must be JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Room input must be an object");
+    const input = value;
+    if (input.op === "presence" && (input.presence === null || typeof input.presence === "object" && !Array.isArray(input.presence))) {
+        return { op: "presence", presence: input.presence };
+    }
+    if ((input.op === "publish" || input.op === "send") && typeof input.type === "string" && "data" in input) {
+        return { op: input.op, type: input.type, data: input.data };
+    }
+    throw new Error("Use {\"op\":\"publish|send\",\"type\":\"name\",\"data\":...} or {\"op\":\"presence\",\"presence\":...}");
+}
+export async function* readRoomLines(input, maxBytes = MAX_LINE_BYTES) {
+    let pending = Buffer.alloc(0);
+    for await (const chunk of input) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let start = 0;
+        for (;;) {
+            const end = bytes.indexOf(10, start);
+            const part = bytes.subarray(start, end < 0 ? bytes.length : end);
+            if (pending.length + part.length > maxBytes)
+                throw new Error("Room input line is too large");
+            pending = pending.length ? Buffer.concat([pending, part]) : part;
+            if (end < 0)
+                break;
+            yield pending.toString("utf8").replace(/\r$/, "");
+            pending = Buffer.alloc(0);
+            start = end + 1;
+        }
+    }
+    if (pending.length)
+        yield pending.toString("utf8");
+}
+export async function connectToRoom(roomId, options) {
+    const after = options.after === undefined ? undefined : Number(options.after);
+    if (after !== undefined && (!Number.isSafeInteger(after) || after < 0))
+        throw new Error("--after must be a non-negative sequence number");
+    const client = createRealtimeClient();
+    let room = null;
+    let stopped = false;
+    let finish;
+    const done = new Promise((resolve) => { finish = resolve; });
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        finish();
+    };
+    const write = (kind, value) => {
+        if (stopped)
+            return;
+        if (process.stdout.writableLength > MAX_OUTPUT_BUFFER_BYTES) {
+            process.stderr.write("Room output is too slow; disconnecting.\n");
+            process.exitCode = 1;
+            stop();
+            return;
+        }
+        process.stdout.write(options.json ? `${JSON.stringify({ kind, ...value })}\n` : `${kind}: ${JSON.stringify(value)}\n`);
+    };
+    const onSignal = () => { stop(); void room?.disconnect().catch(() => undefined); void client.disconnect(); };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    let inputTask = null;
+    try {
+        room = await client.rooms.connect(roomId, {
+            after,
+            onRoom: (active) => {
+                room = active;
+                if (stopped) {
+                    void active.disconnect();
+                    return;
+                }
+                active.subscribeAll((event) => write("event", { event }));
+                active.onMembersChanged((members) => write("members", { members }));
+                active.onOutOfSync((from, to) => write("gap", { from, to }));
+                active.onSendError((failure) => write("error", { message: failure.message }));
+                active.onStateChange((state) => {
+                    write("state", { state });
+                    if (state === "closed" || state === "expired")
+                        stop();
+                });
+            },
+        });
+        if (!stopped)
+            write("connected", { roomId, participantId: room.participantId, sequence: room.sequence });
+        if (!stopped && options.input) {
+            const active = room;
+            inputTask = (async () => {
+                let lineNumber = 0;
+                for await (const line of readRoomLines(process.stdin)) {
+                    if (stopped)
+                        break;
+                    lineNumber++;
+                    if (!line.trim())
+                        continue;
+                    try {
+                        const input = parseRoomInput(line);
+                        if (input.op === "presence")
+                            await active.setPresence(input.presence);
+                        else if (input.op === "send")
+                            active.send(input.type, input.data);
+                        else {
+                            const result = await active.publish(input.type, input.data);
+                            write("ack", { line: lineNumber, sequence: result.sequence, eventId: result.eventId });
+                        }
+                    }
+                    catch (cause) {
+                        write("input_error", { line: lineNumber, message: cause instanceof Error ? cause.message : String(cause) });
+                    }
+                }
+            })().catch((cause) => {
+                write("input_error", { message: cause instanceof Error ? cause.message : String(cause) });
+                process.exitCode = 1;
+                stop();
+            });
+        }
+        await done;
+    }
+    finally {
+        if (options.input)
+            process.stdin.destroy();
+        await room?.disconnect().catch(() => undefined);
+        await client.disconnect();
+        await inputTask?.catch(() => undefined);
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}

package/dist/commands/rooms-rtc-binary.d.ts

@@ -0,0 +1,2 @@
+export declare const RTC_HELPER_VERSION: string;
+export declare function ensureRtcBinary(local?: string): Promise<string>;

package/dist/commands/rooms-rtc-binary.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+// Pin a global release tag after its helper artifacts are published.
+export const RTC_HELPER_VERSION = "v2.67.0";
+const MAX_BINARY_BYTES = 128 * 1024 * 1024;
+async function digest(path) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(path), hash);
+    return hash.digest("hex");
+}
+async function readText(response, limit) {
+    if (!response.body)
+        throw new Error("Empty RTC helper response");
+    const reader = response.body.getReader();
+    const parts = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.length;
+            if (bytes > limit)
+                throw new Error("RTC helper metadata exceeds the size limit");
+            parts.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(parts).toString("utf8");
+}
+export async function ensureRtcBinary(local) {
+    const override = local || process.env.COHUB_RTC_BIN?.trim();
+    if (override) {
+        if (!(await lstat(override)).isFile())
+            throw new Error("RTC helper must be a regular file");
+        return resolve(override);
+    }
+    const platform = { linux: "linux", darwin: "darwin" }[process.platform];
+    const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
+    if (!platform || !arch)
+        throw new Error("Unsupported RTC helper platform; use --helper with a local binary");
+    const version = process.env.COHUB_RTC_VERSION?.trim() || RTC_HELPER_VERSION;
+    if (!version)
+        throw new Error("No RTC helper release is pinned yet; use --helper or COHUB_RTC_VERSION with a published global release");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(version))
+        throw new Error("Invalid RTC helper version");
+    const directory = join(homedir(), ".cache", "cohub", "rtc", version, `${platform}-${arch}`);
+    const binary = join(directory, "cohub-rtc");
+    const checksum = `${binary}.sha256`;
+    const expected = await readFile(checksum, "utf8").catch(() => "");
+    if (/^[a-f0-9]{64}$/.test(expected) && (await lstat(binary).catch(() => null))?.isFile() && await digest(binary) === expected)
+        return binary;
+    await mkdir(directory, { recursive: true });
+    const temporary = await mkdtemp(join(directory, ".download-"));
+    const base = (process.env.COHUB_RTC_CDN_BASE_URL?.trim() || "https://public.cohub.live/rtc").replace(/\/+$/, "");
+    const url = `${base}/${version}/cohub-rtc_${platform}_${arch}.gz`;
+    const signal = AbortSignal.timeout(120_000);
+    try {
+        const manifest = await fetch(`${url}.sha256`, { signal });
+        if (!manifest.ok)
+            throw new Error(`RTC helper ${version} is unavailable (${manifest.status}); use --helper with a locally built cohub-rtc`);
+        const text = await readText(manifest, 1024);
+        const expectedArchive = text.trim().split(/\s+/)[0];
+        if (!expectedArchive || !/^[a-f0-9]{64}$/.test(expectedArchive))
+            throw new Error("Invalid RTC helper checksum");
+        const response = await fetch(url, { signal });
+        if (!response.ok || !response.body)
+            throw new Error(`RTC helper download failed (${response.status})`);
+        let bytes = 0;
+        const bound = () => new Transform({ transform(chunk, _encoding, done) {
+                bytes += chunk.length;
+                done(bytes > MAX_BINARY_BYTES ? new Error("RTC helper exceeds the size limit") : null, chunk);
+            } });
+        const archive = join(temporary, "archive.gz");
+        await pipeline(Readable.fromWeb(response.body), bound(), createWriteStream(archive, { flags: "wx" }), { signal });
+        if (await digest(archive) !== expectedArchive)
+            throw new Error("RTC helper checksum mismatch");
+        for (const name of ["LICENSE", "NOTICE"]) {
+            const response = await fetch(`${base}/${version}/${name}`, { signal });
+            if (!response.ok)
+                throw new Error(`RTC helper ${name} is unavailable (${response.status})`);
+            const text = await readText(response, 64 * 1024);
+            await writeFile(join(temporary, name), text, { flag: "wx" });
+            await rename(join(temporary, name), join(directory, name));
+        }
+        const extracted = join(temporary, "cohub-rtc");
+        bytes = 0;
+        await pipeline(createReadStream(archive), createGunzip(), bound(), createWriteStream(extracted, { flags: "wx", mode: 0o700 }), { signal });
+        await chmod(extracted, 0o700);
+        const hash = await digest(extracted);
+        await writeFile(join(temporary, "checksum"), hash, { flag: "wx" });
+        await rename(extracted, binary);
+        await rename(join(temporary, "checksum"), checksum);
+        return binary;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/commands/rooms-rtc.d.ts

@@ -0,0 +1,21 @@
+export type RtcOptions = {
+    helper?: string;
+    audio?: string;
+    video?: string;
+    audioFormat: "pcm" | "opus";
+    videoFormat: "i420" | "vp8";
+    size?: string;
+    fps: string;
+    rate: string;
+    channels: string;
+    output?: string;
+    receiveFormat: "rtp" | "raw";
+    receiveSize: string;
+    maxBytes: string;
+    participant?: string;
+    channel?: string;
+    delivery: "reliable" | "latest";
+    dataInput?: string;
+    json?: boolean;
+};
+export declare function runRoomRtc(roomId: string, options: RtcOptions): Promise<void>;