@starlove/orbit 1.4.0 → 2.0.0

package/lib/cli/main.js

@@ -0,0 +1,343 @@
+/**
+ * Orbit CLI, loaded by the bin (./orbit.ts): `orbit run` serves the app and the API, `orbit mcp` serves agents
+ * over stdio, and any other first word is a board command (`orbit view`).
+ * Each command loads only what it runs: Hono for `orbit run`, the MCP SDK for
+ * `orbit mcp`, neither for a board command.
+ */
+// First, so Node 22 never prints its SQLite warning.
+import "../quiet-sqlite-warning.js";
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { namedAgentActor } from "../core/actors.js";
+import { readEnv } from "../node/env.js";
+// What `orbit help <word>` says for the commands this file runs itself.
+const SERVER_HELP = {
+    run: `orbit run [--port <n>] [-d]
+Start Orbit: it serves the app and the board commands, then prints the address to open.
+--port <n> uses that port (without it Orbit starts at 13701 and moves up if it's busy);
+-d keeps it running in the background and prints its PID and log.`,
+    mcp: `orbit mcp
+Serve the board commands to an MCP app over stdio (the orbit_read and orbit_write tools).
+Add it once for your user, for example in Claude Code:
+  claude mcp add --scope user orbit --env ORBIT_AGENT_NAME=claude -- orbit mcp`,
+    version: `orbit -v
+Print Orbit's version (also orbit --version).`,
+    migrate: `orbit migrate [<old data folder or exports...>] [--to <new folder>] [--json]
+Bring boards from an older Orbit (1.x, or 2.0 before its rebuild) into this Orbit's data folder
+(~/.starscape/orbit, or DATA_DIR), or the folder --to names, which must be new, empty or hold no
+boards. With no folder named it reads ~/.orbit, the older Orbit's own, and its boards may join
+boards already here when none has the same name. The old files are only read, never changed. Each
+board keeps its cards, numbers and ids, and is checked against the old one; the report says
+anything that couldn't come. Running it again changes nothing.`
+};
+const SERVER_ALIASES = { serve: "run", v: "version" };
+// The server-side commands; any other first word is a board command (orbit view, orbit take...).
+const SERVER_COMMANDS = new Set(["run", "serve", "mcp", "migrate", "version", "help"]);
+// Commands Orbit 2.0 removed: each says what replaced it, in one line, and exits non-zero.
+const REMOVED_COMMANDS = {
+    init: "boards live in Orbit now, not in your repo. Run `orbit run` and make a board in the app, or `orbit boards new <name>`.",
+    reset: "Orbit no longer writes files into your repo. To delete a board, open the app with `orbit run`, then Settings, Data, Delete Board.",
+    dispatch: "your agent takes cards itself: have it run `orbit take`, or `orbit take 12` for one card.",
+    docker: "start Orbit with `orbit run`, or build the Dockerfile that ships with Orbit with docker build."
+};
+/** The one text for `orbit`, `orbit help` and `orbit --help`: start, the board commands, connect an agent. */
+async function printHelp(env) {
+    const { agentLines, helpText } = await import("../commands/index.js");
+    const actor = namedAgentActor(env.agentName);
+    const boardHelp = (await helpText(actor, "cli")).text;
+    console.log(`Orbit: a kanban board for you and your AI agents.
+
+For agents:
+${agentLines({ actor, transport: "cli" })
+        .map((line) => `  ${line}`)
+        .join("\n")}
+
+Start:
+  orbit run: open Orbit in your browser at the address it prints, and make a board
+  orbit run --port 8080 -d: another port, kept running in the background
+  orbit migrate: boards from an older Orbit (in ~/.orbit), brought over
+
+${boardHelp}
+
+Connect an agent:
+  An agent with a shell needs only the orbit command. Say this to it once, or put it
+  in the project's AGENTS.md or CLAUDE.md:
+    Use Orbit for this project's tasks, on the board <board>: run orbit help to learn it,
+    and name the board in commands (orbit view <board>, <board>#12) unless the repo's
+    orbit.json names it.
+  MCP apps get one server for your user, named orbit. In Claude Code:
+    claude mcp add --scope user orbit --env ORBIT_AGENT_NAME=claude -- orbit mcp
+  Name each agent so cards say which did what: in a shell, export ORBIT_AGENT_NAME=<name>;
+  an MCP app sets it in the server's env, as --env does above.
+
+orbit help <command> explains one command; orbit -v prints the version.`);
+}
+/** `run`'s options, or the word it doesn't take. */
+function runArgs(rest) {
+    const args = { port: null, detach: false };
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i] ?? "";
+        if (arg === "--port" && rest[i + 1])
+            args.port = rest[++i] ?? null;
+        else if (arg.startsWith("--port="))
+            args.port = arg.slice("--port=".length);
+        else if (arg === "-d" || arg === "--detach")
+            args.detach = true;
+        else
+            return { unknown: arg };
+    }
+    return args;
+}
+async function startDetached(env, args) {
+    const { makeDefaultDataDir, nextSteps, olderDataWaiting } = await import("../node/data-folder.js");
+    makeDefaultDataDir(env);
+    mkdirSync(env.dataDir, { recursive: true });
+    // The server says for sure in its log; here a folder of boards is enough to tell, without opening it.
+    const boardsDir = join(env.dataDir, "boards");
+    const older = olderDataWaiting(env) && !(existsSync(boardsDir) && readdirSync(boardsDir).length);
+    const logPath = join(env.dataDir, "orbit-run.log");
+    const logFd = openSync(logPath, "a");
+    const childArgs = [fileURLToPath(new URL("./orbit.js", import.meta.url)), "run", ...(args.port ? ["--port", args.port] : [])];
+    const child = spawn(process.execPath, childArgs, { cwd: process.cwd(), detached: true, env: { ...process.env }, stdio: ["ignore", logFd, logFd] });
+    child.unref();
+    closeSync(logFd);
+    const named = args.port ?? (env.port === null ? null : String(env.port));
+    const port = named ?? "13701";
+    console.log("Started Orbit in detached mode.");
+    console.log(`PID: ${child.pid ?? ""}`);
+    console.log(`Log: ${logPath}`);
+    console.log(named ? `URL: http://localhost:${port}` : `URL: starts at http://localhost:${port} (auto-increments if busy; see log)`);
+    // The same next steps the foreground start prints, then how to stop it.
+    console.log("");
+    console.log("Next:");
+    nextSteps(`http://localhost:${port}`, older ? "to see them" : "", older).forEach((line) => { console.log(line); });
+    console.log("");
+    console.log(`Stop it with: kill ${child.pid ?? ""}`);
+}
+/** A migration count's records in the app's words: "1 card", "3 journal entries". */
+const COUNT_WORDS = {
+    states: ["lane", "lanes"],
+    labels: ["label", "labels"],
+    tickets: ["card", "cards"],
+    comments: ["comment", "comments"],
+    review_verdicts: ["review", "reviews"],
+    relations: ["link between cards", "links between cards"],
+    cross_board_relations: ["link to another board", "links to other boards"],
+    attachments: ["image", "images"],
+    board_entries: ["journal entry", "journal entries"],
+    events: ["history event", "history events"]
+};
+function countWords(kind, n) {
+    const words = COUNT_WORDS[kind];
+    return words ? words[n === 1 ? 0 : 1] : kind.replace(/_/g, " ");
+}
+/** `orbit migrate [<old folder or exports...>] [--to <folder>] [--json]`: an older Orbit's boards (~/.orbit when none is named) into a new folder. */
+async function runMigrate(env, rest) {
+    const sources = [];
+    let to = env.dataDir;
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i] ?? "";
+        if (arg === "--to" && rest[i + 1])
+            to = rest[++i] ?? to;
+        else if (arg.startsWith("--to="))
+            to = arg.slice("--to=".length);
+        else if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown argument: ${arg}`);
+            console.error(SERVER_HELP.migrate);
+            process.exitCode = 1;
+            return;
+        }
+        else
+            sources.push(arg);
+    }
+    const { makeDefaultDataDir } = await import("../node/data-folder.js");
+    // With no folder named, into Orbit's own folder: the old boards may join boards already there.
+    const fill = !sources.length && resolve(to) === env.dataDir;
+    if (!sources.length) {
+        // The older Orbit's default, read only when it holds a registry: it is never made or changed here.
+        if (!existsSync(join(env.olderDataDir, "registry.db"))) {
+            console.error(`Nothing to bring: ${env.olderDataDir} holds no boards from an older Orbit. Name the old data folder or exports: orbit migrate <folder or exports...>`);
+            process.exitCode = 1;
+            return;
+        }
+        sources.push(env.olderDataDir);
+    }
+    if (resolve(to) === env.dataDir)
+        makeDefaultDataDir(env);
+    const { migrate } = await import("../node/migrate.js");
+    const report = await migrate({ sources, to, fill });
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(report.already ? `These boards are already in ${report.to}: nothing was changed.` : `Brought ${report.boards.length} board${report.boards.length === 1 ? "" : "s"} into ${report.to}. The old files weren't changed.`);
+    for (const board of report.boards) {
+        const counts = Object.entries(board.counts)
+            .filter(([, n]) => n > 0)
+            .map(([kind, n]) => `${n} ${countWords(kind, n)}`)
+            .join(", ");
+        console.log(`\n${board.slug}: ${counts || "empty"}.`);
+        console.log(`  Checked against the old board: ${board.matched.length === Object.keys(board.counts).length ? "every record and file matches" : `matches for ${board.matched.map((kind) => countWords(kind, 2)).join(", ")}`}.`);
+        for (const note of board.notes)
+            console.log(`  ${note}`);
+    }
+    for (const note of report.notes)
+        console.log(`\n${note}`);
+    // Where 1.x used each board, so its repo can name it again; nothing is written there. A folder
+    // can name one board, so boards 1.x kept for the same folder share a line.
+    const home = homedir();
+    const byFolder = new Map();
+    for (const board of report.boards)
+        if (board.folder_1x)
+            byFolder.set(board.folder_1x, [...(byFolder.get(board.folder_1x) ?? []), board.slug]);
+    if (byFolder.size)
+        console.log("");
+    for (const [folder, slugs] of byFolder) {
+        const shown = folder === home || folder.startsWith(home + sep) ? `~${folder.slice(home.length)}` : folder;
+        const link = slugs.length === 1 ? `${slugs[0] ?? ""}: 1.x used it for ${shown}. Run \`orbit boards link ${slugs[0] ?? ""}\` there.` : `${slugs.join(" and ")}: 1.x used them for ${shown}. A folder names one board: run \`orbit boards link <board>\` there with the one its agents should use.`;
+        console.log(`${link} That folder may still hold 1.x's SKILL-ORBIT.md and an Orbit block in AGENTS.md; you can remove them.`);
+    }
+    if (!report.already && resolve(report.to) !== env.dataDir)
+        console.log(`\nStart Orbit on it with DATA_DIR=${report.to} orbit run.`);
+}
+/** Pulls `-m -` (or --text -) out of the words: the text comes from stdin. */
+function takeStdinText(words) {
+    const out = [];
+    let text;
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i] ?? "";
+        if (["-m", "--message", "--text"].includes(word) && words[i + 1] === "-") {
+            text = readFileSync(0, "utf8").replace(/\n$/, "");
+            i += 1;
+        }
+        else if (["-m=-", "--message=-", "--text=-"].includes(word)) {
+            text = readFileSync(0, "utf8").replace(/\n$/, "");
+        }
+        else {
+            out.push(word);
+        }
+    }
+    return { words: out, text };
+}
+async function runBoardCommand(env, words) {
+    const { words: argv, text } = takeStdinText(words);
+    const input = { argv, transport: "cli", ...(text === undefined ? {} : { text }) };
+    const repo = await import("../node/repo-board.js");
+    if (env.mode === "remote") {
+        if (!env.apiUrl)
+            throw new Error("ORBIT_MODE=remote requires ORBIT_API_URL.");
+        const { createHttpClient } = await import("../client/http.js");
+        // The client reads this repo's orbit.json and sends the board with each command.
+        const client = createHttpClient({ baseUrl: env.apiUrl, headers: { "x-orbit-actor-type": "agent", "x-orbit-agent-name": env.agentName }, board: env.board, repo: () => repo.readRepoBoard(process.cwd()) });
+        const link = repo.repoLinkWords(argv);
+        if (!link)
+            return client.command(input);
+        // The server checks the words and the board; this shell writes the file.
+        const checked = await client.command({ ...input, json: true });
+        if (!checked.ok)
+            return checked;
+        const board = checked.data?.board ?? "";
+        const result = link === "link" ? repo.linkRepoBoard(process.cwd(), board) : repo.unlinkRepoBoard(process.cwd());
+        return result.ok && argv.includes("--json") ? { ...result, text: JSON.stringify(result.data) } : result;
+    }
+    const [{ openLocalOrbit }, { createSession, runCommand }] = await Promise.all([import("../node/local.js"), import("../commands/index.js")]);
+    const local = await openLocalOrbit(env);
+    try {
+        const session = createSession(local.orbit.context(namedAgentActor(env.agentName)), { transport: "cli", board: env.board, repo: repo.repoSourceAt(process.cwd(), { writes: true }) });
+        return await runCommand(input, session);
+    }
+    finally {
+        await local.close();
+    }
+}
+function removed(word) {
+    if (!Object.hasOwn(REMOVED_COMMANDS, word))
+        return false;
+    console.error(`orbit ${word} was removed in Orbit 2.0: ${REMOVED_COMMANDS[word] ?? ""}`);
+    process.exitCode = 1;
+    return true;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const first = argv[0];
+    const env = readEnv();
+    if (first !== undefined && removed(first))
+        return;
+    if (first && !first.startsWith("-") && !SERVER_COMMANDS.has(first)) {
+        const result = await runBoardCommand(env, argv);
+        if (result.ok)
+            console.log(result.text);
+        else {
+            console.error(result.text);
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (first === "help" && argv[1]) {
+        const word = argv[1].replace(/^--?/, "");
+        if (removed(word))
+            return;
+        const server = SERVER_HELP[SERVER_ALIASES[word] ?? word];
+        if (server && !argv[2])
+            console.log(server);
+        else {
+            const { helpText } = await import("../commands/index.js");
+            const result = await helpText(namedAgentActor(env.agentName), "cli", argv.slice(1));
+            if (result.ok)
+                console.log(result.text);
+            else {
+                console.error(result.text);
+                process.exitCode = 1;
+            }
+        }
+        return;
+    }
+    if (first === undefined || first === "-h" || first === "--help" || first === "help") {
+        await printHelp(env);
+        return;
+    }
+    if (first === "run" || first === "serve") {
+        const args = runArgs(argv.slice(1));
+        if ("unknown" in args) {
+            console.error(`Unknown argument: ${args.unknown}`);
+            console.error("Run orbit help to see what Orbit takes.");
+            process.exitCode = 1;
+            return;
+        }
+        if (args.detach) {
+            await startDetached(env, args);
+            return;
+        }
+        const port = args.port === null ? env.port : /^\d{1,5}$/.test(args.port) ? Number(args.port) : env.port;
+        const { runServer } = await import("../node/serve.js");
+        await runServer({ ...env, port });
+        return;
+    }
+    if (first === "mcp") {
+        const { runMcpServer } = await import("../mcp-server.js");
+        await runMcpServer();
+        return;
+    }
+    if (first === "migrate") {
+        await runMigrate(env, argv.slice(1));
+        return;
+    }
+    console.error(`Unknown option ${first}.`);
+    await printHelp(env);
+    process.exitCode = 1;
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+await new Promise((resolve) => process.stdout.write("", () => { resolve(); }));
+await new Promise((resolve) => process.stderr.write("", () => { resolve(); }));

package/lib/cli/orbit.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * The `orbit` bin. Node's warning filter first; `orbit -v` answers here,
+ * loading nothing else; otherwise Node's compile cache goes on, so every later
+ * start skips compiling Orbit and its libraries again, and the CLI itself
+ * (./main.ts) runs.
+ */
+import "../quiet-sqlite-warning.ts";

package/lib/cli/orbit.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * The `orbit` bin. Node's warning filter first; `orbit -v` answers here,
+ * loading nothing else; otherwise Node's compile cache goes on, so every later
+ * start skips compiling Orbit and its libraries again, and the CLI itself
+ * (./main.ts) runs.
+ */
+import "../quiet-sqlite-warning.js";
+import { enableCompileCache } from "node:module";
+// Orbit's search is SQLite's FTS5, which Node's own SQLite has from 22.16 and
+// 24.0 (not 23); on an older Node every new board would fail, so say so first.
+const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 16) || major === 23) {
+    console.error(`Orbit needs Node.js 22.16 or newer (24 is recommended); this is ${process.version}, whose SQLite has no full-text search.`);
+    process.exit(1);
+}
+const first = process.argv[2];
+if (first === "-v" || first === "--version" || first === "version") {
+    const { packageVersion } = await import("../node/package.js");
+    console.log(packageVersion());
+}
+else {
+    enableCompileCache();
+    await import("./main.js");
+}

package/lib/client/http.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The OrbitClient over HTTP: `createHttpClient({ baseUrl })` calls an Orbit's
+ * JSON API with any `fetch` (remote agents, the CLI in remote mode, the web
+ * app, the Suite). Each method is one route; a refusal comes back as the
+ * OrbitError the server answered with.
+ *
+ * A command session's board lives here, on the caller's side: the server
+ * forgets between requests, so each command sends the board this client
+ * chose last, and the caller's orbit.json as it reads it.
+ */
+import type { RepoChoice } from "../commands/index.ts";
+import type { OrbitClient } from "./types.ts";
+export interface HttpClientOptions {
+    baseUrl: string;
+    /** Default: globalThis.fetch. The browser edition passes its in-page app's. */
+    fetch?: typeof fetch;
+    /** x-orbit-agent-name, or a host's own auth. */
+    headers?: Record<string, string>;
+    /** The board a command session starts on (ORBIT_BOARD). */
+    board?: string | null;
+    /** The caller's orbit.json, read where it runs, sent with each command. */
+    repo?: () => RepoChoice | null;
+    /**
+     * How `attachments.url()` gives an image: `route` (the default), the
+     * server's address for its bytes; `object`, the bytes fetched and given as
+     * an object URL, for a `fetch` no browser can reach by address (the
+     * browser edition's in-page app) or a server that needs headers.
+     */
+    images?: "route" | "object";
+    /** The live stream's reconnect delays, in ms: the first, and the most it doubles to. Default 1,000 and 30,000. */
+    reconnect?: {
+        firstMs?: number;
+        maxMs?: number;
+    };
+    /** With no byte from the stream for this long (heartbeats included), it reconnects. Default 75,000 (the server's heartbeat is 30,000). */
+    staleMs?: number;
+}
+export declare function createHttpClient(options: HttpClientOptions): OrbitClient;