@erclx/canon 5.66.0 → 5.67.0

package/src/commands/browser.ts

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { constants, homedir } from 'node:os'
+import type { Command } from 'commander'
+import {
+  AGENT_CLI,
+  CHROMIUM_REVISION,
+  INSTALL_AGENT_BROWSER,
+  browsersRoot,
+  planAgentCall,
+} from '@/browser/agent-cli'
+
+/**
+ * Every byte on stdout and stderr belongs to the child, which skills read
+ * snapshot paths and `--raw eval` values off, so this verb frames nothing and
+ * marks its own refusals with a prefix rather than a record.
+ */
+const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+export function register(program: Command): void {
+  program
+    .command('browser')
+    .description('Drive the pinned agent browser CLI')
+    .argument('[args...]', 'Words passed to the browser CLI untouched')
+    .helpOption('-h, --help', 'Show this help message')
+    .allowUnknownOption()
+    .allowExcessArguments(true)
+    .passThroughOptions()
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Runs ${AGENT_CLI} through bunx in the current directory, so every`,
+        'skill driving a page reaches one version. Snapshots land under',
+        '.playwright-cli/ in the folder it runs in.',
+        '',
+        'open is forced onto the bundled Chromium unless the call names a',
+        `--browser, and refuses rather than downloading when revision ${CHROMIUM_REVISION}`,
+        'is absent. Install it once, outside any pass, with:',
+        `  ${INSTALL_AGENT_BROWSER}`,
+        '',
+        "Stdout, stderr, and the exit code are the browser CLI's. A refusal of",
+        "this verb's own reads 'canon browser:' on stderr.",
+        '',
+        'Exit codes:',
+        "  n  the browser CLI's own exit code",
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon browser --version',
+        '  canon browser -s=canon-12 open http://localhost:4321',
+        '  canon browser -s=canon-12 --raw eval "document.title"',
+        '',
+      ].join('\n'),
+    )
+    .action(async (args: string[]) => {
+      process.exitCode = await runBrowser(args)
+    })
+}
+
+async function runBrowser(args: readonly string[]): Promise<number> {
+  if (Bun.which('bunx') === null) {
+    return refuse('bunx is not on PATH, so the pinned CLI cannot run')
+  }
+
+  const root = browsersRoot(process.env, process.platform, homedir())
+  const call = planAgentCall(args, () =>
+    existsSync(`${root}/chromium-${CHROMIUM_REVISION}`),
+  )
+  if (call.kind === 'refused') return refuse(call.message)
+
+  const child = spawn('bunx', ['-y', AGENT_CLI, ...call.args], {
+    stdio: 'inherit',
+  })
+  // A killed pass must not leave a browser running behind the parent, which a
+  // shell `exec` never had between the caller and the child.
+  const forward = (signal: NodeJS.Signals) => () => child.kill(signal)
+  const handlers = FORWARDED_SIGNALS.map((signal) => {
+    const handler = forward(signal)
+    process.on(signal, handler)
+    return [signal, handler] as const
+  })
+
+  try {
+    return await new Promise<number>((resolve) => {
+      child.on('error', (error) => {
+        process.stderr.write(`canon browser: ${error.message}\n`)
+        resolve(1)
+      })
+      child.on('exit', (code, signal) => {
+        resolve(code ?? 128 + (signal ? constants.signals[signal] : 0))
+      })
+    })
+  } finally {
+    for (const [signal, handler] of handlers) process.off(signal, handler)
+  }
+}
+
+function refuse(message: string): number {
+  process.stderr.write(`canon browser: ${message}\n`)
+  return 1
+}

package/src/commands/intake.ts

@@ -10,6 +10,14 @@ import {
   readFolder,
   type Selection,
 } from '@/intake/folder'
+import {
+  type BaselineOutcome,
+  type CheckOutcome,
+  checkDrive,
+  type DriveFindings,
+  type DriveRefused,
+  recordBaseline,
+} from '@/intake/drive-check'
 import { isUnread } from '@/intake/items'
 import {
   intro,
@@ -37,6 +45,12 @@ interface ListCommandOptions {
   readonly root?: string
 }
 
+interface DriveCheckCommandOptions {
+  readonly baseline?: boolean
+  readonly json?: boolean
+  readonly root?: string
+}
+
 interface AnswerCommandOptions {
   readonly cluster?: string
   readonly json?: boolean
@@ -143,6 +157,67 @@ export function register(program: Command): void {
     .action(async (slug: string, opts: AnswerCommandOptions) => {
       process.exitCode = await runAnswer(slug, opts)
     })
+
+  intake
+    .command('drive-check')
+    .description(
+      'Check an app drive against its goals, the checkout, and its evidence',
+    )
+    .argument('<slug>', 'Intake folder name, as in app-drive-1-0')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--baseline',
+      'Record the main checkout status before the drive, rather than check',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'With --baseline it stores the main checkout status at',
+        '.canon/tmp/app-drive/<slug>/baseline.json, any ordinal dropped from',
+        'the slug, so it runs before the intake folder exists. Without it, it',
+        'reads drive.json in the intake folder and fails the drive on:',
+        '  unmapped         a ## Goals bullet the record carries no entry for',
+        '  unreasoned       a goal marked not-driven with no reason',
+        '  unknown          an entry naming no goal the requirements hold',
+        '  changed          a checkout path that differs from the baseline',
+        '  strayEvidence    an evidence path outside the folder evidence/',
+        '  missingEvidence  an evidence path that holds no file',
+        '  worktreeLeft     the drive worktree the record names, still on disk',
+        '',
+        'A goal matches by its text with any bold label and trailing period',
+        'dropped. A changed path is named and never reverted.',
+        '',
+        'Read `reason` off the record: `recorded` for a baseline, `clean` or',
+        '`failed` for a check, and a refusal otherwise.',
+        '',
+        'Refusals, read off `reason`:',
+        '  no-intake        the project holds no intake folder',
+        '  no-folder        no folder matches the slug',
+        '  ambiguous-slug   a bare slug matches more than one folder',
+        '  bad-input        the slug could leave the scratch folder',
+        '  no-record        the folder carries no drive.json',
+        '  bad-record       drive.json does not parse or breaks its shape',
+        '  no-requirements  the project carries no requirements record',
+        '  no-baseline      no baseline was recorded for the slug',
+        '  unreadable-tree  git cannot read the main checkout status',
+        '',
+        'Exit codes:',
+        '  0  the baseline was recorded, or the drive is clean',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  the drive failed, with every finding in the record',
+        '',
+        'Examples:',
+        '  canon intake drive-check app-drive-1-0 --baseline --json',
+        '  canon intake drive-check app-drive-1-0 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string, opts: DriveCheckCommandOptions) => {
+      process.exitCode = await runDriveCheck(slug, opts)
+    })
 }
 
 function collectSelection(value: string, previous: string[]): string[] {
@@ -262,9 +337,23 @@ async function runAnswer(
   return reportAnswer(outcome, emitJson, root)
 }
 
+async function runDriveCheck(
+  slug: string,
+  opts: DriveCheckCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (opts.baseline) {
+    return reportBaseline(await recordBaseline(root, slug), emitJson, root)
+  }
+
+  return reportDriveCheck(await checkDrive(root, slug), emitJson, root)
+}
+
 function reportRefusal(
   title: string,
-  refused: IntakeRefused,
+  refused: IntakeRefused | DriveRefused,
   emitJson: boolean,
   root: string,
 ): number {
@@ -421,3 +510,94 @@ function reportAnswer(
 
   return 0
 }
+
+function reportBaseline(
+  outcome: BaselineOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake drive-check', outcome, emitJson, root)
+  }
+
+  const path = relative(root, outcome.path)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        reason: 'recorded',
+        baseline: path,
+        entries: outcome.entries,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon intake drive-check')
+  logStep('Baseline')
+  logInfo(`Recorded ${outcome.entries} status line(s).`)
+  logAdd(path)
+  outro()
+
+  return 0
+}
+
+const FINDING_LABELS: Record<keyof DriveFindings, string> = {
+  unmapped: 'Goals with no entry',
+  unreasoned: 'Goals not driven, with no reason',
+  unknown: 'Entries naming no goal',
+  changed: 'Changed in the checkout',
+  strayEvidence: 'Evidence outside evidence/',
+  missingEvidence: 'Evidence holding no file',
+  worktreeLeft: 'Drive worktree still on disk',
+}
+
+function reportDriveCheck(
+  outcome: CheckOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake drive-check', outcome, emitJson, root)
+  }
+
+  const code = outcome.reason === 'clean' ? 0 : 2
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        reason: outcome.reason,
+        goals: outcome.goals,
+        findings: outcome.findings,
+      })}\n`,
+    )
+    return code
+  }
+
+  intro('canon intake drive-check')
+
+  if (outcome.reason === 'clean') {
+    logStep('Clean')
+    logInfo(
+      `${outcome.goals} goal(s) mapped, the checkout untouched, the evidence in place.`,
+    )
+    outro()
+    return code
+  }
+
+  for (const [key, label] of Object.entries(FINDING_LABELS)) {
+    const list = outcome.findings[key as keyof DriveFindings]
+    if (list.length === 0) continue
+    logStep(label)
+    for (const entry of list) logError(entry)
+  }
+  outro()
+
+  return code
+}

