@dsh-workbench/shared 0.1.0

package/src/host/opencli.ts

@@ -0,0 +1,210 @@
+import type { DshShell } from '../api/dsh.js';
+import { OPENCLI_MAX_CONCURRENT, OPENCLI_TIMEOUT_MS } from '../config/constants.js';
+import { parseJsonLoose, quoteShellArg, tailLines } from '../lib/text.js';
+import { helpUrlOf, parseCliErrorEnvelope } from './cli-error';
+import { runShell } from './shell';
+
+const FORBIDDEN_CODES = new Set(['FORBIDDEN', 'PERMISSION_DENIED']);
+
+const SITE_SESSION_ARGS = ['--site-session', 'persistent'] as const;
+
+export class WorkbenchDataError extends Error {
+  readonly code: string;
+  readonly detail?: string;
+  readonly hint?: string;
+  readonly project?: unknown;
+  readonly helpUrl?: string;
+
+  constructor(
+    code: string,
+    message: string,
+    extra: { detail?: string; hint?: string; project?: unknown; helpUrl?: string } = {},
+  ) {
+    super(message);
+    this.name = 'WorkbenchDataError';
+    this.code = code;
+    if (extra.detail !== undefined) this.detail = extra.detail;
+    if (extra.hint !== undefined) this.hint = extra.hint;
+    if (extra.project !== undefined) this.project = extra.project;
+    if (extra.helpUrl !== undefined) this.helpUrl = extra.helpUrl;
+  }
+}
+
+export interface OpencliResult {
+  readonly value: unknown;
+  readonly at: number;
+}
+
+export type OpencliSession = 'persistent' | 'ephemeral';
+
+export function opencliCommandLine(
+  command: string,
+  argv: readonly string[],
+  session: OpencliSession = 'persistent',
+): string {
+  return [
+    quoteShellArg(command),
+    ...argv.map(quoteShellArg),
+    ...(session === 'persistent' ? SITE_SESSION_ARGS : []),
+    '-f',
+    'json',
+  ].join(' ');
+}
+
+export interface Opencli {
+  json(
+    args: readonly string[],
+    options?: { key?: string; workdir?: string; session?: OpencliSession },
+  ): Promise<OpencliResult>;
+}
+
+export function createOpencli(options: {
+  shell: DshShell;
+  plugin: string;
+  logger?: { warn?(message: string): void } | undefined;
+  command?: string;
+  timeoutMs?: number;
+  maxConcurrent?: number;
+}): Opencli {
+  const {
+    shell,
+    plugin,
+    logger,
+    command = 'opencli',
+    timeoutMs = OPENCLI_TIMEOUT_MS,
+    maxConcurrent = OPENCLI_MAX_CONCURRENT,
+  } = options;
+
+  const inflight = new Map<string, Promise<OpencliResult>>();
+
+  const MAX_CONCURRENT = maxConcurrent;
+  let running = 0;
+  const waiting: Array<() => void> = [];
+
+  async function acquire(): Promise<void> {
+    if (running < MAX_CONCURRENT) {
+      running += 1;
+      return;
+    }
+    await new Promise<void>((resolve) => waiting.push(resolve));
+  }
+
+  function release(): void {
+    const next = waiting.shift();
+    if (next === undefined) running -= 1;
+    else next();
+  }
+
+  async function runLimited<T>(task: () => Promise<T>): Promise<T> {
+    await acquire();
+    try {
+      return await task();
+    } finally {
+      release();
+    }
+  }
+
+  async function call(commandLine: string, workdir: string | undefined): Promise<unknown> {
+    let result;
+    try {
+      result = await runShell(shell, commandLine, {
+        ...(workdir === undefined ? {} : { workdir }),
+        timeoutMs,
+      });
+    } catch (error) {
+      throw new WorkbenchDataError('cli-exec-failed', `执行 opencli 失败：${String(error)}`, {
+        hint: '确认 opencli 已安装且在 PATH 里（which opencli）。',
+      });
+    }
+
+    if (result.timedOut) {
+      throw new WorkbenchDataError(
+        'cli-timeout',
+        `opencli 超过 ${Math.round(timeoutMs / 1000)} 秒没有返回`,
+        { hint: '无头浏览器可能没起来，重试一次通常就好。' },
+      );
+    }
+
+    if (result.exitCode !== 0) {
+      const detail = tailLines(result.stderr || result.stdout, 6);
+      const envelope = parseCliErrorEnvelope(result.stderr) ?? parseCliErrorEnvelope(result.stdout);
+
+      const url = envelope === undefined ? undefined : helpUrlOf(envelope);
+      if (envelope?.code === 'AUTH_REQUIRED') {
+        throw new WorkbenchDataError('auth-required', envelope.message, {
+          detail,
+          ...(url === undefined ? {} : { helpUrl: url }),
+        });
+      }
+      if (envelope !== undefined && FORBIDDEN_CODES.has(envelope.code)) {
+        throw new WorkbenchDataError('permission-denied', envelope.message, {
+          detail,
+          ...(url === undefined ? {} : { helpUrl: url }),
+        });
+      }
+      if (envelope !== undefined) {
+        throw new WorkbenchDataError('cli-command-failed', `${envelope.code}：${envelope.message}`, {
+          detail,
+          ...(envelope.help === undefined ? {} : { hint: envelope.help }),
+        });
+      }
+      throw new WorkbenchDataError(
+        'cli-unclassified',
+        `opencli 这条命令没跑通（退出码 ${result.exitCode}），而且没有结构化错误码`,
+        {
+          detail,
+          hint: '多半是插件里没有这条命令（版本旧就会缺），也可能是命令自己失败了：先确认命令存在，再更新插件重试。',
+        },
+      );
+    }
+
+    const parsed = parseJsonLoose(result.stdout);
+    if (parsed === undefined) {
+      throw new WorkbenchDataError('cli-bad-output', 'opencli 输出不是 JSON', {
+        detail: tailLines(result.stdout, 4),
+      });
+    }
+    return parsed;
+  }
+
+  async function json(
+    args: readonly string[],
+    callOptions: { key?: string; workdir?: string; session?: OpencliSession } = {},
+  ): Promise<OpencliResult> {
+    const { key, workdir } = callOptions;
+    const session = callOptions.session ?? 'persistent';
+    const callKey = key ?? args.map((arg) => String(arg)).join(' ');
+
+    const pending = inflight.get(callKey);
+    if (pending !== undefined) return pending;
+
+    const commandLine = opencliCommandLine(command, [plugin, ...args], session);
+
+    const once = async (): Promise<OpencliResult> => {
+      const value = await call(commandLine, workdir);
+      return { value, at: Date.now() };
+    };
+
+    const task = runLimited(async (): Promise<OpencliResult> => {
+      try {
+        return await once();
+      } catch (error) {
+        if (!(error instanceof WorkbenchDataError) || error.code !== 'auth-required') throw error;
+        return await once();
+      }
+    });
+
+    inflight.set(callKey, task);
+    try {
+      return await task;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger?.warn?.(`[dsh-workbench] opencli 调用失败：${message}`);
+      throw error;
+    } finally {
+      inflight.delete(callKey);
+    }
+  }
+
+  return { json };
+}

