@erclx/canon 4.52.0 → 4.54.0

package/src/indexes/list.ts

@@ -0,0 +1,64 @@
+import { dirname, relative, resolve } from 'node:path'
+import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import { collectEntries } from '@/indexes/render'
+import { listIndexes } from '@/indexes/walk'
+
+export interface CatalogEntry {
+  readonly path: string
+  readonly title: string
+  readonly description: string
+}
+
+export interface IndexCatalog {
+  readonly entries: CatalogEntry[]
+  readonly errors: string[]
+}
+
+/**
+ * Flattens every folder index under `root` into one queryable catalog.
+ *
+ * A folder's own frontmatter error lands in `errors` without dropping the
+ * rest of the walk, the same isolation `regenOne` gives one folder.
+ */
+export async function buildIndexCatalog(root: string): Promise<IndexCatalog> {
+  const indexPaths = await listIndexes(root)
+  const entries: CatalogEntry[] = []
+  const errors: string[] = []
+
+  for (const indexPath of indexPaths) {
+    const dir = dirname(indexPath)
+    const frontmatter = await readFrontmatter(indexPath)
+    const title = readField(frontmatter, 'title')
+    const subtitle = readField(frontmatter, 'subtitle')
+
+    if (!title || !subtitle) {
+      errors.push(
+        `missing frontmatter field "title" or "subtitle" in ${indexPath}`,
+      )
+    } else {
+      entries.push({
+        path: relative(root, indexPath),
+        title,
+        description: subtitle,
+      })
+    }
+
+    const collected = await collectEntries(dir)
+    if (!collected.ok) {
+      errors.push(...collected.errors)
+      continue
+    }
+
+    for (const entry of collected.entries) {
+      entries.push({
+        path: relative(root, resolve(dir, entry.name)),
+        title: entry.title,
+        description: entry.description,
+      })
+    }
+  }
+
+  entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  return { entries, errors }
+}

package/src/indexes/render.ts

@@ -64,7 +64,7 @@ async function readIndexHead(
   return { ok: true, head: { raw: frontmatter.raw, title, subtitle } }
 }
 
