@neta-art/cohub-cli 1.2.0 → 1.4.0

package/README.md

@@ -1,38 +1,208 @@
 # @neta-art/cohub-cli
 
-CLI for [Cohub](https://cohub.run) — spaces, sessions, and agent collaboration.
+CLI for [Cohub](https://cohub.run) — work with Spaces, Chats, files, Saves, Tasks, scheduled prompts, search, and multimodal generation from your terminal.
 
 ## Installation
 
 ```bash
 npm install -g @neta-art/cohub-cli
+cohub --help
 ```
 
-## Usage
+## Sign in
+
+For normal use outside Cohub Sandbox, sign in once:
 
 ```bash
-cohub --help
+cohub auth login
+cohub auth whoami
 ```
 
-## Environment
+The CLI will keep you signed in and refresh your session automatically.
 
-The CLI connects to production by default:
+Inside Cohub Sandbox or CI, `COHUB_EXECUTION_TOKEN` can be used as an ephemeral auth override.
 
-- API: `https://api.cohub.run`
-- WebSocket: `wss://gateway.cohub.run/ws`
+## Environment
+
+The CLI uses production by default.
 
 Use the development environment with `ENV=dev`:
 
 ```bash
+ENV=dev cohub auth login
 ENV=dev cohub spaces ls
 ```
 
-Development uses:
+## Usage
+
+Use `--json` when reading output for decisions, extracting IDs, or chaining commands.
+
+For command details:
+
+```bash
+cohub -h
+cohub spaces -h
+cohub spaces prompt -h
+```
+
+## Terminology
+
+| Product UI | CLI / API |
+|---|---|
+| Chat | Session |
+| Save | Checkpoint |
+| Tasks | Task runs |
+| Scheduled prompt | `spaces prompt` schedule |
+| Recurring scheduled prompt | Cron job |
+
+## Spaces
+
+```bash
+cohub spaces ls --json
+cohub spaces get <spaceId> --json
+cohub spaces create --name "<name>" --description "<description>" --json
+cohub spaces rename <spaceId> "<new name>"
+```
+
+Many space-scoped commands need a target Space:
+
+```bash
+cohub -s <spaceId> spaces prompt "message" --json
+```
+
+## Chats and prompts
+
+Use `spaces prompt` for immediate sends, delayed sends, one-time schedules, recurring schedules, new Chats, and existing Chats.
+
+```bash
+# Send now
+cohub -s <spaceId> spaces prompt "message" --json
+
+# Send long content from stdin
+cat prompt.md | cohub -s <spaceId> spaces prompt --json
+
+# Send to an existing Chat
+cohub -s <spaceId> spaces prompt --session <sessionId> "message" --json
+
+# Create a new Chat and send
+cohub -s <spaceId> spaces prompt --title "<chat title>" "message" --json
+
+# Schedule once
+cohub -s <spaceId> spaces prompt --at "2026-05-12T09:00:00+08:00" "message" --json
+
+# Schedule recurring
+cohub -s <spaceId> spaces prompt \
+  --cron "0 9 * * 1-5" \
+  --timezone "Asia/Shanghai" \
+  --title "Daily reminder" \
+  "message" \
+  --json
+```
+
+Scheduling rules:
+
+- Use only one of `--delay-ms`, `--at`, or `--cron`.
+- `--cron` requires `--timezone`.
+
+## Chats / Sessions
+
+```bash
+cohub -s <spaceId> spaces sessions ls --json
+cohub -s <spaceId> spaces sessions create "<title>" --json
+cohub -s <spaceId> spaces sessions get <sessionId> --json
+cohub -s <spaceId> spaces sessions rename <sessionId> "<new title>"
+```
+
+Use `spaces prompt --session <sessionId>` to send to a Chat.
+
+## Search
+
+Search Spaces, Chats, and prior turns:
+
+```bash
+cohub search "query"
+cohub search "query" --limit 20 --json
+```
+
+## Models and multimodal generation
+
+```bash
+cohub models ls --json
+cohub models ls --model-type multimodal --json
+
+cohub generate "a calm lake at sunrise" \
+  --model <model> \
+  --output output.png \
+  --json
+
+cohub generate "restyle this image" \
+  --model <model> \
+  --image ./input.png \
+  --param size=1024x1024 \
+  --json
+```
+
+Supported inputs:
+
+```bash
+--image <path-or-url>
+--video <path-or-url>
+--audio <path-or-url>
+```
+
+Pass generation parameters with `--param key=value` or `--parameters '<json>'`.
+
+## Files
+
+```bash
+cohub -s <spaceId> spaces files ls [path] --json
+cohub -s <spaceId> spaces files cat <path>
+cohub -s <spaceId> spaces files write <path> -c "<content>"
+cohub -s <spaceId> spaces files upload <files...> --dir <dir>
+cohub -s <spaceId> spaces files mv <from> <to>
+cohub -s <spaceId> spaces files rm <path>
+```
+
+Confirm before deleting files or directories.
+
+## Saves
+
+```bash
+cohub -s <spaceId> spaces checkpoints ls --json
+cohub -s <spaceId> spaces checkpoints get <checkpointId> --json
+cohub -s <spaceId> spaces checkpoints create "<description>" --json
+```
+
+## Tasks
+
+```bash
+cohub tasks ls --space <spaceId> --json
+cohub tasks get <taskRunId> --json
+```
+
+Create scheduled sends with `spaces prompt` scheduling flags, not task commands.
+
+## Recurring scheduled prompts
+
+Create recurring scheduled prompts with `spaces prompt --cron ... --timezone ...`.
+
+Manage them with `cron-jobs`:
+
+```bash
+cohub cron-jobs ls <spaceId> --json
+cohub cron-jobs runs <cronJobId> --json
+cohub cron-jobs toggle <cronJobId> on
+cohub cron-jobs toggle <cronJobId> off
+cohub cron-jobs delete <cronJobId>
+```
+
+Confirm before enabling, disabling, or deleting recurring scheduled prompts.
 
-- API: `https://api-dev.cohub.run`
-- WebSocket: `wss://gateway-dev.cohub.run/ws`
+## Safety
 
-Auth tokens are stored per environment:
+Confirm before:
 
-- prod: `~/.config/cohub/token`
-- dev: `~/.config/cohub/token.dev`
+- deleting files or directories
+- creating scheduled or recurring prompts with side effects
+- enabling, disabling, or deleting recurring scheduled prompts
+- changing access policies, member roles, or membership

package/dist/auth.d.ts

@@ -1,12 +1,41 @@
-export declare const getTokenPath: () => string;
-/**
- * Resolve auth token with priority:
- *   1. COHUB_EXECUTION_TOKEN environment variable
- *   2. current environment token file
- *      - prod: ~/.config/cohub/token
- *      - dev: ~/.config/cohub/token.dev
- */
-export declare function resolveToken(): string | null;
-export declare function saveToken(token: string): void;
-export declare function clearToken(): void;
-export declare function tokenSource(): "env" | "file" | null;
+import { type CohubEnvironment } from "@neta-art/cohub";
+export type AuthSource = "execution-token" | "logto" | null;
+type DeviceCode = {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    expiresAt: number;
+    interval: number;
+    createdAt: number;
+};
+type AuthSession = {
+    schemaVersion: 1;
+    env: CohubEnvironment;
+    issuer: string;
+    clientId: string;
+    resource: string;
+    scope: string;
+    tokenType: "Bearer";
+    accessToken: string;
+    refreshToken: string;
+    idToken?: string;
+    accessTokenExpiresAt: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export declare class AuthRequiredError extends Error {
+    constructor(message?: string);
+}
+export declare const readAuthSession: () => AuthSession | null;
+export declare const clearDeviceCode: () => void;
+export declare const clearAuthSession: () => void;
+export declare const authSource: () => AuthSource;
+export declare function resolveAccessToken(): Promise<string | null>;
+export declare function requireAccessToken(): Promise<string>;
+export declare function refreshAccessToken(session?: AuthSession | null): Promise<string | null>;
+export declare function requestDeviceCode(): Promise<DeviceCode>;
+export declare function verifyDeviceCode(): Promise<AuthSession>;
+export declare function loginWithDeviceFlow(onCode: (code: DeviceCode) => void, onPoll?: () => void): Promise<AuthSession>;
+export declare function revokeAndClearAuthSession(): Promise<void>;
+export {};

package/dist/auth.js

@@ -1,43 +1,259 @@
 import { resolveCohubEnvironment } from "@neta-art/cohub";
-import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-const TOKEN_DIR = join(homedir(), ".config", "cohub");
-export const getTokenPath = () => join(TOKEN_DIR, resolveCohubEnvironment() === "dev" ? "token.dev" : "token");
-/**
- * Resolve auth token with priority:
- *   1. COHUB_EXECUTION_TOKEN environment variable
- *   2. current environment token file
- *      - prod: ~/.config/cohub/token
- *      - dev: ~/.config/cohub/token.dev
- */
-export function resolveToken() {
-    if (process.env.COHUB_EXECUTION_TOKEN) {
-        return process.env.COHUB_EXECUTION_TOKEN.trim();
-    }
-    const path = getTokenPath();
-    if (existsSync(path)) {
-        return readFileSync(path, "utf-8").trim();
+import { setTimeout as delay } from "node:timers/promises";
+const CONFIG_DIR = join(homedir(), ".config", "cohub");
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+const DEFAULT_SCOPE = "openid profile email offline_access";
+const DEFAULT_RESOURCE = "https://api.talesofai";
+export class AuthRequiredError extends Error {
+    constructor(message = "Not authenticated") {
+        super(message);
+        this.name = "AuthRequiredError";
     }
+}
+const currentEnv = () => resolveCohubEnvironment();
+const normalizeUrl = (url) => url.trim().replace(/\/+$/, "");
+const authConfig = (env = currentEnv()) => {
+    const prefix = env === "dev" ? "COHUB_DEV" : "COHUB";
+    const defaultIssuer = env === "dev" ? "https://dev-auth.neta.art" : "https://auth.neta.art";
+    const defaultClientId = env === "dev" ? "u2fnfgvf8f16dnt8si2bv" : "f8d26cdlwx85b0e5l3om2";
+    return {
+        issuer: normalizeUrl(process.env[`${prefix}_AUTH_ISSUER`] ?? process.env.COHUB_AUTH_ISSUER ?? defaultIssuer),
+        clientId: process.env[`${prefix}_AUTH_CLIENT_ID`] ?? process.env.COHUB_AUTH_CLIENT_ID ?? defaultClientId,
+        resource: process.env[`${prefix}_AUTH_RESOURCE`] ?? process.env.COHUB_AUTH_RESOURCE ?? DEFAULT_RESOURCE,
+        scope: process.env[`${prefix}_AUTH_SCOPE`] ?? process.env.COHUB_AUTH_SCOPE ?? DEFAULT_SCOPE,
+    };
+};
+const sessionPath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "auth.dev.json" : "auth.json");
+const deviceCodePath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "device-code.dev.json" : "device-code.json");
+const legacyTokenPath = (env = currentEnv()) => join(CONFIG_DIR, env === "dev" ? "token.dev" : "token");
+const writePrivateJson = (path, value) => {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+};
+const readJson = (path) => {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+};
+const removeIfExists = (path) => {
+    if (existsSync(path))
+        rmSync(path);
+};
+const tokenEndpoint = (issuer) => `${issuer}/oidc/token`;
+const deviceEndpoint = (issuer) => `${issuer}/oidc/device/auth`;
+const revocationEndpoint = (issuer) => `${issuer}/oidc/token/revocation`;
+const formPost = async (url, body) => {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+    });
+    const contentType = response.headers.get("content-type") ?? "";
+    const data = contentType.includes("application/json")
+        ? await response.json().catch(() => null)
+        : await response.text().catch(() => null);
+    return { response, data };
+};
+const toNonEmptyString = (value, field) => {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`Invalid auth response: missing ${field}`);
+    return value;
+};
+const toPositiveNumber = (value, field) => {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(number) || number <= 0)
+        throw new Error(`Invalid auth response: invalid ${field}`);
+    return number;
+};
+const authErrorCode = (data) => {
+    if (typeof data !== "object" || data === null)
+        return null;
+    const error = data.error;
+    return typeof error === "string" ? error : null;
+};
+const isUnrecoverableRefreshError = (data) => {
+    const code = authErrorCode(data);
+    return code === "invalid_grant" || code === "invalid_token";
+};
+const toSession = (token, config, env, previous) => {
+    const accessToken = toNonEmptyString(token.access_token, "access_token");
+    const expiresIn = toPositiveNumber(token.expires_in, "expires_in");
+    if (token.token_type !== "Bearer")
+        throw new Error(`Unsupported token type: ${token.token_type}`);
+    if (token.refresh_token !== undefined && !token.refresh_token.trim())
+        throw new Error("Invalid auth response: invalid refresh_token");
+    if (!token.refresh_token && !previous?.refreshToken)
+        throw new Error("Logto did not return a refresh token");
+    const now = Date.now();
+    return {
+        schemaVersion: 1,
+        env,
+        issuer: config.issuer,
+        clientId: config.clientId,
+        resource: config.resource,
+        scope: token.scope ?? config.scope,
+        tokenType: "Bearer",
+        accessToken,
+        refreshToken: token.refresh_token ?? previous?.refreshToken ?? "",
+        idToken: token.id_token ?? previous?.idToken,
+        accessTokenExpiresAt: now + expiresIn * 1000,
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+    };
+};
+export const readAuthSession = () => readJson(sessionPath());
+export const clearDeviceCode = () => {
+    removeIfExists(deviceCodePath());
+};
+export const clearAuthSession = () => {
+    removeIfExists(sessionPath());
+    clearDeviceCode();
+    removeIfExists(legacyTokenPath());
+};
+export const authSource = () => {
+    if (process.env.COHUB_EXECUTION_TOKEN?.trim())
+        return "execution-token";
+    if (readAuthSession())
+        return "logto";
     return null;
+};
+export async function resolveAccessToken() {
+    const executionToken = process.env.COHUB_EXECUTION_TOKEN?.trim();
+    if (executionToken)
+        return executionToken;
+    const session = readAuthSession();
+    if (!session)
+        throw new AuthRequiredError();
+    if (session.accessTokenExpiresAt - Date.now() > EXPIRY_SKEW_MS)
+        return session.accessToken;
+    return refreshAccessToken(session);
 }
