@dsh-workbench/shared 1.1.14-beta.2 → 1.1.14

package/src/host/seam/exec.ts

@@ -0,0 +1,94 @@
+import type { ShellResult } from '../shell.js';
+import type { ShellKind } from '../shell-text.js';
+import type { WriteIntent } from './intent.js';
+
+export type SeamShellKind = ShellKind;
+
+export interface HostWriteIntent {
+  readonly kind: 'host';
+}
+
+export type ExecIntent = WriteIntent | HostWriteIntent;
+
+export type SeamTarget =
+  | { readonly argv: readonly string[] }
+  | { readonly line: string; readonly shellKind?: SeamShellKind | undefined };
+
+export interface SeamOutcomeWithTarget extends ShellResult {
+  readonly outcome?: 'exited' | 'timed-out' | 'spawn-failed';
+}
+
+export interface SpawnRequest {
+  readonly target: SeamTarget;
+  readonly intent: ExecIntent;
+  readonly lifetime: 'host';
+  readonly cwd?: string | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly logFile?: string | undefined;
+  readonly label?: string | undefined;
+}
+
+export interface SpawnExit {
+  readonly code: number | null;
+  readonly signal: string | null;
+}
+
+export interface SpawnHandle {
+  readonly pid: number | undefined;
+  readonly logFile: string | undefined;
+  exit(): Promise<SpawnExit>;
+  onError(listener: (error: Error) => void): () => void;
+  kill(signal?: string): void;
+}
+
+export interface OpenRequest {
+  readonly target: SeamTarget;
+  readonly intent: ExecIntent;
+  readonly cwd?: string | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly label?: string | undefined;
+}
+
+export interface ChannelHandle {
+  readonly pid: number | undefined;
+  write(chunk: string): void;
+  onData(listener: (chunk: string) => void): () => void;
+  onExit(listener: (event: SpawnExit) => void): () => void;
+  onError(listener: (error: Error) => void): () => void;
+  kill(signal?: string): void;
+}
+
+export interface ProcessSpawnOptions {
+  readonly file: string;
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly cwd?: string | undefined;
+  readonly detached: boolean;
+  readonly stdio: 'ignore' | 'pipe' | 'log';
+  readonly logFile?: string | undefined;
+  readonly windowsHide: boolean;
+}
+
+export interface ProcessExitEvent {
+  readonly code: number | null;
+  readonly signal: string | null;
+}
+
+export interface ProcessStream {
+  onData(listener: (chunk: string) => void): () => void;
+}
+
+export interface ProcessChild {
+  readonly pid: number | undefined;
+  readonly stdin: { write(chunk: string): void } | null;
+  readonly stdout: ProcessStream | null;
+  readonly stderr: ProcessStream | null;
+  onExit(listener: (event: ProcessExitEvent) => void): () => void;
+  onError(listener: (error: Error) => void): () => void;
+  unref(): void;
+  kill(signal?: string): void;
+}
+
+export interface ProcessHost {
+  spawn(options: ProcessSpawnOptions): ProcessChild;
+}

package/src/host/seam/host-env.ts

@@ -0,0 +1,20 @@
+export function hostEnvOf(
+  env: Readonly<Record<string, string | undefined>> | undefined,
+): Record<string, string | undefined> {
+  const merged: Record<string, string | undefined> = { ...process.env };
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (value === undefined) delete merged[key];
+    else merged[key] = value;
+  }
+  return merged;
+}
+
+export function definedEnvOf(
+  env: Readonly<Record<string, string | undefined>> | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}

package/src/host/seam/intent.ts

