@erclx/canon 4.4.0 → 4.6.0

package/src/commands/driver.ts

@@ -0,0 +1,266 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import type { DriverRefusal } from '@/driver/drive'
+import { describeViewport } from '@/driver/probes/viewport'
+import { PROBE_NAMES, readDriverPlan } from '@/driver/steps'
+import type { PlanRefusal } from '@/driver/steps'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadDriver`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Driver = typeof import('@/driver/drive')
+
+interface RunOptions {
+  readonly json?: boolean
+}
+
+/**
+ * Spelled here rather than through `plural`, which appends a bare `s` and gets
+ * the plural of this noun wrong.
+ */
+function passes(count: number): string {
+  return `${count} ${count === 1 ? 'pass' : 'passes'}`
+}
+
+/** What a reader does about each way the run document produced no drive. */
+const PLAN_REFUSALS: Record<PlanRefusal, string> = {
+  'unreadable-plan':
+    'The run file is not valid JSON, so no step could be read.',
+  'no-steps': 'The run names no step, so there is nothing to drive.',
+  'no-probes': 'The run names no probe, so every step would measure nothing.',
+  'unknown-probe': 'The run names a probe this build does not ship.',
+  'bad-step': 'A step is missing something the driver needs to perform it.',
+  'no-viewport': 'The run declares no viewport to render at.',
+  'no-width': 'The run declares no viewport width.',
+  'no-heights':
+    'The run names no viewport height, and this command defaults none.',
+}
+
+const DRIVE_REFUSALS: Record<DriverRefusal, string> = {
+  'browser-missing': 'The browser binary is not installed in this project.',
+  'server-unreachable': 'Nothing answered at the URL, so no state was reached.',
+  'drive-failed': 'The drive failed against a reachable page.',
+}
+
+export function register(program: Command): void {
+  program
+    .command('drive')
+    .description(
+      'Walk a page through named interactions and measure each state',
+    )
+    .argument('<url>', 'Address to drive')
+    .argument(
+      '<run>',
+      'JSON file naming the viewports, the probes, and the steps',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A render answers about a page as it loads. Every defect that exists',
+        'only after a menu opens, an answer is chosen, or the page scrolls is',
+        'invisible to one, which is the axis this adds. Probes run after each',
+        'step and never on arrival, so a run reaches the load state by opening',
+        'with a wait step of its own. Write one wherever canon capture does not',
+        'run, since nothing else there measures the page as it first painted.',
+        '',
+        'The run file carries the viewport, the default probe list, and the',
+        'steps. A step names its own probes to override the default. Viewport',
+        'heights are never defaulted: the heights a defect hides at are a',
+        'property of the layout rather than of this command.',
+        '',
+        '  {',
+        '    "viewport": { "width": 1440, "heights": [900, 1200, 1500] },',
+        '    "probes": ["focus", "details"],',
+        '    "steps": [',
+        '      { "name": "open the menu", "kind": "click", "target": "#menu" },',
+        '      { "name": "reach the diagram", "kind": "scroll", "target": "figure",',
+        '        "probes": ["diagram-geometry", "diagram-strokes"] }',
+        '    ]',
+        '  }',
+        '',
+        'It reports findings and never gates. Every probe here carries a class',
+        'of false finding a throwaway version already produced, so a run that',
+        'ends the build on its own reading is a claim this catalog has not',
+        'earned. Branch on the JSON record instead.',
+        '',
+        'Needs a reachable page and a browser binary. Install the browser with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Probes:',
+        ...PROBE_NAMES.map((name) => `  ${name}`),
+        '',
+        'Step kinds:',
+        '  click <target>   press the first element the selector matches',
+        '  scroll <target>  bring the first match into view',
+        '  fill <target>    type text into the first match',
+        '  tab [count]      advance keyboard focus',
+        '  wait <ms>        hold, for a state the page reaches on its own',
+        '',
+        'Exit codes:',
+        '  0  the drive completed, with its findings reported',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon drive http://localhost:4173 run.json',
+        '  canon drive http://localhost:4173 run.json --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (url: string, run: string, opts: RunOptions) => {
+      process.exitCode = await runDriver(url, run, opts)
+    })
+}
+
+async function runDriver(
+  url: string,
+  runPath: string,
+  opts: RunOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const path = resolve(runPath)
+
+  intro(`canon drive ${url}`)
+
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    return refuse(
+      emitJson,
+      url,
+      'no-run-file',
+      `No run file at ${path}. ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+
+  const read = readDriverPlan(source)
+  if (read.kind === 'refused') {
+    return refuse(
+      emitJson,
+      url,
+      read.reason,
+      `${PLAN_REFUSALS[read.reason]} ${read.detail}`,
+    )
+  }
+
+  const { plan } = read
+
+  logStep('Scope')
+  logInfo(
+    `${plural(plan.steps.length, 'step')} at ${plan.viewports.map(describeViewport).join(', ')}, measuring ${plan.probes.join(', ')}`,
+  )
+
+  const driver = await loadDriver()
+  if (!driver) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(emitJson, {
+      url,
+      run: path,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  const result = await driver.drive({ url, plan })
+
+  if (result.status === 'failed') {
+    logStep('Refused')
+    logWarn(DRIVE_REFUSALS[result.reason])
+    if (result.reason === 'server-unreachable') {
+      logWarn(`Start whatever serves ${url}, then run this again.`)
+    }
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    logWarn(result.message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, {
+      url,
+      run: path,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  logStep('Passes')
+  for (const pass of result.passes) {
+    logInfo(
+      `${pass.viewport}  ${pass.step}  ${plural(pass.probes, 'probe')}  ${plural(pass.findings, 'finding')}`,
+    )
+  }
+
+  logStep('Findings')
+  if (result.findings.length === 0) {
+    logInfo(
+      `nothing across ${passes(result.passes.length)}, which is a reading rather than a pass mark`,
+    )
+  } else {
+    logInfo(
+      `${plural(result.findings.length, 'finding')} across ${passes(result.passes.length)}`,
+    )
+    for (const finding of result.findings) {
+      logInfo(`  ${finding.probe}  ${finding.selector}`)
+      logInfo(`      ${finding.detail}`)
+      logInfo(`      after ${finding.step} at ${finding.viewport}`)
+      logInfo(`      ${finding.measured}`)
+    }
+  }
+  outro()
+
+  emit(emitJson, {
+    url,
+    run: path,
+    viewports: plan.viewports,
+    passes: result.passes,
+    findings: result.findings,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+/**
+ * Frames a refusal on stderr and puts the record on stdout, so an operator
+ * reading the terminal sees the reason rather than a command that appeared to
+ * do nothing.
+ */
+function refuse(
+  emitJson: boolean,
+  url: string,
+  reason: string,
+  message: string,
+): number {
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  emit(emitJson, { url, reason, message })
+  return 1
+}
+
+async function loadDriver(): Promise<Driver | undefined> {
+  try {
+    return await import('@/driver/drive')
+  } catch (error) {
+    if (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+function emit(json: boolean, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/commands/feedback.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import type { Command } from 'commander'
 import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { frameError, frameSuccess, palette } from '@/ui'
 
@@ -39,7 +40,10 @@ function isToolkitSource(): boolean {
  * single ignore entry and the single backed-folder entry it already had.
  */
 function writeLocal(body: string): string {
-  const relativeDir = join('.claude', 'review', 'feedback')
+  // Creation, so the destination is the creation default rather than the
+  // resolved read root. A toolkit checkout that has migrated its records already
+  // carries the folder and resolves the same path either way.
+  const relativeDir = creationRel('review', 'feedback')
   const reviewDir = join(PROJECT_ROOT, relativeDir)
   mkdirSync(reviewDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`

package/src/commands/gov.ts

@@ -9,6 +9,7 @@ import {
   scanCounts,
 } from '@/counts/scan'
 import { PROJECT_ROOT } from '@/project-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
 import { installRules, lookupRules } from '@/gov/install'
@@ -65,7 +66,7 @@ import {
   select,
 } from '@/ui'
 
-const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
+const PAYLOAD_REL = creationRel(SCRATCH, 'gov', 'rules.md')
 const RULES_REL = join('.claude', 'rules')
 
 interface InstallOptions {

package/src/commands/slides.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
+import { creationRel } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -16,7 +17,11 @@ export function register(program: Command): void {
     .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(
+      '-o, --out <path>',
+      'Output directory',
+      creationRel('review', 'slides'),
+    )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(
       '-m, --mirror <path>',

package/src/context/citations.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import { listRepositoryFiles } from '@/git-files'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
  * Suppresses citation checking for the source line carrying it.
@@ -76,21 +77,31 @@ export function isFixture(rel: string): boolean {
   return rel.split('/').some((segment) => FIXTURE_SEGMENTS.includes(segment))
 }
 
+/**
+ * Both record roots are spelled, so a citation into a folder that has moved is
+ * still resolved. A pattern fixed at one root matches nothing after the move and
+ * reports nothing, which is a stale reference passing the check that exists to
+ * find it rather than a check that fails.
+ */
 export function citationPattern(folders: readonly string[]): RegExp {
-  const names = folders.map((name) =>
-    name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
-  )
+  const names = folders.map((name) => escape(name))
+  const roots = RECORD_ROOTS.map((name) => escape(name))
+
   return new RegExp(
-    `\\.claude/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
+    `(?:${roots.join('|')})/(?:${names.join('|')})/[A-Za-z0-9._/-]+\\.md`,
     'g',
   )
 }
 
+function escape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
 /**
  * A backticked filename carrying no folder, the form a reference takes when it
  * names a sibling rather than a path.
  *
- * `citationPattern` spells the `.claude/` prefix and cannot see this shape at
+ * `citationPattern` spells a record-root prefix and cannot see this shape at
  * all, which is the reason the form rule exists. Widening that expression to
  * admit a bare name was the alternative and it puts one match in the position of
  * answering two questions, since a spelled path is a reference by construction

package/src/context/folders.ts

@@ -1,9 +1,10 @@
 import { existsSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+import { RECORD_ROOTS } from '@/record-root'
 
 /**
- * Folder names under `.claude/` audited by default.
+ * Folder names under a record root audited by default.
  *
  * A named list rather than the index-plus-entry contract read off disk, so a
  * generated tree satisfying that contract is never measured against a rule
@@ -12,8 +13,8 @@ import { INDEX_FILE, listIndexes } from '@/indexes/walk'
  * here.
  *
  * It doubles as the citation check's scope, since `citationPattern` spells only
- * these names. A `.claude/` folder left off the list is never resolved, so a
- * path into one goes stale silently rather than failing a push.
+ * these names. A folder left off the list is never resolved, so a path into one
+ * goes stale silently rather than failing a push.
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
@@ -21,8 +22,17 @@ export const DEFAULT_FOLDERS: readonly string[] = [
   'wireframes',
 ]
 
-/** The base every folder in the default list sits under. */
-const CLAUDE_BASE = '.claude'
+/**
+ * The bases every folder in the default list is looked for under, in the record
+ * roots' own precedence order.
+ *
+ * `diagrams` is the one name here that is a session record and moves with them,
+ * so the list has to carry the root it moves to. `context` and `wireframes` are
+ * tracked and stay, which leaves them resolvable at a root nothing will ever put
+ * them under. That costs one `existsSync` apiece and is cheaper than a per-name
+ * base map that would state the same split twice.
+ */
+const CLAUDE_BASES: readonly string[] = RECORD_ROOTS
 
 /** The project root, reached only by a name the caller asked for. */
 const ROOT_BASE = '.'
@@ -58,7 +68,7 @@ export interface AuditedFolder {
 }
 
 /**
- * Names the requested `.claude/` folders that actually exist, which is the
+ * Names the requested record-root folders that actually exist, which is the
  * citation check's scope.
  *
  * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
@@ -76,7 +86,7 @@ export function presentNames(folders: readonly AuditedFolder[]): string[] {
   return [
     ...new Set(
       folders
-        .filter((folder) => folder.base === CLAUDE_BASE)
+        .filter((folder) => CLAUDE_BASES.includes(folder.base))
         .map((folder) => folder.name),
     ),
   ]
@@ -157,7 +167,7 @@ export async function resolveFolders(
   names: readonly string[] = DEFAULT_FOLDERS,
   { canResolveAtRoot = false }: ResolveOptions = {},
 ): Promise<FolderResolution> {
-  const bases = canResolveAtRoot ? [CLAUDE_BASE, ROOT_BASE] : [CLAUDE_BASE]
+  const bases = canResolveAtRoot ? [...CLAUDE_BASES, ROOT_BASE] : CLAUDE_BASES
   const folders: AuditedFolder[] = []
   const missing: string[] = []
 

package/src/driver/drive.ts

@@ -0,0 +1,184 @@
+import { chromium } from 'playwright-core'
+import type { Browser, Page } from 'playwright-core'
+import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { probeDetails } from '@/driver/probes/details'
+import {
+  probeDiagramGeometry,
+  probeDiagramStrokes,
+} from '@/driver/probes/diagram'
+import { probeFocus } from '@/driver/probes/focus'
+import { describeViewport } from '@/driver/probes/viewport'
+import type { Viewport } from '@/driver/probes/viewport'
+import { runStep, stepProbes } from '@/driver/steps'
+import type {
+  DriverPlan,
+  Finding,
+  PlacedFinding,
+  ProbeName,
+} from '@/driver/steps'
+
+/**
+ * Walks a page through a caller's interaction sequence and measures each state
+ * it reaches. Every browser reference the driver adds lives here, and
+ * `src/commands/driver.ts` reaches it through a dynamic import so no other
+ * command resolves the engine at startup.
+ *
+ * Like `@/demo/drive` and `@/inventory/walk`, and unlike `@/capture/render`,
+ * this module ships. A command whose whole purpose is measuring someone else's
+ * page cannot stay toolkit-only, and nothing here reaches into `@/capture/`,
+ * which `files` in `package.json` excludes from the published package, so the
+ * two surfaces move independently.
+ *
+ * What separates it from `canon capture` is the axis it adds. A render answers
+ * about a page as it loads, and every defect that exists only after a menu
+ * opens, an answer is chosen, or the page scrolls is invisible to one. Probes
+ * therefore run after a step rather than on arrival, and a run reaches the load
+ * state by opening with a `wait` step of its own. That matters most where
+ * capture does not run, since it is toolkit-only and this command is then the
+ * only thing measuring the page at all.
+ */
+
+/** Each probe keyed by the name a caller writes in the run. */
+const PROBES: Record<ProbeName, (page: Page) => Promise<Finding[]>> = {
+  focus: probeFocus,
+  details: probeDetails,
+  'diagram-geometry': probeDiagramGeometry,
+  'diagram-strokes': probeDiagramStrokes,
+}
+
+export interface DriveOptions {
+  readonly url: string
+  readonly plan: DriverPlan
+}
+
+/** One step measured at one viewport, so a sweep reads as passes rather than a total. */
+export interface PassReading {
+  readonly viewport: string
+  readonly step: string
+  readonly probes: number
+  readonly findings: number
+}
+
+export type DriverRefusal =
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'drive-failed'
+
+export type DriverResult =
+  | {
+      readonly status: 'driven'
+      readonly findings: readonly PlacedFinding[]
+      readonly passes: readonly PassReading[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: DriverRefusal
+      readonly message: string
+    }
+
+function failed(reason: DriverRefusal, error: unknown): DriverResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+export async function drive(options: DriveOptions): Promise<DriverResult> {
+  const started = Date.now()
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'drive-failed',
+      error,
+    )
+  }
+
+  const findings: PlacedFinding[] = []
+  const passes: PassReading[] = []
+
+  try {
+    for (const viewport of options.plan.viewports) {
+      const pass = await driveViewport(browser, options, viewport)
+      findings.push(...pass.findings)
+      passes.push(...pass.passes)
+    }
+  } catch (error) {
+    return failed(
+      isServerUnreachable(error) ? 'server-unreachable' : 'drive-failed',
+      error,
+    )
+  } finally {
+    // Dropped rather than propagated, because a close that fails beside a drive
+    // that already failed would replace the refusal the caller is about to
+    // receive with a reason about teardown.
+    await browser.close().catch(() => undefined)
+  }
+
+  return {
+    status: 'driven',
+    findings,
+    passes,
+    durationMs: Date.now() - started,
+  }
+}
+
+/**
+ * One full pass of the sequence at one viewport, in a context of its own.
+ *
+ * A fresh context per height rather than a resize of the last one, because a
+ * step already run has left the page in a state the next height would inherit,
+ * and a sweep exists to ask the same question of each rather than to ask a
+ * later one of a page the earlier heights already drove.
+ */
+async function driveViewport(
+  browser: Browser,
+  options: DriveOptions,
+  viewport: Viewport,
+): Promise<{ findings: PlacedFinding[]; passes: PassReading[] }> {
+  const context = await browser.newContext({
+    viewport,
+    // Pointed the opposite way from `@/demo/drive`, which asks for the motion
+    // the interface was designed with. A measurement wants it suppressed, since
+    // geometry read mid-transition is a reading of neither state.
+    reducedMotion: 'reduce',
+  })
+
+  const findings: PlacedFinding[] = []
+  const passes: PassReading[] = []
+  const where = describeViewport(viewport)
+
+  try {
+    const page = await context.newPage()
+    await page.goto(options.url, { waitUntil: 'domcontentloaded' })
+
+    for (const step of options.plan.steps) {
+      await runStep(page, step)
+
+      const names = stepProbes(options.plan, step)
+      let count = 0
+      for (const name of names) {
+        const probe = PROBES[name]
+        for (const finding of await probe(page)) {
+          findings.push({ ...finding, step: step.name, viewport: where })
+          count += 1
+        }
+      }
+
+      passes.push({
+        viewport: where,
+        step: step.name,
+        probes: names.length,
+        findings: count,
+      })
+    }
+  } finally {
+    await context.close().catch(() => undefined)
+  }
+
+  return { findings, passes }
+}