@erclx/canon 4.112.0 → 4.114.0

package/src/claude/skills-audit.ts

@@ -1,10 +1,6 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import {
-  type Frontmatter,
-  parseFrontmatter,
-  readField,
-} from '@/indexes/frontmatter'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 
 /** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
 export const EXIT_MISSING_REQUIREMENT = 2
@@ -149,7 +145,7 @@ async function readSkill(
       : Promise.resolve(undefined),
   ])
 
-  const fields = readFields(body)
+  const fields = parseFrontmatter(body)
 
   return {
     rel: join(rel, folder),
@@ -162,19 +158,6 @@ async function readSkill(
   }
 }
 
-/**
- * Returns undefined rather than throwing on unparseable YAML, so one malformed
- * body reports as missing its required fields instead of ending the audit
- * before it reaches the rest of the corpus.
- */
-function readFields(body: string): Frontmatter | undefined {
-  try {
-    return parseFrontmatter(body)
-  } catch {
-    return undefined
-  }
-}
-
 /**
  * A key carrying an empty value declares nothing, so blank reads as absent
  * rather than as a name that disagrees with every folder.

package/src/commands/feedback-format.ts

@@ -89,6 +89,30 @@ export function deriveSlug(body: string): string {
   return slug || SLUG_FALLBACK
 }
 
+/**
+ * Each label must exist on the toolkit repository, because `gh issue create`
+ * refuses the whole issue on an unknown label rather than dropping it.
+ */
+const DOMAIN_LABELS: readonly { pattern: RegExp; label: string }[] = [
+  { pattern: /\bskills?\b/, label: 'skills' },
+  { pattern: /\b(?:cli)s?\b/, label: 'cli' },
+  { pattern: /\b(?:tooling|seeds?)\b/, label: 'tooling' },
+  { pattern: /\b(?:governance)s?\b/, label: 'governance' },
+  { pattern: /\bsnippets?\b/, label: 'snippets' },
+]
+
+/**
+ * Reads only the surface type, the text before the first comma, so a path or
+ * name after it never adds a label.
+ */
+export function deriveDomainLabels(body: string): string[] {
+  const type = (surfaceField(body) ?? '').split(',')[0]?.toLowerCase() ?? ''
+  const labels = DOMAIN_LABELS.filter(({ pattern }) => pattern.test(type)).map(
+    ({ label }) => label,
+  )
+  return [...new Set(labels)]
+}
+
 export function deriveTitle(body: string): string {
   const surface = surfaceField(body)
   const title = surface ? `feedback: ${surface}` : 'toolkit feedback'

package/src/commands/feedback.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import {
+  deriveDomainLabels,
   deriveSlug,
   deriveTitle,
   missingField,
@@ -107,7 +108,7 @@ export function register(program: Command): void {
         const result = await createGithubIssue({
           title: deriveTitle(body),
           body,
-          labels: ['feedback'],
+          labels: ['feedback', ...deriveDomainLabels(body)],
         })
         if (result.ok) {
           frameSuccess('canon feedback', result.url)

package/src/commands/records.ts

@@ -330,6 +330,12 @@ function backupHelp(verb: 'push' | 'pull'): string {
           'It commits nothing outside the folders above and leaves the project working',
           'tree untouched. The push runs even when this call committed nothing, since a',
           'previous run can have committed and then failed to reach the network.',
+          '',
+          'Before staging, it refuses the whole push as unsafe-payload when any new or',
+          'changed file is over 25 MB or carries a credential canon secrets scan would',
+          'report, naming each path. Nothing is staged or committed when it refuses.',
+          'A push the remote rejects undoes the commit this call made, so the records',
+          'stay on disk and no later run sends that commit again.',
         ]
       : [
           'It refuses rather than discarding local records that never reached the remote,',
@@ -569,6 +575,12 @@ async function runPush(opts: BackupCommandOptions): Promise<number> {
   if (outcome.firstSeen.length > 0) {
     logWarn(`first seen: ${outcome.firstSeen.join(', ')}`)
   }
+  for (const path of outcome.added) logInfo(`added: ${path}`)
+  if (outcome.dropped.length > 0) {
+    logWarn(
+      `excluded but still tracked, removed from the history going forward: ${outcome.dropped.join(', ')}`,
+    )
+  }
   logStep(outcome.pushed ? 'Pushed' : 'Nothing to push')
   logInfo(
     outcome.commit
@@ -609,7 +621,11 @@ async function runPull(opts: BackupCommandOptions): Promise<number> {
  */
 function reportRefusal(
   banner: string,
-  outcome: { readonly reason: string; readonly message: string },
+  outcome: {
+    readonly reason: string
+    readonly message: string
+    readonly blocked?: readonly unknown[]
+  },
   emitJson: boolean,
 ): number {
   if (emitJson) {
@@ -619,6 +635,7 @@ function reportRefusal(
         ok: false,
         reason: outcome.reason,
         message: outcome.message,
+        ...(outcome.blocked ? { blocked: outcome.blocked } : {}),
       })}\n`,
     )
     return 1

package/src/commands/teach.ts

@@ -1,4 +1,4 @@
-import { relative } from 'node:path'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
 import { type NavOutcome, generateNav } from '@/teach/nav'
@@ -18,6 +18,7 @@ import {
   type TeachRefused,
   type Term,
   type TermOutcome,
+  teachDir,
   type WorkspaceSummary,
   writeStylesheet,
 } from '@/teach/workspace'
@@ -91,6 +92,18 @@ export function register(program: Command): void {
     .command('teach')
     .description('Manage learning workspaces in .canon/teach/')
     .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Opening a workspace:',
+        '  canon serve .canon/teach --entry <nn>-<topic>/index.html',
+        '',
+        'canon teach list <topic> prints the exact line, with the teach folder',
+        'written from where you stand rather than as this literal.',
+        '',
+      ].join('\n'),
+    )
 
   teach
     .command('list')
@@ -118,6 +131,9 @@ export function register(program: Command): void {
         'A workspace not named NN-<topic> is still listed. It sorts last and',
         'moves no ordinal, since dropping it hides the folder needing a fix.',
         '',
+        'The human output ends with the canon serve line that opens a',
+        'workspace, a template with no topic and the exact line with one.',
+        '',
         'Examples:',
         '  canon teach list',
         '  canon teach list regular-expressions --json',
@@ -852,6 +868,22 @@ function describe(workspace: WorkspaceSummary): string {
   return `${workspace.slug}: ${workspace.lessons} lesson(s), ${workspace.records} record(s), ${workspace.reference} reference page(s), ${workspace.terms} term(s)`
 }
 
+/**
+ * `canon serve` resolves its folder against the caller's cwd, while the list
+ * verb reads the teach folder at the main worktree root, so the line carries
+ * the folder actually read. A literal `.canon/teach` serves an absent folder
+ * from a linked worktree.
+ */
+function serveLine(root: string, entry: string): string {
+  const dir = resolve(teachDir(root))
+  const fromCwd = relative(process.cwd(), dir)
+  const isOutsideCwd =
+    fromCwd === '..' || fromCwd.startsWith(`..${sep}`) || isAbsolute(fromCwd)
+  const printed = fromCwd === '' ? '.' : isOutsideCwd ? dir : fromCwd
+
+  return `canon serve ${printed} --entry ${entry}`
+}
+
 function reportList(
   outcome: ListOutcome,
   emitJson: boolean,
@@ -890,6 +922,12 @@ function reportList(
 
   logStep('Next ordinal')
   logInfo(outcome.next)
+
+  if (outcome.workspaces.length > 0) {
+    logStep('Open')
+    logInfo(serveLine(root, '<nn>-<topic>/index.html'))
+  }
+
   outro()
 
   return 0
@@ -940,6 +978,8 @@ function reportWorkspace(
     logWarn(`no ${workspace.missing.join(' and no ')}`)
   }
 
+  logStep('Open')
+  logInfo(serveLine(root, `${workspace.slug}/index.html`))
   outro()
 
   return 0

package/src/commands/tooling.ts

@@ -20,6 +20,7 @@ import {
 import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
 import { recordToolingChain } from '@/tooling/stamp'
+import { subfolderPath } from '@/tooling/subfolder'
 import {
   intro,
   isNonInteractive,
@@ -93,6 +94,11 @@ export function register(program: Command): void {
         '  canon tooling sync base',
         '  canon tooling sync base --check',
         '  CANON_NON_INTERACTIVE=1 canon tooling sync base --write',
+        '  canon tooling sync vite-react web --skip base',
+        '',
+        'A target below its git root syncs as a subfolder. It withholds',
+        '.github/, which GitHub reads only at the root, and writes a nested',
+        'cspell.json registering the stack word lists.',
         '',
         'To gate CI on tooling drift, run headlessly with neither flag. That',
         'exits 1 when a file would be replaced and 0 when none would, which is',
@@ -358,7 +364,7 @@ async function runSync(
 
   const result = scan(prepared.chain, prepared.target)
 
-  report(result)
+  report(result, prepared.target)
 
   if (opts.diff !== undefined) {
     if (opts.diff.json) {
@@ -568,7 +574,7 @@ async function promptForStack(): Promise<string | undefined> {
   })
 }
 
-function report(result: ScanResult): void {
+function report(result: ScanResult, target: string): void {
   logStep('Scanning configs')
   for (const entry of result.configs) {
     if (entry.state === 'matching') logInfo(entry.rel)
@@ -580,6 +586,8 @@ function report(result: ScanResult): void {
     if (entry.state === 'new') logAdd(entry.rel)
   }
 
+  if (result.withheld.length > 0) reportWithheld(result, target)
+
   logStep('Scanning seeds')
   for (const entry of result.seeds) {
     if (entry.state === 'present') logInfo(entry.rel)
@@ -591,6 +599,7 @@ function report(result: ScanResult): void {
   if (result.hasPackageJson) {
     reportPackage(result)
   } else {
+    logStep('Scanning package.json')
     logWarn(
       "Skipped scripts and deps: no package.json found (run 'bun init' to enable)",
     )
@@ -605,6 +614,20 @@ function report(result: ScanResult): void {
   }
 }
 
+function reportWithheld(result: ScanResult, target: string): void {
+  logStep('Withheld from a subfolder')
+  for (const entry of result.withheld) logWarn(entry.rel)
+  for (const entry of result.withheld) {
+    if (entry.present) {
+      logWarn(`${entry.rel} is already here, and GitHub never reads this copy`)
+    }
+  }
+  logInfo(
+    'GitHub reads workflows only at the repository root. Add a root job that runs this folder with:',
+  )
+  logInfo(`working-directory: ${subfolderPath(target) ?? '.'}`)
+}
+
 function reportPackage(result: ScanResult): void {
   if (result.scripts.length > 0) {
     logStep('Scanning scripts')

package/src/design/components.ts

@@ -594,6 +594,23 @@ html.sb-shut .sb { flex-basis: 0; width: 0; overflow: hidden; }
 .sb-ws > summary:hover, .sb-ws[open] > summary { background: var(--color-chrome); color: var(--color-text); }
 .sb-ws .car { color: var(--color-muted); display: inline-flex; align-items: center; }
 
+/* The top band is as tall as the masthead and a mission title can run to a
+   sentence, so the name stops at two lines rather than overflowing the rule.
+   Nav carries the whole title in the element's \`title\` attribute. The cap
+   trim the crumb labels share is dropped here, since it ends the box at the
+   last baseline and the clip would cut every descender on the second line. */
+.sb-ws { min-width: 0; }
+.sb-ws .ws-name {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  overflow: hidden;
+  min-width: 0;
+  line-height: 1.2;
+  text-box: normal;
+}
+
 .sb-wl {
   position: absolute;
   top: calc(100% + 0.35rem);

package/src/design/tokens.ts

@@ -373,7 +373,7 @@ export const TOKENS: DesignTokens = {
   ],
 
   layout:
-    'Capture widths are 320, 768, 1280 and 1536 pixels, declared once in `tooling/web/configs/e2e/screenshot.ts`, with 320 and 1280 committed as evidence. 320 is the reflow floor and the rest are the breakpoint buckets. The landing page under `web/` sets its own `max-width` media queries between 430 and 1100 pixels per component rather than from a shared scale.',
+    'Capture widths are 320, 768, 1280 and 1536 pixels, declared once in `tooling/web/configs/e2e/screenshot.ts`, with 320 and 1280 committed as evidence. 320 is the reflow floor. Every range the width queries in the generated base and teach stylesheets lay out holds at least one of these widths, so a capture photographs every layout state those stylesheets have, and a design test fails when a query moves or is added so that it opens a range none of them reaches. The landing page under `web/` sets its own `max-width` media queries between 430 and 1100 pixels per component rather than from a shared scale.',
 
   motion:
     'Motion is not used. No transition, animation, or keyframe declaration appears on any rendered surface, and the capture pipeline screenshots a static frame.',

package/src/gate/measures.ts

@@ -103,11 +103,22 @@ const output = (text: string): Emission => ({ kind: 'output', text })
  * `snippets` as a folder-whole entry of its own and the rule reaches every base
  * consumer through that instead.
  *
- * Both are recorded here rather than in a config file: the list is what a
+ * `130-go`, `140-php`, `335-testing-go`, and `336-testing-php` are opt-in by
+ * `--add` until a Go or PHP stack ships, which `target-setup` reaches by
+ * matching a detected language against each rule's description.
+ *
+ * All are recorded here rather than in a config file: the list is what a
  * reader compares a new arrival against, and a config file would absorb the
  * arrival silently.
  */
-export const GOV_EXPECTED_UNREFERENCED = ['260-shadcn', '320-tanstack-query']
+export const GOV_EXPECTED_UNREFERENCED = [
+  '130-go',
+  '140-php',
+  '260-shadcn',
+  '320-tanstack-query',
+  '335-testing-go',
+  '336-testing-php',
+]
 
 /**
  * Scenarios declaring no expectation, taken from `canon sandbox coverage`

package/src/indexes/frontmatter.ts

@@ -11,12 +11,21 @@ export interface Frontmatter {
  * `raw` keeps the delimiters so an index can be rewritten with its own
  * frontmatter untouched, including comments and key order that a parse and
  * re-emit would lose.
+ *
+ * A block that will not parse reads as absent rather than throwing, so one
+ * malformed file reports through the path a caller already takes for a
+ * missing block instead of ending the caller's whole run.
  */
 export function parseFrontmatter(source: string): Frontmatter | undefined {
   const match = source.match(FRONTMATTER)
   if (!match) return undefined
 
-  const parsed = Bun.YAML.parse(match[1])
+  let parsed: unknown
+  try {
+    parsed = Bun.YAML.parse(match[1])
+  } catch {
+    return undefined
+  }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     return undefined
   }

package/src/pr/evidence.ts

@@ -106,8 +106,10 @@ export async function groupEvidence(
   return { kind: 'read', states }
 }
 
+// The raw host serves nothing to a private repository's browser, while the
+// blob form redirects to the bytes carrying the viewer's session.
 function rawUrl(repo: string, sha: string, path: string): string {
-  return `https://raw.githubusercontent.com/${repo}/${sha}/${path}`
+  return `https://github.com/${repo}/blob/${sha}/${path}?raw=true`
 }
 
 export function evidenceMarker(head: string): string {