basalt-ui 1.8.0 → 1.10.0

package/src/cli/index.ts

@@ -165,6 +165,25 @@ export type BasaltConfig = {
    * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
    */
   exemptRules?: Partial<Record<GuardKind, string[]>>
+  /**
+   * 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
 }
 
 const DEFAULT_ROOT = 'src'
@@ -675,8 +694,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 +920,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 +1163,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 +1205,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 +1277,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 +1328,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:')
@@ -1411,6 +1579,202 @@ type DoctorResult = {
   warnings: number
 }
 
+type WorkspacePackage = { readonly name: string; readonly dir: string }
+
+/** {@link collectWorkspacePackages}'s return: the walked packages plus whether a `workspaces`
+ * field was present at all (distinguishes "nothing to compare" from "not a workspace root"). */
+type WorkspaceWalk = {
+  readonly packages: readonly WorkspacePackage[]
+  readonly hasWorkspacesField: boolean
+}
+
+/**
+ * Every subdirectory of `base` (name only), or `[]` if `base` doesn't exist / isn't a directory.
+ * `node_modules` is always excluded — a wildcard workspaces pattern must never descend into a
+ * dependency tree. `skipDotDirs` additionally excludes dot-directories; it is only set by the
+ * `*`/`**` wildcard descent in {@link expandPatternSegments}, never for an explicitly named
+ * literal segment, so a pattern like `.internal/*` still resolves.
+ */
+function subdirNames(base: string, options: { skipDotDirs?: boolean } = {}): string[] {
+  let entries: string[]
+  try {
+    entries = readdirSync(base)
+  } catch {
+    return []
+  }
+  return entries.filter((name) => {
+    if (name === 'node_modules') return false
+    if (options.skipDotDirs && name.startsWith('.')) return false
+    try {
+      return statSync(resolve(base, name)).isDirectory()
+    } catch {
+      return false
+    }
+  })
+}
+
+/**
+ * Expands one glob PATTERN's segments against the filesystem, starting from `baseDir`. Supports
+ * three segment kinds: a literal name, a single `*` wildcard (any one directory), and a `**`
+ * wildcard (zero or more directory levels, i.e. arbitrary depth) — covering a trailing single
+ * wildcard, an interior wildcard between literal segments, and a trailing double-wildcard alike,
+ * not just one trailing single-wildcard segment.
+ */
+function expandPatternSegments(baseDir: string, segments: readonly string[]): string[] {
+  if (segments.length === 0) return [baseDir]
+  const [head, ...rest] = segments
+
+  if (head === '**') {
+    // Zero levels: `**` consumes nothing and the rest of the pattern matches right here.
+    const matches = expandPatternSegments(baseDir, rest)
+    // One-or-more levels: descend into every subdirectory, `**` still active.
+    for (const name of subdirNames(baseDir, { skipDotDirs: true })) {
+      matches.push(...expandPatternSegments(resolve(baseDir, name), segments))
+    }
+    return matches
+  }
+
+  const names =
+    head === '*'
+      ? subdirNames(baseDir, { skipDotDirs: true })
+      : subdirNames(baseDir).filter((n) => n === head)
+  return names.flatMap((name) => expandPatternSegments(resolve(baseDir, name), rest))
+}
+
+/**
+ * Expands a root `package.json`'s `workspaces` patterns into concrete package directories.
+ * Supports literal segments, a single-wildcard segment, and a double-wildcard segment, both
+ * interior and trailing (e.g. `packages` followed by a double wildcard, or an interior single
+ * wildcard between two literal segments) — not just one trailing single-wildcard segment. A
+ * candidate directory that has no `package.json` of its own is skipped, not reported — an empty
+ * scaffold directory is not a workspace package. Also honours npm/bun/yarn `!`-prefixed exclusion
+ * entries (e.g. `["packages/*", "!packages/legacy"]`) — both the included and excluded patterns
+ * are expanded through the same machinery, then the excluded set is subtracted.
+ */
+function expandWorkspaceGlobs(cwd: string, patterns: readonly string[]): string[] {
+  const expand = (pattern: string): string[] =>
+    expandPatternSegments(
+      cwd,
+      pattern.split('/').filter((s) => s.length > 0),
+    )
+
+  const excluded = new Set(
+    patterns
+      .filter((pattern) => pattern.startsWith('!'))
+      .flatMap((pattern) => expand(pattern.replace(/^!+/, ''))),
+  )
+
+  const dirs: string[] = []
+  for (const pattern of patterns) {
+    if (pattern.startsWith('!')) continue
+    for (const abs of expand(pattern)) {
+      if (excluded.has(abs)) continue
+      if (existsSync(resolve(abs, 'package.json'))) dirs.push(abs)
+    }
+  }
+  return dirs
+}
+
+/**
+ * Every workspace package declared by `cwd`'s root `package.json` (npm/bun/yarn `workspaces`
+ * field, array or `{ packages: [...] }` object form), named + directory-resolved — PLUS the root
+ * manifest itself, labelled `"{name} (root)"`. The root is walked because it commonly carries a
+ * hoisted `ai` dev dependency that can itself skew against a workspace package's own major — that
+ * is the producer/consumer shape the whole check exists to catch, and it is invisible if only the
+ * expanded workspace dirs are inspected. `hasWorkspacesField` is `false` (and `packages` empty)
+ * when `cwd` has no `package.json`, no `workspaces` field, or the field is a shape this doesn't
+ * recognize — a repo-wide walk is a bonus check, not something that should ever throw doctor over
+ * an unrecognized `workspaces` shape.
+ */
+function collectWorkspacePackages(cwd: string): WorkspaceWalk {
+  const raw = readIfExists(resolve(cwd, 'package.json'))
+  if (raw === null) return { packages: [], hasWorkspacesField: false }
+
+  let parsed: { workspaces?: unknown; name?: string }
+  try {
+    parsed = JSON.parse(raw) as { workspaces?: unknown; name?: string }
+  } catch {
+    return { packages: [], hasWorkspacesField: false }
+  }
+
+  const patterns = isStringArray(parsed.workspaces)
+    ? parsed.workspaces
+    : parsed.workspaces !== null &&
+        typeof parsed.workspaces === 'object' &&
+        isStringArray((parsed.workspaces as { packages?: unknown }).packages)
+      ? (parsed.workspaces as { packages: string[] }).packages
+      : null
+  if (patterns === null) return { packages: [], hasWorkspacesField: false }
+
+  const rootName = parsed.name && parsed.name.length > 0 ? `${parsed.name} (root)` : '(root)'
+  const workspacePackages = expandWorkspaceGlobs(cwd, patterns).map((dir) => ({
+    name: readPackageName(dir),
+    dir,
+  }))
+
+  return {
+    packages: [{ name: rootName, dir: cwd }, ...workspacePackages],
+    hasWorkspacesField: true,
+  }
+}
+
+/** Narrows to a string array — shared by `collectWorkspacePackages`'s two `workspaces` shapes. */
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+}
+
+/**
+ * First run of digits in a semver range string (`^7.0.15` → `7`), or null if there is none.
+ *
+ * Duplicated verbatim in `configs/oxlint-plugin.js` — that file must stay import-free from this
+ * package (it loads via `jsPlugins` out of a consumer's node_modules, before this package's own
+ * code is necessarily resolvable), so the duplication is structural, not an oversight. Keep both
+ * copies in sync by hand; a future parsing fix (pre-release suffixes, say) must land in both.
+ */
+function majorOf(range: string | undefined): number | null {
+  if (typeof range !== 'string') return null
+  const match = range.match(/\d+/)
+  return match === null ? null : Number(match[0])
+}
+
+/** The `ai` package's declared major at `dir`'s own `package.json`, or null if undeclared/unreadable. */
+function aiMajorAt(dir: string): number | null {
+  const raw = readIfExists(resolve(dir, 'package.json'))
+  if (raw === null) return null
+  try {
+    const pkg = JSON.parse(raw) as {
+      dependencies?: Record<string, string>
+      devDependencies?: Record<string, string>
+      peerDependencies?: Record<string, string>
+    }
+    return majorOf(
+      pkg.dependencies?.['ai'] ?? pkg.devDependencies?.['ai'] ?? pkg.peerDependencies?.['ai'],
+    )
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Splits `basalt.aiMajorSkewReason` into a validated reason (or null) plus whether the key was
+ * present at all but failed validation. A present-but-invalid value (anything other than a
+ * non-empty string — including a bare `true`) is treated as absent for the pass/fail decision, same
+ * as a missing key, but doctor's failure message still calls out that the key exists and is
+ * malformed rather than silently falling back to the plain "no exemption" message — a forgotten key
+ * and a broken one are different mistakes and deserve different guidance.
+ */
+function resolveAiMajorSkewReason(cfg: BasaltConfig): {
+  reason: string | null
+  presentButInvalid: boolean
+} {
+  const raw = cfg.aiMajorSkewReason
+  if (raw === undefined) return { reason: null, presentButInvalid: false }
+  if (typeof raw === 'string' && raw.trim().length > 0) {
+    return { reason: raw, presentButInvalid: false }
+  }
+  return { reason: null, presentButInvalid: true }
+}
+
 /**
  * Check a consumer repo's basalt integration and print a pass/warn report.
  *
@@ -1421,6 +1785,17 @@ type DoctorResult = {
  *
  * Hard failures (exit non-zero):
  *   1. .basalt/manifest.json exists (init was run).
+ *   6. `ai-major-parity`: every workspace package that declares the `ai` package agrees on its
+ *      major version. `basalt/ai-sdk-major` (the oxlint plugin rule) cannot catch this — it checks
+ *      a linted file's NEAREST package.json, so a lint run scoped to one workspace package only
+ *      ever sees that package's own `ai` major and is perfectly happy; the cross-package skew (one
+ *      package streaming on `ai@5`, another parsing it on `ai@7`) only a repo-wide manifest walk
+ *      can see. Skipped entirely when `cwd` has no `workspaces` field or none of its packages
+ *      declare `ai`. A detected skew is exempt-able via `basalt.aiMajorSkewReason` (a non-empty
+ *      reason string, not a bare `true`) in the consumer's package.json — an intentional
+ *      producer/consumer split neutralized by a transform is a locked decision, not a defect, and
+ *      the written reason IS the pin that a permanently-failing guard would otherwise lack. Missing
+ *      or invalid (empty/non-string) still hard-fails exactly as if the key were absent.
  *
  * Warnings (non-fatal):
  *   2. The installed node_modules/basalt-ui version matches the manifest's basaltVersion
@@ -1432,10 +1807,14 @@ type DoctorResult = {
  *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
  *   5. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
  *      a public/ dir exists at all — skipped otherwise).
+ *   7. A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the exemption is
+ *      stale and can be deleted; an exemption nobody revisits is how a real, later skew slips
+ *      through unnoticed.
  *
  * Returns the exit code: 0 = all good, 1 = one or more hard failures.
  */
 export function doctor(cwd: string = process.cwd()): number {
+  const cfg = readBasaltConfig(cwd)
   const result: DoctorResult = { hardFailures: 0, warnings: 0 }
   const lines: string[] = [`\nbasalt-ui doctor — ${cwd}\n`]
 
@@ -1579,6 +1958,61 @@ export function doctor(cwd: string = process.cwd()): number {
     }
   }
 
+  // ── Hard check 6: ai package major version parity across workspace packages ─
+  // basalt/ai-sdk-major (the lint rule) is per-file against the NEAREST package.json, so a lint
+  // run scoped to one workspace package only ever sees that package's own `ai` major and is
+  // perfectly happy. The real defect is CROSS-package (argo defect 1: apps/api on ai@5 producing a
+  // stream apps/dashboard's ai@7 client can't parse) and only a repo-wide manifest walk sees it —
+  // this is that walk. Hard failure, not a warning: a skewed pair throws at runtime, it doesn't
+  // just look different. `basalt.aiMajorSkewReason` exempts an INTENTIONAL skew (e.g. a
+  // producer-side TransformStream neutralizing the divergent enum value) — see the BasaltConfig
+  // JSDoc for its exact semantics; a stale declaration (skew resolved, reason still present) warns
+  // instead of passing silently.
+  const workspaceWalk = collectWorkspacePackages(cwd)
+  const aiMajors = workspaceWalk.packages
+    .map((pkg) => ({ name: pkg.name, major: aiMajorAt(pkg.dir) }))
+    .filter((entry): entry is { name: string; major: number } => entry.major !== null)
+  const { reason: aiMajorSkewReason, presentButInvalid: aiMajorSkewReasonInvalid } =
+    resolveAiMajorSkewReason(cfg)
+  if (aiMajors.length > 0) {
+    const distinctMajors = new Set(aiMajors.map((entry) => entry.major))
+    if (distinctMajors.size > 1) {
+      const summary = aiMajors.map((entry) => `${entry.name}@ai${entry.major}`).join(', ')
+      if (aiMajorSkewReason !== null) {
+        pass(
+          `ai package major version mismatch across workspace packages: ${summary} — exempted via ` +
+            `basalt.aiMajorSkewReason: "${aiMajorSkewReason}"`,
+        )
+      } else if (aiMajorSkewReasonInvalid) {
+        fail(
+          `ai package major version mismatch across workspace packages: ${summary} — ` +
+            'basalt.aiMajorSkewReason is present but is not a non-empty string (a bare `true` is ' +
+            'not accepted); the exemption must carry a written reason, e.g. ' +
+            '`aiMajorSkewReason: "apps/api on ai@5, apps/dashboard on ai@7, neutralized by a ' +
+            'producer-side TransformStream"`.',
+        )
+      } else {
+        fail(`ai package major version mismatch across workspace packages: ${summary}`)
+      }
+    } else {
+      const [major] = distinctMajors
+      if (aiMajorSkewReason !== null) {
+        warn(
+          `basalt.aiMajorSkewReason ("${aiMajorSkewReason}") is declared but the ai package major ` +
+            `already matches across all ${aiMajors.length} workspace package(s) declaring it ` +
+            `(ai@${major}) — the exemption is no longer needed and can be deleted.`,
+        )
+      } else {
+        pass(
+          `ai package major matches across ${aiMajors.length} workspace package(s) declaring it (ai@${major})`,
+        )
+      }
+    }
+  } else if (workspaceWalk.hasWorkspacesField) {
+    // A hard check that can silently not run is worse than one that is absent — say so.
+    pass('ai-major-parity: no workspace package declares the ai dependency — nothing to compare')
+  }
+
   // ── Report ──────────────────────────────────────────────────────────────────
   lines.push('')
   if (result.hardFailures === 0 && result.warnings === 0) {

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.test.tsx

@@ -13,9 +13,11 @@
  *     leaving the prop off, so the absence case asserts no rail and no verdict text at all — which a
  *     future `tone = tone ?? 'good'` style default would immediately fail.
  *
- * No jsdom is configured in this repo (see `theme/use-basalt-spacing.test.tsx`'s doc) —
- * `renderToStaticMarkup` inside a real `MantineProvider` is enough here, since the rail is an inline
- * style on server-rendered markup.
+ * A DOM harness now exists (`tests/setup/dom.ts`, preloaded via the root `bunfig.toml`; see
+ * `theme/use-basalt-spacing.test.tsx`'s doc) — `renderToStaticMarkup` inside a real `MantineProvider`
+ * is used deliberately here instead, since the rail is an inline style on server-rendered markup.
+ * Converting to the DOM harness would only be worth it if a future assertion here needed live DOM
+ * behavior (e.g. computed styles, focus/hover interaction) rather than the static markup string.
  */
 import { MantineProvider } from '@mantine/core'
 import { describe, expect, test } from 'bun:test'

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'