residoo 0.1.0 → 0.2.0

package/src/patterns.js

@@ -28,12 +28,13 @@ const PATTERNS = [
     re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/g },
   { id: "stripe_key", label: "Stripe API key", confidence: "high",
     re: /\b(sk|rk)_live_[A-Za-z0-9]{20,}\b/g },
-  // The negative lookahead keeps this rule and anthropic_key mutually exclusive —
-  // without it, "sk-ant-..." matches BOTH patterns and gets reported twice under
-  // two different (one wrong) provider labels. Verified: both regexes independently
-  // matched a synthetic sk-ant- key before this fix.
+  // The negative lookahead keeps this rule mutually exclusive with anthropic_key
+  // and openrouter_key below — without it, "sk-ant-..." or "sk-or-v1-..." match
+  // BOTH this pattern and the more specific one, and get reported twice under
+  // two different (one wrong) provider labels. Verified: all three regexes
+  // independently matched their overlapping synthetic keys before this fix.
   { id: "openai_key", label: "OpenAI API key", confidence: "high",
-    re: /\bsk-(?!ant-)(proj-)?[A-Za-z0-9_-]{20,}\b/g },
+    re: /\bsk-(?!ant-|or-)(proj-)?[A-Za-z0-9_-]{20,}\b/g },
   { id: "anthropic_key", label: "Anthropic API key", confidence: "high",
     re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
   { id: "google_api_key", label: "Google / Firebase API key", confidence: "high",
@@ -54,6 +55,78 @@ const PATTERNS = [
     re: /"refresh_token"\s*:\s*"[^"\s]{20,}"/gi },
   { id: "access_token_field", label: "access_token field", confidence: "medium",
     re: /"access_token"\s*:\s*"[^"\s]{20,}"/gi },
+
+  // ── AI / LLM providers (added: competitive gap-close, see project history) ─
+  // Every regex body below was checked against a production, field-tested
+  // detector — trufflehog's (github.com/trufflesecurity/trufflehog,
+  // pkg/detectors/<vendor>) — not guessed from a blog post, as of 2026-09.
+  // Cohere, Mistral, Together AI, Fireworks and DeepSeek were researched too
+  // and deliberately left out: none has a trufflehog detector, official docs
+  // describe them as unprefixed/opaque tokens, and DeepSeek's "sk-" prefix is
+  // provably indistinguishable from OpenAI's (trufflehog's own DeepSeek
+  // detector only fires with a nearby "deepseek" keyword as extra context,
+  // which this flat-regex model doesn't have) — exactly the shaky-prefix case
+  // this file's own header comment says to leave out rather than force.
+  { id: "groq_key", label: "Groq API key", confidence: "high",
+    re: /\bgsk_[a-zA-Z0-9]{52}\b/g },
+  { id: "xai_key", label: "xAI (Grok) API key", confidence: "high",
+    re: /\bxai-[0-9a-zA-Z_]{80}\b/g },
+  { id: "openrouter_key", label: "OpenRouter API key", confidence: "high",
+    re: /\bsk-or-v1-[0-9a-f]{64}\b/g },
+  { id: "huggingface_token", label: "Hugging Face access token", confidence: "high",
+    re: /\b(?:hf_|api_org_)[a-zA-Z0-9]{34}\b/g },
+  { id: "pinecone_key", label: "Pinecone API key", confidence: "high",
+    re: /\bpcsk_[A-Za-z0-9]{5,6}_[A-Za-z0-9]{63}\b/g },
+  // No trufflehog detector exists for this one, so it leans on a second,
+  // independent signal instead: Perplexity's own product is literally named
+  // "pplx-api" (see their "Introducing pplx-api" launch post), and every
+  // integration doc that shows a real key (liteLLM, apideck, etc.) agrees on
+  // "pplx-" + a >=40-char body — consistent across independent sources even
+  // without one canonical spec page.
+  { id: "perplexity_key", label: "Perplexity API key", confidence: "high",
+    re: /\bpplx-[A-Za-z0-9]{40,}\b/g },
+  { id: "replicate_token", label: "Replicate API token", confidence: "high",
+    re: /\br8_[0-9A-Za-z_-]{37}\b/g },
+
+  // ── Cloud / infra ──────────────────────────────────────────────────────
+  { id: "digitalocean_token", label: "DigitalOcean access token", confidence: "high",
+    re: /\b(?:dop|doo|dor)_v1_[a-f0-9]{64}\b/g },
+  { id: "supabase_token", label: "Supabase personal access token", confidence: "high",
+    re: /\bsbp_[a-z0-9]{40}\b/g },
+  { id: "vault_token", label: "HashiCorp Vault service token", confidence: "high",
+    // Vault 1.10+ format only (hvs.<90-120 chars>). The pre-1.10 legacy
+    // format is a bare "s." + 18-40 chars — "s." is nowhere near specific
+    // enough to be a vendor prefix, so that older shape is deliberately left
+    // out rather than turned into a noisy 2-character trigger.
+    re: /\bhvs\.[A-Za-z0-9_-]{90,120}\b/g },
+  { id: "onepassword_service_token", label: "1Password service account token", confidence: "high",
+    // Confirmed against 1Password's own developer docs (developer.1password.com
+    // -> 1password.dev/service-accounts/security): the token is "ops_" plus a
+    // base64-encoded JWT, so it always continues "eyJ" (base64 of `{"`).
+    re: /\bops_eyJ[A-Za-z0-9+/=_-]{40,}\b/g },
+
+  // ── Comms / SaaS ───────────────────────────────────────────────────────
+  { id: "discord_webhook", label: "Discord webhook URL", confidence: "high",
+    re: /\bhttps:\/\/discord\.com\/api\/webhooks\/[0-9]{18,19}\/[0-9a-zA-Z_-]{68}\b/g },
+  { id: "telegram_bot_token", label: "Telegram bot token", confidence: "high",
+    re: /\b[0-9]{8,10}:[a-zA-Z0-9_-]{35}\b/g },
+  { id: "mailgun_key", label: "Mailgun API key", confidence: "high",
+    re: /\bkey-[a-z0-9]{32}\b/g },
+  // Notion's own docs explicitly warn against regex-matching its tokens,
+  // since the format has changed before and may again — noted, not ignored,
+  // and worth restating here rather than treating this as equally solid as
+  // the others. secret_ (legacy, exactly 43 chars) is trufflehog-verified;
+  // ntn_ (current format since 2024-09-25) is vendor-confirmed as a prefix
+  // but Notion has not published an exact body length for it, so its bound
+  // below is a floor, not a verified exact count.
+  { id: "notion_token", label: "Notion integration token", confidence: "high",
+    re: /\b(?:secret_[A-Za-z0-9]{43}|ntn_[A-Za-z0-9]{20,})\b/g },
+  { id: "linear_key", label: "Linear API key", confidence: "high",
+    re: /\blin_api_[0-9A-Za-z]{40}\b/g },
+  { id: "sentry_token", label: "Sentry auth token", confidence: "high",
+    // Covers both current Sentry token shapes: org-scoped (sntrys_, base64
+    // JWT-like body) and user-scoped (sntryu_, hex body).
+    re: /\b(?:sntrys_eyJ[A-Za-z0-9+/=_]{100,}|sntryu_[a-f0-9]{64})\b/g },
 ];
 
 /**

package/src/report.js

@@ -28,13 +28,60 @@ function ageDays(mtimeMs) {
   return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
 }
 
-function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false } = {}) {
+/**
+ * The integrity section — findings from src/integrity.js, rendered in the
+ * same visual language as the scan report. Severity drives everything:
+ * "warn" (a verified campaign signature, or a location that exists but
+ * couldn't be verified) paints red and counts toward --fail-on-find; "info"
+ * (a hook/rules file that runs automatically and merely deserves the user's
+ * confirmation) stays dim. Every finding is printed — integrity findings are
+ * few by construction (checkIntegrity caps its own noise), so unlike scan
+ * findings they are never truncated to a top-N.
+ *
+ * Exported separately because cli.js's "no transcript sources on this
+ * machine" path still runs the integrity checks — a planted repo-level hook
+ * is exactly as dangerous on a machine with no transcripts to scan.
+ */
+function renderIntegrity(integrity, { noColor = false } = {}) {
+  const paint = makePaint(noColor);
+  const lines = [];
+  const push = (s = "") => lines.push(s);
+
+  const warns = integrity.findings.filter((f) => f.severity === "warn");
+  const infos = integrity.findings.filter((f) => f.severity === "info");
+  const checked = integrity.filesChecked.filter((f) => f.status === "checked").length;
+  const absent = integrity.filesChecked.filter((f) => f.status === "absent").length;
+
+  if (integrity.findings.length === 0) {
+    push(paint(c.green + c.bold, "✓ Integrity: no planted hooks, droppers, or hidden instructions detected") +
+      `: ${checked} location${checked === 1 ? "" : "s"} checked, ${absent} absent.`);
+  } else if (warns.length > 0) {
+    push(paint(c.red + c.bold, `⚠  Integrity: ${warns.length} warning${warns.length === 1 ? "" : "s"}`) +
+      (infos.length > 0 ? ` + ${infos.length} item${infos.length === 1 ? "" : "s"} to review` : "") +
+      paint(c.dim, ` · ${checked} location${checked === 1 ? "" : "s"} checked`));
+  } else {
+    push(paint(c.bold, `Integrity: ${infos.length} item${infos.length === 1 ? "" : "s"} to review`) +
+      paint(c.dim, ` (nothing matching a known campaign signature) · ${checked} location${checked === 1 ? "" : "s"} checked`));
+  }
+  for (const f of warns) {
+    push(`  ${paint(c.red, "warn")}  ${paint(c.cyan, f.file)}`);
+    push(`        ${f.detail}`);
+  }
+  for (const f of infos) {
+    push(`  ${paint(c.dim, "info")}  ${paint(c.cyan, f.file)}`);
+    push(paint(c.dim, `        ${f.detail}`));
+  }
+  push(paint(c.dim, `   ${integrity.scopeNote}`));
+  return lines.join("\n");
+}
+
+function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false, integrity = null } = {}) {
   const paint = makePaint(noColor);
   const lines = [];
   const push = (s = "") => lines.push(s);
 
   const suppressedNote = suppressedCount > 0
-    ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text — see --include-suppressed)`)
+    ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text; see --include-suppressed)`)
     : "";
   // Surfaced, not silent: a file that couldn't be (fully) read was not fully
   // scanned, and a report must not read as "checked and found nothing" for
