basalt-ui 1.32.1 → 1.34.0

package/src/cli/guard-hook.ts

@@ -5,17 +5,11 @@
  */
 import { isAbsolute, relative, resolve } from 'node:path'
 
-import { DEFAULT_GUARD_CONFIG } from '../guard'
-import type { GuardConfig } from '../guard'
 import { evaluateGuardHook } from '../guard/guard-hook'
-import {
-  DEFAULT_ROOTS,
-  SKIP,
-  declaredProfile,
-  defaultExempt,
-  readBasaltConfig,
-  resolveExemptRules,
-} from './index'
+import { SKIP, declaredProfile, defaultExempt, readBasaltConfig, resolveGuardConfig } from './index'
+import { DEFAULT_ROOTS } from './config'
+
+const ALLOW = '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
 
 /**
  * guard-hook — PreToolUse stdin adapter.
@@ -37,9 +31,7 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     }
   } catch {
     // Unreadable stdin → allow
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
     return 0
   }
 
@@ -48,36 +40,13 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
     payload = JSON.parse(raw)
   } catch {
     // Malformed JSON → allow (never block on a bad payload)
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
     return 0
   }
 
   const cfg = readBasaltConfig(cwd)
-  const guardCfg: GuardConfig = {
-    spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
-    rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
-    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
-    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
-    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
-    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
-    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
-    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
-    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
-    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
-    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
-    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
-    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
-    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
-    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
-    allowComment: 'theme-allow',
-    exemptRules: resolveExemptRules(cfg),
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
-    // Same detection check-theme uses: the hook must never block an edit over advice the app
-    // cannot take ("use @mantine/core's Select") in a repo with no Mantine.
-    ...(declaredProfile(cfg, []) === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
-  }
+  // Same profile as check-theme: never block an edit over advice a no-Mantine app cannot take.
+  const guardCfg = resolveGuardConfig(cfg, declaredProfile(cfg, []))
 
   // Honor the consumer's roots / exempt / skip config so the hook never blocks edits to exempted
   // palette source or files outside the guarded roots (mirrors checkTheme's file-walk scoping).
@@ -107,9 +76,7 @@ export async function guardHook(cwd: string = process.cwd()): Promise<number> {
       }) + '\n',
     )
   } else {
-    process.stdout.write(
-      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n',
-    )
+    process.stdout.write(ALLOW)
   }
   return 0
 }

package/src/cli/index.ts

@@ -1,18 +1,9 @@
 /**
- * basalt-ui CLI — `init`, `sync`, `check-theme`, `doctor`.
- *
- * `checkTheme` is a thin FS walker over the headless guard core (`../guard`). It reads the
- * BasaltConfig, builds a GuardConfig, walks the source roots, calls `checkSource` per file,
- * collects Finding[], groups/reports findings, and returns an exit code.
- *
- * `init` / `sync` scaffold and reconcile the framework's *agentic* surface into a consumer repo:
- * Claude Code rules + skills, a managed CLAUDE.md block, a DESIGN.md seed, and the toolchain
- * seeds (oxlint / oxfmt / lefthook / CI). Both are sha256-manifest driven for safe,
- * idempotent three-way reconciliation. Dependency-free — Node/Bun built-ins only.
- *
- * Runtime-agnostic (Node or Bun) — built-ins only, no `bun`-module import, so the exported API is
- * safe to import under plain Node. Config is read from the consuming package.json `"basalt"` key;
- * argo's hardcoded values are the DEFAULTS.
+ * basalt-ui CLI — the dispatcher plus the plumbing `init`, `sync`, `check-theme` and `doctor` (each
+ * in its own file) share. `init`/`sync` reconcile the agentic surface and the toolchain seeds into
+ * a consumer repo through a sha256 manifest (three-way, idempotent). Runtime-agnostic and
+ * dependency-free — Node/Bun built-ins only, no `bun`-module import. Config is the consuming
+ * package.json's `"basalt"` key; argo's values are the defaults.
  */
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'
@@ -39,225 +30,57 @@ import { COMMAND_OPTIONS, USAGE, unknownFlag } from './help'
 import { init } from './init'
 import { sync } from './sync'
 import { fontsCss, normalizeColorFunctions, tokensCss } from './tokens-css'
