@beryl-so/cli 0.1.0

package/dist/context.js

@@ -0,0 +1,101 @@
+import readline from "node:readline/promises";
+import { CliError, UsageError } from "./errors.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function matchByName(candidates, value, kind) {
+    const lower = value.toLowerCase();
+    const matches = candidates.filter((c) => c.name?.toLowerCase() === lower ||
+        c.root_url?.toLowerCase().replace(/^https?:\/\//, "").replace(/\/$/, "") ===
+            lower.replace(/^https?:\/\//, "").replace(/\/$/, ""));
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1) {
+        throw new CliError(`Multiple ${kind}s match "${value}" — use the id instead:\n` +
+            matches.map((m) => `  ${m.id}  ${m.name ?? m.root_url ?? ""}`).join("\n"));
+    }
+    throw new CliError(`No ${kind} named "${value}" found`);
+}
+export function createContext(options) {
+    const { client, config, json } = options;
+    let workspaceCache;
+    let projectCache;
+    const ctx = {
+        client,
+        config,
+        json,
+        interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        out: options.out ?? ((text) => process.stdout.write(text + "\n")),
+        err: options.err ?? ((text) => process.stderr.write(text + "\n")),
+        async prompt(question) {
+            if (!ctx.interactive) {
+                throw new CliError(`Interactive input required (${question}) but stdin is not a TTY`);
+            }
+            const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                return (await rl.question(question)).trim();
+            }
+            finally {
+                rl.close();
+            }
+        },
+        async confirm(question, force) {
+            if (force)
+                return;
+            if (!ctx.interactive) {
+                throw new CliError(`Refusing without confirmation: ${question} (pass --force to proceed)`);
+            }
+            const answer = await ctx.prompt(`${question} [y/N] `);
+            if (!/^y(es)?$/i.test(answer))
+                throw new CliError("Aborted", 1);
+        },
+        async requireWorkspace(input) {
+            const requested = input.flags.workspace ?? config.workspace;
+            if (requested && UUID_RE.test(requested))
+                return requested;
+            if (workspaceCache && !requested)
+                return workspaceCache;
+            const workspaces = (await client.get("/workspaces/"));
+            if (requested) {
+                workspaceCache = matchByName(workspaces, requested, "workspace");
+            }
+            else if (workspaces.length === 1) {
+                workspaceCache = workspaces[0].id;
+            }
+            else if (workspaces.length === 0) {
+                throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
+            }
+            else {
+                throw new UsageError("Multiple workspaces — pass --workspace <id|name>, set BERYL_WORKSPACE, " +
+                    "or run `beryl workspaces use <id|name>`:\n" +
+                    workspaces.map((w) => `  ${w.id}  ${w.name ?? ""}`).join("\n"));
+            }
+            return workspaceCache;
+        },
+        async requireProject(input) {
+            const requested = input.flags.project ?? config.project;
+            const workspaceId = await ctx.requireWorkspace(input);
+            if (requested && UUID_RE.test(requested))
+                return { workspaceId, projectId: requested };
+            if (projectCache && !requested)
+                return projectCache;
+            const projects = (await client.get(`/workspaces/${workspaceId}/projects`));
+            let projectId;
+            if (requested) {
+                projectId = matchByName(projects, requested, "project");
+            }
+            else if (projects.length === 1) {
+                projectId = projects[0].id;
+            }
+            else if (projects.length === 0) {
+                throw new CliError("No projects in this workspace — create one with `beryl projects create`");
+            }
+            else {
+                throw new UsageError("Multiple projects — pass --project <id|name|url>, set BERYL_PROJECT, " +
+                    "or run `beryl projects use <id|name>`:\n" +
+                    projects.map((p) => `  ${p.id}  ${p.name ?? p.root_url ?? ""}`).join("\n"));
+            }
+            projectCache = { workspaceId, projectId };
+            return projectCache;
+        },
+    };
+    return ctx;
+}

package/dist/errors.js

@@ -0,0 +1,21 @@
+export const EXIT_OK = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_AUTH = 3;
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT_FAILURE) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT_USAGE);
+    }
+}
+export class AuthError extends CliError {
+    constructor(message) {
+        super(message, EXIT_AUTH);
+    }
+}

package/dist/http.js

