basalt-ui 1.8.0 → 1.9.0

package/src/cli/index.ts

@@ -675,8 +675,105 @@ function resolvePeerFlags(cwd: string, flags: ScaffoldFlags): PeerFlags {
   }
 }
 
+/**
+ * Where the seed engine is running relative to the consumer's git repo — decides which
+ * repo-root-shaped seeds are safe to write. `init`/`sync` compute it once per run via
+ * `resolvePlacement` and print the matching skip notices themselves; `managedFiles` only reads it.
+ */
+type PlacementFlags = {
+  /** True when the package directory IS the detected repo root, or no `.git` exists anywhere above
+   *  it (a consumer not using git keeps today's behaviour exactly). False means the package lives
+   *  in a subdirectory of the repo (a monorepo's `web/`, say) — lefthook and GitHub Actions both
+   *  only read config at the repo root, so seeding either one there is worse than not seeding at
+   *  all. */
+  isPackageRepoRoot: boolean
+  /** Absolute path of the detected repo root. Meaningful only when `isPackageRepoRoot` is false —
+   *  otherwise it equals the package dir and is never read. */
+  repoRoot: string
+  /** Absolute path of a `query-client.ts` already present elsewhere under the package's `src/` (the
+   *  consumer relocated it — e.g. to `src/lib/query-client.ts`), or null. The seed's OWN
+   *  destination is deliberately excluded here — that exact-path case is handled by the ordinary
+   *  skip-if-exists logic every seed file already goes through, unchanged. */
+  relocatedQueryClient: string | null
+}
+
+/** The default placement — today's single-package-at-repo-root behaviour, unconditionally. */
+const ROOT_PLACEMENT: PlacementFlags = {
+  isPackageRepoRoot: true,
+  repoRoot: '',
+  relocatedQueryClient: null,
+}
+
+/**
+ * Walks up from `dir` looking for a `.git` entry — ordinarily a directory, but a git worktree or
+ * submodule points it at a FILE instead, and both still mean "this directory is the repo root".
+ * Stops at the filesystem root. Returns `dir` itself when no `.git` is found anywhere, so a
+ * consumer not using git falls back to today's behaviour exactly.
+ */
+function findRepoRoot(dir: string): string {
+  let current = dir
+  for (;;) {
+    if (existsSync(resolve(current, '.git'))) return current
+    const parent = dirname(current)
+    if (parent === current) return dir
+    current = parent
+  }
+}
+
+/**
+ * First path under `dir` (recursive) whose basename is `filename`, or null. Skips dependency/build
+ * dirs, mirroring `walkSourceFiles`'s scoping.
+ */
+function findFileNamed(dir: string, filename: string): string | null {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return null
+  }
+  for (const name of entries) {
+    if (name === 'node_modules' || name === '.git' || name === 'dist') continue
+    const abs = resolve(dir, name)
+    let isDir: boolean
+    try {
+      isDir = statSync(abs).isDirectory()
+    } catch {
+      continue
+    }
+    if (isDir) {
+      const found = findFileNamed(abs, filename)
+      if (found !== null) return found
+    } else if (name === filename) {
+      return abs
+    }
+  }
+  return null
+}
+
+/**
+ * Absolute path of a `query-client.ts` living elsewhere under the package's `src/`, or null. The
+ * seed's own destination is excluded — reseeding on top of a RELOCATED client (the failure this
+ * exists to prevent) is a different case from the seed's own path already being occupied, which the
+ * ordinary skip-if-exists logic handles unchanged.
+ */
+function findRelocatedQueryClient(cwd: string): string | null {
+  const seedAbs = resolve(cwd, 'src/query-client.ts')
+  const found = findFileNamed(resolve(cwd, 'src'), 'query-client.ts')
+  return found !== null && found !== seedAbs ? found : null
+}
+
+/** Resolve a run's placement flags once, from the consumer cwd. */
+function resolvePlacement(cwd: string): PlacementFlags {
+  const repoRoot = findRepoRoot(cwd)
+  return {
+    isPackageRepoRoot: repoRoot === cwd,
+    repoRoot,
+    relocatedQueryClient: findRelocatedQueryClient(cwd),
+  }
+}
+
 /** The full managed-file manifest. Stable, declarative — the single source of truth for init/sync. */
