residoo 0.1.0 → 0.2.0

package/src/sources/kiro-cli.js

@@ -0,0 +1,393 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Kiro CLI (AWS/Kiro's terminal coding agent, binary `kiro-cli` / `kiro`)
+ * session history. Distinct from Kiro IDE (see kiro-ide.js) — same product
+ * family, different application, different storage.
+ *
+ * VERIFICATION STATUS (read this before trusting anything below): the
+ * general shape ("SQLite database in ~/.kiro/", per-directory scoping) is
+ * confirmed directly from Kiro's own official docs
+ * (https://kiro.dev/docs/cli/chat/session-management/, "Technical details"
+ * section — fetched as raw HTML and grepped for the literal text). That
+ * page turns out to be imprecise about the exact path, though (see below) —
+ * caught only by going one step further to a real, actively-maintained,
+ * read-only community tool built specifically to read this data:
+ * github.com/prabhugr/kiro-cli-history. Its own README states plainly "This
+ * tool never writes to or modifies your Kiro CLI session data" and opens
+ * the database "in read-only mode" — and this source fetched and read its
+ * actual Python source (`kiro_history.py`), not just its README prose, the
+ * same standard cursor.js's own research applied to its community source.
+ * This has NOT been checked against a real Kiro CLI install — it is not
+ * installed on the machine this adapter was built on (checked: no `kiro` or
+ * `kiro-cli` on PATH, no `~/.kiro` directory). If you have Kiro 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, then report back either way.
+ *
+ * THREE STORAGE FORMATS. `kiro_history.py`'s own module docstring names
+ * three, and its actual path constants and SQL confirm each one, quoted
+ * near-verbatim:
+ *
+ *   1. v3 (JSONL, used by `kiro-cli --classic`):
+ *      `~/.kiro/sessions/cli/<session-id>.json` (metadata: session_id,
+ *      title, cwd, created_at, updated_at) plus a companion
+ *      `~/.kiro/sessions/cli/<session-id>.jsonl` (the actual conversation —
+ *      one JSON record per line, each with a `kind` field — `"Prompt"` or
+ *      `"AssistantMessage"` observed — and the message text nested at
+ *      `data.content[].data` where `data.content[].kind === "text"`).
+ *      Both files sit FLAT directly in `sessions/cli/`, not nested per
+ *      project — confirmed directly from source (`SESSIONS_DIR.glob("*.json")`,
+ *      a non-recursive glob).
+ *   2. v2 (SQLite, used by the current default TUI mode):
+ *      `~/Library/Application Support/kiro-cli/data.sqlite3` (macOS path —
+ *      this specific tool is macOS-only per its own README), table
+ *      `conversations_v2` — confirmed from its actual query:
+ *      `SELECT key, conversation_id, value, created_at, updated_at FROM
+ *      conversations_v2 ORDER BY updated_at DESC`, where `value` is a JSON
+ *      blob holding the conversation.
+ *   3. v1 (SQLite, legacy): same database file, table `conversations` —
+ *      confirmed from source: `SELECT key, value FROM conversations`, where
+ *      `value` is again a JSON blob (`conversation_id` is read back out of
+ *      the parsed JSON itself here, not a separate column — the schema
+ *      visibly grew a dedicated column between v1 and v2).
+ *
+ * That a real, working tool had to reverse-engineer THREE evolving formats
+ * to stay useful is itself the reason this source discovers tables from
+ * `sqlite_master` at scan time (see readSqliteLines() below) rather than
+ * hardcoding only `conversations`/`conversations_v2` — the same schema-drift
+ * reasoning warp.js documents at length for a comparable situation. A v3-era
+ * SQLite table this source doesn't yet know the name of would still get
+ * scanned.
+ *
+ * WHERE KIRO'S OWN DOCS ARE IMPRECISE: they say simply "SQLite database in
+ * ~/.kiro/" — true of the JSONL sessions (which really do live under
+ * `~/.kiro/`) but not of the SQLite database itself, which in fact lives in
+ * the OS-native local-data directory, a level of precision only the
+ * community tool's actual, working source code provided. This is exactly
+ * the class of error CONTRIBUTING.md's guessed-path warning describes,
+ * caught the same way this project caught an analogous imprecision in a
+ * secondary source for Crush (see crush.js's docstring) — by going to a
+ * source that had to actually work against the real file, not just describe
+ * it.
+ *
+ * PER-OS SQLITE PATH: only the macOS path above is independently confirmed
+ * (kiro-cli-history is explicitly macOS-only). Linux and Windows below are
+ * filled in by structural analogy to the OS-native "local data directory"
+ * convention (Rust's `dirs::data_local_dir()`) — the exact convention this
+ * source separately confirmed, from actual source
+ * (`crates/chat-cli/src/util/paths.rs`), that the sibling AWS product Q
+ * Developer CLI uses for its own `<data-dir>/amazon-q/data.sqlite3` (Kiro
+ * CLI is documented — see kiro.dev's own CLI intro — as building on Q
+ * Developer CLI's agent engine, with `amazon-q` swapped for `kiro-cli` in
+ * exactly the position confirmed on macOS). Flagged as analogy, not
+ * independently quoted, same honesty standard as this project's other
+ * per-OS gaps (e.g. warp.js's Preview-channel filename).
+ */
+function homeDir() { return os.homedir(); }
+
+const KIRO_HOME = path.join(homeDir(), ".kiro");
+const JSONL_SESSIONS_DIR = path.join(KIRO_HOME, "sessions", "cli");
+
+function sqliteDbPath() {
+  if (process.platform === "darwin") {
+    return path.join(homeDir(), "Library", "Application Support", "kiro-cli", "data.sqlite3");
+  }
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || path.join(homeDir(), "AppData", "Local");
+    return path.join(localAppData, "kiro-cli", "data.sqlite3");
+  }
+  // Linux and other XDG-following unix platforms — not independently
+  // confirmed for Kiro CLI specifically; see module docstring.
+  const xdgDataHome = process.env.XDG_DATA_HOME || path.join(homeDir(), ".local", "share");
+  return path.join(xdgDataHome, "kiro-cli", "data.sqlite3");
+}
+
+const SQLITE_DB = sqliteDbPath();
+
+/**
+ * Same lazy-require, feature-detected node:sqlite pattern as cursor.js,
+ * crush.js, and warp.js — see cursor.js's docstring for the full reasoning.
+ * Duplicated rather than shared: each source here is meant to be a small,
+ * self-contained file a reviewer can audit on its own (CONTRIBUTING.md).
+ */
+const NODE_SQLITE_REQUIREMENT = "needs Node.js 22.5+ (node:sqlite not present in this runtime)";
+let sqliteRequireAttempted = false;
+let DatabaseSync = null;
+
+function getDatabaseSync() {
+  if (!sqliteRequireAttempted) {
+    sqliteRequireAttempted = true;
+    try { ({ DatabaseSync } = require("node:sqlite")); }
+    catch { DatabaseSync = null; }
+  }
+  return DatabaseSync;
+}
+
+function id() { return "kiro-cli"; }
+function label() { return "Kiro CLI"; }
+
+function jsonlDirExists() {
+  try { return fs.statSync(JSONL_SESSIONS_DIR).isDirectory(); } catch { return false; }
+}
+
+function sqliteDbExists() {
+  try { return fs.statSync(SQLITE_DB).isFile(); } catch { return false; }
+}
+
+/**
+ * True when either store is present. The JSONL store needs no node:sqlite
+ * at all, so this must not require it merely because the SQLite store also
+ * happens not to exist — same short-circuit-order reasoning as cursor.js's
+ * available(), applied across two independent stores instead of one.
+ */
+function available() {
+  if (jsonlDirExists()) return true;
+  return sqliteDbExists() && Boolean(getDatabaseSync());
+}
+
+/**
+ * Same additive, optional export as cursor.js's/crush.js's/warp.js's
+ * unavailableReason(). Only fires the one case worth calling out
+ * specifically: the SQLite store is the only thing present, and this Node
+ * runtime can't read it. If the JSONL store is present, available() is
+ * already true and there's nothing to explain.
+ */
+function unavailableReason() {
+  if (jsonlDirExists()) return null;
+  if (!sqliteDbExists()) return null;
+  if (getDatabaseSync()) return null;
+  return `Kiro CLI detected but not scanned — ${NODE_SQLITE_REQUIREMENT}`;
+}
+
+// Bounds for readLines() on the JSONL store — same shape as claude-code.js's.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every `.json`/`.jsonl` file
+ * directly under `~/.kiro/sessions/cli/` — flat, non-recursive, matching
+ * kiro-cli-history's own confirmed `SESSIONS_DIR.glob("*.json")` walk (the
+ * companion `.jsonl` files sit alongside, same directory, so a plain
+ * extension filter over one readdir catches both).
+ */
+function* jsonlFiles() {
+  let entries;
+  try { entries = fs.readdirSync(JSONL_SESSIONS_DIR, { withFileTypes: true }); }
+  catch { return; }
+
+  for (const e of entries) {
+    if (!/\.(jsonl|json)$/i.test(e.name)) continue;
+    const full = path.join(JSONL_SESSIONS_DIR, e.name);
+
+    if (e.isFile()) {
+      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;
+    }
+    if (e.isSymbolicLink()) {
+      try {
+        const stat = fs.statSync(full); // follow the link
+        if (!stat.isFile()) { yield { file: full, broken: true }; continue; }
+        yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+      } catch {
+        yield { file: full, broken: true }; // dangling symlink
+      }
+    }
+    // Anything else (a directory named *.json, a FIFO, ...) was never a
+    // scannable transcript in the first place — out of scope, not broken.
+  }
+}
+
+/**
+ * Yield zero or one files() entries for the SQLite database. Identical
+ * shape and reasoning to cursor.js's/warp.js's statIfPresent(): a
+ * constructed, not discovered, path, so lstat is used directly. Missing
+ * entirely (this mode of Kiro CLI never used, or an older/newer version
+ * with a different filename) yields nothing and is NOT broken; a dangling
+ * symlink IS.
+ */
+function* sqliteFileEntry() {
+  let lst;
+  try { lst = fs.lstatSync(SQLITE_DB); }
+  catch { return; }
+
+  if (lst.isSymbolicLink()) {
+    try {
+      const st = fs.statSync(SQLITE_DB);
+      if (!st.isFile()) { yield { file: SQLITE_DB, broken: true }; return; }
+      yield { file: SQLITE_DB, mtimeMs: st.mtimeMs, sizeBytes: st.size, broken: false };
+    } catch {
+      yield { file: SQLITE_DB, broken: true };
+    }
+    return;
+  }
+
+  if (!lst.isFile()) return;
+  yield { file: SQLITE_DB, mtimeMs: lst.mtimeMs, sizeBytes: lst.size, broken: false };
+}
+
+function* files() {
+  yield* jsonlFiles();
+  yield* sqliteFileEntry();
+}
+
+/**
+ * Read one JSONL/JSON transcript file as raw text lines. Identical approach
+ * to claude-code.js's readLines() — see that file's docstring for the full
+ * reasoning; not re-derived here since nothing about it is Kiro-specific.
+ */
+async function readJsonlLines(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();
+  }
+}
+
+// Bounds for the SQLite store's readLines() — same shape as cursor.js's/
+// warp.js's. Not backed by a real large data.sqlite3 this tool was tested
+// against; a generous, honestly-labeled backstop.
+const MAX_DB_BYTES = 512 * 1024 * 1024;
+const READ_TIMEOUT_MS_DB = 60_000;
+const BUSY_TIMEOUT_MS = 5_000;
+const YIELD_EVERY_N_ROWS = 500;
+
+function quoteIdent(name) {
+  return '"' + name.replace(/"/g, '""') + '"';
+}
+
+/**
+ * List every real, user-created table in the database, discovered from
+ * `sqlite_master` rather than hardcoded to `conversations`/`conversations_v2`
+ * — see the module docstring for why (a real community tool already had to
+ * chase this schema through three revisions).
+ */
+function discoverTableNames(db) {
+  try {
+    const rows = db.prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'"
+    ).all();
+    return rows.map((r) => r.name).filter((n) => typeof n === "string" && n.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Turn one row into one scanned text line. Same Uint8Array/BigInt handling
+ * as crush.js's rowToLine() and warp.js's rowToLine() — see either for the
+ * full reasoning; not re-derived here.
+ */
+function rowToLine(row) {
+  const clean = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (v instanceof Uint8Array) clean[k] = Buffer.from(v).toString("utf-8");
+    else if (typeof v === "bigint") clean[k] = v.toString();
+    else clean[k] = v;
+  }
+  return JSON.stringify(clean);
+}
+
+/**
+ * Read the SQLite store as raw text lines — one per row, across every
+ * discovered table. Same status vocabulary and periodic-yield-plus-deadline
+ * approach as cursor.js's/crush.js's/warp.js's readLines(), for the same
+ * reason: node:sqlite is fully synchronous. See cursor.js's own docstring
+ * for the full reasoning.
+ */
+async function readSqliteLines(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 {
+    return { lines: [], status: "failed", bytesRead: 0 };
+  }
+
+  const tables = discoverTableNames(db);
+
+  const lines = [];
+  let bytesRead = 0;
+  const deadline = Date.now() + READ_TIMEOUT_MS_DB;
+  let timedOut = false;
+  let sawError = false;
+
+  for (const table of tables) {
+    let rows;
+    try {
+      rows = db.prepare(`SELECT * FROM ${quoteIdent(table)}`).iterate();
+    } catch {
+      continue;
+    }
+
+    let n = 0;
+    try {
+      for (const row of rows) {
+        const text = rowToLine(row);
+        lines.push(text);
+        bytesRead += Buffer.byteLength(text, "utf-8");
+        n++;
+        if (n % YIELD_EVERY_N_ROWS === 0) {
+          await new Promise((resolve) => setImmediate(resolve));
+          if (Date.now() > deadline) { timedOut = true; break; }
+        }
+      }
+    } catch {
+      sawError = true;
+    }
+    if (timedOut) break;
+  }
+
+  try { db.close(); } catch { /* best-effort close */ }
+
+  if (tables.length === 0) return { lines: [], status: "failed", bytesRead: 0 };
+  if (sawError && lines.length === 0) return { lines: [], status: "failed", bytesRead };
+  if (timedOut || sawError) return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  return { lines, status: "complete", bytesRead };
+}
+
+/**
+ * Dispatch to the JSONL or SQLite reader by matching `file` against the one
+ * known SQLite path — everything else (every entry jsonlFiles() can ever
+ * yield) goes through the plain text reader.
+ */
+async function readLines(file) {
+  if (file === SQLITE_DB) return readSqliteLines(file);
+  return readJsonlLines(file);
+}
+
+module.exports = { id, label, available, unavailableReason, files, readLines };

package/src/sources/kiro-ide.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Kiro IDE (AWS/Kiro's VS Code–based desktop IDE) agent chat history.
+ * Distinct from Kiro CLI (see kiro-cli.js) — same product family, different
+ * application, different storage.
+ *
+ * VERIFICATION STATUS (read this before trusting anything below): the exact
+ * path and directory shape below are corroborated by THREE independent,
+ * real-world sources, none of them official documentation (Kiro's own docs
+ * do not appear to document this path at all — this source found none):
+ *
+ *   1. github.com/kirodotdev/Kiro issue #5469 — a real user's own `du -sh`
+ *      output against their live install: `~/Library/Application
+ *      Support/kiro/User/globalStorage/kiro.kiroagent` (13GB, broken down
+ *      into per-workspace-hash subdirectories like
+ *      `d1c95acd1215dbe372efb48819c04345/`).
+ *   2. github.com/kirodotdev/Kiro issue #4165 — a SECOND, independent real
+ *      user reporting the identical shape from their own install (6,422
+ *      files, ~8.2GB), explicitly describing the content: "Each file
+ *      contains the full context of a spec generation run, including your
+ *      prompts and environment context" — i.e. real prompt/response text,
+ *      exactly the "AI-block" content this source was scoped to find.
+ *   3. github.com/kirodotdev/Kiro PR #5755 (open, unmerged, but written
+ *      against a real install by a third independent contributor) — a
+ *      cache-cleanup script whose actual shell logic this source fetched
+ *      and read directly (`gh pr diff 5755`), which is more precise than
+ *      either issue: it fixes the exact base path (with correct
+ *      capitalization — `Kiro`, not `kiro`, resolving a casing
+ *      inconsistency between the two issues above) and identifies which
+ *      files under it are the real conversation content:
+ *        `~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/`
+ *      containing per-workspace hex-hash directories, each holding:
+ *        - one or more `*.chat` files — "Chat Files (.chat): Conversation
+ *          history with Kiro" (the script's own "WHAT GETS DELETED"
+ *          section) — confirmed as FILES, not directories, by its actual
+ *          deletion command: `find . -name "*.chat" -type f`.
+ *        - other subdirectories holding "File Version Cache: Subdirectories
+ *          containing snapshots of project files used for diff/restore
+ *          operations."
+ *      The companion script in the same PR (`clean-kiro-ide-sessions.sh`)
+ *      further confirms two SIBLING directories exist —
+ *      `~/Library/Application Support/Kiro/Session Storage` (its own
+ *      description: "LevelDB files... window positions, open tabs,
+ *      navigation history") and `.../Kiro/Workspaces` (workspace
+ *      settings/state) — and that neither holds conversation content. This
+ *      mirrors exactly what cursor.js already established for a sibling VS
+ *      Code fork: the generic Electron/VS-Code-shell state (Session
+ *      Storage, Workspaces) is separate from, and uninteresting compared
+ *      to, the extension-specific data under `User/globalStorage/<extension-id>/`
+ *      — here `kiro.kiroagent`, Kiro's own agent extension ID. Deliberately
+ *      OUT OF SCOPE for the same reason gemini-cli.js excludes its
+ *      tool's checkpoints/logs directories: `Session Storage` and
+ *      `Workspaces` are confirmed to hold window/UI state, not agent
+ *      conversation content.
+ *
+ * None of this has been checked against a real Kiro IDE install — it is not
+ * installed on the machine this adapter was built on (checked: no `Kiro.app`
+ * under /Applications, no matching directory under `~/Library/Application
+ * Support`, not findable via `mdfind`). If you have Kiro IDE 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 the path above, then report back either way.
+ *
+ * INTERNAL FORMAT OF `.chat` FILES: not independently confirmed — none of
+ * the three sources above open or describe one's actual bytes, only its
+ * name, size, and general subject ("conversation history", "prompts and
+ * environment context"). This source treats `.chat` files as plain text
+ * (streamed the same way claude-code.js treats `.jsonl`), which is
+ * consistent with every comparable VS-Code-fork/agent-tool store this
+ * project has examined (Cursor's cursorDiskKV values, Warp's blob columns,
+ * Crush's `content` column — all JSON text, none binary) but is, honestly,
+ * an inference from that pattern rather than a confirmed fact about this
+ * specific file format. Per the adapter contract this is safe either way:
+ * a line-by-line text read against a file that happens to be binary just
+ * yields lines that don't pattern-match anything, not a crash — see
+ * claude-code.js's own docstring on this exact point.
+ *
+ * PER-OS PATH: only the macOS path is independently confirmed (all three
+ * sources are macOS reports). Windows and Linux below are filled in by
+ * direct structural analogy to cursor.js's own per-OS `<App>/User/` layout
+ * — the same convention this project already relies on for a sibling VS
+ * Code fork, applied here because Kiro IDE is itself documented as
+ * "VS Code-based" (kirodotdev/Kiro's own repo description). Flagged as
+ * analogy, not independently quoted, same honesty standard as this
+ * project's other per-OS gaps.
+ */
+function kiroUserDir() {
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Kiro", "User");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+    return path.join(appData, "Kiro", "User");
+  }
+  // Linux and other XDG-following unix platforms.
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return path.join(configHome, "Kiro", "User");
+}
+
+const USER_DIR = kiroUserDir();
+const AGENT_STORAGE_DIR = path.join(USER_DIR, "globalStorage", "kiro.kiroagent");
+
+// How many levels deep files() will descend under kiro.kiroagent/ looking
+// for `*.chat` files. The confirmed shape is one workspace-hash level
+// (`<hash>/*.chat`), but the cleanup script's own recursive `find . -name
+// "*.chat"` (no depth limit, run from the kiro.kiroagent root) implies
+// *.chat files are not guaranteed to sit at exactly that one depth — kept
+// bounded rather than hard-coded at exactly 1 for the same reason
+// gemini-cli.js's MAX_CHATS_DEPTH is bounded rather than fixed: a deeper
+// nesting should still get scanned, and a symlink cycle must not turn this
+// into an infinite walk.
+const MAX_WALK_DEPTH = 4;
+
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB — see claude-code.js; not independently
+                                            // measured against a real .chat file here.
+const READ_TIMEOUT_MS = 60_000;
+
+function id() { return "kiro-ide"; }
+function label() { return "Kiro IDE"; }
+
+function available() {
+  try { return fs.statSync(AGENT_STORAGE_DIR).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js and cursor.js
+ * — see claude-code.js's docstring for the full reasoning. Duplicated
+ * rather than imported: each source here is meant to be a small,
+ * self-contained file a reviewer can audit on its own (CONTRIBUTING.md).
+ */
+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());
+
+/**
+ * Walk kiro.kiroagent/ (or one of its subdirectories) for `*.chat` files, up
+ * to MAX_WALK_DEPTH levels deep. The confirmed "file version cache"
+ * subdirectories (diff/restore snapshots, unconfirmed internal format) are
+ * still descended into by this walk — they are not excluded — because a
+ * cache directory could itself, in principle, hold a nested `*.chat` file
+ * under some Kiro version this source has no visibility into; only files
+ * that don't match the `.chat` name pattern are skipped, not whole
+ * directories. See the module docstring for why cache-directory CONTENTS
+ * themselves (i.e. files inside them that aren't named `*.chat`) are out of
+ * scope: their format was never confirmed.
+ */
+function* walkChatFiles(dir, depth) {
+  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)) {
+      if (depth < MAX_WALK_DEPTH) yield* walkChatFiles(full, depth + 1);
+      continue;
+    }
+    if (isFileFollowingSymlink(full, e)) {
+      if (!e.name.endsWith(".chat")) 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;
+    }
+    // Neither resolves as a directory nor a file: a dangling symlink is the
+    // one case worth reporting.
+    if (e.isSymbolicLink()) yield { file: full, broken: true };
+  }
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every `*.chat` file found
+ * under `.../User/globalStorage/kiro.kiroagent/`.
+ */
+function* files() {
+  yield* walkChatFiles(AGENT_STORAGE_DIR, 0);
+}
+
+/**
+ * Read one `.chat` file as an array of raw text lines. Identical approach to
+ * claude-code.js's readLines() — streamed via readline/promises (not
+ * readFileSync+split, for the same V8 string-length-ceiling reason), a
+ * generous size cap, and a hard read timeout since Node's stream/readline
+ * stack has no built-in one. See claude-code.js's own docstring for the
+ * full reasoning; not re-derived here since nothing about it is
+ * Kiro-specific. Whether `.chat` is JSON, JSONL, or something else, lines
+ * don't need to be valid JSON individually per the adapter contract — they
+ * just need pattern-matching against.
+ */
+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 };