@@ -0,0 +1,98 @@
+import { AuthError, CliError } from "./errors.js";
+export const API_PREFIX = "/api/v1";
+export class ApiError extends CliError {
+    status;
+    detail;
+    constructor(status, detail) {
+        const text = typeof detail === "string" ? detail : (JSON.stringify(detail) ?? `HTTP ${status}`);
+        super(`API error ${status}: ${text}`);
+        this.status = status;
+        this.detail = detail;
+    }
+}
+export class ApiClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.token = token;
+    }
+    url(path, query) {
+        const u = new URL(this.baseUrl + API_PREFIX + path);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined && v !== null)
+                u.searchParams.set(k, String(v));
+        }
+        return u.toString();
+    }
+    authHeaders() {
+        return this.token ? { Authorization: `Bearer ${this.token}` } : {};
+    }
+    async request(method, path, opts = {}) {
+        const headers = { ...this.authHeaders(), ...opts.headers };
+        let body;
+        if (opts.form) {
+            body = opts.form;
+        }
+        else if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        let response;
+        try {
+            response = await fetch(this.url(path, opts.query), {
+                method,
+                headers,
+                body,
+                signal: opts.signal,
+            });
+        }
+        catch (err) {
+            throw new CliError(`Could not reach ${this.baseUrl}: ${err.message}`);
+        }
+        if (response.status === 401) {
+            throw new AuthError(this.token
+                ? "Authentication failed — the token is invalid, expired, or revoked. Run `beryl login`."
+                : "Not logged in. Run `beryl login` or set BERYL_API_KEY.");
+        }
+        if (!response.ok) {
+            let detail;
+            const text = await response.text();
+            try {
+                detail = JSON.parse(text).detail ?? text;
+            }
+            catch {
+                detail = text;
+            }
+            throw new ApiError(response.status, detail);
+        }
+        if (opts.raw)
+            return response;
+        if (response.status === 204)
+            return null;
+        const text = await response.text();
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    post(path, body, query) {
+        return this.request("POST", path, { body, query });
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, { body });
+    }
+    put(path, body) {
+        return this.request("PUT", path, { body });
+    }
+    del(path, body) {
+        return this.request("DELETE", path, { body });
+    }
+}

package/dist/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "./adapters/cli.js";
+runCli(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write((err instanceof Error ? (err.stack ?? err.message) : String(err)) + "\n");
+    process.exitCode = 1;
+});

package/dist/output.js

@@ -0,0 +1,80 @@
+const colorEnabled = () => Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const wrap = (open, close) => (text) => colorEnabled() ? `[${open}m${text}[${close}m` : text;
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const cyan = wrap(36, 39);
+export function statusColor(status) {
+    const s = status.trim().toLowerCase();
+    if (["passed", "completed", "active", "ok", "fresh", "enabled"].includes(s))
+        return green(status);
+    if (["failed", "errored", "error", "expired", "canceled"].includes(s))
+        return red(status);
+    if (["running", "queued", "pending", "exploring", "stale"].includes(s))
+        return yellow(status);
+    return status;
+}
+const MAX_CELL = 60;
+function cell(value) {
+    if (value === null || value === undefined)
+        return "";
+    let text;
+    if (typeof value === "object")
+        text = JSON.stringify(value);
+    else
+        text = String(value);
+    text = text.replace(/\s+/g, " ");
+    return text.length > MAX_CELL ? text.slice(0, MAX_CELL - 1) + "…" : text;
+}
+export function table(rows, columns) {
+    if (rows.length === 0)
+        return dim("(none)");
+    const cols = columns ?? Object.keys(rows[0] ?? {});
+    const widths = cols.map((c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length)));
+    const header = cols
+        .map((c, i) => bold(c.toUpperCase().padEnd(widths[i] ?? 0)))
+        .join("  ")
+        .trimEnd();
+    const body = rows.map((r) => cols
+        .map((c, i) => {
+        const padded = cell(r[c]).padEnd(widths[i] ?? 0);
+        return c.includes("status") && padded.trim() ? statusColor(padded) : padded;
+    })
+        .join("  ")
+        .trimEnd());
+    return [header, ...body].join("\n");
+}
+export function keyValues(obj) {
+    const keys = Object.keys(obj);
+    const width = Math.max(0, ...keys.map((k) => k.length));
+    return keys
+        .map((k) => {
+        const v = obj[k];
+        const text = v === null || v === undefined
+            ? dim("—")
+            : typeof v === "object"
+                ? JSON.stringify(v, null, 2).replace(/\n/g, "\n" + " ".repeat(width + 2))
+                : k.includes("status")
+                    ? statusColor(String(v))
+                    : String(v);
+        return `${dim(k.padEnd(width))}  ${text}`;
+    })
+        .join("\n");
+}
+export function autoFormat(data) {
+    if (data === null || data === undefined)
+        return dim("(no output)");
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return dim("(none)");
+        if (typeof data[0] === "object" && data[0] !== null) {
+            return table(data);
+        }
+        return data.map(String).join("\n");
+    }
+    if (typeof data === "object")
+        return keyValues(data);
+    return String(data);
+}

package/dist/registry/index.js

