@neta-art/cohub-cli 4.0.0 → 6.0.0

package/README.md

@@ -157,72 +157,44 @@ 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. Inspect `boards capabilities --json` for the
-supported node types, enums, and coordinate spaces.
-
-```json
-{
-  "nodes": [
-    {
-      "nodeId": "goal",
-      "type": "geo",
-      "parentId": null,
-      "orderKey": null,
-      "x": 80,
-      "y": 80,
-      "width": 240,
-      "height": 120,
-      "rotation": 0,
-      "refKind": null,
-      "refPath": null,
-      "refUrl": null,
-      "view": {},
-      "style": {},
-      "data": {
-        "geo": "rectangle",
-        "text": "Ship",
-        "color": "green",
-        "fillOpacity": 0.12
-      }
-    }
-  ]
-}
+Pass semantic items, effects, and compositions as JSON when creating a Board. The path and title stay explicit in the command. Generate editable templates instead of guessing fields:
+
+```bash
+cohub boards examples create > board-content.json
+cohub boards examples item geo > item.json
+cohub boards examples effect pulse > effect.json
+cohub boards examples composition fade > intro.json
 ```
 
+Inspect `boards capabilities --json` for supported Item types, animation channels, effect kinds, and coordinate spaces.
+
 ```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" } }
-    }
-  ]
-}
+Generate editable semantic JSON templates instead of authoring storage transactions:
+
+```bash
+cohub boards examples item text > item.json
+cohub boards items create <boardId> --input item.json
+
+cohub boards examples composition fade > intro.json
+cohub boards compositions apply <boardId> --input intro.json
+
+cohub boards examples effect pulse > effect.json
+cohub boards effects apply <boardId> --input effect.json
 ```
 