@@ -0,0 +1,101 @@
+/**
+ * 执行缝的语义写入域：调用点只声明自己写哪一类树，不传裸根。
+ * 策略合成、环境注入与拒绝处置都住在执行缝模块里。
+ */
+export type SeamMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+
+export interface ProductWriteIntent {
+  readonly kind: 'product';
+}
+
+export interface WorkspaceWriteIntent {
+  readonly kind: 'workspace';
+}
+
+export interface PathsWriteIntent {
+  readonly kind: 'paths';
+  readonly paths: readonly string[];
+}
+
+export interface NoWriteIntent {
+  readonly kind: 'none';
+}
+
+export type WriteIntent = ProductWriteIntent | WorkspaceWriteIntent | PathsWriteIntent | NoWriteIntent;
+
+export type DenialScope = 'product' | 'workspace' | 'external' | 'unknown';
+
+export interface SeamPolicy {
+  readonly mode: SeamMode;
+  readonly workspaceRoot: string;
+}
+
+export interface SeamDenial {
+  readonly path?: string | undefined;
+  readonly scope: DenialScope;
+  readonly healed?: boolean | undefined;
+}
+
+export interface SeamFact {
+  readonly at: number;
+  readonly verb: 'run' | 'spawn' | 'open';
+  readonly command: string;
+  readonly intent: WriteIntent['kind'] | 'host';
+  readonly mode: SeamMode | 'host';
+  readonly workspaceRoot: string;
+  readonly exitCode: number | null;
+  readonly timedOut: boolean;
+  readonly stalled: boolean;
+  readonly denial?: SeamDenial | undefined;
+}
+
+export type SeamErrorCode =
+  | 'workspace-unknown'
+  | 'read-only'
+  | 'paths-span-trees'
+  | 'scope-not-declared'
+  | 'sandbox-denied'
+  | 'sandbox-unavailable';
+
+export class SeamError extends Error {
+  readonly code: SeamErrorCode;
+  readonly path?: string | undefined;
+  readonly scope?: DenialScope | undefined;
+
+  constructor(code: SeamErrorCode, message: string, extra: { readonly path?: string | undefined; readonly scope?: DenialScope | undefined } = {}) {
+    super(message);
+    this.name = 'SeamError';
+    this.code = code;
+    this.path = extra.path;
+    this.scope = extra.scope;
+  }
+}
+
+export type UnitWriteScope = 'unit' | 'workspace';
+
+export interface UnitSeamRequest {
+  readonly command: string;
+  readonly scope: UnitWriteScope;
+  readonly workdir?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  readonly session?: unknown;
+  readonly signal?: AbortSignal | undefined;
+  readonly retry?: 'safe' | 'never' | undefined;
+}
+
+export function productWrite(): WriteIntent {
+  return { kind: 'product' };
+}
+
+export function workspaceWrite(): WriteIntent {
+  return { kind: 'workspace' };
+}
+
+export function pathsWrite(paths: readonly string[]): WriteIntent {
+  return { kind: 'paths', paths };
+}
+
+export function noWrite(): WriteIntent {
+  return { kind: 'none' };
+}

package/src/host/seam/policy.ts

@@ -0,0 +1,89 @@
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import type { DenialScope, SeamMode, SeamPolicy, WriteIntent } from './intent.js';
+import { SeamError } from './intent.js';
+
+export const SEAM_MODES: readonly SeamMode[] = ['read-only', 'workspace-write', 'danger-full-access'];
+
+export function seamModeOf(value: string | undefined): SeamMode {
+  const text = value?.trim();
+  return text === 'read-only' || text === 'workspace-write' || text === 'danger-full-access' ? text : 'workspace-write';
+}
+
+function rank(mode: SeamMode): number {
+  return mode === 'read-only' ? 0 : mode === 'workspace-write' ? 1 : 2;
+}
+
+export function narrowerMode(left: SeamMode, right: SeamMode): SeamMode {
+  return rank(left) <= rank(right) ? left : right;
+}
+
+export function insideOf(root: string, path: string): boolean {
+  const confined = resolve(root);
+  const target = resolve(path);
+  if (target === confined) return true;
+  return target.startsWith(confined.endsWith(sep) ? confined : `${confined}${sep}`);
+}
+
+export function productPolicy(ceiling: SeamMode, productRoot: string): SeamPolicy {
+  return {
+    mode: ceiling === 'read-only' ? 'read-only' : 'workspace-write',
+    workspaceRoot: resolve(productRoot),
+  };
+}
+
+export function workspacePolicy(ceiling: SeamMode, grant: SeamPolicy | undefined): SeamPolicy {
+  if (grant === undefined) {
+    throw new SeamError('workspace-unknown', '这条会话解析不到工作区：先在左栏选一个工作区再跑需要写工作区的命令');
+  }
+  const mode = narrowerMode(ceiling, grant.mode);
+  if (mode === 'read-only') {
+    throw new SeamError('read-only', '当前会话是只读模式：要写工作区，先在权限设置里切换模式');
+  }
+  return { mode, workspaceRoot: resolve(grant.workspaceRoot) };
+}
+
+function commonDirectory(paths: readonly string[]): string | undefined {
+  const dirs = paths.map((path) => dirname(resolve(path)));
+  let shared = dirs[0];
+  if (shared === undefined) return undefined;
+  for (const dir of dirs.slice(1)) {
+    while (shared !== dirname(shared) && !insideOf(shared, dir)) {
+      shared = dirname(shared);
+    }
+  }
+  return shared;
+}
+
+export function pathsPolicy(ceiling: SeamMode, paths: readonly string[]): SeamPolicy {
+  if (paths.length === 0) {
+    throw new SeamError('paths-span-trees', '这次写入没有给出任何路径');
+  }
+  if (!paths.every((path) => isAbsolute(path))) {
+    throw new SeamError('paths-span-trees', '外部路径必须是绝对路径');
+  }
+  if (ceiling === 'read-only') {
+    throw new SeamError('read-only', '当前部署是只读模式：这条命令不能写外部路径');
+  }
+  const root = commonDirectory(paths);
+  if (root === undefined || (root === sep && paths.length > 1)) {
+    throw new SeamError('paths-span-trees', '这次写入跨了多个目录：请分开做，或把产物改到工作台目录');
+  }
+  if (root === sep) {
+    throw new SeamError('paths-span-trees', '不能把整个文件系统声明成写入域');
+  }
+  return { mode: 'workspace-write', workspaceRoot: root };
+}
+
+export function denialScopeOf(path: string | undefined, policy: SeamPolicy, productRoot: string, grant: SeamPolicy | undefined): DenialScope {
+  if (path === undefined) return 'unknown';
+  if (insideOf(productRoot, path)) return 'product';
+  if (grant !== undefined && insideOf(grant.workspaceRoot, path)) return 'workspace';
+  if (insideOf(policy.workspaceRoot, path)) return policy.workspaceRoot === resolve(productRoot) ? 'product' : 'workspace';
+  return 'external';
+}
+
+export function policyOf(intent: WriteIntent, ceiling: SeamMode, productRoot: string, grant: SeamPolicy | undefined): SeamPolicy {
+  if (intent.kind === 'product' || intent.kind === 'none') return productPolicy(ceiling, productRoot);
+  if (intent.kind === 'workspace') return workspacePolicy(ceiling, grant);
+  return pathsPolicy(ceiling, intent.paths);
+}

