@dsh-workbench/shared 0.3.5 → 0.3.7

package/dist/host/probe-verdict.js

@@ -0,0 +1,143 @@
+import { resolvePluginSource } from "./plugin-source";
+import { isNewerVersion } from "./release";
+export function evaluateUnit(list, unit, failure, command = "opencli", releases = new Map(), libs = []) {
+    const isPlugin = (item) => typeof item === "object" && item !== null;
+    const needs = unit.plugins ?? [];
+    const required = needs.flatMap((need) => need.commands ?? []);
+    const primary = needs[0]?.name;
+    if (failure !== undefined || list === undefined) {
+        return {
+            unit: unit.unit,
+            ...(primary === undefined ? {} : { plugin: primary }),
+            status: "unchecked",
+            required,
+            missing: [],
+            detail: failure ?? "探不动",
+            ...(libs.length === 0 ? {} : { libs }),
+        };
+    }
+    const plugins = list.filter(isPlugin);
+    const installed = new Map(plugins.map((item) => [String(item.name), item]));
+    const states = needs.map((need) => {
+        const hit = installed.get(need.name);
+        if (hit === undefined) {
+            const source = resolvePluginSource(need.installSource, process.env, {
+                command,
+                plugin: need.name,
+            });
+            return {
+                name: need.name,
+                status: "missing",
+                missing: [],
+                install: source.ok ? "ready" : source.problem,
+                command: source.ok ? source.line : pluginInstallCommand(need.name),
+            };
+        }
+        const available = new Set((Array.isArray(hit.commands) ? hit.commands : []).map(String));
+        const missing = (need.commands ?? []).filter((name) => !available.has(name));
+        const release = releases.get(need.name);
+        const behind = release?.latest !== undefined &&
+            isNewerVersion(release.latest, release.installed);
+        const commandsBehind = missing.length > 0;
+        const upgrade = behind && release?.latest !== undefined
+            ? upgradeLine(need, command, release.latest)
+            : undefined;
+        return {
+            name: need.name,
+            status: commandsBehind || behind ? "outdated" : "ok",
+            missing,
+            ...(release === undefined ? {} : { release }),
+            ...(commandsBehind || behind
+                ? {
+                    command: upgrade ??
+                        pluginUpdateCommand(need.name) ??
+                        pluginInstallCommand(need.name),
+                }
+                : {}),
+        };
+    });
+    const absent = states.filter((state) => state.status === "missing");
+    const outdated = states.filter((state) => state.status === "outdated");
+    const missing = states.flatMap((state) => state.missing);
+    const libMissing = libs.filter((state) => state.status === "missing");
+    const libMismatch = libs.filter((state) => state.status === "unsatisfied");
+    const libBehind = libs.filter((state) => state.status === "outdated");
+    const status = absent.length > 0 || libMissing.length > 0 || libMismatch.length > 0
+        ? "missing-plugin"
+        : missing.length > 0
+            ? "missing-commands"
+            : "ok";
+    const blocked = absent.find((state) => state.install !== "ready");
+    const install = absent.length === 0
+        ?
+            libMissing.length > 0 || libMismatch.length > 0
+                ? "ready"
+                : undefined
+        : blocked === undefined
+            ? "ready"
+            : blocked.install;
+    const fix = status === "missing-plugin"
+        ? install === "ready"
+            ? "install"
+            : undefined
+        : outdated.length > 0 || libBehind.length > 0
+            ? "update"
+            : undefined;
+    const first = absent[0] ?? outdated[0] ?? libMissing[0] ?? libMismatch[0] ?? libBehind[0];
+    const gaps = [...(missing.length === 0 ? [] : [`缺必需：${missing.join("、")}`])];
+    const newer = states.filter((state) => state.release?.latest !== undefined &&
+        isNewerVersion(state.release.latest, state.release.installed));
+    const versionText = newer.length === 0
+        ? ""
+        : `（源上有新版：${newer.map((state) => `${state.release?.installed ?? ""} → ${state.release?.latest ?? ""}`).join("、")}）`;
+    const absentNames = [
+        ...absent.map((state) => state.name),
+        ...libMissing.map((state) => state.name),
+    ];
+    const mismatchText = libMismatch.map((state) => {
+        const declared = unit.libs?.find((need) => need.name === state.name)?.version?.trim();
+        return `${state.name}（装的是 ${state.installed ?? "未知"}，声明要 ${declared === undefined || declared === "" ? "任意版本" : declared}）`;
+    });
+    return {
+        unit: unit.unit,
+        ...(primary === undefined ? {} : { plugin: primary }),
+        status,
+        required,
+        missing,
+        detail: absentNames.length > 0 || mismatchText.length > 0
+            ? [
+                ...(absentNames.length === 0
+                    ? []
+                    : [`${plugins.length} 个已装插件里没有 ${absentNames.join("、")}`]),
+                ...mismatchText,
+            ].join("；")
+            : `${needs.length} 份安装都在${gapsText(gaps)}${versionText}${libs.length === 0
+                ? ""
+                : `；交叉依赖：${libs.map((state) => `${state.name}${state.installed === undefined ? " 未装" : ` ${state.installed}`}`).join("、")}${libBehind.length === 0 ? "" : "（源上有新版）"}`}`,
+        ...(fix === undefined && first === undefined
+            ? {}
+            : { command: fix === "install" ? (absent[0] ?? first)?.command : first?.command }),
+        ...(fix === undefined ? {} : { fix }),
+        ...(install === undefined ? {} : { install }),
+        plugins: states,
+        ...(libs.length === 0 ? {} : { libs }),
+    };
+}
+export function gapsText(gaps) {
+    return gaps.length === 0 ? "" : `（${gaps.join("；")}）`;
+}
+export function pluginUpdateCommand(plugin) {
+    return plugin === undefined ? undefined : `opencli plugin update ${plugin}`;
+}
+export function pluginInstallCommand(plugin) {
+    return `opencli plugin install <${plugin ?? "插件"}源>`;
+}
+export function upgradeLine(need, command, latest) {
+    const source = resolvePluginSource(need.installSource, process.env, {
+        command,
+        plugin: need.name,
+        version: latest,
+        mode: "update",
+    });
+    return source.ok ? source.line : undefined;
+}

