basalt-ui 1.27.0 → 1.29.0

package/dist/cli/check-theme.js

@@ -0,0 +1,139 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  checkSource,
+  DEFAULT_GUARD_CONFIG,
+  guardKindRemedy,
+  TOKENS_ONLY_DISABLED_KINDS,
+  unmatchedExemptPatterns
+} from "../guard/index.js";
+import { auditAllows } from "./audit-allows.js";
+import {
+  conflictingProfileFlags,
+  declaredProfile,
+  DEFAULT_ROOTS,
+  readBasaltConfig,
+  resolveExemptRules,
+  resolveProjectDir,
+  resolveRoots,
+  scannableFiles,
+  SERIES_MODULE_HINT_RE,
+  waiverHintFor
+} from "./index.js";
+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);
+  const cwd = project.dir;
+  if (project.relocatedFrom !== null) {
+    console.log(
+      `basalt-ui check-theme: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`
+    );
+  }
+  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,
+    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
+    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
+    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
+    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
+    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
+    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
+    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
+    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
+    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
+    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
+    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
+    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
+    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
+    allowComment: "theme-allow",
+    exemptRules: resolveExemptRules(cfg),
+    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
+    ...profile === "tokens-only" ? { profile: "tokens-only" } : {}
+  };
+  const findings = [];
+  const scanned = scannableFiles(cwd, cfg);
+  for (const rel of scanned) {
+    findings.push(...checkSource(readFileSync(resolve(cwd, rel), "utf8"), rel, guardCfg));
+  }
+  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.`
+      );
+    } else {
+      console.error(
+        `\u2716 basalt-ui check-theme: 0 files scanned \u2014 the configured "basalt.roots" (${roots.join(", ")}) matched zero files. Check the paths in "basalt.roots" in package.json.`
+      );
+    }
+    return 1;
+  }
+  if (flags.includes("--audit-allows")) return auditAllows(cwd, cfg, guardCfg, scanned);
+  for (const unmatched of unmatchedExemptPatterns(guardCfg, scanned)) {
+    console.error(
+      `\u26A0 basalt-ui check-theme: "basalt.exemptRules" entry ${unmatched.kind}: "${unmatched.pattern}" ` + (unmatched.reason === "unknown-kind" ? "names no guard kind \u2014 it exempts nothing at all (a typo, or a kind that was renamed)." : "matched none of the scanned files \u2014 it suppresses nothing, and reads as coverage in a config review while enforcing as much as an empty object.")
+    );
+  }
+  if (findings.length === 0) {
+    console.log("\u2713 Theme guard: no off-palette colors.");
+    return 0;
+  }
+  const errors = findings.filter((f) => f.severity === "error");
+  const warnings = findings.filter((f) => f.severity === "warn");
+  const report = (group, heading) => {
+    const byFile = /* @__PURE__ */ new Map();
+    for (const f of group) {
+      const list = byFile.get(f.relPath) ?? [];
+      list.push(f);
+      byFile.set(f.relPath, list);
+    }
+    console.error(heading);
+    for (const [file, vs] of [...byFile].toSorted()) {
+      console.error(file);
+      for (const v of vs.toSorted((a, b) => a.line - b.line)) {
+        console.error(`  ${String(v.line).padStart(4)}  ${v.kind.padEnd(22)} ${v.text}`);
+      }
+      console.error("");
+    }
+  };
+  if (warnings.length > 0) {
+    report(
+      warnings,
+      // Deliberately neutral about WHY a kind is a warning. Two origins reach this block — a kind
+      // in its grace minor, and a consumer's own `basalt.severity` override — and the finding
+      // doesn't carry which. Promising promotion next minor would be wrong for the second.
+      `\u26A0 Theme guard: ${warnings.length} warning(s) \u2014 reported, not fatal. A kind warns while it is in its grace minor, or because \`basalt.severity\` turned it down; fix on your own schedule.
+`
+    );
+  }
+  if (errors.length > 0) {
+    report(errors, `\u2716 Theme guard: ${errors.length} off-palette / off-identity violation(s)
+`);
+  }
+  const presentKinds = [...new Set(findings.map((f) => f.kind))].toSorted();
+  const waiverHints = [
+    ...new Set(findings.map((f) => waiverHintFor(f.relPath, profile)))
+  ].toSorted();
+  console.error(["Fix:", ...presentKinds.map(guardKindRemedy), ...waiverHints].join(" "));
+  if (findings.some((f) => SERIES_MODULE_HINT_RE.test(f.relPath))) {
+    console.error(
+      'Hint: if a flagged file IS your palette/series source, exempt it via "basalt": { "exempt": ["<path>"] } in package.json.'
+    );
+  }
+  return errors.length > 0 ? 1 : 0;
+}
+export {
+  checkTheme
+};

