residoo 0.1.0 → 0.3.0

package/src/sources/agent-configs.js

@@ -0,0 +1,308 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { createInterface } = require("readline/promises");
+
+/**
+ * Agent CONFIG and STATE files — the first source in this project that is
+ * not a transcript store. Configs earned their own source because they are
+ * the best-MEASURED plaintext secret sink in the 2026 evidence base:
+ * GitGuardian counted 24,008 secrets inside MCP config files on public
+ * GitHub (2,117 still valid); Lakera found live credentials inside
+ * `.claude/settings.local.json` files shipped in ~30 npm packages because
+ * Claude Code's approved-command cache accumulates tokens and no packaging
+ * tool ignores `.claude/` by default; and the year's supply-chain campaigns
+ * (Mini Shai-Hulud, Miasma, ChainDrop) both PLANT persistence in and STEAL
+ * from exactly these files. Published stealer target lists (JFrog's
+ * Bitwarden-CLI-hijack write-up, StepSecurity's Nx Console analysis, the
+ * keyv/Shai-Hulud reports) name several of the paths below verbatim.
+ *
+ * SCOPE — home-level only, and that limitation is real, not rhetorical:
+ * project-level configs (`.mcp.json`, `.claude/settings.json`,
+ * `.cursor/rules/`, `.vscode/tasks.json`, per-repo CLAUDE.md/AGENTS.md —
+ * the files Miasma actually planted in cloned repos) live inside arbitrary
+ * repositories this tool has no way to enumerate from a home directory.
+ * A clean report from this source therefore says nothing about any
+ * project's own config files. v1 ships the home-level set because those
+ * paths are fixed and verifiable; the project-level gap is stated here
+ * rather than papered over.
+ *
+ * PER-PATH VERIFICATION (per CONTRIBUTING.md's no-guessed-paths rule —
+ * "real install" below means the populated machine this source was built
+ * on, checked read-only; "digest" means the 2026-09-02 research digest's
+ * stealer target lists and campaign write-ups, which name exact paths):
+ *
+ *  - `~/.claude.json` — real install (present, live content) + named
+ *    verbatim in JFrog's Bitwarden-CLI-hijack target list + Claude Code's
+ *    own MCP docs (user-scoped MCP servers, env blocks included, are
+ *    stored here).
+ *  - `~/.claude.json.backup` — real install (present; Claude Code's own
+ *    rewrite backup of the file above — same content, same secrets, and a
+ *    scanner that reads the original but not its sibling copy would
+ *    under-report).
+ *  - `~/.claude/settings.json` — real install + the file Mini Shai-Hulud
+ *    and Miasma planted `SessionStart` hooks into + StepSecurity's Nx
+ *    Console write-up names it as a harvest target.
+ *  - `~/.claude/settings.local.json` — real install + Lakera's ~30
+ *    leaking npm packages are this exact filename. This file is the
+ *    reason a config source exists at all: it is NOT supposed to hold
+ *    secrets, and measurably does.
+ *  - `~/.claude/mcp.json` — the one deliberate exception to the rule that
+ *    a path must be vendor-documented or locally present: it is NEITHER
+ *    (Claude Code stores user-scope MCP config inside `~/.claude.json`,
+ *    and it does not exist on the real install verified against). It is
+ *    included anyway because published stealer target lists hunt this
+ *    exact name (JFrog's Bitwarden-CLI list: `~/.claude.json`,
+ *    `.claude/mcp.json`, `~/.kiro/settings/mcp.json`) — where the file
+ *    does exist (hand-written, third-party tooling, older forks), it is
+ *    precisely what an attacker grabs, and when absent it yields nothing
+ *    and costs one lstat.
+ *  - `~/.claude/CLAUDE.md` — Claude Code's own memory docs (user memory
+ *    file) + the TrapDoor campaign hid zero-width-Unicode exfiltration
+ *    instructions in CLAUDE.md files + the digest's stealer roadmap names
+ *    "memory files (MEMORY.md/CLAUDE.md)". Absent on the real install
+ *    (the `~/.claude` root is present); scanned when it exists because
+ *    memory files are where users paste the things they want remembered.
+ *  - Claude Desktop `claude_desktop_config.json` — macOS
+ *    `~/Library/Application Support/Claude/`: real install (present) +
+ *    the official MCP docs (modelcontextprotocol.io, "Connect to local
+ *    MCP servers") document it per-OS. Windows `%APPDATA%\Claude\`: same
+ *    official MCP docs + multiple independent setup guides agree. Linux
+ *    is deliberately NOT covered: there is no official Linux build, and
+ *    the unofficial ports disagree with each other on the config location
+ *    (`~/.config/Claude/` vs `~/.config/claude-desktop/`) — either pick
+ *    would be a guessed path.
+ *  - `~/.cursor/mcp.json` — Cursor's official MCP docs (the global,
+ *    all-projects config; distinct from the per-profile storage
+ *    cursor.js reads) + independent Snyk/liblab/TrueFoundry guides + the
+ *    digest's ~/.cursor deep-dive. Not installed on the build machine.
+ *  - `~/.gemini/settings.json` — Gemini CLI's official settings docs
+ *    (user settings file) + Miasma planted `.gemini/settings.json` (the
+ *    digest names the filename verbatim). Root resolution honors
+ *    GEMINI_CLI_HOME exactly as gemini-cli.js does — that override was
+ *    verified from the project's own source during that adapter's
+ *    research, not guessed here.
+ *  - `~/.codex/config.toml` — OpenAI's official docs (CODEX_HOME "sets
+ *    the root directory for Codex state, including config...", and the
+ *    Codex MCP docs document `mcp_servers` sections in config.toml with
+ *    `env` tables — the documented way to hand an MCP server an API key)
+ *    + multiple independent setup guides showing exactly that. Root
+ *    resolution honors CODEX_HOME exactly as codex-cli.js does.
+ *  - `~/.kiro/settings/mcp.json` — Kiro's official MCP configuration docs
+ *    (global config; their own security page recommends `chmod 600` on
+ *    it, a vendor admission it holds secrets) + named verbatim in JFrog's
+ *    Bitwarden-CLI target list.
+ *
+ * DELIBERATELY NOT READ, and why:
+ *  - `~/.claude/projects/**` — claude-code.js's territory. Overlapping it
+ *    would double-report every finding. (Named side effect: a
+ *    `projects/<slug>/memory/MEMORY.md` is covered by NEITHER source
+ *    today — a real gap that belongs to the transcript source's scope
+ *    discussion, recorded here so it isn't mistaken for covered.)
+ *  - `~/.claude/history.jsonl`, paste-cache, file-history, session-env —
+ *    transcript-adjacent conversation state, not configuration; adding
+ *    them belongs in a transcript source where dedup against session
+ *    files can be reasoned about.
+ *  - `~/.codex/auth.json`, `~/.gemini/oauth_creds.json`, `~/.gemini/.env`,
+ *    `~/.claude/.credentials.json` — credential VAULTS: files whose whole
+ *    documented job is holding the user's own keys/tokens, following the
+ *    precedent opencode.js set for its auth.json. Flagging those re-reports
+ *    what the user put there on purpose. The line drawn: a file that holds
+ *    secrets BY DESIGN is excluded; a file that accumulates secrets by
+ *    accident (settings.local.json's approved-command cache — Lakera's
+ *    finding) is exactly what this source is for.
+ *  - `~/.gemini/GEMINI.md`, `~/.codex/AGENTS.md` — vendor-documented
+ *    memory files, but the research digest never names either exact
+ *    home-level path, leaving them one source short of this project's
+ *    verification bar. Add-with-citation candidates, not omissions by
+ *    oversight.
+ *  - Windsurf/OpenClaw/other "equivalents" — the digest gestures at them
+ *    without naming an exact home-level path; no path, no scan.
+ *
+ * If any of these tools is installed on your machine, the most useful
+ * thing you can do is run `residoo scan` and confirm the per-source file
+ * counts match what you know is on disk, then report back either way —
+ * see CONTRIBUTING.md.
+ */
+function claudeDesktopConfig() {
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return path.join(appData, "Claude", "claude_desktop_config.json");
+  }
+  return null; // Linux: no official build, unofficial ports disagree — see header
+}
+
+function geminiDir() {
+  // GEMINI_CLI_HOME is the tool's own documented override (the CLI creates
+  // a `.gemini` folder INSIDE it) — same resolution gemini-cli.js verified
+  // from the project's source, duplicated per the one-file-per-source rule.
+  if (process.env.GEMINI_CLI_HOME) return path.join(process.env.GEMINI_CLI_HOME, ".gemini");
+  return path.join(os.homedir(), ".gemini");
+}
+
+function codexHome() {
+  // CODEX_HOME per official docs covers "config", not just sessions —
+  // same resolution codex-cli.js uses.
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  return path.join(os.homedir(), ".codex");
+}
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, ".claude");
+const DESKTOP_CONFIG = claudeDesktopConfig();
+const GEMINI_DIR = geminiDir();
+const CODEX_HOME = codexHome();
+const CURSOR_DIR = path.join(HOME, ".cursor");
+const KIRO_DIR = path.join(HOME, ".kiro");
+
+// Every candidate is a single fixed file path (see header for what verified
+// each). Absence is normal and yields nothing — most machines have a few of
+// these tools at most; only a path that LOOKS present but can't be resolved
+// is reported broken.
+const CANDIDATES = [
+  path.join(HOME, ".claude.json"),
+  path.join(HOME, ".claude.json.backup"),
+  path.join(CLAUDE_DIR, "settings.json"),
+  path.join(CLAUDE_DIR, "settings.local.json"),
+  path.join(CLAUDE_DIR, "mcp.json"),
+  path.join(CLAUDE_DIR, "CLAUDE.md"),
+  ...(DESKTOP_CONFIG ? [DESKTOP_CONFIG] : []),
+  path.join(CURSOR_DIR, "mcp.json"),
+  path.join(GEMINI_DIR, "settings.json"),
+  path.join(CODEX_HOME, "config.toml"),
+  path.join(KIRO_DIR, "settings", "mcp.json"),
+];
+
+// Configs are KB-scale in every real observation this source's research
+// produced (the largest, a live ~/.claude.json accumulating per-project
+// state, was tens of KB; community bloat reports for that file reach tens
+// of MB). 64MB is a corrupted-or-pathological-file backstop, not a bound
+// derived from a real file — same caveat cursor.js states for MAX_DB_BYTES.
+// A file over it is surfaced as "too-large", never silently skipped.
+const MAX_BYTES = 64 * 1024 * 1024;
+const READ_TIMEOUT_MS = 60_000;
+
+function id() { return "agent-configs"; }
+function label() { return "Agent config files"; }
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function fileExists(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Available when any of the config ROOTS exists — not just when a candidate
+ * file does. A machine with an empty `~/.cursor` should still show this
+ * source as checked (finding nothing is a result), while a machine with
+ * none of these tools shouldn't list it at all.
+ */
+function available() {
+  return (
+    fileExists(path.join(HOME, ".claude.json")) ||
+    dirExists(CLAUDE_DIR) ||
+    (DESKTOP_CONFIG !== null && dirExists(path.dirname(DESKTOP_CONFIG))) ||
+    dirExists(CURSOR_DIR) ||
+    dirExists(GEMINI_DIR) ||
+    dirExists(CODEX_HOME) ||
+    dirExists(KIRO_DIR)
+  );
+}
+
+/**
+ * Resolve one fixed candidate path into zero or one files() entries — the
+ * same lstat-then-follow shape as cursor.js's statIfPresent, duplicated per
+ * the one-file-per-source convention. These paths are constructed, not
+ * discovered by a directory listing, so there is no Dirent to reuse:
+ * absence yields nothing (normal — see CANDIDATES), a dangling symlink
+ * yields broken (a dotfiles manager symlinking `~/.claude/settings.json`
+ * at a moved target is the realistic case, and silently skipping it is the
+ * exact bug claude-code.js's files() docstring exists to prevent), and
+ * something that is neither file nor symlink at the path is out of scope.
+ */
+function* statIfPresent(p) {
+  let lst;
+  try { lst = fs.lstatSync(p); }
+  catch (err) {
+    // ENOENT/ENOTDIR is the normal not-installed case and yields nothing.
+    // Any other lstat failure (EACCES on `~/.claude` itself, ELOOP) means a
+    // candidate may exist but can't be examined — that's a broken entry,
+    // not absence: available() can still say true for the root, and a
+    // silently empty files() would be the exact silent-exclusion bug the
+    // yield-broken convention exists to prevent.
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return;
+    yield { file: p, broken: true };
+    return;
+  }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(p); // follow the link
+      if (!st.isFile()) { yield { file: p, broken: true }; return; }
+      yield { file: p, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: p, broken: true }; // dangling symlink
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return;
+  yield { file: p, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/** Yield { file, mtimeMs, sizeBytes, broken } for every candidate present. */
+function* files() {
+  for (const p of CANDIDATES) yield* statIfPresent(p);
+}
+
+/**
+ * Read one config file as raw text lines — the same streaming reader as
+ * claude-code.js's readLines (see that docstring for the timeout rationale:
+ * a symlink retargeted between stat and open can block open() forever, and
+ * destroying the stream is the only way out). Configs are JSON, TOML, or
+ * Markdown rather than JSONL, which changes nothing for the caller: scan.js
+ * matches raw text lines, and a token inside a pretty-printed `"env"` block
+ * or a TOML `env` table sits on its own line just like a JSONL record does.
+ * A single-line minified JSON config arrives as one long line — still
+ * within the streaming reader's per-line limits at this source's size cap.
+ *
+ * Same status contract as every source: "complete", "partial" (some lines
+ * were read before a failure — scanned, and flagged), "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 });
+  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 {
+    // Lines read before the failure are real content and may hold a real
+    // secret — an honest "partial" beats a silent false negative.
+    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/aider.js

@@ -0,0 +1,361 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Aider (github.com/Aider-AI/aider) session transcripts.
+ *
+ * VERIFICATION STATUS (read this before trusting anything below): the file
+ * names, on-disk format, and location logic below are corroborated across
+ * FOUR independent, current sources —
+ *
+ *   1. Aider's own official docs (aider.chat/docs/config/options.html),
+ *      which document `--chat-history-file` (default `.aider.chat.history.md`)
+ *      and `--input-history-file` (default `.aider.input.history`).
+ *   2. Aider's own current GitHub source (Aider-AI/aider, `aider/args.py`,
+ *      main branch — fetched directly, not from a cache or a summary):
+ *        default_input_history_file = os.path.join(git_root, ".aider.input.history")
+ *                                       if git_root else ".aider.input.history"
+ *        default_chat_history_file  = os.path.join(git_root, ".aider.chat.history.md")
+ *                                       if git_root else ".aider.chat.history.md"
+ *      i.e. these are NOT under one fixed root the way Claude Code's or
+ *      Cursor's storage is — they land at the root of whatever git repo the
+ *      user ran `aider` inside (or the bare CWD if that wasn't a git repo).
+ *      A real user independently ran into exactly this scattering, filing
+ *      Aider-AI/aider#2684 ("history files accumulate ... outside git
+ *      repos"), which corroborates the CWD/git-root behaviour from the
+ *      outside, not just from reading the source.
+ *   3. A REAL, live `.aider.chat.history.md` from an actual aider user, who
+ *      committed it to their own public repo (github.com/dfeldman/
+ *      operation-conundrum.github.io, file `aider-chat-history.md`, 2628
+ *      lines, dated 2023-05-26 in-content). Fetched and inspected directly.
+ *      It matches the documented format exactly: sessions delimited by
+ *      `# aider chat started at <timestamp>`, each user message as one or
+ *      more `#### `-prefixed markdown lines, tool/system notices as `> `
+ *      blockquote lines, assistant replies as plain markdown including
+ *      fenced code blocks and aider's own `<<<<<<< ORIGINAL / ======= /
+ *      >>>>>>> UPDATED` search-replace diff blocks.
+ *   4. `.aider.input.history` is not aider's own format at all — aider hands
+ *      it straight to `prompt_toolkit.history.FileHistory`, a dependency of
+ *      aider's. Fetched that library's own current source
+ *      (python-prompt-toolkit, `src/prompt_toolkit/history.py`,
+ *      `FileHistory.store_string`) directly: every stored input is appended
+ *      as `\n# <datetime>\n` followed by that input's lines, each prefixed
+ *      with a literal `+`. So this file is not free-form text so much as a
+ *      well-known third-party library's fixed serialization — verified
+ *      against that library's own code, not guessed.
+ *
+ * What none of the above is: a real Aider install on the machine this
+ * source was built on. Checked directly and thoroughly — `which aider`,
+ * `pip3 show aider-chat` / `python3 -m pip show aider-chat`, `brew list
+ * aider`, `pipx list`, common config locations (`~/.config`, `~/Library/
+ * Application Support`, `~/Library/Caches`, `~/Library/Preferences`), and a
+ * filesystem-wide `find`/`mdfind` for `.aider*` and `*aider-chat-history*`.
+ * All came back empty: aider is not installed here, and there is no real
+ * session history on this machine to genuinely verify the schema against.
+ * Per CONTRIBUTING.md's rule 3, this ships anyway because of the four
+ * corroborating sources above, but should be treated the same way cursor.js
+ * asks to be treated: real, but UNVERIFIED against a live install. If you
+ * have Aider installed, running `residoo scan` and checking the results
+ * against what you know is really in your `.aider.chat.history.md` /
+ * `.aider.input.history` files is the single most useful way to firm this
+ * up — please report back either way.
+ *
+ * WHERE THIS SOURCE LOOKS — the fundamentally different problem vs.
+ * claude-code.js / cursor.js:
+ *
+ * Both of those tools keep everything under one fixed, well-known directory
+ * this machine can enumerate directly (~/.claude/projects,
+ * .../Cursor/User). Aider, by its own design (see source citation #2
+ * above), has no such thing — its two history files can be sitting at the
+ * root of literally any git repository, or any bare directory, the user has
+ * ever run `aider` from. There is no manifest anywhere that lists which
+ * directories those were: `~/.aider/installs.json` (see AIDER_HOME below)
+ * only ever records `(version, python-executable)` pairs for "what's new"
+ * notes, and `~/.aider/analytics.json` records anonymized event counters,
+ * neither ever a path. Confirmed directly against aider's own
+ * `is_first_run_of_new_version()` in `main.py` and `Analytics` in
+ * `analytics.py`.
+ *
+ * So `files()` below does a bounded, best-effort walk of the user's home
+ * directory looking for the two exact filenames above (plus, opportunistically,
+ * the one non-default file named below) at any depth. This is an honest,
+ * named engineering tradeoff, not a guess about WHERE aider's format lives
+ * (that part is verified, see above) — it is a search-breadth compromise for
+ * a location that is, by the tool's own design, unbounded. The walk is
+ * gated behind available() (see below) so a user who has never touched
+ * aider pays nothing for it, and it is bounded (MAX_DEPTH, MAX_DIRS_VISITED)
+ * so a user who has pays a bounded, not unlimited, cost. Both bounds are
+ * generous enough to cover realistic project layouts but this is explicitly
+ * NOT an exhaustive filesystem search — a `.aider.chat.history.md` sitting
+ * deeper than MAX_DEPTH below $HOME, or reachable only through a symlinked
+ * directory (deliberately not followed — see walk()'s docstring), will be
+ * missed. That is a real, named limitation, the same spirit as
+ * claude-code.js's admitted peak-memory gap and cursor.js's admitted
+ * untested-on-a-real-install gap — not a silent one.
+ */
+
+const HOME = os.homedir();
+
+// Presence-only signal, NOT the location transcripts live in (see module
+// docstring's "WHERE THIS SOURCE LOOKS" section). Aider writes into this
+// directory on essentially every normal run — install-tracking
+// (installs.json), opt-in anonymous analytics (analytics.json), and OAuth
+// provider tokens (oauth-keys.env) — confirmed directly against
+// `Path.home() / ".aider"` in aider's own main.py/analytics.py. Its mere
+// existence is a reliable, cheap, fixed-path way to answer "has aider ever
+// actually run on this machine" without doing the expensive home-directory
+// walk files() needs for the transcripts themselves.
+const AIDER_HOME = path.join(HOME, ".aider");
+
+const CHAT_HISTORY_NAME = ".aider.chat.history.md";
+const INPUT_HISTORY_NAME = ".aider.input.history";
+// --llm-history-file has NO default (default=None in args.py — confirmed
+// directly) — it only exists if a user explicitly opted in. It is included
+// here purely opportunistically, using the exact filename aider's own
+// --help text uses as its example ("for example, .aider.llm.history"): if a
+// file with this exact name happens to exist alongside the other two, scan
+// it too, since aider's own LLM history log is plausibly full of pasted
+// code/secrets. This is NOT a verified default location the way the other
+// two are — it is a zero-cost opportunistic check with no default to be
+// wrong about, and its absence should never be read as "surely not opted
+// in," just "not opted in under the example name."
+const LLM_HISTORY_NAME = ".aider.llm.history";
+
+const CANDIDATE_NAMES = new Set([CHAT_HISTORY_NAME, INPUT_HISTORY_NAME, LLM_HISTORY_NAME]);
+
+function id() { return "aider"; }
+function label() { return "Aider"; }
+
+function available() {
+  try { return fs.statSync(AIDER_HOME).isDirectory(); } catch { return false; }
+}
+
+// Bounds for the home-directory walk in files() — see the module docstring
+// for why this walk exists at all. Not calibrated against any real, large
+// aider user's directory tree (no real install on this machine — see
+// module docstring); chosen as a generous-but-bounded backstop the same way
+// cursor.js's MAX_DB_BYTES is, not a measured real-world ceiling the way
+// claude-code.js's MAX_BYTES is.
+const MAX_DEPTH = 8; // levels below $HOME a candidate file can be found at
+const MAX_DIRS_VISITED = 50_000; // circuit breaker on total directories read
+
+// Directory names never worth descending into, at any depth: version
+// control internals, dependency/build output, and language/tool caches.
+// This is a performance optimization only, not a correctness boundary —
+// MAX_DIRS_VISITED is what actually bounds worst-case cost; skipping these
+// just spends that budget on directories far more likely to matter. None of
+// aider's own history files are ever written inside any of these (they live
+// at a git root or a bare CWD — never inside .git/, node_modules/, etc.),
+// so skipping them cannot hide a real match.
+const ALWAYS_SKIP_DIR_NAMES = new Set([
+  "node_modules", ".git", ".hg", ".svn", "vendor",
+  ".venv", "venv", "__pycache__", ".tox", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+  ".next", ".nuxt", "dist", "build", "target", ".gradle", ".m2",
+  ".cargo", ".rustup", ".npm", ".yarn", ".pnpm-store", ".cache",
+  ".docker", ".orbstack", ".Trash", ".Trashes",
+  ".Spotlight-V100", ".fseventsd", ".DocumentRevisions-V100", ".TemporaryItems",
+]);
+
+// Skipped ONLY as direct children of $HOME itself (depth 0), never at any
+// deeper level — unlike the names above, these are ordinary, meaningful
+// words a real project directory could legitimately be named (e.g. a repo
+// literally called "build" or "Library"); they are only reliably "OS/user
+// furniture, not a project" when sitting directly under the home directory.
+const HOME_TOP_LEVEL_SKIP_DIR_NAMES = new Set([
+  "Library", "Applications", "Pictures", "Movies", "Music", "Public", "Desktop",
+  "AppData", // Windows counterpart to the above; harmless to check cross-platform
+]);
+
+/**
+ * Same defensive symlink-following as claude-code.js's
+ * isFileFollowingSymlink — duplicated locally rather than imported, same
+ * reasoning cursor.js states: each source here is meant to be a small,
+ * self-contained file a reviewer can audit on its own.
+ *
+ * Used only for the three known candidate filenames themselves (a single,
+ * named entry) — see walk()'s docstring for why open-ended directory
+ * recursion below deliberately does NOT get the same symlink-following
+ * treatment.
+ */
+function isFileFollowingSymlink(fullPath, dirent) {
+  if (dirent.isFile()) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return fs.statSync(fullPath).isFile(); } catch { return false; }
+}
+
+/**
+ * Resolve one candidate-named directory entry (`.aider.chat.history.md`,
+ * `.aider.input.history`, or `.aider.llm.history`) into zero or one files()
+ * entries, following a symlink with that exact name the same way
+ * claude-code.js follows a `*.jsonl`-named symlink. `broken: true` is
+ * reserved for a symlink with one of these exact names that fails to
+ * resolve — genuinely "this looked like an aider history file and wasn't
+ * readable," not the general "most directories we visit aren't
+ * aider-related at all" case walk() itself silently passes over (see its
+ * docstring).
+ */
+function* candidateEntry(fullPath, dirent) {
+  if (!isFileFollowingSymlink(fullPath, dirent)) {
+    if (dirent.isSymbolicLink()) yield { file: fullPath, broken: true };
+    return; // e.g. a directory that happens to be named exactly this — out of scope, not broken
+  }
+  let stat;
+  try { stat = fs.statSync(fullPath); }
+  catch { yield { file: fullPath, broken: true }; return; }
+  yield { file: fullPath, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+}
+
+/**
+ * Recursively walk `dir` (`depth` levels below $HOME) looking for the
+ * candidate filenames above, subject to `budget` (a shared { remaining }
+ * counter across the whole walk — see MAX_DIRS_VISITED).
+ *
+ * Two deliberate departures from claude-code.js/cursor.js's walking style,
+ * both because this walk is open-ended (an unbounded, unknown directory
+ * tree) rather than a listing of one specific, known, expected location:
+ *
+ *  1. Directory symlinks are NOT followed during recursion (only
+ *     `dirent.isDirectory()`, lstat semantics). Following them here — unlike
+ *     following a single, specific, known symlink such as
+ *     ~/.claude/projects/<slug> — risks an infinite cycle (a symlinked
+ *     directory pointing back at one of its own ancestors), which an
+ *     open-ended walk has no other guard against. MAX_DIRS_VISITED still
+ *     bounds worst case even if this reasoning has a gap, but not following
+ *     directory symlinks is the primary defense.
+ *  2. A directory that fails to list (fs.readdirSync throws — permission
+ *     denied, deleted mid-walk, etc.) is silently skipped, NOT reported via
+ *     `broken: true`. claude-code.js reports that for a project directory
+ *     under ~/.claude/projects because every entry there is a known,
+ *     expected Claude Code project folder — a read failure is anomalous and
+ *     worth surfacing. Here, the overwhelming majority of directories this
+ *     function visits have nothing to do with aider at all (this is a
+ *     speculative, exploratory walk of $HOME) — treating every
+ *     permission-denied OS directory encountered along the way as a
+ *     reportable "broken" entry would flood the report with noise carrying
+ *     no actionable signal. `broken` stays reserved for the specific, named
+ *     candidate files themselves (see candidateEntry above), exactly
+ *     mirroring how claude-code.js/cursor.js already treat "some unrelated
+ *     stray entry" as silently out of scope while treating a failure on a
+ *     specifically-expected entry as reportable.
+ */
+function* walk(dir, depth, budget) {
+  if (budget.remaining <= 0) return;
+  budget.remaining--;
+
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+
+  const atHomeLevel = depth === 0;
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+
+    if (CANDIDATE_NAMES.has(e.name)) {
+      yield* candidateEntry(full, e);
+      continue;
+    }
+
+    if (depth >= MAX_DEPTH) continue;
+    if (!e.isDirectory()) continue; // no symlink-following in open-ended recursion — see docstring above
+    if (ALWAYS_SKIP_DIR_NAMES.has(e.name)) continue;
+    if (atHomeLevel && HOME_TOP_LEVEL_SKIP_DIR_NAMES.has(e.name)) continue;
+
+    yield* walk(full, depth + 1, budget);
+  }
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every aider history file
+ * found under $HOME. See the module docstring's "WHERE THIS SOURCE LOOKS"
+ * section for what this walk is and is not guaranteed to cover.
+ */
+function* files() {
+  // available() is the cheap gate on the (unrelated) ~/.aider directory —
+  // see that directory's own comment above for why checking it here, unlike
+  // in claude-code.js/cursor.js, is necessary rather than redundant: this
+  // function's walk root ($HOME) is not the same directory available()
+  // checks, so without this line every residoo user — aider or not — would
+  // pay for a full home-directory walk on every scan.
+  if (!available()) return;
+
+  const budget = { remaining: MAX_DIRS_VISITED };
+  yield* walk(HOME, 0, budget);
+}
+
+// Bounds for readLines() — same rationale and same numbers as
+// claude-code.js, but NOT calibrated against a real large aider file the
+// way claude-code.js's MAX_BYTES was (no real install — see module
+// docstring). Markdown chat transcripts and prompt_toolkit's input-history
+// format are both far more compact than JSONL tool-call payloads (no
+// embedded base64, no repeated schema keys), so multi-gigabyte real files
+// are less likely here than for claude-code.js — but with nothing real to
+// measure, this stays a generous backstop rather than a measured ceiling.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+/**
+ * Read one aider history file as an array of raw text lines.
+ *
+ * Both known formats are already meaningfully line-oriented, so no
+ * reformatting is needed before pattern matching:
+ *   - .aider.chat.history.md is Markdown — every line (a `#### ` prompt
+ *     line, a `> ` tool-notice line, a fenced-code-block line, plain
+ *     assistant prose) is exactly one scanned line, same as any other text
+ *     file this codebase reads.
+ *   - .aider.input.history is prompt_toolkit's FileHistory serialization —
+ *     each stored input's lines are written back out one per file line,
+ *     each prefixed with a literal `+` (plus interleaved `# <datetime>`
+ *     comment lines) — see source citation #4 in the module docstring. The
+ *     leading `+` is left in place rather than stripped: every pattern in
+ *     src/patterns.js matches on `\b` word boundaries, never a `^`
+ *     line-start anchor (checked directly against patterns.js), so a
+ *     secret on a `+`-prefixed line is matched exactly as it would be
+ *     without the prefix. Stripping it would be extra code with no
+ *     detection benefit.
+ *
+ * Implementation (streaming via readline/promises, MAX_BYTES cap,
+ * READ_TIMEOUT_MS watchdog, partial-read lines kept rather than discarded)
+ * is deliberately identical in shape to claude-code.js's readLines() — see
+ * that file's docstring for the full reasoning on each of those choices,
+ * all of which apply here unchanged (this is plain line-delimited UTF-8
+ * text on disk either way, not a database or JSON blob needing cursor.js's
+ * different approach). Duplicated rather than imported, per this project's
+ * one-small-self-contained-file-per-source convention (see cursor.js's own
+ * docstring for the same point).
+ */
+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; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    // Whatever WAS read before the failure is real content and may contain
+    // a real secret — discarding it because the file didn't finish cleanly
+    // would be a silent false negative, same reasoning as claude-code.js.
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };