@dsh-cc/settings-cascade 0.5.0

package/lib/persist.js

@@ -0,0 +1,183 @@
+/**
+ * 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
+ */
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+/** 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;
+}
+/** Deep value equality, stable across JSON-shaped leaves (objects recurse). */
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every(key => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+/**
+ * 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 function diffSections(prev, next, path = []) {
+    if (isPlainObject(prev) && isPlainObject(next)) {
+        const ops = [];
+        for (const [key, value] of Object.entries(next)) {
+            if (Object.prototype.hasOwnProperty.call(prev, key)) {
+                ops.push(...diffSections(prev[key], value, [...path, key]));
+            }
+            else {
+                ops.push({ op: 'set', path: [...path, key], value });
+            }
+        }
+        for (const key of Object.keys(prev)) {
+            if (!Object.prototype.hasOwnProperty.call(next, key)) {
+                ops.push({ op: 'unset', path: [...path, key] });
+            }
+        }
+        return ops;
+    }
+    if (deepEqual(prev, next))
+        return [];
+    return [{ op: 'set', path, value: next }];
+}
+/**
+ * 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 function applyOpsToSection(section, ops) {
+    let out = section;
+    for (const op of ops) {
+        out = applyPathOp(out, op);
+    }
+    return out;
+}
+/** Apply one path op to a detached section, returning the next section. */
+function applyPathOp(section, op) {
+    const [head, ...rest] = op.path;
+    if (head === undefined) {
+        if (op.op === 'unset')
+            return {};
+        if (!isPlainObject(op.value))
+            throw new TypeError('settings-cascade: setting the section root requires a plain object');
+        return { ...op.value };
+    }
+    if (rest.length === 0) {
+        const base = isPlainObject(section) ? section : {};
+        if (op.op === 'set')
+            return { ...base, [head]: op.value };
+        if (!isPlainObject(section))
+            return section;
+        const { [head]: _removed, ...kept } = section;
+        return kept;
+    }
+    const child = isPlainObject(section) ? section[head] : undefined;
+    if (!isPlainObject(child)) {
+        if (op.op === 'unset')
+            return section;
+        return {
+            ...(isPlainObject(section) ? section : {}),
+            [head]: applyPathOp({}, restOp(op, rest)),
+        };
+    }
+    const base = isPlainObject(section) ? section : {};
+    return {
+        ...base,
+        [head]: applyPathOp(child, restOp(op, rest)),
+    };
+}
+/** Rebuild an op focused on the remaining path of a nested traversal. */
+function restOp(op, path) {
+    if (op.op === 'set')
+        return { op: 'set', path, value: op.value };
+    return { op: 'unset', path };
+}
+/** Whether a filesystem error simply means the file is absent. */
+function isENOENT(error) {
+    return error?.code === 'ENOENT';
+}
+/**
+ * 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 async function readUserFile(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isENOENT(error))
+            return {};
+        throw error;
+    }
+    if (text.trim().length === 0)
+        return {};
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`settings-cascade: invalid settings document at ${path}: ${error.message}`, { cause: error });
+    }
+    if (!isPlainObject(root)) {
+        throw new TypeError(`settings-cascade: ${path} must be a JSON object of namespace sections`);
+    }
+    return root;
+}
+/**
+ * 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 async function writeJsonAtomic(path, root) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(root, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        await rename(tmp, path);
+    }
+    catch (error) {
+        await rm(tmp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=persist.js.map

package/lib/persist.js.map

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@dsh-cc/settings-cascade",
+  "description": "Claude Code-style five-level settings cascade provider (ctx.settings) for the DeepSeek Harness",
+  "version": "0.5.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/settings/settings-cascade"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./permissions": {
+      "types": "./lib/permissions.d.ts",
+      "default": "./lib/permissions.js"
+    },
+    "./local-root": {
+      "types": "./lib/local-root.d.ts",
+      "default": "./lib/local-root.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-home-paths": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": ">=0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-home-paths": "link:../../../../deepseek-harness/packages/util/home-paths",
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-settings": "link:../../../../deepseek-harness/packages/settings/settings",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}