@neta-art/cohub-cli 3.7.0 → 3.8.0

package/README.md

@@ -297,6 +297,49 @@ Use `--json` for machine-readable output. `works get`, `works stats`, and `works
 Realtime rooms use a published Work's runtime identity, so they are available
 through `client.work.realtime` in the SDK rather than as CLI commands.
 
+## Drive the Cohub UI
+
+Show a Work preview in the Cohub tab that started the current work, and call
+methods the Work exposes.
+
+```bash
+cohub ui preview <workId|url|cohub://works/...|username/space/work>
+cohub ui preview <work> --call selection.get
+cohub ui preview <work> --call board.focus --data '{"nodeId":"n1"}'
+cohub ui preview <work> --call report.build --input payload.json --json
+```
+
+`ui preview` accepts the same Work references as `works get`. Showing a preview is
+idempotent: repeating it re-activates the same tab and refreshes any launch state
+carried by the reference. With `--call`, the command waits for the Work to announce readiness, invokes the method,
+and waits for the Work to complete the same UI command with `client.ui.reportResult()`.
+
+Work authors decide what is callable by registering handlers inside the Work:
+
+```ts
+client.work.surface.handle("image.open", async (input, { commandId }) => {
+  openImageStudio(input, commandId);
+});
+```
+
+A Work answers only a Cohub app origin, so a third-party site that embeds it
+cannot invoke these methods.
+
+Retrying with the same `--command-id` re-delivers the command rather than
+returning a stale pending record, which recovers a dispatch that never reached the
+browser. The frontend dedupes by command id, so ordinary redelivery does not run
+twice.
+
+Delivery is at-least-once. Deduplication lives in the receiving tab's memory, so a
+retry that spans a page reload can run a `--call` method a second time. Prefer
+methods that are safe to repeat.
+
+Commands reach only the frontend instance that originated the current work,
+resolved from request provenance (`X-Cohub-Source-Client`, propagated into the
+Sandbox as `COHUB_SOURCE_CLIENT_ID`). They cannot target another user's browser,
+and offer no DOM access or script evaluation. Pass `--client` to address a
+specific instance of your own account, and `--command-id` to make retries safe.
+
 ## Saves
 
 ```bash

package/dist/commands/ui.d.ts

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

package/dist/commands/ui.js

