claude-use 4.4.0 → 5.0.0

package/dist/types/resolve/flatten.d.ts

@@ -0,0 +1,13 @@
+import type { CompiledRule, FlattenedCascade, Layer } from "./types";
+/**
+ * Cascade phase one: walk the ordered layer sequence once, spreading each layer's `categories` and `entries` over an accumulator. A later layer's value for the exact same category name, or the exact same key, replaces an earlier layer's value for that identical key. No path-specificity reasoning happens here — that is phase two's job.
+ *
+ * The entries accumulator is keyed by the **canonical** pattern, not the raw written key, so two differently-spelled but equivalent keys (`history/projects/~/work/x` and `history/projects/$HOME/work/x` after expansion) collapse into one rule here instead of racing as two separate candidates in phase two. Every surviving rule carries its own `{ layer, ordinal }`, which is what lets phase two tell a same-layer conflict from a cross-layer one without a separate provenance side-table.
+ *
+ * A key written under the `secret/` prefix is rejected outright with its own diagnostic and contributes no rule at all: `secret` is the one category no layer may open, and a deliberate attempt to name a secret path deserves a clearer error than the silent neutralisation the resolve-time floor check applies to a glob that reaches one incidentally.
+ */
+export declare function flattenLayers(layers: readonly Layer[], options: Readonly<{
+    home: string;
+}>): FlattenedCascade;
+/** Every compiled rule that matches `relPath`, ranked most-specific first. */
+export declare function matchingRules(flattened: FlattenedCascade, relPath: string): CompiledRule[];

package/dist/types/resolve/match.d.ts

@@ -0,0 +1,58 @@
+import { type CategoryName } from "../config/schema";
+import { CliError } from "../cliError";
+import type { CompiledRule } from "./types";
+/** True when `pattern` contains no glob metacharacter, so it can only ever match one literal path. */
+export declare function isExactPattern(pattern: string): boolean;
+/** The pattern's leading run of characters before the first glob metacharacter — the part that is definitely literal. */
+export declare function literalPrefixOf(pattern: string): string;
+/** Normalises a relative path fragment: collapses repeated slashes, drops `./` segments, and strips a trailing slash. Deliberately case-preserving and case-sensitive. */
+export declare function normaliseRelative(fragment: string): string;
+/** The outcome of canonicalising one entries key. */
+export interface CanonicalKey {
+    readonly declaredCategory: CategoryName;
+    /** The pattern with its category prefix stripped, relative to `~/.claude`, with any `history/projects/` path fragment already encoded. */
+    readonly canonicalPattern: string;
+    /** The `history/projects/` path fragment as written, before encoding — retained so ambiguity reporting can name what the author actually typed. */
+    readonly projectFragment?: string;
+}
+/** Raised when an entries key cannot be canonicalised. Carries the offending key so the diagnostic can name it. */
+export declare class EntryKeyError extends CliError {
+    readonly key: string;
+    readonly reason: "unrooted-project-path" | "malformed";
+    constructor(key: string, message: string, reason: "unrooted-project-path" | "malformed");
+}
+/**
+ * Canonicalises one entries key into a pattern over paths relative to `~/.claude`.
+ *
+ * Every key is `<category>/<real-relative-path>`, so the category prefix is stripped and the remainder kept as written — with one deliberately narrow exception. Anything written after the literal `history/projects/` prefix is a real absolute working directory (optionally globbed), not a literal child directory name, because that directory's only real children are Claude Code's own encoded names and there is nothing else meaningful to reference there. Those fragments get `~`-expanded and forward-encoded; every other key in the whole design is a plain literal path or an ordinary glob over one, matched exactly as written.
+ */
+export declare function canonicaliseEntryKey(key: string, options: Readonly<{
+    home: string;
+}>): CanonicalKey;
+/**
+ * Compiles a canonical pattern into a matcher that covers the pattern itself *and* everything beneath it, so a rule written as `knowledge/skills` decides `skills/commit/SKILL.md` too. Two picomatch matchers are needed rather than one: `skills/**` alone covers the subtree but `projects/*` does not match `projects/x/y`, and `projects/*` alone does not cover the files inside a matched project directory.
+ *
+ * Matching is deliberately case-sensitive (`nocase: false`) whatever the host filesystem does, so the same config behaves identically on a case-insensitive APFS volume and a case-sensitive one. `dot: true` so a glob can match a leading-dot entry.
+ */
+export declare function compileMatcher(canonicalPattern: string): (relPath: string) => boolean;
+/**
+ * True when some path *underneath* `dir` could match `canonicalPattern`, whether or not such a path exists today.
+ *
+ * This is what makes a conditional rule force materialisation: a directory Claude Code will write new children into cannot be symlinked wholesale if a rule might have something to say about those not-yet-existing children. Answering that from the pattern's structure rather than from the current file listing is the whole point — asking "does any existing child match" would pass the obvious test and fail the real one.
+ */
+export declare function patternCouldReachUnder(canonicalPattern: string, dir: string): boolean;
+/**
+ * Ranks two compiled rules that both match the same path. A positive result means `a` wins.
+ *
+ * The order, exactly:
+ *
+ * 1. **Different layers — the later layer wins, period.** This rank sits deliberately *above* exactness. Ranking exactness first would let an untrusted committed `.claude-use.json`'s exact key beat your own later, personal glob override, breaking the design's stated trust property that a directory-scoped local rule can only ever tighten what a committed file opened, never the reverse. Nothing in the design asserts that an earlier exact key beats a later glob, so nothing is lost by closing that hole.
+ * 2. Same layer: an exact literal beats a glob.
+ * 3. Same layer: the longer literal prefix wins.
+ * 4. Same layer: more path segments wins, which separates a one-wildcard pattern from a two-wildcard one at the same depth.
+ * 5. Same layer: the later ordinal — source order within the file — wins.
+ * 6. Canonical pattern, compared as a string, as a last-resort determinism guarantee.
+ *
+ * The order must be **total**: returning 0 for two distinct rules would make the winner depend on iteration order, which tests would only catch intermittently.
+ */
+export declare function compareSpecificity(a: CompiledRule, b: CompiledRule): number;

