@neta-art/cohub-cli 6.7.0 → 6.8.1

package/dist/help-path.js

@@ -0,0 +1,223 @@
+function isHelpFlag(token) {
+    return token === "-h" || token === "--help";
+}
+function findChild(command, name) {
+    return command.commands.find((child) => {
+        if (child.name() === "help")
+            return false;
+        return child.name() === name || child.aliases().includes(name);
+    });
+}
+function hasSubcommands(command) {
+    return command.commands.some((child) => child.name() !== "help");
+}
+function knownOptions(command) {
+    const options = [];
+    let current = command;
+    while (current) {
+        options.push(...current.options);
+        current = current.parent;
+    }
+    return options;
+}
+function matchOption(command, token) {
+    if (!token.startsWith("-") || token === "-")
+        return undefined;
+    const eq = token.indexOf("=");
+    const inline = eq >= 0;
+    const flag = inline ? token.slice(0, eq) : token;
+    for (const option of knownOptions(command)) {
+        if (option.short === flag || option.long === flag)
+            return { option, inline };
+    }
+    return undefined;
+}
+function skipOption(command, argv, index) {
+    const token = argv[index] ?? "";
+    const matched = matchOption(command, token);
+    const next = index + 1;
+    if (matched?.inline)
+        return next;
+    const value = argv[next];
+    if (!value)
+        return next;
+    if (matched?.option.required)
+        return next + 1;
+    if (matched?.option.optional && !value.startsWith("-"))
+        return next + 1;
+    return next;
+}
+function remainderRequestsHelp(command, argv) {
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index] ?? "";
+        if (token === "--")
+            break;
+        if (isHelpFlag(token))
+            return true;
+        if (token.startsWith("-")) {
+            index = skipOption(command, argv, index);
+            continue;
+        }
+        index += 1;
+    }
+    return false;
+}
+/** Match `run.ts`: Cohub flags first, then the rest is the shell command. */
+function runRemainderRequestsHelp(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (token === "--")
+            return false;
+        if (isHelpFlag(token))
+            return true;
+        if (token === "--async" || token === "--json")
+            continue;
+        if (token === "-c" || token === "--command") {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--command="))
+            continue;
+        return false;
+    }
+    return false;
+}
+function walkCommandPath(program, argv) {
+    let command = program;
+    const path = [];
+    let helpRequested = false;
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index] ?? "";
+        if (token === "--")
+            break;
+        if (isHelpFlag(token)) {
+            helpRequested = true;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            index = skipOption(command, argv, index);
+            continue;
+        }
+        if (token === "help" && hasSubcommands(command)) {
+            helpRequested = true;
+            index += 1;
+            continue;
+        }
+        const child = findChild(command, token);
+        if (child) {
+            command = child;
+            path.push(child.name());
+            index += 1;
+            continue;
+        }
+        if (hasSubcommands(command)) {
+            const remainder = argv.slice(index + 1);
+            const helpAfter = token === "run" && path.length === 0
+                ? runRemainderRequestsHelp(remainder)
+                : remainderRequestsHelp(command, remainder);
+            return {
+                command,
+                path,
+                helpRequested: helpRequested || helpAfter,
+                unknown: token,
+            };
+        }
+        index += 1;
+    }
+    return { command, path, helpRequested, unknown: null };
+}
+function stripRootCommand(program, argv, name) {
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index] ?? "";
+        if (token === "--")
+            return undefined;
+        if (isHelpFlag(token) || token === "help") {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            index = skipOption(program, argv, index);
+            continue;
+        }
+        if (token !== name)
+            return undefined;
+        return [...argv.slice(0, index), ...argv.slice(index + 1)];
+    }
+    return undefined;
+}
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (Math.abs(a.length - b.length) > 3)
+        return Math.max(a.length, b.length);
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    const previous = Array.from({ length: cols }, (_, index) => index);
+    const current = new Array(cols);
+    for (let i = 1; i < rows; i += 1) {
+        current[0] = i;
+        for (let j = 1; j < cols; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+        }
+        for (let j = 0; j < cols; j += 1)
+            previous[j] = current[j] ?? 0;
+    }
+    return previous[b.length] ?? Math.max(a.length, b.length);
+}
+function suggestCommand(command, token) {
+    const names = [...new Set(command.commands.flatMap((child) => {
+            if (child.name() === "help" || child.name().length <= 1)
+                return [];
+            return [child.name(), ...child.aliases().filter((alias) => alias.length > 1)];
+        }))];
+    let best;
+    let bestDistance = 3;
+    for (const name of names) {
+        const distance = editDistance(token, name);
+        const length = Math.max(token.length, name.length);
+        if (distance >= bestDistance || (length - distance) / length <= 0.4)
+            continue;
+        bestDistance = distance;
+        best = name;
+    }
+    return best;
+}
+export function resolveHelpPath(program, argv) {
+    const walk = walkCommandPath(program, argv);
+    const cliAtRoot = walk.unknown === "cli" && walk.path.length === 0;
+    if (cliAtRoot) {
+        const stripped = stripRootCommand(program, argv, "cli");
+        return {
+            kind: "unknown",
+            token: "cli",
+            tryCommand: stripped && stripped.length > 0 ? stripped.join(" ") : undefined,
+        };
+    }
+    if (!walk.helpRequested)
+        return { kind: "passthrough" };
+    if (walk.unknown === "run" && walk.path.length === 0)
+        return { kind: "run-help" };
+    if (walk.unknown) {
+        return {
+            kind: "unknown",
+            token: walk.unknown,
+            suggestion: suggestCommand(walk.command, walk.unknown),
+        };
+    }
+    return { kind: "help", command: walk.command };
+}
+export function formatUnknownCommandError(result) {
+    const lines = [`error: unknown command '${result.token}'`];
+    if (result.tryCommand)
+        lines.push(`Try: cohub ${result.tryCommand}`);
+    else if (result.token === "cli")
+        lines.push(`cohub has no "cli" subcommand. See cohub --help`);
+    else if (result.suggestion)
+        lines.push(`(Did you mean ${result.suggestion}?)`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/http-put.d.ts

@@ -0,0 +1,25 @@
+export declare class HttpPutError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body?: string);
+}
+export type PutRetryOptions = {
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    fetch?: typeof fetch;
+};
+export declare function putLocalFile(input: PutRetryOptions & {
+    url: string;
+    filePath: string;
+    size: number;
+    headers?: HeadersInit;
+    label: string;
+}): Promise<void>;
+export declare function putBytes(input: PutRetryOptions & {
+    url: string;
+    body: Blob;
+    size?: number;
+    headers?: HeadersInit;
+    label: string;
+}): Promise<void>;

