dsh-plugin-manager-companion 0.1.0

package/dist/official.js

@@ -0,0 +1,205 @@
+/**
+ * 官方适配层：本插件与 DSH 官方能力之间的**唯一**接口。
+ *
+ * 归属：A 类·重写（新代码；旧仓库没有这一层，它直接自建了 REST + patch 写入）。
+ * 官方复用：pluginManager 服务（当前环境写操作）、host-plugin-inventory
+ *   （运行时事实）、app-boot 的 profile 读取与 operations 的 pnpm 通道。
+ * 前提检查：旧仓库假设"官方只有只读清单，所以必须自建写路径"。0.1.6 之后
+ *   该前提消失——官方提供了完整的当前环境写面。本层的职责就是让其余模块
+ *   **不必知道**官方长什么样，同时把"官方不可用"如实降级而不是崩溃。
+ *
+ * 三条硬约束（写在类型与运行时里，不靠约定）：
+ *   1. 当前环境的写操作只走官方 —— 本模块不实现任何文件写入。
+ *   2. 服务名绝不用 'pluginManager' —— 官方已占用，同名注册会让整个
+ *      profile 起不来（旧仓库实测踩过）。
+ *   3. 任何官方能力缺失都降级为"能力不可用 + 原因"，绝不静默假装成功。
+ */
+import { configState } from "./settings.js";
+/**
+ * 官方能力的探针。
+ *
+ * 为什么用 `ctx.get(name)` 而不是声明式 `inject`：
+ * 官方 pluginManager 行在 base bundle 里带
+ * `disabled: !!js "!ctx.get('profileContext')"`，即**没有 profile 时它不装配**。
+ * 若我们声明式 inject 它，本插件会永远停在 PENDING 而不做任何事——用户看到
+ * 一个"装了但没反应"的插件，且没有任何可读的错误。探针 + 降级让插件在
+ * 任何宿主上都能加载并如实说明自己不能做什么。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 当前可用能力；缺失原因在 `missing` 里逐条列出。
+ */
+export function probeOfficialCapabilities(ctx) {
+    const missing = [];
+    const profileContext = ctx.get('profileContext');
+    const profileBacked = profileContext !== undefined;
+    // 官方服务名是 'pluginManager'；我们只读它，绝不提供同名服务。
+    const managerService = ctx.get('pluginManager');
+    const manager = managerService !== undefined;
+    if (!manager) {
+        missing.push(profileBacked
+            ? '官方 pluginManager 服务未装配：本环境无法执行安装/启停（请确认 @deepseek-ai/dsh-plugin-manager 行未被禁用）'
+            : '当前进程不是以 dsh profile 启动的，官方插件管理能力不适用');
+    }
+    const inventory = ctx.get('loader') !== undefined;
+    if (!inventory)
+        missing.push('Loader 服务不可用：运行时事实类检查已跳过');
+    // 配置面降级也要出现在这里：用户看到的是"我改的设置没生效"，必须能在同一处读到原因。
+    const config = configState();
+    if (!config.writable)
+        missing.push('配置不可写（' + (config.detail ?? config.reason ?? '原因未知') + '）');
+    return {
+        profileBacked,
+        manager,
+        inventory,
+        environmentName: profileBacked ? profileContext.name : null,
+        missing,
+    };
+}
+/** 官方能力调用失败的统一错误。 */
+export class OfficialUnavailableError extends Error {
+    capability;
+    /**
+     * @param capability - 缺失的能力名（用于 UI 分组）。
+     * @param reason - 面向用户的原因说明。
+     */
+    constructor(capability, reason) {
+        super(reason);
+        this.capability = capability;
+        this.name = 'OfficialUnavailableError';
+    }
+}
+/**
+ * 我们真正调用过的 pluginManager 方法（缺任何一个都让这项能力不可用）。
+ *
+ * 为什么是显式清单而不是"把接口上的方法全列一遍"：接口是契约面，方法清单是**实际使用**面。
+ * 只有后者才能在官方改方法时给出准确的"我们用到的那一个不见了"，也不会因为官方增删
+ * 我们没用的方法而误报。清单与 OfficialManagerLike 必须同步（下面有编译期校验）。
+ */
+const REQUIRED_MANAGER_METHODS = [
+    'inspect', 'setPluginEnabled', 'setBundleEnabled', 'installBundle', 'removeBundle',
+];
+/** 取该对象上名为 name 的成员是否可调用（含原型链上的方法）。 */
+function isCallableMethod(service, name) {
+    let current = service;
+    while (current !== null) {
+        const value = current[name];
+        if (value !== undefined)
+            return typeof value === 'function';
+        current = Object.getPrototypeOf(current);
+    }
+    return false;
+}
+/**
+ * 取官方 pluginManager，缺失时抛出可读错误。
+ *
+ * 每个调用点都必须经过它——这样"官方不可用"永远以一个**具名错误**出现，
+ * 而不是 `undefined.listBundles is not a function`。
+ *
+ * 两层校验：服务存在（ctx.get）与**我们用到的方法存在**。第二层是 2026-09-19 补的：
+ * 官方改/删一个 Remote 方法时，用户原本看到调用点的 TypeError（读不懂）；现在得到的是
+ * "缺哪个方法"+"所以这项能力不可用"。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 官方管理器（结构式视图）。
+ * @throws {OfficialUnavailableError} 官方管理器未装配，或缺少我们调用到的方法时。
+ */
+export function requireManager(ctx) {
+    const service = ctx.get('pluginManager');
+    if (service === undefined) {
+        throw new OfficialUnavailableError('pluginManager', probeOfficialCapabilities(ctx).missing[0]
+            ?? '官方 pluginManager 服务不可用');
+    }
+    const absent = REQUIRED_MANAGER_METHODS.filter(name => !isCallableMethod(service, name));
+    if (absent.length > 0) {
+        throw new OfficialUnavailableError('pluginManager', '官方 pluginManager 缺少我们用到的' + (absent.length > 1 ? '这些方法：' : '方法：') + absent.join('、')
+            + '：说明官方依赖的接口与预期不一致（官方改过或删过这个方法），'
+            + '因此"当前环境的插件管理"这项能力不可用——升级/回退 @deepseek-ai/dsh-plugin-manager，'
+            + '或改用官方 CLI（dsh plugin）完成同一步操作。');
+    }
+    return service;
+}
+/**
+ * 读运行时事实。
+ *
+ * 优先走官方 `readPluginInventory`（它对 Loader 的投影有自己的一致性保证），
+ * 拿不到时退回直接读 `ctx.loader.entries()`——用户明确要求"最大化利用能力，
+ * 但同时保证不出错"，所以两条路都要有，且**降级是显式的**。
+ *
+ * 返回的 `source` 让诊断页能如实标注数据来源：官方投影口径与直接读 Loader
+ * 口径在字段上一致，但前者会跳过 group 行，后者不会。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 运行时条目与数据来源；两者都不可用时 `entries` 为空且给出原因。
+ */
+export async function readRuntimeInventory(ctx) {
+    // 官方投影优先。
+    try {
+        const mod = await import('@deepseek-ai/dsh-host-plugin-inventory');
+        const snapshot = await mod.readPluginInventory(ctx);
+        return { entries: snapshot.entries, agentPresets: snapshot.agentPresets, source: 'official' };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        // 降级：直接读 Loader，拿得到就标注来源为 loader。
+        const loader = ctx.get('loader');
+        if (loader?.entries === undefined) {
+            return { entries: [], agentPresets: undefined, source: 'unavailable', reason };
+        }
+        try {
+            const entries = [];
+            for (const raw of loader.entries()) {
+                const entry = raw;
+                if (entry.options?.group)
+                    continue;
+                entries.push({
+                    entryId: String(entry.id ?? ''),
+                    moduleName: String(entry.options?.name ?? ''),
+                    enabled: entry.disabled !== true,
+                    fiberPhase: fiberPhaseOf(entry.fiber?.state),
+                });
+            }
+            return { entries, agentPresets: undefined, source: 'loader' };
+        }
+        catch (loaderError) {
+            return {
+                entries: [], agentPresets: undefined, source: 'unavailable',
+                reason: reason + '; loader fallback failed: ' + (loaderError instanceof Error ? loaderError.message : String(loaderError)),
+            };
+        }
+    }
+}
+/**
+ * Cordis FiberState 到官方相位标签的映射。
+ *
+ * 数值取自 `@deepseek-ai/cordis` 的 `FiberState` 枚举（PENDING=0 …
+ * UNLOADING=5）。旧仓库自己定义了一套映射且与本表不一致，是实际缺陷；
+ * 这里逐项对齐官方 `plugin-inventory` 的 `FIBER_PHASE`。
+ *
+ * @param state - fiber.state 的原始数值；undefined 表示无存活 fiber。
+ * @returns 官方相位标签，或 null。
+ */
+export function fiberPhaseOf(state) {
+    switch (state) {
+        case 0: return 'pending';
+        case 1: return 'loading';
+        case 2: return 'active';
+        case 3: return 'failed';
+        case 4: return null; // DISPOSED
+        case 5: return 'unloading';
+        default: return null;
+    }
+}
+/**
+ * 官方能力缺失时是否应该继续。
+ *
+ * 只读检查（诊断、盘点）在能力缺失时**继续**，但把缺失记进报告的 `skipped`；
+ * 写操作必须**失败**，因为静默跳过写会让用户以为改了而实际没改。
+ *
+ * @param capabilities - 探针结果。
+ * @returns 可执行的只读检查项与不可执行的原因。
+ */
+export function readOnlyAvailability(capabilities) {
+    return capabilities.inventory
+        ? { canReadRuntime: true }
+        : { canReadRuntime: false, reason: 'Loader 服务不可用，运行时检查无法执行' };
+}