package/dist/host/shell-text.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
+export declare function quoteShellArg(value: unknown): string;
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
+export declare function tailLines(text: string | null | undefined, lines?: number): string;

package/dist/host/shell-text.js

@@ -0,0 +1,20 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
+export function quoteShellArg(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
+export function tailLines(text, lines = 6) {
+    const all = String(text ?? '')
+        .trim()
+        .split('\n');
+    return all.slice(-lines).join('\n');
+}

package/dist/host/tool-approval.d.ts

@@ -29,6 +29,7 @@ export interface ApprovalCall {
     readonly name?: string | undefined;
     readonly arguments?: unknown;
     readonly workspace?: string | undefined;
+    readonly session?: string | undefined;
 }
 export type ApprovalVerdict = {
     readonly kind: 'read';

package/dist/host/tool-scope.d.ts

@@ -0,0 +1,32 @@
+import type { DshPromptAssembly } from '@dsh-workbench/shared';
+export interface ScopedToolRegistry {
+    restrict(filter: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    }): () => void;
+}
+export interface ToolScopeAgent {
+    readonly ctx?: {
+        readonly tools?: ScopedToolRegistry | undefined;
+        get?<T = unknown>(name: string): T | undefined;
+    } | undefined;
+    readonly session?: {
+        readonly header?: {
+            readonly cwd?: string;
+        } | undefined;
+    } | undefined;
+}
+export interface ToolScopeOptions {
+    deniedTools(workspace: string | null): readonly string[];
+    logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+}
+export interface ToolScope {
+    apply(agent: unknown): void;
+    narrow(assembly: DshPromptAssembly, agent: unknown): DshPromptAssembly;
+    reapply(): void;
+    disposeAll(): void;
+}
+export declare function createToolScope(options: ToolScopeOptions): ToolScope;

package/dist/host/tool-scope.js

@@ -0,0 +1,84 @@
+function agentOf(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function workspaceOf(handle) {
+    const cwd = handle.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : null;
+}
+export function createToolScope(options) {
+    const applied = new WeakMap();
+    const seen = new Set();
+    function toolsOf(handle) {
+        const byProperty = handle.ctx?.tools;
+        if (byProperty?.restrict !== undefined)
+            return byProperty;
+        const byGet = handle.ctx?.get?.('tools');
+        return byGet?.restrict === undefined ? undefined : byGet;
+    }
+    function sync(handle) {
+        const tools = toolsOf(handle);
+        if (tools === undefined) {
+            options.logger?.warn?.('[dsh-workbench] 拿不到 agent 作用域的工具面：这次不收窄（下次再试）');
+            return;
+        }
+        const workspace = workspaceOf(handle);
+        const deny = [...options.deniedTools(workspace)];
+        const signature = `${workspace ?? ''}\u0000${deny.join(',')}`;
+        const previous = applied.get(handle);
+        if (previous !== undefined && previous.signature === signature)
+            return;
+        if (previous === undefined)
+            seen.add(new WeakRef(handle));
+        previous?.dispose();
+        if (deny.length === 0) {
+            options.logger?.info?.('[dsh-workbench] 这个工作区启用了全部套件：不收窄工具面');
+            applied.delete(handle);
+            return;
+        }
+        try {
+            applied.set(handle, { signature, dispose: tools.restrict({ deny }) });
+            options.logger?.info?.(`[dsh-workbench] 按工作区收窄工具面：${workspace ?? '(未知工作区)'} 里收起 ${deny.length} 个工具（${deny.join(', ')}）`);
+        }
+        catch (error) {
+            options.logger?.warn?.(`[dsh-workbench] 收窄工具面失败：${String(error)}`);
+        }
+    }
+    return {
+        apply(agent) {
+            const handle = agentOf(agent);
+            if (handle === undefined)
+                return;
+            sync(handle);
+        },
+        narrow(assembly, agent) {
+            const handle = agentOf(agent);
+            const tools = assembly?.tools;
+            if (handle === undefined || tools === undefined)
+                return assembly;
+            const deny = new Set(options.deniedTools(workspaceOf(handle)));
+            if (deny.size === 0)
+                return assembly;
+            const kept = tools.filter((tool) => !deny.has(tool.name));
+            return kept.length === tools.length ? assembly : { ...assembly, tools: kept };
+        },
+        reapply() {
+            for (const ref of [...seen]) {
+                const handle = ref.deref();
+                if (handle === undefined)
+                    seen.delete(ref);
+                else
+                    sync(handle);
+            }
+        },
+        disposeAll() {
+            for (const ref of [...seen]) {
+                const handle = ref.deref();
+                if (handle === undefined)
+                    continue;
+                applied.get(handle)?.dispose();
+                applied.delete(handle);
+            }
+            seen.clear();
+        },
+    };
+}

package/dist/host/unit-declaration.d.ts

@@ -0,0 +1,65 @@
+import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from '../api/unit.js';
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
+export declare const WORKBENCH_API_VERSION = 1;
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
+export declare const SUPPORTED_API_VERSIONS: readonly number[];
+/**
+ * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ */
+export interface UnitCardDeclaration {
+    readonly titleKey: string;
+    readonly order: number;
+}
+/**
+ * 清单里的一条工具声明：进 dsh 工具表的全名、会不会写，以及生成物里的键名。
+ */
+export interface UnitToolDeclaration {
+    readonly name: string;
+    readonly writes: boolean;
+    readonly key?: string;
+}
+/**
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ */
+export interface UnitDeclaration {
+    readonly apiVersion: number;
+    readonly unit: string;
+    readonly card: UnitCardDeclaration | null;
+    readonly tools: readonly UnitToolDeclaration[];
+    readonly host: UnitHostNeeds;
+    readonly env?: UnitEnvNeeds;
+}
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
+export declare const DECLARATION_KEYS: readonly string[];
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
+export declare const DECLARATION_REQUIRED_KEYS: readonly string[];
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
+export declare function declarationProblemsOf(subject: string, raw: unknown): readonly string[];
+/**
+ * 读一份清单的结果：要么带着规整过的声明与 manifest，要么只带一串问题。
+ */
+export interface DeclarationRead {
+    readonly declaration?: UnitDeclaration;
+    readonly manifest?: UnitManifest;
+    readonly problems: readonly string[];
+}
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
+export declare function readDeclaration(subject: string, raw: unknown): DeclarationRead;

package/dist/host/unit-declaration.js

@@ -0,0 +1,213 @@
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
+export const WORKBENCH_API_VERSION = 1;
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
+export const SUPPORTED_API_VERSIONS = [WORKBENCH_API_VERSION];
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
+export const DECLARATION_KEYS = [
+    'apiVersion',
+    'unit',
+    'card',
+    'tools',
+    'host',
+    'env',
+];
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
+export const DECLARATION_REQUIRED_KEYS = [
+    'apiVersion',
+    'unit',
+    'card',
+    'tools',
+    'host',
+];
+const CARD_KEYS = ['titleKey', 'order'];
+const TOOL_KEYS = ['name', 'writes', 'key'];
+const TOOL_KEY_SHAPE = /^[a-z][a-zA-Z0-9]*$/;
+const HOST_KEYS = ['inject', 'optional'];
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function outsideKeys(value, allowed) {
+    return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+function listOf(keys) {
+    return keys.map((key) => JSON.stringify(key)).join(' / ');
+}
+function stringArrayProblems(at, value) {
+    if (!Array.isArray(value))
+        return [`${at} 要是一串字符串，现在是 ${JSON.stringify(value)}`];
+    return value.flatMap((item, index) => text(item) === '' ? [`${at}[${index}] 不是非空字符串：${JSON.stringify(item)}`] : []);
+}
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
+export function declarationProblemsOf(subject, raw) {
+    if (!isRecord(raw))
+        return [`${subject}: dsh.workbench 不是一个对象 —— ${JSON.stringify(raw)}`];
+    const version = raw.apiVersion;
+    if (version === undefined) {
+        return [
+            `${subject}: dsh.workbench 没有 apiVersion —— 协议从 v${WORKBENCH_API_VERSION} 起，` +
+                `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块（ADR-0038 §2.3）`,
+        ];
+    }
+    if (!Number.isInteger(version) || !SUPPORTED_API_VERSIONS.includes(version)) {
+        return [
+            `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
+                `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）`,
+        ];
+    }
+    const problems = [];
+    const unknown = outsideKeys(raw, DECLARATION_KEYS);
+    if (unknown.length > 0) {
+        problems.push(`${subject}: dsh.workbench 里有协议 v${WORKBENCH_API_VERSION} 不认识的键 ${listOf(unknown)} —— ` +
+            `只有 ${listOf(DECLARATION_KEYS)}。（拼错的键会被外壳**静默忽略**：那句声明等于没写）`);
+    }
+    for (const key of DECLARATION_REQUIRED_KEYS) {
+        if (raw[key] === undefined) {
+            problems.push(`${subject}: dsh.workbench 缺 ${key}` +
+                (key === 'card' ? '（这个模块没有卡片就写 `"card": null`）' : ''));
+        }
+    }
+    const card = raw.card;
+    if (card !== undefined && card !== null) {
+        if (!isRecord(card)) {
+            problems.push(`${subject}: dsh.workbench.card 要么是对象、要么是 null，现在是 ${JSON.stringify(card)}`);
+        }
+        else {
+            const extra = outsideKeys(card, CARD_KEYS);
+            if (extra.length > 0) {
+                problems.push(`${subject}: dsh.workbench.card 里有不认的键 ${listOf(extra)} —— card 只有 ${listOf(CARD_KEYS)}` +
+                    `（卡片默认显不显示由运行期的面板配置决定，清单里没有这一位）`);
+            }
+            if (text(card.titleKey) === '') {
+                problems.push(`${subject}: dsh.workbench.card.titleKey 要是非空字符串（面板那一格的文案键）`);
+            }
+            if (typeof card.order !== 'number' || !Number.isFinite(card.order)) {
+                problems.push(`${subject}: dsh.workbench.card.order 要是数字，现在是 ${JSON.stringify(card.order)}`);
+            }
+        }
+    }
+    const tools = raw.tools;
+    if (tools !== undefined) {
+        if (!Array.isArray(tools)) {
+            problems.push(`${subject}: dsh.workbench.tools 要是一串声明，现在是 ${JSON.stringify(tools)}`);
+        }
+        else {
+            const seen = new Set();
+            const seenKeys = new Set();
+            tools.forEach((tool, index) => {
+                const at = `dsh.workbench.tools[${index}]`;
+                if (!isRecord(tool)) {
+                    problems.push(`${subject}: ${at} 要是对象，现在是 ${JSON.stringify(tool)}`);
+                    return;
+                }
+                const extra = outsideKeys(tool, TOOL_KEYS);
+                if (extra.length > 0) {
+                    problems.push(`${subject}: ${at} 里有不认的键 ${listOf(extra)} —— tools 只有 ${listOf(TOOL_KEYS)}`);
+                }
+                const name = text(tool.name);
+                if (name === '') {
+                    problems.push(`${subject}: ${at}.name 要是非空字符串`);
+                }
+                else if (seen.has(name)) {
+                    problems.push(`${subject}: ${at}.name「${name}」与前面那条撞了 —— 工具名会进 dsh 的工具表，不许重`);
+                }
+                else {
+                    seen.add(name);
+                }
+                if (typeof tool.writes !== 'boolean') {
+                    problems.push(`${subject}: ${at}.writes 要是 true / false（它是"这会写"的唯一声明，缺了审批无从认领）`);
+                }
+                if (tool.key !== undefined) {
+                    const key = text(tool.key);
+                    if (!TOOL_KEY_SHAPE.test(key)) {
+                        problems.push(`${subject}: ${at}.key 要是 lowerCamelCase 的标识符（如 \`sync\` / \`podLogs\`），` +
+                            `现在是 ${JSON.stringify(tool.key)} —— 它会变成生成物里的键名，所以不引号、不许带点或横线`);
+                    }
+                    else if (seenKeys.has(key)) {
+                        problems.push(`${subject}: ${at}.key「${key}」与前面那条撞了 —— 生成物里的键只能有一个`);
+                    }
+                    else {
+                        seenKeys.add(key);
+                    }
+                }
+            });
+        }
+    }
+    const host = raw.host;
+    if (host !== undefined) {
+        if (!isRecord(host)) {
+            problems.push(`${subject}: dsh.workbench.host 要是对象，现在是 ${JSON.stringify(host)}`);
+        }
+        else {
+            const extra = outsideKeys(host, HOST_KEYS);
+            if (extra.length > 0) {
+                problems.push(`${subject}: dsh.workbench.host 里有不认的键 ${listOf(extra)} —— host 只有 ${listOf(HOST_KEYS)}`);
+            }
+            if (host.inject === undefined) {
+                problems.push(`${subject}: dsh.workbench.host.inject 没写 —— 它声明这个模块要外壳的哪几个服务，` +
+                    `外壳靠它判"能不能挂"。一个都不要也要写 \`"inject": []\``);
+            }
+            else {
+                problems.push(...stringArrayProblems(`${subject}: dsh.workbench.host.inject`, host.inject));
+            }
+            if (host.optional !== undefined) {
+                problems.push(...stringArrayProblems(`${subject}: dsh.workbench.host.optional`, host.optional));
+            }
+        }
+    }
+    if (raw.env !== undefined && !isRecord(raw.env)) {
+        problems.push(`${subject}: dsh.workbench.env 要是对象（command / plugins / libs）—— ` +
+            `语义由门禁的 env 判据查，这里只查形状`);
+    }
+    return problems;
+}
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
+export function readDeclaration(subject, raw) {
+    const problems = declarationProblemsOf(subject, raw);
+    if (problems.length > 0)
+        return { problems };
+    const declaration = raw;
+    const card = declaration.card;
+    return {
+        declaration,
+        problems: [],
+        manifest: {
+            id: text(declaration.unit),
+            card: card === null
+                ? null
+                : {
+                    titleKey: text(card.titleKey),
+                    order: card.order,
+                },
+            tools: declaration.tools.map((tool) => ({
+                name: text(tool.name),
+                writes: tool.writes,
+            })),
+            host: {
+                inject: [...(declaration.host.inject ?? [])],
+                ...(declaration.host.optional === undefined ? {} : { optional: [...declaration.host.optional] }),
+            },
+            ...(declaration.env === undefined ? {} : { env: declaration.env }),
+        },
+    };
+}

