@starlove/orbit 1.0.6 → 1.1.0

package/src/core/migrate.js

@@ -0,0 +1,198 @@
+/**
+ * migrate.js — one-time startup migration of per-board SQLite files from
+ * in-repo .orbit/ directories into the central DATA_DIR/boards/<slug>/ store.
+ *
+ * Called during board.js startup, before ensureSchemaForEveryBoard, so that
+ * by the time per-board connections are opened they are already at their
+ * canonical central location.
+ *
+ * If a migration fails the registry row is NOT updated and Orbit continues
+ * to serve from the old in-repo path. A structured warning with agent-actionable
+ * manual instructions is printed to stderr.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { closeConnection, getRegistry, openConnection } from "./db.js";
+import { BOARDS_DIR } from "./paths.js";
+import { listBoards } from "./registry.js";
+
+/** Normalize to forward slashes for consistent cross-platform prefix checks. */
+const fwd = (p) => p.replace(/\\/g, "/");
+
+/** True when db_path already lives inside the canonical BOARDS_DIR. */
+function isCentral(dbPath) {
+  return fwd(dbPath).startsWith(fwd(BOARDS_DIR) + "/");
+}
+
+/** Canonical central path for a given slug. */
+function centralPathFor(slug) {
+  return join(BOARDS_DIR, slug, "board.db");
+}
+
+/** Delete a file if it exists; silently ignore errors. */
+function tryUnlink(p) {
+  try { if (existsSync(p)) unlinkSync(p); } catch { /* ignore */ }
+}
+
+/**
+ * Walk upward from startDir, removing each directory that is now empty.
+ * Stops at stopDir (inclusive) or the first non-empty directory.
+ * This cleans up empty .orbit/ trees left behind after moving the db out.
+ */
+function pruneEmptyAncestors(startDir, stopDir) {
+  const stopFwd = fwd(stopDir);
+  let cur = fwd(startDir);
+  while (cur.startsWith(stopFwd)) {
+    try {
+      if (!existsSync(cur)) {
+        /* already gone, climb */
+      } else if (readdirSync(cur).length > 0) {
+        break; // non-empty — stop here
+      } else {
+        // rmSync({recursive:true, force:true}) works correctly for both files and
+        // empty directories across Node versions and platforms.  We've already
+        // confirmed the directory is empty so nothing is over-deleted.
+        rmSync(cur, { recursive: true, force: true });
+      }
+    } catch {
+      break;
+    }
+    if (cur === stopFwd) break; // reached the limit
+    const parent = fwd(dirname(cur));
+    if (parent === cur) break; // filesystem root
+    cur = parent;
+  }
+}
+
+/**
+ * For a db path inside a repo's .orbit directory, return the .orbit parent.
+ *   /repo/.orbit/board.db          → /repo/.orbit
+ *   /repo/.orbit/boards/x/board.db → /repo/.orbit
+ * Returns null if ".orbit" is not found in the path.
+ */
+function orbitParentDir(dbPath) {
+  const parts = fwd(dbPath).split("/");
+  const idx = parts.lastIndexOf(".orbit");
+  if (idx < 0) return null;
+  return parts.slice(0, idx + 1).join("/");
+}
+
+function sqlLiteral(v) {
+  return `'${String(v).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Attempt to migrate one board from in-repo storage to central storage.
+ * Returns a result object with status: 'migrated' | 'failed' | 'missing_source'.
+ */
+function migrateOneBoard(boardRow) {
+  const { id, slug, db_path: oldPath } = boardRow;
+
+  if (!existsSync(oldPath)) {
+    // Source file is gone; ensureSchemaForEveryBoard will prune the stale row.
+    return { status: "missing_source", board: boardRow, oldPath };
+  }
+
+  const newPath = centralPathFor(slug);
+  mkdirSync(dirname(newPath), { recursive: true });
+
+  try {
+    // Safety: if the target path is already registered to a *different* board id,
+    // skip rather than overwrite live data (guards against corrupted registries with
+    // duplicate slugs — cannot happen through normal API use but is defensive).
+    const existingOwner = getRegistry().prepare("SELECT id FROM boards WHERE db_path = ?").get(newPath);
+    if (existingOwner && existingOwner.id !== id) {
+      return {
+        status: "failed",
+        board: boardRow,
+        oldPath,
+        newPath,
+        error: new Error(
+          `central path ${newPath} is already registered to board ${existingOwner.id} — skipping to avoid data loss`
+        )
+      };
+    }
+
+    // Remove any stale central copy left by a previous partial migration.
+    if (existsSync(newPath)) tryUnlink(newPath);
+
+    // VACUUM INTO creates a clean, WAL-flushed copy. It captures only committed
+    // data and produces a single-file database (no -wal/-shm at the destination).
+    const db = openConnection(oldPath);
+    db.exec(`VACUUM INTO ${sqlLiteral(newPath)};`);
+    closeConnection(oldPath);
+
+    // Update the registry before deleting the source so the canonical pointer is
+    // always valid: if the process dies between these two steps the old file still
+    // exists and the next run will redo the migration cleanly.
+    getRegistry()
+      .prepare("UPDATE boards SET db_path = ?, updated_at = ? WHERE id = ?")
+      .run(newPath, new Date().toISOString(), id);
+
+    // Remove source files (main db + WAL + SHM + journal).
+    tryUnlink(oldPath);
+    tryUnlink(oldPath + "-wal");
+    tryUnlink(oldPath + "-shm");
+    tryUnlink(oldPath + "-journal");
+
+    // Prune now-empty .orbit/ directories from the repo tree.
+    const orbitDir = orbitParentDir(oldPath);
+    if (orbitDir) pruneEmptyAncestors(dirname(oldPath), orbitDir);
+
+    return { status: "migrated", board: boardRow, oldPath, newPath };
+  } catch (error) {
+    // Ensure no lingering open connection or partial central file on failure.
+    try { closeConnection(oldPath); } catch { /* ignore */ }
+    tryUnlink(newPath);
+    return { status: "failed", board: boardRow, oldPath, newPath, error };
+  }
+}
+
+/**
+ * Migrate all boards whose db_path lives outside DATA_DIR into central storage.
+ * Called at server/MCP startup before any per-board connections are opened.
+ * Prints a concise summary for migrated boards; prints agent-actionable
+ * instructions for any failures so a human or AI can complete the migration.
+ */
+export function migrateInRepoBoards() {
+  const pending = listBoards().filter((row) => !isCentral(row.db_path));
+  if (pending.length === 0) return;
+
+  const results = pending.map(migrateOneBoard);
+  const migrated = results.filter((r) => r.status === "migrated");
+  const failed = results.filter((r) => r.status === "failed");
+
+  if (migrated.length > 0) {
+    const n = migrated.length;
+    console.log(`[orbit] Migrated ${n} board${n > 1 ? "s" : ""} to central storage (${BOARDS_DIR}):`);
+    for (const r of migrated) {
+      console.log(`  ✓ ${r.board.slug}`);
+      console.log(`    from: ${r.oldPath}`);
+      console.log(`    to:   ${r.newPath}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    const sep = "  │";
+    const n = failed.length;
+    console.error(`\n[orbit] ⚠ Could not auto-migrate ${n} board${n > 1 ? "s" : ""} to central storage.`);
+    console.error(`${sep} These boards continue to work from their current paths.`);
+    console.error(`${sep} To complete the migration manually, run the commands below and`);
+    console.error(`${sep} restart orbit serve:\n`);
+    for (const r of failed) {
+      const slash = process.platform === "win32" ? "\\" : "/";
+      const destDir = dirname(r.newPath).replace(/\//g, slash);
+      const src = r.oldPath.replace(/\//g, slash);
+      const dest = r.newPath.replace(/\//g, slash);
+      console.error(`${sep} Board: ${r.board.slug}  (error: ${r.error?.message ?? r.error})`);
+      if (process.platform === "win32") {
+        console.error(`${sep}   md "${destDir}"`);
+        console.error(`${sep}   copy "${src}" "${dest}"`);
+      } else {
+        console.error(`${sep}   mkdir -p '${destDir}'`);
+        console.error(`${sep}   cp '${src}' '${dest}'`);
+      }
+      console.error(sep);
+    }
+  }
+}

package/src/core/paths.js

@@ -16,10 +16,16 @@ export const PROJECT_ROOT = process.env.PROJECT_ROOT ? resolve(process.env.PROJE
 export const DATA_DIR = process.env.DATA_DIR || join(homedir(), ".orbit");
 /** Central registry of all boards (metadata + paths to per-board SQLite files). */
 export const REGISTRY_DB_PATH = join(DATA_DIR, "registry.db");
+/** Central directory where every board's SQLite file lives: DATA_DIR/boards/<slug>/board.db */
+export const BOARDS_DIR = join(DATA_DIR, "boards");
 export const EXPORT_DIR = join(DATA_DIR, "exports");
 export const BACKUP_DIR = join(DATA_DIR, "backups");
+/** Central directory for dispatch run artifacts: DATA_DIR/dispatch-runs/<board-slug>/<run-id>/ */
+export const DISPATCH_RUNS_DIR = join(DATA_DIR, "dispatch-runs");
 export const PORT = Number(process.env.PORT || 3337);
 
 mkdirSync(DATA_DIR, { recursive: true });
+mkdirSync(BOARDS_DIR, { recursive: true });
 mkdirSync(EXPORT_DIR, { recursive: true });
 mkdirSync(BACKUP_DIR, { recursive: true });
+mkdirSync(DISPATCH_RUNS_DIR, { recursive: true });

package/src/core/registry.js

@@ -4,9 +4,10 @@
 // the board that owns a given ticket / state / entry / relation. Callers
 // receive `{ board, db }` and pass it down via `ctx`.
 
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createBoardSchema, getRegistry, openConnection } from "./db.js";
+import { BOARDS_DIR } from "./paths.js";
 import { now, slugify } from "./util.js";
 
 export function listBoards() {
@@ -92,14 +93,16 @@ export function updateBoardMeta(boardId, patch) {
     .run(...vals);
 }
 
-/** Where a new board.db should live: flat .orbit/board.db for a repo's first
- *  board, or .orbit/boards/<slug>/board.db for additional boards on the same
- *  repo. */
-export function computeNewBoardDbPath(repoPathNorm, slug) {
-  const reg = getRegistry();
-  const count = reg.prepare("SELECT COUNT(*) AS c FROM boards WHERE repo_path = ?").get(repoPathNorm).c;
-  if (count === 0) return join(repoPathNorm, ".orbit", "board.db");
-  return join(repoPathNorm, ".orbit", "boards", slug, "board.db");
+/** Where a new board.db should live: always in the central DATA_DIR/boards/<slug>/ directory.
+ *  Falls back to a numeric suffix if the canonical path already exists on disk (orphaned file). */
+export function computeNewBoardDbPath(_repoPathNorm, slug) {
+  const preferred = join(BOARDS_DIR, slug, "board.db");
+  if (!existsSync(preferred)) return preferred;
+  for (let i = 2; i < 1000; i++) {
+    const alt = join(BOARDS_DIR, `${slug}-${i}`, "board.db");
+    if (!existsSync(alt)) return alt;
+  }
+  return preferred; // callers will handle any existing file
 }
 
 /** Create the directory + file and apply the per-board schema. Returns the

package/src/core/router.js

@@ -5,9 +5,9 @@
 // board, it is rejected with 400 board_id_required rather than silently
 // inheriting some other caller's recent state.
 
-import { localOwnerActor } from "./auth.js";
+import { actorFromHttpRequest } from "./auth.js";
 import { scheduleAutomaticBoardBackup } from "./backups.js";
-import { readJson, sendJson, setCors } from "./http.js";
+import { readJson, readRaw, sendFile, sendJson, setCors } from "./http.js";
 import {
   findBoardForBoardEntry,
   findBoardForRelation,
@@ -54,11 +54,20 @@ import {
   getTicketRelations
 } from "./relations.js";
 import { searchTickets } from "./search.js";
+import {
+  createTicketAttachment,
+  deleteTicketAttachment,
+  getTicketAttachmentContent,
+  listTicketAttachments,
+  MAX_IMAGE_ATTACHMENT_BYTES
+} from "./attachments.js";
 import {
   checkpointTicket,
   claimNext,
   completeTicket,
-  getContextPack
+  getContextPack,
+  readComments,
+  readTicket
 } from "./agent.js";
 
 /** Build a ctx for an already-resolved registry row + actor. */
@@ -103,11 +112,11 @@ export async function handleApi(req, res, url) {
     return;
   }
 
-  const actor = localOwnerActor();
+  const actor = actorFromHttpRequest(req);
 
   // Bootstrap: read-only registry + one chosen board. No global state mutated.
   if (req.method === "GET" && url.pathname === "/api/bootstrap") {
-    sendJson(res, 200, getBootstrap(actor, url.searchParams.get("board_id")));
+    sendJson(res, 200, getBootstrap(actor, url.searchParams.get("board_id"), url.searchParams.get("board")));
     return;
   }
 
@@ -183,7 +192,9 @@ export async function handleApi(req, res, url) {
       return;
     }
     if (sub === "export" && req.method === "GET") {
-      sendJson(res, 200, exportBoard(row.id, ctx));
+      sendJson(res, 200, exportBoard(row.id, ctx, {
+        includeAttachments: url.searchParams.get("include_attachments") === "true" || url.searchParams.get("include_images") === "true"
+      }));
       return;
     }
     if (sub === "states" && req.method === "POST") {
@@ -212,6 +223,18 @@ export async function handleApi(req, res, url) {
     return;
   }
 
+  // /api/tickets/lookup GET — exact lightweight lookup by number or title.
+  if (req.method === "GET" && url.pathname === "/api/tickets/lookup") {
+    const { boardId, boardSlug } = boardHintsFromQuery(url);
+    const row = resolveBoardFromHint(boardId, boardSlug);
+    if (!row) throw httpError(400, "board_id_required");
+    const lookup = {};
+    if (url.searchParams.has("number")) lookup.number = url.searchParams.get("number");
+    if (url.searchParams.has("title")) lookup.title = url.searchParams.get("title");
+    sendJson(res, 200, readTicket(lookup, ctxFromBoardRow(row, actor)));
+    return;
+  }
+
   // /api/tickets/:id/... — board resolved from query hint or via lookup.
   const ticketPath = url.pathname.match(/^\/api\/tickets\/([^/]+)(?:\/(.*))?$/);
   if (ticketPath) {
@@ -223,6 +246,10 @@ export async function handleApi(req, res, url) {
     if (!found) throw httpError(404, "ticket_not_found");
     const ctx = ctxFromBoardRow(found.board, actor);
 
+    if (sub === "" && req.method === "GET") {
+      sendJson(res, 200, readTicket(ticketId, ctx));
+      return;
+    }
     if (sub === "" && req.method === "PATCH") {
       const body = await readJson(req);
       sendMutationJson(res, 200, updateTicket(ticketId, body, ctx), ctx);
@@ -257,11 +284,40 @@ export async function handleApi(req, res, url) {
       sendJson(res, 200, getTicketBlockers(ticketId, ctx));
       return;
     }
+    if (sub === "comments" && req.method === "GET") {
+      sendJson(res, 200, readComments(ticketId, ctx));
+      return;
+    }
     if (sub === "comments" && req.method === "POST") {
       const body = await readJson(req);
       sendMutationJson(res, 201, createComment(ticketId, body, ctx), ctx);
       return;
     }
+    if (sub === "attachments" && req.method === "GET") {
+      sendJson(res, 200, listTicketAttachments(ticketId, ctx));
+      return;
+    }
+    if (sub === "attachments" && req.method === "POST") {
+      const bytes = await readRaw(req, MAX_IMAGE_ATTACHMENT_BYTES);
+      const attachment = createTicketAttachment(ticketId, {
+        bytes,
+        mime_type: req.headers["content-type"],
+        original_name: req.headers["x-file-name"] || url.searchParams.get("filename") || "image"
+      }, ctx);
+      sendMutationJson(res, 201, attachment, ctx);
+      return;
+    }
+    const attachmentContentPath = sub.match(/^attachments\/([^/]+)\/content$/);
+    if (attachmentContentPath && req.method === "GET") {
+      const result = getTicketAttachmentContent(ticketId, decodeURIComponent(attachmentContentPath[1]), ctx);
+      sendFile(res, result.filePath, result.row.mime_type);
+      return;
+    }
+    const attachmentPath = sub.match(/^attachments\/([^/]+)$/);
+    if (attachmentPath && req.method === "DELETE") {
+      sendMutationJson(res, 200, deleteTicketAttachment(ticketId, decodeURIComponent(attachmentPath[1]), ctx), ctx);
+      return;
+    }
     sendJson(res, 404, { error: "not_found" });
     return;
   }

package/src/core/search.js

@@ -16,38 +16,65 @@ export function searchTickets(args, ctx) {
   if (!q) return { query: q, results: [] };
   if (!canAccessBoard(actor, board)) return { query: q, results: [] };
 
+  const ticketNumber = ticketNumberQuery(q);
   const fts = toFtsQuery(q);
   let rows = [];
-  try {
+
+  if (ticketNumber !== null) {
     rows = db
       .prepare(
-        `SELECT t.*, s.name AS state_name, b.slug AS board_slug,
-                bm25(ticket_fts) AS rank
-         FROM ticket_fts
-         JOIN tickets t ON t.id = ticket_fts.ticket_id
+        `SELECT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug, -1 AS rank
+         FROM tickets t
          JOIN states s ON s.id = t.state_id
          JOIN boards b ON b.id = t.board_id
-         WHERE ticket_fts MATCH ? AND t.archived_at IS NULL
-         ORDER BY rank
+         WHERE t.board_id = ? AND t.number = ? AND t.archived_at IS NULL
          LIMIT ?`
       )
-      .all(fts, limit);
+      .all(board.id, ticketNumber, limit);
+  }
+
+  try {
+    rows = rows.concat(
+      db
+        .prepare(
+          `SELECT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug,
+                  bm25(ticket_fts) AS rank
+           FROM ticket_fts
+           JOIN tickets t ON t.id = ticket_fts.ticket_id
+           JOIN states s ON s.id = t.state_id
+           JOIN boards b ON b.id = t.board_id
+           WHERE ticket_fts MATCH ? AND t.board_id = ? AND t.archived_at IS NULL
+           ORDER BY rank
+           LIMIT ?`
+        )
+        .all(fts, board.id, limit)
+    );
   } catch {
     const like = `%${q}%`;
-    rows = db
-      .prepare(
-        `SELECT DISTINCT t.*, s.name AS state_name, b.slug AS board_slug, 0 AS rank
-         FROM tickets t
-         JOIN states s ON s.id = t.state_id
-         JOIN boards b ON b.id = t.board_id
-         LEFT JOIN comments c ON c.ticket_id = t.id
-         WHERE t.archived_at IS NULL
-           AND (t.title LIKE ? OR t.description LIKE ? OR t.ai_plan LIKE ?
-            OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ? OR c.body LIKE ?)
-         ORDER BY t.updated_at DESC, t.id ASC
-         LIMIT ?`
-      )
-      .all(like, like, like, like, like, like, limit);
+    const numberRank = ticketNumber !== null ? "CASE WHEN t.number = ? THEN -1 ELSE 0 END" : "0";
+    const numberPredicate = ticketNumber !== null ? "OR t.number = ?" : "";
+    const fallbackArgs = ticketNumber !== null ? [ticketNumber, board.id] : [board.id];
+    fallbackArgs.push(like, like, like, like, like, like);
+    if (ticketNumber !== null) fallbackArgs.push(ticketNumber);
+    fallbackArgs.push(limit);
+
+    rows = rows.concat(
+      db
+        .prepare(
+          `SELECT DISTINCT t.*, s.name AS state_name, s.role AS state_role, b.slug AS board_slug, ${numberRank} AS rank
+           FROM tickets t
+           JOIN states s ON s.id = t.state_id
+           JOIN boards b ON b.id = t.board_id
+           LEFT JOIN comments c ON c.ticket_id = t.id
+           WHERE t.board_id = ? AND t.archived_at IS NULL
+             AND (t.title LIKE ? OR t.description LIKE ? OR t.ai_plan LIKE ?
+              OR t.implementation_summary LIKE ? OR t.implementation_updates LIKE ? OR c.body LIKE ?
+              ${numberPredicate})
+           ORDER BY t.updated_at DESC, t.id ASC
+           LIMIT ?`
+        )
+        .all(...fallbackArgs)
+    );
   }
 
   rows.sort((a, b) => {
@@ -73,3 +100,10 @@ export function searchTickets(args, ctx) {
 
   return { query: q, results };
 }
+
+function ticketNumberQuery(q) {
+  const match = String(q).trim().match(/^#?(\d+)$/);
+  if (!match) return null;
+  const number = Number(match[1]);
+  return Number.isSafeInteger(number) ? number : null;
+}

package/src/core/snapshots.js

@@ -13,8 +13,13 @@ import {
   requiredString
 } from "./util.js";
 import { reindexAllTickets } from "./tickets.js";
+import {
+  attachmentRowsForBoard,
+  importAttachmentRows,
+  serializeAttachmentForExport
+} from "./attachments.js";
 
-export function exportBoard(boardId, ctx) {
+export function exportBoard(boardId, ctx, options = {}) {
   const { db, board, actor } = ctx;
   if (boardId !== board.id) throw httpError(404, "board_not_found");
   const innerBoard = boardById(db, boardId);
@@ -56,17 +61,22 @@ export function exportBoard(boardId, ctx) {
        ORDER BY created_at ASC`
     )
     .all(boardId);
+  const attachments = attachmentRowsForBoard(db, boardId).map((row) =>
+    serializeAttachmentForExport(board, row, Boolean(options.includeAttachments))
+  );
 
   return {
     format: "orbit-board-export",
-    version: 5,
+    version: 6,
     exported_at: now(),
+    include_attachments: Boolean(options.includeAttachments),
     board: { ...innerBoard },
     states,
     labels,
     tickets,
     comments,
     relations,
+    attachments,
     board_entries: entries,
     events
   };
@@ -200,6 +210,8 @@ export function importBoardSnapshot(body, ctx) {
       );
     }
 
+    importAttachmentRows(snapshot, ctx, targetBoardId);
+
     for (const entry of snapshot.board_entries || []) {
       db.prepare(
         `INSERT INTO board_entries