@moifort/stack 0.0.0-stage → 0.1.0

package/src/init.ts

@@ -0,0 +1,63 @@
+import { readdir } from 'node:fs/promises'
+import { basename, dirname } from 'node:path'
+import { applies, ROUTINE_STACKS, RULE_STACKS } from '~/catalogue'
+import { CONFIG_FILE, type Stack, StackConfig } from '~/config'
+import { placeholdersIn } from '~/render'
+import { templatePlaceholders } from '~/templates'
+
+/** Every placeholder the selected rules and routines use, so init can ask for exactly those. */
+export const requiredPlaceholders = async (
+  packageDir: string,
+  stacks: readonly Stack[],
+): Promise<string[]> => {
+  const names = new Set<string>()
+  for (const [dir, catalogue] of [
+    ['rules', RULE_STACKS],
+    ['routines', ROUTINE_STACKS],
+  ] as const) {
+    for (const file of (await readdir(`${packageDir}/${dir}`).catch(() => [])).sort()) {
+      if (!file.endsWith('.md') || !applies(catalogue[file], stacks)) continue
+      for (const name of placeholdersIn(await Bun.file(`${packageDir}/${dir}/${file}`).text()))
+        names.add(name)
+    }
+  }
+  for (const name of await templatePlaceholders(packageDir, stacks)) names.add(name)
+  names.delete('STACK_VERSION')
+  names.delete('TODAY')
+  return [...names].sort()
+}
+
+/** Values init can settle without asking: derived from the folder, or a convention. */
+export const defaultPlaceholders = (projectDir: string): Record<string, string> => {
+  const repoName = basename(projectDir)
+  return {
+    CODE_DIR: dirname(projectDir),
+    REPO_NAME: repoName,
+    APP_SLUG: repoName,
+    APP_NAME: repoName.charAt(0).toUpperCase() + repoName.slice(1),
+    SOURCE_LANGUAGE: 'French',
+    SERVED_LANGUAGES: 'French and English',
+    REVIEW_LANGUAGE: 'French',
+    AI_DAILY_ALERT: '3 euros',
+    BILLING_TABLE: 'polyforms-billing.billing_export.gcp_billing_export_v1',
+    GITHUB_OWNER: 'moifort',
+    GITHUB_REPO: `moifort/${repoName}`,
+    BUNDLE_ID: `com.polyforms.${repoName}.app`,
+    // Unknown until the App Store Connect record exists: filled in project-context.md
+    // and here by the bootstrap's last step.
+    APP_STORE_ID: '0',
+    // The Apple developer team: from the environment (the keychain at bootstrap).
+    APPLE_TEAM_ID: process.env.APPLE_TEAM_ID ?? 'TEAMID0000',
+    // Until the first deploy prints the function URL: the local server.
+    SERVER_URL: 'http://127.0.0.1:3000',
+    APP_TAGLINE: "Ce que l'application fait pour vous, en une phrase.",
+    APP_TAGLINE_EN: 'What the app does for you, in one sentence.',
+  }
+}
+
+export const writeConfig = async (projectDir: string, config: StackConfig): Promise<void> => {
+  await Bun.write(
+    `${projectDir}/${CONFIG_FILE}`,
+    `${JSON.stringify(StackConfig.parse(config), null, 2)}\n`,
+  )
+}

package/src/migrations.ts