package/src/commands/pr.ts

@@ -83,14 +83,12 @@ import {
   type MergeRequest,
 } from '@/pr/merge'
 import { listWorktrees } from '@/git/worktree'
+import { branchSlug, buildDriveCopy, loadPreviewConfig } from '@/pr/drive-copy'
 import {
-  branchSlug,
-  buildDriveCopy,
   changedSince,
-  loadPreviewConfig,
   readWorktreeStatus,
   type StatusEntry,
-} from '@/pr/drive-copy'
+} from '@/git/status'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import { LOCAL_CONFIG_REL, readHealthPaths } from '@/pr/health'
@@ -1306,18 +1304,28 @@ export function register(program: Command): void {
       [
         '',
         'A project names what its preview writes in',
-        '`canon/config/preview.json` as `{ "writes": [path], "env": "<NAME>" }`.',
+        '`canon/config/preview.json` as',
+        '`{ "writes": [path], "keep": [path], "env": "<NAME>" }`.',
         'Each `writes` path is relative to the worktree, and `env`, defaulting',
         'to `CANON_PREVIEW_ROOT`, is the variable the server reads for the copy',
         'root. The server resolves each declared path under that root.',
         '',
+        'Each `keep` path sits below a `writes` path, never equal to one, and',
+        'names state the running server owns there, such as a run file. A',
+        "rebuild leaves it in the copy and never copies the worktree's own, so",
+        'list it for a server that writes under a declared path. The key is',
+        'optional.',
+        '',
         'The copy lives at `.canon/tmp/pr/review-ui/<slug>/board/` at the main',
         'worktree root, where `<slug>` is the branch with a leading type',
         'segment dropped and each `/` made `-`. With a number the branch is the',
         "pull request's head, and without one it is the checkout's, so the",
         'worker starting its server before a pull request exists and the',
         'reviewer naming the number land on one copy. Every run but --check',
-        "rebuilds it from the worktree, dropping the last pass's drives.",
+        "resets each declared path from the worktree, dropping the last pass's",
+        'drives, and leaves the rest of the copy root and each `keep` path as',
+        'they are. A page added only to the copy, inside a declared path, is',
+        'wiped.',
         '',
         '--baseline records `git status` for the worktree under',
         '`.canon/tmp/pr/review-ui/<number>/`, and --check reports each path',
@@ -4485,6 +4493,7 @@ async function runDriveCopy(
       target.worktree,
       copyRoot,
       config.config.writes,
+      config.config.keep,
     )
     logStep('Copied')
     logInfo(`${config.config.env}=${copyRoot}`)

package/src/commands/records.ts

@@ -34,6 +34,7 @@ import {
   type StructureFinding,
   validateRecords,
 } from '@/records/validate'
+import type { SessionMapLength } from '@/records/session-map'
 import {
   intro,
   logError,
@@ -92,7 +93,7 @@ export function register(program: Command): void {
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
     .argument(
       '[record]',
-      'One plan stem or folder slug, narrowing both findings and structure to it',
+      'One plan stem, folder slug, or session map stem, narrowing the report to it',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -105,6 +106,7 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        "  sessions    each session map's words against its cap, under `length` and never in the exit",
         '',
         'Structure, under `structure` and never in the exit:',
         "  S1 to S5 from the plan standard, read on plans, a track's README and",
@@ -128,6 +130,7 @@ export function register(program: Command): void {
         '  canon records validate plans',
         '  canon records validate plans feature-records-by-heading',
         '  canon records validate intake --json',
+        '  canon records validate sessions session-orchestrator',
         '',
       ].join('\n'),
     )
@@ -828,6 +831,7 @@ function report(
         records: outcome.records,
         findings: outcome.findings,
         structure: outcome.structure,
+        ...(outcome.length && { length: outcome.length }),
       })}\n`,
     )
   } else {
@@ -846,6 +850,14 @@ function report(
       logStep('Structure, reported and never in the exit')
       for (const entry of outcome.structure) logInfo(describeStructure(entry))
     }
+
+    if (outcome.length) {
+      logStep('Length, reported and never in the exit')
+      for (const entry of outcome.length) {
+        const log = entry.over ? logWarn : logInfo
+        log(describeLength(entry))
+      }
+    }
     outro()
   }
 
@@ -857,6 +869,11 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
+function describeLength(entry: SessionMapLength): string {
+  const verdict = entry.over ? 'over the cap' : 'within the cap'
+  return `${entry.record}: ${entry.words} of ${entry.cap} words, ${verdict}`
+}
+
 function describeStructure(entry: StructureFinding): string {
   const scope = entry.record === entry.subject ? '' : `${entry.record}/`
   return `${entry.criterion} ${scope}${entry.subject}:${entry.line} ${entry.message}`