package/dist/cli/doctor.d.ts

@@ -0,0 +1,47 @@
+export type DoctorResult = {
+    /** Number of hard failures (exit non-zero). */
+    hardFailures: number;
+    /** Number of warnings (informational only). */
+    warnings: number;
+    /**
+     * Number of checks that could not RUN (as opposed to ran and passed). Counted separately and
+     * exits non-zero on its own: under bun's isolated linker `doctor` used to drop two of its five
+     * checks and still print "All checks passed", which is the same false-green this whole surface
+     * exists to remove. A check that cannot run is not a check that passed.
+     */
+    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}). Four checks, numbered in
+ * the order they run and print:
+ *
+ * Hard failures (exit non-zero):
+ *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
+ *   2. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
+ *      preset AND that path resolves. `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.
+ *   4. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *      `peerDependencies` agree on the `ai` package's major. `basalt/ai-sdk-major` (the oxlint
+ *      plugin rule) already catches this per linted FILE against its nearest package.json; this
+ *      check exists for the shape a lint run cannot see — a package whose own manifest asks its
+ *      dependents for one major while it itself runs another. A detected skew is exempt-able via
+ *      `basalt.aiMajorSkewReason` (a non-empty reason string, not a bare `true`); missing or
+ *      invalid still hard-fails as if the key were absent. A declared reason when the majors
+ *      already agree warns that the exemption is stale.
+ *
+ * Warning (non-fatal):
+ *   3. `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.
+ *
+ * Returns the exit code: 0 = all good, 1 = one or more hard failures.
+ */
+export declare function doctor(invocationCwd?: string, flags?: string[]): number;
+//# sourceMappingURL=doctor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA0BA,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CAsM1F"}

package/dist/cli/doctor.js