package/dist/types/resolve/pipeline.d.ts

@@ -0,0 +1,30 @@
+import { type ClassifyResult } from "../config/classify";
+import type { CategoryClassification, CategoryClassificationOverlay } from "../config/schema";
+import { type ResolveAllResult } from "./decide";
+import { type FarmPlan } from "./plan";
+import { type AssembledCascade, type CascadeInput } from "./walk";
+import type { Diagnostic, EntryFacts, FlattenedCascade } from "./types";
+/** Everything one launch needs resolved, in one call. */
+export interface ResolveDecisionsInput {
+    readonly facts: EntryFacts;
+    readonly cascade: CascadeInput;
+    readonly classification: {
+        readonly defaults: CategoryClassification;
+        readonly overlay?: CategoryClassificationOverlay;
+    };
+}
+/** The fully resolved state of one launch: the layers that composed it, every entry's decision, the farm layout, and everything worth reporting. */
+export interface ResolvedState {
+    readonly assembled: AssembledCascade;
+    readonly flattened: FlattenedCascade;
+    readonly classification: ClassifyResult;
+    readonly decisions: ResolveAllResult["decisions"];
+    readonly farm: FarmPlan;
+    readonly diagnostics: readonly Diagnostic[];
+}
+/** The top-level `~/.claude` entry names present in a fact manifest, in sorted order. */
+export declare function topLevelNames(facts: EntryFacts): string[];
+/**
+ * Runs the whole pipeline for one launch: assemble the ordered layer sequence, flatten it, classify the real `~/.claude` entries, decide every path, and plan the resulting farm.
+ */
+export declare function resolveDecisions(input: ResolveDecisionsInput): ResolvedState;

package/dist/types/resolve/plan.d.ts

