@erclx/canon 4.0.0

package/src/slides/open.ts

@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs'
+import { execa } from 'execa'
+
+export async function openDeck(path: string): Promise<boolean> {
+  const windowsPath = await execa('wslpath', ['-w', path], { reject: false })
+  if (windowsPath.exitCode === 0) {
+    const cwd = existsSync('/mnt/c') ? '/mnt/c' : undefined
+    const result = await execa(
+      'cmd.exe',
+      ['/c', 'start', '', windowsPath.stdout.trim()],
+      { cwd, reject: false },
+    )
+    return result.exitCode === 0
+  }
+  const opener = process.platform === 'darwin' ? 'open' : 'xdg-open'
+  const result = await execa(opener, [path], { reject: false })
+  return result.exitCode === 0
+}

package/src/slides/parse.ts

@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs'
+import type { Variant } from '@/slides/styles'
+
+export interface DeckMeta {
+  title: string
+  variant: Variant
+}
+
+export interface Slide {
+  layout: string
+  title: string
+  content: string[]
+}
+
+export interface Deck {
+  meta: DeckMeta
+  slides: Slide[]
+}
+
+const DEFAULT_META: DeckMeta = {
+  title: '',
+  variant: 'light',
+}
+
+export function parseSlidesDoc(path: string): Deck {
+  return parseSlides(readFileSync(path, 'utf8'))
+}
+
+export function parseSlides(raw: string): Deck {
+  const { meta, body } = splitFrontmatter(raw)
+  const slides = body
+    .split(/^---\s*$/m)
+    .map(parseSlide)
+    .filter((slide): slide is Slide => slide !== null)
+  return { meta, slides }
+}
+
+function splitFrontmatter(raw: string): { meta: DeckMeta; body: string } {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?/)
+  if (!match) return { meta: { ...DEFAULT_META }, body: raw }
+  return { meta: parseMeta(match[1]), body: raw.slice(match[0].length) }
+}
+
+function parseMeta(block: string): DeckMeta {
+  const meta: DeckMeta = { ...DEFAULT_META }
+  for (const line of block.split('\n')) {
+    const match = line.match(/^(\w+):\s*(.+?)\s*$/)
+    if (!match) continue
+    const [, key, value] = match
+    if (key === 'title') meta.title = value
+    if (key === 'variant' && (value === 'light' || value === 'dark')) {
+      meta.variant = value
+    }
+  }
+  return meta
+}
+
+function parseSlide(chunk: string): Slide | null {
+  let title = ''
+  let layout = ''
+  const content: string[] = []
+  for (const line of chunk.split('\n')) {
+    const heading = line.match(/^#\s+(.+?)\s*$/)
+    const declared = line.match(/^layout:\s*(.+?)\s*$/)
+    if (heading && !title) {
+      title = heading[1]
+      continue
+    }
+    if (declared && !layout) {
+      layout = declared[1].trim()
+      continue
+    }
+    content.push(line)
+  }
+  const trimmed = content.filter((line) => line.trim())
+  if (!title && !layout && trimmed.length === 0) return null
+  return { layout: layout || inferLayout(trimmed), title, content: trimmed }
+}
+
+function inferLayout(content: string[]): string {
+  return content.some((line) => line.trim().startsWith('-'))
+    ? 'bullets'
+    : 'title'
+}

package/src/slides/render.ts

@@ -0,0 +1,88 @@
+import { copyFileSync, mkdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import PptxGenJS from 'pptxgenjs'
+import {
+  addFooter,
+  type DeckNav,
+  renderDeckSlide,
+  renderToc,
+} from '@/slides/layouts'
+import { type Deck, parseSlidesDoc } from '@/slides/parse'
+import { buildTheme, type Variant } from '@/slides/styles'
+
+export interface RenderResult {
+  pptxPath: string
+  mirrorPath?: string
+  slideCount: number
+}
+
+export interface RenderOptions {
+  variant?: Variant
+  mirror?: string
+}
+
+export async function renderSlidesDoc(
+  sourcePath: string,
+  outDir: string,
+  options: RenderOptions = {},
+): Promise<RenderResult> {
+  const deck = parseSlidesDoc(sourcePath)
+  const variant = options.variant ?? deck.meta.variant
+  const theme = buildTheme(variant)
+
+  const pptx = new PptxGenJS()
+  pptx.layout = 'LAYOUT_WIDE'
+  if (deck.meta.title) pptx.title = deck.meta.title
+
+  const nav = buildNav(deck)
+  for (const slide of deck.slides) {
+    const target = pptx.addSlide()
+    target.background = { color: theme.background }
+    if (slide.layout === 'toc') {
+      renderToc(target, slide, theme, nav)
+    } else {
+      renderDeckSlide(target, slide, theme)
+    }
+    addFooter(target, slide, theme, nav)
+  }
+
+  mkdirSync(outDir, { recursive: true })
+  const fileName = outputName(sourcePath)
+  const pptxPath = join(outDir, fileName)
+  await pptx.writeFile({ fileName: pptxPath })
+
+  const mirrorPath = options.mirror
+    ? mirrorDeck(pptxPath, options.mirror, fileName)
+    : undefined
+  return { pptxPath, mirrorPath, slideCount: deck.slides.length }
+}
+
+function mirrorDeck(
+  pptxPath: string,
+  mirrorDir: string,
+  fileName: string,
+): string {
+  mkdirSync(mirrorDir, { recursive: true })
+  const mirrorPath = join(mirrorDir, fileName)
+  copyFileSync(pptxPath, mirrorPath)
+  return mirrorPath
+}
+
+export function buildNav(deck: Deck): DeckNav {
+  let tocSlide: number | undefined
+  const sections: DeckNav['sections'] = []
+  deck.slides.forEach((slide, index) => {
+    const slideNumber = index + 1
+    if (slide.layout === 'toc' && tocSlide === undefined) {
+      tocSlide = slideNumber
+    }
+    if (slide.layout === 'section') {
+      sections.push({ title: slide.title, slideNumber })
+    }
+  })
+  return { deckTitle: deck.meta.title, tocSlide, sections }
+}
+
+function outputName(sourcePath: string): string {
+  return basename(sourcePath).replace(/\.md$/, '') + '.pptx'
+}

package/src/slides/styles.ts

@@ -0,0 +1,44 @@
+export type Variant = 'light' | 'dark'
+
+export interface Theme {
+  background: string
+  surface: string
+  ink: string
+  muted: string
+  accent: string
+}
+
+const LIGHT: Theme = {
+  background: 'FAF7F2',
+  surface: 'F4EFE6',
+  ink: '1A1815',
+  muted: '7A736A',
+  accent: 'A4471C',
+}
+
+const DARK: Theme = {
+  background: '1A1815',
+  surface: '23201C',
+  ink: 'F4EFE6',
+  muted: 'A39C92',
+  accent: 'C8602E',
+}
+
+export const FONTS = {
+  heading: 'Arial',
+  body: 'Calibri',
+} as const
+
+export const TYPE = {
+  cover: 44,
+  section: 40,
+  title: 30,
+  body: 16,
+  stat: 54,
+  quote: 30,
+  caption: 11,
+} as const
+
+export function buildTheme(variant: Variant): Theme {
+  return variant === 'dark' ? DARK : LIGHT
+}

package/src/snippets/categories.ts

@@ -0,0 +1,66 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDirectory } from '@/target'
+
+export const BASE_CATEGORY = 'base'
+/** A real category resolving to zero entries, for a caller declining on purpose. */
+export const NONE_CATEGORY = 'none'
+
+export function snippetsSourceDir(root: string): string {
+  return join(root, 'snippets')
+}
+
+/**
+ * Lists the folder categories. `base` is the synthetic name for snippets
+ * sitting directly under `snippets/`, so it is not a directory and callers
+ * prepend it themselves.
+ *
+ * Nothing is filtered: toolkit-internal snippets are authored under `internal/`,
+ * which this never reads, so every category found here is publishable.
+ */
+export function listFolderCategories(root: string): string[] {
+  const dir = snippetsSourceDir(root)
+  if (!isDirectory(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+export function listCategories(root: string): string[] {
+  return [BASE_CATEGORY, ...listFolderCategories(root)]
+}
+
+export function categoryDir(root: string, category: string): string {
+  const source = snippetsSourceDir(root)
+  return category === BASE_CATEGORY ? source : join(source, category)
+}
+
+/**
+ * Tests for a directory rather than mere existence. `snippets/` holds files
+ * alongside its category folders, so an argument naming one of them resolves
+ * to a real path that cannot be scanned as a category.
+ *
+ * An empty category refuses rather than resolving, since `join(source, '')`
+ * is `source` and would otherwise report the base directory as the category,
+ * widening an unset value to every base entry instead of naming none.
+ */
+export function categoryExists(root: string, category: string): boolean {
+  if (category === '') return false
+  return isDirectory(categoryDir(root, category))
+}
+
+/**
+ * Lists one category's entry slugs. Only the immediate level is read, matching
+ * the `find -maxdepth 1` the bash used, so a nested folder is its own category
+ * rather than part of its parent.
+ */
+export function listEntries(root: string, category: string): string[] {
+  const dir = categoryDir(root, category)
+  if (!isDirectory(dir)) return []
+
+  return [...new Bun.Glob('*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .map((name) => name.slice(0, -'.md'.length))
+    .sort()
+}

package/src/snippets/list.ts

@@ -0,0 +1,32 @@
+import { listCategories, listEntries } from '@/snippets/categories'
+import { loadPresets } from '@/snippets/presets'
+
+export interface CategoryCatalogEntry {
+  readonly name: string
+  readonly entries: readonly string[]
+}
+
+export interface SnippetsCatalog {
+  readonly presets: readonly {
+    readonly name: string
+    readonly slugs: readonly string[]
+  }[]
+  readonly categories: readonly CategoryCatalogEntry[]
+}
+
+/**
+ * Builds the catalog both output modes read, so the human list and the `--json`
+ * one cannot describe different corpora.
+ */
+export function buildSnippetsCatalog(root: string): SnippetsCatalog {
+  return {
+    presets: loadPresets(root).map((preset) => ({
+      name: preset.name,
+      slugs: preset.slugs,
+    })),
+    categories: listCategories(root).map((name) => ({
+      name,
+      entries: listEntries(root, name),
+    })),
+  }
+}

package/src/snippets/presets.ts

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { snippetsSourceDir } from '@/snippets/categories'
+
+export interface Preset {
+  readonly name: string
+  readonly slugs: readonly string[]
+}
+
+export function presetsPath(root: string): string {
+  return join(snippetsSourceDir(root), 'snippets.toml')
+}
+
+/**
+ * Reads every preset from `snippets.toml`. The bash read section headers with
+ * `grep '^\['` and then re-walked the file per preset with a `BASH_REMATCH`
+ * loop, so a name carrying a bracket or a slug split across lines parsed by
+ * accident rather than by rule.
+ */
+export function loadPresets(root: string): Preset[] {
+  const path = presetsPath(root)
+  if (!existsSync(path)) return []
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const presets: Preset[] = []
+
+  for (const [name, table] of Object.entries(parsed)) {
+    if (typeof table !== 'object' || table === null || Array.isArray(table)) {
+      continue
+    }
+    const names = (table as Record<string, unknown>).names
+    presets.push({
+      name,
+      slugs: Array.isArray(names)
+        ? names.filter(
+            (slug): slug is string => typeof slug === 'string' && slug !== '',
+          )
+        : [],
+    })
+  }
+
+  return presets.sort((left, right) => left.name.localeCompare(right.name))
+}
+
+export function findPreset(root: string, name: string): Preset | undefined {
+  return loadPresets(root).find((preset) => preset.name === name)
+}

package/src/standards/audit.ts

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+import { resolveBaseRef } from '@/git-files'
+import { INDEX_FILE, standardsSourceDir } from '@/standards/read'
+
+/** Returned when a standard new to this branch carries no `## Success criterion` section, the gating check. */
+export const EXIT_MISSING_CRITERION = 2
+
+/** Matched at any casing, level-2 only, per the heading `standards/standard.md` itself uses. */
+const CRITERION_HEADING = /^##\s+success criterion\s*$/im
+
+/**
+ * The reasons an audit produces no reading. `no-corpus` is the ordinary state
+ * of a target that authors no standards of its own, the same absence the
+ * skills audit reads as its own `no-corpus`. The other two are a broken git
+ * invocation rather than a project stating nothing.
+ */
+export type StandardsAuditRefusal =
+  | 'no-corpus'
+  | 'no-base'
+  | 'unreadable-arrivals'
+
+export type StandardsAudit =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly standards: readonly string[]
+      readonly withCriterion: readonly string[]
+      readonly withoutCriterion: readonly string[]
+      readonly arrivals: readonly string[]
+      readonly arrivalsWithoutCriterion: readonly string[]
+    }
+  | { readonly kind: 'refused'; readonly reason: StandardsAuditRefusal }
+
+/**
+ * Measures the corpus authored at `standards/` under `root` against the
+ * `## Success criterion` gate `standards/standard.md` states, and names which
+ * of those files are new since the branch's merge base.
+ *
+ * Reads the working-root corpus alone, never the packaged fallback
+ * `src/standards/read.ts` falls through to for a name lookup, since a target
+ * with no authored standards of its own has nothing here to gate.
+ */
+export async function auditStandards(root: string): Promise<StandardsAudit> {
+  const dir = standardsSourceDir(root)
+  if (!existsSync(dir)) return { kind: 'refused', reason: 'no-corpus' }
+
+  const standards = readdirSync(dir, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== INDEX_FILE,
+    )
+    .map((entry) => entry.name)
+    .sort()
+
+  const withCriterion: string[] = []
+  const withoutCriterion: string[] = []
+  for (const name of standards) {
+    const body = readFileSync(join(dir, name), 'utf8')
+    ;(CRITERION_HEADING.test(body) ? withCriterion : withoutCriterion).push(
+      name,
+    )
+  }
+
+  const base = await resolveBaseRef(root)
+  if (base === undefined) return { kind: 'refused', reason: 'no-base' }
+
+  const arrived = await arrivedStandards(root, base)
+  if (arrived === undefined) {
+    return { kind: 'refused', reason: 'unreadable-arrivals' }
+  }
+
+  const arrivals = standards.filter((name) => arrived.has(name))
+  const arrivalsWithoutCriterion = arrivals.filter((name) =>
+    withoutCriterion.includes(name),
+  )
+
+  return {
+    kind: 'measured',
+    base,
+    standards,
+    withCriterion,
+    withoutCriterion,
+    arrivals,
+    arrivalsWithoutCriterion,
+  }
+}
+
+/**
+ * Only an arrival missing the section sets a failing code. Every other
+ * standard without one is a known gap `standards/standard.md` names rather
+ * than a violation, so failing the push on the 26 already there teaches
+ * contributors to route around the stage.
+ */
+export function auditExitCode(audit: StandardsAudit): number {
+  if (audit.kind === 'refused') return 1
+  return audit.arrivalsWithoutCriterion.length > 0 ? EXIT_MISSING_CRITERION : 0
+}
+
+/**
+ * Filenames under `standards/` present in the working tree and absent at
+ * `base`: a plain add, with rename detection forced off so a standard moved
+ * into the corpus from elsewhere counts the same as one authored fresh.
+ */
+async function arrivedStandards(
+  root: string,
+  base: string,
+): Promise<Set<string> | undefined> {
+  const [added, untracked] = await Promise.all([
+    $`git -C ${root} diff --no-renames --name-only --diff-filter=A ${base} -- standards`
+      .env(gitEnv())
+      .quiet()
+      .nothrow(),
+    $`git -C ${root} ls-files --others --exclude-standard -- standards`
+      .env(gitEnv())
+      .quiet()
+      .nothrow(),
+  ])
+
+  if (added.exitCode !== 0 || untracked.exitCode !== 0) return undefined
+
+  const paths = [
+    ...added.text().split('\n'),
+    ...untracked.text().split('\n'),
+  ].filter(Boolean)
+
+  return new Set(paths.map((path) => basename(path)))
+}

package/src/standards/read.ts

@@ -0,0 +1,100 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { stripFrontmatter } from '@/frontmatter'
+import { PROJECT_ROOT } from '@/project-root'
+
+export const INDEX_FILE = 'index.md'
+
+/** The folder a repository authors standards in, toolkit or project alike. */
+export function standardsSourceDir(root: string): string {
+  return join(root, 'standards')
+}
+
+/**
+ * Spells the package root in a report where every other root spells a
+ * project-relative path. The `source` field promises a path inside the project
+ * and a package copy is the one source that promise cannot cover, so the
+ * spelling has to be one nothing will join to a project root.
+ */
+const PACKAGE_LABEL = '<canon>'
+
+export interface StandardRoot {
+  /** Absolute directory to search. */
+  readonly dir: string
+  /** How a report spells a copy found under this root. */
+  readonly label: string
+}
+
+export interface ResolvedStandard {
+  readonly path: string
+  /** The label of the root that won, joined to the filename. */
+  readonly source: string
+}
+
+/**
+ * The roots a standard resolves against. No toolkit standard installs into a
+ * project any more, so `.claude/standards/` is gone from the list, no repository
+ * generates one, and a target
+ * carries neither entry below: the package corpus is the only root that
+ * answers there, which is what leaves no precedence to reason about.
+ *
+ * The authoring root stays ahead of the package corpus for the repository that
+ * writes standards, where an edit in progress has to win over the copy
+ * `package.json` shipped. A project that authors standards of its own is the
+ * same case under the same folder.
+ */
+export function standardRoots(root: string): StandardRoot[] {
+  return [
+    { dir: standardsSourceDir(root), label: 'standards' },
+    {
+      dir: standardsSourceDir(PROJECT_ROOT),
+      label: join(PACKAGE_LABEL, 'standards'),
+    },
+  ]
+}
+
+function filename(name: string): string {
+  return name.endsWith('.md') ? name : `${name}.md`
+}
+
+/** Resolves a standard by name, with or without the extension. */
+export function resolveStandard(
+  root: string,
+  name: string,
+): ResolvedStandard | undefined {
+  const file = filename(name)
+
+  for (const { dir, label } of standardRoots(root)) {
+    const path = join(dir, file)
+    if (existsSync(path)) return { path, source: join(label, file) }
+  }
+
+  return undefined
+}
+
+/**
+ * Names every standard a resolve could reach, deduplicated across the roots and
+ * sorted. Shown when a name misses, so it doubles as the answer to what the
+ * caller should have typed.
+ */
+export function listStandards(root: string): string[] {
+  const names = new Set<string>()
+
+  for (const { dir } of standardRoots(root)) {
+    if (!existsSync(dir)) continue
+
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue
+      if (!entry.name.endsWith('.md')) continue
+      if (entry.name === INDEX_FILE) continue
+
+      names.add(basename(entry.name, '.md'))
+    }
+  }
+
+  return [...names].sort()
+}
+
+export function readStandard(standard: ResolvedStandard): string {
+  return stripFrontmatter(readFileSync(standard.path, 'utf8'))
+}