@@ -0,0 +1,72 @@
+import { readdir } from 'node:fs/promises'
+import semver from 'semver'
+import { z } from 'zod'
+import { applies } from '~/catalogue'
+import type { Stack } from '~/config'
+import { STACKS } from '~/config'
+
+export const Migration = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  risk: z.enum(['safe', 'review']),
+  stacks: z.array(z.enum([...STACKS, 'any'])),
+  rule: z.string(),
+  check: z.string().optional(),
+})
+export type Migration = z.infer<typeof Migration> & { version: string; path: string; body: string }
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/
+
+/** Reads the minimal YAML the frontmatter uses: `key: value` and `key: [a, b]`. */
+export const parseFrontmatter = (text: string): { data: Record<string, unknown>; body: string } => {
+  const match = FRONTMATTER.exec(text)
+  if (!match) throw new Error('missing frontmatter')
+  const data: Record<string, unknown> = {}
+  for (const line of (match[1] as string).split('\n')) {
+    const [key, ...rest] = line.split(':')
+    if (!key || rest.length === 0) continue
+    const raw = rest.join(':').trim()
+    if (raw.startsWith('[') && raw.endsWith(']')) {
+      data[key.trim()] = raw
+        .slice(1, -1)
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    } else {
+      data[key.trim()] = raw.replace(/^"(.*)"$/, '$1')
+    }
+  }
+  return { data, body: match[2] as string }
+}
+
+export const readMigrations = async (packageDir: string): Promise<Migration[]> => {
+  const root = `${packageDir}/migrations`
+  const versions = await readdir(root, { withFileTypes: true }).catch(() => [])
+  const found: Migration[] = []
+  for (const dir of versions) {
+    if (!dir.isDirectory() || !semver.valid(dir.name)) continue
+    for (const file of await readdir(`${root}/${dir.name}`)) {
+      if (!file.endsWith('.md')) continue
+      const path = `${root}/${dir.name}/${file}`
+      const { data, body } = parseFrontmatter(await Bun.file(path).text())
+      const parsed = Migration.parse(data)
+      if (parsed.risk === 'safe' && !parsed.check)
+        throw new Error(`${path}: a safe migration needs a check`)
+      found.push({ ...parsed, version: dir.name, path, body })
+    }
+  }
+  return found.sort((a, b) => semver.compare(a.version, b.version) || a.id.localeCompare(b.id))
+}
+
+/** Migrations with from < version <= to, for the project's stacks. */
+export const migrationsBetween = (
+  all: Migration[],
+  from: string,
+  to: string,
+  stacks: readonly Stack[],
+): Migration[] =>
+  all.filter(
+    (m) =>
+      semver.gt(m.version, from) &&
+      semver.lte(m.version, to) &&
+      (m.stacks.includes('any') || applies(m.stacks as Stack[], stacks)),
+  )

package/src/migrations.unit.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test'
+import { type Migration, migrationsBetween, parseFrontmatter } from '~/migrations'
+
+const m = (version: string, id: string, stacks: Migration['stacks'] = ['any']): Migration => ({
+  id,
+  version,
+  stacks,
+  risk: 'review',
+  rule: 'rules/10-ios.md#x',
+  path: '',
+  body: '',
+})
+
+describe('migrationsBetween', () => {
+  const all = [
+    m('1.0.0', 'a'),
+    m('1.1.0', 'b', ['ios']),
+    m('1.2.0', 'c', ['backend']),
+    m('2.0.0', 'd'),
+  ]
+  test('excludes from, includes to', () => {
+    expect(migrationsBetween(all, '1.0.0', '1.2.0', ['backend', 'ios']).map((x) => x.id)).toEqual([
+      'b',
+      'c',
+    ])
+  })
+  test('filters on the project stacks, any always applies', () => {
+    expect(migrationsBetween(all, '0.0.0', '2.0.0', ['backend']).map((x) => x.id)).toEqual([
+      'a',
+      'c',
+      'd',
+    ])
+  })
+})
+
+describe('parseFrontmatter', () => {
+  test('reads scalars, quoted scalars and lists', () => {
+    const { data, body } = parseFrontmatter(
+      '---\nid: x-y\nrisk: safe\nstacks: [ios, any]\ncheck: "grep -r x"\n---\nBody\n',
+    )
+    expect(data).toEqual({ id: 'x-y', risk: 'safe', stacks: ['ios', 'any'], check: 'grep -r x' })
+    expect(body).toBe('Body\n')
+  })
+})

package/src/package.ts

@@ -0,0 +1,8 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The root of this package, wherever it is installed. */
+export const packageDir = (): string => resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+export const packageVersion = async (): Promise<string> =>
+  ((await Bun.file(`${packageDir()}/package.json`).json()) as { version: string }).version

package/src/render.ts

