@erclx/canon 5.64.0 → 5.66.0

package/src/pr/rest.ts

@@ -15,8 +15,16 @@ export interface RestPull {
   readonly number?: number
   readonly title?: string
   readonly body?: string | null
-  readonly head?: { readonly ref?: string; readonly sha?: string }
-  readonly base?: { readonly ref?: string }
+  readonly head?: {
+    readonly ref?: string
+    readonly sha?: string
+    /** Null when the fork the head lived in was deleted. */
+    readonly repo?: { readonly full_name?: string } | null
+  }
+  readonly base?: {
+    readonly ref?: string
+    readonly repo?: { readonly full_name?: string }
+  }
   readonly mergeable_state?: string
   readonly state?: string
   readonly draft?: boolean

package/src/sandbox/replay/expected.ts

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { StepResult } from '@/sandbox/replay/run'
+
+/** Sits in a snapshot's folder beside its `.fixture` files and never reaches the replay tree. */
+export const EXPECTED_FILE = 'expected.json'
+
+export interface StepExpectation {
+  readonly exit: number | null
+  readonly findings: number
+}
+
+/**
+ * A snapshot's recorded answer, keyed by step name. It pins the exit and the
+ * finding count rather than the finding lines, so rewording a warning moves
+ * nothing while a seed sync newly calls missing still drifts.
+ */
+export interface ReplayExpectation {
+  readonly steps: Readonly<Record<string, StepExpectation>>
+}
+
+const RECORD_HINT =
+  'run bun src/cli.ts sandbox replay --record if the change meant it'
+
+export function expectationOf(steps: readonly StepResult[]): ReplayExpectation {
+  return {
+    steps: Object.fromEntries(
+      steps.map((s) => [s.step, { exit: s.exit, findings: s.findings.length }]),
+    ),
+  }
+}
+
+function isStepExpectation(value: unknown): value is StepExpectation {
+  if (typeof value !== 'object' || value === null) return false
+  const { exit, findings } = value as Record<string, unknown>
+
+  return (
+    (exit === null || typeof exit === 'number') && typeof findings === 'number'
+  )
+}
+
+/**
+ * The expectation recorded in `dir`, or undefined when none is. Throws naming
+ * the file and the step when the file holds anything but the recorded shape.
+ */
+export function readExpectation(dir: string): ReplayExpectation | undefined {
+  const path = join(dir, EXPECTED_FILE)
+  if (!existsSync(path)) return undefined
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new Error(`${path} does not parse as JSON`)
+  }
+  const steps =
+    typeof parsed === 'object' && parsed !== null
+      ? (parsed as Record<string, unknown>).steps
+      : undefined
+  if (typeof steps !== 'object' || steps === null)
+    throw new Error(`${path} carries no steps object`)
+  for (const [name, value] of Object.entries(steps))
+    if (!isStepExpectation(value))
+      throw new Error(
+        `${path}: step ${name} needs an exit and a findings count`,
+      )
+
+  return { steps: steps as ReplayExpectation['steps'] }
+}
+
+/** Written the way oxfmt leaves JSON, so a recorded file never fails the format stage. */
+export function writeExpectation(
+  dir: string,
+  expectation: ReplayExpectation,
+): void {
+  writeFileSync(
+    join(dir, EXPECTED_FILE),
+    `${JSON.stringify(expectation, null, 2)}\n`,
+  )
+}
+
+function driftOf(
+  run: StepResult,
+  recorded: StepExpectation | undefined,
+): string | undefined {
+  if (recorded === undefined) return `no recorded answer, ${RECORD_HINT}`
+  if (run.exit !== recorded.exit)
+    return `exit ${run.exit}, recorded ${recorded.exit}`
+  if (run.findings.length !== recorded.findings)
+    return `${run.findings.length} findings, recorded ${recorded.findings}`
+
+  return undefined
+}
+
+/**
+ * Judges a snapshot's steps against its recorded answer. A step that already
+ * failed keeps its verdict, since a crash names more than a changed exit. A
+ * step either side lacks drifts, and with no expectation at all every step
+ * does, since a missing input read as a pass is what the replay exists to stop.
+ */
+export function judgeDrift(
+  steps: readonly StepResult[],
+  expectation: ReplayExpectation | undefined,
+): StepResult[] {
+  if (expectation === undefined)
+    return steps.map((s) =>
+      s.verdict === 'ok'
+        ? {
+            ...s,
+            verdict: 'drifted',
+            detail: `no ${EXPECTED_FILE} for this snapshot, run bun src/cli.ts sandbox replay --record`,
+          }
+        : s,
+    )
+
+  const judged = steps.map((s) => {
+    if (s.verdict !== 'ok') return s
+    const detail = driftOf(s, expectation.steps[s.step])
+
+    return detail === undefined
+      ? s
+      : { ...s, verdict: 'drifted' as const, detail }
+  })
+  const ran = new Set(steps.map((s) => s.step))
+  const dropped = Object.keys(expectation.steps)
+    .filter((name) => !ran.has(name))
+    .map((name): StepResult => ({
+      step: name,
+      argv: [],
+      exit: null,
+      verdict: 'drifted',
+      detail: `recorded but did not run, ${RECORD_HINT}`,
+      findings: [],
+    }))
+
+  return [...judged, ...dropped]
+}

