@erclx/canon 5.18.0 → 5.20.0

package/src/commands/teach.ts

@@ -1,12 +1,16 @@
-import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { readdirSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
+import { LiveStream } from '@/serve/live'
 import {
   logServing,
   parsePort,
   serveFields,
   waitForInterrupt,
 } from '@/serve/report'
-import { DEFAULT_PORT, startServer } from '@/serve/static'
+import { DEFAULT_PORT, LIVE_EVENTS_PATH, startServer } from '@/serve/static'
+import { compileScript } from '@/teach/browser/compile'
+import { reload } from '@/teach/browser/reload'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavGenerated, type NavOutcome, generateNav } from '@/teach/nav'
 import type { RenderOutcome } from '@/teach/render'
@@ -942,8 +946,17 @@ async function runUp(
       ? 'index.html'
       : relative(dir, resolve(root, contents)).split(sep).join('/')
 
-  const served = startServer(dir, { port, entry })
+  const stream = refreshOnChange(root, dir, topic, emitJson)
+  const served = startServer(dir, {
+    port,
+    entry,
+    live: {
+      stream,
+      script: compileScript(reload, [LIVE_EVENTS_PATH]),
+    },
+  })
   if (!served.ok) {
+    stream.close()
     // A serve refusal carries a reason the teach refusals do not list, so it
     // is written here in the teach record's shape rather than through one.
     if (emitJson) {
@@ -970,10 +983,105 @@ async function runUp(
     logServing(served)
   }
 
-  await waitForInterrupt(served.stop)
+  await waitForInterrupt(async () => {
+    stream.close()
+    await served.stop()
+  })
   return 0
 }
 
+/**
+ * An editor's swap or backup file, or anything under a dot folder. It changes
+ * nothing a page shows, so it neither starts a pass nor counts as served.
+ */
+function isScratch(path: string): boolean {
+  return path
+    .split(/[\\/]/)
+    .some((segment) => segment.startsWith('.') || segment.endsWith('~'))
+}
+
+/**
+ * What the served folder holds, as each file's path, size, and mtime. A pass
+ * whose `nav` wrote nothing leaves it unchanged, which is how the echo of a
+ * pass's own writes settles without a second reload.
+ */
+function servedState(dir: string): string {
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)))
+    .filter((path) => !isScratch(path))
+    .sort()
+    .map((path) => {
+      const stat = statSync(join(dir, path), { throwIfNoEntry: false })
+      return `${path}:${stat?.size}:${stat?.mtimeMs}`
+    })
+    .join('\n')
+}
+
+/**
+ * Re-runs `nav` on each settled change under the teach folder and tells every
+ * open page to reload once a pass changed what is served. Passes run one at a
+ * time, since `nav` is not reentrant over the files it rewrites, and a change
+ * arriving mid-pass is coalesced into exactly one more. A refused or failed
+ * pass sends no reload, so a page never reloads onto a half-written state.
+ */
+function refreshOnChange(
+  root: string,
+  dir: string,
+  topic: string | undefined,
+  emitJson: boolean,
+): LiveStream<string> {
+  let isRunning = false
+  let isDirty = false
+  let state = servedState(dir)
+
+  const report = (message: string, isWarning: boolean) => {
+    if (emitJson) process.stderr.write(`${message}\n`)
+    else if (isWarning) logWarn(message)
+    else logInfo(message)
+  }
+
+  const pass = async (): Promise<void> => {
+    const nav = await generateNav(root, topic)
+    if (!nav.ok) {
+      report(`Refresh refused: ${nav.message}`, true)
+      return
+    }
+    const next = servedState(dir)
+    if (next === state) return
+    state = next
+    stream.send({ reload: true })
+    report(`Refreshed ${nav.lessons} lessons, reloading open pages`, false)
+  }
+
+  const schedule = async (): Promise<void> => {
+    if (isRunning) {
+      isDirty = true
+      return
+    }
+    isRunning = true
+    do {
+      isDirty = false
+      // A throw, such as the teach folder removed mid-pass, is reported and
+      // the loop carries on, since a rejection left here would end the
+      // process and a stuck flag would end every later refresh.
+      try {
+        await pass()
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code ?? String(error)
+        report(`Refresh failed: ${code}`, true)
+      }
+    } while (isDirty)
+    isRunning = false
+  }
+
+  const stream = new LiveStream<string>(dir, {
+    map: (path) => (isScratch(path) ? undefined : path),
+    onChange: () => void schedule(),
+  })
+  return stream
+}
+
 function reportRefusal(
   title: string,
   refused: TeachRefused,

package/src/gate/stages.ts

@@ -192,11 +192,17 @@ export const STAGES: readonly Stage[] = [
         argv: ['gov', 'regen'],
         failure: 'Consumed-copy regen failed',
       },
+      {
+        kind: 'drift',
+        pathspec: 'governance/rules/standards',
+        failure:
+          'Standard-pointer rules drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
+      },
       {
         kind: 'drift',
         pathspec: '.claude/rules',
         failure:
-          'Consumed copies drifted. Run bun run check and commit .claude/rules.',
+          'Consumed copies drifted. Run bun run check and commit governance/rules/standards and .claude/rules.',
       },
     ],
     success: 'Consumed copies clean',

