@neta-art/cohub-cli 3.5.1 → 3.6.0

package/README.md

@@ -63,6 +63,7 @@ cohub spaces get <spaceId> --json
 cohub -s <spaceId> spaces get
 COHUB_SPACE_ID=<spaceId> cohub spaces get
 cohub spaces create --name "<name>" --description "<description>" --json
+cohub spaces create --name "<name>" --checkpoint <checkpointId> --json
 cohub spaces update <spaceId> --slug <space-slug>
 cohub spaces rename <spaceId> "<new name>"
 cohub -s <spaceId> spaces invites create --role builder --days 7
@@ -274,7 +275,8 @@ Publish and manage Work entries from a Space workspace. Public Work URLs require
 cohub profile update --username <username>
 cohub spaces update <spaceId> --slug <space-slug>
 cohub -s <spaceId> works ls --json
-cohub works get <workId> --json
+cohub works get <workId|url|username/space/work> --json
+cohub works download <workId|url|username/space/work> --output <path>
 cohub -s <spaceId> works publish demo --file dist/index.html
 cohub -s <spaceId> works publish site --dir dist
 cohub -s <spaceId> works publish app --port 3000
@@ -289,7 +291,10 @@ Resolve a published Work by public identity:
 cohub works resolve <workSlug> --owner <username> --space-slug <spaceSlug>
 ```
 
-Use `--json` for machine-readable output. The resolve command requires both `--owner` and `--space-slug` so missing public profile data fails with a clear message.
+Use `--json` for machine-readable output. `works get` and `works download` also accept `cohub://works/<username>/<space>/<work>` mention URIs. Download restores newly published file and directory artifacts directly from the CDN with checksum verification. HTML files with companion assets are restored as directory bundles; Board and port Works are not downloadable. The resolve command remains available for explicit slug-based lookup.
+
+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.
 
 ## Saves
 

package/dist/commands/sandbox.d.ts

@@ -1,2 +1,3 @@
 import type { Command } from "commander";
+export declare const resolveLocalSpaceName: (rootDir: string, requestedName?: string) => string;
 export declare function registerSandbox(program: Command): void;

package/dist/commands/sandbox.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { stat } from "node:fs/promises";
 import { createInterface } from "node:readline";
-import { resolve } from "node:path";
+import { basename, resolve } from "node:path";
 import { resolveCohubEnvironment, resolveWebsocketUrl } from "@neta-art/cohub";
 import { requireAccessToken } from "../auth.js";
 import { createClient } from "../client.js";
@@ -28,6 +28,7 @@ const confirm = async (question) => {
     }
 };
 const webBaseUrl = () => resolveCohubEnvironment() === "prod" ? "https://cohub.run" : "https://dev.cohub.run";
+export const resolveLocalSpaceName = (rootDir, requestedName) => requestedName?.trim() || basename(rootDir) || "local-space";
 // Consent copy is deliberately explicit: a local sandbox runs agent-issued
 // shell commands as the current OS user. File RPCs are fenced to the folder,
 // but shell commands are NOT — they can read/write anything the user can
@@ -97,7 +98,7 @@ export function registerSandbox(program) {
                     return error("Aborted", "No space was created");
             }
             const created = await client.spaces.create({
-                name: opts.name,
+                name: resolveLocalSpaceName(rootDir, opts.name),
                 config: { sandbox: { provider: "local" } },
             });
             spaceId = created.space.id;

package/dist/commands/spaces.d.ts

@@ -1,3 +1,17 @@
+import type { CohubHttpClient, CreateSpaceInput } from "@neta-art/cohub";
 import type { Command } from "commander";
+export type SpaceCreateOptions = {
+    name: string;
+    description?: string;
+    checkpoint?: string;
+    autoDestroy?: string;
+    idleTtl?: string;
+    spec?: string;
+    json?: boolean;
+};
+export declare function buildSpaceCreateInput(opts: SpaceCreateOptions): CreateSpaceInput;
 export declare function registerPrompt(program: Command): void;
+export declare function registerSpaceCreate(spacesCmd: Command, dependencies?: {
+    createClient?: () => CohubHttpClient;
+}): Command;
 export declare function registerSpaces(program: Command): void;