package/src/host/seam/process.ts

@@ -0,0 +1,90 @@
+import { closeSync, openSync } from 'node:fs';
+import type { Readable, Writable } from 'node:stream';
+import { execa, type Options, type ResultPromise } from 'execa';
+import type {
+  ProcessChild,
+  ProcessExitEvent,
+  ProcessHost,
+  ProcessSpawnOptions,
+  ProcessStream,
+} from './exec.js';
+
+function streamOf(readable: Readable | null | undefined): ProcessStream | null {
+  if (readable === null || readable === undefined) return null;
+  return {
+    onData(listener) {
+      const handler = (chunk: unknown): void => listener(String(chunk));
+      readable.on('data', handler);
+      return () => {
+        readable.off('data', handler);
+      };
+    },
+  };
+}
+
+export function createNodeProcessHost(): ProcessHost {
+  return {
+    spawn(options: ProcessSpawnOptions): ProcessChild {
+      const logFd =
+        options.stdio === 'log' && options.logFile !== undefined ? openSync(options.logFile, 'a') : undefined;
+      const stdio: Options['stdio'] =
+        options.stdio === 'pipe'
+          ? 'pipe'
+          : logFd === undefined
+            ? 'ignore'
+            : (['ignore', logFd, logFd] as unknown as Options['stdio']);
+      let logClosed = false;
+      const closeLog = (): void => {
+        if (logClosed || logFd === undefined) return;
+        logClosed = true;
+        closeSync(logFd);
+      };
+      let child: ResultPromise;
+      try {
+        child = execa(options.file, [...options.args], {
+          ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+          env: { ...options.env },
+          detached: options.detached,
+          stdio,
+          windowsHide: options.windowsHide,
+          reject: false,
+          buffer: false,
+        } as Options);
+      } catch (error) {
+        closeLog();
+        throw error;
+      }
+      if (logFd !== undefined) {
+        child.nodeChildProcess.once('spawn', closeLog);
+        child.nodeChildProcess.once('error', closeLog);
+      }
+      const stdin = child.stdin as Writable | null | undefined;
+      return {
+        pid: child.pid,
+        stdin: stdin === null || stdin === undefined ? null : { write: (chunk: string) => stdin.write(chunk) },
+        stdout: streamOf(child.stdout as Readable | null | undefined),
+        stderr: streamOf(child.stderr as Readable | null | undefined),
+        onExit(listener) {
+          const handler = (code: number | null, signal: string | null): void =>
+            listener({ code, signal } satisfies ProcessExitEvent);
+          child.nodeChildProcess.on('exit', handler);
+          return () => {
+            child.nodeChildProcess.off('exit', handler);
+          };
+        },
+        onError(listener) {
+          child.nodeChildProcess.on('error', listener);
+          return () => {
+            child.nodeChildProcess.off('error', listener);
+          };
+        },
+        unref() {
+          child.nodeChildProcess.unref();
+        },
+        kill(signal) {
+          child.kill(signal as NodeJS.Signals | undefined);
+        },
+      };
+    },
+  };
+}