@erclx/canon 4.79.0 → 4.81.0

package/src/surface-root.ts

@@ -56,26 +56,19 @@ export function spell(root: SurfaceRoot, entry: string): string {
 }
 
 /**
- * The creation default for one entry.
+ * The root a surface resolves at: the first that carries it, and
+ * `CREATION_ROOT` when neither does.
  *
- * The stamp folder keeps creating under `.claude/` until its own move lands,
- * since the install stamp and the audits baseline still write there by a
- * fixed path. A read resolving to `canon/config/` in a fresh project would
- * answer from a folder nothing writes.
- */
-function creationRootFor(entry: string): SurfaceRoot {
-  return entry === 'canon' ? '.claude' : CREATION_ROOT
-}
-
-/**
- * The root a surface resolves at: the first that carries it, and the creation
- * default when neither does.
+ * The stamp folder used to take a carve-out here, staying at `.claude/` while
+ * the install stamp and the audits baseline still wrote there by a fixed path
+ * of their own. Both moved to `canon/config/` by a fixed path of their own, so
+ * every entry now shares the one default.
  */
 function rootOf(root: string, entry: string): SurfaceRoot {
   return (
     SURFACE_ROOTS.find((candidate) =>
       existsSync(join(root, candidate, spell(candidate, entry))),
-    ) ?? creationRootFor(entry)
+    ) ?? CREATION_ROOT
   )
 }
 

package/src/sync/stamp.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
+import { resolveExisting } from '@/legacy-path'
 import { recordTarget } from '@/targets/registry'
 
 /**
@@ -56,7 +57,21 @@ export interface Stamp {
   readonly domains: Readonly<Partial<Record<StampDomain, DomainStamp>>>
 }
 
+/**
+ * Where a stamp is written today, `canon/config/config.json`. Named
+ * `stampPath` rather than `surfaceStampPath` because the write side has only
+ * one current path, unlike the read side's fallback chain below.
+ */
 export function stampPath(target: string): string {
+  return join(target, 'canon', 'config', 'config.json')
+}
+
+/**
+ * Where the stamp wrote before this move, `.claude/canon/config.json`. Kept
+ * for the same reason as the two spellings below: a target stamped under it
+ * still carries its config here, and `readStamp` falls back to it.
+ */
+export function claudeCanonStampPath(target: string): string {
   return join(target, '.claude', 'canon', 'config.json')
 }
 
@@ -84,18 +99,6 @@ export function retiredNameStampPath(target: string): string {
   return join(target, '.claude', 'aitk', 'config.json')
 }
 
-/**
- * The stamp path under the new surface root, `canon/config/config.json`.
- *
- * Read ahead of `stampPath`, extending the same mechanism rather than adding a
- * new one: a target that has moved reads its config from the root it moved
- * to, and one that has not falls through to the spellings below unchanged.
- * The write destination does not move to it in this batch.
- */
-function surfaceStampPath(target: string): string {
-  return join(target, 'canon', 'config', 'config.json')
-}
-
 /**
  * Every spelling a stamp has been written under, current first. The order is
  * the read order, so a target carrying more than one resolves to the newest.
@@ -105,10 +108,10 @@ function surfaceStampPath(target: string): string {
  * second breaking change aimed at exactly the targets that were slowest to
  * migrate the first time.
  */