+Use `--mutation-id` or `--command-id` when a script needs a stable idempotency key across retries.
+
 ```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 play <boardId> <compositionId>
 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/app-download.d.ts

@@ -0,0 +1,11 @@
+import type { AppGetResponse } from "@neta-art/cohub";
+type DownloadResult = {
+    appId: string;
+    version: number;
+    kind: "file" | "directory";
+    output: string;
+    files: number;
+    bytes: number;
+};
+export declare function downloadApp(detail: AppGetResponse, outputOption?: string, fetcher?: typeof fetch): Promise<DownloadResult>;
+export {};

package/dist/{work-download.js → app-download.js}

@@ -9,11 +9,11 @@ const MAX_CONTENT_FILE_BYTES = 1024 * 1024 * 1024;
 const DOWNLOAD_CONCURRENCY = 4;
 function safeRelativePath(value, label) {
     if (!value || value.includes("\\") || value.includes("\0") || posix.isAbsolute(value)) {
-        throw new Error(`Invalid ${label} in Work manifest`);
+        throw new Error(`Invalid ${label} in app manifest`);
     }
     const segments = value.split("/");
     if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
-        throw new Error(`Invalid ${label} in Work manifest`);
+        throw new Error(`Invalid ${label} in app manifest`);
     }
     return posix.normalize(value);
 }
@@ -31,7 +31,7 @@ function isManifestFile(value) {
 }
 function parseManifest(value) {
     if (!value || typeof value !== "object")
-        throw new Error("Work download manifest is invalid");
+        throw new Error("App download manifest is invalid");
     const manifest = value;
     if (manifest.kind !== "cohub.work.artifact-manifest"
         || manifest.version !== 1
@@ -45,7 +45,7 @@ function parseManifest(value) {
         || !Array.isArray(manifest.files)
         || !manifest.files.every(isManifestFile)
         || manifest.files.length !== manifest.fileCount) {
-        throw new Error("Work download manifest is invalid");
+        throw new Error("App download manifest is invalid");
     }
     const seenArtifactPaths = new Set();
     const seenOutputPaths = new Set();
@@ -54,26 +54,26 @@ function parseManifest(value) {
         file.artifactPath = safeRelativePath(file.artifactPath, "artifact path");
         file.outputPath = safeRelativePath(file.outputPath, "output path");
         if (seenArtifactPaths.has(file.artifactPath) || seenOutputPaths.has(file.outputPath)) {
-            throw new Error("Work download manifest contains duplicate paths");
+            throw new Error("App download manifest contains duplicate paths");
         }
         seenArtifactPaths.add(file.artifactPath);
         seenOutputPaths.add(file.outputPath);
         sizeBytes += file.sizeBytes;
     }
     if (sizeBytes !== manifest.sizeBytes)
-        throw new Error("Work download manifest size is invalid");
+        throw new Error("App download manifest size is invalid");
     safeRelativePath(manifest.entrypoint, "entrypoint");
     return manifest;
 }
 async function readManifest(url, expectedSha256, fetcher) {
     const response = await fetcher(url);
     if (!response.ok)
-        throw new Error(`Failed to download Work manifest (${response.status})`);
+        throw new Error(`Failed to download app manifest (${response.status})`);
     if (!response.body)
-        throw new Error("Work download manifest is invalid");
+        throw new Error("App download manifest is invalid");
     const contentLength = Number(response.headers.get("content-length") ?? 0);
     if (Number.isFinite(contentLength) && contentLength > MANIFEST_MAX_BYTES) {
-        throw new Error("Work download manifest is too large");
+        throw new Error("App download manifest is too large");
     }
     const chunks = [];
     let sizeBytes = 0;
@@ -81,19 +81,19 @@ async function readManifest(url, expectedSha256, fetcher) {
         const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         sizeBytes += bytes.byteLength;
         if (sizeBytes > MANIFEST_MAX_BYTES)
-            throw new Error("Work download manifest is too large");
+            throw new Error("App download manifest is too large");
         chunks.push(bytes);
     }
     const bytes = Buffer.concat(chunks, sizeBytes);
     const sha256 = createHash("sha256").update(bytes).digest("hex");
     if (sha256 !== expectedSha256)
-        throw new Error("Work download manifest checksum mismatch");
+        throw new Error("App download manifest checksum mismatch");
     let parsed;
     try {
         parsed = JSON.parse(bytes.toString("utf8"));
     }
     catch {
-        throw new Error("Work download manifest is invalid");
+        throw new Error("App download manifest is invalid");
     }
     return parseManifest(parsed);
 }
@@ -203,25 +203,25 @@ async function downloadFiles(input) {
         throw failure;
     return downloadedBytes.reduce((sum, size) => sum + size, 0);
 }
-export async function downloadWork(detail, outputOption, fetcher = fetch) {
-    const { work, content } = detail;
+export async function downloadApp(detail, outputOption, fetcher = fetch) {
+    const { app, content } = detail;
     if (!content)
-        throw new Error("This Work has no published downloadable artifact");
+        throw new Error("This app has no published downloadable artifact");
     if (content.kind === "port")
-        throw new Error("Port Works do not have a downloadable artifact");
+        throw new Error("Port apps do not have a downloadable artifact");
     if (content.kind === "board")
-        throw new Error("Board Works do not have a restorable file or directory artifact");
+        throw new Error("Board apps do not have a restorable file or directory artifact");
     if (!content.download)
-        throw new Error("This Work version does not support download");
+        throw new Error("This app version does not support download");
     const manifest = await readManifest(content.download.manifestUrl, content.download.manifestSha256, fetcher);
     if (manifest.targetType !== content.targetType || manifest.targetRef !== content.path) {
-        throw new Error("Work download manifest does not match the published artifact");
+        throw new Error("App download manifest does not match the published artifact");
     }
     const entry = manifest.files.find((file) => file.artifactPath === manifest.entrypoint);
     if (!entry)
-        throw new Error("Work download manifest entrypoint is missing");
+        throw new Error("App download manifest entrypoint is missing");
     const hasDirectoryOutput = manifest.targetType === "directory" || manifest.files.length > 1;
-    const output = resolve(outputOption ?? (hasDirectoryOutput ? work.slug : basename(manifest.targetRef)));
+    const output = resolve(outputOption ?? (hasDirectoryOutput ? app.slug : basename(manifest.targetRef)));
     await assertOutputMissing(output);
     await mkdir(dirname(output), { recursive: true });
     const stage = await mkdtemp(join(dirname(output), `.${basename(output)}.cohub-download-`));
@@ -237,8 +237,8 @@ export async function downloadWork(detail, outputOption, fetcher = fetch) {
             await rm(stage, { recursive: true, force: true });
         }
         return {
-            workId: work.id,
-            version: work.latestVersion,
+            appId: app.id,
+            version: app.latestVersion,
             kind: hasDirectoryOutput ? "directory" : "file",
             output,
             files: files.length,

package/dist/app-ref.d.ts

@@ -0,0 +1,5 @@
+import type { CohubHttpClient, ParsedAppRef, AppGetResponse } from "@neta-art/cohub";
+import { formatAppRef, parseAppRef } from "@neta-art/cohub";
+export type { ParsedAppRef };
+export { formatAppRef, parseAppRef };
+export declare function getAppByRef(client: CohubHttpClient, input: string): Promise<AppGetResponse>;

package/dist/app-ref.js

@@ -0,0 +1,8 @@
+import { formatAppRef, parseAppRef } from "@neta-art/cohub";
+export { formatAppRef, parseAppRef };
+export function getAppByRef(client, input) {
+    const ref = parseAppRef(input);
+    return "id" in ref
+        ? client.apps.get(ref.id)
+        : client.apps.getBySlug(ref.username, ref.spaceSlug, ref.appSlug);
+}

package/dist/board-export.js

@@ -9,7 +9,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
-import { boardBootstrapToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
+import { boardAuthoringSnapshotToDocument, boardImageKeySource, imageAssetKey, planBoardExport, selectBoardExportAssets, } from "@neta-art/cohub/board";
 import { createBoardHeadlessRenderer, exportBoardImageBytes, } from "@neta-art/cohub/board/headless";
 import { resolveBoardId } from "./board-command-support.js";
 import { createClient } from "./client.js";
@@ -64,11 +64,11 @@ export function resolveBundledFonts() {
 export async function loadBoardDocument(spaceId, target) {
     const client = createClient();
     const boardId = await resolveBoardId(spaceId, target);
-    const bootstrap = await client.space(spaceId).board(boardId).inspect({ include: ["nodes"] });
+    const snapshot = await client.space(spaceId).board(boardId).authoring({ include: ["items", "connections"] });
     return {
-        document: boardBootstrapToDocument(bootstrap),
-        boardId: bootstrap.board.id,
-        title: bootstrap.board.title ?? null,
+        document: boardAuthoringSnapshotToDocument(snapshot),
+        boardId: snapshot.board.id,
+        title: snapshot.board.title ?? null,
     };
 }
 /**

package/dist/commands/app-commerce.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerAppCommerce(appsCmd: Command): void;

package/dist/commands/{work-commerce.js → app-commerce.js}

@@ -69,31 +69,31 @@ function printOrder(order) {
         { key: "paidAt", label: "Paid At" },
     ]);
 }
-export function registerWorkCommerce(worksCmd) {
-    const commerceCmd = worksCmd
+export function registerAppCommerce(appsCmd) {
+    const commerceCmd = appsCmd
         .command("commerce")
-        .description("Work commerce operations")
+        .description("App commerce operations")
         .addHelpText("after", `
 Examples:
