@erclx/canon 5.33.0 → 5.34.0

package/governance/detect.toml

@@ -0,0 +1,201 @@
+# Evidence that marks a project as wanting an opt-in rule. Each table is keyed by
+# a rule basename, the same key `renames.toml` and the stacks use, so a rename
+# sweep reaches this file too. `canon gov detect` reads it and proposes every
+# rule whose evidence a target holds, and `target-setup` puts those proposals to
+# the operator before anything installs.
+#
+# `deps` are package names read from `package.json` (`dependencies` and
+# `devDependencies`), `pyproject.toml`, `go.mod`, and `composer.json`, at the
+# root and in every folder to depth two. `files` are globs matched against the
+# target's git-listed paths to depth two, and against each folder on those
+# paths, so `.github/workflows` matches a folder holding a workflow. A glob with
+# no wildcard is also tested on disk, which reaches a gitignored path such as
+# `.canon/canvas`.
+#
+# Every rule no stack reaches needs a table here, which the `unreferenced-rules`
+# gate stage checks, along with every key naming a live rule. A table for a rule
+# a stack already reaches is harmless, since the verb leaves out every rule the
+# caller's stack resolves.
+
+["skill"]
+deps = []
+files = [".claude/skills", "claude/skills"]
+
+["700-ci-workflow"]
+deps = []
+files = [".github/workflows"]
+
+["765-spelling"]
+deps = ["cspell"]
+files = [".cspell", "cspell.json", ".cspell.json", "cspell.config.*"]
+
+["775-dependencies"]
+deps = []
+files = ["**/package.json", "**/pyproject.toml", "**/go.mod", "**/composer.json"]
+
+["780-config-comments"]
+deps = []
+files = [".editorconfig", "**/Dockerfile*", "**/*.config.*", "**/.env.example"]
+
+["790-code-comments"]
+deps = []
+files = ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.sh", "**/*.py"]
+
+["130-go"]
+deps = []
+files = ["**/go.mod"]
+
+["140-php"]
+deps = []
+files = ["**/composer.json"]
+
+["200-react"]
+deps = ["react"]
+files = []
+
+["210-astro"]
+deps = ["astro"]
+files = ["**/astro.config.*"]
+
+["220-fastapi"]
+deps = ["fastapi"]
+files = []
+
+["230-nextjs"]
+deps = ["next"]
+files = ["**/next.config.*"]
+
+["250-tailwind"]
+deps = ["tailwindcss", "@tailwindcss/vite", "@tailwindcss/postcss"]
+files = ["**/tailwind.config.*"]
+
+["260-shadcn"]
+deps = []
+files = ["**/components.json"]
+
+["305-e2e-reliability"]
+deps = ["@playwright/test", "playwright", "cypress"]
+files = ["**/e2e"]
+
+["306-test-scope"]
+deps = ["@playwright/test", "playwright", "cypress"]
+files = ["**/e2e"]
+
+["310-zod"]
+deps = ["zod"]
+files = []
+
+["320-tanstack-query"]
+deps = [
+  "@tanstack/react-query",
+  "@tanstack/vue-query",
+  "@tanstack/solid-query",
+  "@tanstack/svelte-query",
+  "@tanstack/query-core",
+]
+files = []
+
+["335-testing-go"]
+deps = []
+files = ["**/go.mod"]
+
+["336-testing-php"]
+deps = ["phpunit/phpunit", "pestphp/pest"]
+files = ["**/phpunit.xml", "**/phpunit.xml.dist"]
+
+["340-pydantic"]
+deps = ["pydantic"]
+files = []
+
+["350-security-web"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["360-security-server"]
+deps = [
+  "express",
+  "fastify",
+  "hono",
+  "koa",
+  "elysia",
+  "@nestjs/core",
+  "fastapi",
+  "django",
+  "flask",
+  "starlette",
+  "laravel/framework",
+  "symfony/http-kernel",
+  "slim/slim",
+  "github.com/gin-gonic/gin",
+  "github.com/labstack/echo/v4",
+  "github.com/go-chi/chi/v5",
+  "github.com/gofiber/fiber/v2",
+]
+files = []
+
+["370-database"]
+deps = [
+  "prisma",
+  "@prisma/client",
+  "drizzle-orm",
+  "typeorm",
+  "sequelize",
+  "knex",
+  "kysely",
+  "mongoose",
+  "pg",
+  "mysql2",
+  "better-sqlite3",
+  "sqlalchemy",
+  "alembic",
+  "psycopg",
+  "psycopg2",
+  "psycopg2-binary",
+  "asyncpg",
+  "django",
+  "doctrine/orm",
+  "illuminate/database",
+  "gorm.io/gorm",
+  "github.com/jackc/pgx/v5",
+]
+files = ["**/migrations", "**/schema.prisma", "**/*.sql"]
+
+["400-ui"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["410-a11y"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["420-forms"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["430-ux-completeness"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["440-surface-capture"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["450-link-behavior"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["460-design-taste"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["canon/DESIGN.md", "index.html", "*/index.html"]
+
+["465-interface-casing"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["470-motion"]
+deps = ["react", "vue", "svelte", "astro", "next", "solid-js", "preact"]
+files = ["index.html", "*/index.html"]
+
+["480-canvas"]
+deps = []
+files = [".canon/canvas"]

package/governance/rules/code/000-code.md

@@ -1,5 +1,5 @@
 ---
-description: Code placement, shape, dependency, error, and naming choices a model does not make by default
+description: Routes code placement and shape decisions to the skills that carry them
 ---
 
 # Code standards
@@ -7,19 +7,7 @@ description: Code placement, shape, dependency, error, and naming choices a mode
 ## Placement
 
 - Load the `canon:codebase-layout` skill before placing a new file, and report it rather than proceeding silently when it does not resolve.
-- Prioritize native platform capabilities over third-party libraries.
-- Ensure data and configuration reside in designated Single Source of Truth locations.
 
 ## Shape
 
 - Load the `canon:code-craft` skill before deciding the shape of a new function, class, or module, and report it rather than proceeding silently when it does not resolve.
-
-## Errors
-
-- Return structured error types for recoverable failures.
-- Never expose internal implementation details in error messages.
-
-## Naming
-
-- Prefix booleans with `is`, `has`, `should`, or `can`: `isLoading`, `hasAccess`.
-- Prefix event handlers with `handle`: `handleClick`, `handleSubmit`.

package/governance/rules/code/010-testing.md

@@ -1,37 +1,9 @@
 ---
-description: Enforce universal testing standards and best practices
+description: Routes a test edit to the skill that carries the testing floors
 ---
 
 # Testing standards
 
 ## Before writing a test
 
-- Load the `canon:test-craft` skill before choosing the layer for a new test, and report it rather than proceeding silently when the skill does not resolve.
-
-## Test structure
-
-- Structure tests using the Arrange, Act, Assert (AAA) pattern.
-- Each test should verify a single behavior.
-- Do not use conditional logic or loops within test bodies.
-
-## Test focus
-
-- Do not test private functions or internal state directly.
-- Do not target arbitrary coverage percentages.
-
-## Organization and isolation
-
-- Group related tests using the framework's nesting mechanism.
-- Keep nesting shallow (max 2 levels).
-- Ensure tests are independent with no shared side effects.
-- Clean up side effects and restore state after each test.
-
-## Test data and async
-
-- Use factory functions or builders for test data over inline object literals.
-- Always await async operations.
-- Do not fire-and-forget promises in tests.
-
-## Verification
-
-- Do not use snapshot testing for verification.
+- Load the `canon:test-craft` skill before writing or changing a test, and report it rather than proceeding silently when the skill does not resolve.

package/governance/rules/ui/400-ui.md

@@ -11,7 +11,7 @@ paths:
 
 ## Punctuation
 
-- Do not use em dashes (`—`). Use a comma or period, or restructure the sentence.
+- Do not use em dashes (`—`) or semicolons (`;`). Use a comma or period, or restructure the sentence.
 - Do not add punctuation to button labels or short action strings.
 
 ## Button copy

package/governance/rules/ui/480-canvas.md

@@ -0,0 +1,13 @@
+---
+description: Route edits to canvas frames under .canon/canvas/ to the canvas-board skill for the house style, and keep frame text and box height readable
+paths:
+  - '.canon/canvas/**'
+---
+
+# Canvas standards
+
+## Frames
+
+- Load the `canon:canvas-board` skill before drawing or editing a frame. It carries the house style for an explanation frame and the content format. Report it rather than proceeding silently when the skill does not resolve.
+- Write explanation frame text in sentence case. A mockup of the project's interface follows its design document instead.
+- Size each explanation frame's box to show all its content with no scrollbar.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.33.0",
+  "version": "5.34.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.ts

@@ -50,7 +50,6 @@ import { listSkills } from '../../src/claude/skills-list'
 import { countCommands } from '../../src/counts/catalogs'
 import { buildDesignCss } from '../../src/design/css'
 import { buildGovCatalog } from '../../src/gov/list'
-import { listStandardEntries } from '../../src/standards/list'
 import { buildStackSummaries } from '../../src/tooling/list'
 
 const root = new URL('../..', import.meta.url).pathname
@@ -87,11 +86,6 @@ function run(): void {
   const { values, frames } = buildFrameValues({
     skills: listSkills(root).map((entry) => entry.name),
     gov: buildGovCatalog(root),
-    // The toolkit root only: a project-local standard would put a row in the
-    // hero the toolkit does not ship.
-    standards: listStandardEntries(root).filter((entry) =>
-      entry.source.startsWith('standards/'),
-    ),
     toolingStacks: buildStackSummaries(root),
     commandCount: countCommands(root) ?? 0,
     tokenCss,

package/scripts/lib/ui.sh

@@ -96,12 +96,3 @@ close_timeline() {
   set_palette 2
   echo -e "${GREY}└${NC}" >&2
 }
-
-guard_root() {
-  local target="$1"
-  local target_abs
-  target_abs=$(cd "$target" && pwd)
-  if [ "$target_abs" = "$PROJECT_ROOT" ]; then
-    log_error "Cannot run against toolkit root. Files here are the source of truth."
-  fi
-}

package/src/canvas/arrange.ts

@@ -0,0 +1,66 @@
+import { type Box, FRAME_GAP, type Frame } from '@/canvas/content'
+
+export interface Placement {
+  readonly name: string
+  readonly from: Box
+  readonly to: Box
+}
+
+function boxOf(frame: Frame): Box {
+  return {
+    x: frame.x,
+    y: frame.y,
+    width: frame.width,
+    height: frame.height,
+  }
+}
+
+/**
+ * Boxes whose vertical spans overlap share a row, so a row the operator dragged
+ * stays a row. Reading by overlap rather than by an equal `y` lets a frame a
+ * few pixels off its neighbor still join it.
+ */
+function rowsOf(frames: readonly Frame[]): Frame[][] {
+  const sorted = [...frames].sort((a, b) => a.y - b.y || a.x - b.x)
+  const rows: Frame[][] = []
+  let bottom = Number.NEGATIVE_INFINITY
+  for (const frame of sorted) {
+    const row = rows.at(-1)
+    if (row && frame.y < bottom) {
+      row.push(frame)
+      bottom = Math.max(bottom, frame.y + frame.height)
+    } else {
+      rows.push([frame])
+      bottom = frame.y + frame.height
+    }
+  }
+  return rows.map((row) =>
+    row.sort((a, b) => a.x - b.x || a.name.localeCompare(b.name)),
+  )
+}
+
+/**
+ * Re-lays a page's frames: each row left to right on `FRAME_GAP` from the
+ * page's leftmost edge, rows stacked on their tallest box plus the gap from
+ * the page's top edge. Returns only the frames whose position changes.
+ */
+export function planArrange(frames: readonly Frame[]): Placement[] {
+  if (frames.length === 0) return []
+  const left = Math.min(...frames.map((frame) => frame.x))
+  let top = Math.min(...frames.map((frame) => frame.y))
+
+  const moves: Placement[] = []
+  for (const row of rowsOf(frames)) {
+    let x = left
+    for (const frame of row) {
+      const from = boxOf(frame)
+      const to: Box = { ...from, x, y: top }
+      if (from.x !== to.x || from.y !== to.y) {
+        moves.push({ name: frame.name, from, to })
+      }
+      x += frame.width + FRAME_GAP
+    }
+    top += Math.max(...row.map((frame) => frame.height)) + FRAME_GAP
+  }
+  return moves
+}

package/src/canvas/capture.ts

@@ -157,7 +157,7 @@ export async function captureCanvas(
   })
 }
 
-type ServeRefused = {
+export type ServeRefused = {
   readonly ok: false
   readonly reason: 'no-server' | 'capture-failed'
   readonly detail: string
@@ -168,20 +168,34 @@ async function serveFor<T>(
   deps: CaptureDeps,
   run: (base: string, capture: CaptureEngine) => Promise<T>,
 ): Promise<T | ServeRefused> {
-  const start = deps.start ?? startCanvas
+  return serveCanvas(root, deps.start, async (base) => {
+    const capture =
+      deps.capture ?? (await import('@/capture/render')).captureSources
+    return run(base, capture)
+  })
+}
+
+/**
+ * Runs a call against a canvas served on a free port for its length, so a verb
+ * that renders frames reads the same address the board shows.
+ */
+export async function serveCanvas<T>(
+  root: string,
+  startOverride: CaptureDeps['start'],
+  run: (base: string) => Promise<T>,
+): Promise<T | ServeRefused> {
+  const start = startOverride ?? startCanvas
   const server = start(root, { port: 0, shell: new Response('') })
   if (!server.ok) {
     return {
       ok: false,
       reason: 'no-server',
-      detail: `${server.detail}, so run canon canvas serve and capture again`,
+      detail: `${server.detail}, so run canon canvas serve and try again`,
     }
   }
 
   try {
-    const capture =
-      deps.capture ?? (await import('@/capture/render')).captureSources
-    return await run(server.url, capture)
+    return await run(server.url)
   } catch (error) {
     return {
       ok: false,

package/src/canvas/content.ts

@@ -578,6 +578,45 @@ export function restoreBox(
   })
 }
 
+export type PruneOutcome =
+  | { readonly ok: true; readonly dropped: readonly string[] }
+  | ContentRefused
+
+/**
+ * Lists the layout entries whose frame file is gone, and removes them under
+ * the layout lock unless `write` is false. `readPage` never reports them, so
+ * this is the one place an entry outliving its frame is seen.
+ */
+export function pruneLayout(
+  root: string,
+  page: string,
+  write: boolean,
+): PruneOutcome {
+  if (!isValidName(page)) {
+    return refuse('invalid-name', `${page} is not a valid page name`)
+  }
+  const dir = pagePath(root, page)
+  if (!isDirectory(dir)) return refuse('no-page', `page ${page} does not exist`)
+
+  const prune = (): PruneOutcome => {
+    const { boxes, malformed } = readLayout(dir)
+    if (malformed) {
+      return refuse('malformed-layout', `${page}/${LAYOUT_FILE} does not parse`)
+    }
+    const present = new Set(frameNames(dir))
+    const dropped = [...boxes.keys()].filter((name) => !present.has(name))
+    if (write && dropped.length > 0) {
+      writeLayout(
+        dir,
+        new Map([...boxes].filter(([name]) => present.has(name))),
+      )
+    }
+    return { ok: true, dropped }
+  }
+
+  return write ? withFileLock(join(dir, LAYOUT_FILE), prune) : prune()
+}
+
 export interface Selection {
   readonly page: string
   readonly frame: string