@dsh-workbench/shared 1.1.8 → 1.1.9

package/dist/host/flow/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * 一条流程：按顺序跑的步骤清单；步骤里的动作按名字从注册表取。
+ */
+export interface FlowDefinition {
+    readonly id: string;
+    readonly title: string;
+    readonly target?: FlowValue | undefined;
+    readonly stopWhen?: FlowPredicate | undefined;
+    readonly steps: readonly FlowStep[];
+}
+/**
+ * 重试：`attempts` 是额外次数，总共最多 6 次。
+ */
+export interface FlowRetry {
+    readonly attempts: number;
+    readonly delayMs?: number | undefined;
+}
+/**
+ * 轮询：每次调动作，`until` 判停；`maxMs: 0` 表示不限时。
+ * `onTimeout: 'continue'` 把 `undefined` 写进步骤结果，交给后面的 `when` 决定。
+ */
+export interface FlowPoll {
+    readonly everyMs: number;
+    readonly maxMs: number;
+    readonly until: FlowPredicate;
+    readonly onTimeout?: 'fail' | 'continue' | undefined;
+}
+/**
+ * 逐项展开：`over` 求成数组，每项用 `item` 作用域跑一次，最多 `max` 项。
+ */
+export interface FlowForEach {
+    readonly over: FlowValue;
+    readonly as: string;
+    readonly max: number;
+}
+/**
+ * 一步：调用一个注册表里的动作，可选重试、轮询、逐项展开。
+ */
+export interface FlowActionStep {
+    readonly id: string;
+    readonly title?: string | undefined;
+    readonly action: string;
+    readonly with?: Readonly<Record<string, FlowValue>> | undefined;
+    readonly when?: FlowPredicate | undefined;
+    readonly retry?: FlowRetry | undefined;
+    readonly poll?: FlowPoll | undefined;
+    readonly forEach?: FlowForEach | undefined;
+}
+/**
+ * 一步：跑另一条流程；`with` 求出来的对象就是子流程的 `in`，结果挂在 `steps.<id>` 下。
+ */
+export interface FlowSubFlowStep {
+    readonly id: string;
+    readonly title?: string | undefined;
+    readonly flow: FlowDefinition;
+    readonly with?: Readonly<Record<string, FlowValue>> | undefined;
+    readonly when?: FlowPredicate | undefined;
+}
+/**
+ * 一步要么调动作，要么跑子流程。
+ */
+export type FlowStep = FlowActionStep | FlowSubFlowStep;
+/**
+ * 步骤入参里的一个值：字面量、引用，或二选一。
+ * 引用只从 `in` / `steps` / `item` / `value` 起头；`value` 只在 `poll.until` 里。
+ */
+export type FlowValue = {
+    readonly $ref: string;
+} | {
+    readonly $lit: unknown;
+} | {
+    readonly $default: readonly [FlowValue, FlowValue];
+};
+/**
+ * 条件表达式：相等、包含、存在、与、非；没有算术与函数调用。
+ */
+export type FlowPredicate = {
+    readonly $eq: readonly [FlowValue, FlowValue];
+} | {
+    readonly $in: readonly [FlowValue, readonly unknown[]];
+} | {
+    readonly $exists: FlowValue;
+} | {
+    readonly $and: readonly FlowPredicate[];
+} | {
+    readonly $not: FlowPredicate;
+};
+/**
+ * 求值现场：流程输入、已经跑完的步骤输出、当前 `forEach` 项、当前 `poll` 返回值。
+ */
+export interface FlowScope {
+    readonly in: unknown;
+    readonly steps: Readonly<Record<string, unknown>>;
+    readonly item?: unknown;
+    readonly value?: unknown;
+}
+/**
+ * 动作执行时拿到的现场：取消信号、这次跑的 id 与工作区、当前步骤 id、一行进度、登录提示。
+ */
+export interface FlowActionContext {
+    readonly signal: AbortSignal;
+    readonly runId: string;
+    readonly workspace: string;
+    readonly stepId: string;
+    log(text: string): void;
+    login(url: string): void;
+}
+/**
+ * 动作的可选元数据：给人看的标题、入参形状、以及“会不会改平台”。
+ * `writes` 只给外层审批用，不参与执行。
+ */
+export interface FlowActionMeta {
+    readonly title?: string | undefined;
+    readonly description?: string | undefined;
+    readonly input?: Readonly<Record<string, unknown>> | undefined;
+    readonly writes?: boolean | undefined;
+}
+/**
+ * 一个动作：实现完全自由，引擎只按名字调它。
+ */
+export type FlowAction = (input: unknown, context: FlowActionContext) => Promise<unknown>;
+/**
+ * 注册表里的一格：名字、实现、元数据。
+ */
+export interface RegisteredFlowAction {
+    readonly name: string;
+    readonly action: FlowAction;
+    readonly meta: FlowActionMeta;
+}
+/**
+ * 动作注册表：流程只能引用这里登记过的名字。
+ */
+export interface FlowActionRegistry {
+    register(name: string, action: FlowAction, meta?: FlowActionMeta): void;
+    get(name: string): RegisteredFlowAction | undefined;
+    has(name: string): boolean;
+    list(): readonly RegisteredFlowAction[];
+}
+/**
+ * 步骤事件：开始、成功、跳过、失败、需要登录；重试时带第几次。
+ */
+export interface FlowStepEvent {
+    readonly stepId: string;
+    readonly title: string;
+    readonly status: 'running' | 'ok' | 'skipped' | 'failed' | 'needs-login';
+    readonly attempt?: number | undefined;
+    readonly message?: string | undefined;
+    readonly loginUrl?: string | undefined;
+}
+/**
+ * 跑一条流程要的那几件：流程、输入、动作表、取消信号、身份与进度回调。
+ * `sleep` / `now` 可注入，测试里用假时钟。
+ */
+export interface FlowRunOptions {
+    readonly flow: FlowDefinition;
+    readonly input: unknown;
+    readonly actions: FlowActionRegistry;
+    readonly signal: AbortSignal;
+    readonly runId: string;
+    readonly workspace: string;
+    readonly onStep: (event: FlowStepEvent) => void;
+    readonly sleep?: ((ms: number, signal: AbortSignal) => Promise<void>) | undefined;
+    readonly now?: (() => number) | undefined;
+}
+/**
+ * 一次跑的结果：成功、失败或停止；停止不是失败。
+ */
+export interface FlowResult {
+    readonly status: 'ok' | 'failed' | 'stopped';
+    readonly target: string;
+    readonly steps: Readonly<Record<string, unknown>>;
+    readonly failedStep?: string | undefined;
+    readonly error?: unknown;
+}
+/**
+ * 一条校验问题：指到具体路径，给 agent 或人直接改。
+ */
+export interface FlowProblem {
+    readonly path: string;
+    readonly problem: string;
+}
+/**
+ * 校验结果：`ok` 为真表示没有 problems。
+ */
+export interface FlowCheck {
+    readonly ok: boolean;
+    readonly problems: readonly FlowProblem[];
+}

