@starlove/orbit 1.4.0 → 2.0.0

package/lib/node/migrate.js

@@ -0,0 +1,635 @@
+/**
+ * `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 { createHash } from "node:crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { openSqliteStore } from "../adapters/sqlite/index.js";
+import { checkFile } from "../adapters/sqlite/database.js";
+import { localOwnerActor } from "../core/actors.js";
+import { ARTIFACTS, cardLinkFromElsewhere } from "../core/card-paths.js";
+import { onBoard } from "../core/context.js";
+import { OrbitError, isOrbitError } from "../core/errors.js";
+import { parseNebulaUrl } from "../core/nebula-link.js";
+import { EXPORT_FORMAT, OLD_PREVIEW_FORMAT, exportBoard, fromOldPreview, importKeepingBoard, keptLabelColor } from "../core/snapshots.js";
+import { storedImageType } from "../core/files.js";
+import { cleanName, isSlug, normalizeEntryType, normalizePriority, normalizeTicketType, slugify } from "../core/text.js";
+import { createOrbit } from "../orbit.js";
+const KINDS = ["states", "labels", "tickets", "comments", "review_verdicts", "relations", "attachments", "board_entries", "events"];
+const text = (value) => (typeof value === "string" ? value : typeof value === "number" || typeof value === "bigint" || typeof value === "boolean" ? String(value) : "");
+// ------------------------------------------------------------------ reading a folder
+/**
+ * The real path of `path` when it is a plain file inside `root` (both read
+ * through any links), else null: a symlink, a folder or a device is never
+ * read, wherever it points.
+ */
+function plainFileInside(root, path) {
+    try {
+        if (!lstatSync(path).isFile())
+            return null;
+        const real = realpathSync(path);
+        return inside(realpathSync(root), real) !== null ? real : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Copies a database and the journal files beside it to `into` as
+ * `board.db`, and opens the copy. Each must be a plain file inside `root`;
+ * null when the database isn't, or a journal beside it is something else.
+ */
+function openCopy(root, path, into) {
+    if (!plainFileInside(root, path))
+        return null;
+    const journals = ["-wal", "-shm"].filter((suffix) => existsOrLink(path + suffix));
+    if (journals.some((suffix) => !plainFileInside(root, path + suffix)))
+        return null;
+    mkdirSync(into, { recursive: true });
+    for (const suffix of ["", ...journals])
+        copyFileSync(path + suffix, join(into, `board.db${suffix}`));
+    return new DatabaseSync(join(into, "board.db"));
+}
+/**
+ * A 1.x board kept in a repo, as 1.x's registry can name one: a plain file
+ * (`lstat`) named `board.db`, judged by its real path, directly in a folder
+ * named `.orbit` (`<repo>/.orbit/board.db`), or, for a repo's later boards
+ * in 1.0, in `<repo>/.orbit/boards/<slug>/`. The `.orbit` folder's real
+ * path, which then stands in for the old folder for this board's files, and
+ * the file's real path; or null. A registry can name any path, but this way
+ * it can only bring another of the same person's boards.
+ */
+function repoBoard(path) {
+    try {
+        if (!lstatSync(path).isFile())
+            return null;
+        const real = realpathSync(path);
+        if (basename(real) !== "board.db")
+            return null;
+        const folder = dirname(real);
+        if (basename(folder) === ".orbit")
+            return { root: folder, path: real };
+        const orbitFolder = dirname(dirname(folder));
+        const later = isSlug(basename(folder)) && basename(dirname(folder)) === "boards" && basename(orbitFolder) === ".orbit";
+        return later ? { root: orbitFolder, path: real } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when anything is at `path`, a dangling link included. */
+function existsOrLink(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tableRows(db, table) {
+    const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+    return exists ? db.prepare(`SELECT * FROM ${table}`).all() : [];
+}
+/** Every plain file under `dir`, by its path inside it, and how many entries weren't plain files or folders (links). */
+function filesUnder(dir) {
+    const out = new Map();
+    let refused = 0;
+    if (!existsSync(dir) || !lstatSync(dir).isDirectory())
+        return { files: out, refused: existsOrLink(dir) ? 1 : 0 };
+    const walk = (at) => {
+        for (const entry of readdirSync(at, { withFileTypes: true })) {
+            const path = join(at, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else if (entry.isFile())
+                out.set(relative(dir, path).split(sep).join("/"), readFileSync(path));
+            else
+                refused += 1;
+        }
+    };
+    walk(dir);
+    return { files: out, refused };
+}
+const inside = (root, path) => {
+    const rel = relative(root, path);
+    return rel && !rel.startsWith("..") && !rel.startsWith(sep) && rel !== path ? rel.split(sep).join("/") : null;
+};
+/**
+ * A card's link to markdown, as v2 keeps it: relative to the board's
+ * artifacts. A full path into the old board's artifacts keeps its part
+ * inside them; one into the old folder's dispatch runs (1.x) brings that
+ * file along under `dispatch-runs/`; anything else names a file this Orbit
+ * can't reach, so the link is left empty and said.
+ */
+function linkFor(source, oldData, boardDir, card, field) {
+    const value = text(card[field]);
+    if (!value || !/^([a-z]:)?[\\/]/i.test(value))
+        return;
+    const path = value.replace(/\\/g, "/");
+    const label = field === "plan_artifact_path" ? "plan link" : "work summary link";
+    const inArtifacts = boardDir ? inside(join(boardDir, "artifacts"), path) : null;
+    if (inArtifacts) {
+        card[field] = inArtifacts;
+        return;
+    }
+    const inRuns = oldData ? inside(join(oldData, "dispatch-runs"), path) : null;
+    const real = oldData && inRuns ? plainFileInside(oldData, path) : null;
+    if (inRuns && existsOrLink(path) && !real)
+        source.refused += 1;
+    if (inRuns && real) {
+        const kept = `dispatch-runs/${inRuns}`;
+        source.files.set(kept, readFileSync(real));
+        card[field] = kept;
+        return;
+    }
+    const fromExport = boardDir === null ? cardLinkFromElsewhere(value) : null;
+    if (fromExport) {
+        card[field] = fromExport;
+        return;
+    }
+    card[field] = "";
+    source.notes.push(`#${text(card.number)}'s ${label} named a file ${boardDir === null ? "the export doesn't carry" : "outside Orbit's folder"} (${value}); it is left empty.`);
+}
+/**
+ * Why an image's file wasn't read, in plain words, or null when it is just
+ * missing. `place` names the folder the board was read against (the old
+ * folder, or a repo board's `.orbit` folder).
+ */
+function imageRefusal(stored, path, escapes, place) {
+    if (escapes)
+        return `names a path outside its board's attachments (${stored})`;
+    let entry;
+    try {
+        entry = lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+    if (entry.isSymbolicLink())
+        return "is a link, not a plain file";
+    if (!entry.isFile())
+        return "isn't a plain file";
+    return `is reached through a link out of ${place}`;
+}
+/** One board's database (a copy of it), read as an export. */
+function readBoardFile(db, files, root, attachmentsDir, place) {
+    const board = tableRows(db, "boards")[0] ?? {};
+    const labelsOf = new Map();
+    const labels = tableRows(db, "labels");
+    const labelById = new Map(labels.map((label) => [text(label.id), label]));
+    for (const link of tableRows(db, "ticket_labels")) {
+        const label = labelById.get(text(link.label_id));
+        if (label)
+            labelsOf.set(text(link.ticket_id), [...(labelsOf.get(text(link.ticket_id)) ?? []), label]);
+    }
+    const missingImages = [];
+    const refusedImages = [];
+    const attachments = tableRows(db, "ticket_attachments").map((row) => {
+        const stored = text(row.stored_path);
+        const path = join(attachmentsDir, stored);
+        const escapes = inside(attachmentsDir, path) === null;
+        const real = escapes ? null : plainFileInside(root, path);
+        const name = text(row.original_name) || text(row.id);
+        const refusal = real ? null : imageRefusal(stored, path, escapes, place);
+        if (refusal)
+            refusedImages.push(`The image ${name} ${refusal}, so it wasn't read; its card has no copy of it.`);
+        else if (!real)
+            missingImages.push(`The image ${name} wasn't in ${place}; its card has no copy of it.`);
+        return { ...row, data_base64: real ? readFileSync(real).toString("base64") : null, included: Boolean(real) };
+    });
+    const snapshot = {
+        format: EXPORT_FORMAT,
+        board,
+        states: tableRows(db, "states"),
+        labels,
+        tickets: tableRows(db, "tickets").map((ticket) => ({ ...ticket, labels: labelsOf.get(text(ticket.id)) ?? [] })),
+        comments: tableRows(db, "comments"),
+        review_verdicts: tableRows(db, "review_verdicts"),
+        relations: tableRows(db, "relations"),
+        attachments,
+        board_entries: tableRows(db, "board_entries"),
+        events: tableRows(db, "events")
+    };
+    return { id: text(board.id), slug: text(board.slug), snapshot, files, missingImages, refusedImages };
+}
+const HOW_TO_BRING = "To bring it, export it from Orbit 1.x or 2.0 (npx @starlove/orbit@1, or the 2.0 you had) and name the export beside the old folder: orbit migrate <old folder> <export> --to <new folder>.";
+/** Why none of a board's files that are there was read, in plain words. */
+function refusedReason(folder, present) {
+    const path = present[0] ?? "";
+    if (lstatSync(path).isSymbolicLink())
+        return `its file (${path}) is a link, not a plain file, so it wasn't read.`;
+    if (!lstatSync(path).isFile())
+        return `its registry names ${path}, which isn't a file.`;
+    const real = realpathSync(path);
+    if (inside(resolve(folder), path) !== null)
+        return `its file is reached through a link out of the old folder (it is really ${real}), so it wasn't read.`;
+    if (real !== resolve(path))
+        return `its registry names ${path}, which is reached through a link to ${real}, and that isn't a repo's .orbit/board.db, so it wasn't read.`;
+    return `its registry names a file outside the old folder (${path}) that isn't a repo's .orbit/board.db, so it wasn't read.`;
+}
+/** Why a board whose file isn't there wasn't brought: a path that can't be reached says why, one outside the folder says so. */
+function goneReason(folder, candidates, named) {
+    for (const candidate of candidates) {
+        try {
+            lstatSync(candidate);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT")
+                continue;
+            const why = code === "ELOOP" ? "its path goes round a loop of links" : code === "ENOTDIR" ? "a part of its path isn't a folder" : code === "EACCES" || code === "EPERM" ? "Orbit isn't allowed to read it" : `the system said ${code ?? "no"}`;
+            return `its registry names ${candidate}, which can't be reached (${why}), so it wasn't read.`;
+        }
+    }
+    const outside = named !== "" && inside(resolve(folder), resolve(folder, named)) === null;
+    if (outside)
+        return `its file isn't where its registry says (${cleanName(named)}).`;
+    return `its file is gone from the old folder${named ? ` (its registry names ${cleanName(named)})` : ""}.`;
+}
+/**
+ * An older Orbit's data folder: each board in its registry, read from a
+ * copy. Only plain files are read: a board's file is found under
+ * `boards/<slug>/` (when its slug is one) or where its registry row says,
+ * when that is inside the folder or is a 1.x repo board's file in
+ * `<repo>/.orbit/` (`repoBoard`), whose own folder then holds
+ * its images and markdown files. Copies are named by their place in the
+ * registry, never by anything the folder says.
+ */
+function readFolder(folder, scratch, notes) {
+    const registryPath = join(folder, "registry.db");
+    try {
+        if (checkFile(registryPath))
+            throw new OrbitError("migration_source_unreadable", { message: `${folder} is already this Orbit's data folder: point DATA_DIR at it.` });
+    }
+    catch (error) {
+        if (!isOrbitError(error) || error.code !== "data_needs_migration")
+            throw error;
+    }
+    const registry = openCopy(folder, registryPath, join(scratch, "registry"));
+    if (!registry)
+        throw new OrbitError("migration_source_unreadable", { message: `${registryPath} isn't a plain file inside ${folder}, so it wasn't read.` });
+    const rows = tableRows(registry, "boards");
+    registry.close();
+    const boards = [];
+    for (const [n, row] of rows.entries()) {
+        const slug = text(row.slug);
+        const label = cleanName(slug) || cleanName(row.name) || `#${String(n + 1)}`;
+        // 1.4 and 2.0 keep every board under boards/<slug>; 1.x's registry may name a repo's .orbit/board.db.
+        const named = text(row.db_path);
+        const candidates = [isSlug(slug) ? join(folder, "boards", slug, "board.db") : "", named ? resolve(folder, named) : ""].filter(Boolean);
+        const present = candidates.filter(existsOrLink);
+        const inFolder = present.find((candidate) => plainFileInside(folder, candidate));
+        const repo = inFolder ? null : present.map(repoBoard).find((found) => found !== null) ?? null;
+        const path = inFolder ?? repo?.path ?? null;
+        const root = repo?.root ?? folder;
+        if (!path) {
+            notes.push(present.length ? `The board ${label} wasn't brought: ${refusedReason(folder, present)} ${HOW_TO_BRING}` : `The board ${label} (${cleanName(row.name)}) wasn't brought: ${goneReason(folder, candidates, named)} ${HOW_TO_BRING}`);
+            continue;
+        }
+        const boardDir = dirname(path);
+        const db = openCopy(root, path, join(scratch, "boards", String(n)));
+        if (!db) {
+            notes.push(`The board ${label} wasn't brought: a file beside its database (its -wal or -shm) is a link or not a plain file, so it wasn't read. Put the file itself in the link's place and run this again.`);
+            continue;
+        }
+        const artifacts = filesUnder(join(boardDir, "artifacts"));
+        let read;
+        try {
+            read = readBoardFile(db, artifacts.files, root, join(boardDir, "attachments"), repo ? `its .orbit folder (${repo.root})` : "the old folder");
+        }
+        catch {
+            notes.push(`The board ${label} wasn't brought: its file isn't a board database Orbit can read.`);
+            continue;
+        }
+        finally {
+            db.close();
+        }
+        const source = {
+            ...read,
+            from: path,
+            refused: artifacts.refused + read.refusedImages.length,
+            notes: [
+                ...read.missingImages,
+                ...read.refusedImages
+            ]
+        };
+        if (repo)
+            source.notes.push(`It was a board kept in a repo, read from ${path} (nothing there was changed).`);
+        if (artifacts.refused)
+            source.notes.push(`${String(artifacts.refused)} ${artifacts.refused === 1 ? "entry under its markdown files wasn't a plain file (a link), so it wasn't" : "entries under its markdown files weren't plain files (links), so they weren't"} read.`);
+        const folder1x = cleanName(row.repo_path);
+        if (folder1x)
+            source.folder1x = folder1x;
+        for (const card of source.snapshot.tickets) {
+            linkFor(source, folder, boardDir, card, "plan_artifact_path");
+            linkFor(source, folder, boardDir, card, "implementation_artifact_path");
+        }
+        boards.push(source);
+    }
+    return boards;
+}
+// ------------------------------------------------------------------ reading an export
+function readExport(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new OrbitError("migration_source_unreadable", { message: `${path} isn't a data folder or a board's export.` });
+    }
+    const row = raw && typeof raw === "object" ? raw : {};
+    const shaped = row.schema === OLD_PREVIEW_FORMAT ? fromOldPreview(row) : row;
+    const board = shaped.board && typeof shaped.board === "object" ? shaped.board : null;
+    if (shaped.format !== EXPORT_FORMAT || !board || !text(board.id) || !text(board.slug))
+        throw new OrbitError("migration_source_unreadable", { message: `${path} isn't a board's export from Orbit.` });
+    const snapshot = { ...shaped, board, tickets: (shaped.tickets ?? []).map((ticket) => ({ ...ticket })) };
+    const source = { id: text(board.id), slug: text(board.slug), from: path, snapshot, files: new Map(), notes: [], refused: 0 };
+    const images = (shaped.attachments ?? []).filter((image) => !image.data_base64).length;
+    if (images)
+        source.notes.push(`${images} image${images === 1 ? "" : "s"} came without their bytes (the export was made without images); the cards keep their names only.`);
+    for (const card of snapshot.tickets) {
+        linkFor(source, null, null, card, "plan_artifact_path");
+        linkFor(source, null, null, card, "implementation_artifact_path");
+    }
+    if (snapshot.tickets.some((card) => text(card.plan_artifact_path) || text(card.implementation_artifact_path)))
+        source.notes.push("An export carries no markdown files: cards' plan and work summary links name files this folder doesn't have.");
+    return source;
+}
+// ------------------------------------------------------------------ checking
+const sha = (value) => createHash("sha256").update(typeof value === "string" || value instanceof Uint8Array ? value : JSON.stringify(value)).digest("hex");
+/** The fields each kind of record must bring unchanged, as v2 keeps them. */
+function projected(kind, row) {
+    const at = (...keys) => Object.fromEntries(keys.map((key) => [key, row[key] ?? null]));
+    switch (kind) {
+        case "states":
+            return { ...at("id", "position", "role", "created_at"), name: cleanName(row.name) || "Lane", is_default: Number(row.is_default ?? 0) };
+        case "labels":
+            return { ...at("id", "name", "created_at"), color: keptLabelColor(row.color) };
+        case "tickets":
+            return {
+                ...at("id", "number", "title", "description", "parent_ticket_id", "ai_plan", "implementation_summary", "implementation_updates", "state_id", "created_at", "updated_at", "archived_at"),
+                type: normalizeTicketType(row.type ?? "task"),
+                priority: normalizePriority(row.priority),
+                plan_artifact_path: cardLinkFromElsewhere(row.plan_artifact_path) ?? "",
+                implementation_artifact_path: cardLinkFromElsewhere(row.implementation_artifact_path) ?? "",
+                nebula_url: parseNebulaUrl(row.nebula_url) ?? "",
+                labels: (row.labels ?? []).map((label) => text(label.id)).sort()
+            };
+        case "comments":
+            return { ...at("id", "ticket_id", "body", "created_at"), author: row.author ?? "import", kind: row.kind ?? "comment", omitted_for_ai: Number(row.omitted_for_ai ?? 0) };
+        case "review_verdicts":
+            return at("id", "ticket_id", "verdict", "blocking_findings_json", "optional_findings_json", "evidence_commands_json", "reviewer_profile", "reviewed_commit_sha", "created_at");
+        case "relations":
+            return { ...at("id", "source_ticket_id", "target_ticket_id", "created_at"), type: row.type ?? "relates_to" };
+        case "attachments":
+            // Stored as its bytes say (an SVG as a download only), on both sides.
+            return { ...at("id", "ticket_id", "original_name", "size_bytes", "sha256", "created_at"), mime_type: storedImageType(row.mime_type || "image/png", typeof row.data_base64 === "string" && row.data_base64 ? Buffer.from(row.data_base64, "base64") : null) };
+        case "board_entries":
+            return { ...at("id", "title", "body", "ticket_id", "created_at", "updated_at", "struck_at"), type: normalizeEntryType(row.type) };
+        case "events":
+            return at("id", "ticket_id", "actor", "type", "body_json", "created_at");
+    }
+}
+function fingerprint(kind, rows) {
+    const hashes = new Map();
+    for (const row of rows)
+        hashes.set(text(row.id), sha(projected(kind, row)));
+    return { ids: [...hashes.keys()].sort(), hashes };
+}
+/** The board as written, against its source: per kind, its count, ids and content; then its markdown files. */
+async function check(c, source, boardId) {
+    const row = await c.store.boards.get(boardId);
+    if (!row)
+        throw new OrbitError("storage_failed", { message: `The board ${source.slug} wasn't written.` });
+    const bc = await onBoard(c, row);
+    const written = (await exportBoard(bc, { includeAttachments: true }));
+    const report = { slug: row.slug, id: row.id, from: source.from, counts: {}, matched: [], notes: [...source.notes], images_kept_as_downloads: 0, refused_files: source.refused, ...(source.folder1x ? { folder_1x: source.folder1x } : {}) };
+    for (const kind of KINDS) {
+        const want = fingerprint(kind, source.snapshot[kind] ?? []);
+        const got = fingerprint(kind, written[kind] ?? []);
+        report.counts[kind] = got.ids.length;
+        const missing = want.ids.filter((id) => !got.hashes.has(id));
+        const changed = want.ids.filter((id) => got.hashes.has(id) && got.hashes.get(id) !== want.hashes.get(id));
+        const extra = got.ids.filter((id) => !want.hashes.has(id));
+        if (!missing.length && !changed.length && !extra.length)
+            report.matched.push(kind);
+        else
+            report.notes.push(`${kind.replace(/_/g, " ")}: ${[missing.length ? `${missing.length} not brought (${missing.slice(0, 5).join(", ")})` : "", changed.length ? `${changed.length} changed (${changed.slice(0, 5).join(", ")})` : "", extra.length ? `${extra.length} more than the source` : ""].filter(Boolean).join("; ")}.`);
+    }
+    // Images: the bytes each record names are the bytes stored.
+    for (const image of written.attachments ?? []) {
+        if (image.download_only)
+            report.images_kept_as_downloads += 1;
+        if (image.data_base64 && sha(Buffer.from(text(image.data_base64), "base64")) !== text(image.sha256))
+            report.notes.push(`The image ${text(image.original_name)}'s bytes don't match its record.`);
+    }
+    let files = 0;
+    for (const [path, bytes] of source.files) {
+        const stored = await c.blobs.get(boardId, ARTIFACTS + path);
+        if (stored && sha(stored) === sha(bytes))
+            files += 1;
+        else
+            report.notes.push(`The markdown file ${path} didn't come over.`);
+    }
+    report.counts.markdown_files = files;
+    if (files === source.files.size)
+        report.matched.push("markdown_files");
+    if (report.images_kept_as_downloads)
+        report.notes.push(`${String(report.images_kept_as_downloads)} image${report.images_kept_as_downloads === 1 ? " is" : "s are"} kept as a file to download only (an SVG, or bytes that aren't a PNG, JPEG, GIF, WebP or AVIF image).`);
+    return report;
+}
+// ------------------------------------------------------------------ the run
+function isEmptyDir(path) {
+    if (!existsOrLink(path))
+        return true;
+    const stat = lstatSync(path);
+    return stat.isDirectory() && readdirSync(path).length === 0;
+}
+/** Opens Orbit over a data folder of v2's, as the owner. */
+async function openTarget(dataDir) {
+    const store = await openSqliteStore({ dataDir });
+    const orbit = createOrbit({ store, blobs: store.blobs, deployment: { data_dir: dataDir } });
+    return { c: orbit.context(localOwnerActor()), close: () => store.close() };
+}
+/** The old boards that a board already in the target would collide with, by slug or id. */
+async function clashes(c, boards) {
+    const held = await c.store.boards.list();
+    const found = [];
+    for (const old of boards) {
+        const row = held.find((board) => board.id === old.id || board.slug === old.slug);
+        if (!row)
+            continue;
+        const cards = (await (await onBoard(c, row)).data.read((r) => r.tickets.list())).length;
+        found.push({ old, here: { slug: row.slug, id: row.id, cards } });
+    }
+    return found;
+}
+/** The refusal when old boards collide with boards here: each one with its cards on both sides, then what to run. */
+function clashText(to, found) {
+    const cards = (n) => `${String(n)} card${n === 1 ? "" : "s"}`;
+    const one = found.length === 1;
+    const lines = [`Nothing was changed: ${to} already holds ${one ? "a board" : "boards"} the older Orbit also has.`];
+    for (const { old, here } of found) {
+        const there = cards(old.snapshot.tickets.length);
+        lines.push(here.slug === old.slug ? `  ${here.slug}: ${cards(here.cards)} here, ${there} in the older Orbit.` : `  ${here.slug}: ${cards(here.cards)} here; it is the older Orbit's ${old.slug} (the same board), with ${there} there.`);
+    }
+    const names = found.map((clash) => clash.here.slug);
+    const listed = one ? (names[0] ?? "") : `${names.slice(0, -1).join(", ")} and ${names.at(-1) ?? ""}`;
+    lines.push(`If ${listed} here ${one ? "holds" : "hold"} nothing you need, delete ${one ? "it" : "them"} in the app (Settings, Data, Delete board) and run \`orbit migrate\` again. Or bring the old boards to another folder: \`orbit migrate --to <folder>\`.`);
+    return lines.join("\n");
+}
+/** `path` with every link resolved, for a path that may not exist yet: its nearest existing folder's real path, then the rest. */
+function realPathOf(path) {
+    const rest = [];
+    let at = resolve(path);
+    for (;;) {
+        try {
+            return join(realpathSync(at), ...rest.reverse());
+        }
+        catch {
+            const up = dirname(at);
+            if (up === at)
+                return resolve(path);
+            rest.push(basename(at));
+            at = up;
+        }
+    }
+}
+/**
+ * A source's slug as v2 keeps it. An old registry or an export may say
+ * anything, so a slug that isn't one (a path, a line break) is made one, and
+ * the report says so.
+ */
+function keptSlug(source, n) {
+    if (isSlug(source.slug))
+        return;
+    const made = slugify(source.slug) || `board-${String(n + 1)}`;
+    source.notes.push(`Its slug in the old data wasn't one Orbit keeps (${JSON.stringify(cleanName(source.slug).slice(0, 80))}); it is ${made} here.`);
+    source.slug = made;
+}
+/** One board into the target, with its markdown files, then checked against its source. */
+async function bring(c, board) {
+    const { board: row, crossDropped } = await importKeepingBoard(c, board.snapshot, { id: board.id, slug: board.slug });
+    if (crossDropped)
+        board.notes.push(`${String(crossDropped)} link${crossDropped === 1 ? "" : "s"} to cards on other boards didn't come: the other cards aren't in this folder.`);
+    for (const [path, bytes] of board.files)
+        await c.blobs.put(row.id, ARTIFACTS + path, bytes);
+    return check(c, board, row.id);
+}
+/** Every board into a folder that held none; when one fails, the boards this run made are removed and the error rethrown. */
+async function bringInPlace(c, boards) {
+    const reports = [];
+    try {
+        for (const board of boards)
+            reports.push(await bring(c, board));
+        return reports;
+    }
+    catch (error) {
+        for (const board of boards) {
+            if (!(await c.store.boards.get(board.id)))
+                continue;
+            await c.store.boards.remove(board.id);
+            await c.blobs.removeBoard(board.id);
+        }
+        throw error;
+    }
+}
+export async function migrate(options) {
+    const to = resolve(options.to);
+    const sources = options.sources.map((source) => resolve(source));
+    if (!sources.length)
+        throw new OrbitError("migration_source_unreadable", { message: "Name the old data folder or the exports to bring over." });
+    const realTo = realPathOf(to);
+    for (const source of sources) {
+        if (!existsSync(source))
+            throw new OrbitError("migration_source_unreadable", { message: `${source} doesn't exist.` });
+        const realSource = realpathSync(source);
+        const around = (a, b) => a === b || inside(a, b) !== null || inside(b, a) !== null;
+        if (around(source, to) || around(realSource, realTo))
+            throw new OrbitError("migration_target_in_use", { message: `Orbit brings old boards into a new folder of its own, never into or around the old one: choose another folder than ${to}.` });
+    }
+    const scratch = mkdtempSync(join(tmpdir(), "orbit-migrate-"));
+    const notes = [];
+    try {
+        const boards = sources.flatMap((source, i) => (lstatSync(realpathSync(source)).isDirectory() ? readFolder(source, join(scratch, String(i)), notes) : [readExport(source)]));
+        boards.forEach(keptSlug);
+        const slugs = new Set();
+        for (const board of boards) {
+            if (slugs.has(board.slug))
+                throw new OrbitError("migration_target_in_use", { message: `Two of the sources hold a board named ${board.slug}: bring them over one at a time, into two folders.` });
+            slugs.add(board.slug);
+        }
+        // A folder an earlier run made: when every board is there, nothing is done.
+        if (!isEmptyDir(to)) {
+            if (lstatSync(to).isSymbolicLink())
+                throw new OrbitError("migration_target_in_use", { message: `${to} is a link, not a folder: choose a new folder for Orbit's data.` });
+            if (!existsSync(join(to, "registry.db")))
+                throw new OrbitError("migration_target_in_use", { message: `${to} isn't empty: choose a new folder for Orbit's data.` });
+            const target = await openTarget(to);
+            try {
+                const there = await Promise.all(boards.map((board) => target.c.store.boards.get(board.id)));
+                if (there.every(Boolean))
+                    return { to, already: true, boards: await Promise.all(boards.map((board) => check(target.c, board, board.id))), notes };
+                // Orbit's own folder with no board yet (an upgrader ran orbit run first), or, filled with no
+                // folder named, holding none of these boards' slugs or ids: the boards come in through the
+                // store, which an Orbit running there shares, and go again if one fails.
+                if (!(await target.c.store.boards.list()).length)
+                    return { to, already: false, boards: await bringInPlace(target.c, boards), notes };
+                if (options.fill) {
+                    const found = await clashes(target.c, boards);
+                    if (found.length)
+                        throw new OrbitError("migration_target_in_use", { message: clashText(to, found) });
+                    return { to, already: false, boards: await bringInPlace(target.c, boards), notes };
+                }
+            }
+            finally {
+                await target.close();
+            }
+            throw new OrbitError("migration_target_in_use", { message: `${to} already holds other boards: choose a new folder for Orbit's data.` });
+        }
+        // Built beside its final name, then moved into place.
+        mkdirSync(dirname(to), { recursive: true });
+        const building = mkdtempSync(join(dirname(to), `.${basename(to)}.migrating-`));
+        try {
+            const target = await openTarget(building);
+            const reports = [];
+            try {
+                for (const board of boards)
+                    reports.push(await bring(target.c, board));
+            }
+            finally {
+                await target.close();
+            }
+            // The target was absent or empty when the run began; anything in it now is someone else's, so it is refused, never removed.
+            if (existsOrLink(to)) {
+                if (!isEmptyDir(to) || lstatSync(to).isSymbolicLink())
+                    throw new OrbitError("migration_target_in_use", { message: `${to} was filled while the boards were brought over: nothing was written there. Choose a new folder for Orbit's data.` });
+                rmdirSync(to);
+            }
+            renameSync(building, to);
+            return { to, already: false, boards: reports, notes };
+        }
+        catch (error) {
+            rmSync(building, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/lib/node/package.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The installed package: its folder and its version. Kept apart from the
+ * store so `orbit -v` reads one small file and loads nothing else.
+ */
+/** The package's folder: two up from this file in src/node/ or lib/node/. */
+export declare const PACKAGE_ROOT: string;
+export declare function packageVersion(): string;

package/lib/node/package.js

@@ -0,0 +1,14 @@
+/**
+ * The installed package: its folder and its version. Kept apart from the
+ * store so `orbit -v` reads one small file and loads nothing else.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The package's folder: two up from this file in src/node/ or lib/node/. */
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+let version = null;
+export function packageVersion() {
+    version ??= JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
+    return version;
+}