@starlove/orbit 1.0.1

package/src/core/queries.js

@@ -0,0 +1,246 @@
+// Read/write helpers that all take an explicit `db` connection. No hidden
+// "active board" state — callers pass in the connection for the board they
+// resolved at the request boundary.
+
+import { httpError, id, now, requiredString } from "./util.js";
+
+export function ticketByNumber(db, boardId, number) {
+  return db
+    .prepare(
+      `SELECT t.*, s.name AS state_name, s.role AS state_role,
+              b.slug AS board_slug, b.name AS board_name
+       FROM tickets t
+       JOIN states s ON s.id = t.state_id
+       JOIN boards b ON b.id = t.board_id
+       WHERE t.board_id = ? AND t.number = ?`
+    )
+    .get(boardId, number);
+}
+
+export function ticketByTitle(db, boardId, title) {
+  return db
+    .prepare(
+      `SELECT t.*, s.name AS state_name, s.role AS state_role,
+              b.slug AS board_slug, b.name AS board_name
+       FROM tickets t
+       JOIN states s ON s.id = t.state_id
+       JOIN boards b ON b.id = t.board_id
+       WHERE t.board_id = ? AND lower(t.title) = lower(?)
+       ORDER BY t.archived_at IS NULL DESC, t.number DESC
+       LIMIT 1`
+    )
+    .get(boardId, title);
+}
+
+export function ticketById(db, ticketId) {
+  return db
+    .prepare(
+      `SELECT t.*, s.name AS state_name, s.role AS state_role,
+              b.slug AS board_slug, b.name AS board_name
+       FROM tickets t
+       JOIN states s ON s.id = t.state_id
+       JOIN boards b ON b.id = t.board_id
+       WHERE t.id = ?`
+    )
+    .get(ticketId);
+}
+
+export function boardById(db, boardId) {
+  return db.prepare("SELECT * FROM boards WHERE id = ?").get(boardId);
+}
+
+export function stateByName(db, boardId, name) {
+  return db.prepare("SELECT * FROM states WHERE board_id = ? AND name = ?").get(boardId, name);
+}
+
+export function stateByRole(db, boardId, role) {
+  return db
+    .prepare("SELECT * FROM states WHERE board_id = ? AND role = ? ORDER BY position LIMIT 1")
+    .get(boardId, role);
+}
+
+export function stateById(db, stateId) {
+  return db.prepare("SELECT * FROM states WHERE id = ?").get(stateId);
+}
+
+export function defaultStateId(db, boardId) {
+  const state =
+    db.prepare("SELECT id FROM states WHERE board_id = ? AND is_default = 1").get(boardId) ||
+    db.prepare("SELECT id FROM states WHERE board_id = ? ORDER BY position LIMIT 1").get(boardId);
+  if (!state) throw httpError(400, "board_has_no_states");
+  return state.id;
+}
+
+export function compactStatePositions(db, boardId) {
+  const states = db.prepare("SELECT id FROM states WHERE board_id = ? ORDER BY position").all(boardId);
+  states.forEach((state, position) => {
+    db.prepare("UPDATE states SET position = ? WHERE id = ?").run(position, state.id);
+  });
+}
+
+export function labelsForTicket(db, ticketId) {
+  return db
+    .prepare(
+      `SELECT l.*
+       FROM ticket_labels tl
+       JOIN labels l ON l.id = tl.label_id
+       WHERE tl.ticket_id = ?
+       ORDER BY l.name`
+    )
+    .all(ticketId);
+}
+
+export function childTicketsFor(db, ticketId) {
+  return db
+    .prepare(
+      `SELECT t.*, s.name AS state_name, s.role AS state_role,
+              b.slug AS board_slug, b.name AS board_name
+       FROM tickets t
+       JOIN states s ON s.id = t.state_id
+       JOIN boards b ON b.id = t.board_id
+       WHERE t.parent_ticket_id = ? AND t.archived_at IS NULL
+       ORDER BY t.number ASC`
+    )
+    .all(ticketId);
+}
+
+export function archivedTicketsForBoard(db, boardId) {
+  return db
+    .prepare(
+      `SELECT t.*, s.name AS state_name, s.role AS state_role,
+              b.slug AS board_slug, b.name AS board_name
+       FROM tickets t
+       JOIN states s ON s.id = t.state_id
+       JOIN boards b ON b.id = t.board_id
+       WHERE t.board_id = ? AND t.archived_at IS NOT NULL
+       ORDER BY t.archived_at DESC`
+    )
+    .all(boardId);
+}
+
+export function compactTicket(ticket) {
+  if (!ticket) return null;
+  return {
+    id: ticket.id,
+    board_id: ticket.board_id,
+    board_slug: ticket.board_slug,
+    number: ticket.number,
+    title: ticket.title,
+    type: ticket.type,
+    state_name: ticket.state_name,
+    state_role: ticket.state_role,
+    priority: ticket.priority
+  };
+}
+
+export function uniqueTickets(tickets) {
+  const seen = new Set();
+  const result = [];
+  for (const ticket of tickets) {
+    if (!ticket || seen.has(ticket.id)) continue;
+    seen.add(ticket.id);
+    result.push(ticket);
+  }
+  return result;
+}
+
+export function relationRows(db, ticketId) {
+  const rows = db
+    .prepare(
+      `SELECT r.*,
+              source.title AS source_title,
+              source.number AS source_number,
+              source.board_id AS source_board_id,
+              target.title AS target_title,
+              target.number AS target_number,
+              target.board_id AS target_board_id
+       FROM relations r
+       JOIN tickets source ON source.id = r.source_ticket_id
+       JOIN tickets target ON target.id = r.target_ticket_id
+       WHERE (r.source_ticket_id = ? OR r.target_ticket_id = ?)
+         AND source.archived_at IS NULL AND target.archived_at IS NULL
+       ORDER BY r.created_at ASC`
+    )
+    .all(ticketId, ticketId);
+
+  return rows.map((row) => {
+    const isSource = row.source_ticket_id === ticketId;
+    const otherId = isSource ? row.target_ticket_id : row.source_ticket_id;
+    const other = ticketById(db, otherId);
+    return {
+      id: row.id,
+      type: row.type,
+      direction: isSource ? "outgoing" : "incoming",
+      other_ticket: other
+    };
+  });
+}
+
+// Returns the set of tickets currently blocking `ticketId`. The relation row
+// IS the source of truth: a `blocked_by` row exists iff the target is still
+// blocking. Cleanup happens at state-change time (tickets.js auto-deletes
+// blocks/blocked_by rows when a ticket moves to a role='done' lane) or when
+// the user removes the relation manually in the UI. So this resolver doesn't
+// re-check lane state — it just returns the unarchived rows. Exception: epic
+// targets expand to their children, since the epic itself isn't what gets
+// "done"; each open child (state role != 'done', not archived) is a blocker
+// and carries via_epic_id so callers can explain the dependency.
+export function unresolvedBlockers(db, ticketId) {
+  const direct = db
+    .prepare(
+      `SELECT target.*, s.name AS state_name, s.role AS state_role
+       FROM relations r
+       JOIN tickets target ON target.id = r.target_ticket_id
+       JOIN states s ON s.id = target.state_id
+       WHERE r.source_ticket_id = ? AND r.type = 'blocked_by' AND target.archived_at IS NULL`
+    )
+    .all(ticketId);
+
+  const expandEpicChildren = db.prepare(
+    `SELECT t.*, s.name AS state_name, s.role AS state_role
+     FROM tickets t
+     JOIN states s ON s.id = t.state_id
+     WHERE t.parent_ticket_id = ? AND t.archived_at IS NULL AND (s.role IS NULL OR s.role != 'done')`
+  );
+
+  const seen = new Set();
+  const blockers = [];
+  for (const row of direct) {
+    if (row.type === "epic") {
+      const children = expandEpicChildren.all(row.id);
+      for (const child of children) {
+        if (seen.has(child.id)) continue;
+        seen.add(child.id);
+        blockers.push({ ...child, via_epic_id: row.id });
+      }
+      continue;
+    }
+    if (seen.has(row.id)) continue;
+    seen.add(row.id);
+    blockers.push(row);
+  }
+  return blockers;
+}
+
+export function ensureLabel(db, boardId, name, color = "#64748b") {
+  const cleanName = requiredString(name, "label").trim();
+  const existing = db.prepare("SELECT * FROM labels WHERE board_id = ? AND name = ?").get(boardId, cleanName);
+  if (existing) return existing;
+  const labelId = id();
+  db.prepare("INSERT INTO labels (id, board_id, name, color, created_at) VALUES (?, ?, ?, ?, ?)").run(
+    labelId,
+    boardId,
+    cleanName,
+    color,
+    now()
+  );
+  return db.prepare("SELECT * FROM labels WHERE id = ?").get(labelId);
+}
+
+export function addComment(db, ticketId, author, kind, body) {
+  const commentId = id();
+  db.prepare(
+    "INSERT INTO comments (id, ticket_id, author, kind, body, created_at) VALUES (?, ?, ?, ?, ?, ?)"
+  ).run(commentId, ticketId, author, kind, body, now());
+  return db.prepare("SELECT * FROM comments WHERE id = ?").get(commentId);
+}

