@erclx/canon 4.8.1 → 4.9.1

package/src/sync/engine.ts

@@ -139,6 +139,8 @@ export interface SyncAdapter {
   collectMissing?(target: string): RetiredSurface[]
   /** Dropped from the walk, so neither matching nor orphaned. */
   isExcluded?(file: InstalledFile): boolean
+  /** Glob the walk lists. Defaults to `DEFAULT_INSTALL_PATTERN`. */
+  readonly installPattern?: string
   /**
    * Top-level folder under `installedRoot` that is project-authored by
    * location rather than by the name inference `locateSource` runs.
@@ -158,15 +160,26 @@ export interface SyncAdapter {
 }
 
 /**
- * Lists installed markdown, dotfiles included. `Bun.Glob` skips entries
- * beginning with a dot unless `dot` is set, and every domain installs under
- * `.claude/`, so a nested dot-directory would silently drop out of the walk.
+ * What a domain installs, when it installs something other than markdown.
+ * Design ships a stylesheet, and every other domain ships prose.
  */
-export function listInstalled(root: string, target: string): InstalledFile[] {
+export const DEFAULT_INSTALL_PATTERN = '**/*.md'
+
+/**
+ * Lists installed files matching the domain's pattern, dotfiles included.
+ * `Bun.Glob` skips entries beginning with a dot unless `dot` is set, and every
+ * domain installs under `.claude/`, so a nested dot-directory would silently
+ * drop out of the walk.
+ */
+export function listInstalled(
+  root: string,
+  target: string,
+  pattern: string = DEFAULT_INSTALL_PATTERN,
+): InstalledFile[] {
   if (!existsSync(root)) return []
 
   return [
-    ...new Bun.Glob('**/*.md').scanSync({
+    ...new Bun.Glob(pattern).scanSync({
       cwd: root,
       onlyFiles: true,
       dot: true,
@@ -192,7 +205,11 @@ export function planSync(adapter: SyncAdapter, target: string): SyncPlan {
   const hashes = stampedHashes(readStamp(target), adapter.stamp?.domain)
   const walked = new Set<string>()
 
-  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+  for (const file of listInstalled(
+    adapter.installedRoot(target),
+    target,
+    adapter.installPattern,
+  )) {
     if (adapter.isExcluded?.(file) === true) continue
     walked.add(toStampKey(file.rel))
 
@@ -562,7 +579,11 @@ export async function recordStamp(
 
   const hashes: Record<string, string> = {}
 
-  for (const file of listInstalled(adapter.installedRoot(target), target)) {
+  for (const file of listInstalled(
+    adapter.installedRoot(target),
+    target,
+    adapter.installPattern,
+  )) {
     if (adapter.isExcluded?.(file) === true) continue
     if (isProjectAuthored(adapter, file)) continue
 

package/src/sync/stamp.ts

@@ -6,16 +6,17 @@ import { execa } from 'execa'
 import { recordTarget } from '@/targets/registry'
 
 /**
- * Domains the stamp can record. Governance attributes file by file through the
- * sync engine. Tooling runs its own inject and manifest machinery, so it
- * records the stack chain it resolved instead and carries no file hashes.
+ * Domains the stamp can record. Governance and design both attribute file by
+ * file through the sync engine. Tooling runs its own inject and manifest
+ * machinery, so it records the stack chain it resolved instead and carries no
+ * file hashes.
  *
  * A stamp written before the standards or snippets install channel closed
  * still carries a `standards` or `snippets` record. `isStamp` ignores the key
  * and `sortDomains` drops it on the next write, so the target loses a domain
  * nothing can refresh rather than losing the whole file.
  */
-export const STAMP_DOMAINS = ['governance', 'tooling'] as const
+export const STAMP_DOMAINS = ['governance', 'design', 'tooling'] as const
 
 export type StampDomain = (typeof STAMP_DOMAINS)[number]
 

package/src/sync/target.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import { DESIGN_INSTALL_DIR } from '@/design/adapter'
 import { isDirectory } from '@/target'
 
-export const SYNC_DOMAINS = ['governance', 'claude'] as const
+export const SYNC_DOMAINS = ['governance', 'design', 'claude'] as const
 
 export type SyncDomain = (typeof SYNC_DOMAINS)[number]
 
@@ -13,6 +14,7 @@ export interface DomainState {
 
 const DOMAIN_MARKERS: Record<SyncDomain, string> = {
   governance: join('.claude', 'rules'),
+  design: DESIGN_INSTALL_DIR,
   claude: '.claude',
 }
 
@@ -24,6 +26,7 @@ const DOMAIN_MARKERS: Record<SyncDomain, string> = {
  */
 const DOMAIN_PATHS: Record<SyncDomain, readonly string[]> = {
   governance: ['.claude/rules/', '.claude/GOV.md'],
+  design: ['.claude/design/'],
   claude: ['.gitignore'],
 }
 

package/src/teach/workspace.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
+import { buildDesignCss } from '@/design/css'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
 import { recordDir } from '@/record-root'
@@ -841,3 +842,59 @@ export async function defineTerms(
 
   return { ok: true, slug: found.slug, path, defined: terms }
 }
+
+export interface StylesheetWritten {
+  readonly ok: true
+  readonly slug: string
+  /** Relative to the root, so a caller prints a path a reader can open. */
+  readonly path: string
+  /** False when the workspace already held one and this call left it alone. */
+  readonly written: boolean
+}
+
+export type StylesheetOutcome = StylesheetWritten | TeachRefused
+
+const STYLESHEET_BANNER = [
+  'Seeded by `canon teach stylesheet` from the design source in',
+  'src/design/tokens.ts. The tokens and the two components below are the',
+  'system this workspace renders in. Add lesson rules under them and read a',
+  'value through its custom property rather than restating the hex, which is',
+  'what let one workspace fork the palette from every other.',
+].join('\n   ')
+
+/**
+ * Writes a workspace's one stylesheet from the design source.
+ *
+ * Every workspace used to carry a hand-authored copy, which is how the course
+ * palette forked once per workspace. The name is fixed at `TEACH_STYLESHEET`
+ * and the folder at `TEACH_ASSETS` for the same reason a second lesson has to
+ * reach the file the first one wrote, and this is what puts the values in it.
+ *
+ * An existing stylesheet is left alone rather than replaced. A workspace adds
+ * lesson rules to this file as it goes, so overwriting would discard them, and
+ * `--force` is the caller saying it wants the seed back.
+ */
+export async function writeStylesheet(
+  root: string,
+  selector: string,
+  force = false,
+): Promise<StylesheetOutcome> {
+  const found = await readWorkspace(root, selector)
+  if (!found.ok) return found
+
+  const workspace = found.workspace
+  const rel = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+  const path = join(root, rel)
+
+  if (existsSync(path) && !force) {
+    return { ok: true, slug: workspace.slug, path: rel, written: false }
+  }
+
+  await mkdir(join(root, workspace.path, TEACH_ASSETS), { recursive: true })
+  await writeFile(
+    path,
+    buildDesignCss(undefined, { banner: STYLESHEET_BANNER }),
+  )
+
+  return { ok: true, slug: workspace.slug, path: rel, written: true }
+}