@@ -43,14 +90,18 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   // project-name-derived directory slug, which is exactly the kind of thing
   // every other line in this report is careful to redact down from.
   const unreadableNote = unreadableFiles.length > 0
-    ? paint(c.yellow, `⚠  ${unreadableFiles.length} file(s) not fully scanned — see --json for which and why.`)
+    ? paint(c.yellow, `⚠  ${unreadableFiles.length} file(s) not fully scanned. See --json for which and why.`)
     : null;
 
   if (findings.length === 0) {
     push(paint(c.green + c.bold, "✓ No exposed secrets found") +
-      ` — ${filesScanned} file${filesScanned === 1 ? "" : "s"} scanned across ${sourcesScanned.join(", ") || "no sources"}.` +
+      `: ${filesScanned} file${filesScanned === 1 ? "" : "s"} scanned across ${sourcesScanned.join(", ") || "no sources"}.` +
       suppressedNote);
     if (unreadableNote) push(unreadableNote);
+    if (integrity) {
+      push();
+      push(renderIntegrity(integrity, { noColor }));
+    }
     return lines.join("\n");
   }
 
@@ -91,14 +142,22 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
   }
   if (byFile.size > fileRows.length) push(paint(c.dim, `  … and ${byFile.size - fileRows.length} more file(s)`));
 
