basalt-ui 1.26.0 → 1.28.0

package/src/cli/placement-engine.test.ts

@@ -1,298 +0,0 @@
-/**
- * Placement-engine contract tests. init/sync write into consumers' git-tracked trees, which makes
- * this the highest-risk code in the repo — every ownership promise the managed/seed model makes is
- * asserted here:
- *
- *  - sync is idempotent (second run is a byte-level no-op, manifest stable)
- *  - a locally-edited managed file is never clobbered (skipped + reported; --check exits 1)
- *  - --force overwrites managed files but never touches seeds
- *  - a seed is recreated only when missing
- *  - block-splicing preserves surrounding host content, appends when markers are absent, and
- *    errors loudly on duplicate markers instead of silently picking one
- *  - --check performs zero writes (filesystem is byte-identical afterwards)
- *  - exit codes: 0 clean / 1 drift
- */
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import {
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-import { init, sync } from './index.ts'
-
-const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
-const SHIPPED_RULE = readFileSync(resolve(PKG_ROOT, 'agent/rules/basalt-tokens.md'), 'utf8')
-const SHIPPED_SKILL = readFileSync(resolve(PKG_ROOT, 'agent/skills/basalt-design/SKILL.md'), 'utf8')
-
-let dir: string
-
-beforeEach(() => {
-  dir = mkdtempSync(resolve(tmpdir(), 'basalt-engine-'))
-  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture' }))
-})
-
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true })
-})
-
-function read(relPath: string): string {
-  return readFileSync(join(dir, relPath), 'utf8')
-}
-
-function write(relPath: string, content: string): void {
-  const abs = join(dir, relPath)
-  mkdirSync(resolve(abs, '..'), { recursive: true })
-  writeFileSync(abs, content, 'utf8')
-}
-
-/** Byte-level snapshot of every file under the fixture dir — the zero-writes/idempotency oracle. */
-function snapshotDir(root: string = dir): Map<string, string> {
-  const out = new Map<string, string>()
-  function walk(d: string): void {
-    for (const name of readdirSync(d)) {
-      const abs = resolve(d, name)
-      if (statSync(abs).isDirectory()) walk(abs)
-      else out.set(relative(root, abs), readFileSync(abs, 'utf8'))
-    }
-  }
-  walk(root)
-  return out
-}
-
-function silenced<T>(fn: () => T): T {
-  const originalLog = console.log
-  const originalError = console.error
-  console.log = () => {}
-  console.error = () => {}
-  try {
-    return fn()
-  } finally {
-    console.log = originalLog
-    console.error = originalError
-  }
-}
-
-/** Captures both console.log and console.error — init()/sync() interleave the two. */
-function capture(fn: () => number): { code: number; log: string } {
-  const originalLog = console.log
-  const originalError = console.error
-  let log = ''
-  console.log = (...args: unknown[]) => {
-    log += `${args.join(' ')}\n`
-  }
-  console.error = (...args: unknown[]) => {
-    log += `${args.join(' ')}\n`
-  }
-  try {
-    return { code: fn(), log }
-  } finally {
-    console.log = originalLog
-    console.error = originalError
-  }
-}
-
-describe('managed vs seed placement', () => {
-  it('init places rules AND skills as managed files, plus the toolchain seeds', () => {
-    silenced(() => init(dir))
-    expect(read('.claude/rules/basalt-tokens.md')).toBe(SHIPPED_RULE)
-    expect(read('.claude/skills/basalt-design/SKILL.md')).toBe(SHIPPED_SKILL)
-    expect(existsSync(join(dir, '.claude/skills/basalt-app/SKILL.md'))).toBe(true)
-    expect(existsSync(join(dir, '.claude/skills/basalt-charts/SKILL.md'))).toBe(true)
-    // Seeds are references, not copies — the toolchain auto-updates through node_modules.
-    expect(read('.oxlintrc.json')).toContain('./node_modules/basalt-ui/configs/oxlint.json')
-    expect(read('lefthook.yml')).toContain('node_modules/basalt-ui/configs/lefthook.yml')
-  })
-
-  it('sync is idempotent: the second run is a byte-level no-op and the manifest is stable', () => {
-    silenced(() => init(dir))
-    expect(silenced(() => sync({}, dir))).toBe(0)
-    const before = snapshotDir()
-    expect(silenced(() => sync({}, dir))).toBe(0)
-    expect(snapshotDir()).toEqual(before)
-    expect(silenced(() => sync({ check: true }, dir))).toBe(0)
-  })
-
-  it('a locally-edited managed file is never clobbered: skipped by sync, --check exits 1', () => {
-    silenced(() => init(dir))
-    write('.claude/rules/basalt-tokens.md', '# my local law\n')
-    expect(silenced(() => sync({}, dir))).toBe(0)
-    expect(read('.claude/rules/basalt-tokens.md')).toBe('# my local law\n')
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-  })
-
-  it('--force overwrites a drifted managed file but never touches a seed', () => {
-    silenced(() => init(dir))
-    write('.claude/rules/basalt-tokens.md', '# my local law\n')
-    write('.claude/skills/basalt-design/SKILL.md', '# my local skill\n')
-    write('DESIGN.md', '# my design\n')
-    write('lefthook.yml', 'pre-commit:\n  commands: {}\n')
-    silenced(() => sync({ force: true }, dir))
-    expect(read('.claude/rules/basalt-tokens.md')).toBe(SHIPPED_RULE)
-    expect(read('.claude/skills/basalt-design/SKILL.md')).toBe(SHIPPED_SKILL)
-    expect(read('DESIGN.md')).toBe('# my design\n')
-    expect(read('lefthook.yml')).toBe('pre-commit:\n  commands: {}\n')
-  })
-
-  it('a seed is recreated only when missing; an edited seed never drifts --check', () => {
-    silenced(() => init(dir))
-    rmSync(join(dir, 'DESIGN.md'))
-    silenced(() => sync({}, dir))
-    expect(existsSync(join(dir, 'DESIGN.md'))).toBe(true)
-    write('DESIGN.md', '# my design\n')
-    silenced(() => sync({}, dir))
-    expect(read('DESIGN.md')).toBe('# my design\n')
-    expect(silenced(() => sync({ check: true }, dir))).toBe(0)
-  })
-
-  it('a pre-existing consumer file at a managed dest is kept by init, then treated as drift', () => {
-    write('.claude/rules/basalt-tokens.md', '# predates basalt\n')
-    silenced(() => init(dir))
-    expect(read('.claude/rules/basalt-tokens.md')).toBe('# predates basalt\n')
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-    silenced(() => sync({ force: true }, dir))
-    expect(read('.claude/rules/basalt-tokens.md')).toBe(SHIPPED_RULE)
-  })
-})
-
-describe('block splicing (managed with markers)', () => {
-  it('appends the block when markers are absent, preserving existing host content', () => {
-    write('CLAUDE.md', '# fixture app\n\nMy own instructions.\n')
-    silenced(() => init(dir))
-    const host = read('CLAUDE.md')
-    expect(host.startsWith('# fixture app\n\nMy own instructions.')).toBe(true)
-    expect(host).toContain('<!-- basalt:begin')
-    expect(host).toContain('<!-- basalt:end -->')
-  })
-
-  it('replaces only the marked region on sync, preserving content before and after', () => {
-    silenced(() => init(dir))
-    // A stale region from an older basalt-ui, embedded in consumer-owned host content.
-    write(
-      'CLAUDE.md',
-      '# above\n\n<!-- basalt:begin 0.9.9 -->\nstale body\n<!-- basalt:end -->\n\n# below\n',
-    )
-    silenced(() => sync({ force: true }, dir))
-    const after = read('CLAUDE.md')
-    expect(after.startsWith('# above\n')).toBe(true)
-    expect(after.trimEnd().endsWith('# below')).toBe(true)
-    expect(after).not.toContain('stale body')
-    expect(after.match(/<!-- basalt:begin/g)?.length).toBe(1)
-  })
-
-  it('errors loudly on duplicate begin markers instead of silently picking one', () => {
-    silenced(() => init(dir))
-    const block = read('CLAUDE.md')
-    write('CLAUDE.md', `${block}\n\n${block}`)
-    expect(() => silenced(() => sync({}, dir))).toThrow(/duplicate/)
-    expect(() => silenced(() => sync({ check: true }, dir))).toThrow(/duplicate/)
-  })
-})
-
-describe('--check performs zero writes', () => {
-  it('leaves the filesystem byte-identical on a clean tree AND on a drifted tree', () => {
-    silenced(() => init(dir))
-    const clean = snapshotDir()
-    expect(silenced(() => sync({ check: true }, dir))).toBe(0)
-    expect(snapshotDir()).toEqual(clean)
-
-    write('.claude/rules/basalt-tokens.md', '# my local law\n')
-    rmSync(join(dir, 'DESIGN.md'))
-    const drifted = snapshotDir()
-    expect(silenced(() => sync({ check: true }, dir))).toBe(1)
-    expect(snapshotDir()).toEqual(drifted)
-  })
-})
-
-// A real consumer's repo root (an API + collector) had its dashboard package in `web/`, one level
-// below the repo `.git`. `init`/`sync` used to seed lefthook.yml, .github/workflows/check.yml, and
-// src/query-client.ts relative to the PACKAGE dir regardless — none of which anything reads from
-// there, and re-created on every sync even after the consumer relocated them by hand.
-describe('repo-root-shaped seeds (lefthook.yml / check.yml / query-client.ts)', () => {
-  it('package IS the repo root (a bare .git dir present): writes lefthook.yml and check.yml, unchanged', () => {
-    mkdirSync(join(dir, '.git'))
-    silenced(() => init(dir))
-    expect(existsSync(join(dir, 'lefthook.yml'))).toBe(true)
-    expect(existsSync(join(dir, '.github/workflows/check.yml'))).toBe(true)
-  })
-
-  it('no .git anywhere in the tree: falls back to writing lefthook.yml and check.yml, unchanged', () => {
-    silenced(() => init(dir))
-    expect(existsSync(join(dir, 'lefthook.yml'))).toBe(true)
-    expect(existsSync(join(dir, '.github/workflows/check.yml'))).toBe(true)
-  })
-
-  it('package lives in a subdirectory of the repo: init skips both tooling seeds, notes the repo root, exits 0', () => {
-    mkdirSync(join(dir, '.git'))
-    const webDir = join(dir, 'web')
-    mkdirSync(webDir, { recursive: true })
-    writeFileSync(join(webDir, 'package.json'), JSON.stringify({ name: 'web' }))
-
-    const { code, log } = capture(() => init(webDir))
-
-    expect(code).toBe(0)
-    expect(existsSync(join(webDir, 'lefthook.yml'))).toBe(false)
-    expect(existsSync(join(webDir, '.github/workflows/check.yml'))).toBe(false)
-    expect(log).toContain('lefthook.yml')
-    expect(log).toContain('.github/workflows/check.yml')
-    expect(log).toContain(dir)
-    // Repo-root-shaped seeds are skipped; everything else still seeds normally.
-    expect(existsSync(join(webDir, 'DESIGN.md'))).toBe(true)
-    expect(existsSync(join(webDir, '.oxlintrc.json'))).toBe(true)
-  })
-
-  it('package lives in a subdirectory of the repo: sync ALSO skips both tooling seeds and notes it, exits 0', () => {
-    mkdirSync(join(dir, '.git'))
-    const webDir = join(dir, 'web')
-    mkdirSync(webDir, { recursive: true })
-    writeFileSync(join(webDir, 'package.json'), JSON.stringify({ name: 'web' }))
-    silenced(() => init(webDir))
-
-    const { code, log } = capture(() => sync({}, webDir))
-
-    expect(code).toBe(0)
-    expect(existsSync(join(webDir, 'lefthook.yml'))).toBe(false)
-    expect(existsSync(join(webDir, '.github/workflows/check.yml'))).toBe(false)
-    expect(log).toContain('lefthook.yml')
-  })
-
-  it('an existing query-client.ts elsewhere under src/ suppresses the seed and names the found file', () => {
-    writeFileSync(
-      join(dir, 'package.json'),
-      JSON.stringify({ name: 'fixture', dependencies: { '@tanstack/react-query': '^5.101.0' } }),
-    )
-    write('src/lib/query-client.ts', 'export const queryClient = 1\n')
-
-    const { code, log } = capture(() => init(dir))
-
-    expect(code).toBe(0)
-    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(false)
-    expect(read('src/lib/query-client.ts')).toBe('export const queryClient = 1\n')
-    expect(log).toContain('src/lib/query-client.ts')
-  })
-
-  it('an existing query-client.ts elsewhere under src/ keeps suppressing the seed on sync', () => {
-    writeFileSync(
-      join(dir, 'package.json'),
-      JSON.stringify({ name: 'fixture', dependencies: { '@tanstack/react-query': '^5.101.0' } }),
-    )
-    silenced(() => init(dir))
-    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(true)
-    rmSync(join(dir, 'src/query-client.ts'))
-    write('src/lib/query-client.ts', 'export const queryClient = 1\n')
-
-    const { code, log } = capture(() => sync({}, dir))
-
-    expect(code).toBe(0)
-    expect(existsSync(join(dir, 'src/query-client.ts'))).toBe(false)
-    expect(log).toContain('src/lib/query-client.ts')
-  })
-})

