@deepseek-ai/cordis-plugin-include 1.0.5-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Shigma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @cordisjs/plugin-include
+
+File-backed loader tree for Cordis. The include plugin reads a YAML or JSON
+file, turns it into loader entries, and writes updates back when the file is
+writable.
+
+## Usage
+
+```ts
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+
+const root = new Context()
+await root.plugin(Loader, { baseUrl: import.meta.url })
+await root.plugin(Include, {
+  path: './cordis.yml',
+  initial: [],
+  enableLogs: true,
+})
+```
+
+Example `cordis.yml`:
+
+```yaml
+- id: timer
+  name: '@cordisjs/plugin-timer'
+- id: app
+  name: ./plugins/app
+  config:
+    message: hello
+```
+
+## Config
+
+| Field | Description |
+| --- | --- |
+| `path` | YAML or JSON file path resolved from `ctx.baseUrl`. |
+| `initial` | Entry list written when the file is missing. |
+| `patches` | Runtime patches applied after reading the file. |
+| `enableLogs` | Enables loader apply, reload, and unload logs. |
+
+Patches can insert entries or override fields on entries with a matching `id`.

package/lib/index.js

@@ -0,0 +1,297 @@
+import { EntryConfigResolver, EntryTree, interpolate, isJsExpr } from "@deepseek-ai/cordis-plugin-loader";
+import { Service } from "@deepseek-ai/cordis";
+import { extname } from "node:path";
+import { access, constants, readFile, rename, writeFile } from "node:fs/promises";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import * as yaml from "js-yaml";
+//#region lib/types/index.js
+var __rewriteRelativeImportExtension = function(path, preserveJsx) {
+	if (typeof path === "string" && /^\.\.?\//.test(path)) return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function(m, tsx, d, ext, cm) {
+		return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : d + ext + "." + cm.toLowerCase() + "js";
+	});
+	return path;
+};
+const JsExpr = new yaml.Type("tag:yaml.org,2002:js", {
+	kind: "scalar",
+	resolve: (data) => typeof data === "string",
+	construct: (data) => ({ __jsExpr: data }),
+	predicate: isJsExpr,
+	represent: (data) => data["__jsExpr"]
+});
+/**
+* The entry-list YAML dialect: `!!js` scalars round-trip as expression nodes
+* the Loader evaluates at entry activation. Exported so config tooling
+* (`dsh --dump-config`) parses and prints exactly the dialect this include
+* mounts.
+*/
+const entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr);
+const schema = entryListSchema;
+const writable = {
+	".json": "application/json",
+	".yaml": "application/yaml",
+	".yml": "application/yaml"
+};
+const supported = new Set(Object.keys(writable));
+const WRITE_RETRY_LIMIT = 10;
+const WRITE_RETRY_DELAY_MS = 50;
+function retryableWriteError(error) {
+	const code = error?.code;
+	return code === "EACCES" || code === "EBUSY" || code === "EPERM";
+}
+/**
+* Apply patch lists to an entry list — THE patch semantics of this include,
+* shared by mounting (`applyPatches`) and offline config tooling
+* (`dsh --dump-config`) so a dump can never drift from what boots. The input
+* is never mutated and the result is always detached from it (even with no
+* patches): patching or mounting shared entry objects would bake earlier
+* values into the cached parse, so repeated application (config hot-reloads)
+* could never revert a removed or changed patch. Inserted entries are indexed
+* as they are added, so a later patch in the same list can target a row an
+* earlier patch inserted. A patch that matches nothing warns and is skipped.
+* @param data - the parsed entry list (JSON-safe plain data).
+* @param patches - the patch list to apply, in order.
+* @param warn - sink for skipped-patch diagnostics (printf-style, `%C` = code).
+* @returns a detached entry list with every applicable patch applied.
+*/
+function applyEntryPatches(data, patches, warn) {
+	data = structuredClone(data);
+	if (!patches?.length) return data;
+	const entryMap = /* @__PURE__ */ new Map();
+	const buildMap = (entries) => {
+		for (const entry of entries) {
+			if (entry.id) entryMap.set(entry.id, entry);
+			if (entry.group && Array.isArray(entry.config)) buildMap(entry.config);
+		}
+	};
+	buildMap(data);
+	for (const patch of patches) {
+		const { id, insert, name, ...overrides } = patch;
+		if (insert) {
+			if (id) {
+				const target = entryMap.get(id);
+				if (!target) {
+					warn("patch insert: entry %C not found", id);
+					continue;
+				}
+				if (!target.group) {
+					warn("patch insert: entry %C is not a group", id);
+					continue;
+				}
+				if (!Array.isArray(target.config)) target.config = [];
+				target.config.push(...insert);
+			} else data.push(...insert);
+			buildMap(insert);
+			continue;
+		}
+		if (!id) {
+			warn("patch: id is required for non-insert patches");
+			continue;
+		}
+		const target = entryMap.get(id);
+		if (!target) {
+			warn("patch: entry %C not found", id);
+			continue;
+		}
+		if (name && name !== target.name) {
+			warn("patch: name mismatch for %C (expected %C, got %C), skipping", id, target.name, name);
+			continue;
+		}
+		for (const [key, value] of Object.entries(overrides)) {
+			if (key === "id") continue;
+			target[key] = value;
+		}
+	}
+	return data;
+}
+var ConfigFileError = class extends Error {
+	stage;
+	constructor(stage, path, cause) {
+		super(`failed to ${stage} config file ${path}`, { cause });
+		this.stage = stage;
+		this.name = "ConfigFileError";
+	}
+};
+/** Loader entry tree backed by a YAML or JSON file. */
+var Include = class extends EntryTree {
+	config;
+	static inject = ["loader"];
+	/**
+	* Resolve Include's own options while preserving nested entry expressions.
+	* @param ctx - the Include plugin context.
+	* @param config - the raw Include config.
+	* @returns resolved Include options with `initial` and `patches` untouched.
+	*/
+	static [EntryConfigResolver](ctx, config) {
+		const { initial, patches, ...own } = config;
+		return {
+			...interpolate(ctx, own),
+			...initial === void 0 ? {} : { initial },
+			...patches === void 0 ? {} : { patches }
+		};
+	}
+	filename;
+	type;
+	readonly;
+	content;
+	data;
+	writeTask;
+	pendingWrite;
+	writeQueue = Promise.resolve();
+	applyQueue = Promise.resolve();
+	constructor(ctx, config) {
+		super(ctx);
+		this.config = config;
+		this.enableLogs = config.enableLogs ?? ctx.fiber.entry?.parent.tree.enableLogs ?? false;
+		this.filename = fileURLToPath(new URL(this.config.path, this.ctx.baseUrl));
+		const ext = extname(this.filename);
+		if (!supported.has(ext)) throw new Error(`extension "${ext}" not supported`);
+		this.type = writable[ext];
+		this.readonly = !this.type;
+		this.ctx.baseUrl = new URL(".", pathToFileURL(this.filename)).href;
+		ctx.on("internal/update", async (config, _, next) => {
+			if (config.path !== this.config.path) return next();
+			await this.enqueue(async () => {
+				const data = this.applyPatches(this.data, config.patches);
+				await this.root.update(data);
+				this.config = config;
+			});
+		});
+	}
+	/**
+	* Serialize one child-tree mutation behind every earlier one. The group's
+	* transactional `update` is not reentrant: two concurrent applies (the init
+	* apply racing an HMR-triggered refresh from the watcher's initial scan)
+	* interleave create and rollback on the same entries and strand the include
+	* fiber without settling, so every apply path funnels through this queue.
+	* A predecessor's failure is its own caller's outcome and never gates the
+	* next task.
+	*/
+	enqueue(task) {
+		const run = this.applyQueue.then(task, task);
+		this.applyQueue = run.then(() => {}, () => {});
+		return run;
+	}
+	async checkAccess() {
+		if (!this.type) return;
+		try {
+			await access(this.filename, constants.W_OK);
+		} catch {
+			this.readonly = true;
+		}
+	}
+	async read(forced = false) {
+		let content;
+		try {
+			content = await readFile(this.filename, "utf8");
+		} catch (error) {
+			throw new ConfigFileError("read", this.filename, error);
+		}
+		if (!forced && this.content === content) return;
+		let data;
+		try {
+			if (this.type === "application/yaml") data = yaml.load(content, { schema });
+			else if (this.type === "application/json") data = JSON.parse(content);
+			else {
+				const module = await import(__rewriteRelativeImportExtension(
+					/* @vite-ignore */
+					this.filename
+				));
+				data = module.default || module;
+			}
+		} catch (error) {
+			throw new ConfigFileError("parse", this.filename, error);
+		}
+		if (!Array.isArray(data)) throw new ConfigFileError("validate", this.filename, /* @__PURE__ */ new TypeError("config file must be a top-level array"));
+		return {
+			content,
+			data
+		};
+	}
+	applyPatches(data, patches) {
+		return applyEntryPatches(data, patches, (message, ...args) => {
+			this.ctx.root.logger?.("loader").warn(message, ...args);
+		});
+	}
+	async *[Service.init]() {
+		let candidate;
+		try {
+			candidate = await this.read(true);
+		} catch (error) {
+			if (!(error instanceof ConfigFileError) || error.stage !== "read" || error.cause?.code !== "ENOENT") throw error;
+			if (this.config.initial) {
+				await this._writeFile(this.config.initial);
+				candidate = await this.read(true);
+			} else throw new Error(`config file not found: ${this.filename}`);
+		}
+		yield () => this.stop();
+		await this.apply(candidate);
+	}
+	async stop() {
+		await this.root.stop();
+		await this.flushWrite();
+	}
+	/**
+	* Re-read the file and transactionally refresh child entries when content changed.
+	* @returns a promise resolving after the new tree commits, or immediately when unchanged.
+	* @throws when reading, parsing, validation, application, or rollback fails; the last good tree remains active when rollback succeeds.
+	*/
+	async refresh() {
+		await this.enqueue(async () => {
+			const candidate = await this.read();
+			if (!candidate) return;
+			await this._apply(candidate);
+		});
+	}
+	apply(candidate) {
+		return this.enqueue(() => this._apply(candidate));
+	}
+	async _apply(candidate) {
+		const data = this.applyPatches(candidate.data, this.config.patches);
+		await this.root.update(data);
+		this.content = candidate.content;
+		this.data = candidate.data;
+		await this.checkAccess();
+	}
+	async _writeFile(config) {
+		if (this.readonly) throw new Error(`cannot overwrite readonly config`);
+		if (this.type === "application/yaml") this.content = yaml.dump(config, { schema });
+		else if (this.type === "application/json") this.content = JSON.stringify(config, null, 2);
+		await writeFile(this.filename + ".tmp", this.content);
+		for (let retry = 0;; retry++) try {
+			await rename(this.filename + ".tmp", this.filename);
+			return;
+		} catch (error) {
+			if (!retryableWriteError(error) || retry >= WRITE_RETRY_LIMIT) throw error;
+			await setTimeout$1((retry + 1) * WRITE_RETRY_DELAY_MS);
+		}
+	}
+	writeFile(config) {
+		clearTimeout(this.writeTask);
+		this.pendingWrite = config;
+		this.writeTask = setTimeout(() => {
+			this.flushWrite();
+		}, 0);
+	}
+	flushWrite() {
+		clearTimeout(this.writeTask);
+		this.writeTask = void 0;
+		const config = this.pendingWrite;
+		this.pendingWrite = void 0;
+		if (config === void 0) return this.writeQueue;
+		const run = this.writeQueue.then(() => this._writeFile(config), () => this._writeFile(config));
+		this.writeQueue = run;
+		run.catch((error) => {
+			this.ctx.root.logger?.("loader").warn("failed to write config file %C", this.filename);
+			this.ctx.root.logger?.("loader").warn(error);
+		});
+		return run;
+	}
+	/** Schedule a write of the current root entry data. */
+	write() {
+		this.context.emit("loader/config-update");
+		return this.writeFile(this.root.data);
+	}
+};
+//#endregion
+export { Include, Include as default, applyEntryPatches, entryListSchema };

