@erclx/canon 5.33.0 → 5.35.0

package/src/commands/canvas.ts

@@ -9,12 +9,15 @@ import {
   DEFAULT_FRAME,
   listPages,
   moveFrame,
+  pruneLayout,
   readPage,
   readSelection,
   renamePage,
   resizeFrame,
 } from '@/canvas/content'
+import { planArrange } from '@/canvas/arrange'
 import { captureCanvas, captureComposite } from '@/canvas/capture'
+import { fitCanvas, isOwed } from '@/canvas/fit'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -148,7 +151,7 @@ export function register(program: Command): void {
     .command('canvas')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture, fit, arrange)',
     )
     .addHelpText(
       'after',
@@ -167,6 +170,8 @@ export function register(program: Command): void {
         "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
         '  canon canvas editing drafts/hero',
         '  canon canvas capture drafts/hero',
+        '  canon canvas fit drafts/hero --json',
+        '  canon canvas arrange drafts --check',
         '  canon canvas list --json',
         '',
       ].join('\n'),
@@ -728,6 +733,179 @@ export function register(program: Command): void {
       outro()
       if (failed) process.exitCode = 1
     })
+
+  withRoot(
+    canvas
+      .command('fit')
+      .description("Set each frame's height to its content")
+      .argument('<target>', '<page>/<frame> for one frame, <page> for all')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Measures each frame in the capture browser at its box width, through',
+        'the served address, so the faces the canvas serves are the ones read.',
+        'The height is the content height rounded up, with no margin. A',
+        'content wider than the box is reported and the box is never widened.',
+        'A frame whose body text names a family the canvas does not serve is',
+        'reported as font, since its height may not hold in another browser.',
+        '',
+        'Run canvas arrange after a fit that grew a frame, since rows below',
+        'do not move on their own.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused or the browser failed',
+        '  2  --check found a height off, a wide frame, or a font',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: FitOptions) => {
+      process.exitCode = await runFit(target, opts)
+    })
+
+  withRoot(
+    canvas
+      .command('arrange')
+      .description('Re-lay a page in rows on the frame gap')
+      .argument('<page>', 'Page to arrange')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Keeps the rows the frames already sit in, orders each left to right on',
+        'the frame gap, stacks the rows on their tallest frame, and drops',
+        'layout entries whose frame file is gone.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused',
+        '  2  --check found frames to move or entries to drop',
+        '',
+      ].join('\n'),
+    )
+    .action(async (pageName: string, opts: FitOptions) => {
+      process.exitCode = await runArrange(pageName, opts)
+    })
+}
+
+interface FitOptions extends RootOptions {
+  readonly check?: boolean
+}
+
+async function runFit(target: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+
+  const check = opts.check ?? false
+  let outcome: Awaited<ReturnType<typeof fitCanvas>>
+  try {
+    outcome = await fitCanvas(resolved.root, target, !check)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const frames = outcome.rows.map((row) => ({ ...row, owed: isOwed(row) }))
+  const owed = frames.some((row) => row.owed)
+  if (emitJson) writeJson({ ok: true, written: outcome.written, frames })
+  intro(BANNER)
+  for (const row of frames) {
+    const name = `${row.page}/${row.frame}`
+    if (row.fitted === row.height) logInfo(`${name} fits at ${row.height}`)
+    else if (outcome.written) logAdd(`${name} ${row.height} to ${row.fitted}`)
+    else logStep(`${name} owes ${row.height} to ${row.fitted}`)
+    if (row.wide) logWarn(`${name} is wider than its box, so widen the box`)
+    if (row.viewport) {
+      logWarn(
+        `${name} sets a height in viewport units, so its height was not written and a fixed height fits it`,
+      )
+    }
+    if (row.font) {
+      logWarn(
+        `${name} sets ${row.family}, which the canvas does not serve, so its height may not hold in another browser`,
+      )
+    }
+  }
+  outro()
+  return check && owed ? 2 : 0
+}
+
+async function runArrange(pageName: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+  const { root } = resolved
+
+  const page = readPage(root, pageName)
+  if (!page) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'no-page',
+        detail: `page ${pageName} does not exist`,
+      },
+      emitJson,
+    )
+  }
+  if (page.layoutIssue) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'malformed-layout',
+        detail: `${pageName}/layout.json does not parse`,
+      },
+      emitJson,
+    )
+  }
+
+  const check = opts.check ?? false
+  const pruned = pruneLayout(root, pageName, !check)
+  if (!pruned.ok) return refuse(pruned, emitJson)
+
+  const moves = planArrange(page.frames)
+  if (!check) {
+    for (const move of moves) {
+      const outcome = resizeFrame(root, pageName, move.name, move.to)
+      if (!outcome.ok) return refuse(outcome, emitJson)
+    }
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      page: pageName,
+      written: !check,
+      moved: moves.map((move) => ({
+        frame: move.name,
+        from: { x: move.from.x, y: move.from.y },
+        to: { x: move.to.x, y: move.to.y },
+      })),
+      dropped: pruned.dropped,
+    })
+  }
+  intro(BANNER)
+  for (const move of moves) {
+    const text = `${pageName}/${move.name} ${move.from.x}, ${move.from.y} to ${move.to.x}, ${move.to.y}`
+    if (check) logStep(`${text} is owed`)
+    else logAdd(text)
+  }
+  for (const name of pruned.dropped) {
+    logWarn(
+      `${pageName}/${name} has no frame file, so its entry is ${check ? 'owed a drop' : 'dropped'}`,
+    )
+  }
+  if (moves.length === 0 && pruned.dropped.length === 0) {
+    logInfo(`${pageName} is already laid out`)
+  }
+  outro()
+  return check && (moves.length > 0 || pruned.dropped.length > 0) ? 2 : 0
 }
 
 interface CaptureOptions extends RootOptions {

package/src/commands/gov.ts

@@ -19,6 +19,7 @@ import {
   govStackExists,
   listGovStacks,
   mergeExtraRules,
+  resolveExtraRules,
   resolveRules,
 } from '@/gov/stacks'
 import {
@@ -51,6 +52,7 @@ import {
   type TestOrderReport,
 } from '@/gov/test-order'
 import { recordStamp, runDomainSync } from '@/sync/engine'
+import { detectRules } from '@/gov/detect'
 import { writeChainStamp } from '@/sync/stamp'
 import { resolveTarget } from '@/targets/validate'
 import {
@@ -141,7 +143,7 @@ export function register(program: Command): void {
   gov
     .command('install')
     .description('Install a governance stack into .claude/rules/canon/')
-    .argument('[stack]', 'Stack name (e.g. base, node, react)')
+    .argument('[stack]', 'Stack name (e.g. base, node, python)')
     .argument('[target]', 'Target directory', '.')
     .helpOption('-h, --help', 'Show this help message')
     .option('--add <rules>', 'Comma-separated rules to layer on the stack')
@@ -150,9 +152,14 @@ export function register(program: Command): void {
       [
         '',
         'Examples:',
-        '  canon gov install react',
+        '  canon gov install node',
         '  canon gov install node ../my-app',
-        '  canon gov install astro --add 200-react,260-shadcn ../my-app',
+        '  canon gov install node --add 210-astro,260-shadcn ../my-app',
+        '  canon gov install --add tasks,plan ../my-app',
+        '',
+        'With --add and no stack, the named rules install alone. A first',
+        'positional naming a stack is read as the stack, so pass . or a path',
+        'carrying a slash to force a target that shares a stack name.',
         '',
       ].join('\n'),
     )
@@ -221,6 +228,31 @@ export function register(program: Command): void {
       process.exitCode = runList(opts)
     })
 
+  gov
+    .command('detect')
+    .description('Propose opt-in rules from the evidence a target holds')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--stack <stack>', 'Leave out every rule this stack resolves')
+    .option('--json', 'Emit machine-readable JSON')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads governance/detect.toml and matches each rule against the',
+        "target's manifests and git-listed paths to depth two. Pass the",
+        'proposals to canon gov install --add once confirmed.',
+        '',
+        'Examples:',
+        '  canon gov detect --json',
+        '  canon gov detect ../my-app --stack node --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: DetectOptions) => {
+      process.exitCode = await runDetect(target, opts)
+    })
+
   gov
     .command('test-order')
     .description(
@@ -275,7 +307,7 @@ export function register(program: Command): void {
         'members a closed catalog holds, then compares the stated figure',
         'against what the tree actually counts.',
         '',
-        'Catalogs read: skills, governance rules, standards, CLI commands,',
+        'Catalogs read: skills, governance rules, CLI commands,',
         'and audit ids. Closed rather than derived, so widening the',
         'set is a deliberate change rather than a side effect of a new list',
         'command shipping elsewhere.',
@@ -409,10 +441,6 @@ export function register(program: Command): void {
         'present and the question answerable.',
         '',
         'Forms read, with where each resolves:',
-        '  standard  canon standards <name> , against standards/ alone, which',
-        '            is where the verb itself looks. internal/standards/ is not',
-        '            tried, since a name resolving only there refuses for the',
-        '            session that opens the citation.',
         '  path      a backticked path carrying a directory segment and a file',
         '            extension, against the root',
         "  sibling   a bare <nnn>-<slug>.md , against the citing rule's folder",
@@ -422,7 +450,7 @@ export function register(program: Command): void {
         '  naming a file, such as canon/context/<domain>.md or app/**/route.ts',
         '  a bare filename naming a convention, such as route.ts or manifest.toml',
         '  a span carrying no file extension, which is a folder or a module',
-        '  specifier, such as src/pages/ , next/font , or claude/standards',
+        '  specifier, such as src/pages/ , next/font , or claude/skills',
         '  a fenced block, which displays a path rather than pointing at one',
         '',
         'Exempt, reported by name rather than dropped:',
@@ -1070,6 +1098,7 @@ function runList(opts: ListOptions): number {
         ...(sections.stacks ? { stacks: catalog.stacks } : {}),
         ...(sections.rules ? { rules: catalog.rules } : {}),
         unreferenced: catalog.unreferenced,
+        staleDetect: catalog.staleDetect,
       })}\n`,
     )
     return 0
@@ -1097,6 +1126,51 @@ function runList(opts: ListOptions): number {
   return 0
 }
 
+interface DetectOptions {
+  readonly stack?: string
+  readonly json?: boolean
+}
+
+async function runDetect(target: string, opts: DetectOptions): Promise<number> {
+  const resolved = resolve(target)
+  if (!existsSync(resolved)) {
+    logError(`Target not found: ${target}`)
+    return 1
+  }
+
+  const result = await detectRules(PROJECT_ROOT, resolved, opts.stack)
+  if (!result.ok) {
+    logError(`Stack not found: ${result.missingStack}`)
+    return 1
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        target: resolved,
+        stack: opts.stack ?? null,
+        proposals: result.proposals,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon gov detect')
+  if (result.proposals.length === 0) {
+    logInfo('No opt-in rule matched this target')
+  } else {
+    logStep('Proposed rules')
+    for (const proposal of result.proposals) {
+      const reasons = proposal.evidence
+        .map((evidence) => `${evidence.match} in ${evidence.path}`)
+        .join(', ')
+      logInfo(`${proposal.rule}: ${reasons}`)
+    }
+  }
+  outro()
+  return 0
+}
+
 /**
  * Silent on success so the consumed-copy stage that calls it stays quiet. It is
  * the only work that stage does now. The installed set is readable on disk, so
@@ -1171,6 +1245,11 @@ async function runInstall(
 ): Promise<number> {
   intro('canon gov install')
 
+  const add = opts.add ?? ''
+  if (add !== '' && isAddWithoutStack(stack, target)) {
+    return installExtras(add, stack ?? target)
+  }
+
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
@@ -1194,7 +1273,6 @@ async function runInstall(
     return 1
   }
 
-  const add = opts.add ?? ''
   const rules =
     add === '' ? resolution.rules : mergeExtraRules(resolution.rules, add)
 
@@ -1247,6 +1325,67 @@ async function runInstall(
   return 0
 }
 
+/**
+ * Whether `--add` runs with no stack under it. Commander fills the first
+ * positional before the second, so `--add a,b ../my-app` arrives with the
+ * target in `stack` and the default `.` in `target`. A first positional that
+ * names a stack keeps today's meaning, so a folder named `node` reads as the
+ * stack, and `.` or a path carrying a slash is how a caller forces the target.
+ */
+function isAddWithoutStack(stack: string | undefined, target: string): boolean {
+  if (stack === undefined) return true
+  if (target !== '.') return false
+  if (stack === '.' || stack.includes('/')) return true
+  return !govStackExists(PROJECT_ROOT, stack)
+}
+
+/**
+ * Installs `--add` names alone. The chain stamp is left as it was, since the
+ * extras are not a stack, and overwriting the chain would cost a target the
+ * missing-rule report its stack install recorded.
+ */
+async function installExtras(add: string, target: string): Promise<number> {
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  logStep('Resolving extras with no stack')
+
+  const { found, missing } = lookupRules(PROJECT_ROOT, resolveExtraRules(add))
+  for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
+  for (const source of found) logInfo(source.rule)
+
+  if (found.length === 0) {
+    logError('No named rule resolved, so nothing was installed.')
+    outro()
+    return 1
+  }
+
+  const shouldInstall = await select({
+    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldInstall) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Installing rules')
+  for (const rel of await installRules(found, resolved)) logAdd(rel)
+
+  await recordStamp(createGovAdapter(PROJECT_ROOT), resolved, new Date())
+
+  const { GREEN, NC } = palette(process.stderr)
+  outro()
+  process.stderr.write(`${GREEN}✓ Rules installed${NC}\n`)
+  return 0
+}
+
 /**
  * Emits the rules payload the `gov-*` skills read. The output lands in the
  * target's scratch directory rather than stdout because the file is the

package/src/commands/init.ts

@@ -40,7 +40,7 @@ export function register(program: Command): void {
         'Examples:',
         '  canon init',
         '  canon init ../my-app',
-        '  canon init --stack astro --add 260-shadcn ../my-app',
+        '  canon init --stack node --add 210-astro,260-shadcn ../my-app',
         '  canon init --skip governance ../my-app',
         '',
       ].join('\n'),

package/src/commands/labels.ts

@@ -10,7 +10,6 @@ import { checkTitleFormat, type TitleFormatIssue } from '@/labels/format'
 import { MAP_REL } from '@/labels/map'
 import { isReleasePullRequest, scanPhaseLabels } from '@/labels/phase'
 import { checkSections } from '@/labels/sections'
-import { scanTitleSpelling } from '@/labels/spelling'
 import { BAN_SETS } from '@/markdown/bans'
 import { bodyLines, scanBans } from '@/markdown/scan'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
@@ -169,7 +168,7 @@ export function register(program: Command): void {
   labels
     .command('scan')
     .description(
-      'Fail a pull request or a posted review whose title, body, or review comment carries a phase label, a board identifier, a session link, or a title with an unspelled word',
+      'Fail a pull request or a posted review whose title, body, or review comment carries a phase label, a board identifier, or a session link',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option(
@@ -188,7 +187,7 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Reads canon standards versioning for the two namespaces and sorts every',
+        'Reads the git-commit versioning reference for the two namespaces and sorts every',
         'version-shaped token this pull request carries into the one the pull',
         'request is allowed to hold. A release-please pull request, read off its',
         'own fixed head branch and title, may carry semver references. Every',
@@ -212,13 +211,6 @@ export function register(program: Command): void {
         'session and for no other reader, which no clone repairs, so it is read',
         'on a release pull request too, where the board identifier is not.',
         '',
-        "It also spell-checks the title alone against this repository's own",
-        'cspell config, since release-please copies the title into',
-        'CHANGELOG.md and nothing else spell-checks it first. The check shells',
-        "this repository's own resolved cspell binary and reports nothing when",
-        'a target project carries none, rather than reaching the network or',
-        'forcing a new dependency.',
-        '',
         "It also grades the title alone against claude/skills/git-pr/references/pr.md's ## Title",
         'section: the `<type>(<scope>)[!]: <subject>` structure, lowercase casing',
         'for the type, the scope, and the first subject word, and a 72-',
@@ -234,11 +226,11 @@ export function register(program: Command): void {
         'request or a review, outside a code span or a link.',
         '',
         'Exit codes:',
-        '  0  none of the seven found',
+        '  0  none of the six found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
         '     session link, a banned character, a heading outside the closed',
-        '     list or a required one missing, a title word no dictionary holds, or a title',
+        '     list or a required one missing, or a title',
         "     breaking claude/skills/git-pr/references/pr.md's format, casing, or length",
         '',
         'Examples:',
@@ -532,7 +524,6 @@ async function runScan(opts: ScanOptions): Promise<number> {
   }
 
   const result = scanPhaseLabels(resolved)
-  const spelling = await scanTitleSpelling(resolved.title, process.cwd())
   // A scan given no title, whatever produced that absence, has nothing to
   // grade and would otherwise fail as `structure` for the wrong reason.
   const titleFormat =
@@ -579,34 +570,6 @@ async function runScan(opts: ScanOptions): Promise<number> {
     for (const link of result.sessionLinks) logWarn(link)
   }
 
-  const spellingChecked = spelling.kind === 'checked'
-  const unspelledWords =
-    spelling.kind === 'checked' ? spelling.unknownWords : []
-
-  logStep(
-    spelling.kind === 'unavailable'
-      ? 'Spelling unavailable'
-      : unspelledWords.length === 0
-        ? 'Clean'
-        : 'Unspelled word found',
-  )
-  if (spelling.kind === 'unavailable' && spelling.reason === 'no-binary') {
-    logInfo(
-      `no node_modules/.bin/cspell resolved walking up from ${spelling.probedFrom}, so the title was not checked`,
-    )
-  } else if (spelling.kind === 'unavailable') {
-    logInfo(
-      `cspell did not exit clean or with issues found (${spelling.message}), so the title was not checked`,
-    )
-  } else if (unspelledWords.length === 0) {
-    logInfo('no word in the title is absent from every dictionary')
-  } else {
-    logWarn(
-      `${plural(unspelledWords.length, 'word')} in the title absent from every dictionary. Fix the spelling, or add jargon and project-specific terms to .cspell/project-terms.txt and dependency vocabulary to .cspell/tech-stack.txt.`,
-    )
-    for (const word of unspelledWords) logWarn(word)
-  }
-
   const titleFormatIssues = titleFormat?.issues ?? []
 
   // A review carries its own headings, a release-please body opens on a
@@ -707,8 +670,6 @@ async function runScan(opts: ScanOptions): Promise<number> {
         semverTags: result.semverTags,
         boardReferences: result.boardReferences,
         sessionLinks: result.sessionLinks,
-        unspelledWords,
-        spellingChecked,
         titleFormatIssues,
         sections: { checked: sectionsChecked, ...sections },
         bannedCharacters,
@@ -719,7 +680,6 @@ async function runScan(opts: ScanOptions): Promise<number> {
   return result.phaseLabels.length === 0 &&
     result.boardReferences.length === 0 &&
     result.sessionLinks.length === 0 &&
-    unspelledWords.length === 0 &&
     titleFormatIssues.length === 0 &&
     sections.outside.length === 0 &&
     sections.missing.length === 0 &&

package/src/commands/migrate.ts

@@ -1124,7 +1124,7 @@ export function register(program: Command): void {
         'repoints every citation that names one, live or archived.',
         '',
         'A promoted folder is one a durable record cites and no source file',
-        'under claude/, scripts/, src/, governance/, or standards/ names by',
+        'under claude/, scripts/, src/, or governance/ names by',
         'path. A folder a script still writes into stays in scratch, since',
         'moving it needs a code change first.',
         '',