basalt-ui 1.19.0 → 1.20.0

package/dist/cli/index.js

@@ -10,7 +10,13 @@ import {
 } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkSource, DEFAULT_GUARD_CONFIG, GUARD_RULES } from "../guard/index.js";
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
+  GUARD_RULES,
+  TOKENS_ONLY_DISABLED_KINDS
+} from "../guard/index.js";
 import { evaluateGuardHook } from "../guard/guard-hook.js";
 import { RULE_NAMES, SKILL_NAMES, SURFACES, TOKEN_LAYER_BOUNDARY_SURFACES } from "../surfaces.js";
 import { buildPaletteCss, deriveSpacing } from "../tokens/index.js";
@@ -61,6 +67,7 @@ function readBasaltConfig(cwd) {
     return {};
   }
 }
+const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
   let entries;
   try {
@@ -78,7 +85,7 @@ function walkSourceFiles(dir, out = []) {
       continue;
     }
     if (isDir) walkSourceFiles(abs, out);
-    else if (/\.(?:tsx?|css)$/.test(name)) out.push(abs);
+    else if (SCANNABLE_EXT.test(name)) out.push(abs);
   }
   return out;
 }
@@ -101,10 +108,145 @@ const GUARD_KIND_EXPLANATIONS = {
   "sub-16-input-font": "sub-16-input-font: fontSize below 16 on a form control is dead code against the `!important` iOS floor in styles.css \u2014 drop the override or be honest about 16px.",
   "raw-font-family": "raw-font-family: route the font stack through createBasaltTheme(overrides, { fonts }) / the --basalt-font-sans|head|mono vars instead of a hardcoded fontFamily literal."
 };