package/src/host/plugin-source.ts

@@ -0,0 +1,145 @@
+import type { PluginSource } from '../api/unit.js';
+import { quoteShellArg } from '../lib/text.js';
+import { npmCacheDir, toolchainOpencliDir, vendorPeerLink, vendorPrefix } from '../host/opencli-runtime.js';
+
+export type PluginSourceProblem =
+  | "not-declared"
+  | "env-missing"
+  | "malformed";
+
+export interface PluginSourceCommand {
+  readonly line: string;
+  readonly optional?: true;
+}
+
+export type ResolvedPluginSource =
+  | {
+      readonly ok: true;
+      readonly commands: readonly PluginSourceCommand[];
+      readonly line: string;
+    }
+  | {
+      readonly ok: false;
+      readonly problem: PluginSourceProblem;
+      readonly env?: string;
+    };
+
+export interface PluginSourceOptions {
+  readonly command?: string;
+  readonly plugin?: string;
+  readonly version?: string;
+  readonly mode?: "install" | "update";
+}
+
+function mergeLines(commands: readonly PluginSourceCommand[]): string {
+  return commands
+    .map((item) =>
+      item.optional === true ? `(${item.line} || true)` : item.line,
+    )
+    .join(" && ");
+}
+
+function envValue(
+  env: Readonly<Record<string, string | undefined>>,
+  name: string,
+): { readonly ok: true; readonly value: string } | { readonly ok: false } {
+  const value = env[name]?.trim();
+  return value === undefined || value === ""
+    ? { ok: false }
+    : { ok: true, value };
+}
+
+export function npmRegistryOf(
+  source: { readonly registryEnv: string; readonly registryDefault?: string },
+  env: Readonly<Record<string, string | undefined>>,
+): { readonly ok: true; readonly value: string } | { readonly ok: false } {
+  const fromEnv = envValue(env, source.registryEnv);
+  if (fromEnv.ok) return fromEnv;
+  const fallback = source.registryDefault?.trim();
+  return fallback === undefined || fallback === ""
+    ? { ok: false }
+    : { ok: true, value: fallback };
+}
+
+function installOne(command: string, spec: string): ResolvedPluginSource {
+  const line = `${quoteShellArg(command)} plugin install ${quoteShellArg(spec)}`;
+  return { ok: true, commands: [{ line }], line };
+}
+
+function npmSource(
+  source: {
+    readonly package: string;
+    readonly registryEnv: string;
+    readonly registryDefault?: string;
+  },
+  env: Readonly<Record<string, string | undefined>>,
+  options: PluginSourceOptions,
+): ResolvedPluginSource {
+  const registry = npmRegistryOf(source, env);
+  if (!registry.ok)
+    return { ok: false, problem: "env-missing", env: source.registryEnv };
+
+  const name = source.package.trim();
+  if (name === "") return { ok: false, problem: "malformed" };
+
+  const {
+    command = "opencli",
+    plugin = "",
+    version = "latest",
+    mode = "install",
+  } = options;
+  const prefix = vendorPrefix();
+  const dirInPrefix = `${prefix}/node_modules/${name}`;
+  const peer = vendorPeerLink();
+
+  const commands: PluginSourceCommand[] = [
+    {
+      line: [
+        "npm i",
+        `--prefix ${quoteShellArg(prefix)}`,
+        quoteShellArg(`${name}@${version}`),
+        `--registry ${quoteShellArg(registry.value)}`,
+        `--cache ${quoteShellArg(npmCacheDir())}`,
+      ].join(" "),
+    },
+    {
+      line: `rm -rf ${quoteShellArg(peer.dir)} && mkdir -p ${quoteShellArg(peer.parent)} && ln -s ${quoteShellArg(toolchainOpencliDir())} ${quoteShellArg(peer.dir)}`,
+    },
+  ];
+
+  if (mode === "install") {
+    if (plugin !== "") {
+      commands.push({
+        line: `${quoteShellArg(command)} plugin uninstall ${quoteShellArg(plugin)}`,
+        optional: true,
+      });
+    }
+    commands.push({
+      line: `NPM_CONFIG_REGISTRY=${quoteShellArg(registry.value)} ${quoteShellArg(command)} plugin install ${quoteShellArg(dirInPrefix)}`,
+    });
+  }
+
+  return { ok: true, commands, line: mergeLines(commands) };
+}
+
+export function resolvePluginSource(
+  source: PluginSource | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+  options: PluginSourceOptions = {},
+): ResolvedPluginSource {
+  if (source === undefined) return { ok: false, problem: "not-declared" };
+
+  const command = options.command ?? "opencli";
+  if (source.kind === "git") {
+    const url = source.url.trim();
+    return url === ""
+      ? { ok: false, problem: "malformed" }
+      : installOne(command, url);
+  }
+  if (source.kind === "npm") return npmSource(source, env, options);
+
+  const value = envValue(env, source.env);
+  return value.ok
+    ? installOne(command, value.value)
+    : { ok: false, problem: "env-missing", env: source.env };
+}

