@threadcrumbs/common 0.0.0-stage → 0.1.1

package/lib/cursor-folder.mjs

@@ -0,0 +1,107 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+const isDir = async (p) => {
+  try {
+    return (await fsp.stat(p)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Turn `Users-me-Documents-GitHub-my-web-app` back into a path.
+ *
+ * Every separator became a dash and so did every dash already in a folder name, which makes the
+ * encoding lossy and the obvious reverse — replace each dash with a slash — wrong for most real
+ * repositories. That reverse is wrong for any project with a dash in its name:
+ * `my-web-app` comes back as `my/web/app`, `personal-site-2025` as
+ * `personal/site/2025`. Since `project` is what claims a hex zone, that is not cosmetic.
+ *
+ * It is lossier than dashes alone. Any run of characters that is not a letter or a digit became
+ * one dash — `C:\` is `c-`, `data_pipeline_v2` is `data-pipeline-v2` — so a folder cannot
+ * be found by turning tokens back into a name and asking whether it exists. Instead each folder
+ * on disk is encoded the same way and compared with what is left of the name, longest first,
+ * backtracking when a greedy match leads nowhere. On Windows the walk starts from the drive the
+ * leading letter names; the drive letter's case is whatever the path was opened with, so it and
+ * every other comparison there ignores case, as the filesystem does.
+ *
+ * A repository that has since been deleted cannot be resolved by anyone, and falls back to
+ * attaching the rest as a single dashed name — the likelier reading, since a folder name with
+ * dashes in it is far more common than four nested single-word folders.
+ */
+export const encodeFolderName = (name) => name.replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '')
+
+/** The folders under `dir` as `[encoded, name]`, longest encoding first, read once per decode. */
+async function encodedChildren(dir, seen) {
+  if (seen.has(dir)) return seen.get(dir)
+  let out = []
+  try {
+    out = (await fsp.readdir(dir, { withFileTypes: true }))
+      .filter((e) => e.isDirectory() || e.isSymbolicLink())
+      .map((e) => [encodeFolderName(e.name), e.name])
+      .filter(([encoded]) => encoded)
+      .sort((a, b) => b[0].length - a[0].length)
+  } catch {
+    /* unreadable or gone */
+  }
+  seen.set(dir, out)
+  return out
+}
+
+async function resolveEncoded(rest, from, fold, seen) {
+  if (!rest) return from
+  const key = fold ? rest.toLowerCase() : rest
+  for (const [encoded, name] of await encodedChildren(from, seen)) {
+    const e = fold ? encoded.toLowerCase() : encoded
+    if (key !== e && !key.startsWith(`${e}-`)) continue
+    const candidate = path.join(from, name)
+    if (!(await isDir(candidate))) continue
+    const found = await resolveEncoded(rest.slice(e.length + 1), candidate, fold, seen)
+    if (found) return found
+  }
+  return ''
+}
+
+/**
+ * The folder an encoded name stands for. `root` and `windows` exist for the tests; the scan takes
+ * the machine's own.
+ */
+export async function decodeFolder(name, { windows = process.platform === 'win32', root } = {}) {
+  const drive = windows ? /^([A-Za-z])(?:-(.*))?$/.exec(name) : null
+  const start = root || (drive ? `${drive[1].toUpperCase()}:${path.win32.sep}` : path.parse(process.cwd()).root)
+  const rest = drive ? drive[2] || '' : name.replace(/^-+/, '')
+  const seen = new Map()
+  const resolved = await resolveEncoded(rest, start, windows, seen)
+  if (resolved) return resolved
+
+  // Nothing on disk answers to it any more: keep the deepest ancestor that does and let the
+  // remainder stand as one name.
+  let dir = start
+  let left = rest
+  for (;;) {
+    const key = windows ? left.toLowerCase() : left
+    const next = (await encodedChildren(dir, seen)).find(([encoded]) => {
+      const e = windows ? encoded.toLowerCase() : encoded
+      return key.startsWith(`${e}-`)
+    })
+    if (!next) break
+    dir = path.join(dir, next[1])
+    left = left.slice(next[0].length + 1)
+  }
+  return left ? path.join(dir, left) : dir
+}
+
+/**
+ * Cursor files a window with no folder open under `empty-window`. That is not a project, and
+ * decoded it became a zone called "empty-window" at the root of the disk.
+ */
+const NO_FOLDER = new Set(['empty-window'])
+
+const decodeCache = new Map()
+export async function decodeProjectDir(name) {
+  if (decodeCache.has(name)) return decodeCache.get(name)
+  const out = NO_FOLDER.has(name) ? '' : await decodeFolder(name)
+  decodeCache.set(name, out)
+  return out
+}

package/lib/fsutil.mjs

@@ -0,0 +1,191 @@
+/**
+ * Filesystem helpers shared by every harness adapter.
+ *
+ * Nothing in here knows about a particular harness — an adapter is free to ignore the lot
+ * and read its data however it likes. See `harnesses/README.md` for the contract.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+/** Read the first chunk of a file without pulling a 12MB transcript into memory. */
+export async function readHead(file, bytes) {
+  const fh = await fsp.open(file, 'r')
+  try {
+    const buf = Buffer.allocUnsafe(bytes)
+    const { bytesRead } = await fh.read(buf, 0, bytes, 0)
+    const text = buf.subarray(0, bytesRead).toString('utf8')
+    // Drop a trailing partial line so JSON.parse never sees half a record.
+    return bytesRead === bytes ? text.slice(0, text.lastIndexOf('\n') + 1) : text
+  } finally {
+    await fh.close()
+  }
+}
+
+/**
+ * The last `bytes` of a file, with a leading partial line dropped. The mirror of `readHead`,
+ * for the questions only the end of a transcript answers — whose turn it is right now.
+ */
+export async function readTail(file, bytes) {
+  const fh = await fsp.open(file, 'r')
+  try {
+    const { size } = await fh.stat()
+    const want = Math.min(bytes, size)
+    const buf = Buffer.allocUnsafe(want)
+    const { bytesRead } = await fh.read(buf, 0, want, size - want)
+    const text = buf.subarray(0, bytesRead).toString('utf8')
+    return want === size ? text : text.slice(text.indexOf('\n') + 1)
+  } finally {
+    await fh.close()
+  }
+}
+
+/** Parse a JSONL blob, skipping the partial or malformed lines a live file always has. */
+export function jsonLines(text) {
+  const out = []
+  for (const line of text.split('\n')) {
+    const t = line.trim()
+    if (!t.startsWith('{')) continue
+    try {
+      out.push(JSON.parse(t))
+    } catch {
+      /* partial or malformed line — skip */
+    }
+  }
+  return out
+}
+
+export async function listFiles(dir, filter) {
+  let entries
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  return entries.filter((e) => e.isFile() && filter(e.name)).map((e) => path.join(dir, e.name))
+}
+
+export async function listDirs(dir) {
+  try {
+    const entries = await fsp.readdir(dir, { withFileTypes: true })
+    return entries.filter((e) => e.isDirectory()).map((e) => path.join(dir, e.name))
+  } catch {
+    return []
+  }
+}
+
+/** Does this path exist at all? Adapters use it to answer `detect()`. */
+export async function exists(p) {
+  try {
+    await fsp.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Where an executable is, as an absolute path, or null. PATH first, then `extraDirs` — the
+ * places an installer puts a binary that a server started with a thin PATH (an IDE launcher, a
+ * service unit) would not see. Candidates are resolved rather than joined: the caller may spawn
+ * from a different working directory than this check ran in, and a relative PATH entry would
+ * then name two different files. X_OK alone passes for a directory, hence the stat.
+ *
+ * It never looks inside an application bundle, and no caller should hand it a path that does.
+ * Running a binary out of somebody else's `.app` is how you get the OS blaming us for it.
+ *
+ * On Windows a bare name is never the file. `claude` is `claude.exe` from the native installer or
+ * `claude.cmd` from npm — and npm leaves an extensionless `claude` beside the `.cmd` as well, a
+ * shell script for Git Bash that Windows cannot run. Matching that one handed a terminal a file it
+ * could only fail on. So a name with no extension is tried with the extensions Windows can launch,
+ * and never on its own.
+ *
+ * `THREADCRUMBS_CLI_DIRS`, when set, stands in for every caller's `extraDirs`, and empty means
+ * PATH alone. It is the same kind of override as `CLAUDE_CONFIG_DIR`: the suite uses it to test
+ * "no CLI installed" on a machine that has one in `/opt/homebrew/bin`, which an emptied PATH
+ * alone would still find. Kept here rather than per adapter, so one switch covers them all.
+ */
+export async function findExecutable(name, extraDirs = []) {
+  if (typeof name !== 'string' || !name) return null
+  const explicit = name.includes('/') || name.includes(path.sep)
+  const onPath = (process.env.PATH || '').split(path.delimiter).filter(Boolean)
+  const override = process.env.THREADCRUMBS_CLI_DIRS
+  const installDirs = override === undefined ? extraDirs : override.split(path.delimiter).filter(Boolean)
+  const launchable = WINDOWS_EXTS.includes(path.extname(name).toLowerCase())
+  const names = process.platform === 'win32' && !launchable ? WINDOWS_EXTS.map((ext) => name + ext) : [name]
+
+  for (const dir of explicit ? ['.'] : [...onPath, ...installDirs]) {
+    for (const file of names) {
+      const candidate = path.resolve(dir, file)
+      if (await isExecutableFile(candidate)) return candidate
+    }
+  }
+  return null
+}
+
+/** What CreateProcess will start, best first. PATHEXT also lists script hosts, which it will not. */
+const WINDOWS_EXTS = ['.exe', '.cmd', '.bat', '.com']
+
+async function isExecutableFile(candidate) {
+  try {
+    await fsp.access(candidate, fsp.constants.X_OK)
+  } catch {
+    return false
+  }
+  try {
+    return (await fsp.stat(candidate)).isFile()
+  } catch {
+    // An app execution alias — `wt.exe`, and anything else the Store installs into
+    // `%LOCALAPPDATA%\Microsoft\WindowsApps` — is a reparse point only CreateProcess follows:
+    // `stat` fails on it with EACCES while the alias itself is there and starts fine. Without
+    // this, Windows Terminal was never found and every terminal opened in plain `cmd.exe`.
+    if (process.platform !== 'win32') return false
+    const link = await fsp.lstat(candidate).catch(() => null)
+    return Boolean(link && !link.isDirectory())
+  }
+}
+
+export const num = (v) => {
+  const n = Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+export function parseJsonLine(line) {
+  if (!line || line[0] !== '{') return null
+  try {
+    return JSON.parse(line)
+  } catch {
+    return null
+  }
+}
+
+const CHUNK_BYTES = 4 * 1024 * 1024
+const NEWLINE = 0x0a
+
+export async function readNewLines(file, from, to, carry = Buffer.alloc(0)) {
+  const lines = []
+  let pending = carry
+  const handle = await fsp.open(file, 'r')
+  try {
+    for (let position = from; position < to; ) {
+      const length = Math.min(CHUNK_BYTES, to - position)
+      const chunk = Buffer.alloc(length)
+      const { bytesRead } = await handle.read(chunk, 0, length, position)
+      if (!bytesRead) break
+      position += bytesRead
+      const joined = pending.length ? Buffer.concat([pending, chunk.subarray(0, bytesRead)]) : chunk.subarray(0, bytesRead)
+      const end = joined.lastIndexOf(NEWLINE)
+      if (end < 0) {
+        pending = joined
+        continue
+      }
+      for (const line of joined.subarray(0, end).toString('utf8').split('\n')) {
+        const trimmed = line.trim()
+        if (trimmed) lines.push(trimmed)
+      }
+      pending = Buffer.from(joined.subarray(end + 1))
+    }
+  } finally {
+    await handle.close()
+  }
+  return { lines, carry: pending }
+}

package/lib/hermes-home.mjs

@@ -0,0 +1,30 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * Where Hermes keeps its session store. HERMES_HOME wins everywhere; otherwise
+ * a platform default — `~/.hermes` on POSIX (macOS matches Linux, no Darwin
+ * special-case upstream) vs `%LOCALAPPDATA%\hermes` on native Windows. On
+ * Windows an older `%USERPROFILE%\.hermes` layout still counts when it holds
+ * the store; WSL2 follows the Linux layout. `HERMES_DATA_DIR_SUFFIX` is appended
+ * to the default folder's name, as Hermes itself does.
+ *
+ * Pure and injectable so the matrix can be unit-tested without a Mac or
+ * Windows box: platform/env/home/exists default to the live process values,
+ * so the no-arg call IS the production probe.
+ */
+export function resolveHermesHome({ platform = process.platform, env = process.env, home = os.homedir(), exists = fs.existsSync } = {}) {
+  if (env.HERMES_HOME) return env.HERMES_HOME
+  const suffix = env.HERMES_DATA_DIR_SUFFIX || ''
+  if (platform !== 'win32') return path.join(home, `.hermes${suffix}`)
+  const modern = path.join(
+    env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'),
+    `hermes${suffix}`
+  )
+  const legacy = path.join(home, `.hermes${suffix}`)
+  if (!exists(path.join(modern, 'state.db')) && exists(path.join(legacy, 'state.db'))) {
+    return legacy
+  }
+  return modern
+}

package/lib/jsonl-follower.mjs

@@ -0,0 +1,45 @@
+import { parseJsonLine, readNewLines } from './fsutil.mjs'
+
+export function jsonlFollower({ empty, apply }) {
+  const files = new Map()
+
+  async function advance(entry, file, size) {
+    if (!entry.state || size < entry.state.offset) entry.state = { ...empty(), offset: 0, carry: Buffer.alloc(0) }
+    const state = entry.state
+    if (size === state.offset) return state
+    try {
+      const { lines, carry } = await readNewLines(file, state.offset, size, state.carry)
+      state.offset = size
+      state.carry = carry
+      for (const line of lines) {
+        const record = parseJsonLine(line)
+        if (record) apply(state, record)
+      }
+    } catch (err) {
+      entry.state = null
+      throw err
+    }
+    return state
+  }
+
+  function read(file, stat) {
+    let entry = files.get(file)
+    if (!entry) {
+      entry = { state: null, queue: Promise.resolve(), seen: true }
+      files.set(file, entry)
+    }
+    entry.seen = true
+    const next = entry.queue.then(() => advance(entry, file, stat.size))
+    entry.queue = next.catch(() => {})
+    return next
+  }
+
+  function sweep() {
+    for (const [file, entry] of files) {
+      if (entry.seen) entry.seen = false
+      else files.delete(file)
+    }
+  }
+
+  return { read, sweep }
+}