@dsh-workbench/shared 1.1.8 → 1.1.10

package/dist/host/port-types.d.ts

@@ -1,10 +1,14 @@
 import type { DshHostContext, DshShell } from '../api/dsh.js';
+import type { RuntimeCapabilities, RuntimeProfile } from '../contract/capabilities.js';
+import type { PluginPackageKind } from '../contract/protocol/bundle-install.js';
 import type { LibNeed, SupplySource } from '../contract/needs.js';
 import type { NeedProbeInput, UnitCapability } from '../contract/unit-capability.js';
+import type { DataReader } from '../contract/data.js';
+import type { LibRunner } from '../contract/runner.js';
 import type { WorkbenchSelfUpdate } from '../contract/protocol/bundle-install.js';
-import type { BundleManager, InstalledModule, OpencliResolution, ProfileModule, ProfilePackage, RegistryNotebook, SelfUpdateRequest, SelfUpdateStart } from './adapter-types.js';
+import type { BundleManager, InstalledModule, ProfileModule, ProfilePackage, RegistryNotebook, RuntimeStatus, SelfUpdateRequest, SelfUpdateStart } from './adapter-types.js';
 import type { PostResource, RouteHandler, RouteTable } from './http.js';
-import type { PluginSourceOptions, ResolvedPluginSource } from './plugin-source.js';
+import type { PluginSourceOptions, ResolvedPluginSource } from '../contract/plugin-source.js';
 export interface LoggerLike {
     info?(message: string): void;
     warn?(message: string): void;
@@ -16,7 +20,7 @@ export interface ProfilePort {
 }
 export type SupplyPluginSource = ResolvedPluginSource;
 export interface SupplyPackageRoute {
-    readonly kind: 'opencli-plugin' | 'dsh-bundle' | 'neither';
+    readonly kind: PluginPackageKind | 'dsh-bundle' | 'neither';
     readonly pkg?: string;
     readonly pluginName?: string;
 }
@@ -63,6 +67,9 @@ export interface EnvSupplyPort {
         }>;
         readonly version?: string | undefined;
     }): string;
+    libUninstallCommand(options: {
+        readonly need: LibNeed;
+    }): string;
     pluginInstallPlan(options: SupplyPluginInstallOptions): ResolvedPluginSource;
     latestVersion(options: SupplyLatestOptions): Promise<string | undefined>;
     missingReleaseParts(options: SupplyMissingPartsOptions): Promise<readonly string[]>;
