@erclx/canon 5.25.0 → 5.26.0

package/src/secrets/marker.ts

@@ -1,9 +1,9 @@
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 /**
  * The inline token exempting one line from the secret scan.
  *
- * Shaped on the `stub: true` precedent in `src/seed-marker.ts`, which answers
+ * Shaped on the `stub: true` precedent in `src/tooling/seed-marker.ts`, which answers
  * a check whose own comment records a false-positive class. The exemption
  * travels with the line it exempts rather than sitting in a path list away
  * from it, so a reader meeting a muted match finds the reason on the spot.

package/src/secrets/scan.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { listRepositoryFiles } from '@/git-files'
 import { isExempt } from '@/secrets/marker'
 import { matchLine } from '@/secrets/patterns'

package/src/shipped/references.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 /**
  * The corpora a target reader reaches, which is the `files` field less `src`.
@@ -113,7 +113,7 @@ const COMMIT_SHA = /(?<![0-9A-Za-z_@/#])([0-9a-f]{7,40})(?![0-9A-Za-z_])/g
  * one.
  *
  * The literal is hardcoded rather than read from `package.json` or
- * `git remote`, matching `src/github-format.ts` and `src/commands/repo.ts`,
+ * `git remote`, matching `src/feedback/github-format.ts` and `src/commands/repo.ts`,
  * which already hardcode it.
  *
  * Same word-boundary discipline as the two patterns above: a word character

package/src/slides/convert/export.ts

@@ -1,10 +1,4 @@
-import {
-  copyFileSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-} from 'node:fs'
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import JSZip from 'jszip'
@@ -42,6 +36,7 @@ import {
   type WalkedSlide,
   walkSlide,
 } from '@/slides/convert/walk'
+import { slideFiles } from '@/slides/decks'
 import { embedFonts, type FontNotice } from '@/slides/package/fonts'
 import {
   type EntranceSpec,
@@ -127,15 +122,6 @@ function refused(reason: ExportRefusal, message: string): ExportResult {
   return { status: 'refused', reason, message }
 }
 
-/** Every `.html` file directly in the folder, in filename order. */
-export function slideFiles(sourceDir: string): string[] {
-  return readdirSync(sourceDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
-    .map((entry) => entry.name)
-    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
-    .map((name) => join(sourceDir, name))
-}
-
 /** A picture whose bytes the post-write pass replaces or whose corners it rounds. */
 interface Patch {
   readonly slide: number

package/src/slides/decks.ts

@@ -0,0 +1,110 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { creationRel, recordDir } from '@/record-root'
+import { readDeck } from '@/slides/convert/deck'
+
+/**
+ * A deck is a folder under the record root's `slides/`, holding its `.html`
+ * slides, an optional `deck.json`, and its assets. `layouts/` beside the decks
+ * holds the project's shared layouts and is never a deck itself.
+ */
+export const SLIDES_FOLDER = 'slides'
+
+export const LAYOUTS_FOLDER = 'layouts'
+
+export interface Deck {
+  readonly name: string
+  /** From `deck.json`, falling back to the folder name as the export does. */
+  readonly title: string
+  readonly slides: number
+  /** Relative to the project root. */
+  readonly path: string
+}
+
+export type DeckRefusal = 'no-decks' | 'ambiguous' | 'no-deck'
+
+export type DeckResolution =
+  | { readonly status: 'resolved'; readonly dir: string }
+  | {
+      readonly status: 'refused'
+      readonly reason: DeckRefusal
+      readonly message: string
+    }
+
+/** Every `.html` file directly in the folder, in filename order. */
+export function slideFiles(dir: string): string[] {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.html'))
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .map((name) => join(dir, name))
+}
+
+export function listDecks(root: string): Deck[] {
+  const dir = recordDir(root, SLIDES_FOLDER)
+  if (!isDirectory(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== LAYOUTS_FOLDER)
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((name) => {
+      const deckDir = join(dir, name)
+      const slides = slideFiles(deckDir).length
+      if (slides === 0) return []
+      const read = readDeck(deckDir)
+      const title = read.status === 'read' ? read.deck.title : name
+      return [{ name, title, slides, path: relative(root, deckDir) }]
+    })
+}
+
+/**
+ * The folder `render` reads. A deck name wins over a folder of the same name
+ * relative to the root, and no name at all takes the only deck there is.
+ */
+export function resolveDeck(
+  root: string,
+  target: string | undefined,
+): DeckResolution {
+  const decks = listDecks(root)
+  const at = creationRel(root, SLIDES_FOLDER)
+
+  if (target === undefined) {
+    const [only, ...rest] = decks
+    if (only === undefined) {
+      return refuse('no-decks', `No deck under ${at}/. Draw one there first.`)
+    }
+    if (rest.length > 0) {
+      return refuse(
+        'ambiguous',
+        `${decks.length} decks under ${at}/, name one: ${names(decks)}`,
+      )
+    }
+    return { status: 'resolved', dir: join(root, only.path) }
+  }
+
+  const named = decks.find((deck) => deck.name === target)
+  if (named) return { status: 'resolved', dir: join(root, named.path) }
+
+  const folder = resolve(root, target)
+  if (isDirectory(folder)) return { status: 'resolved', dir: folder }
+
+  return refuse(
+    'no-deck',
+    decks.length === 0
+      ? `${target} is neither a deck under ${at}/ nor a folder`
+      : `${target} is neither a deck nor a folder. Decks: ${names(decks)}`,
+  )
+}
+
+function names(decks: readonly Deck[]): string {
+  return decks.map((deck) => deck.name).join(', ')
+}
+
+function refuse(reason: DeckRefusal, message: string): DeckResolution {
+  return { status: 'refused', reason, message }
+}
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && statSync(path).isDirectory()
+}

package/src/standards/read.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { basename, join } from 'node:path'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
 
 export const INDEX_FILE = 'index.md'

package/src/sync/seeds-report.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs'
 import { relative } from 'node:path'
 import { planSeeds, type Seed } from '@/claude/seeds'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { findInstalledOrigin, readHistoryIndex } from '@/sync/history'
 
 /**

package/src/tasks/answers.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { isAbsolute, relative, resolve } from 'node:path'
-import { isUnder } from '@/paths'
+import { isUnder } from '@/tasks/paths'
 import { recordDir, recordDirs } from '@/record-root'
 import {
   hasStagedBatches,

package/src/tasks/archive.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve, sep } from 'node:path'
 import { regenOne } from '@/indexes/regen'
-import { isUnder } from '@/paths'
+import { isUnder } from '@/tasks/paths'
 import { recordDir, recordDirs } from '@/record-root'
 
 const TASKS = 'tasks'

package/src/teach/nav.ts

@@ -7,7 +7,7 @@ import {
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
-import { stripFrontmatter } from '@/frontmatter'
+import { stripFrontmatter } from '@/markdown/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
 import { compileScript } from '@/teach/browser/compile'

package/src/tooling/inject.ts

@@ -3,7 +3,7 @@ import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'
 import { $ } from 'bun'
 import { copyPreservingMode } from '@/copy'
-import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { rewritesOnInstall, stripSeedMarker } from '@/tooling/seed-marker'
 import { resolveSurfacePath } from '@/surface-root'
 import { mergeSections, pruneSections } from '@/tooling/gitignore'
 import {

package/src/web/readme-citations.ts

@@ -1,4 +1,4 @@
-import { isMarked } from '@/exempt-marker'
+import { isMarked } from '@/sweep/exempt-marker'
 
 export const README_PARAPHRASE_MARKER = 'canon-allow-readme-paraphrase'
 

package/standards/architecture.md

@@ -54,6 +54,7 @@ Use `## Overview`, `## Key technical decisions` with one named H3 per decision,
 
 - Rewrite a decision a later one changed rather than appending the change beside it. A reader should find the design that stands in one place, with the alternative that lost stated once.
 - Hold only what is open under `## Risks / open questions`. An entry leaves the section in the change that settles it, becoming a decision here when it fills a slot and moving to the domain context entry it constrains when it does not.
+- Carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read the record whole for drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
 
 ## Verification anchors
 

package/standards/canvas.md

@@ -78,7 +78,7 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 - Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
 - Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
 - Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
-- Do not assume a default font. Set `font-family` on the `html` element with an installed family first, since a capture checks the root's first family and the browser's default serif is absent from many machines.
+- Do not assume a default font. Set `font-family` with an installed family first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or its wireframes, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 

package/standards/requirements.md

@@ -46,6 +46,8 @@ This file loads into every session, so its weight is paid before any work starts
 
 Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.
 
+The record may carry an optional `reviewed: YYYY-MM-DD` frontmatter field naming the day someone last read it whole for identity drift. Whoever finishes that review sets it as the review's last edit, and `canon records stale canonical` reads it to count the releases shipped since. A record with no field reads as never reviewed.
+
 Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness, so a section here states what is wanted and never when it lands.
 
 ## Distribution

package/standards/skill-practice.md

@@ -47,5 +47,6 @@ A practice skill failing any of these is non-conforming even when every heading
 ## Which skills are practice skills
 
 - `canon claude skills audit` keeps the list of practice skills and checks each listed one for the three closing sections and the ledger.
+- It keeps a wider ledger list beside it, holding every practice skill plus the skills that teach a craft drawn from outside sources without a practice's closing shape. A skill on the wider list alone owes the ledger and none of the three sections.
 - Never mark a skill as a practice skill in its own frontmatter, since a self-declared kind lets a skill exempt itself.
-- The list names this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.
+- Both lists name this toolkit's shipped skills alone, so a project's own practice skill takes this shape with no check behind it.

package/standards/skill.md

@@ -130,6 +130,7 @@ allowed-tools: <tools required>
 - Below the ceiling, name the branch that skips a block before moving it. A block every run dereferences costs a read and saves nothing.
 - Past the ceiling, move a whole step to a reference, preferring a step a named branch skips. Keep the step heading in the body with one line naming the file to read on reaching it, so the body still shows every step in order.
 - Name every file under `references/` in the body at the point a session reads it, since an unnamed reference is never loaded.
+- Open a file under `references/` running over 100 lines with a `## Contents` H2 of anchor links after its H1 and intro, so a session that reads only the top of the file still sees everything it holds.
 - Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
 - Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.