@@ -0,0 +1,140 @@
+import { readFileSync } from "node:fs";
+import { parseWorkRef, UI_COMMAND_DEFAULT_TIMEOUT_MS, UI_COMMAND_MAX_TIMEOUT_MS, } from "@neta-art/cohub";
+import { createClient } from "../client.js";
+import { error, handleHttp, json as outJson, jsonRequested, ok } from "../output.js";
+import { getWorkByRef } from "../work-ref.js";
+function readCallInput(opts) {
+    if (opts.data !== undefined && opts.input !== undefined) {
+        return error("Conflicting input", "Use either --data or --input, not both.");
+    }
+    const raw = opts.data !== undefined
+        ? opts.data
+        : opts.input !== undefined
+            ? opts.input === "-"
+                ? readFileSync(0, "utf-8")
+                : readFileSync(opts.input, "utf-8")
+            : undefined;
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return error("Invalid input", "Call input must be valid JSON.");
+    }
+}
+function parseTimeout(value) {
+    if (!value)
+        return UI_COMMAND_DEFAULT_TIMEOUT_MS;
+    const parsed = Math.floor(Number(value));
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > UI_COMMAND_MAX_TIMEOUT_MS) {
+        return error("Invalid timeout", `--timeout-ms must be between 1 and ${UI_COMMAND_MAX_TIMEOUT_MS} milliseconds.`);
+    }
+    return parsed;
+}
+async function resolveWorkTarget(client, ref) {
+    const parsed = parseWorkRef(ref);
+    const detail = await getWorkByRef(client, ref);
+    return {
+        workId: detail.work.id,
+        label: detail.work.slug,
+        launch: {
+            ...(parsed.search ? { search: parsed.search } : {}),
+            ...(parsed.hash ? { hash: parsed.hash } : {}),
+        },
+    };
+}
+function reportDispatch(record) {
+    if (record.status !== "pending") {
+        reportOutcome(record, Boolean(record.command.request));
+        return;
+    }
+    ok(`UI command dispatched (${record.commandId})`);
+}
+function reportOutcome(record, called) {
+    if (record.status === "applied") {
+        ok(called ? "Work preview shown and method called" : "Work preview shown");
+        if (record.result !== undefined) {
+            console.log(typeof record.result === "string" ? record.result : JSON.stringify(record.result, null, 2));
+        }
+        return;
+    }
+    error(`UI command ${record.status}`, record.error?.message ?? "The Cohub frontend did not apply this command.");
+}
+export function registerUi(program) {
+    const ui = program
+        .command("ui")
+        .description("Drive the Cohub frontend that started this work")
+        .addHelpText("after", `
+Commands reach only the frontend instance that originated the current chat,
+resolved from request provenance. Nothing else can be targeted.
+
+Examples:
+  cohub ui preview <work-id>
+  cohub ui preview alice/studio/launch
+  cohub ui preview https://cohub.run/alice/studio/w/launch?view=timeline
+  cohub ui preview <work-id> --call selection.get
+  cohub ui preview <work-id> --call board.focus --data '{"nodeId":"n1"}'
+`);
+    const preview = ui
+        .command("preview <work>")
+        .description("Show a Work preview tab, optionally calling a method it exposes")
+        .option("--call <method>", "Method the Work registered via client.work.surface.handle()")
+        .option("--data <json>", "Inline JSON input for --call")
+        .option("-i, --input <file>", "JSON input file for --call; use - for stdin")
+        .option("--client <clientId>", "Target a specific frontend instance of your account")
+        .option("--command-id <id>", "Stable id so retries never dispatch twice")
+        .option("--no-wait", "Dispatch the command and exit without waiting for a result")
+        .option("--timeout-ms <ms>", `How long to wait for the frontend (default: ${UI_COMMAND_DEFAULT_TIMEOUT_MS}; max: ${UI_COMMAND_MAX_TIMEOUT_MS})`)
+        .option("--json", "Output as JSON")
+        .action(async (work, opts) => {
+        const callInput = opts.call ? readCallInput(opts) : undefined;
+        if (!opts.call && (opts.data !== undefined || opts.input !== undefined)) {
+            return error("Missing --call", "--data and --input only apply together with --call.");
+        }
+        if (opts.noWait && opts.timeoutMs !== undefined) {
+            return error("Conflicting wait options", "Use either --no-wait or --timeout-ms, not both.");
+        }
+        const timeoutMs = parseTimeout(opts.timeoutMs);
+        const client = createClient();
+        try {
+            const target = await resolveWorkTarget(client, work);
+            const request = opts.call
+                ? { method: opts.call, ...(callInput === undefined ? {} : { input: callInput }) }
+                : undefined;
+            const input = {
+                command: {
+                    type: "preview.show",
+                    preview: {
+                        kind: "work",
+                        workId: target.workId,
+                        label: target.label,
+                        ...(target.launch.search || target.launch.hash ? { launch: target.launch } : {}),
+                    },
+                    ...(request ? { request } : {}),
+                },
+                ...(opts.client ? { targetClientId: opts.client } : {}),
+                ...(opts.commandId ? { commandId: opts.commandId } : {}),
+            };
+            const record = opts.noWait
+                ? (await client.ui.create(input)).command
+                : await client.ui.run(input, { timeoutMs });
+            if (jsonRequested(opts))
+                return outJson(record);
+            if (opts.noWait)
+                return reportDispatch(record);
+            reportOutcome(record, Boolean(request));
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === "WorkRefParseError")
+                return error(e.message);
+            handleHttp(e);
+        }
+    });
+    preview.addHelpText("after", `
+Notes:
+  - Showing a preview is idempotent; repeating it re-activates the same tab.
+  - --call waits for the Work to announce readiness, then invokes the method.
+  - Which methods exist is up to the Work author.
+`);
+}

package/dist/index.js

@@ -18,6 +18,7 @@ import { registerPrompt, registerSpaces } from "./commands/spaces.js";
 import { maybeHandleRunCommand } from "./commands/run.js";
 import { registerSandbox } from "./commands/sandbox.js";
 import { registerTasks } from "./commands/tasks.js";