@@ -0,0 +1,57 @@
+import type { Decision, EntryFacts, FlattenedCascade } from "./types";
+/** What the farm should contain at one path. */
+type FarmPlanEntry = 
+/** A single symlink standing in for this whole path — always absolute, always under `claudeHome`. */
+{
+    readonly kind: "link";
+    readonly rel: string;
+    readonly target: string;
+}
+/** A real local directory the farm builds itself, because the decision beneath it is not uniform or because a conditional rule could touch it. */
+ | {
+    readonly kind: "materialise";
+    readonly rel: string;
+    readonly reason: MaterialiseReason;
+}
+/** Nothing at all in the farm for this path. */
+ | {
+    readonly kind: "omit";
+    readonly rel: string;
+};
+/** Why a directory has to be built rather than symlinked. */
+type MaterialiseReason = 
+/** Descendants of this directory resolve to different decisions, so a single symlink cannot express the outcome. */
+"split-decision"
+/** A conditional entries rule could match something under this directory, so the decision has to stay live. */
+ | "conditional-rule";
+/** The full farm plan for one resolved cascade. */
+export interface FarmPlan {
+    /** Every planned path, parents before children. */
+    readonly entries: readonly FarmPlanEntry[];
+    /** Directories the farm builds itself, in plan order. Written into the farm manifest so the next resync can tell them apart from directories Claude Code created. */
+    readonly materialised: readonly string[];
+    readonly links: readonly {
+        readonly rel: string;
+        readonly target: string;
+    }[];
+}
+/** Everything `planFarm` needs, all of it already resolved. */
+export interface PlanFarmParams {
+    readonly facts: EntryFacts;
+    readonly decisions: ReadonlyMap<string, Decision>;
+    readonly flattened: FlattenedCascade;
+}
+/** Indexes the fact manifest by parent path, so the plan can descend the tree without touching a filesystem. */
+export declare function buildChildIndex(facts: EntryFacts): Map<string, string[]>;
+/**
+ * Turns a resolved set of decisions into a concrete farm layout.
+ *
+ * A directory becomes one symlink when the decision is uniform across its whole subtree, which is what keeps the common resync cheap — a few dozen top-level symlinks rather than a rebuilt tree. It is materialised, and recursed into, when either:
+ *
+ * - its subtree's decisions genuinely disagree, so no single symlink can express the outcome; or
+ * - **any** conditional entries rule could reach something under it, even when today's evaluation happens to be uniform. This second case is the one a naive "is the decision uniform right now" check gets wrong: a symlinked directory freezes the decision for every file Claude Code creates *after* the resync, so a `newerThan` condition meant to share recent sessions would never see a session written five minutes from now. The bug only surfaces for files that do not exist yet, which is precisely why the check has to be structural rather than observational.
+ *
+ * Every symlink target is `<claudeHome>/<rel>`, unconditionally. That matters for the entries inside a materialised directory that are themselves relative symlinks escaping `~/.claude` (a real condition, not a hypothetical one — a skills directory linked out to a separate dotfiles repository, for instance). Copying such a link's own relative target verbatim would resolve to a different place from the farm's own depth, and copying its resolved absolute target would pin the farm to wherever that link pointed at resync time. Linking at `<claudeHome>/<rel>` and letting the OS follow the remaining hops from there is the only form that stays correct.
+ */
+export declare function planFarm(params: PlanFarmParams): FarmPlan;
+export {};