-  cohub works commerce products resolve --work-id <work-id> --product-key pro_pack
-  cohub works commerce entitlements --work-id <work-id>
-  cohub works commerce credits consume --work-id <work-id> --amount 100
+  cohub apps commerce products resolve --app-id <app-id> --product-key pro_pack
+  cohub apps commerce entitlements --app-id <app-id>
+  cohub apps commerce credits consume --app-id <app-id> --amount 100
 `);
     const productsCmd = commerceCmd
         .command("products")
         .description("Resolve commerce products");
     productsCmd
         .command("resolve")
-        .description("Resolve public products for a work")
-        .option("--work-id <id>", "Work ID")
+        .description("Resolve public products for an app")
+        .option("--app-id <id>", "App ID")
         .option("--product-key <key>", "Product key", collectOption)
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const appId = requireText(opts.appId, "app ID", "--app-id <id>");
         const productKeys = requireList(opts.productKey, "product key", "--product-key <key>");
         const client = createClient();
         try {
-            const result = await client.workCommerce.resolveProducts(workId, { productKeys });
+            const result = await client.appCommerce.resolveProducts(appId, { productKeys });
             if (jsonRequested(opts))
                 return outJson(result);
             printProducts(result.products);
@@ -104,14 +104,14 @@ Examples:
     });
     commerceCmd
         .command("entitlements")
-        .description("Show viewer entitlements and credit balance for a work")
-        .option("--work-id <id>", "Work ID")
+        .description("Show viewer entitlements and credit balance for an app")
+        .option("--app-id <id>", "App ID")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const appId = requireText(opts.appId, "app ID", "--app-id <id>");
         const client = createClient();
         try {
-            const result = await client.workCommerce.getEntitlements(workId);
+            const result = await client.appCommerce.getEntitlements(appId);
             if (jsonRequested(opts))
                 return outJson(result);
             printEntitlements(result);
@@ -122,17 +122,17 @@ Examples:
     });
     const creditsCmd = commerceCmd
         .command("credits")
-        .description("Consume credits for a work");
+        .description("Consume credits for an app");
     creditsCmd
         .command("consume")
-        .description("Consume credits for a work (self by default)")
-        .option("--work-id <id>", "Work ID")
+        .description("Consume credits for an app (self by default)")
+        .option("--app-id <id>", "App ID")
         .option("--amount <n>", "Positive integer credit amount")
         .option("--operation-id <id>", "Idempotency key (generated when omitted)")
         .option("--reason <text>", "Reason for the consumption")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const appId = requireText(opts.appId, "app ID", "--app-id <id>");
         const amountText = requireText(opts.amount, "amount", "--amount <n>");
         const amount = Number.parseInt(amountText, 10);
         if (!Number.isSafeInteger(amount) || amount <= 0) {
@@ -141,7 +141,7 @@ Examples:
         const operationId = opts.operationId?.trim() || crypto.randomUUID();
         const client = createClient();
         try {
-            const result = await client.workCommerce.consumeCredits(workId, {
+            const result = await client.appCommerce.consumeCredits(appId, {
                 amount,
                 operationId,
                 reason: opts.reason,
@@ -167,16 +167,16 @@ Examples:
     });
     commerceCmd
         .command("purchase")
-        .description("Create a work purchase checkout")
-        .option("--work-id <id>", "Work ID")
+        .description("Create an app purchase checkout")
+        .option("--app-id <id>", "App ID")
         .option("--product-key <key>", "Product key")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const appId = requireText(opts.appId, "app ID", "--app-id <id>");
         const productKey = requireText(opts.productKey, "product key", "--product-key <key>");
         const client = createClient();
         try {
-            const result = await client.workCommerce.purchase(workId, { productKey });
+            const result = await client.appCommerce.purchase(appId, { productKey });
             if (jsonRequested(opts))
                 return outJson(result);
             ok(`Checkout created: ${result.checkout.orderId}`);
@@ -205,16 +205,16 @@ Examples:
         .description("Look up commerce orders");
     ordersCmd
         .command("get")
-        .description("Show a work commerce order")
-        .option("--work-id <id>", "Work ID")
+        .description("Show an app commerce order")
+        .option("--app-id <id>", "App ID")
         .option("--order-id <id>", "Order ID")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const workId = requireText(opts.workId, "work ID", "--work-id <id>");
+        const appId = requireText(opts.appId, "app ID", "--app-id <id>");
         const orderId = requireText(opts.orderId, "order ID", "--order-id <id>");
         const client = createClient();
         try {
-            const result = await client.workCommerce.getOrder(workId, orderId);
+            const result = await client.appCommerce.getOrder(appId, orderId);
             if (jsonRequested(opts))
                 return outJson(result);
             printOrder(result.order);

package/dist/commands/apps.d.ts

@@ -0,0 +1,4 @@
+import { type CohubHttpClient, type AppViewStatsResponse } from "@neta-art/cohub";
+import type { Command } from "commander";
+export declare function getAppStatsByRef(client: CohubHttpClient, app: string): Promise<AppViewStatsResponse>;
+export declare function registerApps(program: Command): void;