package/lib/types/index.d.ts

@@ -0,0 +1,105 @@
+import { EntryConfigResolver, EntryTree, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader';
+import { Context, Service } from '@deepseek-ai/cordis';
+import * as yaml from 'js-yaml';
+/**
+ * The entry-list YAML dialect: `!!js` scalars round-trip as expression nodes
+ * the Loader evaluates at entry activation. Exported so config tooling
+ * (`dsh --dump-config`) parses and prints exactly the dialect this include
+ * mounts.
+ */
+export declare const entryListSchema: yaml.Schema;
+/**
+ * Apply patch lists to an entry list — THE patch semantics of this include,
+ * shared by mounting (`applyPatches`) and offline config tooling
+ * (`dsh --dump-config`) so a dump can never drift from what boots. The input
+ * is never mutated and the result is always detached from it (even with no
+ * patches): patching or mounting shared entry objects would bake earlier
+ * values into the cached parse, so repeated application (config hot-reloads)
+ * could never revert a removed or changed patch. Inserted entries are indexed
+ * as they are added, so a later patch in the same list can target a row an
+ * earlier patch inserted. A patch that matches nothing warns and is skipped.
+ * @param data - the parsed entry list (JSON-safe plain data).
+ * @param patches - the patch list to apply, in order.
+ * @param warn - sink for skipped-patch diagnostics (printf-style, `%C` = code).
+ * @returns a detached entry list with every applicable patch applied.
+ */
+export declare function applyEntryPatches(data: EntryOptions[], patches: PatchOptions[] | undefined, warn: (message: string, ...args: any[]) => void): EntryOptions[];
+/** Runtime patch applied to entries loaded from an included config file. */
+export interface PatchOptions {
+    id?: string;
+    insert?: EntryOptions[];
+    name?: string;
+    config?: any;
+    group?: boolean | null;
+    disabled?: boolean | null;
+    inject?: any;
+    intercept?: any;
+    isolate?: any;
+    [key: string]: any;
+}
+/** Config namespace for the file-backed include loader. */
+export declare namespace Include {
+    /** Config for a file-backed loader subtree. */
+    interface Config {
+        /** YAML or JSON path resolved from `ctx.baseUrl`. */
+        path: string;
+        /** Entry list written when the file does not already exist. */
+        initial?: any[];
+        /** Runtime patches applied after reading the file. */
+        patches?: PatchOptions[];
+        /** Enables loader apply/reload/unload logs for this subtree. */
+        enableLogs?: boolean;
+    }
+}
+/** Loader entry tree backed by a YAML or JSON file. */
+export declare class Include extends EntryTree {
+    config: Include.Config;
+    static inject: string[];
+    /**
+     * Resolve Include's own options while preserving nested entry expressions.
+     * @param ctx - the Include plugin context.
+     * @param config - the raw Include config.
+     * @returns resolved Include options with `initial` and `patches` untouched.
+     */
+    static [EntryConfigResolver](ctx: Context, config: Include.Config): Include.Config;
+    filename: string;
+    private type?;
+    private readonly;
+    private content?;
+    private data?;
+    private writeTask?;
+    private pendingWrite?;
+    private writeQueue;
+    private applyQueue;
+    constructor(ctx: Context, config: Include.Config);
+    /**
+     * Serialize one child-tree mutation behind every earlier one. The group's
+     * transactional `update` is not reentrant: two concurrent applies (the init
+     * apply racing an HMR-triggered refresh from the watcher's initial scan)
+     * interleave create and rollback on the same entries and strand the include
+     * fiber without settling, so every apply path funnels through this queue.
+     * A predecessor's failure is its own caller's outcome and never gates the
+     * next task.
+     */
+    private enqueue;
+    private checkAccess;
+    private read;
+    private applyPatches;
+    [Service.init](): AsyncGenerator<() => Promise<void>, void, unknown>;
+    stop(): Promise<void>;
+    /**
+     * Re-read the file and transactionally refresh child entries when content changed.
+     * @returns a promise resolving after the new tree commits, or immediately when unchanged.
+     * @throws when reading, parsing, validation, application, or rollback fails; the last good tree remains active when rollback succeeds.
+     */
+    refresh(): Promise<void>;
+    private apply;
+    private _apply;
+    private _writeFile;
+    private writeFile;
+    private flushWrite;
+    /** Schedule a write of the current root entry data. */
+    write(): void;
+}
+export default Include;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAyB,KAAK,YAAY,EAAE,MAAM,mCAAmC,CAAA;AAC5H,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKtD,OAAO,KAAK,IAAI,MAAM,SAAS,CAAA;AAU/B;;;;;GAKG;AACH,eAAO,MAAM,eAAe,aAAkC,CAAA;AAoB9D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,YAAY,EAAE,EACpB,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,EACnC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAC9C,YAAY,EAAE,CAkEhB;AAgBD,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACzB,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,OAAO,CAAC,EAAE,GAAG,CAAA;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED,2DAA2D;AAC3D,yBAAiB,OAAO,CAAC;IACvB,+CAA+C;IAC/C,UAAiB,MAAM;QACrB,qDAAqD;QACrD,IAAI,EAAE,MAAM,CAAA;QACZ,+DAA+D;QAC/D,OAAO,CAAC,EAAE,GAAG,EAAE,CAAA;QACf,sDAAsD;QACtD,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;QACxB,gEAAgE;QAChE,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB;CACF;AAED,uDAAuD;AACvD,qBAAa,OAAQ,SAAQ,SAAS;IA4BH,MAAM,EAAE,OAAO,CAAC,MAAM;IA3BvD,MAAM,CAAC,MAAM,WAAa;IAE1B;;;;;OAKG;IACH,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM;IAS3E,QAAQ,EAAE,MAAM,CAAA;IACvB,OAAO,CAAC,IAAI,CAAC,CAAQ;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAQ;IACxB,OAAO,CAAC,IAAI,CAAC,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAC,CAA4B;IAC9C,OAAO,CAAC,YAAY,CAAC,CAAgB;IACrC,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,UAAU,CAAsC;gBAE5C,GAAG,EAAE,OAAO,EAAS,MAAM,EAAE,OAAO,CAAC,MAAM;IAsBvD;;;;;;;;OAQG;IACH,OAAO,CAAC,OAAO;YAMD,WAAW;YASX,IAAI;IA2BlB,OAAO,CAAC,YAAY;IAMb,CAAC,OAAO,CAAC,IAAI,CAAC;IAkBf,IAAI;IAKV;;;;OAIG;IACG,OAAO;IAUb,OAAO,CAAC,KAAK;YAIC,MAAM;YAQN,UAAU;IAqBxB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAkBlB,uDAAuD;IACvD,KAAK;CAIN;AAED,eAAe,OAAO,CAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deepseek-ai/cordis-plugin-include",
+  "description": "Include files in cordis configurations",
+  "version": "1.0.5-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "vendor/include"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "author": "Shigma <shigma10826@gmail.com>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "@deepseek-ai/cosmokit": "^1.8.2-rc.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,385 @@
+import { EntryConfigResolver, EntryTree, interpolate, isJsExpr, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
+import { Context, Service } from '@deepseek-ai/cordis'
+import { extname } from 'node:path'
+import { access, constants, readFile, rename, writeFile } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import * as yaml from 'js-yaml'
+
+const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: (data) => typeof data === 'string',
+  construct: (data) => ({ __jsExpr: data }),
+  predicate: isJsExpr,
+  represent: (data) => data['__jsExpr'],
+})
+
+/**
+ * The entry-list YAML dialect: `!!js` scalars round-trip as expression nodes
+ * the Loader evaluates at entry activation. Exported so config tooling
+ * (`dsh --dump-config`) parses and prints exactly the dialect this include
+ * mounts.
+ */
+export const entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr)
+
+const schema = entryListSchema
+
+const writable: Record<string, string> = {
+  '.json': 'application/json',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml',
+}
+
+const supported = new Set(Object.keys(writable))
+
+const WRITE_RETRY_LIMIT = 10
+const WRITE_RETRY_DELAY_MS = 50
+
+function retryableWriteError(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException | null)?.code
+  return code === 'EACCES' || code === 'EBUSY' || code === 'EPERM'
+}
+
+/**
+ * Apply patch lists to an entry list — THE patch semantics of this include,
+ * shared by mounting (`applyPatches`) and offline config tooling
+ * (`dsh --dump-config`) so a dump can never drift from what boots. The input
+ * is never mutated and the result is always detached from it (even with no
+ * patches): patching or mounting shared entry objects would bake earlier
+ * values into the cached parse, so repeated application (config hot-reloads)
+ * could never revert a removed or changed patch. Inserted entries are indexed
+ * as they are added, so a later patch in the same list can target a row an
+ * earlier patch inserted. A patch that matches nothing warns and is skipped.
+ * @param data - the parsed entry list (JSON-safe plain data).
+ * @param patches - the patch list to apply, in order.
+ * @param warn - sink for skipped-patch diagnostics (printf-style, `%C` = code).
+ * @returns a detached entry list with every applicable patch applied.
+ */
+export function applyEntryPatches(
+  data: EntryOptions[],
+  patches: PatchOptions[] | undefined,
+  warn: (message: string, ...args: any[]) => void,
+): EntryOptions[] {
+  data = structuredClone(data)
+  if (!patches?.length) return data
+
+  const entryMap = new Map<string, EntryOptions>()
+  const buildMap = (entries: EntryOptions[]) => {
+    for (const entry of entries) {
+      if (entry.id) entryMap.set(entry.id, entry)
+      if (entry.group && Array.isArray(entry.config)) {
+        buildMap(entry.config)
+      }
+    }
+  }
+  buildMap(data)
+
+  for (const patch of patches) {
+    const { id, insert, name, ...overrides } = patch
+
+    if (insert) {
+      if (id) {
+        const target = entryMap.get(id)
+        if (!target) {
+          warn('patch insert: entry %C not found', id)
+          continue
+        }
+        if (!target.group) {
+          warn('patch insert: entry %C is not a group', id)
+          continue
+        }
+        if (!Array.isArray(target.config)) target.config = []
+        target.config.push(...insert)
+      } else {
+        data.push(...insert)
+      }
+      // Index what this patch added so a LATER patch in the same list can
+      // target it. Patch lists compose one layer per source (each bundle
+      // layer, then the user's, then `--patch` overlays), and a layer must be
+      // able to configure or disable a row an earlier layer inserted; without
+      // this, inserted rows were silently unpatchable.
+      buildMap(insert)
+      continue
+    }
+
+    if (!id) {
+      warn('patch: id is required for non-insert patches')
+      continue
+    }
+
+    const target = entryMap.get(id)
+    if (!target) {
+      warn('patch: entry %C not found', id)
+      continue
+    }
+
+    if (name && name !== target.name) {
+      warn('patch: name mismatch for %C (expected %C, got %C), skipping', id, target.name, name)
+      continue
+    }
+
+    for (const [key, value] of Object.entries(overrides)) {
+      if (key === 'id') continue
+      target[key] = value
+    }
+  }
+
+  return data
+}
+
+type ConfigUpdateStage = 'read' | 'parse' | 'validate'
+
+interface ReadCandidate {
+  content: string
+  data: EntryOptions[]
+}
+
+class ConfigFileError extends Error {
+  constructor(public readonly stage: ConfigUpdateStage, path: string, cause: unknown) {
+    super(`failed to ${stage} config file ${path}`, { cause })
+    this.name = 'ConfigFileError'
+  }
+}
+
+/** Runtime patch applied to entries loaded from an included config file. */
+export interface PatchOptions {
+  id?: string
+  insert?: EntryOptions[]
+  name?: string
+  config?: any
+  group?: boolean | null
+  disabled?: boolean | null
+  inject?: any
+  intercept?: any
+  isolate?: any
+  [key: string]: any
+}
+
+/** Config namespace for the file-backed include loader. */
+export namespace Include {
+  /** Config for a file-backed loader subtree. */
+  export interface Config {
+    /** YAML or JSON path resolved from `ctx.baseUrl`. */
+    path: string
+    /** Entry list written when the file does not already exist. */
+    initial?: any[]
+    /** Runtime patches applied after reading the file. */
+    patches?: PatchOptions[]
+    /** Enables loader apply/reload/unload logs for this subtree. */
+    enableLogs?: boolean
+  }
+}
+
+/** Loader entry tree backed by a YAML or JSON file. */
+export class Include extends EntryTree {
+  static inject = ['loader']
+
+  /**
+   * Resolve Include's own options while preserving nested entry expressions.
+   * @param ctx - the Include plugin context.
+   * @param config - the raw Include config.
+   * @returns resolved Include options with `initial` and `patches` untouched.
+   */
+  static [EntryConfigResolver](ctx: Context, config: Include.Config): Include.Config {
+    const { initial, patches, ...own } = config
+    return {
+      ...interpolate(ctx, own),
+      ...(initial === undefined ? {} : { initial }),
+      ...(patches === undefined ? {} : { patches }),
+    }
+  }
+
+  public filename: string
+  private type?: string
+  private readonly: boolean
+  private content?: string
+  private data?: EntryOptions[]
+  private writeTask?: NodeJS.Timeout | undefined
+  private pendingWrite?: EntryOptions[]
+  private writeQueue: Promise<void> = Promise.resolve()
+  private applyQueue: Promise<unknown> = Promise.resolve()
+
+  constructor(ctx: Context, public config: Include.Config) {
+    super(ctx)
+    this.enableLogs = config.enableLogs ?? ctx.fiber.entry?.parent.tree.enableLogs ?? false
+    this.filename = fileURLToPath(new URL(this.config.path, this.ctx.baseUrl))
+    const ext = extname(this.filename)
+    if (!supported.has(ext)) {
+      throw new Error(`extension "${ext}" not supported`)
+    }
+    this.type = writable[ext]
+    this.readonly = !this.type
+    this.ctx.baseUrl = new URL('.', pathToFileURL(this.filename)).href
+
+    ctx.on('internal/update', async (config, _, next) => {
+      if (config.path !== this.config.path) return next()
+      await this.enqueue(async () => {
+        const data = this.applyPatches(this.data!, config.patches)
+        await this.root.update(data)
+        this.config = config
+      })
+    })
+  }
+
+  /**
+   * Serialize one child-tree mutation behind every earlier one. The group's
+   * transactional `update` is not reentrant: two concurrent applies (the init
+   * apply racing an HMR-triggered refresh from the watcher's initial scan)
+   * interleave create and rollback on the same entries and strand the include
+   * fiber without settling, so every apply path funnels through this queue.
+   * A predecessor's failure is its own caller's outcome and never gates the
+   * next task.
+   */
+  private enqueue<T>(task: () => Promise<T>): Promise<T> {
+    const run = this.applyQueue.then(task, task)
+    this.applyQueue = run.then(() => {}, () => {})
+    return run
+  }
+
+  private async checkAccess() {
+    if (!this.type) return
+    try {
+      await access(this.filename, constants.W_OK)
+    } catch {
+      this.readonly = true
+    }
+  }
+
+  private async read(forced = false): Promise<ReadCandidate | undefined> {
+    let content: string
+    try {
+      content = await readFile(this.filename, 'utf8')
+    } catch (error) {
+      throw new ConfigFileError('read', this.filename, error)
+    }
+    if (!forced && this.content === content) return
+    let data: any
+    try {
+      if (this.type === 'application/yaml') {
+        data = yaml.load(content, { schema })
+      } else if (this.type === 'application/json') {
+        data = JSON.parse(content)
+      } else {
+        const module = await import(/* @vite-ignore */ this.filename)
+        data = module.default || module
+      }
+    } catch (error) {
+      throw new ConfigFileError('parse', this.filename, error)
+    }
+    if (!Array.isArray(data)) {
+      throw new ConfigFileError('validate', this.filename, new TypeError('config file must be a top-level array'))
+    }
+    return { content, data }
+  }
+
+  private applyPatches(data: EntryOptions[], patches?: PatchOptions[]): EntryOptions[] {
+    return applyEntryPatches(data, patches, (message, ...args) => {
+      this.ctx.root.logger?.('loader').warn(message, ...args)
+    })
+  }
+
+  async* [Service.init]() {
+    let candidate: ReadCandidate
+    try {
+      candidate = (await this.read(true))!
+    } catch (error) {
+      if (!(error instanceof ConfigFileError) || error.stage !== 'read' || (error.cause as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error
+      if (this.config.initial) {
+        await this._writeFile(this.config.initial as any)
+        candidate = (await this.read(true))!
+      } else {
+        throw new Error(`config file not found: ${this.filename}`)
+      }
+    }
+
+    yield () => this.stop()
+    await this.apply(candidate)
+  }
+
+  async stop() {
+    await this.root.stop()
+    await this.flushWrite()
+  }
+
+  /**
+   * Re-read the file and transactionally refresh child entries when content changed.
+   * @returns a promise resolving after the new tree commits, or immediately when unchanged.
+   * @throws when reading, parsing, validation, application, or rollback fails; the last good tree remains active when rollback succeeds.
+   */
+  async refresh() {
+    // Read inside the queue so the changed-content check compares against the
+    // predecessor's committed state, not a mid-apply snapshot.
+    await this.enqueue(async () => {
+      const candidate = await this.read()
+      if (!candidate) return
+      await this._apply(candidate)
+    })
+  }
+
+  private apply(candidate: ReadCandidate) {
+    return this.enqueue(() => this._apply(candidate))
+  }
+
+  private async _apply(candidate: ReadCandidate) {
+    const data = this.applyPatches(candidate.data, this.config.patches)
+    await this.root.update(data)
+    this.content = candidate.content
+    this.data = candidate.data
+    await this.checkAccess()
+  }
+
+  private async _writeFile(config: EntryOptions[]) {
+    if (this.readonly) {
+      throw new Error(`cannot overwrite readonly config`)
+    }
+    if (this.type === 'application/yaml') {
+      this.content = yaml.dump(config, { schema })
+    } else if (this.type === 'application/json') {
+      this.content = JSON.stringify(config, null, 2)
+    }
+    await writeFile(this.filename + '.tmp', this.content!)
+    for (let retry = 0; ; retry++) {
+      try {
+        await rename(this.filename + '.tmp', this.filename)
+        return
+      } catch (error) {
+        if (!retryableWriteError(error) || retry >= WRITE_RETRY_LIMIT) throw error
+        await delay((retry + 1) * WRITE_RETRY_DELAY_MS)
+      }
+    }
+  }
+
+  private writeFile(config: EntryOptions[]) {
+    clearTimeout(this.writeTask)
+    this.pendingWrite = config
+    this.writeTask = setTimeout(() => {
+      void this.flushWrite()
+    }, 0)
+  }
+
+  private flushWrite(): Promise<void> {
+    clearTimeout(this.writeTask)
+    this.writeTask = undefined
+    const config = this.pendingWrite
+    this.pendingWrite = undefined
+    if (config === undefined) return this.writeQueue
+    const run = this.writeQueue.then(
+      () => this._writeFile(config),
+      () => this._writeFile(config),
+    )
+    this.writeQueue = run
+    void run.catch((error) => {
+      this.ctx.root.logger?.('loader').warn('failed to write config file %C', this.filename)
+      this.ctx.root.logger?.('loader').warn(error)
+    })
+    return run
+  }
+
+  /** Schedule a write of the current root entry data. */
+  write() {
+    this.context.emit('loader/config-update')
+    return this.writeFile(this.root.data)
+  }
+}
+
+export default Include