residoo 0.1.0 → 0.2.0

package/src/sources/codex-cli.js

@@ -0,0 +1,258 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { createInterface } = require("readline/promises");
+
+/**
+ * OpenAI's Codex CLI (the `codex` coding-agent binary — see
+ * https://github.com/openai/codex — NOT the retired "Codex" language model
+ * from 2021). Also referred to below as "Codex CLI" throughout to keep that
+ * distinction unambiguous.
+ *
+ * VERIFICATION STATUS: this source was NOT checked against a real Codex CLI
+ * install — `codex` is not installed on the machine this adapter was built
+ * on (checked: no `codex` on PATH, no `~/.codex`, no Homebrew/npm-global
+ * install, mdfind turned up nothing for a local CLI install — the only
+ * "codex" hits on this machine were the ChatGPT desktop app's own unrelated
+ * `com.openai.chat` local cache for its cloud-hosted "Codex" task feature,
+ * which is a different product with no local session transcripts of its
+ * own to scan; it runs in a remote container, not on this machine). Per
+ * CONTRIBUTING.md this ships anyway because it clears that bar a different
+ * way: multiple independent, credible, and largely recent sources agree
+ * with each other on the exact path and schema below, including official
+ * OpenAI documentation, the tool's own GitHub issue tracker describing this
+ * exact file layout as a live bug surface, and more than one third-party
+ * tool that reads these same files for a living. Specifically:
+ *
+ *  - Official docs (developers.openai.com/codex/environment-variables,
+ *    redirects to learn.chatgpt.com/docs/config-file/environment-variables):
+ *    CODEX_HOME "sets the root directory for Codex state, including config,
+ *    auth, logs, sessions, skills, and standalone package metadata,"
+ *    defaulting to `~/.codex`.
+ *  - openai/codex GitHub issue #21660 ("rollout: session JSONL files are
+ *    created world-readable (mode 0644) on Unix") and issue #20864
+ *    ("Codex Desktop App becomes laggy because it scans all
+ *    `~/.codex/sessions` rollout files...") — both filed against the real
+ *    tool, both independently naming this exact directory.
+ *  - openai/codex GitHub Discussion #24042, a real, working, open-source
+ *    native macOS viewer built specifically to read `~/.codex/sessions/
+ *    *.jsonl`, and community tools codex-trace (PixelPaw-Labs) and
+ *    codex-history-list (shinshin86) doing the same — the kind of "a
+ *    maintained tool reads the same files" corroboration CONTRIBUTING.md
+ *    calls out explicitly.
+ *  - openai/codex GitHub issue #17000 ("Auto-archive and zstd-compress
+ *    inactive local rollout files...") independently confirms the
+ *    `rollout-*.jsonl` naming and the date-partitioned directory shape by
+ *    proposing changes to it. NOTE: this issue also shows the zstd
+ *    compression feature it proposes is NOT yet shipped as of this
+ *    research — a compression detail that appeared in one AI-generated
+ *    summary was traced back to this still-open proposal, not a shipped
+ *    behavior, so no zstd decompression is assumed live here. It's still
+ *    handled defensively below (see ZSTD_RE) in case that changes.
+ *  - Independent write-ups (a dev.to reverse-engineering post showing real
+ *    rollout JSONL line shapes, prismmd.app and betelgeuse.work blog posts,
+ *    and a Codex-Knowledge-Base article on session archiving) all agree on
+ *    the same `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`
+ *    shape and on a parallel `~/.codex/archived_sessions/` tree used when a
+ *    session is archived (the rollout JSONL is moved, not transformed).
+ *  - Multiple of the above also describe a flat `~/.codex/history.jsonl` —
+ *    one line per user turn, holding just the raw text the user typed for
+ *    that turn (not the full conversation) — which is real, secret-scanning
+ *    -relevant content (a pasted key or token lands here) distinct from the
+ *    per-session rollout files, so it's read too.
+ *
+ * Deliberately NOT read: `~/.codex/session_index.jsonl`. Independent
+ * sources agree it is a lightweight metadata cache only (id, timestamp,
+ * cwd, model, status) that explicitly does NOT duplicate rollout content —
+ * scanning it would add file-walk cost with no realistic chance of a
+ * secret-bearing line. Also not read: anything under `~/.codex` that isn't
+ * one of the three content locations above — chiefly `config.toml`,
+ * `auth.json`, and `log/`, which are Codex's own config/credential/log
+ * files, not session transcript content, mirroring how claude-code.js and
+ * cursor.js each stay scoped to actual conversation data rather than a
+ * tool's entire state directory.
+ *
+ * If you have Codex CLI installed, the most useful thing you can do is run
+ * `residoo scan` and confirm `sourcesScanned`/`filesScanned` look right for
+ * what you know is actually on disk under `~/.codex`, then report back
+ * either way — see CONTRIBUTING.md.
+ */
+function codexHome() {
+  // Honoring CODEX_HOME (rather than hardcoding ~/.codex) mirrors how
+  // cursor.js honors XDG_CONFIG_HOME — the tool's own documented override,
+  // not a guess, and the official docs above are explicit that sessions,
+  // not just config, live under this root.
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+  return path.join(os.homedir(), ".codex");
+}
+
+const ROOT = codexHome();
+const SESSIONS_DIR = path.join(ROOT, "sessions");
+const ARCHIVED_SESSIONS_DIR = path.join(ROOT, "archived_sessions");
+const HISTORY_FILE = path.join(ROOT, "history.jsonl");
+
+// A rollout file this large has not been reported anywhere in this source's
+// research; kept identical to claude-code.js's bound (same underlying
+// concern — V8's whole-string ceiling doesn't apply here since this source
+// also streams line-by-line, but a shared, already-reasoned-about number
+// beats inventing a new one with no evidence behind it).
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+// Symlink-loop safety for the recursive sessions/archived_sessions walk.
+// claude-code.js never needed a depth bound — its walk is exactly two
+// levels (project dir, then files in it). Walking an arbitrary
+// YYYY/MM/DD(/...)? tree that may itself contain a symlink is a genuinely
+// new risk this source introduces, so it gets a guard claude-code.js didn't
+// need. 12 gives generous headroom over the documented 3-level date
+// partitioning while still bounding a pathological symlink cycle.
+const MAX_WALK_DEPTH = 12;
+
+// See the ZSTD note in the module docstring: not confirmed shipped, but
+// handled honestly rather than assumed absent forever. A zero-dependency
+// project has no built-in Zstandard decoder available across the supported
+// Node range (>=18), so a matching file is surfaced as a normal, resolvable
+// file entry (not "broken" — it's not unresolvable, just undecodable by
+// this tool) and readLines() reports it "failed" rather than silently
+// omitting it from the walk.
+const ZSTD_RE = /\.zst$/i;
+const JSONL_RE = /\.jsonl$/i;
+
+function id() { return "codex-cli"; }
+function label() { return "Codex CLI"; }
+
+function available() {
+  try { return fs.statSync(ROOT).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Same lstat-vs-stat symlink-following pattern as claude-code.js's
+ * isKindFollowingSymlink — duplicated rather than imported, matching this
+ * project's convention (cursor.js's docstring on the same duplication:
+ * "each source in this project is meant to be a small, self-contained file
+ * a reviewer can audit on its own").
+ */
+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());
+
+/**
+ * Recursively walk one directory (sessions/ or archived_sessions/) yielding
+ * { file, mtimeMs, sizeBytes, broken } for every `*.jsonl` (scanned) and
+ * `*.zst` (surfaced, see ZSTD_RE above) file found at any depth, following
+ * symlinks the same way claude-code.js's files() does for project dirs and
+ * jsonl files, and reporting a dangling symlink as broken rather than
+ * skipping it silently. Any other file extension under this tree is out of
+ * scope, same as claude-code.js ignoring non-`.jsonl` entries.
+ */
+function* walkSessionDir(dir, depth) {
+  if (depth > MAX_WALK_DEPTH) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; } // dir vanished or unreadable mid-walk — not reportable, nothing was ever yielded for it
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+
+    if (!e.isFile() && !e.isDirectory()) {
+      // Symlink (or other special entry) — resolve to find out which kind.
+      if (isDirFollowingSymlink(full, e)) { yield* walkSessionDir(full, depth + 1); continue; }
+      if (isFileFollowingSymlink(full, e)) {
+        if (!JSONL_RE.test(e.name) && !ZSTD_RE.test(e.name)) continue;
+        let stat;
+        try { stat = fs.statSync(full); } catch { yield { file: full, broken: true }; continue; }
+        yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+        continue;
+      }
+      // Didn't resolve to either — a dangling symlink is the plausible
+      // real-world case (see claude-code.js's identical reasoning).
+      if (e.isSymbolicLink()) yield { file: full, broken: true };
+      continue;
+    }
+
+    if (e.isDirectory()) { yield* walkSessionDir(full, depth + 1); continue; }
+
+    if (!JSONL_RE.test(e.name) && !ZSTD_RE.test(e.name)) continue;
+    let stat;
+    try { stat = fs.statSync(full); } catch { yield { file: full, broken: true }; continue; }
+    yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every rollout file under
+ * sessions/ and archived_sessions/, plus the single flat history.jsonl —
+ * see the module docstring for why each of these three (and only these
+ * three) locations is read.
+ */
+function* files() {
+  yield* walkSessionDir(SESSIONS_DIR, 0);
+  yield* walkSessionDir(ARCHIVED_SESSIONS_DIR, 0);
+
+  // history.jsonl is a single fixed-name file, not a directory to walk —
+  // same lstat-first, follow-if-symlink handling as cursor.js's
+  // statIfPresent, and a path that simply doesn't exist (most installs,
+  // depending on version/config) is normal, not broken.
+  let lst;
+  try { lst = fs.lstatSync(HISTORY_FILE); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(HISTORY_FILE);
+      if (!st.isFile()) { yield { file: HISTORY_FILE, broken: true }; return; }
+      yield { file: HISTORY_FILE, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: HISTORY_FILE, broken: true };
+    }
+    return;
+  }
+  if (!lst.isFile()) return;
+  yield { file: HISTORY_FILE, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * Read one file as an array of raw text lines. Identical streaming strategy
+ * to claude-code.js's readLines (see that file's docstring for the full
+ * reasoning on why streaming + a read timeout + honest partial-read
+ * handling all matter) — duplicated rather than shared, per this project's
+ * one-file-per-source convention. The one addition is the zstd short-circuit
+ * at the top; see ZSTD_RE above.
+ */
+async function readLines(file) {
+  if (ZSTD_RE.test(file)) return { lines: [], status: "failed", bytesRead: 0 };
+
+  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/cody.js

@@ -0,0 +1,325 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Sourcegraph Cody — the VS Code extension (publisher.name `sourcegraph.cody-ai`).
+ *
+ * VERIFICATION STATUS (read this before trusting anything below):
+ * multi-source-corroborated-but-UNVERIFIED against a real install. Neither VS
+ * Code nor the Cody extension is installed on the machine this adapter was
+ * built on (checked: no /Applications/*Code*.app, no `code`/`code-insiders`
+ * on PATH, no ~/Library/Application Support/Code, no
+ * ~/.vscode/extensions/sourcegraph.cody-ai-*, no
+ * ~/Library/Application Support/JetBrains/<product>/options/cody_history.xml).
+ * What
+ * IS unusually strong here, short of a real install: the storage mechanism
+ * was read directly out of two projects' own current shipped source — not
+ * inferred from a blog post — cross-checked against Sourcegraph's own docs:
+ *
+ *   1. CODY'S OWN SOURCE, read directly from
+ *      github.com/sourcegraph/cody-public-snapshot (`main`,
+ *      vscode/src/services/LocalStorageProvider.ts, fetched verbatim via
+ *      `gh api repos/sourcegraph/cody-public-snapshot/contents/...` on
+ *      2026-09-02): the class keeps
+ *        `protected readonly KEY_LOCAL_HISTORY = 'cody-local-chatHistory-v2'`
+ *      and every read/write of chat history
+ *      (getChatHistory/setChatHistory/deleteChatHistory) goes through
+ *      `this.storage.get/update(this.KEY_LOCAL_HISTORY, ...)`, where
+ *      `this.storage` is set, once, at extension activation via
+ *      `localStorage.setStorage(context.globalState)` (see the same file,
+ *      `activate()`/`initVSCodeStorage()` in `LocalStorageProvider.ts` and
+ *      `extension.node.ts`) — i.e. the standard VS Code extension `Memento`
+ *      API (`context.globalState`), not a bespoke file Cody writes itself.
+ *      `vscode/package.json` (same repo, same fetch) confirms the extension's
+ *      identity: `"name": "cody-ai"`, `"publisher": "sourcegraph"` — VS
+ *      Code's own `getExtensionId(publisher, name)` (see next point) makes
+ *      that `sourcegraph.cody-ai`, matching the `globalStorage/
+ *      sourcegraph.cody-ai/` path fragment independently named in
+ *      Sourcegraph's own troubleshooting docs
+ *      (sourcegraph.com/docs/cody/troubleshooting, a real user's globalStorage
+ *      resource path is quoted there verbatim).
+ *
+ *   2. VS CODE'S OWN SOURCE for what `context.globalState` actually resolves
+ *      to on disk, read directly from github.com/microsoft/vscode (`main`,
+ *      fetched the same way, 2026-09-02):
+ *        - `src/vs/workbench/api/browser/mainThreadStorage.ts` —
+ *          `$setValue(shared, key, value)` calls
+ *          `extensionStorageService.setExtensionState(key, value, shared)`,
+ *          where `key` here is the calling extension's id, not a
+ *          caller-chosen storage key.
+ *        - `src/vs/platform/extensionManagement/common/extensionStorage.ts`
+ *          — `setExtensionState(extension, state, global)` resolves
+ *          `extensionId = getExtensionId(extension)` and then does
+ *          `storageService.store(extensionId, JSON.stringify(state),
+ *          global ? StorageScope.PROFILE : StorageScope.WORKSPACE, ...)`.
+ *          `getExtensionId(publisher, name)` (`extensionManagementUtil.ts`)
+ *          is exactly `` `${publisher}.${name}` ``.
+ *        - Net effect: EVERY globalState key an extension sets (Cody's
+ *          `cody-local-chatHistory-v2` included) is merged into ONE JSON
+ *          object, and that whole object is stored as a SINGLE row, keyed by
+ *          the extension id itself, in the PROFILE-scope storage — which is
+ *          the same shared, per-profile `state.vscdb` / `ItemTable` that
+ *          cursor.js already reads for Cursor's own tables in this project
+ *          (Cursor is a VS Code fork; this is the un-forked, upstream version
+ *          of that exact mechanism). This is CORE VS Code behavior, not
+ *          Cody-specific or version-fragile the way Cursor's own bespoke
+ *          `cursorDiskKV` table naming has reportedly been (see cursor.js).
+ *
+ * Net path: `<VS Code User dir>/globalStorage/state.vscdb`, table
+ * `ItemTable`, one row with `key = 'sourcegraph.cody-ai'` whose `value` is a
+ * JSON object containing (among any other keys the extension has ever set)
+ * `cody-local-chatHistory-v2` — every chat transcript title, message, and any
+ * pasted code/output the user has had Cody see.
+ *
+ * Deliberately scoped to VS Code only. Cody also ships a JetBrains plugin,
+ * but its chat history lives in a fundamentally different place: read
+ * directly from the same cody-public-snapshot repo,
+ * `jetbrains/src/main/kotlin/com/sourcegraph/cody/history/HistoryService.kt`
+ * declares `@State(name = "ChatHistory", storages =
+ * [Storage("cody_history.xml")])` at `@Service(Service.Level.PROJECT)` —
+ * PROJECT level, meaning one `cody_history.xml` per JetBrains project
+ * (typically under that project's own `.idea/` directory), not one file
+ * under a single, enumerable user-profile directory the way every other
+ * source in this project works. Finding those would mean either scanning the
+ * whole filesystem for `.idea/cody_history.xml` or trusting a JetBrains
+ * "recent projects" list — neither verified here and both a meaningfully
+ * different shape of problem — so it is left out rather than guessed at. See
+ * CONTRIBUTING.md.
+ *
+ * Only the DEFAULT VS Code profile is covered, for the same reason
+ * copilot-chat.js in this project already gives for itself: a non-default
+ * profile's globalStorage lives under `User/profiles/<profileId>/...`
+ * instead of `User/globalStorage` directly, per
+ * `IUserDataProfilesService.defaultProfile` in the same VS Code source read
+ * above.
+ */
+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 id() { return "cody"; }
+function label() { return "Sourcegraph Cody"; }
+
+/**
+ * Same lazy-require pattern as cursor.js, for the same reason: index.js
+ * requires every source unconditionally, so an eager top-level
+ * `require("node:sqlite")` would print Node's one-per-process
+ * ExperimentalWarning for every user on Node 22.5+, even the large majority
+ * who have never installed VS Code at all. See cursor.js's own docstring on
+ * getDatabaseSync() for the full reasoning — duplicated here rather than
+ * imported, matching this project's "small, self-contained file" convention.
+ */
+const NODE_SQLITE_REQUIREMENT = "needs Node.js 22.5+ (node:sqlite not present in this runtime)";
+let sqliteRequireAttempted = false;
+let DatabaseSync = null;
+
+function getDatabaseSync() {
+  if (!sqliteRequireAttempted) {
+    sqliteRequireAttempted = true;
+    try { ({ DatabaseSync } = require("node:sqlite")); }
+    catch { DatabaseSync = null; }
+  }
+  return DatabaseSync;
+}
+
+function anyVscodeUserDirExists() {
+  return vscodeUserDirs().some((dir) => {
+    try { return fs.statSync(dir).isDirectory(); } catch { return false; }
+  });
+}
+
+function available() {
+  // Cheap fs check first, on purpose — see cursor.js's available() for why
+  // short-circuiting here matters (skip requiring node:sqlite, and its
+  // possible warning, when there is plainly nothing to read).
+  return anyVscodeUserDirExists() && Boolean(getDatabaseSync());
+}
+
+/**
+ * Same optional, additive contract as cursor.js's unavailableReason() — see
+ * that file's docstring. Only fires for the one case worth calling out: a VS
+ * Code User dir genuinely exists but this Node runtime is too old for
+ * node:sqlite, so silently vanishing from "Sources checked" would misread as
+ * "VS Code isn't installed," which would be false.
+ */
+function unavailableReason() {
+  if (!anyVscodeUserDirExists()) return null;
+  if (getDatabaseSync()) return null;
+  return `Sourcegraph Cody detected but not scanned — ${NODE_SQLITE_REQUIREMENT}`;
+}
+
+/**
+ * Same defensive symlink-following stat, duplicated from cursor.js's
+ * statIfPresent — see that file's docstring for the full reasoning. A path
+ * that doesn't exist yields nothing (normal: e.g. no "Code - Insiders" User
+ * dir because Insiders was never installed); a dangling symlink is reported
+ * `broken: true` rather than silently skipped.
+ */
+function* statIfPresent(dbPath) {
+  let lst;
+  try { lst = fs.lstatSync(dbPath); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(dbPath); // follow the link
+      if (!st.isFile()) { yield { file: dbPath, broken: true }; return; }
+      yield { file: dbPath, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: dbPath, broken: true }; // dangling symlink
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return; // something unexpected sits at this path — out of scope, not broken
+  yield { file: dbPath, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for the default profile's
+ * state.vscdb under every VS Code variant this adapter checks (standard +
+ * Insiders). Purely a filesystem walk + stat — never opens the database, so
+ * it works even in a Node runtime where node:sqlite isn't available (only
+ * readLines() actually needs it, same division of labour as cursor.js).
+ */
+function* files() {
+  for (const userDir of vscodeUserDirs()) {
+    yield* statIfPresent(path.join(userDir, "globalStorage", "state.vscdb"));
+  }
+}
+
+// Not backed by a real Cody state.vscdb row this tool was tested against (no
+// VS Code install to test with) — see the verification-status note above.
+// Generous backstop against a corrupted/pathological file, same rationale as
+// cursor.js's own MAX_DB_BYTES.
+const MAX_DB_BYTES = 512 * 1024 * 1024;
+const READ_TIMEOUT_MS = 60_000;
+const BUSY_TIMEOUT_MS = 5_000;
+
+/**
+ * Cody's extension id is `sourcegraph.cody-ai` (verified directly against
+ * vscode/package.json — see the module docstring). The LIKE clause is a
+ * deliberately narrow safety margin, not a guess-widening: it catches a
+ * differently-suffixed Sourcegraph Cody extension id (e.g. a possible future
+ * `sourcegraph.cody-ai-nightly`-style variant) without sweeping in any other
+ * publisher's or extension's state the way reading the whole ItemTable
+ * (cursor.js's approach, appropriate there because Cursor owns that entire
+ * file) would for a shared, multi-extension file like this one.
+ */
+const CODY_KEY_PATTERN = "sourcegraph.cody%";
+
+/**
+ * Same storage-class handling as cursor.js's valueToText — see that file's
+ * docstring. A PROFILE-scope row here is written via
+ * `JSON.stringify(state)` (see module docstring), i.e. always a JS string
+ * (TEXT storage class) in every real case this adapter's research found, but
+ * the BLOB fallback is kept for parity with cursor.js and cheap insurance
+ * against a SQLite storage-class surprise.
+ */
+function valueToText(value) {
+  if (typeof value === "string") return value;
+  if (value instanceof Uint8Array) return Buffer.from(value).toString("utf-8");
+  return null;
+}
+
+/**
+ * Read one state.vscdb's Cody-owned row(s) as an array of raw text "lines" —
+ * one per matching ItemTable row's decoded value (in practice, at most one:
+ * a single row keyed `sourcegraph.cody-ai` holding a JSON object with every
+ * globalState key the extension has ever set, `cody-local-chatHistory-v2`
+ * included). Returns { lines, status, bytesRead } with the same status
+ * vocabulary as every other source in this project.
+ *
+ * Synchronous node:sqlite, same "no real preemptive timeout possible, so
+ * check a wall-clock deadline between statements" approach as cursor.js —
+ * see that file's docstring. With at most a handful of matching rows here
+ * (unlike cursor.js's tens-of-thousands-of-rows cursorDiskKV table), the
+ * per-row yield-to-event-loop machinery is far less likely to matter in
+ * practice, but the deadline check is kept for consistency and as insurance
+ * against a single pathologically large row's own decode time — the same
+ * named, un-bounded asymmetry cursor.js's own docstring admits.
+ */
+async function readLines(file) {
+  const DB = getDatabaseSync();
+  if (!DB) return { lines: [], status: "failed", bytesRead: 0 };
+
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_DB_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  let db;
+  try {
+    db = new DB(file, { readOnly: true });
+    db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+  } catch {
+    // Deleted between files() and this call, a corrupt/non-SQLite file at
+    // this path, or VS Code holding a lock this readonly open can't get past
+    // within BUSY_TIMEOUT_MS — genuinely "could not read this," not "read it,
+    // found nothing." Status "failed" keeps the scan report honest about
+    // that difference (CONTRIBUTING.md rule 5).
+    return { lines: [], status: "failed", bytesRead: 0 };
+  }
+
+  let rows;
+  try {
+    rows = db.prepare("SELECT value FROM ItemTable WHERE key LIKE ?").iterate(CODY_KEY_PATTERN);
+  } catch {
+    // ItemTable itself doesn't exist — this file opened fine as SQLite but
+    // didn't match the schema this adapter understands, a real "could not
+    // extract anything," not "extracted zero real rows."
+    try { db.close(); } catch { /* best-effort */ }
+    return { lines: [], status: "failed", bytesRead: 0 };
+  }
+
+  const lines = [];
+  let bytesRead = 0;
+  const deadline = Date.now() + READ_TIMEOUT_MS;
+  let timedOut = false;
+  let sawError = false;
+  let n = 0;
+
+  try {
+    for (const row of rows) {
+      const text = valueToText(row.value);
+      // One matching row becomes one scanned "line," using the value exactly
+      // as VS Code wrote it — not re-parsed/re-stringified — same reasoning
+      // as cursor.js: keeps every byte the regexes depend on intact, and
+      // sidesteps needing to track Cody's own nested key name
+      // (`cody-local-chatHistory-v2`) as it evolves across versions.
+      if (text) { lines.push(text); bytesRead += Buffer.byteLength(text, "utf-8"); }
+      n++;
+      if (n % 500 === 0) {
+        await new Promise((resolve) => setImmediate(resolve));
+        if (Date.now() > deadline) { timedOut = true; break; }
+      }
+    }
+  } catch {
+    // Whatever WAS read before a mid-iteration failure (e.g. a corrupted
+    // page) is real content and may contain a real secret — kept, not
+    // discarded, same as claude-code.js/cursor.js.
+    sawError = true;
+  }
+
+  try { db.close(); } catch { /* best-effort close */ }
+
+  if (sawError && lines.length === 0) return { lines: [], status: "failed", bytesRead };
+  if (timedOut || sawError) return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  return { lines, status: "complete", bytesRead };
+}
+
+module.exports = { id, label, available, unavailableReason, files, readLines };