package/dist/commands/spaces.js

@@ -67,6 +67,31 @@ const parseAutoDestroy = (opts) => {
     return { mode: "idle", ttlSeconds };
 };
 const parseSandboxSpec = (value) => value ? parseChoice(value, "sandbox spec", SANDBOX_SPEC_IDS) : undefined;
+export function buildSpaceCreateInput(opts) {
+    const autoDestroy = parseAutoDestroy(opts);
+    const spec = parseSandboxSpec(opts.spec);
+    const checkpointId = opts.checkpoint?.trim();
+    if (opts.checkpoint !== undefined && !checkpointId) {
+        return error("Invalid checkpoint", "Checkpoint ID is required");
+    }
+    return {
+        name: opts.name,
+        description: opts.description,
+        ...(checkpointId
+            ? { bootstrapSource: { type: "checkpoint", checkpointId } }
+            : {}),
+        ...((autoDestroy || spec)
+            ? {
+                config: {
+                    sandbox: {
+                        ...(autoDestroy ? { autoDestroy } : {}),
+                        ...(spec ? { spec } : {}),
+                    },
+                },
+            }
+            : {}),
+    };
+}
 const formatAutoDestroy = (policy) => {
     if (!policy)
         return `${cliEnv === "prod" ? "12h" : "10m"} (default)`;
@@ -376,6 +401,36 @@ export function registerPrompt(program) {
         .option("--json", "Output as JSON")
         .action((words, opts) => runCompletionCommand(program, words, opts));
 }
+export function registerSpaceCreate(spacesCmd, dependencies = {}) {
+    const getClient = dependencies.createClient ?? createClient;
+    return spacesCmd
+        .command("create")
+        .description("Create a new space")
+        .requiredOption("-n, --name <name>", "Space name")
+        .option("-d, --description <desc>", "Space description")
+        .option("--checkpoint <id>", "Create from a checkpoint")
+        .option("--auto-destroy <mode>", "Sandbox auto destroy mode: idle or never")
+        .option("--idle-ttl <seconds>", "Idle auto destroy TTL in seconds, max 2592000 (30d)")
+        .option("--spec <spec>", "Sandbox spec: standard, boost, or ultra")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const client = getClient();
+        try {
+            const result = await client.spaces.create(buildSpaceCreateInput(opts));
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Space created: ${result.space.id}`);
+            table([{ ...result.space, taskRunId: result.taskRunId }], [
+                { key: "id", label: "ID" },
+                { key: "name", label: "Name" },
+                { key: "taskRunId", label: "Task" },
+            ]);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
+}
 export function registerSpaces(program) {
     const spacesCmd = program.command("spaces").description("Space management");
     registerSpaceInvitations(spacesCmd);
@@ -441,38 +496,7 @@ export function registerSpaces(program) {
         }
     });
     // ── spaces create ──
-    spacesCmd
-        .command("create")
-        .description("Create a new space")
-        .option("-n, --name <name>", "Space name")
-        .option("-d, --description <desc>", "Space description")
-        .option("--auto-destroy <mode>", "Sandbox auto destroy mode: idle or never")
-        .option("--idle-ttl <seconds>", "Idle auto destroy TTL in seconds, max 2592000 (30d)")
-        .option("--spec <spec>", "Sandbox spec: standard, boost, or ultra")
-        .option("--json", "Output as JSON")
-        .action(async (opts) => {
-        const client = createClient();
-        try {
-            const autoDestroy = parseAutoDestroy(opts);
-            const spec = parseSandboxSpec(opts.spec);
-            const result = await client.spaces.create({
-                name: opts.name,
-                description: opts.description,
-                ...((autoDestroy || spec) ? { config: { sandbox: { ...(autoDestroy ? { autoDestroy } : {}), ...(spec ? { spec } : {}) } } } : {}),
-            });
-            if (jsonRequested(opts))
-                return outJson(result);
-            ok(`Space created: ${result.space.id}`);
-            table([result.space], [
-                { key: "id", label: "ID" },
-                { key: "name", label: "Name" },
-                { key: "taskRunId", label: "Task" },
-            ]);
-        }
-        catch (e) {
-            handleHttp(e);
-        }
-    });
+    registerSpaceCreate(spacesCmd);
     // ── spaces update ──
     spacesCmd
         .command("update <id>")

package/dist/commands/tasks.d.ts

@@ -1,2 +1,8 @@
 import type { Command } from "commander";
-export declare function registerTasks(program: Command): void;
+import { createClient } from "../client.js";
+type TasksClient = ReturnType<typeof createClient>;
+type RegisterTasksDependencies = {
+    createClient?: () => TasksClient;
+};
+export declare function registerTasks(program: Command, dependencies?: RegisterTasksDependencies): void;
+export {};

package/dist/commands/tasks.js

@@ -1,6 +1,7 @@
 import { createClient } from "../client.js";
 import { table, json as outJson, jsonRequested, handleHttp } from "../output.js";
-export function registerTasks(program) {
+export function registerTasks(program, dependencies = {}) {
+    const getClient = dependencies.createClient ?? createClient;
     const cmd = program.command("tasks", { hidden: true }).description("Task runs");
     cmd
         .command("ls")
@@ -15,16 +16,17 @@ export function registerTasks(program) {
         .option("--cursor <cursor>", "Page cursor")
         .option("--json", "Output as JSON")
         .action(async (opts) => {
-        const client = createClient();
+        const client = getClient();
         try {
             const limit = opts.limit ? Number(opts.limit) : 50;
             if (!Number.isFinite(limit) || limit < 1)
                 throw new Error("limit must be a positive number");
             const filters = { limit: Math.floor(limit) };
+            const spaceId = opts.space ?? program.opts().space;
             if (opts.cronJob)
                 filters.cronJobId = opts.cronJob;
-            if (opts.space)
-                filters.spaceId = opts.space;
+            if (spaceId)
+                filters.spaceId = spaceId;
             if (opts.session)
                 filters.sessionId = opts.session;
             if (opts.type)
@@ -58,7 +60,7 @@ export function registerTasks(program) {
         .description("Task run details")
         .option("--json", "Output as JSON")
         .action(async (id, opts) => {
-        const client = createClient();
+        const client = getClient();
         try {
             const result = await client.tasks.get(id);
             if (jsonRequested(opts))

package/dist/commands/works.js

@@ -2,6 +2,8 @@ import { HttpError } from "@neta-art/cohub";
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
+import { downloadWork } from "../work-download.js";
+import { getWorkByRef } from "../work-ref.js";
 import { registerWorkCommerce } from "./work-commerce.js";
 const WORK_STATUSES = ["published", "disabled"];
 const WORK_VISIBILITIES = ["public", "space"];
@@ -143,13 +145,13 @@ export function registerWorks(program) {
         }
     });
     worksCmd
-        .command("get <id>")
-        .description("Show work details")
+        .command("get <work>")
+        .description("Show work details by id, URL, mention URI, or username/space/work")
         .option("--json", "Output as JSON")
-        .action(async (id, opts) => {
+        .action(async (work, opts) => {
         const client = createClient();
         try {
-            const result = await client.works.get(id);
+            const result = await getWorkByRef(client, work);
             if (jsonRequested(opts))
                 return outJson(result);
             printWork(result.work);
@@ -159,6 +161,24 @@ export function registerWorks(program) {
             handleHttp(e);
         }
     });
+    worksCmd
+        .command("download <work>")
+        .description("Download a published file or directory Work")
+        .option("-o, --output <path>", "Output file or directory")
+        .option("--json", "Output as JSON")
+        .action(async (work, opts) => {
+        const client = createClient();
+        try {
+            const detail = await getWorkByRef(client, work);
+            const result = await downloadWork(detail, opts.output);
+            if (jsonRequested(opts))
+                return outJson(result);
+            ok(`Downloaded ${result.files} file${result.files === 1 ? "" : "s"} to ${result.output}`);
+        }
+        catch (e) {
+            handleHttp(e);
+        }
+    });
     worksCmd
         .command("resolve <workSlug>")
         .description("Resolve a published work by owner and space slug")

package/dist/work-download.d.ts

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

package/dist/work-download.js

@@ -0,0 +1,254 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { link, lstat, mkdir, mkdtemp, rename, rm, rmdir } from "node:fs/promises";
+import { basename, dirname, join, posix, resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+const MANIFEST_MAX_BYTES = 4 * 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`);
+    }
+    const segments = value.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new Error(`Invalid ${label} in Work manifest`);
+    }
+    return posix.normalize(value);
+}
+function isManifestFile(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const file = value;
+    return typeof file.artifactPath === "string"
+        && typeof file.outputPath === "string"
+        && (typeof file.mimeType === "string" || file.mimeType === null)
+        && Number.isSafeInteger(file.sizeBytes)
+        && Number(file.sizeBytes) >= 0
+        && typeof file.sha256 === "string"
+        && /^[0-9a-f]{64}$/i.test(file.sha256);
+}
+function parseManifest(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Work download manifest is invalid");
+    const manifest = value;
+    if (manifest.kind !== "cohub.work.artifact-manifest"
+        || manifest.version !== 1
+        || (manifest.targetType !== "file" && manifest.targetType !== "directory")
+        || typeof manifest.targetRef !== "string"
+        || typeof manifest.entrypoint !== "string"
+        || !Number.isSafeInteger(manifest.fileCount)
+        || Number(manifest.fileCount) < 1
+        || !Number.isSafeInteger(manifest.sizeBytes)
+        || Number(manifest.sizeBytes) < 0
+        || !Array.isArray(manifest.files)
+        || !manifest.files.every(isManifestFile)
+        || manifest.files.length !== manifest.fileCount) {
+        throw new Error("Work download manifest is invalid");
+    }
+    const seenArtifactPaths = new Set();
+    const seenOutputPaths = new Set();
+    let sizeBytes = 0;
+    for (const file of manifest.files) {
+        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");
+        }
+        seenArtifactPaths.add(file.artifactPath);
+        seenOutputPaths.add(file.outputPath);
+        sizeBytes += file.sizeBytes;
+    }
+    if (sizeBytes !== manifest.sizeBytes)
+        throw new Error("Work 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})`);
+    if (!response.body)
+        throw new Error("Work 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");
+    }
+    const chunks = [];
+    let sizeBytes = 0;
+    for await (const chunk of Readable.fromWeb(response.body)) {
+        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");
+        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");
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new Error("Work download manifest is invalid");
+    }
+    return parseManifest(parsed);
+}
+function artifactUrl(contentUrl, artifactPath) {
+    const base = new URL("./", contentUrl);
+    const encodedPath = safeRelativePath(artifactPath, "artifact path")
+        .split("/")
+        .map(encodeURIComponent)
+        .join("/");
+    return new URL(encodedPath, base).toString();
+}
+async function downloadFile(url, output, expected, fetcher) {
+    const response = await fetcher(url);
+    if (!response.ok || !response.body)
+        throw new Error(`Failed to download ${expected.outputPath} (${response.status})`);
+    await mkdir(dirname(output), { recursive: true });
+    let sizeBytes = 0;
+    const hash = createHash("sha256");
+    const verifier = new Transform({
+        transform(chunk, _encoding, callback) {
+            sizeBytes += chunk.byteLength;
+            if (sizeBytes > expected.sizeBytes) {
+                callback(new Error(`Downloaded file verification failed: ${expected.outputPath}`));
+                return;
+            }
+            hash.update(chunk);
+            callback(null, chunk);
+        },
+    });
+    await pipeline(Readable.fromWeb(response.body), verifier, createWriteStream(output, { flags: "wx" }));
+    if (sizeBytes !== expected.sizeBytes || hash.digest("hex") !== expected.sha256) {
+        throw new Error(`Downloaded file verification failed: ${expected.outputPath}`);
+    }
+}
+function outputExistsError(output) {
+    return new Error(`Output already exists: ${output}`);
+}
+async function outputExists(output) {
+    return Boolean(await lstat(output).catch((cause) => {
+        if (cause.code === "ENOENT")
+            return null;
+        throw cause;
+    }));
+}
+async function assertOutputMissing(output) {
+    if (await outputExists(output))
+        throw outputExistsError(output);
+}
+async function installFileNoReplace(stagedFile, output) {
+    try {
+        await link(stagedFile, output);
+    }
+    catch (cause) {
+        if (cause.code === "EEXIST")
+            throw outputExistsError(output);
+        throw cause;
+    }
+}
+async function installDirectoryNoReplace(stage, output) {
+    if (process.platform === "win32") {
+        try {
+            // Windows directory renames already fail when the destination exists.
+            await rename(stage, output);
+            return;
+        }
+        catch (cause) {
+            if (await outputExists(output))
+                throw outputExistsError(output);
+            throw cause;
+        }
+    }
+    try {
+        await mkdir(output);
+    }
+    catch (cause) {
+        if (cause.code === "EEXIST")
+            throw outputExistsError(output);
+        throw cause;
+    }
+    try {
+        await rename(stage, output);
+    }
+    catch (cause) {
+        await rmdir(output).catch(() => undefined);
+        throw cause;
+    }
+}
+async function downloadFiles(input) {
+    let next = 0;
+    let failed = false;
+    let failure;
+    const workers = Array.from({ length: Math.min(DOWNLOAD_CONCURRENCY, input.files.length) }, async () => {
+        while (!failed && next < input.files.length) {
+            const index = next++;
+            const file = input.files[index];
+            if (!file)
+                continue;
+            try {
+                await downloadFile(artifactUrl(input.contentUrl, file.artifactPath), join(input.stage, ...file.outputPath.split("/")), file, input.fetcher);
+            }
+            catch (cause) {
+                if (!failed)
+                    failure = cause;
+                failed = true;
+            }
+        }
+    });
+    await Promise.all(workers);
+    if (failed)
+        throw failure;
+}
+export async function downloadWork(detail, outputOption, fetcher = fetch) {
+    const { work, content } = detail;
+    if (!content)
+        throw new Error("This Work has no published downloadable artifact");
+    if (content.kind === "port")
+        throw new Error("Port Works do not have a downloadable artifact");
+    if (content.kind === "board")
+        throw new Error("Board Works do not have a restorable file or directory artifact");
+    if (!content.download)
+        throw new Error("This Work 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");
+    }
+    const entry = manifest.files.find((file) => file.artifactPath === manifest.entrypoint);
+    if (!entry)
+        throw new Error("Work download manifest entrypoint is missing");
+    const hasDirectoryOutput = manifest.targetType === "directory" || manifest.files.length > 1;
+    const output = resolve(outputOption ?? (hasDirectoryOutput ? work.slug : basename(manifest.targetRef)));
+    await assertOutputMissing(output);
+    await mkdir(dirname(output), { recursive: true });
+    const stage = await mkdtemp(join(dirname(output), `.${basename(output)}.cohub-download-`));
+    try {
+        const files = hasDirectoryOutput ? manifest.files : [entry];
+        await downloadFiles({ files, contentUrl: content.url, stage, fetcher });
+        if (hasDirectoryOutput) {
+            await installDirectoryNoReplace(stage, output);
+        }
+        else {
+            const stagedFile = join(stage, ...entry.outputPath.split("/"));
+            await installFileNoReplace(stagedFile, output);
+            await rm(stage, { recursive: true, force: true });
+        }
+        return {
+            workId: work.id,
+            version: work.latestVersion,
+            kind: hasDirectoryOutput ? "directory" : "file",
+            output,
+            files: files.length,
+            bytes: files.reduce((sum, file) => sum + file.sizeBytes, 0),
+            verified: true,
+        };
+    }
+    catch (cause) {
+        await rm(stage, { recursive: true, force: true }).catch(() => undefined);
+        throw cause;
+    }
+}

package/dist/work-ref.d.ts

@@ -0,0 +1,13 @@
+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;
+export declare function getWorkByRef(client: CohubHttpClient, input: string): Promise<WorkGetResponse>;
+export {};

package/dist/work-ref.js

@@ -0,0 +1,61 @@
+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}`;
+}
+export function getWorkByRef(client, input) {
+    const ref = parseWorkRef(input);
+    return "id" in ref
+        ? client.works.get(ref.id)
+        : client.works.getBySlug(ref.username, ref.spaceSlug, ref.workSlug);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "3.5.1",
+  "version": "3.6.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": "4.9.0"
+    "@neta-art/cohub": "5.1.0"
   },
   "publishConfig": {
     "access": "public"