@threadcrumbs/threadnauts 0.0.0-stage → 1.0.0

package/server/scan.mjs

@@ -0,0 +1,187 @@
+/**
+ * Harness-agnostic thread scanning.
+ *
+ * This module knows nothing about any particular agent harness: it asks every harness that
+ * is present on this machine for its threads, stamps each one with which harness it came
+ * from, and hands back a single list sorted by recency. Everything harness-specific lives
+ * in `@threadcrumbs/common/harnesses` — see `harnesses/README.md` in the common repo.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { HARNESSES, detectedHarnesses, harnessById } from '@threadcrumbs/common/harnesses'
+
+/** `\\?\C:\…` to `C:\…`. Only where a drive follows: `\\?\UNC\server\share` is a different animal. */
+const dropLongPrefix = (p) => (/^\\\\\?\\[A-Za-z]:[\\/]/.test(p) ? p.slice(4) : p)
+
+/**
+ * A project's ground is keyed on its name, and a name is the last segment of its path — so two
+ * checkouts of the same repo, `~/workspaces/1/foo` and `~/workspaces/2/foo`, are both "foo".
+ * Left alone they share one plot and their threads become indistinguishable, which is wrong for
+ * anyone keeping parallel copies instead of using worktrees.
+ *
+ * Where a name is ambiguous, grow it leftward along the path until it is not: `1/foo` and
+ * `2/foo`. Only names that actually collide are touched, and that restraint is the point — the
+ * name is also the key a saved layout is stored under, so disambiguating unconditionally would
+ * move every plot on everybody's map to fix something most people never hit.
+ */
+export function disambiguateProjects(threads) {
+  // Windows hands the same checkout back as `c:\…` from one transcript and `C:\…` from
+  // another: the CLI's project-directory encoding keeps whatever case the drive letter was
+  // given. Those are one path, not two — and counted as two they make an unambiguous name look
+  // ambiguous, which renames a plot on a machine that has no collision at all.
+  //
+  // Codex hands the same checkout back a third way: with the extended-length prefix, as
+  // `\\?\C:\…`. That does not begin with a drive letter, so the case fold below never reached
+  // it and one folder on disk arrived here as two paths — enough to make `geh` look ambiguous
+  // against itself and rename both plots to their full absolute paths. Drop the prefix first,
+  // but only where a drive follows it: `\\?\UNC\server\share` is a different animal, and
+  // folding its first character would be wrong.
+  const canonical = (p) => {
+    const s = dropLongPrefix(p)
+    return /^[A-Za-z]:[\\/]/.test(s) ? s[0].toLowerCase() + s.slice(1) : s
+  }
+
+  const pathsByName = new Map()
+  for (const t of threads) {
+    if (!t.project) continue
+    if (!pathsByName.has(t.project)) pathsByName.set(t.project, new Set())
+    pathsByName.get(t.project).add(canonical(t.projectPath || ''))
+  }
+
+  const renames = new Map()
+  for (const [name, paths] of pathsByName) {
+    if (paths.size < 2) continue
+    const list = [...paths]
+    // Both separators. A Windows path splits on neither otherwise, leaving a single "segment"
+    // that is the whole absolute path — which then becomes the plot's name on the map.
+    const segments = list.map((p) => p.split(/[\\/]/).filter(Boolean))
+    const deepest = Math.max(...segments.map((s) => s.length))
+
+    // Take one more trailing segment until every path in the group reads differently. Paths
+    // that differ at all must separate by `deepest`, so this always terminates. A thread with
+    // no path at all cannot be told apart by one, so it keeps the bare name and the others
+    // move around it.
+    const labelAt = (segs, depth) => (segs.length ? segs.slice(-depth).join('/') : name)
+    let depth = 1
+    let labels = segments.map((segs) => labelAt(segs, depth))
+    while (new Set(labels).size < list.length && depth < deepest) {
+      depth += 1
+      labels = segments.map((segs) => labelAt(segs, depth))
+    }
+    list.forEach((path, i) => renames.set(`${name}\u0000${path}`, labels[i]))
+  }
+
+  if (!renames.size) return threads
+  return threads.map((t) => {
+    const next = renames.get(`${t.project || ''}\u0000${canonical(t.projectPath || '')}`)
+    return next && next !== t.project ? { ...t, project: next } : t
+  })
+}
+
+/**
+ * A linked git worktree belongs on its repository's plot.
+ *
+ * Claude Code's own `.claude/worktrees/<name>` is recognised by its adapter from the path alone.
+ * A harness that keeps worktrees somewhere of its own is not: Codex puts them under
+ * `~/.codex/worktrees/<id>/<repo>`, which gave the repo a second plot under its own name, and the
+ * disambiguation above then renamed both plots to tell them apart. The checkout itself says where
+ * it belongs — a linked worktree's `.git` is a file reading `gitdir: <repo>/.git/worktrees/<name>`
+ * — so that is read, rather than any harness's folder layout guessed at. A submodule's `.git`
+ * file points into `.git/modules` instead, and is left alone.
+ *
+ * Kept per folder for the life of the process: a checkout does not change which repository it
+ * belongs to, and the scan runs on a short poll.
+ */
+const linkedWorktrees = new Map()
+export async function linkedWorktree(dir) {
+  if (linkedWorktrees.has(dir)) return linkedWorktrees.get(dir)
+  let found = null
+  try {
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(await fsp.readFile(path.join(dir, '.git'), 'utf8'))
+    const gitdir = m ? path.resolve(dir, m[1]) : ''
+    const at = gitdir.search(/[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/)
+    if (at > 0) found = { root: gitdir.slice(0, at), name: path.basename(gitdir) }
+  } catch {
+    /* `.git` is a directory, or there is none: not a linked worktree */
+  }
+  linkedWorktrees.set(dir, found)
+  return found
+}
+
+/**
+ * A worktree that has since been removed has no `.git` left to read. One made by Claude Code still
+ * says where it belonged, because it sits inside the repository at `.claude/worktrees/<name>` —
+ * and other harnesses get run in those too.
+ */
+const NESTED_WORKTREE = /^(.+?)[\\/]\.claude[\\/]worktrees[\\/]([^\\/]+)[\\/]?$/
+
+/** Threads an adapter already placed in a worktree are left as they are. */
+export async function placeWorktrees(threads) {
+  return Promise.all(
+    threads.map(async (t) => {
+      if (t.worktree || !t.projectPath || !path.isAbsolute(t.projectPath)) return t
+      const nested = NESTED_WORKTREE.exec(t.projectPath)
+      const linked = (await linkedWorktree(t.projectPath)) || (nested && { root: nested[1], name: nested[2] })
+      if (!linked) return t
+      return { ...t, project: path.basename(linked.root), projectPath: linked.root, worktree: linked.name }
+    })
+  )
+}
+
+/**
+ * Every thread from every detected harness.
+ *
+ * A harness that throws is skipped rather than allowed to take the scan down with it: one
+ * broken adapter should cost you that harness's threads, not the whole colony.
+ */
+export async function scanThreads() {
+  const harnesses = await detectedHarnesses()
+  const lists = await Promise.all(
+    harnesses.map(async (h) => {
+      try {
+        const threads = await h.scanThreads()
+        return threads.map((t) => ({ ...t, harness: h.id, harnessName: h.name }))
+      } catch (err) {
+        console.warn(`scan: harness "${h.id}" failed to scan —`, err?.message || err)
+        return []
+      }
+    })
+  )
+  // The prefix goes before anything reads the path, so a plot's folder is one a person would type.
+  const flat = lists.flat().map((t) => (t.projectPath ? { ...t, projectPath: dropLongPrefix(t.projectPath) } : t))
+  const threads = disambiguateProjects(await placeWorktrees(flat))
+  threads.sort((a, b) => b.lastActivityAt - a.lastActivityAt)
+  return threads
+}
+
+/** What the HUD shows in the harness list: who is installed, and what they can do. */
+export async function harnessStatus() {
+  const detected = new Set((await detectedHarnesses()).map((h) => h.id))
+  return Promise.all(
+    HARNESSES.map(async (h) => ({
+      id: h.id,
+      name: h.name,
+      detected: detected.has(h.id),
+      // Optional. An adapter that can see its harness but cannot read it — wrong Node, a store
+      // it does not understand — says why here instead of failing silently on every poll.
+      error: h.diagnostic ? await h.diagnostic().catch(() => '') : '',
+    }))
+  )
+}
+
+/** The harness to use when a caller has not said — the first one present on this machine. */
+export async function defaultHarness() {
+  const [first] = await detectedHarnesses()
+  return first?.id || ''
+}
+
+const dispatch = (harnessId) => {
+  const h = harnessById(harnessId)
+  if (!h) throw new Error(`Unknown harness "${harnessId}"`)
+  return h
+}
+
+/** Both may be async: an adapter that has to look for a CLI on disk cannot answer synchronously. */
+export const openThread = async (harnessId, ref) => dispatch(harnessId).openThread(ref)
+
+export const newSession = async (harnessId, dir) => dispatch(harnessId).newSession(dir)

package/server/serve.mjs

@@ -0,0 +1,7 @@
+import { startServer } from './http-server.mjs'
+
+const PORT = Number(process.env.PORT) || 5274
+const HOST = process.env.THREADNAUTS_HOST || '127.0.0.1'
+
+await startServer({ port: PORT, host: HOST })
+console.log(`Threadnauts → http://${HOST}:${PORT}`)

package/server/threadgauge.mjs

@@ -0,0 +1,42 @@
+const FIRST_PORT = 5274
+const PORTS_TO_TRY = 20
+const LOOPBACKS = ['127.0.0.1', '::1']
+const PROBE_TIMEOUT_MS = 500
+const CONTEXT_TIMEOUT_MS = 2000
+const REUSE_FOUND_MS = 15000
+
+const originOf = (host, port) => `http://${host.includes(':') ? `[${host}]` : host}:${port}`
+
+async function answersAsThreadgauge(origin, fetch) {
+  try {
+    const response = await fetch(`${origin}/api/about`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+    return (await response.json())?.app === 'threadgauge'
+  } catch {
+    return false
+  }
+}
+
+export async function findThreadgauge({ fetch = globalThis.fetch, first = FIRST_PORT, tries = PORTS_TO_TRY, hosts = LOOPBACKS } = {}) {
+  const probes = []
+  for (let port = first; port < first + tries; port++) for (const host of hosts) probes.push({ port, origin: originOf(host, port) })
+  const found = await Promise.all(probes.map(({ origin }) => answersAsThreadgauge(origin, fetch)))
+  const index = found.indexOf(true)
+  return index === -1 ? null : `http://localhost:${probes[index].port}/`
+}
+
+export function threadgaugeContexts({ fetch = globalThis.fetch, find = () => findThreadgauge({ fetch }), now = Date.now } = {}) {
+  let found = { url: null, at: -Infinity }
+  return async function contexts() {
+    if (now() - found.at > REUSE_FOUND_MS) found = { url: await find(), at: now() }
+    if (!found.url) return { url: null, contexts: {} }
+    try {
+      const response = await fetch(`${found.url}api/sessions`, { signal: AbortSignal.timeout(CONTEXT_TIMEOUT_MS) })
+      const { sessions = [] } = response.ok ? await response.json() : {}
+      const known = sessions.filter((s) => s.id && s.context).map((s) => [s.id, { used: s.context.used, limit: s.context.limit }])
+      return { url: found.url, contexts: Object.fromEntries(known) }
+    } catch {
+      found = { url: null, at: -Infinity }
+      return { url: null, contexts: {} }
+    }
+  }
+}