package/dist/types/resolve/projects.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Forward-only encoding of a real working directory into the single directory name Claude Code gives it under `~/.claude/projects/`.
+ *
+ * The encoding collapses the *entire* non-alphanumeric character class to `-`, not just the path separator: `.`, `_`, ` `, `@`, and `/` all become `-`, while letters and digits pass through with their case preserved. This was confirmed against a real installation's project directories, not assumed from the one `/`-becomes-`-` sample the README quotes.
+ *
+ * The encoding is therefore many-to-one: `~/work/clients/acme`, `~/work/clients-acme`, and `~/work-clients/acme` all produce the identical name. That makes it impossible to invert, so this module never tries: there is no decode function here, and `projects.test.ts` asserts the module's export list to keep it that way. Only the forward direction — real path to encoded name — is ever computed, and `detectEncodingAmbiguity` reports when a pattern's encoded form could plausibly correspond to more than one real path rather than resolving it silently.
+ */
+import { CliError } from "../cliError";
+/** Encodes one real, fully-literal path into the directory name Claude Code would give it under `~/.claude/projects/`. */
+export declare function encodeProjectPath(realPath: string): string;
+/** One piece of a pattern split on its wildcard tokens: either a literal run to encode, or a wildcard to leave alone. */
+export interface PatternFragment {
+    readonly kind: "literal" | "wildcard";
+    readonly text: string;
+}
+/**
+ * Splits a pattern into alternating literal runs and wildcard tokens. Encoding the whole pattern string in one pass would turn `*` into `-` along with everything else, silently converting a glob into a literal that matches nothing.
+ */
+export declare function splitOnWildcards(pattern: string): PatternFragment[];
+/** Raised when a `history/projects/` pattern's path fragment is neither `~`-rooted nor absolute, so there is no real path to encode. */
+export declare class UnrootedProjectPathError extends CliError {
+    readonly fragment: string;
+    constructor(fragment: string);
+}
+/** Expands a leading `~` to the given home directory. A `~` anywhere else in the path is an ordinary character. */
+export declare function expandHome(fragment: string, home: string): string;
+/**
+ * Encodes a possibly-globbed real path into a pattern that matches Claude Code's own `~/.claude/projects/` directory names.
+ *
+ * Order matters and is fixed: expand `~` to the real home first (encoding `~` would turn it into `-` and lose the reference), reject anything not home-or-root-rooted, then split on wildcard tokens and encode only the literal runs.
+ */
+export declare function encodeProjectPattern(fragment: string, options: Readonly<{
+    home: string;
+}>): string;
+/** Why a pattern's encoded form might not identify the real path its author had in mind. */
+export type EncodingAmbiguityReason = 
+/** The literal portion contains a character other than `/` that encodes to `-`, so a sibling path differing only in that character encodes identically. */
+"lossy-characters"
+/** Two different patterns in the same configuration encode to the identical form. */
+ | "collides-with-sibling-pattern";
+/** One reported ambiguity in a `history/projects/` pattern. */
+export interface EncodingAmbiguity {
+    readonly fragment: string;
+    readonly encoded: string;
+    readonly reason: EncodingAmbiguityReason;
+    readonly detail: string;
+}
+/**
+ * Reports, for a set of `history/projects/` path fragments, every case where the encoded form could plausibly correspond to more than one real path.
+ *
+ * Two signals, both actionable:
+ *
+ * - `lossy-characters` — the fragment's literal portion contains a character besides `/` that encodes to `-`. Because encoding is many-to-one, a sibling path with that character replaced by a separator (or vice versa) produces the identical name, so this pattern may match a directory belonging to a different real path.
+ * - `collides-with-sibling-pattern` — two distinct fragments in the same configuration encode identically, which proves a collision outright rather than merely suggesting one.
+ *
+ * When `existingNames` is supplied, `detail` also names how many real project directories the encoded form currently matches, so the report says what actually happened rather than only what could.
+ */
+export declare function detectEncodingAmbiguity(fragments: readonly string[], options: {
+    home: string;
+    existingNames?: readonly string[];
+}): EncodingAmbiguity[];

package/dist/types/resolve/reconcile.d.ts

