@erclx/canon 5.4.0 → 5.5.0

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
 }
 

package/src/context/architecture.ts

@@ -63,6 +63,12 @@ export interface DecisionReport {
    * it. Never gates, per `standards/architecture.md`'s `## Length` section.
    */
   readonly words: number
+  /**
+   * Whether a sentence outside code opens with `Revisit when`. Read on every
+   * record and required only by one stating the clause, so a project that
+   * never adopted it sees the reading without failing on it.
+   */
+  readonly revisit: boolean
 }
 
 export interface ArchitectureReport {
@@ -86,6 +92,12 @@ export interface ArchitectureReport {
    * project that never adopted a cap is measured and never gated.
    */
   readonly entryCap?: number
+  /**
+   * Whether the record states that every decision closes with a revisit
+   * sentence. Declared by the record for the reason the cap is, so a record
+   * that never wrote the clause is reported and never gated.
+   */
+  readonly revisitRequired: boolean
   readonly decisions: readonly DecisionReport[]
 }
 
@@ -214,6 +226,8 @@ interface RawDecision {
   readonly heading: string
   readonly line: number
   readonly body: string
+  /** The body with its fenced lines dropped, which is where prose is read. */
+  readonly prose: string
 }
 
 /**
@@ -230,7 +244,19 @@ interface RawDecision {
 export function splitDecisions(source: string): RawDecision[] {
   const lines = bodyLines(source)
   const decisions: RawDecision[] = []
-  let open: { heading: string; line: number; body: string[] } | undefined
+  let open:
+    | { heading: string; line: number; body: string[]; prose: string[] }
+    | undefined
+
+  const close = (): void => {
+    if (!open) return
+    decisions.push({
+      heading: open.heading,
+      line: open.line,
+      body: open.body.join('\n'),
+      prose: open.prose.join('\n'),
+    })
+  }
 
   for (const line of lines) {
     if (line.fenced) {
@@ -240,23 +266,24 @@ export function splitDecisions(source: string): RawDecision[] {
 
     const heading = line.text.match(DECISION_HEADING)?.[1]
     if (heading !== undefined) {
-      if (open) decisions.push({ ...open, body: open.body.join('\n') })
-      open = { heading, line: line.number, body: [] }
+      close()
+      open = { heading, line: line.number, body: [], prose: [] }
       continue
     }
 
     // A decision runs to the next `###` or to the section that follows the
     // decision list, so the risks below never read as the last entry's body.
     if (SECTION_HEADING.test(line.text)) {
-      if (open) decisions.push({ ...open, body: open.body.join('\n') })
+      close()
       open = undefined
       continue
     }
 
     open?.body.push(line.text)
+    open?.prose.push(line.text)
   }
 
-  if (open) decisions.push({ ...open, body: open.body.join('\n') })
+  close()
   return decisions
 }
 
@@ -383,6 +410,41 @@ export function readEntryCap(source: string): number | undefined {
   return readCardinal(source.match(ENTRY_CAP_CLAUSE)?.[1])
 }
 
+const REVISIT_CLAUSE =
+  /\bevery\s+decision\s+closes\s+with\s+a\s+revisit\s+sentence\b/i
+/**
+ * `Revisit when` opening a sentence: at the start of the text, after a line
+ * break, or after a sentence's closing stop. Mid-sentence it is not the
+ * sentence the standard asks for.
+ */
+const REVISIT_SENTENCE = /(?:^|\n|[.!?]\s+)\s*(?:[-*]\s+)?Revisit when\b/
+
+/**
+ * Whether the record states the revisit clause for itself, read off its prose
+ * alone so a template quoting the clause inside a fence does not adopt it.
+ *
+ * The clause is the record's own, like the cap, so wording that drifts past it
+ * falls back to reporting rather than to a requirement held here.
+ */
+export function readRevisitRule(source: string): boolean {
+  const prose = bodyLines(source)
+    .filter((line) => !line.fenced)
+    .map((line) => line.text)
+    .join('\n')
+    .replace(CODE_SPAN, ' ')
+  return REVISIT_CLAUSE.test(prose)
+}
+
+/**
+ * Whether a decision's prose carries a sentence opening `Revisit when`.
+ *
+ * Presence only, never content, so a vacuous sentence passes. A code span is
+ * dropped first, since a standard quoting the form is not stating one.
+ */
+export function hasRevisitSentence(prose: string): boolean {
+  return REVISIT_SENTENCE.test(prose.replace(CODE_SPAN, ' '))
+}
+
 /** Whether a read failed because nothing sits at the path. */
 function isMissing(error: unknown): boolean {
   const code = (error as { code?: unknown }).code
@@ -421,6 +483,7 @@ export async function measureArchitecture(
 
   const allowances = readAllowances(source)
   const entryCap = readEntryCap(source)
+  const revisitRequired = readRevisitRule(source)
   const raw = splitDecisions(source)
   const decisions = await Promise.all(
     raw.map(async (entry) => {
@@ -433,6 +496,7 @@ export async function measureArchitecture(
         ...(quantified !== undefined && { quantified }),
         checks: await namedChecks(root, entry.body),
         words: wordCount(entry.body),
+        revisit: hasRevisitSentence(entry.prose),
       }
     }),
   )
@@ -453,6 +517,7 @@ export async function measureArchitecture(
       ceiling: ceilingFor(allowances, raw.length),
     }),
     ...(entryCap !== undefined && { entryCap }),
+    revisitRequired,
     decisions,
   }
 }
@@ -470,6 +535,18 @@ export function isOverCount(report: ArchitectureReport): boolean {
   )
 }
 