package/dist/http-put.js

@@ -0,0 +1,132 @@
+import { createReadStream } from "node:fs";
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_DELAY_MS = 200;
+const RETRYABLE_STATUS = new Set([408, 411, 425, 429, 500, 502, 503, 504]);
+const RETRYABLE_CODES = new Set([
+    "BodyTimeoutError",
+    "ConnectTimeoutError",
+    "EAI_AGAIN",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENOTFOUND",
+    "EPIPE",
+    "ETIMEDOUT",
+    "HeadersTimeoutError",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_CONNECT",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+export class HttpPutError extends Error {
+    status;
+    body;
+    constructor(message, status, body = "") {
+        super(message);
+        this.name = "HttpPutError";
+        this.status = status;
+        this.body = body;
+    }
+}
+function withContentLength(headers, contentLength) {
+    const result = new Headers(headers);
+    if (contentLength !== undefined && !result.has("content-length")) {
+        result.set("content-length", String(contentLength));
+    }
+    return result;
+}
+function errorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const record = error;
+    if (typeof record.code === "string")
+        return record.code;
+    if (typeof record.cause?.code === "string")
+        return record.cause.code;
+    if (typeof record.cause?.name === "string")
+        return record.cause.name;
+    if (typeof record.name === "string")
+        return record.name;
+    return undefined;
+}
+function isRetryableError(error) {
+    const code = errorCode(error);
+    return Boolean(code && RETRYABLE_CODES.has(code));
+}
+function isRetryableStatus(status) {
+    return RETRYABLE_STATUS.has(status);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function failureMessage(label, status, detail) {
+    return `Failed to upload ${label}: HTTP ${status}${detail ? ` — ${detail}` : ""}`;
+}
+async function putWithRetry(input) {
+    const attempts = input.attempts ?? DEFAULT_ATTEMPTS;
+    const delayMs = input.delayMs ?? DEFAULT_DELAY_MS;
+    const sleep = input.sleep ?? defaultSleep;
+    const fetchImpl = input.fetch ?? fetch;
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            const response = await fetchImpl(input.url, {
+                method: "PUT",
+                headers: withContentLength(input.headers, input.contentLength),
+                body: input.body(),
+                ...(input.duplex ? { duplex: "half" } : {}),
+            });
+            if (response.ok)
+                return response;
+            const detail = await response.text().catch(() => "");
+            const error = new HttpPutError(failureMessage(input.label, response.status, detail), response.status, detail);
+            if (attempt < attempts - 1 && isRetryableStatus(response.status)) {
+                lastError = error;
+                await sleep(delayMs * 2 ** attempt);
+                continue;
+            }
+            throw error;
+        }
+        catch (error) {
+            if (error instanceof HttpPutError)
+                throw error;
+            lastError = error;
+            if (attempt < attempts - 1 && isRetryableError(error)) {
+                await sleep(delayMs * 2 ** attempt);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw lastError;
+}
+export async function putLocalFile(input) {
+    await putWithRetry({
+        url: input.url,
+        body: () => createReadStream(input.filePath),
+        headers: input.headers,
+        contentLength: input.size,
+        duplex: true,
+        label: input.label,
+        attempts: input.attempts,
+        delayMs: input.delayMs,
+        sleep: input.sleep,
+        fetch: input.fetch,
+    });
+}
+export async function putBytes(input) {
+    const body = input.body;
+    await putWithRetry({
+        url: input.url,
+        body: () => body,
+        headers: input.headers,
+        contentLength: input.size,
+        label: input.label,
+        attempts: input.attempts,
+        delayMs: input.delayMs,
+        sleep: input.sleep,
+        fetch: input.fetch,
+    });
+}

package/dist/index.js

@@ -16,11 +16,12 @@ import { registerSearch } from "./commands/search.js";
 import { registerReferences } from "./commands/references.js";
 import { registerReferrals } from "./commands/referrals.js";
 import { registerPrompt, registerSpaces } from "./commands/spaces.js";
-import { maybeHandleRunCommand } from "./commands/run.js";
+import { maybeHandleRunCommand, printRunHelp } from "./commands/run.js";
 import { registerSandbox } from "./commands/sandbox.js";
 import { registerTasks } from "./commands/tasks.js";
 import { registerDesktop, registerLegacyUi } from "./commands/desktop.js";
 import { registerApps } from "./commands/apps.js";
+import { formatUnknownCommandError, resolveHelpPath } from "./help-path.js";
 const VERSION = (() => {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
@@ -36,18 +37,22 @@ program
     .summary("Work with Cohub from your terminal")
     .description("Send prompts, manage Space files, and publish public output.")
     .version(VERSION, "-v, --version", "Show version")
-    .option("-s, --space <id>", "Target Space ID")
+    .option("-s, --space <id>", "Target Space ID (defaults to your Home space)")
     .option("--json", "Print machine-readable JSON when supported")
     .helpOption("-h, --help", "Show help")
     .addHelpText("after", `
 
+Help:
+  cohub apps publish --help
+  cohub help apps publish
+
 Common commands:
   cohub auth login
   cohub profile avatar ./avatar.png
   cohub spaces ls
-  cohub -s <space-id> prompt "Fix the failing tests"
-  cohub -s <space-id> completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
-  cohub -s <space-id> run -- git status
+  cohub prompt "Fix the failing tests"
+  cohub completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
+  cohub run -- git status
   cohub sandbox up ./my-project
   cohub search "release notes"
   cohub -s <space-id> boards inspect <board-id>
@@ -62,9 +67,14 @@ Common commands:
   cohub models ls --model-type multimodal
   cohub generate "A calm lake at sunrise" --model <model> --output lake.png
 
+Target space:
+  -s <space-id>, then COHUB_SPACE_ID, then your Home space
+
 Environment:
+  COHUB_SPACE_ID         Target Space ID when -s is omitted
   COHUB_EXECUTION_TOKEN  Use this token instead of the stored Logto session
   ENV=dev                Use the development Cohub environment
+  HTTPS_PROXY            Honored for API and uploads (also HTTP_PROXY, NO_PROXY)
 `);
 registerAuth(program);
 registerBoards(program);
@@ -88,7 +98,20 @@ registerApps(program);
 registerDesktop(program);
 registerLegacyUi(program);
 const argv = process.argv.slice(2);
-if (await maybeHandleRunCommand(argv)) {
+const help = resolveHelpPath(program, argv);
+if (help.kind === "help") {
+    help.command.outputHelp();
+}
+else if (help.kind === "run-help") {
+    printRunHelp();
+}
+else if (help.kind === "unknown") {
+    process.stderr.write(formatUnknownCommandError(help));
+    process.exit(1);
+}
+else if (await maybeHandleRunCommand(argv)) {
     process.exit();
 }
-program.parse();
+else {
+    program.parse();
+}

package/dist/launcher.d.ts

@@ -1,2 +1,4 @@
 export declare function exitCodeForChild(code: number | null, signal: NodeJS.Signals | null): number;
-export declare function relaunchCli(entrypoint: string, argv: string[]): Promise<number>;
+export declare function relaunchCli(entrypoint: string, argv: string[], options?: {
+    execArgv?: readonly string[];
+}): Promise<number>;

package/dist/launcher.js

@@ -8,9 +8,9 @@ export function exitCodeForChild(code, signal) {
         return 1;
     return 128 + (constants.signals[signal] ?? 1);
 }
-export function relaunchCli(entrypoint, argv) {
+export function relaunchCli(entrypoint, argv, options) {
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [entrypoint, ...argv], {
+        const child = spawn(process.execPath, [...(options?.execArgv ?? []), entrypoint, ...argv], {
             env: process.env,
             stdio: "inherit",
         });

package/dist/space.d.ts

@@ -1,2 +1,32 @@
 import type { Command } from "commander";
-export declare function resolveSpace(program: Command): string;
+/**
+ * Cache key aligned with auth: execution token is exclusive (same as
+ * `resolveAccessToken`) and never falls back to a local Logto session.
+ * Execution grants identify the actor as `actorUserId`, not `sub`.
+ */
+export declare function identityKeyFrom(input: {
+    env: string;
+    executionToken?: string | null;
+    idToken?: string | null;
+    accessToken?: string | null;
+}): string | null;
+/** Exported for tests; production always uses `CACHE_PATH`. */
+export declare function readDefaultSpaceCache(path: string, key: string, now?: number): string | null;
+export declare function clearDefaultSpaceCache(): void;
+/** Explicit target from `-s/--space` (any ancestor) or `COHUB_SPACE_ID`, else null. */
+export declare function explicitSpace(program: Command): string | null;
+/**
+ * Resolve the user's home space when no target is given. Cached locally per
+ * identity so repeated invocations skip the network entirely, and memoized
+ * in-process so preAction hooks and actions share a single lookup.
+ * Network and auth failures propagate so callers can report them faithfully.
+ */
+export declare function resolveDefaultSpace(): Promise<string | null>;
+/** Shared exit for commands that need a space but resolved none. */
+export declare function missingSpaceError(): never;
+/**
+ * Target space for a command: explicit `-s`/`COHUB_SPACE_ID` first, then the
+ * user's home space. Exits with guidance when neither is available; request
+ * failures go through the shared HTTP error handler.
+ */
+export declare function resolveSpace(program: Command): Promise<string>;

package/dist/space.js

@@ -1,5 +1,85 @@
-import { error } from "./output.js";
-export function resolveSpace(program) {
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { resolveCohubEnvironment } from "@neta-art/cohub";
+import { readAuthSession } from "./auth.js";
+import { createClient } from "./client.js";
+import { error, handleHttp } from "./output.js";
+const CONFIG_DIR = join(homedir(), ".config", "cohub");
+const CACHE_PATH = join(CONFIG_DIR, "default-space.json");
+/** Home space is stable; a one-day TTL bounds how long a stale hit survives. */
+const CACHE_TTL_MS = 86_400_000;
+function jwtClaim(token, key) {
+    const payload = token?.split(".")[1];
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+        const value = parsed[key];
+        return typeof value === "string" && value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cache key aligned with auth: execution token is exclusive (same as
+ * `resolveAccessToken`) and never falls back to a local Logto session.
+ * Execution grants identify the actor as `actorUserId`, not `sub`.
+ */
+export function identityKeyFrom(input) {
+    if (input.executionToken) {
+        const actor = jwtClaim(input.executionToken, "actorUserId") ?? jwtClaim(input.executionToken, "sub");
+        return actor ? `${input.env}:${actor}` : null;
+    }
+    const sub = jwtClaim(input.idToken, "sub") ?? jwtClaim(input.accessToken, "sub");
+    return sub ? `${input.env}:${sub}` : null;
+}
+function identityKey() {
+    const session = readAuthSession();
+    return identityKeyFrom({
+        env: resolveCohubEnvironment(),
+        executionToken: process.env.COHUB_EXECUTION_TOKEN?.trim(),
+        idToken: session?.idToken,
+        accessToken: session?.accessToken,
+    });
+}
+/** Exported for tests; production always uses `CACHE_PATH`. */
+export function readDefaultSpaceCache(path, key, now = Date.now()) {
+    try {
+        const cache = JSON.parse(readFileSync(path, "utf-8"));
+        if (cache.key !== key || typeof cache.spaceId !== "string" || typeof cache.cachedAt !== "number")
+            return null;
+        if (now - cache.cachedAt > CACHE_TTL_MS)
+            return null;
+        return cache.spaceId;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedDefaultSpace(key, spaceId) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        const cache = { key, spaceId, cachedAt: Date.now() };
+        writeFileSync(CACHE_PATH, `${JSON.stringify(cache, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+    }
+    catch {
+        // Cache is best-effort; never fail the command over it.
+    }
+}
+let defaultSpacePromise = null;
+export function clearDefaultSpaceCache() {
+    defaultSpacePromise = null;
+    try {
+        rmSync(CACHE_PATH, { force: true });
+    }
+    catch {
+        // Best-effort, same as writes.
+    }
+}
+/** Explicit target from `-s/--space` (any ancestor) or `COHUB_SPACE_ID`, else null. */
+export function explicitSpace(program) {
     let current = program;
     while (current) {
         const opts = current.opts();
@@ -7,8 +87,39 @@ export function resolveSpace(program) {
             return opts.space.trim();
         current = current.parent ?? null;
     }
-    const envSpace = process.env.COHUB_SPACE_ID?.trim();
-    if (envSpace)
-        return envSpace;
-    return error("Missing required space", "Add -s, --space <id> or set COHUB_SPACE_ID.");
+    return process.env.COHUB_SPACE_ID?.trim() || null;
+}
+/**
+ * Resolve the user's home space when no target is given. Cached locally per
+ * identity so repeated invocations skip the network entirely, and memoized
+ * in-process so preAction hooks and actions share a single lookup.
+ * Network and auth failures propagate so callers can report them faithfully.
+ */
+export function resolveDefaultSpace() {
+    defaultSpacePromise ??= (async () => {
+        const key = identityKey();
+        if (key) {
+            const cached = readDefaultSpaceCache(CACHE_PATH, key);
+            if (cached)
+                return cached;
+        }
+        const space = (await createClient().spaces.getDefault()).space ?? null;
+        // Recent-space fallback from getDefault() is not stable enough to cache.
+        if (space?.id && space.slug === "home" && key)
+            writeCachedDefaultSpace(key, space.id);
+        return space?.id ?? null;
+    })();
+    return defaultSpacePromise;
+}
+/** Shared exit for commands that need a space but resolved none. */
+export function missingSpaceError() {
+    return error("No target space", "Add -s, --space <id> or set COHUB_SPACE_ID. Run `cohub auth login` to use your home space.");
+}
+/**
+ * Target space for a command: explicit `-s`/`COHUB_SPACE_ID` first, then the
+ * user's home space. Exits with guidance when neither is available; request
+ * failures go through the shared HTTP error handler.
+ */
+export async function resolveSpace(program) {
+    return explicitSpace(program) ?? (await resolveDefaultSpace().catch(handleHttp)) ?? missingSpaceError();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-cli",
-  "version": "6.7.0",
+  "version": "6.8.1",
   "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.20.1",
     "sharp": "^0.35.4",
-    "@neta-art/cohub": "8.10.0"
+    "@neta-art/cohub": "8.10.2"
   },
   "publishConfig": {
     "access": "public"