@@ -0,0 +1,13 @@
+const PLACEHOLDER = /\{\{([A-Z][A-Z0-9_]*)\}\}/g
+
+/** The placeholder names a text uses, in order of first appearance, without duplicates. */
+export const placeholdersIn = (text: string): string[] => [
+  ...new Set([...text.matchAll(PLACEHOLDER)].map((m) => m[1] as string)),
+]
+
+/** Replaces every placeholder; throws naming the first value that is missing. */
+export const render = (text: string, values: Record<string, string>): string => {
+  const missing = placeholdersIn(text).filter((name) => values[name] === undefined)
+  if (missing.length > 0) throw new Error(`missing placeholder value: ${missing.join(', ')}`)
+  return text.replace(PLACEHOLDER, (_, name: string) => values[name] as string)
+}

package/src/render.unit.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from 'bun:test'
+import { placeholdersIn, render } from '~/render'
+
+describe('render', () => {
+  test('replaces every placeholder, each as many times as it appears', () => {
+    expect(render('{{A}} and {{B}} and {{A}}', { A: 'x', B: 'y' })).toBe('x and y and x')
+  })
+  test('lists the placeholders once each, in order', () => {
+    expect(placeholdersIn('{{B}} {{A}} {{B}}')).toEqual(['B', 'A'])
+  })
+  test('fails naming the missing values, before replacing anything', () => {
+    expect(() => render('{{A}} {{B}}', { A: 'x' })).toThrow('missing placeholder value: B')
+  })
+  test('ignores lowercase braces and template syntax that is not a placeholder', () => {
+    expect(render('{{ not }} {{a}}', {})).toBe('{{ not }} {{a}}')
+  })
+})

package/src/sync.int.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { requiredPlaceholders } from '~/init'
+import { packageDir } from '~/package'
+import { applyPlan, checkPlan, planSync, withHooks, withRulesBlock } from '~/sync'
+
+let project: string
+beforeEach(async () => {
+  project = await mkdtemp(join(tmpdir(), 'stack-'))
+})
+afterEach(async () => {
+  await rm(project, { recursive: true, force: true })
+})
+
+const values = async (stacks: ('backend' | 'ios' | 'ai' | 'site')[]) => {
+  const placeholders: Record<string, string> = {}
+  for (const name of await requiredPlaceholders(packageDir(), stacks))
+    placeholders[name] = `<${name}>`
+  return placeholders
+}
+
+describe('sync', () => {
+  test('a project without the ios stack gets no ios rule, skill or hook', async () => {
+    const plan = await planSync(
+      packageDir(),
+      { stacks: ['backend'], placeholders: await values(['backend']), exclude: [] },
+      '1.0.0',
+    )
+    const paths = [...plan.files.keys()]
+    expect(paths).toContain('stack/rules/00-collaboration.md')
+    expect(paths).toContain('stack/rules/09-backend.md')
+    expect(paths).not.toContain('stack/rules/10-ios.md')
+    expect(paths.some((p) => p.includes('shutdown-simulators'))).toBe(false)
+    expect(paths).toContain('stack/VERSION')
+  })
+
+  test('fails before writing when a placeholder has no value', async () => {
+    await expect(
+      planSync(packageDir(), { stacks: ['backend'], placeholders: {}, exclude: [] }, '1.0.0'),
+    ).rejects.toThrow('missing placeholder value')
+  })
+
+  test('applies, then checks clean; a hand edit and a stale block are reported', async () => {
+    const config = {
+      stacks: ['backend', 'ios'] as const,
+      placeholders: await values(['backend', 'ios']),
+      exclude: [],
+    }
+    const plan = await planSync(packageDir(), { ...config, stacks: [...config.stacks] }, '1.0.0')
+    await applyPlan(project, plan)
+    expect(await checkPlan(project, plan)).toEqual([])
+    const rendered = await Bun.file(join(project, 'stack/rules/00-collaboration.md')).text()
+    expect(rendered).not.toMatch(/\{\{[A-Z_]+\}\}/)
+    const claude = await Bun.file(join(project, 'CLAUDE.md')).text()
+    expect(claude).toContain('@stack/rules/10-ios.md')
+    const settings = await Bun.file(join(project, '.claude/settings.json')).json()
+    expect(JSON.stringify(settings.hooks.PostToolUse)).toContain(
+      'shutdown-simulators-after-push.sh',
+    )
+
+    await Bun.write(join(project, 'stack/rules/00-collaboration.md'), 'edited by hand\n')
+    await Bun.write(join(project, 'CLAUDE.md'), '# P\n')
+    const problems = await checkPlan(project, plan)
+    expect(problems).toContain('stack/rules/00-collaboration.md: differs from sync')
+    expect(problems).toContain('CLAUDE.md: rules block out of date')
+  })
+
+  test('running twice gives the same files', async () => {
+    const config = {
+      stacks: ['backend'] as 'backend'[],
+      placeholders: await values(['backend']),
+      exclude: [],
+    }
+    const plan = await planSync(packageDir(), config, '1.0.0')
+    await applyPlan(project, plan)
+    await applyPlan(project, plan)
+    expect(await checkPlan(project, plan)).toEqual([])
+  })
+})
+
+describe('withRulesBlock', () => {
+  test('inserts the block under the title, then replaces it in place', () => {
+    const once = withRulesBlock('# App\n\nText\n', ['@stack/rules/a.md'])
+    expect(once).toBe(
+      '# App\n\n<!-- stack:rules -->\n@stack/rules/a.md\n<!-- /stack:rules -->\n\nText\n',
+    )
+    const twice = withRulesBlock(once, ['@stack/rules/b.md'])
+    expect(twice).toBe(
+      '# App\n\n<!-- stack:rules -->\n@stack/rules/b.md\n<!-- /stack:rules -->\n\nText\n',
+    )
+  })
+})
+
+describe('withHooks', () => {
+  test('registers a hook once and keeps what was there', () => {
+    const once = withHooks({ permissions: { allow: [] } }, ['x.sh'])
+    const twice = withHooks(once, ['x.sh'])
+    expect((twice.hooks as { PostToolUse: unknown[] }).PostToolUse).toHaveLength(1)
+    expect(twice.permissions).toEqual({ allow: [] })
+  })
+})

