@dsh-workbench/shared 1.1.6 → 1.1.7

package/dist/contract/needs.d.ts

@@ -76,12 +76,15 @@ export interface ExtensionNeed extends NeedCommon {
 }
 /**
  * 要在隔离运行时里有一个共用依赖包。
+ * `runs` 写它自己会起哪些运行时的命令（如 `["opencli"]`）—— 写了外壳就把那份执行器注入进去
+ * （库侧约定 `setOpencliRunner`）；不写就按它自己在 PATH 上找。
  */
 export interface LibNeed extends NeedCommon {
     readonly kind: 'lib';
     readonly name: string;
     readonly version?: string;
     readonly sources?: readonly SupplySource[];
+    readonly runs?: readonly string[] | undefined;
 }
 /**
  * 跑起来时要有这个环境变量；`secret` 为真时任何地方都不回显它的值。

package/dist/contract/needs.js

@@ -22,6 +22,7 @@ export const NEED_KEYS = [
     'secret',
     'install',
     'docs',
+    'runs',
 ];
 const SOURCE_KEYS = ['kind', 'package', 'registryEnv', 'registryDefault', 'url', 'ref', 'path', 'env'];
 const REGISTRY_PATTERN = /^(?:https?|file):\/\//;
@@ -149,6 +150,20 @@ export function binInstallProblemsOf(raw, at) {
     }
     return errors;
 }
+function libRunsProblemsOf(raw, at) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        return [`${at}.runs 要是数组`];
+    if (raw.length === 0)
+        return [`${at}.runs 是空数组 —— 不自己跑命令就整条删掉`];
+    const names = raw.map((one) => text(one));
+    if (names.some((one) => one === ''))
+        return [`${at}.runs 里有空字符串`];
+    if (new Set(names).size !== names.length)
+        return [`${at}.runs 里有重复的运行时`];
+    return [];
+}
 function perKindProblemsOf(kind, raw, at) {
     const errors = [];
     if (kind === 'bin' || kind === 'lib' || kind === 'env') {
@@ -159,6 +174,8 @@ function perKindProblemsOf(kind, raw, at) {
         errors.push(...binInstallProblemsOf(raw['install'], at));
     if (raw['docs'] !== undefined && text(raw['docs']) === '')
         errors.push(`${at}.docs 是空串`);
+    if (kind === 'lib')
+        errors.push(...libRunsProblemsOf(raw['runs'], at));
     if (kind === 'extension') {
         if (text(raw['runtime']) === '')
             errors.push(`${at}.runtime 没写 —— 扩展属于哪个运行时（如 opencli）`);

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

@@ -0,0 +1,20 @@
+import type { LibReader } from '../contract/lib.js';
+import type { OpencliRunner } from './opencli-runner.js';
+export interface LibRuntimes {
+    readonly opencli?: OpencliRunner | undefined;
+}
+interface Logger {
+    warn?(message: string): void;
+}
+/**
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
+ *
+ * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。
+ * @param libs 原来的读库口。
+ * @param runtimes 外壳手上有的执行器，按运行时名字给。
+ * @param logger 记 warn 的地方（默认不记）。
+ * @returns 包好的读库口；`load` 的签名与返回不变。
+ */
+export declare function withLibRunners(libs: LibReader, runtimes: LibRuntimes, logger?: Logger): LibReader;
+export {};

package/dist/host/lib-runners.js

@@ -0,0 +1,46 @@
+function runnerOf(runtimes, runtime) {
+    return runtime === 'opencli' ? runtimes.opencli : undefined;
+}
+function setterNameOf(runtime) {
+    return `set${runtime.charAt(0).toUpperCase()}${runtime.slice(1)}Runner`;
+}
+/**
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
+ *
+ * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。
+ * @param libs 原来的读库口。
+ * @param runtimes 外壳手上有的执行器，按运行时名字给。
+ * @param logger 记 warn 的地方（默认不记）。
+ * @returns 包好的读库口；`load` 的签名与返回不变。
+ */
+export function withLibRunners(libs, runtimes, logger) {
+    const warned = new Set();
+    const warnOnce = (key, message) => {
+        if (warned.has(key))
+            return;
+        warned.add(key);
+        logger?.warn?.(message);
+    };
+    return {
+        async load(need, entry) {
+            const module = await libs.load(need, entry);
+            for (const runtime of need.runs ?? []) {
+                const runner = runnerOf(runtimes, runtime);
+                if (runner === undefined) {
+                    warnOnce(`${need.name}:${runtime}:unsupported`, `[dsh-workbench] ${need.name} 声明了自己会跑 ${runtime}，但工作台没有这个执行器 —— 它会按自己的方式找`);
+                    continue;
+                }
+                const setter = typeof module === 'object' && module !== null
+                    ? module[setterNameOf(runtime)]
+                    : undefined;
+                if (typeof setter !== 'function') {
+                    warnOnce(`${need.name}:${entry}:${runtime}:missing`, `[dsh-workbench] ${need.name} 声明了自己会跑 ${runtime}，但这一版没有 ${setterNameOf(runtime)} —— 它会按 PATH 找`);
+                    continue;
+                }
+                setter.call(module, runner);
+            }
+            return module;
+        },
+    };
+}

