@dsh-cc/settings-cascade 0.5.0

package/lib/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `@dsh-cc/settings-cascade`.
+ * @module @dsh-cc/settings-cascade/invariant
+ */
+const PACKAGE_NAME = '@dsh-cc/settings-cascade';
+/** Cordis companion plugin name. */
+export const name = 'settings-cascade-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this provider's contracts are the cross-file merge
+ * and policy first-source-wins — composition logic proven by package tests;
+ * the in-process commit relation is owned by `@deepseek-ai/dsh-settings`.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,0BAA0B,CAAA;AAE/C,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,4BAA4B,CAAA;AAChD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;;GAIG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/lib/local-root.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Local-settings directory resolution: Claude Code reads
+ * `.claude/settings.local.json` from the git **main checkout root** when the
+ * session starts inside a linked worktree, or from the git toplevel when it
+ * starts in a subdirectory. This module computes that directory without
+ * touching the session cwd or git working tree. Git probes and `stat` are read-only.
+ *
+ * The linked-worktree detector and canonicalisation mirror the TUI project
+ * identity code in `packages/ui/tui/src/project.ts` (`isLinkedWorktree`,
+ * `canonical`) — see the comment there pointing back here. Keep the two in
+ * sync; they must not drift.
+ *
+ * Node builtins only: this file is imported through the
+ * `@dsh-cc/settings-cascade/local-root` subpath by packages that must
+ * not pull in cordis or the settings runtime.
+ *
+ * @module @dsh-cc/settings-cascade/local-root
+ */
+/** A successful synchronous git invocation. */
+export interface LocalRootExecResult {
+    stdout: string;
+}
+/**
+ * Run one git argv in `cwd`, synchronously. Returns undefined on spawn
+ * failure, non-zero exit, or timeout. Injectable so tests script the git
+ * conversation; the default spawns real `git`.
+ */
+export type LocalRootExec = (argv: readonly string[], cwd: string) => LocalRootExecResult | undefined;
+/** Injectable environment for {@link resolveLocalSettingsDir} (tests only). */
+export interface LocalRootDeps {
+    /** Git probe; defaults to a bounded `spawnSync('git', …)`. */
+    exec?: LocalRootExec;
+    /** Home directory; defaults to `os.homedir()`. */
+    homedir?: string;
+    /** Platform override; defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Current uid; when undefined the uid comparison is skipped. */
+    getuid?: () => number | undefined;
+    /** stat-like probe returning the owner uid; may throw (fail-closed). */
+    stat?: (path: string) => {
+        uid: number;
+    };
+}
+/** Test hook: drop the module-level memo. */
+export declare function __clearLocalRootCache(): void;
+/**
+ * Resolve the directory that holds `.claude/settings.local.json` for a
+ * launch directory. Hoists to the git main checkout root (linked worktree)
+ * or the git toplevel (subdirectory start) unless a safety fallback applies:
+ * not a git repo, Windows, repo root equals `$HOME`, a bare-main hoist
+ * target without `.git`, or ownership of the repo root / `.git` / `.claude`
+ * cannot be confirmed as the current user (fail-closed). Paths *inside* the
+ * file still resolve against the launch directory.
+ *
+ * Results are memoised per resolved `cwd` for the default exec only;
+ * injected execs bypass the cache entirely (see `__clearLocalRootCache`).
+ */
+export declare function resolveLocalSettingsDir(cwd: string, deps?: LocalRootDeps): string;
+//# sourceMappingURL=local-root.d.ts.map

package/lib/local-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-root.d.ts","sourceRoot":"","sources":["../src/local-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,mBAAmB,GAAG,SAAS,CAAA;AAErG,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAA;IAC1B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACjC,wEAAwE;IACxE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC;AAyCD,6CAA6C;AAC7C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,MAAM,CASrF"}

package/lib/local-root.js

