@erclx/canon 5.65.0 → 5.67.0

package/docs/workflow/visual-design-workflow.md

@@ -43,8 +43,9 @@ Run `canon drive --help` for the step kinds and the run file shape.
 Two reviews run beside each other and finish on their own clocks.
 
 - `canon:review-pr` reads the code and the stills in the evidence comment, and posts under `## Review`.
-- `canon:review-ui` never reads the diff. It drives each checklist box in the running app through the pinned `@playwright/cli` and posts under `## UI review`.
+- `canon:review-ui` never reads the diff. It drives each checklist box in the running app through `canon browser`, which runs the pinned `@playwright/cli`, and posts under `## UI review`.
 - Every box gets one verdict, being pass, fail, needs eyes, or not driven.
+- The pass refuses rather than download a browser. Install it once per machine with `canon browser install-browser chromium`.
 
 After the boxes, `review-ui` sweeps every route they reached:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.65.0",
+  "version": "5.67.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/audits/catalog.ts

@@ -451,7 +451,11 @@ function testOrderCounts(record: unknown): Record<string, number> | undefined {
   })
 }
 
-/** The record kinds `canon records validate` takes, and the corpus each reads. */
+/**
+ * The record kinds whose findings the aggregate counts, and the corpus each
+ * reads. `sessions` is left out because it reports length alone and never a
+ * finding, so a row for it would always count zero.
+ */
 const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
   ['plans', 'per-machine'],
   ['groundwork', 'per-machine'],

package/src/browser/agent-cli.ts

@@ -0,0 +1,68 @@
+/**
+ * The pinned agent browser CLI every skill driving a page reaches through
+ * `canon browser`, so every call in a run and every run on a machine reach one
+ * version. `open` is forced onto the bundled Chromium, since the CLI's default
+ * channel is a branded Chrome most machines lack, and it refuses rather than
+ * downloading when that browser is absent, since a dispatched reviewer that
+ * installs mid-pass spends its budget on the download.
+ */
+
+export const AGENT_CLI = '@playwright/cli@0.1.22'
+
+/**
+ * The Chromium revision that CLI version requires. It moves with the pin, and
+ * it is separate from the revision `INSTALL_BROWSER` fetches for the engine.
+ */
+export const CHROMIUM_REVISION = '1247'
+
+export const INSTALL_AGENT_BROWSER = 'canon browser install-browser chromium'
+
+export type AgentCall =
+  | { readonly kind: 'run'; readonly args: readonly string[] }
+  | { readonly kind: 'refused'; readonly message: string }
+
+/**
+ * Rewrites the caller's words into the child's, reading the revision only for
+ * `open`, the one verb that launches a browser. Global flags may lead the verb,
+ * as in `-s=<name> --raw open <url>`.
+ */
+export function planAgentCall(
+  args: readonly string[],
+  hasRevision: () => boolean,
+): AgentCall {
+  const verbAt = args.findIndex((arg) => !arg.startsWith('-'))
+  if (verbAt === -1 || args[verbAt] !== 'open') return { kind: 'run', args }
+
+  if (!hasRevision()) {
+    return {
+      kind: 'refused',
+      message: `Chromium revision ${CHROMIUM_REVISION} is not installed. Run once, outside the pass: ${INSTALL_AGENT_BROWSER}`,
+    }
+  }
+
+  const namesBrowser = args.some(
+    (arg) => arg === '--browser' || arg.startsWith('--browser='),
+  )
+  if (namesBrowser) return { kind: 'run', args }
+
+  return {
+    kind: 'run',
+    args: [
+      ...args.slice(0, verbAt + 1),
+      '--browser=chromium',
+      ...args.slice(verbAt + 1),
+    ],
+  }
+}
+
+/** Where Playwright keeps downloaded browsers, by its own lookup order. */
+export function browsersRoot(
+  env: Readonly<Record<string, string | undefined>>,
+  platform: string,
+  home: string,
+): string {
+  const override = env.PLAYWRIGHT_BROWSERS_PATH
+  if (override !== undefined && override !== '') return override
+  if (platform === 'darwin') return `${home}/Library/Caches/ms-playwright`
+  return `${home}/.cache/ms-playwright`
+}

