residoo 0.1.0 → 0.2.0

package/src/sources/antigravity-cli.js

@@ -0,0 +1,155 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Google Antigravity (antigravity.google) — the agentic development platform
+ * Google launched at I/O 2026, whose CLI (built in Go, replacing Gemini CLI
+ * for agentic use) and desktop editor both write local session state under
+ * `~/.gemini/antigravity*`.
+ *
+ * VERIFICATION STATUS: corroborated by one detailed, credible source — NOT
+ * by two independent sources of the exact schema, and NOT checked against a
+ * real install on the machine this source was built on (no `~/.gemini`
+ * directory exists there; see CONTRIBUTING.md). Ship this with that
+ * explicitly weaker standing in mind relative to this project's other new
+ * sources.
+ *
+ * The source: jazzyalex/agent-sessions (github.com/jazzyalex/agent-sessions,
+ * 800+ stars) — a real, actively maintained macOS app built specifically to
+ * parse local AI-coding-agent session history for browsing/search — ships a
+ * dedicated guide page, "Antigravity CLI local history: transcripts and
+ * brain artifacts under `~/.gemini`," documenting (as this tool's own
+ * behavior, i.e. code the maintainer wrote and presumably ran against a real
+ * Antigravity install, not a secondhand description):
+ *   - CLI transcripts: `~/.gemini/antigravity-cli/brain/<conversation-id>/
+ *     .system_generated/logs/transcript.jsonl` (one step per line: fields
+ *     including step_index, source, type, status, created_at, content,
+ *     tool_calls, thinking, truncated_fields) plus a sibling
+ *     `transcript_full.jsonl` restoring content the primary file truncates.
+ *   - Editor artifacts: `~/.gemini/antigravity/brain/<conversation-id>/`
+ *     holding per-artifact Markdown (`task.md`, `implementation_plan.md`,
+ *     `walkthrough.md`, `proposal.md`) each paired with a `.metadata.json`.
+ *   - The same guide notes upgraded installs may also carry
+ *     `~/.gemini/antigravity-ide/brain` and `~/.gemini/antigravity-backup/
+ *     brain`, but says its own tool only scans the first two — this source
+ *     follows that same, narrower choice rather than guessing at the other
+ *     two directory names' internal shape.
+ *
+ * Real-world significance: Antigravity is a first-party Google product
+ * (Google I/O 2026 launch, "the only tool in this group not built on VS
+ * Code," free public preview with Gemini 3 Pro access as of that launch),
+ * so — schema-verification caveat above notwithstanding — this is exactly
+ * the kind of tool this project's coverage would be conspicuously incomplete
+ * without.
+ *
+ * This source walks both brain roots recursively for `.jsonl`, `.json`, and
+ * `.md` files (skipping the `.system_generated/logs` vs top-level distinction
+ * rather than hard-coding it) — the same "match by extension, don't pin the
+ * exact depth" tolerance claude-code.js applies to its own project-slug
+ * directories, since a screenshot or other binary asset the CLI writes
+ * alongside these would not match any of those three extensions anyway.
+ */
+const HOME = os.homedir();
+const GEMINI_DIR = path.join(HOME, ".gemini");
+const CLI_BRAIN_ROOT = path.join(GEMINI_DIR, "antigravity-cli", "brain");
+const EDITOR_BRAIN_ROOT = path.join(GEMINI_DIR, "antigravity", "brain");
+
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB — same backstop as claude-code.js.
+const READ_TIMEOUT_MS = 60_000;
+const MAX_WALK_DEPTH = 8;
+
+function id() { return "antigravity"; }
+function label() { return "Google Antigravity"; }
+
+function available() {
+  for (const root of [CLI_BRAIN_ROOT, EDITOR_BRAIN_ROOT]) {
+    try { if (fs.statSync(root).isDirectory()) return true; } catch { /* try the next root */ }
+  }
+  return false;
+}
+
+/**
+ * Same defensive symlink-following helpers as claude-code.js — see that
+ * file's docstring. Duplicated rather than imported, per this project's
+ * self-contained-source-file convention (see cursor.js's docstring).
+ */
+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());
+
+const TEXT_EXTENSIONS = new Set([".jsonl", ".json", ".md"]);
+
+/**
+ * Recursively yield { file, mtimeMs, sizeBytes, broken } for every plain
+ * text-like (see TEXT_EXTENSIONS) file under `dir` — see factory-droid.js's
+ * walk() for the identical symlink-handling reasoning.
+ */
+function* walk(dir, depth) {
+  if (depth > MAX_WALK_DEPTH) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (isDirFollowingSymlink(full, e)) {
+      yield* walk(full, depth + 1);
+      continue;
+    }
+    const isFile = isFileFollowingSymlink(full, e);
+    if (!isFile) {
+      if (e.isSymbolicLink()) yield { file: full, broken: true };
+      continue;
+    }
+    if (!TEXT_EXTENSIONS.has(path.extname(e.name))) continue; // e.g. a captured screenshot — out of scope
+    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 };
+  }
+}
+
+function* files() {
+  yield* walk(CLI_BRAIN_ROOT, 0);
+  yield* walk(EDITOR_BRAIN_ROOT, 0);
+}
+
+/**
+ * Read one transcript/artifact file as raw text lines. Identical streaming/
+ * timeout/partial-read discipline to claude-code.js's readLines().
+ */
+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 });
+  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;
+    }
+    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/cline.js