-async function collectEntries(
+export async function collectEntries(
   dir: string,
 ): Promise<
   { ok: true; entries: IndexEntry[] } | { ok: false; errors: string[] }

package/src/labels/event.ts

@@ -6,6 +6,8 @@ export type ScanInputRefusal =
   | 'unreadable-event'
   | 'not-a-pull-request'
   | 'unreadable-review'
+  | 'conflicting-body-input'
+  | 'unreadable-body-file'
 
 export type ResolvedScanInput =
   | {
@@ -26,6 +28,7 @@ export interface ScanInputOptions {
   readonly event?: string
   readonly title?: string
   readonly body?: string
+  readonly bodyFile?: string
   readonly head?: string
 }
 
@@ -46,6 +49,27 @@ export function resolveScanInput(opts: ScanInputOptions): ResolvedScanInput {
   let headRefName = opts.head
   let source: 'pull-request' | 'review' = 'pull-request'
 
+  if (opts.bodyFile !== undefined) {
+    if (body !== undefined) {
+      return {
+        kind: 'refused',
+        reason: 'conflicting-body-input',
+        message:
+          '--body and --body-file cannot both be given, since only one text can be scanned.',
+      }
+    }
+
+    try {
+      body = readFileSync(opts.bodyFile, 'utf8')
+    } catch {
+      return {
+        kind: 'refused',
+        reason: 'unreadable-body-file',
+        message: `${opts.bodyFile} could not be read, so no body was there to scan.`,
+      }
+    }
+  }
+
   if (opts.event !== undefined) {
     let raw: string
     try {

package/src/records/validate.ts

@@ -72,6 +72,7 @@ export const FINDING_KINDS = [
   'closing-partial',
   'item-incomplete',
   'category-mismatch',
+  'operator-call-phrasing',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -157,6 +158,53 @@ export function isSharedScratch(kind: RecordKind): boolean {
 const NONE_IDENTIFIED = 'None identified.'
 const NUMBERED_FILE = /^\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
 
+/**
+ * The suggestion the plan standard fixes for a question that turns on the
+ * operator's preference rather than on a technical default. `src/tasks/answers.ts`
+ * reads this alongside `normalizeOperatorCall` so the dispatch gate and this
+ * write-time check cannot drift into recognizing different spellings.
+ */
+export const OPERATOR_CALL = 'needs your call'
+
+/**
+ * The two demonstrated paraphrases of `OPERATOR_CALL`, longer variant first so
+ * it is not read as a shorter match sitting inside it: `operator's call` is a
+ * substring of `the operator's call`, and checking it first would rewrite the
+ * `the` into place with the wrong phrase on either side.
+ */
+const OPERATOR_CALL_PHRASES = [
+  "the operator's call",
+  "operator's call",
+] as const
+
+/**
+ * Reads a recognized paraphrase as the canonical phrase, so a caller testing
+ * `startsWith(OPERATOR_CALL)` sees one spelling regardless of which wording the
+ * author used. Case-insensitive, since the corpus capitalizes a suggestion's
+ * first word, and it rewrites only the matched span so the reason text either
+ * side of it survives untouched.
+ *
+ * Short-circuits on an already-canonical opening before scanning the rest of
+ * the text. Without that, a suggestion already opening with `needs your call`
+ * that goes on to mention a paraphrase inside its own reason, such as
+ * `needs your call, since the operator's call outranks a default`, has that
+ * later occurrence rewritten too, which garbles the reason the dispatcher
+ * reports rather than leaving it as the author wrote it.
+ */
+export function normalizeOperatorCall(text: string): string {
+  const lower = text.toLowerCase()
+  if (lower.startsWith(OPERATOR_CALL)) return text
+
+  for (const phrase of OPERATOR_CALL_PHRASES) {
+    const at = lower.indexOf(phrase)
+    if (at !== -1) {
+      return `${text.slice(0, at)}your call${text.slice(at + phrase.length)}`
+    }
+  }
+
+  return text
+}
+
 function finding(
   kind: FindingKind,
   record: string,
@@ -295,6 +343,9 @@ function shorten(label: string): string {
   return label.length > 60 ? `${label.slice(0, 57)}...` : label
 }
 
+const SUGGESTED_PREFIX = '- Suggested:'
+const ANSWER_PREFIX = '- Answer:'
+
 function checkQuestionContract(name: string, lines: string[]): Finding[] {
   if (lines.some((line) => line.trim() === NONE_IDENTIFIED)) return []
 
@@ -302,8 +353,12 @@ function checkQuestionContract(name: string, lines: string[]): Finding[] {
 
   for (const question of readQuestions(lines)) {
     const subject = shorten(question.label)
+    const suggested = question.body.find((line) =>
+      line.startsWith(SUGGESTED_PREFIX),
+    )
+    const answer = question.body.find((line) => line.startsWith(ANSWER_PREFIX))
 
-    if (!question.body.some((line) => line.startsWith('- Suggested:'))) {
+    if (!suggested) {
       findings.push(
         finding(
           'suggestion-missing',
@@ -314,7 +369,7 @@ function checkQuestionContract(name: string, lines: string[]): Finding[] {
       )
     }
 
-    if (!question.body.some((line) => line.startsWith('- Answer:'))) {
+    if (!answer) {
       findings.push(
         finding(
           'question-unanswerable',
@@ -324,6 +379,29 @@ function checkQuestionContract(name: string, lines: string[]): Finding[] {
         ),
       )
     }
+
+    if (
+      suggested &&
+      answer &&
+      answer.slice(ANSWER_PREFIX.length).trim() === ''
+    ) {
+      const text = suggested.slice(SUGGESTED_PREFIX.length).trim()
+      const normalized = normalizeOperatorCall(text)
+
+      if (
+        normalized.toLowerCase().startsWith(OPERATOR_CALL) &&
+        !text.toLowerCase().startsWith(OPERATOR_CALL)
+      ) {
+        findings.push(
+          finding(
+            'operator-call-phrasing',
+            name,
+            subject,
+            'defers to the operator over a blank Answer without opening with the canonical needs your call, so a paraphrase reaches the corpus instead of the fixed spelling.',
+          ),
+        )
+      }
+    }
   }
 
   return findings

package/src/tasks/answers.ts

@@ -3,20 +3,17 @@ import { readFile } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
 import { isUnder } from '@/paths'
 import { recordDir, recordDirs } from '@/record-root'
-import { readQuestions, splitPlanSections } from '@/records/validate'
+import {
+  normalizeOperatorCall,
+  OPERATOR_CALL,
+  readQuestions,
+  splitPlanSections,
+} from '@/records/validate'
 
 const PLANS = 'plans'
 const TASKS = 'tasks'
 const ARCHIVE = 'archive'
 
-/**
- * The suggestion the plan standard fixes for a question that turns on the
- * operator's preference rather than on a technical default. Every other
- * suggestion is accepted by a blank slot, so only this phrase over an empty
- * `- Answer:` is a stop.
- */
-const OPERATOR_CALL = 'needs your call'
-
 const SUGGESTED_PREFIX = '- Suggested:'
 const ANSWER_PREFIX = '- Answer:'
 
@@ -112,9 +109,15 @@ function isAnswered(body: readonly string[]): boolean {
  * behind a full stop, so both separators come off. Reporting the phrase with
  * whatever punctuation followed it hands the operator a stray mark where the
  * reason should start.
+ *
+ * Takes the normalized suggestion rather than the raw one, so the length
+ * stripped from the front is always `OPERATOR_CALL`'s own regardless of which
+ * recognized wording the author wrote. The `operator's call` and
+ * `the operator's call` variants read longer than `your call`, and slicing by
+ * the canonical length against the raw text would cut into the reason itself.
  */
-function reasonOf(suggested: string): string {
-  const rest = suggested.slice(OPERATOR_CALL.length).replace(/^[,.;:\s]+/, '')
+function reasonOf(normalized: string): string {
+  const rest = normalized.slice(OPERATOR_CALL.length).replace(/^[,.;:\s]+/, '')
 
   return rest.length > 0 ? rest : 'no reason stated'
 }
@@ -130,10 +133,13 @@ function openQuestions(lines: readonly string[]): OpenQuestion[] {
 
   for (const question of readQuestions(lines)) {
     const suggested = suggestionOf(question.body)
-    if (!suggested?.toLowerCase().startsWith(OPERATOR_CALL)) continue
+    if (!suggested) continue
+
+    const normalized = normalizeOperatorCall(suggested)
+    if (!normalized.toLowerCase().startsWith(OPERATOR_CALL)) continue
     if (isAnswered(question.body)) continue
 
-    open.push({ label: question.label, why: reasonOf(suggested) })
+    open.push({ label: question.label, why: reasonOf(normalized) })
   }
 
   return open

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

@@ -6,6 +6,7 @@ const baseURL = `http://localhost:${4321 + (Number(process.env.WORKTREE_PORT_OFF
 export default defineConfig({
   testDir: 'e2e',
   forbidOnly: isCI,
+  // Absorbs shared-runner noise on a fresh scaffold with no flake history, at the cost of hiding a real defect until someone reads the run summary.
   retries: isCI ? 2 : 0,
   // No override here: Playwright's own CPU-derived default suits every CI runner
   reporter: isCI ? 'list' : 'html',
@@ -19,7 +20,9 @@ export default defineConfig({
     { name: 'webkit', use: { ...devices['Desktop Safari'] } },
   ],
   webServer: {
-    command: 'bun run build && bun run preview',
+    command: process.env.DIST_PREBUILT
+      ? 'bun run preview'
+      : 'bun run build && bun run preview',
     url: baseURL,
     reuseExistingServer: false,
     env: { ASTRO_PREVIEW_BACKGROUND: '0' },

package/tooling/astro/reference.md

@@ -19,7 +19,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 - `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
-- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
+- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
 - `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). `src/pages/**` exempt from filename and folder naming conventions because Astro's file-based routing ties names to URL segments.
 

package/tooling/vite-react/configs/playwright.config.ts

@@ -6,6 +6,7 @@ const baseURL = `http://localhost:${5173 + (Number(process.env.WORKTREE_PORT_OFF
 export default defineConfig({
   testDir: 'e2e',
   forbidOnly: isCI,
+  // Absorbs shared-runner noise on a fresh scaffold with no flake history, at the cost of hiding a real defect until someone reads the run summary.
   retries: isCI ? 2 : 0,
   // No override here: Playwright's own CPU-derived default suits every CI runner
   reporter: isCI ? 'list' : 'html',

package/tooling/web/configs/.github/workflows/verify.yml

@@ -5,6 +5,10 @@ on:
     branches: [main]
   workflow_dispatch:
 
+concurrency:
+  group: verify-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   static-checks:
     name: 🔍 Static Checks
@@ -90,6 +94,13 @@ jobs:
       - name: Build
         run: bun run build
 
+      - name: Upload Build Output
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+          retention-days: 1
+
   e2e-tests:
     name: 🎭 E2E Tests
     runs-on: ubuntu-latest
@@ -111,18 +122,29 @@ jobs:
       - name: Install Dependencies
         run: bun install --frozen-lockfile
 
+      - name: Download Build Output
+        uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+
+      - name: Install Playwright System Dependencies
+        run: bunx playwright install-deps chromium
+
       - name: Cache Playwright Browsers
         id: playwright-cache
         uses: actions/cache@v4
         with:
           path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ hashFiles('**/package.json') }}
+          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('**/package.json') }}
 
       - name: Install Playwright Chromium
         if: steps.playwright-cache.outputs.cache-hit != 'true'
         run: bunx playwright install chromium
 
       - name: Run E2E Tests
+        env:
+          DIST_PREBUILT: 'true'
         run: bun run test:e2e --project=chromium
 
       - name: Upload E2E Report

package/tooling/web/configs/e2e/screenshot.ts

@@ -24,10 +24,29 @@ const CASES: CaptureCase[] = [
   },
 ]
 
+const args = process.argv.slice(2)
+const checkConsoleClean = args.includes('--check-console-clean')
+const requireBaseUrl = args.includes('--require-base-url')
+
+if (requireBaseUrl && !process.env.SCREENSHOT_BASE_URL) {
+  console.error('SCREENSHOT_BASE_URL is required with --require-base-url')
+  process.exit(1)
+}
+
 const BASE_URL = process.env.SCREENSHOT_BASE_URL ?? 'http://localhost:4173'
-const OUT_DIR = 'screenshots'
+
+let hostname: string
+try {
+  hostname = new URL(BASE_URL).hostname
+} catch {
+  console.error(`SCREENSHOT_BASE_URL is not a valid URL: ${BASE_URL}`)
+  process.exit(1)
+}
+
+const OUT_DIR = path.join('screenshots', hostname)
 
 const browser = await chromium.launch()
+const consoleErrors: string[] = []
 
 for (const captureCase of CASES) {
   const context = await browser.newContext({
@@ -35,6 +54,16 @@ for (const captureCase of CASES) {
   })
   const page = await context.newPage()
 
+  if (checkConsoleClean) {
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(
+          `${captureCase.section}/${captureCase.theme}: ${msg.text()}`,
+        )
+      }
+    })
+  }
+
   if (captureCase.setup) await captureCase.setup(page)
 
   await page.goto(`${BASE_URL}${captureCase.route}`)
@@ -51,3 +80,9 @@ for (const captureCase of CASES) {
 }
 
 await browser.close()
+
+if (checkConsoleClean && consoleErrors.length > 0) {
+  console.error('console errors detected:')
+  for (const error of consoleErrors) console.error(`  ${error}`)
+  process.exit(1)
+}

package/tooling/web/configs/scripts/screenshot.sh

@@ -11,7 +11,7 @@ fi
 bun run build
 bun run preview >/dev/null 2>&1 &
 PREVIEW_PID=$!
-trap 'kill "$PREVIEW_PID" 2>/dev/null; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+trap 'kill "$PREVIEW_PID" 2>/dev/null || true; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
 
 for _ in $(seq 1 40); do
   if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then

package/tooling/web/manifest.toml

@@ -47,6 +47,7 @@ packages = [
 "test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
 "test:e2e:report" = "playwright show-report"
 "check:full" = "./scripts/verify.sh && bun run test:e2e"
+"smoke:prod" = "bun e2e/screenshot.ts --check-console-clean --require-base-url"
 
 [scripts.override]
 "lint" = "eslint . --max-warnings 0"
@@ -55,5 +56,5 @@ packages = [
 [gitignore]
 "# Build" = ["dist/"]
 "# Coverage" = ["coverage/"]
-"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/", "screenshots/"]
+"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]
 "# VSCode" = [".vscode/*", "!.vscode/extensions.json", "!.vscode/settings.json"]

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<section>/<theme>.png`. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<hostname>/<section>/<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -106,11 +106,20 @@ Append rows:
 | `bun run test:e2e` | Run Playwright E2E tests. |
 | `bun run test:e2e:changed` | Run Playwright E2E tests for specs the import graph reaches from the current diff. |
 | `bun run screenshot` | Build, preview, then capture screenshots. |
+| `bun run smoke:prod` | Capture against `SCREENSHOT_BASE_URL`, requiring it set and failing on any console error. |
 
 `canon tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
 
 `governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a route changes. It fires on route and page files rather than on every component, so a shared component changing every screen fires nothing and the operator runs the capture by hand.
 
+The screenshot output now tracks in git rather than getting discarded, so the first capture a scaffolded target runs after this change is the baseline it commits.
+
+## Gitignore (extend)
+
+`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+
+- `"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/"]`
+
 ## Verify script
 
 The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build. Stack adapters may override if their typecheck or build differs.