package/dist/host/unit-face.d.ts

@@ -28,6 +28,7 @@ export interface UnitMountDeps {
         readonly force?: boolean;
     }) => Promise<UnitCapability | undefined>;
     readonly longTasks?: LongTaskHost | undefined;
+    readonly longTaskRuns?: (() => ReadonlyMap<string, LongTaskRegistry<LongTaskBase>>) | undefined;
 }
 export type ContextRenderer = (ref: {
     readonly kind: string;

package/dist/host/unit-readiness.d.ts

@@ -0,0 +1,7 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+export interface UnitReadiness {
+    readonly canMount: boolean;
+    readonly missingHard: readonly string[];
+    readonly missingSoft: readonly string[];
+}
+export declare function unitReadiness(manifest: UnitManifest, lookup: (name: string) => unknown): UnitReadiness;

package/dist/host/unit-readiness.js

@@ -0,0 +1,5 @@
+export function unitReadiness(manifest, lookup) {
+    const missingHard = manifest.host.inject.filter((name) => lookup(name) === undefined);
+    const missingSoft = (manifest.host.optional ?? []).filter((name) => lookup(name) === undefined);
+    return { canMount: missingHard.length === 0, missingHard, missingSoft };
+}

package/dist/host/unit-registry.d.ts

@@ -0,0 +1,9 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+import type { UnitHostFace } from './unit-face';
+export interface UnitRegistry {
+    register(face: UnitHostFace): () => void;
+    all(): readonly UnitHostFace[];
+    manifests(): readonly UnitManifest[];
+    subscribe(listener: () => void): () => void;
+}
+export declare function createUnitRegistry(): UnitRegistry;

package/dist/host/unit-registry.js

@@ -0,0 +1,33 @@
+export function createUnitRegistry() {
+    const faces = [];
+    const ids = new Set();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        register(face) {
+            const id = face.manifest.id;
+            if (ids.has(id))
+                throw new Error(`套件 id 重复：${id}（id 会进持久化配置，不能撞）`);
+            ids.add(id);
+            faces.push(face);
+            notify();
+            return () => {
+                const index = faces.indexOf(face);
+                if (index < 0)
+                    return;
+                faces.splice(index, 1);
+                ids.delete(id);
+                notify();
+            };
+        },
+        all: () => faces,
+        manifests: () => faces.map((face) => face.manifest),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}

package/dist/host/version-range.d.ts

@@ -0,0 +1,2 @@
+export type VersionVerdict = 'satisfied' | 'unsatisfied' | 'malformed';
+export declare function checkVersionRange(contract: string | undefined, version: string): VersionVerdict;