@@ -0,0 +1,74 @@
+import { accountCommands } from "../commands/account.js";
+import { authCommands } from "../commands/auth.js";
+import { configCommands } from "../commands/config-vars.js";
+import { credentialCommands } from "../commands/credentials.js";
+import { environmentCommands } from "../commands/environments.js";
+import { explorationCommands } from "../commands/explorations.js";
+import { initCommands } from "../commands/init.js";
+import { mcpCommands } from "../commands/mcp.js";
+import { projectCommands } from "../commands/projects.js";
+import { runCommands } from "../commands/runs.js";
+import { testCommands } from "../commands/tests.js";
+import { workspaceCommands } from "../commands/workspaces.js";
+export const WORKSPACE_FLAG = {
+    name: "workspace",
+    type: "string",
+    description: "Workspace id or name (defaults to BERYL_WORKSPACE, .beryl.json, `beryl workspaces use`, " +
+        "or your only workspace)",
+};
+export const PROJECT_FLAG = {
+    name: "project",
+    type: "string",
+    description: "Project id, name, or URL (defaults to BERYL_PROJECT, .beryl.json, `beryl projects use`, " +
+        "or the workspace's only project)",
+};
+function withScopeFlags(spec) {
+    if (!spec.scope || spec.scope === "none")
+        return spec;
+    const extra = [];
+    const has = (name) => spec.flags?.some((f) => f.name === name);
+    if (!has("workspace"))
+        extra.push(WORKSPACE_FLAG);
+    if (spec.scope === "project" && !has("project"))
+        extra.push(PROJECT_FLAG);
+    return { ...spec, flags: [...(spec.flags ?? []), ...extra] };
+}
+export const commands = [
+    ...initCommands,
+    ...authCommands,
+    ...workspaceCommands,
+    ...projectCommands,
+    ...environmentCommands,
+    ...testCommands,
+    ...runCommands,
+    ...explorationCommands,
+    ...configCommands,
+    ...credentialCommands,
+    ...accountCommands,
+    ...mcpCommands,
+].map(withScopeFlags);
+export function findCommand(words) {
+    let best;
+    for (const spec of commands) {
+        const parts = spec.name.split(" ");
+        if (parts.length > words.length)
+            continue;
+        if (parts.every((p, i) => p === words[i])) {
+            if (!best || parts.length > best.consumed)
+                best = { spec, consumed: parts.length };
+        }
+    }
+    return best;
+}
+export function commandGroups() {
+    const groups = new Map();
+    for (const spec of commands) {
+        if (spec.hidden)
+            continue;
+        const group = spec.name.split(" ")[0];
+        const list = groups.get(group) ?? [];
+        list.push(spec);
+        groups.set(group, list);
+    }
+    return groups;
+}

package/dist/registry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sse.js

@@ -0,0 +1,98 @@
+import { CliError } from "./errors.js";
+export function parseSseChunk(buffer) {
+    const events = [];
+    let rest = buffer;
+    for (;;) {
+        const sep = rest.search(/\n\n|\r\n\r\n/);
+        if (sep === -1)
+            return { events, rest };
+        const block = rest.slice(0, sep);
+        rest = rest.slice(sep + (rest.startsWith("\r\n\r\n", sep) ? 4 : 2));
+        const data = block
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trimStart())
+            .join("\n");
+        if (data)
+            events.push(data);
+    }
+}
+const MAX_CONSECUTIVE_FAILURES = 5;
+/**
+ * Yields parsed JSON events from an SSE endpoint. Reconnects on transient
+ * network drops (the backend replays state on connect); the consumer decides
+ * when the stream is terminal and breaks out.
+ */
+export async function* sseStream(client, path, signal) {
+    let failures = 0;
+    for (;;) {
+        let response;
+        try {
+            response = (await client.request("GET", path, {
+                raw: true,
+                headers: { Accept: "text/event-stream" },
+                signal,
+            }));
+        }
+        catch (err) {
+            if (signal?.aborted)
+                return;
+            failures += 1;
+            if (failures >= MAX_CONSECUTIVE_FAILURES)
+                throw err;
+            await sleep(Math.min(1000 * 2 ** failures, 15_000), signal);
+            continue;
+        }
+        if (!response.body)
+            throw new CliError("Stream response had no body");
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const { events, rest } = parseSseChunk(buffer);
+                buffer = rest;
+                for (const data of events) {
+                    failures = 0;
+                    try {
+                        yield JSON.parse(data);
+                    }
+                    catch {
+                        // non-JSON frame (comment/heartbeat) — skip
+                    }
+                }
+            }
+            // Clean server-side close without a terminal event: reconnect and replay.
+            failures += 1;
+            if (failures >= MAX_CONSECUTIVE_FAILURES)
+                return;
+            await sleep(1000, signal);
+        }
+        catch (err) {
+            if (signal?.aborted)
+                return;
+            failures += 1;
+            if (failures >= MAX_CONSECUTIVE_FAILURES)
+                throw err;
+            await sleep(Math.min(1000 * 2 ** failures, 15_000), signal);
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+        if (signal?.aborted)
+            return;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@beryl-so/cli",
+  "version": "0.1.0",
+  "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://beryl.so/docs/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vibe-Monitor/beryl.git",
+    "directory": "cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "beryl": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "tsx src/index.ts",
+    "docs": "tsx scripts/gen-docs.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}