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

package/src/host/__tests__/shell-render.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { callOperatorOf, invocationOf, quotedArgvLine, quotedLineOf } from '../shell-render.js';
+
+describe('callOperatorOf', () => {
+  it('pwsh：命令位置带引号时补 & 调用符', () => {
+    expect(callOperatorOf('pwsh', "'C:\\Program Files\\opencli\\opencli.cmd' 'browser'")).toBe(
+      "& 'C:\\Program Files\\opencli\\opencli.cmd' 'browser'",
+    );
+    expect(callOperatorOf('pwsh', '"C:\\tools\\x.cmd" list')).toBe('& "C:\\tools\\x.cmd" list');
+  });
+
+  it('pwsh：不带引号（或以空白开头的不带引号）原样', () => {
+    expect(callOperatorOf('pwsh', 'pnpm install')).toBe('pnpm install');
+    expect(callOperatorOf('pwsh', '  pnpm install')).toBe('  pnpm install');
+  });
+
+  it('posix 不管引号：bash 里命令位置本来就是命令', () => {
+    expect(callOperatorOf('posix', "'opencli' 'browser'")).toBe("'opencli' 'browser'");
+  });
+});
+
+describe('invocationOf', () => {
+  it('pwsh：-NoProfile -NonInteractive -Command，载荷带上 &', () => {
+    expect(invocationOf('pwsh', "'opencli' 'browser' 'list'")).toEqual({
+      file: 'pwsh',
+      args: ['-NoProfile', '-NonInteractive', '-Command', "& 'opencli' 'browser' 'list'"],
+    });
+  });
+
+  it('pwsh：普通命令行不加 &', () => {
+    expect(invocationOf('pwsh', 'pnpm add left-pad')).toEqual({
+      file: 'pwsh',
+      args: ['-NoProfile', '-NonInteractive', '-Command', 'pnpm add left-pad'],
+    });
+  });
+
+  it('posix：bash -c，脚本原样', () => {
+    expect(invocationOf('posix', "'opencli' 'browser'")).toEqual({ file: 'bash', args: ['-c', "'opencli' 'browser'"] });
+  });
+});
+
+describe('quotedArgvLine / quotedLineOf', () => {
+  it('posix：单引号；内嵌引号关引号再转义', () => {
+    expect(quotedArgvLine(['a b', "c'd"], 'darwin')).toBe(`'a b' 'c'\\''d'`);
+  });
+
+  it('win32：单引号 + 内嵌引号双写', () => {
+    expect(quotedArgvLine(['a b', "c'd"], 'win32')).toBe("'a b' 'c''d'");
+  });
+
+  it('空 argv 给空串', () => {
+    expect(quotedArgvLine([], 'darwin')).toBe('');
+  });
+
+  it('整条 invocation 按目标平台引号', () => {
+    expect(quotedLineOf({ file: 'pwsh', args: ['-Command', 'dir'] }, 'win32')).toBe("'pwsh' '-Command' 'dir'");
+  });
+});

package/src/host/__tests__/shell.test.ts

@@ -24,7 +24,31 @@ function replyingShell(exitCode: number, timedOut = false): DshShell {
   };
 }
 
