@starlove/orbit 1.4.1 → 2.0.0

package/lib/mcp-server.js

@@ -0,0 +1,120 @@
+/**
+ * `orbit mcp`: the board commands for an MCP app over stdio, on the MCP SDK's
+ * low-level Server. Two tools take a command line (orbit_read refuses
+ * anything that writes), and the guide is a resource. Local mode runs Orbit
+ * in this process on the data folder; remote mode (ORBIT_MODE=remote) sends
+ * each command to ORBIT_API_URL. Either way the repo's orbit.json is read
+ * where the server runs, or in the folder `--cwd` names.
+ */
+import "./quiet-sqlite-warning.js";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { ProtocolError, ProtocolErrorCode, ResourceNotFoundError, Server } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { namedAgentActor } from "./core/actors.js";
+import { ORBIT_COMMAND_INSTRUCTIONS, commandTools } from "./commands/agent-tools.js";
+import { readEnv } from "./node/env.js";
+import { PACKAGE_ROOT, openLocalOrbit, packageVersion } from "./node/local.js";
+import { readRepoBoard, repoSourceAt } from "./node/repo-board.js";
+const GUIDE = {
+    uri: "orbit://guide",
+    name: "orbit-guide",
+    title: "Orbit agent guide",
+    description: "How to work Orbit cards, fields, blockers, Journal, and the HTTP API.",
+    mimeType: "text/markdown"
+};
+/** Where to read the repo's orbit.json: where `orbit mcp` runs, or the folder `--cwd <dir>` names. */
+function repoDir(args) {
+    let dir = null;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? "";
+        if (arg === "--cwd" && args[i + 1])
+            dir = args[++i] ?? null;
+        else if (arg.startsWith("--cwd="))
+            dir = arg.slice("--cwd=".length);
+    }
+    return resolve(process.cwd(), dir ?? ".");
+}
+async function openClient() {
+    const env = readEnv();
+    const dir = repoDir(process.argv.slice(2));
+    if (env.mode === "remote") {
+        if (!env.apiUrl)
+            throw new Error("ORBIT_MODE=remote requires ORBIT_API_URL.");
+        const { createHttpClient } = await import("./client/http.js");
+        const client = createHttpClient({
+            baseUrl: env.apiUrl,
+            headers: { "x-orbit-actor-type": "agent", "x-orbit-agent-name": env.agentName },
+            board: env.board,
+            repo: () => readRepoBoard(dir)
+        });
+        return { client, close: () => Promise.resolve() };
+    }
+    const local = await openLocalOrbit(env);
+    return { client: local.orbit.client(namedAgentActor(env.agentName), { transport: "mcp", board: env.board, repo: repoSourceAt(dir) }), close: () => local.close() };
+}
+export async function runMcpServer() {
+    const args = process.argv.slice(process.argv[2] === "mcp" ? 3 : 2);
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? "";
+        if (arg === "--cwd" && args[i + 1])
+            i += 1;
+        else if (!arg.startsWith("--cwd=")) {
+            console.error(`Unknown argument: ${arg}`);
+            console.error("Run orbit help to see what Orbit takes.");
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const { client, close } = await openClient();
+    const tools = commandTools();
+    let guide = null;
+    const guideText = () => (guide ??= readFileSync(join(PACKAGE_ROOT, "docs", "AGENT_GUIDE.md"), "utf8"));
+    // The low-level Server keeps the tool list, descriptions, schemas and instructions exactly as Orbit writes them (the fixtures pin them).
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    const server = new Server({ name: "starscape-orbit", title: "Starscape Orbit", version: packageVersion() }, { capabilities: { tools: {}, resources: {} }, instructions: ORBIT_COMMAND_INSTRUCTIONS });
+    server.setRequestHandler("tools/list", () => ({ tools: tools.map(({ name, description, inputSchema, annotations }) => ({ name, description, inputSchema, annotations })) }));
+    server.setRequestHandler("tools/call", async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        const tool = tools.find((candidate) => candidate.name === name);
+        if (!tool)
+            throw new ProtocolError(ProtocolErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        const command = args.command;
+        if (typeof command !== "string" || !command.trim()) {
+            return { content: [{ type: "text", text: `${tool.name} needs a command, e.g. ${tool.name === "orbit_read" ? "view" : "take"}. help lists them all.` }], isError: true };
+        }
+        try {
+            const reply = await client.command({ command, ...(typeof args.text === "string" ? { text: args.text } : {}), readOnly: tool.name === "orbit_read" });
+            return { content: [{ type: "text", text: reply.text }], ...(reply.ok ? {} : { isError: true }) };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: error instanceof Error && error.message ? error.message : "Tool call failed." }], isError: true };
+        }
+    });
+    server.setRequestHandler("resources/list", () => ({ resources: [GUIDE] }));
+    server.setRequestHandler("resources/templates/list", () => ({ resourceTemplates: [] }));
+    server.setRequestHandler("resources/read", (request) => {
+        const { uri } = request.params;
+        if (uri !== GUIDE.uri)
+            throw new ResourceNotFoundError(uri, `Resource not found: ${uri}`);
+        return { contents: [{ uri, mimeType: GUIDE.mimeType, text: guideText() }] };
+    });
+    let stopping = false;
+    const shutdown = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        void server
+            .close()
+            .catch(() => undefined)
+            .then(close)
+            .finally(() => process.exit(0));
+    };
+    process.stdin.on("end", shutdown);
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    await server.connect(new StdioServerTransport());
+}
+// Run when started directly (an MCP app's `node .../mcp-server.js`); `orbit mcp` imports runMcpServer.
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname))
+    await runMcpServer();