package/dist/paths.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 基础层：Harness home / profile 路径、manifest 读取、安全校验、全局互斥队列。
+ * 本模块不 import 任何兄弟模块，是其余一切的地基。
+ *
+ * 归属：A 类·重写（旧 src/paths.ts 仅作意图参考，未复制代码）。
+ * 官方复用：ctx.profileContext（当前环境事实）、readProfileManifest。
+ * 前提检查：旧实现靠扫描 process.argv 猜"当前 profile"，脆弱且有历史 bug
+ *   （issue #1：nvm 下 argv[1] 是脚本路径，被当成 profile 名）。官方
+ *   0.1.6 提供 ctx.profileContext.name —— 直接、权威、无需猜测。
+ *   本模块把"当前环境"改为注入式：由 apply() 传入官方事实，探测仅作兜底。
+ */
+import type { ManifestField } from './types.ts';
+/** 本包名（用于行 id、缓存目录、自识别）。 */
+export declare const OUR_PACKAGE_NAME = "dsh-plugin-manager-companion";
+/** 本插件的 Loader 行 id。**绝不用 'plugin-manager'**——官方 base bundle 已占用该 id。 */
+export declare const OUR_ROW_ID = "dsh-plugin-manager-companion";
+/** 解析 Harness home（DSH_HOME 优先，否则 ~/.dsh）。 */
+export declare function dshHome(): string;
+/** profiles 根目录。 */
+export declare function profilesRoot(): string;
+/**
+ * 环境名安全规则。
+ * `.` / `..` 会逃出 profiles 根（join(profiles,'..') === dshHome），
+ * 旧实现在这里被删过整个 Harness home，必须保留此校验。
+ */
+export declare function isSafeEnvironmentName(name: string): boolean;
+/** 解析一个环境的目录，拒绝路径穿越。 */
+export declare function environmentDir(name: string): string;
+/** 环境 manifest 的解析结果。 */
+export interface EnvironmentManifest {
+    /** `dsh.profile.bundles` 层栈；读不懂时为空数组，**必须**配合 unknownFields 判断。 */
+    readonly bundles: readonly string[];
+    /** 直接依赖名列表；读不懂时为空数组，**必须**配合 unknownFields 判断。 */
+    readonly dependencies: readonly string[];
+    /** 原始解析对象，供诊断读取任意字段。 */
+    readonly raw: Record<string, unknown>;
+    /** 无法解析（JSON 坏掉）时的原因；成功时为 undefined。 */
+    readonly broken?: string;
+    /**
+     * 这份 manifest 里我们**读不出来**的派生字段（缺省 = 全部读得出来）。
+     *
+     * 存在的理由：这一整轮都在反对"把不知道说成知道"。读取器原本会把两种完全不同的
+     * 事实读成同一个结果（空数组）：
+     *   · 确实没有声明层栈 / 确实没有依赖 → 空数组是**事实**；
+     *   · 官方把 `dsh.profile.bundles` 改名、或把 `dependencies` 写成数组 → 空数组是**假阴性**
+     *     （后者还会被读成一个名叫 "0" 的依赖：Object.keys(['a']) === ['0']）。
+     * 现在后者进这份清单（配 unknownReason），调用方据此少说那句话。
+     */
+    readonly unknownFields?: readonly ManifestField[];
+    /** 读不出来的原因（面向用户的一句话）；全部读得出来时为 undefined。 */
+    readonly unknownReason?: string;
+}
+/**
+ * 读取一个环境的 manifest。
+ *
+ * 与旧实现的差别：**解析失败不再静默返回空**。旧实现在 manifest 损坏时
+ * 返回 `{}`，让"零依赖零 bundle"看起来像真实状态，掩盖了真正的问题。
+ * 这里把失败原因显式带回，交给诊断层报告。
+ *
+ * 同一条原则也适用于"格式读不懂"：官方若改了 `dsh.profile.bundles` 的名字或位置，
+ * 旧写法会读出空数组且不报错——诊断会把"我不知道"说成"这个环境没有层栈"。
+ * 现在这种形态返回 `unknownFields` + `unknownReason`（见字段注释）：**按字段**表达，
+ * 以后再加派生字段不需要第三个布尔。
+ *
+ * @param dir - 环境目录。
+ * @returns 解析结果；**读派生字段前先看 unknownFields**。
+ */
+export declare function readEnvironmentManifest(dir: string): EnvironmentManifest;
+/** 一个环境的 patch 文件路径。 */
+export declare function environmentPatchPath(dir: string): string;
+export declare function enqueueMutation<T>(task: () => Promise<T>): Promise<T>;
+/**
+ * 当前运行环境的名称。
+ *
+ * 优先官方事实：`ctx.profileContext.name`（由 apply 注入）。
+ * 兜底：解析 argv 的 `--profile <name>`。
+ * 两者都拿不到时返回 null——调用方必须把它当作"未知"而非"没有环境"，
+ * 不做任何破坏性推断。
+ */
+export declare function detectCurrentEnvironmentName(argv?: readonly string[]): string | null;
+/** 官方内置环境：只读，环境管理不修改它们的层栈。 */
+export declare const BUILTIN_ENVIRONMENTS: readonly ["web", "headless"];
+/**
+ * 是否为官方内置环境。
+ *
+ * **必须大小写不敏感**：Windows 与 macOS 的默认文件系统大小写不敏感，
+ * 于是 `WEB` 与 `web` 指向**同一个目录**。若这里按精确大小写比较，
+ * `removeEnvironment('WEB')` 会删掉官方内置 web 环境的目录，还返回成功——
+ * 不可逆、且 Linux 门禁永远测不出来（审计 W-01，已在真 win32 Node 上复现）。
+ * 判据取"这个名字在这台机器上会落到哪个目录"，而不是"字符串是否逐字相等"。
+ *
+ * @param name - 环境名（调用方给的原始大小写）。
+ * @returns 是否指向官方内置环境。
+ */
+export declare function isBuiltinEnvironment(name: string): boolean;
+/**
+ * 两个环境名在这台机器上是否指向**同一个目录**。
+ *
+ * Windows 与 macOS 默认文件系统大小写不敏感：`web` 与 `WEB` 是同一个目录。
+ * 所有"拒绝在某个环境上操作"的护栏（当前环境不可删/不可停、内置环境只读）都必须用它，
+ * 否则非规范大小写就能绕过护栏——审计 W-01 是它的最坏形态（删掉官方内置环境并报成功）。
+ * Linux 是大小写敏感的，那里两个名字确实是两个目录，所以不能无条件忽略大小写。
+ *
+ * @param a - 环境名之一。
+ * @param b - 环境名之二。
+ * @returns 是否指向同一个环境。
+ */
+export declare function sameEnvironment(a: string | null, b: string | null): boolean;