+function sandboxedShell(): DshShell {
+  return {
+    resolve: (request) => request,
+    execute: async () => ({
+      result: async () => ({
+        exitCode: 3_221_225_794,
+        timedOut: false,
+        aborted: false,
+        stdout: { text: '', truncated: false },
+        stderr: { text: 'windows-acl-run: token setup failed\n', truncated: false },
+        sandbox: { mode: 'workspace-write', denied: false, runnerFailed: true },
+      }),
+    }),
+  };
+}
+
 describe('runShell', () => {
+  it('★ 沙箱事实原样带回来：runnerFailed 不当成"命令自己退出"', async () => {
+    const result = await runShell(sandboxedShell(), 'echo hi');
+
+    expect(result.exitCode).toBe(3_221_225_794);
+    expect(result.sandbox?.runnerFailed).toBe(true);
+    expect(result.stderr).toContain('windows-acl-run');
+  });
+
   it('★ 宿主一直不交结果 → 到点自己收尾，不把调用方挂住', async () => {
     vi.useFakeTimers();
     try {

package/src/host/__tests__/time.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { clockOf, epochOf, now, nowIso } from '../time.js';
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('宿主时间入口', () => {
+  it('now 读的是 Date.now，nowIso 是合法 ISO', () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-02T03:04:05.000Z'));
+    expect(now()).toBe(Date.parse('2026-01-02T03:04:05.000Z'));
+    expect(nowIso()).toBe('2026-01-02T03:04:05.000Z');
+  });
+
+  it('格式化助手仍只看传入值', () => {
+    expect(clockOf(0)).toBe('00:00:00');
+    expect(epochOf('1970-01-01T00:00:01.000Z')).toBe(1000);
+  });
+});

package/src/host/adapter-set.ts

@@ -85,7 +85,6 @@ const FULL_METHODS = [
   ['runtime', 'runners'],
   ['runtime', 'health'],
   ['runtime', 'seed'],
-  ['runtime', 'warnUnwritableRoot'],
   ['plugins', 'declarationLookup'],
   ['plugins', 'createUnits'],
   ['actions', 'configSyncHandler'],

package/src/host/changelog.ts

@@ -1,3 +1,4 @@
+import { now as clockNow } from './time.js';
 import dayjs from 'dayjs';
 
 export const CHANGELOG_FILE = 'CHANGELOG.md';
@@ -37,7 +38,7 @@ export function changelogVersion(value: string): string {
     .replace(/^v/, '');
 }
 
-export function changelogDate(now: Date = new Date()): string {
+export function changelogDate(now: Date = new Date(clockNow())): string {
   return dayjs(now).format('YYYY-MM-DD');
 }
 

package/src/host/config-sync.ts

@@ -1,26 +1,12 @@
-import { existsSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import type { PostResource, RouteHandler } from './http.js';
 import type { ConfigSyncProfile, ConfigSyncRow, ConfigSyncSnapshot } from '../contract/protocol/config-sync.js';
 import { CONFIG_SYNC_RESOURCE } from '../contract/protocol/config-sync.js';
+import { writePatchFile } from './patch.js';
 
-export interface PatchBlock {
-  readonly key: string;
-  readonly id: string;
-  readonly insert: boolean;
-  readonly body: string;
-  readonly names: readonly string[];
-}
-
-interface SpannedBlock extends PatchBlock {
-  readonly from: number;
-  readonly to: number;
-}
+import { patchBlocks, spannedBlocks, type PatchBlock } from './patch-blocks.js';
 
-const ID_LINE = /^- id:[ \t]*"?([^"\s#]+)/;
-const INSERT_LINE = /^- insert:[ \t]*$/;
-const NESTED_ID = /^[ \t]+-[ \t]*id:[ \t]*"?([^"\s#]+)/;
-const NAME_LINE = /^[ \t]*-?[ \t]*name:[ \t]*['"]?([^'"\s#]+)/;
 const COMMENT_LINE = /^[ \t]*#/;
 const ISOLATION_IDS = new Set([
   'session-persistence-jsonl',
@@ -29,56 +15,6 @@ const ISOLATION_IDS = new Set([
   'sandbox-policy',
 ]);
 
-function trimmedTail(lines: readonly string[]): readonly string[] {
-  let end = lines.length;
-  while (end > 0 && (lines[end - 1] ?? '').trim() === '') end -= 1;
-  return lines.slice(0, end);
-}
-
-function matched(text: string, pattern: RegExp): string | undefined {
-  const found = pattern.exec(text);
-  return found === null ? undefined : found[1];
-}
-
-function blockOf(body: string, index: number): PatchBlock {
-  const lines = body.split('\n');
-  const first = lines[0] ?? '';
-  const id = matched(first, ID_LINE);
-  const nested = lines.flatMap((line) => {
-    const one = matched(line, NESTED_ID);
-    return one === undefined ? [] : [one];
-  });
-  const insert = id === undefined && INSERT_LINE.test(first);
-  const label = id ?? nested.join(', ');
-  const key = id !== undefined ? `id:${id}` : insert ? `insert:${nested.join(', ')}` : `block:${String(index)}`;
-  const names = lines.flatMap((line) => {
-    const one = matched(line, NAME_LINE);
-    return one === undefined ? [] : [one];
-  });
-  return { key, id: label === '' ? key : label, insert, body, names };
-}
-
-function spannedBlocks(text: string): SpannedBlock[] {
-  const lines = text.split('\n');
-  const starts: number[] = [];
-  lines.forEach((line, index) => {
-    if (/^- /.test(line) || line === '-') starts.push(index);
-  });
-  const blocks: SpannedBlock[] = [];
-  for (let i = 0; i < starts.length; i += 1) {
-    const from = starts[i] ?? 0;
-    const to = i + 1 < starts.length ? (starts[i + 1] ?? lines.length) : lines.length;
-    const body = trimmedTail(lines.slice(from, to)).join('\n');
-    if (body.trim() === '') continue;
-    blocks.push({ ...blockOf(body, blocks.length), from, to });
-  }
-  return blocks;
-}
-
-export function patchBlocks(text: string): PatchBlock[] {
-  return spannedBlocks(text).map(({ from: _from, to: _to, ...block }) => block);
-}
-
 export function normalizeBlock(body: string): string {
   return body
     .split('\n')
@@ -184,29 +120,6 @@ export function readPatchBlocks(
   }
 }
 
-function patchMode(path: string): number {
-  try {
-    return statSync(path).mode & 0o777;
-  } catch {
-    return 0o644;
-  }
-}
-
-export function writePatchFile(path: string, text: string): void {
-  const mode = patchMode(path);
-  const tmp = `${path}.wb-sync-${String(process.pid)}`;
-  writeFileSync(tmp, text, { mode });
-  try {
-    renameSync(tmp, path);
-  } catch (error) {
-    try {
-      unlinkSync(tmp);
-    } catch {
-      throw error;
-    }
-    throw error;
-  }
-}
 
 export interface ConfigSyncDeps {
   readonly home: string;

package/src/host/env-policy.ts

@@ -0,0 +1,192 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { dshHome } from './data-root.js';
+import type { ShellKind } from './shell-text.js';
+
+export type EnvLayer = Readonly<Record<string, string | undefined>>;
+
+/**
+ * 把父进程环境里的字符串值拷成一层 env（丢掉 undefined）。
+ * @param parent 父环境（通常是 `process.env`）。
+ * @returns 可继续叠加的 env 层。
+ */
+export function inheritedEnvOf(parent: NodeJS.ProcessEnv | EnvLayer): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parent)) {
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 在一层 env 上叠另一层；`undefined` 表示删掉这个键。
+ * @param base 底层 env。
+ * @param layer 上层 env；值为 undefined 的键被删除。
+ * @returns 叠加后的新对象。
+ */
+export function overlayEnvOf(
+  base: EnvLayer,
+  layer: EnvLayer | undefined,
+): Record<string, string | undefined> {
+  const merged: Record<string, string | undefined> = { ...base };
+  for (const [key, value] of Object.entries(layer ?? {})) {
+    if (value === undefined) delete merged[key];
+    else merged[key] = value;
+  }
+  return merged;
+}
+
+/**
+ * 把 env 层收成只含字符串的 env（用于执行缝 `env` 参数）。
+ * @param layer env 层。
+ * @returns 只含字符串键值的对象。
+ */
+export function envTextOf(layer: EnvLayer): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(layer)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * 在 PATH 前面插一组目录（去重、空项丢掉）。
+ * @param parentPath 原来的 PATH。
+ * @param bins 要前插的目录，按顺序。
+ * @param separator 平台分隔符，默认 `path.delimiter`。
+ * @returns 新的 PATH。
+ */
+export function pathWithBinsOf(
+  parentPath: string | undefined,
+  bins: readonly string[],
+  separator: string = delimiter,
+): string {
+  const parts = (parentPath ?? '').split(separator).filter((part) => part !== '' && !bins.includes(part));
+  return [...bins, ...parts].join(separator);
+}
+
+function existingPointer(realHome: string, name: string): string | undefined {
+  const file = join(realHome, name);
+  return existsSync(file) ? file : undefined;
+}
+
+export interface ProductEnvInput {
+  readonly runtimeRoot: string;
+  readonly home?: string | undefined;
+  readonly realHome?: string | undefined;
+}
+
+/**
+ * 产品域（运行时根）的受控 env：隔离 HOME、npm/pnpm 缓存都钉在运行时根，真 npmrc/gitconfig 只读指过去。
+ * @param input 运行时根、可选的 HOME 与真实用户目录。
+ * @returns 产品域 env。
+ */
+export function productEnvOf(input: ProductEnvInput): Record<string, string> {
+  const runtimeRoot = input.runtimeRoot;
+  const realHome = input.realHome ?? homedir();
+  const env: Record<string, string> = {
+    HOME: input.home ?? join(runtimeRoot, 'home'),
+    DSH_HOME: dshHome(),
+    DSH_WORKBENCH_HOME: runtimeRoot,
+    npm_config_cache: join(runtimeRoot, 'npm-cache'),
+    NPM_CONFIG_CACHE: join(runtimeRoot, 'npm-cache'),
+    npm_config_logs_dir: join(runtimeRoot, 'npm-logs'),
+    npm_config_store_dir: join(runtimeRoot, 'pnpm-store'),
+    npm_config_cache_dir: join(runtimeRoot, 'pnpm-cache'),
+    npm_config_state_dir: join(runtimeRoot, 'pnpm-state'),
+    npm_config_update_notifier: 'false',
+    npm_config_fund: 'false',
+    NO_UPDATE_NOTIFIER: '1',
+  };
+  const npmrc = existingPointer(realHome, '.npmrc');
+  if (npmrc !== undefined) env['NPM_CONFIG_USERCONFIG'] = npmrc;
+  const gitconfig = existingPointer(realHome, '.gitconfig');
+  if (gitconfig !== undefined) env['GIT_CONFIG_GLOBAL'] = gitconfig;
+  return env;
+}
+
+export interface UnitEnvInput extends ProductEnvInput {
+  readonly unitRoot: string;
+}
+
+/**
+ * 模块单元的受控 env：在产品域基础上把 HOME 与 npm/pnpm 目录全钉到单元数据目录。
+ * @param input 运行时根、单元数据目录、可选的 TRUE 用户目录。
+ * @returns 单元 env。
+ */
+export function unitEnvOf(input: UnitEnvInput): Record<string, string> {
+  const unitRoot = input.unitRoot;
+  return {
+    ...productEnvOf({ ...input, home: join(unitRoot, 'home') }),
+    npm_config_cache: join(unitRoot, 'npm-cache'),
+    NPM_CONFIG_CACHE: join(unitRoot, 'npm-cache'),
+    npm_config_logs_dir: join(unitRoot, 'npm-logs'),
+    npm_config_store_dir: join(unitRoot, 'pnpm-store'),
+    npm_config_cache_dir: join(unitRoot, 'pnpm-cache'),
+    npm_config_state_dir: join(unitRoot, 'pnpm-state'),
+  };
+}
+
+export interface BootstrapEnvInput {
+  readonly root: string;
+  readonly realHome: string;
+  readonly shellKind: ShellKind;
+  readonly parent?: NodeJS.ProcessEnv | EnvLayer | undefined;
+  readonly path?: string | undefined;
+}
+
+/**
+ * 自举/装工具链的受控 env：继承父环境，HOME 与 npm 缓存钉到运行时根，PATH 可换成桌面自带 bin。
+ * @param input 运行时根、真实用户目录、shell 种类、父环境与可选的 PATH。
+ * @returns 自举 env。
+ */
+export function bootstrapEnvOf(input: BootstrapEnvInput): Record<string, string> {
+  const env = inheritedEnvOf(input.parent ?? process.env);
+  if (input.path !== undefined) env['PATH'] = input.path;
+  const home = join(input.root, 'home');
+  env['HOME'] = home;
+  if (input.shellKind === 'pwsh') env['USERPROFILE'] = home;
+  const userConfig = existingPointer(input.realHome, '.npmrc');
+  if (userConfig !== undefined) env['NPM_CONFIG_USERCONFIG'] = userConfig;
+  const cache = join(input.root, 'npm-cache');
+  env['npm_config_cache'] = cache;
+  env['NPM_CONFIG_CACHE'] = cache;
+  env['NO_COLOR'] = '1';
+  env['TERM'] = 'dumb';
+  return env;
+}
+
+/**
+ * git 的非交互 env：关掉终端提示/askpass；Windows 上不给 askpass 指 POSIX 路径（那台机器上没有）。
+ * @param platform 宿主平台。
+ * @returns git 非交互 env。
+ */
+export function promptlessGitEnvOf(platform: NodeJS.Platform): Record<string, string> {
+  const shared = {
+    GIT_TERMINAL_PROMPT: '0',
+    SSH_ASKPASS_REQUIRE: 'never',
+    GCM_INTERACTIVE: 'never',
+    GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new',
+  };
+  if (platform === 'win32') return shared;
+  return { ...shared, GIT_ASKPASS: '/usr/bin/false', SSH_ASKPASS: '/usr/bin/false' };
+}
+
+/**
+ * 在父环境上叠加 `promptlessGitEnvOf`，得到可传给执行缝的 git env。
+ * @param parent 父环境。
+ * @param platform 宿主平台。
+ * @returns 只含字符串的 env。
+ */
+export function promptlessProcessEnvOf(
+  parent: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+): Record<string, string> {
+  const env = { ...inheritedEnvOf(parent), ...promptlessGitEnvOf(platform) };
+  if (platform === 'win32') {
+    delete env['GIT_ASKPASS'];
+    delete env['SSH_ASKPASS'];
+  }
+  return env;
+}

package/src/host/extension.ts

@@ -1,3 +1,4 @@
+import { now } from './time.js';
 import type { DataReader } from '../contract/data.js';
 import type { ExtensionCaller, ExtensionCallOptions, ExtensionValue } from '../contract/extension.js';
 import type { ExtensionNeed } from '../contract/needs.js';
@@ -30,7 +31,7 @@ export function extensionCallerOf(
         argv: [need.name, ...args],
         ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
       });
-      if (result.ok) return { value: result.data, at: Date.now() };
+      if (result.ok) return { value: result.data, at: now() };
       const code = result.error.pageCode ?? cliCodeOf(result.error.code);
       const command = [need.name, ...args].join(' ');
       const advice =

package/src/host/flow/run.ts

@@ -1,3 +1,4 @@
+import { now as clockNow } from '../time.js';
 import { evalPredicate, resolveInput, resolveValue } from './expr.js';
 import type {
   FlowAction,
@@ -197,7 +198,7 @@ async function runOne(options: RunOneOptions): Promise<unknown> {
 export async function runFlow(options: FlowRunOptions): Promise<FlowResult> {
   const { flow, input, actions, signal, runId, workspace, onStep } = options;
   const sleep = options.sleep ?? defaultSleep;
-  const now = options.now ?? (() => Date.now());
+  const now = options.now ?? (() => clockNow());
   const steps: Record<string, unknown> = {};
   const emit = (event: FlowStepEvent): void => {
     try {

package/src/host/fs-write.ts

@@ -0,0 +1,147 @@
+import { appendFileSync, chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import writeFileAtomic from 'write-file-atomic';
+
+export type WriteMode = number | 'keep';
+
+export interface WriteFileOptions {
+  readonly atomic?: boolean | undefined;
+  readonly mkdir?: boolean | undefined;
+  readonly fsync?: boolean | undefined;
+  readonly mode?: WriteMode | undefined;
+}
+
+function modeOf(path: string, mode: WriteMode | undefined): number {
+  if (typeof mode === 'number') return mode;
+  try {
+    return statSync(path).mode & 0o777;
+  } catch {
+    return 0o644;
+  }
+}
+
+function prepareOf(path: string, options: WriteFileOptions): number {
+  if (options.mkdir !== false) mkdirSync(dirname(path), { recursive: true });
+  return modeOf(path, options.mode);
+}
+
+function atomicOptionsOf(mode: number, options: WriteFileOptions): { mode: number; fsync?: boolean } {
+  return options.fsync === true ? { mode, fsync: true } : { mode };
+}
+
+/**
+ * 把文本写进文件；默认原子写（temp + rename）、目录不存在就建、已有文件保留原权限。
+ * @param path 目标文件；父目录按 `mkdir` 决定是否创建。
+ * @param text 文本内容。
+ * @param options 原子/目录/权限/fsync；`mode` 默认 `'keep'`（新文件 0644）。
+ */
+export function writeTextFile(path: string, text: string, options: WriteFileOptions = {}): void {
+  const mode = prepareOf(path, options);
+  if (options.atomic === false) {
+    writeFileSync(path, text, { mode });
+    return;
+  }
+  writeFileAtomic.sync(path, text, atomicOptionsOf(mode, options));
+}
+
+/**
+ * 往文件末尾追加文本；文件或目录不存在就建。追加不是原子写，只给「日志/采集」这类只增不改的流。
+ * @param path 目标文件。
+ * @param text 追加内容。
+ */
+export function appendTextFile(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, text, { mode: modeOf(path, 'keep') });
+}
+
+/**
+ * `writeTextFile` 的异步版；语义与默认值相同。
+ * @param path 目标文件。
+ * @param text 文本内容。
+ * @param options 原子/目录/权限/fsync。
+ * @returns 落盘完成。
+ */
+export async function writeTextFileAsync(path: string, text: string, options: WriteFileOptions = {}): Promise<void> {
+  const mode = prepareOf(path, options);
+  if (options.atomic === false) {
+    writeFileSync(path, text, { mode });
+    return;
+  }
+  await writeFileAtomic(path, text, atomicOptionsOf(mode, options));
+}
+
+/**
+ * 把二进制写进文件；语义与默认值同 `writeTextFile`。
+ * @param path 目标文件。
+ * @param bytes 二进制内容。
+ * @param options 原子/目录/权限/fsync。
+ */
+export function writeBytesFile(path: string, bytes: Uint8Array, options: WriteFileOptions = {}): void {
+  const mode = prepareOf(path, options);
+  if (options.atomic === false) {
+    writeFileSync(path, bytes, { mode });
+    return;
+  }
+  writeFileAtomic.sync(path, Buffer.from(bytes), atomicOptionsOf(mode, options));
+}
+
+/**
+ * `writeBytesFile` 的异步版；语义与默认值相同。
+ * @param path 目标文件。
+ * @param bytes 二进制内容。
+ * @param options 原子/目录/权限/fsync。
+ * @returns 落盘完成。
+ */
+export async function writeBytesFileAsync(
+  path: string,
+  bytes: Uint8Array,
+  options: WriteFileOptions = {},
+): Promise<void> {
+  const mode = prepareOf(path, options);
+  if (options.atomic === false) {
+    writeFileSync(path, bytes, { mode });
+    return;
+  }
+  await writeFileAtomic(path, Buffer.from(bytes), atomicOptionsOf(mode, options));
+}
+
+/**
+ * 把 JSON 写进文件：`JSON.stringify(value, null, 2)` 加末尾换行；语义与默认值同 `writeTextFile`。
+ * @param path 目标文件。
+ * @param value 可序列化的值。
+ * @param options 原子/目录/权限/fsync。
+ */
+export function writeJsonFile(path: string, value: unknown, options: WriteFileOptions = {}): void {
+  writeTextFile(path, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+/**
+ * `writeJsonFile` 的异步版；语义与默认值相同。
+ * @param path 目标文件。
+ * @param value 可序列化的值。
+ * @param options 原子/目录/权限/fsync。
+ * @returns 落盘完成。
+ */
+export async function writeJsonFileAsync(
+  path: string,
+  value: unknown,
+  options: WriteFileOptions = {},
+): Promise<void> {
+  await writeTextFileAsync(path, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+/**
+ * 确保目录存在（`mkdir -p`）。
+ * @param dir 目录路径。
+ */
+export function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * 把已存在的文件设成可执行（0755）。
+ * @param path 文件路径。
+ */
+export function makeExecutable(path: string): void {
+  chmodSync(path, 0o755);
+}

package/src/host/host-kit.ts

@@ -1,10 +1,11 @@
 import type { HostSurface } from '../contract/protocol/platform.js';
 import type { EnvSupplyPort } from './port-types.js';
+import type { UnitSeam } from './seam/unit-seam.js';
 import { createFlowHost, type FlowHost } from './flow/kit.js';
 import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
 
 /**
- * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法、宿主平台事实。
+ * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法、宿主平台事实、按 unit 绑定的执行缝门面。
  */
 export interface HostKit {
   readonly flow: FlowHost;
@@ -12,17 +13,20 @@ export interface HostKit {
   readonly sessionWorkspace: typeof sessionWorkspace;
   readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
   readonly surface: HostSurface;
+  readonly seam?: UnitSeam | undefined;
 }
 
 /**
  * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
  * @param parts.libInstallCommand 拼「装这个共用依赖」的那条命令。
  * @param parts.surface 宿主平台事实；由组合根按 profile 与宿主进程算好再交进来。
- * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface。
+ * @param parts.seam 按 unit 绑定好的执行缝门面；模块清单没声明写入域时缺省不给。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand / surface，有门面时带上 seam。
  */
 export function createHostKit(parts: {
   readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
   readonly surface: HostSurface;
+  readonly seam?: UnitSeam | undefined;
 }): HostKit {
   return {
     flow: createFlowHost(),
@@ -30,5 +34,6 @@ export function createHostKit(parts: {
     sessionWorkspace,
     libInstallCommand: parts.libInstallCommand,
     surface: parts.surface,
+    ...(parts.seam === undefined ? {} : { seam: parts.seam }),
   };
 }