@starlove/orbit 1.4.1 → 2.0.0

package/lib/adapters/sqlite/store.js

@@ -0,0 +1,385 @@
+/**
+ * The SQLite adapter: Orbit's storage port on `node:sqlite`, over a data
+ * folder.
+ *
+ *   registry.db                        the list of boards and the settings
+ *   boards/<folder>/board.db           one board's records
+ *   boards/<folder>/attachments/...    its images (the blob store)
+ *   boards/<folder>/artifacts/...      its markdown
+ *   backups/                           copies (VACUUM INTO), with each board's files linked beside them
+ *
+ * The schema is ./schema.ts. A folder whose files lack v2's version (Orbit
+ * 1.x, or 2.0 before its rebuild) is refused untouched, with
+ * `data_needs_migration`. Several stores, in one process or several, can open
+ * one folder at once: SQLite's locks keep their writes one at a time, and
+ * each hears the others' changes.
+ */
+import { existsSync, mkdirSync, readdirSync, rmdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { OrbitError, isOrbitError } from "../../core/errors.js";
+import { createSqliteBackups } from "./backups.js";
+import { createSqliteBlobStore } from "./blobs.js";
+import { BoardFiles } from "./board.js";
+import { checkFile, Connection, createFile, untilFree } from "./database.js";
+import { Lock } from "./lock.js";
+import { CROSS, toRecord } from "./records.js";
+import { BOARD_SCHEMA, REGISTRY_SCHEMA } from "./schema.js";
+const LISTING = "id, slug, name, folder, repo_url, default_branch, last_active_at, created_at, updated_at";
+const REGISTRY = {
+    list: `SELECT ${LISTING} FROM boards ORDER BY name, seq`,
+    get: `SELECT ${LISTING} FROM boards WHERE id = ?`,
+    bySlug: `SELECT ${LISTING} FROM boards WHERE slug = ?`,
+    latest: `SELECT ${LISTING} FROM boards ORDER BY last_active_at DESC, seq DESC LIMIT 1`,
+    slugTaken: "SELECT 1 AS taken FROM boards WHERE slug = ? AND id <> ?",
+    folderTaken: "SELECT 1 AS taken FROM boards WHERE folder = ?",
+    insert: `INSERT INTO boards (${LISTING}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    touch: "UPDATE boards SET last_active_at = ?, updated_at = ? WHERE id = ?",
+    follow: "UPDATE boards SET slug = ?, name = ?, repo_url = ?, default_branch = ?, updated_at = ? WHERE id = ?",
+    remove: "DELETE FROM boards WHERE id = ? RETURNING folder",
+    setting: "SELECT value FROM settings WHERE key = ?",
+    setSetting: "INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value"
+};
+const TABLE_OF = { state: "states", ticket: "tickets", entry: "board_entries", relation: "relations" };
+/** A board's folder name, from the slug it was made with: letters, digits, `.`, `_` and `-`. */
+function folderName(slug) {
+    const name = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "").slice(0, 80);
+    return name || "board";
+}
+/**
+ * Opens a store over `dataDir`, making the folder and its registry when
+ * they're missing. Rejects with `data_needs_migration` for a folder of older
+ * data, which it leaves as it was.
+ */
+export function openSqliteStore(options) {
+    return new Promise((resolve) => {
+        resolve(open(options));
+    });
+}
+function open(options) {
+    const { dataDir } = options;
+    const busyMs = options.busyTimeoutMs ?? 5000;
+    const registryPath = join(dataDir, "registry.db");
+    const boardsDir = join(dataDir, "boards");
+    // Checked before anything is made, so a folder of older data is left exactly as it was.
+    if (!checkFile(registryPath)) {
+        mkdirSync(dataDir, { recursive: true });
+        createFile(registryPath, REGISTRY_SCHEMA);
+        checkFile(registryPath);
+    }
+    mkdirSync(boardsDir, { recursive: true });
+    const regWriter = new Connection(registryPath);
+    const regReader = new Connection(registryPath, { queryOnly: true });
+    const registryLock = new Lock();
+    /** Each board's folder, once seen; kept after a board is removed, so its blobs can still be removed. */
+    const folders = new Map();
+    const opened = new Map();
+    let closed = false;
+    const deadline = () => Date.now() + busyMs;
+    const live = () => {
+        if (closed)
+            throw new OrbitError("storage_failed", { message: "This store is closed." });
+    };
+    const listing = (row) => {
+        const folder = String(row.folder);
+        folders.set(String(row.id), folder);
+        return {
+            id: String(row.id),
+            slug: String(row.slug),
+            name: String(row.name),
+            db_path: join(boardsDir, folder, "board.db"),
+            repo_url: String(row.repo_url),
+            default_branch: String(row.default_branch),
+            last_active_at: row.last_active_at === null ? null : String(row.last_active_at),
+            created_at: String(row.created_at),
+            updated_at: String(row.updated_at)
+        };
+    };
+    const find = (sql, key) => {
+        live();
+        const row = regReader.get(sql, [key]);
+        return row ? listing(row) : null;
+    };
+    const listed = () => {
+        live();
+        return regReader.all(REGISTRY.list).map(listing);
+    };
+    /** A registry write on its own, in turn with the others. */
+    const registryWrite = (attempt) => registryLock.run(() => untilFree(attempt, deadline()));
+    const host = {
+        busyMs,
+        slugTaken: (slug, exceptId) => regReader.get(REGISTRY.slugTaken, [slug, exceptId]) !== undefined,
+        async follow(board) {
+            const release = await registryLock.acquire();
+            try {
+                await untilFree(() => {
+                    regWriter.exec("BEGIN IMMEDIATE");
+                }, deadline());
+                try {
+                    regWriter.run(REGISTRY.follow, [board.slug, board.name, board.repo_url, board.default_branch, board.updated_at, board.id]);
+                }
+                catch (error) {
+                    regWriter.rollback();
+                    throw error;
+                }
+            }
+            catch (error) {
+                release();
+                throw error;
+            }
+            return {
+                commit() {
+                    try {
+                        regWriter.exec("COMMIT");
+                    }
+                    finally {
+                        release();
+                    }
+                },
+                rollback() {
+                    regWriter.rollback();
+                    release();
+                }
+            };
+        }
+    };
+    /** The board's open files: opened once per store, and again after the board was made anew. */
+    async function filesOf(entry) {
+        const pending = opened.get(entry.id);
+        if (pending) {
+            const files = await pending.catch(() => null);
+            if (files?.isLive())
+                return files;
+            if (opened.get(entry.id) === pending)
+                opened.delete(entry.id);
+        }
+        const opening = BoardFiles.open(host, entry.id, entry.db_path, entry.slug);
+        opened.set(entry.id, opening);
+        try {
+            return await opening;
+        }
+        catch (error) {
+            if (opened.get(entry.id) === opening)
+                opened.delete(entry.id);
+            throw error;
+        }
+    }
+    const boardStores = new WeakMap();
+    const storeOf = (files) => {
+        let store = boardStores.get(files);
+        if (!store) {
+            store = files.store();
+            boardStores.set(files, store);
+        }
+        return store;
+    };
+    /** A folder no board uses and nothing is in. */
+    function freeFolder(slug) {
+        const base = folderName(slug);
+        for (let n = 1;; n += 1) {
+            const name = n === 1 ? base : `${base}-${String(n)}`;
+            if (regWriter.get(REGISTRY.folderTaken, [name]))
+                continue;
+            const path = join(boardsDir, name);
+            if (existsSync(path) && readdirSync(path).length > 0)
+                continue;
+            return name;
+        }
+    }
+    const boards = {
+        list: () => Promise.resolve(listed()),
+        get: (id) => Promise.resolve(find(REGISTRY.get, id)),
+        bySlug: (slug) => Promise.resolve(find(REGISTRY.bySlug, slug)),
+        latest() {
+            live();
+            const row = regReader.get(REGISTRY.latest);
+            return Promise.resolve(row ? listing(row) : null);
+        },
+        create(board, seed) {
+            return registryLock.run(async () => {
+                live();
+                await untilFree(() => {
+                    regWriter.exec("BEGIN IMMEDIATE");
+                }, deadline());
+                let folderPath = null;
+                let files = null;
+                try {
+                    if (regWriter.get(REGISTRY.get, [board.id]))
+                        throw new OrbitError("duplicate_id");
+                    if (regWriter.get(REGISTRY.bySlug, [board.slug]))
+                        throw new OrbitError("board_slug_taken");
+                    const folder = freeFolder(board.slug);
+                    folderPath = join(boardsDir, folder);
+                    mkdirSync(folderPath, { recursive: true });
+                    const dbPath = join(folderPath, "board.db");
+                    createFile(dbPath, BOARD_SCHEMA);
+                    files = await BoardFiles.open(host, board.id, dbPath, board.slug);
+                    const made = await files.seed(board, seed);
+                    regWriter.run(REGISTRY.insert, [made.id, made.slug, made.name, folder, made.repo_url, made.default_branch, board.created_at, made.created_at, made.updated_at]);
+                    regWriter.exec("COMMIT");
+                    opened.set(board.id, Promise.resolve(files));
+                    const entry = regReader.get(REGISTRY.get, [board.id]);
+                    if (!entry)
+                        throw new OrbitError("storage_failed");
+                    return listing(entry);
+                }
+                catch (error) {
+                    regWriter.rollback();
+                    files?.markRemoved();
+                    if (folderPath)
+                        rmSync(folderPath, { recursive: true, force: true });
+                    throw error;
+                }
+            });
+        },
+        async touch(id, at) {
+            live();
+            const { changes } = await registryWrite(() => regWriter.run(REGISTRY.touch, [at, at, id]));
+            if (changes === 0)
+                throw new OrbitError("board_not_found");
+        },
+        async remove(id, options = {}) {
+            live();
+            const entry = find(REGISTRY.get, id);
+            if (!entry)
+                throw new OrbitError("board_not_found");
+            const files = await opened.get(id)?.catch(() => null);
+            const unlist = async () => {
+                const removed = [];
+                if (!options.keepData) {
+                    // The files go before the board leaves the list: a delete stopped by a
+                    // file another program holds leaves the board listed, to be deleted again.
+                    // This store lets go of them first, since an open handle keeps a file on Windows.
+                    files?.markRemoved();
+                    opened.delete(id);
+                    try {
+                        for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+                            const path = `${entry.db_path}${suffix}`;
+                            if (!existsSync(path))
+                                continue;
+                            rmSync(path, REMOVE_FILE);
+                            removed.push(path);
+                        }
+                    }
+                    catch (error) {
+                        throw filesBusy(error, entry.slug);
+                    }
+                }
+                const row = await registryWrite(() => regWriter.get(REGISTRY.remove, [id]));
+                if (!row)
+                    throw new OrbitError("board_not_found");
+                if (options.keepData) {
+                    files?.markRemoved();
+                    opened.delete(id);
+                    return { removed };
+                }
+                try {
+                    rmdirSync(join(boardsDir, String(row.folder)));
+                }
+                catch {
+                    // Its images and markdown are still there: the blob store's to remove.
+                }
+                return { removed };
+            };
+            return files ? files.exclusive(unlist) : unlist();
+        }
+    };
+    const settings = {
+        get(key) {
+            live();
+            const row = regReader.get(REGISTRY.setting, [key]);
+            return Promise.resolve(row ? String(row.value) : null);
+        },
+        async set(key, value) {
+            live();
+            await registryWrite(() => regWriter.run(REGISTRY.setSetting, [key, value]));
+        }
+    };
+    /** A board's folder: what this store has seen, else the registry's; null for a board it never had. */
+    const folderOf = (boardId) => {
+        if (!folders.has(boardId))
+            find(REGISTRY.get, boardId);
+        const folder = folders.get(boardId);
+        return folder === undefined ? null : join(boardsDir, folder);
+    };
+    return {
+        boards,
+        settings,
+        blobs: createSqliteBlobStore(folderOf),
+        backups: createSqliteBackups({
+            dataDir,
+            retention: options.backupRetention ?? 30,
+            busyMs,
+            now: options.now ?? (() => new Date()),
+            board(id) {
+                const entry = find(REGISTRY.get, id);
+                return entry ? { dbPath: entry.db_path, slug: entry.slug, name: entry.name } : null;
+            }
+        }),
+        async board(id) {
+            live();
+            const pending = opened.get(id);
+            const known = pending ? await pending.catch(() => null) : null;
+            if (known?.isLive())
+                return storeOf(known);
+            const entry = find(REGISTRY.get, id);
+            if (!entry)
+                throw new OrbitError("board_not_found");
+            return storeOf(await filesOf(entry));
+        },
+        async locate(kind, id, hint) {
+            live();
+            const order = listed().sort((a, b) => Number(b.id === hint) - Number(a.id === hint));
+            for (const entry of order) {
+                const files = await filesOf(entry);
+                if (files.query(`SELECT 1 AS here FROM ${TABLE_OF[kind]} WHERE id = ? LIMIT 1`, [id]).length > 0)
+                    return entry;
+            }
+            return null;
+        },
+        async relationsInto(boardId) {
+            live();
+            const found = [];
+            for (const entry of listed()) {
+                // A board whose file is gone (or won't open) links to nothing, as cross-board reads treat it: one such board never stops every other card's drawer.
+                const files = await filesOf(entry).catch((error) => {
+                    if (isOrbitError(error))
+                        return null;
+                    throw error;
+                });
+                if (!files)
+                    continue;
+                for (const row of files.query(`${CROSS.select} WHERE target_board_id = ? ORDER BY created_at, seq`, [boardId])) {
+                    found.push({ board_id: entry.id, relation: toRecord(CROSS, row, entry.id) });
+                }
+            }
+            return found;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            for (const pending of opened.values()) {
+                const files = await pending.catch(() => null);
+                await files?.close();
+            }
+            opened.clear();
+            await registryLock.run(() => {
+                regWriter.close();
+                regReader.close();
+                return Promise.resolve();
+            });
+        }
+    };
+}
+/** Windows refuses to remove a file another program has open, often only for a moment. */
+const REMOVE_FILE = process.platform === "win32" ? { force: true, maxRetries: 10, retryDelay: 100 } : { force: true };
+/** A file another program holds becomes `board_files_busy`, which says what to do; anything else is a storage fault. */
+function filesBusy(error, slug) {
+    const code = error?.code;
+    if (code !== "EBUSY" && code !== "EPERM" && code !== "ENOTEMPTY")
+        return new OrbitError("storage_failed", { cause: error });
+    return new OrbitError("board_files_busy", {
+        message: `Orbit couldn't remove the files of board "${slug}": another program has them open. On Windows that is usually an Orbit server, an MCP helper, an AI app, an editor or a terminal. Close it, then delete the board again from Settings.`,
+        cause: error
+    });
+}

