basalt-ui 1.27.0 → 1.29.0

package/src/cli/init.ts

@@ -0,0 +1,247 @@
+/**
+ * `init` — split out of `src/cli/index.ts` (C2) so the dispatcher file holds routing only. Imports
+ * the managed-file manifest engine back from `./index`, this package's shared CLI helpers, and the
+ * oxlint-preset plugin reader from `./sync` (also called there).
+ */
+import { existsSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+
+import { deriveSpacing } from '../tokens'
+import type { MergeLintResult, ScaffoldFlags } from './index'
+import {
+  MANIFEST_PATH,
+  findBasaltInstall,
+  managedFiles,
+  mergeOxlintExtends,
+  normalizeForLedger,
+  patchPackageJson,
+  pruneRetiredManagedFiles,
+  readManifest,
+  reconcileRoots,
+  relativePosix,
+  renderContext,
+  reportPrune,
+  resolvePeerFlags,
+  resolvePlacement,
+  rootsNotices,
+  sha256,
+  shippedAssetPath,
+  unitState,
+  writeFileEnsuringDir,
+  writeUnit,
+} from './index'
+import { readOxlintPresetPlugins } from './sync'
+
+/**
+ * What a consumer LOSES by `init` keeping a file it already had — the half the aggregate
+ * `20 written, 2 kept` never said. A kept `.oxlintrc.json` is the headline case: the framework's
+ * whole lint half stays off, and every gate downstream reports green over it.
+ */
+const KEPT_FILE_COST: Record<string, string> = {
+  '.oxlintrc.json':
+    'the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / ' +
+    'unicorn plugins) is NOT active — nothing else turns it on, and every gate stays green ' +
+    'without it. Re-run with `--merge-lint` to splice the extends in, or add it by hand.',
+  'lefthook.yml':
+    'the pre-commit oxlint / oxfmt / check-theme jobs are not wired — add `extends: ' +
+    '[<preset>]` to your own file.',
+  '.github/workflows/check.yml':
+    'CI does not run check-theme or the sync drift gate — copy those steps into your own workflow.',
+  '.oxfmtrc.json': 'your existing formatter config stands; basalt formats nothing on its own.',
+  'DESIGN.md': 'the design brief Claude reads is yours, not the seeded one.',
+}
+
+/** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
+export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags = {}): number {
+  // ── Describe the repo BEFORE rendering anything ───────────────────────────
+  // Every roots-derived seed (the CI oxfmt globs, DESIGN.md's series path, the default scan
+  // exemption) renders from `basalt.roots`, so the key has to exist first. Writing it is what
+  // stops a workspace repo scaffolding a guard that scans zero files while doctor reports green.
+  const install = findBasaltInstall(cwd)
+  if (install.dir === null) {
+    console.error(
+      `⚠ basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it — the ` +
+        'seeded `extends` paths and CI steps are being written against the repo root by assumption. ' +
+        'Install basalt-ui here (or at the repo root) and re-run `basalt-ui init` so they resolve.',
+    )
+  }
+
+  const rootsState = reconcileRoots(cwd, { write: true })
+
+  // Built AFTER the roots patch — every roots-derived template variable reads the key just written.
+  const ctx = renderContext(cwd)
+
+  // `basalt-tokens.md` tells the consumer to wire `oxlint . && basalt-ui check-theme` into their
+  // lint, and init's own closing message says to run check-theme next — but nothing ever added a
+  // script, so the guard stayed manual for exactly as long as someone remembered it.
+  const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`
+  const seededLintScript = patchPackageJson(cwd, (pkg) => {
+    const scripts = (pkg['scripts'] ?? {}) as Record<string, unknown>
+    if (scripts['lint:basalt'] !== undefined) return false
+    pkg['scripts'] = { ...scripts, 'lint:basalt': lintScript }
+    return true
+  })
+
+  const manifest = readManifest(cwd)
+  const peers = resolvePeerFlags(cwd, scaffoldFlags)
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
+
+  const writtenFiles: string[] = []
+  const keptFiles: string[] = []
+  const missingSources: string[] = []
+
+  for (const file of files) {
+    const state = unitState(file, cwd, ctx)
+    if (state.desired === null) {
+      missingSources.push(file.source)
+      continue
+    }
+
+    // Whole files (managed + seed) are skip-if-exists on init; a marker-spliced region always
+    // inserts/updates itself inside its host file.
+    const destExists = existsSync(resolve(cwd, file.dest))
+    if (!file.markers && destExists) {
+      // Already present — keep the consumer's copy untouched. Record the SHIPPED hash (normalized,
+      // same ledger form `writeUnit` uses) so a later sync treats a pre-existing-but-different file
+      // as locally drifted (skip unless --force), never silently clobbering a file the consumer
+      // authored before init.
+      manifest.files[file.dest] = sha256(normalizeForLedger(state.desired))
+      keptFiles.push(file.dest)
+      continue
+    }
+
+    const hash = writeUnit(file, cwd, state.desired)
+    manifest.files[file.dest] = hash
+    writtenFiles.push(file.dest)
+  }
+
+  // A re-`init` over an existing install reconciles the derived namespaces too — otherwise the only
+  // route out of a retired rule file is `sync`, and `init` is what a consumer reaches for after an
+  // upgrade that changed the doctrine set.
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files)
+
+  const mergeLint: MergeLintResult | null =
+    scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null
+
+  manifest.basaltVersion = ctx.vars.BASALT_VERSION
+  manifest.spacingScale = { ...deriveSpacing(0).scale }
+  writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}\n`)
+
+  console.log(
+    `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`,
+  )
+  reportPrune(pruned)
+  if (missingSources.length > 0) {
+    console.log(
+      `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
+    )
+  }
+  // Naming the kept files is the fix for the report's headline false-green: `20 written, 2 kept`
+  // named neither the file nor the consequence, so a repo that already had an `.oxlintrc.json`
+  // ended up with the framework's lint half off and every gate downstream reporting green.
+  if (keptFiles.length > 0) {
+    console.log(`\nKept (already present — basalt did not touch them):`)
+    for (const dest of keptFiles) {
+      const cost = KEPT_FILE_COST[dest]
+      console.log(cost === undefined ? `  · ${dest}` : `  · ${dest} — ${cost}`)
+    }
+  }
+  if (mergeLint !== null) {
+    const mergeMessage: Record<MergeLintResult, string> = {
+      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+      already: '.oxlintrc.json already extends the shipped preset — nothing to do',
+      absent:
+        'no existing .oxlintrc.json to merge into (the seeded one already extends the preset)',
+      unreadable: '.oxlintrc.json is not valid JSON — merge the extends entry by hand',
+      'has-comments':
+        '.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each ' +
+        `rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`,
+    }
+    console.log(`basalt-ui init: --merge-lint — ${mergeMessage[mergeLint]}`)
+  }
+  const rootsMessages = rootsNotices(rootsState)
+  for (const line of rootsMessages.log) console.log(`basalt-ui init: ${line}`)
+  for (const line of rootsMessages.error) console.error(`⚠ basalt-ui init: ${line}`)
+  if (seededLintScript) {
+    console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`)
+  }
+  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped — neither lefthook nor GitHub
+  // Actions reads config from anywhere but the repo root, so a package living in a subdirectory
+  // skips both rather than relocating them into a spot nothing reads.
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui init: skipped lefthook.yml (this package is not the repo root — repo root ` +
+        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
+        `${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its ` +
+        `check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` ` +
+        'so the guard runs where your basalt config actually lives.',
+    )
+    console.log(
+      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root — ` +
+        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
+        `repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, 'configs/check.yml')} ` +
+        'into your root CI workflow instead.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui init: skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
+  // query-client.ts / __root.tsx reference the optional TanStack peers directly — seeding them
+  // without the peer installed would ship an unresolved import. Hint how to opt in instead.
+  if (!peers.hasQuery) {
+    console.log(
+      'basalt-ui init: skipped src/query-client.ts (no @tanstack/react-query dependency detected) — ' +
+        'install it, or re-run with --with-query, to scaffold it.',
+    )
+  }
+  if (!peers.hasRouter || !peers.hasQuery) {
+    console.log(
+      'basalt-ui init: skipped src/routes/__root.tsx (needs both @tanstack/react-router and ' +
+        '@tanstack/react-query) — install both, or re-run with --with-router --with-query, to scaffold it.',
+    )
+  }
+  // The guard-hook PreToolUse registration is NOT written automatically — add it manually to
+  // .claude/settings.json so every Write/Edit/MultiEdit goes through the theme guard.
+  console.log(
+    `\nTheme guard hook: add to .claude/settings.json → hooks.PreToolUse to catch violations before they land:\n` +
+      `  "hooks": {\n` +
+      `    "PreToolUse": [\n` +
+      `      {\n` +
+      `        "matcher": "Write|Edit|MultiEdit",\n` +
+      `        "hooks": [{ "type": "command", "command": "${ctx.vars.BASALT_BIN} guard-hook" }]\n` +
+      `      }\n` +
+      `    ]\n` +
+      `  }`,
+  )
+  // `init` on an existing app is a LINT-DEBT EVENT, not a no-op — the shipped preset turns on whole
+  // oxlint plugins the repo was never linted against, so previously-clean code lands with real
+  // findings on the first run. Naming the plugins (derived from the preset, so the count can't
+  // drift) is what turns that from a nasty surprise into a scheduled triage.
+  const presetPlugins = readOxlintPresetPlugins(ctx.pkgRoot)
+  if (presetPlugins.length > 0) {
+    console.log(
+      `\nLint debt: adopting the shipped oxlint preset on an EXISTING app is not a no-op — it turns ` +
+        `on ${presetPlugins.length} plugins (${presetPlugins.join(', ')}) plus the basalt/* design ` +
+        'rules, on code never linted against them. Run `oxlint .` now and triage the count before ' +
+        'your next commit; turn a rule off in your own .oxlintrc.json with a written reason rather ' +
+        'than blanket-disabling a plugin.',
+    )
+  }
+  console.log(
+    'Activate the hooks: `lefthook install` — the seeded lefthook.yml is inert until the git hooks ' +
+      'are written, and looks configured either way.',
+  )
+  // First adoption on a previously guard-clean repo can surface a wall of findings (the 1.0 guard
+  // adds several rule kinds beyond a legacy local guard) — steer toward tuning config, not mass-allow.
+  console.log(
+    `\nFirst run: run \`${ctx.vars.BASALT_BIN} check-theme\` next (or \`bun run lint:basalt\`), then ` +
+      'tune the per-rule `basalt.*` config keys in package.json for anything that fires — do not ' +
+      'mass-`theme-allow` findings. Then `basalt-ui doctor` to confirm the wiring actually took.',
+  )
+  return 0
+}

package/src/cli/sync.ts

@@ -0,0 +1,324 @@
+/**
+ * `sync` — split out of `src/cli/index.ts` (C2) so the dispatcher file holds routing only. Imports
+ * the managed-file manifest engine (`managedFiles`, `readManifest`, `writeUnit`, `reconcileRoots`,
+ * …), the toolchain-seam inspectors (`inspectLefthookGate`, `basaltPresetEntry`), and project
+ * resolution back from `./index`, this package's shared CLI helpers.
+ */
+import { existsSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+
+import { deriveSpacing } from '../tokens'
+import {
+  MANIFEST_PATH,
+  basaltPresetEntry,
+  classify,
+  conflictingProfileFlags,
+  declaredProfile,
+  diffSummary,
+  findBasaltInstall,
+  inspectLefthookGate,
+  isStringArray,
+  managedFiles,
+  normalizeForLedger,
+  parseJsonc,
+  pruneRetiredManagedFiles,
+  readBasaltConfig,
+  readIfExists,
+  readManifest,
+  readSource,
+  reconcileRoots,
+  relativePosix,
+  renderContext,
+  reportPrune,
+  resolvePeerFlags,
+  resolvePlacement,
+  resolveProjectDir,
+  rootsNotices,
+  sha256,
+  shippedAssetPath,
+  unitState,
+  writeFileEnsuringDir,
+  writeUnit,
+} from './index'
+
+/** The oxlint plugins the shipped preset switches on — read from the preset, never restated. */
+export function readOxlintPresetPlugins(pkgRoot: string): string[] {
+  const raw = readSource(pkgRoot, 'configs/oxlint.json')
+  if (raw === null) return []
+  try {
+    const plugins = (JSON.parse(raw) as { plugins?: unknown }).plugins
+    return isStringArray(plugins) ? plugins : []
+  } catch {
+    return []
+  }
+}
+
+export type SyncOptions = {
+  force?: boolean
+  check?: boolean
+  /** The raw flag list, read for `--tokens-only` / `--framework` exactly as check-theme reads it. */
+  flags?: readonly string[]
+}
+
+/**
+ * The nearest ANCESTOR of `dir` (exclusive) carrying a basalt manifest, or null.
+ *
+ * `resolveProjectDir` resolves to exactly one directory — `BASALT_CWD` when set, else the
+ * invocation cwd — and never walks. The shape that produced this function is the one that resolver
+ * doesn't cover: a consumer standing in `apps/dashboard`, the package that actually depends on
+ * basalt-ui, whose install lives at the repo root above it. With nothing walking up, `sync` read
+ * "no manifest here" as "nothing scaffolded yet" and wrote a complete second consumer beside the
+ * real one.
+ */
+/**
+ * The sentence `sync` prints when the cwd carries no install but an ancestor does.
+ *
+ * Shared with `doctor` deliberately. The two commands already share `resolveProjectDir`, but not
+ * the ADVICE: `sync` named the parent install (1.22.0's "stop scaffolding a second consumer" fix)
+ * while `doctor`, in the same directory, kept prescribing `basalt-ui init` — so following doctor
+ * literally performed the exact mistake that fix exists to prevent. One function, one sentence.
+ */
+export function parentInstallAdvice(cwd: string, parent: string, verb: string): string {
+  return (
+    `This repo's install is at ${relativePosix(cwd, parent)} (${parent}) — run ${verb} there, ` +
+    'or set BASALT_CWD to it.'
+  )
+}
+
+export function findManifestAbove(dir: string): string | null {
+  let current = resolve(dir, '..')
+  for (;;) {
+    if (existsSync(resolve(current, MANIFEST_PATH))) return current
+    const parent = resolve(current, '..')
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+/**
+ * Reconcile managed files with the shipped versions via a sha256 three-way compare.
+ *
+ * - `--check` makes NO writes; exits non-zero if any managed file is out-of-date or locally drifted
+ *   (a CI freshness gate), exit 0 when all current.
+ * - `--force` overwrites locally-drifted files instead of skipping them.
+ *
+ * Runs against `resolveProjectDir(cwd)`, exactly as `check-theme` and `doctor` do — and then
+ * REFUSES rather than scaffolding when the resolved project has no manifest. See
+ * {@link findManifestAbove} for the failure that bought this: `sync` is the drift refresh and
+ * `init` is the scaffold, so placing twenty files on a cwd that was never a consumer is a decision
+ * `sync` does not get to make silently.
+ */
+export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd()): number {
+  const syncFlags = opts.flags ?? []
+  if (conflictingProfileFlags(syncFlags)) {
+    console.error('basalt-ui sync: --tokens-only and --framework are alternatives — pass one.')
+    return 1
+  }
+  const project = resolveProjectDir(invocationCwd)
+  const cwd = project.dir
+  if (project.relocatedFrom !== null) {
+    console.log(`basalt-ui sync: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`)
+  }
+
+  // Profile before the refusal, because in a tokens-only consumer the refusal's own advice is
+  // wrong: it names `basalt-ui init`, and `doctor` in the same directory at the same version says
+  // in so many words that init is NOT the fix there — it places a Mantine doctrine the consumer
+  // has no use for. Mirrors doctor's manifest row verbatim, and exits 0 so `sync --check` is
+  // wirable into a tokens-only repo's CI (the one drift gate every other consumer runs).
+  //
+  // DECLARED, never inferred — the same asymmetry check-theme applies, for the same reason: the
+  // answer SILENCES the whole reconciliation, and inferring it from a missing @mantine/core would
+  // turn a framework consumer that keeps Mantine in a sibling package into a silent no-op.
+  if (declaredProfile(readBasaltConfig(cwd), syncFlags) === 'tokens-only') {
+    console.log(
+      `basalt-ui sync: ${MANIFEST_PATH}: n/a — a tokens-only consumer has no scaffold to ` +
+        'reconcile. The token layer is refreshed by re-running `basalt-ui tokens:css`, and ' +
+        '`tokens:css --check` is its drift gate. Pass --framework to force the full profile.',
+    )
+    return 0
+  }
+
+  // The refusal runs BEFORE reconcileRoots, which WRITES `basalt.roots` into package.json — that
+  // key is half the damage: a second `basalt` block means check-theme scans a different tree
+  // depending on which directory it was invoked from.
+  if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
+    const elsewhere = findManifestAbove(cwd)
+    const wouldWrite = managedFiles(resolvePeerFlags(cwd, {}), resolvePlacement(cwd)).length
+    console.error(
+      `✖ basalt-ui sync: no ${MANIFEST_PATH} at ${cwd} — refusing to scaffold. ` +
+        `\`sync\` refreshes an EXISTING basalt install; creating one is \`basalt-ui init\`'s ` +
+        `decision, and continuing here would write ${wouldWrite} managed file(s) into this ` +
+        'directory.' +
+        (elsewhere === null
+          ? ' No manifest exists at any ancestor either — run `basalt-ui init` here if this ' +
+            'package really is meant to be a consumer.'
+          : ` ${parentInstallAdvice(cwd, elsewhere, 'sync')}`),
+    )
+    return 1
+  }
+
+  // Before renderContext, which reads `basalt.roots` for the roots-derived template variables.
+  const rootsState = reconcileRoots(cwd, { write: opts.check !== true })
+  const ctx = renderContext(cwd)
+  const manifest = readManifest(cwd)
+  const peers = resolvePeerFlags(cwd, {})
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
+
+  let updated = 0
+  // `created` and `recreated` were one counter, and `0 updated, 20 recreated` is what a full
+  // scaffold printed — a word that means "it was here, it went missing, I put it back" describing
+  // twenty files this directory never had. The ledger already knows which: an entry in
+  // `manifest.files` is basalt saying it placed the file once.
+  let created = 0
+  let recreated = 0
+  let skippedDrift = 0
+  let staleForCheck = 0
+  const driftLines: string[] = []
+  const missingSources: string[] = []
+
+  for (const file of files) {
+    const state = unitState(file, cwd, ctx)
+    if (state.desired === null) {
+      missingSources.push(file.source)
+      continue
+    }
+
+    const tracked = manifest.files[file.dest] !== undefined
+
+    // `seed` is written once, then owned by the consumer — never reconciled, never reported.
+    if (file.mode === 'seed') {
+      if (state.current === null && !opts.check) {
+        manifest.files[file.dest] = writeUnit(file, cwd, state.desired)
+        if (tracked) recreated++
+        else created++
+      }
+      continue
+    }
+
+    const kind = classify(state, manifest.files[file.dest])
+
+    if (kind === 'current') {
+      // On-disk bytes already equal `desired` exactly — record the ledger's normalized form
+      // (not the raw bytes) so this entry keeps behaving like every other `writeUnit`-recorded
+      // hash for a future classify() call.
+      manifest.files[file.dest] = sha256(normalizeForLedger(state.desired))
+      continue
+    }
+
+    if (kind === 'drifted' && !opts.force) {
+      driftLines.push(diffSummary(file, state))
+      staleForCheck++
+      skippedDrift++
+      continue
+    }
+
+    // missing | unchanged | (drifted && force) → write the shipped version.
+    staleForCheck++
+    if (opts.check) continue
+    manifest.files[file.dest] = writeUnit(file, cwd, state.desired)
+    if (kind !== 'missing') updated++
+    else if (tracked) recreated++
+    else created++
+  }
+
+  // Retired rules/skills: the derived namespaces (RULE_NAMES / SKILL_NAMES) are the only managed
+  // sets whose MEMBERSHIP moves between versions, so this is where an upstream deletion reaches a
+  // consumer. Counted into `staleForCheck` so `sync --check` is red until it is applied — a rule
+  // file basalt stopped shipping is drift, and the agent goes on reading it otherwise.
+  const pruned = pruneRetiredManagedFiles(cwd, manifest, files, {
+    dryRun: opts.check === true,
+    force: opts.force === true,
+  })
+  staleForCheck += pruned.removed.length + pruned.drifted.length
+
+  // Placement notices — informational, never affect the exit code (a skipped tooling seed or a
+  // relocated scaffold is a legitimate consumer choice, not a sync failure).
+  if (!placement.isPackageRepoRoot) {
+    console.log(
+      `basalt-ui sync: skipped lefthook.yml (this package is not the repo root — repo root ` +
+        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
+        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
+    )
+    console.log(
+      `basalt-ui sync: skipped .github/workflows/check.yml (this package is not the repo root — ` +
+        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
+        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    console.log(
+      `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
+
+  const rootsMessages = rootsNotices(rootsState)
+  for (const line of rootsMessages.log) console.log(`basalt-ui sync: ${line}`)
+  for (const line of rootsMessages.error) console.error(`⚠ basalt-ui sync: ${line}`)
+
+  // The two `extends` seams sync does NOT own. Reported here because sync is the command an
+  // UPGRADE runs, and an upgrade is exactly when a resolved path goes stale — 1.20.0 fixed the
+  // paths `init` renders and reached no existing consumer at all. Informational: these are
+  // consumer-owned files, and `doctor` is the gate that fails on them.
+  const install = findBasaltInstall(cwd)
+  const lefthookGate = inspectLefthookGate(placement.repoRoot)
+  if (lefthookGate.kind === 'absent') {
+    console.error(
+      `⚠ basalt-ui sync: ${lefthookGate.file}: \`lefthook dump\` resolves the merged config and ` +
+        'no pre-commit command runs check-theme — there is no pre-commit gate. Add ' +
+        `"extends: [${shippedAssetPath(install, placement.repoRoot, 'configs/lefthook.yml')}]".`,
+    )
+  }
+  const oxlintrcRaw = readIfExists(resolve(cwd, '.oxlintrc.json'))
+  const oxlintEntry =
+    oxlintrcRaw === null ? null : basaltPresetEntry(parseJsonc(oxlintrcRaw)?.['extends'])
+  if (oxlintEntry !== null && !existsSync(resolve(cwd, oxlintEntry))) {
+    console.error(
+      `⚠ basalt-ui sync: .oxlintrc.json extends "${oxlintEntry}", which does not exist — oxlint ` +
+        'refuses to start on a missing extends target (`NotFound`). Repoint it at ' +
+        `"${shippedAssetPath(install, cwd, 'configs/oxlint.json')}".`,
+    )
+  }
+
+  if (opts.check) {
+    if (driftLines.length > 0) {
+      console.error('basalt-ui sync --check: locally-drifted managed files:')
+      for (const l of driftLines) console.error(l)
+    }
+    const retired = [...pruned.removed, ...pruned.drifted]
+    if (retired.length > 0) {
+      console.error(
+        `basalt-ui sync --check: ${retired.length} retired rule/skill file(s) still present: ` +
+          `${retired.join(', ')} — run \`basalt-ui sync\`.`,
+      )
+    }
+    if (staleForCheck > 0) {
+      console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`)
+      return 1
+    }
+    console.log('✓ basalt-ui sync --check: all managed files current.')
+    return 0
+  }
+
+  manifest.basaltVersion = ctx.vars.BASALT_VERSION
+  manifest.spacingScale = { ...deriveSpacing(0).scale }
+  writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}\n`)
+
+  console.log(
+    `basalt-ui sync: ${updated} updated, ${created} created, ${recreated} recreated, ` +
+      `${skippedDrift} skipped (drift), ${pruned.removed.length} retired.`,
+  )
+  reportPrune(pruned)
+  if (driftLines.length > 0) {
+    console.log('Locally-edited files were skipped (run with --force to overwrite):')
+    for (const l of driftLines) console.log(l)
+  }
+  if (missingSources.length > 0) {
+    console.log(
+      `basalt-ui sync: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
+    )
+  }
+  return 0
+}