package/dist/host/flow/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/host-actions.d.ts

@@ -0,0 +1,2 @@
+import type { HostActions } from './port-types.js';
+export declare function createHostActions(): HostActions;

package/dist/host/host-actions.js

@@ -0,0 +1,5 @@
+import { configSyncAction, configSyncHandler } from './config-sync.js';
+import { profileCreateAction, profileCreateHandler } from './profile-create.js';
+export function createHostActions() {
+    return { configSyncAction, configSyncHandler, profileCreateAction, profileCreateHandler };
+}

package/dist/host/host-kit.d.ts

@@ -0,0 +1,19 @@
+import type { EnvSupplyPort } from './port-types.js';
+import { type FlowHost } from './flow/kit.js';
+import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
+/**
+ * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法。
+ */
+export interface HostKit {
+    readonly flow: FlowHost;
+    readonly sessionIdOf: typeof sessionIdOf;
+    readonly sessionWorkspace: typeof sessionWorkspace;
+    readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+}
+/**
+ * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ */
+export declare function createHostKit(parts: {
+    readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+}): HostKit;

package/dist/host/host-kit.js

@@ -0,0 +1,14 @@
+import { createFlowHost } from './flow/kit.js';
+import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
+/**
+ * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ */
+export function createHostKit(parts) {
+    return {
+        flow: createFlowHost(),
+        sessionIdOf,
+        sessionWorkspace,
+        libInstallCommand: parts.libInstallCommand,
+    };
+}

package/dist/host/http.d.ts

@@ -1,6 +1,7 @@
 import type { DshHostContext } from '../api/dsh.js';
 import { type PanelStateStore } from './panel-state.js';
 import { type ProvisionHandler } from './provision.js';
