@erclx/canon 4.0.0

package/src/tooling/gitignore.ts

@@ -0,0 +1,122 @@
+import type { GitignoreSection } from '@/tooling/manifest'
+
+export interface MergeResult {
+  readonly content: string
+  readonly added: readonly string[]
+}
+
+export interface PruneResult {
+  readonly content: string
+  readonly removed: readonly string[]
+}
+
+/**
+ * Splits a gitignore body the way `while IFS= read -r line` did, so a file
+ * with or without a trailing newline yields the same logical lines.
+ */
+function toLines(content: string): string[] {
+  if (content === '') return []
+  const lines = content.split('\n')
+  if (lines[lines.length - 1] === '') lines.pop()
+  return lines
+}
+
+function fromLines(lines: readonly string[]): string {
+  if (lines.length === 0) return ''
+  return `${lines.join('\n')}\n`
+}
+
+function withoutTrailingSlash(entry: string): string {
+  return entry.endsWith('/') ? entry.slice(0, -1) : entry
+}
+
+function hasEntry(lines: readonly string[], entry: string): boolean {
+  return lines.includes(entry) || lines.includes(withoutTrailingSlash(entry))
+}
+
+/**
+ * Appends every manifest entry the file does not already carry.
+ *
+ * Two behaviors are load-bearing and preserved from `merge_gitignore`. The
+ * section header is written only when the whole section is missing, so a
+ * partially present section appends its entries bare at the end of the file.
+ * Presence is re-checked against the growing file, so an entry added by an
+ * earlier section or an earlier stack in the chain is not added twice.
+ */
+export function mergeSections(
+  content: string,
+  sections: readonly GitignoreSection[],
+): MergeResult {
+  let next = content
+  const added: string[] = []
+
+  for (const section of sections) {
+    const lines = toLines(next)
+    const missing = section.entries.filter((entry) => !hasEntry(lines, entry))
+    if (missing.length === 0) continue
+
+    if (missing.length === section.entries.length) {
+      next += `\n${section.header}\n`
+    }
+
+    for (const entry of missing) {
+      next += `${entry}\n`
+      added.push(entry)
+    }
+  }
+
+  return { content: next, added }
+}
+
+/**
+ * Drops entries that sit under a managed header but are no longer in the
+ * manifest. A section runs from its header line until the first blank line or
+ * the next comment, matching `prune_gitignore_section`.
+ */
+export function pruneSections(
+  content: string,
+  sections: readonly GitignoreSection[],
+): PruneResult {
+  let lines = toLines(content)
+  const removed: string[] = []
+
+  for (const section of sections) {
+    const kept: string[] = []
+    let inSection = false
+
+    for (const line of lines) {
+      if (line === section.header) {
+        inSection = true
+        kept.push(line)
+        continue
+      }
+
+      if (!inSection) {
+        kept.push(line)
+        continue
+      }
+
+      if (line === '' || line.startsWith('#')) {
+        inSection = false
+        kept.push(line)
+        continue
+      }
+
+      const isAllowed = section.entries.some(
+        (entry) =>
+          line === entry ||
+          withoutTrailingSlash(line) === withoutTrailingSlash(entry),
+      )
+
+      if (isAllowed) {
+        kept.push(line)
+      } else {
+        removed.push(line)
+      }
+    }
+
+    lines = kept
+  }
+
+  return { content: removed.length > 0 ? fromLines(lines) : content, removed }
+}

package/src/tooling/inject.ts

