@awarebydefault/display-case 1.0.0

package/src/commands/init-run.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { runInit, runUninstall } from './init'
+
+/**
+ * End-to-end exercise of the scaffolder against a throwaway repo. A `.git`
+ * marker makes the temp dir its own repo root so `findRepoRoot` stops there and
+ * every artifact lands inside the sandbox.
+ */
+
+const dirs: string[] = []
+const opts = { agent: 'claude', json: false }
+
+const makeRepo = async (extra: Record<string, string> = {}) => {
+  const dir = await makeTempDir()
+  dirs.push(dir)
+  await writeFiles(dir, { '.git/HEAD': 'ref: refs/heads/main\n', ...extra })
+  return dir
+}
+
+afterEach(async () => {
+  while (dirs.length)
+    await rm(dirs.pop() as string, { recursive: true, force: true })
+})
+
+describe('runInit / runUninstall', () => {
+  test('a dry run plans changes without writing anything', async () => {
+    const dir = await makeRepo()
+    const res = await runInit(dir, { ...opts, dryRun: true })
+    expect(res.command).toBe('init')
+    expect(existsSync(join(dir, '.claude/launch.json'))).toBe(false)
+    expect(existsSync(join(dir, 'AGENTS.md'))).toBe(false)
+    const launch = res.items.find((i) => i.artifact.endsWith('launch.json'))
+    expect(launch?.action).toBe('created')
+  })
+
+  test('init writes the launch config and the instructions pointer', async () => {
+    const dir = await makeRepo()
+    await runInit(dir, { ...opts, dryRun: false })
+    expect(existsSync(join(dir, '.claude/launch.json'))).toBe(true)
+    const agents = await Bun.file(join(dir, 'AGENTS.md')).text()
+    expect(agents).toContain('## Display Case (for agents)')
+    expect(agents).toContain('display-case:agent-guide:start')
+  })
+
+  test('re-running init is idempotent (the second run skips everything)', async () => {
+    const dir = await makeRepo()
+    await runInit(dir, { ...opts, dryRun: false })
+    const again = await runInit(dir, { ...opts, dryRun: false })
+    expect(again.items.every((i) => i.action === 'skipped')).toBe(true)
+  })
+
+  test('init merges into an existing launch.json without clobbering entries', async () => {
+    const dir = await makeRepo({
+      '.claude/launch.json': `${JSON.stringify(
+        { version: '0.0.1', configurations: [{ name: 'other', port: 9 }] },
+        null,
+        2,
+      )}\n`,
+    })
+    await runInit(dir, { ...opts, dryRun: false })
+    const launch = JSON.parse(
+      await Bun.file(join(dir, '.claude/launch.json')).text(),
+    )
+    const names = (launch.configurations as { name: string }[]).map(
+      (c) => c.name,
+    )
+    expect(names).toContain('other')
+    expect(names).toContain('display-case')
+  })
+
+  test('init appends to an existing AGENTS.md, preserving prior content', async () => {
+    const dir = await makeRepo({ 'AGENTS.md': '# Project\n' })
+    await runInit(dir, { ...opts, dryRun: false })
+    const agents = await Bun.file(join(dir, 'AGENTS.md')).text()
+    expect(agents).toContain('# Project')
+    expect(agents).toContain('## Display Case (for agents)')
+  })
+
+  test('uninstall removes exactly what init wrote and is idempotent', async () => {
+    const dir = await makeRepo()
+    await runInit(dir, { ...opts, dryRun: false })
+
+    const out = await runUninstall(dir, { ...opts, dryRun: false })
+    expect(out.command).toBe('uninstall')
+
+    const launch = JSON.parse(
+      await Bun.file(join(dir, '.claude/launch.json')).text(),
+    )
+    const entry = (launch.configurations as { name: string }[]).find(
+      (c) => c.name === 'display-case',
+    )
+    expect(entry).toBeUndefined()
+
+    const agents = await Bun.file(join(dir, 'AGENTS.md')).text()
+    expect(agents).not.toContain('display-case:agent-guide:start')
+
+    const again = await runUninstall(dir, { ...opts, dryRun: false })
+    expect(again.items.every((i) => i.action === 'skipped')).toBe(true)
+  })
+
+  test('uninstall preserves an unrelated launch entry', async () => {
+    const dir = await makeRepo({
+      '.claude/launch.json': `${JSON.stringify(
+        { version: '0.0.1', configurations: [{ name: 'other', port: 9 }] },
+        null,
+        2,
+      )}\n`,
+    })
+    await runInit(dir, { ...opts, dryRun: false })
+    await runUninstall(dir, { ...opts, dryRun: false })
+    const launch = JSON.parse(
+      await Bun.file(join(dir, '.claude/launch.json')).text(),
+    )
+    const names = (launch.configurations as { name: string }[]).map(
+      (c) => c.name,
+    )
+    expect(names).toEqual(['other'])
+  })
+})