package/lib/browser/in-page.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The browser edition: Orbit's own core in the page, over IndexedDB, with
+ * no server. `openBrowserOrbit()` opens the store, Orbit and its HTTP app,
+ * and gives a `fetch` that answers the JSON API in the page (app.fetch) and
+ * an OrbitClient over it. The web app sends its requests there as it would
+ * to `orbit run`; the event stream works the same way, through app.fetch.
+ *
+ * What a browser can't do stays off: agents (MCP), the folder picker,
+ * self-update. The version is the build's, with no check for a newer one.
+ */
+import type { OrbitClient } from "../client/types.ts";
+import type { OrbitApp } from "../http/app.ts";
+import type { Orbit } from "../orbit.ts";
+export interface BrowserOrbit {
+    orbit: Orbit;
+    app: OrbitApp;
+    /** The JSON API, answered in this page. */
+    fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    /** The OrbitClient over that fetch: images as object URLs, changes through the event stream. */
+    client: OrbitClient;
+    close(): Promise<void>;
+}
+export interface BrowserOrbitOptions {
+    /** The build's version, for Help and /api/version. */
+    version: string;
+    /** The IndexedDB database. Default: `orbit`. */
+    name?: string;
+    /** Make the welcome board when there are no boards. Default: true. */
+    seed?: boolean;
+}
+export declare function openBrowserOrbit(options: BrowserOrbitOptions): Promise<BrowserOrbit>;