-export function saveToken(token) {
-    const trimmed = token.trim();
-    if (!trimmed)
-        throw new Error("Token cannot be empty");
-    mkdirSync(TOKEN_DIR, { recursive: true });
-    writeFileSync(getTokenPath(), trimmed);
+export async function requireAccessToken() {
+    const token = await resolveAccessToken();
+    if (!token)
+        throw new AuthRequiredError();
+    return token;
 }
-export function clearToken() {
-    const path = getTokenPath();
-    if (existsSync(path)) {
-        rmSync(path);
+export async function refreshAccessToken(session = readAuthSession()) {
+    if (!session?.refreshToken)
+        throw new AuthRequiredError();
+    const config = authConfig(session.env);
+    const { response, data } = await formPost(tokenEndpoint(session.issuer), new URLSearchParams({
+        client_id: session.clientId,
+        grant_type: "refresh_token",
+        refresh_token: session.refreshToken,
+        scope: session.scope,
+        resource: session.resource,
+    }));
+    if (!response.ok) {
+        if (isUnrecoverableRefreshError(data)) {
+            clearAuthSession();
+            return null;
+        }
+        throw new Error(formatAuthError(data, response.status));
     }
+    const next = toSession(data, config, session.env, session);
+    writePrivateJson(sessionPath(session.env), next);
+    return next.accessToken;
 }
-export function tokenSource() {
-    if (process.env.COHUB_EXECUTION_TOKEN)
-        return "env";
-    if (existsSync(getTokenPath()))
-        return "file";
-    return null;
+export async function requestDeviceCode() {
+    const env = currentEnv();
+    const config = authConfig(env);
+    const { response, data } = await formPost(deviceEndpoint(config.issuer), new URLSearchParams({
+        client_id: config.clientId,
+        scope: config.scope,
+        resource: config.resource,
+    }));
+    if (!response.ok || typeof data !== "object" || data === null) {
+        throw new Error(typeof data === "string" ? data : `Failed to request device code: HTTP ${response.status}`);
+    }
+    const body = data;
+    const now = Date.now();
+    const expiresIn = toPositiveNumber(body.expires_in, "expires_in");
+    const interval = body.interval === undefined ? 5 : toPositiveNumber(body.interval, "interval");
+    const verificationUri = toNonEmptyString(body.verification_uri, "verification_uri");
+    const deviceCode = {
+        deviceCode: toNonEmptyString(body.device_code, "device_code"),
+        userCode: toNonEmptyString(body.user_code, "user_code"),
+        verificationUri,
+        verificationUriComplete: body.verification_uri_complete === undefined
+            ? verificationUri
+            : toNonEmptyString(body.verification_uri_complete, "verification_uri_complete"),
+        expiresAt: now + expiresIn * 1000,
+        interval,
+        createdAt: now,
+    };
+    writePrivateJson(deviceCodePath(env), deviceCode);
+    return deviceCode;
+}
+export async function verifyDeviceCode() {
+    const env = currentEnv();
+    const config = authConfig(env);
+    const deviceCode = readJson(deviceCodePath(env));
+    if (!deviceCode)
+        throw new Error("Device code not found. Run `cohub auth login --request-code` first.");
+    if (deviceCode.expiresAt <= Date.now())
+        throw new Error("Device code expired. Run `cohub auth login` again.");
+    const { response, data } = await formPost(tokenEndpoint(config.issuer), new URLSearchParams({
+        client_id: config.clientId,
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: deviceCode.deviceCode,
+        resource: config.resource,
+    }));
+    if (!response.ok)
+        throw new Error(formatAuthError(data, response.status));
+    const session = toSession(data, config, env);
+    writePrivateJson(sessionPath(env), session);
+    removeIfExists(deviceCodePath(env));
+    return session;
+}
+export async function loginWithDeviceFlow(onCode, onPoll) {
+    const code = await requestDeviceCode();
+    onCode(code);
+    while (Date.now() < code.expiresAt) {
+        await delay(code.interval * 1000);
+        onPoll?.();
+        try {
+            return await verifyDeviceCode();
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            if (message.includes("authorization_pending"))
+                continue;
+            if (message.includes("slow_down")) {
+                await delay(code.interval * 1000);
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw new Error("Login timed out. Run `cohub auth login` again.");
+}
+export async function revokeAndClearAuthSession() {
+    const session = readAuthSession();
+    if (session?.refreshToken) {
+        await formPost(revocationEndpoint(session.issuer), new URLSearchParams({
+            client_id: session.clientId,
+            token: session.refreshToken,
+            token_type_hint: "refresh_token",
+        })).catch(() => null);
+    }
+    clearAuthSession();
+}
+function formatAuthError(data, status) {
+    if (typeof data === "object" && data !== null) {
+        const record = data;
+        const code = String(record.error ?? "");
+        const description = String(record.error_description ?? "");
+        return [code, description].filter(Boolean).join(": ") || `Authentication failed: HTTP ${status}`;
+    }
+    return typeof data === "string" && data ? data : `Authentication failed: HTTP ${status}`;
 }

package/dist/client.d.ts

@@ -1,2 +1,2 @@
 import { CohubHttpClient } from "@neta-art/cohub";
-export declare function createClient(token: string): CohubHttpClient;
+export declare function createClient(): CohubHttpClient;

package/dist/client.js

@@ -1,6 +1,8 @@
 import { CohubHttpClient } from "@neta-art/cohub";
-export function createClient(token) {
+import { clearDeviceCode, resolveAccessToken } from "./auth.js";
+export function createClient() {
     return new CohubHttpClient({
-        getAccessToken: () => token,
+        getAccessToken: resolveAccessToken,
+        onUnauthorized: clearDeviceCode,
     });
 }