package/src/cli/shipped-versions.test.ts

@@ -1,83 +0,0 @@
-/**
- * No shipped artifact may name a basalt version npm never served.
- *
- * Three rounds running, the newest `MIGRATING.md` heading named a phantom — `1.20.1` (shipped as
- * 1.21.0), then `1.21.1` (shipped as 1.22.0) — because the docs pass runs BEFORE semantic-release
- * computes the number, so whatever is written is a guess. That would be a docs problem alone if it
- * stayed in docs. It does not: `sync` copies `agent/rules/**` and `agent/skills/**` verbatim into
- * every consumer, so "Since 1.21.1" is currently shipped, as fact, into seven repos.
- *
- * This is the gate that ends it, and it is mechanical rather than editorial: every basalt-shaped
- * version literal in a file a consumer receives must appear as a release heading in CHANGELOG.md —
- * the one file `semantic-release` writes AFTER the number exists. A guessed version fails here
- * before it can ship.
- *
- * Deliberately NOT a ban on version literals: `agent/rules/**` is release-history prose and
- * "widened at 1.21.0, promoted at 1.22.0" is exactly the sentence a consumer needs. What it may
- * not do is name a release that does not exist.
- *
- * The complementary half — no version stamped into a file nothing ever rewrites — lives in
- * `toolchain-wiring.test.ts` ("DESIGN.md carries no version").
- *
- * Run: bun test packages/basalt-ui/src/cli/shipped-versions.test.ts
- */
-import { readdirSync, readFileSync, statSync } from 'node:fs'
-import { join, relative, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { describe, expect, it } from 'bun:test'
-
-const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
-
-/** Every version CHANGELOG.md records, plus the one package.json currently declares. */
-const RELEASED = new Set<string>([
-  ...(
-    readFileSync(resolve(PKG_ROOT, 'CHANGELOG.md'), 'utf8').match(/^#+\s*\[?(\d+\.\d+\.\d+)/gm) ??
-    []
-  ).map((h) => h.replace(/^#+\s*\[?/, '')),
-  (JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8')) as { version: string })
-    .version,
-])
-
-/**
- * basalt's own version line is 0.x / 1.x, so a literal with any other major belongs to a peer
- * (visx 4.0.0, motion 12.42.0, the fontsource 5.2.x trio) and is none of this gate's business. A
- * `^`/`~`/`@`-prefixed literal is a dependency RANGE for the same reason — `vite-plugin-pwa
- * (^1.3.0)` shares a major with basalt and is still not a claim about basalt.
- */
-const BASALT_VERSION_LITERAL = /(^|[^-~^@\w.])([01]\.\d+\.\d+)(?![\w.])/g
-
-function versionsIn(content: string): string[] {
-  return [...content.matchAll(BASALT_VERSION_LITERAL)].map((m) => m[2] as string)
-}
-
-/** Every file under `dir`, recursively. */
-function filesUnder(dir: string): string[] {
-  return readdirSync(dir).flatMap((name) => {
-    const abs = join(dir, name)
-    return statSync(abs).isDirectory() ? filesUnder(abs) : [abs]
-  })
-}
-
-// Everything `init`/`sync` place in a consumer repo, plus the presets they `extends` into.
-const SHIPPED = [
-  ...filesUnder(resolve(PKG_ROOT, 'agent')),
-  resolve(PKG_ROOT, 'configs/check.yml'),
-  resolve(PKG_ROOT, 'configs/lefthook.yml'),
-]
-
-describe('shipped agent assets name only versions that exist', () => {
-  it.each(SHIPPED.map((abs) => [relative(PKG_ROOT, abs), abs] as const))(
-    '%s',
-    (_rel, abs: string) => {
-      const unreleased = [...new Set(versionsIn(readFileSync(abs, 'utf8')))].filter(
-        (v) => !RELEASED.has(v),
-      )
-      expect(unreleased).toEqual([])
-    },
-  )
-
-  it('reads a real changelog, so an empty RELEASED set can never make this vacuous', () => {
-    expect(RELEASED.size).toBeGreaterThan(20)
-    expect(RELEASED.has('1.21.1')).toBe(false)
-  })
-})

package/src/cli/tarball-parity.test.ts

@@ -1,44 +0,0 @@
-/**
- * Fast tarball-parity approximation: every source path the CLI reads via readSource must exist on
- * disk AND be covered by a package.json `files` entry — otherwise `init`/`sync` silently skip it
- * for every npm consumer while working fine in this repo (exactly how the skills shipped outside
- * the tarball at 1.0.0). The authoritative check against the real packed artifact runs in
- * scripts/pack-test.sh (check-tarball-parity.mjs); this one runs on every `bun test`.
- */
-import { describe, expect, it } from 'bun:test'
-import { existsSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-import { managedFiles } from './index.ts'
-
-const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url))
-const pkg = JSON.parse(readFileSync(resolve(PKG_ROOT, 'package.json'), 'utf8')) as {
-  files: string[]
-  bin: Record<string, string>
-}
-
-/** True when `path` is matched by one of the `files` entries (dir prefix or exact file). */
-function coveredByFilesField(path: string): boolean {
-  return pkg.files.some((entry) => {
-    const dir = entry.endsWith('/') ? entry : `${entry}/`
-    return path === entry || path.startsWith(dir)
-  })
-}
-
-const sources = [...new Set(managedFiles({ hasRouter: true, hasQuery: true }).map((f) => f.source))]
-
-describe('tarball parity (files-field approximation)', () => {
-  it.each(sources)('CLI-read source %s exists and is covered by the files field', (source) => {
-    expect(existsSync(resolve(PKG_ROOT, source))).toBe(true)
-    expect(coveredByFilesField(source)).toBe(true)
-  })
-
-  it('every bin entry points at a shipped file', () => {
-    for (const binPath of Object.values(pkg.bin)) {
-      const rel = binPath.replace(/^\.\//, '')
-      expect(existsSync(resolve(PKG_ROOT, rel))).toBe(true)
-      expect(coveredByFilesField(rel)).toBe(true)
-    }
-  })
-})

package/src/cli/template-format.test.ts

@@ -1,64 +0,0 @@
-/**
- * Format-idempotency for every shipped template that lands in a consumer VERBATIM — the `managed`
- * files (rules, skills, the marker-spliced CLAUDE block; see `./index.ts`'s `managedFiles()`).
- * `seed` templates are excluded: they are a one-time starting point the consumer immediately owns
- * and may reformat however they like, so their shipped formatting is not load-bearing.
- *
- * basalt-ui itself MANDATES oxfmt in the shipped lefthook/CI templates — so if a shipped `copy`/
- * `block` template's bytes are not already oxfmt-clean, the first thing a consumer does (run
- * `basalt sync`, or just commit) puts oxlint/oxfmt and `sync --check` in permanent disagreement:
- * `basalt sync` writes the drifted bytes, the lefthook pre-commit hook's own `oxfmt --check`
- * rejects the commit, running `oxfmt` to fix it re-drifts the file from what `sync --check`
- * expects. This is exactly how `CLAUDE-block.md.tpl` shipped: no blank line after
- * `<!-- basalt:begin -->`, which oxfmt's own block-HTML-comment rule then rewrites, re-triggering
- * drift forever. Assert every copy/block template round-trips through the exact oxfmt binary +
- * config basalt-ui ships, unchanged — this class of "basalt's own gates fighting each other" bug
- * must not recur.
- */
-import { spawnSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { describe, expect, it } from 'bun:test'
-
-import { RULE_NAMES, SKILL_NAMES } from './index'
-
-const PKG_ROOT = resolve(import.meta.dir, '../..')
-const REPO_ROOT = resolve(PKG_ROOT, '../..')
-const OXFMT_BIN = resolve(REPO_ROOT, 'node_modules/.bin/oxfmt')
-const OXFMT_CONFIG = resolve(PKG_ROOT, 'configs/oxfmt.json')
-
-/** Format `content` through the exact oxfmt binary + config basalt-ui ships; assert it is a no-op. */
-function expectOxfmtNoop(fileName: string, content: string): void {
-  const result = spawnSync(OXFMT_BIN, ['--stdin-filepath', fileName, '-c', OXFMT_CONFIG], {
-    input: content,
-    encoding: 'utf8',
-  })
-  expect(result.status).toBe(0)
-  expect(result.stdout).toBe(content)
-}
-
-describe('shipped managed templates are oxfmt-clean', () => {
-  it('CLAUDE-block.md.tpl (managed, marker-spliced) round-trips unchanged with placeholders filled', () => {
-    const tpl = readFileSync(resolve(PKG_ROOT, 'agent/templates/CLAUDE-block.md.tpl'), 'utf8')
-    const filled = tpl
-      .replace(/\{\{BASALT_VERSION\}\}/g, '1.0.0')
-      .replace(/\{\{APP_NAME\}\}/g, 'app')
-    expectOxfmtNoop('CLAUDE.md', filled)
-  })
-
-  it.each([...RULE_NAMES])('agent/rules/basalt-%s.md (managed) round-trips unchanged', (name) => {
-    const content = readFileSync(resolve(PKG_ROOT, `agent/rules/basalt-${name}.md`), 'utf8')
-    expectOxfmtNoop(`basalt-${name}.md`, content)
-  })
-
-  it.each([...SKILL_NAMES])('agent/skills/%s/SKILL.md (managed) round-trips unchanged', (name) => {
-    const content = readFileSync(resolve(PKG_ROOT, `agent/skills/${name}/SKILL.md`), 'utf8')
-    expectOxfmtNoop('SKILL.md', content)
-  })
-
-  it('configs/oxfmt.json (seeded verbatim as .oxfmtrc.json) round-trips unchanged', () => {
-    // A seed, but its bytes land verbatim and oxfmt itself reads the result — keep it clean too.
-    const content = readFileSync(resolve(PKG_ROOT, 'configs/oxfmt.json'), 'utf8')
-    expectOxfmtNoop('.oxfmtrc.json', content)
-  })
-})