package/lib/browser/in-page.js

@@ -0,0 +1,46 @@
+/// <reference lib="dom" />
+/**
+ * The browser edition: Orbit's own core in the page, over IndexedDB, with
+ * no server. `openBrowserOrbit()` opens the store, Orbit and its HTTP app,
+ * and gives a `fetch` that answers the JSON API in the page (app.fetch) and
+ * an OrbitClient over it. The web app sends its requests there as it would
+ * to `orbit run`; the event stream works the same way, through app.fetch.
+ *
+ * What a browser can't do stays off: agents (MCP), the folder picker,
+ * self-update. The version is the build's, with no check for a newer one.
+ */
+import { openIndexedDbStore } from "../adapters/indexeddb/index.js";
+import { createLocalLocks, webLocks } from "../adapters/indexeddb/locks.js";
+import { createHttpClient } from "../client/http.js";
+import { createOrbitApp } from "../http/app.js";
+import { createOrbit } from "../orbit.js";
+import { bringOldPreview } from "./old-preview.js";
+import { seedPreviewBoard } from "./preview-board.js";
+export async function openBrowserOrbit(options) {
+    const locks = webLocks() ?? createLocalLocks();
+    const store = await openIndexedDbStore({ locks, ...(options.name ? { name: options.name } : {}) });
+    const version = {
+        current: options.version,
+        deployMode: "browser",
+        selfUpdate: false,
+        repoUrl: "",
+        changesUrl: "",
+        enabled: false,
+        latest: null,
+        updateAvailable: false,
+        error: null,
+        checkedAt: null
+    };
+    const orbit = createOrbit({ store, blobs: store.blobs, host: { version: () => Promise.resolve(version) } });
+    const app = createOrbitApp(orbit, { version: options.version });
+    if (options.seed !== false) {
+        // The old preview's board first (once per origin), so a person who used it finds it instead of a welcome board.
+        await locks.request("orbit-browser-edition:seed", async () => {
+            await bringOldPreview(orbit).catch(() => null);
+        });
+        await seedPreviewBoard(orbit, locks);
+    }
+    const inPage = (input, init) => app.fetch(new Request(input, init));
+    const client = createHttpClient({ baseUrl: location.origin, fetch: inPage, images: "object" });
+    return { orbit, app, fetch: inPage, client, close: () => orbit.close() };
+}

