@erclx/canon 5.3.0 → 5.5.0

package/src/audits/catalog.ts

@@ -140,7 +140,7 @@ function allOf(
 }
 
 /**
- * Reads the architecture record's three measures, or nothing when the project
+ * Reads the architecture record's measures, or nothing when the project
  * carries no record.
  *
  * Three states rather than two, matching what the verb publishes. The key
@@ -172,8 +172,11 @@ function architectureCounts(
   const entryCap =
     typeof record.entryCap === 'number' ? record.entryCap : undefined
 
+  const revisitRequired = record.revisitRequired === true
+
   let unverifiable = 0
   let unchecked = 0
+  let lackingRevisit = 0
   for (const raw of decisions) {
     const entry = asObject(raw)
     const claim = entry?.claim
@@ -182,6 +185,7 @@ function architectureCounts(
 
     if (claim === 'neither') unverifiable += 1
     else if (checks === 0) unchecked += 1
+    if (revisitRequired && entry?.revisit !== true) lackingRevisit += 1
   }
 
   return {
@@ -195,6 +199,8 @@ function architectureCounts(
     ...(entryCap !== undefined && {
       recordOverCount: decisions.length > entryCap ? 1 : 0,
     }),
+    // Absent on a record stating no revisit clause, for the same reason.
+    ...(revisitRequired && { recordMissingRevisit: lackingRevisit }),
     recordUnverifiable: unverifiable,
     recordUnchecked: unchecked,
   }

package/src/claude/cases/authoring.ts

@@ -5,11 +5,6 @@ import type { SkillCase } from '@/claude/skills-rank'
  * skills that revise rather than generate.
  */
 export const AUTHORING_CASES: readonly SkillCase[] = [
-  {
-    prompt:
-      'I need a shell tool with prompts and a nice terminal UI for people to run by hand.',
-    expect: 'bash-script',
-  },
   {
     prompt:
       'Wire up a GitHub Actions pipeline with parallel jobs for this repo.',

package/src/commands/context.ts

@@ -25,6 +25,7 @@ import {
   isOverCount,
   isOverLength,
   measureArchitecture,
+  missingRevisit,
   testableCount,
 } from '@/context/architecture'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -122,8 +123,10 @@ export function register(program: Command): void {
         'states its own line allowances gates when it is past the ceiling',
         'those derive, on any run except --citations-only, which never',
         'measures it. A record stating an entry cap gates the same way when',
-        'it holds more decisions than the cap. A record stating neither is',
-        'reported and never gated. --gate widens the gate to the other two',
+        'it holds more decisions than the cap, and a record stating that',
+        'every decision closes with a revisit sentence gates when one lacks',
+        'it. A record stating none of the three is reported and never',
+        'gated. --gate widens the gate to the other two',
         'findings that are facts rather than judgments: a missing required',
         'section and index drift. A context entry requires Overview and',
         'Layout, and a wireframe requires Regions, States, Copy, and Not on',
@@ -739,6 +742,8 @@ async function runAudit(
     unresolvedCitations: citations.unresolved.length,
     recordOverLength: record !== undefined && isOverLength(record),
     recordOverCount: record !== undefined && isOverCount(record),
+    recordMissingRevisit:
+      record !== undefined && missingRevisit(record).length > 0,
     sections,
     drift,
     wireframes,
@@ -1194,6 +1199,24 @@ function reportRecord(
     )
   }
 
+  const revisited = report.decisions.filter((entry) => entry.revisit).length
+  const lackingRevisit = missingRevisit(report)
+  if (!report.revisitRequired) {
+    logInfo(
+      `${revisited} of ${plural(decisions, 'decision')} close with a revisit sentence, and the record states no revisit clause, so this is reported and never gated.`,
+    )
+  } else if (lackingRevisit.length > 0) {
+    for (const heading of lackingRevisit) {
+      logError(
+        `"${heading}" carries no sentence opening "Revisit when", which the record requires of every decision.`,
+      )
+    }
+  } else {
+    logInfo(
+      `Every one of ${plural(decisions, 'decision')} closes with the revisit sentence the record requires.`,
+    )
+  }
+
   if (decisions === 0) {
     logWarn('The record declares no decision, so nothing was classified.')
     return

package/src/commands/pr.ts

@@ -462,6 +462,16 @@ export function register(program: Command): void {
         'comment. Together with --checklist it does, so the checklist and the',
         'link land in one comment.',
         '',
+        'Both reasons carry what the marked comment already posted, each field',
+        'present only when that comment holds it:',
+        '  preview    the hosted **Preview:** address the comment opens with',
+        '  local      the **Local preview:** address under it',
+        '  checklist  the checklist between its delimiters, ticks included',
+        'These come from the comment already posted, never from the flags this',
+        'call passed. A checklist posted on its own carries no marker, so the',
+        'record reports none of the three for it. An unread thread refuses as',
+        'gh-failed on both reasons rather than reporting the fields absent.',
+        '',
         'Exit codes:',
         '  0  read, whether it produced a body or reported no-evidence',
         '  1  refused, with the reason on stderr or in the JSON record',
@@ -1424,47 +1434,6 @@ async function runEvidence(
     baseTree.has(path),
   )
 
-  // A local address rides on a checklist or a hosted preview and never opens
-  // a comment alone, so a docs-only branch with a server up posts nothing.
-  const hasChecklistAndLocal =
-    suppliedChecklist !== undefined && opts.local !== undefined
-  if (
-    grouped.kind === 'refused' &&
-    opts.preview === undefined &&
-    !hasChecklistAndLocal
-  ) {
-    logStep('Skipped')
-    logInfo(
-      'No changed path carries an evidence/ segment, so there is nothing to post.',
-    )
-    outro()
-    if (emitJson) {
-      process.stdout.write(
-        `${JSON.stringify({
-          root,
-          ...(identity.number !== undefined && { number: identity.number }),
-          reason: 'no-evidence',
-        })}\n`,
-      )
-    }
-    return 0
-  }
-
-  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
-  const repo =
-    repoRow === null
-      ? undefined
-      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
-
-  if (repo === undefined) {
-    return refuseWith(
-      'gh-failed',
-      EVIDENCE_REFUSALS['gh-failed'],
-      emitJson,
-      root,
-    )
-  }
-
   let commentId: number | undefined
   let carriedPreview: string | undefined
   let carriedChecklist: string | undefined
@@ -1480,6 +1449,8 @@ async function runEvidence(
     // An unread thread refuses rather than rendering, since a body built
     // without it knows neither the comment to edit nor the preview address
     // to carry, and posting it would duplicate the comment and drop the link.
+    // It refuses ahead of no-evidence too, so that record never reports an
+    // absent field it did not read.
     let comments: readonly { url?: string; body: string }[] | undefined
     if (commentsRow !== null) {
       try {
@@ -1506,6 +1477,56 @@ async function runEvidence(
     carriedLocal = findEvidenceLocal(comments)
   }
 
+  // What the marked comment already shows a reviewer, kept apart from the
+  // flags this call passed so a reader learns what is posted.
+  const carried = {
+    ...(carriedPreview !== undefined && { preview: carriedPreview }),
+    ...(carriedLocal !== undefined && { local: carriedLocal }),
+    ...(carriedChecklist !== undefined && { checklist: carriedChecklist }),
+  }
+
+  // A local address rides on a checklist or a hosted preview and never opens
+  // a comment alone, so a docs-only branch with a server up posts nothing.
+  const hasChecklistAndLocal =
+    suppliedChecklist !== undefined && opts.local !== undefined
+  if (
+    grouped.kind === 'refused' &&
+    opts.preview === undefined &&
+    !hasChecklistAndLocal
+  ) {
+    logStep('Skipped')
+    logInfo(
+      'No changed path carries an evidence/ segment, so there is nothing to post.',
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          ...(identity.number !== undefined && { number: identity.number }),
+          reason: 'no-evidence',
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  const repoRow = await gh(root, ['repo', 'view', '--json', 'nameWithOwner'])
+  const repo =
+    repoRow === null
+      ? undefined
+      : (JSON.parse(repoRow) as { nameWithOwner?: string }).nameWithOwner
+
+  if (repo === undefined) {
+    return refuseWith(
+      'gh-failed',
+      EVIDENCE_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+    )
+  }
+
   const preview = opts.preview ?? carriedPreview
   const local = opts.local ?? carriedLocal
   const checklist = suppliedChecklist ?? carriedChecklist
@@ -1548,6 +1569,7 @@ async function runEvidence(
         head: identity.head,
         body,
         ...(commentId !== undefined && { commentId }),
+        ...carried,
       })}\n`,
     )
   }

package/src/commands/serve.ts

@@ -1,7 +1,6 @@
 import type { Command } from 'commander'
-import { relative } from 'node:path'
-import { DEFAULT_PORT, type ServeOutcome, startServer } from '@/serve/static'
-import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+import { parsePort, report, waitForInterrupt } from '@/serve/report'
+import { DEFAULT_PORT, startServer } from '@/serve/static'
 
 const DEFAULT_DIR = '.'
 
@@ -78,92 +77,3 @@ async function runServe(
   await waitForInterrupt(outcome.stop)
   return 0
 }
-
-/**
- * The relative path where it stays inside the working directory, and the
- * absolute one where it climbs out. A run from a linked worktree serving the
- * main root reports `../../teach`, which names the directory without giving a
- * reader anything they can open.
- */
-function displayPath(root: string): string {
-  const near = relative(process.cwd(), root)
-  if (near === '') return '.'
-  return near.startsWith('..') ? root : near
-}
-
-/**
- * Undefined for a value that is not a port, distinct from an absent flag,
- * which takes the default. A `Number` of a typo is `NaN`, and passing that on
- * asks the runtime to bind a port nobody named.
- */
-function parsePort(raw: string | undefined): number | undefined {
-  if (raw === undefined) return DEFAULT_PORT
-  const value = Number(raw)
-  if (!Number.isInteger(value) || value < 0 || value > 65535) return undefined
-  return value
-}
-
-function report(outcome: ServeOutcome, emitJson: boolean): number {
-  if (!outcome.ok) {
-    if (emitJson) {
-      process.stdout.write(
-        `${JSON.stringify({ ok: false, reason: outcome.reason, detail: outcome.detail })}\n`,
-      )
-      return 1
-    }
-    intro('canon serve')
-    logError(outcome.detail)
-    outro()
-    return 1
-  }
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({
-        ok: true,
-        root: outcome.root,
-        host: outcome.host,
-        port: outcome.port,
-        entry: outcome.entry,
-        url: outcome.url,
-        entryExists: outcome.entryExists,
-      })}\n`,
-    )
-    return 0
-  }
-
-  intro('canon serve')
-  logStep('Serving')
-  logInfo(displayPath(outcome.root))
-  logStep('Open')
-  logInfo(outcome.url)
-
-  if (!outcome.entryExists) {
-    logStep('No entry page')
-    logWarn(
-      `${outcome.entry} is not in that directory, so the link opens a 404`,
-    )
-  }
-
-  logStep('Stop')
-  logInfo('Ctrl-C')
-  return 0
-}
-
-/**
- * Resolves when the process is asked to stop. The frame is closed here rather
- * than in the reporter, because the run is the serving rather than the start,
- * and closing at start would print the frame's end while the server ran on.
- */
-function waitForInterrupt(stop: () => Promise<void>): Promise<void> {
-  return new Promise((settle) => {
-    const finish = () => {
-      void stop().then(() => {
-        outro()
-        settle()
-      })
-    }
-    process.once('SIGINT', finish)
-    process.once('SIGTERM', finish)
-  })
-}

package/src/commands/teach.ts

@@ -1,7 +1,14 @@
 import { isAbsolute, relative, resolve, sep } from 'node:path'
 import type { Command } from 'commander'
+import {
+  logServing,
+  parsePort,
+  serveFields,
+  waitForInterrupt,
+} from '@/serve/report'
+import { DEFAULT_PORT, startServer } from '@/serve/static'
 import { type LessonOutcome, planLesson } from '@/teach/lesson'
-import { type NavOutcome, generateNav } from '@/teach/nav'
+import { type NavGenerated, type NavOutcome, generateNav } from '@/teach/nav'
 import type { RenderOutcome } from '@/teach/render'
 import {
   defineTerms,
@@ -83,6 +90,12 @@ interface NavCommandOptions {
   readonly root?: string
 }
 
+interface UpCommandOptions {
+  readonly json?: boolean
+  readonly port?: string
+  readonly root?: string
+}
+
 interface RenderCommandOptions {
   readonly json?: boolean
 }
@@ -96,11 +109,12 @@ export function register(program: Command): void {
       'after',
       [
         '',
-        'Opening a workspace:',
-        '  canon serve .canon/teach --entry <nn>-<topic>/index.html',
+        'Viewing a workspace:',
+        '  canon teach up <topic>',
         '',
-        'canon teach list <topic> prints the exact line, with the teach folder',
-        'written from where you stand rather than as this literal.',
+        'It refreshes the chrome and serves the workspace. To serve without',
+        'rewriting anything, canon teach list <topic> prints the canon serve',
+        'line, with the teach folder written from where you stand.',
         '',
       ].join('\n'),
     )
@@ -178,6 +192,7 @@ export function register(program: Command): void {
         'It derives the ordinal from the highest already present and writes',
         'MISSION.md, RESOURCES.md, and GLOSSARY.md. A topic another workspace',
         'already covers is refused, since a second one forks the records.',
+        'It creates a workspace and serves nothing: canon teach up views one.',
         '',
         'Examples:',
         '  canon teach open regular-expressions --subject "Reading and writing regular expressions" \\',
@@ -365,6 +380,10 @@ export function register(program: Command): void {
         'the prev/next footer nav, and the behavior scripts. The authored',
         '<h1>, lede, body, and quiz are left untouched.',
         '',
+        "A workspace's generated assets/base.css is rewritten on every run, so",
+        'a CLI upgrade reaches it. Its course.css is never rewritten, and a',
+        'workspace holding only a course.css is not given a base.css.',
+        '',
         'A lesson missing one of the four chrome markers is refused rather',
         "than rewritten, reported by name in the JSON record's skipped list",
         'and on stderr, while every other lesson still rewrites.',
@@ -379,6 +398,45 @@ export function register(program: Command): void {
       process.exitCode = await runNav(topic, opts)
     })
 
+  teach
+    .command('up')
+    .description('Refresh the chrome with nav, then serve the teach folder')
+    .argument('[topic]', 'Workspace folder or topic the printed link opens')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--port <number>', `Port to try first, default ${DEFAULT_PORT}`)
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Teach root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the server stopped after running',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Runs the nav pass for the topic, or for every workspace when none is',
+        'named, then serves the teach folder through the same server as',
+        'canon serve. The link opens the topic contents page, or the root',
+        'listing with no topic. A lesson nav skips is reported and the server',
+        'still starts, while a nav refusal starts no server.',
+        '',
+        'Viewing writes: every page and generated stylesheet nav owns is',
+        'rewritten first. canon teach list <topic> prints a canon serve line',
+        'that serves without rewriting.',
+        '',
+        'It runs until interrupted. A session wanting the link without waiting',
+        'starts it in the background and reads the record off stdout.',
+        '',
+        'Examples:',
+        '  canon teach up regular-expressions',
+        '  canon teach up --port 4000 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string | undefined, opts: UpCommandOptions) => {
+      process.exitCode = await runUp(topic, opts)
+    })
+
   teach
     .command('render')
     .description('Render a lesson body block list to HTML')
@@ -805,21 +863,29 @@ function reportNav(
     return reportRefusal('canon teach nav', outcome, emitJson, root)
 
   if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({
-        ok: true,
-        root: outcome.root,
-        contents: outcome.contents,
-        lessons: outcome.lessons,
-        reference: outcome.reference,
-        skipped: outcome.skipped,
-        unresolved: outcome.unresolved,
-      })}\n`,
-    )
+    process.stdout.write(`${JSON.stringify(navFields(outcome))}\n`)
     return 0
   }
 
   intro('canon teach nav')
+  logNav(outcome)
+  outro()
+  return 0
+}
+
+function navFields(outcome: NavGenerated): Record<string, unknown> {
+  return {
+    ok: true,
+    root: outcome.root,
+    contents: outcome.contents,
+    lessons: outcome.lessons,
+    reference: outcome.reference,
+    skipped: outcome.skipped,
+    unresolved: outcome.unresolved,
+  }
+}
+
+function logNav(outcome: NavGenerated): void {
   logStep('Root')
   logInfo(outcome.root)
   logStep('Contents')
@@ -842,8 +908,67 @@ function reportNav(
       logWarn(`${reference.file}: lesson ${reference.lesson}`)
     }
   }
+}
 
-  outro()
+async function runUp(
+  topic: string | undefined,
+  opts: UpCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = await rootFor(opts.root)
+
+  const port = parsePort(opts.port)
+  if (port === undefined) {
+    return reportRefusal(
+      'canon teach up',
+      badInput(`${opts.port} is not a port`),
+      emitJson,
+      root,
+    )
+  }
+
+  const nav = await generateNav(root, topic)
+  if (!nav.ok) return reportRefusal('canon teach up', nav, emitJson, root)
+
+  // The server resolves its folder against the cwd, and the teach folder sits
+  // at the main worktree root, so it takes the absolute path a linked
+  // worktree can still reach.
+  const dir = resolve(teachDir(root))
+  const contents = nav.contents[0]
+  const entry =
+    topic === undefined || contents === undefined
+      ? 'index.html'
+      : relative(dir, resolve(root, contents)).split(sep).join('/')
+
+  const served = startServer(dir, { port, entry })
+  if (!served.ok) {
+    // 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) {
+      process.stderr.write(`${served.detail}\n`)
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, root, reason: served.reason, message: served.detail, detail: [] })}\n`,
+      )
+      return 1
+    }
+    intro('canon teach up')
+    logStep('Refused')
+    logError(served.detail)
+    outro()
+    return 1
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ...navFields(nav), served: served.root, ...serveFields(served) })}\n`,
+    )
+  } else {
+    intro('canon teach up')
+    logNav(nav)
+    logServing(served)
+  }
+
+  await waitForInterrupt(served.stop)
   return 0
 }