package/src/host/provision.ts

@@ -0,0 +1,34 @@
+import type { ProvisionAction } from '../api/workbench-contract.js';
+
+export type { ProvisionAction };
+
+export const PROVISION_ACTIONS = [
+  'install',
+  'update',
+  'uninstall',
+  'update-dependency',
+] as const satisfies readonly ProvisionAction[];
+
+export const DEPENDENCY_ACTIONS = ['update-dependency'] as const satisfies readonly ProvisionAction[];
+
+export function isDependencyAction(
+  action: ProvisionAction,
+): action is (typeof DEPENDENCY_ACTIONS)[number] {
+  return (DEPENDENCY_ACTIONS as readonly ProvisionAction[]).includes(action);
+}
+
+type MissingAction = Exclude<ProvisionAction, (typeof PROVISION_ACTIONS)[number]>;
+
+const ALL_ACTIONS_COVERED: MissingAction extends never ? true : never = true;
+void ALL_ACTIONS_COVERED;
+
+export interface ProvisionRequest {
+  readonly action: ProvisionAction;
+  readonly unit?: string;
+  readonly id?: string;
+}
+
+export interface ProvisionHandler {
+  handle(request: ProvisionRequest): Promise<unknown> | unknown;
+  affectedUnits?(request: ProvisionRequest): readonly string[];
+}

