@dsh-workbench/shared 0.3.6 → 0.3.7

package/dist/host/probe-libs.js

@@ -0,0 +1,61 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { libDir, libInstallCommand } from './opencli-runtime';
+import { isNewerVersion, latestVersion } from './release';
+import { resetReleaseCache } from './release';
+import { checkVersionRange } from './version-range';
+export function installedLibVersion(name) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(libDir(name), 'package.json'), 'utf8'));
+        const version = parsed.version;
+        return typeof version === 'string' && version.trim() !== ''
+            ? version.trim()
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function probeLibs(options) {
+    const { needs, shell, force } = options;
+    const found = new Map();
+    for (const need of needs) {
+        if (found.has(need.name))
+            continue;
+        const base = { name: need.name, purpose: need.purpose };
+        const installed = installedLibVersion(need.name);
+        if (installed === undefined) {
+            found.set(need.name, {
+                ...base,
+                status: 'missing',
+                command: libInstallCommand({ need }),
+            });
+            continue;
+        }
+        if (checkVersionRange(need.version, installed) !== 'satisfied') {
+            found.set(need.name, {
+                ...base,
+                status: 'unsatisfied',
+                installed,
+                command: libInstallCommand({ need }),
+            });
+            continue;
+        }
+        const registry = process.env[need.registryEnv]?.trim() || need.registryDefault;
+        const latest = await latestVersion({ shell, name: need.name, registry, force });
+        const behind = latest !== undefined && isNewerVersion(latest, installed);
+        found.set(need.name, {
+            ...base,
+            status: behind ? 'outdated' : 'ok',
+            installed,
+            ...(latest === undefined ? {} : { latest }),
+            ...(behind
+                ? { command: libInstallCommand({ need, version: latest }) }
+                : {}),
+        });
+    }
+    return found;
+}
+export function resetLibCache() {
+    resetReleaseCache();
+}

package/dist/host/probe-units.d.ts

@@ -0,0 +1,17 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import { type UnitCapability, type UnitCommands } from "./probe-libs";
+export type { UnitCapability, UnitCommands, UnitLibState, UnitPluginState } from "./probe-libs";
+export declare function parsePluginList(stdout: string): unknown[] | undefined;
+export declare function probeUnitCommands(options: {
+    shell: DshShell;
+    command?: string;
+    unit: UnitCommands;
+    force?: boolean;
+}): Promise<UnitCapability>;
+export declare function probeUnits(options: {
+    shell: DshShell;
+    command?: string;
+    units: readonly UnitCommands[];
+    force?: boolean;
+}): Promise<UnitCapability[]>;
+export declare const resetProbeCache: () => void;

package/dist/host/probe-units.js

@@ -0,0 +1,102 @@
+import { OPENCLI_TIMEOUT_MS, PROBE_TTL_MS } from '@dsh-workbench/shared';
+import { createTimedMemo } from "./probe-cache";
+import { parseJsonLoose } from '@dsh-workbench/shared';
+import { npmRegistryOf } from "./plugin-source";
+import { probeRelease } from "./release";
+import { probeLibs } from "./probe-libs";
+import { evaluateUnit } from "./probe-verdict";
+import { runShell } from "./shell";
+export function parsePluginList(stdout) {
+    const parsed = parseJsonLoose(stdout);
+    if (Array.isArray(parsed))
+        return parsed;
+    return /no plugins? installed/i.test(stdout) ? [] : undefined;
+}
+async function probeReleases(units, options) {
+    const needs = new Map();
+    for (const unit of units) {
+        for (const need of unit.plugins ?? []) {
+            const source = need.installSource;
+            if (source?.kind === "npm")
+                needs.set(need.name, source);
+        }
+    }
+    const found = new Map();
+    for (const [plugin, source] of needs) {
+        const registry = npmRegistryOf(source, process.env);
+        const signal = await probeRelease({
+            shell: options.shell,
+            package: source.package,
+            ...(registry.ok ? { registry: registry.value } : {}),
+            force: options.force,
+        });
+        if (signal !== undefined)
+            found.set(plugin, signal);
+    }
+    return found;
+}
+export async function probeUnitCommands(options) {
+    const all = await probeUnits({ ...options, units: [options.unit] });
+    return (all[0] ??
+        evaluateUnit(undefined, options.unit, "unchecked", options.command ?? "opencli"));
+}
+export async function probeUnits(options) {
+    const { shell, command = "opencli", units, force = false } = options;
+    const hits = units.map((unit) => unitCache.get(`${command}:${unit.unit}`));
+    if (!force && hits.every((hit) => hit !== undefined)) {
+        return hits;
+    }
+    const result = await runShell(shell, `${command} plugin list -f json`, {
+        timeoutMs: OPENCLI_TIMEOUT_MS,
+    }).then((value) => ({
+        kind: "ok",
+        stdout: value.exitCode === 0 ? value.stdout : "",
+        stderr: value.stderr,
+    }), (error) => ({
+        kind: "error",
+        stdout: "",
+        stderr: String(error),
+    }));
+    const list = result.kind === "ok" ? parsePluginList(result.stdout) : undefined;
+    const failure = result.kind === "error"
+        ? result.stderr
+        : list === undefined
+            ? "plugin list 的输出读不懂（不是 JSON 数组）"
+            : undefined;
+    if (failure !== undefined) {
+        return units.map((unit) => {
+            const capability = {
+                unit: unit.unit,
+                ...(unit.plugins?.[0] === undefined
+                    ? {}
+                    : { plugin: unit.plugins[0].name }),
+                status: "unchecked",
+                required: (unit.plugins ?? []).flatMap((need) => need.commands ?? []),
+                missing: [],
+                detail: failure,
+            };
+            unitCache.set(`${command}:${unit.unit}`, capability);
+            return capability;
+        });
+    }
+    const [releases, libs] = await Promise.all([
+        probeReleases(units, { shell, force }),
+        probeLibs({
+            needs: units.flatMap((unit) => unit.libs ?? []),
+            shell,
+            force,
+        }),
+    ]);
+    return units.map((unit) => {
+        const capability = evaluateUnit(list, unit, undefined, command, releases, libsOfUnit(unit, libs));
+        unitCache.set(`${command}:${unit.unit}`, capability);
+        return capability;
+    });
+}
+function libsOfUnit(unit, libs) {
+    return (unit.libs ?? [])
+        .map((need) => libs.get(need.name))
+        .filter((state) => state !== undefined);
+}
+const unitCache = createTimedMemo(PROBE_TTL_MS);
+export const resetProbeCache = () => void unitCache.clear();

package/dist/host/probe-verdict.d.ts

@@ -0,0 +1,7 @@
+import type { PluginRelease, UnitPluginNeed } from '@dsh-workbench/shared';
+import type { UnitCapability, UnitCommands, UnitLibState } from "./probe-libs";
+export declare function evaluateUnit(list: readonly unknown[] | undefined, unit: UnitCommands, failure: string | undefined, command?: string, releases?: ReadonlyMap<string, PluginRelease>, libs?: readonly UnitLibState[]): UnitCapability;
+export declare function gapsText(gaps: readonly string[]): string;
+export declare function pluginUpdateCommand(plugin: string | undefined): string | undefined;
+export declare function pluginInstallCommand(plugin: string | undefined): string;
+export declare function upgradeLine(need: UnitPluginNeed, command: string, latest: string): string | undefined;

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-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;