package/lib/node/assets.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The app's files from a folder (dist/full). A path that names no file
+ * answers with the app's page, as the app's hash routes expect; a path
+ * outside the folder is refused. With no build in the folder, the page says
+ * how to make one.
+ */
+export declare function folderAssets(root: string): (request: Request, pathname: string) => Promise<Response | null>;

package/lib/node/assets.js

@@ -0,0 +1,68 @@
+/**
+ * The app's files from a folder (dist/full). A path that names no file
+ * answers with the app's page, as the app's hash routes expect; a path
+ * outside the folder is refused. With no build in the folder, the page says
+ * how to make one.
+ */
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml"
+};
+/** /app and /app/... are the same files as /. */
+function assetPath(pathname) {
+    return pathname === "/app" || pathname.startsWith("/app/") ? pathname.slice(4) || "/" : pathname;
+}
+/**
+ * The page's Content-Security-Policy, which the build wrote beside it
+ * (`csp.txt`: its inline scripts allowed by hash, nothing else inline). A
+ * folder without one (a build from before it) still refuses framing.
+ */
+function pagePolicy(root) {
+    try {
+        return readFileSync(resolve(root, "csp.txt"), "utf8").trim() || "frame-ancestors 'none'";
+    }
+    catch {
+        return "frame-ancestors 'none'";
+    }
+}
+export function folderAssets(root) {
+    const policy = pagePolicy(root);
+    async function serve(request, pathname) {
+        const path = assetPath(pathname);
+        let decoded;
+        try {
+            decoded = decodeURIComponent(path === "/" ? "/index.html" : path);
+        }
+        catch {
+            return new Response(null, { status: 404 });
+        }
+        const file = resolve(root, `.${decoded}`);
+        if (!file.startsWith(root))
+            return new Response(null, { status: 403 });
+        try {
+            const data = await readFile(file);
+            return new Response(request.method === "HEAD" ? null : data, {
+                status: 200,
+                headers: {
+                    "Content-Type": TYPES[extname(file)] ?? "application/octet-stream",
+                    "Cache-Control": "no-store",
+                    // Scripts only from Orbit itself, and another site must not frame the UI and steer clicks (clickjacking).
+                    "Content-Security-Policy": policy,
+                    "X-Frame-Options": "DENY"
+                }
+            });
+        }
+        catch {
+            if (pathname !== "/")
+                return serve(request, "/");
+            return new Response("Orbit's web app isn't built here. In a checkout, run: node build.mjs\n", { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+        }
+    }
+    return serve;
+}

package/lib/node/data-folder.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The default data folder on this computer: made for its user alone, and
+ * whether an older Orbit's boards wait in its old default for `orbit migrate`.
+ */
+import type { OrbitEnv } from "./env.ts";
+/**
+ * Makes ~/.starscape and ~/.starscape/orbit when they are missing, readable by
+ * this user alone (0700), because boards are private work. A folder that
+ * exists keeps its mode, and a DATA_DIR someone set is the store's to make.
+ */
+export declare function makeDefaultDataDir(env: OrbitEnv): void;
+/**
+ * True when Orbit runs on its default folder and an older Orbit's registry is
+ * in ~/.orbit. Only the file's presence is checked: it is never opened.
+ */
+export declare function olderDataWaiting(env: OrbitEnv): boolean;
+/**
+ * The numbered steps `orbit run` prints under "Next:". While the default
+ * folder holds no boards and the old one does, bringing them comes first.
+ */
+export declare function nextSteps(url: string, open: string, older: boolean): string[];

package/lib/node/data-folder.js

@@ -0,0 +1,34 @@
+/**
+ * The default data folder on this computer: made for its user alone, and
+ * whether an older Orbit's boards wait in its old default for `orbit migrate`.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Makes ~/.starscape and ~/.starscape/orbit when they are missing, readable by
+ * this user alone (0700), because boards are private work. A folder that
+ * exists keeps its mode, and a DATA_DIR someone set is the store's to make.
+ */
+export function makeDefaultDataDir(env) {
+    if (env.dataDirIsDefault)
+        mkdirSync(env.dataDir, { recursive: true, mode: 0o700 });
+}
+/**
+ * True when Orbit runs on its default folder and an older Orbit's registry is
+ * in ~/.orbit. Only the file's presence is checked: it is never opened.
+ */
+export function olderDataWaiting(env) {
+    return env.dataDirIsDefault && existsSync(join(env.olderDataDir, "registry.db"));
+}
+/**
+ * The numbered steps `orbit run` prints under "Next:". While the default
+ * folder holds no boards and the old one does, bringing them comes first.
+ */
+export function nextSteps(url, open, older) {
+    const steps = [
+        ...(older ? ["Bring your boards from an older Orbit (in ~/.orbit): run orbit migrate in a terminal (it only reads the old files)."] : []),
+        `Open ${url} in your browser${open ? ` ${open}` : ""}.`,
+        "Connect your agents: in the app, Help, then Connect your agents. Or run orbit help."
+    ];
+    return steps.map((step, i) => `  ${String(i + 1)}. ${step}`);
+}

package/lib/node/env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What Orbit reads from the environment, checked once where it enters. A
+ * value that can't be used falls back to its default,
+ * except ORBIT_MODE, which is refused: a typo there would quietly point an
+ * agent at the wrong Orbit. Plain checks, not zod: every command reads the
+ * environment, and loading zod costs one-shot commands like `orbit view`
+ * more than their whole start (60 to 100 ms).
+ */
+export interface OrbitEnv {
+    dataDir: string;
+    /** True when Orbit uses its default, ~/.starscape/orbit, which an agent's `orbit mcp` finds without being told. */
+    dataDirIsDefault: boolean;
+    /** An older Orbit's default data folder, ~/.orbit: what `orbit migrate` reads when no folder is named. */
+    olderDataDir: string;
+    /** Null when no PORT was given (Orbit starts at 13701 and moves up past busy ports). */
+    port: number | null;
+    host: string;
+    /** Names besides IP addresses, localhost and tailnet names that `orbit run` answers to (ORBIT_ALLOWED_HOSTS). */
+    allowedHosts: string[];
+    mode: "local" | "remote";
+    apiUrl: string;
+    agentName: string;
+    board: string | null;
+    backups: {
+        enabled: boolean;
+        delayMs: number;
+        retention: number;
+    };
+    selfUpdate: boolean;
+    updates: {
+        enabled: boolean;
+        ttlMinutes: number;
+        branch: string;
+        token: string;
+        docker: boolean;
+    };
+}
+export declare function readEnv(env?: NodeJS.ProcessEnv): OrbitEnv;

package/lib/node/env.js

@@ -0,0 +1,49 @@
+/**
+ * What Orbit reads from the environment, checked once where it enters. A
+ * value that can't be used falls back to its default,
+ * except ORBIT_MODE, which is refused: a typo there would quietly point an
+ * agent at the wrong Orbit. Plain checks, not zod: every command reads the
+ * environment, and loading zod costs one-shot commands like `orbit view`
+ * more than their whole start (60 to 100 ms).
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { allowedHostsFrom } from "./host-check.js";
+/** A value with its spaces trimmed, or undefined when it is missing or blank. */
+const text = (value) => value?.trim() || undefined;
+/** A whole number of at least `min`, or the fallback. */
+function whole(value, fallback, min = 0) {
+    const trimmed = value?.trim() ?? "";
+    if (!/^\d+$/.test(trimmed))
+        return fallback;
+    const number = Number(trimmed);
+    return Number.isSafeInteger(number) && number >= min ? number : fallback;
+}
+/** True when the value says off: 0, false or off. */
+const isOff = (value) => ["0", "false", "off"].includes((value ?? "1").trim().toLowerCase());
+export function readEnv(env = process.env) {
+    const home = resolve(text(env.HOME) ?? homedir());
+    // Each Starscape product keeps its own folder under ~/.starscape, which the Suite can link.
+    const fallbackDir = join(home, ".starscape", "orbit");
+    const dataDir = resolve(text(env.DATA_DIR) ?? fallbackDir);
+    const modeWord = (env.ORBIT_MODE ?? "local").trim().toLowerCase();
+    if (!["local", "", "remote", "http"].includes(modeWord))
+        throw new Error(`Unsupported ORBIT_MODE: ${env.ORBIT_MODE ?? ""}`);
+    const portText = text(env.PORT);
+    const port = portText && /^\d{1,5}$/.test(portText) ? Number(portText) : null;
+    return {
+        dataDir,
+        dataDirIsDefault: dataDir === resolve(fallbackDir),
+        olderDataDir: join(home, ".orbit"),
+        port,
+        host: text(env.HOST) ?? text(env.ORBIT_HOST) ?? "127.0.0.1",
+        allowedHosts: allowedHostsFrom(env.ORBIT_ALLOWED_HOSTS),
+        mode: modeWord === "remote" || modeWord === "http" ? "remote" : "local",
+        apiUrl: (text(env.ORBIT_API_URL) ?? "").replace(/\/+$/, ""),
+        agentName: text(env.ORBIT_AGENT_NAME) ?? "agent",
+        board: text(env.ORBIT_BOARD) ?? text(env.ORBIT_DEFAULT_BOARD) ?? null,
+        backups: { enabled: !isOff(env.ORBIT_AUTO_BACKUPS), delayMs: whole(env.ORBIT_AUTO_BACKUP_DELAY_MS, 120_000), retention: whole(env.ORBIT_BACKUP_RETENTION, 30, 1) },
+        selfUpdate: text(env.ORBIT_SELF_UPDATE) === "1",
+        updates: { enabled: text(env.ORBIT_UPDATE_CHECK) !== "0", ttlMinutes: whole(env.ORBIT_UPDATE_TTL, 60, 1), branch: text(env.ORBIT_UPDATE_BRANCH) ?? "master", token: text(env.ORBIT_GITHUB_TOKEN) ?? "", docker: text(env.ORBIT_DOCKER) === "1" }
+    };
+}

package/lib/node/host-check.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The names `orbit run` answers to. The API has no accounts and trusts its
+ * own pages, so a page of another site that a DNS rebind points at this
+ * computer would look like Orbit's own (same Host, same Origin). A browser
+ * always says which name it asked for, so a request naming anything else is
+ * refused (421) before it reaches the app: an IP address, `localhost` and
+ * `*.localhost`, a tailnet name (`*.ts.net`), the name HOST binds to, and
+ * the names in ORBIT_ALLOWED_HOSTS (a reverse proxy's own domain, a short
+ * tailnet name, a `.local` or LAN name) are answered. The same goes for X-Forwarded-Host, which a proxy sets.
+ */
+/** A Host header's name, without its port, lowercased and without a final dot; "" for none. */
+export declare function hostName(value: string): string;
+export interface HostCheck {
+    /** The name a request was refused for, or null when every name it gives is one Orbit answers to. */
+    refused(headers: Headers): string | null;
+}
+/** Names from ORBIT_ALLOWED_HOSTS: comma-separated, each a name (a port, if given, is ignored). */
+export declare function allowedHostsFrom(value: string | undefined): string[];
+export declare function hostCheck(options: {
+    bind: string;
+    allowed: readonly string[];
+}): HostCheck;
+/** The one plain line a refused name gets. */
+export declare function misdirected(name: string): Response;

package/lib/node/host-check.js

@@ -0,0 +1,53 @@
+/**
+ * The names `orbit run` answers to. The API has no accounts and trusts its
+ * own pages, so a page of another site that a DNS rebind points at this
+ * computer would look like Orbit's own (same Host, same Origin). A browser
+ * always says which name it asked for, so a request naming anything else is
+ * refused (421) before it reaches the app: an IP address, `localhost` and
+ * `*.localhost`, a tailnet name (`*.ts.net`), the name HOST binds to, and
+ * the names in ORBIT_ALLOWED_HOSTS (a reverse proxy's own domain, a short
+ * tailnet name, a `.local` or LAN name) are answered. The same goes for X-Forwarded-Host, which a proxy sets.
+ */
+import { isIP } from "node:net";
+/** A Host header's name, without its port, lowercased and without a final dot; "" for none. */
+export function hostName(value) {
+    const host = value.trim().toLowerCase();
+    if (host.startsWith("[")) {
+        const end = host.indexOf("]");
+        return end > 0 ? host.slice(1, end) : host;
+    }
+    const colon = host.lastIndexOf(":");
+    // One colon is a port; more is a bare IPv6 address (not valid in Host, but an address all the same).
+    const name = colon > -1 && host.indexOf(":") === colon ? host.slice(0, colon) : host;
+    return name.replace(/\.$/, "");
+}
+/** Names from ORBIT_ALLOWED_HOSTS: comma-separated, each a name (a port, if given, is ignored). */
+export function allowedHostsFrom(value) {
+    return (value ?? "")
+        .split(",")
+        .map(hostName)
+        .filter(Boolean);
+}
+export function hostCheck(options) {
+    const named = new Set([...options.allowed.map(hostName), hostName(options.bind)].filter(Boolean));
+    const answers = (name) => isIP(name) !== 0 || name === "localhost" || name.endsWith(".localhost") || name.endsWith(".ts.net") || named.has(name);
+    return {
+        refused(headers) {
+            const given = [headers.get("host"), ...(headers.get("x-forwarded-host") ?? "").split(",")].map((value) => (value ?? "").trim()).filter(Boolean);
+            for (const value of given) {
+                const name = hostName(value);
+                if (!answers(name))
+                    return name || value;
+            }
+            return null;
+        }
+    };
+}
+/** The one plain line a refused name gets. */
+export function misdirected(name) {
+    const shown = name.replace(/[^A-Za-z0-9.:[\]_-]/g, "").slice(0, 120) || "given";
+    return new Response(`Orbit doesn't answer to the name ${shown}. To use it, add ${shown} to ORBIT_ALLOWED_HOSTS (comma-separated) where Orbit runs, then restart it.\n`, {
+        status: 421,
+        headers: { "Content-Type": "text/plain; charset=utf-8", "X-Content-Type-Options": "nosniff", "Cache-Control": "no-store" }
+    });
+}

package/lib/node/host-services.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What the computer Orbit runs on does for the app open on it: the update
+ * check (the version on GitHub's default branch, cached; only the server
+ * polls, so GitHub's limits never matter), the opt-in self-update, and a
+ * folder picker. The HTTP app reaches them through `HostServices`.
+ */
+import type { HostServices } from "../client/types.ts";
+import type { OrbitEnv } from "./env.ts";
+export declare function hostServices(env: OrbitEnv, dataDir: string): HostServices;

package/lib/node/host-services.js

@@ -0,0 +1,150 @@
+/**
+ * What the computer Orbit runs on does for the app open on it: the update
+ * check (the version on GitHub's default branch, cached; only the server
+ * polls, so GitHub's limits never matter), the opt-in self-update, and a
+ * folder picker. The HTTP app reaches them through `HostServices`.
+ */
+import { execFile, spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { PACKAGE_ROOT, packageVersion } from "./local.js";
+const CHECK_TIMEOUT_MS = 5000;
+function repoCoordinates() {
+    let url = "";
+    try {
+        const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+        url = pkg.repository?.url ?? "";
+    }
+    catch {
+        url = "";
+    }
+    const match = /github\.com[/:]([^/]+)\/([^/.]+)/i.exec(url);
+    return { owner: match?.[1] ?? "brucestarlove", repo: match?.[2] ?? "ss-orbit" };
+}
+/** How this Orbit runs, which decides the update instructions the app shows. */
+function deployMode(env) {
+    if (env.updates.docker || existsSync("/.dockerenv"))
+        return "docker";
+    if (existsSync(join(PACKAGE_ROOT, ".git")))
+        return "source";
+    return "dist";
+}
+/** True when `latest` is strictly newer than `current` ("a.b.c", any suffix ignored). */
+function isNewer(latest, current) {
+    const parse = (v) => v.replace(/^v/, "").split(/[.+-]/).map((n) => Number(n) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < 3; i += 1) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+async function fetchLatest(env) {
+    const { owner, repo } = repoCoordinates();
+    const headers = { Accept: "application/vnd.github.raw+json", "User-Agent": "orbit-update-check" };
+    if (env.updates.token)
+        headers.Authorization = `Bearer ${env.updates.token}`;
+    try {
+        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/contents/package.json?ref=${encodeURIComponent(env.updates.branch)}`, { headers, signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+        if (res.status === 403 || res.status === 429)
+            return { error: "rate_limited" };
+        if (!res.ok)
+            return { error: `http_${res.status}` };
+        const { version } = JSON.parse(await res.text());
+        if (typeof version !== "string" || !version)
+            return { error: "no_version" };
+        return { latest: version };
+    }
+    catch (error) {
+        return { error: error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError") ? "timeout" : "unreachable" };
+    }
+}
+/** A folder picker on this computer, by platform: the commands to try in order. */
+function pickerCommands(title) {
+    const windows = {
+        command: "powershell.exe",
+        args: [
+            "-NoProfile",
+            "-STA",
+            "-Command",
+            [
+                "Add-Type -AssemblyName System.Windows.Forms",
+                "$dialog = New-Object System.Windows.Forms.FolderBrowserDialog",
+                `$dialog.Description = ${JSON.stringify(title)}`,
+                "if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {",
+                "  [Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+                "  Write-Output $dialog.SelectedPath",
+                "}"
+            ].join("; ")
+        ]
+    };
+    if (process.platform === "darwin")
+        return [{ command: "osascript", args: ["-e", `POSIX path of (choose folder with prompt ${JSON.stringify(title)})`] }];
+    if (process.platform === "win32")
+        return [windows];
+    return [{ command: "zenity", args: ["--file-selection", "--directory", "--title", title] }, { command: "kdialog", args: ["--getexistingdirectory", ".", title] }, windows];
+}
+function wslPath(raw) {
+    const drive = /^([a-zA-Z]):[\\/](.*)$/.exec(raw.trim());
+    if (!drive)
+        return raw.trim();
+    return `/mnt/${(drive[1] ?? "").toLowerCase()}/${(drive[2] ?? "").replace(/\\/g, "/").replace(/^\/+/, "")}`;
+}
+async function pickFolder() {
+    const run = promisify(execFile);
+    const commands = pickerCommands("Choose repo folder for Orbit board");
+    let missing = 0;
+    for (const spec of commands) {
+        try {
+            const { stdout } = await run(spec.command, spec.args, { encoding: "utf8", timeout: 120_000, windowsHide: false });
+            const raw = stdout.trim();
+            const path = raw ? resolve(process.platform === "linux" && spec.command === "powershell.exe" ? wslPath(raw) : raw) : "";
+            return path ? { path } : { canceled: true };
+        }
+        catch (error) {
+            const failure = error;
+            if (failure.code === "ENOENT") {
+                missing += 1;
+                continue;
+            }
+            if (failure.code === 1 && /cancel/i.test(typeof failure.stderr === "string" ? failure.stderr : ""))
+                return { canceled: true };
+            throw error;
+        }
+    }
+    return missing === commands.length ? { unsupported: true } : { canceled: true };
+}
+export function hostServices(env, dataDir) {
+    let cache = null;
+    const fixed = () => {
+        const { owner, repo } = repoCoordinates();
+        return { current: packageVersion(), deployMode: deployMode(env), selfUpdate: env.selfUpdate, repoUrl: `https://github.com/${owner}/${repo}`, changesUrl: `https://github.com/${owner}/${repo}/commits/${env.updates.branch}` };
+    };
+    return {
+        async version({ force }) {
+            if (!env.updates.enabled)
+                return { ...fixed(), enabled: false, latest: null, updateAvailable: false, error: null, checkedAt: null };
+            if (!force && cache && Date.now() - cache.at < env.updates.ttlMinutes * 60_000)
+                return cache.payload;
+            const result = await fetchLatest(env);
+            const payload = { ...fixed(), enabled: true, latest: result.latest ?? null, updateAvailable: Boolean(result.latest) && isNewer(result.latest ?? "", packageVersion()), error: result.error ?? null, checkedAt: new Date().toISOString() };
+            cache = { at: Date.now(), payload };
+            return payload;
+        },
+        selfUpdate() {
+            if (!env.selfUpdate)
+                return null;
+            const script = join(PACKAGE_ROOT, "scripts", "update.sh");
+            if (!existsSync(script))
+                return { started: false, error: "script_missing" };
+            const child = spawn("bash", [script], { cwd: PACKAGE_ROOT, detached: true, stdio: "ignore", env: { ...process.env, ORBIT_REPO_DIR: PACKAGE_ROOT, ORBIT_SERVER_PID: String(process.pid), ORBIT_DATA_DIR: dataDir } });
+            child.unref();
+            return { started: true };
+        },
+        pickFolder
+    };
+}

package/lib/node/local.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Orbit on this computer: the SQLite store in the data folder, the
+ * deployment the person's own app shows, and a backup a while after the
+ * first write of each day. Every entry point that runs Orbit in-process opens it here.
+ */
+import type { Orbit } from "../orbit.ts";
+import type { OrbitEnv } from "./env.ts";
+import type { HostServices } from "../client/types.ts";
+export { PACKAGE_ROOT, packageVersion } from "./package.ts";
+/** The MCP server's file beside the CLI (src/ in a checkout, lib/ in an install); the app builds its connect command from it. */
+export declare const MCP_SERVER_PATH: string;
+/** Where the app's files are: dist/full, which an install ships and a checkout builds (`node build.mjs`). */
+export declare function publicDir(): string;
+export interface LocalOrbit {
+    orbit: Orbit;
+    /** Waits for nothing: pending backups are dropped, then the store is closed. */
+    close(): Promise<void>;
+}
+/** Opens the data folder (refusing one of older data with `data_needs_migration`) and Orbit over it. */
+export declare function openLocalOrbit(env: OrbitEnv, options?: {
+    host?: HostServices;
+}): Promise<LocalOrbit>;