package/src/commands/init.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test'
+import { reconcilePointer } from './init'
+
+// The sentinel contract reconcilePointer keys off of. Hardcoded here on purpose:
+// the test pins the exact marker format that init writes and uninstall strips.
+const START = '<!-- display-case:agent-guide:start -->'
+const END = '<!-- display-case:agent-guide:end -->'
+const block = (body: string) => `${START}\n## Display Case\n\n${body}\n${END}`
+
+describe('reconcilePointer', () => {
+  test('creates the block in an empty file', () => {
+    const b = block('v1')
+    const r = reconcilePointer('', b)
+    expect(r.action).toBe('created')
+    expect(r.next).toBe(`${b}\n`)
+  })
+
+  test('appends to existing content with a blank-line separator', () => {
+    const b = block('v1')
+    const r = reconcilePointer('# Project', b)
+    expect(r.action).toBe('created')
+    expect(r.next).toBe(`# Project\n\n${b}\n`)
+  })
+
+  test('normalizes to one blank line when content already ends in a newline', () => {
+    const b = block('v1')
+    const r = reconcilePointer('# Project\n', b)
+    expect(r.action).toBe('created')
+    expect(r.next).toBe(`# Project\n\n${b}\n`)
+  })
+
+  test('skips when the present block is byte-identical', () => {
+    const b = block('v1')
+    const current = `intro\n\n${b}\n`
+    const r = reconcilePointer(current, b)
+    expect(r.action).toBe('skipped')
+    expect(r.next).toBe(current) // unchanged → runInit writes nothing
+  })
+
+  test('refreshes a drifted block in place', () => {
+    const current = `intro\n\n${block('OLD wording')}\n`
+    const next = block('NEW wording')
+    const r = reconcilePointer(current, next)
+    expect(r.action).toBe('updated')
+    expect(r.next).toBe(`intro\n\n${next}\n`)
+    expect(r.next).not.toContain('OLD wording')
+  })
+
+  test('replaces only the block, preserving text before and after', () => {
+    const current = `before\n${block('OLD')}\nafter\n`
+    const next = block('NEW')
+    const r = reconcilePointer(current, next)
+    expect(r.action).toBe('updated')
+    expect(r.next).toBe(`before\n${next}\nafter\n`)
+  })
+
+  test('does not let a `$` in the block corrupt the replacement', () => {
+    const current = block('OLD')
+    const next = block('cost is $1 — see $& and $1 literally')
+    const r = reconcilePointer(current, next)
+    expect(r.next).toBe(next)
+  })
+})

package/src/commands/init.ts