@@ -0,0 +1,193 @@
+import { existsSync } from 'node:fs'
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { $ } from 'bun'
+import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+import { mergeSections, pruneSections } from '@/tooling/gitignore'
+import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  applyScripts,
+  collectDeps,
+  readPackage,
+  serializePackage,
+} from '@/tooling/package'
+import { logAdd, logRemove, logStep } from '@/ui'
+
+export async function injectConfigs(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    const files = listFiles(manifest.configsDir)
+    if (files.length === 0) continue
+
+    logStep(`Applying ${manifest.name} configs`)
+    for (const rel of files) {
+      await copyPreservingMode(
+        join(manifest.configsDir, rel),
+        join(target, rel),
+      )
+      logAdd(rel)
+      applied.push(rel)
+    }
+  }
+
+  return applied
+}
+
+/**
+ * Writes a seed to a target that does not have it, dropping the stub marker on
+ * the way. The marker is toolkit bookkeeping read by the seed gate, so a target
+ * receiving it would carry a field its own tooling never reads. Only markdown
+ * carries frontmatter, and every other seed copies byte for byte.
+ */
+async function writeSeed(src: string, dest: string): Promise<void> {
+  if (!rewritesOnInstall(src)) {
+    await copyFile(src, dest)
+    return
+  }
+
+  await writeFile(dest, stripSeedMarker(await readFile(src, 'utf8')))
+}
+
+/**
+ * Copies a seed when the target lacks it. When the target already has one and
+ * the seed is a `.txt` word list, missing lines are appended and the file is
+ * re-sorted. Every other existing file is left untouched.
+ */
+async function mergeSeedFile(src: string, dest: string): Promise<void> {
+  await mkdir(dirname(dest), { recursive: true })
+
+  if (!existsSync(dest)) {
+    await writeSeed(src, dest)
+    return
+  }
+
+  if (!src.endsWith('.txt')) return
+
+  const existing = (await readFile(dest, 'utf8')).split('\n')
+  const incoming = (await readFile(src, 'utf8')).split('\n')
+  const missing = incoming.filter(
+    (word) => word !== '' && !existing.includes(word),
+  )
+
+  if (missing.length === 0) return
+
+  const merged = [...existing.filter((line) => line !== ''), ...missing].sort()
+  await writeFile(dest, `${merged.join('\n')}\n`)
+}
+
+export async function injectSeeds(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    const files = listFiles(manifest.seedsDir)
+    if (files.length === 0) continue
+
+    logStep(`Applying ${manifest.name} seeds`)
+    for (const rel of files) {
+      await mergeSeedFile(join(manifest.seedsDir, rel), join(target, rel))
+      logAdd(rel)
+      applied.push(rel)
+    }
+  }
+
+  return applied
+}
+
+export async function injectGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const path = join(target, '.gitignore')
+  const added: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    if (manifest.gitignore.length === 0) continue
+
+    const content = existsSync(path) ? await readFile(path, 'utf8') : ''
+    const result = mergeSections(content, manifest.gitignore)
+    if (result.added.length === 0) continue
+
+    logStep(`Applying ${manifest.name} gitignore`)
+    await writeFile(path, result.content)
+    for (const entry of result.added) {
+      logAdd(entry)
+      added.push(entry)
+    }
+  }
+
+  if (added.length === 0 && !existsSync(path)) await writeFile(path, '')
+
+  return added
+}
+
+export async function pruneGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const path = join(target, '.gitignore')
+  if (!existsSync(path)) return []
+
+  const removed: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    if (manifest.gitignore.length === 0) continue
+
+    const content = await readFile(path, 'utf8')
+    const result = pruneSections(content, manifest.gitignore)
+    if (result.removed.length === 0) continue
+
+    await writeFile(path, result.content)
+    for (const entry of result.removed) {
+      logRemove(entry)
+      removed.push(entry)
+    }
+  }
+
+  return removed
+}
+
+/**
+ * Installs missing dev dependencies, fills package scripts, and merges
+ * gitignore entries. This is the `inject_tooling_manifest` sequence, which
+ * assumed a target that already has a package.json.
+ */
+export async function injectManifest(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<void> {
+  const packagePath = join(target, 'package.json')
+  const pkg = readPackage(packagePath)
+
+  if (pkg) {
+    const missing = collectDeps(chain, pkg)
+      .filter((dep) => dep.state === 'missing')
+      .map((dep) => dep.spec)
+
+    if (missing.length > 0) {
+      logStep('Installing missing dependencies')
+      await $`bun add -D ${missing}`.cwd(target)
+      for (const spec of missing) logAdd(spec)
+    }
+
+    const fresh = readPackage(packagePath)
+    if (fresh) {
+      const result = applyScripts(fresh, chain)
+      if (result.added.length > 0 || result.overridden.length > 0) {
+        logStep('Applying scripts')
+        for (const key of result.added) logAdd(key)
+        for (const key of result.overridden) logAdd(key)
+        await writeFile(packagePath, serializePackage(result.pkg))
+      }
+    }
+  }
+
+  await injectGitignore(chain, target)
+}

package/src/tooling/list.ts

@@ -0,0 +1,39 @@
+import { listStacks, loadManifest } from '@/tooling/manifest'
+
+export interface StackSummary {
+  readonly name: string
+  readonly extends: string | null
+  readonly devDeps: number
+  readonly scripts: number
+  readonly gitignoreGroups: number
+}
+
+/**
+ * Summarizes each installable stack. The counts come from `loadManifest`
+ * rather than the three `awk` programs the bash carried, so the list and the
+ * sync it previews read the same parse.
+ */
+export function buildStackSummaries(root: string): StackSummary[] {
+  const summaries: StackSummary[] = []
+
+  for (const stack of listStacks(root)) {
+    const manifest = loadManifest(root, stack)
+    if (!manifest) continue
+
+    summaries.push({
+      name: manifest.name,
+      extends: manifest.parent ?? null,
+      devDeps: manifest.devPackages.length,
+      scripts: Object.keys(manifest.scripts).length,
+      gitignoreGroups: manifest.gitignore.length,
+    })
+  }
+
+  return summaries
+}
+
+export function describeStack(summary: StackSummary): string {
+  const counts = `${summary.devDeps} dev deps, ${summary.scripts} scripts, ${summary.gitignoreGroups} gitignore groups`
+  const prefix = summary.extends === null ? '' : `extends: ${summary.extends}, `
+  return `${summary.name} (${prefix}${counts})`
+}

package/src/tooling/manifest.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const EXCLUDED_STACKS = ['claude']
+
+export interface GitignoreSection {
+  readonly header: string
+  readonly entries: readonly string[]
+}
+
+export interface Manifest {
+  readonly name: string
+  readonly parent?: string
+  readonly dir: string
+  readonly configsDir: string
+  readonly seedsDir: string
+  readonly scripts: Readonly<Record<string, string>>
+  readonly scriptOverrides: Readonly<Record<string, string>>
+  readonly gitignore: readonly GitignoreSection[]
+  readonly devPackages: readonly string[]
+}
+
+export interface ChainOptions {
+  readonly skipStack?: string
+}
+
+function toolingDir(root: string): string {
+  return join(root, 'tooling')
+}
+
+function manifestPath(root: string, stack: string): string {
+  return join(toolingDir(root), stack, 'manifest.toml')
+}
+
+/**
+ * Lists every file under a directory, dotfiles included. Bun.Glob skips
+ * entries beginning with a dot unless `dot` is set, and tooling configs are
+ * almost entirely dotfiles, so omitting it silently matches nothing.
+ */
+export function listFiles(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  return [
+    ...new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true, dot: true }),
+  ].sort()
+}
+
+/**
+ * Reverses a chain so the furthest ancestor is applied first and nearer
+ * stacks overwrite it.
+ */
+export function ancestorsFirst(chain: readonly Manifest[]): Manifest[] {
+  return [...chain].reverse()
+}
+
+export function stackExists(root: string, stack: string): boolean {
+  return existsSync(join(toolingDir(root), stack))
+}
+
+export function isStackExcluded(stack: string): boolean {
+  return EXCLUDED_STACKS.includes(stack)
+}
+
+/**
+ * Lists installable stack names, filtering the `claude` stack the way
+ * `is_tooling_stack_excluded` in `scripts/lib/tooling.sh` did. Claude is
+ * managed by `canon claude`, not `canon tooling`.
+ */
+export function listStacks(root: string): string[] {
+  const dir = toolingDir(root)
+  if (!existsSync(dir)) return []
+
+  return [...new Bun.Glob('*/manifest.toml').scanSync({ cwd: dir })]
+    .map((entry) => entry.split('/')[0])
+    .filter((name) => !isStackExcluded(name))
+    .sort()
+}
+
+/**
+ * Reads one manifest into a typed shape. Returns undefined when the file is
+ * absent, matching the bash guards that silently skipped a missing manifest.
+ */
+export function loadManifest(
+  root: string,
+  stack: string,
+): Manifest | undefined {
+  const path = manifestPath(root, stack)
+  if (!existsSync(path)) return undefined
+
+  const parsed = asTable(Bun.TOML.parse(readFileSync(path, 'utf8')))
+  const stackTable = asTable(parsed.stack)
+  const parent =
+    typeof stackTable.extends === 'string' ? stackTable.extends : ''
+  const scriptsTable = asTable(parsed.scripts)
+  const dir = join(toolingDir(root), stack)
+
+  return {
+    name: stack,
+    parent: parent === '' ? undefined : parent,
+    dir,
+    configsDir: join(dir, 'configs'),
+    seedsDir: join(dir, 'seeds'),
+    scripts: pickStrings(scriptsTable),
+    scriptOverrides: pickStrings(asTable(scriptsTable.override)),
+    gitignore: readGitignoreSections(asTable(parsed.gitignore)),
+    devPackages: readDevPackages(parsed.dependencies),
+  }
+}
+
+/**
+ * Walks the `extends` chain once, self first. Callers that apply parent
+ * values before child values reverse the result. Replaces the seventeen
+ * copies of `grep '^extends' | cut -d'"' -f2` the bash carried.
+ *
+ * A stack matching `skipStack` truncates the chain at that point, mirroring
+ * the `[ "$stack" = "${SKIP_STACK:-}" ] && return` guard.
+ */
+export function resolveChain(
+  root: string,
+  stack: string,
+  options: ChainOptions = {},
+): Manifest[] {
+  const chain: Manifest[] = []
+  const seen = new Set<string>()
+  let current: string | undefined = stack
+
+  while (current !== undefined) {
+    if (current === options.skipStack) break
+    if (seen.has(current)) break
+    seen.add(current)
+
+    const manifest: Manifest | undefined = loadManifest(root, current)
+    if (!manifest) break
+
+    chain.push(manifest)
+    current = manifest.parent
+  }
+
+  return chain
+}
+
+function asTable(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return {}
+  }
+  return value as Record<string, unknown>
+}
+
+function pickStrings(table: Record<string, unknown>): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const [key, value] of Object.entries(table)) {
+    if (typeof value === 'string') result[key] = value
+  }
+  return result
+}
+
+function readGitignoreSections(
+  table: Record<string, unknown>,
+): GitignoreSection[] {
+  const sections: GitignoreSection[] = []
+  for (const [header, value] of Object.entries(table)) {
+    if (!Array.isArray(value)) continue
+    const entries = value.filter(
+      (entry): entry is string => typeof entry === 'string' && entry !== '',
+    )
+    sections.push({ header, entries })
+  }
+  return sections
+}
+
+function readDevPackages(dependencies: unknown): string[] {
+  const dev = asTable(asTable(dependencies).dev)
+  if (!Array.isArray(dev.packages)) return []
+  return dev.packages.filter(
+    (entry): entry is string => typeof entry === 'string' && entry !== '',
+  )
+}