@@ -0,0 +1,80 @@
+import type { Diagnostic } from "./types";
+/** The manifest the farm builder writes into each scratch tree before the atomic swap. */
+export interface FarmManifest {
+    readonly version: 1;
+    readonly builtAtMs: number;
+    readonly identity: string;
+    readonly configProfile?: string;
+    readonly cwd: string;
+    readonly claudeHome: string;
+    /** Directories the previous resync built itself. Without this list, a directory the farm materialised and a directory Claude Code created are indistinguishable on disk — both are real, both contain real children. */
+    readonly materialised: readonly string[];
+    readonly links: readonly {
+        readonly rel: string;
+        readonly target: string;
+    }[];
+}
+/** One node of a directory listing, relative to the tree's own root. */
+export interface ListingEntry {
+    /** Path relative to the tree root, forward-slash separated. */
+    readonly rel: string;
+    readonly kind: "dir" | "file" | "symlink";
+    /** A content hash for a file, used to recognise data that has already been adopted. Absent for directories and symlinks. */
+    readonly contentHash?: string;
+}
+/** What to do about one path found in the old farm. */
+export type ReconcileAction = 
+/** New data Claude Code wrote that the canonical tree does not have. Copy it to `to`. */
+{
+    readonly kind: "adopt";
+    readonly rel: string;
+    readonly reason: "absent-from-canonical";
+}
+/** New data whose canonical counterpart exists but differs. The canonical copy is authoritative; the farm copy is preserved alongside it for the user to reconcile. */
+ | {
+    readonly kind: "adopt-conflict";
+    readonly rel: string;
+}
+/** Nothing to do, with the reason recorded so `claude-use check` can explain a no-op. */
+ | {
+    readonly kind: "skip";
+    readonly rel: string;
+    readonly reason: SkipReason;
+};
+/** Why a path in the old farm needs no action. */
+type SkipReason = 
+/** A symlink the previous resync placed. It is a view of the canonical tree, so there is nothing to write back. */
+"is-symlink"
+/** A directory the previous resync materialised. Not new data itself; its children are examined individually. */
+ | "tracked-materialised-dir"
+/** Real data whose canonical counterpart already holds identical content — already adopted, possibly by an earlier run that then crashed before the swap. */
+ | "identical-content";
+/** The result of planning a reconciliation pass. */
+export interface ReconciliationPlan {
+    readonly actions: readonly ReconcileAction[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** True when the manifest was missing or unusable and every real directory in the farm was treated as materialised. */
+    readonly conservative: boolean;
+}
+/** Everything the reconciliation planner reads. It performs no I/O of its own — the launcher executes the actions it returns. */
+export interface ReconcileParams {
+    /** The previous resync's manifest, or undefined when it is missing or failed to parse. */
+    readonly manifest?: FarmManifest;
+    /** A flat listing of the old, still-live farm. */
+    readonly farmListing: readonly ListingEntry[];
+    /** A flat listing of the canonical `~/.claude`. */
+    readonly canonicalListing: readonly ListingEntry[];
+}
+/**
+ * Plans the write-through reconciliation pass that runs before each resync builds its new scratch tree.
+ *
+ * A materialised directory stops being a live view of `~/.claude` and becomes a locally-built directory of symlinks frozen at resync time. Anything Claude Code writes into it afterwards — a brand-new project subdirectory, a new session file inside an existing one — lands as a real, untracked child: invisible to every other identity, and liable to be read as stale scaffolding and pruned by a later resync. This pass finds that data and copies it back into the canonical `~/.claude`, where it belongs, before anything else happens.
+ *
+ * The manifest is what makes this possible at all. A directory the farm materialised and a directory Claude Code created look identical on disk, so without the previous resync's own record of what it built, there is no way to tell the two apart. When the manifest is missing or unreadable, the pass falls back to **conservative mode** — every real directory in the farm is treated as materialised, so every real child anywhere becomes an adopt candidate — and reports it. That is deliberately over-eager rather than a silent no-op: over-adopting copies data into the place it was always meant to live, while under-adopting loses it.
+ *
+ * The pass is deliberately independent of the *new* resolved state. A directory whose new decision is `omit`, or one collapsing back from materialised to a plain symlink, still gets reconciled first — those are precisely the cases where the data would otherwise be discarded, which is the whole reason this exists.
+ *
+ * It is also idempotent: re-running against the same old farm after a crash mid-resync produces only `skip("identical-content")` for anything the interrupted run already copied across.
+ */
+export declare function planReconciliation(params: ReconcileParams): ReconciliationPlan;
+export {};

package/dist/types/resolve/types.d.ts

@@ -0,0 +1,159 @@
+import type { CategoryMap, CategoryName, Entries, LaunchFlags, OverridableCategory, WhenCondition } from "../config/schema";
+/** A layer's index in the assembled cascade. Strictly ascending in composition order: a higher id was composed later and therefore wins on the comparator's first rank. */
+export type LayerId = number;
+/** Where a cascade layer came from. Purely descriptive — precedence is carried by `LayerId`, never by kind. */
+type LayerKind = "global-config" | "config-profile" | "directory-rule" | "portable" | "portable-local" | "cli-override";
+/** One composable layer of the cascade: its own category toggles and entries overrides, plus the entries key order captured at load time. */
+export interface Layer {
+    readonly id: LayerId;
+    readonly kind: LayerKind;
+    /** Human-readable origin (a file path, or a profile name) used by `claude-use check` to explain a decision. */
+    readonly source: string;
+    readonly categories?: CategoryMap;
+    readonly entries?: Entries;
+    /** The entries object's own key insertion order, from `src/config/load.ts`. Falls back to `Object.keys(entries)` when absent. */
+    readonly entryOrder?: readonly string[];
+    readonly launch?: LaunchFlags;
+}
+/** Facts about one entry under `~/.claude`, relative to `~/.claude` itself. */
+export interface EntryFact {
+    /** Path relative to `~/.claude`, forward-slash separated, never leading or trailing slash. */
+    readonly relPath: string;
+    readonly isDirectory: boolean;
+    /** True when the entry is itself a symlink (including the relative, tree-escaping symlinks that already exist inside a real `~/.claude`). */
+    readonly isSymlink: boolean;
+    /** The entry's own mtime. */
+    readonly mtimeMs: number;
+    /** The most recent mtime anywhere in this entry's subtree — its own mtime for a plain file. A directory-scoped `newerThan` must read this, never the directory's own inode mtime, which does not change when a file three levels down is rewritten. */
+    readonly latestMtimeMs: number;
+    /** The entry's own size. */
+    readonly sizeBytes: number;
+    /** The recursive total size of this entry's subtree — its own size for a plain file. A directory-scoped `maxSizeBytes` must read this, never the directory's own ~4KB inode size. */
+    readonly totalSizeBytes: number;
+}
+/**
+ * Every fact the resolver needs, injected rather than read. Nothing in `src/resolve/` ever touches a real filesystem, git repository, clock, or environment: something else builds this structure and hands it over, which is what makes the whole resolver unit-testable with fake mtimes, a fake branch, and a fake environment.
+ */
+export interface EntryFacts {
+    readonly nowMs: number;
+    /** The real home directory, used to expand `~` in `history/projects/` patterns. */
+    readonly home: string;
+    /** The canonical `~/.claude` directory every relative path in `entries` is relative to. */
+    readonly claudeHome: string;
+    /** The working directory the cascade was resolved for. */
+    readonly cwd: string;
+    /** The git branch checked out at `cwd`, or undefined when `cwd` is not in a repository. */
+    readonly branch?: string;
+    /** True when `cwd`'s repository is in detached-HEAD state, in which case no `branch` condition can match. */
+    readonly branchDetached?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    /** Every entry under `~/.claude`, keyed by its path relative to `~/.claude`. Directories appear alongside their descendants. */
+    readonly entries: ReadonlyMap<string, EntryFact>;
+}
+/** A single entries override, compiled into the form the resolver actually matches against. */
+export interface CompiledRule {
+    /** The key exactly as written in its source file, for diagnostics. */
+    readonly rawKey: string;
+    /** The category prefix the key declared. Cross-checked against the real classification of every path it matches. */
+    readonly declaredCategory: CategoryName;
+    /** The key with its category prefix stripped and (under `history/projects/`) its path fragment encoded — a pattern over paths relative to `~/.claude`. Two differently-spelled but equivalent keys share one canonical pattern and therefore collapse to one rule. */
+    readonly canonicalPattern: string;
+    readonly value: boolean;
+    readonly when?: WhenCondition;
+    readonly layer: LayerId;
+    /** The key's position within its own layer's entries object, used only by the comparator's final same-layer tie-break. */
+    readonly ordinal: number;
+    /** True when the canonical pattern contains no glob metacharacter. */
+    readonly isExact: boolean;
+    /** The pattern's leading run of literal (non-wildcard) characters. */
+    readonly literalPrefix: string;
+    /** How many `/`-separated segments the canonical pattern has. */
+    readonly segmentCount: number;
+    /** Matches the pattern itself and everything beneath it, so a rule on `skills` covers `skills/commit/SKILL.md`. */
+    readonly matches: (relPath: string) => boolean;
+}
+/** How a decision was reached, for `claude-use check`'s "which layer decided this" output. */
+type DecisionVia = 
+/** The unconditional pre-cascade floor: the path's real classification is `secret`. */
+"secret-floor"
+/** Nothing in the classification map recognises the path's top-level entry. */
+ | "unclassified"
+/** An entries rule matched and its condition (if any) held. */
+ | "entry-rule"
+/** No entries rule survived; a layer's category toggle decided it. */
+ | "category-override"
+/** No entries rule and no category toggle; the shipped default for the category decided it. */
+ | "category-default";
+/** One entry's resolved sharing decision plus the reasoning behind it. */
+export interface Decision {
+    readonly relPath: string;
+    readonly shared: boolean;
+    readonly via: DecisionVia;
+    readonly category: CategoryName | null;
+    /** The winning entries rule, when `via` is "entry-rule". */
+    readonly rule?: CompiledRule;
+    /** Rules that matched but whose `when` condition failed, in descending specificity — each was eliminated and resolution continued to the next candidate. */
+    readonly eliminated?: readonly EliminatedRule[];
+}
+/** A candidate rule that matched the path but was eliminated because its `when` condition did not hold. */
+export interface EliminatedRule {
+    readonly rule: CompiledRule;
+    readonly failed: readonly string[];
+}
+/** Every diagnostic the resolver can raise. Codes are stable strings so `claude-use check` and tests can assert on them. */
+type DiagnosticCode = 
+/** A profile's `extends` graph contains a cycle. */
+"EXTENDS_CYCLE"
+/** An `extends` entry names a profile that does not exist. */
+ | "MISSING_PROFILE"
+/** An entries key was written under the `secret/` prefix. Rejected at compile time — `secret` can never be overridden by any layer. */
+ | "SECRET_ENTRY_KEY"
+/** An entries key under some other prefix matched a path whose real classification is `secret`. Neutralised at resolve time by the floor check. */
+ | "SECRET_PATH_NEUTRALISED"
+/** An entries key's declared category prefix disagrees with the real classification of a path it matched. */
+ | "CATEGORY_PREFIX_MISMATCH"
+/** An entries key is not of the form `<category>/<path>`. The schema rejects these at parse time; this fires only for a layer built in code. */
+ | "MALFORMED_ENTRY_KEY"
+/** An earlier layer's exact key lost to a later layer's glob. Correct per the comparator, but worth surfacing rather than resolving silently. */
+ | "EXACT_ENTRY_OVERRIDDEN_BY_LATER_GLOB"
+/** A `history/projects/` pattern's encoded form could plausibly correspond to more than one real path. */
+ | "AMBIGUOUS_PROJECT_ENCODING"
+/** A `history/projects/` key's path fragment is neither home-rooted nor absolute, so it cannot be encoded. */
+ | "UNROOTED_PROJECT_PATH"
+/** A `~/.claude` entry nothing in the classification map recognises. */
+ | "UNCLASSIFIED_ENTRY"
+/** An empty `when: {}` object, which is vacuously true and therefore has no effect. */
+ | "EMPTY_WHEN"
+/** The previous farm's manifest is missing or unreadable, so reconciliation ran in conservative mode. */
+ | "FARM_MANIFEST_MISSING"
+/** A file Claude Code wrote into a materialised farm directory differs from the canonical copy of the same path. */
+ | "RECONCILE_CONFLICT"
+/** Reconciliation proposed adopting a path whose real classification is `secret`. Refused: the secret floor applies to data moving into `~/.claude` exactly as it applies to data moving out. */
+ | "RECONCILE_SECRET_BLOCKED"
+/** A previous launch was interrupted mid-swap and this launch completed or undid the half-finished work. */
+ | "FARM_SWAP_RECOVERED"
+/** A superseded farm could not be discarded because it still held data the new farm has its own entry for, so it was left on disk for the user to look at. */
+ | "FARM_PREVIOUS_RETAINED";
+/** Severity of a diagnostic. An `error` means a configuration layer asked for something the tool refused to do. */
+type DiagnosticSeverity = "error" | "warning" | "info";
+/** One structured diagnostic. */
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    /** The config key, profile name, or entry path the diagnostic concerns. */
+    readonly subject?: string;
+    /** The layer that raised it, when the diagnostic is attributable to one. */
+    readonly layer?: LayerId;
+}
+/** The flattened result of cascade phase one. */
+export interface FlattenedCascade {
+    /** The last value each overridable category was set to across every layer. Categories no layer touched are absent. */
+    readonly categories: ReadonlyMap<OverridableCategory, boolean>;
+    /** One compiled rule per canonical pattern — later layers having already overwritten earlier ones for identical patterns. */
+    readonly rules: ReadonlyMap<string, CompiledRule>;
+    /** Launch flags, last layer wins per field. */
+    readonly launch: LaunchFlags;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export {};

package/dist/types/resolve/walk.d.ts

@@ -0,0 +1,85 @@
+import type { DirectoryRule, GlobalConfig, PortableConfig } from "../config/schema";
+import { type ProfileLoader } from "./extends";
+import type { Diagnostic, Layer } from "./types";
+/** Injected predicate answering whether a directory can be read, so the walk stays pure. */
+export type ReadablePredicate = (dir: string) => boolean;
+/** Options for the upward directory walk. */
+export interface WalkOptions {
+    /** The user's home directory, the walk's default stopping point. */
+    readonly home: string;
+    /** Where to stop walking upward, inclusive. Defaults to `home`, and is what `walkUpLimit` in the global config sets. */
+    readonly limit?: string;
+    /** Answers whether a directory is readable. A directory that is not stops the walk there rather than failing the launch. */
+    readonly isReadable?: ReadablePredicate;
+}
+/**
+ * Collects `cwd` and every ancestor of it, shallowest-first, the way Claude Code itself resolves nested `CLAUDE.md` files.
+ *
+ * The walk stops at (and includes) the limit directory — `$HOME` by default — or at the filesystem root when `cwd` is not beneath the limit at all. An ancestor that cannot be read stops the walk there rather than failing the launch: a directory you cannot read cannot carry a config file you were meant to obey.
+ *
+ * `cwd` is expected to already be a real path; resolving symlinks is the caller's job, so this stays free of filesystem access.
+ */
+export declare function walkDirectoryAncestors(cwd: string, options: WalkOptions): string[];
+/** The up-to-three configuration sources that can apply at one directory level. */
+export interface DirectoryLevelSources {
+    readonly dir: string;
+    /** The committed, team-shared `.claude-use.json` at this level. */
+    readonly portable?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** Every rule in this user's own `~/.claude-use/directory-rules.json` whose path is exactly this level, in file order. */
+    readonly rules?: readonly {
+        readonly rule: DirectoryRule;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    }[];
+    /** The gitignored `.claude-use.local.json` at this level. */
+    readonly portableLocal?: {
+        readonly config: PortableConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+}
+/** Everything needed to assemble the full ordered layer sequence, all of it already loaded by the caller. */
+export interface CascadeInput {
+    readonly home: string;
+    /** The user-global `~/.claude-use/config.json`, the least-specific layer above the shipped defaults. */
+    readonly globalConfig?: {
+        readonly config: GlobalConfig;
+        readonly entryOrder?: readonly string[];
+        readonly filepath: string;
+    };
+    /** The configuration profile chosen by the caller's own precedence rules: explicit flag, then the active identity's default, then the global default. */
+    readonly baseConfigProfile?: string;
+    readonly loadProfile: ProfileLoader;
+    /** Directory levels, shallowest-first, as produced by `walkDirectoryAncestors`. */
+    readonly levels?: readonly DirectoryLevelSources[];
+    /** One-off overrides from the command line or environment, composed last so they beat everything. */
+    readonly cliOverride?: {
+        readonly categories?: Layer["categories"];
+        readonly entries?: Layer["entries"];
+        readonly entryOrder?: readonly string[];
+        readonly launch?: Layer["launch"];
+    };
+}
+/** The assembled cascade: an ordered layer sequence plus what the walk itself decided. */
+export interface AssembledCascade {
+    readonly layers: readonly Layer[];
+    readonly diagnostics: readonly Diagnostic[];
+    /** The deepest directory-level `identity` pin encountered, which the launcher uses as a safety net beneath an explicit `@name`. */
+    readonly identityPin?: string;
+    /** The deepest directory-level `configProfile` selection encountered, which is what `claude-use configure` treats as the active profile for a path. */
+    readonly directoryConfigProfile?: string;
+}
+/**
+ * Assembles the full ordered layer sequence.
+ *
+ * Order is: the user-global config, then the base configuration profile's own `extends` chain, then every directory level shallowest-to-deepest, then one-off command-line overrides.
+ *
+ * Within one directory level, up to three sources fold most-personal-last: the committed `.claude-use.json` (team-shared), then this user's own `directory-rules.json` entries for that exact path, then `.claude-use.local.json` (this clone, this user, never committed). That three-source fold happens once per level, and the whole shallowest-to-deepest walk is one continuous sequence through those folded levels — a deeper level's three-source result composes on top of a shallower level's, never gathered per-source across the whole tree first.
+ *
+ * A level source that names a `configProfile` composes that profile's whole chain in *before* its own inline overrides, so the source reads as "everything that profile says, plus what is additionally true this far down the tree" rather than swapping the base profile out wholesale.
+ */
+export declare function assembleCascade(input: CascadeInput): AssembledCascade;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-use",
-  "version": "4.4.0",
+  "version": "5.0.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "Apache-2.0",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",
@@ -24,7 +24,10 @@
     "claude-use": "dist/cli.cjs"
   },
   "files": [
-    "dist/cli.cjs"
+    "dist/cli.cjs",
+    "dist/index.mjs",
+    "dist/index.cjs",
+    "dist/types"
   ],
   "scripts": {
     "prepare": "husky && node scripts/build.mts --bundle-only",
@@ -77,5 +80,16 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.0",
     "vitest": "^4.1.11"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
   }
 }