@dsh-workbench/shared 0.1.6 → 0.1.8

package/dist/host/preflight.js

@@ -0,0 +1,233 @@
+import { INSTALL_TIMEOUT_MS, OPENCLI_TIMEOUT_MS, WARM_TIMEOUT_MS } from '@dsh-workbench/shared';
+import { tailLines } from '@dsh-workbench/shared';
+import { opencliCommandLine } from './opencli';
+import { isolatedInstallCommand } from './opencli-runtime';
+import { runShell } from './shell';
+export function classifyFailure(text) {
+    const lower = text.toLowerCase();
+    if (/eacces|eperm|permission denied|operation not permitted/.test(lower))
+        return 'permission';
+    if (/enotfound|etimedout|econnrefused|econnreset|network|proxy|fetch failed/.test(lower))
+        return 'network';
+    if (/command not found|not found|no such file/.test(lower))
+        return 'missing';
+    return 'unknown';
+}
+export function readBridgeReport(stdout) {
+    const text = String(stdout ?? '');
+    const ok = /^\[OK\] Daemon:/m.test(text) && /^\[OK\] Extension:/m.test(text) && /^\[OK\] Connectivity:/m.test(text);
+    if (ok) {
+        const good = text.split('\n').find((line) => line.trim() === 'Everything looks good!');
+        return { ok: true, issues: [], detail: good?.trim() ?? tailLines(text, 1) };
+    }
+    const found = new Set();
+    if (!/^\[OK\] Daemon:/m.test(text))
+        found.add('daemon');
+    if (!/^\[OK\] Extension:/m.test(text))
+        found.add('extension');
+    if (/Multiple Chrome profiles are connected/i.test(text))
+        found.add('profile');
+    if (/Default browser profile is stale|Selected browser profile is not connected/i.test(text)) {
+        found.add('stale');
+    }
+    if (found.has('profile') || found.has('stale'))
+        found.delete('extension');
+    if (found.size === 0)
+        found.add('unknown');
+    const order = ['profile', 'stale', 'daemon', 'extension', 'unknown'];
+    return { ok: false, issues: order.filter((issue) => found.has(issue)), detail: issuesSection(text) };
+}
+function issuesSection(text) {
+    const lines = text.split('\n');
+    const start = lines.findIndex((line) => /^Issues:/.test(line.trim()));
+    if (start < 0)
+        return tailLines(text, 6);
+    return lines.slice(start).join('\n').trim();
+}
+function bridgeFixCommand(command, issues) {
+    if (issues.includes('profile') || issues.includes('stale'))
+        return `${command} profile list`;
+    if (issues.includes('daemon') || issues.includes('extension'))
+        return `${command} daemon restart`;
+    return undefined;
+}
+export const OPENCLI_INSTALL_COMMAND = isolatedInstallCommand();
+const WARMABLE_BRIDGE_ISSUES = ['daemon', 'stale'];
+export function canWarm(bridge) {
+    return bridge.ok || bridge.issues.every((issue) => WARMABLE_BRIDGE_ISSUES.includes(issue));
+}
+function step(id) {
+    return { id, status: 'pending' };
+}
+export function createPreflight(options) {
+    const { shell, command = 'opencli', logger } = options;
+    const installCommand = options.installCommand ?? OPENCLI_INSTALL_COMMAND;
+    const warmReads = () => options.warmReads?.() ?? [];
+    const steps = () => [
+        step('opencli'),
+        step('bridge'),
+        ...(warmReads().length === 0 ? [] : [step('warm')]),
+    ];
+    let current = { phase: 'idle', steps: steps(), at: Date.now() };
+    let running = null;
+    let latest = null;
+    let rerun = false;
+    function set(next) {
+        current = { ...current, ...next, at: Date.now() };
+        return current;
+    }
+    function patchStep(id, patch) {
+        return set({ steps: current.steps.map((item) => (item.id === id ? { ...item, ...patch } : item)) });
+    }
+    async function exec(commandLine, timeoutMs) {
+        try {
+            const result = await runShell(shell, commandLine, { timeoutMs });
+            if (result.timedOut) {
+                return { kind: 'error', detail: `超时（${String(timeoutMs)} ms）：${commandLine}` };
+            }
+            if (result.exitCode !== 0) {
+                return { kind: 'nonzero', detail: tailLines(result.stderr || result.stdout, 4) };
+            }
+            return { kind: 'ok', stdout: result.stdout };
+        }
+        catch (error) {
+            return { kind: 'error', detail: String(error) };
+        }
+    }
+    async function probeVersion() {
+        const result = await exec(`${command} --version`, OPENCLI_TIMEOUT_MS);
+        if (result.kind === 'ok')
+            return { ok: true, missing: false, detail: result.stdout.trim().split('\n')[0] ?? '' };
+        return { ok: false, missing: result.kind === 'nonzero', detail: result.detail };
+    }
+    async function probeBridge() {
+        const result = await exec(`${command} doctor`, OPENCLI_TIMEOUT_MS);
+        if (result.kind !== 'ok')
+            return { ok: false, detail: result.detail, issues: ['unknown'] };
+        const report = readBridgeReport(result.stdout);
+        if (report.ok)
+            return report;
+        return { ...report, command: bridgeFixCommand(command, report.issues) };
+    }
+    async function installOpencli() {
+        if (options.install !== undefined)
+            return options.install();
+        const result = await exec(installCommand, INSTALL_TIMEOUT_MS);
+        if (result.kind !== 'ok')
+            return { ok: false, detail: result.detail };
+        return { ok: true, detail: tailLines(result.stdout, 1) };
+    }
+    async function warmSites(bridge) {
+        const reads = warmReads();
+        if (reads.length === 0)
+            return bridge;
+        if (!canWarm(bridge)) {
+            patchStep('warm', { status: 'warn', detail: '' });
+            return bridge;
+        }
+        patchStep('warm', {
+            status: 'running',
+            action: `${command} <套件自己声明的那条读命令> --site-session persistent -f json`,
+        });
+        const results = await Promise.all(reads.map((read) => exec(opencliCommandLine(command, read), WARM_TIMEOUT_MS)));
+        const failed = reads.filter((_, index) => results[index]?.kind !== 'ok');
+        patchStep('warm', {
+            status: failed.length === 0 ? 'ok' : 'warn',
+            detail: failed.length === 0 ? String(reads.length) : failed.map((read) => read.join(' ')).join(' '),
+            action: undefined,
+        });
+        if (bridge.ok)
+            return bridge;
+        const again = await probeBridge();
+        patchStep('bridge', {
+            status: again.ok ? 'ok' : 'warn',
+            detail: again.detail,
+            action: undefined,
+            command: again.command,
+        });
+        return again;
+    }
+    async function doRun() {
+        set({ phase: 'checking', error: undefined, failure: undefined, steps: steps() });
+        patchStep('opencli', { status: 'running', action: `${command} --version` });
+        let version = await probeVersion();
+        if (!version.ok && !version.missing) {
+            patchStep('opencli', { status: 'failed', detail: version.detail, action: undefined });
+            return set({
+                phase: 'failed',
+                error: version.detail,
+                failure: classifyFailure(version.detail),
+                guidance: 'shell',
+            });
+        }
+        if (!version.ok) {
+            set({ phase: 'installing' });
+            patchStep('opencli', { status: 'running', action: installCommand, command: installCommand });
+            const installed = await installOpencli();
+            if (!installed.ok) {
+                patchStep('opencli', {
+                    status: 'failed',
+                    detail: installed.detail,
+                    command: installCommand,
+                });
+                return set({
+                    phase: 'failed',
+                    error: installed.detail,
+                    failure: classifyFailure(installed.detail),
+                    guidance: 'install',
+                });
+            }
+            patchStep('opencli', { status: 'running', action: `${command} --version` });
+            version = await probeVersion();
+            if (!version.ok) {
+                patchStep('opencli', { status: 'failed', detail: version.detail, command: installCommand });
+                return set({
+                    phase: 'failed',
+                    error: version.detail,
+                    failure: classifyFailure(version.detail),
+                    guidance: 'path',
+                });
+            }
+        }
+        patchStep('opencli', { status: 'ok', detail: version.detail, action: undefined });
+        patchStep('bridge', { status: 'running', action: `${command} doctor` });
+        const bridge = await probeBridge();
+        const healable = !bridge.ok && warmReads().length > 0 && canWarm(bridge);
+        if (!healable) {
+            patchStep('bridge', {
+                status: bridge.ok ? 'ok' : 'warn',
+                detail: bridge.detail,
+                action: undefined,
+                ...(bridge.command === undefined ? {} : { command: bridge.command }),
+            });
+        }
+        const settled = await warmSites(bridge);
+        logger?.warn?.(`[dsh-workbench] 环境体检：${current.steps.map((item) => `${item.id}=${item.status}`).join(' ')}`);
+        return set({ phase: 'ready', ...(settled.ok ? {} : { bridgeIssues: settled.issues }) });
+    }
+    async function start(runOptions = {}) {
+        if (running !== null) {
+            if (runOptions.force === true)
+                rerun = true;
+            return running;
+        }
+        if (runOptions.force !== true && latest !== null)
+            return latest;
+        const inflight = doRun();
+        latest = inflight;
+        running = inflight;
+        await inflight.catch(() => undefined);
+        running = null;
+        if (rerun) {
+            rerun = false;
+            return start({ force: true });
+        }
+        return inflight;
+    }
+    return {
+        run: start,
+        snapshot() {
+            return current;
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+export interface TimedMemo<T> {
+    get(key: string, now?: number): T | undefined;
+    set(key: string, value: T, now?: number): void;
+    clear(): void;
+}
+export declare function createTimedMemo<T>(ttlMs: number): TimedMemo<T>;

package/dist/host/probe-cache.js

@@ -0,0 +1,19 @@
+export function createTimedMemo(ttlMs) {
+    const entries = new Map();
+    return {
+        get(key, now = Date.now()) {
+            const hit = entries.get(key);
+            if (hit === undefined)
+                return undefined;
+            if (now - hit.at >= ttlMs)
+                return undefined;
+            return hit.value;
+        },
+        set(key, value, now = Date.now()) {
+            entries.set(key, { at: now, value });
+        },
+        clear() {
+            entries.clear();
+        },
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import type { PluginRelease, UnitLibNeed, UnitPluginNeed } from '@dsh-workbench/shared';
+import type { PluginSourceProblem } from './plugin-source';
+export interface UnitLibState {
+    readonly name: string;
+    readonly purpose: string;
+    readonly status: 'ok' | 'outdated' | 'missing' | 'unsatisfied';
+    readonly installed?: string;
+    readonly latest?: string;
+    readonly command?: string;
+}
+export declare function installedLibVersion(name: string): string | undefined;
+export declare function probeLibs(options: {
+    readonly needs: readonly UnitLibNeed[];
+    readonly shell: DshShell;
+    readonly force: boolean;
+}): Promise<ReadonlyMap<string, UnitLibState>>;
+export interface UnitCommands {
+    readonly unit: string;
+    readonly plugins?: readonly UnitPluginNeed[];
+    readonly libs?: readonly UnitLibNeed[];
+}
+export interface UnitPluginState {
+    readonly name: string;
+    readonly status: "ok" | "outdated" | "missing";
+    readonly missing: readonly string[];
+    readonly install?: "ready" | PluginSourceProblem;
+    readonly command?: string;
+    readonly release?: PluginRelease;
+}
+export interface UnitCapability {
+    readonly unit: string;
+    readonly status: "ok" | "missing-commands" | "missing-plugin" | "unchecked";
+    readonly plugin?: string;
+    readonly required: readonly string[];
+    readonly missing: readonly string[];
+    readonly detail: string;
+    readonly command?: string;
+    readonly fix?: "install" | "update";
+    readonly install?: "ready" | PluginSourceProblem;
+    readonly plugins?: readonly UnitPluginState[];
+    readonly libs?: readonly UnitLibState[];
+    readonly released?: boolean;
+}
+export declare function resetLibCache(): void;

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