basalt-ui 1.40.3 → 2.0.0

package/src/cli/doctor.ts

@@ -8,6 +8,8 @@ import { relative, resolve } from 'node:path'
 
 import type { BasaltConfig } from './config'
 import {
+  AGENTS_MD,
+  LEGACY_BLOCK_HOST,
   MANIFEST_PATH,
   basaltBinCommand,
   basaltPresetEntry,
@@ -15,6 +17,7 @@ import {
   declaredProfile,
   findBasaltInstall,
   findRepoRoot,
+  importsAgentsMd,
   inspectLefthookGate,
   OXLINT_FILES,
   OXLINT_NO_BIN,
@@ -24,12 +27,30 @@ import {
   readIfExists,
   readManifest,
   resolveProjectDir,
+  sameFile,
   scannableFiles,
+  scanBlock,
   shippedAssetPath,
 } from './index'
 import { resolveRoots } from './config'
+import {
+  appWiringCheck,
+  droppedSubpathsCheck,
+  retiredLintRulesCheck,
+  tsconfigBaseCheck,
+} from './doctor-upgrade'
+import type { Check } from './doctor-upgrade'
 import { findManifestAbove, parentInstallAdvice } from './sync'
 
+/** `sameFile`, but doctor never crashes: a path that cannot be inspected is "not provably the same". */
+function isSameFile(a: string, b: string): boolean {
+  try {
+    return sameFile(a, b)
+  } catch {
+    return false
+  }
+}
+
 export type DoctorResult = {
   /** Number of hard failures (exit non-zero). */
   hardFailures: number
@@ -45,12 +66,8 @@ export type DoctorResult = {
 }
 
 /**
- * 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.
+ * First run of digits in a semver range (`^7.0.15` → `7`), or null. Duplicated in
+ * `configs/oxlint-plugin.js`, which must stay import-free; keep both copies in sync.
  */
 function majorOf(range: string | undefined): number | null {
   if (typeof range !== 'string') return null
@@ -62,12 +79,7 @@ function majorOf(range: string | undefined): number | null {
 const AI_MAJOR_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies'] as const
 type AiMajorField = (typeof AI_MAJOR_FIELDS)[number]
 
-/**
- * The `ai` package's major per dependency field, all within THIS package.json — not walked across
- * workspace packages (that discovery was deleted with the rest of the multi-repo machinery). A
- * skew here is still real: a package declaring `dependencies.ai: 5` alongside
- * `peerDependencies.ai: 7` asks its own consumers for a different major than it itself runs.
- */
+/** The `ai` major per dependency field of THIS package.json (not walked across workspaces). */
 function aiMajorsAt(dir: string): Partial<Record<AiMajorField, number>> {
   const raw = readIfExists(resolve(dir, 'package.json'))
   if (raw === null) return {}
@@ -84,14 +96,7 @@ function aiMajorsAt(dir: string): Partial<Record<AiMajorField, number>> {
   }
 }
 
-/**
- * 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.
- */
+/** `basalt.aiMajorSkewReason` as a validated reason, plus whether the key was present but invalid. */
 function resolveAiMajorSkewReason(cfg: BasaltConfig): {
   reason: string | null
   presentButInvalid: boolean
@@ -105,37 +110,24 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
 }
 
 /**
- * Check a consumer repo's basalt integration and print a pass/warn report.
- *
- * Narrowed to what a single-directory-scoped run can actually verify — no workspace-glob walking,
- * no ascend/descend project discovery (see {@link resolveProjectDir}). Six checks, numbered in
- * the order they run and print:
+ * Check a consumer repo's basalt integration and print a pass/warn report. One directory, no
+ * workspace walking (see {@link resolveProjectDir}). Checks, in print order:
  *
  * Hard failures (exit non-zero):
- *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
- *   2. `install-parity`: basalt-ui resolves, doctor prints WHERE and at what version, and that
- *      version agrees with the manifest's `basaltVersion`.
- *   3. `guard-scan`: `check-theme` would scan more than zero files, sharing `scannableFiles` so the
- *      two cannot disagree. Both RESTORED in 1.30.0 after four minors gone with no MIGRATING row —
- *      README § `doctor` carries what their absence cost.
- *   4. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
- *      preset AND that path resolves (warns when no `oxlint` bin does). `init` keeps an existing config, so the framework's whole
- *      lint half can be silently off — one repo carried six real violations invisibly across five
- *      minors this way.
- *   6. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
- *      `peerDependencies` agree on the `ai` package's major — the shape `basalt/ai-sdk-major` (per
- *      linted FILE) cannot see. A skew is exempt-able via `basalt.aiMajorSkewReason` (a non-empty
- *      reason, not a bare `true`); a declared reason when the majors agree warns it is stale.
+ *   1. `.basalt/manifest.json` exists.
+ *   2. `install-parity`: basalt-ui resolves, and its version matches the manifest's `basaltVersion`.
+ *   3. `guard-scan`: `check-theme` would scan more than zero files (shares `scannableFiles`).
+ *   4. `oxlint-preset`: `.oxlintrc.json` extends the shipped preset AND that path resolves.
+ *   7. `ai-major-parity`: the `ai` major agrees across this package.json's dependency fields
+ *      (exempt via `basalt.aiMajorSkewReason`; a stale reason warns).
+ *   8-11. `tsconfig-base`, `retired-lint-rules`, `dropped-subpaths`, `app-wiring` (./doctor-upgrade);
+ *      a check that cannot run is SKIPPED and exits non-zero.
  *
  * Warning (non-fatal):
- *   5. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
- *      `lefthook dump --format json` (resolves `extends`/`include`/`root:` the way lefthook itself
- *      does — see {@link inspectLefthookGate}). No lefthook config at all is a pass (a consumer may
- *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook
- *      dump could not read at all (binary missing, or the dump failed) warns and says so, rather
- *      than inventing a verdict.
+ *   5. `lefthook-preset`: a pre-commit command runs `check-theme` (read via `lefthook dump`).
+ *   6. `claude-md`: a project-root `CLAUDE.md` that does not import `@AGENTS.md` suppresses it.
  *
- * Returns the exit code: 0 = all good, 1 = one or more hard failures.
+ * Returns the exit code: 0 = all good, 1 = one or more hard failures or skipped checks.
  */
 export function doctor(invocationCwd: string = process.cwd(), flags: string[] = []): number {
   if (conflictingProfileFlags('doctor', flags)) return 1
@@ -156,6 +148,10 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     lines.push(`  ✖ ${msg}`)
     result.hardFailures++
   }
+  function skip(msg: string): void {
+    lines.push(`  ? SKIPPED ${msg}`)
+    result.skipped++
+  }
 
   if (project.relocatedFrom !== null) {
     lines.push(`  → BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.\n`)
@@ -193,12 +189,13 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
 
   const install = findBasaltInstall(cwd)
 
-  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the CLAUDE-block's claim)
+  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the AGENTS-block's claim)
   const manifestVersion = profile === 'tokens-only' ? undefined : readManifest(cwd).basaltVersion
   const at = install.dir === null ? '' : `${relative(cwd, install.dir)} (${install.version})`
   if (install.dir === null) {
     fail(
-      'install-parity: basalt-ui does not resolve here, above, or in a sibling workspace package.',
+      'install-parity: basalt-ui does not resolve here, above, or in a sibling workspace package. ' +
+        'Fix: `bun add basalt-ui`.',
     )
   } else if (manifestVersion === undefined || install.version === manifestVersion) {
     const matches = manifestVersion === undefined ? '' : " and matches the manifest's basaltVersion"
@@ -219,16 +216,14 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     fail(
       'guard-scan: `check-theme` would scan ZERO files here — either `basalt.roots` points at ' +
         'paths that do not exist, or this is not the package the config lives in (BASALT_CWD, ' +
-        'else the cwd; nothing is inferred).',
+        'else the cwd; nothing is inferred). Fix: set `"basalt": { "roots": ["src"] }` in package.json.',
     )
   } else {
     pass(`guard-scan: check-theme covers ${scanned} file(s) under ${resolveRoots(cfg).join(', ')}`)
   }
 
   // ── Hard check 4: the consumer's oxlint config extends the shipped preset ──
-  // `init` KEEPS an existing `.oxlintrc.json`, so a repo can carry the whole scaffold with the
-  // framework's lint half switched off and nothing anywhere saying so. One repo ran five minors
-  // that way and surfaced six real `basalt/no-raw-font-size` errors the moment it was wired.
+  // `init` KEEPS an existing `.oxlintrc.json`, so the framework's lint half can be silently off.
   if (profile === 'tokens-only') {
     pass('oxlint-preset: n/a — the shipped preset is a Mantine/React preset')
   } else {
@@ -247,7 +242,8 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
       const parsed = parseJsonc(oxlintrcRaw)
       if (parsed === null) {
         fail(
-          '.oxlintrc.json does not parse as JSON/JSONC — cannot tell whether it extends the preset',
+          '.oxlintrc.json does not parse as JSON/JSONC — cannot tell whether it extends the preset. ' +
+            'Fix the syntax error, then re-run `basalt-ui doctor`.',
         )
       } else {
         const entry = basaltPresetEntry(parsed['extends'])
@@ -256,7 +252,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
           fail(
             '.oxlintrc.json does NOT extend the shipped preset — every basalt/* design rule is off ' +
               `and oxlint reports green without them. Add "extends": ["${correct}"], or re-run ` +
-              '`basalt-ui init --merge-lint` to splice it in.',
+              '`basalt-ui init` to splice it in (or add it by hand).',
           )
         } else if (!existsSync(resolve(cwd, entry))) {
           fail(
@@ -274,8 +270,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
   }
 
   // ── Warn check 5: the pre-commit hook actually runs the guard ──────────────
-  // Read via `lefthook dump --format json`, which resolves `extends`/`include`/remote configs/
-  // `root:` the way lefthook itself does — see {@link inspectLefthookGate}.
+  // Read via `lefthook dump --format json` (see {@link inspectLefthookGate}).
   const repoRoot = findRepoRoot(cwd)
   const lefthookGate =
     profile === 'tokens-only' ? { kind: 'n/a' as const } : inspectLefthookGate(repoRoot)
@@ -300,14 +295,38 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     )
   }
 
-  // ── Hard check 6: ai package major version parity within THIS package.json ─
-  // 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. This check reads the SAME package.json across its dependencies/
-  // devDependencies/peerDependencies fields — the shape a lint run cannot see. Hard failure, not a
-  // warning: a skewed pair throws at runtime, it doesn't just look different.
-  // `basalt.aiMajorSkewReason` exempts an INTENTIONAL skew; a stale declaration (skew resolved,
-  // reason still present) warns instead of passing silently.
+  // ── Warn check 6: a project-root CLAUDE.md that shadows AGENTS.md ───────────
+  // The managed block lives in AGENTS.md. Claude Code loads a repo-root AGENTS.md directly, but ANY
+  // CLAUDE.md in or above the cwd suppresses it unless that file imports `@AGENTS.md` — so a
+  // leftover CLAUDE.md means the block (and the rest of AGENTS.md) is not loaded, whether or not it
+  // still carries a block. A symlink to AGENTS.md is one file and is fine. Warn only: what else
+  // CLAUDE.md holds is the consumer's.
+  const legacyHost = resolve(cwd, LEGACY_BLOCK_HOST)
+  const legacy = profile === 'tokens-only' ? null : readIfExists(legacyHost)
+  if (legacy !== null && !isSameFile(legacyHost, resolve(cwd, AGENTS_MD))) {
+    const scan = scanBlock(legacy)
+    const issues: string[] = []
+    if (scan.problem !== null) {
+      issues.push(`has a malformed basalt block (${scan.problem}) — fix it by hand, then \`sync\``)
+    } else if (scan.region !== null) {
+      issues.push(
+        `still carries a stale basalt block — delete it by hand; \`sync\` keeps ${AGENTS_MD} current`,
+      )
+    }
+    if (!importsAgentsMd(legacy)) {
+      issues.push(
+        `does not import \`@${AGENTS_MD}\`, so Claude Code loads it INSTEAD of ${AGENTS_MD} and the ` +
+          `basalt block never reaches the agent — move its content into ${AGENTS_MD} and delete it, ` +
+          `or add \`@${AGENTS_MD}\``,
+      )
+    }
+    if (issues.length > 0) warn(`${LEGACY_BLOCK_HOST} ${issues.join('; and ')}.`)
+  }
+
+  // ── Hard check 7: ai package major version parity within THIS package.json ─
+  // basalt/ai-sdk-major is per-file against the NEAREST package.json; this reads one package.json
+  // across its dependency fields. Hard failure: a skewed pair throws at runtime. An intentional skew
+  // is exempt via `basalt.aiMajorSkewReason`; a stale reason warns.
   const aiMajors = aiMajorsAt(cwd)
   const aiEntries = AI_MAJOR_FIELDS.filter((field) => aiMajors[field] !== undefined).map(
     (field) => ({ field, major: aiMajors[field] as number }),
@@ -327,10 +346,13 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
         fail(
           `ai package major version mismatch within this package.json: ${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.',
+            'not accepted). Fix: set it to a non-empty reason string, or align the majors.',
         )
       } else {
-        fail(`ai package major version mismatch within this package.json: ${summary}`)
+        fail(
+          `ai package major version mismatch within this package.json: ${summary}. Fix: align ` +
+            'every field of this package.json on one `ai` major.',
+        )
       }
     } else {
       const [major] = distinctMajors
@@ -348,19 +370,49 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     pass('ai-major-parity: this package.json declares no ai dependency — nothing to compare')
   }
 
+  // ── Hard checks 8-11: strictness and the 1.x → 2.0 upgrade path (./doctor-upgrade) ──────────
+  if (profile === 'tokens-only') {
+    pass(
+      'tsconfig-base / retired-lint-rules / dropped-subpaths / app-wiring: n/a — a tokens-only consumer',
+    )
+  } else {
+    const upgrade: [string, Check][] = [
+      ['tsconfig-base: tsconfig.json extends the shipped preset', tsconfigBaseCheck(cwd)],
+      [
+        'retired-lint-rules: .oxlintrc.json sets no retired basalt/* rule',
+        retiredLintRulesCheck(cwd, install),
+      ],
+      [
+        'dropped-subpaths: no import of a basalt-ui subpath the install lacks',
+        droppedSubpathsCheck(cwd, cfg, install),
+      ],
+      [
+        'app-wiring: the entry mounts BasaltProvider and the router tree is generated',
+        appWiringCheck(cwd),
+      ],
+    ]
+    for (const [ok, check] of upgrade) {
+      if (check === null) pass(ok)
+      else if ('fail' in check) fail(check.fail)
+      else skip(check.skip)
+    }
+  }
+
   // ── Report ──────────────────────────────────────────────────────────────────
   lines.push('')
-  if (result.hardFailures === 0 && result.warnings === 0) {
+  if (result.hardFailures === 0 && result.warnings === 0 && result.skipped === 0) {
     lines.push('All checks passed.')
   } else {
     const parts: string[] = []
     if (result.hardFailures > 0) parts.push(`${result.hardFailures} hard failure(s)`)
+    if (result.skipped > 0)
+      parts.push(`${result.skipped} SKIPPED (a check that cannot run is not a pass)`)
     parts.push(`${result.warnings} warning(s)`)
     lines.push(`${parts.join(', ')}.`)
   }
   lines.push('')
 
-  if (result.hardFailures > 0) {
+  if (result.hardFailures > 0 || result.skipped > 0) {
     console.error(lines.join('\n'))
     return 1
   }

package/src/cli/help.ts

@@ -14,9 +14,7 @@ import { parseArgs } from 'node:util'
 
 export const COMMAND_OPTIONS: Record<string, Record<string, { type: 'string' | 'boolean' }>> = {
   init: {
-    'with-router': { type: 'boolean' },
-    'with-query': { type: 'boolean' },
-    'merge-lint': { type: 'boolean' },
+    'no-merge-lint': { type: 'boolean' },
   },
   sync: {
     force: { type: 'boolean' },
@@ -65,7 +63,7 @@ export function unknownFlag(cmd: string, flags: readonly string[]): string | nul
 
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 export const USAGE =
-  'Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n' +
+  'Usage: basalt-ui <--version | init [--no-merge-lint] |\n' +
   '                  sync [--force] [--check] [--verbose] [--tokens-only|--framework] |\n' +
   '                  check-theme [--audit-allows] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +