@erclx/canon 4.0.0

package/src/serve/static.ts

@@ -0,0 +1,322 @@
+import { existsSync, realpathSync, statSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+/**
+ * The loopback interface, never a wildcard bind. A preview serves whatever
+ * directory it is pointed at, and the folders this exists for are the
+ * gitignored record trees, so reaching the network is the one thing it must
+ * not do.
+ */
+export const SERVE_HOST = '127.0.0.1'
+
+/** Tried first, then the next ports in order, so a second preview still opens. */
+export const DEFAULT_PORT = 8787
+
+/** How far past the requested port to look before refusing. */
+const PORT_ATTEMPTS = 20
+
+const DEFAULT_ENTRY = 'index.html'
+
+/**
+ * Extensions a browser has to be told about. Anything absent is served as an
+ * octet stream, which downloads rather than renders, and that is the safe
+ * direction for a type this map does not claim to know.
+ */
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  css: 'text/css; charset=utf-8',
+  gif: 'image/gif',
+  htm: 'text/html; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  js: 'text/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  /**
+   * Plain text rather than `text/markdown`, which a browser offers to save
+   * instead of showing. A reader following a link to a source page wants to
+   * read it, and the rendered sibling is a separate file.
+   */
+  md: 'text/plain; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  txt: 'text/plain; charset=utf-8',
+  webp: 'image/webp',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+}
+
+export type ServeRefusal =
+  | 'no-root'
+  | 'not-a-directory'
+  | 'no-port'
+  | 'no-entry'
+  | 'bind-failed'
+
+export interface ServeRefused {
+  readonly ok: false
+  readonly reason: ServeRefusal
+  readonly detail: string
+}
+
+export interface ServeStarted {
+  readonly ok: true
+  /** Absolute, so a report names the directory rather than the caller's cwd. */
+  readonly root: string
+  readonly host: string
+  readonly port: number
+  /** The entry page relative to the root, as the URL spells it. */
+  readonly entry: string
+  /** What a reader clicks. Complete, including the entry page. */
+  readonly url: string
+  /** Whether the entry page exists. A missing one is reported, never fatal. */
+  readonly entryExists: boolean
+  readonly stop: () => Promise<void>
+}
+
+export type ServeOutcome = ServeStarted | ServeRefused
+
+export interface ServeOptions {
+  readonly port?: number
+  readonly entry?: string
+}
+
+function refuse(reason: ServeRefusal, detail: string): ServeRefused {
+  return { ok: false, reason, detail }
+}
+
+function contentType(path: string): string {
+  const dot = path.lastIndexOf('.')
+  if (dot === -1) return 'application/octet-stream'
+  const ext = path.slice(dot + 1).toLowerCase()
+  return CONTENT_TYPES[ext] ?? 'application/octet-stream'
+}
+
+/**
+ * Resolves a request path inside the root, or returns undefined when it escapes.
+ * The containment test compares resolved absolute paths rather than inspecting
+ * the request for `..`, because an encoded traversal survives a textual scan and
+ * does not survive resolution.
+ */
+export function resolveWithin(
+  root: string,
+  requestPath: string,
+): string | undefined {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(requestPath)
+  } catch {
+    return undefined
+  }
+  /**
+   * A NUL truncates the path at the filesystem layer, so a request carrying one
+   * asks for a different file than the one the containment test read.
+   */
+  if (decoded.includes('\0')) return undefined
+
+  const relativePath = decoded.replace(/^\/+/, '')
+  const target = resolve(root, relativePath)
+  if (target !== root && !target.startsWith(root + sep)) return undefined
+  return target
+}
+
+/**
+ * Re-tests containment after following symlinks. `resolveWithin` is lexical
+ * and `resolve` does not follow a link, so a link inside the root clears that
+ * test while the file it points at sits outside. This repository is a live
+ * instance, since `claude/standards` and `claude/snippets` are links out of
+ * `claude/`.
+ *
+ * Only a path that exists is checked, because a link can be followed only once
+ * there is something on the other end, and a path that resolves to nothing is
+ * a 404 rather than an escape.
+ */
+function escapesThroughLink(root: string, target: string): boolean {
+  if (!existsSync(target)) return false
+  try {
+    const realRoot = realpathSync(root)
+    const realTarget = realpathSync(target)
+    return realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)
+  } catch {
+    /* Unreadable resolves to no answer, and no answer is refused. */
+    return true
+  }
+}
+
+/**
+ * Whether a bind failure is contention worth trying the next port for.
+ *
+ * Lifted out of the loop so the decision is testable. Manufacturing a real
+ * non-contention bind failure needs a privileged port or an unavailable
+ * interface and neither travels between machines, where an error value does,
+ * so this is unit-tested and the bind itself is not.
+ */
+export function shouldWalkPast(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'EADDRINUSE'
+}
+
+/**
+ * Picks a listening port, starting at the requested one and walking forward.
+ * A busy port is the ordinary case rather than a failure, since a preview of
+ * one workspace is routinely open while another is started.
+ */
+function listen(
+  root: string,
+  first: number,
+): { server: ReturnType<typeof Bun.serve>; port: number } | undefined {
+  for (let port = first; port < first + PORT_ATTEMPTS; port++) {
+    try {
+      const server = Bun.serve({
+        hostname: SERVE_HOST,
+        port,
+        fetch: (request) => respond(root, request),
+      })
+      /**
+       * The bound port rather than the requested one. Port 0 asks the OS to
+       * choose, so reporting the request builds a URL pointing at nothing.
+       * The type admits undefined for a unix socket, which a bind carrying a
+       * hostname and a port never is, and the request is the honest fallback.
+       */
+      return { server, port: server.port ?? port }
+    } catch (error) {
+      /**
+       * Contention is the one cause worth walking past. A permission failure
+       * or an unavailable interface swallowed here would be retried twenty
+       * times and then reported as a port range being full, which names a
+       * cause nothing checked. `startServer` turns the rethrow into a refusal.
+       */
+      if (!shouldWalkPast(error)) throw error
+    }
+  }
+  return undefined
+}
+
+export async function respond(
+  root: string,
+  request: Request,
+): Promise<Response> {
+  const { pathname, search } = new URL(request.url)
+  const forbidden = () =>
+    new Response('Forbidden\n', {
+      status: 403,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+
+  const target = resolveWithin(root, pathname)
+  if (!target) return forbidden()
+
+  /**
+   * Tested here as well as before the read, because the redirect below answers
+   * ahead of that one. A redirect firing on an out-of-root directory reports
+   * that it exists, where one that does not answers 404, and the pair is a
+   * fact about the filesystem outside the root.
+   */
+  if (escapesThroughLink(root, target)) return forbidden()
+
+  let path = target
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    /**
+     * A browser resolves a relative asset against the last slash of the URL it
+     * is on, so answering a directory in place leaves `/lesson` asking for
+     * `/course.css` rather than `/lesson/course.css` and the page renders
+     * unstyled. The redirect moves the base before the index is served.
+     */
+    if (!pathname.endsWith('/')) {
+      return new Response(null, {
+        status: 301,
+        headers: { location: `${pathname}/${search}` },
+      })
+    }
+    path = join(path, DEFAULT_ENTRY)
+  }
+
+  /**
+   * Sits immediately before the read rather than beside the path that produced
+   * it, so every path reaching `Bun.file` has been tested whatever produced
+   * it. Checking the request path alone left the appended index untested, and
+   * a real directory holding a linked index was served.
+   */
+  if (escapesThroughLink(root, path)) return forbidden()
+
+  const file = Bun.file(path)
+  if (!(await file.exists())) {
+    return new Response(`Not found: ${pathname}\n`, {
+      status: 404,
+      headers: { 'content-type': 'text/plain; charset=utf-8' },
+    })
+  }
+
+  return new Response(file, {
+    headers: {
+      'content-type': contentType(path),
+      /**
+       * A preview is edited and reloaded continuously, and a cached stylesheet
+       * reads as a fix that did not work. Revalidation is the whole point of
+       * the surface, so it is not negotiable per response.
+       */
+      'cache-control': 'no-store',
+    },
+  })
+}
+
+export function startServer(
+  dir: string,
+  options: ServeOptions = {},
+): ServeOutcome {
+  const root = resolve(process.cwd(), dir)
+  if (!existsSync(root)) return refuse('no-root', `${dir} does not exist`)
+  if (!statSync(root).isDirectory())
+    return refuse('not-a-directory', `${dir} is not a directory`)
+
+  const entry = (options.entry ?? DEFAULT_ENTRY).replace(/^\/+/, '')
+
+  /**
+   * Checked before a port is taken, since `url` is the field a caller is told
+   * to read and hand to a reader. An entry the containment test rejects would
+   * otherwise be reported as a link the server then refuses. An entry that is
+   * merely absent is not this case and does not refuse, which `entryExists`
+   * reports instead.
+   */
+  const entryPath = resolveWithin(root, entry)
+  if (!entryPath) return refuse('no-entry', `${entry} escapes ${dir}`)
+
+  const first = options.port ?? DEFAULT_PORT
+
+  /**
+   * A bind failure that is not contention reaches here as a throw, and the
+   * command's own help promises a reason on stderr or in the record. A stack
+   * trace is neither, so it is caught and named.
+   */
+  let bound: ReturnType<typeof listen>
+  try {
+    bound = listen(root, first)
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
+    return refuse(
+      'bind-failed',
+      `could not bind ${SERVE_HOST}:${first} (${code})`,
+    )
+  }
+
+  if (!bound) {
+    return refuse(
+      'no-port',
+      `no free port between ${first} and ${first + PORT_ATTEMPTS - 1}`,
+    )
+  }
+
+  return {
+    ok: true,
+    root,
+    host: SERVE_HOST,
+    port: bound.port,
+    entry,
+    url: `http://${SERVE_HOST}:${bound.port}/${entry}`,
+    entryExists: existsSync(entryPath),
+    stop: async () => {
+      await bound.server.stop(true)
+    },
+  }
+}

package/src/sessions/claim.ts

@@ -0,0 +1,85 @@
+import {
+  repositoryOf,
+  resolveSessions,
+  type ResolvedSession,
+  type SessionReport,
+} from '@/sessions/resolve'
+import {
+  branchRefs,
+  listWorktrees,
+  type RefReport,
+  type WorktreeEntry,
+} from '@/worktree'
+
+export interface ClaimReport {
+  readonly claimed: boolean
+  readonly worktree: string | null
+  readonly sessions: readonly ResolvedSession[]
+  /** The refs already naming the branch, local head and `origin` remote-tracking alike. */
+  readonly refs: readonly string[]
+  /** False when the session roster could not be read, so `claimed` covers the readings around it alone and cannot be trusted as a clean "unclaimed". */
+  readonly sessionsReadable: boolean
+  /** False when the ref read failed, which is the same false clean under a different reading. */
+  readonly refsReadable: boolean
+}
+
+export interface ClaimOptions {
+  /**
+   * The repository the claim is answered about, not merely where the caller
+   * stands. Every reading below is taken against it, so handing another
+   * project's path asks about that project, which is what lets a dispatcher in
+   * one repository see a branch held in another. Defaults to the caller's own
+   * directory, so a call omitting it answers exactly as it always has.
+   */
+  readonly cwd?: string
+  readonly resolve?: () => Promise<SessionReport>
+  readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>
+  readonly branchRefs?: (branch: string, cwd: string) => Promise<RefReport>
+}
+
+/**
+ * Answers whether a branch is already claimed, composing the three readings no
+ * one surface can answer alone: a worktree can outlive the session that made
+ * it, a session can hold a branch before a worktree exists for it, and a branch
+ * behind a merged pull request has neither while still being taken.
+ *
+ * The two readable flags stay separate because a caller told the roster failed
+ * looks at the roster. Folding either into `claimed` would report the failure
+ * as a clean "unclaimed", which is the answer this exists to stop giving.
+ */
+export async function checkClaim(
+  branch: string,
+  opts: ClaimOptions = {},
+): Promise<ClaimReport> {
+  const cwd = opts.cwd ?? process.cwd()
+  const resolve = opts.resolve ?? resolveSessions
+  const listAll = opts.listWorktrees ?? listWorktrees
+  const readRefs = opts.branchRefs ?? branchRefs
+
+  const [repository, worktrees, report, refs] = await Promise.all([
+    repositoryOf(cwd),
+    listAll(cwd),
+    resolve(),
+    readRefs(branch, cwd),
+  ])
+
+  const worktree =
+    worktrees.find((entry) => entry.branch === branch)?.path ?? null
+
+  const sessions =
+    report.kind === 'resolved'
+      ? report.sessions.filter(
+          (session) =>
+            session.branch === branch && session.repository === repository,
+        )
+      : []
+
+  return {
+    claimed: worktree !== null || sessions.length > 0 || refs.refs.length > 0,
+    worktree,
+    sessions,
+    refs: refs.refs,
+    sessionsReadable: report.kind === 'resolved',
+    refsReadable: refs.readable,
+  }
+}

package/src/sessions/live.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs'
+import type { SessionRecord } from '@/sessions/registry'
+
+/**
+ * How far the liveness answer can be trusted.
+ *
+ * `confirmed` means the running process was matched against the start time the
+ * record stamped, so the pid belongs to the session that wrote the file.
+ * `unverified` means the pid answers a signal probe and nothing more, which
+ * cannot separate the original session from whatever inherited its pid.
+ */
+export type Confidence = 'confirmed' | 'unverified'
+
+export interface Liveness {
+  readonly alive: boolean
+  readonly confidence: Confidence
+}
+
+export interface LivenessProbes {
+  /** The start time of a running process, or null where it cannot be read. */
+  readonly procStartOf: (pid: number) => string | null
+  /** Whether the pid answers at all, ignoring which process holds it. */
+  readonly responds: (pid: number) => boolean
+}
+
+/**
+ * Reads a running process's start time from the process filesystem.
+ *
+ * The comm field is parenthesised and may itself contain spaces, so the split
+ * runs from the last `)` rather than over the whole line. Fields resume at the
+ * third, which puts the twenty-second at offset nineteen.
+ */
+function procStartOf(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const tail = stat.slice(stat.lastIndexOf(')') + 1).trim()
+    return tail.split(/\s+/)[19] ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Signal zero performs the permission and existence checks and delivers nothing. */
+function responds(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // A live process owned by another user answers EPERM, which is an answer.
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
+
+/**
+ * Decides whether a record describes a session that is still running.
+ *
+ * The two paths are not interchangeable and the caller is told which one ran.
+ * Where the process filesystem answers, a start-time mismatch is a dead session
+ * whose pid was reused and the record is discarded. Where it does not, the
+ * probe alone stands, and every surviving row is marked so a caller never reads
+ * a recycled pid as a confirmed identity.
+ */
+export function liveness(
+  record: SessionRecord,
+  probes: LivenessProbes = SYSTEM_PROBES,
+): Liveness {
+  const started = record.procStart
+
+  if (started !== undefined && started.length > 0) {
+    const running = probes.procStartOf(record.pid)
+    if (running !== null) {
+      return { alive: running === started, confidence: 'confirmed' }
+    }
+  }
+
+  return { alive: probes.responds(record.pid), confidence: 'unverified' }
+}

package/src/sessions/registry.ts

@@ -0,0 +1,137 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * One session's own record of itself, as the client writes it.
+ *
+ * Only the fields this domain reads are declared. The client writes several
+ * more, and naming them here would put a second copy of its schema in a
+ * repository that does not own it.
+ */
+export interface SessionRecord {
+  readonly pid: number
+  readonly cwd: string
+  readonly name: string
+  /**
+   * Optional because the guard admitting a record checks the three fields above
+   * and no more. A client predating any of these writes a record the roster
+   * still wants, so the type says what the guard actually proved.
+   */
+  readonly sessionId: string | undefined
+  readonly kind: string | undefined
+  readonly status: string | undefined
+  /**
+   * The epoch millisecond the client last changed `status`. Measured against
+   * the live registry, 23 of 341 usable records carry it, and the one record
+   * that has ever carried `status: "waiting"` is not among them, so its
+   * absence tracks a client version rather than a record's age alone.
+   * Declared here rather than read opportunistically off the parsed object,
+   * since this file is what states what the domain reads and an undeclared
+   * field read anyway is the drift this domain exists downstream of.
+   */
+  readonly statusUpdatedAt: number | undefined
+  /**
+   * The epoch millisecond the client last wrote the record at all, a coarser
+   * stamp than `statusUpdatedAt` that a client writes whether or not it also
+   * stamps the status change itself. Declared as the fallback dwell source
+   * for a record predating the narrower field, per the same reasoning above.
+   */
+  readonly updatedAt: number | undefined
+  readonly startedAt: number | undefined
+  /**
+   * The process start time the client stamped at launch, compared against the
+   * running process to separate a live session from a record whose pid has
+   * been handed to something else.
+   */
+  readonly procStart: string | undefined
+}
+
+/**
+ * Resolves the folder holding one file per session.
+ *
+ * `CLAUDE_CONFIG_DIR` comes first because a client honouring it writes its
+ * records nowhere near the home directory, and a read that ignored it would
+ * report an empty roster on a machine running sessions.
+ */
+export function registryDir(): string {
+  const configured = process.env.CLAUDE_CONFIG_DIR
+  const base =
+    configured && configured.length > 0
+      ? configured
+      : join(homedir(), '.claude')
+  return join(base, 'sessions')
+}
+
+/**
+ * Fields whose absence leaves a row unable to answer the question asked of it.
+ *
+ * The pid has to be positive rather than merely numeric. Signal zero addresses
+ * the caller's own process group rather than a process, so a record carrying
+ * zero would answer the liveness probe and enter the roster as a live session.
+ */
+function isUsable(value: Partial<SessionRecord>): value is SessionRecord {
+  return (
+    typeof value.pid === 'number' &&
+    Number.isInteger(value.pid) &&
+    value.pid > 0 &&
+    typeof value.cwd === 'string' &&
+    value.cwd.length > 0 &&
+    typeof value.name === 'string' &&
+    value.name.length > 0
+  )
+}
+
+/**
+ * An absent folder and an empty one are separate answers.
+ *
+ * The first means no client ever wrote a record here, so the read never ran and
+ * a roster of none would report a machine with no sessions when the truth is a
+ * lookup that failed. The second is a machine whose sessions have all ended.
+ */
+export type Registry =
+  | { readonly kind: 'absent'; readonly dir: string }
+  | {
+      readonly kind: 'read'
+      readonly dir: string
+      readonly records: SessionRecord[]
+    }
+
+/**
+ * Reads every session record in the folder, newest first.
+ *
+ * A file that does not parse, or that parses without the fields a row is built
+ * from, is dropped rather than reported. The folder accumulates a record per
+ * session and is never pruned, so it holds thousands of entries from clients
+ * spanning many versions, and a finding per stale shape would bury the live
+ * sessions this exists to name.
+ */
+export function readRegistry(dir: string = registryDir()): Registry {
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return { kind: 'absent', dir }
+  }
+
+  const records: SessionRecord[] = []
+
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(join(dir, name), 'utf8'))
+      if (typeof parsed !== 'object' || parsed === null) continue
+      const record = parsed as Partial<SessionRecord>
+      if (isUsable(record)) records.push(record)
+    } catch {
+      // Unreadable or malformed. See the note above.
+    }
+  }
+
+  return {
+    kind: 'read',
+    dir,
+    records: records.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0)),
+  }
+}