+/**
+ * The headings of decisions lacking a revisit sentence the record requires.
+ *
+ * Empty for a record stating no clause, for the reason `isOverCount` gives.
+ */
+export function missingRevisit(report: ArchitectureReport): string[] {
+  if (!report.revisitRequired) return []
+  return report.decisions
+    .filter((entry) => !entry.revisit)
+    .map((entry) => entry.heading)
+}
+
 /**
  * Whether the record is longer than the ceiling it derives for itself.
  *

package/src/context/gate.ts

@@ -19,6 +19,12 @@ export interface GateInput {
    * gates under the same two modes and is false in the same two cases.
    */
   readonly recordOverCount: boolean
+  /**
+   * Whether a decision lacks the revisit sentence the record requires of
+   * every decision, which gates under the same two modes and is false in the
+   * same two cases, plus a record stating no such clause.
+   */
+  readonly recordMissingRevisit: boolean
   readonly sections: readonly SectionFinding[]
   readonly drift: readonly FolderDrift[]
   /**
@@ -73,8 +79,8 @@ export function hasSketchWithEvidence(
  * Whether the audit found something that should fail the caller.
  *
  * An unresolved citation is a broken pointer and gates unconditionally, and so
- * does a record past its own ceiling or its own entry cap: the record states
- * each limit for itself, which makes those the measures here that are facts
+ * does a record past its own ceiling or its own entry cap, or missing a
+ * revisit sentence it requires: the record states each rule for itself, which makes those the measures here that are facts
  * rather than thresholds a reader weighs. The findings `--gate` adds are
  * the ones answerable from the file itself: a required section it does not
  * declare, an index disagreeing with its folder, and a wireframe's States
@@ -88,13 +94,14 @@ export function isGating({
   unresolvedCitations,
   recordOverLength,
   recordOverCount,
+  recordMissingRevisit,
   sections,
   drift,
   wireframes,
   widened,
 }: GateInput): boolean {
   if (unresolvedCitations > 0) return true
-  if (recordOverLength || recordOverCount) return true
+  if (recordOverLength || recordOverCount || recordMissingRevisit) return true
   if (!widened) return false
 
   return sections.length > 0 || hasDrift(drift) || hasStatesMismatch(wireframes)

package/src/gate/measures.ts

@@ -11,6 +11,7 @@ import {
   isOverCount,
   isOverLength,
   measureArchitecture,
+  missingRevisit,
 } from '@/context/architecture'
 import { auditSkills } from '@/claude/skills-audit'
 import { listRepositoryFiles } from '@/git-files'
@@ -239,14 +240,15 @@ function citedPaths(record: { paths?: unknown } | undefined): string[] {
 }
 
 /**
- * The architecture record against the two limits it states for itself: the
- * line ceiling its allowances derive and the entry cap.
+ * The architecture record against the three rules it states for itself: the
+ * line ceiling its allowances derive, the entry cap, and the revisit sentence
+ * closing each decision.
  *
  * Read in-process rather than through `context audit`, whose one gating stage
  * here runs `--citations-only` and never opens the record, which is why the
  * line ceiling went unenforced by `bun run check` until this stage. A project
- * carrying no record, or a record stating neither limit, passes, since both
- * limits belong to the record rather than to the toolkit.
+ * carrying no record, or a record stating none of the three, passes, since
+ * each rule belongs to the record rather than to the toolkit.
  */
 export const architectureRecord: Measure = async (ctx) => {
   const report = await measureArchitecture(ctx.root)
@@ -255,11 +257,14 @@ export const architectureRecord: Measure = async (ctx) => {
   }
 
   const decisions = report.decisions.length
+  const lackingRevisit = missingRevisit(report)
   const failures = [
     isOverCount(report) &&
       `${decisions} decisions against a cap of ${report.entryCap}. Merge two or retire one in ${report.rel}, never compress.`,
     isOverLength(report) &&
       `${report.lines} lines against a ceiling of ${report.ceiling} in ${report.rel}.`,
+    lackingRevisit.length > 0 &&
+      `No revisit sentence in ${lackingRevisit.map((heading) => `"${heading}"`).join(', ')}. Close each with one opening "Revisit when" in ${report.rel}.`,
   ].filter((failure): failure is string => typeof failure === 'string')
 
   if (failures.length > 0) return { emissions: [], failure: failures.join(' ') }

package/src/gate/stages.ts

@@ -354,7 +354,7 @@ export const STAGES: readonly Stage[] = [
     success: 'Context citations resolve',
   },
   {
-    // The record's two limits are facts it states about itself, unlike the
+    // The record's three rules are facts it states about itself, unlike the
     // judgment thresholds the stage above leaves out, so they gate here.
     id: 'architecture-record',
     label: 'Architecture record',

package/src/serve/report.ts

@@ -0,0 +1,110 @@
+import { relative } from 'node:path'
+import {
+  DEFAULT_PORT,
+  type ServeOutcome,
+  type ServeStarted,
+} from '@/serve/static'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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
+}
+
+/** The fields a started server reports, shared by every command that serves. */
+export function serveFields(outcome: ServeStarted): {
+  readonly host: string
+  readonly port: number
+  readonly entry: string
+  readonly url: string
+  readonly entryExists: boolean
+} {
+  return {
+    host: outcome.host,
+    port: outcome.port,
+    entry: outcome.entry,
+    url: outcome.url,
+    entryExists: outcome.entryExists,
+  }
+}
+
+/** The steps a framed report prints for a running server, inside its frame. */
+export function logServing(outcome: ServeStarted): void {
+  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')
+}
+
+export 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, ...serveFields(outcome) })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon serve')
+  logServing(outcome)
+  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.
+ */
+export 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)
+  })
+}