-function managedFiles(peers: PeerFlags): ManagedFile[] {
+function managedFiles(peers: PeerFlags, placement: PlacementFlags = ROOT_PLACEMENT): ManagedFile[] {
   // ── managed: exactly what Claude reads ──────────────────────────────────────
   const rules: ManagedFile[] = RULE_NAMES.map((name) => ({
     dest: `.claude/rules/basalt-${name}.md`,
@@ -804,10 +901,16 @@ function managedFiles(peers: PeerFlags): ManagedFile[] {
   // type) — both are documented optional peers, so seeding either scaffold without its peer(s)
   // installed would ship a file with an unresolved import.
   const scaffolds: ManagedFile[] = []
-  if (peers.hasQuery) scaffolds.push(queryClient)
+  if (peers.hasQuery && placement.relocatedQueryClient === null) scaffolds.push(queryClient)
   if (peers.hasRouter && peers.hasQuery) scaffolds.push(rootRoute)
 
-  return [...rules, ...skills, claudeBlock, design, oxfmt, lefthook, ci, oxlintrc, ...scaffolds]
+  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped: lefthook and GitHub Actions
+  // only ever read config at the repo root, so a package living in a subdirectory (a monorepo's
+  // `web/`) skips both rather than relocating them — the repo root very often already has its own
+  // lefthook/CI config, and writing over or beside it is worse than not writing at all.
+  const rootTooling: ManagedFile[] = placement.isPackageRepoRoot ? [lefthook, ci] : []
+
+  return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
 type Manifest = {
@@ -1041,7 +1144,8 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   const manifest = readManifest(cwd)
   migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
   const peers = resolvePeerFlags(cwd, scaffoldFlags)
-  const files = managedFiles(peers)
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
 
   let written = 0
   let skipped = 0
@@ -1082,6 +1186,28 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(', ')}`,
     )
   }
+  // 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 ` +
+        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
+    )
+    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; extend node_modules/basalt-ui/configs/check.yml from 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) {
@@ -1132,7 +1258,8 @@ export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): numbe
   const manifest = readManifest(cwd)
   if (!opts.check) migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest)
   const peers = resolvePeerFlags(cwd, {})
-  const files = managedFiles(peers)
+  const placement = resolvePlacement(cwd)
+  const files = managedFiles(peers, placement)
 
   let updated = 0
   let recreated = 0
@@ -1182,6 +1309,28 @@ export function sync(opts: SyncOptions = {}, cwd: string = process.cwd()): numbe
     else updated++
   }
 
+  // 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.',
+    )
+  }
+
   if (opts.check) {
     if (driftLines.length > 0) {
       console.error('basalt-ui sync --check: locally-drifted managed files:')

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

@@ -81,6 +81,25 @@ function silenced<T>(fn: () => T): T {
   }
 }
 
+/** 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))
@@ -192,3 +211,88 @@ describe('--check performs zero writes', () => {
     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/dashboard/stat-card.tsx

@@ -38,6 +38,18 @@
  * @example
  * // The earned zero — a measured value worth asserting, not a card that merely has no reading.
  * <StatCard label="Downtime · last 24h" value="0 min" tone="good" />
+ *
+ * @example
+ * // The honest gate. A zero can be synthesized as well as measured — a downtime figure derived
+ * // from outage rows reads 0 both when probes ran clean AND when no probe cycle was ingested at
+ * // all, because a dead collector opens no outage row either. `tone` is a positive assertion
+ * // about a reading, so the gate belongs on whether a reading exists, not on whether the number
+ * // happens to be defined — those are separate facts. Gate on measured coverage instead:
+ * <StatCard
+ *   label="Downtime · last 24h"
+ *   value={`${downtimeMinutes} min`}
+ *   tone={hasCoverage ? (downtimeMinutes === 0 ? 'good' : 'bad') : undefined}
+ * />
  */
 import { Box, Card, Group, VisuallyHidden } from '@mantine/core'
 import type { ReactNode } from 'react'

package/src/guard/check-source.test.ts

@@ -409,6 +409,16 @@ describe('raw-html-layout', () => {
     const f = find(`<div style={{ display: 'flex' }} /> // theme-allow`)
     expect(kinds(f)).not.toContain('raw-html-layout')
   })
+
+  it('does NOT flag a raw <div> with inline display:flex in a chart file — the Flex/Grid/Group remedy is @mantine/*, banned in the Mantine-free chart layer', () => {
+    const f = find(`<div style={{ display: 'flex', gap: 8 }} />`, CHART_PATH)
+    expect(kinds(f)).not.toContain('raw-html-layout')
+  })
+
+  it('still flags the same literal in a non-chart path (the check is not globally weakened)', () => {
+    const f = find(`<div style={{ display: 'flex', gap: 8 }} />`, PATH)
+    expect(kinds(f)).toContain('raw-html-layout')
+  })
 })
 
 // ── 10. inline-spacing ───────────────────────────────────────────────────────