+  if (integrity) {
+    push();
+    push(renderIntegrity(integrity, { noColor }));
+  }
+
   push();
-  push(paint(c.dim, "Values are redacted in this report — first/last 4 characters only. Nothing scanned"));
+  push(paint(c.dim, "Values are redacted in this report (first/last 4 characters only). Nothing scanned"));
   push(paint(c.dim, "here left your machine; residoo makes no network calls. Run with --json for full detail."));
 
   return lines.join("\n");
 }
 
-function renderJson(result) {
+// `integrity` is the checkIntegrity() result, or null when --no-integrity
+// skipped it — the key is always present so a --json consumer can tell
+// "checked, clean" apart from "never checked" without guessing from absence.
+function renderJson(result, integrity = null) {
   return JSON.stringify(
     {
       summary: {
@@ -114,10 +173,18 @@ function renderJson(result) {
         rule: f.ruleId, label: f.label, confidence: f.confidence,
         source: f.source, file: f.relFile, line: f.line, preview: f.preview,
       })),
+      integrity: integrity
+        ? {
+            warningCount: integrity.findings.filter((f) => f.severity === "warn").length,
+            findings: integrity.findings,
+            filesChecked: integrity.filesChecked,
+            scopeNote: integrity.scopeNote,
+          }
+        : null,
     },
     null,
     2
   );
 }
 
-module.exports = { render, renderJson };
+module.exports = { render, renderIntegrity, renderJson };

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 };