@erclx/canon 4.4.0 → 4.6.0

package/src/driver/steps.ts

@@ -0,0 +1,266 @@
+import type { Page } from 'playwright-core'
+import {
+  type ViewportSpec,
+  type ViewportRefusal,
+  resolveViewports,
+} from '@/driver/probes/viewport'
+
+/**
+ * The interaction vocabulary a caller writes a run in, and the runner that
+ * performs one step of it.
+ *
+ * Adapted from `@/demo/drive`'s `runStep` with the pointer travel, the video
+ * context, and the caption bar dropped. Driving for a recording and driving for
+ * a measurement want opposite things from the same actions: a recording pays
+ * for visible motion between two points, and a measurement wants the page in
+ * the next state as directly as the engine can put it there, since every
+ * millisecond of travel is a millisecond a probe is not reading.
+ */
+
+/** How long a transition is given to finish before anything measures the result. */
+const SETTLE_MS = 250
+
+/**
+ * The probes a step can ask for. A fixed catalog rather than the pluggable
+ * subject system `@/inventory/subjects` carries, because every lesson behind
+ * these was a probe running at the wrong moment or trusting the wrong signal,
+ * rather than a probe a project needed to author for itself.
+ */
+export const PROBE_NAMES = [
+  'focus',
+  'details',
+  'diagram-geometry',
+  'diagram-strokes',
+] as const
+
+export type ProbeName = (typeof PROBE_NAMES)[number]
+
+/**
+ * One thing a probe measured and judged wrong. The step and the viewport are
+ * filled in by the orchestrator rather than by the probe, since a probe runs
+ * with no knowledge of which pass it is on and a finding is unreadable without
+ * both. A `measured` row carries what a reader needs to check the judgment
+ * without rerunning the probe.
+ */
+export interface Finding {
+  readonly probe: ProbeName
+  readonly selector: string
+  readonly detail: string
+  readonly measured: string
+}
+
+/** A finding once the run has said where it happened. */
+export interface PlacedFinding extends Finding {
+  readonly step: string
+  readonly viewport: string
+}
+
+interface StepCommon {
+  /** What the step did, carried onto every finding it produced. */
+  readonly name: string
+  /** Overrides the run-level list for this step alone. */
+  readonly probes?: readonly ProbeName[]
+}
+
+export type DriverStep = StepCommon &
+  (
+    | { readonly kind: 'click'; readonly target: string }
+    | { readonly kind: 'scroll'; readonly target: string }
+    | { readonly kind: 'fill'; readonly target: string; readonly text: string }
+    | { readonly kind: 'tab'; readonly count: number }
+    | { readonly kind: 'wait'; readonly ms: number }
+  )
+
+export interface DriverPlan {
+  /** Runs after every step that names no list of its own. */
+  readonly probes: readonly ProbeName[]
+  readonly viewports: readonly {
+    readonly width: number
+    readonly height: number
+  }[]
+  readonly steps: readonly DriverStep[]
+}
+
+export type PlanRefusal =
+  | 'unreadable-plan'
+  | 'no-steps'
+  | 'no-probes'
+  | 'unknown-probe'
+  | 'bad-step'
+  | ViewportRefusal
+
+export type PlanRead =
+  | { readonly kind: 'read'; readonly plan: DriverPlan }
+  | {
+      readonly kind: 'refused'
+      readonly reason: PlanRefusal
+      readonly detail: string
+    }
+
+function refused(reason: PlanRefusal, detail: string): PlanRead {
+  return { kind: 'refused', reason, detail }
+}
+
+/**
+ * Reads a run out of a JSON document. A file rather than a config key at the
+ * project root, and JSON rather than the TOML `canon inventory` declares its
+ * routes in, because a route catalog is state a project holds and an
+ * interaction sequence is a script written for one question.
+ */
+export function readDriverPlan(source: string): PlanRead {
+  let document: unknown
+  try {
+    document = JSON.parse(source)
+  } catch (error) {
+    return refused(
+      'unreadable-plan',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+
+  if (typeof document !== 'object' || document === null) {
+    return refused('unreadable-plan', 'the document is not an object')
+  }
+
+  const record = document as Record<string, unknown>
+
+  const viewports = resolveViewports(
+    record.viewport as ViewportSpec | undefined,
+  )
+  if (viewports.kind === 'refused') {
+    return refused(viewports.reason, viewports.detail)
+  }
+
+  const probes = readProbeList(record.probes)
+  if (typeof probes === 'string') return refused('unknown-probe', probes)
+  if (probes.length === 0) {
+    return refused(
+      'no-probes',
+      'probes names no probe, so every step would run and measure nothing',
+    )
+  }
+
+  if (!Array.isArray(record.steps) || record.steps.length === 0) {
+    return refused('no-steps', 'steps carries no entry, so nothing is driven')
+  }
+
+  const steps: DriverStep[] = []
+  for (const [index, entry] of record.steps.entries()) {
+    const step = readStep(entry, index)
+    if (typeof step === 'string') return refused('bad-step', step)
+    if (step.probes) {
+      const named = readProbeList(step.probes)
+      if (typeof named === 'string') return refused('unknown-probe', named)
+      // Refused for the same reason the run-level list is. An empty list here
+      // silently runs the step and measures nothing, and a pass reporting zero
+      // findings is indistinguishable from one that looked.
+      if (named.length === 0) {
+        return refused(
+          'no-probes',
+          `${step.name} names an empty probe list, so the step would run and measure nothing`,
+        )
+      }
+    }
+    steps.push(step)
+  }
+
+  return {
+    kind: 'read',
+    plan: { probes, viewports: viewports.viewports, steps },
+  }
+}
+
+/** Returns the parsed list, or the message naming what failed. */
+function readProbeList(value: unknown): ProbeName[] | string {
+  if (value === undefined) return [...PROBE_NAMES]
+  if (!Array.isArray(value)) return 'probes is not a list'
+
+  const names: ProbeName[] = []
+  for (const entry of value) {
+    if (!isProbeName(entry)) {
+      return `no probe named ${String(entry)}. This build ships: ${PROBE_NAMES.join(', ')}.`
+    }
+    names.push(entry)
+  }
+  return names
+}
+
+function isProbeName(value: unknown): value is ProbeName {
+  return typeof value === 'string' && PROBE_NAMES.includes(value as ProbeName)
+}
+
+/** Returns the parsed step, or the message naming what failed. */
+function readStep(entry: unknown, index: number): DriverStep | string {
+  const at = `step ${index + 1}`
+  if (typeof entry !== 'object' || entry === null)
+    return `${at} is not an object`
+
+  const step = entry as Record<string, unknown>
+  const name = typeof step.name === 'string' ? step.name : undefined
+  if (!name) return `${at} carries no name, and a finding is attributed by it`
+
+  const probes = step.probes as readonly ProbeName[] | undefined
+  const common = { name, ...(probes ? { probes } : {}) }
+  const target = typeof step.target === 'string' ? step.target : undefined
+
+  switch (step.kind) {
+    case 'click':
+      if (!target) return `${at} is a click with no target`
+      return { ...common, kind: 'click', target }
+    case 'scroll':
+      if (!target) return `${at} is a scroll with no target`
+      return { ...common, kind: 'scroll', target }
+    case 'fill':
+      if (!target) return `${at} is a fill with no target`
+      if (typeof step.text !== 'string') return `${at} is a fill with no text`
+      return { ...common, kind: 'fill', target, text: step.text }
+    case 'tab':
+      return {
+        ...common,
+        kind: 'tab',
+        count: typeof step.count === 'number' ? step.count : 1,
+      }
+    case 'wait':
+      if (typeof step.ms !== 'number') return `${at} is a wait with no ms`
+      return { ...common, kind: 'wait', ms: step.ms }
+    default:
+      return `${at} names kind ${String(step.kind)}, which is not click, scroll, fill, tab, or wait`
+  }
+}
+
+/** The probes this step asks for, which is the run's list unless it names one. */
+export function stepProbes(
+  plan: DriverPlan,
+  step: DriverStep,
+): readonly ProbeName[] {
+  return step.probes ?? plan.probes
+}
+
+/**
+ * Performs one step and lets whatever it started settle. The settle is the
+ * step's rather than each probe's, because a transition runs once and every
+ * probe after it would otherwise pay for the same wait again.
+ */
+export async function runStep(page: Page, step: DriverStep): Promise<void> {
+  switch (step.kind) {
+    case 'click':
+      await page.locator(step.target).first().click()
+      break
+    case 'scroll':
+      await page.locator(step.target).first().scrollIntoViewIfNeeded()
+      break
+    case 'fill':
+      await page.locator(step.target).first().fill(step.text)
+      break
+    case 'tab':
+      for (let press = 0; press < step.count; press += 1) {
+        await page.keyboard.press('Tab')
+      }
+      break
+    case 'wait':
+      await page.waitForTimeout(step.ms)
+      return
+  }
+
+  await page.waitForTimeout(SETTLE_MS)
+}

package/src/gate/measures.ts

@@ -97,7 +97,7 @@ export const SANDBOX_UNDECLARED_CEILING = 47
  * rather than derived, because this stage only ever names the file in a remedy
  * a reader has to be able to open, and `canon audits run` owns writing it.
  */
-export const AUDITS_BASELINE = '.claude/audits/baseline.json'
+export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
 export const HERO_STAMP_FAILURE =
   'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html and commit all three files together.'

package/src/intake/folder.ts

@@ -9,6 +9,7 @@ import {
   readItems,
   writeAnswerLine,
 } from '@/intake/items'
+import { recordDir } from '@/record-root'
 
 export const INTAKE_REFUSALS = [
   'no-intake',
@@ -80,7 +81,7 @@ function refuse(
 }
 
 export function intakeDir(root: string): string {
-  return join(root, '.claude', 'intake')
+  return recordDir(root, 'intake')
 }
 
 /**

package/src/inventory/walk.ts

@@ -1,6 +1,10 @@
 import { chromium } from 'playwright-core'
 import type { Browser } from 'playwright-core'
-import { isBrowserMissing } from '@/browser/engine'
+import {
+  enterKeyboardModality,
+  isBrowserMissing,
+  isServerUnreachable,
+} from '@/browser/engine'
 import { routeUrl } from '@/inventory/config'
 import type { Reading } from '@/inventory/group'
 import type { Subject } from '@/inventory/subjects'
@@ -61,19 +65,6 @@ function failed(reason: WalkRefusal, error: unknown): WalkResult {
   }
 }
 
-/**
- * Separates a server nobody started from a page that failed for its own
- * reasons. The first is the precondition this command cannot create, and
- * reporting it as an empty listing would say the site gives no answers when
- * nothing was ever asked.
- */
-function isServerUnreachable(error: unknown): boolean {
-  const text = error instanceof Error ? error.message : String(error)
-  return /ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION_RESET|ERR_EMPTY_RESPONSE/i.test(
-    text,
-  )
-}
-
 export async function walk(options: WalkOptions): Promise<WalkResult> {
   const started = Date.now()
 
@@ -98,10 +89,7 @@ export async function walk(options: WalkOptions): Promise<WalkResult> {
         waitUntil: 'domcontentloaded',
       })
 
-      // Puts the page in keyboard modality before anything is focused, because
-      // a `:focus-visible` ring is the treatment a pointer never reveals and
-      // programmatic focus alone does not match it.
-      await page.keyboard.press('Tab')
+      await enterKeyboardModality(page)
 
       const rows = await page.evaluate(options.subject.read, options.query)
       for (const row of rows) readings.push({ route, ...row })

package/src/record-root.ts

@@ -0,0 +1,134 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The roots a session record folder is read at, in precedence order.
+ *
+ * `.canon/` wins because a tree that carries it has been migrated, and reading
+ * `.claude/` there would answer from the copy the move left behind. A tree that
+ * carries neither is every tree today, which is what keeps this branch a no-op
+ * until the move lands.
+ *
+ * The shape is `readStamp`'s: order the spellings, take the first that exists,
+ * and stand the creation default in when none does.
+ */
+export const RECORD_ROOTS = ['.canon', '.claude'] as const
+
+export type RecordRoot = (typeof RECORD_ROOTS)[number]
+
+/**
+ * The root a record folder is created at.
+ *
+ * It disagrees with the read precedence above on purpose, and the disagreement
+ * is the whole of this branch. Creating under `.canon/` before the move would
+ * write records to a root whose ignore line may not have reached a target yet,
+ * and it would split one project's records across two roots with no verb able
+ * to reconcile them. The move flips this line and nothing else.
+ */
+export const CREATION_ROOT: RecordRoot = '.claude'
+
+/**
+ * The deletable scratch folder, named at the spelling `.claude/` gives it.
+ *
+ * It is the one folder whose name differs by root. Inside a dotted root the
+ * leading dot hides nothing already hidden and costs a bare `ls` that omits the
+ * folder, so the move drops it. Every other record folder keeps its name,
+ * `.records.git` included, where the dot marks the mechanism apart from a
+ * payload rather than hiding it.
+ */
+export const SCRATCH = '.tmp'
+
+/** The scratch folder's name under `.canon/`. */
+const CANON_SCRATCH = 'tmp'
+
+/** How a root spells a folder name. Only the scratch folder differs. */
+function spell(root: RecordRoot, folder: string): string {
+  return root === '.canon' && folder === SCRATCH ? CANON_SCRATCH : folder
+}
+
+/**
+ * The root a folder resolves at: the first that carries it, and the creation
+ * default when neither does.
+ *
+ * Presence is read on the record folder itself rather than on the full path, so
+ * an archive or a payload that does not exist yet still resolves beside the
+ * records it belongs to rather than at the creation default.
+ */
+function rootOf(root: string, folder: string): RecordRoot {
+  return (
+    RECORD_ROOTS.find((candidate) =>
+      existsSync(join(root, candidate, spell(candidate, folder))),
+    ) ?? CREATION_ROOT
+  )
+}
+
+/**
+ * Where a record folder is read.
+ *
+ * `folder` is the record folder itself and `rest` is whatever sits inside it,
+ * so a caller spells no root and no folder-name variant of its own. A caller
+ * that spells `.claude` by hand is the one thing the move has to find, and one
+ * that calls this is one the move never has to open again.
+ */
+export function recordDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  const at = rootOf(root, folder)
+
+  return join(root, at, spell(at, folder), ...rest)
+}
+
+/**
+ * Every root a record folder would be read at, in precedence order, whether or
+ * not it is on disk.
+ *
+ * Containment tests take this rather than `recordDir`, since a path written
+ * against the root a tree no longer uses is still a path into that folder and
+ * reading it as outside would report a shipped plan as still live.
+ */
+export function recordDirs(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string[] {
+  return RECORD_ROOTS.map((candidate) =>
+    join(root, candidate, spell(candidate, folder), ...rest),
+  )
+}
+
+/** Where a record folder is created, which is the creation default always. */
+export function creationDir(
+  root: string,
+  folder: string,
+  ...rest: string[]
+): string {
+  return join(root, CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+}
+
+/**
+ * The creation destination relative to the project root, which is the form a
+ * message displays and an option default carries.
+ */
+export function creationRel(folder: string, ...rest: string[]): string {
+  return join(CREATION_ROOT, spell(CREATION_ROOT, folder), ...rest)
+}
+
+/**
+ * The record root itself, for a caller whose subject is the root rather than a
+ * folder inside it.
+ *
+ * A half-migrated tree resolves here on the root that exists rather than on the
+ * folders under it, which is what makes the backup history and its work tree
+ * one answer. Splitting them would let a push resolve a history at one root and
+ * stage a work tree at the other, which stages the deletion of every folder the
+ * move relocated.
+ */
+export function recordRoot(root: string): string {
+  return join(
+    root,
+    RECORD_ROOTS.find((candidate) => existsSync(join(root, candidate))) ??
+      CREATION_ROOT,
+  )
+}

package/src/records/backup.ts

@@ -1,16 +1,18 @@
 import { existsSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
+import { recordRoot } from '@/record-root'
 
 /**
- * The folders a backup carries, relative to `.claude/`. Most of them are the
- * `# Claude` group the claude manifest ships, minus three: `.claude/.tmp`,
- * which is defined as deletable without loss, `.claude/worktrees/`, whose
- * contents belong to the enclosing repository already, and
- * `.claude/.records.git/`, which is the history the rest are pushed into. The
- * list is spelled out rather than read off that group so adding an ignore entry
- * cannot silently enlarge the payload.
+ * The folders a backup carries, relative to the record root `workTree` resolves
+ * rather than to `.claude/` specifically, since the same nine names sit under
+ * whichever root a tree holds. Most of them are the `# Claude` group the claude
+ * manifest ships, minus three: the scratch folder, which is defined as deletable
+ * without loss, `worktrees/`, whose contents belong to the enclosing repository
+ * already, and `.records.git/`, which is the history the rest are pushed into.
+ * The list is spelled out rather than read off that group so adding an ignore
+ * entry cannot silently enlarge the payload.
  *
  * `diagrams` is the one name the manifest group does not carry, so a target
  * tracks it where this repository ignores it. That is the second reason to
@@ -65,10 +67,25 @@ const RETIRED_FOLDERS = [
   'task-archive',
 ] as const
 
-/** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
-const RECORDS_GIT_DIR = join('.claude', '.records.git')
+/** The history directory's own name, which keeps its dot at either record root. */
+const RECORDS_GIT_NAME = '.records.git'
 
-const WORK_TREE = '.claude'
+/**
+ * The tree a backup stages, which is the record root itself.
+ *
+ * It resolves the root rather than each folder under it, so the history and the
+ * work tree are one answer. Resolving them apart would let a half-migrated tree
+ * open a history at one root and stage a work tree at the other, which stages
+ * the deletion of every folder the move relocated and pushes it.
+ */
+function workTree(root: string): string {
+  return recordRoot(root)
+}
+
+/** Holds the records history beside the folders it tracks, ignored by the enclosing repository. */
+function recordsGitDir(root: string): string {
+  return join(workTree(root), RECORDS_GIT_NAME)
+}
 
 /** Both directions name the branch, so a machine whose `init.defaultBranch` differs still lands on it. */
 const RECORDS_BRANCH = 'main'
@@ -150,11 +167,11 @@ interface GitResult {
  * work tree.
  */
 async function records(root: string, args: string[]): Promise<GitResult> {
-  const gitDir = resolve(root, RECORDS_GIT_DIR)
-  const workTree = resolve(root, WORK_TREE)
+  const gitDir = resolve(recordsGitDir(root))
+  const tree = resolve(workTree(root))
 
   const result =
-    await $`git -C ${workTree} --git-dir=${gitDir} --work-tree=${workTree} ${args}`
+    await $`git -C ${tree} --git-dir=${gitDir} --work-tree=${tree} ${args}`
       .env(gitEnv())
       .quiet()
       .nothrow()
@@ -237,13 +254,15 @@ async function enclosingRemoteUrls(
  * cannot be read is what keeps a failed comparison from reading as a pass.
  */
 async function resolveRemote(root: string): Promise<string | BackupRefused> {
-  if (!existsSync(join(root, RECORDS_GIT_DIR))) {
+  const gitDir = recordsGitDir(root)
+
+  if (!existsSync(gitDir)) {
     return refuse(
       'no-repository',
       [
-        `No records history at ${RECORDS_GIT_DIR}. Create it once, against a private repository:`,
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} init`,
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+        `No records history at ${relative(root, gitDir)}. Create it once, against a private repository:`,
+        `  git --git-dir=${gitDir} init`,
+        `  git --git-dir=${gitDir} remote add origin <private-repo-url>`,
       ].join('\n'),
     )
   }
@@ -254,7 +273,7 @@ async function resolveRemote(root: string): Promise<string | BackupRefused> {
       'no-remote',
       [
         'The records history has no origin. Point it at a private repository:',
-        `  git --git-dir=${join(root, RECORDS_GIT_DIR)} remote add origin <private-repo-url>`,
+        `  git --git-dir=${gitDir} remote add origin <private-repo-url>`,
       ].join('\n'),
     )
   }
@@ -299,8 +318,7 @@ async function scopedFolders(root: string): Promise<string[]> {
   )
 
   return [...BACKED_FOLDERS, ...RETIRED_FOLDERS].filter(
-    (folder) =>
-      existsSync(join(root, WORK_TREE, folder)) || indexed.has(folder),
+    (folder) => existsSync(join(workTree(root), folder)) || indexed.has(folder),
   )
 }
 
@@ -311,7 +329,7 @@ function topSegment(path: string): string {
 /** What a report names, which is the folders a reader can go and open. */
 function presentFolders(root: string): string[] {
   return BACKED_FOLDERS.filter((folder) =>
-    existsSync(join(root, WORK_TREE, folder)),
+    existsSync(join(workTree(root), folder)),
   )
 }
 

package/src/records/size.ts

@@ -1,12 +1,13 @@
 import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
+import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
 import { BACKED_FOLDERS } from '@/records/backup'
 
 /**
- * The folders a size reading covers, relative to `.claude/`.
+ * The folders a size reading covers, named at the record root they sit under.
  *
- * It is the backed set plus `.tmp`, which a backup skips because it is
+ * It is the backed set plus the scratch folder, which a backup skips because it is
  * deletable without loss and a reading covers because deletable is not the same
  * as empty: the routing handoffs and the memory archive both sit there and both
  * accumulate. `.records.git` stays out because it is the backup history rather
@@ -14,7 +15,7 @@ import { BACKED_FOLDERS } from '@/records/backup'
  * checkout of the enclosing repository with its own removal verb, and one of
  * them outweighs every record folder combined.
  */
-export const SIZED_FOLDERS = [...BACKED_FOLDERS, '.tmp'] as const
+export const SIZED_FOLDERS = [...BACKED_FOLDERS, SCRATCH] as const
 
 /**
  * The windows a reading reports, in days.
@@ -34,7 +35,7 @@ export interface WindowCount {
 }
 
 export interface FolderSize {
-  /** Relative to `.claude/`, which is the name a reader opens. */
+  /** Relative to the record root, which is the name a reader opens. */
   readonly folder: string
   readonly present: boolean
   readonly files: number
@@ -170,7 +171,7 @@ async function measure(
   folder: string,
   now: number,
 ): Promise<FolderSize> {
-  const path = join(root, '.claude', folder)
+  const path = recordDir(root, folder)
   const empty = GROWTH_WINDOWS.map((days) => ({ days, files: 0 }))
 
   if (!existsSync(path)) {
@@ -212,11 +213,15 @@ export async function sizeRecords(
   root: string,
   now: number = Date.now(),
 ): Promise<SizeOutcome> {
-  if (!existsSync(join(root, '.claude'))) {
+  // Either root answers, so a migrated tree is read rather than refused. The
+  // roots are tested rather than the folders under them, since a project that
+  // holds the root and no records yet is empty rather than absent and the
+  // per-folder `present` flags already say which of the ten it carries.
+  if (!RECORD_ROOTS.some((name) => existsSync(join(root, name)))) {
     return {
       ok: false,
       reason: 'no-folder',
-      message: `No .claude directory at ${root}, so there are no record folders to read.`,
+      message: `No ${RECORD_ROOTS.join(' or ')} directory at ${root}, so there are no record folders to read.`,
     }
   }