+import type { RuntimeStatus } from './adapter-types.js';
 export type RouteHandler = (search: URLSearchParams) => Promise<unknown> | unknown;
 export type RouteTable = Record<string, RouteHandler>;
 export declare function flag(search: URLSearchParams, name: string): boolean;
@@ -32,12 +33,7 @@ export declare function preflightHandler(preflight: {
     snapshot(): unknown;
 }): RouteHandler;
 export declare function capabilityHandler(probe: (unit: string | undefined, force: boolean) => Promise<unknown> | unknown): RouteHandler;
-export interface OpencliHealth {
-    readonly command: string;
-    readonly source: 'env' | 'isolated' | 'path';
-    readonly isolated: string | null;
-}
-export declare function healthHandler(ctx: DshHostContext, opencli?: OpencliHealth): RouteHandler;
+export declare function healthHandler(ctx: DshHostContext, runtimes?: Readonly<Record<string, RuntimeStatus>>): RouteHandler;
 export declare function registerPrefs(ctx: DshHostContext, resources: readonly PostResource[], wrote?: ((resource: string, write: PostWrite) => void) | undefined): () => void;
 export declare function registerActions(ctx: DshHostContext, resources: readonly PostResource[], wrote?: ((resource: string, write: PostWrite) => void) | undefined): () => void;
 export declare function registerPanelState(ctx: DshHostContext, store: PanelStateStore): () => void;

package/dist/host/http.js

@@ -194,7 +194,7 @@ export function capabilityHandler(probe) {
         return { ok: true, ...result };
     };
 }