package/src/sync.ts

@@ -0,0 +1,161 @@
+import { chmod, mkdir, readdir, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { applies, HOOK_STACKS, ROUTINE_STACKS, RULE_STACKS, SKILL_STACKS } from '~/catalogue'
+import type { StackConfig } from '~/config'
+import { render } from '~/render'
+import { planTemplates } from '~/templates'
+
+export type Plan = {
+  /** Files to write in the project, path relative to the project root, with their content. */
+  files: Map<string, string>
+  /** The lines the CLAUDE.md rules block must hold. */
+  ruleImports: string[]
+}
+
+const RULES_BLOCK_START = '<!-- stack:rules -->'
+const RULES_BLOCK_END = '<!-- /stack:rules -->'
+
+const listFiles = async (dir: string, filter: (name: string) => boolean): Promise<string[]> =>
+  (await readdir(dir).catch(() => [])).filter(filter).sort()
+
+/** Everything sync would write, computed before anything is written: a missing placeholder fails here. */
+export const planSync = async (
+  packageDir: string,
+  config: StackConfig,
+  version: string,
+): Promise<Plan> => {
+  const files = new Map<string, string>()
+  const values = { ...config.placeholders, STACK_VERSION: version }
+  const { stacks, exclude } = config
+
+  const rules = await listFiles(`${packageDir}/rules`, (f) => f.endsWith('.md'))
+  const ruleImports: string[] = []
+  for (const name of rules) {
+    if (!applies(RULE_STACKS[name], stacks) || exclude.includes(name)) continue
+    const text = await Bun.file(`${packageDir}/rules/${name}`).text()
+    files.set(`stack/rules/${name}`, render(text, values))
+    ruleImports.push(`@stack/rules/${name}`)
+  }
+
+  const routines = await listFiles(`${packageDir}/routines`, (f) => f.endsWith('.md'))
+  for (const name of routines) {
+    if (!applies(ROUTINE_STACKS[name], stacks)) continue
+    const text = await Bun.file(`${packageDir}/routines/${name}`).text()
+    files.set(`stack/routines/${name}`, render(text, values))
+  }
+
+  const skills = await readdir(`${packageDir}/skills`, { withFileTypes: true }).catch(() => [])
+  for (const skill of skills) {
+    if (!skill.isDirectory() || !applies(SKILL_STACKS[skill.name], stacks)) continue
+    for (const file of await listFiles(`${packageDir}/skills/${skill.name}`, () => true)) {
+      const text = await Bun.file(`${packageDir}/skills/${skill.name}/${file}`).text()
+      files.set(`.claude/skills/${skill.name}/${file}`, text)
+    }
+  }
+
+  const hooks = await listFiles(`${packageDir}/hooks`, (f) => f.endsWith('.sh'))
+  for (const name of hooks) {
+    if (!applies(HOOK_STACKS[name], stacks)) continue
+    files.set(`.claude/hooks/${name}`, await Bun.file(`${packageDir}/hooks/${name}`).text())
+  }
+
+  files.set('stack/VERSION', `${version}\n`)
+  return { files, ruleImports }
+}
+
+/** Rewrites the rules block of a CLAUDE.md; adds it at the top when absent. */
+export const withRulesBlock = (claudeMd: string, imports: string[]): string => {
+  const block = [RULES_BLOCK_START, ...imports, RULES_BLOCK_END].join('\n')
+  const start = claudeMd.indexOf(RULES_BLOCK_START)
+  const end = claudeMd.indexOf(RULES_BLOCK_END)
+  if (start >= 0 && end > start) {
+    return claudeMd.slice(0, start) + block + claudeMd.slice(end + RULES_BLOCK_END.length)
+  }
+  const lines = claudeMd.split('\n')
+  const title = lines.findIndex((l) => l.startsWith('# '))
+  if (title >= 0) {
+    lines.splice(title + 1, 0, '', block)
+    return lines.join('\n')
+  }
+  return `${block}\n\n${claudeMd}`
+}
+
+/** The hook registrations sync adds to .claude/settings.json. */
+export const withHooks = (
+  settings: Record<string, unknown>,
+  hookFiles: string[],
+): Record<string, unknown> => {
+  const hooks = (settings.hooks ?? {}) as Record<string, unknown[]>
+  const post = [...((hooks.PostToolUse as unknown[] | undefined) ?? [])]
+  for (const file of hookFiles) {
+    const command = `.claude/hooks/${file}`
+    const already = post.some((entry) => JSON.stringify(entry).includes(command))
+    if (!already) post.push({ matcher: 'Bash', hooks: [{ type: 'command', command }] })
+  }
+  return { ...settings, hooks: { ...hooks, PostToolUse: post } }
+}
+
+/** Writes the templates into a project that does not have them yet: a file that
+ *  already exists is left alone, so init on an existing project adds what is
+ *  missing and overwrites nothing. */
+export const applyTemplates = async (
+  packageDir: string,
+  projectDir: string,
+  config: StackConfig,
+  values: Record<string, string>,
+): Promise<{ written: string[]; kept: string[] }> => {
+  const written: string[] = []
+  const kept: string[] = []
+  for (const file of await planTemplates(packageDir, config, values)) {
+    const target = join(projectDir, file.path)
+    if (await Bun.file(target).exists()) {
+      kept.push(file.path)
+      continue
+    }
+    await mkdir(dirname(target), { recursive: true })
+    await Bun.write(target, file.content)
+    if (file.executable) await chmod(target, 0o755)
+    written.push(file.path)
+  }
+  return { written, kept }
+}
+
+export const applyPlan = async (projectDir: string, plan: Plan): Promise<void> => {
+  await rm(join(projectDir, 'stack/rules'), { recursive: true, force: true })
+  await rm(join(projectDir, 'stack/routines'), { recursive: true, force: true })
+  for (const [path, content] of plan.files) {
+    const target = join(projectDir, path)
+    await mkdir(dirname(target), { recursive: true })
+    await Bun.write(target, content)
+  }
+  const claudePath = join(projectDir, 'CLAUDE.md')
+  const claudeFile = Bun.file(claudePath)
+  const claude = (await claudeFile.exists()) ? await claudeFile.text() : '# Project\n'
+  await Bun.write(claudePath, withRulesBlock(claude, plan.ruleImports))
+  const hookFiles = [...plan.files.keys()]
+    .filter((p) => p.startsWith('.claude/hooks/'))
+    .map((p) => p.slice('.claude/hooks/'.length))
+  if (hookFiles.length > 0) {
+    const settingsPath = join(projectDir, '.claude/settings.json')
+    const settingsFile = Bun.file(settingsPath)
+    const settings = (await settingsFile.exists()) ? await settingsFile.json() : {}
+    await mkdir(dirname(settingsPath), { recursive: true })
+    await Bun.write(settingsPath, `${JSON.stringify(withHooks(settings, hookFiles), null, 2)}\n`)
+  }
+}
+
+/** The differences between the project and what sync would produce; empty when in sync. */
+export const checkPlan = async (projectDir: string, plan: Plan): Promise<string[]> => {
+  const problems: string[] = []
+  for (const [path, content] of plan.files) {
+    const file = Bun.file(join(projectDir, path))
+    if (!(await file.exists())) problems.push(`${path}: missing`)
+    else if ((await file.text()) !== content) problems.push(`${path}: differs from sync`)
+    if (/\{\{[A-Z][A-Z0-9_]*\}\}/.test(content)) problems.push(`${path}: raw placeholder left`)
+  }
+  const claudeFile = Bun.file(join(projectDir, 'CLAUDE.md'))
+  const claude = (await claudeFile.exists()) ? await claudeFile.text() : ''
+  if (withRulesBlock(claude, plan.ruleImports) !== claude)
+    problems.push('CLAUDE.md: rules block out of date')
+  return problems
+}

package/src/templates.ts

@@ -0,0 +1,121 @@
+import { readdir } from 'node:fs/promises'
+import { extname, join, relative } from 'node:path'
+import type { Stack, StackConfig } from '~/config'
+import { placeholdersIn, render } from '~/render'
+
+/** The folders of templates/ that a project with these stacks receives, in order:
+ *  base first, then one per selected stack. A later folder may add files or
+ *  merge into a JSON file an earlier one wrote (`<name>.merge.json`). */
+export const templateFolders = (stacks: readonly Stack[]): string[] => ['base', ...stacks]
+
+const TEXT = new Set([
+  '.md',
+  '.ts',
+  '.tsx',
+  '.js',
+  '.json',
+  '.yml',
+  '.yaml',
+  '.toml',
+  '.tf',
+  '.example',
+  '.sh',
+  '.swift',
+  '.graphql',
+  '.html',
+  '.css',
+  '.txt',
+  '.plist',
+  '.xcstrings',
+  '.rules',
+  '.gitignore',
+  '.entitlements',
+  '.xcprivacy',
+  '.strings',
+  '.xctestplan',
+  '.pbxproj',
+  '.resolved',
+])
+export const isText = (path: string): boolean => {
+  const ext = extname(path) || path.slice(path.lastIndexOf('/') + 1)
+  return TEXT.has(ext) || ext === '' || path.endsWith('/tf')
+}
+
+const walk = async (dir: string): Promise<string[]> => {
+  const out: string[] = []
+  for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...(await walk(path)))
+    else out.push(path)
+  }
+  return out.sort()
+}
+
+const deepMerge = (into: Record<string, unknown>, from: Record<string, unknown>) => {
+  for (const [key, value] of Object.entries(from)) {
+    const current = into[key]
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      current &&
+      typeof current === 'object' &&
+      !Array.isArray(current)
+    ) {
+      deepMerge(current as Record<string, unknown>, value as Record<string, unknown>)
+    } else into[key] = value
+  }
+  return into
+}
+
+export type TemplateFile = { path: string; content: string | Uint8Array; executable: boolean }
+
+/** Every file the templates produce for a project, rendered, in memory. */
+export const planTemplates = async (
+  packageDir: string,
+  config: StackConfig,
+  values: Record<string, string>,
+): Promise<TemplateFile[]> => {
+  const files = new Map<string, TemplateFile>()
+  for (const folder of templateFolders(config.stacks)) {
+    const root = join(packageDir, 'templates', folder)
+    for (const path of await walk(root)) {
+      const rel = render(relative(root, path), values)
+      const file = Bun.file(path)
+      const executable = ((await file.stat()).mode & 0o111) !== 0
+      if (rel.endsWith('.merge.json')) {
+        const target = rel.replace(/\.merge\.json$/, '.json')
+        const existing = files.get(target)
+        const base =
+          existing && typeof existing.content === 'string' ? JSON.parse(existing.content) : {}
+        const merged = deepMerge(base, JSON.parse(render(await file.text(), values)))
+        files.set(target, {
+          path: target,
+          content: `${JSON.stringify(merged, null, 2)}\n`,
+          executable: false,
+        })
+        continue
+      }
+      if (isText(rel))
+        files.set(rel, { path: rel, content: render(await file.text(), values), executable })
+      else
+        files.set(rel, { path: rel, content: new Uint8Array(await file.arrayBuffer()), executable })
+    }
+  }
+  return [...files.values()]
+}
+
+/** The placeholders the templates of these stacks use. */
+export const templatePlaceholders = async (
+  packageDir: string,
+  stacks: readonly Stack[],
+): Promise<string[]> => {
+  const names = new Set<string>()
+  for (const folder of templateFolders(stacks)) {
+    for (const path of await walk(join(packageDir, 'templates', folder))) {
+      if (!isText(path)) continue
+      for (const name of placeholdersIn(await Bun.file(path).text())) names.add(name)
+    }
+  }
+  return [...names].sort()
+}

