@worca/app 0.0.1

package/src/core/plugins-lock.mjs

@@ -0,0 +1,49 @@
+// src/core/plugins-lock.mjs
+// Plugin on-disk layout roots + plugins.lock.json (plugin spec §5). The lock is
+// a diffable FILE, deliberately NOT a worca-cc.db table: the shared-DB
+// cross-branch user_version stamping is a recorded hazard (db.mjs
+// reconcileSchema), and the plugin layer is machine-global like ~/.worca-cc/agents.
+// Lock shape: { [name]: { repo, subdir, pinnedSha, version, enabled,
+// installedAt, linked?: true, ...unknown keys preserved verbatim } }.
+// Sync IO mirrors settings.mjs: reads never throw; write is temp+rename atomic
+// (the settings.mjs:89-92 idiom, sync variant).
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { worcaHome } from './projects.mjs';
+
+/** Anti-traversal guard: a plugin name is a bare kebab dir stem, never a path. */
+export const DIR_NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+function safeName(name) {
+  const n = String(name ?? '');
+  if (!DIR_NAME_RE.test(n)) throw new Error(`invalid plugin name "${n}"`);
+  return n;
+}
+
+export function pluginsRoot() { return join(worcaHome(), 'plugins'); }
+export function pluginDir(name) { return join(pluginsRoot(), safeName(name)); }
+export function pluginCurrentDir(name) { return join(pluginDir(name), 'current'); }
+export function pluginDataDir(name) { return join(pluginDir(name), 'data'); }
+export function pluginsLockFile() { return join(pluginsRoot(), 'plugins.lock.json'); }
+
+/** Read the lock; missing/corrupt/non-object -> {}. Entries are NOT normalized:
+ *  unknown keys written by newer worca-cc versions survive read-modify-write cycles. */
+export function readPluginsLock() {
+  try {
+    const v = JSON.parse(readFileSync(pluginsLockFile(), 'utf8'));
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Atomic write (temp+rename). Creates the plugins root on first use. */
+export function writePluginsLock(lock) {
+  const file = pluginsLockFile();
+  mkdirSync(pluginsRoot(), { recursive: true });
+  const tmp = `${file}.${randomBytes(4).toString('hex')}.tmp`;
+  writeFileSync(tmp, JSON.stringify(lock ?? {}, null, 2) + '\n', 'utf8');
+  renameSync(tmp, file);
+  return lock ?? {};
+}

package/src/core/preflight-node.mjs

@@ -0,0 +1,122 @@
+// src/core/preflight-node.mjs  (FINAL)
+// Runtime preflight for the node:sqlite backend. Called once at each entry point
+// (src/cli/worca-cc.mjs, ui/server.mjs) BEFORE any DB is opened. Guarantees the
+// process is on a Node with a FLAGLESS node:sqlite (>= 22.13.0) and that the module
+// actually imports, then fails fast with an actionable message instead of letting a
+// cryptic error surface deep inside db.mjs.
+//
+// Pure, dependency-free (semver-ish compare is hand-rolled — no new dependency,
+// matching the project's "Node built-ins + express + ws" rule). Deliberately does
+// NOT import db.mjs: the version check must not open the DB.
+//
+// NOTE: distinct from src/core/preflight.mjs (optional-TOOL detection, detectTools()).
+// This is the Node-RUNTIME preflight.
+
+import process from 'node:process';
+import { createRequire } from 'node:module';
+
+/** Minimum Node that ships a flagless node:sqlite (v22 LTS 'Jod' backport / v23.4+). */
+export const MIN_NODE = '22.13.0';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Parse a version string into [major, minor, patch] integers. Tolerant: ignores a
+ * leading "v", ignores any pre-release/build suffix, treats missing/non-numeric
+ * components as 0.
+ * @param {string} v
+ * @returns {[number, number, number]}
+ */
+function parse(v) {
+  const core = String(v).trim().replace(/^v/i, '').split(/[-+]/, 1)[0];
+  const [maj = '0', min = '0', pat = '0'] = core.split('.');
+  const n = (s) => {
+    const x = parseInt(s, 10);
+    return Number.isFinite(x) ? x : 0;
+  };
+  return [n(maj), n(min), n(pat)];
+}
+
+/**
+ * Compare two version strings numerically by major.minor.patch.
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function cmpVersions(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+/**
+ * Is `actual` (default: the running process's Node) >= MIN_NODE?
+ * @param {string} [actual=process.versions.node]
+ * @returns {boolean}
+ */
+export function meetsMinNode(actual = process.versions.node) {
+  return cmpVersions(actual, MIN_NODE) >= 0;
+}
+
+/**
+ * Confirm node:sqlite imports and exposes DatabaseSync. Returns null on success or a
+ * short error string on failure (never throws). node:sqlite is a builtin, so require
+ * resolves synchronously even in this ESM module — keeping preflight a plain sync
+ * call that matches the synchronous data layer.
+ * @returns {string | null}
+ */
+export function probeSqlite() {
+  try {
+    const mod = require('node:sqlite');
+    if (!mod || typeof mod.DatabaseSync !== 'function') {
+      return 'node:sqlite imported but DatabaseSync is missing';
+    }
+    return null;
+  } catch (err) {
+    return err && err.message ? err.message : String(err);
+  }
+}
+
+/**
+ * Full runtime preflight. If the Node version is too old OR node:sqlite cannot be
+ * loaded, print a clear, actionable message to stderr and exit non-zero (code 1).
+ * Otherwise return normally. Called once per entry point before opening the DB.
+ *
+ * Kept side-effecting (writes stderr, calls process.exit) on purpose: it is the
+ * single fail-fast gate. The pure helpers above are what the unit tests exercise.
+ *
+ * @param {{ exit?: (code:number)=>never, err?: (s:string)=>void }} [io] injectable
+ *   for tests; defaults to process.exit / process.stderr.write.
+ */
+export function preflightNode(io = {}) {
+  const exit = io.exit || ((c) => process.exit(c));
+  const err = io.err || ((s) => process.stderr.write(s));
+  const actual = process.versions.node;
+
+  if (!meetsMinNode(actual)) {
+    err(
+      `\nworca: Node ${actual} is too old.\n` +
+        `  Worca CC stores its state in SQLite via the built-in node:sqlite module,\n` +
+        `  which is only available (flag-free) on Node >= ${MIN_NODE}.\n` +
+        `  Please upgrade Node (e.g. \`nvm install --lts\` or use the bundled .nvmrc:\n` +
+        `  \`nvm use\`), then re-run.\n\n`
+    );
+    return exit(1);
+  }
+
+  const sqliteErr = probeSqlite();
+  if (sqliteErr) {
+    err(
+      `\nworca: the built-in node:sqlite module could not be loaded.\n` +
+        `  (${sqliteErr})\n` +
+        `  Worca CC requires Node >= ${MIN_NODE} with node:sqlite available.\n` +
+        `  You are on Node ${actual}. Upgrade Node (\`nvm use\` with the bundled\n` +
+        `  .nvmrc) and re-run.\n\n`
+    );
+    return exit(1);
+  }
+}

package/src/core/preflight.mjs

@@ -0,0 +1,341 @@
+// src/core/preflight.mjs
+// Detect optional knowledge-graph tooling in the user's environment so agents
+// can be told to use it. Two tools are supported:
+//   - graphify              (github.com/safishamsi/graphify)
+//   - code-review-graph     (github.com/tirth8205/code-review-graph)
+//
+// Rule: if BOTH are present, prefer graphify.
+//
+// Every probe is wrapped so that a missing binary, missing file, or failing
+// subprocess resolves to `false` and NEVER throws.
+
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { constants as FS } from 'node:fs';
+
+/**
+ * Run a command and resolve to its trimmed stdout, or null on any failure.
+ * Times out defensively so a hung probe can't block preflight.
+ */
+function execSafe(cmd, args, { timeout = 4000 } = {}) {
+  return new Promise((resolveP) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch {
+      resolveP(null);
+      return;
+    }
+    let out = '';
+    let settled = false;
+    const done = (val) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveP(val);
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+      done(null);
+    }, timeout);
+
+    child.stdout?.on('data', (d) => {
+      out += d.toString();
+    });
+    // Drain stderr so the child can't block on a full pipe.
+    child.stderr?.on('data', () => {});
+    child.on('error', () => done(null));
+    child.on('close', (code) => done(code === 0 ? out.trim() : null));
+  });
+}
+
+/** True if `which <name>` resolves to a path. */
+async function whichOk(name) {
+  const out = await execSafe('which', [name]);
+  return typeof out === 'string' && out.length > 0;
+}
+
+/** True if a filesystem path is accessible. */
+async function pathExists(p) {
+  try {
+    await access(p, FS.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True if `pipx list` output mentions `needle` (case-insensitive). */
+async function pipxMentions(needle) {
+  const out = await execSafe('pipx', ['list']);
+  return !!out && out.toLowerCase().includes(needle.toLowerCase());
+}
+
+/** True if `pip show <pkg>` (or pip3) reports an installed package. */
+async function pipShows(pkg) {
+  for (const pip of ['pip', 'pip3']) {
+    const out = await execSafe(pip, ['show', pkg]);
+    if (out && out.toLowerCase().includes('name:')) return true;
+  }
+  return false;
+}
+
+/**
+ * Detect graphify and HOW it is installed. Returns:
+ *   { found: boolean, kind: 'cli'|'skill'|'output-cached'|null }
+ *
+ * The `kind` controls the instruction wording so the agent picks the right
+ * dispatch mechanism (Bash CLI vs Skill tool vs read cached output). Priority:
+ *   1. `which graphify`            → 'cli'   (executable on PATH)
+ *   2. pipx / pip shows graphify   → 'cli'   (importable / on PATH soon)
+ *   3. ~/.claude/skills/graphify/  → 'skill' (Claude Code skill, no binary)
+ *   4. <projectDir>/graphify-out   → 'output-cached' (graph exists from prior run)
+ *
+ * Ordering matters: a host with both a CLI and a skill prefers the CLI because
+ * an agent can drive it directly. An `output-cached` win is the weakest — it
+ * means a graph exists but we don't know how it was built.
+ */
+async function detectGraphify(projectDir) {
+  if (await whichOk('graphify')) return { found: true, kind: 'cli' };
+  if (await pipxMentions('graphify')) return { found: true, kind: 'cli' };
+  if (await pipShows('graphify')) return { found: true, kind: 'cli' };
+  if (await pathExists(join(homedir(), '.claude', 'skills', 'graphify', 'SKILL.md'))) {
+    return { found: true, kind: 'skill' };
+  }
+  if (await pathExists(join(projectDir, 'graphify-out'))) {
+    return { found: true, kind: 'output-cached' };
+  }
+  return { found: false, kind: null };
+}
+
+/**
+ * Detect code-review-graph. ANY of:
+ *  - `which code-review-graph`
+ *  - pipx list / pip show code-review-graph mentions it
+ *  - a cloned dir named code-review-graph reachable (cwd or home)
+ */
+async function detectCodeReviewGraph(projectDir) {
+  const checks = await Promise.all([
+    whichOk('code-review-graph'),
+    pipxMentions('code-review-graph'),
+    pipShows('code-review-graph'),
+    pathExists(join(projectDir, 'code-review-graph')),
+    pathExists(join(homedir(), 'code-review-graph')),
+  ]);
+  return checks.some(Boolean);
+}
+
+/**
+ * Build the human-readable instruction injected into agent system prompts.
+ * The wording is branched by `kind` so the agent uses the right dispatch
+ * mechanism (Bash CLI, Skill tool, or simply reading cached output).
+ */
+export function buildInstruction(tool, kind) {
+  if (tool === 'graphify') {
+    if (kind === 'skill') {
+      return (
+        'A code knowledge-graph SKILL named "graphify" is available. It is a ' +
+        'Claude Code skill, NOT a shell command — do NOT try to run it via Bash. ' +
+        'BEFORE analyzing or planning, invoke it via the `Skill` tool, e.g. ' +
+        '`Skill(skill: "graphify", args: "<your question about the code>")`. ' +
+        'Use its output to ground your work in real codebase structure rather ' +
+        'than assumptions. A cached graph may already exist at ' +
+        'graphify-out/ — consult it if present.'
+      );
+    }
+    if (kind === 'output-cached') {
+      return (
+        'A graphify knowledge graph has ALREADY been built for this project at ' +
+        'graphify-out/. No graphify binary or Skill was detected, so ' +
+        'do NOT try to invoke or rebuild it — just READ the cached output. BEFORE ' +
+        'analyzing or planning, read graphify-out/GRAPH_REPORT.md for the overview, ' +
+        'then open graphify-out/graph.json to trace specific symbols and their ' +
+        'edges, so your understanding is grounded in real structure rather than ' +
+        'assumptions.'
+      );
+    }
+    // 'cli' (or unspecified, treated as CLI for safety).
+    // `graphify query` does literal token-matching to pick BFS start nodes, so a
+    // natural-language PHRASE matches almost nothing (only stray tokens, often in
+    // test files) and yields noise — which makes agents give up and fall back to
+    // grep. The instruction therefore teaches one-concept-at-a-time querying and
+    // points at the already-built graph instead of a nonexistent build command.
+    return (
+      'A code knowledge-graph CLI named "graphify" is available on PATH, and a ' +
+      'graph has ALREADY been built at graphify-out/ (do NOT rebuild). ' +
+      'BEFORE analyzing or planning, ground yourself in the real codebase: first ' +
+      'read graphify-out/GRAPH_REPORT.md for the overview, then query the graph ' +
+      'via Bash. Query ONE concept at a time — a single symbol or term, NOT a ' +
+      'natural-language phrase (phrases match almost nothing and return noise). ' +
+      'Useful commands:\n' +
+      '  graphify query "<concept>"    # BFS neighborhood of one term, e.g. "effort"\n' +
+      '  graphify explain "<symbol>"   # one node plus its direct connections\n' +
+      '  graphify path "<A>" "<B>"     # how two symbols are connected\n' +
+      'Run several single-concept queries rather than one long one. Use ' +
+      'Glob/Grep/Read only for what the graph cannot answer.'
+    );
+  }
+  if (tool === 'code-review-graph') {
+    return (
+      'A code-analysis CLI named "code-review-graph" is available in this ' +
+      'environment. Run it via Bash to build a graph of the codebase and inform ' +
+      'your analysis, planning, and review with its output rather than relying ' +
+      'on assumptions about code structure.'
+    );
+  }
+  return '';
+}
+
+/**
+ * Instruction for agents when a fresh AST graph has been built INSIDE the
+ * current worktree at ./graphify-out/. Paths are cwd-relative (agents run with
+ * cwd=worktree); the AST-only nature is called out so agents calibrate.
+ */
+export function worktreeGraphInstruction() {
+  return (
+    'A code knowledge-graph CLI named "graphify" is available, and a fresh graph ' +
+    'for THIS worktree has been built at graphify-out/ (relative to your working ' +
+    'directory). It is an AST-only structural graph (symbols, files, and their ' +
+    'structural relationships) with NO semantic/inferred edges. BEFORE analyzing ' +
+    'or planning, ground yourself in the real code: first read ' +
+    'graphify-out/GRAPH_REPORT.md for the overview, then query the graph via Bash. ' +
+    'Query ONE concept at a time — a single symbol or term, NOT a natural-language ' +
+    'phrase (phrases match almost nothing and return noise). Useful commands:\n' +
+    '  graphify query "<concept>"    # BFS neighborhood of one term\n' +
+    '  graphify explain "<symbol>"   # one node plus its direct connections\n' +
+    '  graphify path "<A>" "<B>"     # how two symbols are connected\n' +
+    'Run several single-concept queries. Use Glob/Grep/Read for anything the ' +
+    'graph cannot answer.'
+  );
+}
+
+/**
+ * Run `graphify update <dir>` headlessly to build/refresh an AST graph at
+ * <dir>/graphify-out/. Spawned with cwd=cwd so graphify's stray cwd-relative
+ * manifest write lands inside the same worktree, never the main repo. Bounded
+ * by timeoutMs (macOS has no timeout(1)); on overrun the child is SIGKILLed.
+ * Never throws. Resolves { ok, code, timedOut, stderr }.
+ */
+export function runGraphifyUpdate({ dir, cwd, timeoutMs = 120000 } = {}) {
+  return new Promise((resolveP) => {
+    let child;
+    try {
+      child = spawn('graphify', ['update', dir], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      resolveP({ ok: false, code: -1, timedOut: false, stderr: err.message });
+      return;
+    }
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+    const done = (val) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveP(val);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        /* ignore */
+      }
+      done({ ok: false, code: -1, timedOut: true, stderr: 'graphify update timed out' });
+    }, timeoutMs);
+    child.stdout?.on('data', () => {});
+    child.stderr?.on('data', (d) => {
+      stderr += d.toString();
+    });
+    child.on('error', (err) => done({ ok: false, code: -1, timedOut, stderr: stderr || err.message }));
+    child.on('close', (code) => done({ ok: code === 0, code: code ?? -1, timedOut, stderr }));
+  });
+}
+
+/**
+ * Detect optional tooling for a project directory.
+ * @param {string} projectDir
+ * @returns {Promise<{
+ *   graphify:boolean,
+ *   codeReviewGraph:boolean,
+ *   tool:('graphify'|'code-review-graph'|null),
+ *   kind:('cli'|'skill'|'output-cached'|null),
+ *   instruction:string,
+ * }>}
+ */
+export async function detectTools(projectDir) {
+  const dir = projectDir || process.cwd();
+  let graphifyInfo = { found: false, kind: null };
+  let codeReviewGraph = false;
+  try {
+    [graphifyInfo, codeReviewGraph] = await Promise.all([
+      detectGraphify(dir),
+      detectCodeReviewGraph(dir),
+    ]);
+  } catch {
+    // Absolute belt-and-suspenders: detection must never throw.
+    graphifyInfo = { found: false, kind: null };
+    codeReviewGraph = false;
+  }
+  // BOTH installed => prefer graphify.
+  const tool = graphifyInfo.found ? 'graphify' : codeReviewGraph ? 'code-review-graph' : null;
+  const kind = tool === 'graphify' ? graphifyInfo.kind : tool === 'code-review-graph' ? 'cli' : null;
+  return {
+    graphify: graphifyInfo.found,
+    codeReviewGraph,
+    tool,
+    kind,
+    instruction: buildInstruction(tool, kind),
+  };
+}
+
+/**
+ * Detect tooling for EACH project in a workspace, in parallel. A trivial
+ * Promise.all over detectTools, returning a Map keyed by projectDir so the
+ * orchestrator can grant each member its own per-project graph instruction.
+ * detectTools never throws, so this never throws. Member order is irrelevant
+ * (the Map is keyed by dir); the caller iterates by sorted projectKey.
+ * @param {string[]} projectDirs
+ * @returns {Promise<Map<string,{tool,kind,instruction}>>}
+ */
+export async function detectToolsPerProject(projectDirs) {
+  const dirs = Array.isArray(projectDirs) ? projectDirs : [];
+  const infos = await Promise.all(dirs.map((dir) => detectTools(dir)));
+  const map = new Map();
+  dirs.forEach((dir, i) => map.set(dir, infos[i]));
+  return map;
+}
+
+/**
+ * §8.18 / Phase-0 gate V5: parse `claude --help` ONCE per run and assert that this
+ * build advertises `--mcp-config`. Version drift, not a CLI unknown — V5 PASSED on
+ * the development machine (`claude --help` line 113,
+ * `docs/run-root-verification.md`), so this ships as insurance for OTHER machines.
+ *
+ * On absence the caller degrades gracefully (skip the flag, warn loudly naming the
+ * required version >= 2.1.220) rather than failing the run: R1(a)/(c) still hold via
+ * the cwd and ancestor mechanisms, and R1(b) is reported as DEGRADED.
+ *
+ * Deliberately NO `addDir` field: `--add-dir` is not probed because no shipped
+ * feature uses it (§5.3 — it needs `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`
+ * to carry memory at all, E2), and a probe field no consumer reads is dead weight.
+ *
+ * Never throws: a missing binary / hung process resolves to
+ * `{ mcpConfig: false, version: null }`, which the caller treats the same as an old
+ * CLI. (A machine with no `claude` on PATH fails loudly at the first node anyway.)
+ * @param {string} [bin] the claude binary (defaults to `claude`)
+ * @returns {Promise<{mcpConfig: boolean, version: string|null}>}
+ */
+export async function probeClaudeCapabilities(bin = 'claude') {
+  const exe = bin && String(bin).trim() ? String(bin).trim() : 'claude';
+  const help = await execSafe(exe, ['--help'], { timeout: 8000 });
+  const raw = await execSafe(exe, ['--version'], { timeout: 8000 });
+  const version = raw ? (/(\d+\.\d+\.\d+)/.exec(raw)?.[1] ?? raw.split(/\s+/)[0] ?? null) : null;
+  return { mcpConfig: !!help && help.includes('--mcp-config'), version };
+}

package/src/core/projects.mjs

@@ -0,0 +1,157 @@
+// src/core/projects.mjs
+// Named project registry: a small persistent list of { name, path } entries the
+// web UI uses to populate its project dropdown.
+//
+// node:sqlite migration: now persisted in the `projects` table; path helpers vestigial.
+//
+// Reads never throw: a fresh/empty DB yields an empty list. Writes validate then
+// persist inside a single db.mjs tx(). Each row is keyed by projectKey(path)
+// (store.mjs), so every worktree of a repo maps to one row.
+
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getWorcaRoot, defaultRoot } from './settings.mjs';
+import { getDb, prepare, tx } from './db.mjs';
+import { projectKey } from './store.mjs';
+
+/**
+ * Absolute path to the .worca-cc data directory. Base resolution precedence:
+ *   1. WORCA_HOME env (non-empty)  — tests/smoke isolation + CLI override
+ *   2. persisted Settings root        — the user-chosen "Worca CC root folder"
+ *   3. defaultRoot()                  — the OS home
+ * Read fresh every call, so a saved root applies to new operations w/o restart.
+ */
+export function worcaHome() {
+  const env = process.env.WORCA_HOME;
+  if (!(env && env.trim()) && process.env.NODE_TEST_CONTEXT &&
+      !process.env.WORCA_TEST_ALLOW_HOME_FALLBACK) {
+    // Under the node:test runner the real ~/.worca-cc must be unreachable: a test
+    // (or a fire-and-forget write outliving its teardown) that resolves the home
+    // with no WORCA_HOME set would silently pollute the user's real store.
+    // WORCA_TEST_ALLOW_HOME_FALLBACK opts out for tests that exercise the
+    // settings/home fallback tiers and sandbox HOME/USERPROFILE themselves.
+    throw new Error(
+      'worcaHome(): WORCA_HOME is unset under the node:test runner — ' +
+      'tests must never touch the real ~/.worca-cc (use test/helpers/temp-home.mjs#useTempHome)'
+    );
+  }
+  const base = env && env.trim() ? env : (getWorcaRoot() || defaultRoot());
+  return join(resolve(base), '.worca-cc');
+}
+
+/**
+ * Absolute path to the (legacy) registry file.
+ *
+ * VESTIGIAL (node:sqlite migration §0.6): the registry now lives in the `projects`
+ * table, not this JSON file. This export is retained only for backward
+ * import-compatibility (test imports); it no longer describes where data lives.
+ */
+export function projectsFile() {
+  return join(worcaHome(), 'projects.json');
+}
+
+/**
+ * Expand a leading ~ and resolve to an absolute path. Mirrors the web server's
+ * historical resolveProjectDir so the registry and runs agree on a path.
+ * @param {string} input
+ * @returns {string|null} absolute path, or null for empty/non-string input
+ */
+export function normalizeProjectPath(input) {
+  if (!input || typeof input !== 'string' || !input.trim()) return null;
+  let p = input.trim();
+  if (p.startsWith('~')) p = join(process.env.HOME || process.env.USERPROFILE || '', p.slice(1));
+  return resolve(p);
+}
+
+/** True when the path exists and is a directory. */
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the raw registry rows from the DB, ordered by creation then name for a
+ * stable list. Never throws (a fresh DB simply has no rows). The DB call is
+ * synchronous (node:sqlite); we return the plain array.
+ * @returns {Array<{key:string, name:string, path:string}>}
+ */
+function readRows() {
+  getDb(); // ensure the singleton is open + migrated before preparing
+  return prepare(
+    'SELECT key, name, path FROM projects ORDER BY created_at, name'
+  ).all();
+}
+
+/**
+ * List saved projects, each annotated with a runtime `exists` flag (true when the
+ * path is an existing directory). The flag is computed, never persisted. Reads
+ * from the projects table; never throws.
+ * @returns {Promise<Array<{name:string, path:string, exists:boolean}>>}
+ */
+export async function listProjects() {
+  return readRows().map((e) => ({ name: e.name, path: e.path, exists: isDir(e.path) }));
+}
+
+/**
+ * Number of registered projects (missing-on-disk rows included, matching the
+ * Projects list + its sidebar count). Cheap COUNT(*); never throws.
+ * Uses the bare `prepare` already imported at projects.mjs:14.
+ * @returns {number}
+ */
+export function countProjects() {
+  getDb(); // ensure the singleton is open + migrated before preparing
+  const row = prepare('SELECT COUNT(*) AS n FROM projects').get();
+  return row ? Number(row.n) : 0;
+}
+
+/**
+ * Add a project. Validates and persists to the projects table. Returns the
+ * updated annotated list. Keyed by projectKey(path) (store.mjs), so every worktree
+ * of a repo maps to one row. Name uniqueness is case-insensitive (checked here AND
+ * backed by the NOCASE unique index).
+ * @param {{name:string, path:string}} input
+ * @throws {Error} on empty name/path, a path that exists but is not a directory,
+ *   a duplicate name (case-insensitive), or a duplicate path/key.
+ */
+export async function addProject(input) {
+  const name = (input && typeof input.name === 'string' ? input.name : '').trim();
+  if (!name) throw new Error('project name is required');
+  const path = normalizeProjectPath(input && input.path);
+  if (!path) throw new Error('project path is required');
+  // A path that exists must be a directory; a non-existent path is allowed (the run
+  // creates it), matching the orchestrator's mkdir-on-run behavior.
+  if (existsSync(path) && !isDir(path)) throw new Error('path is not a directory');
+
+  const key = projectKey(path);
+  const createdAt = new Date().toISOString();
+  tx(() => {
+    // Case-insensitive duplicate-name guard (matches the legacy check + the index).
+    const clash = prepare('SELECT 1 FROM projects WHERE name = ? COLLATE NOCASE').get(name);
+    if (clash) throw new Error(`a project named "${name}" already exists`);
+    // Same path -> same key -> PK collision; report it cleanly rather than crashing.
+    const samePath = prepare('SELECT 1 FROM projects WHERE key = ?').get(key);
+    if (samePath) throw new Error('this project path is already registered');
+    prepare(
+      'INSERT INTO projects (key, name, path, created_at) VALUES (?, ?, ?, ?)'
+    ).run(key, name, path, createdAt);
+  });
+  return listProjects();
+}
+
+/**
+ * Remove a project by name (case-insensitive). Absent name is a no-op.
+ * @param {string} name
+ * @returns {Promise<Array<{name:string, path:string, exists:boolean}>>}
+ */
+export async function removeProject(name) {
+  const key = (typeof name === 'string' ? name : '').trim();
+  if (key) {
+    tx(() => {
+      prepare('DELETE FROM projects WHERE name = ? COLLATE NOCASE').run(key);
+    });
+  }
+  return listProjects();
+}