package/dist/paths.js

@@ -0,0 +1,236 @@
+/**
+ * 基础层：Harness home / profile 路径、manifest 读取、安全校验、全局互斥队列。
+ * 本模块不 import 任何兄弟模块，是其余一切的地基。
+ *
+ * 归属：A 类·重写（旧 src/paths.ts 仅作意图参考，未复制代码）。
+ * 官方复用：ctx.profileContext（当前环境事实）、readProfileManifest。
+ * 前提检查：旧实现靠扫描 process.argv 猜"当前 profile"，脆弱且有历史 bug
+ *   （issue #1：nvm 下 argv[1] 是脚本路径，被当成 profile 名）。官方
+ *   0.1.6 提供 ctx.profileContext.name —— 直接、权威、无需猜测。
+ *   本模块把"当前环境"改为注入式：由 apply() 传入官方事实，探测仅作兜底。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+/** 本包名（用于行 id、缓存目录、自识别）。 */
+export const OUR_PACKAGE_NAME = 'dsh-plugin-manager-companion';
+/** 本插件的 Loader 行 id。**绝不用 'plugin-manager'**——官方 base bundle 已占用该 id。 */
+export const OUR_ROW_ID = 'dsh-plugin-manager-companion';
+/** 解析 Harness home（DSH_HOME 优先，否则 ~/.dsh）。 */
+export function dshHome() {
+    return process.env.DSH_HOME ?? join(homedir(), '.dsh');
+}
+/** profiles 根目录。 */
+export function profilesRoot() {
+    return join(dshHome(), 'profiles');
+}
+/**
+ * 环境名安全规则。
+ * `.` / `..` 会逃出 profiles 根（join(profiles,'..') === dshHome），
+ * 旧实现在这里被删过整个 Harness home，必须保留此校验。
+ */
+export function isSafeEnvironmentName(name) {
+    return /^[A-Za-z0-9._-]+$/.test(name) && name !== '.' && name !== '..' && name.length <= 120;
+}
+/** 解析一个环境的目录，拒绝路径穿越。 */
+export function environmentDir(name) {
+    if (!isSafeEnvironmentName(name)) {
+        throw new Error('unsafe environment name: ' + JSON.stringify(name));
+    }
+    const dir = join(profilesRoot(), name);
+    // 纵深防御：解析后的路径必须仍在 profiles 根之内。
+    if (!resolve(dir).startsWith(resolve(profilesRoot()) + sep)) {
+        throw new Error('unsafe environment name: ' + JSON.stringify(name));
+    }
+    return dir;
+}
+/**
+ * 读取一个环境的 manifest。
+ *
+ * 与旧实现的差别：**解析失败不再静默返回空**。旧实现在 manifest 损坏时
+ * 返回 `{}`，让"零依赖零 bundle"看起来像真实状态，掩盖了真正的问题。
+ * 这里把失败原因显式带回，交给诊断层报告。
+ *
+ * 同一条原则也适用于"格式读不懂"：官方若改了 `dsh.profile.bundles` 的名字或位置，
+ * 旧写法会读出空数组且不报错——诊断会把"我不知道"说成"这个环境没有层栈"。
+ * 现在这种形态返回 `unknownFields` + `unknownReason`（见字段注释）：**按字段**表达，
+ * 以后再加派生字段不需要第三个布尔。
+ *
+ * @param dir - 环境目录。
+ * @returns 解析结果；**读派生字段前先看 unknownFields**。
+ */
+export function readEnvironmentManifest(dir) {
+    const path = join(dir, 'package.json');
+    // 没有 manifest 文件 = 确实没有声明层栈（不是"读不懂"）。
+    if (!existsSync(path))
+        return { bundles: [], dependencies: [], raw: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        return {
+            bundles: [], dependencies: [], raw: {},
+            broken: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // 顶层不是对象：整份 manifest 都不可用——两个派生字段都读不出来（不是"为空"）。
+    if (!isRecord(parsed)) {
+        return {
+            bundles: [], dependencies: [], raw: {},
+            unknownFields: ['bundles', 'dependencies'],
+            unknownReason: 'package.json 的顶层不是 JSON 对象（是 ' + typeofOf(parsed) + '）',
+        };
+    }
+    const raw = parsed;
+    const unknownFields = [];
+    let reason;
+    // dependencies：只有普通对象才读得出依赖名。数组会走 Object.keys → ['0', '1']，
+    // 那是把 `dependencies: ['a']` 读成一个名叫 "0" 的依赖（同一族的假阴性）。
+    const depsValue = raw['dependencies'];
+    if (depsValue !== undefined && depsValue !== null && !isRecord(depsValue)) {
+        unknownFields.push('dependencies');
+        // 原因要指名是哪个字段、当前是什么类型——用户读了才知道该去看什么。
+        reason = 'dependencies 不是普通对象（当前类型：' + typeofOf(depsValue) + '），读不出依赖名';
+    }
+    const dependencies = isRecord(depsValue) ? Object.keys(depsValue) : [];
+    let bundles = [];
+    const dshValue = raw['dsh'];
+    if (dshValue === undefined) {
+        // dsh 整段缺失 = 这个环境没有声明 profile 段，层栈确实是空的。
+    }
+    else if (!isRecord(dshValue)) {
+        reason = 'dsh 段不是对象（官方可能改了这一层的结构）';
+        unknownFields.push('bundles');
+    }
+    else {
+        const profileValue = dshValue['profile'];
+        if (profileValue === undefined) {
+            // dsh.profile 缺失 = 没有声明层栈。
+        }
+        else if (!isRecord(profileValue)) {
+            reason = 'dsh.profile 不是对象（官方可能改了这一层的结构）';
+            unknownFields.push('bundles');
+        }
+        else {
+            const bundlesValue = profileValue['bundles'];
+            if (bundlesValue === undefined) {
+                // 关键区分：profile 段**存在**、但没有 bundles 字段、却带着别的键（例如 layers / list）
+                // ——这是"官方改了字段名"的形态，不是"没有声明层栈"。真空层栈也会写 bundles: []；
+                // 只有 profile 段完全为空 {} 才当成确定的空。
+                const unknownKeys = Object.keys(profileValue).filter(key => key !== 'bundles');
+                if (unknownKeys.length > 0) {
+                    reason = 'dsh.profile 里没有 bundles 字段，却有 ' + unknownKeys.join('、')
+                        + '（官方可能把层栈字段改名或移位了）';
+                    unknownFields.push('bundles');
+                }
+            }
+            else if (!Array.isArray(bundlesValue)) {
+                reason = 'dsh.profile.bundles 存在但不是数组（当前类型：' + typeofOf(bundlesValue) + '）';
+                unknownFields.push('bundles');
+            }
+            else if (!bundlesValue.every(item => typeof item === 'string')) {
+                reason = 'dsh.profile.bundles 里有非字符串项';
+                unknownFields.push('bundles');
+            }
+            else {
+                bundles = [...bundlesValue];
+            }
+        }
+    }
+    const fields = [...new Set(unknownFields)];
+    if (fields.length === 0)
+        return { bundles, dependencies, raw };
+    return {
+        bundles, dependencies, raw,
+        unknownFields: fields,
+        unknownReason: reason ?? '这份 manifest 的字段形态与预期不一致（原因未知）',
+    };
+}
+/** 是不是普通对象（数组与 null 都不算）。 */
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** 供原因文案使用的类型名。 */
+function typeofOf(value) {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+/** 一个环境的 patch 文件路径。 */
+export function environmentPatchPath(dir) {
+    return join(dir, 'cordis.patch.yml');
+}
+/**
+ * 全局变更互斥队列（进程内）。
+ *
+ * 环境变更操作串行执行：并发 pnpm 调用会各自基于自己的快照重写 manifest
+ * （丢依赖），并发文件编辑会丢行。进程内仅覆盖本进程；跨进程由官方
+ * withFileLock 在 package.json 上兜底。
+ */
+let mutationQueue = Promise.resolve();
+export function enqueueMutation(task) {
+    const run = mutationQueue.then(task, task);
+    mutationQueue = run.catch(() => { });
+    return run;
+}
+/**
+ * 当前运行环境的名称。
+ *
+ * 优先官方事实：`ctx.profileContext.name`（由 apply 注入）。
+ * 兜底：解析 argv 的 `--profile <name>`。
+ * 两者都拿不到时返回 null——调用方必须把它当作"未知"而非"没有环境"，
+ * 不做任何破坏性推断。
+ */
+export function detectCurrentEnvironmentName(argv = process.argv) {
+    const flagIndex = argv.indexOf('--profile');
+    if (flagIndex >= 0) {
+        const flagged = argv[flagIndex + 1];
+        if (flagged !== undefined && isSafeEnvironmentName(flagged))
+            return flagged;
+    }
+    return null;
+}
+/** 官方内置环境：只读，环境管理不修改它们的层栈。 */
+export const BUILTIN_ENVIRONMENTS = ['web', 'headless'];
+/**
+ * 是否为官方内置环境。
+ *
+ * **必须大小写不敏感**：Windows 与 macOS 的默认文件系统大小写不敏感，
+ * 于是 `WEB` 与 `web` 指向**同一个目录**。若这里按精确大小写比较，
+ * `removeEnvironment('WEB')` 会删掉官方内置 web 环境的目录，还返回成功——
+ * 不可逆、且 Linux 门禁永远测不出来（审计 W-01，已在真 win32 Node 上复现）。
+ * 判据取"这个名字在这台机器上会落到哪个目录"，而不是"字符串是否逐字相等"。
+ *
+ * @param name - 环境名（调用方给的原始大小写）。
+ * @returns 是否指向官方内置环境。
+ */
+export function isBuiltinEnvironment(name) {
+    const lower = name.toLowerCase();
+    return BUILTIN_ENVIRONMENTS.some((builtin) => builtin.toLowerCase() === lower);
+}
+/**
+ * 两个环境名在这台机器上是否指向**同一个目录**。
+ *
+ * Windows 与 macOS 默认文件系统大小写不敏感：`web` 与 `WEB` 是同一个目录。
+ * 所有"拒绝在某个环境上操作"的护栏（当前环境不可删/不可停、内置环境只读）都必须用它，
+ * 否则非规范大小写就能绕过护栏——审计 W-01 是它的最坏形态（删掉官方内置环境并报成功）。
+ * Linux 是大小写敏感的，那里两个名字确实是两个目录，所以不能无条件忽略大小写。
+ *
+ * @param a - 环境名之一。
+ * @param b - 环境名之二。
+ * @returns 是否指向同一个环境。
+ */
+export function sameEnvironment(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    if (a === b)
+        return true;
+    return caseInsensitiveFs() && a.toLowerCase() === b.toLowerCase();
+}
+/** 默认文件系统是否大小写不敏感（保守取向：这里判"是"只会让人被多拒绝一次，判"否"可能删错东西）。 */
+function caseInsensitiveFs() {
+    return process.platform === 'win32' || process.platform === 'darwin';
+}