@@ -0,0 +1,208 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Cline (VS Code extension, historically shipped as "Claude Dev") session
+ * history.
+ *
+ * VERIFICATION STATUS: the path and file layout below were read directly out
+ * of Cline's own current source on GitHub (cline/cline) during this source's
+ * research — not inferred from a blog post and not guessed from Roo Code's
+ * near-identical fork, even though the two are in fact near-identical.
+ * Specifically:
+ *   - apps/vscode/src/core/storage/disk.ts — GlobalFileNames constants and
+ *     ensureTaskDirectoryExists()/getGlobalStorageDir(), which resolve
+ *     through the VS Code extension's own `globalStorageUri` (NOT
+ *     workspaceStorage) into `tasks/<taskId>/`.
+ *   - apps/vscode/package.json — `"name": "claude-dev"`, `"publisher":
+ *     "saoudrizwan"`, confirming the on-disk globalStorage folder is really
+ *     still `saoudrizwan.claude-dev` (Cline shipped as "Claude Dev" and kept
+ *     its original package.json identity across the product's later rename
+ *     to Cline — this is NOT the same as the current "Cline" display name,
+ *     and guessing `cline.cline` or similar would have been wrong).
+ * What this could NOT be checked against: a real Cline install on the
+ * machine this source was built on — VS Code itself isn't installed there.
+ * See CONTRIBUTING.md for what "verified" is supposed to mean and treat
+ * findings from this source accordingly until someone with Cline actually
+ * installed confirms it against real data.
+ *
+ * Cline writes one JSON file per concern into a per-task directory under its
+ * extension's VS Code globalStorage folder:
+ *
+ *   <VS Code User dir>/globalStorage/saoudrizwan.claude-dev/tasks/<taskId>/
+ *     api_conversation_history.json   - full message history sent to the model
+ *     ui_messages.json                - the rendered chat transcript
+ *     context_history.json            - context-window bookkeeping
+ *     task_metadata.json              - files touched, model/token usage
+ *     settings.json                   - a per-task settings snapshot
+ *
+ * Filenames are deliberately NOT allow-listed beyond "every *.json file
+ * directly inside tasks/<taskId>/": GlobalFileNames in Cline's own source has
+ * gained entries over time (context_history.json is a relatively recent
+ * addition) and hard-coding today's list is exactly the kind of thing likely
+ * to go stale the same way cursor.js's docstring describes for Cursor's own
+ * key names. A task's `checkpoints/` subdirectory (shadow-git snapshots used
+ * for file revert) is deliberately NOT walked — those are git object stores,
+ * not text transcripts.
+ *
+ * Base directory: VS Code has a portable/remote/Insiders/fork multiverse of
+ * possible per-profile "User" directories. This source checks the two by far
+ * most common ones on each OS — standard VS Code ("Code") and VS Code
+ * Insiders ("Code - Insiders") — and deliberately does NOT attempt every
+ * fork (VSCodium, etc.) or the separate ~/.vscode-server tree used by
+ * remote-SSH sessions: a named, narrower scope rather than a guess at an
+ * exhaustive list.
+ *
+ * Also out of scope, named rather than silently skipped: Cline's task-title
+ * history INDEX (the array a "History" panel is built from) is not a plain
+ * file — it is read via VS Code's own `context.globalState` API, which
+ * persists into a *different*, central per-profile database
+ * (globalStorage/state.vscdb, shared by every installed extension, keyed by
+ * extension id) rather than anywhere under this extension's own
+ * globalStorage folder. Parsing that shared, VS-Code-owned database is out of
+ * scope for this source; the per-task JSON files above are where actual
+ * conversation content — and anything pasted into it — lives.
+ */
+const EXT_ID = "saoudrizwan.claude-dev";
+
+function vscodeUserDirs() {
+  const home = os.homedir();
+  const variants = ["Code", "Code - Insiders"];
+  if (process.platform === "darwin") {
+    return variants.map((v) => path.join(home, "Library", "Application Support", v, "User"));
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return variants.map((v) => path.join(appData, v, "User"));
+  }
+  // Linux and other XDG-following unix platforms.
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return variants.map((v) => path.join(configHome, v, "User"));
+}
+
+function tasksDirs() {
+  return vscodeUserDirs().map((userDir) => path.join(userDir, "globalStorage", EXT_ID, "tasks"));
+}
+
+// Bounds for readLines() — same rationale and same values as claude-code.js:
+// generous headroom over any real transcript, plus a hard stop against a
+// hung read. Not backed by a real Cline 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;
+
+function id() { return "cline"; }
+function label() { return "Cline"; }
+
+function available() {
+  return tasksDirs().some((dir) => {
+    try { return fs.statSync(dir).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: each source in
+ * this project is meant to be a small, self-contained file a reviewer can
+ * audit on its own (see CONTRIBUTING.md and cursor.js's own note on this).
+ */
+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());
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every *.json file directly
+ * inside every task directory, across every candidate VS Code User dir.
+ *
+ * broken:true marks a tasks/ entry or a *.json entry that looked like it
+ * should resolve (chiefly a dangling symlink) but didn't — never silently
+ * skipped, same convention as claude-code.js and cursor.js.
+ */
+function* files() {
+  for (const tasksDir of tasksDirs()) {
+    let taskEntries;
+    try { taskEntries = fs.readdirSync(tasksDir, { withFileTypes: true }); }
+    catch { continue; } // this VS Code variant/profile simply has no Cline tasks dir — normal, not broken
+
+    for (const taskEntry of taskEntries) {
+      const taskDir = path.join(tasksDir, taskEntry.name);
+      if (!isDirFollowingSymlink(taskDir, taskEntry)) {
+        if (taskEntry.isSymbolicLink()) yield { file: taskDir, broken: true };
+        continue; // a stray non-directory entry under tasks/ is out of scope, not broken
+      }
+
+      let fileEntries;
+      try { fileEntries = fs.readdirSync(taskDir, { withFileTypes: true }); }
+      catch { yield { file: taskDir, broken: true }; continue; }
+
+      for (const e of fileEntries) {
+        if (!e.name.endsWith(".json")) continue;
+        const file = path.join(taskDir, e.name);
+        if (!isFileFollowingSymlink(file, e)) {
+          if (e.isSymbolicLink()) yield { file, broken: true };
+          continue;
+        }
+        let stat;
+        try { stat = fs.statSync(file); } catch { yield { file, broken: true }; continue; }
+        yield { file, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+      }
+    }
+  }
+}
+
+/**
+ * Read one JSON file as an array of raw text lines.
+ *
+ * Cline writes these via `JSON.stringify(value, null, 2)` (confirmed from
+ * disk.ts) — real multi-line, indented text, not a single giant line — so
+ * the same streamed readline/promises approach claude-code.js uses for JSONL
+ * applies here essentially unchanged, and gets the same benefits: no
+ * whole-file-as-one-string V8 string-length ceiling, and a partial read (the
+ * file started streaming but the read failed partway) 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/codebuff.js

@@ -0,0 +1,295 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Codebuff (codebuff.com, formerly named "Manicode" — the on-disk config
+ * directory still uses the old name) local chat history.
+ *
+ * VERIFICATION STATUS: NOT checked against a real Codebuff install — neither
+ * `codebuff` nor `manicode` is on PATH, and no `~/.config/manicode*`
+ * directory exists on the machine this adapter was built on (checked PATH,
+ * npm -g, mdfind, the paths below directly). Ships anyway per
+ * CONTRIBUTING.md rule 3, on the strength of three independent, current,
+ * mutually-corroborating sources:
+ *
+ *  1. Codebuff's own official docs (codebuff.com/docs/advanced), which
+ *     document the `CODEBUFF_DATA_DIR` override and the fact that history is
+ *     scoped per "channel" (production/dev/staging).
+ *  2. A real, independent, third-party tool's own written documentation of
+ *     the format: CodexBar (github.com/steipete/CodexBar,
+ *     docs/codebuff.md), which states conversation history "is stored
+ *     locally at ~/.config/manicode/projects/<project-name>/chats" and that
+ *     `~/.config/manicode/credentials.json` is written after `codebuff
+ *     login` — the "formerly manicode" naming and directory layout agree
+ *     exactly with source 3 below.
+ *  3. The strongest source: ccusage (github.com/ccusage/ccusage, a real,
+ *     independently maintained, actively developed CLI usage tracker with
+ *     18k+ real GitHub stars — sanity-checked directly, not assumed) ships
+ *     its OWN tested Rust adapter for Codebuff
+ *     (rust/adapters/codebuff/src/{paths,parser,loader}.rs), fetched and
+ *     read directly, not summarized secondhand. Its unit tests embed a real
+ *     fixture file at
+ *     `projects/project-a/chats/2026-01-02T03-04-05.000Z/chat-messages.json`
+ *     containing actual message-object shapes
+ *     (`{"role":"user","text":"hello"}`,
+ *     `{"id":"...","role":"assistant","timestamp":"...","metadata":{"model":"...","usage":{...}},"credits":1.25}`)
+ *     — this is a real, working, unrelated tool's reverse-engineered
+ *     understanding of the exact same file this source reads, the same
+ *     evidentiary bar cursor.js's own docstring cites approvingly for its
+ *     own two corroborating community tools.
+ *
+ * Directory layout (agreed by all three sources): one root per "channel" —
+ * `~/.config/manicode` (production), `~/.config/manicode-dev`,
+ * `~/.config/manicode-staging` — each containing
+ * `projects/<project>/chats/<chatId>/chat-messages.json`, overridable via
+ * the `CODEBUFF_DATA_DIR` env var (a comma-separated list of channel roots;
+ * source 1 and source 3 agree on both the env var name and its comma-list
+ * shape). `chat-messages.json` is a JSON ARRAY of message objects — not
+ * line-delimited — so, per the adapter-contract note about non-line-
+ * delimited storage, each message object becomes one scanned "line" (see
+ * extractTopLevelJsonObjects() below).
+ *
+ * Deliberately NOT scanned: `credentials.json` (Codebuff's own CLI auth
+ * token for the logged-in account) — it is not a session transcript, and
+ * every other source in this project scans transcripts only, not each
+ * tool's own credential store (cursor.js, for instance, does not read
+ * Cursor's OS keychain entries either).
+ */
+const CODEBUFF_DATA_DIR_ENV = "CODEBUFF_DATA_DIR";
+const CHANNELS = ["manicode", "manicode-dev", "manicode-staging"];
+
+function id() { return "codebuff"; }
+function label() { return "Codebuff"; }
+
+/**
+ * Resolve the "projects" root for every configured channel, deduped.
+ *
+ * Mirrors ccusage's own `codebuff_project_roots()` exactly: when
+ * CODEBUFF_DATA_DIR is set, each comma-separated entry is used as-is if its
+ * basename is already "projects", otherwise "projects" is appended — this
+ * lets a user point the env var either at a channel root or directly at its
+ * projects subdirectory, matching Codebuff's own documented flexibility.
+ */
+function codebuffProjectRoots() {
+  const envVal = process.env[CODEBUFF_DATA_DIR_ENV];
+  let roots;
+  if (envVal && envVal.trim() !== "") {
+    roots = envVal
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s !== "")
+      .map((p) => path.resolve(p));
+  } else {
+    const home = os.homedir();
+    roots = CHANNELS.map((channel) => path.join(home, ".config", channel));
+  }
+
+  const seen = new Set();
+  const projectRoots = [];
+  for (const root of roots) {
+    const projectRoot = path.basename(root) === "projects" ? root : path.join(root, "projects");
+    let isDir = false;
+    try { isDir = fs.statSync(projectRoot).isDirectory(); } catch { isDir = false; }
+    if (isDir && !seen.has(projectRoot)) {
+      seen.add(projectRoot);
+      projectRoots.push(projectRoot);
+    }
+  }
+  return projectRoots;
+}
+
+function available() {
+  return codebuffProjectRoots().length > 0;
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js's
+ * isDirFollowingSymlink/isFileFollowingSymlink — duplicated rather than
+ * imported per this project's one-small-self-contained-file-per-source
+ * convention (see cursor.js's own docstring for why).
+ */
+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());
+
+/**
+ * Resolve one candidate `chat-messages.json` path into zero or one files()
+ * entries — same lstat-first, follow-if-symlink shape as cursor.js's
+ * statIfPresent, and for the same reason: this path is constructed (joined
+ * onto an already-resolved chat directory), not discovered via a Dirent, so
+ * there is no Dirent to reuse the isKindFollowingSymlink check against. A
+ * chat directory with no chat-messages.json yet (a brand new, still-empty
+ * chat) is normal and NOT broken; only a symlink that fails to resolve is.
+ */
+function* statFileIfPresent(file) {
+  let lst;
+  try { lst = fs.lstatSync(file); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(file);
+      if (!st.isFile()) { yield { file, broken: true }; return; }
+      yield { file, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file, broken: true };
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return;
+  yield { file, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every chat-messages.json
+ * found under every configured channel's projects root:
+ * <projectsRoot>/<project>/chats/<chatId>/chat-messages.json.
+ */
+function* files() {
+  for (const projectsRoot of codebuffProjectRoots()) {
+    let projectEntries;
+    try { projectEntries = fs.readdirSync(projectsRoot, { withFileTypes: true }); }
+    catch { continue; }
+
+    for (const proj of projectEntries) {
+      const projDir = path.join(projectsRoot, proj.name);
+      if (!isDirFollowingSymlink(projDir, proj)) {
+        if (proj.isSymbolicLink()) yield { file: projDir, broken: true };
+        continue;
+      }
+
+      const chatsDir = path.join(projDir, "chats");
+      let chatEntries;
+      try { chatEntries = fs.readdirSync(chatsDir, { withFileTypes: true }); }
+      catch { continue; } // no "chats" subdir yet — normal for a project with no chat history
+
+      for (const chat of chatEntries) {
+        const chatDir = path.join(chatsDir, chat.name);
+        if (!isDirFollowingSymlink(chatDir, chat)) {
+          if (chat.isSymbolicLink()) yield { file: chatDir, broken: true };
+          continue;
+        }
+        yield* statFileIfPresent(path.join(chatDir, "chat-messages.json"));
+      }
+    }
+  }
+}
+
+// A single chat's message history has not been observed anywhere in this
+// source's research to approach this size — like cursor.js's MAX_DB_BYTES,
+// this is a generous, untested-against-a-real-huge-file backstop against a
+// corrupted or pathological file, not an empirically derived ceiling.
+const MAX_BYTES = 512 * 1024 * 1024;
+const READ_TIMEOUT_MS = 60_000;
+
+/**
+ * Read the whole file as text, bounded by a wall-clock deadline the same
+ * way claude-code.js bounds its line-by-line read: no timeout exists
+ * natively anywhere in Node's stream stack, so a symlink retargeted onto
+ * something with no natural EOF (e.g. a FIFO with no writer) would otherwise
+ * hang forever with no 'error' or 'end' ever firing. Destroying the stream
+ * is what actually unblocks that.
+ *
+ * Resolves with whatever text WAS accumulated even when the read errors or
+ * times out partway — the caller (readLines) still extracts every complete
+ * top-level JSON object out of that partial text rather than discarding it,
+ * the same "partial read is still real content" principle claude-code.js's
+ * and cursor.js's own docstrings insist on.
+ */
+function readWholeFileBounded(file) {
+  return new Promise((resolve) => {
+    const stream = fs.createReadStream(file, { encoding: "utf-8" });
+    let text = "";
+    let bytesRead = 0;
+    let errored = false;
+    const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+    stream.on("data", (chunk) => {
+      text += chunk;
+      bytesRead += Buffer.byteLength(chunk, "utf-8");
+    });
+    stream.on("end", () => {
+      clearTimeout(timer);
+      resolve({ text, bytesRead, complete: true });
+    });
+    stream.on("error", () => {
+      if (errored) return; // 'error' can fire once for the destroy() and once natively
+      errored = true;
+      clearTimeout(timer);
+      resolve({ text, bytesRead, complete: false });
+    });
+  });
+}
+
+/**
+ * Extract every complete top-level `{...}` object out of arbitrary JSON
+ * text, tracking brace depth and string/escape state, WITHOUT requiring the
+ * surrounding `[ ... ]` array to be syntactically complete.
+ *
+ * This is what lets a partial read (timeout, mid-write file, I/O error)
+ * still surface every message that was fully written before the cutoff,
+ * instead of the whole file being discarded because JSON.parse on truncated
+ * input throws. It is also what lets a fully-successful read skip a real
+ * JSON.parse of the whole array entirely: each returned substring is used
+ * verbatim as one scanned "line", the same "don't re-serialize, keep the
+ * exact bytes the regexes depend on" reasoning cursor.js's valueToText()
+ * docstring gives for not round-tripping through JSON.parse/stringify.
+ */
+function extractTopLevelJsonObjects(text) {
+  const objects = [];
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escape = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escape) escape = false;
+      else if (ch === "\\") escape = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') { inString = true; continue; }
+    if (ch === "{") {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (ch === "}") {
+      if (depth > 0) depth--;
+      if (depth === 0 && start !== -1) {
+        objects.push(text.slice(start, i + 1));
+        start = -1;
+      }
+    }
+  }
+  return objects;
+}
+
+/**
+ * Read one chat-messages.json as an array of raw text "lines", one per
+ * top-level message object. Returns { lines, status, bytesRead } with the
+ * same status vocabulary as claude-code.js/cursor.js: "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 { text, bytesRead, complete } = await readWholeFileBounded(file);
+  const lines = extractTopLevelJsonObjects(text);
+
+  if (complete) return { lines, status: "complete", bytesRead };
+  // Errored or timed out partway: whatever complete objects WERE recovered
+  // are real content and may contain a real secret — never discard them
+  // just because the tail of the file didn't finish cleanly.
+  return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+}
+
+module.exports = { id, label, available, files, readLines };