-export function healthHandler(ctx, opencli) {
+export function healthHandler(ctx, runtimes) {
     return () => {
         const profile = ctx.get('profileContext');
         const dir = profile?.dir;
@@ -205,7 +205,7 @@ export function healthHandler(ctx, opencli) {
             profileDir: dir ?? null,
             pid: process.pid,
             now: new Date().toISOString(),
-            ...(opencli === undefined ? {} : { opencli }),
+            ...(runtimes === undefined ? {} : { runtimes }),
         };
     };
 }

package/dist/host/installed-module.d.ts

@@ -0,0 +1,23 @@
+import type { DshHostContext } from '../api/dsh.js';
+import type { InstalledModule, ProfileModule, ProfilePackage } from './adapter-types.js';
+export interface UnitDeclarationSource {
+    readonly pkg: string;
+    readonly declaration: unknown;
+}
+export declare function profileDirOf(ctx: DshHostContext): string | null;
+export declare function profileManifestOf(profileDir: string | null): Readonly<Record<string, unknown>> | undefined;
+export declare function profileModules(profileDir: string | null): readonly ProfileModule[];
+export declare function createDeclarationLookup(profileDir: string | null): (unit: string) => UnitDeclarationSource | undefined;
+export declare function moduleDeclarationOf(profileDir: string | null, pkg: string): unknown;
+export interface DeclarationGap {
+    readonly pkg: string;
+    readonly problems: readonly string[];
+}
+export declare function declarationGaps(profileDir: string | null): readonly DeclarationGap[] | undefined;
+export declare function declaredPluginCommands(profileDir: string | null): ReadonlyMap<string, ReadonlySet<string>>;
+export declare function readInstalledModule(profileDir: string | null, pkg: string): InstalledModule;
+export declare function isPackedArtifactSpec(spec: string): boolean;
+export declare function isLocalDependencySpec(spec: string): boolean;
+export declare function isRegistryDependencySpec(spec: string): boolean;
+export declare function readProfilePackage(profileDir: string | null, pkg: string): ProfilePackage | undefined;
+export declare function packageVersionAt(packageRoot: string): string | undefined;

package/dist/host/installed-module.js

@@ -0,0 +1,264 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { declarationProblemsOf, readDeclaration } from '../contract/unit-declaration.js';
+import { packageSourceOf } from './installed-sources.js';
+import { scopeOf } from './adapter-types.js';
+import { isPackageName } from './spec.js';
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function asText(value) {
+    return typeof value === 'string' ? value : '';
+}
+export function profileDirOf(ctx) {
+    const profile = ctx.get('profileContext');
+    const dir = typeof profile?.dir === 'string' ? profile.dir.trim() : '';
+    return dir === '' ? null : dir;
+}
+function stringsOf(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+export function profileManifestOf(profileDir) {
+    if (profileDir === null)
+        return undefined;
+    try {
+        return asRecord(JSON.parse(fs.readFileSync(path.join(profileDir, 'package.json'), 'utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function profileModules(profileDir) {
+    const record = profileManifestOf(profileDir);
+    if (record === undefined)
+        return [];
+    const bundles = stringsOf(asRecord(asRecord(record.dsh)?.profile)?.bundles);
+    const dependencies = asRecord(record.dependencies) ?? {};
+    const names = bundles.length > 0 ? bundles : Object.keys(dependencies);
+    const found = [];
+    for (const pkg of names) {
+        const read = readInstalledModule(profileDir, pkg);
+        if (read.kind === 'module') {
+            const spec = asText(dependencies[read.pkg]);
+            found.push({
+                pkg: read.pkg,
+                unit: read.unit,
+                version: read.version,
+                ...(read.registry === undefined ? {} : { registry: read.registry }),
+                local: isLocalDependencySpec(spec),
+                fromRegistry: isRegistryDependencySpec(spec),
+            });
+        }
+    }
+    return found;
+}
+export function createDeclarationLookup(profileDir) {
+    let roster;
+    const scan = () => new Map(profileModules(profileDir).map((row) => [row.unit, row.pkg]));
+    return (unit) => {
+        roster ??= scan();
+        let pkg = roster.get(unit);
+        if (pkg === undefined) {
+            roster = scan();
+            pkg = roster.get(unit);
+        }
+        return pkg === undefined ? undefined : { pkg, declaration: moduleDeclarationOf(profileDir, pkg) };
+    };
+}
+function registryFromLockfile(profileDir, pkg) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(profileDir, 'pnpm-lock.yaml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const at = text.indexOf(`  ${pkg}@`);
+    const quoted = at === -1 ? text.indexOf(`  '${pkg}@`) : at;
+    if (quoted === -1)
+        return undefined;
+    const headerEnd = text.indexOf('\n', quoted);
+    const end = headerEnd === -1 ? -1 : text.indexOf('\n  ', headerEnd + 1);
+    const block = text.slice(quoted, end === -1 ? quoted + 900 : end);
+    const match = /tarball:\s*([^\s,}]+)/.exec(block);
+    const tarball = match?.[1];
+    if (tarball === undefined || !tarball.startsWith('http'))
+        return undefined;
+    const cut = tarball.lastIndexOf(`/${pkg}/`);
+    if (cut <= 'https://'.length)
+        return undefined;
+    return tarball.slice(0, cut);
+}
+function unquoted(value) {
+    const quote = value.charAt(0);
+    if (value.length >= 2 && (quote === '"' || quote === "'") && value.endsWith(quote)) {
+        return value.slice(1, -1).trim();
+    }
+    return value;
+}
+function registryFromNpmrc(profileDir, pkg) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(profileDir, '.npmrc'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const scope = scopeOf(pkg);
+    let fallback;
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith(';'))
+            continue;
+        const separator = trimmed.indexOf('=');
+        if (separator <= 0)
+            continue;
+        const key = trimmed.slice(0, separator).trim();
+        const value = unquoted(trimmed.slice(separator + 1).trim());
+        if (value === '')
+            continue;
+        if (scope !== null && key === `${scope}:registry`)
+            return value;
+        if (key === 'registry')
+            fallback = value;
+    }
+    return fallback;
+}
+function registryOf(profileDir, pkg, manifest) {
+    const declared = asText(asRecord(manifest.publishConfig)?.registry);
+    if (declared !== '')
+        return declared;
+    const recorded = packageSourceOf(profileDir, pkg);
+    if (recorded !== undefined)
+        return recorded.registry;
+    const locked = registryFromLockfile(profileDir, pkg);
+    return locked === undefined ? registryFromNpmrc(profileDir, pkg) : locked;
+}
+export function moduleDeclarationOf(profileDir, pkg) {
+    if (profileDir === null || !isPackageName(pkg))
+        return undefined;
+    try {
+        const text = fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8');
+        return asRecord(asRecord(asRecord(JSON.parse(text))?.dsh)?.workbench);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function declarationGaps(profileDir) {
+    if (profileManifestOf(profileDir) === undefined)
+        return undefined;
+    const gaps = [];
+    for (const module of profileModules(profileDir)) {
+        const problems = declarationProblemsOf(module.pkg, moduleDeclarationOf(profileDir, module.pkg));
+        if (problems.length > 0)
+            gaps.push({ pkg: module.pkg, problems });
+    }
+    return gaps;
+}
+export function declaredPluginCommands(profileDir) {
+    const declared = new Map();
+    for (const module of profileModules(profileDir)) {
+        const read = readDeclaration(module.pkg, moduleDeclarationOf(profileDir, module.pkg));
+        for (const need of read.manifest?.needs ?? []) {
+            if (need.kind !== 'extension')
+                continue;
+            const name = need.name.trim();
+            if (name === '')
+                continue;
+            const commands = declared.get(name) ?? new Set();
+            for (const command of need.commands ?? [])
+                commands.add(command);
+            declared.set(name, commands);
+        }
+    }
+    return declared;
+}
+export function readInstalledModule(profileDir, pkg) {
+    if (profileDir === null || !isPackageName(pkg))
+        return { kind: 'unknown', pkg };
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8'));
+    }
+    catch {
+        return { kind: 'unknown', pkg };
+    }
+    const record = asRecord(manifest);
+    if (record === undefined)
+        return { kind: 'unknown', pkg };
+    const declared = asRecord(asRecord(record.dsh)?.workbench);
+    const unit = declared === undefined ? '' : asText(declared.unit);
+    if (unit === '')
+        return { kind: 'not-module', pkg };
+    const registry = registryOf(profileDir, pkg, record);
+    return {
+        kind: 'module',
+        pkg,
+        unit,
+        version: asText(record.version),
+        ...(registry === undefined ? {} : { registry }),
+    };
+}
+const PACKED_ARTIFACT = /\.(?:tgz|tar\.gz|tar)$/i;
+export function isPackedArtifactSpec(spec) {
+    const trimmed = spec.trim();
+    const pkgPath = trimmed.startsWith('file:') ? trimmed.slice('file:'.length) : trimmed;
+    return PACKED_ARTIFACT.test(pkgPath);
+}
+export function isLocalDependencySpec(spec) {
+    const trimmed = spec.trim();
+    if (isPackedArtifactSpec(trimmed))
+        return false;
+    return (trimmed.startsWith('link:') ||
+        trimmed.startsWith('file:') ||
+        trimmed.startsWith('./') ||
+        trimmed.startsWith('../') ||
+        trimmed.startsWith('/'));
+}
+const NON_REGISTRY_SPEC = /^(?:git\+|git:|github:|gitlab:|bitbucket:|https?:|ssh:|workspace:)/i;
+export function isRegistryDependencySpec(spec) {
+    const trimmed = spec.trim();
+    if (trimmed === '')
+        return true;
+    if (isLocalDependencySpec(trimmed) || isPackedArtifactSpec(trimmed))
+        return false;
+    return !NON_REGISTRY_SPEC.test(trimmed);
+}
+export function readProfilePackage(profileDir, pkg) {
+    if (profileDir === null || !isPackageName(pkg))
+        return undefined;
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(profileDir, 'node_modules', pkg, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const record = asRecord(manifest);
+    if (record === undefined)
+        return undefined;
+    const version = asText(record.version);
+    if (version === '')
+        return undefined;
+    const registry = registryOf(profileDir, pkg, record);
+    const dependencies = asRecord(profileManifestOf(profileDir)?.dependencies) ?? {};
+    const local = isLocalDependencySpec(asText(dependencies[pkg]));
+    return {
+        pkg,
+        version,
+        ...(registry === undefined ? {} : { registry }),
+        ...(local ? { local: true } : {}),
+    };
+}
+export function packageVersionAt(packageRoot) {
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const version = asText(asRecord(manifest)?.version);
+    return version === '' ? undefined : version;
+}

package/dist/host/lib-install.d.ts

@@ -8,13 +8,11 @@ export declare function libInstallCommand(options: {
     readonly source: NpmSource;
     readonly version?: string | undefined;
     readonly env?: NodeJS.ProcessEnv | undefined;
+    readonly prefix: string;
+    readonly cacheDir?: string | undefined;
+}): string;
+export declare function binInstallCommand(need: BinNeed, os: HostOs, env: NodeJS.ProcessEnv, prefix: string, cacheDir?: string): string | undefined;
+export declare function libUninstallCommand(options: {
+    readonly need: LibNeed;
+    readonly prefix: string;
 }): string;
-/**
- * 这个 bin 在这台机器上怎么装：作者写了 `install` 且平台对得上才给出那条命令。
- * `command` 原样照抄；`npm` 装进隔离运行时的共用依赖前缀（那份包里的 bin 会自动上 PATH）。
- * @param need 一条 bin 需要。
- * @param os 宿主平台（由平台适配器给出）。
- * @param env 取 registry 环境变量的地方。
- * @returns 一条能直接粘进终端的命令；没声明或平台不对就是 undefined。
- */
-export declare function binInstallCommand(need: BinNeed, os: HostOs, env?: NodeJS.ProcessEnv): string | undefined;

package/dist/host/lib-install.js

@@ -1,22 +1,14 @@
-import { npmRegistryOf } from './plugin-source.js';
+import { npmRegistryOf } from './npm-registry.js';
 import { quoteShellArg } from './shell-text.js';
-import { libsPrefix, npmCacheDir } from './paths.js';
 export function libInstallCommand(options) {
     const { need, source, version } = options;
     const registry = npmRegistryOf(source, options.env ?? process.env);
     const spec = version ?? need.version ?? 'latest';
     const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
-    return `npm i --prefix ${quoteShellArg(libsPrefix())} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag} --cache ${quoteShellArg(npmCacheDir())}`;
+    const cacheFlag = options.cacheDir === undefined ? '' : ` --cache ${quoteShellArg(options.cacheDir)}`;
+    return `npm i --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag}${cacheFlag}`;
 }
-/**
- * 这个 bin 在这台机器上怎么装：作者写了 `install` 且平台对得上才给出那条命令。
- * `command` 原样照抄；`npm` 装进隔离运行时的共用依赖前缀（那份包里的 bin 会自动上 PATH）。
- * @param need 一条 bin 需要。
- * @param os 宿主平台（由平台适配器给出）。
- * @param env 取 registry 环境变量的地方。
- * @returns 一条能直接粘进终端的命令；没声明或平台不对就是 undefined。
- */
-export function binInstallCommand(need, os, env = process.env) {
+export function binInstallCommand(need, os, env, prefix, cacheDir) {
     const install = need.install;
     if (install === undefined)
         return undefined;
@@ -30,6 +22,8 @@ export function binInstallCommand(need, os, env = process.env) {
     if (packageName === '')
         return undefined;
     return libInstallCommand({
+        prefix,
+        ...(cacheDir === undefined ? {} : { cacheDir }),
         need: { kind: 'lib', name: packageName, purpose: need.purpose },
         source: {
             kind: 'npm',
@@ -40,3 +34,6 @@ export function binInstallCommand(need, os, env = process.env) {
         env,
     });
 }
+export function libUninstallCommand(options) {
+    return `npm uninstall --prefix ${quoteShellArg(options.prefix)} ${quoteShellArg(options.need.name)}`;
+}

package/dist/host/lib-runners.d.ts

@@ -1,13 +1,11 @@
 import type { LibReader } from '../contract/lib.js';
-import type { OpencliRunner } from './opencli-runner.js';
-export interface LibRuntimes {
-    readonly opencli?: OpencliRunner | undefined;
-}
+import type { LibRunner } from '../contract/runner.js';
+export type LibRuntimes = Readonly<Record<string, LibRunner>>;
 interface Logger {
     warn?(message: string): void;
 }
 /**
- * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `set<Runtime>Runner`
  * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
  *
  * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。

package/dist/host/lib-runners.js

@@ -1,11 +1,11 @@
 function runnerOf(runtimes, runtime) {
-    return runtime === 'opencli' ? runtimes.opencli : undefined;
+    return runtimes[runtime];
 }
 function setterNameOf(runtime) {
     return `set${runtime.charAt(0).toUpperCase()}${runtime.slice(1)}Runner`;
 }
 /**
- * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `set<Runtime>Runner`
  * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
  *
  * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。

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

@@ -0,0 +1,7 @@
+import { localDirOf } from './spec.js';
+export { localDirOf };
+export declare function packageManifestOf(dir: string): Readonly<Record<string, unknown>> | undefined;
+export declare function dshRecordOf(dir: string): unknown | undefined;
+export declare function packageNameOf(dir: string): string | undefined;
+export declare function pathDeclarationOf(spec: string): unknown | undefined;
+export declare function declarationRefusalOf(name: string, raw: unknown): readonly string[];