package/src/tooling/package.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync } from 'node:fs'
+import type { Manifest } from '@/tooling/manifest'
+
+export interface PackageJson {
+  readonly dependencies?: Record<string, string>
+  readonly devDependencies?: Record<string, string>
+  readonly scripts?: Record<string, string>
+  readonly [key: string]: unknown
+}
+
+export interface ScriptState {
+  readonly key: string
+  readonly state: 'missing' | 'drifted' | 'matching'
+}
+
+export interface DepState {
+  readonly spec: string
+  readonly name: string
+  readonly state: 'missing' | 'present'
+}
+
+export function readPackage(path: string): PackageJson | undefined {
+  if (!existsSync(path)) return undefined
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as PackageJson
+  } catch {
+    return undefined
+  }
+}
+
+export function serializePackage(pkg: PackageJson): string {
+  return `${JSON.stringify(pkg, null, 2)}\n`
+}
+
+/**
+ * Splits a dependency spec into its package name, handling the scoped case
+ * where the leading `@` is part of the name rather than a version separator.
+ * `@scope/pkg@^1.2.3` yields `@scope/pkg`, `react@19` yields `react`.
+ */
+export function parseSpec(spec: string): { name: string; pin: string } {
+  let name = spec
+
+  if (spec.startsWith('@')) {
+    const rest = spec.slice(1)
+    if (rest.includes('@')) name = `@${rest.slice(0, rest.indexOf('@'))}`
+  } else {
+    name = spec.split('@')[0]
+  }
+
+  const pin = spec === name ? '' : spec.slice(name.length + 1)
+  return { name, pin }
+}
+
+function firstInteger(value: string): string | undefined {
+  return value.match(/[0-9]+/)?.[0]
+}
+
+/**
+ * Compares a manifest pin against what package.json records. A spec counts as
+ * missing when absent, or when the pinned major differs from the installed
+ * major. Anything looser than a major mismatch is left alone.
+ */
+function isSatisfied(installed: string | undefined, pin: string): boolean {
+  if (installed === undefined) return false
+  if (pin === '') return true
+
+  const pinMajor = firstInteger(pin)
+  const installedMajor = firstInteger(installed)
+  if (pinMajor === undefined) return true
+
+  return pinMajor === installedMajor
+}
+
+/**
+ * Resolves dev dependencies across the chain, ancestors first, deduplicated by
+ * package name so the outermost stack that names a package wins.
+ */
+export function collectDeps(
+  chain: readonly Manifest[],
+  pkg: PackageJson,
+): DepState[] {
+  const installed = { ...pkg.dependencies, ...pkg.devDependencies }
+  const seen = new Set<string>()
+  const states: DepState[] = []
+
+  for (const manifest of [...chain].reverse()) {
+    for (const spec of manifest.devPackages) {
+      const { name, pin } = parseSpec(spec)
+      if (name === '' || seen.has(name)) continue
+      seen.add(name)
+
+      states.push({
+        spec,
+        name,
+        state: isSatisfied(installed[name], pin) ? 'present' : 'missing',
+      })
+    }
+  }
+
+  return states
+}
+
+/**
+ * Compares manifest scripts against package.json, nearest stack first, so a
+ * child definition shadows the parent it extends.
+ */
+export function collectScripts(
+  chain: readonly Manifest[],
+  pkg: PackageJson,
+): ScriptState[] {
+  const scripts = pkg.scripts ?? {}
+  const seen = new Set<string>()
+  const states: ScriptState[] = []
+
+  for (const manifest of chain) {
+    for (const [key, value] of Object.entries(manifest.scripts)) {
+      if (seen.has(key)) continue
+      seen.add(key)
+
+      const current = scripts[key]
+      if (current === undefined) {
+        states.push({ key, state: 'missing' })
+      } else if (current !== value) {
+        states.push({ key, state: 'drifted' })
+      } else {
+        states.push({ key, state: 'matching' })
+      }
+    }
+  }
+
+  return states
+}
+
+/**
+ * Fills scripts the target does not define, nearest stack first, then replays
+ * `[scripts.override]` from the furthest ancestor inward so the nearest stack
+ * has the last word. This is the ordering `apply_stack_scripts` produced
+ * through its recursion.
+ */
+export function applyScripts(
+  pkg: PackageJson,
+  chain: readonly Manifest[],
+): { pkg: PackageJson; added: string[]; overridden: string[] } {
+  const scripts: Record<string, string> = { ...pkg.scripts }
+  const added: string[] = []
+  const overridden: string[] = []
+
+  for (const manifest of chain) {
+    for (const [key, value] of Object.entries(manifest.scripts)) {
+      if (scripts[key] === undefined) {
+        scripts[key] = value
+        added.push(key)
+      }
+    }
+  }
+
+  for (const manifest of [...chain].reverse()) {
+    for (const [key, value] of Object.entries(manifest.scriptOverrides)) {
+      if (scripts[key] === value) continue
+      scripts[key] = value
+      if (!overridden.includes(key)) overridden.push(key)
+    }
+  }
+
+  return { pkg: { ...pkg, scripts }, added, overridden }
+}