@starlove/orbit 1.4.1 → 2.0.0

package/lib/node/local.js

@@ -0,0 +1,61 @@
+/**
+ * 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 { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { openSqliteStore } from "../adapters/sqlite/index.js";
+import { createOrbit } from "../orbit.js";
+import { makeDefaultDataDir, olderDataWaiting } from "./data-folder.js";
+import { PACKAGE_ROOT } from "./package.js";
+export { PACKAGE_ROOT, packageVersion } from "./package.js";
+/** 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 const MCP_SERVER_PATH = fileURLToPath(new URL("../mcp-server.js", import.meta.url));
+/** Where the app's files are: dist/full, which an install ships and a checkout builds (`node build.mjs`). */
+export function publicDir() {
+    return join(PACKAGE_ROOT, "dist", "full");
+}
+/** Opens the data folder (refusing one of older data with `data_needs_migration`) and Orbit over it. */
+export async function openLocalOrbit(env, options = {}) {
+    makeDefaultDataDir(env);
+    const store = await openSqliteStore({ dataDir: env.dataDir, backupRetention: env.backups.retention });
+    const timers = new Map();
+    const changed = (boardId) => {
+        if (!env.backups.enabled)
+            return;
+        const pending = timers.get(boardId);
+        if (pending)
+            clearTimeout(pending);
+        const timer = setTimeout(() => {
+            timers.delete(boardId);
+            void (async () => {
+                try {
+                    await store.backups.board(boardId, "auto-write", { oncePerDay: true });
+                    await store.backups.directory("auto-write", { oncePerDay: true });
+                }
+                catch (error) {
+                    console.warn(`[orbit] Automatic write backup failed for board ${boardId}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            })();
+        }, env.backups.delayMs);
+        timer.unref();
+        timers.set(boardId, timer);
+    };
+    const orbit = createOrbit({
+        store,
+        blobs: store.blobs,
+        changed,
+        ...(options.host ? { host: options.host } : {}),
+        deployment: { app_root: PACKAGE_ROOT, data_dir: env.dataDir, data_dir_default: env.dataDirIsDefault, mcp_server_path: MCP_SERVER_PATH, export_dir: join(env.dataDir, "exports"), older_data: olderDataWaiting(env) }
+    });
+    return {
+        orbit,
+        async close() {
+            for (const timer of timers.values())
+                clearTimeout(timer);
+            timers.clear();
+            await store.close();
+        }
+    };
+}

package/lib/node/migrate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `orbit migrate`: an older Orbit's boards (1.x, or 2.0 before its rebuild)
+ * brought into a new data folder of this one. The source is a data folder or
+ * board exports; it is only ever read: its files are copied to a temporary
+ * folder first and opened there, so not even SQLite's own files beside them
+ * change. Each board keeps its id, its slug and every record's id, and is
+ * checked against its source after it is written: the counts, the ids and a
+ * hash of each kind of record, its images' and markdown files' bytes too.
+ * What can't come (a link to a file outside Orbit's folder, a board whose
+ * file is gone) is said in the report, never dropped quietly. The new folder
+ * is built beside its final name and moved into place once every board is
+ * in, so a run that stops leaves nothing half made under that name; a second
+ * run finds the boards there and changes nothing, and a folder holding other
+ * boards is refused.
+ */
+import type { Id } from "../core/model.ts";
+export interface BoardReport {
+    slug: string;
+    id: Id;
+    from: string;
+    counts: Record<string, number>;
+    /** Each kind of record whose count, ids and content match its source. */
+    matched: string[];
+    /** What didn't come over as it was, in plain words. */
+    notes: string[];
+    /** Images kept as files to download only: an SVG, or bytes that aren't an image type Orbit shows. */
+    images_kept_as_downloads: number;
+    /** Files that weren't read: not plain files where the board keeps them (a symlink, say), or an image whose path leaves its attachments. */
+    refused_files: number;
+    /** The project folder 1.x used this board for, as its registry named it; v2 stores none, so the report says where to link it. */
+    folder_1x?: string;
+}
+export interface MigrationReport {
+    to: string;
+    /** True when every board was already in the folder: nothing was written. */
+    already: boolean;
+    boards: BoardReport[];
+    /** About the sources as a whole (a board whose file is gone, an unreadable file). */
+    notes: string[];
+}
+export interface MigrateOptions {
+    /** Data folders and export files of an older Orbit. */
+    sources: readonly string[];
+    /** The new data folder: absent or empty, Orbit's own holding no board yet, or one an earlier run made from the same sources. */
+    to: string;
+    /**
+     * `to` is Orbit's own folder, filled as `orbit migrate` with no folder named
+     * does: it may hold boards already, and the old ones join them when none
+     * has the same slug or id there. All or nothing.
+     */
+    fill?: boolean;
+}
+export declare function migrate(options: MigrateOptions): Promise<MigrationReport>;