-export function stampPaths(target: string): readonly string[] {
+export function stampPaths(target: string): readonly [string, ...string[]] {
   return [
-    surfaceStampPath(target),
     stampPath(target),
+    claudeCanonStampPath(target),
     retiredNameStampPath(target),
     legacyStampPath(target),
   ]
@@ -120,7 +123,10 @@ export function stampPaths(target: string): readonly string[] {
  * there is nothing to migrate off of.
  */
 export function isLegacyStamped(target: string): boolean {
-  if (existsSync(surfaceStampPath(target)) || existsSync(stampPath(target))) {
+  if (
+    existsSync(stampPath(target)) ||
+    existsSync(claudeCanonStampPath(target))
+  ) {
     return false
   }
   return (
@@ -158,8 +164,7 @@ export function toStampKey(rel: string): string {
  * was read from.
  */
 export function readStamp(target: string): Stamp | undefined {
-  const found = stampPaths(target).find((path) => existsSync(path))
-  return found === undefined ? undefined : readStampFile(found)
+  return readStampFile(resolveExisting(stampPaths(target)))
 }
 
 function readStampFile(path: string): Stamp | undefined {

package/src/targets/sweep.ts

@@ -3,6 +3,7 @@ import { join, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git-env'
 import {
+  claudeCanonStampPath,
   isLegacyStamped,
   legacyStampPath,
   retiredNameStampPath,
@@ -91,15 +92,18 @@ export interface SweepOptions {
 }
 
 /**
- * Whether a folder carries an install stamp at the current path or either
+ * Whether a folder carries an install stamp at the current path or any
  * retired one. `aitk@3.57.0` still writes the folder form,
  * `retiredNameStampPath`, as its current path, so a target a pre-rename
  * binary syncs after this check drops the folder form would otherwise vanish
- * from the walk with nothing saying so.
+ * from the walk with nothing saying so. `claudeCanonStampPath` is the spelling
+ * every target carried before the stamp moved to `canon/config/`, which a
+ * target this batch has not reached still writes to.
  */
 function isStamped(path: string): boolean {
   return (
     Bun.file(stampPath(path)).size > 0 ||
+    Bun.file(claudeCanonStampPath(path)).size > 0 ||
     Bun.file(retiredNameStampPath(path)).size > 0 ||
     Bun.file(legacyStampPath(path)).size > 0
   )

package/src/teach/render.ts

@@ -0,0 +1,126 @@
+import { Heading } from '@/teach/components/heading'
+import { List } from '@/teach/components/list'
+import { Paragraph } from '@/teach/components/paragraph'
+import { render } from '@/teach/html/jsx-runtime'
+import type { TeachRefused } from '@/teach/workspace'
+
+export type LessonBlock =
+  | { readonly type: 'heading'; readonly level: 1 | 2; readonly text: string }
+  | {
+      readonly type: 'paragraph'
+      readonly text: string
+      readonly lede?: boolean
+    }
+  | {
+      readonly type: 'list'
+      readonly items: readonly string[]
+      readonly ordered?: boolean
+    }
+  | { readonly type: 'raw'; readonly html: string }
+
+export interface RenderRendered {
+  readonly ok: true
+  readonly html: string
+}
+
+export type RenderOutcome = RenderRendered | TeachRefused
+
+const BLOCK_TYPES = ['heading', 'paragraph', 'list', 'raw'] as const
+
+function isBlockType(value: unknown): value is LessonBlock['type'] {
+  return (BLOCK_TYPES as readonly string[]).includes(value as string)
+}
+
+function badBlock(index: number, message: string): TeachRefused {
+  return {
+    ok: false,
+    reason: 'bad-input',
+    message: `Block ${index}: ${message}`,
+    detail: [],
+  }
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every(isString)
+}
+
+function renderBlock(
+  block: unknown,
+  index: number,
+): { readonly html: string } | TeachRefused {
+  if (typeof block !== 'object' || block === null || !('type' in block)) {
+    return badBlock(index, 'not an object carrying a type')
+  }
+
+  const type = (block as { readonly type: unknown }).type
+
+  if (!isBlockType(type)) {
+    return badBlock(index, `unrecognized type ${JSON.stringify(type)}`)
+  }
+
+  const fields = block as Record<string, unknown>
+
+  switch (type) {
+    case 'heading': {
+      if (fields.level !== 1 && fields.level !== 2) {
+        return badBlock(index, 'heading needs level 1 or 2')
+      }
+      if (!isString(fields.text)) {
+        return badBlock(index, 'heading needs a string text')
+      }
+      return {
+        html: render(Heading({ level: fields.level, children: fields.text })),
+      }
+    }
+    case 'paragraph': {
+      if (!isString(fields.text)) {
+        return badBlock(index, 'paragraph needs a string text')
+      }
+      if (fields.lede !== undefined && typeof fields.lede !== 'boolean') {
+        return badBlock(index, 'paragraph lede must be a boolean')
+      }
+      return {
+        html: render(Paragraph({ lede: fields.lede, children: fields.text })),
+      }
+    }
+    case 'list': {
+      if (!isStringArray(fields.items)) {
+        return badBlock(index, 'list needs an items array of strings')
+      }
+      if (fields.ordered !== undefined && typeof fields.ordered !== 'boolean') {
+        return badBlock(index, 'list ordered must be a boolean')
+      }
+      return {
+        html: render(List({ ordered: fields.ordered, items: fields.items })),
+      }
+    }
+    case 'raw': {
+      if (!isString(fields.html)) {
+        return badBlock(index, 'raw needs a string html')
+      }
+      return { html: fields.html }
+    }
+  }
+}
+
+/**
+ * Renders a lesson body's structural blocks through the same components
+ * `render-fixture.tsx` composes by hand, so a real lesson and the committed
+ * fixture share one rendering mechanism. Every block past the first refusal
+ * goes unread, matching how a malformed JSON parse refuses the whole call.
+ */
+export function renderLessonBody(blocks: readonly unknown[]): RenderOutcome {
+  const rendered: string[] = []
+
+  for (const [index, block] of blocks.entries()) {
+    const result = renderBlock(block, index)
+    if ('ok' in result) return result
+    rendered.push(result.html)
+  }
+
+  return { ok: true, html: rendered.join('\n') }
+}