package/src/claude/cases/git.ts

@@ -22,6 +22,10 @@ export const GIT_CASES: readonly SkillCase[] = [
     prompt: 'Turn this bug into a GitHub issue and file it.',
     expect: 'git-issue',
   },
+  {
+    prompt: 'Close #42 without merging, #57 supersedes it.',
+    expect: 'git-pr-close',
+  },
   {
     prompt: 'Write the title and body for this pull request.',
     expect: 'git-pr',

package/src/claude/cases/workflow.ts

@@ -149,6 +149,26 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
     prompt: 'Tell me the paint and layout cost of this page right now.',
     expect: 'ux-measure',
   },
+  {
+    prompt:
+      'We just tagged the release. Spin up a copy of the build and use it with me as its users would, then file whatever breaks.',
+    expect: 'app-drive',
+  },
+  {
+    prompt:
+      'Before we plan the next wave, put the built app through every goal in the requirements with me and write up what we hit.',
+    expect: 'app-drive',
+  },
+  {
+    prompt:
+      'I need real footage of the board import flow for the launch video. Film it from our app so HyperFrames can zoom in on the clicks.',
+    expect: 'ui-record',
+  },
+  {
+    prompt:
+      'Shoot the takes for the storyboard we wrote, one clip per beat of the app doing its thing.',
+    expect: 'ui-record',
+  },
   {
     prompt:
       'I am building this branch for another session. What am I on the hook for, and what is off limits?',

package/src/cli/help.ts

@@ -42,6 +42,8 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['serve [dir]', 'Serve a directory on localhost, print the link'],
       ['inventory [subj]', 'Report one computed property across every route'],
       ['drive <url> <run>', 'Walk a page through interactions, measure each'],
+      ['browser [args]', 'Drive the pinned agent browser CLI'],
+      ['take <url> <plan>', 'Film a web app with a click log and camera track'],
       ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
     ],
   },
