@4fu/arbor-environment-dir 0.0.0-stage → 0.1.0

package/directory-environment.js

@@ -0,0 +1,830 @@
+/**
+ * The default `Environment`: one shared directory, mounted read-only into every
+ * window at `/env` (docs/environment.md).
+ *
+ * ```text
+ * <root>/env/skills/<name>/            a skill, with its scripts beside it
+ * <root>/env/mcp/<name>.json           an MCP server's configuration
+ * <root>/env/mcp/<name>/<name>.json    an MCP server that brought its own code
+ * <root>/env/services/<name>/svc.json  a service, beside its files
+ * <root>/env/settings.json             identity, rules, judge, model tiers
+ * <root>/revisions/<kind>/<name>/<n>/  one copy of every installed revision
+ * <root>/index.json                    the items and their revisions
+ * ```
+ *
+ * Each item has its own revision, so two windows changing different items never
+ * conflict. A draft is staged and validated before anything is replaced, so a
+ * refused `reload` changes nothing: an item is replaced as a whole, and a
+ * service that fails its health check is rolled back to the revision it had.
+ *
+ * The built-in skills ship with the framework and are seeded on first use. They
+ * are read-only: the model writes its own skills beside them.
+ */
+import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { arborError } from "@4fu/arbor-errors";
+import { StdioMcpServer } from "./mcp.js";
+/** What a window reads the environment at, which is mounted read-only. */
+const ENV_PREFIX = "/env";
+/** The built-in skills, seeded read-only on first use. */
+export const BUILTIN_SKILLS = ["arbor-skill", "arbor-mcp", "arbor-service", "arbor-settings"];
+/** The built-in skill that covers each kind, which every refusal names. */
+export const BUILTIN_SKILL_PATH = {
+    skill: "/env/skills/arbor-skill/SKILL.md",
+    mcp: "/env/skills/arbor-mcp/SKILL.md",
+    service: "/env/skills/arbor-service/SKILL.md",
+    settings: "/env/skills/arbor-settings/SKILL.md",
+};
+/** The one line an MCP server's item carries when its configuration says nothing. */
+const MCP_DESCRIPTION = "一个 MCP 服务器，它的函数在 code_exec 中调用。";
+/** The one line the settings item carries. */
+const SETTINGS_DESCRIPTION = "身份、通用规则、judge、模型分层和各项阈值。";
+/** The prefix an item's ref carries, one per kind. */
+const KIND_PREFIX = {
+    skill: "sk",
+    mcp: "mcp",
+    service: "svc",
+    settings: "set",
+};
+/** The spellings a model may use for a kind: `skill:deploy`, `sk:deploy`. */
+const KIND_ALIASES = {
+    skill: "skill",
+    sk: "skill",
+    mcp: "mcp",
+    server: "mcp",
+    service: "service",
+    svc: "service",
+    settings: "settings",
+    set: "settings",
+};
+export class DirectoryEnvironment {
+    /** What a window reads the environment at. */
+    mount;
+    /** The directory the environment lives in, which the host reads. */
+    directory;
+    root;
+    supervisor;
+    secretOf;
+    clock;
+    index = { revision: 0, items: [] };
+    /** Every environment revision, oldest first. */
+    log = [];
+    ready;
+    constructor(options) {
+        this.root = options.root;
+        this.mount = options.mount ?? ENV_PREFIX;
+        this.directory = join(options.root, "env");
+        this.supervisor = options.supervisor;
+        this.secretOf = options.secretOf;
+        this.clock = options.now ?? (() => Date.now());
+    }
+    async revision() {
+        return `e${(await this.read()).revision}`;
+    }
+    async list() {
+        return (await this.read()).items.map((entry) => itemOf(entry));
+    }
+    async history(item) {
+        await this.read();
+        if (item === undefined)
+            return [...this.log];
+        const wanted = itemKey(item);
+        return this.log.filter((revision) => revision.changes.some((change) => itemKey(change.item.ref) === wanted));
+    }
+    async settings() {
+        const index = await this.read();
+        const entry = index.items.find((one) => one.kind === "settings");
+        if (entry === undefined)
+            return undefined;
+        const text = await readText(join(this.root, entry.target));
+        if (text === null)
+            return undefined;
+        return JSON.parse(text);
+    }
+    async validate(drafts) {
+        await this.read();
+        const staged = await this.stage(drafts);
+        const items = [];
+        for (const draft of staged) {
+            const outcome = await this.check(draft);
+            items.push({ name: draft.name, ok: outcome.ok, ...(outcome.ok ? {} : { error: outcome.error }) });
+            await discard(draft);
+        }
+        return { ok: items.every((item) => item.ok), items };
+    }
+    async install(drafts, remove) {
+        const index = await this.read();
+        const removals = [...(remove ?? [])];
+        if (drafts.length === 0 && removals.length === 0) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.empty",
+                message: "reload：install 和 remove 至少要给一个",
+                nextAction: "给出 install 或 remove 之一。",
+            });
+        }
+        // Everything is staged and checked before anything is replaced, so a refusal
+        // leaves the environment exactly as it was.
+        const staged = await this.stage(drafts);
+        const checked = await this.checkAll(staged);
+        const leaving = this.leaving(removals, index);
+        this.checkRevisions(checked, index);
+        const time = this.clock();
+        const changes = [];
+        for (const draft of checked) {
+            const previous = index.items.find((entry) => entry.kind === draft.draft.kind && entry.name === draft.draft.name);
+            const entry = await this.apply(draft, previous, time);
+            const at = index.items.findIndex((one) => one.kind === entry.kind && one.name === entry.name);
+            if (at === -1)
+                index.items.push(entry);
+            else
+                index.items[at] = entry;
+            changes.push({
+                change: previous === undefined ? "added" : "changed",
+                item: itemOf(entry),
+            });
+        }
+        for (const entry of leaving) {
+            await this.removeItem(entry);
+            index.items = index.items.filter((one) => one.ref !== entry.ref);
+            changes.push({ change: "removed", item: itemOf(entry) });
+        }
+        index.revision += 1;
+        const revision = {
+            ref: `e${index.revision}`,
+            previous: this.log.at(-1)?.ref ?? null,
+            time,
+            window: null,
+            changes,
+        };
+        this.log.push(revision);
+        await this.write(index);
+        return revision;
+    }
+    async remove(items) {
+        return this.install([], items);
+    }
+    async delta(since) {
+        const index = await this.read();
+        const from = revisionNumber(since);
+        const current = `e${index.revision}`;
+        if (from >= index.revision)
+            return { revision: current, previous: since, items: [] };
+        // What the window had when it opened, walked from the log rather than
+        // guessed: an item revision and an environment revision are different
+        // numbers.
+        const had = new Set();
+        const latest = new Map();
+        for (const revision of this.log) {
+            const at = revisionNumber(revision.ref);
+            for (const change of revision.changes) {
+                const key = itemKey(change.item.ref);
+                if (at <= from) {
+                    if (change.change === "removed")
+                        had.delete(key);
+                    else
+                        had.add(key);
+                    continue;
+                }
+                latest.set(key, { change: change.change, item: change.item });
+            }
+        }
+        const items = [];
+        for (const key of [...latest.keys()].sort()) {
+            const change = latest.get(key);
+            if (change === undefined)
+                continue;
+            const now = index.items.find((entry) => itemKey(entry.ref) === key);
+            const was = had.has(key);
+            // An item added and removed again inside the window never reached it, so
+            // it is not named at all.
+            if (now === undefined && !was)
+                continue;
+            if (now === undefined) {
+                items.push({ change: "removed", item: change.item });
+                continue;
+            }
+            if (was && change.change === "added")
+                continue;
+            items.push({ change: was ? "changed" : "added", item: itemOf(now) });
+        }
+        return { revision: current, previous: since, items };
+    }
+    /** Start every installed service again, after a host restart. */
+    async resume() {
+        const index = await this.read();
+        if (this.supervisor === undefined)
+            return;
+        for (const entry of index.items) {
+            if (entry.kind !== "service" || entry.spec === undefined)
+                continue;
+            await this.supervisor.start(entry.spec).catch(() => { });
+        }
+    }
+    async call(server, fn, args) {
+        const index = await this.read();
+        const entry = index.items.find((one) => one.kind === "mcp" && one.name === server);
+        if (entry === undefined) {
+            throw arborError({
+                code: "not_found",
+                rule: "env.notfound",
+                message: `环境：没有 MCP 服务器 ${server}`,
+                nextAction: "用 env.list 查看当前安装的服务器。",
+                details: { server },
+            });
+        }
+        const spec = entry.spec;
+        if (spec === undefined || spec.command === "" || spec.dir === undefined) {
+            throw arborError({
+                code: "unavailable",
+                rule: "mcp.url.unsupported",
+                message: `环境：MCP 服务器 ${server} 是一个远程地址，本实现只调用 stdio 服务器`,
+                nextAction: "把该服务器换成本地 command 形式，或给主机换一个 Environment 实现。",
+                details: { server },
+            });
+        }
+        // A server is started for the call and stopped after it: an MCP server is a
+        // capability, not a resident service, so it holds no pipe open on the host
+        // between calls. A server that died is started again by the next call.
+        const running = await this.serve(entry.name, spec);
+        try {
+            return await running.call(fn, args);
+        }
+        finally {
+            await running.close();
+        }
+    }
+    /** Start one MCP server for one call. */
+    async serve(name, spec) {
+        return StdioMcpServer.start({
+            name,
+            dir: spec.dir,
+            command: spec.command,
+            ...(spec.args === undefined ? {} : { args: spec.args }),
+            ...(spec.secrets === undefined ? {} : { secrets: spec.secrets }),
+            ...(spec.env === undefined ? {} : { env: spec.env }),
+            ...(this.secretOf === undefined ? {} : { secretOf: this.secretOf }),
+        });
+    }
+    // ---- staging and validation --------------------------------------------
+    /** Copy every draft into the staging area, so nothing is read in place. */
+    async stage(drafts) {
+        const staged = [];
+        for (const draft of drafts) {
+            const from = isAbsolute(draft.path) ? draft.path : resolve(process.cwd(), draft.path);
+            const info = await stat(from).catch(() => null);
+            if (info === null) {
+                throw arborError({
+                    code: "not_found",
+                    rule: "env.draft.missing",
+                    message: `环境：草稿 ${draft.path} 不存在`,
+                    nextAction: "用 workspace.ls 查看工作区里的草稿路径。",
+                    details: { path: draft.path },
+                });
+            }
+            const target = join(this.root, "staging", `${staged.length}-${draft.kind}-${safeName(draft.name)}`);
+            await rm(target, { recursive: true, force: true });
+            if (info.isDirectory()) {
+                await cp(from, target, { recursive: true });
+                staged.push({ ...draft, path: target, directory: true });
+                continue;
+            }
+            await mkdir(target, { recursive: true });
+            await cp(from, join(target, `${draft.name}.json`));
+            staged.push({ ...draft, path: target, directory: false });
+        }
+        return staged;
+    }
+    /** Validate every staged draft, or refuse with the first one that failed. */
+    async checkAll(staged) {
+        const checked = [];
+        for (const draft of staged) {
+            const outcome = await this.check(draft);
+            if (outcome.ok) {
+                checked.push({ draft, ...outcome.value });
+                continue;
+            }
+            for (const one of staged)
+                await discard(one);
+            throw arborError({
+                code: outcome.error.code,
+                rule: outcome.error.rule,
+                message: outcome.error.message,
+                ...(outcome.error.nextAction === undefined ? {} : { nextAction: outcome.error.nextAction }),
+                ...(outcome.error.details === undefined ? {} : { details: outcome.error.details }),
+            });
+        }
+        return checked;
+    }
+    /** One staged draft: its description, and what its kind needs beyond that. */
+    async check(draft) {
+        try {
+            if (draft.kind === "skill")
+                return { ok: true, value: { description: await this.checkSkill(draft) } };
+            if (draft.kind === "settings") {
+                await this.checkSettings(draft);
+                return { ok: true, value: { description: SETTINGS_DESCRIPTION } };
+            }
+            if (draft.kind === "mcp")
+                return { ok: true, value: await this.checkMcp(draft) };
+            return { ok: true, value: await this.checkService(draft) };
+        }
+        catch (error) {
+            return { ok: false, error: errorInfo(error, draft) };
+        }
+    }
+    /** A skill parses: a title, then one line that says what it is for. */
+    async checkSkill(draft) {
+        const text = await readText(join(draft.path, "SKILL.md"));
+        if (text === null) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.skill",
+                message: `环境：草稿 ${draft.name} 中没有 SKILL.md`,
+                nextAction: "读 /env/skills/arbor-skill/SKILL.md 的「结构」一节，按它补上 SKILL.md。",
+                details: { name: draft.name },
+            });
+        }
+        const lines = text.split("\n").map((line) => line.trim());
+        if (lines[0]?.startsWith("# ") !== true) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.skill",
+                message: `环境：技能 ${draft.name} 的第一行不是一级标题`,
+                nextAction: "读 /env/skills/arbor-skill/SKILL.md 的「结构」一节，把第一行写成 # 标题。",
+                details: { name: draft.name },
+            });
+        }
+        const description = lines.slice(1).find((line) => line !== "") ?? "";
+        if (description === "") {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.skill",
+                message: `环境：技能 ${draft.name} 没有一行说明`,
+                nextAction: "读 /env/skills/arbor-skill/SKILL.md 的「结构」一节，在标题下写一行说明。",
+                details: { name: draft.name },
+            });
+        }
+        return description;
+    }
+    /** The settings parse into the settings shape. */
+    async checkSettings(draft) {
+        const text = await readText(join(draft.path, `${draft.name}.json`));
+        if (text === null) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.settings",
+                message: `环境：草稿 ${draft.path} 中没有 ${draft.name}.json`,
+                nextAction: "读 /env/skills/arbor-settings/SKILL.md 的「结构」一节，按它写设置文件。",
+                details: { name: draft.name },
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.settings",
+                message: `环境：设置文件解析失败：${error instanceof Error ? error.message : String(error)}`,
+                nextAction: "读 /env/skills/arbor-settings/SKILL.md 的「结构」一节，修正 JSON 后重新调用 reload。",
+            });
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.settings",
+                message: "环境：设置文件必须是一个 JSON 对象",
+                nextAction: "读 /env/skills/arbor-settings/SKILL.md 的「结构」一节，按字段写成一个对象。",
+            });
+        }
+    }
+    /**
+     * An MCP server starts and lists its functions. It runs from the staged
+     * directory, so a draft that brought its own code is validated exactly as it
+     * will run once installed.
+     */
+    async checkMcp(draft) {
+        const config = await readJson(join(draft.path, `${draft.name}.json`));
+        if (config === null) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.mcp",
+                message: `环境：MCP 服务器 ${draft.name} 的配置缺失或不是 JSON`,
+                nextAction: "读 /env/skills/arbor-mcp/SKILL.md 的「结构」一节，按它写配置文件。",
+                details: { name: draft.name },
+            });
+        }
+        const command = stringField(config, "command");
+        const description = stringField(config, "description") || MCP_DESCRIPTION;
+        if (command === "" && stringField(config, "url") === "") {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.mcp",
+                message: `环境：MCP 服务器 ${draft.name} 的配置中没有 command 或 url`,
+                nextAction: "读 /env/skills/arbor-mcp/SKILL.md 的「结构」一节，补上 command 或 url。",
+                details: { name: draft.name },
+            });
+        }
+        const spec = {
+            name: draft.name,
+            command,
+            ...(stringsField(config, "args") === undefined ? {} : { args: stringsField(config, "args") }),
+            ...(stringsField(config, "secrets") === undefined ? {} : { secrets: stringsField(config, "secrets") }),
+            ...(objectField(config, "env") === undefined ? {} : { env: objectField(config, "env") }),
+        };
+        if (command === "") {
+            // A server already running elsewhere: its shape is all this
+            // implementation can check without reaching the network.
+            return { description, spec };
+        }
+        const server = await StdioMcpServer.start({
+            dir: draft.path,
+            ...spec,
+            ...(this.secretOf === undefined ? {} : { secretOf: this.secretOf }),
+        }).catch((error) => {
+            throw arborError({
+                code: "unavailable",
+                rule: "env.draft.mcp",
+                message: `环境：MCP 服务器 ${draft.name} 启动失败`,
+                nextAction: "读 /env/skills/arbor-mcp/SKILL.md 的「自测」一节，把服务器在本窗口工作区里跑通后再调用 reload。",
+                details: { name: draft.name, upstream: error instanceof Error ? error.message : String(error) },
+                cause: error,
+            });
+        });
+        try {
+            return { description, functions: await server.functions(), spec };
+        }
+        finally {
+            await server.close();
+        }
+    }
+    /** A service's configuration parses, and it is started when it installs. */
+    async checkService(draft) {
+        const config = await readJson(join(draft.path, "svc.json"));
+        if (config === null) {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.service",
+                message: `环境：服务 ${draft.name} 的配置缺失或不是 JSON`,
+                nextAction: "读 /env/skills/arbor-service/SKILL.md 的「结构」一节，按它写 svc.json。",
+                details: { name: draft.name },
+            });
+        }
+        const command = stringField(config, "command");
+        if (command === "") {
+            throw arborError({
+                code: "invalid_input",
+                rule: "env.draft.service",
+                message: `环境：服务 ${draft.name} 的配置中没有 command`,
+                nextAction: "读 /env/skills/arbor-service/SKILL.md 的「结构」一节，补上 command。",
+                details: { name: draft.name },
+            });
+        }
+        if (this.supervisor === undefined) {
+            throw arborError({
+                code: "unavailable",
+                rule: "env.supervisor.absent",
+                message: `环境：本主机没有配置服务监督器，无法安装服务 ${draft.name}`,
+                nextAction: "移除该服务项，或在配置了监督器的主机上安装它。",
+                details: { name: draft.name },
+            });
+        }
+        const healthCheck = config.healthCheck;
+        const restart = config.restart;
+        const quota = config.quota;
+        const args = stringsField(config, "args");
+        const ports = numbersField(config, "ports");
+        const secrets = stringsField(config, "secrets");
+        const env = objectField(config, "env");
+        return {
+            description: stringField(config, "description") || `一个常驻服务：${command}`,
+            spec: {
+                name: draft.name,
+                command,
+                ...(args === undefined ? {} : { args }),
+                ...(ports === undefined ? {} : { ports }),
+                ...(healthCheck === undefined ? {} : { healthCheck }),
+                ...(secrets === undefined ? {} : { secrets }),
+                ...(restart === undefined ? {} : { restart }),
+                ...(quota === undefined ? {} : { quota }),
+                ...(env === undefined ? {} : { env }),
+            },
+        };
+    }
+    // ---- applying a change --------------------------------------------------
+    /**
+     * Replace one item as a whole, then start a service and wait for its health
+     * check. A service that never becomes healthy is rolled back to the revision
+     * it had, so a refused `reload` changes nothing.
+     */
+    async apply(draft, previous, time) {
+        const revision = (previous?.revision ?? 0) + 1;
+        const entry = {
+            ref: `${KIND_PREFIX[draft.draft.kind]}:${draft.draft.name}@${revision}`,
+            kind: draft.draft.kind,
+            name: draft.draft.name,
+            description: draft.description,
+            revision,
+            time,
+            ...(draft.functions === undefined ? {} : { functions: draft.functions }),
+            target: targetOf(draft.draft),
+        };
+        if (draft.draft.kind === "skill")
+            entry.path = `${this.mount}/skills/${draft.draft.name}`;
+        if (draft.draft.kind === "mcp") {
+            entry.path = draft.draft.directory
+                ? `${this.mount}/mcp/${draft.draft.name}/${draft.draft.name}.json`
+                : `${this.mount}/mcp/${draft.draft.name}.json`;
+        }
+        if (draft.draft.kind === "service") {
+            entry.path = `${this.mount}/services/${draft.draft.name}/svc.json`;
+            entry.spec = { ...draft.spec, dir: join(this.root, entry.target) };
+        }
+        if (draft.draft.kind === "settings")
+            entry.path = `${this.mount}/settings.json`;
+        if (draft.draft.kind === "mcp" && draft.spec !== undefined) {
+            entry.spec = {
+                ...draft.spec,
+                // The command runs in the item's own directory, so a server that brought
+                // its code finds it where it installed it.
+                dir: draft.draft.directory
+                    ? join(this.root, entry.target)
+                    : dirname(join(this.root, entry.target)),
+            };
+        }
+        // The revision the item had is kept before it is replaced, so a failed
+        // install can put it back.
+        if (previous !== undefined)
+            await this.keepRevision(previous);
+        await copyTree(configOf(draft.draft), join(this.root, entry.target));
+        if (draft.draft.kind === "service" && this.supervisor !== undefined && entry.spec !== undefined) {
+            try {
+                await this.supervisor.start(entry.spec);
+            }
+            catch (error) {
+                await this.rollback(entry, previous);
+                throw arborError({
+                    code: "unavailable",
+                    rule: "env.draft.service",
+                    message: `环境：服务 ${draft.draft.name} 没有通过健康检查`,
+                    nextAction: "用 services.logs 查看服务的输出，修好后重新调用 reload。",
+                    details: { name: draft.draft.name, upstream: error instanceof Error ? error.message : String(error) },
+                    cause: error,
+                });
+            }
+        }
+        await this.keepRevision(entry);
+        return entry;
+    }
+    /** Put the revision an item had back, after a failed install. */
+    async rollback(entry, previous) {
+        const target = join(this.root, entry.target);
+        await rm(target, { recursive: true, force: true });
+        if (previous === undefined)
+            return;
+        await copyTree(join(this.root, "revisions", KIND_PREFIX[previous.kind], previous.name, `${previous.revision}`), target);
+    }
+    /** Stop a service and remove its files. */
+    async removeItem(entry) {
+        if (entry.kind === "service" && this.supervisor !== undefined) {
+            await this.supervisor.stop(entry.name).catch(() => { });
+        }
+        await rm(join(this.root, entry.target), { recursive: true, force: true });
+    }
+    /** Keep one copy of an installed revision, so a revert can install it again. */
+    async keepRevision(entry) {
+        await copyTree(join(this.root, entry.target), join(this.root, "revisions", KIND_PREFIX[entry.kind], entry.name, `${entry.revision}`));
+    }
+    /**
+     * The revision check (docs/environment.md#changing-the-environment): a draft
+     * is based on the revision its window read, and another window that installed
+     * a newer one since refuses the call, so the model merges and calls again.
+     */
+    checkRevisions(checked, index) {
+        for (const draft of checked) {
+            const installed = index.items.find((entry) => entry.kind === draft.draft.kind && entry.name === draft.draft.name);
+            const read = draft.draft.copiedFrom;
+            if (installed === undefined || read === undefined || installed.revision <= read)
+                continue;
+            throw arborError({
+                code: "conflict",
+                rule: "env.draft.stale",
+                message: `环境：${installed.ref} 已被其他窗口更新到第 ${installed.revision} 版，草稿基于旧的 ${read} 版`,
+                nextAction: `读 ${BUILTIN_SKILL_PATH[draft.draft.kind]} 的「修订冲突」一节，把新旧内容合并进草稿，再重新调用 reload。`,
+                details: { item: installed.ref, revision: installed.revision, read },
+            });
+        }
+    }
+    /** The items a `reload({ remove })` names, or a refusal naming what is missing. */
+    leaving(removals, index) {
+        const leaving = [];
+        for (const wanted of removals) {
+            const key = itemKey(wanted);
+            const entry = index.items.find((one) => itemKey(one.ref) === key);
+            if (entry === undefined) {
+                throw arborError({
+                    code: "not_found",
+                    rule: "env.notfound",
+                    message: `环境：没有环境项 ${wanted}`,
+                    nextAction: "用 env.list 查看当前的环境项和它们的引用。",
+                    details: { item: wanted },
+                });
+            }
+            if (entry.builtin === true) {
+                throw arborError({
+                    code: "refused",
+                    rule: "env.readonly",
+                    message: `环境：${entry.ref} 是框架内置的技能，只读`,
+                    nextAction: "内置技能只读；要改就写一个自己的技能，用 env.list 看它的路径。",
+                    details: { item: entry.ref },
+                });
+            }
+            if (!leaving.includes(entry))
+                leaving.push(entry);
+        }
+        return leaving;
+    }
+    // ---- the index ----------------------------------------------------------
+    /** The index, seeded with the built-in skills on first use. */
+    async read() {
+        if (this.ready === undefined) {
+            this.ready = this.load().catch((error) => {
+                this.ready = undefined;
+                throw error;
+            });
+        }
+        await this.ready;
+        return this.index;
+    }
+    async load() {
+        const text = await readText(join(this.root, "index.json"));
+        if (text !== null) {
+            const parsed = JSON.parse(text);
+            this.index = { revision: parsed.revision ?? 0, items: parsed.items ?? [] };
+            const log = await readText(join(this.root, "revisions.json"));
+            this.log = log === null ? [] : JSON.parse(log);
+        }
+        await this.seedBuiltins();
+        await this.write(this.index);
+    }
+    /** Copy the built-in skills in, read-only, when they are not there yet. */
+    async seedBuiltins() {
+        const here = fileURLToPath(new URL(".", import.meta.url));
+        for (const name of BUILTIN_SKILLS) {
+            if (this.index.items.some((entry) => entry.name === name))
+                continue;
+            const target = join(this.root, "env", "skills", name);
+            await mkdir(dirname(target), { recursive: true });
+            await cp(join(here, "skills", name), target, { recursive: true });
+            const text = await readText(join(target, "SKILL.md"));
+            const lines = (text ?? "").split("\n").map((line) => line.trim());
+            const entry = {
+                ref: `sk:${name}@1`,
+                kind: "skill",
+                name,
+                description: lines.slice(1).find((line) => line !== "") ?? "",
+                path: `${this.mount}/skills/${name}`,
+                revision: 1,
+                time: this.clock(),
+                builtin: true,
+                target: join("env", "skills", name),
+            };
+            this.index.items.push(entry);
+            await this.keepRevision(entry);
+        }
+    }
+    async write(index) {
+        await mkdir(this.root, { recursive: true });
+        await writeFile(join(this.root, "index.json"), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+        await writeFile(join(this.root, "revisions.json"), `${JSON.stringify(this.log, null, 2)}\n`, "utf8");
+    }
+}
+/** One index entry as every other layer sees it. */
+function itemOf(entry) {
+    return {
+        ref: entry.ref,
+        kind: entry.kind,
+        name: entry.name,
+        description: entry.description,
+        ...(entry.path === undefined ? {} : { path: entry.path }),
+        revision: entry.revision,
+        time: entry.time,
+        ...(entry.builtin === undefined ? {} : { builtin: entry.builtin }),
+        ...(entry.functions === undefined ? {} : { functions: entry.functions }),
+    };
+}
+/** `sk:deploy@4` and `skill:deploy` both address the item `sk:deploy`. */
+function itemKey(ref) {
+    const match = /^(sk|mcp|svc|set|skill|server|service|settings):([^@]+)/.exec(ref);
+    if (match === null)
+        return ref;
+    const kind = KIND_ALIASES[match[1] ?? ""] ?? "skill";
+    return `${KIND_PREFIX[kind]}:${match[2] ?? ""}`;
+}
+/** An environment revision's number, so the log can be walked. */
+function revisionNumber(ref) {
+    return Number(/^e(\d+)$/.exec(ref)?.[1] ?? 0);
+}
+/**
+ * Where an item's own files live, relative to the root. An MCP server that
+ * brought its own code keeps the whole directory, so its command runs beside it.
+ */
+function targetOf(draft) {
+    if (draft.kind === "settings")
+        return join("env", `${draft.name}.json`);
+    if (draft.kind === "skill")
+        return join("env", "skills", draft.name);
+    if (draft.kind === "service")
+        return join("env", "services", draft.name);
+    return draft.directory ? join("env", "mcp", draft.name) : join("env", "mcp", `${draft.name}.json`);
+}
+/** The file a staged draft holds its configuration in. */
+function configOf(draft) {
+    return draft.directory ? draft.path : join(draft.path, `${draft.name}.json`);
+}
+/** Copy a file or a whole directory onto a path, replacing what was there. */
+async function copyTree(from, to) {
+    const info = await stat(from).catch(() => null);
+    if (info === null)
+        return;
+    if (info.isDirectory()) {
+        await rm(to, { recursive: true, force: true });
+        await mkdir(dirname(to), { recursive: true });
+        await cp(from, to, { recursive: true });
+        return;
+    }
+    await mkdir(dirname(to), { recursive: true });
+    await cp(from, to);
+}
+/** Clean up one staged draft, whether it was installed or refused. */
+async function discard(draft) {
+    await rm(draft.path, { recursive: true, force: true }).catch(() => { });
+}
+function errorInfo(error, draft) {
+    const info = error;
+    if (info.rule === undefined) {
+        return {
+            code: "invalid_input",
+            rule: "env.draft",
+            message: `环境：草稿 ${draft.name} 无效：${error instanceof Error ? error.message : String(error)}`,
+            nextAction: "修正草稿后重新调用 reload。",
+        };
+    }
+    return {
+        code: info.code ?? "invalid_input",
+        rule: info.rule,
+        message: info.message ?? "",
+        ...(info.nextAction === undefined ? {} : { nextAction: info.nextAction }),
+        ...(info.details === undefined ? {} : { details: info.details }),
+    };
+}
+async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function readJson(path) {
+    const text = await readText(path);
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringField(config, key) {
+    const value = config[key];
+    return typeof value === "string" ? value : "";
+}
+function stringsField(config, key) {
+    const value = config[key];
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((item) => typeof item === "string");
+}
+function numbersField(config, key) {
+    const value = config[key];
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((item) => typeof item === "number" && Number.isFinite(item));
+}
+function objectField(config, key) {
+    const value = config[key];
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function safeName(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, "_");
+}