@dsh-workbench/shared 0.1.0

package/src/config/storage.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { readFlag, readText, writeFlag, writeText } from './storage';
+
+function fakeStorage(options: { throwOnWrite?: boolean } = {}) {
+  const data = new Map<string, string>();
+  return {
+    data,
+    storage: {
+      getItem: (key: string) => data.get(key) ?? null,
+      setItem: (key: string, value: string) => {
+        if (options.throwOnWrite === true) throw new Error('QuotaExceededError');
+        data.set(key, value);
+      },
+      removeItem: (key: string) => {
+        data.delete(key);
+      },
+    },
+  };
+}
+
+function useStorage(options: { throwOnWrite?: boolean } = {}) {
+  const fake = fakeStorage(options);
+  vi.stubGlobal('window', { localStorage: fake.storage });
+  return fake;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('storage', () => {
+  it('写进去能读回来', () => {
+    const fake = useStorage();
+    writeText('k', 'v');
+    expect(readText('k')).toBe('v');
+    expect(fake.data.get('k')).toBe('v');
+  });
+
+  it('写 null 等于删除', () => {
+    const fake = useStorage();
+    writeText('k', 'v');
+    writeText('k', null);
+    expect(readText('k')).toBeNull();
+    expect(fake.data.has('k')).toBe(false);
+  });
+
+  it('没存过时读回 null / 默认值', () => {
+    useStorage();
+    expect(readText('missing')).toBeNull();
+    expect(readFlag('missing', true)).toBe(true);
+    expect(readFlag('missing', false)).toBe(false);
+  });
+
+  it('布尔开关按字面量往返', () => {
+    useStorage();
+    writeFlag('on', true);
+    writeFlag('off', false);
+    expect(readFlag('on', false)).toBe(true);
+    expect(readFlag('off', true)).toBe(false);
+  });
+
+  it('只有字面量 "true" 算真：脏数据不因为"非空"就把开关打开', () => {
+    useStorage();
+    writeText('weird', 'yes');
+    writeText('one', '1');
+    expect(readFlag('weird', true)).toBe(false);
+    expect(readFlag('one', true)).toBe(false);
+    expect(readFlag('never', true)).toBe(true);
+  });
+
+  it('localStorage 抛异常时静默降级（隐私模式不该让面板崩掉）', () => {
+    useStorage({ throwOnWrite: true });
+    expect(() => writeText('k', 'v')).not.toThrow();
+    expect(readText('k')).toBeNull();
+  });
+
+  it('window 上没有 localStorage 时也不抛', () => {
+    vi.stubGlobal('window', {});
+    expect(() => writeText('k', 'v')).not.toThrow();
+    expect(readText('k')).toBeNull();
+  });
+});

package/src/config/storage.ts

@@ -0,0 +1,25 @@
+export function readText(key: string): string | null {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+export function writeText(key: string, value: string | null): void {
+  try {
+    if (value === null) window.localStorage.removeItem(key);
+    else window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+
+export function readFlag(key: string, fallback: boolean): boolean {
+  const raw = readText(key);
+  if (raw === null) return fallback;
+  return raw === 'true';
+}
+
+export function writeFlag(key: string, value: boolean): void {
+  writeText(key, value ? 'true' : 'false');
+}

package/src/host/__tests__/fakes.ts

@@ -0,0 +1,116 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import type { DshShell } from '../../api/dsh.js';
+import type { Opencli, OpencliResult } from '../../host/opencli.js';
+
+export interface ShellCall {
+  command: string;
+  workdir?: string;
+  timeoutMs?: number;
+  onExpiry?: string;
+  stdoutMaxBytes?: number;
+}
+
+export interface ShellReply {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  timedOut?: boolean;
+  aborted?: boolean;
+  failWith?: Error;
+}
+
+const tick = (): Promise<void> => delay(0);
+
+export function createFakeShell(replies: ShellReply[] | ((call: ShellCall, index: number) => ShellReply) = []) {
+  const calls: ShellCall[] = [];
+  let running = 0;
+  let peak = 0;
+
+  const replyAt = (index: number): ShellReply =>
+    typeof replies === 'function' ? replies(calls[index] as ShellCall, index) : (replies[index] ?? {});
+
+  const shell: DshShell = {
+    resolve(request) {
+      calls.push(request as ShellCall);
+      return request;
+    },
+    async execute() {
+      const index = calls.length - 1;
+      const reply = replyAt(index);
+      if (reply.failWith !== undefined) throw reply.failWith;
+
+      running += 1;
+      peak = Math.max(peak, running);
+
+      return {
+        async result() {
+          await tick();
+          running -= 1;
+          return {
+            exitCode: reply.exitCode ?? 0,
+            timedOut: reply.timedOut ?? false,
+            aborted: reply.aborted ?? false,
+            stdout: { text: reply.stdout ?? '', truncated: false },
+            stderr: { text: reply.stderr ?? '', truncated: false },
+          };
+        },
+      };
+    },
+  };
+
+  return {
+    shell,
+    calls,
+    peak: () => peak,
+    commands: () => calls.map((call) => call.command),
+  };
+}
+
+export interface OpencliCall {
+  args: readonly string[];
+  key?: string;
+  workdir?: string;
+  refresh?: boolean;
+}
+
+export function createFakeOpencli(
+  replies: Array<unknown | Error> | ((call: OpencliCall, index: number) => unknown | Error) = [],
+) {
+  const calls: OpencliCall[] = [];
+
+  const opencli: Opencli = {
+    async json(args, options = {}) {
+      const call: OpencliCall = {
+        args,
+        ...(options.key === undefined ? {} : { key: options.key }),
+        ...(options.workdir === undefined ? {} : { workdir: options.workdir }),
+      };
+      calls.push(call);
+      const index = calls.length - 1;
+      const reply =
+        typeof replies === 'function' ? replies(call, index) : (replies[index] ?? []);
+
+      if (reply instanceof Error) throw reply;
+      return { value: reply, at: Date.now() } satisfies OpencliResult;
+    },
+  };
+
+  return {
+    opencli,
+    calls,
+    keys: () => calls.map((call) => call.key),
+  };
+}
+
+export function createFakeLogger() {
+  const warnings: string[] = [];
+  return {
+    logger: {
+      info: () => {},
+      warn: (message: string) => {
+        warnings.push(message);
+      },
+    },
+    warnings,
+  };
+}

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

@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OPENCLI_PIN } from '../../config/constants.js';
+
+async function load(dshHome: string, home: string) {
+  vi.resetModules();
+  vi.stubEnv('DSH_HOME', dshHome);
+  vi.stubEnv('HOME', home);
+  return import('../opencli-runtime');
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetModules();
+});
+
+describe('opencli 隔离运行时', () => {
+  it('三条路径都从 $DSH_HOME 推（与 wrapper 必须一致）', async () => {
+    const runtime = await load('/tmp/dshhome', '/tmp/realhome');
+
+    expect(runtime.isolatedRoot()).toBe('/tmp/dshhome/workbench/opencli');
+    expect(runtime.isolatedHome()).toBe('/tmp/dshhome/workbench/opencli/home');
+    expect(runtime.toolchainDir()).toBe('/tmp/dshhome/workbench/opencli/toolchain');
+  });
+
+  it('DSH_HOME 为空 → 退回 $HOME/.dsh（与 wrapper 的 `${DSH_HOME:-…}` 同义）', async () => {
+    const runtime = await load('', '/tmp/realhome');
+
+    expect(runtime.isolatedRoot()).toBe('/tmp/realhome/.dsh/workbench/opencli');
+  });
+
+  it('★ 安装命令装进**隔离前缀**且钉住版本 —— 不是 npm i -g', async () => {
+    const runtime = await load('/tmp/dshhome', '/tmp/realhome');
+    const command = runtime.isolatedInstallCommand();
+
+    expect(command).toContain("--prefix '/tmp/dshhome/workbench/opencli/toolchain'");
+    expect(command).toContain(`@jackwener/opencli@${OPENCLI_PIN}`);
+    expect(command).not.toContain(' -g');
+    expect(command).toContain("--cache '/tmp/dshhome/workbench/opencli/npm-cache'");
+  });
+
+  it('★ 对外给的入口是**稳定路径**（软链），不依赖本仓库在哪', async () => {
+    const runtime = await load('/tmp/dshhome', '/tmp/realhome');
+
+    expect(runtime.isolatedCommand()).toBe('/tmp/dshhome/workbench/opencli/bin/opencli');
+  });
+});

package/src/host/cli-error.ts

@@ -0,0 +1,77 @@
+export interface CliErrorEnvelope {
+  readonly code: string;
+  readonly message: string;
+  readonly help?: string;
+  readonly exitCode?: number;
+}
+
+function unquote(raw: string): string {
+  const value = raw.trim();
+  if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function joinBlock(previous: string, line: string, fold: boolean): string {
+  if (previous === '') return line;
+  return fold ? `${previous} ${line}` : `${previous}\n${line}`;
+}
+
+export function parseCliErrorEnvelope(text: string | undefined): CliErrorEnvelope | undefined {
+  if (text === undefined || text.trim() === '') return undefined;
+
+  const lines = text.split('\n');
+  const start = lines.findIndex((line) => /^error:\s*$/.test(line.trim()) || /^error:\s*\S/.test(line.trim()));
+  if (start === -1) return undefined;
+
+  const scalars: Record<string, string> = {};
+  let current: string | undefined;
+  let block: { readonly key: string; readonly fold: boolean; readonly indent: number } | undefined;
+  const errorIndent = lines[start]?.search(/\S/) ?? 0;
+  for (const line of lines.slice(start + 1)) {
+    if (line.trim() === '') continue;
+    const indent = line.search(/\S/);
+    if (block !== undefined && indent > block.indent) {
+      scalars[block.key] = joinBlock(scalars[block.key] ?? '', line.trim(), block.fold);
+      continue;
+    }
+    block = undefined;
+    if (indent <= errorIndent) break;
+
+    const match = /^\s*(code|message|help|exitCode):\s*(.*)$/.exec(line);
+    if (match === null) {
+      if (current !== undefined) scalars[current] = `${scalars[current] ?? ''} ${line.trim()}`.trim();
+      continue;
+    }
+    const [, key, value] = match;
+    if (key === undefined) continue;
+    const raw = (value ?? '').trim();
+    const marker = /^([|>])[0-9]*([+-]?)$/.exec(raw);
+    if (marker !== null) {
+      scalars[key] = '';
+      block = { key, fold: marker[1] === '>', indent };
+      current = key;
+      continue;
+    }
+    scalars[key] = unquote(raw);
+    current = key;
+  }
+
+  const code = scalars['code'];
+  const message = scalars['message'];
+  if (code === undefined || code === '') return undefined;
+
+  const exitCode = scalars['exitCode'];
+  return {
+    code,
+    message: message ?? code,
+    ...(scalars['help'] === undefined || scalars['help'] === '' ? {} : { help: scalars['help'] }),
+    ...(exitCode === undefined || Number.isNaN(Number(exitCode)) ? {} : { exitCode: Number(exitCode) }),
+  };
+}
+
+export function helpUrlOf(envelope: CliErrorEnvelope): string | undefined {
+  const match = /https?:\/\/[^\s"'`]+/.exec(envelope.help ?? '');
+  return match?.[0];
+}

package/src/host/data-root.ts

@@ -0,0 +1,13 @@
+export function dshHome(): string {
+  const configured = process.env.DSH_HOME?.trim();
+  if (configured !== undefined && configured !== '') return configured;
+  return `${process.env.HOME ?? ''}/.dsh`;
+}
+
+export function workbenchRoot(): string {
+  return `${dshHome()}/workbench`;
+}
+
+export function workspacesRoot(): string {
+  return `${workbenchRoot()}/workspaces`;
+}

package/src/host/facts.ts

@@ -0,0 +1,69 @@
+import type { UnitManifest } from '../api/unit.js';
+
+export interface FactChange {
+  readonly rev: number;
+  readonly facts: readonly string[];
+}
+
+export interface FactSnapshot extends FactChange {
+  readonly epoch: string;
+}
+
+export interface FactLog {
+  bump(facts: readonly string[]): FactChange;
+  revision(): number;
+  epoch(): string;
+  since(rev: number): FactSnapshot;
+  subscribe(listener: (change: FactChange) => void): () => void;
+}
+
+export function createFactLog(options: { readonly epoch?: string } = {}): FactLog {
+  const epoch = options.epoch ?? `e${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+  let rev = 0;
+  const last = new Map<string, number>();
+  const listeners = new Set<(change: FactChange) => void>();
+
+  return {
+    epoch: () => epoch,
+    revision: () => rev,
+    bump(facts) {
+      rev += 1;
+      const named = [...new Set(facts.filter((name) => name !== ''))];
+      for (const name of named) last.set(name, rev);
+      const change: FactChange = { rev, facts: named };
+      for (const listener of [...listeners]) listener(change);
+      return change;
+    },
+    since(seen) {
+      const facts = [...last.entries()].filter(([, at]) => at > seen).map(([name]) => name);
+      return { epoch, rev, facts };
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+export interface ToolUnit {
+  readonly unit: string;
+  readonly writes: boolean;
+}
+
+export function toolUnits(manifests: readonly UnitManifest[]): Map<string, ToolUnit> {
+  const map = new Map<string, ToolUnit>();
+  for (const manifest of manifests) {
+    for (const tool of manifest.tools ?? []) {
+      map.set(tool.name, { unit: manifest.id, writes: tool.writes });
+    }
+  }
+  return map;
+}
+
+export function wroteNow(result: unknown): boolean | undefined {
+  const value = (result as { value?: unknown } | null)?.value;
+  const wrote = (value as { wrote?: unknown } | null)?.wrote;
+  return typeof wrote === 'boolean' ? wrote : undefined;
+}

package/src/host/git.ts

@@ -0,0 +1,99 @@
+import type { DshShell } from '../api/dsh.js';
+import { quoteShellArg, tailLines } from '../lib/text.js';
+import { runShell } from './shell.js';
+
+export type OriginRead =
+  | { readonly kind: 'ok'; readonly remote: string }
+  | { readonly kind: 'no-origin'; readonly detail?: string }
+  | { readonly kind: 'unknown'; readonly reason: string; readonly detail?: string };
+
+export type OriginReader = (path: string) => Promise<OriginRead>;
+
+export type BranchRead =
+  | { readonly kind: 'ok'; readonly branch: string }
+  | { readonly kind: 'no-branch'; readonly detail?: string | undefined }
+  | { readonly kind: 'unknown'; readonly reason: string; readonly detail?: string | undefined };
+
+export type BranchReader = (path: string) => Promise<BranchRead>;
+
+export type HeadRead =
+  | { readonly kind: 'ok'; readonly commit: string }
+  | { readonly kind: 'no-head'; readonly detail?: string }
+  | { readonly kind: 'unknown'; readonly reason: string; readonly detail?: string };
+
+export type HeadReader = (path: string) => Promise<HeadRead>;
+
+export function createHeadReader(options: {
+  shell: DshShell;
+  logger?: { warn?(message: string): void } | undefined;
+}): HeadReader {
+  const { shell, logger } = options;
+
+  return async function readHead(path: string): Promise<HeadRead> {
+    const key = String(path ?? '').trim();
+    if (!key) return { kind: 'unknown', reason: 'no-path' };
+
+    let result;
+    try {
+      result = await runShell(shell, `git -C ${quoteShellArg(key)} rev-parse HEAD`);
+    } catch (error) {
+      logger?.warn?.(`[dsh-workbench] git rev-parse 执行失败：${String(error)}`);
+      return { kind: 'unknown', reason: 'exec-failed', detail: String(error) };
+    }
+
+    if (result.exitCode !== 0) {
+      return { kind: 'no-head', detail: tailLines(result.stderr, 3) };
+    }
+    return { kind: 'ok', commit: result.stdout.trim() };
+  };
+}
+
+export function createBranchReader(options: {
+  shell: DshShell;
+  logger?: { warn?(message: string): void } | undefined;
+}): BranchReader {
+  const { shell, logger } = options;
+
+  return async function readBranch(path: string): Promise<BranchRead> {
+    const key = String(path ?? '').trim();
+    if (!key) return { kind: 'unknown', reason: 'no-path' };
+
+    let result;
+    try {
+      result = await runShell(shell, `git -C ${quoteShellArg(key)} rev-parse --abbrev-ref HEAD`);
+    } catch (error) {
+      logger?.warn?.(`[dsh-workbench] git rev-parse --abbrev-ref 执行失败：${String(error)}`);
+      return { kind: 'unknown', reason: 'exec-failed', detail: String(error) };
+    }
+
+    const name = result.stdout.trim();
+    if (result.exitCode !== 0) return { kind: 'no-branch', detail: tailLines(result.stderr, 3) };
+    if (name === '' || name === 'HEAD') return { kind: 'no-branch', detail: name };
+    return { kind: 'ok', branch: name };
+  };
+}
+
+export function createOriginReader(options: {
+  shell: DshShell;
+  logger?: { warn?(message: string): void } | undefined;
+}): OriginReader {
+  const { shell, logger } = options;
+
+  return async function readOrigin(path: string): Promise<OriginRead> {
+    const key = String(path ?? '').trim();
+    if (!key) return { kind: 'unknown', reason: 'no-path' };
+
+    let result;
+    try {
+      result = await runShell(shell, `git -C ${quoteShellArg(key)} remote get-url origin`);
+    } catch (error) {
+      logger?.warn?.(`[dsh-workbench] git remote 执行失败：${String(error)}`);
+      return { kind: 'unknown', reason: 'exec-failed', detail: String(error) };
+    }
+
+    if (result.exitCode !== 0) {
+      return { kind: 'no-origin', detail: tailLines(result.stderr, 3) };
+    }
+    return { kind: 'ok', remote: result.stdout.trim() };
+  };
+}