+import { registerUi } from "./commands/ui.js";
 import { registerWorks } from "./commands/works.js";
 import { ensureCliSelfUpdated } from "./self-update.js";
 const VERSION = (() => {
@@ -54,6 +55,7 @@ Common commands:
   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
+  cohub ui preview <work-id> --call selection.get
   cohub -s <space-id> spaces commerce products list
   cohub models ls
   cohub models ls --model-type multimodal
@@ -81,6 +83,7 @@ registerReferrals(program);
 registerTasks(program);
 registerCronJobs(program);
 registerWorks(program);
+registerUi(program);
 const isVersionRequest = (argv) => argv.some((arg) => arg === "-v" || arg === "--version");
 try {
     const argv = process.argv.slice(2);

package/dist/work-ref.d.ts

@@ -1,13 +1,5 @@
-import type { CohubHttpClient, WorkGetResponse } from "@neta-art/cohub";
-type WorkPublicRef = {
-    username: string;
-    spaceSlug: string;
-    workSlug: string;
-};
-export type ParsedWorkRef = {
-    id: string;
-} | WorkPublicRef;
-export declare function parseWorkRef(input: string): ParsedWorkRef;
-export declare function formatWorkRef(ref: ParsedWorkRef): string;
+import type { CohubHttpClient, ParsedWorkRef, WorkGetResponse } from "@neta-art/cohub";
+import { formatWorkRef, parseWorkRef } from "@neta-art/cohub";
+export type { ParsedWorkRef };
+export { formatWorkRef, parseWorkRef };
 export declare function getWorkByRef(client: CohubHttpClient, input: string): Promise<WorkGetResponse>;
-export {};

package/dist/work-ref.js

@@ -1,58 +1,5 @@
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-const USERNAME_PATTERN = /^(?!-)(?!.*--)[a-z0-9-]{1,39}(?<!-)$/;
-const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9_-]{0,78}[a-z0-9])?$/;
-function decodePart(value) {
-    try {
-        return decodeURIComponent(value).trim();
-    }
-    catch {
-        return "";
-    }
-}
-function publicRef(parts) {
-    if (parts.length !== 3)
-        return null;
-    const [username = "", spaceSlug = "", workSlug = ""] = parts.map(decodePart);
-    return USERNAME_PATTERN.test(username) && SLUG_PATTERN.test(spaceSlug) && SLUG_PATTERN.test(workSlug)
-        ? { username, spaceSlug, workSlug }
-        : null;
-}
-function parseUrlRef(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        return null;
-    }
-    const parts = url.pathname.split("/").filter(Boolean);
-    if (url.protocol === "cohub:" && url.hostname === "works")
-        return publicRef(parts) ?? null;
-    if (url.protocol !== "http:" && url.protocol !== "https:")
-        return null;
-    if (parts.length === 4 && parts[0] === "spaces" && UUID_PATTERN.test(parts[1] ?? "") && parts[2] === "works" && UUID_PATTERN.test(parts[3] ?? "")) {
-        return { id: parts[3] };
-    }
-    if (parts.length === 4 && parts[2] === "w")
-        return publicRef([parts[0], parts[1], parts[3]]);
-    return null;
-}
-export function parseWorkRef(input) {
-    const value = input.trim();
-    if (UUID_PATTERN.test(value))
-        return { id: value };
-    const parsedUrl = parseUrlRef(value.includes("://") ? value : value.startsWith("/") ? `https://cohub.invalid${value}` : value);
-    if (parsedUrl)
-        return parsedUrl;
-    const parts = value.split("/").filter(Boolean);
-    const parsedPublic = parts.length === 3 ? publicRef(parts) : null;
-    if (parsedPublic)
-        return parsedPublic;
-    throw new Error("Work must be an id, public URL, cohub://works URI, or username/space/work reference");
-}
-export function formatWorkRef(ref) {
-    return "id" in ref ? ref.id : `${ref.username}/${ref.spaceSlug}/${ref.workSlug}`;
-}
+import { formatWorkRef, parseWorkRef } from "@neta-art/cohub";
+export { formatWorkRef, parseWorkRef };
 export function getWorkByRef(client, input) {
     const ref = parseWorkRef(input);
     return "id" in ref

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "CLI for Cohub — spaces, sessions, and agent collaboration.",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,7 @@
     "commander": "^15.0.0",
     "pixi.js": "^8.19.0",
     "sharp": "^0.35.3",
-    "@neta-art/cohub": "5.2.0"
+    "@neta-art/cohub": "5.3.0"
   },
   "publishConfig": {
     "access": "public"