package/src/host/shell.ts

@@ -0,0 +1,42 @@
+import type { DshShell } from '../api/dsh.js';
+import { GIT_TIMEOUT_MS } from '../config/constants.js';
+
+export interface ShellResult {
+  readonly exitCode: number | null;
+  readonly timedOut: boolean;
+  readonly aborted: boolean;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly truncated: boolean;
+}
+
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+
+export async function runShell(
+  shell: DshShell,
+  command: string,
+  options: { workdir?: string; timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<ShellResult> {
+  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal } = options;
+
+  const spec = shell.resolve({
+    command,
+    ...(workdir === undefined ? {} : { workdir }),
+    timeoutMs,
+    onExpiry: 'kill',
+    stdoutMaxBytes: DEFAULT_MAX_BYTES,
+    ...(signal === undefined ? {} : { signal }),
+  });
+
+  const execution = await shell.execute(spec);
+  const result = await execution.result();
+
+  return {
+    exitCode: result.exitCode,
+    timedOut: result.timedOut === true,
+    aborted: result.aborted === true,
+    stdout: result.stdout.text,
+    stderr: result.stderr.text,
+    truncated: result.stdout.truncated || result.stderr.truncated,
+  };
+}

package/src/host/tool-approval.ts

@@ -0,0 +1,243 @@
+export type AskDecision =
+  | {
+      readonly kind: 'ask';
+      readonly reason: string;
+      readonly displayReason: { readonly en: string; readonly zh: string };
+    }
+  | {
+      readonly kind: 'deny';
+      readonly reason: string;
+    };
+
+export interface ApprovalDetail {
+  readonly en: string;
+  readonly zh: string;
+}
+
+export type ApprovalFacts = ApprovalDetail | { readonly blocked: string };
+
+export interface ApprovalCall {
+  readonly name?: string | undefined;
+  readonly arguments?: unknown;
+  readonly workspace?: string | undefined;
+}
+
+export interface ApprovalContext {
+  readonly titleOf?: ((id: string) => string | undefined) | undefined;
+  readonly writes?: boolean | undefined;
+  readonly detailOf?:
+    | ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>)
+    | undefined;
+}
+
+function compose(
+  detail: ApprovalDetail | undefined,
+  texts: { readonly generic: ApprovalDetail; readonly question: ApprovalDetail },
+): ApprovalDetail {
+  if (detail === undefined || typeof detail.zh !== 'string' || detail.zh.trim() === '') return texts.generic;
+  return { en: `${detail.en} — ${texts.question.en}`, zh: `${detail.zh} —— ${texts.question.zh}` };
+}
+
+function actionOf(call: ApprovalCall): { action?: string; id?: string } {
+  const raw = call.arguments;
+  if (typeof raw !== 'object' || raw === null) return {};
+  const value = raw as { action?: unknown; id?: unknown; unit?: unknown };
+  return {
+    ...(typeof value.action === 'string' ? { action: value.action } : {}),
+    ...(typeof value.id === 'string' ? { id: value.id } : typeof value.unit === 'string' ? { id: value.unit } : {}),
+  };
+}
+
+const READ_ONLY_ACTIONS = new Set(['list', '']);
+
+interface AskSpec {
+  readonly reason: string;
+  readonly generic: ApprovalDetail;
+  readonly question: ApprovalDetail;
+}
+
+type CallEffect =
+  | { readonly kind: 'ask'; readonly spec: AskSpec }
+  | { readonly kind: 'read' }
+  | { readonly kind: 'unknown' };
+
+const READ: CallEffect = { kind: 'read' };
+const UNKNOWN: CallEffect = { kind: 'unknown' };
+
+function ask(spec: AskSpec): CallEffect {
+  return { kind: 'ask', spec };
+}
+
+function confirmed(call: ApprovalCall): boolean | undefined {
+  const raw = call.arguments;
+  if (typeof raw !== 'object' || raw === null) return undefined;
+  const value = (raw as { confirm?: unknown }).confirm;
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function effectOf(call: ApprovalCall, context: ApprovalContext): CallEffect {
+  const name = call.name ?? '';
+  const { action, id } = actionOf(call);
+  const readAction = action !== undefined && action !== '' && READ_ONLY_ACTIONS.has(action);
+
+  const what = (): string => {
+    if (id === undefined || id === '') return '一个模块';
+    return `「${context.titleOf?.(id) ?? id}」`;
+  };
+
+  if (name === 'workbench_cmdb_release') {
+    if (confirmed(call) !== true) return READ;
+    return ask({
+      reason: 'confirm=true releases a version to a real environment',
+      generic: {
+        en: 'The agent wants to deploy a version for real (confirm: true) — it deploys on the platform (non-production). Allow?',
+        zh: 'agent 想在非生产环境上**真的部署一个版本**（confirm: true）—— 会在平台上部署。允许吗？',
+      },
+      question: {
+        en: 'it deploys on the platform for real (non-production). Allow?',
+        zh: '会在平台上真的部署一次（非生产环境）。允许吗？',
+      },
+    });
+  }
+
+  if (name === 'workbench_coding_issue_comment' || name === 'workbench_coding_issue_transfer') {
+    if (confirmed(call) !== true) return READ;
+    const comment = name === 'workbench_coding_issue_comment';
+    return ask({
+      reason: comment
+        ? 'confirm=true posts a comment on the platform'
+        : 'confirm=true moves an issue to another status on the platform',
+      generic: comment
+        ? {
+            en: 'The agent wants to post a comment on the platform for real (confirm: true) — it writes on the platform. Allow?',
+            zh: 'agent 想**真的给一条缺陷加评论**（confirm: true）—— 会写平台数据。允许吗？',
+          }
+        : {
+            en: 'The agent wants to move an issue to another status for real (confirm: true) — it writes on the platform. Allow?',
+            zh: 'agent 想**真的把一条缺陷流转到别的状态**（confirm: true）—— 会写平台数据。允许吗？',
+          },
+      question: comment
+        ? {
+            en: 'it posts that comment on the platform for real. Allow?',
+            zh: '会在平台上真的发表这条评论。允许吗？',
+          }
+        : {
+            en: 'it changes that issue status on the platform for real. Allow?',
+            zh: '会在平台上真的改这条缺陷的状态。允许吗？',
+          },
+    });
+  }
+
+  if (name === 'workbench_modules') {
+    if (readAction) return READ;
+    if (action === 'update-dependency') {
+      return ask({
+        reason: `workbench_modules update-dependency ${id ?? ''} upgrades a shared dependency on this machine`,
+        generic: {
+          en: `The agent wants to upgrade the shared dependency ${what()} (it changes what is installed on this machine). Allow?`,
+          zh: `agent 想升级共用依赖 ${what()}（会改这台机器上装的东西）。允许吗？`,
+        },
+        question: {
+          en: 'it upgrades that shared dependency on this machine. Allow?',
+          zh: `会升级共用依赖 ${what()}。允许吗？`,
+        },
+      });
+    }
+    const verb = action === 'install' ? '装' : action === 'uninstall' ? '卸载' : action === 'update' ? '更新' : '装 / 更新 / 卸载';
+    return ask({
+      reason: `workbench_modules ${action ?? '(unknown action)'} ${id ?? ''} changes plugins on this machine`.trim(),
+      generic: {
+        en: `The agent wants to ${verb === '装' ? 'install' : verb === '卸载' ? 'remove' : verb === '更新' ? 'update' : 'install/update/remove'} the module ${what()} (it changes plugins on this machine). Allow?`,
+        zh: `agent 想${verb}模块 ${what()}（会改这台机器上的插件）。允许吗？`,
+      },
+      question: {
+        en: 'it changes plugins on this machine. Allow?',
+        zh: '会改这台机器上的插件。允许吗？',
+      },
+    });
+  }
+
+  if (name !== 'workbench_panels') return UNKNOWN;
+
+  if (readAction) return READ;
+
+  if (action === 'hide') {
+    return ask({
+      reason: 'workbench_panels hide removes a module from the panel',
+      generic: {
+        en: `The agent wants to remove ${what()} from this project's panel (its agent tools go offline here too). Allow?`,
+        zh: `agent 想把 ${what()} 从这个项目的面板上收起来（这个项目里它的 agent 工具也一起下线）。允许吗？`,
+      },
+      question: {
+        en: 'it takes that module off this panel (its agent tools go offline here too). Allow?',
+        zh: `${what()}会从这个项目的面板上收起来（这个项目里它的 agent 工具也一起下线）。允许吗？`,
+      },
+    });
+  }
+  if (action === 'move') {
+    return ask({
+      reason: 'workbench_panels move reorders the panel',
+      generic: {
+        en: `The agent wants to reorder this project's panel (put ${what()} first). Allow?`,
+        zh: `agent 想调整这个项目面板的顺序（把 ${what()} 放前面）。允许吗？`,
+      },
+      question: {
+        en: `it reorders this panel (${what()} goes first). Allow?`,
+        zh: `会调整这个项目面板的顺序（${what()}放前面）。允许吗？`,
+      },
+    });
+  }
+  if (action === 'reset') {
+    return ask({
+      reason: 'workbench_panels reset clears the panel',
+      generic: {
+        en: "The agent wants to clear this project's panel (every module goes offline here). Allow?",
+        zh: 'agent 想清空这个项目的面板（所有模块在这个项目里都下线）。允许吗？',
+      },
+      question: {
+        en: 'it clears this panel (every module goes offline here). Allow?',
+        zh: '会清空这个项目的面板（所有模块在这个项目里都下线）。允许吗？',
+      },
+    });
+  }
+  return ask({
+    reason: `workbench_panels ${action ?? '(unknown action)'} changes the user's panel`,
+    generic: {
+      en: `The agent wants to add ${what()} to this project's panel. Allow?`,
+      zh: `agent 想把 ${what()} 加到**这个项目**的面板上。允许吗？`,
+    },
+    question: {
+      en: `it adds ${what()} to this project's panel. Allow?`,
+      zh: `会把 ${what()} 加到**这个项目**的面板上。允许吗？`,
+    },
+  });
+}
+
+export async function approvalFor(
+  call: ApprovalCall,
+  context: ApprovalContext = {},
+): Promise<AskDecision | undefined> {
+  const effect = effectOf(call, context);
+  if (effect.kind === 'read') return undefined;
+  if (effect.kind === 'unknown') {
+    if (context.writes !== true) return undefined;
+    return {
+      kind: 'deny',
+      reason:
+        `${call.name ?? '这把工具'} 在清单里声明会写东西，但审批表没认领这次调用 —— 停下：` +
+        '给它在 tool-approval.ts 里补一条审批（含"这次会发生什么"），别让写静默过去',
+    };
+  }
+  const { spec } = effect;
+
+  let facts: ApprovalFacts | undefined;
+  try {
+    facts = await context.detailOf?.(call);
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return { kind: 'deny', reason: `拿不到"这次会发生什么"，已经停下：${why}` };
+  }
+  if (facts !== undefined && 'blocked' in facts) return { kind: 'deny', reason: facts.blocked };
+
+  return { kind: 'ask', reason: spec.reason, displayReason: compose(facts, spec) };
+}