@zhin.js/config-yaml 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+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,66 @@
+# @zhin.js/config-yaml
+
+下一代 Runtime 的可选 YAML `ConfigDocumentPort`。它在 YAML AST 上应用结构化 patch，保留未触及节点的注释、引号、anchor/alias、`${ENV}` 字符串、键顺序、缩进和换行风格，并通过同目录临时文件加原子 rename 持久化。
+
+> 当前包属于 `feature/next` 绿地实现，版本仍为 `0.0.0` 且未作为稳定 API 发布。
+
+## 为什么独立成包
+
+`@zhin.js/runtime` 只定义 `ConfigDocumentPort`，默认生产闭包不包含 YAML parser。需要 `config.yml` 的 Root 单独安装本包；只使用内存配置或其他配置存储时无需承担这项依赖。
+
+本包只增加 `yaml@2.9.0`，不依赖 Vite、编译器、CSS 工具或 native/wasm 模块。包含 Runtime 的完整生产安装仍受 5MB 门禁约束。
+
+## 使用
+
+```ts
+import { YamlConfigDocument } from '@zhin.js/config-yaml';
+import { RootRuntime } from '@zhin.js/runtime';
+
+const runtime = new RootRuntime({
+  projectRoot: process.cwd(),
+  modules,
+  environment: { name: 'production', mode: 'production', platform: 'node' },
+  config: new YamlConfigDocument('config.yml'),
+});
+
+await runtime.start();
+await runtime.patchConfig([{
+  op: 'set',
+  path: ['plugins', 'reports', 'retries'],
+  value: 5,
+}]);
+```
+
+Root 先用组合后的 JSON Schema 校验候选文档，再执行受影响 Plugin forest 的 shadow setup。只有两步都成功，YAML transaction 才作为 generation handoff 的最后一个 participant 提交；CAS 前失败会恢复原始文件并撤销新 generation Resource。
+
+## 文档事务
+
+`read()` 返回原始对象和基于文件字节的 SHA-256 revision。`prepare()` 只构造候选 AST，不写文件。`commit()` 在写入前再次检查 revision，随后使用同目录临时文件和原子 rename；`rollback()` 也先确认文件仍是本事务写入的 revision，避免覆盖外部编辑。
+
+以下情况抛出明确错误：
+
+- `ConfigDocumentParseError`：YAML 无法解析，或根节点不是 mapping。
+- `ConfigDocumentConflictError`：read/prepare/commit/rollback 之间文件被其他写入者修改。
+- `ConfigPatchPathError`：删除文档根或使用 `__proto__` 等不安全路径。
+
+环境变量表达式目前按普通字符串保留。环境 overlay 和 secret 解析属于独立 Root Resource，不由 YAML adapter 隐式展开。
+
+## 保真边界
+
+未触及 AST 节点会保留 comment、scalar style、anchor/alias 与顺序。被替换 scalar 沿用 `yaml` AST 节点已有的样式；新增节点使用 `yaml` 的稳定默认输出。整个文档沿用原文件检测到的缩进宽度与 LF/CRLF 风格。
+
+原子 rename 防止读取到半写文件，但不替代跨主机分布式锁。多个进程写同一文件时，revision 冲突会拒绝后写者，调用方应重新读取后再规划 patch。
+
+## 开发验证
+
+```bash
+pnpm --filter @zhin.js/config-yaml test
+pnpm --filter @zhin.js/config-yaml build
+pnpm --filter @zhin.js/config-yaml check:size
+```
+
+## 相关文档
+
+- [Plugin Runtime](../runtime/README.md)
+- [Config、Discovery 与 HMR](../../../docs/architecture/target-implementation/config-discovery-hmr.md)
+- [Greenfield Bootstrap 状态](../../../docs/architecture/target-implementation/greenfield-bootstrap.md)

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './yaml-config-document.js';

package/lib/index.js

@@ -0,0 +1 @@
+export * from './yaml-config-document.js';

package/lib/yaml-config-document.d.ts

@@ -0,0 +1,19 @@
+import { type ConfigDocumentPort, type ConfigDocumentSnapshot, type ConfigPatch, type PreparedConfigDocument } from '@zhin.js/runtime';
+export declare class YamlConfigDocumentError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class ConfigDocumentParseError extends YamlConfigDocumentError {
+    readonly file: string;
+    readonly issues: readonly string[];
+    constructor(file: string, issues: readonly string[]);
+}
+export declare class ConfigDocumentConflictError extends YamlConfigDocumentError {
+    readonly file: string;
+    constructor(file: string);
+}
+export declare class YamlConfigDocument implements ConfigDocumentPort {
+    readonly file: string;
+    constructor(file: string);
+    read(): Promise<ConfigDocumentSnapshot>;
+    prepare(current: ConfigDocumentSnapshot, patches: readonly ConfigPatch[]): Promise<PreparedConfigDocument>;
+}

package/lib/yaml-config-document.js