-
-/** Shape of the optional `"basalt"` key in a consumer's package.json. */
-export type BasaltConfig = {
-  /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
-  roots?: string[]
-  /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
-  exempt?: string[]
-  /**
-   * Declares this package a tokens-only consumer: it uses the `--vx-*` layer and no Mantine. Turns
-   * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
-   * factory, leaving the color and typography kinds live. Default: `'mantine'`.
-   *
-   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
-   * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
-   * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
-   * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
-   */
-  profile?: 'mantine' | 'tokens-only'
-  /**
-   * Extra files to scan, named individually and relative to this package — for a design surface
-   * that lives outside every root and outside the `index.html` / `public/` conventions the walker
-   * already derives. Also the ONLY way a `.json` is ever scanned: the guard understands JSON as
-   * markup, but a consumer repo's JSON is overwhelmingly config, fixtures and lockfiles, so
-   * blanket-scanning it is a false-positive generator rather than a guard.
-   *
-   * @example
-   * { include: ['app/manifest.json', 'emails/template.html'] }
-   */
-  include?: string[]
-  /** Named spacing-scale steps (px) flagged when used as a raw spacing prop. Default: 10/12/16/20/32. */
-  spacingSteps?: number[]
-  /** Per-kind severity override — `'warn'` reports without failing, `'error'` fails the build.
-   *  See `GuardSeverity` in ../guard/types for the grace-minor doctrine behind it. */
-  severity?: Partial<Record<GuardKind, GuardSeverity>>
-  /** Off-identity Mantine accent families forbidden as chrome accents. Default: argo's set. */
-  forbiddenAccents?: string[]
-  /** Earned accent hue recorded in DESIGN.md `{{ACCENT_HUE}}`. Default: `blue`. */
-  accentHue?: string
-  /**
-   * Flag any numeric radius prop literal (radius={6}) — use the radius token scale instead.
-   * Default: `true` (ON). Set `false` to disable the `raw-radius` check (e.g. a repo that DEFINES
-   * the radius primitives).
-   */
-  rawRadius?: boolean
-  /**
-   * Flag ad-hoc inline surface styling (`border`/`borderRadius`/`boxShadow` literals in a `style={{}}`)
-   * that bypasses the radius-token + `VX.surface.*` + `VX.shadowCard` system. Default: `true` (ON).
-   * Set `false` to disable the `raw-surface` check.
-   */
-  rawSurface?: boolean
-  /**
-   * Flag `withBorder` on a `Card` / `Paper`. Card depth is `--vx-shadow-card` — a whisper shadow
-   * with the 1px ring baked into the SAME value — so `withBorder` draws a SECOND, real border over
-   * that ring and the card reads heavy/boxed (docs/DESIGN-SPEC.md doctrine inversion #1).
-   * `withBorder={false}` and `<Card.Section withBorder>` (a section divider) both pass.
-   * Default: `true` (ON). Set `false` to disable the `card-with-border` check.
-   */
-  cardWithBorder?: boolean
-  /**
-   * Flag references to a raw Mantine ramp step used for surface color
-   * (`var(--mantine-color-gray-N)` / `var(--mantine-color-dark-N)`) — these bypass the basalt
-   * surface tokens. Default: `true` (ON). Set `false` to disable the `off-system-surface-var` check.
-   */
-  offSystemSurfaceVar?: boolean
-  /**
-   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`,
-   * `var(--mantine-color-red-6)`. A pinned step is one fixed swatch in BOTH color schemes, so it
-   * cannot stay legible in either; route a verdict color through `VX.status.*` / `--vx-status-*`,
-   * or drop the index (`c="red"`) and let the theme resolve the shade per scheme. `gray-*`/`dark-*`
-   * in `var()` form belong to `off-system-surface-var` instead. Default: `true` (ON). Set `false`
-   * to disable the `mantine-shade-index` check.
-   */
-  mantineShadeIndex?: boolean
-  /**
-   * Flag raw lowercase JSX layout/surface elements (`div`/`span`/`section`/…) carrying an inline
-   * `style={{}}` with a layout/surface property — steer to a Mantine layout primitive
-   * (`Box`/`Flex`/`Grid`/`Stack`/`Group`/`SimpleGrid`/`Paper`). Default: `true` (ON). Set `false`
-   * to disable the `raw-html-layout` check.
-   */
-  rawHtmlLayout?: boolean
-  /**
-   * Flag spacing/sizing literals inside an inline `style={{}}` (`padding`/`margin`/`gap`/…) — the
-   * `raw-spacing` check only catches the Mantine prop syntax. Default: `true` (ON). Set `false` to
-   * disable the `inline-spacing` check.
-   */
-  inlineSpacing?: boolean
-  /**
-   * Flag `display: 'flex' | 'grid' | 'inline-flex' | 'inline-grid'` in an inline `style={{}}` —
-   * steer to `<Flex>`/`<Grid>`/`<Group>`. Default: `true` (ON). Set `false` to disable the
-   * `inline-display` check.
-   */
-  inlineDisplay?: boolean
-  /**
-   * Flag raw `<AxisLeft>` / `<AxisBottom>` / `<AxisRight>` visx JSX inside chart files (a path
-   * containing `/charts/`) — these bypass the `AxisLeftNumeric` / `AxisBottomDate` /
-   * `AxisRightNumeric` primitives that carry the theme tokens + smart ticks. The legitimate wrapper
-   * (`Axes.tsx`, which IS the primitive) is exempt. Default: `true` (ON). Set `false` to disable the
-   * `raw-visx-axis` check.
-   */
-  rawVisxAxis?: boolean
-  /**
-   * Flag a hardcoded duration/spring/ease literal inline in a `transition={{...}}` prop — route it
-   * through `MOTION_DURATION` / `MOTION_SPRING` / `MOTION_EASE_STANDARD` instead. Default: `true`
-   * (ON). Set `false` to disable the `raw-motion-value` check.
-   */
-  rawMotionValue?: boolean
-  /**
-   * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
-   * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
-   * (ON). Set `false` to disable the `chart-missing-aria-label` check.
-   */
-  chartMissingAriaLabel?: boolean
-  /**
-   * Flag a raw lowercase `<input>`/`<select>`/`<textarea>` JSX element — it bypasses the entire
-   * theme, not just the iOS font-size floor. Use the Mantine equivalents (`TextInput`,
-   * `NumberInput`, `Select`, `Textarea`, …) instead. Default: `true` (ON). Set `false` to disable
-   * the `raw-form-control` check.
-   */
-  rawFormControl?: boolean
-  /**
-   * Flag a `fontSize`/`font-size` literal below 16 inside a `style={{…}}` on a raw form control,
-   * or a Mantine `styles={{ input: {…} }}` per-part style — the `styles.css` iOS floor is
-   * `!important`, so the override is dead code. Default: `true` (ON). Set `false` to disable the
-   * `sub-16-input-font` check.
-   */
-  sub16InputFont?: boolean
-  /**
-   * Path of the consumer's guard-exempt series file, for DESIGN.md `{{SERIES_MODULE_PATH}}`.
-   * Default: `<first basalt.root>/lib/series.ts` — see `resolveSeriesModulePath`.
-   */
-  seriesModulePath?: string
-  /**
-   * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
-   * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
-   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
-   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
-   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
-   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
-   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
-   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
-   *
-   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
-   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
-   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
-   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
-   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
-   * still suppresses. The array form stays supported and unchanged; nothing here is required.
-   *
-   * @example
-   * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
-   * @example
-   * { exemptRules: { 'raw-hex': { paths: ['site.webmanifest'],
-   *   reason: 'a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var' } } }
-   */
-  exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
-  /**
-   * Declares an intentional `ai` package major-version skew across workspace packages, exempting
-   * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
-   * because the whole point of this key is that the pairing is written down, not just switched off.
-   * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
-   *
-   * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
-   * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
-   * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
-   * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
-   * slips through unnoticed).
-   *
-   * @example
-   * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
-   * // neutralizes the one enum value that differs between the two majors.
-   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
-   *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
-   */
-  aiMajorSkewReason?: string
-}
+import { DEFAULT_ROOT, exemptRulePaths, resolveRoots } from './config'
+import type { BasaltConfig } from './config'
 
 /**
- * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
- * it exists. See `BasaltConfig.exemptRules`.
+ * The consumer's `GuardConfig`: every `basalt` key the guard knows, over `DEFAULT_GUARD_CONFIG`.
+ * One builder for `check-theme` and `guard-hook`, so the hook never judges an edit by a different
+ * config than the build. `exemptRules` reaches the guard as paths only — the reason the object form
+ * carries is accountability for a human and for `--audit-allows`, not a second shape to scan.
  */