package/lib/browser/old-preview.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The board of the old browser preview (1.x and 2.0 before its rebuild kept
+ * it in this origin's `starscape-orbit-preview` database), brought into the
+ * browser edition once, so a person who tried Orbit here finds their board.
+ * Its database is opened at the version it has and read in one read-only
+ * transaction, so it stays as it was. A board nobody changed (the preview's
+ * own welcome board, as it was made) isn't brought: the new edition has its
+ * own. Whatever happens, it is decided once per origin.
+ */
+import type { Orbit } from "../orbit.ts";
+export declare const OLD_PREVIEW_DB = "starscape-orbit-preview";
+/** Brings the old preview's board over, once per origin; says what it did (or null when it was decided before). */
+export declare function bringOldPreview(orbit: Orbit): Promise<string | null>;

package/lib/browser/old-preview.js

@@ -0,0 +1,80 @@
+/// <reference lib="dom" />
+/**
+ * The board of the old browser preview (1.x and 2.0 before its rebuild kept
+ * it in this origin's `starscape-orbit-preview` database), brought into the
+ * browser edition once, so a person who tried Orbit here finds their board.
+ * Its database is opened at the version it has and read in one read-only
+ * transaction, so it stays as it was. A board nobody changed (the preview's
+ * own welcome board, as it was made) isn't brought: the new edition has its
+ * own. Whatever happens, it is decided once per origin.
+ */
+import { localOwnerActor } from "../core/actors.js";
+import { OLD_PREVIEW_FORMAT, fromOldPreview, importKeepingBoard } from "../core/snapshots.js";
+export const OLD_PREVIEW_DB = "starscape-orbit-preview";
+const DONE = "old_preview";
+const STORES = ["boards", "states", "labels", "tickets", "ticket_labels", "comments", "relations", "board_entries", "events"];
+/** The old database's stores, read whole; null when this origin has none. */
+async function readOldPreview() {
+    if (typeof indexedDB === "undefined" || typeof indexedDB.databases !== "function")
+        return null;
+    // Opening a database that isn't there would make it: look first.
+    if (!(await indexedDB.databases()).some((db) => db.name === OLD_PREVIEW_DB))
+        return null;
+    const db = await new Promise((resolve, reject) => {
+        const request = indexedDB.open(OLD_PREVIEW_DB);
+        request.onsuccess = () => {
+            resolve(request.result);
+        };
+        request.onerror = () => {
+            reject(request.error ?? new Error("The old preview's database didn't open."));
+        };
+    });
+    try {
+        const names = STORES.filter((name) => db.objectStoreNames.contains(name));
+        if (!names.length)
+            return null;
+        const tx = db.transaction(names, "readonly");
+        const read = await Promise.all(names.map((name) => new Promise((resolve, reject) => {
+            const request = tx.objectStore(name).getAll();
+            request.onsuccess = () => {
+                resolve([name, request.result]);
+            };
+            request.onerror = () => {
+                reject(request.error ?? new Error(`The old preview's ${name} didn't read.`));
+            };
+        })));
+        return Object.fromEntries(read);
+    }
+    finally {
+        db.close();
+    }
+}
+/** True when a person changed the board after the preview made it: any record newer than the board. */
+function changedByAPerson(stores, board) {
+    const made = typeof board.created_at === "string" ? board.created_at : "";
+    if ((stores.events ?? []).length)
+        return true;
+    return STORES.some((name) => (stores[name] ?? []).some((row) => [row.created_at, row.updated_at, row.struck_at, row.archived_at].some((at) => typeof at === "string" && at > made)));
+}
+/** Brings the old preview's board over, once per origin; says what it did (or null when it was decided before). */
+export async function bringOldPreview(orbit) {
+    const c = orbit.context(localOwnerActor());
+    if (await c.store.settings.get(DONE))
+        return null;
+    const stores = await readOldPreview().catch(() => null);
+    const board = stores?.boards?.[0];
+    let outcome = "none";
+    if (stores && board && changedByAPerson(stores, board)) {
+        let slug = typeof board.slug === "string" && board.slug ? board.slug : "preview";
+        for (let i = 2; await c.store.boards.bySlug(slug); i += 1)
+            slug = `${typeof board.slug === "string" && board.slug ? board.slug : "preview"}-${i}`;
+        const id = typeof board.id === "string" && board.id && !(await c.store.boards.get(board.id)) ? board.id : c.ids.next();
+        await importKeepingBoard(c, fromOldPreview({ schema: OLD_PREVIEW_FORMAT, board, ...stores }), { id, slug });
+        outcome = `brought:${slug}`;
+    }
+    else if (stores && board) {
+        outcome = "unchanged";
+    }
+    await c.store.settings.set(DONE, JSON.stringify({ outcome, at: c.clock.now() }));
+    return outcome;
+}

package/lib/browser/preview-board.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The board a newcomer finds in the browser edition: lanes, a few cards
+ * that show the way around, and a note. Made once, through the core, by
+ * whichever tab gets there first.
+ */
+import type { Locks } from "../adapters/indexeddb/locks.ts";
+import type { Orbit } from "../orbit.ts";
+export declare function seedPreviewBoard(orbit: Orbit, locks: Locks): Promise<void>;

package/lib/browser/preview-board.js

@@ -0,0 +1,69 @@
+/**
+ * The board a newcomer finds in the browser edition: lanes, a few cards
+ * that show the way around, and a note. Made once, through the core, by
+ * whichever tab gets there first.
+ */
+import { localOwnerActor } from "../core/actors.js";
+const LANES = [
+    ["Backlog", null],
+    ["Todo", null],
+    ["In Progress", "in_progress"],
+    ["Review", "review"],
+    ["Done", "done"],
+    ["Cancelled", null]
+];
+export async function seedPreviewBoard(orbit, locks) {
+    const client = orbit.client({ ...localOwnerActor(), id: "system", name: "system" });
+    await locks.request("orbit-browser-edition:seed", async () => {
+        if ((await client.boards.list()).boards.length)
+            return;
+        const board = await client.boards.create({ name: "Preview Board", slug: "preview", ai_enabled: false, states: LANES });
+        await client.boards.update(board.slug, {
+            project_notes: "This preview lives entirely in your browser (IndexedDB). Use it to try the flow; export the snapshot from Settings → Data when you want to move to a real Orbit install.",
+            agent_instructions: "Preview edition has no agent or MCP integration. Install the full Orbit app with npm i -g @starlove/orbit, then run orbit run and create or import a board."
+        });
+        const hint = { board_id: board.id };
+        const lanes = (await client.bootstrap(hint)).states;
+        const lane = (name) => lanes.find((state) => state.name === name)?.id;
+        const epic = await client.tickets.create({
+            ...hint,
+            title: "Try the preview kanban",
+            description: "This onboarding card is for the in-browser preview. Drag it across lanes, edit fields, add comments: it all stays in this browser only.",
+            type: "epic",
+            ai_plan: "1. Drag this card to In Progress.\n2. Add a comment.\n3. Export the snapshot from Settings → Data.",
+            state_id: lane("Todo"),
+            priority: 4,
+            labels: ["onboarding", "needs-decomposition"]
+        });
+        await client.tickets.create({
+            ...hint,
+            title: "Edit a card and watch it persist",
+            description: "Click into a card, change its title, refresh: your edit survives because it lives in IndexedDB.",
+            type: "feature",
+            parent_ticket_id: epic.id,
+            state_id: lane("Todo"),
+            priority: 3,
+            labels: ["onboarding"]
+        });
+        await client.tickets.create({
+            ...hint,
+            title: "Move me to In Progress",
+            description: "Drag this card to the In Progress lane, then to Review.",
+            type: "task",
+            parent_ticket_id: epic.id,
+            state_id: lane("Backlog"),
+            priority: 2,
+            labels: ["onboarding"]
+        });
+        await client.tickets.create({
+            ...hint,
+            title: "Export your snapshot when ready",
+            description: "Settings → Data → Export downloads a JSON snapshot you can import into a real Orbit install.",
+            type: "task",
+            state_id: lane("Backlog"),
+            priority: 1,
+            labels: ["onboarding"]
+        });
+        await client.comments.create(epic.id, { body: "Welcome to the Orbit preview. Everything lives in your browser.", kind: "note" }, hint);
+    });
+}

package/lib/cli/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+import "../quiet-sqlite-warning.ts";