@@ -527,6 +537,16 @@ describe('inline-display', () => {
     const f = find(`<Box style={{ display: 'flex' }} /> // theme-allow`)
     expect(kinds(f)).not.toContain('inline-display')
   })
+
+  it('does NOT flag display: "flex" in a chart file — the Flex/Grid/Group remedy is @mantine/*, banned in the Mantine-free chart layer', () => {
+    const f = find(`<Box style={{ display: 'flex' }} />`, CHART_PATH)
+    expect(kinds(f)).not.toContain('inline-display')
+  })
+
+  it('still flags the same literal in a non-chart path (the check is not globally weakened)', () => {
+    const f = find(`<Box style={{ display: 'flex' }} />`, PATH)
+    expect(kinds(f)).toContain('inline-display')
+  })
 })
 
 // ── 12. raw-visx-axis ────────────────────────────────────────────────────────

package/src/guard/index.ts

@@ -282,10 +282,13 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
  *
  * `mantine-shade-index` landed in 1.7.0 and is the sole entry — it rejects `c="yellow.7"`, which
- * previously passed, and the one real consumer has several. Its promotion is **deferred to 1.9.0**:
- * 1.8.0 shipped the same day as 1.7.0, so promoting on the next minor number would have given the
- * consumer roughly no runway at all — which is the exact failure the grace minor exists to prevent,
- * and the runway is measured in consumer upgrades, not in version numbers. Promote it by deleting
+ * previously passed, and the one real consumer has several. Its promotion is **deferred to 1.10.0**,
+ * for the second time and for the same reason both times: the runway is measured in consumer
+ * upgrades, not in version numbers. 1.8.0 shipped the same day as 1.7.0, so promoting there would
+ * have given no runway at all. 1.9.0 then carried the chart-layer batch the same consumer asked
+ * for — bundling a build-breaking promotion into the minor they upgrade for the fixes turns a
+ * routine bump into an unplanned refactor, which is precisely what the grace minor exists to
+ * prevent. 1.10.0 is the first minor they can take the promotion on its own. Promote it by deleting
  * the entry (its own commit).
  *
  * @example
@@ -294,7 +297,7 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * }
  */
 const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
-  'mantine-shade-index': 'introduced 1.7.0 — promote to error in 1.9.0',
+  'mantine-shade-index': 'introduced 1.7.0 — promote to error in 1.10.0',
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
@@ -688,8 +691,12 @@ export const GUARD_RULES = {
     kind: 'raw-html-layout',
     pattern: RAW_HTML_TAG, // handled inline (3-condition conjunction); entry keeps registry complete
     enabled: (cfg: GuardConfig) => cfg.rawHtmlLayout,
-    // JSX-tag-shaped (`<div style={{...}}>`) — never appears in CSS text.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    // JSX-tag-shaped (`<div style={{...}}>`) — never appears in CSS text. Also excluded from
+    // chart files: the remedy (Box/Flex/Grid/Stack/Group) is `@mantine/*`, and src/charts/** is a
+    // lint-enforced Mantine-free layer (basalt/token-layer-boundary) — so inside a chart file the
+    // finding is unactionable, not merely inconvenient, and the only "fix" would be a theme-allow
+    // comment written inside the very directory this rule protects.
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message:
       'Raw HTML element with inline layout/surface styling — use a Mantine layout primitive (Box/Flex/Grid/Stack/Group).',
   },
@@ -704,8 +711,12 @@ export const GUARD_RULES = {
     pattern: INLINE_DISPLAY,
     enabled: (cfg: GuardConfig) => cfg.inlineDisplay,
     // JSX-object-shaped (`display: 'flex'`, quoted value) — CSS never quotes a keyword value
-    // (`display: flex;` is bare), so the pattern's quote anchor can never match real CSS.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    // (`display: flex;` is bare), so the pattern's quote anchor can never match real CSS. Also
+    // excluded from chart files: the remedy (Flex/Grid/Group) is `@mantine/*`, and src/charts/**
+    // is a lint-enforced Mantine-free layer (basalt/token-layer-boundary) — so inside a chart file
+    // the finding is unactionable, not merely inconvenient, and the only "fix" would be a
+    // theme-allow comment written inside the very directory this rule protects.
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message: 'Use <Flex>/<Grid>/<Group> instead of an inline display:flex/grid.',
   },
   'raw-visx-axis': {