@dsh-workbench/shared 1.1.14 → 1.1.16

package/dist/host/fs-write.d.ts

@@ -12,6 +12,12 @@ export interface WriteFileOptions {
  * @param options 原子/目录/权限/fsync；`mode` 默认 `'keep'`（新文件 0644）。
  */
 export declare function writeTextFile(path: string, text: string, options?: WriteFileOptions): void;
+/**
+ * 往文件末尾追加文本；文件或目录不存在就建。追加不是原子写，只给「日志/采集」这类只增不改的流。
+ * @param path 目标文件。
+ * @param text 追加内容。
+ */
+export declare function appendTextFile(path: string, text: string): void;
 /**
  * `writeTextFile` 的异步版；语义与默认值相同。
  * @param path 目标文件。

package/dist/host/fs-write.js

@@ -1,4 +1,4 @@
-import { chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
 function modeOf(path, mode) {
@@ -33,6 +33,15 @@ export function writeTextFile(path, text, options = {}) {
     }
     writeFileAtomic.sync(path, text, atomicOptionsOf(mode, options));
 }
+/**
+ * 往文件末尾追加文本；文件或目录不存在就建。追加不是原子写，只给「日志/采集」这类只增不改的流。
+ * @param path 目标文件。
+ * @param text 追加内容。
+ */
+export function appendTextFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, text, { mode: modeOf(path, 'keep') });
+}
 /**
  * `writeTextFile` 的异步版；语义与默认值相同。
  * @param path 目标文件。

package/dist/host/seam/policy.js

@@ -1,4 +1,4 @@
-import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, parse, resolve, sep } from 'node:path';
 import { SeamError } from './intent.js';
 export const SEAM_MODES = ['read-only', 'workspace-write', 'danger-full-access'];
 export function seamModeOf(value) {
@@ -20,7 +20,7 @@ export function insideOf(root, path) {
 }
 export function productPolicy(ceiling, productRoot) {
     return {
-        mode: ceiling === 'read-only' ? 'read-only' : 'workspace-write',
+        mode: ceiling === 'read-only' ? 'read-only' : ceiling === 'danger-full-access' ? 'danger-full-access' : 'workspace-write',
         workspaceRoot: resolve(productRoot),
     };
 }
@@ -34,6 +34,9 @@ export function workspacePolicy(ceiling, grant) {
     }
     return { mode, workspaceRoot: resolve(grant.workspaceRoot) };
 }
+function atFilesystemRoot(path) {
+    return parse(path).root === path;
+}
 function commonDirectory(paths) {
     const dirs = paths.map((path) => dirname(resolve(path)));
     let shared = dirs[0];
@@ -57,11 +60,11 @@ export function pathsPolicy(ceiling, paths) {
         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 === undefined) {
+        throw new SeamError('paths-span-trees', '这次写入没有给出任何路径');
     }
-    if (root === sep) {
-        throw new SeamError('paths-span-trees', '不能把整个文件系统声明成写入域');
+    if (atFilesystemRoot(root)) {
+        throw new SeamError('paths-span-trees', paths.length > 1 ? '这次写入跨了多个目录：请分开做，或把产物改到工作台目录' : '不能把整个文件系统声明成写入域');
     }
     return { mode: 'workspace-write', workspaceRoot: root };
 }

package/dist/host/seam/run.js

@@ -2,7 +2,8 @@ import { now } from '../time.js';
 import { mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { workbenchRoot } from '../data-root.js';
-import { quoteShellArg, shellKindOf } from '../shell-text.js';
+import { shellKindOf } from '../shell-text.js';
+import { callOperatorOf, invocationOf, quotedArgvLine, quotedLineOf } from '../shell-render.js';
 import { runShell } from '../shell.js';
 import { deniedPathOf, sandboxDeniedOf } from './denial.js';
 import { seamProductEnv } from './env.js';
@@ -55,29 +56,22 @@ function targetOf(request) {
     throw new SeamError('scope-not-declared', '这条执行请求要么给 argv，要么给一条命令行，不能两个都给或都不给');
 }
 function displayOf(target) {
-    return 'argv' in target ? target.argv.map((one) => quoteShellArg(one)).join(' ') : target.line;
+    return 'argv' in target ? quotedArgvLine(target.argv) : target.line;
 }
-function shellInvocationOf(shellKind, line) {
-    return shellKind === 'pwsh'
-        ? { file: 'pwsh', args: ['-NoProfile', '-NonInteractive', '-Command', line] }
-        : { file: 'bash', args: ['-c', line] };
-}
-function invocationOf(target, shellKind) {
+function targetInvocationOf(target, shellKind) {
     if ('argv' in target) {
         const [file, ...args] = target.argv;
         if (file === undefined)
             throw new SeamError('scope-not-declared', 'argv 是空的：至少给一个可执行文件');
         return { file, args };
     }
-    return shellInvocationOf(shellKind ?? shellKindOf(), target.line);
+    return invocationOf(shellKind ?? shellKindOf(), target.line);
 }
 function sandboxedLineOf(target, shellKind) {
-    if ('argv' in target)
-        return target.argv.map((one) => quoteShellArg(one)).join(' ');
+    const line = 'argv' in target ? quotedArgvLine(target.argv) : target.line;
     if (shellKind === undefined)
-        return target.line;
-    const invocation = shellInvocationOf(shellKind, target.line);
-    return [invocation.file, ...invocation.args].map((one) => quoteShellArg(one)).join(' ');
+        return callOperatorOf(shellKindOf(), line);
+    return callOperatorOf(shellKindOf(), quotedLineOf(invocationOf(shellKind, line)));
 }
 export function createSeam(ports) {
     const runtimeRoot = ports.runtimeRoot ?? workbenchRoot();
@@ -133,7 +127,7 @@ export function createSeam(ports) {
         return undefined;
     }
     async function runHost(request, target) {
-        const invocation = invocationOf(target, request.shellKind);
+        const invocation = targetInvocationOf(target, request.shellKind);
         const child = processes.spawn({
             file: invocation.file,
             args: invocation.args,
@@ -186,7 +180,7 @@ export function createSeam(ports) {
         };
     }
     function spawnHost(request) {
-        const invocation = invocationOf(request.target, undefined);
+        const invocation = targetInvocationOf(request.target, undefined);
         const logFile = request.logFile ?? join(runtimeRoot, 'logs', `${request.label ?? 'spawn'}-${String(now())}.log`);
         mkdirSync(dirname(logFile), { recursive: true });
         const child = processes.spawn({
@@ -252,7 +246,7 @@ export function createSeam(ports) {
         };
     }
     function openHost(request) {
-        const invocation = invocationOf(request.target, undefined);
+        const invocation = targetInvocationOf(request.target, undefined);
         const child = processes.spawn({
             file: invocation.file,
             args: invocation.args,

package/dist/host/shell-render.d.ts

@@ -0,0 +1,9 @@
+import type { ShellKind } from './shell-text.js';
+export interface ShellInvocation {
+    readonly file: string;
+    readonly args: readonly string[];
+}
+export declare function callOperatorOf(kind: ShellKind, script: string): string;
+export declare function invocationOf(kind: ShellKind, script: string): ShellInvocation;
+export declare function quotedArgvLine(argv: readonly string[], platform?: NodeJS.Platform): string;
+export declare function quotedLineOf(invocation: ShellInvocation, platform?: NodeJS.Platform): string;

package/dist/host/shell-render.js

@@ -0,0 +1,18 @@
+import { quoteShellArgFor } from './shell-text.js';
+const QUOTED_HEAD = /^\s*['"]/;
+export function callOperatorOf(kind, script) {
+    if (kind !== 'pwsh' || !QUOTED_HEAD.test(script))
+        return script;
+    return `& ${script}`;
+}
+export function invocationOf(kind, script) {
+    return kind === 'pwsh'
+        ? { file: 'pwsh', args: ['-NoProfile', '-NonInteractive', '-Command', callOperatorOf('pwsh', script)] }
+        : { file: 'bash', args: ['-c', script] };
+}
+export function quotedArgvLine(argv, platform = process.platform) {
+    return argv.map((one) => quoteShellArgFor(one, platform)).join(' ');
+}
+export function quotedLineOf(invocation, platform = process.platform) {
+    return quotedArgvLine([invocation.file, ...invocation.args], platform);
+}

package/dist/host.d.ts

@@ -67,6 +67,7 @@ export * from './host/write-result.js';
 export * from './host/cli-error.js';
 export * from './host/data-root.js';
 export * from './host/shell-text.js';
+export * from './host/shell-render.js';
 export * from './host/shell.js';
 export * from './host/seam/intent.js';
 export * from './host/seam/policy.js';

package/dist/host.js

@@ -67,6 +67,7 @@ export * from './host/write-result.js';
 export * from './host/cli-error.js';
 export * from './host/data-root.js';
 export * from './host/shell-text.js';
+export * from './host/shell-render.js';
 export * from './host/shell.js';
 export * from './host/seam/intent.js';
 export * from './host/seam/policy.js';

package/package.json

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

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

@@ -1,8 +1,9 @@
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve, sep } from 'node:path';
 import { afterAll, describe, expect, it } from 'vitest';
 import { SeamError } from '../seam/intent.js';
+import { pathsPolicy } from '../seam/policy.js';
 import { createSeam } from '../seam/run.js';
 import { createUnitSeam, unitDataRoot } from '../seam/unit-seam.js';
 import { createFakeProcesses, createFakeShell, createFakeLogger } from '../../testing/host-fakes.js';
@@ -46,6 +47,13 @@ describe('createSeam', () => {
     expect(policyOf(fake.calls[0])).toEqual({ mode: 'workspace-write', workspaceRoot: ROOT });
   });
 
+  it('产品域跟到部署上限：danger-full-access 时不再收窄成 workspace-write', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT, ceiling: 'danger-full-access' });
+    await seam.run({ command: 'npm view x version', intent: { kind: 'product' } });
+    expect(policyOf(fake.calls[0])).toEqual({ mode: 'danger-full-access', workspaceRoot: ROOT });
+  });
+
   it('工作区域：取会话解析结果；上限更宽时按会话', async () => {
     const fake = createFakeShell([{}]);
     const seam = createSeam({
@@ -80,6 +88,15 @@ describe('createSeam', () => {
     expect(fake.calls).toHaveLength(0);
   });
 
+  it('路径共同根是文件系统根就拒（win32 的盘根也算）', () => {
+    const root = resolve(sep);
+    expect(() => pathsPolicy('workspace-write', [join(root, 'a.png'), join(root, 'b.png')])).toThrow(SeamError);
+    expect(pathsPolicy('workspace-write', [join(SCRATCH, 'a.png'), join(SCRATCH, 'b.png')])).toEqual({
+      mode: 'workspace-write',
+      workspaceRoot: SCRATCH,
+    });
+  });
+
   it('外部路径：同一目录可以，跨目录拒绝', async () => {
     const fake = createFakeShell([{}]);
     const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
@@ -291,6 +308,47 @@ describe('宿主域：run / spawn / open', () => {
     const fake = createFakeShell([{}]);
     const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
     await seam.run({ argv: ['npm', 'view', 'left-pad', 'version'], intent: { kind: 'product' } });
-    expect(fake.calls[0]?.command).toBe("'npm' 'view' 'left-pad' 'version'");
+    const call = process.platform === 'win32' ? "& 'npm' 'view' 'left-pad' 'version'" : "'npm' 'view' 'left-pad' 'version'";
+    expect(fake.calls[0]?.command).toBe(call);
+  });
+});
+
+describe('pwsh 命令行', () => {
+  it('host 域：命令行以引号开头时补 & 调用符', async () => {
+    const fake = createFakeProcesses([{}]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, allowHost: true, processes: fake.host });
+    await seam.run({
+      command: "'C:\\Program Files\\opencli\\opencli.cmd' 'browser' 'list'",
+      shellKind: 'pwsh',
+      intent: { kind: 'host' },
+    });
+    expect(fake.calls[0]?.file).toBe('pwsh');
+    expect(fake.calls[0]?.args).toEqual([
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      "& 'C:\\Program Files\\opencli\\opencli.cmd' 'browser' 'list'",
+    ]);
+  });
+
+  it('host 域：不以引号开头的命令行不加 &', async () => {
+    const fake = createFakeProcesses([{}]);
+    const seam = createSeam({ shell: createFakeShell([]).shell, runtimeRoot: ROOT, allowHost: true, processes: fake.host });
+    await seam.run({ command: 'pnpm add left-pad', shellKind: 'pwsh', intent: { kind: 'host' } });
+    expect(fake.calls[0]?.args?.at(-1)).toBe('pnpm add left-pad');
+  });
+
+  it('沙箱域：pwsh 下带引号的命令行也落在 -Command 里补 &', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await seam.run({ command: "'opencli' 'browser' 'list'", shellKind: 'pwsh', intent: { kind: 'none' } });
+    expect(fake.calls[0]?.command).toMatch(/'-Command' '& /);
+  });
+
+  it('沙箱域：pwsh 下普通命令行原样进 -Command', async () => {
+    const fake = createFakeShell([{}]);
+    const seam = createSeam({ shell: fake.shell, runtimeRoot: ROOT });
+    await seam.run({ command: 'pnpm install', shellKind: 'pwsh', intent: { kind: 'none' } });
+    expect(fake.calls[0]?.command).toContain("'-Command' 'pnpm install'");
   });
 });

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/fs-write.ts

@@ -1,4 +1,4 @@
-import { chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import writeFileAtomic from 'write-file-atomic';
 
@@ -44,6 +44,16 @@ export function writeTextFile(path: string, text: string, options: WriteFileOpti
   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 目标文件。

package/src/host/seam/policy.ts

@@ -1,4 +1,4 @@
-import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import { dirname, isAbsolute, parse, resolve, sep } from 'node:path';
 import type { DenialScope, SeamMode, SeamPolicy, WriteIntent } from './intent.js';
 import { SeamError } from './intent.js';
 
@@ -26,7 +26,7 @@ export function insideOf(root: string, path: string): boolean {
 
 export function productPolicy(ceiling: SeamMode, productRoot: string): SeamPolicy {
   return {
-    mode: ceiling === 'read-only' ? 'read-only' : 'workspace-write',
+    mode: ceiling === 'read-only' ? 'read-only' : ceiling === 'danger-full-access' ? 'danger-full-access' : 'workspace-write',
     workspaceRoot: resolve(productRoot),
   };
 }
@@ -42,6 +42,10 @@ export function workspacePolicy(ceiling: SeamMode, grant: SeamPolicy | undefined
   return { mode, workspaceRoot: resolve(grant.workspaceRoot) };
 }
 
+function atFilesystemRoot(path: string): boolean {
+  return parse(path).root === path;
+}
+
 function commonDirectory(paths: readonly string[]): string | undefined {
   const dirs = paths.map((path) => dirname(resolve(path)));
   let shared = dirs[0];
@@ -65,11 +69,14 @@ export function pathsPolicy(ceiling: SeamMode, paths: readonly string[]): SeamPo
     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 === undefined) {
+    throw new SeamError('paths-span-trees', '这次写入没有给出任何路径');
   }
-  if (root === sep) {
-    throw new SeamError('paths-span-trees', '不能把整个文件系统声明成写入域');
+  if (atFilesystemRoot(root)) {
+    throw new SeamError(
+      'paths-span-trees',
+      paths.length > 1 ? '这次写入跨了多个目录：请分开做，或把产物改到工作台目录' : '不能把整个文件系统声明成写入域',
+    );
   }
   return { mode: 'workspace-write', workspaceRoot: root };
 }

package/src/host/seam/run.ts

@@ -3,7 +3,8 @@ import { mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import type { DshShell } from '../../api/dsh.js';
 import { workbenchRoot } from '../data-root.js';
-import { quoteShellArg, shellKindOf } from '../shell-text.js';
+import { shellKindOf } from '../shell-text.js';
+import { callOperatorOf, invocationOf, quotedArgvLine, quotedLineOf } from '../shell-render.js';
 import { runShell, type ShellResult } from '../shell.js';
 import { deniedPathOf, sandboxDeniedOf } from './denial.js';
 import { seamProductEnv } from './env.js';
@@ -119,29 +120,22 @@ function targetOf(request: {
 }
 
 function displayOf(target: SeamTarget): string {
-  return 'argv' in target ? target.argv.map((one) => quoteShellArg(one)).join(' ') : target.line;
+  return 'argv' in target ? quotedArgvLine(target.argv) : target.line;
 }
 
-function shellInvocationOf(shellKind: SeamShellKind, line: string): { file: string; args: string[] } {
-  return shellKind === 'pwsh'
-    ? { file: 'pwsh', args: ['-NoProfile', '-NonInteractive', '-Command', line] }
-    : { file: 'bash', args: ['-c', line] };
-}
-
-function invocationOf(target: SeamTarget, shellKind: SeamShellKind | undefined): { file: string; args: string[] } {
+function targetInvocationOf(target: SeamTarget, shellKind: SeamShellKind | undefined): { file: string; args: readonly string[] } {
   if ('argv' in target) {
     const [file, ...args] = target.argv;
     if (file === undefined) throw new SeamError('scope-not-declared', 'argv 是空的：至少给一个可执行文件');
     return { file, args };
   }
-  return shellInvocationOf(shellKind ?? shellKindOf(), target.line);
+  return invocationOf(shellKind ?? shellKindOf(), target.line);
 }
 
 function sandboxedLineOf(target: SeamTarget, shellKind: SeamShellKind | undefined): string {
-  if ('argv' in target) return target.argv.map((one) => quoteShellArg(one)).join(' ');
-  if (shellKind === undefined) return target.line;
-  const invocation = shellInvocationOf(shellKind, target.line);
-  return [invocation.file, ...invocation.args].map((one) => quoteShellArg(one)).join(' ');
+  const line = 'argv' in target ? quotedArgvLine(target.argv) : target.line;
+  if (shellKind === undefined) return callOperatorOf(shellKindOf(), line);
+  return callOperatorOf(shellKindOf(), quotedLineOf(invocationOf(shellKind, line)));
 }
 
 export function createSeam(ports: SeamPorts): Seam {
@@ -197,7 +191,7 @@ export function createSeam(ports: SeamPorts): Seam {
   }
 
   async function runHost(request: SeamRequest, target: SeamTarget): Promise<ShellResult> {
-    const invocation = invocationOf(target, request.shellKind);
+    const invocation = targetInvocationOf(target, request.shellKind);
     const child = processes.spawn({
       file: invocation.file,
       args: invocation.args,
@@ -249,7 +243,7 @@ export function createSeam(ports: SeamPorts): Seam {
   }
 
   function spawnHost(request: SpawnRequest): SpawnHandle {
-    const invocation = invocationOf(request.target, undefined);
+    const invocation = targetInvocationOf(request.target, undefined);
     const logFile =
       request.logFile ?? join(runtimeRoot, 'logs', `${request.label ?? 'spawn'}-${String(now())}.log`);
     mkdirSync(dirname(logFile), { recursive: true });
@@ -315,7 +309,7 @@ export function createSeam(ports: SeamPorts): Seam {
   }
 
   function openHost(request: OpenRequest): ChannelHandle {
-    const invocation = invocationOf(request.target, undefined);
+    const invocation = targetInvocationOf(request.target, undefined);
     const child: ProcessChild = processes.spawn({
       file: invocation.file,
       args: invocation.args,

package/src/host/shell-render.ts

@@ -0,0 +1,28 @@
+import type { ShellKind } from './shell-text.js';
+import { quoteShellArgFor } from './shell-text.js';
+
+export interface ShellInvocation {
+  readonly file: string;
+  readonly args: readonly string[];
+}
+
+const QUOTED_HEAD = /^\s*['"]/;
+
+export function callOperatorOf(kind: ShellKind, script: string): string {
+  if (kind !== 'pwsh' || !QUOTED_HEAD.test(script)) return script;
+  return `& ${script}`;
+}
+
+export function invocationOf(kind: ShellKind, script: string): ShellInvocation {
+  return kind === 'pwsh'
+    ? { file: 'pwsh', args: ['-NoProfile', '-NonInteractive', '-Command', callOperatorOf('pwsh', script)] }
+    : { file: 'bash', args: ['-c', script] };
+}
+
+export function quotedArgvLine(argv: readonly string[], platform: NodeJS.Platform = process.platform): string {
+  return argv.map((one) => quoteShellArgFor(one, platform)).join(' ');
+}
+
+export function quotedLineOf(invocation: ShellInvocation, platform: NodeJS.Platform = process.platform): string {
+  return quotedArgvLine([invocation.file, ...invocation.args], platform);
+}

package/src/host.ts

@@ -77,6 +77,7 @@ export * from './host/write-result.js';
 export * from './host/cli-error.js';
 export * from './host/data-root.js';
 export * from './host/shell-text.js';
+export * from './host/shell-render.js';
 export * from './host/shell.js';
 export * from './host/seam/intent.js';
 export * from './host/seam/policy.js';