package/src/core/registry.js

@@ -0,0 +1,207 @@
+// Registry-level operations. No mutable global "active board" state lives
+// here: every function either reads from the registry, opens a known
+// per-board DB by path, or scans a bounded set of registry rows to locate
+// 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 { dirname, join } from "node:path";
+import { createBoardSchema, getRegistry, openConnection } from "./db.js";
+import { now, slugify } from "./util.js";
+
+export function listBoards() {
+  return getRegistry().prepare("SELECT * FROM boards ORDER BY name").all();
+}
+
+export function getBoardByRegistryId(boardId) {
+  return getRegistry().prepare("SELECT * FROM boards WHERE id = ?").get(boardId);
+}
+
+export function getBoardBySlug(slug) {
+  return getRegistry().prepare("SELECT * FROM boards WHERE slug = ?").get(slugify(slug));
+}
+
+export function getBoardByRepoPath(repoPathNorm) {
+  return getRegistry()
+    .prepare(
+      `SELECT * FROM boards
+       WHERE repo_path = ?
+       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC
+       LIMIT 1`
+    )
+    .get(repoPathNorm);
+}
+
+/** Most-recently-active registry row, or null. Used as a tie-breaker for the
+ *  bootstrap-default case when no board is specified by the caller. */
+export function pickDefaultBoard() {
+  return getRegistry()
+    .prepare(
+      `SELECT * FROM boards
+       ORDER BY (last_active_at IS NULL) ASC, last_active_at DESC, created_at ASC
+       LIMIT 1`
+    )
+    .get();
+}
+
+export function deleteBoard(boardId) {
+  getRegistry().prepare("DELETE FROM boards WHERE id = ?").run(boardId);
+}
+
+export function touchBoardActive(boardId) {
+  const t = now();
+  getRegistry()
+    .prepare("UPDATE boards SET last_active_at = ?, updated_at = ? WHERE id = ?")
+    .run(t, t, boardId);
+}
+
+export function insertBoard(row) {
+  const t = row.created_at || now();
+  getRegistry()
+    .prepare(
+      `INSERT INTO boards (id, slug, name, repo_path, db_path, repo_url, default_branch, last_active_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      row.id,
+      row.slug,
+      row.name,
+      row.repo_path,
+      row.db_path,
+      row.repo_url || "",
+      row.default_branch || "main",
+      row.last_active_at || t,
+      t,
+      row.updated_at || t
+    );
+}
+
+export function updateBoardMeta(boardId, patch) {
+  const sets = [];
+  const vals = [];
+  for (const k of ["slug", "name", "repo_path", "db_path", "repo_url", "default_branch"]) {
+    if (patch[k] !== undefined) {
+      sets.push(`${k} = ?`);
+      vals.push(patch[k]);
+    }
+  }
+  if (!sets.length) return;
+  vals.push(now(), boardId);
+  getRegistry()
+    .prepare(`UPDATE boards SET ${sets.join(", ")}, updated_at = ? WHERE id = ?`)
+    .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");
+}
+
+/** Create the directory + file and apply the per-board schema. Returns the
+ *  open connection. */
+export function ensureBoardDbFileAndSchema(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const conn = openConnection(dbPath);
+  createBoardSchema(conn);
+  return conn;
+}
+
+/** Open the connection for a registry row. */
+export function openBoardDb(boardRow) {
+  return openConnection(boardRow.db_path);
+}
+
+// Whitelisted table names — these come from our own call sites, never user
+// input, but interpolating into SQL is only safe because of this guard.
+const ROW_OWNER_TABLES = new Set(["tickets", "states", "board_entries", "relations"]);
+
+/**
+ * Find which registry board's DB contains a row with `id` in `table`. Pure:
+ * opens one db per candidate to probe and returns `{ board, db }` (no global
+ * side effects). If `hintBoardId` is supplied it's checked first to avoid a
+ * full scan across every registered board.
+ */
+function findBoardForRow(table, rowId, hintBoardId = null) {
+  if (!ROW_OWNER_TABLES.has(table)) throw new Error(`unsupported owner table: ${table}`);
+  const probe = `SELECT 1 FROM ${table} WHERE id = ?`;
+  if (hintBoardId) {
+    const hint = getBoardByRegistryId(hintBoardId);
+    if (hint) {
+      const db = openBoardDb(hint);
+      if (db.prepare(probe).get(rowId)) return { board: hint, db };
+    }
+  }
+  for (const row of listBoards()) {
+    if (hintBoardId && row.id === hintBoardId) continue;
+    const db = openBoardDb(row);
+    if (db.prepare(probe).get(rowId)) return { board: row, db };
+  }
+  return null;
+}
+
+export const findBoardForTicket = (ticketId, hintBoardId = null) =>
+  findBoardForRow("tickets", ticketId, hintBoardId);
+export const findBoardForState = (stateId, hintBoardId = null) =>
+  findBoardForRow("states", stateId, hintBoardId);
+export const findBoardForBoardEntry = (entryId, hintBoardId = null) =>
+  findBoardForRow("board_entries", entryId, hintBoardId);
+export const findBoardForRelation = (relationId, hintBoardId = null) =>
+  findBoardForRow("relations", relationId, hintBoardId);
+
+/** Sync a per-board DB's single boards-row into the registry. Idempotent. */
+export function syncRegistryFromBoardDb(boardRow, db) {
+  const b = db.prepare("SELECT * FROM boards LIMIT 1").get();
+  if (!b) return;
+
+  const reg = getRegistry();
+  const t = now();
+  const existing = reg.prepare("SELECT id FROM boards WHERE id = ?").get(b.id);
+  if (existing) {
+    reg
+      .prepare(
+        `UPDATE boards SET slug = ?, name = ?, db_path = ?, repo_url = ?, default_branch = ?, updated_at = ?
+         WHERE id = ?`
+      )
+      .run(b.slug, b.name, boardRow.db_path, b.repo_url || "", b.default_branch || "main", t, b.id);
+    return;
+  }
+
+  const existingPath = reg.prepare("SELECT id FROM boards WHERE db_path = ?").get(boardRow.db_path);
+  if (existingPath) {
+    reg
+      .prepare(
+        `UPDATE boards SET id = ?, slug = ?, name = ?, repo_path = ?, db_path = ?, repo_url = ?, default_branch = ?, updated_at = ?
+         WHERE id = ?`
+      )
+      .run(
+        b.id,
+        b.slug,
+        b.name,
+        boardRow.repo_path,
+        boardRow.db_path,
+        b.repo_url || "",
+        b.default_branch || "main",
+        t,
+        existingPath.id
+      );
+    return;
+  }
+
+  insertBoard({
+    id: b.id,
+    slug: b.slug,
+    name: b.name,
+    repo_path: boardRow.repo_path,
+    db_path: boardRow.db_path,
+    repo_url: b.repo_url || "",
+    default_branch: b.default_branch || "main",
+    last_active_at: t,
+    created_at: t,
+    updated_at: t
+  });
+}

package/src/core/relations.js

@@ -0,0 +1,163 @@
+import { boardById, childTicketsFor, relationRows, ticketById, unresolvedBlockers } from "./queries.js";
+import { tx } from "./db.js";
+import { requireBoardAccess, requirePermission } from "./auth.js";
+import { recordEvent } from "./events.js";
+import { httpError, id, now, requiredString } from "./util.js";
+
+export function createRelation(body, ctx) {
+  const { db, board, actor } = ctx;
+  const sourceId = requiredString(body.source_ticket_id, "source_ticket_id");
+  const source = ticketById(db, sourceId);
+  if (!source || source.board_id !== board.id) throw httpError(404, "ticket_not_found");
+
+  const target = ticketById(db, requiredString(body.target_ticket_id, "target_ticket_id"));
+  // Relations are only meaningful within a single board's DB. Cross-board
+  // relations are not supported by the schema (foreign keys live in this DB
+  // only) and would invent silent invariants.
+  if (!target || target.board_id !== board.id) throw httpError(404, "ticket_not_found");
+
+  requireBoardAccess(actor, boardById(db, source.board_id));
+  requirePermission(actor, "write");
+
+  if (source.id === target.id) throw httpError(400, "relation_self");
+  if (source.parent_ticket_id === target.id || target.parent_ticket_id === source.id) {
+    throw httpError(400, "relation_redundant_with_parent");
+  }
+
+  const relationType = body.type || "relates_to";
+  // Hierarchy is stored on the ticket row (parent_ticket_id), not in the
+  // relations table. The `child_of` / `parent_of` types only appear as
+  // read-only synthetic entries in getTicketRelations output — pointing
+  // callers at the right write path keeps the two models disjoint.
+  if (relationType === "child_of" || relationType === "parent_of") {
+    throw httpError(400, "hierarchy_uses_parent_ticket_id");
+  }
+  // Blocker relations are meaningless against a target that's already in a
+  // done lane — the row would be a stale blocker on creation. Reject so
+  // callers fix the data instead of silently creating dead relations.
+  if (relationType === "blocked_by" && target.state_role === "done") {
+    throw httpError(400, "blocker_target_already_done");
+  }
+  if (relationType === "blocks" && source.state_role === "done") {
+    throw httpError(400, "blocker_source_already_done");
+  }
+  const existing = db
+    .prepare("SELECT * FROM relations WHERE source_ticket_id = ? AND target_ticket_id = ? AND type = ?")
+    .get(source.id, target.id, relationType);
+  // Don't silently 201 on a no-op: an INSERT OR IGNORE that hit the UNIQUE
+  // constraint would have returned the pre-existing row, hiding from the
+  // caller that nothing was created.
+  if (existing) throw httpError(409, "relation_exists");
+
+  const relationId = id();
+  return tx(db, () => {
+    db.prepare(
+      "INSERT INTO relations (id, source_ticket_id, target_ticket_id, type, created_at) VALUES (?, ?, ?, ?, ?)"
+    ).run(relationId, source.id, target.id, relationType, now());
+    recordEvent(db, source.board_id, "relation_created", source.id, actor.name, {
+      target_ticket_id: target.id,
+      type: relationType
+    });
+    return db.prepare("SELECT * FROM relations WHERE id = ?").get(relationId);
+  });
+}
+
+export function deleteRelation(relationId, ctx) {
+  const { db, board, actor } = ctx;
+  const row = db.prepare("SELECT * FROM relations WHERE id = ?").get(relationId);
+  if (!row) throw httpError(404, "relation_not_found");
+  const source = ticketById(db, row.source_ticket_id);
+  const target = ticketById(db, row.target_ticket_id);
+  // Relation must live in the resolved board (sanity check — same DB by
+  // definition since router resolved this board, but keep the assertion).
+  if (source && source.board_id !== board.id) throw httpError(404, "relation_not_found");
+  if (source) requireBoardAccess(actor, boardById(db, source.board_id));
+  if (target) requireBoardAccess(actor, boardById(db, target.board_id));
+  requirePermission(actor, "write");
+  return tx(db, () => {
+    db.prepare("DELETE FROM relations WHERE id = ?").run(relationId);
+    recordEvent(db, source?.board_id || board.id, "relation_deleted", row.source_ticket_id, actor.name, {
+      target_ticket_id: row.target_ticket_id,
+      type: row.type
+    });
+    return { ok: true };
+  });
+}
+
+export function getTicketRelations(ticketId, ctx) {
+  const { db, board, actor } = ctx;
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  const compactOther = (other) => other && {
+    id: other.id,
+    number: other.number,
+    title: other.title,
+    type: other.type,
+    state_id: other.state_id,
+    state_name: other.state_name,
+    state_role: other.state_role,
+    parent_ticket_id: other.parent_ticket_id
+  };
+
+  const relations = relationRows(db, ticketId).map((row) => ({
+    id: row.id,
+    type: row.type,
+    direction: row.direction,
+    source: "relation",
+    other_ticket: compactOther(row.other_ticket)
+  }));
+
+  // Hierarchy is the other relationship model in the system. We don't store
+  // it in the `relations` table (parent_ticket_id is a column on the ticket
+  // row, kept disjoint from peer relations), but agents asking "what's linked
+  // to this ticket?" want a single answer. Synthesize read-only `child_of` /
+  // `parent_of` entries here. Marked source='hierarchy' so callers know they
+  // can't delete via DELETE /api/relations/:id; mutate via PATCH on the
+  // ticket's parent_ticket_id instead.
+  if (ticket.parent_ticket_id) {
+    const parent = ticketById(db, ticket.parent_ticket_id);
+    if (parent && !parent.archived_at) {
+      relations.push({
+        id: null,
+        type: "child_of",
+        direction: "outgoing",
+        source: "hierarchy",
+        other_ticket: compactOther(parent)
+      });
+    }
+  }
+  for (const child of childTicketsFor(db, ticketId)) {
+    relations.push({
+      id: null,
+      type: "parent_of",
+      direction: "outgoing",
+      source: "hierarchy",
+      other_ticket: compactOther(child)
+    });
+  }
+
+  return { ticket_id: ticket.id, relations };
+}
+
+export function getTicketBlockers(ticketId, ctx) {
+  const { db, board, actor } = ctx;
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  requireBoardAccess(actor, boardById(db, ticket.board_id));
+  const blockers = unresolvedBlockers(db, ticketId).map((row) => ({
+    id: row.id,
+    number: row.number,
+    title: row.title,
+    type: row.type,
+    state_id: row.state_id,
+    state_name: row.state_name,
+    state_role: row.state_role,
+    via_epic_id: row.via_epic_id || null
+  }));
+  return {
+    ticket_id: ticket.id,
+    can_start: blockers.length === 0,
+    blockers
+  };
+}