-function checkTheme(cwd = process.cwd()) {
-  const cfg = readBasaltConfig(cwd);
-  const roots = cfg.roots ?? DEFAULT_ROOTS;
+function relativePosix(fromDir, toPath) {
+  const rel = relative(fromDir, toPath).replace(/\\/g, "/");
+  if (rel === "") return ".";
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+const UNRESOLVED_INSTALL = { dir: null, version: null, how: null };
+function basaltInstallAt(dir) {
+  const installDir = resolve(dir, "node_modules", "basalt-ui");
+  const raw = readIfExists(resolve(installDir, "package.json"));
+  if (raw === null) return null;
+  try {
+    const pkg = JSON.parse(raw);
+    return { dir: installDir, version: pkg.version ?? null };
+  } catch {
+    return { dir: installDir, version: null };
+  }
+}
+function findBasaltInstall(cwd) {
+  const own = basaltInstallAt(cwd);
+  if (own !== null) return { ...own, how: "cwd" };
+  let current = dirname(cwd);
+  for (; ; ) {
+    const found = basaltInstallAt(current);
+    if (found !== null) return { ...found, how: "ancestor" };
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  for (const pkg of collectWorkspacePackages(cwd).packages) {
+    if (pkg.dir === cwd) continue;
+    const found = basaltInstallAt(pkg.dir);
+    if (found !== null) return { ...found, how: "workspace" };
+  }
+  return UNRESOLVED_INSTALL;
+}
+function shippedAssetPath(install, fromDir, asset) {
+  if (install.dir === null) return `./node_modules/basalt-ui/${asset}`;
+  return `${relativePosix(fromDir, install.dir)}/${asset}`;
+}
+function hasBasaltProject(dir) {
+  if (existsSync(resolve(dir, MANIFEST_PATH))) return true;
+  const raw = readIfExists(resolve(dir, "package.json"));
+  if (raw === null) return false;
+  try {
+    return JSON.parse(raw).basalt !== void 0;
+  } catch {
+    return false;
+  }
+}
+function resolveProjectDir(cwd) {
+  const override = process.env["BASALT_CWD"];
+  if (override !== void 0 && override.length > 0) {
+    const dir = isAbsolute(override) ? override : resolve(cwd, override);
+    return { dir, relocatedFrom: dir === cwd ? null : cwd, ambiguous: null };
+  }
+  if (hasBasaltProject(cwd)) return { dir: cwd, relocatedFrom: null, ambiguous: null };
+  const candidates = collectWorkspacePackages(cwd).packages.filter((pkg) => pkg.dir !== cwd && hasBasaltProject(pkg.dir)).map((pkg) => pkg.dir);
+  if (candidates.length === 1) {
+    return { dir: candidates[0], relocatedFrom: cwd, ambiguous: null };
+  }
+  if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates };
+  return { dir: cwd, relocatedFrom: null, ambiguous: null };
+}
+function declaredProfile(cfg, flags) {
+  if (flags.includes("--tokens-only")) return "tokens-only";
+  if (flags.includes("--framework")) return "framework";
+  return cfg.profile === "tokens-only" ? "tokens-only" : "framework";
+}
+function conflictingProfileFlags(flags) {
+  return flags.includes("--tokens-only") && flags.includes("--framework");
+}
+function workspaceHasMantine(cwd) {
+  if (hasDependency(cwd, "@mantine/core")) return true;
+  return collectWorkspacePackages(cwd).packages.some(
+    (pkg) => hasDependency(pkg.dir, "@mantine/core")
+  );
+}
+function inferredProfile(cwd, cfg, flags) {
+  if (flags.includes("--tokens-only") || flags.includes("--framework") || cfg.profile !== void 0) {
+    return declaredProfile(cfg, flags);
+  }
+  return !existsSync(resolve(cwd, MANIFEST_PATH)) && !workspaceHasMantine(cwd) ? "tokens-only" : "framework";
+}
+function scannableFiles(cwd, cfg) {
   const exempt = new Set(cfg.exempt ?? defaultExempt(cfg));
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (abs) => {
+    const rel = relative(cwd, abs).replace(/\\/g, "/");
+    if (rel.startsWith("..") || SKIP.test(rel) || exempt.has(rel) || seen.has(rel)) return;
+    seen.add(rel);
+    out.push(rel);
+  };
+  for (const root of resolveRoots(cfg)) {
+    const rootAbs = resolve(cwd, root);
+    for (const f of walkSourceFiles(rootAbs)) add(f);
+    for (const f of appShellFiles(rootAbs)) add(f);
+  }
+  for (const rel of cfg.include ?? []) add(resolve(cwd, rel));
+  return out;
+}
+function appShellFiles(rootAbs) {
+  const appDir = dirname(rootAbs);
+  const out = [];
+  for (const name of ["index.html", "index.htm"]) {
+    const abs = resolve(appDir, name);
+    if (existsSync(abs)) out.push(abs);
+  }
+  out.push(...walkSourceFiles(resolve(appDir, "public")));
+  return out;
+}
+function checkTheme(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error(
+      "basalt-ui check-theme: --tokens-only and --framework are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `\u2716 basalt-ui check-theme: no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run it from one of them, or set BASALT_CWD to pick.`
+    );
+    return 1;
+  }
+  const cwd = project.dir;
+  if (project.relocatedFrom !== null) {
+    console.log(
+      `basalt-ui check-theme: no basalt config at ${project.relocatedFrom} \u2014 running in ${relativePosix(project.relocatedFrom, cwd)}, where it lives.`
+    );
+  }
+  const cfg = readBasaltConfig(cwd);
+  const roots = resolveRoots(cfg);
+  const profile = declaredProfile(cfg, flags);
+  if (profile === "tokens-only") {
+    console.log(
+      `basalt-ui check-theme: tokens-only profile \u2014 ${TOKENS_ONLY_DISABLED_KINDS.size} Mantine-coupled kinds are off; the color and typography kinds still apply. Pass --framework to force the full set.`
+    );
+  }
   const guardCfg = {
     spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
     rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
@@ -124,20 +266,15 @@ function checkTheme(cwd = process.cwd()) {
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
     exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity
+    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    ...profile === "tokens-only" ? { profile: "tokens-only" } : {}
   };
   const findings = [];
-  let scannedCount = 0;
-  for (const root of roots) {
-    for (const f of walkSourceFiles(resolve(cwd, root))) {
-      const rel = relative(cwd, f).replace(/\\/g, "/");
-      if (SKIP.test(rel) || exempt.has(rel)) continue;
-      scannedCount += 1;
-      const text = readFileSync(f, "utf8");
-      findings.push(...checkSource(text, rel, guardCfg));
-    }
+  const scanned = scannableFiles(cwd, cfg);
+  for (const rel of scanned) {
+    findings.push(...checkSource(readFileSync(resolve(cwd, rel), "utf8"), rel, guardCfg));
   }
-  if (scannedCount === 0) {
+  if (scanned.length === 0) {
     if (cfg.roots === void 0) {
       console.error(
         `\u2716 basalt-ui check-theme: 0 files scanned \u2014 no "basalt.roots" configured in package.json, and the built-in default roots (${DEFAULT_ROOTS.join(", ")}) matched zero files. Set "basalt": { "roots": [...] } in package.json to point at your source directories.`
@@ -230,12 +367,17 @@ function readFrameworkVersion(pkgRoot) {
   }
 }
 function buildTemplateVars(pkgRoot, cwd, cfg) {
+  const install = findBasaltInstall(cwd);
+  const binDir = install.dir === null ? null : resolve(install.dir, "..", ".bin");
   return {
     APP_NAME: readPackageName(cwd),
     BASALT_VERSION: readFrameworkVersion(pkgRoot),
     ACCENT_HUE: cfg.accentHue ?? "blue",
     SERIES_MODULE_PATH: resolveSeriesModulePath(cfg),
-    ROOTS_GLOBS: resolveRoots(cfg).map(toRootGlob).join(" ")
+    ROOTS_GLOBS: resolveRoots(cfg).map(toRootGlob).join(" "),
+    OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, "configs/oxlint.json"),
+    LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, "configs/lefthook.yml"),
+    BASALT_BIN: binDir === null ? "bunx basalt-ui" : `${relativePosix(cwd, binDir).replace(/^\.\//, "")}/basalt-ui`
   };
 }
 function fillTemplate(tpl, vars) {
@@ -383,7 +525,15 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     dest: "lefthook.yml",
     mode: "seed",
     source: "configs/lefthook.yml",
-    render: () => "# Seeded by basalt-ui init \u2014 you own this file; sync never touches it again.\n# The extends target supplies oxlint + oxfmt + check-theme pre-commit jobs and\n# auto-updates with the basalt-ui package. Add your own commands alongside.\nextends:\n  - node_modules/basalt-ui/configs/lefthook.yml\n"
+    render: (ctx) => `# Seeded by basalt-ui init \u2014 you own this file; sync never touches it again.
+# The extends target supplies oxlint + oxfmt + check-theme pre-commit jobs and
+# auto-updates with the basalt-ui package. Add your own commands alongside.
+# The path is RESOLVED from where basalt-ui actually installed, not assumed at the
+# repo root \u2014 under an isolated linker it lives beside the package that depends on it.
+# Run \`lefthook install\` once: the file is inert until the git hooks are written.
+extends:
+  - ${ctx.vars.LEFTHOOK_PRESET_PATH.replace(/^\.\//, "")}
+`
   };
   const ci = {
     dest: ".github/workflows/check.yml",
@@ -399,7 +549,10 @@ function managedFiles(peers, placement = ROOT_PLACEMENT) {
     dest: ".oxlintrc.json",
     mode: "seed",
     source: "configs/oxlint.json",
-    render: () => '{\n  "extends": ["./node_modules/basalt-ui/configs/oxlint.json"]\n}\n'
+    render: (ctx) => `{
+  "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"]
+}
+`
   };
   const queryClient = {
     dest: "src/query-client.ts",
@@ -510,15 +663,142 @@ function renderContext(cwd) {
   const pkgRoot = packageRoot();
   return { pkgRoot, vars: buildTemplateVars(pkgRoot, cwd, readBasaltConfig(cwd)) };
 }
+function patchPackageJson(cwd, mutate) {
+  const abs = resolve(cwd, "package.json");
+  const raw = readIfExists(abs);
+  if (raw === null) return false;
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  if (!mutate(pkg)) return false;
+  const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? "  ";
+  writeFileSync(abs, JSON.stringify(pkg, null, indent) + (raw.endsWith("\n") ? "\n" : ""));
+  return true;
+}
+function detectRoots(cwd) {
+  const workspacePackages = collectWorkspacePackages(cwd).packages.filter((pkg) => pkg.dir !== cwd);
+  const withSrc = workspacePackages.filter((pkg) => existsSync(resolve(pkg.dir, "src")));
+  const uiPackages = withSrc.filter(
+    (pkg) => hasDependency(pkg.dir, "basalt-ui") || hasDependency(pkg.dir, "@mantine/core")
+  );
+  const chosen = uiPackages.length > 0 ? uiPackages : withSrc;
+  if (chosen.length > 0) {
+    return chosen.map((pkg) => relativePosix(cwd, resolve(pkg.dir, "src")).replace(/^\.\//, ""));
+  }
+  return existsSync(resolve(cwd, DEFAULT_ROOT)) ? [DEFAULT_ROOT] : [];
+}
+function stripJsonc(text) {
+  let out = "";
+  let inString = false;
+  let escaped = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (inString) {
+      out += ch;
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      out += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i += 1;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i += 1;
+      i += 2;
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1");
+}
+function parseJsonc(text) {
+  try {
+    return JSON.parse(stripJsonc(text));
+  } catch {
+    return null;
+  }
+}
+function extendsBasaltPreset(entries) {
+  return Array.isArray(entries) && entries.some(
+    (entry) => typeof entry === "string" && entry.endsWith("basalt-ui/configs/oxlint.json")
+  );
+}
+function mergeOxlintExtends(cwd, presetPath) {
+  const abs = resolve(cwd, ".oxlintrc.json");
+  const raw = readIfExists(abs);
+  if (raw === null) return "absent";
+  const cfg = parseJsonc(raw);
+  if (cfg === null) return "unreadable";
+  if (extendsBasaltPreset(cfg["extends"])) return "already";
+  if (stripJsonc(raw) !== raw) return "has-comments";
+  const existing = Array.isArray(cfg["extends"]) ? cfg["extends"].filter((entry) => typeof entry === "string") : [];
+  const merged = "extends" in cfg ? {} : { extends: [presetPath] };
+  for (const [key, value] of Object.entries(cfg)) {
+    merged[key] = key === "extends" ? [presetPath, ...existing] : value;
+  }
+  const indent = /\n([ \t]+)"/.exec(raw)?.[1] ?? "  ";
+  writeFileSync(abs, JSON.stringify(merged, null, indent) + (raw.endsWith("\n") ? "\n" : ""));
+  return "added";
+}
+const KEPT_FILE_COST = {
+  ".oxlintrc.json": "the shipped oxlint preset (the basalt/* design rules AND the jsx-a11y / import / promise / unicorn plugins) is NOT active \u2014 nothing else turns it on, and every gate stays green without it. Re-run with `--merge-lint` to splice the extends in, or add it by hand.",
+  "lefthook.yml": "the pre-commit oxlint / oxfmt / check-theme jobs are not wired \u2014 add `extends: [<preset>]` to your own file.",
+  ".github/workflows/check.yml": "CI does not run check-theme or the sync drift gate \u2014 copy those steps into your own workflow.",
+  ".oxfmtrc.json": "your existing formatter config stands; basalt formats nothing on its own.",
+  "DESIGN.md": "the design brief Claude reads is yours, not the seeded one."
+};
 function init(cwd = process.cwd(), scaffoldFlags = {}) {
+  const install = findBasaltInstall(cwd);
+  if (install.dir === null) {
+    console.error(
+      `\u26A0 basalt-ui init: basalt-ui does not resolve from ${cwd} or any directory above it \u2014 the seeded \`extends\` paths and CI steps are being written against the repo root by assumption. Install basalt-ui here (or at the repo root) and re-run \`basalt-ui init\` so they resolve.`
+    );
+  }
+  let seededRoots = null;
+  let rootsUndetectable = false;
+  if (readBasaltConfig(cwd).roots === void 0) {
+    const detected = detectRoots(cwd);
+    if (detected.length === 0) {
+      rootsUndetectable = true;
+    } else if (patchPackageJson(cwd, (pkg) => {
+      const basalt = pkg["basalt"] ?? {};
+      if (basalt["roots"] !== void 0) return false;
+      pkg["basalt"] = { ...basalt, roots: detected };
+      return true;
+    })) {
+      seededRoots = detected;
+    }
+  }
   const ctx = renderContext(cwd);
+  const lintScript = `oxlint . && ${ctx.vars.BASALT_BIN} check-theme`;
+  const seededLintScript = patchPackageJson(cwd, (pkg) => {
+    const scripts = pkg["scripts"] ?? {};
+    if (scripts["lint:basalt"] !== void 0) return false;
+    pkg["scripts"] = { ...scripts, "lint:basalt": lintScript };
+    return true;
+  });
   const manifest = readManifest(cwd);
   migrateLegacyOxfmt(cwd, ctx.pkgRoot, manifest);
   const peers = resolvePeerFlags(cwd, scaffoldFlags);
   const placement = resolvePlacement(cwd);
   const files = managedFiles(peers, placement);
-  let written = 0;
-  let skipped = 0;
+  const writtenFiles = [];
+  const keptFiles = [];
   const missingSources = [];
   for (const file of files) {
     const state = unitState(file, cwd, ctx);
@@ -529,29 +809,63 @@ function init(cwd = process.cwd(), scaffoldFlags = {}) {
     const destExists = existsSync(resolve(cwd, file.dest));
     if (!file.markers && destExists) {
       manifest.files[file.dest] = sha256(normalizeForLedger(state.desired));
-      skipped++;
+      keptFiles.push(file.dest);
       continue;
     }
     const hash = writeUnit(file, cwd, state.desired);
     manifest.files[file.dest] = hash;
-    written++;
+    writtenFiles.push(file.dest);
   }
+  const mergeLint = scaffoldFlags.mergeLint === true ? mergeOxlintExtends(cwd, ctx.vars.OXLINT_PRESET_PATH) : null;
   manifest.basaltVersion = ctx.vars.BASALT_VERSION;
   manifest.spacingScale = { ...deriveSpacing(0).scale };
   writeFileEnsuringDir(resolve(cwd, MANIFEST_PATH), `${JSON.stringify(manifest, null, 2)}
 `);
-  console.log(`basalt-ui init: ${written} written, ${skipped} kept, manifest at ${MANIFEST_PATH}`);
+  console.log(
+    `basalt-ui init: ${writtenFiles.length} written, ${keptFiles.length} kept, manifest at ${MANIFEST_PATH}`
+  );
   if (missingSources.length > 0) {
     console.log(
       `basalt-ui init: ${missingSources.length} shipped asset(s) not present, skipped: ${missingSources.join(", ")}`
     );
   }
+  if (keptFiles.length > 0) {
+    console.log(`
+Kept (already present \u2014 basalt did not touch them):`);
+    for (const dest of keptFiles) {
+      const cost = KEPT_FILE_COST[dest];
+      console.log(cost === void 0 ? `  \xB7 ${dest}` : `  \xB7 ${dest} \u2014 ${cost}`);
+    }
+  }
+  if (mergeLint !== null) {
+    const mergeMessage = {
+      added: `spliced "${ctx.vars.OXLINT_PRESET_PATH}" into the existing .oxlintrc.json extends`,
+      already: ".oxlintrc.json already extends the shipped preset \u2014 nothing to do",
+      absent: "no existing .oxlintrc.json to merge into (the seeded one already extends the preset)",
+      unreadable: ".oxlintrc.json is not valid JSON \u2014 merge the extends entry by hand",
+      "has-comments": `.oxlintrc.json carries comments; rewriting it would delete them (usually the reason each rule is off). Add "extends": ["${ctx.vars.OXLINT_PRESET_PATH}"] as the first entry by hand.`
+    };
+    console.log(`basalt-ui init: --merge-lint \u2014 ${mergeMessage[mergeLint]}`);
+  }
+  if (seededRoots !== null) {
+    console.log(
+      `basalt-ui init: wrote "basalt": { "roots": ${JSON.stringify(seededRoots)} } to package.json \u2014 check-theme, the CI oxfmt globs and the default scan exemption all derive from it. Correct it if your sources live elsewhere.`
+    );
+  }
+  if (rootsUndetectable) {
+    console.error(
+      '\u26A0 basalt-ui init: could not infer "basalt.roots" \u2014 no src/ here and no workspace package with one. Set "basalt": { "roots": [...] } in package.json by hand, or check-theme will fail with "0 files scanned".'
+    );
+  }
+  if (seededLintScript) {
+    console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`);
+  }
   if (!placement.isPackageRepoRoot) {
     console.log(
-      `basalt-ui init: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.`
+      `basalt-ui init: skipped lefthook.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 lefthook only reads config at the repo root; extend ${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` so the guard runs where your basalt config actually lives.`
     );
     console.log(
-      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.`
+      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root \u2014 repo root detected at ${placement.repoRoot}) \u2014 GitHub Actions only reads .github/ at the repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, "configs/check.yml")} into your root CI workflow instead.`
     );
   }
   if (placement.relocatedQueryClient !== null) {
@@ -581,11 +895,32 @@ Theme guard hook: add to .claude/settings.json \u2192 hooks.PreToolUse to catch
     ]
   }`
   );
+  const presetPlugins = readOxlintPresetPlugins(ctx.pkgRoot);
+  if (presetPlugins.length > 0) {
+    console.log(
+      `
+Lint debt: adopting the shipped oxlint preset on an EXISTING app is not a no-op \u2014 it turns on ${presetPlugins.length} plugins (${presetPlugins.join(", ")}) plus the basalt/* design rules, on code never linted against them. Run \`oxlint .\` now and triage the count before your next commit; turn a rule off in your own .oxlintrc.json with a written reason rather than blanket-disabling a plugin.`
+    );
+  }
+  console.log(
+    "Activate the hooks: `lefthook install` \u2014 the seeded lefthook.yml is inert until the git hooks are written, and looks configured either way."
+  );
   console.log(
-    "\nFirst run: run `basalt-ui check-theme` next, then tune the per-rule `basalt.*` config keys in package.json for anything that fires \u2014 do not mass-`theme-allow` findings."
+    `
+First run: run \`${ctx.vars.BASALT_BIN} check-theme\` next (or \`bun run lint:basalt\`), then tune the per-rule \`basalt.*\` config keys in package.json for anything that fires \u2014 do not mass-\`theme-allow\` findings. Then \`basalt-ui doctor\` to confirm the wiring actually took.`
   );
   return 0;
 }
+function readOxlintPresetPlugins(pkgRoot) {
+  const raw = readSource(pkgRoot, "configs/oxlint.json");
+  if (raw === null) return [];
+  try {
+    const plugins = JSON.parse(raw).plugins;
+    return isStringArray(plugins) ? plugins : [];
+  } catch {
+    return [];
+  }
+}
 function sync(opts = {}, cwd = process.cwd()) {
   const ctx = renderContext(cwd);
   const manifest = readManifest(cwd);
@@ -725,7 +1060,7 @@ function checkCoverage() {
   for (const exportKey of pkgExports) {
     if (exportKey === "." || exportKey === "./styles.css" || exportKey.startsWith("./configs/"))
       continue;
-    if (!(exportKey in SURFACES)) {
+    if (!Object.hasOwn(SURFACES, exportKey)) {
       failures.push(`package.json exports key '${exportKey}' has no matching SURFACES entry`);
     }
   }
@@ -880,9 +1215,27 @@ function resolveAiMajorSkewReason(cfg) {
   }
   return { reason: null, presentButInvalid: true };
 }
-function doctor(cwd = process.cwd()) {
+function doctor(invocationCwd = process.cwd(), flags = []) {
+  if (conflictingProfileFlags(flags)) {
+    console.error("basalt-ui doctor: --tokens-only and --framework are alternatives \u2014 pass one.");
+    return 1;
+  }
+  const project = resolveProjectDir(invocationCwd);
+  if (project.ambiguous !== null) {
+    console.error(
+      `
+basalt-ui doctor \u2014 ${invocationCwd}
+
+  \u2716 no basalt config at ${invocationCwd}, and ${project.ambiguous.length} workspace packages carry one (${project.ambiguous.map((d) => relativePosix(invocationCwd, d)).join(", ")}) \u2014 run doctor from one of them, or set BASALT_CWD to pick.
+
+1 hard failure(s), 0 warning(s).
+`
+    );
+    return 1;
+  }
+  const cwd = project.dir;
   const cfg = readBasaltConfig(cwd);
-  const result = { hardFailures: 0, warnings: 0 };
+  const result = { hardFailures: 0, warnings: 0, skipped: 0 };
   const lines = [`
 basalt-ui doctor \u2014 ${cwd}
 `];
@@ -893,26 +1246,59 @@ basalt-ui doctor \u2014 ${cwd}
     lines.push(`  \u26A0 ${msg}`);
     result.warnings++;
   }
+  function skip(msg) {
+    lines.push(`  \u2298 SKIPPED \u2014 ${msg}`);
+    result.skipped++;
+  }
   function fail(msg) {
     lines.push(`  \u2716 ${msg}`);
     result.hardFailures++;
   }
+  if (project.relocatedFrom !== null) {
+    lines.push(
+      `  \u2192 no basalt config at ${project.relocatedFrom} \u2014 reporting on ${relativePosix(project.relocatedFrom, cwd)}, where it lives.
+`
+    );
+  }
   const manifestAbs = resolve(cwd, MANIFEST_PATH);
   const manifestExists = existsSync(manifestAbs);
-  if (manifestExists) {
+  const profile = inferredProfile(cwd, cfg, flags);
+  if (profile === "tokens-only") {
+    lines.push(
+      "  profile: tokens-only \u2014 checking the token layer only. The scaffold checks below are not\n  applicable; `basalt-ui init` is NOT the fix here, it places a Mantine doctrine you have no\n  use for. Pass --framework to force the full profile.\n"
+    );
+    if (cfg.profile === void 0) {
+      lines.push(
+        '  \u2192 inferred (no .basalt/manifest.json and no @mantine/core in this workspace). Write it\n    down as "basalt": { "profile": "tokens-only" } in package.json \u2014 check-theme does not\n    infer it, so today it still reports the Mantine-only kinds against this repo.\n'
+      );
+    }
+  }
+  if (profile === "tokens-only") {
+    pass(`${MANIFEST_PATH}: n/a \u2014 a tokens-only consumer has no scaffold to reconcile`);
+  } else if (manifestExists) {
     pass(`${MANIFEST_PATH} exists`);
   } else {
     fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
   }
-  const consumerPkgRaw = readIfExists(resolve(cwd, "node_modules", "basalt-ui", "package.json"));
-  let installedVersion = null;
-  if (consumerPkgRaw !== null) {
-    try {
-      const consumerPkg = JSON.parse(consumerPkgRaw);
-      installedVersion = consumerPkg.version ?? null;
-    } catch {
-      warn("could not parse node_modules/basalt-ui/package.json \u2014 version checks skipped");
-    }
+  const install = findBasaltInstall(cwd);
+  const installedVersion = install.version;
+  if (install.dir === null) {
+    fail(
+      `basalt-ui does not resolve from ${cwd}, any directory above it, or any workspace package \u2014 so every version check below is unrunnable, \`extends: [<preset>]\` cannot resolve, and \`bunx basalt-ui\` will silently fetch a DIFFERENT copy from npm instead of your pinned one. Add basalt-ui as a dependency here (or at the repo root) and re-run.`
+    );
+  } else if (install.how === "cwd") {
+    pass(
+      `basalt-ui resolves at ./node_modules/basalt-ui (${installedVersion ?? "unknown version"})`
+    );
+  } else {
+    pass(
+      `basalt-ui resolves at ${relativePosix(cwd, install.dir)} (${installedVersion ?? "unknown version"}, found via the ${install.how}) \u2014 seeded \`extends\` paths and CI steps must use that path, not ./node_modules/basalt-ui.`
+    );
+  }
+  if (profile === "framework" && manifestExists && installedVersion === null) {
+    skip(
+      "installed-vs-manifest version \u2014 basalt-ui did not resolve, so there is nothing to compare"
+    );
   }
   if (manifestExists && installedVersion !== null) {
     const manifestVersion = readManifest(cwd).basaltVersion;
@@ -930,11 +1316,17 @@ basalt-ui doctor \u2014 ${cwd}
   }
   const cliVersion = readFrameworkVersion(packageRoot());
   const cliIsTheInstall = installedVersion === null || installedVersion === cliVersion;
-  if (manifestExists && !cliIsTheInstall) {
+  if (profile === "tokens-only") {
+    pass("spacing scale: n/a \u2014 a tokens-only consumer renders no basalt Mantine theme");
+  } else if (!manifestExists) {
+    skip(
+      `spacing scale \u2014 no ${MANIFEST_PATH} records the scale this app last synced with, so there is nothing to compare against`
+    );
+  } else if (!cliIsTheInstall) {
     pass(
       `spacing scale not compared \u2014 this CLI (${cliVersion}) is not the installed basalt-ui (${installedVersion}), so its scale is not the one the app renders with`
     );
-  } else if (manifestExists) {
+  } else {
     const recorded = readManifest(cwd).spacingScale;
     const current = deriveSpacing(0).scale;
     if (recorded === void 0) {
@@ -951,17 +1343,54 @@ basalt-ui doctor \u2014 ${cwd}
       }
     }
   }
-  if (installedVersion !== null) {
-    if (installedVersion !== cliVersion) {
-      warn(
-        `running CLI version (${cliVersion}) differs from the installed basalt-ui version in node_modules (${installedVersion}) \u2014 likely a stale \`bunx basalt-ui\` fetch from npm; add basalt-ui as a root devDependency so the bin hoists from your workspace.`
+  if (installedVersion === null) {
+    skip("CLI-vs-installed version \u2014 basalt-ui did not resolve, so there is no installed version");
+  } else if (installedVersion !== cliVersion) {
+    warn(
+      `running CLI version (${cliVersion}) differs from the installed basalt-ui version at ${install.dir === null ? "node_modules" : relativePosix(cwd, install.dir)} (${installedVersion}) \u2014 likely a stale \`bunx basalt-ui\` fetch from npm; run the local bin (\`node_modules/.bin/basalt-ui\`, or a package.json script) so the pinned copy is the one that runs.`
+    );
+  } else {
+    pass(`CLI version (${cliVersion}) matches the installed basalt-ui`);
+  }
+  if (profile === "tokens-only") {
+    pass("guard-scan: n/a \u2014 the theme guard is a Mantine-app check");
+  } else {
+    const scanned = scannableFiles(cwd, cfg);
+    if (scanned.length === 0) {
+      fail(
+        `guard-scan: check-theme would scan 0 files \u2014 the roots (${resolveRoots(cfg).join(", ")}) match nothing under ${cwd}, so the palette guard is a no-op that still exits green in every gate that does not run it. Set "basalt": { "roots": [...] } in package.json.`
       );
     } else {
-      pass(`CLI version (${cliVersion}) matches the installed basalt-ui in node_modules`);
+      pass(
+        `guard-scan: check-theme covers ${scanned.length} file(s) under ${resolveRoots(cfg).join(", ")}`
+      );
+    }
+  }
+  if (profile === "tokens-only") {
+    pass("oxlint-preset: n/a \u2014 the shipped preset is a Mantine/React preset");
+  } else {
+    const oxlintrcRaw = readIfExists(resolve(cwd, ".oxlintrc.json"));
+    if (oxlintrcRaw === null) {
+      fail(
+        ".oxlintrc.json missing \u2014 the shipped oxlint preset (the basalt/* design rules) is not active. Run `basalt-ui init` to seed it."
+      );
+    } else {
+      const parsed = parseJsonc(oxlintrcRaw);
+      if (parsed === null) {
+        skip(
+          ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset"
+        );
+      } else if (extendsBasaltPreset(parsed["extends"])) {
+        pass(".oxlintrc.json extends the shipped basalt-ui oxlint preset");
+      } else {
+        fail(
+          `.oxlintrc.json does NOT extend the shipped preset \u2014 every basalt/* design rule is off and oxlint reports green without them. Add "extends": ["${shippedAssetPath(install, cwd, "configs/oxlint.json")}"], or re-run \`basalt-ui init --merge-lint\` to splice it in.`
+        );
+      }
     }
   }
   const publicDir = resolve(cwd, "public");
-  if (existsSync(publicDir)) {
+  if (profile === "framework" && existsSync(publicDir)) {
     const iconFiles = [
       "favicon.ico",
       "favicon.svg",
@@ -1013,15 +1442,17 @@ basalt-ui doctor \u2014 ${cwd}
     pass("ai-major-parity: no workspace package declares the ai dependency \u2014 nothing to compare");
   }
   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 {
-    if (result.hardFailures > 0)
-      lines.push(`${result.hardFailures} hard failure(s), ${result.warnings} warning(s).`);
-    else lines.push(`${result.warnings} warning(s).`);
+    const parts = [];
+    if (result.hardFailures > 0) parts.push(`${result.hardFailures} hard failure(s)`);
+    if (result.skipped > 0) parts.push(`${result.skipped} check(s) SKIPPED (could not run)`);
+    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;
   }
@@ -1101,8 +1532,61 @@ function flagValue(flags, name) {
   const value = flags[i + 1];
   return value === void 0 || value.startsWith("--") ? void 0 : value;
 }
+function generatedHeader(version, command, flags) {
+  const shown = flags.filter((f) => f !== "--check");
+  const invocation = shown.length === 0 ? command : `${command} ${shown.join(" ")}`;
+  return `${GENERATED_HEADER_LINE}
+/* basalt-ui ${version} \u2014 \`basalt-ui ${invocation}\` */
+`;
+}
+function normalizeColorFunctions(css) {
+  return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
+    const parts = args.split(",").map((part) => part.trim());
+    return `${fn}(${parts.join(", ")})`;
+  });
+}
+const SCHEME_CLASS_SENTINEL = "data-basalt-scheme-class";
+function emitGeneratedCss(content, flags, cwd, command) {
+  const out = flagValue(flags, "--out");
+  const check = flags.includes("--check");
+  if (out === void 0) {
+    if (check) {
+      console.error(
+        `${command}: --check needs --out <path> \u2014 there is nothing to compare stdout to.`
+      );
+      return 1;
+    }
+    process.stdout.write(content);
+    return 0;
+  }
+  const target = isAbsolute(out) ? out : resolve(cwd, out);
+  const shown = relative(cwd, target) || target;
+  if (check) {
+    const onDisk = readIfExists(target);
+    if (onDisk === null) {
+      console.error(
+        `\u2716 ${command} --check: ${shown} does not exist \u2014 run without --check to write it.`
+      );
+      return 1;
+    }
+    if (onDisk === content) {
+      console.log(`\u2713 ${command} --check: ${shown} is up to date.`);
+      return 0;
+    }
+    console.error(
+      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${onDisk.split("\n").length} lines, emitted ${content.split("\n").length}) \u2014 re-run the same command without --check and commit the result.`
+    );
+    return 1;
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  console.log(`wrote ${content.split("\n").length} lines \u2192 ${shown}`);
+  return 0;
+}
 function tokensCss(flags, cwd = process.cwd()) {
   const attribute = flagValue(flags, "--selector-attribute");
+  const schemeClass = flagValue(flags, "--selector-class");
+  const lightClass = flagValue(flags, "--light-class");
   const darkValue = flagValue(flags, "--dark-value");
   const lightValue = flagValue(flags, "--light-value");
   const defaultScheme = flagValue(flags, "--default-scheme");
@@ -1117,12 +1601,31 @@ function tokensCss(flags, cwd = process.cwd()) {
     console.error(`tokens:css: --only must be core or all (got '${only}')`);
     return 1;
   }
+  if (schemeClass !== void 0 && attribute !== void 0) {
+    console.error(
+      "tokens:css: --selector-class and --selector-attribute are alternatives \u2014 pass one."
+    );
+    return 1;
+  }
+  if (schemeClass !== void 0 && /[^\w-]/.test(schemeClass)) {
+    console.error(
+      `tokens:css: --selector-class must be a plain CSS class name (got '${schemeClass}')`
+    );
+    return 1;
+  }
+  if (lightClass !== void 0 && /[^\w-]/.test(lightClass)) {
+    console.error(`tokens:css: --light-class must be a plain CSS class name (got '${lightClass}')`);
+    return 1;
+  }
+  const resolvedDarkValue = schemeClass !== void 0 ? schemeClass : darkValue;
+  const resolvedLightValue = schemeClass !== void 0 ? lightClass ?? "light" : lightValue;
+  const resolvedAttribute = schemeClass !== void 0 ? SCHEME_CLASS_SENTINEL : attribute;
   const scheme = {
-    ...attribute === void 0 ? {} : { attribute },
-    ...darkValue === void 0 ? {} : { darkValue },
-    ...lightValue === void 0 ? {} : { lightValue }
+    ...resolvedAttribute === void 0 ? {} : { attribute: resolvedAttribute },
+    ...resolvedDarkValue === void 0 ? {} : { darkValue: resolvedDarkValue },
+    ...resolvedLightValue === void 0 ? {} : { lightValue: resolvedLightValue }
   };
-  const css = buildPaletteCss({
+  let css = buildPaletteCss({
     ...Object.keys(scheme).length === 0 ? {} : { scheme },
     ...defaultScheme === void 0 ? {} : { defaultScheme },
     ...flags.includes("--media-fallback") ? { mediaFallback: true } : {},
@@ -1133,17 +1636,44 @@ function tokensCss(flags, cwd = process.cwd()) {
     // are, which is the one thing this command is documented never to allow.
     ...flags.includes("--no-legacy-aliases") ? { legacyAliases: false } : {}
   });
-  const out = flagValue(flags, "--out");
-  if (out === void 0) {
-    process.stdout.write(`${css}
-`);
-    return 0;
+  if (schemeClass !== void 0) {
+    css = css.replace(
+      new RegExp(`\\[${SCHEME_CLASS_SENTINEL}='([\\w-]+)'\\]`, "g"),
+      (_match, value) => `.${value}`
+    );
   }
-  const target = isAbsolute(out) ? out : resolve(cwd, out);
-  mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, css);
-  console.log(`wrote ${css.split("\n").length} lines \u2192 ${relative(cwd, target) || target}`);
-  return 0;
+  const version = readFrameworkVersion(packageRoot());
+  const content = `${generatedHeader(version, "tokens:css", flags)}${normalizeColorFunctions(css)}
+`;
+  return emitGeneratedCss(content, flags, cwd, "tokens:css");
+}
+function readShippedFontDecls(pkgRoot) {
+  const css = readSource(pkgRoot, "dist/styles.css") ?? readSource(pkgRoot, "src/styles.css");
+  if (css === null) return [];
+  const decls = [];
+  for (const match of css.matchAll(/(--basalt-font[\w-]*)\s*:\s*([^;]+);/g)) {
+    decls.push({
+      name: match[1],
+      value: match[2].replace(/\s+/g, " ").trim()
+    });
+  }
+  return decls;
+}
+function fontsCss(flags, cwd = process.cwd()) {
+  const pkgRoot = packageRoot();
+  const decls = readShippedFontDecls(pkgRoot);
+  if (decls.length === 0) {
+    console.error(
+      "fonts:css: could not read the shipped font stacks from styles.css \u2014 this is a packaging bug in basalt-ui, not a config error."
+    );
+    return 1;
+  }
+  const body = `:root {
+${decls.map((d) => `  ${d.name}: ${d.value};`).join("\n")}
+}
+`;
+  const header = generatedHeader(readFrameworkVersion(pkgRoot), "fonts:css", flags);
+  return emitGeneratedCss(`${header}${body}`, flags, cwd, "fonts:css");
 }
 async function guardHook(cwd = process.cwd()) {
   let raw;
@@ -1190,7 +1720,10 @@ async function guardHook(cwd = process.cwd()) {
     sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
     allowComment: "theme-allow",
     exemptRules: cfg.exemptRules ?? DEFAULT_GUARD_CONFIG.exemptRules,
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity
+    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    // Same detection check-theme uses: the hook must never block an edit over advice the app
+    // cannot take ("use @mantine/core's Select") in a repo with no Mantine.
+    ...declaredProfile(cfg, []) === "tokens-only" ? { profile: "tokens-only" } : {}
   };
   const roots = cfg.roots ?? DEFAULT_ROOTS;
   const exempt = new Set(cfg.exempt ?? defaultExempt(cfg));
@@ -1222,7 +1755,7 @@ async function guardHook(cwd = process.cwd()) {
   }
   return 0;
 }
-const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] | sync [--force] [--check] | check-theme | check-coverage | info [--json] | doctor | guard-hook | tokens:css | help>\n\ntokens:css [--out <path>] [--selector-attribute <attr>] [--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  --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\nEvery subcommand accepts --help / -h to print this message and exit without running.";
+const USAGE = "Usage: basalt-ui <init [--with-router] [--with-query] [--merge-lint] | sync [--force] [--check] |\n                  check-theme | check-coverage | info [--json] | doctor [--tokens-only|--framework] |\n                  guard-hook | tokens:css | fonts:css | help>\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  Auto-detects a tokens-only consumer (no manifest + no @mantine/core) and checks only what\n  applies. A check that cannot RUN is reported as SKIPPED and exits non-zero.\n\ncheck-theme / doctor honour BASALT_CWD, and relocate to the single workspace package carrying a\nbasalt config when invoked from a repo root that has none \u2014 several carrying one is ambiguous\nand exits 1 in BOTH. --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.";
 function run(argv, cwd = process.cwd()) {
   const [cmd, ...flags] = argv;
   if (cmd === "help" || cmd === "--help" || cmd === "-h" || flags.includes("--help") || flags.includes("-h")) {
@@ -1233,22 +1766,25 @@ function run(argv, cwd = process.cwd()) {
     case "init":
       return init(cwd, {
         withRouter: flags.includes("--with-router"),
-        withQuery: flags.includes("--with-query")
+        withQuery: flags.includes("--with-query"),
+        mergeLint: flags.includes("--merge-lint")
       });
     case "sync":
       return sync({ force: flags.includes("--force"), check: flags.includes("--check") }, cwd);
     case "check-theme":
-      return checkTheme(cwd);
+      return checkTheme(cwd, flags);
     case "check-coverage":
       return checkCoverage();
     case "info":
       return info(flags);
     case "doctor":
-      return doctor(cwd);
+      return doctor(cwd, flags);
     case "guard-hook":
       return guardHook(cwd);
     case "tokens:css":
       return tokensCss(flags, cwd);
+    case "fonts:css":
+      return fontsCss(flags, cwd);
     default:
       console.error(USAGE);
       return 1;
@@ -1261,10 +1797,12 @@ export {
   checkCoverage,
   checkTheme,
   doctor,
+  fontsCss,
   guardHook,
   info,
   init,
   managedFiles,
+  normalizeColorFunctions,
   normalizeForLedger,
   run,
   sync,