residoo 0.1.0 → 0.2.0

package/src/sources/copilot-cli.js

@@ -0,0 +1,300 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * GitHub Copilot CLI — the standalone `copilot` agentic terminal tool
+ * (npm package `@github/copilot`; also reachable as `gh copilot` once
+ * installed). NOT the VS Code "Copilot Chat" panel — see copilot-chat.js for
+ * that genuinely different product with a genuinely different storage
+ * format. Also NOT the older `gh-copilot` `gh` CLI extension (the
+ * `suggest`/`explain` command-line-suggestion tool) — that predecessor is
+ * unrelated and out of scope here; this adapter targets the current agentic
+ * CLI whose own docs are cited below.
+ *
+ * VERIFICATION STATUS (read this before trusting anything below):
+ * multi-source-corroborated-but-UNVERIFIED against a real install. Copilot
+ * CLI is not installed on the machine this adapter was built on (checked:
+ * no ~/.copilot, no `copilot` on PATH, no `gh extension list` entry, no
+ * Homebrew formula/cask installed under that name — the one local
+ * "copilot.rb" formula present is an unrelated AWS tool, `aws/copilot-cli`).
+ * Corroborating sources, most authoritative first:
+ *
+ *  1. Official GitHub Docs, "GitHub Copilot CLI configuration directory"
+ *     (docs.github.com/en/copilot/reference/copilot-cli-reference/
+ *     cli-config-dir-reference), fetched 2026-09-02. States plainly: default
+ *     location is `~/.copilot` (`$HOME/.copilot`), overridable via the
+ *     `COPILOT_HOME` environment variable. Its own directory-listing table
+ *     names, verbatim: `session-state/` ("Session history and workspace
+ *     data"), `command-history-state/` ("Command history data"), `logs/`
+ *     ("Session log files", named `process-{timestamp}-{pid}.log`), and
+ *     `session-store.db` (File — "SQLite database for cross-session data").
+ *     Separately also names `config.json` ("automatically managed
+ *     application state including authentication"), `mcp-secrets/`, and
+ *     `mcp-oauth-config/` — this tool's OWN credential/token storage, not
+ *     conversation content; deliberately excluded here, same reasoning
+ *     claude-code.js's scope never reaches `~/.claude.json`.
+ *  2. Official GitHub Docs, "About GitHub Copilot CLI session data"
+ *     (docs.github.com/en/copilot/concepts/agents/copilot-cli/chronicle),
+ *     fetched 2026-09-02. States each session is persisted as "a set of
+ *     files in the `~/.copilot/session-state/` directory," recording "your
+ *     prompts, Copilot's responses, the tools that were used, and details of
+ *     files that were modified" — i.e. exactly the transcript content this
+ *     scanner exists to check, confirmed as living there by GitHub's own
+ *     docs, not just inferred.
+ *  3. jonmagic.com/posts/github-copilot-session-search-and-resume-cli/ — a
+ *     real practitioner's own inspection of actual files on their machine,
+ *     independent of GitHub's docs. Confirms the concrete shape:
+ *     `~/.copilot/session-state/<uuid>/` per session, containing
+ *     `workspace.yaml` (metadata) and `events.jsonl` (a newline-delimited
+ *     JSON event stream — quotes real event lines: `session.start`,
+ *     `user.message`, `assistant.turn_start`, `tool.execution_start` with
+ *     its `arguments`, `tool.execution_complete`, `session.shutdown`), and
+ *     explicitly notes "some sessions have additional files such as
+ *     `session.db`, plans, checkpoints, or VS Code metadata" that "vary by
+ *     Copilot version" — i.e. confirms the file set is NOT a fixed, safely
+ *     allow-listable list, which is why files() below does not hard-code one
+ *     (same reasoning cursor.js gives for not allow-listing its own row
+ *     keys).
+ *  4. dfberry.github.io/2026-04-16-session-storage-decision-guide —
+ *     independently corroborates `session-state/<id>/events.jsonl` and
+ *     `session-store.db`, and adds the SQLite schema: seven tables
+ *     including "sessions, turns, checkpoints, session_files, session_refs"
+ *     plus an FTS5 search index, and warns not to delete the `.db-wal` file
+ *     while Copilot is running (confirming it's a live, WAL-mode SQLite
+ *     file, not an inert export).
+ *
+ * `session-store.db`'s ROW-LEVEL schema (which column of which table, if
+ * any, holds raw prompt/response text vs. only derived search-index data) is
+ * corroborated by exactly ONE of the sources above (#4) — short of this
+ * project's normal two-independent-source bar for a claim precise enough to
+ * write a SQL query against, unlike cursor.js's table/column shape, which
+ * had a real live install AND multiple agreeing write-ups behind it.
+ * Guessing at that schema is exactly the "SQLite schema drifted, bare
+ * except/continue swallowed it, tool reported a full scan as clean" failure
+ * this cluster's brief calls out by name. `session-store.db` is therefore
+ * DELIBERATELY NOT queried here — the actual prompts/responses/tool-args
+ * this scanner cares about are independently, solidly confirmed (sources
+ * #2–#4 agree) to live in `session-state/**`'s plain-text files regardless,
+ * so this is a named, bounded gap rather than a load-bearing one. If a
+ * future contributor confirms the exact table/column shape against a real
+ * install, add it then — with that verification.
+ *
+ * `command-history-state` has been reported in TWO conflicting shapes across
+ * the sources above and elsewhere: the official config-dir-reference table
+ * (#1) lists it as a DIRECTORY (`command-history-state/`), while several
+ * independent write-ups (inventivehq.com's own config-file breakdown;
+ * rajeevpentyala.com's "[Quick Tip] GitHub Copilot CLI | Get Prompt History")
+ * describe a single FILE, `command-history-state.json`, holding a
+ * `commandHistory` array of every prompt typed. Rather than guess which is
+ * current, this adapter checks for BOTH shapes and scans whichever is
+ * actually present — the same "don't pick a side, read what's really there"
+ * approach cursor.js takes for its own two-possible-storage-location
+ * uncertainty. This is real typed-prompt content (a very plausible place for
+ * a pasted secret to land) and is in scope.
+ *
+ * Deliberately excluded, named rather than silently skipped: `settings.json`,
+ * `config.json`, `lsp-config.json`, `mcp-config.json`,
+ * `permissions-config.json`, `mcp-oauth-config/`, `mcp-secrets/`,
+ * `agents/`, `skills/`, `instructions/`, `extensions/`, `hooks/`,
+ * `installed-plugins/`, `plugin-data/`, `ide/`, and `session-store.db`
+ * (discussed above). These are Copilot CLI's OWN configuration and
+ * credential/token storage, not user session transcripts — scanning and
+ * potentially surfacing THOSE would run against residoo's own purpose, and
+ * mirrors claude-code.js never reaching into `~/.claude/settings.json` or
+ * `~/.claude.json`.
+ */
+function copilotHome() {
+  const override = process.env.COPILOT_HOME;
+  if (override) return override; // per official docs; used as given, same trust level cursor.js gives XDG_CONFIG_HOME
+  return path.join(os.homedir(), ".copilot");
+}
+
+const ROOT = copilotHome();
+
+// Storage-class extensions this adapter knows are SQLite (or its WAL/SHM/
+// journal siblings) and deliberately does not treat as scannable text —
+// covers both the top-level session-store.db and any per-session
+// "session.db" jonmagic.com's inspection found inside session-state/<uuid>/.
+// Matched case-insensitively against the file's extension only.
+const BINARY_DB_EXTENSIONS = new Set([".db", ".db-wal", ".db-shm", ".db-journal", ".sqlite", ".sqlite3"]);
+
+// Bounds for readLines() — same values as claude-code.js. Not backed by a
+// real Copilot CLI transcript this tool was tested against (no install to
+// test with) — see the verification-status note above.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+// Recursion guard for walking session-state/ and command-history-state/ —
+// per-session subdirectories are one level deep in every source consulted,
+// but the cap (and symlink-cycle de-dup) exists purely to bound a
+// pathological or unexpectedly deep layout, same as windsurf.js's own walk.
+const MAX_WALK_DEPTH = 12;
+
+function id() { return "copilot-cli"; }
+function label() { return "GitHub Copilot CLI"; }
+
+function available() {
+  try { return fs.statSync(ROOT).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js's
+ * isDirFollowingSymlink/isFileFollowingSymlink — see that file's docstring
+ * for the full reasoning. Duplicated rather than imported, matching this
+ * project's "small, self-contained file" convention.
+ */
+function isKindFollowingSymlink(fullPath, dirent, checkFn) {
+  if (checkFn(dirent)) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return checkFn(fs.statSync(fullPath)); } catch { return false; }
+}
+const isDirFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isDirectory());
+const isFileFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isFile());
+
+function isBinaryDbFile(name) {
+  const ext = path.extname(name).toLowerCase();
+  return BINARY_DB_EXTENSIONS.has(ext);
+}
+
+/**
+ * Recursively yield { file, mtimeMs, sizeBytes, broken } for every file
+ * under `dir` EXCEPT ones recognized as SQLite-family by extension (see
+ * BINARY_DB_EXTENSIONS and the module docstring for why those are excluded
+ * rather than read as text). No further extension allow-listing is done —
+ * per jonmagic.com's own real inspection (cited above), the exact set of
+ * per-session files varies by Copilot CLI version, so this walks whatever is
+ * actually there, the same "don't hard-code a list likely to go stale"
+ * reasoning cursor.js applies to its own row keys.
+ *
+ * A dangling symlink (file or directory) is reported broken:true rather
+ * than silently skipped, matching claude-code.js's convention.
+ * `visitedRealDirs` de-dupes symlinked directories by resolved real path so
+ * a symlink cycle terminates instead of recursing forever.
+ */
+function* walkTextFiles(dir, depth, visitedRealDirs) {
+  if (depth > MAX_WALK_DEPTH) return;
+
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; } // this directory doesn't exist here — normal for an unused feature, not broken
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+
+    if (isDirFollowingSymlink(full, e)) {
+      if (e.isSymbolicLink()) {
+        let real;
+        try { real = fs.realpathSync(full); }
+        catch { yield { file: full, broken: true }; continue; }
+        if (visitedRealDirs.has(real)) continue;
+        visitedRealDirs.add(real);
+      }
+      yield* walkTextFiles(full, depth + 1, visitedRealDirs);
+      continue;
+    }
+
+    if (isBinaryDbFile(e.name)) continue; // known SQLite-family file — deliberately out of scope, see docstring
+
+    if (!isFileFollowingSymlink(full, e)) {
+      if (e.isSymbolicLink()) yield { file: full, broken: true };
+      continue;
+    }
+
+    let stat;
+    try { stat = fs.statSync(full); } catch { yield { file: full, broken: true }; continue; }
+    yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+/**
+ * Resolve the single-file shape of command-history-state
+ * (~/.copilot/command-history-state.json — see docstring for why both
+ * shapes are checked) into zero or one files() entries. Same lstat-based
+ * logic and broken-vs-absent convention as cursor.js's statIfPresent().
+ */
+function* statIfPresentFile(filePath) {
+  let lst;
+  try { lst = fs.lstatSync(filePath); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(filePath);
+      if (!st.isFile()) { yield { file: filePath, broken: true }; return; }
+      yield { file: filePath, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: filePath, broken: true };
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return;
+  yield { file: filePath, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every candidate transcript
+ * file this adapter knows how to find under $COPILOT_HOME (default
+ * ~/.copilot): every non-SQLite file under session-state/ and under
+ * command-history-state/ (if it exists as a directory), the single
+ * command-history-state.json file (if it exists instead, as a file), and
+ * every non-SQLite file under logs/.
+ */
+function* files() {
+  yield* walkTextFiles(path.join(ROOT, "session-state"), 0, new Set());
+  yield* walkTextFiles(path.join(ROOT, "command-history-state"), 0, new Set());
+  yield* statIfPresentFile(path.join(ROOT, "command-history-state.json"));
+  yield* walkTextFiles(path.join(ROOT, "logs"), 0, new Set());
+}
+
+/**
+ * Read one file as an array of raw text lines.
+ *
+ * Every format this adapter's files() can yield is real UTF-8 text by
+ * construction: `events.jsonl` is one JSON record per line (confirmed
+ * directly from jonmagic.com's quoted real event lines), `workspace.yaml`
+ * and `command-history-state.json`/`.../*.json` are ordinary structured
+ * text, and `logs/process-*.log` are plain log files. The same streamed
+ * readline/promises approach claude-code.js and cline.js use applies
+ * unchanged here — no whole-file-as-one-string V8 length ceiling, and a
+ * partial read still returns whatever lines WERE read rather than
+ * discarding real content. Status vocabulary matches every other source in
+ * this project: "complete", "partial", "too-large", "failed".
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  // Same rationale as claude-code.js: no natural timeout exists anywhere in
+  // Node's stream/readline stack, and a retargeted symlink can make the
+  // underlying open() block forever with no event ever firing. Destroying
+  // the stream is what actually unblocks that.
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };

package/src/sources/crush.js

@@ -0,0 +1,364 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Crush (charmbracelet/crush) session/chat history.
+ *
+ * VERIFICATION STATUS (read this before trusting anything below): this
+ * source is corroborated by the actual current Go source code of the
+ * official charmbracelet/crush repository on GitHub — fetched and read
+ * directly from the `main` branch (goose migration SQL, the config/data-dir
+ * resolution code, and the project-registry code), not inferred from a
+ * description of it. It has NOT been checked against a real Crush install —
+ * Crush is not installed on the machine this adapter was built on (checked:
+ * no `crush` on PATH, no `~/.local/share/crush` directory, not in `brew
+ * list`, no `crush`-named entry anywhere findable via `mdfind`). If you have
+ * Crush installed, the most useful thing you can do is run `residoo scan`
+ * and confirm `sourcesScanned`/`filesScanned` look right for what you know
+ * is actually on disk (`crush dirs` prints Crush's own view of its config
+ * and data locations), then report back either way.
+ *
+ * STORAGE MODEL — genuinely different from most sources in this project, so
+ * spelled out in full:
+ *
+ * Crush keeps its SQLite database PER PROJECT, the same way git keeps a
+ * `.git` directory per repo, not in one global well-known folder. Confirmed
+ * directly in source (`internal/config/config.go`, the `Options.DataDirectory`
+ * field doc comment): "DataDirectory is where Crush keeps per-project state
+ * such as the SQLite database and workspace overrides. Relative paths are
+ * resolved against the working directory; absolute paths are used as-is,"
+ * default `.crush`. `internal/db/connect.go` confirms the filename:
+ * `dbPath := filepath.Join(dataDir, "crush.db")`.
+ *
+ * So there is no single directory to list. What Crush DOES keep centrally is
+ * a small JSON registry of every project it has ever been run against —
+ * confirmed directly in `internal/projects/projects.go`:
+ *   - `projectsFilePath()` returns
+ *     `filepath.Join(filepath.Dir(config.GlobalConfigData()), "projects.json")`.
+ *   - Schema: `{"projects":[{"path":"...","data_dir":"...","last_accessed":"..."}]}`
+ *     (the `Project`/`ProjectList` structs, same file).
+ *   - `internal/cmd/root.go` calls `projects.Register(cwd, cfg.Options.DataDirectory)`
+ *     unconditionally on every normal `crush` invocation, immediately before
+ *     `db.Connect(ctx, cfg.Options.DataDirectory)` — so any project that has
+ *     ever actually written a `crush.db` is, in the overwhelmingly common
+ *     case, also listed here (failure to register is logged and non-fatal,
+ *     so a very unlucky write failure could in principle desync the two —
+ *     acknowledged, not fixable from outside the tool).
+ *   - Crush's own `stats --all` command reads this exact file to aggregate
+ *     across projects (`internal/cmd/stats.go`,
+ *     `gatherStatsFromProjects()` → `projects.Load()` →
+ *     `filepath.Join(p.DataDir, "crush.db")`) — this source's files() does
+ *     the same walk. Crush also ships a `stats --crawl-dir` mode that does a
+ *     full recursive filesystem walk for orphaned `.crush/crush.db`
+ *     directories instead; this source deliberately does NOT replicate that
+ *     — an unbounded home-directory crawl is a different cost/risk profile
+ *     than every other source in this project, and Crush's own default
+ *     behavior (registry-based, not crawl-based) is the one this mirrors.
+ *     A `crush.db` from a project Crush was never actually run `cd`-first
+ *     into (registration skipped some other way) would be missed; that is a
+ *     real, named gap, not a silent one.
+ *
+ * `GlobalConfigData()`'s directory (`internal/config/load.go`) — resolved in
+ * this exact order, replicated in `crushGlobalDataDir()` below:
+ *   1. `$CRUSH_GLOBAL_DATA` if set, used as-is (no `crush` suffix appended).
+ *   2. `$XDG_DATA_HOME/crush` if `XDG_DATA_HOME` is set.
+ *   3. Windows: `%LOCALAPPDATA%\crush` (`LOCALAPPDATA` env, falling back to
+ *      `%USERPROFILE%\AppData\Local`).
+ *   4. Otherwise (macOS AND Linux — confirmed no Darwin special-case in
+ *      source, unlike Cursor): `$HOME/.local/share/crush`.
+ *
+ * DB schema, confirmed directly from the goose migration files under
+ * `internal/db/migrations/`: `20250424200609_initial.sql` creates `sessions`
+ * (id, title, message_count, prompt/completion tokens, cost, timestamps) and
+ * `messages` (id, session_id, role, `parts` TEXT — a JSON array of message
+ * content parts — model, timestamps) and `files` (id, session_id, path,
+ * `content` TEXT, version, timestamps — full-content snapshots of files the
+ * agent read or wrote during a session, kept for diffing/undo). Later
+ * migrations only ADD columns to `messages`/`sessions`
+ * (`20250627000000_add_provider_to_messages.sql`,
+ * `20250810000000_add_is_summary_message.sql`,
+ * `20250812000000_add_todos_to_sessions.sql`) or add an unrelated
+ * path-only `read_files` table (`20260127000000_add_read_files_table.sql` —
+ * session_id/path/read_at, no content, not scanned). `internal/message/
+ * content.go` confirms `parts` holds real plaintext — `TextContent{Text
+ * string}`, `ReasoningContent{Thinking string}` — not an opaque or encrypted
+ * blob. `internal/db/connect.go`'s pragmas (`journal_mode=WAL`,
+ * `secure_delete=ON`, ordinary `busy_timeout`) show nothing about
+ * encryption; nothing in source opens this database with a key.
+ *
+ * This source reads BOTH `messages` and `files` — both hold real content a
+ * secret could be sitting in (a pasted token in a chat turn; a `.env` file
+ * the agent happened to read, whose full text `files` snapshots verbatim).
+ * `sessions` (title/todos only) and `read_files` (paths/timestamps only) are
+ * left out as low-value scope creep, same judgment call gemini-cli.js
+ * documents for its own out-of-scope directories. Each table is read via
+ * `SELECT * FROM <table>` with no column allowlist — deliberately, same
+ * reasoning as cursor.js: column additions (already observed twice above)
+ * should not require an adapter update to keep being scanned.
+ *
+ * `internal/home/home.go` confirms `home.Dir()` is exactly
+ * `os.UserHomeDir()` — no XDG override on the home directory itself, matching
+ * Node's `os.homedir()`.
+ *
+ * One secondary source was also checked — Vercel's AI Gateway docs page on
+ * Crush — and is worth naming the gap in: it describes the database as
+ * simply living in `~/.local/share/crush/`. Direct source inspection shows
+ * that is imprecise: that directory holds `crush.json` (config) and
+ * `projects.json` (the registry this source actually reads); each project's
+ * real `crush.db` lives at the `data_dir` THAT FILE points to, by default
+ * `<project>/.crush/crush.db`. This is exactly the kind of guessed-path
+ * error CONTRIBUTING.md warns about, caught only by going to source instead
+ * of trusting the paraphrase.
+ */
+function crushGlobalDataDir() {
+  const crushGlobalData = process.env.CRUSH_GLOBAL_DATA;
+  if (crushGlobalData) return crushGlobalData; // used as-is, per GlobalConfigData()
+  const xdgDataHome = process.env.XDG_DATA_HOME;
+  if (xdgDataHome) return path.join(xdgDataHome, "crush");
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return path.join(localAppData, "crush");
+  }
+  return path.join(os.homedir(), ".local", "share", "crush");
+}
+
+const GLOBAL_DATA_DIR = crushGlobalDataDir();
+const PROJECTS_REGISTRY = path.join(GLOBAL_DATA_DIR, "projects.json");
+
+/**
+ * Same lazy-require, feature-detected node:sqlite pattern as cursor.js — see
+ * that file's docstring for the full reasoning (an eager top-level require
+ * would print Node's ExperimentalWarning on every `residoo scan` for every
+ * user, even the majority who have never touched Crush). Duplicated rather
+ * than shared: each source here is meant to be a small, self-contained file
+ * a reviewer can audit on its own (CONTRIBUTING.md).
+ */
+const NODE_SQLITE_REQUIREMENT = "needs Node.js 22.5+ (node:sqlite not present in this runtime)";
+let sqliteRequireAttempted = false;
+let DatabaseSync = null;
+
+function getDatabaseSync() {
+  if (!sqliteRequireAttempted) {
+    sqliteRequireAttempted = true;
+    try { ({ DatabaseSync } = require("node:sqlite")); }
+    catch { DatabaseSync = null; }
+  }
+  return DatabaseSync;
+}
+
+function id() { return "crush"; }
+function label() { return "Crush"; }
+
+function globalDataDirExists() {
+  try { return fs.statSync(GLOBAL_DATA_DIR).isDirectory(); } catch { return false; }
+}
+
+function available() {
+  // Cheap fs check first, same short-circuit reasoning as cursor.js's
+  // available(): the common case is Crush simply isn't installed, and that
+  // must not cost requiring node:sqlite.
+  return globalDataDirExists() && Boolean(getDatabaseSync());
+}
+
+/**
+ * Same additive, optional export as cursor.js's unavailableReason() — see
+ * that file's docstring. Distinguishes "Crush isn't here" (say nothing) from
+ * "Crush is here but this Node runtime can't read its database" (say so).
+ */
+function unavailableReason() {
+  if (!globalDataDirExists()) return null;
+  if (getDatabaseSync()) return null;
+  return `Crush detected but not scanned — ${NODE_SQLITE_REQUIREMENT}`;
+}
+
+/**
+ * Resolve one candidate `crush.db` path into zero or one files() entries.
+ * Identical in shape and reasoning to cursor.js's statIfPresent(): these
+ * paths are constructed from the projects.json registry, not discovered by
+ * listing a directory, so lstat is used directly rather than readdirSync's
+ * Dirent. A path that simply does not exist (a project registered, then
+ * later deleted, or a data_dir that was never actually written to) yields
+ * nothing and is NOT broken; a dangling symlink IS.
+ */
+function* statIfPresent(dbPath) {
+  let lst;
+  try { lst = fs.lstatSync(dbPath); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(dbPath); // follow the link
+      if (!st.isFile()) { yield { file: dbPath, broken: true }; return; }
+      yield { file: dbPath, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: dbPath, broken: true }; // dangling symlink
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return; // something unexpected sits at this path — out of scope, not broken
+  yield { file: dbPath, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every project's crush.db
+ * listed in the projects.json registry (see module docstring for exactly
+ * what that registry is and isn't guaranteed to contain).
+ *
+ * A missing registry (Crush never run, or a version old enough not to write
+ * one) yields nothing — the ordinary "nothing to scan yet" case, not broken.
+ * A registry that exists but fails to parse as JSON IS reported broken: were
+ * this silently skipped, a corrupt registry would make a real, populated
+ * install scan as cleanly empty, exactly the false "all clear" CONTRIBUTING.md
+ * rule 5 exists to prevent.
+ */
+function* files() {
+  let raw;
+  try { raw = fs.readFileSync(PROJECTS_REGISTRY, "utf-8"); }
+  catch { return; }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { yield { file: PROJECTS_REGISTRY, broken: true }; return; }
+
+  const projects = Array.isArray(parsed && parsed.projects) ? parsed.projects : [];
+  const seen = new Set();
+
+  for (const p of projects) {
+    if (!p || typeof p.data_dir !== "string" || p.data_dir === "") continue;
+    // Registered data_dir is documented to always be stored absolute
+    // (config.go: "After defaulting the stored value is always absolute").
+    // Resolved against the project's own path as a defensive fallback only,
+    // in case an older/foreign registry entry ever violates that invariant.
+    const dataDir = path.isAbsolute(p.data_dir)
+      ? p.data_dir
+      : path.resolve(typeof p.path === "string" ? p.path : GLOBAL_DATA_DIR, p.data_dir);
+    const dbPath = path.join(dataDir, "crush.db");
+    if (seen.has(dbPath)) continue;
+    seen.add(dbPath);
+    yield* statIfPresent(dbPath);
+  }
+}
+
+// A crush.db this large has not been observed anywhere in this source's
+// research — no real install was available to produce or measure one. Same
+// honest caveat as gemini-cli.js's MAX_BYTES: a generous, untested backstop
+// against a pathological file, not evidence of what real databases look like.
+const MAX_DB_BYTES = 512 * 1024 * 1024;
+const READ_TIMEOUT_MS = 60_000;
+const BUSY_TIMEOUT_MS = 5_000;
+const YIELD_EVERY_N_ROWS = 500;
+
+// See module docstring for why these two tables and not sessions/read_files.
+const TABLES = ["messages", "files"];
+
+/**
+ * Turn one row (a plain object keyed by column name, as node:sqlite's
+ * StatementSync#iterate() returns it) into one scanned text line. No column
+ * allowlist — see module docstring. Two JS value shapes need converting
+ * before JSON.stringify can touch them without throwing or losing data:
+ * a BLOB-affinity column can come back as a Uint8Array (none are declared in
+ * this schema today, handled anyway for the same forward-compatibility
+ * reason cursor.js's valueToText() exists); and node:sqlite returns an
+ * INTEGER that doesn't fit a safe JS number as a BigInt, which
+ * JSON.stringify throws a TypeError on unless converted first — verified
+ * against node:sqlite's own documented behavior, not observed against a
+ * real oversized column in this schema (every INTEGER column here is a
+ * timestamp or a small count, in practice always safe-integer-range).
+ */
+function rowToLine(row) {
+  const clean = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (v instanceof Uint8Array) clean[k] = Buffer.from(v).toString("utf-8");
+    else if (typeof v === "bigint") clean[k] = v.toString();
+    else clean[k] = v;
+  }
+  return JSON.stringify(clean);
+}
+
+/**
+ * Read one crush.db as an array of raw text "lines" — one per row (across
+ * `messages` and `files`), each turned into a single JSON-stringified line
+ * by rowToLine(). Same status vocabulary and same iterate()-with-periodic-
+ * yield-and-deadline-check approach as cursor.js's readLines() for the same
+ * reason: node:sqlite is fully synchronous, so a wall-clock deadline can
+ * only be enforced between rows, not preemptively mid-row. See cursor.js's
+ * own docstring for the full reasoning; not re-derived here since nothing
+ * about it is Crush-specific.
+ */
+async function readLines(file) {
+  const DB = getDatabaseSync();
+  if (!DB) return { lines: [], status: "failed", bytesRead: 0 };
+
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_DB_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  let db;
+  try {
+    db = new DB(file, { readOnly: true });
+    db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+  } catch {
+    // Deleted between files() and this call, a corrupt/non-SQLite file, or
+    // Crush itself holding a lock this readonly open can't get past within
+    // BUSY_TIMEOUT_MS — all genuinely "could not read this," not "read it,
+    // found nothing." Status "failed" keeps that distinction honest.
+    return { lines: [], status: "failed", bytesRead: 0 };
+  }
+
+  const lines = [];
+  let bytesRead = 0;
+  const deadline = Date.now() + READ_TIMEOUT_MS;
+  let timedOut = false;
+  let sawError = false;
+  let foundAnyTable = false;
+
+  for (const table of TABLES) {
+    let rows;
+    try {
+      rows = db.prepare(`SELECT * FROM ${table}`).iterate();
+    } catch {
+      // This particular table genuinely doesn't exist in this file's schema
+      // (a Crush version old enough to predate it, in principle) — not a
+      // read failure for the OTHER table, so just move on.
+      continue;
+    }
+    foundAnyTable = true;
+
+    let n = 0;
+    try {
+      for (const row of rows) {
+        const text = rowToLine(row);
+        lines.push(text);
+        bytesRead += Buffer.byteLength(text, "utf-8");
+        n++;
+        if (n % YIELD_EVERY_N_ROWS === 0) {
+          await new Promise((resolve) => setImmediate(resolve));
+          if (Date.now() > deadline) { timedOut = true; break; }
+        }
+      }
+    } catch {
+      // A row iterator can itself throw partway (e.g. a corrupted page hit
+      // mid-scan) — whatever WAS read before that is real content, kept the
+      // same way claude-code.js keeps a partial read rather than discarding it.
+      sawError = true;
+    }
+    if (timedOut) break;
+  }
+
+  try { db.close(); } catch { /* best-effort close; nothing left to do if this fails */ }
+
+  // Neither known table existed at all — opened fine as SQLite but didn't
+  // match the schema this source understands, a real "could not extract
+  // anything," not the same as "extracted zero real rows."
+  if (!foundAnyTable) return { lines: [], status: "failed", bytesRead: 0 };
+  if (sawError && lines.length === 0) return { lines: [], status: "failed", bytesRead };
+  if (timedOut || sawError) return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  return { lines, status: "complete", bytesRead };
+}
+
+module.exports = { id, label, available, unavailableReason, files, readLines };