@erclx/aitk 3.45.0 → 3.47.0

package/src/commands/sessions.ts

@@ -2,10 +2,13 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
+  callerIdentity,
   repositoryOf,
   type ResolvedSession,
   resolveSessions,
+  type SelfReport,
   type SessionReport,
+  selfOf,
 } from '@/sessions/resolve'
 import {
   intro,
@@ -21,6 +24,7 @@ interface ListCommandOptions {
   readonly json?: boolean
   readonly branch?: string
   readonly repository?: string
+  readonly self?: boolean
 }
 
 const REASONS: Record<string, string> = {
@@ -52,6 +56,10 @@ export function register(program: Command): void {
       '--repository <path>',
       'Answer about this project rather than the working one',
     )
+    .option(
+      '--self',
+      "Report the caller's own row, and refuse where the roster holds none",
+    )
     .addHelpText(
       'after',
       [
@@ -93,6 +101,19 @@ export function register(program: Command): void {
         'The match can return more than one session. Read the count rather than',
         'the first row, since two sessions can hold one branch.',
         '',
+        "--self narrows the report to the caller's own row, which is what a",
+        'dispatcher reads to learn the sessionId it carries into a launch. It',
+        'joins on CLAUDE_CODE_SESSION_ID first, falls back to CLAUDE_PID, and',
+        'falls back again to the pid the messaging socket path spells. It never',
+        'reads CLAUDE_CODE_HOST_SESSION_ID, which holds a value from another',
+        'namespace that matches no row.',
+        '',
+        'It refuses with reason "no-self-identity" when the environment states',
+        'none of the three, and "no-self-row" when it states one and no live',
+        'row carries it. The second is the ordinary answer for a session',
+        'driving from Remote Control, which is addressable on the message',
+        'channel and holds no local process record for the roster to report.',
+        '',
         'Each session writes its own working directory beside its own name, so a',
         'name from a session listing joins to a branch by an exact match rather',
         'than by ordering the roster on start time.',
@@ -108,6 +129,7 @@ export function register(program: Command): void {
         '  aitk sessions list --json',
         '  aitk sessions list --branch feat/parser --json',
         '  aitk sessions list --branch chore/agents --repository ../caret --json',
+        '  aitk sessions list --self --json',
         '',
       ].join('\n'),
     )
@@ -136,6 +158,34 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     return 1
   }
 
+  // The roster read returns every row and marks none of them as the caller, so
+  // the join runs here, ahead of any scope. Resolving it after the branch
+  // filter would answer "no row" for a caller whose row was merely filtered
+  // out, which is a different failure wearing the same reason.
+  const own = opts.self ? selfOf(report.sessions, callerIdentity()) : null
+
+  if (own?.kind === 'unresolved') {
+    intro('aitk sessions list')
+    logStep('Refused')
+    logWarn(selfRefusal(own))
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({
+          dir: report.dir,
+          reason:
+            own.reason === 'no-identity' ? 'no-self-identity' : 'no-self-row',
+          sessions: [],
+        })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  const pool = own === null ? report.sessions : [own.session]
+
   // A branch name identifies a branch inside one repository and nothing across
   // a machine, so an unscoped match reaches a session working in a different
   // project. `main` is the name that collides on every machine running two.
@@ -164,11 +214,11 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   }
 
   const shown = opts.branch
-    ? report.sessions.filter(
+    ? pool.filter(
         (session) =>
           session.branch === opts.branch && session.repository === repository,
       )
-    : report.sessions
+    : pool
 
   const claim = opts.branch
     ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
@@ -176,7 +226,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
 
   intro('aitk sessions list')
   reportConfidence(report)
-  reportSessions(shown, opts.branch, repository)
+  reportSessions(shown, opts.branch, repository, own !== null)
   if (claim) reportClaim(claim)
   outro()
 
@@ -200,6 +250,22 @@ async function runList(opts: ListCommandOptions): Promise<number> {
   return 0
 }
 
+/**
+ * Separates a client that states no identity from a roster holding no row for
+ * one it does state, since the two send a reader to different places.
+ */
+function selfRefusal(own: Extract<SelfReport, { kind: 'unresolved' }>): string {
+  if (own.reason === 'no-identity') {
+    return 'Nothing in the environment identifies this session, so --self has nothing to match against. A client setting none of CLAUDE_CODE_SESSION_ID, CLAUDE_PID, or CLAUDE_CODE_MESSAGING_SOCKET cannot be located on the roster at all.'
+  }
+
+  const held =
+    own.identity.sessionId ??
+    (own.identity.pid === null ? 'nothing' : `pid ${own.identity.pid}`)
+
+  return `The environment identifies this session as ${held}, and no live row carries it. The roster holds local process records alone, so a session driving through Remote Control never appears here, and a record whose session has ended is dropped ahead of the match.`
+}
+
 /**
  * States how liveness was decided on every run, including the run that decided
  * it the strong way.
@@ -239,6 +305,7 @@ function reportSessions(
   sessions: readonly ResolvedSession[],
   branch: string | undefined,
   repository: string | null,
+  scoped: boolean,
 ): void {
   logStep('Sessions')
 
@@ -248,11 +315,21 @@ function reportSessions(
     )
   }
 
+  // An empty result under --self says nothing about the roster, since the pool
+  // was narrowed to one row before the branch filter ran. Reporting the wider
+  // answer there would claim a reading this run never took.
   if (sessions.length === 0) {
+    if (branch) {
+      logInfo(
+        scoped
+          ? `This session does not hold ${branch}.`
+          : `No live session in this repository holds ${branch}.`,
+      )
+      return
+    }
+
     logInfo(
-      branch
-        ? `No live session in this repository holds ${branch}.`
-        : 'No live session. Every record in the registry belongs to a session that has ended.',
+      'No live session. Every record in the registry belongs to a session that has ended.',
     )
     return
   }

package/src/process/harness.ts

@@ -0,0 +1,167 @@
+import { spawnSync } from 'node:child_process'
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/project-root'
+import { stateDir } from '@/targets/registry'
+
+const CLI = join(PROJECT_ROOT, 'src/cli.ts')
+
+/** No case has ever needed longer, and a blocked verb should fail fast. */
+const DEFAULT_TIMEOUT_MS = 10_000
+
+export interface ProcessRun {
+  readonly status: number | null
+  readonly stdout: string
+  readonly stderr: string
+  readonly json: unknown
+}
+
+export interface RunCliOptions {
+  readonly cwd: string
+  readonly env?: NodeJS.ProcessEnv
+  readonly timeoutMs?: number
+}
+
+/**
+ * Thrown when a case reaches past its declared temporary directory into this
+ * machine's real toolkit state. `stateDir()` in `src/targets/registry.ts`
+ * holds both the target registry `gov install` and `gov sync` record into and
+ * the sandbox tree `aitk sandbox` provisions into, so a case that inherits the
+ * real `HOME` unmodified writes into whichever of the two a verb touches, and
+ * nothing but this check would ever say so.
+ */
+export class ContainmentViolation extends Error {}
+
+/**
+ * Compares two snapshots of this machine's real toolkit state directory and
+ * reports whether a spawn changed it. A pure comparison over the two reads
+ * rather than the read itself, so the detection logic is testable without
+ * touching the filesystem or spawning anything.
+ */
+export function detectStateLeak(
+  before: string | undefined,
+  after: string | undefined,
+): boolean {
+  return before !== after
+}
+
+/**
+ * A sorted `path:size` listing of every file under this machine's real
+ * `stateDir()`, walked recursively rather than read one level deep, so a
+ * write nested inside an existing folder, such as a file the sandbox tree
+ * already holds, shows up the same as a new top-level entry. Reading a single
+ * known file, such as the target registry alone, would miss every sibling
+ * `stateDir()` grows, which is what left the sandbox tree unwatched.
+ */
+export function snapshotStateDir(): string {
+  const root = stateDir()
+  const rows: string[] = []
+
+  function walk(dir: string): void {
+    let names: string[]
+    try {
+      names = readdirSync(dir)
+    } catch {
+      return
+    }
+
+    for (const name of names.sort()) {
+      const full = join(dir, name)
+      let info: ReturnType<typeof statSync>
+      try {
+        info = statSync(full)
+      } catch {
+        continue
+      }
+      if (info.isDirectory()) walk(full)
+      else rows.push(`${full}:${info.size}`)
+    }
+  }
+
+  walk(root)
+  return rows.join('\n')
+}
+
+/**
+ * Spawns the real entry point rather than calling a command's action function
+ * in-process, so a case answers whether a verb is registered, whether it
+ * exits the way its own contract states, and whether its `--json` record
+ * parses off stdout alone, none of which an in-process call can misreport.
+ *
+ * A git hook exports `GIT_DIR`, which would resolve a fixture's git-aware
+ * reads against this checkout instead of the temporary directory a case
+ * builds, so every spawn drops the `GIT_` prefix before adding the headless
+ * flag every case needs to avoid a picker blocking on stdin.
+ *
+ * `AITK_STATE_DIR` and `AITK_SANDBOX_DIR` get the same treatment as `GIT_DIR`,
+ * each pointed at a folder under the case's own `cwd` rather than dropped,
+ * since dropping either alone would still resolve through the inherited
+ * `HOME` to this machine's real `~/.local/state/aitk`. `stateDir()` and
+ * `sandboxTree()` resolve the same three ways and share that parent, so both
+ * overrides move together. A case explicitly passing its own value through
+ * `options.env` still wins, matching `AITK_NON_INTERACTIVE` below.
+ *
+ * The `stateDir()` snapshot before and after the spawn is what actually
+ * catches an escape past that redirection, since a default can be wrong in a
+ * way a case never asserts on its own, and it is what `AITK_SANDBOX_DIR`
+ * rides for free: the sandbox tree already sits under `stateDir()`, so
+ * walking the whole directory catches a leak there with no override of its
+ * own to add. `ContainmentViolation` fails loud rather than leaving a dead
+ * row for a reviewer to find on a real machine.
+ */
+export function runCli(
+  args: readonly string[],
+  options: RunCliOptions,
+): ProcessRun {
+  const inherited = Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')),
+  )
+
+  const before = snapshotStateDir()
+
+  const result = spawnSync('bun', [CLI, ...args], {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    env: {
+      ...inherited,
+      AITK_NON_INTERACTIVE: '1',
+      AITK_STATE_DIR: join(options.cwd, '.aitk-state'),
+      AITK_SANDBOX_DIR: join(options.cwd, '.aitk-state', 'sandbox'),
+      ...options.env,
+    },
+  })
+
+  const after = snapshotStateDir()
+  if (detectStateLeak(before, after)) {
+    throw new ContainmentViolation(
+      `A case wrote into this machine's real toolkit state at ${stateDir()}. ` +
+        'Every process-tier case must stay inside the directory it declared.',
+    )
+  }
+
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    json: parseJson(result.stdout),
+  }
+}
+
+/**
+ * Data goes to stdout and framing to stderr, so a harness reading `--json`
+ * off the merged output would assert against a record no verb ever wrote. A
+ * command that emits no JSON, or fails before it gets there, leaves the
+ * field `undefined` rather than throwing, so a case asserting the exit code
+ * of a refusal is not also forced to guard a parse.
+ */
+function parseJson(stdout: string): unknown {
+  const trimmed = stdout.trim()
+  if (trimmed === '') return undefined
+
+  try {
+    return JSON.parse(trimmed)
+  } catch {
+    return undefined
+  }
+}

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)
+    },
+  }
+}