package/src/validate-content.ts

@@ -0,0 +1,65 @@
+/**
+ * Content validation, run in the package's CI: every migration and routine parses, no safe
+ * migration without a check, no em or en dash in what is shipped, no identifier that belongs
+ * to one project (the denylist lives outside the published files).
+ */
+import { readdir } from 'node:fs/promises'
+import { parseFrontmatter, readMigrations } from '~/migrations'
+import { packageDir } from '~/package'
+
+const root = packageDir()
+const problems: string[] = []
+
+const walk = async (dir: string): Promise<string[]> => {
+  const out: string[] = []
+  for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+    const path = `${dir}/${entry.name}`
+    if (entry.isDirectory()) out.push(...(await walk(path)))
+    else out.push(path)
+  }
+  return out
+}
+
+const denylist = (
+  await Bun.file(`${root}/.denylist`)
+    .text()
+    .catch(() => '')
+)
+  .split('\n')
+  .map((l) => l.trim())
+  .filter((l) => l && !l.startsWith('#'))
+
+for (const dir of ['rules', 'routines', 'skills', 'migrations']) {
+  for (const path of await walk(`${root}/${dir}`)) {
+    if (!path.endsWith('.md')) continue
+    const text = await Bun.file(path).text()
+    const rel = path.slice(root.length + 1)
+    if (/[—–]/.test(text)) problems.push(`${rel}: em or en dash`)
+    for (const word of denylist) if (text.includes(word)) problems.push(`${rel}: contains ${word}`)
+  }
+}
+
+for (const path of await walk(`${root}/routines`)) {
+  const { data } = parseFrontmatter(await Bun.file(path).text())
+  for (const key of ['id', 'scope', 'runtime', 'cadence', 'title']) {
+    if (!data[key]) problems.push(`${path.slice(root.length + 1)}: frontmatter lacks ${key}`)
+  }
+}
+
+try {
+  for (const m of await readMigrations(root)) {
+    const [file, anchor] = m.rule.split('#')
+    const ruleText = await Bun.file(`${root}/${file}`)
+      .text()
+      .catch(() => '')
+    if (!ruleText) problems.push(`${m.path}: rule file ${file} not found`)
+    else if (anchor && !ruleText.toLowerCase().includes(`## ${anchor.replace(/-/g, ' ')}`))
+      problems.push(`${m.path}: heading ${anchor} not found in ${file}`)
+  }
+} catch (error) {
+  problems.push(String(error))
+}
+
+for (const p of problems) console.error(p)
+console.log(problems.length === 0 ? 'content valid' : `${problems.length} problem(s)`)
+process.exit(problems.length === 0 ? 0 : 1)