basalt-ui 1.41.0 → 2.0.1

package/dist/cli/doctor-upgrade.js

@@ -0,0 +1,314 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, relative, resolve } from "node:path";
+import { BASALT_CONFIG_KEYS, RETIRED_CONFIG_KEYS } from "./config.js";
+import { parseJsonc, readIfExists, scannableFiles } from "./index.js";
+const guarded = (id, run) => {
+  try {
+    return run();
+  } catch (error) {
+    return { skip: `${id}: cannot run (${error.message}).` };
+  }
+};
+const TSCONFIG_PRESET = /(?:^|\/)basalt-ui\/configs\/tsconfig\.(?:base|react-app)\.json$/;
+const TSCONFIG_PRESET_ID = "basalt-ui/configs/tsconfig.react-app.json";
+const TSCONFIG_FIX = `"extends": "${TSCONFIG_PRESET_ID}" (tsconfig.base.json for a package without a DOM)`;
+const MAX_EXTENDS_DEPTH = 8;
+const tsconfigFile = (p) => p.endsWith(".json") ? p : resolve(p, "tsconfig.json");
+function resolveBare(spec, dir) {
+  const from = createRequire(resolve(dir, "x.js"));
+  for (const candidate of [spec, `${spec}.json`, `${spec}/tsconfig.json`]) {
+    try {
+      return from.resolve(candidate);
+    } catch {
+    }
+  }
+  return null;
+}
+function extendsPreset(file, unknown, seen = []) {
+  if (seen.includes(file)) return false;
+  const text = readIfExists(file);
+  const parsed = text === null ? null : parseJsonc(text);
+  if (parsed === null) {
+    unknown.push(`could not ${text === null ? "read" : "parse"} ${file}`);
+    return false;
+  }
+  const extended = [parsed["extends"]].flat().filter((e) => typeof e === "string");
+  if (extended.some((e) => TSCONFIG_PRESET.test(e))) return true;
+  if (seen.length >= MAX_EXTENDS_DEPTH) return false;
+  const refs = Array.isArray(parsed["references"]) ? parsed["references"] : [];
+  const next = [
+    ...extended.flatMap((e) => {
+      if (e.startsWith(".")) return [resolve(dirname(file), e.endsWith(".json") ? e : `${e}.json`)];
+      const found = resolveBare(e, dirname(file));
+      if (found === null) unknown.push(`cannot resolve extends ${e}`);
+      return found === null ? [] : [found];
+    }),
+    ...refs.flatMap((r) => {
+      const path = r?.path;
+      return typeof path === "string" ? [tsconfigFile(resolve(dirname(file), path))] : [];
+    })
+  ];
+  return next.some((f) => extendsPreset(f, unknown, [...seen, file]));
+}
+function tsconfigBaseCheck(cwd) {
+  return guarded("tsconfig-base", () => {
+    const file = resolve(cwd, "tsconfig.json");
+    if (readIfExists(file) === null) {
+      return { fail: `tsconfig-base: tsconfig.json missing. Fix: create it with ${TSCONFIG_FIX}.` };
+    }
+    const unknown = [];
+    if (extendsPreset(file, unknown)) return null;
+    if (unknown.length > 0) {
+      const why = [...new Set(unknown)].join("; ");
+      return {
+        skip: `tsconfig-base: ${why}, so whether tsconfig.json reaches the preset is unknown.`
+      };
+    }
+    return {
+      fail: `tsconfig-base: tsconfig.json (and the configs it references) does not extend the shipped preset \u2014 the 2.0 types assume strict, exactOptionalPropertyTypes and noUncheckedIndexedAccess. Fix: set ${TSCONFIG_FIX}.`
+    };
+  });
+}
+const CHARTS_FIX = "charts moved to basalt-ui/charts; basalt/chart-engine-boundary replaces it. Delete the entry";
+const RETIRED_FIX = {
+  // The four 2.0 removals go live when #163 adds them to the plugin's RETIRED_RULE_IDS.
+  "provider-above-router": "BasaltProvider mounts the router; delete the entry",
+  "page-bar-budget": "the PageBarActions/SectionActions tuple types enforce it; delete the entry",
+  "agent-resume-guard": "useChat/Chat are banned outright; delete the entry",
+  "deprecated-export": "2.0 ships no deprecations; delete the entry",
+  ...Object.fromEntries(
+    [
+      "unframed-chart",
+      "visx-boundary",
+      "visx-tooltip",
+      "hand-rolled-plot",
+      "chart-legend-literal",
+      "raw-visx-axis",
+      "chart-missing-aria-label"
+    ].map((id) => [id, CHARTS_FIX])
+  )
+};
+function basaltRuleIds(file, seen = /* @__PURE__ */ new Set()) {
+  const text = seen.has(file) ? null : readIfExists(file);
+  const parsed = text === null ? null : parseJsonc(text);
+  if (parsed === null) return [];
+  seen.add(file);
+  const overrides = Array.isArray(parsed["overrides"]) ? parsed["overrides"] : [];
+  const rules = [parsed["rules"], ...overrides.map((o) => o?.rules)];
+  const ids = rules.flatMap(
+    (b) => typeof b === "object" && b !== null ? Object.keys(b).filter((k) => k.startsWith("basalt/")) : []
+  );
+  const local = [parsed["extends"]].flat().filter((e) => typeof e === "string" && e.startsWith(".")).map((e) => resolve(dirname(file), e)).filter((abs) => !abs.includes("node_modules"));
+  return [...ids.map((k) => k.slice(7)), ...local.flatMap((abs) => basaltRuleIds(abs, seen))];
+}
+function retiredLintRulesCheck(cwd, install) {
+  const id = "retired-lint-rules";
+  const dir = install.dir;
+  if (dir === null)
+    return { skip: `${id}: basalt-ui does not resolve, so its plugin cannot be read.` };
+  return guarded(id, () => {
+    const ids = [...new Set(basaltRuleIds(resolve(cwd, ".oxlintrc.json")))];
+    if (ids.length === 0) return null;
+    const pluginPath = resolve(dir, "configs/oxlint-plugin.js");
+    const plugin = createRequire(pluginPath)(pluginPath);
+    const retired = new Set(plugin.RETIRED_RULE_IDS);
+    const registered = new Set(Object.keys(plugin.default?.rules ?? {}));
+    if (registered.size === 0) {
+      return { skip: `${id}: ${pluginPath} registers no rules, so none can be compared.` };
+    }
+    const gone = ids.filter((rule) => retired.has(rule) || !registered.has(rule));
+    if (gone.length === 0) return null;
+    const named = gone.map((r) => `basalt/${r} (${RETIRED_FIX[r] ?? "retired; delete the entry"})`);
+    return {
+      fail: `${id}: .oxlintrc.json sets rules the installed plugin does not register: ${named.join("; ")}. Fix: delete each entry (MIGRATING.md \xA7 2.0).`
+    };
+  });
+}
+const TOKEN = /("(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`)|\/\/[^\n]*|\/\*[\s\S]*?\*\//g;
+const SUBPATH_IMPORT = /(?:(?:^|;)[ \t]*(?:(?:import|export)\b[^'"`;]*?\bfrom|import)\s*|(?<![.\w$])(?:import|require)\s*\(\s*)(['"])basalt-ui\/([^'"]+)\1/gm;
+function tokenize(src) {
+  const literals = [];
+  const code = src.replace(TOKEN, (m, literal, at) => {
+    if (literal === void 0) return m.replace(/[^\n]/g, " ");
+    if (!literal.startsWith("`")) {
+      literals.push([at, at + m.length]);
+      return m;
+    }
+    return m.replace(
+      /(\$\{[^}]*\})|[^\n`]/g,
+      (c, interpolation) => interpolation ?? " "
+    );
+  });
+  return { code, inLiteral: (at) => literals.some(([from, to]) => at >= from && at < to) };
+}
+function basaltImports(src) {
+  const { code, inLiteral } = tokenize(src);
+  return [...code.matchAll(SUBPATH_IMPORT)].filter((m) => !inLiteral(m.index)).map((m) => [m[2], code.slice(0, m.index + m[0].length).split("\n").length]);
+}
+function droppedSubpathsCheck(cwd, cfg, install) {
+  const id = "dropped-subpaths";
+  const dir = install.dir;
+  if (dir === null)
+    return { skip: `${id}: basalt-ui does not resolve, so its exports cannot be read.` };
+  return guarded(id, () => {
+    const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8"));
+    if (pkg.exports === void 0) return null;
+    const keys = Object.keys(pkg.exports);
+    const has = (sub) => keys.some(
+      (k) => k === `./${sub}` || k.endsWith("*") && `./${sub}`.startsWith(k.slice(0, -1))
+    );
+    const hits = [];
+    for (const rel of scannableFiles(cwd, cfg).filter(
+      (f) => /\.(?:[cm]?[jt]sx?|vue|astro)$/.test(f)
+    )) {
+      for (const [sub, line] of basaltImports(readIfExists(resolve(cwd, rel)) ?? "")) {
+        if (!has(sub)) hits.push(`${rel}:${line} imports basalt-ui/${sub}`);
+      }
+    }
+    if (hits.length === 0) return null;
+    const more = hits.length > 10 ? ` (+${hits.length - 10} more)` : "";
+    return {
+      fail: `${id}: ${hits.slice(0, 10).join("; ")}${more}. Fix: see MIGRATING.md \xA7 2.0 for each subpath's replacement.`
+    };
+  });
+}
+const includesSrc = (config) => [config?.["include"], config?.["files"]].some(
+  (list) => Array.isArray(list) && list.some((e) => typeof e === "string" && /^(?:\.\/)?src(?:\/|$)/.test(e))
+);
+function seedTsconfigExtends(cwd) {
+  const root = resolve(cwd, "tsconfig.json");
+  const rootText = readIfExists(root);
+  if (rootText === null || tsconfigBaseCheck(cwd) === null) return null;
+  const refs = parseJsonc(rootText)?.["references"];
+  const covering = (Array.isArray(refs) ? refs : []).map((r) => r?.path).flatMap((path) => typeof path === "string" ? [tsconfigFile(resolve(cwd, path))] : []).find((f) => includesSrc(parseJsonc(readIfExists(f) ?? "null")));
+  const files = parseJsonc(rootText)?.["files"];
+  if (covering === void 0 && Array.isArray(refs) && refs.length > 0 && Array.isArray(files) && files.length === 0) {
+    return `tsconfig.json is a solution-style config and no referenced config includes src \u2014 set ${TSCONFIG_FIX} in the one that covers src.`;
+  }
+  const target = covering ?? root;
+  const text = readIfExists(target) ?? "";
+  const name = relative(cwd, target);
+  const parsed = parseJsonc(text);
+  if (parsed === null) return `${name} does not parse \u2014 set ${TSCONFIG_FIX} by hand.`;
+  if (parsed["extends"] !== void 0) {
+    return `${name} already extends something else \u2014 make it also extend ${TSCONFIG_FIX}.`;
+  }
+  const open = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*\{/.exec(text);
+  if (open === null) return `${name} is not a JSON object \u2014 set ${TSCONFIG_FIX} by hand.`;
+  const comma = Object.keys(parsed).length > 0 ? "," : "";
+  const at = open[0].length;
+  const key = `
+  "extends": "${TSCONFIG_PRESET_ID}"${comma}`;
+  writeFileSync(target, `${text.slice(0, at)}${key}${text.slice(at)}`);
+  return `added "extends": "${TSCONFIG_PRESET_ID}" to ${name}.`;
+}
+const VITE_CONFIGS = ["ts", "mts", "cts", "js", "mjs", "cjs"].map((e) => `vite.config.${e}`);
+const SEED_HINT = "node_modules/basalt-ui/agent/templates/main.tpl";
+const ROUTER_PLUGIN_FIX = "Fix: `bun add -D @tanstack/router-plugin`, add `tanstackRouter({ target: 'react', autoCodeSplitting: true })` from '@tanstack/router-plugin/vite' to `plugins` in vite.config.ts (before react()), then run vite once to generate src/routeTree.gen.ts.";
+function htmlEntry(html) {
+  for (const [, attrs = ""] of html.replace(/<!--[\s\S]*?-->/g, "").matchAll(/<script\b([^>]*)>/gi)) {
+    const src = /\bsrc\s*=\s*["']?([^"'\s>]+)/i.exec(attrs)?.[1];
+    if (/\btype\s*=\s*["']?module\b/i.test(attrs) && src !== void 0 && !/^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(src)) {
+      return src;
+    }
+  }
+  return void 0;
+}
+function registersRouterPlugin(src) {
+  const { code, inLiteral } = tokenize(src);
+  const pluginsAt = [...code.matchAll(/\bplugins\b/g)].find((m) => !inLiteral(m.index))?.index;
+  if (pluginsAt === void 0) return false;
+  const imports = code.matchAll(
+    /(?:^|;)[ \t]*import\s+(?:type\s+)?([^'"`;]*?)\s*from\s*(['"])@tanstack\/router-plugin(?:\/[^'"]*)?\2/gm
+  );
+  return [...imports].some((m) => {
+    if (inLiteral(m.index)) return false;
+    const names = (m[1] ?? "").replace(/[{}]/g, "").split(",").map((part) => part.trim()).filter((part) => part !== "" && !/^type\s/.test(part)).map((part) => part.split(/\s+as\s+/).pop());
+    return names.some(
+      (name) => [
+        ...code.matchAll(
+          new RegExp(`(?<![.\\w$])${name.replace(/\$/g, "\\$")}(?:\\.\\w+)?\\s*\\(`, "g")
+        )
+      ].some((call) => call.index > pluginsAt && !inLiteral(call.index))
+    );
+  });
+}
+function appWiringCheck(cwd) {
+  return guarded("app-wiring", () => {
+    const entry = (htmlEntry(readIfExists(resolve(cwd, "index.html")) ?? "") ?? "src/main.tsx").replace(/^\//, "");
+    const text = readIfExists(resolve(cwd, entry));
+    if (text === null) {
+      return { fail: `app-wiring: ${entry} does not exist. Fix: make it match ${SEED_HINT}.` };
+    }
+    const { code, inLiteral } = tokenize(text);
+    const used = (name) => [...code.matchAll(new RegExp(`\\b${name}\\b`, "g"))].some((m) => !inLiteral(m.index));
+    const missing = ["BasaltProvider", "createBasaltRouter"].filter((name) => !used(name));
+    if (missing.length > 0) {
+      return {
+        fail: `app-wiring: ${entry} does not use ${missing.join(" or ")}. Fix: make it match ${SEED_HINT} (\`init\` seeds it only when the file is absent).`
+      };
+    }
+    const vite = VITE_CONFIGS.map((f) => readIfExists(resolve(cwd, f))).find((t) => t !== null) ?? "";
+    const dirs = [.../* @__PURE__ */ new Set([dirname(entry), "src"])];
+    const generated = dirs.some(
+      (d) => ["ts", "tsx", "js"].some((e) => existsSync(resolve(cwd, d, `routeTree.gen.${e}`)))
+    );
+    if (generated || registersRouterPlugin(vite)) return null;
+    return {
+      fail: `app-wiring: no vite.config calls the TanStack router plugin and ${dirs.join(" or ")}/routeTree.gen.ts does not exist. ${ROUTER_PLUGIN_FIX}`
+    };
+  });
+}
+function unknownConfigKeysCheck(cwd) {
+  return guarded("config-keys", () => {
+    const raw = readIfExists(resolve(cwd, "package.json"));
+    const block = raw === null ? null : JSON.parse(raw).basalt;
+    if (typeof block !== "object" || block === null || Array.isArray(block)) return null;
+    const known = new Set(BASALT_CONFIG_KEYS);
+    const unknown = Object.keys(block).filter((k) => !known.has(k));
+    if (unknown.length === 0) return null;
+    const named = unknown.map(
+      (k) => `basalt.${k} (${RETIRED_CONFIG_KEYS[k] ?? "not a basalt key"})`
+    );
+    return {
+      fail: `config-keys: package.json sets keys basalt-ui does not read: ${named.join("; ")}. Fix: delete each key.`
+    };
+  });
+}
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+function installedVersion(cwd, pkg) {
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    const raw = readIfExists(resolve(dir, "node_modules", pkg, "package.json"));
+    if (raw !== null) return JSON.parse(raw).version ?? null;
+    if (dirname(dir) === dir) return null;
+  }
+}
+function exactPeersCheck(cwd, install) {
+  const id = "exact-peers";
+  if (install.dir === null)
+    return { skip: `${id}: basalt-ui does not resolve, so its peers cannot be read.` };
+  const dir = install.dir;
+  return guarded(id, () => {
+    const raw = readIfExists(resolve(dir, "package.json"));
+    const peers = (raw === null ? {} : JSON.parse(raw).peerDependencies) ?? {};
+    const off = Object.entries(peers).filter(([, range]) => EXACT_VERSION.test(range)).flatMap(([pkg, pin]) => {
+      const have = installedVersion(cwd, pkg);
+      return have === null || have === pin ? [] : [`${pkg}@${have} (basalt-ui pins ${pin}): \`bun add ${pkg}@${pin}\``];
+    });
+    if (off.length === 0) return null;
+    return {
+      fail: `${id}: installed peers differ from basalt-ui's exact pins. Fix: ${off.join("; ")}.`
+    };
+  });
+}
+export {
+  appWiringCheck,
+  droppedSubpathsCheck,
+  exactPeersCheck,
+  retiredLintRulesCheck,
+  seedTsconfigExtends,
+  tsconfigBaseCheck,
+  tsconfigFile,
+  unknownConfigKeysCheck
+};

package/dist/cli/doctor.d.ts

@@ -12,40 +12,25 @@ export type DoctorResult = {
     skipped: number;
 };
 /**
- * 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}). Seven 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.
- *   7. `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-13. `tsconfig-base`, `retired-lint-rules`, `dropped-subpaths`, `app-wiring`, `exact-peers`,
+ *      `config-keys` (./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.
- *   6. `claude-md`: a project-root `CLAUDE.md` that does not import `@AGENTS.md` suppresses
- *      `AGENTS.md` (and with it the managed block); one that still carries a basalt block — or a
- *      malformed one — says so. A `CLAUDE.md` symlinked to `AGENTS.md` is one file and passes.
+ *   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 declare function doctor(invocationCwd?: string, flags?: string[]): number;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA8CA,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CA+P1F"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAuDA,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CAsS1F"}

package/dist/cli/doctor.js

@@ -26,6 +26,14 @@ import {
   shippedAssetPath
 } from "./index.js";
 import { resolveRoots } from "./config.js";
+import {
+  appWiringCheck,
+  droppedSubpathsCheck,
+  exactPeersCheck,
+  retiredLintRulesCheck,
+  tsconfigBaseCheck,
+  unknownConfigKeysCheck
+} from "./doctor-upgrade.js";
 import { findManifestAbove, parentInstallAdvice } from "./sync.js";
 function isSameFile(a, b) {
   try {
@@ -83,6 +91,10 @@ basalt-ui doctor \u2014 ${cwd}
     lines.push(`  \u2716 ${msg}`);
     result.hardFailures++;
   }
+  function skip(msg) {
+    lines.push(`  ? SKIPPED ${msg}`);
+    result.skipped++;
+  }
   if (project.relocatedFrom !== null) {
     lines.push(`  \u2192 BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.
 `);
@@ -112,7 +124,7 @@ basalt-ui doctor \u2014 ${cwd}
   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 === void 0 || install.version === manifestVersion) {
     const matches = manifestVersion === void 0 ? "" : " and matches the manifest's basaltVersion";
@@ -127,7 +139,7 @@ basalt-ui doctor \u2014 ${cwd}
     pass("guard-scan: n/a \u2014 a tokens-only consumer runs the token lane, not the file walk");
   } else if (scanned === 0) {
     fail(
-      "guard-scan: `check-theme` would scan ZERO files here \u2014 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)."
+      'guard-scan: `check-theme` would scan ZERO files here \u2014 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). Fix: set `"basalt": { "roots": ["src"] }` in package.json.'
     );
   } else {
     pass(`guard-scan: check-theme covers ${scanned} file(s) under ${resolveRoots(cfg).join(", ")}`);
@@ -144,14 +156,14 @@ basalt-ui doctor \u2014 ${cwd}
       const parsed = parseJsonc(oxlintrcRaw);
       if (parsed === null) {
         fail(
-          ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset"
+          ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset. Fix the syntax error, then re-run `basalt-ui doctor`."
         );
       } else {
         const entry = basaltPresetEntry(parsed["extends"]);
         const correct = shippedAssetPath(install, cwd, OXLINT_FILES.preset);
         if (entry === null) {
           fail(
-            `.oxlintrc.json does NOT extend the shipped preset \u2014 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.`
+            `.oxlintrc.json does NOT extend the shipped preset \u2014 every basalt/* design rule is off and oxlint reports green without them. Add "extends": ["${correct}"], or re-run \`basalt-ui init\` to splice it in (or add it by hand).`
           );
         } else if (!existsSync(resolve(cwd, entry))) {
           fail(
@@ -191,7 +203,9 @@ basalt-ui doctor \u2014 ${cwd}
     if (scan.problem !== null) {
       issues.push(`has a malformed basalt block (${scan.problem}) \u2014 fix it by hand, then \`sync\``);
     } else if (scan.region !== null) {
-      issues.push(`still carries a stale basalt block \u2014 run \`basalt-ui sync\` to move it`);
+      issues.push(
+        `still carries a stale basalt block \u2014 delete it by hand; \`sync\` keeps ${AGENTS_MD} current`
+      );
     }
     if (!importsAgentsMd(legacy)) {
       issues.push(
@@ -215,10 +229,12 @@ basalt-ui doctor \u2014 ${cwd}
         );
       } else if (aiMajorSkewReasonInvalid) {
         fail(
-          `ai package major version mismatch within this package.json: ${summary} \u2014 basalt.aiMajorSkewReason is present but is not a non-empty string (a bare \`true\` is not accepted); the exemption must carry a written reason.`
+          `ai package major version mismatch within this package.json: ${summary} \u2014 basalt.aiMajorSkewReason is present but is not a non-empty string (a bare \`true\` is 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;
@@ -233,17 +249,50 @@ basalt-ui doctor \u2014 ${cwd}
   } else {
     pass("ai-major-parity: this package.json declares no ai dependency \u2014 nothing to compare");
   }
+  if (profile === "tokens-only") {
+    pass(
+      "tsconfig-base / retired-lint-rules / dropped-subpaths / app-wiring: n/a \u2014 a tokens-only consumer"
+    );
+  } else {
+    const upgrade = [
+      ["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)
+      ],
+      ["exact-peers: installed exact-pinned peers match basalt-ui", exactPeersCheck(cwd, install)],
+      [
+        "config-keys: the basalt config block sets only keys basalt-ui reads",
+        unknownConfigKeysCheck(cwd)
+      ]
+    ];
+    for (const [ok, check] of upgrade) {
+      if (check === null) pass(ok);
+      else if ("fail" in check) fail(check.fail);
+      else skip(check.skip);
+    }
+  }
   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 = [];
     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/dist/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC,CAkC1F,CAAA;AAED;yCACyC;AACzC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED,0GAA0G;AAC1G,eAAO,MAAM,KAAK,QAoC0E,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC,CAgC1F,CAAA;AAED;yCACyC;AACzC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED,0GAA0G;AAC1G,eAAO,MAAM,KAAK,QAoC0E,CAAA"}

package/dist/cli/help.js

@@ -1,9 +1,7 @@
 import { parseArgs } from "node:util";
 const COMMAND_OPTIONS = {
   init: {
-    "with-router": { type: "boolean" },
-    "with-query": { type: "boolean" },
-    "merge-lint": { type: "boolean" }
+    "no-merge-lint": { type: "boolean" }
   },
   sync: {
     force: { type: "boolean" },
@@ -46,7 +44,7 @@ function unknownFlag(cmd, flags) {
     return match?.[1] ?? flags.find((f) => f.startsWith("-")) ?? flags[0] ?? null;
   }
 }
-const USAGE = "Usage: basalt-ui <--version | init [--with-router] [--with-query] [--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\ncheck-theme [--tokens-only|--framework] [--audit-allows]\n  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n  `basalt.exemptRules` entry, with what each one still suppresses \u2014 proved by re-running the\n  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Checks THIS project only: the manifest exists, the oxlint preset is wired, the pre-commit\n  hook runs check-theme (via `lefthook dump`), and the ai package major is consistent within\n  this package.json. Profile is DECLARED, same as check-theme \u2014 never inferred.\n\nsync [--force] [--check] [--verbose] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n  --check prints the permanent placement skips as a COUNT; --verbose spells them out again.\n\ncheck-theme / doctor / sync all resolve their project the same way: BASALT_CWD, else the\ninvocation cwd \u2014 nothing inferred, nothing ascended or descended into.\n--tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.\n--version / -v prints the resolved package version and exits 0 \u2014 the one command that proves\nWHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\nunrecognized flag exits 1 and names what it did not understand; neither is ever ignored.";
+const USAGE = "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\ncheck-theme [--tokens-only|--framework] [--audit-allows]\n  --audit-allows reports instead of scanning: every `theme-allow` annotation and every\n  `basalt.exemptRules` entry, with what each one still suppresses \u2014 proved by re-running the\n  guard with that one waiver neutralized, not by reading its text. Exits 1 on a waiver that\n  suppresses nothing (dead), which is what makes it usable as a CI gate.\n\ntokens:css [--out <path>] [--check] [--selector-attribute <attr> | --selector-class <class>]\n           [--light-class <class>] [--dark-value <v>] [--light-value <v>]\n           [--default-scheme <dark|light|none>] [--media-fallback] [--only <core|all>]\n           [--no-legacy-aliases]\n  Emit the --vx-* stylesheet (stdout unless --out). Defaults reproduce basalt-ui/tokens.css.\n  --selector-class emits `:root.dark` instead of an attribute selector (the Tailwind convention).\n  --check writes nothing and exits 1 when --out differs from what would be emitted (a CI gate).\n  --no-legacy-aliases drops the deprecated camelCase spellings (--vx-accentFill and friends),\n  which are emitted by default as aliases of the canonical kebab-case names.\n\nfonts:css [--out <path>] [--check]\n  Emit the shipped --basalt-font-* stacks as plain CSS \u2014 the typeface half of the token layer,\n  otherwise reachable only by importing styles.css.\n\ndoctor [--tokens-only|--framework]\n  Checks THIS project only: the manifest exists, the oxlint preset is wired, the pre-commit\n  hook runs check-theme (via `lefthook dump`), and the ai package major is consistent within\n  this package.json. Profile is DECLARED, same as check-theme \u2014 never inferred.\n\nsync [--force] [--check] [--verbose] [--tokens-only|--framework]\n  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n  has no scaffold to reconcile, so sync reports n/a and exits 0 there \u2014 as doctor does.\n  --check prints the permanent placement skips as a COUNT; --verbose spells them out again.\n\ncheck-theme / doctor / sync all resolve their project the same way: BASALT_CWD, else the\ninvocation cwd \u2014 nothing inferred, nothing ascended or descended into.\n--tokens-only and --framework are alternatives; passing both is an error.\n\nEvery subcommand accepts --help / -h to print this message and exit without running.\n--version / -v prints the resolved package version and exits 0 \u2014 the one command that proves\nWHICH basalt-ui ran, which a `bunx` cache can otherwise make a lie. An unknown command or an\nunrecognized flag exits 1 and names what it did not understand; neither is ever ignored.";
 export {
   COMMAND_OPTIONS,
   USAGE,