basalt-ui 1.27.0 → 1.29.0

package/dist/cli/index.d.ts

@@ -1,6 +1,11 @@
-import type { GuardKind, GuardSeverity } from '../guard/index.js';
+import type { GuardConfig, GuardKind, GuardSeverity } from '../guard/index.js';
 import { RULE_NAMES, SKILL_NAMES } from '../surfaces.js';
-import type { RuleName } from '../surfaces.js';
+import { checkTheme } from './check-theme.js';
+import { doctor } from './doctor.js';
+import { guardHook } from './guard-hook.js';
+import { init } from './init.js';
+import { sync } from './sync.js';
+import { fontsCss, normalizeColorFunctions, tokensCss } from './tokens-css.js';
 /** Shape of the optional `"basalt"` key in a consumer's package.json. */
 export type BasaltConfig = {
     /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
@@ -106,12 +111,6 @@ export type BasaltConfig = {
      * (ON). Set `false` to disable the `raw-motion-value` check.
      */
     rawMotionValue?: boolean;
-    /**
-     * Flag a hand-rolled `<ChartLegend items={[...]}>` array literal — legend entries must be
-     * derived (e.g. `items={deriveLegend(series)}`), never authored inline. Default: `true` (ON).
-     * Set `false` to disable the `unframed-chart` check.
-     */
-    unframedChart?: boolean;
     /**
      * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
      * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
@@ -185,19 +184,142 @@ export type BasaltConfig = {
  * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
  * it exists. See `BasaltConfig.exemptRules`.
  */
-type ExemptRuleEntry = string[] | {
+export type ExemptRuleEntry = string[] | {
     paths: string[];
     reason: string;
 };
+/** The paths half of an exemption entry, whichever form it was written in. */
+export declare function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[];
+/** The recorded reason for an exemption entry, or null for the bare-array form. */
+export declare function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null;
+/**
+ * The guard-shaped `exemptRules` — paths only. The reason the object form carries never reaches
+ * the guard: it is accountability for a human reading a diff and for `--audit-allows`, and giving
+ * the scan a second shape to understand would only be a way for the two to disagree.
+ */
+export declare function resolveExemptRules(cfg: BasaltConfig): GuardConfig['exemptRules'];
+export declare const DEFAULT_ROOT = "src";
+export declare const DEFAULT_ROOTS: string[];
+/**
+ * The configured source roots, or the built-in default. The ONE resolution every roots-derived seed
+ * reads — an empty `roots: []` falls back rather than resolving to nothing, because a bare `??`
+ * would let `[]` through and render an empty oxfmt glob into the seeded CI, reproducing the exact
+ * "matches zero files" break this derivation exists to prevent.
+ */
+export declare function resolveRoots(cfg: BasaltConfig): string[];
 /**
- * Theme guard — thin FS walker over the headless `../guard` core. Reads BasaltConfig, builds a
- * GuardConfig, walks roots, calls checkSource per file, collects Finding[], groups/reports, returns
- * 0 (clean) / 1 (violations). A `theme-allow` comment exempts a line.
+ * Default scan exemption — a bare consumer's only palette source is its series module (the doctrine
+ * directs every consumer to put raw hex series colors there). Shares `resolveSeriesModulePath` with
+ * `buildTemplateVars`'s `{{SERIES_MODULE_PATH}}`, so the seeded path and the exemption can't drift.
+ */
+export declare function defaultExempt(cfg: BasaltConfig): string[];
+export declare const SKIP: RegExp;
+/** Filenames that look like they ARE the palette source, for the check-theme escape-hatch hint. */
+export declare const SERIES_MODULE_HINT_RE: RegExp;
+export declare function readBasaltConfig(cwd: string): BasaltConfig;
+/** A path relative to `fromDir`, POSIX-separated and always explicitly relative (`./` / `../`). */
+export declare function relativePosix(fromDir: string, toPath: string): string;
+/**
+ * Where `basalt-ui` actually resolves from, seen from a consumer directory.
  *
- * Runs against `resolveProjectDir(cwd)`, not `cwd` — see that type's doc for why a root-invoked
- * hook or CI step has to find the package the config lives in rather than scan nothing and pass.
+ * Every toolchain seam basalt seeds (`.oxlintrc.json`'s `extends`, `lefthook.yml`'s `extends`, the
+ * CI `run:` steps) used to hardcode `./node_modules/basalt-ui` at the repo ROOT. Under bun's
+ * isolated linker a library package that declares basalt a peer + devDependency gets
+ * `<pkg>/node_modules/basalt-ui` and NOTHING at the root, so all three silently failed to resolve
+ * and `bunx` fetched a second, different copy from npm instead. Resolution therefore walks
+ * OUTWARD from the consumer dir first, then across the workspace packages — and every caller
+ * renders its paths from the answer rather than assuming the root.
+ */
+export type BasaltInstall = {
+    /** Absolute path of the resolved `node_modules/basalt-ui` directory, or null when unresolvable. */
+    dir: string | null;
+    /** The resolved copy's own version, or null. */
+    version: string | null;
+    /** How it was found — `null` when unresolved. `'workspace'` is the isolated-linker case. */
+    how: 'cwd' | 'ancestor' | 'workspace' | null;
+};
+/** Resolve the installed basalt-ui: cwd, then every ancestor, then the workspace packages. */
+export declare function findBasaltInstall(cwd: string): BasaltInstall;
+/**
+ * The `extends`/`run:` path a seeded config should carry to reach a shipped asset — rendered from
+ * where basalt ACTUALLY resolves, relative to the directory the config lives in. Falls back to the
+ * root-relative form when nothing resolves (a pre-install `init`), so the seed is still the shape a
+ * later `bun install` makes true.
  */
-export declare function checkTheme(invocationCwd?: string, flags?: readonly string[]): number;
+export declare function shippedAssetPath(install: BasaltInstall, fromDir: string, asset: string): string;
+/**
+ * Which directory a project-scoped command (`check-theme`, `doctor`) should actually read.
+ *
+ * One resolver, nothing inferred: `BASALT_CWD` when set, else the invocation cwd. A monorepo
+ * package whose install lives elsewhere sets `BASALT_CWD` explicitly (or the invoking script's
+ * `root:`/`cwd` does) rather than relying on workspace-glob discovery or an ancestor/descendant
+ * walk — both were deleted (see `resolveProjectDir`'s own doc below) as multi-repo speculation for
+ * a single-owner fleet where every consumer already runs its own commands from its own directory.
+ * The scan scope within that directory is `basalt.roots` in `package.json` (default `src`).
+ */
+type ProjectResolution = {
+    /** The directory to read. Equals the invocation cwd unless BASALT_CWD relocated it. */
+    dir: string;
+    /** The invocation cwd when BASALT_CWD relocated the command away from it, else null. */
+    relocatedFrom: string | null;
+};
+/**
+ * Which directory a project-scoped command reads: `BASALT_CWD` when set, else the invocation cwd
+ * — nothing inferred, nothing walked. Workspace-glob discovery and ancestor/descendant fallbacks
+ * (multi-repo speculation for a single-owner fleet where every consumer runs its own commands from
+ * its own directory) were deleted; a monorepo package that needs a different root sets `BASALT_CWD`
+ * explicitly, or the invoking script's `root:`/`cwd` does.
+ */
+export declare function resolveProjectDir(cwd: string): ProjectResolution;
+/**
+ * Which shape of consumer a project-scoped command is looking at.
+ *
+ * A tokens-only consumer took the `--vx-*` layer and nothing else. Every guard kind whose remedy is
+ * a Mantine component or the React theme factory is meaningless there — telling a Mantine-free app
+ * to swap its `<select>` for `@mantine/core`'s `Select` is advice it must not take.
+ *
+ * DECLARED, never inferred, when the answer SILENCES something. The two callers want opposite
+ * failure directions and so do not share a default:
+ *
+ * - `check-theme` (`declaredProfile`) turns 17 kinds OFF, so it moves on an explicit signal only —
+ *   `--tokens-only`, or `"basalt": { "profile": "tokens-only" }`. Inferring it from the ABSENCE of
+ *   `@mantine/core` would silence the Mantine half of the guard on any repo that keeps its Mantine
+ *   dependency in a workspace package rather than the one holding the basalt config, which is
+ *   precisely this round's "reports green while enforcing nothing" failure with the guard's own
+ *   hand on the switch.
+ * - `doctor` no longer infers a profile at all (workspace-wide Mantine detection was deleted along
+ *   with the rest of the multi-repo discovery); it reads the same declaration `check-theme` does.
+ */
+export declare function declaredProfile(cfg: BasaltConfig, flags: readonly string[]): DoctorProfile;
+/**
+ * `--tokens-only` and `--framework` are alternatives, so passing both is a contradiction rather
+ * than a precedence question — the same reading `tokens:css` already applies to `--selector-class`
+ * vs `--selector-attribute`. Silently preferring one meant a CI step that accumulated both flags
+ * enforced whichever the code happened to test first.
+ */
+export declare function conflictingProfileFlags(flags: readonly string[]): boolean;
+/**
+ * The relative paths `check-theme` would actually scan for a given config — the ONE place the walk
+ * + `SKIP` + `exempt` filtering lives, so `doctor`'s "the guard sees zero files" check can never
+ * disagree with what `check-theme` does.
+ */
+export declare function scannableFiles(cwd: string, cfg: BasaltConfig): string[];
+/**
+ * The waiver closer for a file, gated on the profile.
+ *
+ * `guardWaiverHint` keys off the file class, and for a `.webmanifest` it leads with
+ * `basaltAppPlugin` — right for a Mantine app, since a hex in a manifest can never be *right* and
+ * the plugin removes the hand-copy entirely. A `profile: tokens-only` consumer has definitionally
+ * opted out of that layer: rollhook's Astro site has no `index.html` for the plugin to transform,
+ * imports no basalt JavaScript at all, and owns maskable icons the plugin does not emit. Leading
+ * with the plugin there is advice the consumer cannot take, in the one release that finally gave
+ * that file class a remedy.
+ *
+ * So under tokens-only a manifest is treated as what it is to that consumer — plain JSON, with the
+ * member as the whole answer — plus one sentence saying which remedy is being withheld and why.
+ * The remedy text still comes from the guard's own registry; only the class mapping is decided here.
+ */
+export declare function waiverHintFor(relPath: string, profile: DoctorProfile): string;
 /**
  * How a file the framework writes into a consumer repo is owned. Two modes, one question:
  * **does Claude read this file?**
@@ -239,7 +361,7 @@ type ManagedFile = {
     render: (ctx: RenderContext) => string | null;
 };
 /** Everything a template needs to resolve its `{{…}}` placeholders. */
-type RenderContext = {
+export type RenderContext = {
     pkgRoot: string;
     vars: TemplateVars;
 };
@@ -266,28 +388,52 @@ type TemplateVars = {
      */
     BASALT_BIN: string;
 };
-declare const MANIFEST_PATH = ".basalt/manifest.json";
+export declare const MANIFEST_PATH = ".basalt/manifest.json";
+export declare function sha256(text: string): string;
+export declare function readIfExists(abs: string): string | null;
+/** Read a shipped source asset from the package root; null if the sibling hasn't authored it yet. */
+export declare function readSource(pkgRoot: string, source: string): string | null;
+/** The framework's own published version, read from the package root package.json. */
+export declare function readFrameworkVersion(pkgRoot: string): string;
+/**
+ * How a seeded script, a seeded CI step, or a piece of doctor advice should invoke the CLI.
+ *
+ * The LOCAL bin wherever basalt actually resolved; `bunx basalt-ui` only as the pre-install
+ * fallback. `bunx` does not re-resolve a package it has cached, so a seeded `bunx basalt-ui` lets a
+ * consumer pin one version and be gated by another — which is exactly what happened across three
+ * consumer repos, in CI, in package.json scripts and in a `.claude` PreToolUse hook, all of them
+ * placed here. Every emitted invocation goes through this function so there is one place for it to
+ * be right.
+ */
+export declare function basaltBinCommand(install: BasaltInstall, cwd: string): string;
 /**
  * Explicit `--with-router` / `--with-query` CLI flags force-include a router/query scaffold even
  * when the peer isn't detected in the consumer's package.json yet (e.g. it's about to be added).
  */
-type ScaffoldFlags = {
+export type ScaffoldFlags = {
     withRouter?: boolean;
     withQuery?: boolean;
     /** `--merge-lint`: splice the shipped preset's `extends` into an `.oxlintrc.json` init would keep. */
     mergeLint?: boolean;
 };
 /** Router/query peer presence, resolved from detection + explicit flags. */
-type PeerFlags = {
+export type PeerFlags = {
     hasRouter: boolean;
     hasQuery: boolean;
 };
+/**
+ * Resolves whether the consumer has the optional TanStack router/query peers — auto-detected from
+ * package.json, or forced via `--with-router` / `--with-query`. Both `basalt-ui init` (for gating
+ * which seed scaffolds to write) and `basalt-ui sync` (so it doesn't silently re-seed a scaffold whose
+ * peer was never installed) call this once, up front.
+ */
+export declare function resolvePeerFlags(cwd: string, flags: ScaffoldFlags): PeerFlags;
 /**
  * Where the seed engine is running relative to the consumer's git repo — decides which
  * repo-root-shaped seeds are safe to write. `init`/`sync` compute it once per run via
  * `resolvePlacement` and print the matching skip notices themselves; `managedFiles` only reads it.
  */
-type PlacementFlags = {
+export type PlacementFlags = {
     /** True when the package directory IS the detected repo root, or no `.git` exists anywhere above
      *  it (a consumer not using git keeps today's behaviour exactly). False means the package lives
      *  in a subdirectory of the repo (a monorepo's `web/`, say) — lefthook and GitHub Actions both
@@ -303,9 +449,20 @@ type PlacementFlags = {
      *  skip-if-exists logic every seed file already goes through, unchanged. */
     relocatedQueryClient: string | null;
 };
+/** The default placement — today's single-package-at-repo-root behaviour, unconditionally. */
+export declare const ROOT_PLACEMENT: PlacementFlags;
+/**
+ * Walks up from `dir` looking for a `.git` entry — ordinarily a directory, but a git worktree or
+ * submodule points it at a FILE instead, and both still mean "this directory is the repo root".
+ * Stops at the filesystem root. Returns `dir` itself when no `.git` is found anywhere, so a
+ * consumer not using git falls back to today's behaviour exactly.
+ */
+export declare function findRepoRoot(dir: string): string;
+/** Resolve a run's placement flags once, from the consumer cwd. */
+export declare function resolvePlacement(cwd: string): PlacementFlags;
 /** The full managed-file manifest. Stable, declarative — the single source of truth for init/sync. */
-declare function managedFiles(peers: PeerFlags, placement?: PlacementFlags): ManagedFile[];
-type Manifest = {
+export declare function managedFiles(peers: PeerFlags, placement?: PlacementFlags): ManagedFile[];
+export type Manifest = {
     version: 1;
     /** The basalt-ui version that last wrote this manifest — `doctor`'s one reconciliation axis. */
     basaltVersion?: string;
@@ -325,8 +482,56 @@ type Manifest = {
      */
     spacingScale?: Record<string, number>;
 };
+export declare function readManifest(cwd: string): Manifest;
 /** A tracked dest inside a derived namespace that this basalt version no longer ships. */
 export declare function retiredManagedDests(manifest: Manifest, files: readonly ManagedFile[]): readonly string[];
+/** Outcome of one prune pass — `removed` was deleted, `drifted` was locally edited and left alone. */
+export type PruneResult = {
+    removed: string[];
+    drifted: string[];
+};
+/**
+ * Report a prune pass. Always names the files: a doctrine file DISAPPEARING from a consumer's
+ * `.claude/` is exactly the class of change the sync diff exists to be reviewed, and `9 removed`
+ * with no names is what made the kept-files line a false green before 1.23.0.
+ */
+export declare function reportPrune(pruned: PruneResult): void;
+/**
+ * Delete the managed rule/skill files this basalt version retired, and drop their manifest entries.
+ *
+ * The 13→6 rule merge (`docs/CONTROLS-SPEC.md` §7) is the case this exists for: nine
+ * `.claude/rules/basalt-*.md` files stopped shipping in one minor, and without this a consumer's
+ * agent would go on reading `basalt-router.md`'s superseded placement doctrine forever, with
+ * `sync --check` reporting green because nothing in the ledger asks about a dest the run no longer
+ * places.
+ *
+ * Same three-way discipline as every other managed unit, so a consumer edit is never discarded
+ * silently: an untouched file (matching its recorded hash, raw or normalized) is deleted and its
+ * entry dropped; a locally-edited one is LEFT in place, reported, and keeps its entry so
+ * `sync --check` stays red and `--force` can still finish the job. `dryRun` is `--check`.
+ */
+export declare function pruneRetiredManagedFiles(cwd: string, manifest: Manifest, files: readonly ManagedFile[], opts?: {
+    dryRun?: boolean;
+    force?: boolean;
+}): PruneResult;
+/** The frozen `> Managed by basalt-ui (1.9.0).` opener every pre-fix DESIGN.md seed carries. */
+export declare function writeFileEnsuringDir(abs: string, content: string): void;
+/** Resolve the package root at runtime (two levels up from dist/cli/index.js). */
+export declare function packageRoot(): string;
+/**
+ * The current on-disk state of a managed unit, plus the version the framework wants. For a
+ * marker-spliced file the "current" unit is the existing region (markers included); otherwise it
+ * is the whole file.
+ */
+export type UnitState = {
+    /** The managed unit's current bytes on disk (block region / whole file). */
+    current: string | null;
+    /** The managed unit's desired bytes from the shipped source. null = source not shipped yet. */
+    desired: string | null;
+};
+/** Read the current vs desired managed-unit bytes for a file. */
+export declare function unitState(file: ManagedFile, cwd: string, ctx: RenderContext): UnitState;
+type Classification = 'unchanged' | 'drifted' | 'missing' | 'current';
 /**
  * Normalize a managed unit's rendered bytes for the ledger comparison below — makes a delta that is
  * PURELY formatting or a version bump invisible to drift detection, while a real prose/content edit
@@ -348,274 +553,156 @@ export declare function retiredManagedDests(manifest: Manifest, files: readonly
  * Deliberately whitespace-only — word content is untouched, so a genuine hand-edit inside the block
  * still changes the normalized text and still classifies `drifted`.
  */
-declare function normalizeForLedger(text: string): string;
-/** Scaffold all managed files into the consumer repo, then write the manifest. Idempotent. Returns 0. */
-export declare function init(cwd?: string, scaffoldFlags?: ScaffoldFlags): number;
-type SyncOptions = {
-    force?: boolean;
-    check?: boolean;
-    /** The raw flag list, read for `--tokens-only` / `--framework` exactly as check-theme reads it. */
-    flags?: readonly string[];
-};
+export declare function normalizeForLedger(text: string): string;
 /**
- * Reconcile managed files with the shipped versions via a sha256 three-way compare.
+ * Write a managed unit to disk (whole file, or marker-spliced region). Returns the unit's hash —
+ * `sha256(normalizeForLedger(desired))`, NOT the raw bytes.
  *
- * - `--check` makes NO writes; exits non-zero if any managed file is out-of-date or locally drifted
- *   (a CI freshness gate), exit 0 when all current.
- * - `--force` overwrites locally-drifted files instead of skipping them.
- *
- * Runs against `resolveProjectDir(cwd)`, exactly as `check-theme` and `doctor` do — and then
- * REFUSES rather than scaffolding when the resolved project has no manifest. See
- * {@link findManifestAbove} for the failure that bought this: `sync` is the drift refresh and
- * `init` is the scaffold, so placing twenty files on a cwd that was never a consumer is a decision
- * `sync` does not get to make silently.
+ * This is the ledger: the manifest already records "what basalt shipped last sync", one entry per
+ * dest — a stored NORMALIZED hash makes that same single entry survive both a downstream formatter
+ * (the consumer's own lefthook oxfmt reformatting the written file/block after this function has
+ * already returned) and a version bump that changed the template's own words since the recorded
+ * entry — the argo cross-version case: current is v1.0.0's block, post-oxfmt; desired is v1.0.1's
+ * (different words, e.g. the CLI bin rename). Recording the raw hash can never reconcile that;
+ * recording the normalized hash lets `classify()` normalize `state.current` the same way and
+ * compare directly against it, no separate historical-hash storage required.
  */
-export declare function sync(opts?: SyncOptions, invocationCwd?: string): number;
-/** The block's delimiters. Both are HTML comments, so the block renders as nothing in a viewer. */
-export declare const COVERAGE_BLOCK_OPEN = "<!-- basalt:coverage -->";
-export declare const COVERAGE_BLOCK_CLOSE = "<!-- /basalt:coverage -->";
+export declare function writeUnit(file: ManagedFile, cwd: string, desired: string): string;
 /**
- * What actually enforces one rule file's doctrine, as the file itself should state it.
- *
- * Derived from SURFACES — the union over every doctrine surface carrying that `rule`, because
- * `rule` is many-to-one (`data` covers `./data`, `./data/table`, `./data/virtual`; `mantine` covers
- * `.` and `./connectivity`). Naming only one surface's coverage would understate the rule.
+ * Classify a managed file against the manifest for a sync run.
+ * - missing  : the managed unit is absent on disk → recreate.
+ * - current  : on disk == desired → nothing to do.
+ * - unchanged: on disk matches a KNOWN-SHIPPED rendering of this template, checked three ways (any
+ *              one is sufficient) — but != desired as-is → safe overwrite:
+ *              1. `sha256(current) === manifestHash` — legacy raw-hash path. An existing consumer
+ *                 manifest (written before this fix, or by a still-running older CLI) holds the RAW
+ *                 hash of what was written, not the normalized one; keep matching it directly so an
+ *                 upgrade never mass-classifies a pristine tree as drifted.
+ *                 Residual transitional gap: a manifest written by a pre-1.0.2 CLI holds a raw hash
+ *                 of the exact old bytes, so if the on-disk block was ALSO reformatted by a
+ *                 downstream formatter AND the template body changed cross-version in the same
+ *                 upgrade, none of the three paths above match and it classifies `drifted`, needing
+ *                 one `--force`. Once any sync since writes a normalized entry (path 2/3 or a
+ *                 healed write), the gap is closed for good for that file. Deliberately not solved
+ *                 by keeping a historical per-version ledger — that's a real but bounded tradeoff.
+ *              2. `sha256(normalizeForLedger(current)) === manifestHash` — the ledger proper.
+ *                 `manifestHash` normally holds `sha256(normalizeForLedger(<bytes written at the
+ *                 last sync>))` (see `writeUnit`); normalizing `current` the same way and comparing
+ *                 survives a downstream formatter reformatting the file AND a version bump that
+ *                 changed the template's own words between the sync that wrote this manifest entry
+ *                 and the version being synced now — the argo cross-version false positive.
+ *              3. `normalizeForLedger(current) === normalizeForLedger(desired)` — same-version
+ *                 fallback for when there is no manifest entry to compare against at all (e.g. it
+ *                 was dropped), but the on-disk bytes still match today's rendering modulo
+ *                 formatting noise.
+ * - drifted  : on disk matches NONE of the above (a real, word-level local edit) → skip unless
+ *              --force.
  */
-export declare function coverageFor(rule: RuleName): {
-    guardKinds: string[];
-    pluginRules: string[];
-    advisoryLaws: string[];
-};
-/**
- * The generated block for one rule, verbatim — HTML comments only, one claim per line so a diff
- * points at the claim that changed rather than at a reflowed paragraph.
- *
- * `not guarded` is printed even when empty, and that is the point: a rule file whose block says
- * `not guarded: —` is claiming full coverage, which is a claim someone can check. A block that
- * simply omitted the section would read as "nothing to declare" whether or not anyone had looked
- * (D8 — see docs/CONTROLS-SPEC.md §6 "Honest coverage").
- */
-export declare function coverageBlock(rule: RuleName): string;
-/** The block a rule file currently carries, or null when it has none yet. */
-export declare function readCoverageBlock(text: string): string | null;
-/**
- * `text` with `block` in it — replacing the existing block, or inserted directly below the YAML
- * frontmatter (the rule files' `paths:` header is load-bearing and must stay first).
- */
-export declare function applyCoverageBlock(text: string, block: string): string;
+export declare function classify(state: UnitState, manifestHash: string | undefined): Classification;
+export declare function diffSummary(file: ManagedFile, state: UnitState): string;
+/** Build the render context for a run from the package root + consumer cwd/config. */
+export declare function renderContext(cwd: string): RenderContext;
 /**
- * Reconcile every rule file's coverage block against SURFACES.
- *
- * `'write'` refreshes them; `'check'` is the CI gate. A rule file with NO block yet is REPORTED,
- * never failed — the blocks are inserted by the agent-layer wave that rewrites those files, and a
- * gate that failed before they exist would have to be landed disabled, which is how a gate stays
- * disabled. A block that exists and DISAGREES is a hard failure: that is drift, and drift in a
- * coverage claim is the defect the block was added for.
+ * Read → mutate → write the consumer's package.json, preserving its own indentation and trailing
+ * newline. `mutate` returns false to abort the write (nothing to change). Returns whether a write
+ * happened. Deliberately a JSON round-trip rather than a textual splice: key ORDER is preserved by
+ * `JSON.parse`/`stringify`, and anything fancier would be a formatter this CLI has no business being.
  */
-export declare function reconcileCoverageBlocks(pkgRoot: string, mode: 'write' | 'check'): {
-    failures: string[];
-    notes: string[];
+export declare function patchPackageJson(cwd: string, mutate: (pkg: Record<string, unknown>) => boolean): boolean;
+/** What `reconcileRoots` found — the one roots decision `init` and `sync` both report from. */
+export type RootsState = 
+/** The key was absent and has just been written. */
+{
+    readonly kind: 'wrote';
+    readonly roots: string[];
+}
+/** The key is absent and nothing plausible could be inferred. */
+ | {
+    readonly kind: 'undetectable';
+}
+/** The key is already declared. `unscanned` names inferable roots it does not cover. */
+ | {
+    readonly kind: 'declared';
+    readonly declared: string[];
+    readonly unscanned: string[];
 };
 /**
- * Assert the 11 invariants against the live SURFACES + GUARD_RULES + the shipped agent layer, and
- * (with `--write` / `--check`) reconcile the generated `<!-- basalt:coverage -->` header of every
- * rule file against SURFACES. Returns 0 when all pass; 1 when any fail (console.error each failure).
+ * Read — and when absent and `write` is set, seed — `basalt.roots`.
  *
- * Eleven assertions:
- *  1. Every doctrine spec's guardKinds ⊆ keyof GUARD_RULES.
- *  2. Every doctrine rule (deduped) maps to agent/rules/basalt-{rule}.md on disk.
- *  3. Every doctrine skill (deduped) maps to agent/skills/{skill}/SKILL.md on disk.
- *  4. Every non-#, non-'.' JS-subpath SURFACES key has a package.json exports entry.
- *  5. Every real package.json exports key has a SURFACES entry.
- *  6. Every surface with non-empty forbiddenImports has a globs field.
- *  7. Every headless surface is Mantine-free — via all 3 `forbiddenImports` bans, OR (for
- *     `TOKEN_LAYER_BOUNDARY_SURFACES` members, `./charts`/`./tokens`) exemption, since their
- *     Mantine-free guarantee is covered by the repo-local-only `basalt/token-layer-boundary`
- *     plugin rule instead — this assertion cannot verify that rule's live registration itself (see
- *     the assertion's own comment below for why); basalt's own CI does
- *     (`tests/surfaces-coverage.test.ts`).
- *  8. Every doctrine optionalPeers entry exists in peerDependencies AND peerDependenciesMeta.
- *  9. Every registered oxlint plugin rule (PLUGIN_RULE_ID_LIST) maps to EXACTLY ONE surface's
- *     `pluginRules` — so a new rule cannot ship homeless, and one rule cannot be counted twice as
- *     coverage. Like assertion 7 this reads SURFACES only: whether the plugin really registers
- *     those ids is asserted against the plugin itself in `configs/oxlint-plugin.test.ts`, which a
- *     shipped CLI running from a consumer's node_modules cannot do.
- * 10. Every shipped agent-layer file is inside its line budget, and the six rules are inside the
- *     whole-layer total (`AGENT_LINE_BUDGETS` / `AGENT_RULE_TOTAL_BUDGET`).
- * 11. Every `GUARD_RULES` kind appears on at least one doctrine surface — assertion 9's twin for
- *     the text lane. Without it a kind could ship, be documented as a law in the spec, and be
- *     omitted from every generated coverage header, which is how two wave-6 kinds left
- *     `agent/rules/basalt-controls.md` printing "guard kinds — none" (D8). Unlike 9 this is
- *     one-directional: a kind may legitimately appear on SEVERAL surfaces (`raw-hex` is on
- *     `./charts` and `./tokens`), because a text scan is not partitioned by subpath the way a
- *     plugin rule id is.
+ * Shared by `init` and `sync` because the key going missing is the SAME false green in both: the
+ * built-in `src` default happens to resolve from a package cwd, so `guard-scan` passes, `check-theme`
+ * scans something, and the repo is silently guarding a subset of itself. `init` wrote it and `sync`
+ * did not — which meant the fix reached new scaffolds only, while every existing consumer (the ones
+ * who by definition upgrade rather than scaffold) stayed on the undeclared default.
  *
- * Tooling surfaces are exempt from assertions 1–3 by the discriminant.
- * Synthetic #-keys participate in assertions 1 and 2 but feed assertion 3 only
- * via the deduped skill union (no independent per-#-surface skill row).
+ * A DECLARED value is never overwritten, not even when the layout disagrees with it. `roots` is a
+ * subset by construction in a monorepo — a React-free package deliberately left out is the normal
+ * case, not drift — so a disagreement is reported as one line naming what is not covered, and the
+ * consumer decides. Silently widening someone's deliberate scope would turn an upgrade into an
+ * unplanned lint debt.
  */
-export declare function checkCoverage(flags?: readonly string[]): number;
-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;
+export declare function reconcileRoots(cwd: string, opts: {
+    write: boolean;
+}): RootsState;
+/** The lines `init`/`sync` print for a roots reconciliation. Empty when there is nothing to say. */
+export declare function rootsNotices(state: RootsState): {
+    log: string[];
+    error: string[];
 };
+/** Parse a JSONC document, or null when it does not parse at all. */
+export declare function parseJsonc(text: string): Record<string, unknown> | null;
+/** Outcome of splicing the shipped preset into an `.oxlintrc.json` the consumer already had. */
+export type MergeLintResult = 'added' | 'already' | 'absent' | 'unreadable' | 'has-comments';
 /**
- * Check a consumer repo's basalt integration and print a pass/warn report.
- *
- * With the plugin retired there is exactly ONE version axis — the npm package — so doctor verifies
- * one thing: the basalt-ui resolved in the consumer's node_modules against the version recorded in
- * .basalt/manifest.json at the last init/sync. File-level drift is `sync --check`'s job, not
- * doctor's.
+ * The `extends` entry pointing at the shipped oxlint preset, or null when none does.
  *
- * The checks are numbered in the order they run and print — there is no gap, and the number in a
- * section header below is the number in the report.
- *
- * Hard failures (exit non-zero):
- *   1. .basalt/manifest.json exists (init was run).
- *   2. `basalt-resolves`: basalt-ui resolves from here. Unresolvable used to make checks silently
- *      VANISH from the report (5 checks became 3) while the footer still read "All checks passed".
- *      It is also the moment `bunx basalt-ui` stops using the pinned copy.
- *   6. `guard-scan`: `check-theme` would scan MORE than zero files. `check-theme` already exits 1
- *      on "0 files scanned"; doctor disagreeing with it in the same repo is the bug.
- *   7. `oxlint-preset`: the consumer's `.oxlintrc.json` actually `extends` the shipped preset AND
- *      that path RESOLVES. `init` keeps an existing config, so the framework's whole lint half can
- *      be off with nothing to say so — one repo carried six real violations invisibly across five
- *      minors that way. Matching the string alone reproduced the same false green one layer in: a
- *      well-shaped entry pointing at a path that no longer exists passed this check in the very
- *      tree where oxlint refused to start with `NotFound`.
- *   8. `lefthook-preset`: the repo-root lefthook config's `extends` target resolves. lefthook
- *      merges a MISSING target into zero commands and exits 0 — no error, a clean `lefthook dump`,
- *      and no pre-commit gate. Nothing but a check can see that. Not-extending-at-all is a warning
- *      (a consumer may run their own hooks); extending a path that isn't there is a hard failure.
- *   10. `ai-major-parity`: every workspace package that declares the `ai` package agrees on its
- *      major version. `basalt/ai-sdk-major` (the oxlint plugin rule) cannot catch this — it checks
- *      a linted file's NEAREST package.json, so a lint run scoped to one workspace package only
- *      ever sees that package's own `ai` major and is perfectly happy; the cross-package skew (one
- *      package streaming on `ai@5`, another parsing it on `ai@7`) only a repo-wide manifest walk
- *      can see. Skipped entirely when `cwd` has no `workspaces` field or none of its packages
- *      declare `ai`. A detected skew is exempt-able via `basalt.aiMajorSkewReason` (a non-empty
- *      reason string, not a bare `true`) in the consumer's package.json — an intentional
- *      producer/consumer split neutralized by a transform is a locked decision, not a defect, and
- *      the written reason IS the pin that a permanently-failing guard would otherwise lack. Missing
- *      or invalid (empty/non-string) still hard-fails exactly as if the key were absent.
- *
- * Warnings (non-fatal):
- *   3. The installed node_modules/basalt-ui version matches the manifest's basaltVersion
- *      (a mismatch means the package was upgraded but `sync` never ran — the placed doctrine is
- *      stale).
- *   4. The spacing scale still matches the one stamped into the manifest at the last init/sync
- *      (skipped when there is no manifest to compare against; a neutral pass when this CLI is
- *      demonstrably not the installed package — see the check).
- *   5. The running CLI's own version matches the installed basalt-ui (catches a stale
- *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
- *   9. The icon files `basaltAppPlugin` (basalt-ui/vite) references exist under the app package's
- *      public/ — the package found via `basalt.roots`, not just cwd, so a root-invoked run still
- *      reaches it. Never silently omitted: no plugin call anywhere is a pass that says so, a
- *      plugin call with no public/ beside it is a SKIPPED.
- *   10 (second half). A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the
- *      exemption is stale and can be deleted; an exemption nobody revisits is how a real, later
- *      skew slips through unnoticed.
- *
- * An AMBIGUOUS project (no config here, several workspace packages carrying one) short-circuits
- * before any of them, exactly as `check-theme` does: running the remaining checks against the wrong
- * root buries the one real error under spurious ones.
- *
- * SKIPPED is now a third outcome beside pass/warn/fail and exits non-zero on its own — a check that
- * cannot run is not a check that passed. "Not applicable to this profile" is a pass, not a skip.
- *
- * Returns the exit code: 0 = all good, 1 = one or more hard failures or unrunnable checks.
+ * Returns the ENTRY rather than a boolean because the string alone proves nothing: a consumer that
+ * upgraded (or moved to an isolated linker) keeps a perfectly well-shaped
+ * `./node_modules/basalt-ui/configs/oxlint.json` that resolves to nothing, and oxlint then refuses
+ * to start with `NotFound` while a check built to prove the framework is ON reports green. The
+ * caller resolves this against the config's own directory — see `extendsSeam`.
  */
-export declare function doctor(invocationCwd?: string, flags?: string[]): number;
-/** One row in the `basalt info` output — one per published JS subpath export. */
-export type InfoSubpath = {
-    path: string;
-    description: string;
-    layer: string;
-    rule: string | null;
-    skills: readonly string[];
-    optionalPeers: string[];
+export declare function basaltPresetEntry(entries: unknown): string | null;
+export type LefthookGate = 
+/** No such config file — nothing is wired, and that is a legitimate consumer choice. */
+{
+    readonly kind: 'no-file';
+}
+/** A command runs the guard — the gate exists. */
+ | {
+    readonly kind: 'wired';
+    readonly file: string;
+}
+/** `lefthook dump` merged everything and no command runs the guard — provably no gate. */
+ | {
+    readonly kind: 'absent';
+    readonly file: string;
+}
+/** A config exists but `lefthook dump --format json` could not be run or parsed. */
+ | {
+    readonly kind: 'unreadable';
+    readonly file: string;
 };
-/** The stable JSON shape for `basalt info --json`. */
-export type InfoOutput = {
-    name: string;
-    version: string;
-    subpaths: InfoSubpath[];
-};
-/**
- * Print a human-readable (or JSON) map of the published basalt-ui surface derived from
- * SURFACES + package.json. Every row is live-derived — the subpath list cannot drift.
- *
- * `basalt info`         → human-readable table
- * `basalt info --json`  → stable JSON (InfoOutput shape)
- */
-export declare function info(flags: string[]): number;
-/**
- * Space- and number-normalize the argument list of a legacy color function so the emitted file
- * survives a normal repo's formatter.
- *
- * This is FORMATTING ONLY and deliberately the CLI's single deviation from "print exactly what
- * `buildPaletteCss` returned": `rgba(255,255,255,0.6)` and `rgba(255, 255, 255, 0.6)` are the same
- * colour, the shipped palette emits the first form on the dark side and the second on the light
- * side, and a consumer committing the output ate a lint-ignore entry for the difference. The token
- * VALUES are untouched — nothing here can change what basalt's tokens are.
- *
- * Trailing zeros go the same way and for the same reason: prettier rewrites `0.10` → `0.1`, so the
- * two `rgba(28, 25, 23, 0.10)` alphas in the light shadow tokens were the whole reason the one
- * framework-free consumer still could not lint its committed sheet — `--fix` and `tokens:css
- * --check` disagreed forever, and the lint-ignore entry survived two releases. Only a bare decimal
- * literal is touched (never a `%`, a `var()` or a unit), and `0.10`/`0.1` are the same number.
- *
- * Exported for tests, so the expectation can be computed rather than restated.
- */
-export declare function normalizeColorFunctions(css: string): string;
-/**
- * tokens:css — emit the `--vx-*` stylesheet, optionally retargeted.
- *
- * The escape hatch from installing anything: a static site runs this once (`bunx basalt-ui
- * tokens:css --selector-attribute data-theme --out src/tokens.css`) and consumes basalt's token
- * system as plain CSS, with no package in its dependency tree at all. `basalt-ui/tokens.css` is the
- * same artifact for a consumer that does install; this command exists for the ones that shouldn't
- * have to just to change a selector.
- *
- * It parses flags and calls `buildPaletteCss` for the token VALUES — the CLI and the API must not
- * be able to disagree about what basalt's tokens are. What it adds is strictly file framing for an
- * artifact a consumer COMMITS: the `@generated` header (the guard's skip marker), a trailing
- * newline, and `rgba()` argument spacing. All three were reported by the one framework-free
- * consumer as the reasons the output could not simply be committed.
- */
-export declare function tokensCss(flags: string[], cwd?: string): number;
+export declare function inspectLefthookGate(repoRoot: string): LefthookGate;
 /**
- * fonts:css — emit the shipped `--basalt-font-*` stacks as plain CSS.
- *
- * The typeface half of the framework-free route, which had no supported path at all: `tokens.css`
- * emits no font vars, `styles.css` is the one place the defaults live and a framework-free consumer
- * is told not to import it, and `buildFontsCss` returns `''` unless the caller already knows the
- * stacks. The one non-Mantine consumer lost its font identity entirely and hardcoded the stacks —
- * which the theme guard then flagged as `raw-font-family`.
- *
- * The declarations are READ from the shipped stylesheet rather than restated here, so this command
- * and `basalt-ui/styles.css` can never name different typefaces. Note the fonts themselves are
- * `@fontsource-variable/*` packages: without them the stacks fall through to their own system
- * fallbacks, which is the intended framework-free behaviour.
+ * Splice the shipped preset into an EXISTING `.oxlintrc.json` (`init --merge-lint`). Opt-in, not
+ * automatic: turning the framework on adds real lint debt to previously-clean code (see the
+ * lint-debt notice `init` prints), and that is a decision, not a scaffold step. Prepends the preset
+ * so the consumer's own `extends` entries still win.
  */
-export declare function fontsCss(flags: string[], cwd?: string): number;
+export declare function mergeOxlintExtends(cwd: string, presetPath: string): MergeLintResult;
 /**
- * guard-hook — PreToolUse stdin adapter.
+ * Which shape of consumer a project-scoped command is looking at.
  *
- * 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.
+ * `framework` — the Mantine app the scaffold is for. `tokens-only` — a consumer that took the
+ * `--vx-*` layer and nothing else (rollhook: no Mantine, no manifest, `tokens:css` output). Telling
+ * the second to "run `basalt-ui init`" is the wrong instruction: init scaffolds Mantine rules,
+ * skills and a DESIGN.md it will never read. DECLARED only (`--framework` / `--tokens-only`, or
+ * `"basalt": { "profile": "tokens-only" }`) — never inferred; see {@link declaredProfile}.
  */
-export declare function guardHook(cwd?: string): Promise<number>;
+export type DoctorProfile = 'framework' | 'tokens-only';
+/** Narrows to a string array — shared by `collectWorkspacePackages`'s two `workspaces` shapes. */
+export declare function isStringArray(value: unknown): value is string[];
 /**
  * CLI dispatcher — parses argv (subcommand + flags) and returns the command's exit code. The bin
  * entry is the ONLY caller that translates this to process.exit, so init/sync/checkTheme stay free
@@ -628,6 +715,9 @@ export declare function guardHook(cwd?: string): Promise<number>;
  * The `guard-hook` subcommand is async (reads stdin); all others are synchronous.
  */
 export declare function run(argv: string[], cwd?: string): number | Promise<number>;
-export { managedFiles, MANIFEST_PATH, normalizeForLedger, RULE_NAMES, SKILL_NAMES };
-export type { ManagedFile, Manifest, SyncOptions, DoctorResult };
+export { RULE_NAMES, SKILL_NAMES };
+export type { ManagedFile };
+export { checkTheme, doctor, guardHook, init, sync, fontsCss, normalizeColorFunctions, tokensCss };
+export type { SyncOptions } from './sync.js';
+export type { DoctorResult } from './doctor.js';
 //# sourceMappingURL=index.d.ts.map