package/dist/host/opencli-runner.d.ts

@@ -0,0 +1,25 @@
+import type { DataRequest, DataResult } from '../contract/data.js';
+/**
+ * 一条 opencli 命令的执行器：同一形状的 `execFile('opencli', args)`，结果只留 stdout。
+ */
+export type OpencliRunner = (args: readonly string[]) => Promise<{
+    readonly stdout: string;
+}>;
+/**
+ * 读缝（`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/opencli-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);
+    };
+}

package/dist/host.d.ts

@@ -34,6 +34,8 @@ export * from './host/tokens.js';
 export * from './host/tool-approval.js';
 export * from './host/tool-kit.js';
 export * from './host/unit-face.js';
+export * from './host/opencli-runner.js';
+export * from './host/lib-runners.js';
 export * from './host/value-handoff.js';
 export * from './host/workspace-store.js';
 export * from './host/write-result.js';

package/dist/host.js

@@ -34,6 +34,8 @@ export * from './host/tokens.js';
 export * from './host/tool-approval.js';
 export * from './host/tool-kit.js';
 export * from './host/unit-face.js';
+export * from './host/opencli-runner.js';
+export * from './host/lib-runners.js';
 export * from './host/value-handoff.js';
 export * from './host/workspace-store.js';
 export * from './host/write-result.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/contract/__tests__/needs.test.ts

@@ -114,6 +114,14 @@ describe('needs 校验矩阵', () => {
     expect(errorsOf({ ...base, id: '' }).join(' ')).toContain('id 是空串');
   });
 
+  it('lib 声明 runs（会自己起运行时的命令）→ 过；写歪了判红并点名', () => {
+    expect(errorsOf({ ...base, runs: ['opencli'] })).toEqual([]);
+    expect(errorsOf({ ...base, runs: 'opencli' }).join(' ')).toContain('.runs 要是数组');
+    expect(errorsOf({ ...base, runs: [] }).join(' ')).toContain('空数组');
+    expect(errorsOf({ ...base, runs: [''] }).join(' ')).toContain('空字符串');
+    expect(errorsOf({ ...base, runs: ['opencli', 'opencli'] }).join(' ')).toContain('重复');
+  });
+
   it('★ need 内未知字段只是警告；x- 前缀直接忽略（不为可选字段升协议版本）', () => {
     const read = needProblemsOf('demo', { ...base, future: 1, 'x-vendor': true }, 0);
     expect(read.errors).toEqual([]);

package/src/contract/needs.ts

@@ -82,12 +82,15 @@ export interface ExtensionNeed extends NeedCommon {
 
 /**
  * 要在隔离运行时里有一个共用依赖包。
+ * `runs` 写它自己会起哪些运行时的命令（如 `["opencli"]`）—— 写了外壳就把那份执行器注入进去
+ * （库侧约定 `setOpencliRunner`）；不写就按它自己在 PATH 上找。
  */
 export interface LibNeed extends NeedCommon {
   readonly kind: 'lib';
   readonly name: string;
   readonly version?: string;
   readonly sources?: readonly SupplySource[];
+  readonly runs?: readonly string[] | undefined;
 }
 
 /**
@@ -128,6 +131,7 @@ export const NEED_KEYS: readonly string[] = [
   'secret',
   'install',
   'docs',
+  'runs',
 ];
 
 /**
@@ -267,6 +271,16 @@ export function binInstallProblemsOf(raw: unknown, at: string): readonly string[
   return errors;
 }
 
+function libRunsProblemsOf(raw: unknown, at: string): readonly string[] {
+  if (raw === undefined) return [];
+  if (!Array.isArray(raw)) return [`${at}.runs 要是数组`];
+  if (raw.length === 0) return [`${at}.runs 是空数组 —— 不自己跑命令就整条删掉`];
+  const names = raw.map((one) => text(one));
+  if (names.some((one) => one === '')) return [`${at}.runs 里有空字符串`];
+  if (new Set(names).size !== names.length) return [`${at}.runs 里有重复的运行时`];
+  return [];
+}
+
 function perKindProblemsOf(
   kind: NeedKind,
   raw: Readonly<Record<string, unknown>>,
@@ -278,6 +292,7 @@ function perKindProblemsOf(
   }
   if (kind === 'bin') errors.push(...binInstallProblemsOf(raw['install'], at));
   if (raw['docs'] !== undefined && text(raw['docs']) === '') errors.push(`${at}.docs 是空串`);
+  if (kind === 'lib') errors.push(...libRunsProblemsOf(raw['runs'], at));
   if (kind === 'extension') {
     if (text(raw['runtime']) === '') errors.push(`${at}.runtime 没写 —— 扩展属于哪个运行时（如 opencli）`);
     if (text(raw['name']) === '') errors.push(`${at}.name 没写`);

package/src/host/__tests__/lib-runners.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { LibNeed } from '../../contract/needs.js';
+import type { LibReader } from '../../contract/lib.js';
+import type { OpencliRunner } from '../opencli-runner.js';
+import { withLibRunners } from '../lib-runners.js';
+
+const runner: OpencliRunner = async () => ({ stdout: '[]' });
+
+function needOf(runs?: readonly string[]): LibNeed {
+  return {
+    kind: 'lib',
+    name: 'opencli-workflow',
+    purpose: '发布编排',
+    ...(runs === undefined ? {} : { runs }),
+  };
+}
+
+function libsOf(module: unknown): LibReader {
+  return {
+    async load<T = unknown>(): Promise<T> {
+      return module as T;
+    },
+  };
+}
+
+function logger(): { readonly warn: ReturnType<typeof vi.fn<(message: string) => void>> } {
+  return { warn: vi.fn<(message: string) => void>() };
+}
+
+describe('withLibRunners', () => {
+  it('没声明 runs → 原样返回，不注入、不记 warn', async () => {
+    const module = { setOpencliRunner: vi.fn() };
+    const warn = logger();
+    const libs = withLibRunners(libsOf(module), { opencli: runner }, warn);
+
+    await expect(libs.load(needOf(), 'src/utils.js')).resolves.toBe(module);
+    expect(module.setOpencliRunner).not.toHaveBeenCalled();
+    expect(warn.warn).not.toHaveBeenCalled();
+  });
+
+  it('声明了 opencli 且库有 setOpencliRunner → 把执行器交进去', async () => {
+    const module = { setOpencliRunner: vi.fn() };
+    const warn = logger();
+    const libs = withLibRunners(libsOf(module), { opencli: runner }, warn);
+
+    await expect(libs.load(needOf(['opencli']), 'src/utils.js')).resolves.toBe(module);
+    expect(module.setOpencliRunner).toHaveBeenCalledWith(runner);
+    expect(warn.warn).not.toHaveBeenCalled();
+  });
+
+  it('库版本旧、没有 setter → 不注入，只 warn 一次', async () => {
+    const module = {};
+    const warn = logger();
+    const libs = withLibRunners(libsOf(module), { opencli: runner }, warn);
+
+    await libs.load(needOf(['opencli']), 'src/utils.js');
+    await libs.load(needOf(['opencli']), 'src/utils.js');
+
+    expect(warn.warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.warn.mock.calls[0]?.[0])).toContain('没有 setOpencliRunner');
+  });
+
+  it('声明了外壳没有的运行时 → 不注入，只 warn 一次', async () => {
+    const module = { setGitRunner: vi.fn() };
+    const warn = logger();
+    const libs = withLibRunners(libsOf(module), { opencli: runner }, warn);
+
+    await libs.load(needOf(['git']), 'src/utils.js');
+
+    expect(module.setGitRunner).not.toHaveBeenCalled();
+    expect(warn.warn).toHaveBeenCalledTimes(1);
+    expect(String(warn.warn.mock.calls[0]?.[0])).toContain('没有这个执行器');
+  });
+
+  it('模块导出不是对象（函数 / 原始值）也不炸', async () => {
+    const warn = logger();
+    const libs = withLibRunners(libsOf(() => undefined), { opencli: runner }, warn);
+
+    await expect(libs.load(needOf(['opencli']), 'src/utils.js')).resolves.toBeTypeOf('function');
+    expect(warn.warn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/host/__tests__/opencli-runner.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { DataRequest, DataResult } from '../../contract/data.js';
+import { opencliRunnerOf } from '../opencli-runner.js';
+
+type Read = (request: DataRequest) => Promise<DataResult<unknown>>;
+
+function readerOf(result: DataResult<unknown>): {
+  readonly read: Read;
+  readonly spy: ReturnType<typeof vi.fn>;
+} {
+  const spy = vi.fn(async (_request: DataRequest) => result);
+  return { read: spy as unknown as Read, spy };
+}
+
+describe('opencliRunnerOf', () => {
+  it('把 argv 原样交给读缝，解析后的值序列化回 stdout', async () => {
+    const { read, spy } = readerOf({ ok: true, data: [{ name: 'lsznh' }] });
+    const runner = opencliRunnerOf(read);
+
+    await expect(
+      runner(['argocd', 'application-resource-tree', '--name', 'lsznh']),
+    ).resolves.toEqual({ stdout: JSON.stringify([{ name: 'lsznh' }]) });
+    expect(spy).toHaveBeenCalledWith({
+      kind: 'command',
+      adapter: 'opencli',
+      argv: ['argocd', 'application-resource-tree', '--name', 'lsznh'],
+    });
+  });
+
+  it('timeoutMs 透传给读缝；不传就不出现这一格', async () => {
+    const withTimeout = readerOf({ ok: true, data: [] });
+    await opencliRunnerOf(withTimeout.read, { timeoutMs: 1_800_000 })([
+      'coding',
+      'ci-status',
+    ]);
+    expect(withTimeout.spy).toHaveBeenCalledWith(
+      expect.objectContaining({ timeoutMs: 1_800_000 }),
+    );
+
+    const withoutTimeout = readerOf({ ok: true, data: [] });
+    await opencliRunnerOf(withoutTimeout.read)(['coding', 'ci-status']);
+    expect(withoutTimeout.spy).toHaveBeenCalledWith(
+      expect.not.objectContaining({ timeoutMs: expect.anything() }),
+    );
+  });
+
+  it('未登录还原成 opencli 的约定：退出码 77 + AUTH_REQUIRED + 登录地址', async () => {
+    const { read } = readerOf({
+      ok: false,
+      error: {
+        code: 'auth',
+        pageCode: 'auth-required',
+        message: 'Coding 未登录',
+        helpUrl: 'https://baiguokeji.coding.net/login',
+      },
+    });
+
+    const failure = await opencliRunnerOf(read)(['coding', 'ci-status']).then(
+      () => null,
+      (error: unknown) => error as Error & { code?: number },
+    );
+
+    expect(failure).toBeInstanceOf(Error);
+    expect(failure?.code).toBe(77);
+    expect(failure?.message).toBe(
+      [
+        'Command failed: opencli coding ci-status',
+        'code: AUTH_REQUIRED',
+        'message: Coding 未登录',
+        'help: Please open Chrome or Chromium and log in to https://baiguokeji.coding.net/login',
+      ].join('\n'),
+    );
+  });
+
+  it('其它失败保留 Command failed 外壳与原因 / 细节 / 下一步', async () => {
+    const { read } = readerOf({
+      ok: false,
+      error: {
+        code: 'command',
+        pageCode: 'cli-command-failed',
+        message: 'UNKNOWN：插件里没有这条命令',
+        detail: 'error: unknown command',
+        hint: '升级插件后重试',
+      },
+    });
+
+    const failure = await opencliRunnerOf(read)([
+      'argocd',
+      'application-resource-tree',
+    ]).then(
+      () => null,
+      (error: unknown) => error as Error,
+    );
+
+    expect(failure?.message).toBe(
+      [
+        'Command failed: opencli argocd application-resource-tree',
+        'UNKNOWN：插件里没有这条命令',
+        'error: unknown command',
+        '升级插件后重试',
+      ].join('\n'),
+    );
+  });
+
+  it('没有原因时也有一句能看懂的兜底', async () => {
+    const { read } = readerOf({
+      ok: false,
+      error: { code: 'command', message: '' },
+    });
+
+    const failure = await opencliRunnerOf(read)(['cmdb', 'publish']).then(
+      () => null,
+      (error: unknown) => error as Error,
+    );
+
+    expect(failure?.message).toBe(
+      'Command failed: opencli cmdb publish\nopencli 这条命令没跑通',
+    );
+  });
+});

package/src/host/lib-runners.ts

@@ -0,0 +1,70 @@
+import type { LibNeed } from '../contract/needs.js';
+import type { LibReader } from '../contract/lib.js';
+import type { OpencliRunner } from './opencli-runner.js';
+
+export interface LibRuntimes {
+  readonly opencli?: OpencliRunner | undefined;
+}
+
+interface Logger {
+  warn?(message: string): void;
+}
+
+function runnerOf(runtimes: LibRuntimes, runtime: string): OpencliRunner | undefined {
+  return runtime === 'opencli' ? runtimes.opencli : undefined;
+}
+
+function setterNameOf(runtime: string): string {
+  return `set${runtime.charAt(0).toUpperCase()}${runtime.slice(1)}Runner`;
+}
+
+/**
+ * 给声明了 `runs` 的 lib 注入「跑这个运行时」的执行器：库侧按约定暴露 `setOpencliRunner`
+ * （运行时名字首字母大写 + `Runner`），外壳在每次 `load` 之后把执行器交给它。
+ *
+ * 没暴露的（版本旧）就保持它自己的行为（按 PATH 找），只记一条 warn；不熟悉的运行时同样只 warn。
+ * @param libs 原来的读库口。
+ * @param runtimes 外壳手上有的执行器，按运行时名字给。
+ * @param logger 记 warn 的地方（默认不记）。
+ * @returns 包好的读库口；`load` 的签名与返回不变。
+ */
+export function withLibRunners(
+  libs: LibReader,
+  runtimes: LibRuntimes,
+  logger?: Logger,
+): LibReader {
+  const warned = new Set<string>();
+  const warnOnce = (key: string, message: string): void => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    logger?.warn?.(message);
+  };
+  return {
+    async load<T = unknown>(need: LibNeed, entry: string): Promise<T> {
+      const module = await libs.load<T>(need, entry);
+      for (const runtime of need.runs ?? []) {
+        const runner = runnerOf(runtimes, runtime);
+        if (runner === undefined) {
+          warnOnce(
+            `${need.name}:${runtime}:unsupported`,
+            `[dsh-workbench] ${need.name} 声明了自己会跑 ${runtime}，但工作台没有这个执行器 —— 它会按自己的方式找`,
+          );
+          continue;
+        }
+        const setter =
+          typeof module === 'object' && module !== null
+            ? (module as Record<string, unknown>)[setterNameOf(runtime)]
+            : undefined;
+        if (typeof setter !== 'function') {
+          warnOnce(
+            `${need.name}:${entry}:${runtime}:missing`,
+            `[dsh-workbench] ${need.name} 声明了自己会跑 ${runtime}，但这一版没有 ${setterNameOf(runtime)} —— 它会按 PATH 找`,
+          );
+          continue;
+        }
+        (setter as (runner: OpencliRunner) => void).call(module, runner);
+      }
+      return module;
+    },
+  };
+}