@@ -70,10 +77,14 @@ export interface EnvSupplyPort {
     splitNpmSpec(spec: string): SupplyNpmRef | undefined;
 }
 export interface ModulePort {
+    isolatedRoot(): string;
     isolatedHome(): string;
-    cliCatalogPath(): string;
-    vendorPluginsDir(): string;
-    opencliInstallCommand(): string;
+    pluginPackagePrefix?(): string;
+    pluginManifestFile?(): string;
+    cliCatalogPath?(): string;
+    vendorPluginsDir?(): string;
+    runtimeInstallCommand?(): string;
+    afterLibInstall(): void;
     profileDirOf(ctx: DshHostContext): string | null;
     profileModules(dir: string | null): readonly ProfileModule[];
     readInstalledModule(dir: string | null, pkg: string): InstalledModule;
@@ -116,8 +127,10 @@ export interface ProbePreflightInput {
     readonly routes: RouteTable;
     readonly ctx: DshHostContext;
     readonly shell: DshShell;
-    readonly opencliCommand: string;
-    readonly installCommand?: string | undefined;
+    readonly runtimeCommands: Readonly<Record<string, string>>;
+    readonly runtimeCapabilities: RuntimeCapabilities;
+    readonly runtimeCheck?: (() => Promise<RuntimeCheck>) | undefined;
+    readonly runtimeLabel?: string | undefined;
     readonly warmReads: () => readonly (readonly string[])[];
 }
 export interface ProbePort {
@@ -129,9 +142,29 @@ export interface RuntimeSeedOptions {
     readonly corePackageUrl: string;
     readonly log: (message: string) => void;
 }
+export type { RuntimeCapabilities, RuntimeProfile, RuntimeTerms } from '../contract/capabilities.js';
+export interface RuntimeCheck {
+    readonly ok: boolean;
+    readonly detail: string;
+}
+export interface RuntimeCommandSurface {
+    readonly name: string;
+    readonly pluginPrefix: string;
+    invoke(site: string, command?: string): string;
+    help(site: string): string;
+    browser?(verb: readonly string[]): string;
+    background?(command: string, argv: readonly string[]): string;
+    readonly authorHint?: string;
+}
 export interface RuntimePort {
     packageRoot(moduleUrl: string): string;
-    opencliCommand(ctx: DshHostContext): OpencliResolution;
+    capabilities(ctx: DshHostContext): RuntimeCapabilities;
+    profile?(ctx: DshHostContext): RuntimeProfile;
+    commandSurface?(ctx: DshHostContext): RuntimeCommandSurface | undefined;
+    check?(ctx: DshHostContext): Promise<RuntimeCheck>;
+    commands(ctx: DshHostContext): Readonly<Record<string, string>>;
+    runners(ctx: DshHostContext, data: DataReader): Readonly<Record<string, LibRunner>>;
+    health(ctx: DshHostContext): Readonly<Record<string, RuntimeStatus>>;
     seed(ctx: DshHostContext, options: RuntimeSeedOptions): void;
     warnUnwritableRoot(ctx: DshHostContext): void;
 }

package/dist/host/preflight.d.ts

@@ -1,10 +1,11 @@
-export type PreflightStepId = 'toolchain' | 'opencli' | 'bridge' | 'diy' | 'warm';
+export type PreflightStepId = 'toolchain' | 'cli' | 'bridge' | 'runtime' | 'diy' | 'warm';
 export type PreflightStepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'failed';
 export type PreflightFailure = 'permission' | 'network' | 'missing' | 'unknown';
 export type PreflightGuidance = 'install' | 'path' | 'shell';
-export type PreflightBridgeIssue = 'daemon' | 'extension' | 'profile' | 'stale' | 'unknown';
+export type PreflightBridgeIssue = string;
 export interface PreflightStep {
     readonly id: PreflightStepId;
+    readonly label?: string;
     readonly status: PreflightStepStatus;
     readonly detail?: string;
     readonly action?: string;

package/dist/host/profile-create.d.ts

@@ -0,0 +1,18 @@
+import type { PostResource, RouteHandler } from './http.js';
+import type { ProfileCreateApplied, ProfileCreateSnapshot } from '../contract/protocol/profile-create.js';
+export interface ProfileCreateDeps {
+    readonly home: string;
+    readonly self: string;
+    readonly packageRoot: string;
+    readonly runSetup?: ((env: Readonly<Record<string, string>>) => Promise<{
+        ok: boolean;
+        log: string;
+    }>) | undefined;
+}
+export declare function profileCreateSnapshot(deps: ProfileCreateDeps): ProfileCreateSnapshot;
+export declare function profileCreateHandler(deps: ProfileCreateDeps): RouteHandler;
+export declare function profileCreateApply(deps: ProfileCreateDeps, payload: unknown): Promise<ProfileCreateApplied | {
+    ok: false;
+    text: string;
+}>;
+export declare function profileCreateAction(deps: ProfileCreateDeps): PostResource;

package/dist/host/profile-create.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { quoteShellArg } from './shell-text.js';
+import { PROFILE_CREATE_RESOURCE } from '../contract/protocol/profile-create.js';
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const BUNDLE = '@dsh-workbench/core';
+function textOf(value) {
+    return typeof value === 'string' ? value : '';
+}
+function profileNames(profilesDir) {
+    try {
+        return readdirSync(profilesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+            .map((entry) => entry.name)
+            .filter((name) => existsSync(join(profilesDir, name, 'package.json')))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+export function profileCreateSnapshot(deps) {
+    const profiles = profileNames(join(deps.home, 'profiles')).map((name) => ({
+        name,
+        current: name === deps.self,
+        readable: true,
+    }));
+    return { current: deps.self, profiles };
+}
+export function profileCreateHandler(deps) {
+    return () => ({ ok: true, ...profileCreateSnapshot(deps) });
+}
+function inside(base, path) {
+    const root = resolve(base);
+    const target = resolve(path);
+    return target === root ? false : target.startsWith(`${root}${sep}`);
+}
+export async function profileCreateApply(deps, payload) {
+    const body = typeof payload === 'object' && payload !== null ? payload : {};
+    const profile = textOf(body['profile']).trim();
+    const source = textOf(body['source']).trim();
+    const copy = typeof body['copy'] === 'object' && body['copy'] !== null ? body['copy'] : {};
+    const flags = {
+        settings: copy['settings'] === true,
+    };
+    if (!PROFILE_NAME.test(profile))
+        return { ok: false, text: '新工作台的名字不合法：只用字母、数字、点、下划线或短横线' };
+    if (source === '')
+        return { ok: false, text: '先选一个来源 profile' };
+    if (source === profile)
+        return { ok: false, text: '来源不能是新工作台自己' };
+    const profilesDir = join(deps.home, 'profiles');
+    if (!profileNames(profilesDir).includes(source))
+        return { ok: false, text: `没有这个 profile：${source}` };
+    if (existsSync(join(profilesDir, profile)))
+        return { ok: false, text: `已经有一个叫 ${profile} 的 profile` };
+    const targetHome = join(deps.home, profile);
+    if (existsSync(targetHome))
+        return { ok: false, text: `运行时目录已经存在：${targetHome}` };
+    const env = {
+        DSH_HOME: deps.home,
+        DSH_WORKBENCH_HOME: targetHome,
+        WORKBENCH_PROFILE: profile,
+        WORKBENCH_SOURCE_PROFILE: source,
+        WB_CLONE: '1',
+        WB_COPY_SETTINGS: flags.settings ? '1' : '0',
+    };
+    const setup = deps.runSetup;
+    if (setup === undefined) {
+        return { ok: false, text: '这台机器上没有装工作台的脚本入口，建不了新的工作台。' };
+    }
+    const cleanup = () => {
+        try {
+            if (inside(profilesDir, join(profilesDir, profile)))
+                rmSync(join(profilesDir, profile), { recursive: true, force: true });
+            if (inside(deps.home, targetHome))
+                rmSync(targetHome, { recursive: true, force: true });
+        }
+        catch {
+            return;
+        }
+    };
+    const result = await setup(env);
+    if (!result.ok) {
+        cleanup();
+        return { ok: false, text: `创建失败：${result.log.trim().slice(-1200) || 'setup 没给出原因'}` };
+    }
+    try {
+        const manifest = JSON.parse(readFileSync(join(profilesDir, profile, 'package.json'), 'utf8'));
+        const bundles = manifest.dsh?.profile?.bundles;
+        if (!Array.isArray(bundles) || !bundles.includes(BUNDLE)) {
+            cleanup();
+            return { ok: false, text: 'profile 建好了，但工作台 bundle 没被选中；先跑一次 setup 修好它' };
+        }
+    }
+    catch (error) {
+        cleanup();
+        return { ok: false, text: `profile 建好了，但读不了清单：${error instanceof Error ? error.message : String(error)}` };
+    }
+    const copied = Object.entries(flags)
+        .filter(([, on]) => on)
+        .map(([name]) => name);
+    const bin = join(deps.packageRoot, 'bin', 'dsh-workbench');
+    return {
+        ok: true,
+        profile,
+        source,
+        home: targetHome,
+        command: `WORKBENCH_PROFILE=${quoteShellArg(profile)} ${quoteShellArg(bin)}`,
+        copied,
+    };
+}
+export function profileCreateAction(deps) {
+    return {
+        resource: PROFILE_CREATE_RESOURCE,
+        handle: (payload) => profileCreateApply(deps, payload),
+    };
+}

package/dist/host/profile-registries.d.ts

@@ -0,0 +1,10 @@
+import type { RegistryEntry, RegistryNotebook } from './adapter-types.js';
+export declare const REGISTRY_MARKER = "# dsh-workbench \u5199\u7684\uFF1A\u8FD9\u4E00\u884C\u7684\u5305\u53EA\u5728\u8FD9\u4E2A\u6E90\u4E0A\uFF08dsh \u5378\u8F7D\u6CA1\u6709\u6E90\u53C2\u6570\uFF0Cpnpm \u5F97\u95EE\u5F97\u5230\uFF09";
+export declare function sourcesFromLockfile(text: string): readonly RegistryEntry[];
+export interface RegistryConfigMerge {
+    readonly text: string;
+    readonly added: readonly string[];
+}
+export declare function mergeRegistryConfig(text: string, entries: readonly RegistryEntry[]): RegistryConfigMerge;
+export declare function replaceScopeRegistry(text: string, scope: string, registry: string): string;
+export declare function createRegistryNotebook(dir: string | null): RegistryNotebook;

package/dist/host/profile-registries.js

@@ -0,0 +1,150 @@
+import { normalizeRegistry, sameRegistry, scopeOf } from './adapter-types.js';
+import fs from 'node:fs';
+import path from 'node:path';
+export const REGISTRY_MARKER = '# dsh-workbench 写的：这一行的包只在这个源上（dsh 卸载没有源参数，pnpm 得问得到）';
+function registryRootOf(name, tarball) {
+    const at = tarball.indexOf(`/${name}/-/`);
+    if (at > 0)
+        return normalizeRegistry(tarball.slice(0, at));
+    try {
+        return normalizeRegistry(new URL(tarball).origin);
+    }
+    catch {
+        return null;
+    }
+}
+const PACKAGE_KEY = /^ {2}'?(\S+)'?:\s*$/;
+const PACKAGE_NAME = /^(?:@[^/\s]+\/)?[^/\s@]+$/;
+const TARBALL = /tarball:\s*(\S+?)\}?\s*$/;
+export function sourcesFromLockfile(text) {
+    const found = new Map();
+    let name = null;
+    for (const line of text.split('\n')) {
+        const key = PACKAGE_KEY.exec(line);
+        if (key !== null) {
+            const raw = key[1] ?? '';
+            const at = raw.lastIndexOf('@');
+            const candidate = at > 0 ? raw.slice(0, at) : '';
+            name = PACKAGE_NAME.test(candidate) ? candidate : null;
+            continue;
+        }
+        if (name === null)
+            continue;
+        const tarball = TARBALL.exec(line);
+        if (tarball === null)
+            continue;
+        const scope = scopeOf(name);
+        const root = registryRootOf(name, tarball[1] ?? '');
+        name = null;
+        if (scope === null || root === null)
+            continue;
+        const seen = found.get(scope);
+        if (seen === undefined)
+            found.set(scope, root);
+        else if (!sameRegistry(seen, root))
+            found.set(scope, null);
+    }
+    return [...found.entries()]
+        .filter((entry) => entry[1] !== null)
+        .map(([scope, registry]) => ({ scope, registry }));
+}
+export function mergeRegistryConfig(text, entries) {
+    const lines = text.split('\n');
+    const present = (key) => lines.some((line) => line.trim().startsWith(`${key}=`));
+    const appended = [];
+    const added = [];
+    for (const entry of entries) {
+        const key = `${entry.scope}:registry`;
+        if (entry.registry.trim() === '' || present(key))
+            continue;
+        lines.push(`${key}=${normalizeRegistry(entry.registry)}`);
+        appended.push(`${key}=${normalizeRegistry(entry.registry)}`);
+        added.push(key);
+    }
+    if (appended.length === 0)
+        return { text, added: [] };
+    const base = text === '' ? '' : text.endsWith('\n') ? text : `${text}\n`;
+    const marker = base.includes(REGISTRY_MARKER) ? '' : `${REGISTRY_MARKER}\n`;
+    return { text: `${base}${marker}${appended.join('\n')}\n`, added };
+}
+export function replaceScopeRegistry(text, scope, registry) {
+    const key = `${scope}:registry`;
+    const value = normalizeRegistry(registry);
+    let found = false;
+    const lines = text.split('\n').map((line) => {
+        if (!line.trim().startsWith(`${key}=`))
+            return line;
+        found = true;
+        return `${key}=${value}`;
+    });
+    if (found)
+        return lines.join('\n');
+    const base = text === '' ? '' : text.endsWith('\n') ? text : `${text}\n`;
+    return `${base}${key}=${value}\n`;
+}
+function readNpmrc(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function writeNpmrc(file, text) {
+    const temp = `${file}.dsh-workbench.tmp`;
+    fs.writeFileSync(temp, text, { mode: 0o600 });
+    fs.renameSync(temp, file);
+}
+export function createRegistryNotebook(dir) {
+    return {
+        sources() {
+            if (dir === null)
+                return [];
+            try {
+                return sourcesFromLockfile(fs.readFileSync(path.join(dir, 'pnpm-lock.yaml'), 'utf8'));
+            }
+            catch {
+                return [];
+            }
+        },
+        remember(entries) {
+            if (dir === null || entries.length === 0)
+                return [];
+            const file = path.join(dir, '.npmrc');
+            const merged = mergeRegistryConfig(readNpmrc(file), entries);
+            if (merged.added.length === 0)
+                return [];
+            writeNpmrc(file, merged.text);
+            return merged.added;
+        },
+        swapScope(scope, registry) {
+            if (dir === null || scope.trim() === '' || registry.trim() === '')
+                return () => { };
+            const file = path.join(dir, '.npmrc');
+            const key = `${scope.trim()}:registry`;
+            const value = normalizeRegistry(registry);
+            const before = readNpmrc(file);
+            const previous = before.split('\n').find((line) => line.trim().startsWith(`${key}=`));
+            const after = replaceScopeRegistry(before, scope.trim(), registry);
+            if (after === before)
+                return () => { };
+            writeNpmrc(file, after);
+            return () => {
+                const now = readNpmrc(file);
+                if (now === after) {
+                    if (before === '')
+                        fs.rmSync(file, { force: true });
+                    else
+                        writeNpmrc(file, before);
+                    return;
+                }
+                if (!now.includes(`${key}=${value}`))
+                    return;
+                const restored = previous === undefined
+                    ? now.split('\n').filter((line) => !line.trim().startsWith(`${key}=`)).join('\n')
+                    : now.replace(`${key}=${value}`, previous);
+                writeNpmrc(file, restored);
+            };
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { DshShell } from '../api/dsh.js';
+export interface RegistryDshLookup {
+    readonly readable: boolean;
+    readonly raw: unknown;
+}
+export interface RegistryLookup {
+    registryDshOf(options: RegistryDshOptions): Promise<RegistryDshLookup>;
+    registryDeclarationOf(options: RegistryDeclarationOptions): Promise<unknown | undefined>;
+}
+interface RegistryDshOptions {
+    readonly shell: DshShell;
+    readonly name: string;
+    readonly registry?: string | undefined;
+    readonly force?: boolean;
+    readonly cacheDir?: string | undefined;
+}
+interface RegistryDeclarationOptions extends RegistryDshOptions {
+    readonly registry: string;
+}
+export declare function createRegistryLookup(): RegistryLookup;
+export {};

package/dist/host/registry-declaration.js

@@ -0,0 +1,33 @@
+import { runShell } from './shell.js';
+import { quoteShellArg } from './shell-text.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { VERSION_CHECK_TIMEOUT_MS, VERSION_CHECK_TTL_MS } from '../config/constants.js';
+function recordOf(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+export function createRegistryLookup() {
+    const cache = new Map();
+    return {
+        registryDshOf: (options) => dshOf(cache, options),
+        registryDeclarationOf: async (options) => {
+            const found = await dshOf(cache, options);
+            return found.readable ? recordOf(found.raw)?.workbench : undefined;
+        },
+    };
+}
+async function dshOf(cache, options) {
+    const { shell, name, registry, force = false, cacheDir } = options;
+    const key = `${registry ?? ''}|${name}`;
+    const hit = cache.get(key);
+    if (!force && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS) {
+        return { readable: true, raw: hit.raw };
+    }
+    const at = registry === undefined ? '' : ` --registry ${quoteShellArg(registry)}`;
+    const cached = cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
+    const result = await runShell(shell, `npm view ${quoteShellArg(name)} dsh --json${at}${cached}`, { timeoutMs: VERSION_CHECK_TIMEOUT_MS }).catch(() => undefined);
+    const parsed = result?.exitCode === 0 ? parseJsonLoose(result.stdout) : undefined;
+    if (parsed === undefined)
+        return { readable: false, raw: undefined };
+    cache.set(key, { at: Date.now(), raw: parsed });
+    return { readable: true, raw: parsed };
+}

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

@@ -0,0 +1,34 @@
+import type { DshShell } from '../api/dsh.js';
+import type { PluginRelease } from '../contract/unit.js';
+export declare function parseLedgerVersion(stdout: string, name: string): string | undefined;
+export interface ReleaseProbe {
+    latestVersion(options: LatestVersionOptions): Promise<string | undefined>;
+    missingReleaseParts(options: MissingPartsOptions): Promise<readonly string[]>;
+    probeRelease(options: ProbeReleaseOptions): Promise<PluginRelease | undefined>;
+    reset(): void;
+}
+export declare function createReleaseProbe(): ReleaseProbe;
+interface LatestVersionOptions {
+    readonly shell: DshShell;
+    readonly name: string;
+    readonly registry: string;
+    readonly force?: boolean;
+    readonly cacheDir?: string | undefined;
+}
+interface MissingPartsOptions {
+    readonly shell: DshShell;
+    readonly name: string;
+    readonly registry: string;
+    readonly version: string;
+    readonly force?: boolean;
+    readonly cacheDir?: string | undefined;
+}
+interface ProbeReleaseOptions {
+    readonly shell: DshShell;
+    readonly package: string;
+    readonly registry?: string | undefined;
+    readonly force?: boolean;
+    readonly cacheDir?: string | undefined;
+    readonly prefix?: string | undefined;
+}
+export {};

package/dist/host/release-probe.js

@@ -0,0 +1,88 @@
+import { RELEASE_PACKAGES } from './release-packages.generated.js';
+import { VERSION_CHECK_TIMEOUT_MS, VERSION_CHECK_TTL_MS } from '../config/constants.js';
+import { isValidVersion } from './version.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { quoteShellArg } from './shell-text.js';
+import { runShell } from './shell.js';
+function cacheFlag(cacheDir) {
+    return cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
+}
+export function parseLedgerVersion(stdout, name) {
+    const parsed = parseJsonLoose(stdout);
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const entry = parsed
+        .dependencies?.[name];
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const version = entry.version;
+    return typeof version === "string" && isValidVersion(version.trim())
+        ? version.trim()
+        : undefined;
+}
+function parseVersion(stdout) {
+    const value = stdout.trim();
+    return isValidVersion(value) ? value : undefined;
+}
+export function createReleaseProbe() {
+    const latestCache = new Map();
+    const existsCache = new Map();
+    return {
+        latestVersion: async (options) => latestVersionOf(latestCache, options),
+        missingReleaseParts: async (options) => missingPartsOf(latestCache, existsCache, options),
+        probeRelease: async (options) => probeOf(latestCache, options),
+        reset: () => {
+            latestCache.clear();
+            existsCache.clear();
+        },
+    };
+}
+async function latestVersionOf(latestCache, options) {
+    const { shell, name, registry, force = false, cacheDir } = options;
+    const key = `${registry}|${name}`;
+    const hit = latestCache.get(key);
+    if (!force && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS)
+        return hit.value;
+    const result = await runShell(shell, `npm view ${quoteShellArg(name)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`, { timeoutMs: VERSION_CHECK_TIMEOUT_MS }).catch(() => undefined);
+    const read = result?.exitCode === 0 ? parseVersion(result.stdout) : undefined;
+    latestCache.set(key, { at: Date.now(), value: read });
+    return read;
+}
+async function versionExists(existsCache, options) {
+    const { shell, name, version, registry, force = false, cacheDir } = options;
+    const key = `${registry}|${name}@${version}`;
+    const hit = existsCache.get(key);
+    if (!force && hit !== undefined && (hit.value || Date.now() - hit.at < VERSION_CHECK_TTL_MS))
+        return hit.value;
+    const result = await runShell(shell, `npm view ${quoteShellArg(`${name}@${version}`)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`, { timeoutMs: VERSION_CHECK_TIMEOUT_MS }).catch(() => undefined);
+    const value = result?.exitCode === 0 && parseVersion(result.stdout) !== undefined;
+    existsCache.set(key, { at: Date.now(), value });
+    return value;
+}
+async function missingPartsOf(latestCache, existsCache, options) {
+    const { shell, name, registry, version, force = false, cacheDir } = options;
+    const checked = await Promise.all(RELEASE_PACKAGES.filter((part) => part !== name).map(async (part) => ({
+        part,
+        present: await versionExists(existsCache, { shell, name: part, version, registry, force, cacheDir }),
+    })));
+    return checked.filter((entry) => !entry.present).map((entry) => entry.part);
+}
+async function probeOf(latestCache, options) {
+    const { shell, package: pkg, registry, force = false, cacheDir, prefix } = options;
+    if (pkg === "")
+        return undefined;
+    const ledger = await runShell(shell, `npm ls --prefix ${quoteShellArg(prefix ?? '')} ${quoteShellArg(pkg)} --json --depth=0${cacheFlag(cacheDir)}`, { timeoutMs: VERSION_CHECK_TIMEOUT_MS }).catch(() => undefined);
+    const installed = ledger === undefined ? undefined : parseLedgerVersion(ledger.stdout, pkg);
+    if (installed === undefined)
+        return undefined;
+    const source = registry === undefined || registry.trim() === ""
+        ? undefined
+        : registry.trim();
+    const latest = source === undefined
+        ? undefined
+        : await latestVersionOf(latestCache, { shell, name: pkg, registry: source, force, cacheDir });
+    return {
+        installed,
+        ...(latest === undefined ? {} : { latest }),
+    };
+}

package/dist/host/runner.d.ts

@@ -0,0 +1,26 @@
+import type { DataRequest, DataResult } from '../contract/data.js';
+/**
+ * 一条 opencli 命令的执行器：同一形状的 `execFile('opencli', args)`，结果只留 stdout。
+ */
+export type LibRunner = (args: readonly string[]) => Promise<{
+    readonly stdout: string;
+}>;
+export type OpencliRunner = LibRunner;
+/**
+ * 读缝（`DataReader.read`）的形状；模块直接把自己的 `data.read` 传进来即可。
+ */
+export type OpencliRead = (request: DataRequest) => Promise<DataResult<unknown>>;
+export interface OpencliRunnerOptions {
+    readonly timeoutMs?: number;
+}
+/**
+ * 把读缝包成一条 opencli 命令的执行器：给还按 `execFile('opencli', args)` 收结果的编排库用，
+ * 让它们跑在面板用的那份 opencli 上（同一套插件、同一份登录态）。
+ *
+ * 失败按 opencli 自己的约定还原：未登录是 `code: AUTH_REQUIRED` + 退出码 77，编排库的
+ * 「等登录再重试」才接得上；其它失败保留 `Command failed: opencli …` 那句外壳。
+ * @param read 模块手里的读缝（`data.read`）。
+ * @param options `timeoutMs` 透传给读缝；不传就用读缝自己的默认值。
+ * @returns 执行器；直接交给编排库的 `setOpencliRunner`。
+ */
+export declare function opencliRunnerOf(read: OpencliRead, options?: OpencliRunnerOptions): OpencliRunner;

package/dist/host/runner.js

@@ -0,0 +1,50 @@
+const AUTH_REQUIRED_EXIT_CODE = 77;
+function textOf(value) {
+    return typeof value === 'string' ? value : '';
+}
+function failedOf(args, error) {
+    const head = `Command failed: opencli ${args.join(' ')}`;
+    const auth = error?.pageCode === 'auth-required';
+    const helpUrl = textOf(error?.helpUrl);
+    const detail = textOf(error?.detail);
+    const hint = textOf(error?.hint);
+    const failed = new Error([
+        head,
+        ...(auth
+            ? ['code: AUTH_REQUIRED', `message: ${textOf(error?.message)}`]
+            : [textOf(error?.message) || 'opencli 这条命令没跑通']),
+        ...(detail === '' ? [] : [detail]),
+        ...(hint === '' ? [] : [hint]),
+        ...(auth && helpUrl !== ''
+            ? [`help: Please open Chrome or Chromium and log in to ${helpUrl}`]
+            : []),
+    ].join('\n'));
+    if (auth)
+        failed.code = AUTH_REQUIRED_EXIT_CODE;
+    return failed;
+}
+/**
+ * 把读缝包成一条 opencli 命令的执行器：给还按 `execFile('opencli', args)` 收结果的编排库用，
+ * 让它们跑在面板用的那份 opencli 上（同一套插件、同一份登录态）。
+ *
+ * 失败按 opencli 自己的约定还原：未登录是 `code: AUTH_REQUIRED` + 退出码 77，编排库的
+ * 「等登录再重试」才接得上；其它失败保留 `Command failed: opencli …` 那句外壳。
+ * @param read 模块手里的读缝（`data.read`）。
+ * @param options `timeoutMs` 透传给读缝；不传就用读缝自己的默认值。
+ * @returns 执行器；直接交给编排库的 `setOpencliRunner`。
+ */
+export function opencliRunnerOf(read, options = {}) {
+    return async (args) => {
+        const result = await read({
+            kind: 'command',
+            adapter: 'opencli',
+            argv: [...args],
+            ...(options.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: options.timeoutMs }),
+        });
+        if (result.ok)
+            return { stdout: JSON.stringify(result.data) };
+        throw failedOf(args, result.error);
+    };
+}