@erclx/canon 4.0.0

package/src/commands/serve.ts

@@ -0,0 +1,159 @@
+import type { Command } from 'commander'
+import { relative } from 'node:path'
+import { DEFAULT_PORT, type ServeOutcome, startServer } from '@/serve/static'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+const DEFAULT_DIR = '.'
+
+interface ServeCommandOptions {
+  readonly entry?: string
+  readonly json?: boolean
+  readonly port?: string
+}
+
+export function register(program: Command): void {
+  program
+    .command('serve')
+    .description('Serve a directory over localhost and print the preview link')
+    .argument('[dir]', 'Directory to serve', DEFAULT_DIR)
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--port <number>', `Port to try first, default ${DEFAULT_PORT}`)
+    .option('--entry <path>', 'Page the printed link opens, default index.html')
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the server stopped after running',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'The server binds 127.0.0.1 and nothing else, and it sends no cache',
+        'headers, so an edited stylesheet is never served stale. A port in use',
+        'is not a failure: the next free one is taken and the link says which.',
+        '',
+        'It runs until interrupted. A session wanting the link without waiting',
+        'starts it in the background and reads the record off stdout.',
+        '',
+        'Examples:',
+        '  canon serve .claude/teach',
+        '  canon serve .claude/teach --entry 03-fde-system-design/index.html',
+        '  canon serve dist --port 4000 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (dir: string, opts: ServeCommandOptions) => {
+      process.exitCode = await runServe(dir, opts)
+    })
+}
+
+async function runServe(
+  dir: string,
+  opts: ServeCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  const port = parsePort(opts.port)
+  if (port === undefined) {
+    return report(
+      { ok: false, reason: 'no-port', detail: `${opts.port} is not a port` },
+      emitJson,
+    )
+  }
+
+  const outcome = startServer(dir, { port, entry: opts.entry })
+  const code = report(outcome, emitJson)
+  if (!outcome.ok) return code
+
+  await waitForInterrupt(outcome.stop)
+  return 0
+}
+
+/**
+ * The relative path where it stays inside the working directory, and the
+ * absolute one where it climbs out. A run from a linked worktree serving the
+ * main root reports `../../teach`, which names the directory without giving a
+ * reader anything they can open.
+ */
+function displayPath(root: string): string {
+  const near = relative(process.cwd(), root)
+  if (near === '') return '.'
+  return near.startsWith('..') ? root : near
+}
+
+/**
+ * Undefined for a value that is not a port, distinct from an absent flag,
+ * which takes the default. A `Number` of a typo is `NaN`, and passing that on
+ * asks the runtime to bind a port nobody named.
+ */
+function parsePort(raw: string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_PORT
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0 || value > 65535) return undefined
+  return value
+}
+
+function report(outcome: ServeOutcome, emitJson: boolean): number {
+  if (!outcome.ok) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, reason: outcome.reason, detail: outcome.detail })}\n`,
+      )
+      return 1
+    }
+    intro('canon serve')
+    logError(outcome.detail)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root: outcome.root,
+        host: outcome.host,
+        port: outcome.port,
+        entry: outcome.entry,
+        url: outcome.url,
+        entryExists: outcome.entryExists,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon serve')
+  logStep('Serving')
+  logInfo(displayPath(outcome.root))
+  logStep('Open')
+  logInfo(outcome.url)
+
+  if (!outcome.entryExists) {
+    logStep('No entry page')
+    logWarn(
+      `${outcome.entry} is not in that directory, so the link opens a 404`,
+    )
+  }
+
+  logStep('Stop')
+  logInfo('Ctrl-C')
+  return 0
+}
+
+/**
+ * Resolves when the process is asked to stop. The frame is closed here rather
+ * than in the reporter, because the run is the serving rather than the start,
+ * and closing at start would print the frame's end while the server ran on.
+ */
+function waitForInterrupt(stop: () => Promise<void>): Promise<void> {
+  return new Promise((settle) => {
+    const finish = () => {
+      void stop().then(() => {
+        outro()
+        settle()
+      })
+    }
+    process.once('SIGINT', finish)
+    process.once('SIGTERM', finish)
+  })
+}

package/src/commands/sessions.ts

@@ -0,0 +1,408 @@
+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,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly branch?: string
+  readonly repository?: string
+  readonly self?: boolean
+}
+
+const REASONS: Record<string, string> = {
+  'not-a-repository': 'working outside any git repository',
+  'detached-head': 'detached HEAD, so the worktree holds no branch name',
+  'git-unavailable': 'git is not on the path, so nothing could be read',
+}
+
+export function register(program: Command): void {
+  const sessions = program
+    .command('sessions')
+    .description(
+      'Resolve live peer sessions to the worktree and branch each holds',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+
+  sessions
+    .command('list')
+    .description(
+      'Report every live session with its working directory and branch',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--branch <name>',
+      'Report only the sessions holding this branch in this repository',
+    )
+    .option(
+      '--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',
+      [
+        '',
+        'Exit codes:',
+        '  0  the roster was read',
+        '  1  refused, with the reason on stderr',
+        '',
+        '--branch scopes the match to one repository, since a branch name',
+        'identifies a branch there and nothing across a machine. That is the',
+        'repository the command runs in unless --repository names another.',
+        'A bare run reports every repository and carries the repository field,',
+        'so a caller filtering by hand has something that identifies one.',
+        '',
+        '--repository moves every reading to the project at that path, the',
+        'session match and the worktree and ref reads alike. The roster is',
+        'machine-wide already, so this is what lets a dispatcher in one project',
+        'see a branch a live session holds in another rather than reading it as',
+        'unclaimed and sending a second session onto it.',
+        '',
+        'With --branch, the JSON also carries "worktree" (the path of any',
+        'worktree already checked out to it, or null), "refs" (the refs that',
+        'already name it, local head and origin remote-tracking alike), and',
+        '"claimed" (true when a worktree, a live session, or an existing ref',
+        'holds it). A dispatcher reads "claimed" rather than composing the',
+        'three fields itself, since each alone misses a real claim: 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.',
+        '',
+        '"sessionsReadable" is false when the session roster could not be read',
+        'and "refsReadable" is false when the ref read failed. Either one',
+        'leaves "claimed" covering the readings around it alone. Treat that',
+        'case as unverified rather than as a clean "false".',
+        '',
+        'The ref read sees the remote at whatever the last fetch left, so a',
+        'branch pushed from another machine since then reads absent here.',
+        '',
+        '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.',
+        '',
+        'The confidence field says how the liveness of a row was decided.',
+        '"confirmed" matched the running process against the start time the',
+        'record stamped. "unverified" means only that the pid answers, which',
+        'cannot rule out a pid handed to an unrelated process, so a roster',
+        'reported that way is a candidate list rather than an identity.',
+        '',
+        'The JSON record also carries "statusUpdatedAt" (the stamp the client',
+        'wrote beside "status", or null where its record carries none) and',
+        '"statusDwellMs" (the elapsed milliseconds since that stamp, falling',
+        'back to the coarser "updatedAt" where the narrower one is absent,',
+        'computed at read time and clamped at zero against clock skew). The',
+        'framed listing renders the same dwell beside the status, at the',
+        'coarsest unit that keeps it a whole number.',
+        '',
+        'Examples:',
+        '  canon sessions list',
+        '  canon sessions list --json',
+        '  canon sessions list --branch feat/parser --json',
+        '  canon sessions list --branch chore/agents --repository ../caret --json',
+        '  canon sessions list --self --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: ListCommandOptions) => {
+      process.exitCode = await runList(opts)
+    })
+}
+
+async function runList(opts: ListCommandOptions): Promise<number> {
+  const report = await resolveSessions()
+
+  if (report.kind === 'absent') {
+    intro('canon sessions list')
+    logStep('Refused')
+    logWarn(
+      `No session registry at ${report.dir}. Nothing was read, so this is not a machine with no sessions.`,
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ dir: report.dir, reason: 'no-registry', sessions: [] })}\n`,
+      )
+    }
+
+    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('canon 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.
+  //
+  // Which repository that is is the caller's to name. The roster this filters
+  // is machine-wide already, so a dispatcher asking about another project was
+  // answered "unclaimed" about a branch a live session there was holding.
+  const at = opts.repository ? resolve(opts.repository) : process.cwd()
+  const repository = opts.branch ? await repositoryOf(at) : null
+
+  if (opts.branch && repository === null) {
+    intro('canon sessions list')
+    logStep('Refused')
+    logWarn(
+      `--branch scopes the match to one repository, and none resolved at ${at}. Run it inside one, name another with --repository, or read the whole roster and filter on the repository field.`,
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ dir: report.dir, reason: 'no-repository', sessions: [] })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  const shown = opts.branch
+    ? pool.filter(
+        (session) =>
+          session.branch === opts.branch && session.repository === repository,
+      )
+    : pool
+
+  const claim = opts.branch
+    ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
+    : null
+
+  intro('canon sessions list')
+  reportConfidence(report)
+  reportSessions(shown, opts.branch, repository, own !== null)
+  if (claim) reportClaim(claim)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        dir: report.dir,
+        confidence: report.confidence,
+        branch: opts.branch ?? null,
+        repository,
+        worktree: claim?.worktree ?? null,
+        refs: claim?.refs ?? null,
+        claimed: claim?.claimed ?? null,
+        sessionsReadable: claim?.sessionsReadable ?? null,
+        refsReadable: claim?.refsReadable ?? null,
+        sessions: shown,
+      })}\n`,
+    )
+  }
+
+  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.
+ *
+ * A caller reading a roster has no other way to tell a confirmed identity from
+ * a pid that merely answered, and the two support different actions: the first
+ * addresses a session directly and the second opens by asking to be corrected.
+ */
+function reportConfidence(
+  report: Extract<SessionReport, { kind: 'resolved' }>,
+): void {
+  logStep('Liveness')
+
+  // A roster of none decided nothing, so the confirmed line would claim a check
+  // over rows that do not exist. The registry is never pruned and holds a record
+  // per session ever run, which is what makes the empty result worth stating.
+  if (report.sessions.length === 0) {
+    logInfo(
+      'No row to decide. Every record belongs to a session that has ended.',
+    )
+    return
+  }
+
+  if (report.confidence === 'confirmed') {
+    logInfo(
+      'Every row matched a running process against the start time its record stamped.',
+    )
+    return
+  }
+
+  logWarn(
+    'Start times could not be read, so rows rest on a pid answering alone. Treat the mapping as inferred and open by asking to be corrected.',
+  )
+}
+
+function reportSessions(
+  sessions: readonly ResolvedSession[],
+  branch: string | undefined,
+  repository: string | null,
+  scoped: boolean,
+): void {
+  logStep('Sessions')
+
+  if (branch) {
+    logInfo(
+      `Scoped to ${repository}, since a branch name identifies one there.`,
+    )
+  }
+
+  // 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(
+      'No live session. Every record in the registry belongs to a session that has ended.',
+    )
+    return
+  }
+
+  // The count is what a dispatch turns on. One row is a target and several are
+  // candidates, and the caller cannot tell them apart from a roster alone.
+  if (branch && sessions.length > 1) {
+    logWarn(
+      `${sessions.length} sessions hold ${branch}. Confirm which one before addressing it.`,
+    )
+  }
+
+  logInfo(plural(sessions.length, 'live session'))
+  pipeOutput(
+    sessions
+      .map((session) => {
+        const held =
+          session.branch ??
+          `unresolved: ${REASONS[session.unresolved ?? ''] ?? 'unknown'}`
+        const dwell = formatDwell(session.statusDwellMs)
+        const status = dwell ? `${session.status} ${dwell}` : session.status
+        return `${session.name}  ${status}  ${held}\n  ${session.cwd}`
+      })
+      .join('\n'),
+  )
+}
+
+/**
+ * Renders the dwell at the coarsest unit that keeps it a whole number, since a
+ * reader scanning a roster wants an age at a glance rather than a millisecond
+ * count. An absent dwell renders as nothing, folding a status carrying no
+ * stamp back to the bare status line the reader already knew.
+ */
+function formatDwell(ms: number | null): string {
+  if (ms === null) return ''
+  const seconds = Math.round(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.round(minutes / 60)
+  return `${hours}h`
+}
+
+function reportClaim(claim: ClaimReport): void {
+  logStep('Claim')
+
+  if (claim.worktree) {
+    logInfo(`Worktree: ${claim.worktree}`)
+  }
+
+  if (claim.refs.length > 0) {
+    logInfo(`Refs: ${claim.refs.join(', ')}`)
+  }
+
+  logInfo(claim.claimed ? 'Claimed.' : 'Unclaimed.')
+
+  if (!claim.sessionsReadable) {
+    logWarn(
+      'The session roster could not be read, so this leaves the session half out. Treat it as unverified rather than clear.',
+    )
+  }
+
+  if (!claim.refsReadable) {
+    logWarn(
+      'The ref read failed, so this cannot say whether the branch already exists. Treat it as unverified rather than clear.',
+    )
+  }
+}

package/src/commands/slides.ts

@@ -0,0 +1,126 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { LAYOUTS } from '@/slides/layouts'
+import { openDeck } from '@/slides/open'
+import { renderSlidesDoc } from '@/slides/render'
+import type { Variant } from '@/slides/styles'
+import { intro, outro, palette } from '@/ui'
+
+export function register(program: Command): void {
+  const slides = program
+    .command('slides')
+    .description('Slide deck commands (render, list)')
+
+  slides
+    .command('render')
+    .description('Render a SLIDES.md source into a PowerPoint deck')
+    .option('-s, --source <path>', 'Source SLIDES.md path', '.claude/SLIDES.md')
+    .option('-o, --out <path>', 'Output directory', '.claude/review/slides')
+    .option('-v, --variant <variant>', 'Override variant (light or dark)')
+    .option(
+      '-m, --mirror <path>',
+      'Copy the deck to this directory after writing',
+    )
+    .option('--open', 'Open the deck after writing')
+    .action(
+      async (opts: {
+        source: string
+        out: string
+        variant?: string
+        mirror?: string
+        open?: boolean
+      }) => {
+        try {
+          const sourcePath = resolve(process.cwd(), opts.source)
+          const outDir = resolve(process.cwd(), opts.out)
+          if (!existsSync(sourcePath)) {
+            fail(`${opts.source} not found`)
+          }
+          const variant = parseVariant(opts.variant)
+          const mirror = resolveMirror(opts.mirror)
+          const { GREEN, GREY, NC, RED } = palette(process.stderr)
+          intro('Render slides')
+          const result = await renderSlidesDoc(sourcePath, outDir, {
+            variant,
+            mirror,
+          })
+          process.stderr.write(
+            `${GREY}│${NC} ${GREEN}✓${NC} ${result.slideCount} slides\n${GREY}│${NC} ${GREEN}✓${NC} ${result.pptxPath}\n`,
+          )
+          if (result.mirrorPath) {
+            process.stderr.write(
+              `${GREY}│${NC} ${GREEN}✓${NC} mirrored to ${result.mirrorPath}\n`,
+            )
+          }
+          if (opts.open) {
+            const target = result.mirrorPath ?? result.pptxPath
+            const opened = await openDeck(target)
+            const mark = opened ? `${GREEN}✓${NC}` : `${RED}✗${NC}`
+            process.stderr.write(
+              `${GREY}│${NC} ${mark} ${opened ? 'opened' : 'could not open'} ${target}\n`,
+            )
+          }
+          outro()
+        } catch (error) {
+          reportFailure(error)
+        }
+      },
+    )
+
+  slides
+    .command('list')
+    .description('List the available slide layouts')
+    .option('--json', 'Output the layout catalog as JSON')
+    .action((opts: { json?: boolean }) => {
+      if (opts.json) {
+        process.stdout.write(`${JSON.stringify(LAYOUTS)}\n`)
+        return
+      }
+      const { GREEN, GREY, NC } = palette(process.stderr)
+      intro('Slide layouts')
+      for (const layout of LAYOUTS) {
+        process.stderr.write(
+          `${GREY}│${NC} ${GREEN}✓${NC} ${layout.name}  ${GREY}${layout.description}${NC}\n`,
+        )
+      }
+      outro()
+    })
+}
+
+function parseVariant(value: string | undefined): Variant | undefined {
+  if (value === undefined) return undefined
+  if (value === 'light' || value === 'dark') return value
+  fail(`Invalid variant "${value}". Use light or dark.`)
+}
+
+function resolveMirror(value: string | undefined): string | undefined {
+  const mirror = value ?? process.env.CANON_SLIDES_MIRROR
+  return mirror ? resolve(process.cwd(), mirror) : undefined
+}
+
+/**
+ * Carries a fail-fast message from a validation helper to the action that
+ * called it. `fail` has to keep its `never` return, since that is what makes
+ * `parseVariant` exhaustive to the compiler, and a helper deep in the call
+ * stack cannot set `process.exitCode` and unwind on its own.
+ */
+class SlidesError extends Error {}
+
+function fail(message: string): never {
+  throw new SlidesError(message)
+}
+
+/**
+ * `src/cli.ts` calls `program.parse()` without awaiting it, so a rejected
+ * action promise reaches no handler and Bun prints a stack trace. Every action
+ * that calls `fail` catches at its own boundary.
+ */
+function reportFailure(error: unknown): void {
+  if (!(error instanceof SlidesError)) throw error
+  const { GREY, NC, RED } = palette(process.stderr)
+  process.stderr.write(
+    `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${error.message}\n${GREY}└${NC}\n`,
+  )
+  process.exitCode = 1
+}