@@ -0,0 +1,412 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, rm } from 'node:fs/promises'
+import { dirname, join, relative, resolve } from 'node:path'
+import type { AgentTarget } from './agents'
+import { AGENT_TARGETS } from './agents'
+
+/**
+ * Scaffolds (and removes) Display Case's AI-agent integration in a target repo.
+ * Every write is idempotent and merge-aware; every removal is owns-only —
+ * artifacts are identified the same way they are written (a fixed launch
+ * `name`, the bundled skill ids, and sentinel-delimited instruction markers),
+ * so the two commands stay in lock-step without an install manifest.
+ */
+
+const PKG_ROOT = resolve(import.meta.dir, '..', '..')
+const SKILLS_SRC = join(PKG_ROOT, 'skills')
+const PROMPT_FILE = join(PKG_ROOT, 'display-case.prompt.md')
+
+const LAUNCH_NAME = 'display-case'
+const SENTINEL_START = '<!-- display-case:agent-guide:start -->'
+const SENTINEL_END = '<!-- display-case:agent-guide:end -->'
+
+export type Action = 'created' | 'updated' | 'skipped' | 'removed'
+
+export interface PlanItem {
+  artifact: string
+  action: Action
+  detail?: string
+}
+
+export interface RunOptions {
+  agent: string
+  dryRun: boolean
+  json: boolean
+  /** init only: also set up the default visual-regression toolchain. */
+  withVisual?: boolean
+}
+
+const VISUAL_PACKAGES = [
+  'playwright',
+  '@axe-core/playwright',
+  'pixelmatch',
+  'pngjs',
+]
+
+async function setupVisualToolchain(repoRoot: string): Promise<void> {
+  const run = async (cmd: string[]) => {
+    const proc = Bun.spawn(cmd, {
+      cwd: repoRoot,
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    const code = await proc.exited
+    if (code !== 0)
+      throw new Error(`\`${cmd.join(' ')}\` failed (exit ${code})`)
+  }
+  await run(['bun', 'add', '--dev', ...VISUAL_PACKAGES])
+  await run(['bunx', 'playwright', 'install', 'chromium'])
+}
+
+export interface RunResult {
+  command: 'init' | 'uninstall'
+  agent: string
+  dryRun: boolean
+  json: boolean
+  items: PlanItem[]
+}
+
+function findRepoRoot(start: string): string {
+  let dir = start
+  for (let i = 0; i < 12; i++) {
+    if (existsSync(join(dir, '.git'))) return dir
+    const parent = resolve(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+  return start
+}
+
+async function bundledSkillIds(): Promise<string[]> {
+  if (!existsSync(SKILLS_SRC)) return []
+  const entries = await readdir(SKILLS_SRC, { withFileTypes: true })
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort()
+}
+
+async function readJson(path: string): Promise<Record<string, unknown> | null> {
+  if (!(await Bun.file(path).exists())) return null
+  return JSON.parse(await Bun.file(path).text()) as Record<string, unknown>
+}
+
+function resolveInstructionsFile(
+  repoRoot: string,
+  target: AgentTarget,
+): string {
+  const found = target.instructionsFiles.find((f) =>
+    existsSync(join(repoRoot, f)),
+  )
+  return join(repoRoot, found ?? target.instructionsFiles[0])
+}
+
+function launchEntry(repoRoot: string, pkgDir: string) {
+  const cliRel = relative(repoRoot, join(PKG_ROOT, 'src', 'cli.ts'))
+  const showcaseRel = relative(repoRoot, pkgDir)
+  return {
+    name: LAUNCH_NAME,
+    runtimeExecutable: 'bun',
+    // `--dev` enables watching Display Case's own chrome (not just the showcased
+    // package), so editing the shell hot-reloads even when `showcaseRel` points
+    // elsewhere. It's a no-op when showcasing Display Case itself.
+    runtimeArgs: [cliRel, showcaseRel, '--port=3100', '--dev'],
+    port: 3100,
+  }
+}
+
+function guideBlock(repoRoot: string): string {
+  const promptRel = relative(repoRoot, PROMPT_FILE)
+  const docsRel = relative(repoRoot, join(PKG_ROOT, 'docs', 'ai-agents.md'))
+  return [
+    SENTINEL_START,
+    '## Display Case (for agents)',
+    '',
+    'Browse the component showcase with `bun run display-case`; `--print-manifest` lists every component/case as JSON.',
+    'Snapshot one case in isolation at `/render/<component>/<case>?theme=light|dark` (chrome-free HTML).',
+    `See [${promptRel}](${promptRel}) for authoring and [${docsRel}](${docsRel}) for the agent workflow.`,
+    SENTINEL_END,
+  ].join('\n')
+}
+
+/**
+ * Reconcile the sentinel-delimited agent-guide block in an instructions file
+ * against the freshly-rendered `block`. Pure — returns the action to report and
+ * the next file contents, so `runInit` only has to write when `next` changed.
+ *
+ * - No block present → append it (`created`).
+ * - Block present and byte-identical → `skipped`.
+ * - Block present but drifted → replace just that block in place (`updated`),
+ *   so a re-init always converges the pointer to the bundled content.
+ */
+export function reconcilePointer(
+  current: string,
+  block: string,
+): { action: Action; detail: string; next: string } {
+  if (current.includes(SENTINEL_START) && current.includes(SENTINEL_END)) {
+    const blockRe = new RegExp(`${SENTINEL_START}[\\s\\S]*?${SENTINEL_END}`)
+    if (current.match(blockRe)?.[0] === block) {
+      return {
+        action: 'skipped',
+        detail: 'pointer already up to date',
+        next: current,
+      }
+    }
+    // Replace via a function so a `$` in the block is never read as a
+    // replacement pattern; the regex is non-global → only the first block.
+    return {
+      action: 'updated',
+      detail: 'refreshed agent-guide pointer',
+      next: current.replace(blockRe, () => block),
+    }
+  }
+  let sep = ''
+  if (current.length) sep = current.endsWith('\n') ? '\n' : '\n\n'
+  return {
+    action: 'created',
+    detail: 'added agent-guide pointer',
+    next: `${current}${sep}${block}\n`,
+  }
+}
+
+/** Are two directories' files byte-identical (used to decide skip vs update)? */
+async function dirsEqual(a: string, b: string): Promise<boolean> {
+  if (!existsSync(b)) return false
+  const list = async (d: string) =>
+    (await readdir(d, { withFileTypes: true }))
+      .filter((e) => e.isFile())
+      .map((e) => e.name)
+      .sort()
+  const [fa, fb] = await Promise.all([list(a), list(b)])
+  if (fa.join('|') !== fb.join('|')) return false
+  for (const name of fa) {
+    const [ta, tb] = await Promise.all([
+      Bun.file(join(a, name)).text(),
+      Bun.file(join(b, name)).text(),
+    ])
+    if (ta !== tb) return false
+  }
+  return true
+}
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true })
+  for (const e of await readdir(src, { withFileTypes: true })) {
+    if (e.isFile())
+      await Bun.write(join(dest, e.name), Bun.file(join(src, e.name)))
+  }
+}
+
+export async function runInit(
+  pkgDir: string,
+  opts: RunOptions,
+): Promise<RunResult> {
+  const target = AGENT_TARGETS[opts.agent] as AgentTarget
+  const repoRoot = findRepoRoot(pkgDir)
+  const items: PlanItem[] = []
+
+  // 1. Launch config — merge, never clobber other entries.
+  const launchPath = join(repoRoot, target.launchConfigPath)
+  const existing = await readJson(launchPath)
+  const config = existing ?? { version: '0.0.1', configurations: [] }
+  const configs =
+    (config.configurations as Record<string, unknown>[] | undefined) ?? []
+  const entry = launchEntry(repoRoot, pkgDir)
+  const idx = configs.findIndex((c) => c.name === LAUNCH_NAME)
+  if (idx === -1) {
+    configs.push(entry)
+    items.push({
+      artifact: target.launchConfigPath,
+      action: 'created',
+      detail: `added "${LAUNCH_NAME}" entry`,
+    })
+  } else if (JSON.stringify(configs[idx]) !== JSON.stringify(entry)) {
+    configs[idx] = entry
+    items.push({
+      artifact: target.launchConfigPath,
+      action: 'updated',
+      detail: `refreshed "${LAUNCH_NAME}" entry`,
+    })
+  } else {
+    items.push({
+      artifact: target.launchConfigPath,
+      action: 'skipped',
+      detail: 'entry already present',
+    })
+  }
+  config.configurations = configs
+  if (!opts.dryRun && items[items.length - 1].action !== 'skipped') {
+    await mkdir(dirname(launchPath), { recursive: true })
+    await Bun.write(launchPath, `${JSON.stringify(config, null, 2)}\n`)
+  }
+
+  // 2. Skills — copy each bundled skill, skip identical, update changed.
+  for (const id of await bundledSkillIds()) {
+    const src = join(SKILLS_SRC, id)
+    const dest = join(repoRoot, target.skillsDir, id)
+    const rel = join(target.skillsDir, id)
+    if (await dirsEqual(src, dest)) {
+      items.push({ artifact: rel, action: 'skipped', detail: 'identical' })
+      continue
+    }
+    const action: Action = existsSync(dest) ? 'updated' : 'created'
+    items.push({ artifact: rel, action })
+    if (!opts.dryRun) await copyDir(src, dest)
+  }
+
+  // 3. Instructions pointer — sentinel-marked, idempotent, and self-refreshing.
+  // reconcilePointer converges an existing block to the bundled content (like
+  // the skills above): byte-identical → skipped; drifted → replaced in place.
+  const instrPath = resolveInstructionsFile(repoRoot, target)
+  const instrRel = relative(repoRoot, instrPath)
+  const current = (await Bun.file(instrPath).exists())
+    ? await Bun.file(instrPath).text()
+    : ''
+  const { action, detail, next } = reconcilePointer(
+    current,
+    guideBlock(repoRoot),
+  )
+  items.push({ artifact: instrRel, action, detail })
+  if (!opts.dryRun && next !== current) await Bun.write(instrPath, next)
+
+  // 4. Optional visual-regression toolchain (opt-in).
+  if (opts.withVisual) {
+    items.push({
+      artifact: 'visual-regression toolchain',
+      action: 'created',
+      detail: 'Playwright Chromium + pixelmatch/pngjs',
+    })
+    if (!opts.dryRun) await setupVisualToolchain(repoRoot)
+  } else {
+    items.push({
+      artifact: 'visual-regression toolchain',
+      action: 'skipped',
+      detail: 'run `init --with-visual` to set up',
+    })
+  }
+
+  return {
+    command: 'init',
+    agent: opts.agent,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    items,
+  }
+}
+
+export async function runUninstall(
+  pkgDir: string,
+  opts: RunOptions,
+): Promise<RunResult> {
+  const target = AGENT_TARGETS[opts.agent] as AgentTarget
+  const repoRoot = findRepoRoot(pkgDir)
+  const items: PlanItem[] = []
+
+  // 1. Launch config — drop only our entry; keep the file and other entries.
+  const launchPath = join(repoRoot, target.launchConfigPath)
+  const config = await readJson(launchPath)
+  if (config) {
+    const configs =
+      (config.configurations as Record<string, unknown>[] | undefined) ?? []
+    const idx = configs.findIndex((c) => c.name === LAUNCH_NAME)
+    if (idx === -1) {
+      items.push({
+        artifact: target.launchConfigPath,
+        action: 'skipped',
+        detail: 'no entry to remove',
+      })
+    } else {
+      configs.splice(idx, 1)
+      config.configurations = configs
+      items.push({
+        artifact: target.launchConfigPath,
+        action: 'removed',
+        detail: `removed "${LAUNCH_NAME}" entry`,
+      })
+      if (!opts.dryRun)
+        await Bun.write(launchPath, `${JSON.stringify(config, null, 2)}\n`)
+    }
+  } else {
+    items.push({
+      artifact: target.launchConfigPath,
+      action: 'skipped',
+      detail: 'no launch config',
+    })
+  }
+
+  // 2. Skills — remove only directories matching bundled skill ids.
+  for (const id of await bundledSkillIds()) {
+    const dest = join(repoRoot, target.skillsDir, id)
+    const rel = join(target.skillsDir, id)
+    if (existsSync(dest)) {
+      items.push({ artifact: rel, action: 'removed' })
+      if (!opts.dryRun) await rm(dest, { recursive: true, force: true })
+    } else {
+      items.push({ artifact: rel, action: 'skipped', detail: 'not installed' })
+    }
+  }
+
+  // 3. Instructions pointer — strip only the sentinel-delimited block.
+  const instrPath = resolveInstructionsFile(repoRoot, target)
+  const instrRel = relative(repoRoot, instrPath)
+  const current = (await Bun.file(instrPath).exists())
+    ? await Bun.file(instrPath).text()
+    : ''
+  if (current.includes(SENTINEL_START) && current.includes(SENTINEL_END)) {
+    const re = new RegExp(
+      `\\n*${SENTINEL_START}[\\s\\S]*?${SENTINEL_END}\\n*`,
+      'g',
+    )
+    const stripped = `${current
+      .replace(re, '\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd()}\n`
+    items.push({
+      artifact: instrRel,
+      action: 'removed',
+      detail: 'removed agent-guide pointer',
+    })
+    if (!opts.dryRun) await Bun.write(instrPath, stripped)
+  } else {
+    items.push({
+      artifact: instrRel,
+      action: 'skipped',
+      detail: 'no pointer present',
+    })
+  }
+
+  return {
+    command: 'uninstall',
+    agent: opts.agent,
+    dryRun: opts.dryRun,
+    json: opts.json,
+    items,
+  }
+}
+
+const MARK: Record<Action, string> = {
+  created: '+',
+  updated: '~',
+  removed: '-',
+  skipped: '·',
+}
+
+/** Print the result as a human report, or JSON when requested. */
+export function report(result: RunResult): void {
+  if (result.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+  const verb = result.command === 'init' ? 'init' : 'uninstall'
+  const dry = result.dryRun ? ' (dry run)' : ''
+  console.log(`\n  display-case ${verb} → ${result.agent}${dry}`)
+  for (const it of result.items) {
+    console.log(
+      `    ${MARK[it.action]} ${it.action.padEnd(7)} ${it.artifact}${it.detail ? `  (${it.detail})` : ''}`,
+    )
+  }
+  const changed = result.items.filter((i) => i.action !== 'skipped').length
+  console.log(
+    `  ${changed} change(s)${result.dryRun ? ' planned' : ''}, ${result.items.length - changed} skipped\n`,
+  )
+}