@@ -100,6 +102,7 @@ const EXAMPLES = [
   'canon capture assets/captures/install.html --selector .window --out assets/frames',
   'canon inventory focus --json',
   'canon drive http://localhost:4173 run.json --json',
+  'canon take http://localhost:4173 plan.json --out takes --json',
   'pbpaste | canon feedback',
   'canon transcripts https://youtu.be/VIDEO_ID',
   'canon tasks --help --all',

package/src/cli.ts

@@ -14,6 +14,8 @@ import { register as capture } from '@/commands/capture'
 import { register as serve } from '@/commands/serve'
 import { register as inventory } from '@/commands/inventory'
 import { register as driver } from '@/commands/driver'
+import { register as browser } from '@/commands/browser'
+import { register as take } from '@/commands/take'
 import { register as feedback } from '@/commands/feedback'
 import { register as transcripts } from '@/commands/transcripts'
 import { register as tasks } from '@/commands/tasks'
@@ -78,6 +80,8 @@ capture(program)
 serve(program)
 inventory(program)
 driver(program)
+browser(program)
+take(program)
 feedback(program)
 transcripts(program)
 tasks(program)

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/labels.ts

@@ -14,9 +14,10 @@ import {
 } from '@/labels/density'
 import { resolveScanInput } from '@/labels/event'
 import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
-import { MAP_REL } from '@/labels/map'
+import { MAP_REL, readLabelMap } from '@/labels/map'
 import { isReleasePullRequest, scanPhaseLabels } from '@/labels/phase'
 import { checkSections } from '@/labels/sections'
+import { missingLabels } from '@/labels/sync'
 import { BAN_SETS } from '@/markdown/bans'
 import { bodyLines, scanBans } from '@/markdown/scan'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
@@ -33,6 +34,12 @@ interface ApplyOptions extends AuditOptions {
 
 type ApplyRefusal = 'bad-number' | 'no-branch' | 'gh-failed' | 'head-mismatch'
 
+interface SyncOptions {
+  readonly root?: string
+  readonly check?: boolean
+  readonly json?: boolean
+}
+
 const GH_TIMEOUT_MS = 30_000
 
 interface ScanOptions {
@@ -187,6 +194,48 @@ export function register(program: Command): void {
       process.exitCode = await runApply(number, opts)
     })
 
+  labels
+    .command('sync')
+    .description(
+      'Create on the remote each label the map names that it lacks, never editing or deleting one',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--check', 'Report the labels missing and write nothing')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        `Reads the label names under [domains] in ${MAP_REL}, reads the remote's`,
+        'labels over REST, and creates each one the remote lacks. A label already',
+        'on the remote is left as it is, and one the map does not name is never',
+        'touched. A project declaring no map creates nothing and exits 0.',
+        '',
+        'Run it once after installing a map and again after adding a row, so',
+        '`canon labels apply` finds every label it earns.',
+        '',
+        'Record: labels, present, created, missing, failed',
+        '',
+        'Exit codes:',
+        '  0  the remote carries every label the map names after the run',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '  2  labels are still missing, being any under --check, or a failed',
+        '     create otherwise',
+        '',
+        'Reasons:',
+        '  gh-failed  the remote labels could not be read, so nothing was written',
+        '',
+        'Examples:',
+        '  canon labels sync',
+        '  canon labels sync --check --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SyncOptions) => {
+      process.exitCode = await runSync(opts)
+    })
+
   labels
     .command('scan')
     .description(
@@ -544,9 +593,7 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   }
 
   for (const label of diff.missingOnRemote) {
-    logWarn(
-      `${label} is not on the remote. Create it with: gh label create ${label}`,
-    )
+    logWarn(`${label} is not on the remote. Create it with: canon labels sync`)
   }
   for (const label of failed) logWarn(`Label apply failed: ${label}`)
 
@@ -577,6 +624,107 @@ async function runApply(number: string, opts: ApplyOptions): Promise<number> {
   return owed.length === 0 ? 0 : 2
 }
 
+async function runSync(opts: SyncOptions): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
+
+  intro('canon labels sync')
+
+  const map = readLabelMap(root)
+
+  if (map.kind === 'refused' && map.reason === 'no-map') {
+    logStep('Labels')
+    logInfo(REFUSALS['no-map'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          reason: 'no-map',
+          labels: [],
+          present: [],
+          created: [],
+          missing: [],
+          failed: [],
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const refuse = (reason: LabelAuditRefusal | 'gh-failed'): number => {
+    const message =
+      reason === 'gh-failed'
+        ? 'gh could not read the remote labels, so nothing was written.'
+        : REFUSALS[reason]
+    logStep('Refused')
+    logWarn(message)
+    outro()
+    if (emitJson) {
+      process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+    }
+    return 1
+  }
+
+  if (map.kind === 'refused') return refuse(map.reason)
+
+  const remoteRaw = await gh(root, [
+    'api',
+    '--paginate',
+    'repos/{owner}/{repo}/labels',
+    '--jq',
+    '.[].name',
+  ])
+  if (remoteRaw === null) return refuse('gh-failed')
+
+  const labels = map.domains.map((row) => row.label)
+  const present = nonEmptyLines(remoteRaw)
+  const toCreate = missingLabels(labels, present)
+
+  const created: string[] = []
+  const failed: string[] = []
+
+  if (!isCheck) {
+    for (const label of toCreate) {
+      const wrote = await gh(root, [
+        'api',
+        '-X',
+        'POST',
+        'repos/{owner}/{repo}/labels',
+        '-f',
+        `name=${label}`,
+        '--silent',
+      ])
+      if (wrote === null) failed.push(label)
+      else created.push(label)
+    }
+  }
+
+  const missing = toCreate.filter((label) => !created.includes(label))
+
+  logStep('Labels')
+  logInfo(labels.join(', '))
+
+  if (isCheck) {
+    logStep(missing.length === 0 ? 'Nothing missing' : 'Missing')
+    for (const label of missing) logWarn(label)
+  } else {
+    logStep('Created')
+    logInfo(created.length === 0 ? 'no label was created' : created.join(', '))
+  }
+  for (const label of failed) logWarn(`Label create failed: ${label}`)
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ labels, present, created, missing, failed })}\n`,
+    )
+  }
+
+  return missing.length === 0 ? 0 : 2
+}
+
 /**
  * Reads `--closes` as the issues the body must close. Undefined when the flag
  * is absent, which skips the check, and a message when the value is neither