package/src/gov/citations.ts

@@ -266,7 +266,7 @@ export function collectCitations(text: string): RawCitation[] {
  *
  * A rule spelling a whole path there is declaring that exact artifact, and a
  * body line naming it again is naming what the rule governs rather than
- * pointing a reader somewhere. `governance/rules/canon/660-diagrams.md` tells
+ * pointing a reader somewhere. `governance/rules/standards/diagrams.md` tells
  * its reader to convert a `.claude/DIAGRAMS.md` left by an older install, which
  * is correctly absent from this tree and correctly named in the rule.
  */

package/src/gov/standard-rules.ts

@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { basename, join, relative } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import { parseFrontmatter } from '@/indexes/frontmatter'
+
+const STANDARDS_REL = 'standards'
+
+/** The band the generated rules ship in, named for what they point at. */
+export const STANDARD_RULES_BAND = 'standards'
+
+export type StandardRulesResult =
+  | { readonly ok: true; readonly written: readonly string[] }
+  | { readonly ok: false; readonly reason: string }
+
+interface StandardRule {
+  readonly name: string
+  readonly sourceRel: string
+  readonly title: string
+  readonly description: string
+  readonly paths: readonly string[]
+  readonly bullets: readonly string[]
+}
+
+export function standardRulesDir(root: string): string {
+  return join(rulesSourceDir(root), STANDARD_RULES_BAND)
+}
+
+/**
+ * Generates one path-scoped rule per standard whose frontmatter carries
+ * `paths:`. The standard owns the glob and the operative bullets, so the rule
+ * is output, committed beside the authored bands so every reader of
+ * `governance/rules/` sees it as an ordinary file.
+ *
+ * Every standard is read and checked before anything is written, so a refusal
+ * leaves the previous output whole rather than half cleared.
+ */
+export async function regenStandardRules(
+  root: string,
+): Promise<StandardRulesResult> {
+  const standardsDir = join(root, STANDARDS_REL)
+  if (!existsSync(standardsDir)) return { ok: true, written: [] }
+
+  const reserved = reservedNames(root)
+  const rules: StandardRule[] = []
+
+  for (const file of readdirSync(standardsDir).sort()) {
+    if (!file.endsWith('.md')) continue
+    const read = readStandard(root, file, reserved)
+    if (typeof read === 'string') return { ok: false, reason: read }
+    if (read !== undefined) rules.push(read)
+  }
+
+  const dir = standardRulesDir(root)
+  await rm(dir, { recursive: true, force: true })
+  if (rules.length > 0) await mkdir(dir, { recursive: true })
+
+  const written: string[] = []
+  for (const rule of rules) {
+    const dest = join(dir, `${rule.name}.md`)
+    await writeFile(dest, renderStandardRule(rule))
+    written.push(relative(root, dest))
+  }
+
+  return { ok: true, written }
+}
+
+/**
+ * Band folders and authored rule basenames. A bare-word rule name equal to a
+ * band would install the whole band through `--add`, and one equal to an
+ * authored rule would shadow it in the name index.
+ */
+function reservedNames(root: string): {
+  readonly bands: ReadonlySet<string>
+  readonly rules: ReadonlySet<string>
+} {
+  const bands = new Set<string>([STANDARD_RULES_BAND])
+  const rules = new Set<string>()
+
+  for (const rel of listRuleSourcePaths(root)) {
+    const segments = rel.split('/')
+    if (segments.length > 1) bands.add(segments[0])
+    if (segments[0] === STANDARD_RULES_BAND) continue
+    rules.add(basename(rel, '.md'))
+  }
+
+  return { bands, rules }
+}
+
+/** A rule to render, `undefined` for a standard with no `paths:`, or a reason. */
+function readStandard(
+  root: string,
+  file: string,
+  reserved: ReturnType<typeof reservedNames>,
+): StandardRule | string | undefined {
+  const sourceRel = `${STANDARDS_REL}/${file}`
+  const fields = parseFrontmatter(
+    readFileSync(join(root, STANDARDS_REL, file), 'utf8'),
+  )?.fields
+  if (fields === undefined || fields.paths === undefined) return undefined
+
+  const name = basename(file, '.md')
+  if (!isStringList(fields.paths)) {
+    return `${sourceRel}: paths must be a list of strings`
+  }
+  if (fields.rule !== undefined && !isStringList(fields.rule)) {
+    return `${sourceRel}: rule must be a list of strings`
+  }
+  if (reserved.bands.has(name)) {
+    return `${sourceRel}: name collides with a rule band folder`
+  }
+  if (reserved.rules.has(name)) {
+    return `${sourceRel}: name collides with an authored rule`
+  }
+
+  return {
+    name,
+    sourceRel,
+    title: typeof fields.title === 'string' ? fields.title : name,
+    description:
+      typeof fields.description === 'string' ? fields.description : '',
+    paths: fields.paths,
+    bullets: fields.rule ?? [],
+  }
+}
+
+function isStringList(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+  )
+}
+
+function renderStandardRule(rule: StandardRule): string {
+  const scope = rule.description.replace(/\.$/, '')
+  const pointer = [
+    `Follow the ${rule.name} standard for ${lowerFirst(scope)}.`,
+    'It is the single source.',
+    `Read it with \`canon standards ${rule.name}\`.`,
+  ].join(' ')
+
+  return [
+    '---',
+    `# Generated by \`canon gov regen\` from ${rule.sourceRel}. Edit that frontmatter, not this file.`,
+    `description: ${yamlScalar(rule.description)}`,
+    'paths:',
+    ...rule.paths.map((glob) => `  - ${yamlQuoted(glob)}`),
+    '---',
+    '',
+    `# ${rule.title.replace(/\breference$/, 'standards')}`,
+    '',
+    '## Authority',
+    '',
+    ...[pointer, ...rule.bullets].map((bullet) => `- ${bullet}`),
+    '',
+  ].join('\n')
+}
+
+function lowerFirst(text: string): string {
+  return text.charAt(0).toLowerCase() + text.slice(1)
+}
+
+/** Plain when YAML would read it back unchanged, single-quoted otherwise. */
+function yamlScalar(text: string): string {
+  const isPlain =
+    text !== '' &&
+    !/^[-?:,[\]{}#&*!|>'"%@`\s]/.test(text) &&
+    !/: |\s#|:$|\s$/.test(text)
+  return isPlain ? text : yamlQuoted(text)
+}
+
+/**
+ * Quoted the way Prettier's `singleQuote` leaves YAML, so the drift check
+ * never fights the formatter: single quotes unless the text holds one and
+ * double quotes would need no escape.
+ */
+function yamlQuoted(text: string): string {
+  if (text.includes("'") && !/["\\]/.test(text)) return `"${text}"`
+  return `'${text.replaceAll("'", "''")}'`
+}

package/src/sandbox/equivalence.ts

@@ -17,6 +17,7 @@ import {
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { collectCoverage, DEFAULT_ARM } from '@/sandbox/coverage'
+import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
 /** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
 const FIXTURES_DIR = 'fixtures'
@@ -136,6 +137,8 @@ export interface EquivalenceOptions {
   readonly targets: readonly string[]
   readonly base: string
   readonly includeAnchor: boolean
+  /** Runs anchor arms against a local bare repository and a stub `gh`, never the shared anchor. */
+  readonly stubRemote?: boolean
   readonly useMasks: boolean
   readonly out?: string
 }
@@ -516,7 +519,15 @@ function configDirFor(dir: string): string {
   return `${dir}.config`
 }
 
-function provisionEnv(arm: Arm, dir: string): NodeJS.ProcessEnv {
+function stubDirFor(dir: string): string {
+  return `${dir}.stub`
+}
+
+function provisionEnv(
+  arm: Arm,
+  dir: string,
+  stubbed = false,
+): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = {
     ...process.env,
     CANON_NON_INTERACTIVE: '1',
@@ -524,6 +535,7 @@ function provisionEnv(arm: Arm, dir: string): NodeJS.ProcessEnv {
     CANON_SANDBOX_RUN_ID: PINNED_RUN_ID,
     CLAUDE_CONFIG_DIR: configDirFor(dir),
   }
+  if (stubbed) Object.assign(env, createStubRemote(stubDirFor(dir)))
   if (arm.arm === undefined) delete env.SANDBOX_SCENARIO
   else env.SANDBOX_SCENARIO = arm.arm
 
@@ -541,13 +553,14 @@ async function provision(
   arm: Arm,
   dir: string,
   logPath: string,
+  stubbed: boolean,
 ): Promise<Provisioned> {
   rmSync(dir, { recursive: true, force: true })
   rmSync(configDirFor(dir), { recursive: true, force: true })
   const exit = await runProcess(
     'bun',
     [join(root, 'src', 'cli.ts'), 'sandbox', `${arm.category}:${arm.command}`],
-    { cwd: root, env: provisionEnv(arm, dir), logPath },
+    { cwd: root, env: provisionEnv(arm, dir, stubbed), logPath },
   )
   const log = readFileSync(logPath, 'utf8').split(root).join(ROOT_PLACEHOLDER)
 
@@ -592,8 +605,12 @@ async function checkHead(
   }
 }
 
-function withExit(manifest: Manifest, run: Provisioned): Manifest {
-  const next = new Map(manifest)
+function withExit(
+  manifest: Manifest,
+  run: Provisioned,
+  stub?: Manifest,
+): Manifest {
+  const next = new Map([...manifest, ...(stub ?? [])])
   next.set('exit', String(run.exit))
   next.set('log', run.log)
 
@@ -608,16 +625,20 @@ async function runArm(
   headRoot: string,
   masks: readonly Mask[],
   declared: boolean,
+  stubbed: boolean,
 ): Promise<ArmRecord> {
   const key = armKey(arm)
   const dir = join(workDir, 'arms', `arm-${index}`)
   const logPath = join(workDir, 'logs', `arm-${index}.log`)
 
-  const base = await provision(baseRoot, arm, dir, logPath)
-  const baseManifest = withExit(buildManifest(dir), base)
+  const stubManifest = (): Manifest | undefined =>
+    stubbed ? readStubManifest(stubDirFor(dir)) : undefined
 
-  const head = await provision(headRoot, arm, dir, logPath)
-  const headManifest = withExit(buildManifest(dir), head)
+  const base = await provision(baseRoot, arm, dir, logPath, stubbed)
+  const baseManifest = withExit(buildManifest(dir), base, stubManifest())
+
+  const head = await provision(headRoot, arm, dir, logPath, stubbed)
+  const headManifest = withExit(buildManifest(dir), head, stubManifest())
 
   // Kept beside the logs, so a reader of an `--out` folder can see what a
   // difference was rather than only that one exists.
@@ -643,6 +664,7 @@ async function runArm(
     : undefined
 
   rmSync(configDirFor(dir), { recursive: true, force: true })
+  rmSync(stubDirFor(dir), { recursive: true, force: true })
 
   return {
     arm: key,
@@ -770,8 +792,13 @@ export async function runEquivalence(
   try {
     const baseRoot = join(workDir, 'base')
     const baseCommit = git(options.root, ['rev-parse', options.base])
-    const runnable = arms.filter((a) => !a.anchor || options.includeAnchor)
-    const skipped = arms.filter((a) => a.anchor && !options.includeAnchor)
+    const stubRemote = options.stubRemote === true
+    const runnable = arms.filter(
+      (a) => !a.anchor || options.includeAnchor || stubRemote,
+    )
+    const skipped = arms.filter(
+      (a) => a.anchor && !options.includeAnchor && !stubRemote,
+    )
 
     const indexed = new Map(arms.map((a, i) => [armKey(a), i]))
     const run = (arm: Arm): Promise<ArmRecord> =>
@@ -783,18 +810,20 @@ export async function runEquivalence(
         options.root,
         masks,
         declaredKeys.has(armKey(arm)),
+        stubRemote && arm.anchor,
       )
 
     // Anchor arms force-push `main` and recreate a pull request on one shared
-    // remote, so they run strictly one at a time.
+    // remote, so they run strictly one at a time. A stub remote is private to its
+    // arm, so those arms join the pool.
+    const shared = (a: Arm): boolean => a.anchor && !stubRemote
     const offline = await pool(
-      runnable.filter((a) => !a.anchor),
+      runnable.filter((a) => !shared(a)),
       CONCURRENCY,
       (arm) => run(arm),
     )
     const anchored: ArmRecord[] = []
-    for (const arm of runnable.filter((a) => a.anchor))
-      anchored.push(await run(arm))
+    for (const arm of runnable.filter(shared)) anchored.push(await run(arm))
 
     const records: ArmRecord[] = [
       ...offline,

package/src/sandbox/stub-remote.ts

@@ -0,0 +1,140 @@
+import { execFileSync } from 'node:child_process'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+const STUB_ORG = 'stub-org'
+const ANCHOR_REPO = 'canon-sandbox'
+
+/** The URL `sandbox_anchor_url` builds once `GITHUB_ORG` names the stub organization. */
+export const STUB_ANCHOR_URL = `https://github.com/${STUB_ORG}/${ANCHOR_REPO}.git`
+
+/** Port 9 is the discard service, which nothing listens on, so a real HTTPS attempt fails. */
+const DEAD_PROXY = 'http://127.0.0.1:9'
+
+/** Pinned so a commit id depends on its tree alone and two provisions of one tree agree. */
+const PINNED_DATE = '2026-01-01T00:00:00Z'
+
+/**
+ * Answers the `gh` calls the git scenarios make and fails on any other, so a new
+ * call reaches a reader as a red arm rather than a silent pass. Every call is
+ * logged as one line, quoted so an argument holding a space stays one argument.
+ */
+const STUB_GH = `#!/usr/bin/env bash
+# stub gh
+dir="$STUB_GH_DIR"
+line="$(printf '%q ' "$@")"
+line="\${line% }"
+printf '%s\\n' "$line" >>"$dir/gh.log"
+
+case "$1" in
+api) exit 0 ;;
+pr)
+  case "$2" in
+  create)
+    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
+    count=$((count + 1))
+    echo "$count" >"$dir/pr-count"
+    echo "https://github.com/${STUB_ORG}/${ANCHOR_REPO}/pull/$count"
+    exit 0
+    ;;
+  close | list) exit 0 ;;
+  esac
+  ;;
+esac
+
+printf '%s\\n' "$line" >>"$dir/gh-unknown.log"
+echo "stub gh: unknown call: $line" >&2
+exit 1
+`
+
+/**
+ * Builds a local bare repository and a stub `gh` under `stubDir` and returns the
+ * environment that sends a provision's pushes and `gh` calls there. Nothing in
+ * it reaches the shared anchor: the URL rewrite turns every push into a file
+ * path, and the stub heads `PATH` ahead of any real `gh`.
+ */
+export function createStubRemote(stubDir: string): Record<string, string> {
+  rmSync(stubDir, { recursive: true, force: true })
+  const bin = join(stubDir, 'bin')
+  const remotes = join(stubDir, 'remotes')
+  mkdirSync(bin, { recursive: true })
+  mkdirSync(remotes, { recursive: true })
+
+  execFileSync(
+    'git',
+    ['init', '-q', '--bare', '-b', 'main', join(remotes, `${ANCHOR_REPO}.git`)],
+    { stdio: 'ignore' },
+  )
+
+  const gh = join(bin, 'gh')
+  writeFileSync(gh, STUB_GH)
+  chmodSync(gh, 0o755)
+
+  return {
+    PATH: `${bin}:${process.env.PATH ?? ''}`,
+    STUB_GH_DIR: stubDir,
+    GITHUB_ORG: STUB_ORG,
+    GIT_CONFIG_COUNT: '1',
+    GIT_CONFIG_KEY_0: `url.${remotes}/.insteadOf`,
+    GIT_CONFIG_VALUE_0: `https://github.com/${STUB_ORG}/`,
+    GIT_AUTHOR_DATE: PINNED_DATE,
+    GIT_COMMITTER_DATE: PINNED_DATE,
+    HTTPS_PROXY: DEAD_PROXY,
+    https_proxy: DEAD_PROXY,
+    ALL_PROXY: DEAD_PROXY,
+  }
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trimEnd()
+}
+
+function readLog(path: string): string {
+  return existsSync(path) ? readFileSync(path, 'utf8').trimEnd() : ''
+}
+
+/**
+ * Reads what a provision left in the stub: the `gh` calls, the calls it did not
+ * recognize, and for each bare repository every ref with its tip tree and the
+ * commit subjects beneath it. A tree id carries no timestamp, so it compares
+ * across two runs where a commit id would not.
+ */
+export function readStubManifest(stubDir: string): Map<string, string> {
+  const manifest = new Map<string, string>()
+  manifest.set('stub:gh', readLog(join(stubDir, 'gh.log')))
+  manifest.set('stub:gh-unknown', readLog(join(stubDir, 'gh-unknown.log')))
+
+  const remotes = join(stubDir, 'remotes')
+  if (!existsSync(remotes)) return manifest
+
+  for (const entry of readdirSync(remotes).sort()) {
+    if (!entry.endsWith('.git')) continue
+    const repo = join(remotes, entry)
+    const name = entry.slice(0, -'.git'.length)
+
+    const refs = git(repo, ['for-each-ref', '--format=%(refname) %(tree)'])
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => {
+        const ref = line.split(' ')[0] ?? ''
+        const subjects = git(repo, ['log', '--format=  %s', '--reverse', ref])
+
+        return `${line}\n${subjects}`
+      })
+    manifest.set(`stub:${name}:refs`, refs.join('\n'))
+  }
+
+  return manifest
+}