@@ -0,0 +1,197 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  MANIFEST_PATH,
+  basaltBinCommand,
+  basaltPresetEntry,
+  conflictingProfileFlags,
+  declaredProfile,
+  findBasaltInstall,
+  findRepoRoot,
+  inspectLefthookGate,
+  parseJsonc,
+  readBasaltConfig,
+  readIfExists,
+  resolveProjectDir,
+  shippedAssetPath
+} from "./index.js";
+import { findManifestAbove, parentInstallAdvice } from "./sync.js";
+function majorOf(range) {
+  if (typeof range !== "string") return null;
+  const match = range.match(/\d+/);
+  return match === null ? null : Number(match[0]);
+}
+const AI_MAJOR_FIELDS = ["dependencies", "devDependencies", "peerDependencies"];
+function aiMajorsAt(dir) {
+  const raw = readIfExists(resolve(dir, "package.json"));
+  if (raw === null) return {};
+  try {
+    const pkg = JSON.parse(raw);
+    const out = {};
+    for (const field of AI_MAJOR_FIELDS) {
+      const major = majorOf(pkg[field]?.["ai"]);
+      if (major !== null) out[field] = major;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+function resolveAiMajorSkewReason(cfg) {
+  const raw = cfg.aiMajorSkewReason;
+  if (raw === void 0) return { reason: null, presentButInvalid: false };
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return { reason: raw, presentButInvalid: false };
+  }
+  return { reason: null, presentButInvalid: true };
+}
+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);
+  const cwd = project.dir;
+  const cfg = readBasaltConfig(cwd);
+  const result = { hardFailures: 0, warnings: 0, skipped: 0 };
+  const lines = [`
+basalt-ui doctor \u2014 ${cwd}
+`];
+  function pass(msg) {
+    lines.push(`  \u2713 ${msg}`);
+  }
+  function warn(msg) {
+    lines.push(`  \u26A0 ${msg}`);
+    result.warnings++;
+  }
+  function fail(msg) {
+    lines.push(`  \u2716 ${msg}`);
+    result.hardFailures++;
+  }
+  if (project.relocatedFrom !== null) {
+    lines.push(`  \u2192 BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.
+`);
+  }
+  const profile = declaredProfile(cfg, flags);
+  if (profile === "tokens-only") {
+    lines.push(
+      "  profile: tokens-only \u2014 checking the token layer only. `basalt-ui init` is NOT the fix\n  here, it places a Mantine doctrine you have no use for. Pass --framework to force the\n  full profile.\n"
+    );
+  }
+  const manifestAbs = resolve(cwd, MANIFEST_PATH);
+  const manifestExists = existsSync(manifestAbs);
+  const parentInstall = manifestExists ? null : findManifestAbove(cwd);
+  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 if (parentInstall !== null) {
+    fail(
+      `${MANIFEST_PATH} missing here, but this is not an unscaffolded consumer. ${parentInstallAdvice(cwd, parentInstall, "doctor")} \`basalt-ui init\` is NOT the fix: it would scaffold a SECOND consumer beside the real one.`
+    );
+  } else {
+    fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
+  }
+  const install = findBasaltInstall(cwd);
+  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. " + (parentInstall === null ? "Run `basalt-ui init` to seed it." : `${parentInstallAdvice(cwd, parentInstall, "doctor")} The preset is seeded once, at the install \u2014 not per package.`)
+      );
+    } else {
+      const parsed = parseJsonc(oxlintrcRaw);
+      if (parsed === null) {
+        fail(
+          ".oxlintrc.json does not parse as JSON/JSONC \u2014 cannot tell whether it extends the preset"
+        );
+      } else {
+        const entry = basaltPresetEntry(parsed["extends"]);
+        const correct = shippedAssetPath(install, cwd, "configs/oxlint.json");
+        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.`
+          );
+        } else if (!existsSync(resolve(cwd, entry))) {
+          fail(
+            `.oxlintrc.json extends "${entry}", which does not exist (${resolve(cwd, entry)}) \u2014 oxlint refuses to start on a missing extends target (\`NotFound\`), so nothing is linted at all. Repoint it at "${correct}", where basalt-ui actually resolves.`
+          );
+        } else {
+          pass(`.oxlintrc.json extends the shipped basalt-ui oxlint preset (${entry})`);
+        }
+      }
+    }
+  }
+  const repoRoot = findRepoRoot(cwd);
+  const lefthookGate = profile === "tokens-only" ? { kind: "n/a" } : inspectLefthookGate(repoRoot);
+  const lefthookCorrect = shippedAssetPath(install, repoRoot, "configs/lefthook.yml");
+  if (lefthookGate.kind === "n/a") {
+    pass("lefthook-preset: n/a \u2014 a tokens-only consumer wires its own hooks");
+  } else if (lefthookGate.kind === "no-file") {
+    pass(`lefthook-preset: n/a \u2014 no lefthook config at ${repoRoot}`);
+  } else if (lefthookGate.kind === "wired") {
+    pass(`${lefthookGate.file}: \`lefthook dump\` shows a pre-commit command running check-theme.`);
+  } else if (lefthookGate.kind === "absent") {
+    warn(
+      `${lefthookGate.file}: \`lefthook dump\` resolves the merged config and NO pre-commit command runs check-theme \u2014 the theme guard is not gating commits. Add "extends: [${lefthookCorrect}]", or your own command running \`${basaltBinCommand(install, cwd)} check-theme\`.`
+    );
+  } else {
+    warn(
+      `${lefthookGate.file}: \`lefthook dump\` could not be run or parsed here (lefthook may not be installed) \u2014 treat this check as advisory. Verify by running \`lefthook dump\` yourself.`
+    );
+  }
+  const aiMajors = aiMajorsAt(cwd);
+  const aiEntries = AI_MAJOR_FIELDS.filter((field) => aiMajors[field] !== void 0).map(
+    (field) => ({ field, major: aiMajors[field] })
+  );
+  const { reason: aiMajorSkewReason, presentButInvalid: aiMajorSkewReasonInvalid } = resolveAiMajorSkewReason(cfg);
+  if (aiEntries.length > 0) {
+    const distinctMajors = new Set(aiEntries.map((entry) => entry.major));
+    if (distinctMajors.size > 1) {
+      const summary = aiEntries.map((entry) => `${entry.field}@ai${entry.major}`).join(", ");
+      if (aiMajorSkewReason !== null) {
+        pass(
+          `ai package major version mismatch within this package.json: ${summary} \u2014 exempted via basalt.aiMajorSkewReason: "${aiMajorSkewReason}"`
+        );
+      } 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.`
+        );
+      } else {
+        fail(`ai package major version mismatch within this package.json: ${summary}`);
+      }
+    } else {
+      const [major] = distinctMajors;
+      if (aiMajorSkewReason !== null) {
+        warn(
+          `basalt.aiMajorSkewReason ("${aiMajorSkewReason}") is declared but the ai package major already agrees within this package.json (ai@${major}) \u2014 the exemption is no longer needed and can be deleted.`
+        );
+      } else {
+        pass(`ai package major is consistent within this package.json (ai@${major})`);
+      }
+    }
+  } else {
+    pass("ai-major-parity: this package.json declares no ai dependency \u2014 nothing to compare");
+  }
+  lines.push("");
+  if (result.hardFailures === 0 && result.warnings === 0) {
+    lines.push("All checks passed.");
+  } else {
+    const parts = [];
+    if (result.hardFailures > 0) parts.push(`${result.hardFailures} hard failure(s)`);
+    parts.push(`${result.warnings} warning(s)`);
+    lines.push(`${parts.join(", ")}.`);
+  }
+  lines.push("");
+  if (result.hardFailures > 0) {
+    console.error(lines.join("\n"));
+    return 1;
+  }
+  console.log(lines.join("\n"));
+  return 0;
+}
+export {
+  doctor
+};

package/dist/cli/guard-hook.d.ts

@@ -0,0 +1,9 @@
+/**
+ * guard-hook — PreToolUse stdin adapter.
+ *
+ * Reads a JSON PreToolUse payload from stdin, evaluates it against the consumer's GuardConfig
+ * (from the "basalt" key in the nearest package.json), and writes the Claude Code hook response
+ * to stdout. Always exits 0 — the hook must never block Claude on a parse error or non-file tool.
+ */
+export declare function guardHook(cwd?: string): Promise<number>;
+//# sourceMappingURL=guard-hook.d.ts.map

package/dist/cli/guard-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-hook.d.ts","sourceRoot":"","sources":["../../src/cli/guard-hook.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF5E"}

package/dist/cli/guard-hook.js

@@ -0,0 +1,93 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { DEFAULT_GUARD_CONFIG } from "../guard/index.js";
+import { evaluateGuardHook } from "../guard/guard-hook.js";
+import {
+  DEFAULT_ROOTS,
+  SKIP,
+  declaredProfile,
+  defaultExempt,
+  readBasaltConfig,
+  resolveExemptRules
+} from "./index.js";
+async function guardHook(cwd = process.cwd()) {
+  let raw;
+  try {
+    if (typeof globalThis["Bun"] !== "undefined") {
+      raw = await globalThis["Bun"].stdin.text();
+    } else {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      raw = Buffer.concat(chunks).toString("utf8");
+    }
+  } catch {
+    process.stdout.write(
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
+    );
+    return 0;
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.stdout.write(
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
+    );
+    return 0;
+  }
+  const cfg = readBasaltConfig(cwd);
+  const guardCfg = {
+    spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
+    rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
+    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
+    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
+    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
+    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
+    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
+    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
+    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
+    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
+    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
+    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
+    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
+    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
+    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
+    allowComment: "theme-allow",
+    exemptRules: resolveExemptRules(cfg),
+    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));
+  const isInScope = (filePath) => {
+    const abs = isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+    const rel = relative(cwd, abs).replace(/\\/g, "/");
+    if (rel === "" || rel.startsWith("..")) return false;
+    if (SKIP.test(rel) || exempt.has(rel)) return false;
+    return roots.some((root) => {
+      const r = root.replace(/\\/g, "/").replace(/\/+$/, "");
+      return rel === r || rel.startsWith(`${r}/`);
+    });
+  };
+  const result = evaluateGuardHook(payload, guardCfg, { isInScope });
+  if (result.permissionDecision === "deny" && result.reason !== void 0) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: result.reason
+        }
+      }) + "\n"
+    );
+  } else {
+    process.stdout.write(
+      '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n'
+    );
+  }
+  return 0;
+}
+export {
+  guardHook
+};

package/dist/cli/help.d.ts

@@ -0,0 +1,9 @@
+export declare const COMMAND_OPTIONS: Record<string, Record<string, {
+    type: 'string' | 'boolean';
+}>>;
+/** The first flag `cmd` does not accept, or null. Unknown commands return null — the dispatcher's
+ * default branch already names those. */
+export declare function unknownFlag(cmd: string, flags: readonly string[]): string | null;
+/** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
+export declare const USAGE: string;
+//# sourceMappingURL=help.d.ts.map

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

@@ -0,0 +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,CAiC1F,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,QAmC0E,CAAA"}

package/dist/cli/help.js

@@ -0,0 +1,53 @@
+import { parseArgs } from "node:util";
+const COMMAND_OPTIONS = {
+  init: {
+    "with-router": { type: "boolean" },
+    "with-query": { type: "boolean" },
+    "merge-lint": { type: "boolean" }
+  },
+  sync: {
+    force: { type: "boolean" },
+    check: { type: "boolean" },
+    "tokens-only": { type: "boolean" },
+    framework: { type: "boolean" }
+  },
+  "check-theme": {
+    "audit-allows": { type: "boolean" },
+    "tokens-only": { type: "boolean" },
+    framework: { type: "boolean" }
+  },
+  doctor: { "tokens-only": { type: "boolean" }, framework: { type: "boolean" } },
+  "guard-hook": {},
+  "tokens:css": {
+    out: { type: "string" },
+    check: { type: "boolean" },
+    "selector-attribute": { type: "string" },
+    "selector-class": { type: "string" },
+    "light-class": { type: "string" },
+    "dark-value": { type: "string" },
+    "light-value": { type: "string" },
+    "default-scheme": { type: "string" },
+    "media-fallback": { type: "boolean" },
+    only: { type: "string" },
+    "no-legacy-aliases": { type: "boolean" }
+  },
+  "fonts:css": { out: { type: "string" }, check: { type: "boolean" } }
+};
+function unknownFlag(cmd, flags) {
+  const options = COMMAND_OPTIONS[cmd];
+  if (options === void 0) return null;
+  try {
+    parseArgs({ args: [...flags], options, strict: true, allowPositionals: false });
+    return null;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const match = /'(-{1,2}[^']+)'/.exec(message);
+    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] [--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] [--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\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,
+  unknownFlag
+};