@@ -0,0 +1,170 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { ConfigPatchPathError, } from '@zhin.js/runtime';
+import { parseDocument } from 'yaml';
+export class YamlConfigDocumentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'YamlConfigDocumentError';
+    }
+}
+export class ConfigDocumentParseError extends YamlConfigDocumentError {
+    file;
+    issues;
+    constructor(file, issues) {
+        super(`Cannot parse YAML config ${file}:\n${issues.map((issue) => `- ${issue}`).join('\n')}`);
+        this.file = file;
+        this.issues = issues;
+        this.name = 'ConfigDocumentParseError';
+    }
+}
+export class ConfigDocumentConflictError extends YamlConfigDocumentError {
+    file;
+    constructor(file) {
+        super(`YAML config changed since it was read: ${file}`);
+        this.file = file;
+        this.name = 'ConfigDocumentConflictError';
+    }
+}
+export class YamlConfigDocument {
+    file;
+    constructor(file) {
+        this.file = resolve(file);
+    }
+    async read() {
+        const source = await readFile(this.file, 'utf8');
+        return snapshot(parse(this.file, source), source);
+    }
+    async prepare(current, patches) {
+        const source = await readFile(this.file, 'utf8');
+        assertRevision(this.file, source, current.revision);
+        const document = parseYaml(this.file, source);
+        for (const patch of patches)
+            applyPatch(document, patch);
+        const candidateSource = stringify(document, source);
+        const candidate = parse(this.file, candidateSource);
+        const fileMode = (await stat(this.file)).mode;
+        return new PreparedYamlConfigDocument(this.file, source, current.revision, candidateSource, candidate, fileMode);
+    }
+}
+class PreparedYamlConfigDocument {
+    document;
+    #file;
+    #previousSource;
+    #previousRevision;
+    #candidateSource;
+    #mode;
+    #candidateRevision;
+    #state = 'prepared';
+    #committedSnapshot;
+    constructor(file, previousSource, previousRevision, candidateSource, document, mode) {
+        this.#file = file;
+        this.#previousSource = previousSource;
+        this.#previousRevision = previousRevision;
+        this.#candidateSource = candidateSource;
+        this.#mode = mode;
+        this.document = document;
+        this.#candidateRevision = revision(candidateSource);
+    }
+    async commit() {
+        if (this.#state === 'committed')
+            return requireSnapshot(this.#committedSnapshot);
+        if (this.#state === 'rolled-back') {
+            throw new YamlConfigDocumentError('A rolled-back YAML config transaction cannot commit');
+        }
+        const source = await readFile(this.#file, 'utf8');
+        assertRevision(this.#file, source, this.#previousRevision);
+        // Build every result before rename so successful replacement is the last
+        // fallible step visible to callers.
+        const committed = Object.freeze({
+            document: this.document,
+            revision: this.#candidateRevision,
+        });
+        await atomicReplace(this.#file, this.#candidateSource, this.#mode);
+        this.#committedSnapshot = committed;
+        this.#state = 'committed';
+        return committed;
+    }
+    async rollback() {
+        if (this.#state !== 'committed') {
+            if (this.#state === 'prepared')
+                this.#state = 'rolled-back';
+            return;
+        }
+        const source = await readFile(this.#file, 'utf8');
+        assertRevision(this.#file, source, this.#candidateRevision);
+        await atomicReplace(this.#file, this.#previousSource, this.#mode);
+        this.#state = 'rolled-back';
+    }
+}
+function parseYaml(file, source) {
+    const document = parseDocument(source, { prettyErrors: true, strict: true });
+    if (document.errors.length > 0) {
+        throw new ConfigDocumentParseError(file, Object.freeze(document.errors.map((error) => error.message)));
+    }
+    return document;
+}
+function parse(file, source) {
+    const value = parseYaml(file, source).toJS({ maxAliasCount: 100 });
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ConfigDocumentParseError(file, ['The document root must be a mapping']);
+    }
+    return Object.freeze(value);
+}
+function applyPatch(document, patch) {
+    assertPath(patch.path);
+    if (patch.path.length === 0) {
+        if (patch.op === 'remove') {
+            throw new ConfigPatchPathError('The config document root cannot be removed');
+        }
+        if (!patch.value || typeof patch.value !== 'object' || Array.isArray(patch.value)) {
+            throw new ConfigPatchPathError('The config document root must be an object');
+        }
+        document.contents = document.createNode(structuredClone(patch.value));
+        return;
+    }
+    if (patch.op === 'set')
+        document.setIn(patch.path, structuredClone(patch.value));
+    else
+        document.deleteIn(patch.path);
+}
+function assertPath(path) {
+    for (const segment of path) {
+        if (!segment || segment === '__proto__' || segment === 'prototype' || segment === 'constructor') {
+            throw new ConfigPatchPathError(`Unsafe config path segment: ${segment || '<empty>'}`);
+        }
+    }
+}
+function stringify(document, original) {
+    const indentation = original.match(/^( +)\S/mu)?.[1].length ?? 2;
+    const source = document.toString({ indent: indentation, lineWidth: 0 });
+    return original.includes('\r\n') ? source.replaceAll('\n', '\r\n') : source;
+}
+function snapshot(document, source) {
+    return Object.freeze({ document, revision: revision(source) });
+}
+function revision(source) {
+    return createHash('sha256').update(source).digest('hex');
+}
+function assertRevision(file, source, expected) {
+    if (revision(source) !== expected)
+        throw new ConfigDocumentConflictError(file);
+}
+async function atomicReplace(file, source, mode) {
+    const temporary = `${basename(file)}.${process.pid}.${randomUUID()}.tmp`;
+    const target = resolve(dirname(file), temporary);
+    try {
+        await writeFile(target, source, { mode });
+        await rename(target, file);
+    }
+    catch (error) {
+        await rm(target, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function requireSnapshot(value) {
+    if (!value)
+        throw new Error('Committed YAML transaction has no snapshot');
+    return value;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@zhin.js/config-yaml",
+  "version": "1.0.0",
+  "description": "Comment-preserving YAML ConfigDocument adapter for the Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "yaml": "2.9.0",
+    "@zhin.js/runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/config-yaml"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/config-yaml/tests",
+    "check:size": "node ../../../scripts/check-plugin-runtime-install-size.mjs @zhin.js/config-yaml"
+  }
+}