-export type ExemptRuleEntry = string[] | { paths: string[]; reason: string }
-
-/** The paths half of an exemption entry, whichever form it was written in. */
-export function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[] {
-  if (entry === undefined) return []
-  return Array.isArray(entry) ? entry : entry.paths
-}
-
-/** The recorded reason for an exemption entry, or null for the bare-array form. */
-export function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null {
-  if (entry === undefined || Array.isArray(entry)) return null
-  return entry.reason.trim().length > 0 ? entry.reason.trim() : null
-}
+type PassthroughKey = Exclude<keyof GuardConfig, 'allowComment' | 'exemptRules' | 'profile'>
 
 /**
- * The guard-shaped `exemptRules` — paths only. The reason the object form carries never reaches
- * the guard: it is accountability for a human reading a diff and for `--audit-allows`, and giving
- * the scan a second shape to understand would only be a way for the two to disagree.
+ * The `basalt` keys that reach the guard verbatim — named, never matched by name at runtime.
+ * `satisfies Record<…>` makes a GuardConfig key missing here, or one that is not a key, a tsc error.
  */
-export function resolveExemptRules(cfg: BasaltConfig): GuardConfig['exemptRules'] {
-  if (cfg.exemptRules === undefined) return DEFAULT_GUARD_CONFIG.exemptRules
-  const out: Partial<Record<GuardKind, string[]>> = {}
-  for (const [kind, entry] of Object.entries(cfg.exemptRules)) {
-    out[kind as GuardKind] = exemptRulePaths(entry)
+const GUARD_PASSTHROUGH = {
+  spacingSteps: true,
+  rawRadius: true,
+  forbiddenAccents: true,
+  mantineShadeIndex: true,
+  rawSurface: true,
+  cardWithBorder: true,
+  offSystemSurfaceVar: true,
+  rawHtmlLayout: true,
+  inlineSpacing: true,
+  inlineDisplay: true,
+  rawVisxAxis: true,
+  rawMotionValue: true,
+  chartMissingAriaLabel: true,
+  rawFormControl: true,
+  sub16InputFont: true,
+  severity: true,
+} as const satisfies Record<PassthroughKey, true>
+
+export function resolveGuardConfig(cfg: BasaltConfig, profile: DoctorProfile): GuardConfig {
+  const exemptRules: Partial<Record<GuardKind, string[]>> = {}
+  for (const [kind, entry] of Object.entries(cfg.exemptRules ?? {})) {
+    exemptRules[kind as GuardKind] = exemptRulePaths(entry)
+  }
+  // Typed as the guard's shape, so a BasaltConfig field whose type drifts from it fails to compile.
+  const from: Partial<Pick<GuardConfig, PassthroughKey>> = cfg
+  const set = (Object.keys(GUARD_PASSTHROUGH) as PassthroughKey[]).filter(
+    (k) => (from[k] ?? null) !== null,
+  )
+  return {
+    ...DEFAULT_GUARD_CONFIG,
+    ...Object.fromEntries(set.map((k) => [k, from[k]])),
+    allowComment: 'theme-allow',
+    exemptRules,
+    ...(profile === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
   }
-  return out
-}
-
-export const DEFAULT_ROOT = 'src'
-export const DEFAULT_ROOTS = [DEFAULT_ROOT]
-
-/**
- * The configured source roots, or the built-in default. The ONE resolution every roots-derived seed
- * reads — an empty `roots: []` falls back rather than resolving to nothing, because a bare `??`
- * would let `[]` through and render an empty oxfmt glob into the seeded CI, reproducing the exact
- * "matches zero files" break this derivation exists to prevent.
- */
-export function resolveRoots(cfg: BasaltConfig): string[] {
-  return cfg.roots?.length ? cfg.roots : DEFAULT_ROOTS
 }
 
 /**
@@ -514,23 +337,9 @@ export function resolveProjectDir(cwd: string): ProjectResolution {
 }
 
 /**
- * Which shape of consumer a project-scoped command is looking at.
- *
- * A tokens-only consumer took the `--vx-*` layer and nothing else. Every guard kind whose remedy is
- * a Mantine component or the React theme factory is meaningless there — telling a Mantine-free app
- * to swap its `<select>` for `@mantine/core`'s `Select` is advice it must not take.
- *
- * DECLARED, never inferred, when the answer SILENCES something. The two callers want opposite
- * failure directions and so do not share a default:
- *
- * - `check-theme` (`declaredProfile`) turns 17 kinds OFF, so it moves on an explicit signal only —
- *   `--tokens-only`, or `"basalt": { "profile": "tokens-only" }`. Inferring it from the ABSENCE of
- *   `@mantine/core` would silence the Mantine half of the guard on any repo that keeps its Mantine
- *   dependency in a workspace package rather than the one holding the basalt config, which is
- *   precisely this round's "reports green while enforcing nothing" failure with the guard's own
- *   hand on the switch.
- * - `doctor` no longer infers a profile at all (workspace-wide Mantine detection was deleted along
- *   with the rest of the multi-repo discovery); it reads the same declaration `check-theme` does.
+ * Which shape of consumer a project-scoped command is looking at — DECLARED, never inferred
+ * (`--tokens-only`, or `"basalt": { "profile": "tokens-only" }`), because the answer switches the
+ * Mantine-remedy guard kinds off. Why that direction: package CLAUDE.md § CLI.
  */
 export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile {
   if (flags.includes('--tokens-only')) return 'tokens-only'
@@ -544,8 +353,21 @@ export function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): Do
  * vs `--selector-attribute`. Silently preferring one meant a CI step that accumulated both flags
  * enforced whichever the code happened to test first.
  */
-export function conflictingProfileFlags(flags: readonly string[]): boolean {
-  return flags.includes('--tokens-only') && flags.includes('--framework')
+export function conflictingProfileFlags(command: string, flags: readonly string[]): boolean {
+  const both = flags.includes('--tokens-only') && flags.includes('--framework')
+  if (both)
+    console.error(
+      `basalt-ui ${command}: --tokens-only and --framework are alternatives — pass one.`,
+    )
+  return both
+}
+
+/** Says so when `BASALT_CWD` moved the command off the directory it was invoked in. */
+export function noteRelocation(command: string, project: ProjectResolution): void {
+  if (project.relocatedFrom === null) return
+  console.log(
+    `basalt-ui ${command}: BASALT_CWD relocated from ${project.relocatedFrom} to ${project.dir}.`,
+  )
 }
 
 /**
@@ -605,19 +427,11 @@ function appShellFiles(rootAbs: string): string[] {
 const PLAIN_JSON_HINT_PATH = 'manifest.json'
 
 /**
- * The waiver closer for a file, gated on the profile.
- *
- * `guardWaiverHint` keys off the file class, and for a `.webmanifest` it leads with
- * `basaltAppPlugin` — right for a Mantine app, since a hex in a manifest can never be *right* and
- * the plugin removes the hand-copy entirely. A `profile: tokens-only` consumer has definitionally
- * opted out of that layer: rollhook's Astro site has no `index.html` for the plugin to transform,
- * imports no basalt JavaScript at all, and owns maskable icons the plugin does not emit. Leading
- * with the plugin there is advice the consumer cannot take, in the one release that finally gave
- * that file class a remedy.
- *
- * So under tokens-only a manifest is treated as what it is to that consumer — plain JSON, with the
- * member as the whole answer — plus one sentence saying which remedy is being withheld and why.
- * The remedy text still comes from the guard's own registry; only the class mapping is decided here.
+ * The waiver closer for a file, gated on the profile. `guardWaiverHint` leads a `.webmanifest` with
+ * `basaltAppPlugin` — right for a Mantine app, advice a `profile: tokens-only` consumer cannot take
+ * (rollhook's Astro site has no `index.html` for the plugin and owns its maskable icons). There the
+ * manifest is plain JSON — the member is the whole answer, plus one sentence on the withheld remedy.
+ * The remedy text still comes from the guard's registry; only the class mapping is decided here.
  */
 export function waiverHintFor(relPath: string, profile: DoctorProfile): string {
   if (profile !== 'tokens-only' || !relPath.endsWith('.webmanifest')) {
@@ -772,7 +586,7 @@ function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): Tem
     ACCENT_HUE: cfg.accentHue ?? 'blue',
     SERIES_MODULE_PATH: resolveSeriesModulePath(cfg),
     ROOTS_GLOBS: resolveRoots(cfg).map(toRootGlob).join(' '),
-    OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/oxlint.json'),
+    OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, OXLINT_FILES.preset),
     LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/lefthook.yml'),
     BASALT_BIN: basaltBinCommand(install, cwd),
   }
@@ -1077,7 +891,7 @@ export function managedFiles(
   const oxlintrc: ManagedFile = {
     dest: '.oxlintrc.json',
     mode: 'seed',
-    source: 'configs/oxlint.json',
+    source: OXLINT_FILES.preset,
     render: (ctx) => `{\n  "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"]\n}\n`,
   }
 
@@ -1395,16 +1209,9 @@ export function normalizeForLedger(text: string): string {
 
 /**
  * Write a managed unit to disk (whole file, or marker-spliced region). Returns the unit's hash —
- * `sha256(normalizeForLedger(desired))`, NOT the raw bytes.
- *
- * This is the ledger: the manifest already records "what basalt shipped last sync", one entry per
- * dest — a stored NORMALIZED hash makes that same single entry survive both a downstream formatter
- * (the consumer's own lefthook oxfmt reformatting the written file/block after this function has
- * already returned) and a version bump that changed the template's own words since the recorded
- * entry — the argo cross-version case: current is v1.0.0's block, post-oxfmt; desired is v1.0.1's
- * (different words, e.g. the CLI bin rename). Recording the raw hash can never reconcile that;
- * recording the normalized hash lets `classify()` normalize `state.current` the same way and
- * compare directly against it, no separate historical-hash storage required.
+ * `sha256(normalizeForLedger(desired))`, NOT the raw bytes: the normalized hash is what lets one
+ * manifest entry survive a downstream formatter and a cross-version template change (`classify`'s
+ * path 2 is the reader).
  */
 export function writeUnit(file: ManagedFile, cwd: string, desired: string): string {
   const destAbs = resolve(cwd, file.dest)
@@ -1427,13 +1234,8 @@ export function writeUnit(file: ManagedFile, cwd: string, desired: string): stri
  *                 manifest (written before this fix, or by a still-running older CLI) holds the RAW
  *                 hash of what was written, not the normalized one; keep matching it directly so an
  *                 upgrade never mass-classifies a pristine tree as drifted.
- *                 Residual transitional gap: a manifest written by a pre-1.0.2 CLI holds a raw hash
- *                 of the exact old bytes, so if the on-disk block was ALSO reformatted by a
- *                 downstream formatter AND the template body changed cross-version in the same
- *                 upgrade, none of the three paths above match and it classifies `drifted`, needing
- *                 one `--force`. Once any sync since writes a normalized entry (path 2/3 or a
- *                 healed write), the gap is closed for good for that file. Deliberately not solved
- *                 by keeping a historical per-version ledger — that's a real but bounded tradeoff.
+ *                 (A pre-1.0.2 raw entry whose block was ALSO reformatted across a template change
+ *                 needs one `--force`; bounded, and deliberately not solved with a version ledger.)
  *              2. `sha256(normalizeForLedger(current)) === manifestHash` — the ledger proper.
  *                 `manifestHash` normally holds `sha256(normalizeForLedger(<bytes written at the
  *                 last sync>))` (see `writeUnit`); normalizing `current` the same way and comparing
@@ -1665,22 +1467,26 @@ export function parseJsonc(text: string): Record<string, unknown> | null {
 /** Outcome of splicing the shipped preset into an `.oxlintrc.json` the consumer already had. */
 export type MergeLintResult = 'added' | 'already' | 'absent' | 'unreadable' | 'has-comments'
 
+/** The shipped oxlint files, package-relative — the one spelling every reader of them uses. */
+export const OXLINT_FILES = {
+  preset: 'configs/oxlint.json',
+  guards: 'configs/oxlint-basalt.json',
+  plugin: 'configs/oxlint-plugin.js',
+} as const
+
+/** Whether an `extends`/`jsPlugins` entry names that shipped basalt-ui file. */
+export const namesShipped = (entry: unknown, file: string): entry is string =>
+  typeof entry === 'string' && entry.endsWith(`basalt-ui/${file}`)
+
 /**
- * The `extends` entry pointing at the shipped oxlint preset, or null when none does.
- *
- * Returns the ENTRY rather than a boolean because the string alone proves nothing: a consumer that
- * upgraded (or moved to an isolated linker) keeps a perfectly well-shaped
- * `./node_modules/basalt-ui/configs/oxlint.json` that resolves to nothing, and oxlint then refuses
- * to start with `NotFound` while a check built to prove the framework is ON reports green. The
- * caller resolves this against the config's own directory — see `extendsSeam`.
+ * The `extends` entry naming a shipped preset (full or guards-only), or null. The ENTRY, not a
+ * boolean: a well-shaped `./node_modules/basalt-ui/configs/oxlint.json` can resolve to nothing
+ * (an upgrade, an isolated linker), and oxlint then dies `NotFound` while a check built to prove the
+ * lane is ON reports green — callers resolve it against the config's own directory.
  */
 export function basaltPresetEntry(entries: unknown): string | null {
-  if (!Array.isArray(entries)) return null
-  const match = entries.find(
-    (entry): entry is string =>
-      typeof entry === 'string' && entry.endsWith('basalt-ui/configs/oxlint.json'),
-  )
-  return match ?? null
+  const presets = [OXLINT_FILES.preset, OXLINT_FILES.guards]
+  return [entries].flat().find((e): e is string => presets.some((f) => namesShipped(e, f))) ?? null
 }
 
 // ── The lefthook gate — checked via `lefthook dump`, not hand-rolled YAML parsing ────────────────
@@ -1761,13 +1567,14 @@ export function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintRe
   if (raw === null) return 'absent'
   const cfg = parseJsonc(raw)
   if (cfg === null) return 'unreadable'
-  if (basaltPresetEntry(cfg['extends']) !== null) return 'already'
+  if ([cfg['extends']].flat().some((e) => namesShipped(e, OXLINT_FILES.preset))) return 'already'
   // Rewriting a JSONC config through JSON.stringify would silently delete the consumer's comments,
   // which in a lint config are usually the WHY of every disabled rule. Refuse and say so.
   if (stripJsonc(raw) !== raw) return 'has-comments'
-  const existing = Array.isArray(cfg['extends'])
-    ? (cfg['extends'] as unknown[]).filter((entry) => typeof entry === 'string')
-    : []
+  // The guards-only preset is a subset of the full one — upgrading replaces it, never stacks it.
+  const existing = [cfg['extends']]
+    .flat()
+    .filter((e): e is string => typeof e === 'string' && !namesShipped(e, OXLINT_FILES.guards))
   // Rebuild rather than spread, so `extends` keeps its original position when it was already there
   // and lands first when it wasn't — a diff a human reviews should not reshuffle the whole file.
   const merged: Record<string, unknown> = 'extends' in cfg ? {} : { extends: [presetPath] }

package/src/cli/sync.ts

@@ -20,6 +20,8 @@ import {
   isStringArray,
   managedFiles,
   normalizeForLedger,
+  noteRelocation,
+  OXLINT_FILES,
   parseJsonc,
   placementNotices,
   pruneRetiredManagedFiles,
@@ -44,14 +46,8 @@ import {
 
 /** 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 []
-  }
+  const plugins = parseJsonc(readSource(pkgRoot, OXLINT_FILES.preset) ?? 'null')?.['plugins']
+  return isStringArray(plugins) ? plugins : []
 }
 
 export type SyncOptions = {
@@ -111,15 +107,10 @@ export function findManifestAbove(dir: string): string | null {
  */
 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
-  }
+  if (conflictingProfileFlags('sync', syncFlags)) 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}.`)
-  }
+  noteRelocation('sync', project)
 
   // 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
@@ -265,7 +256,7 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     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')}".`,
+        `"${shippedAssetPath(install, cwd, OXLINT_FILES.preset)}".`,
     )
   }
 

package/src/commands/define-commands.ts

@@ -24,7 +24,6 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
-import { isDev } from '../common/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 
@@ -172,7 +171,8 @@ export function defineCommand(cmd: Command): Command {
 export function runCommand(id: CommandId, ctx?: CommandRunContext): void | Promise<void> {
   const cmd = activeCommands[id as string]
   if (cmd === undefined) {
-    if (isDev()) console.warn(`[basalt] runCommand: no command registered for "${id}"`)
+    if (process.env.NODE_ENV !== 'production')
+      console.warn(`[basalt] runCommand: no command registered for "${id}"`)
     return
   }
   return cmd.run(ctx)