@@ -0,0 +1,140 @@
+/**
+ * Local-settings directory resolution: Claude Code reads
+ * `.claude/settings.local.json` from the git **main checkout root** when the
+ * session starts inside a linked worktree, or from the git toplevel when it
+ * starts in a subdirectory. This module computes that directory without
+ * touching the session cwd or git working tree. Git probes and `stat` are read-only.
+ *
+ * The linked-worktree detector and canonicalisation mirror the TUI project
+ * identity code in `packages/ui/tui/src/project.ts` (`isLinkedWorktree`,
+ * `canonical`) — see the comment there pointing back here. Keep the two in
+ * sync; they must not drift.
+ *
+ * Node builtins only: this file is imported through the
+ * `@dsh-cc/settings-cascade/local-root` subpath by packages that must
+ * not pull in cordis or the settings runtime.
+ *
+ * @module @dsh-cc/settings-cascade/local-root
+ */
+import { spawnSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir as osHomedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+/** Git probe timeout, mirroring the TUI `gitExecSync` bound. */
+const GIT_PROBE_TIMEOUT_MS = 2000;
+/** The default exec: real `git` via spawnSync with a bounded timeout. */
+const defaultExec = (argv, cwd) => {
+    const result = spawnSync('git', [...argv], { cwd, encoding: 'utf8', timeout: GIT_PROBE_TIMEOUT_MS });
+    if (result.error !== undefined || result.status !== 0)
+        return undefined;
+    return { stdout: result.stdout };
+};
+/** Canonicalise a path: resolve then dereference symlinks; resolve on failure. */
+function canonical(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/**
+ * True when `commonDir` marks a *linked* worktree whose main root is its
+ * parent. Mirrors `isLinkedWorktree` in `packages/ui/tui/src/project.ts` —
+ * keep the two in sync (see the module doc comment there).
+ */
+function isLinkedWorktree(commonDir, top) {
+    if (!commonDir.endsWith(`${sep}.git`))
+        return false;
+    return resolve(commonDir) !== resolve(join(top, '.git'));
+}
+/** Best-effort owner uid; undefined when stat fails (absent or unreadable). */
+function ownerUid(path, deps) {
+    const stat = deps.stat ?? (path => statSync(path));
+    try {
+        return stat(path).uid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Module-level memo keyed by `resolve(cwd)`, default-exec calls only. */
+const cache = new Map();
+/** Test hook: drop the module-level memo. */
+export function __clearLocalRootCache() {
+    cache.clear();
+}
+/**
+ * Resolve the directory that holds `.claude/settings.local.json` for a
+ * launch directory. Hoists to the git main checkout root (linked worktree)
+ * or the git toplevel (subdirectory start) unless a safety fallback applies:
+ * not a git repo, Windows, repo root equals `$HOME`, a bare-main hoist
+ * target without `.git`, or ownership of the repo root / `.git` / `.claude`
+ * cannot be confirmed as the current user (fail-closed). Paths *inside* the
+ * file still resolve against the launch directory.
+ *
+ * Results are memoised per resolved `cwd` for the default exec only;
+ * injected execs bypass the cache entirely (see `__clearLocalRootCache`).
+ */
+export function resolveLocalSettingsDir(cwd, deps = {}) {
+    const key = resolve(cwd);
+    if (deps.exec === undefined) {
+        const memoised = cache.get(key);
+        if (memoised !== undefined)
+            return memoised;
+    }
+    const result = resolveUncached(cwd, deps);
+    if (deps.exec === undefined)
+        cache.set(key, result);
+    return result;
+}
+function resolveUncached(cwd, deps) {
+    // Windows paths/permissions differ; Claude Code keeps the local file local.
+    if ((deps.platform ?? process.platform) === 'win32')
+        return resolve(cwd);
+    const exec = deps.exec ?? defaultExec;
+    const topRaw = exec(['rev-parse', '--show-toplevel'], cwd)?.stdout.trim();
+    if (topRaw === undefined || topRaw.length === 0)
+        return resolve(cwd);
+    const commonRaw = exec(['rev-parse', '--git-common-dir'], cwd)?.stdout.trim();
+    if (commonRaw === undefined || commonRaw.length === 0)
+        return resolve(cwd);
+    const topAbs = canonical(topRaw);
+    const commonDir = canonical(resolve(cwd, commonRaw));
+    const hoist = isLinkedWorktree(commonDir, topAbs);
+    const mainRoot = hoist ? dirname(commonDir) : topAbs;
+    // Bare-main guard: a hoisted common dir like `/x/repo.git` would resolve
+    // the "main root" to `/x`, which is not a checkout. A missing or
+    // unstatable `<mainRoot>/.git` refuses the hoist (the required-`.git`
+    // check below also fails closed on it).
+    if (hoist && ownerUid(join(mainRoot, '.git'), deps) === undefined)
+        return resolve(cwd);
+    // Never let the local file live directly in $HOME.
+    if (canonical(deps.homedir ?? osHomedir()) === mainRoot)
+        return resolve(cwd);
+    // Tests inject `getuid`; production uses `process.getuid` (absent on
+    // win32, which already returned above). An explicit `getuid: () => undefined`
+    // skips the uid comparison while still fail-closing on a throwing stat.
+    const uid = (deps.getuid ?? (() => process.getuid?.()))();
+    // Fail-closed: mainRoot and <mainRoot>/.git must stat AND (when the uid is
+    // observable) be owned by the current user. <mainRoot>/.claude is optional
+    // — ENOENT is fine, the file may be created later — but an EACCES on a
+    // 0700 `.git` must not escape the guard.
+    const checks = [
+        [mainRoot, true],
+        [join(mainRoot, '.git'), true],
+        [join(mainRoot, '.claude'), false],
+    ];
+    for (const [path, required] of checks) {
+        const owner = ownerUid(path, deps);
+        if (owner === undefined) {
+            if (required)
+                return resolve(cwd);
+            continue;
+        }
+        if (uid !== undefined && owner !== uid)
+            return resolve(cwd);
+    }
+    return mainRoot;
+}
+//# sourceMappingURL=local-root.js.map

package/lib/local-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-root.js","sourceRoot":"","sources":["../src/local-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAChD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAEvD,gEAAgE;AAChE,MAAM,oBAAoB,GAAG,IAAI,CAAA;AA4BjC,yEAAyE;AACzE,MAAM,WAAW,GAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IAC/C,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC,CAAA;IACpG,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACvE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AAClC,CAAC,CAAA;AAED,kFAAkF;AAClF,SAAS,SAAS,CAAC,IAAY;IAC7B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,SAAiB,EAAE,GAAW;IACtD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,GAAG,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IACnD,OAAO,OAAO,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAAC,IAAY,EAAE,IAAmB;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IAClD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAA;AAEvC,6CAA6C;AAC7C,MAAM,UAAU,qBAAqB;IACnC,KAAK,CAAC,KAAK,EAAE,CAAA;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW,EAAE,OAAsB,EAAE;IAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,QAAQ,CAAA;IAC7C,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACzC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IACnD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,eAAe,CAAC,GAAW,EAAE,IAAmB;IACvD,4EAA4E;IAC5E,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAExE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,WAAW,CAAA;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;IACzE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IACpE,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,kBAAkB,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;IAC7E,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAE1E,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IAChC,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAA;IACpD,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAEpD,yEAAyE;IACzE,iEAAiE;IACjE,sEAAsE;IACtE,wCAAwC;IACxC,IAAI,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAEtF,mDAAmD;IACnD,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAE5E,qEAAqE;IACrE,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAA;IACzD,2EAA2E;IAC3E,2EAA2E;IAC3E,uEAAuE;IACvE,yCAAyC;IACzC,MAAM,MAAM,GAA8C;QACxD,CAAC,QAAQ,EAAE,IAAI,CAAC;QAChB,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC;QAC9B,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,KAAK,CAAC;KACnC,CAAA;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAClC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,QAAQ;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;YACjC,SAAQ;QACV,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,IAAI,KAAK,KAAK,GAAG;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAC7D,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/lib/merge.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Deep-merge semantics for the settings cascade. Plain objects merge
+ * recursively; permission objects (`allow`/`deny`/`ask`) union their rule
+ * arrays with `deny` taking precedence over `allow`; every other array and
+ * scalar value from a higher layer replaces the lower layer wholesale.
+ * @module @dsh-cc/settings-cascade/merge
+ */
+/**
+ * Merge one permission object over a lower one. `allow`, `deny`, and `ask`
+ * union across layers, and the unioned `deny` set is removed from `allow` so a
+ * higher-layer deny always wins over a lower-layer allow. Other keys deep-merge
+ * with ordinary rules (arrays override).
+ * @param lower - the lower-priority permission object.
+ * @param higher - the higher-priority permission object.
+ * @returns the merged permission object.
+ */
+export declare function mergePermissionObject(lower: Record<string, unknown>, higher: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Compute the unioned deny set and the allow set that excludes it — the
+ * `deny`-precedence rule applied to one lower and one higher permission object.
+ * @param lower - the lower-priority permission object.
+ * @param higher - the higher-priority permission object.
+ * @returns the unioned `deny` and deduped `allow` with denied rules removed.
+ */
+export declare function unionDenyPrecedence(lower: {
+    allow?: string[];
+    deny?: string[];
+}, higher: {
+    allow?: string[];
+    deny?: string[];
+}): {
+    allow: string[];
+    deny: string[];
+};
+/**
+ * Merge one JSON-compatible value over a lower one. When both are plain
+ * objects the merge recurses — through the permission rule for permission
+ * objects and per-key otherwise; any other pair lets the higher value replace
+ * the lower wholesale. Neither input is mutated.
+ * @param lower - the lower-priority value.
+ * @param higher - the higher-priority value; `undefined` keeps the lower value.
+ * @returns the merged value.
+ */
+export declare function mergeValue<T = unknown>(lower: T, higher: unknown): T;
+/**
+ * Merge one whole namespace section over a lower section (recursive deep
+ * merge with the permission array rules and higher-array-override semantics).
+ * @param lower - the lower-priority raw section.
+ * @param higher - the higher-priority raw section.
+ * @returns the merged raw section.
+ */
+export declare function mergeSettingsSection(lower: Record<string, unknown>, higher: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=merge.d.ts.map

package/lib/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiCH;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCzB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,EAC5C,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAKrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,CAAC,CAapE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB"}

package/lib/merge.js

@@ -0,0 +1,126 @@
+/**
+ * Deep-merge semantics for the settings cascade. Plain objects merge
+ * recursively; permission objects (`allow`/`deny`/`ask`) union their rule
+ * arrays with `deny` taking precedence over `allow`; every other array and
+ * scalar value from a higher layer replaces the lower layer wholesale.
+ * @module @dsh-cc/settings-cascade/merge
+ */
+/** The permission rule arrays that merge by union across layers. */
+const PERMISSION_KEYS = ['allow', 'deny', 'ask'];
+/** Whether a value is a plain data object (not an array, null, or instance). */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Whether an object holds at least one permission rule array. */
+function isPermissionObject(value) {
+    return PERMISSION_KEYS.some(key => key in value);
+}
+/** Concatenate string arrays and deduplicate, preserving first-seen order. */
+function unionStrings(...lists) {
+    const seen = new Set();
+    const out = [];
+    for (const list of lists) {
+        if (list === undefined)
+            continue;
+        for (const entry of list) {
+            if (!seen.has(entry)) {
+                seen.add(entry);
+                out.push(entry);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Merge one permission object over a lower one. `allow`, `deny`, and `ask`
+ * union across layers, and the unioned `deny` set is removed from `allow` so a
+ * higher-layer deny always wins over a lower-layer allow. Other keys deep-merge
+ * with ordinary rules (arrays override).
+ * @param lower - the lower-priority permission object.
+ * @param higher - the higher-priority permission object.
+ * @returns the merged permission object.
+ */
+export function mergePermissionObject(lower, higher) {
+    const lowerAllow = lower['allow'];
+    const lowerDeny = lower['deny'];
+    const lowerAsk = lower['ask'];
+    const higherAllow = higher['allow'];
+    const higherDeny = higher['deny'];
+    const higherAsk = higher['ask'];
+    const deny = unionStrings(lowerDeny, higherDeny);
+    const denied = new Set(deny);
+    const allow = unionStrings(lowerAllow, higherAllow).filter(rule => !denied.has(rule));
+    const ask = unionStrings(lowerAsk, higherAsk);
+    // Start from both layers' non-permission keys; the derived allow/deny/ask
+    // replace the lower layer's originals below, and empty permission arrays are
+    // omitted — an empty `allow` after deny filtering means "nothing allowed",
+    // and JSON settings conventionally drop empty lists.
+    const merged = {};
+    for (const [key, value] of Object.entries(lower)) {
+        if (PERMISSION_KEYS.includes(key))
+            continue;
+        merged[key] = value;
+    }
+    for (const [key, value] of Object.entries(higher)) {
+        if (PERMISSION_KEYS.includes(key))
+            continue;
+        merged[key] = key in merged ? mergeValue(merged[key], value) : value;
+    }
+    return {
+        ...merged,
+        ...(allow.length > 0 ? { allow } : {}),
+        ...(deny.length > 0 ? { deny } : {}),
+        ...(ask.length > 0 ? { ask } : {}),
+    };
+}
+/**
+ * Compute the unioned deny set and the allow set that excludes it — the
+ * `deny`-precedence rule applied to one lower and one higher permission object.
+ * @param lower - the lower-priority permission object.
+ * @param higher - the higher-priority permission object.
+ * @returns the unioned `deny` and deduped `allow` with denied rules removed.
+ */
+export function unionDenyPrecedence(lower, higher) {
+    const deny = unionStrings(lower.deny, higher.deny);
+    const denied = new Set(deny);
+    const allow = unionStrings(lower.allow, higher.allow).filter(rule => !denied.has(rule));
+    return { allow, deny };
+}
+/**
+ * Merge one JSON-compatible value over a lower one. When both are plain
+ * objects the merge recurses — through the permission rule for permission
+ * objects and per-key otherwise; any other pair lets the higher value replace
+ * the lower wholesale. Neither input is mutated.
+ * @param lower - the lower-priority value.
+ * @param higher - the higher-priority value; `undefined` keeps the lower value.
+ * @returns the merged value.
+ */
+export function mergeValue(lower, higher) {
+    if (higher === undefined)
+        return lower;
+    if (isPlainObject(lower) && isPlainObject(higher)) {
+        if (isPermissionObject(lower) || isPermissionObject(higher)) {
+            return mergePermissionObject(lower, higher);
+        }
+        const merged = { ...lower };
+        for (const [key, value] of Object.entries(higher)) {
+            merged[key] = key in merged ? mergeValue(merged[key], value) : value;
+        }
+        return merged;
+    }
+    return higher;
+}
+/**
+ * Merge one whole namespace section over a lower section (recursive deep
+ * merge with the permission array rules and higher-array-override semantics).
+ * @param lower - the lower-priority raw section.
+ * @param higher - the higher-priority raw section.
+ * @returns the merged raw section.
+ */
+export function mergeSettingsSection(lower, higher) {
+    return mergeValue(lower, higher);
+}
+//# sourceMappingURL=merge.js.map

package/lib/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"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"}

package/lib/permissions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Claude Code-compatible `permissions` field schema, exported as a standalone
+ * value so the permission-rule engine (B2) and the settings cascade share one
+ * definition of the settings.json `permissions` shape.
+ * @module @dsh-cc/settings-cascade/permissions
+ */
+import z from '@deepseek-ai/schemastery';
+/** A single permission rule — a tool-scoped match string, e.g. `Bash(npm run *)`. */
+export declare const PermissionRuleSchema: z<string>;
+/** `defaultMode` values — the default permission mode when a tool needs access. */
+export declare const PERMISSION_MODES: readonly ["default", "acceptEdits", "plan", "bypassPermissions", "auto"];
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+/** The settings.json `permissions` section, matching Claude Code's schema. */
+export interface Permissions {
+    /** Tool operations allowed without prompting. */
+    allow?: string[];
+    /** Tool operations always blocked. */
+    deny?: string[];
+    /** Tool operations that always prompt for confirmation. */
+    ask?: string[];
+    /** Default permission mode when a tool needs access. */
+    defaultMode?: PermissionMode;
+    /** `'disable'` turns off the ability to bypass permission prompts. */
+    disableBypassPermissionsMode?: 'disable';
+    /** Additional directories included in the permission scope. */
+    additionalDirectories?: string[];
+    /** Protected file wildcard patterns — file writes to them are high risk. */
+    protectedFiles?: string[];
+    /** Raw dangerous-command regex sources for the risk classifier. */
+    dangerousPatterns?: string[];
+}
+/**
+ * Schemastery schema for the `permissions` section. Unknown fields pass
+ * through unmodified, matching Claude Code's passthrough behavior.
+ */
+export declare const PermissionsSchema: z<Permissions>;
+//# sourceMappingURL=permissions.d.ts.map

package/lib/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAc,CAAA;AAEzD,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,0EAA2E,CAAA;AACxG,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,wDAAwD;IACxD,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,sEAAsE;IACtE,4BAA4B,CAAC,EAAE,SAAS,CAAA;IACxC,+DAA+D;IAC/D,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAA;IAChC,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,WAAW,CAS3C,CAAA"}

package/lib/permissions.js

@@ -0,0 +1,26 @@
+/**
+ * Claude Code-compatible `permissions` field schema, exported as a standalone
+ * value so the permission-rule engine (B2) and the settings cascade share one
+ * definition of the settings.json `permissions` shape.
+ * @module @dsh-cc/settings-cascade/permissions
+ */
+import z from '@deepseek-ai/schemastery';
+/** A single permission rule — a tool-scoped match string, e.g. `Bash(npm run *)`. */
+export const PermissionRuleSchema = z.string();
+/** `defaultMode` values — the default permission mode when a tool needs access. */
+export const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'bypassPermissions', 'auto'];
+/**
+ * Schemastery schema for the `permissions` section. Unknown fields pass
+ * through unmodified, matching Claude Code's passthrough behavior.
+ */
+export const PermissionsSchema = z.object({
+    allow: z.array(z.string()),
+    deny: z.array(z.string()),
+    ask: z.array(z.string()),
+    defaultMode: z.union(PERMISSION_MODES),
+    disableBypassPermissionsMode: z.union(['disable']),
+    additionalDirectories: z.array(z.string()),
+    protectedFiles: z.array(z.string()),
+    dangerousPatterns: z.array(z.string()),
+});
+//# sourceMappingURL=permissions.js.map

package/lib/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAc,CAAC,CAAC,MAAM,EAAE,CAAA;AAEzD,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,CAAU,CAAA;AAuBxG;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAmB,CAAC,CAAC,MAAM,CAAC;IACxD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACzB,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IACtC,4BAA4B,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC;IAClD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACnC,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CACvC,CAAC,CAAA"}

package/lib/persist.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Surgical-delta persistence for the settings cascade. When a write reaches
+ * the provider it carries the full merged section for one namespace; writing
+ * that whole section into the user settings file would smear higher-layer
+ * (project/local/flag/policy) contributions into the user layer. Instead the
+ * section is diffed against the last-published shadow and only the leaf-level
+ * change ops are applied onto the user file's own section. File writes are
+ * atomic (temp + rename) so a crash never leaves a half-written document.
+ * @module @dsh-cc/settings-cascade/persist
+ */
+/** One leaf-level change to a JSON section, mirroring the seam's path ops. */
+export type JsonOp = {
+    op: 'set';
+    path: string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: string[];
+};
+/**
+ * Diff two JSON sections into leaf-level ops. Leaves equal by deep value
+ * equality produce no op; changed or added leaves produce `set`; keys present
+ * in `prev` but absent in `next` produce `unset`. Arrays compare as whole
+ * leaves. When both sides are plain objects the diff recurses; when one side
+ * is not a plain object while the other is, the node is replaced wholesale.
+ * Neither input is mutated.
+ * @param prev - the earlier section (the shadow of what was published before).
+ * @param next - the desired section (the merged write target).
+ * @param path - the JSON path accumulated so far; defaults to the root `[]`.
+ * @returns the ordered ops that transform `prev` into `next`.
+ */
+export declare function diffSections(prev: unknown, next: unknown, path?: string[]): JsonOp[];
+/**
+ * Apply a list of ops onto a detached JSON section, returning the next
+ * section. Mirrors the seam's `applyPathOp`: a nested `set` that meets a
+ * non-plain-object intermediate node replaces that node wholesale with an
+ * object built around the remaining path; `unset` on a missing key is a
+ * no-op; a `set` with an empty path requires a plain object and replaces the
+ * whole section; an `unset` with an empty path yields `{}`. The input is not
+ * mutated.
+ * @param section - the current section (`undefined` when the namespace is absent).
+ * @param ops - the ops to apply in order.
+ * @returns the resulting section.
+ */
+export declare function applyOpsToSection(section: unknown, ops: JsonOp[]): unknown;
+/**
+ * Read one settings document into a plain object. Absence and whitespace-only
+ * content read as `{}`; invalid JSON or a non-object root fail loud with the
+ * path, mirroring the cascade provider's load-time parse.
+ * @param path - the absolute settings file path.
+ * @returns the parsed root document, or `{}` when the file is absent or blank.
+ */
+export declare function readUserFile(path: string): Promise<Record<string, unknown>>;
+/**
+ * Write a JSON root document atomically. The parent directory is created with
+ * mode `0o700`, the document is written to a random temp sibling under mode
+ * `0o600`, then renamed over the target. On any failure after the temp file is
+ * created it is best-effort removed before the error rethrows. The temp name
+ * is random (rather than fixed) so concurrent writers never collide on it.
+ * @param path - the absolute target settings file path.
+ * @param root - the plain-object document to serialize.
+ */
+export declare function writeJsonAtomic(path: string, root: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=persist.d.ts.map

package/lib/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../src/persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,8EAA8E;AAC9E,MAAM,MAAM,MAAM,GACd;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAqBnC;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAmBxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAM1E;AA2CD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAmBjF;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhG"}