package/src/host/opencli-runner.ts

@@ -0,0 +1,76 @@
+import type { DataError, DataRequest, DataResult } from '../contract/data.js';
+
+/**
+ * 一条 opencli 命令的执行器：同一形状的 `execFile('opencli', args)`，结果只留 stdout。
+ */
+export type OpencliRunner = (
+  args: readonly string[],
+) => Promise<{ readonly stdout: string }>;
+
+/**
+ * 读缝（`DataReader.read`）的形状；模块直接把自己的 `data.read` 传进来即可。
+ */
+export type OpencliRead = (
+  request: DataRequest,
+) => Promise<DataResult<unknown>>;
+
+export interface OpencliRunnerOptions {
+  readonly timeoutMs?: number;
+}
+
+const AUTH_REQUIRED_EXIT_CODE = 77;
+
+function textOf(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function failedOf(args: readonly string[], error: DataError | undefined): 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 as Error & { code?: number }).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: OpencliRead,
+  options: OpencliRunnerOptions = {},
+): OpencliRunner {
+  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);
+  };
+}

package/src/host.ts

@@ -34,6 +34,8 @@ export * from './host/tokens.js';
 export * from './host/tool-approval.js';
 export * from './host/tool-kit.js';
 export * from './host/unit-face.js';
+export * from './host/opencli-runner.js';
+export * from './host/lib-runners.js';
 export * from './host/value-handoff.js';
 export * from './host/workspace-store.js';
 export * from './host/write-result.js';