package/src/sandbox/replay/run.ts

@@ -0,0 +1,348 @@
+import { spawnSync } from 'node:child_process'
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+} from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { gitEnv } from '@/git/env'
+import { EXPECTED_FILE } from '@/sandbox/replay/expected'
+import {
+  findingsOf,
+  judgeFormat,
+  judgeStep,
+  type ReplayVerdict,
+  type StepOutput,
+} from '@/sandbox/replay/verdict'
+import { FIXTURE_SUFFIX, listFixtureFiles } from '@/sandbox/scenario'
+
+export interface ReplaySource {
+  readonly name: string
+  readonly path: string
+  /**
+   * A snapshot is a folder of `.fixture` files with no history, committed
+   * fresh in the copy. A checkout is a consumer's real repository, copied
+   * whole with its history so its gitignored records come along.
+   */
+  readonly kind: 'snapshot' | 'checkout'
+}
+
+export interface ReplayContext {
+  /** The canon checkout whose CLI, formatter, and golden config the replay runs. */
+  readonly checkoutRoot: string
+  /** The folder each replay's temp tree is made under, outside every repository. */
+  readonly tempRoot: string
+}
+
+export interface StepResult {
+  readonly step: string
+  readonly argv: readonly string[]
+  readonly exit: number | null
+  readonly verdict: ReplayVerdict
+  readonly detail?: string
+  /** The `!` lines the step printed, reported whatever the verdict. */
+  readonly findings: readonly string[]
+}
+
+export interface ReplayResult {
+  readonly name: string
+  readonly kind: ReplaySource['kind']
+  readonly steps: readonly StepResult[]
+  /** Paths sync added or changed, relative to the tree, sorted. */
+  readonly written: readonly string[]
+}
+
+/**
+ * The sync, then the reads a consumer runs after one, each `--json` read a
+ * contract on its own stdout. The reads run on the unstaged result, which is
+ * the state a consumer's session meets before anyone commits the sync.
+ */
+const CLI_STEPS: readonly { step: string; args: readonly string[] }[] = [
+  { step: 'sync', args: ['sync', '.'] },
+  { step: 'sync --check', args: ['sync', '--check', '.', '--json'] },
+  { step: 'context audit', args: ['context', 'audit', '--json'] },
+  { step: 'markdown audit', args: ['markdown', 'audit', '--json'] },
+  { step: 'migrate status', args: ['migrate', 'status', '--json'] },
+]
+
+/** Each step took seconds on both consumers in the spike, so five minutes is a hang. */
+const STEP_TIMEOUT_MS = 300_000
+
+/**
+ * A checkout copy skips installs at any depth and the linked worktrees other
+ * sessions hold, neither of which a sync or a health read touches.
+ */
+function isCopied(rel: string): boolean {
+  return rel.split('/').at(-1) !== 'node_modules' && rel !== '.claude/worktrees'
+}
+
+/**
+ * Git's background maintenance creates and removes files such as
+ * `.git/objects/maintenance.lock` while a copy walks the checkout, and a file
+ * listed then gone throws ENOENT. A short bound covers every transient name
+ * git uses, where a filter on `*.lock` would cover one.
+ */
+const COPY_ATTEMPTS = 3
+
+export function copyCheckout(
+  source: ReplaySource,
+  tree: string,
+  copy: typeof cpSync = cpSync,
+): void {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      copy(source.path, tree, {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: (from) => isCopied(relative(source.path, from)),
+      })
+      return
+    } catch (error) {
+      const vanished = (error as NodeJS.ErrnoException).code === 'ENOENT'
+      if (!vanished || attempt === COPY_ATTEMPTS) throw error
+      rmSync(tree, { recursive: true, force: true })
+    }
+  }
+}
+
+/**
+ * Copies a source into `tree`. A snapshot's files lose their `.fixture`
+ * suffix and its recorded expectation stays behind, and a checkout copies whole rather than cloning, since a clone
+ * drops the gitignored `.canon/` records a consumer's health verbs read.
+ */
+export function copySource(source: ReplaySource, tree: string): void {
+  if (source.kind === 'checkout') {
+    copyCheckout(source, tree)
+    return
+  }
+
+  for (const file of listFixtureFiles(source.path)) {
+    if (relative(source.path, file) === EXPECTED_FILE) continue
+    if (!file.endsWith(FIXTURE_SUFFIX))
+      throw new Error(
+        `Snapshot file missing the ${FIXTURE_SUFFIX} suffix: ${file}`,
+      )
+    const target = join(
+      tree,
+      relative(source.path, file).slice(0, -FIXTURE_SUFFIX.length),
+    )
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(file, target)
+  }
+}
+
+/**
+ * Every child gets git's resolution variables stripped, since a pre-push hook
+ * exports `GIT_DIR` and a commit in the temp tree would otherwise land in the
+ * canon repository running the gate.
+ */
+function childEnv(): NodeJS.ProcessEnv {
+  return { ...gitEnv(), CANON_NON_INTERACTIVE: '1', NO_COLOR: '1' }
+}
+
+function spawn(
+  command: string,
+  argv: readonly string[],
+  cwd: string,
+  json: boolean,
+): StepOutput {
+  const result = spawnSync(command, argv, {
+    cwd,
+    env: childEnv(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: STEP_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+  })
+
+  return {
+    status: result.status,
+    signal: result.signal,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? result.error?.message ?? '',
+    json,
+  }
+}
+
+function git(tree: string, ...args: string[]): void {
+  const result = spawnSync(
+    'git',
+    [
+      '-c',
+      'user.name=canon-replay',
+      '-c',
+      'user.email=replay@localhost',
+      '-c',
+      'commit.gpgsign=false',
+      ...args,
+    ],
+    { cwd: tree, env: childEnv(), encoding: 'utf8' },
+  )
+  if (result.status !== 0)
+    throw new Error(
+      `git ${args.join(' ')} failed in the replay tree: ${result.stderr.trim()}`,
+    )
+}
+
+/** Every folder under the snapshot root, each one consumer's frozen managed paths. */
+export function listSnapshots(dir: string): ReplaySource[] {
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => ({ name, path: join(dir, name), kind: 'snapshot' }))
+}
+
+export interface SourceRefusal {
+  readonly reason: 'not-found' | 'not-a-repo' | 'dirty'
+  readonly message: string
+}
+
+/**
+ * Why a named checkout cannot be replayed, or undefined when it can. A dirty
+ * tree is refused rather than copied, since sync refuses one and the replay
+ * would then read a tree nobody synced, reporting the refusal as a clean run.
+ */
+export function checkoutRefusal(path: string): SourceRefusal | undefined {
+  if (!existsSync(path))
+    return { reason: 'not-found', message: `No folder at ${path}` }
+
+  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: path,
+    env: childEnv(),
+    encoding: 'utf8',
+  })
+  if (top.status !== 0 || top.stdout.trim() !== realpathSync(path))
+    return {
+      reason: 'not-a-repo',
+      message: `${path} is not the root of a git repository`,
+    }
+
+  const status = spawnSync('git', ['status', '--porcelain'], {
+    cwd: path,
+    env: childEnv(),
+    encoding: 'utf8',
+  })
+  if (status.stdout.trim() !== '')
+    return {
+      reason: 'dirty',
+      message: `${path} has uncommitted changes. Commit or stash them, then replay it.`,
+    }
+
+  return undefined
+}
+
+/** Added, modified, and untracked paths after the sync. A deletion has nothing to format. */
+function writtenPaths(tree: string): string[] {
+  const result = spawnSync(
+    'git',
+    ['status', '--porcelain', '-z', '--untracked-files=all'],
+    {
+      cwd: tree,
+      env: childEnv(),
+      encoding: 'utf8',
+    },
+  )
+
+  return result.stdout
+    .split('\0')
+    .filter((entry) => entry.length > 3 && !entry.slice(0, 2).includes('D'))
+    .map((entry) => entry.slice(3))
+    .sort()
+}
+
+/**
+ * Copies one source into a fresh temp tree, syncs it with the checkout's own
+ * CLI, and runs the health reads and the format check on the unstaged
+ * result. The tree is removed whatever the steps conclude.
+ */
+export function replaySource(
+  source: ReplaySource,
+  context: ReplayContext,
+): ReplayResult {
+  mkdirSync(context.tempRoot, { recursive: true })
+  const tree = mkdtempSync(join(context.tempRoot, `${source.name}-`))
+  const cli = join(context.checkoutRoot, 'src', 'cli.ts')
+  const steps: StepResult[] = []
+
+  try {
+    copySource(source, tree)
+    if (source.kind === 'snapshot') {
+      git(tree, 'init', '-q', '-b', 'main')
+      git(tree, 'add', '-A')
+      git(tree, 'commit', '-q', '-m', 'snapshot')
+    }
+
+    for (const { step, args } of CLI_STEPS) {
+      const output = spawn('bun', [cli, ...args], tree, args.includes('--json'))
+      steps.push({
+        step,
+        argv: ['canon', ...args],
+        exit: output.status,
+        ...judgeStep(output),
+        findings: findingsOf(output.stderr),
+      })
+    }
+
+    const written = writtenPaths(tree)
+    steps.push(formatStep(context.checkoutRoot, tree, written))
+
+    return { name: source.name, kind: source.kind, steps, written }
+  } finally {
+    rmSync(tree, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Runs the checkout's oxfmt over what sync wrote, under the golden config canon
+ * ships to every target rather than oxfmt's defaults, which quote YAML
+ * frontmatter differently from every consumer and would fail clean files.
+ */
+function formatStep(
+  checkoutRoot: string,
+  tree: string,
+  written: readonly string[],
+): StepResult {
+  const config = join(
+    checkoutRoot,
+    'tooling',
+    'base',
+    'configs',
+    '.oxfmtrc.json',
+  )
+  const args = [
+    '-c',
+    config,
+    '--check',
+    '--no-error-on-unmatched-pattern',
+    ...written,
+  ]
+  const argv = ['oxfmt', '--check', '<written>']
+  if (written.length === 0)
+    return { step: 'format', argv, exit: 0, verdict: 'ok', findings: [] }
+
+  const output = spawn(oxfmtBinary(checkoutRoot), args, tree, false)
+
+  return {
+    step: 'format',
+    argv,
+    exit: output.status,
+    ...judgeFormat(output),
+    findings: [],
+  }
+}
+
+function oxfmtBinary(checkoutRoot: string): string {
+  return join(checkoutRoot, 'node_modules', '.bin', 'oxfmt')
+}
+
+export function hasFormatter(checkoutRoot: string): boolean {
+  return existsSync(oxfmtBinary(checkoutRoot))
+}

package/src/sandbox/replay/verdict.ts

@@ -0,0 +1,102 @@
+/**
+ * What one step of a replay concluded. A finding or a refusal is the verb
+ * working, so it reads `ok`. Only a run that broke rather than answered fails:
+ * a `crash` threw or died, an `unreadable` run answered in a shape a caller
+ * cannot parse, and an `unformatted` tree holds a file sync wrote that the
+ * formatter canon ships rejects. A `drifted` read answered a frozen snapshot
+ * differently from the answer recorded beside it, which `judgeDrift` decides.
+ */
+export type ReplayVerdict =
+  | 'ok'
+  | 'crash'
+  | 'unreadable'
+  | 'unformatted'
+  | 'drifted'
+
+export interface StepOutput {
+  /** Null when the process ended on a signal, a timeout included. */
+  readonly status: number | null
+  readonly signal: string | null
+  readonly stdout: string
+  readonly stderr: string
+  /** Whether the step asked for `--json`, which makes stdout a contract. */
+  readonly json: boolean
+}
+
+export interface Judgement {
+  readonly verdict: ReplayVerdict
+  readonly detail?: string
+}
+
+/** A JavaScript stack frame, `at fn (file:line:col)` or a bare `at file:line:col`. */
+const STACK_FRAME = /^\s+at .*:\d+:\d+\)?$/m
+
+/** The line naming what was thrown, `TypeError: ...` or a system code such as `ENOENT: ...`. */
+const THROWN_LINE = /^(?:error: |[A-Z][A-Za-z]*Error: |E[A-Z]+: ).*$/m
+
+function crashOf(output: StepOutput): Judgement | undefined {
+  if (output.signal !== null)
+    return { verdict: 'crash', detail: `killed by ${output.signal}` }
+  if (!STACK_FRAME.test(output.stderr)) return undefined
+
+  return {
+    verdict: 'crash',
+    detail: THROWN_LINE.exec(output.stderr)?.[0] ?? 'stack trace on stderr',
+  }
+}
+
+export function judgeStep(output: StepOutput): Judgement {
+  const crash = crashOf(output)
+  if (crash !== undefined) return crash
+  if (!output.json) return { verdict: 'ok' }
+
+  try {
+    JSON.parse(output.stdout)
+  } catch {
+    const first = output.stdout.trim().split('\n')[0]
+
+    return {
+      verdict: 'unreadable',
+      detail:
+        first === undefined || first === ''
+          ? 'empty stdout'
+          : `stdout does not parse: ${first.slice(0, 120)}`,
+    }
+  }
+
+  return { verdict: 'ok' }
+}
+
+/**
+ * The warnings a step printed, each line the CLI marks `!` on a stream that is
+ * not a terminal. They never fail the replay, and carrying them is what lets a
+ * reader see a finding the verdict passed, such as a seed sync calls missing.
+ */
+export function findingsOf(stderr: string): string[] {
+  return stderr
+    .split('\n')
+    .filter((line) => line.startsWith('! '))
+    .map((line) => line.slice(2).trim())
+}
+
+/** oxfmt lists each file it would change as `<path> (<n>ms)` under `--check`. */
+const OXFMT_FILE = /^(\S.*) \(\d+m?s\)$/
+
+export function judgeFormat(output: StepOutput): Judgement {
+  const crash = crashOf(output)
+  if (crash !== undefined) return crash
+  if (output.status === 0) return { verdict: 'ok' }
+
+  const files = output.stdout
+    .split('\n')
+    .map((line) => OXFMT_FILE.exec(line.trim())?.[1])
+    .filter((file): file is string => file !== undefined)
+
+  return {
+    verdict: 'unformatted',
+    detail:
+      files.length > 0
+        ? files.join(', ')
+        : output.stderr.trim().split('\n')[0] || `exit ${output.status}`,
+  }
+}

package/src/tooling/verify-stack.ts

@@ -95,19 +95,18 @@ async function run({
   logStep(`Scaffolding ${stack}`)
   // Manifests carry shell syntax (`&&`, `cd`, quoted globs), so the command
   // runs under a shell rather than as a split argv.
-  const scaffold = await shell(
-    manifest.scaffold.replaceAll('{{name}}', name),
-    runsDir,
-  )
+  const scaffoldCommand = manifest.scaffold.replaceAll('{{name}}', name)
+  const scaffold = await shell(scaffoldCommand, runsDir)
   if (scaffold.failed) {
     logWarn('Scaffold failed')
+    process.stderr.write(`$ ${scaffoldCommand}\n`)
     writeTail(scaffold.all)
-    state.isFailed = true
   }
 
   if (!existsSync(state.dir)) {
     return refuse(`Scaffold did not produce ${state.dir}`)
   }
+  record(state, 'Scaffold', !scaffold.failed)
 
   await shell(
     'git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify --allow-empty',

package/tooling/astro/configs/playwright.config.ts

@@ -14,8 +14,8 @@ export default defineConfig({
     trace: 'on-first-retry',
     baseURL,
     // Nothing to wait out unless a test asserts motion. Opt back in per test with page.emulateMedia({ reducedMotion: 'no-preference' }).
-    // It is a context option rather than a top-level one, so written beside
-    // `baseURL` it type-checks nowhere and reaches no page.
+    // A top-level `use.reducedMotion` works from Playwright 1.50.
+    // `contextOptions` is the spelling that works on every version.
     contextOptions: { reducedMotion: 'reduce' },
   },
   projects: [

package/tooling/base/reference.md

@@ -39,6 +39,7 @@ Seeds live in `tooling/base/seeds/`. Sync drops each once on first install and n
 - `.github/workflows/verify.yml` runs on pull requests targeting `main` and on `workflow_dispatch`. A multi-root project adds its own jobs here.
 - `.github/pull_request_template.md` has `## Summary`, `## Key changes`, `## Technical context`, and `## Testing`. A project adds its own checklist lines.
 - `canon/context/development/` holds the `setup` and `ci` entries under a folder index. Extend them with project-specific commands and workflows, and keep canonical rationale here.
+- `canon/config/pr-labels.toml` is the starter pull request label map, covering what the toolkit installs. A project adds a row per surface of its own.
 
 ## Tool pairing
 

package/tooling/base/seeds/canon/config/pr-labels.toml

@@ -0,0 +1,41 @@
+# Pull request domain labels.
+#
+# `git-pr` matches the paths a branch changed against the prefixes below and
+# applies every label that matches. The rows here cover what the toolkit
+# installs. Add a row per surface of your own, such as `app = ["src/"]`, and
+# `canon labels audit` names any changed path no row reaches.
+#
+# Each label has to exist on the remote before a pull request can carry it.
+# Run `canon labels sync` once to create the ones the remote lacks, and again
+# after adding a row.
+#
+# The matching rule and the `[declined]` table are described in the `git-pr`
+# skill's labels reference.
+
+[domains]
+tooling = [
+  ".github/",
+  ".husky/",
+  "scripts/",
+  ".gitignore",
+  ".lintstagedrc",
+  ".oxfmtrc.json",
+  ".prettierignore",
+  "commitlint.config.js",
+  "package.json",
+  "bun.lock",
+  "canon/config/",
+]
+claude = [".claude/", "CLAUDE.md"]
+docs = [
+  "README.md",
+  "docs/",
+  "canon/REQUIREMENTS.md",
+  "canon/DESIGN.md",
+  "canon/context/",
+]
+
+# Paths deliberately left unlabelled, keyed by the reason.
+[declined]
+# Release automation opens its own pull request and applies its own label.
+release-managed = ["CHANGELOG.md", ".release-please-manifest.json"]