@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/register.ts

@@ -0,0 +1,161 @@
+/**
+ * Linchpin helper that binds a typed host handler to an SDK-registered gateway
+ * method descriptor BY ID.
+ *
+ * The SDK's `GatewayMethodCatalog` constructor auto-registers every builtin
+ * descriptor (channels.* / email.* / calendar.* / ...) with `handler:undefined`.
+ * The host attaches its implementation by looking up that canonical descriptor
+ * via `catalog.get(id)` and re-registering it WITH the handler using
+ * `{ replace: true }`. Only the handler slot changes; the SDK's id, schema,
+ * access, scopes, and dangerous flags are preserved verbatim. No descriptor or
+ * schema is ever authored here.
+ */
+import type {
+  GatewayMethodCatalog,
+  GatewayMethodInvocation,
+  GatewayMethodInvocationContext,
+} from './contracts.ts';
+import { HandlerError, REQUIRE_CONFIRM } from './errors.ts';
+
+/** Function returned by every registration; calling it removes the attached handler. */
+export type Unregister = () => void;
+
+/** Normalized, host-facing principal/auth context derived from the SDK invocation. */
+export interface HandlerContextEnvelope {
+  readonly principalId: string;
+  readonly admin: boolean;
+  readonly scopes: string[];
+  readonly explicitUserRequest: boolean;
+  readonly authToken: string;
+}
+
+/** Typed, host-facing shape of a single method invocation. */
+export interface HandlerInvocation<TBody> {
+  readonly body: TBody;
+  readonly query: Record<string, string>;
+  readonly context: HandlerContextEnvelope;
+}
+
+/** A host handler: receives the typed invocation, returns the method result. */
+export type TypedHandler<TBody, TResult> = (
+  input: HandlerInvocation<TBody>,
+) => Promise<TResult>;
+
+export interface RegisterHandlerOptions {
+  /**
+   * When true, the wrapper enforces a confirmation gate before the handler
+   * runs: `body.confirm === true` AND `context.explicitUserRequest === true`.
+   */
+  readonly confirm?: boolean;
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/**
+ * Derive the host-facing context envelope from the raw SDK invocation context.
+ * `explicitUserRequest` is carried in `context.metadata.explicitUserRequest`.
+ */
+export function normalizeContext(c: GatewayMethodInvocationContext): HandlerContextEnvelope {
+  const metadata = c.metadata ?? {};
+  return {
+    principalId: c.principalId ?? '',
+    admin: c.admin === true,
+    scopes: c.scopes ? [...c.scopes] : [],
+    explicitUserRequest: metadata.explicitUserRequest === true,
+    authToken: c.authToken ?? '',
+  };
+}
+
+function normalizeQuery(query: GatewayMethodInvocation['query']): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!query) return out;
+  for (const [key, value] of Object.entries(query)) {
+    if (typeof value === 'string') out[key] = value;
+    else if (value != null) out[key] = String(value);
+  }
+  return out;
+}
+
+/**
+ * Guard a confirmation-gated mutation. Throws `HandlerError(REQUIRE_CONFIRM, 403)`
+ * unless the caller both set `body.confirm === true` and the request was an
+ * explicit user request.
+ */
+export function assertConfirmed(
+  body: unknown,
+  ctx: { readonly explicitUserRequest: boolean },
+): void {
+  const confirmed =
+    typeof body === 'object'
+    && body !== null
+    && (body as { confirm?: unknown }).confirm === true;
+  if (!confirmed || ctx.explicitUserRequest !== true) {
+    throw new HandlerError('explicit user confirmation required', REQUIRE_CONFIRM, 403);
+  }
+}
+
+/**
+ * Attach a typed handler to the SDK-registered descriptor identified by
+ * `methodId`. Reuses the descriptor the catalog already holds and re-registers
+ * it with the wrapped handler via `{ replace: true }`, flipping the builtin
+ * method from HTTP-fallback to in-process execution.
+ */
+export function registerCatalogHandler<TBody, TResult>(
+  catalog: GatewayMethodCatalog,
+  methodId: string,
+  handler: TypedHandler<TBody, TResult>,
+  options?: RegisterHandlerOptions,
+): Unregister {
+  const descriptor = catalog.get(methodId);
+  if (!descriptor) {
+    throw new HandlerError(`Unknown gateway method: ${methodId}`, 'UNKNOWN_METHOD', 404);
+  }
+
+  const wrapped = async (inv: GatewayMethodInvocation): Promise<unknown> => {
+    const context = normalizeContext(inv.context);
+    const body = inv.body as TBody;
+    if (options?.confirm) assertConfirmed(inv.body, context);
+    try {
+      return await handler({ body, query: normalizeQuery(inv.query), context });
+    } catch (error) {
+      if (error instanceof HandlerError) throw error;
+      throw new HandlerError(errorMessage(error), 'HANDLER_FAILED', 500);
+    }
+  };
+
+  return catalog.register(descriptor, wrapped, { replace: true });
+}
+
+/** A single id→handler binding for batch registration. */
+export interface CatalogHandlerEntry {
+  readonly id: string;
+  readonly handler: TypedHandler<unknown, unknown>;
+  readonly options?: RegisterHandlerOptions;
+}
+
+/**
+ * Register many handlers at once. Returns a single `Unregister` that tears them
+ * down in REVERSE registration order (best-effort: a failing teardown never
+ * aborts the rest).
+ */
+export function registerCatalogHandlers(
+  catalog: GatewayMethodCatalog,
+  entries: readonly CatalogHandlerEntry[],
+): Unregister {
+  const teardowns: Unregister[] = [];
+  for (const entry of entries) {
+    teardowns.push(registerCatalogHandler(catalog, entry.id, entry.handler, entry.options));
+  }
+  return () => {
+    for (let i = teardowns.length - 1; i >= 0; i -= 1) {
+      try {
+        teardowns[i]!();
+      } catch {
+        // best-effort teardown; continue unwinding the rest
+      }
+    }
+  };
+}

package/src/daemon/handlers/remote/backends/cloud-terminal.ts

@@ -0,0 +1,142 @@
+import { mkdir, writeFile, chmod, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import type { PeerRecord } from '../peer-registry.ts';
+import type { CloudTerminalBackendConfig } from '../peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type BackendDispatchResult,
+  type DispatchPayload,
+  BackendDispatchError,
+  resolveTimeout,
+  buildRemoteShellCommand,
+} from './types.ts';
+import { runProcess } from './process-runner.ts';
+import { tokenizeCommand } from './local-process.ts';
+
+/**
+ * Cloud-terminal backend: executes a command in a managed cloud shell / VM via
+ * the provider CLI (gcloud / aws / az). The provider credential is resolved from
+ * the daemon credential store and supplied to the CLI via a 0600 credentials
+ * file or a provider-specific env var — never as an argv token, never logged.
+ */
+export function createCloudTerminalBackend(ctx: BackendContext): Backend {
+  const credDir = join(ctx.homeDirectory, '.goodvibes', 'tui', 'operator', 'cloud-creds');
+
+  async function writeCredentialFile(peerId: string, value: string): Promise<string> {
+    await mkdir(credDir, { recursive: true });
+    await chmod(credDir, 0o700).catch(() => {});
+    const suffix = randomBytes(4).toString('hex');
+    const path = join(credDir, `${peerId}.${suffix}.cred`);
+    await writeFile(path, value, { mode: 0o600 });
+    await chmod(path, 0o600).catch(() => {});
+    return path;
+  }
+
+  function buildArgs(
+    config: CloudTerminalBackendConfig,
+    remoteCommand: string,
+  ): { args: string[]; credEnvKey?: string } {
+    switch (config.provider) {
+      case 'gcp': {
+        // gcloud compute ssh runs `command` on the target Cloud Shell / instance.
+        const args = ['gcloud', 'compute', 'ssh'];
+        if (config.projectId) args.push('--project', config.projectId);
+        if (config.location) args.push('--zone', config.location);
+        args.push(config.instance ?? 'cloudshell', '--command', remoteCommand);
+        return { args, credEnvKey: 'CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE' };
+      }
+      case 'aws': {
+        // aws ssm send-command style: run shell command on a managed instance.
+        const args = ['aws', 'ssm', 'start-session'];
+        if (config.location) args.push('--region', config.location);
+        if (config.instance) args.push('--target', config.instance);
+        args.push(
+          '--document-name', 'AWS-StartInteractiveCommand',
+          '--parameters', `command=${remoteCommand}`,
+        );
+        return { args, credEnvKey: 'AWS_SHARED_CREDENTIALS_FILE' };
+      }
+      case 'azure': {
+        // az vm run-command invoke executes a script on the target VM.
+        const args = ['az', 'vm', 'run-command', 'invoke'];
+        if (config.projectId) args.push('--resource-group', config.projectId);
+        if (config.instance) args.push('--name', config.instance);
+        args.push(
+          '--command-id', 'RunShellScript',
+          '--scripts', remoteCommand,
+        );
+        return { args, credEnvKey: 'AZURE_AUTH_LOCATION' };
+      }
+      default:
+        throw new BackendDispatchError(
+          `Unsupported cloud provider: ${String(config.provider)}`,
+          'REMOTE_BACKEND_UNSUPPORTED_PROVIDER',
+        );
+    }
+  }
+
+  return {
+    kind: 'cloud-terminal',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'cloud-terminal') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a cloud-terminal peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'cloud-terminal' } & CloudTerminalBackendConfig;
+      if (tokenizeCommand(command).length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+      const credential = await ctx.credentials.resolveRef(config.credentialRef);
+      if (!credential || credential.length === 0) {
+        throw new BackendDispatchError(
+          `Could not resolve cloud credential for peer '${peer.peerId}'.`,
+          'REMOTE_BACKEND_CREDENTIAL_MISSING',
+        );
+      }
+      const remoteCommand = buildRemoteShellCommand(command, payload?.args);
+      const { args, credEnvKey } = buildArgs(config, remoteCommand);
+      const credPath = await writeCredentialFile(peer.peerId, credential);
+      const env: Record<string, string> = { ...(payload?.env ?? {}) };
+      if (credEnvKey) env[credEnvKey] = credPath;
+
+      ctx.logger.info('remote cloud-terminal dispatch', {
+        peerId: peer.peerId,
+        provider: config.provider,
+      });
+      try {
+        const result = await runProcess({
+          args,
+          timeoutMs: resolveTimeout(payload),
+          env,
+          ...(payload?.stdin !== undefined ? { stdin: payload.stdin } : {}),
+        });
+        return {
+          exitCode: result.timedOut ? 124 : result.exitCode,
+          stdout: result.stdout,
+          stderr: result.timedOut
+            ? `${result.stderr}\n[remote] cloud command timed out`
+            : result.stderr,
+        };
+      } finally {
+        // The plaintext provider credential file is single-use: remove it as
+        // soon as the CLI has run (or failed) so credentials never accumulate
+        // on disk under cloud-creds/.
+        await rm(credPath, { force: true }).catch(() => {});
+      }
+    },
+    async teardown(): Promise<void> {
+      // Per-invocation cred files are already removed in dispatch's finally;
+      // sweep the cloud-creds/ dir on teardown to clear any file orphaned by a
+      // hard crash mid-dispatch so no provider credential outlives the daemon.
+      await rm(credDir, { recursive: true, force: true }).catch(() => {});
+    },
+  };
+}

package/src/daemon/handlers/remote/backends/docker.ts

@@ -0,0 +1,79 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import type { DockerBackendConfig } from '../peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type BackendDispatchResult,
+  type DispatchPayload,
+  BackendDispatchError,
+  resolveTimeout,
+  buildRemoteShellCommand,
+} from './types.ts';
+import { runProcess } from './process-runner.ts';
+import { tokenizeCommand } from './local-process.ts';
+
+/**
+ * Docker backend: runs `docker exec {containerName} {command}` against the local
+ * Docker socket (or a configured DOCKER_HOST). The command is executed inside
+ * the target container via `sh -c` so shell semantics survive the hop, while the
+ * docker argv itself is fully tokenized (no shell on the daemon side).
+ */
+export function createDockerBackend(ctx: BackendContext): Backend {
+  return {
+    kind: 'docker',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'docker') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a docker peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'docker' } & DockerBackendConfig;
+      if (tokenizeCommand(command).length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+
+      // Resolve DOCKER_HOST. When it is a secret reference, pull the real value
+      // from the credential store and pass it via env (never argv).
+      const env: Record<string, string> = { ...(payload?.env ?? {}) };
+      if (config.dockerHost) {
+        const resolved = config.dockerHost.startsWith('goodvibes://')
+          ? await ctx.credentials.resolveRef(config.dockerHost)
+          : config.dockerHost;
+        if (!resolved) {
+          throw new BackendDispatchError(
+            `Could not resolve dockerHost for peer '${peer.peerId}'.`,
+            'REMOTE_BACKEND_CREDENTIAL_MISSING',
+          );
+        }
+        env.DOCKER_HOST = resolved;
+      }
+
+      const innerCommand = buildRemoteShellCommand(command, payload?.args);
+
+      const args = ['docker', 'exec'];
+      if (payload?.stdin !== undefined) args.push('-i');
+      args.push(config.containerName, 'sh', '-c', innerCommand);
+
+      ctx.logger.info('remote docker dispatch', {
+        peerId: peer.peerId,
+        container: config.containerName,
+      });
+      const result = await runProcess({
+        args,
+        timeoutMs: resolveTimeout(payload),
+        env,
+        ...(payload?.stdin !== undefined ? { stdin: payload.stdin } : {}),
+      });
+      return {
+        exitCode: result.timedOut ? 124 : result.exitCode,
+        stdout: result.stdout,
+        stderr: result.timedOut ? `${result.stderr}\n[remote] docker exec timed out` : result.stderr,
+      };
+    },
+  };
+}

package/src/daemon/handlers/remote/backends/index.ts

@@ -0,0 +1,40 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import { type Backend, type BackendContext } from './types.ts';
+import { createLocalProcessBackend } from './local-process.ts';
+import { createDockerBackend } from './docker.ts';
+import { createSshBackend } from './ssh.ts';
+import { createCloudTerminalBackend } from './cloud-terminal.ts';
+
+export type {
+  Backend,
+  BackendContext,
+  BackendDispatchResult,
+  DispatchPayload,
+} from './types.ts';
+export {
+  BackendDispatchError,
+  DEFAULT_SYNC_TIMEOUT_MS,
+  MAX_SYNC_TIMEOUT_MS,
+  resolveTimeout,
+} from './types.ts';
+
+/**
+ * Build the full backend map keyed by backendKind. Each backend resolves its
+ * own credentials lazily from the daemon credential store on dispatch; no
+ * network or process work happens at construction time.
+ */
+export function createBackends(
+  ctx: BackendContext,
+): Map<PeerRecord['backendKind'], Backend> {
+  const backends: Backend[] = [
+    createLocalProcessBackend(ctx),
+    createDockerBackend(ctx),
+    createSshBackend(ctx),
+    createCloudTerminalBackend(ctx),
+  ];
+  const map = new Map<PeerRecord['backendKind'], Backend>();
+  for (const backend of backends) {
+    map.set(backend.kind, backend);
+  }
+  return map;
+}

package/src/daemon/handlers/remote/backends/local-process.ts

@@ -0,0 +1,113 @@
+import type { PeerRecord } from '../peer-registry.ts';
+import type { LocalProcessBackendConfig } from '../peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type BackendDispatchResult,
+  type DispatchPayload,
+  BackendDispatchError,
+  resolveTimeout,
+} from './types.ts';
+import { runProcess } from './process-runner.ts';
+
+/** Split a command string into argv, honoring single/double quotes. */
+export function tokenizeCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  let started = false;
+  for (const ch of command) {
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      started = true;
+      continue;
+    }
+    if (ch === '\\' && quote !== "'") {
+      escaped = true;
+      started = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      started = true;
+      continue;
+    }
+    if (ch === ' ' || ch === '\t' || ch === '\n') {
+      if (started) {
+        tokens.push(current);
+        current = '';
+        started = false;
+      }
+      continue;
+    }
+    current += ch;
+    started = true;
+  }
+  if (started) tokens.push(current);
+  if (quote) {
+    throw new BackendDispatchError('Unterminated quote in command string.', 'REMOTE_BACKEND_BAD_COMMAND');
+  }
+  return tokens;
+}
+
+/**
+ * Local-process backend: spawns the command directly on the daemon host. This is
+ * the lowest-friction backend, used for self-hosted peers. An optional
+ * allowlist on backendConfig restricts which executables may run.
+ */
+export function createLocalProcessBackend(ctx: BackendContext): Backend {
+  return {
+    kind: 'local-process',
+    async dispatch(
+      peer: PeerRecord,
+      command: string,
+      payload?: DispatchPayload,
+    ): Promise<BackendDispatchResult> {
+      if (peer.backendConfig.kind !== 'local-process') {
+        throw new BackendDispatchError(
+          `Peer '${peer.peerId}' is not a local-process peer.`,
+          'REMOTE_BACKEND_KIND_MISMATCH',
+        );
+      }
+      const config = peer.backendConfig as { kind: 'local-process' } & LocalProcessBackendConfig;
+      const tokens = tokenizeCommand(command);
+      if (tokens.length === 0) {
+        throw new BackendDispatchError('Empty command.', 'REMOTE_BACKEND_BAD_COMMAND');
+      }
+      const executable = tokens[0]!;
+      if (config.allowedCommands && config.allowedCommands.length > 0) {
+        if (!config.allowedCommands.includes(executable)) {
+          throw new BackendDispatchError(
+            `Command '${executable}' is not in the peer allowlist.`,
+            'REMOTE_BACKEND_COMMAND_DENIED',
+          );
+        }
+      }
+      const args = [...tokens, ...(payload?.args ?? [])];
+      const cwd = payload?.cwd ?? config.cwd;
+      ctx.logger.info('remote local-process dispatch', { peerId: peer.peerId, executable });
+      const result = await runProcess({
+        args,
+        timeoutMs: resolveTimeout(payload),
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(payload?.env !== undefined ? { env: payload.env } : {}),
+        ...(payload?.stdin !== undefined ? { stdin: payload.stdin } : {}),
+      });
+      return {
+        exitCode: result.timedOut ? 124 : result.exitCode,
+        stdout: result.stdout,
+        stderr: result.timedOut ? `${result.stderr}\n[remote] command timed out` : result.stderr,
+      };
+    },
+  };
+}

package/src/daemon/handlers/remote/backends/process-runner.ts

@@ -0,0 +1,127 @@
+// Shared subprocess runner built on Bun.spawn. Captures stdout/stderr/exit code
+// with a hard timeout. Used by every backend that shells out (docker/ssh/cloud/
+// local-process). No credentials are ever passed as argv — callers pass key
+// material via files or the `env` overlay.
+
+export interface RunOptions {
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs: number;
+}
+
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+interface BunSubprocessLike {
+  readonly stdout: ReadableStream<Uint8Array> | null;
+  readonly stderr: ReadableStream<Uint8Array> | null;
+  readonly stdin: { write(chunk: string): void; end(): void | Promise<void> } | null;
+  readonly exited: Promise<number>;
+  kill(signal?: number | string): void;
+}
+
+interface BunSpawnOptions {
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  stdin?: 'pipe' | 'ignore';
+  stdout: 'pipe';
+  stderr: 'pipe';
+}
+
+type BunSpawn = (cmd: string[], options: BunSpawnOptions) => BunSubprocessLike;
+
+function getBunSpawn(): BunSpawn {
+  const globalBun = (globalThis as { Bun?: { spawn?: unknown } }).Bun;
+  if (!globalBun || typeof globalBun.spawn !== 'function') {
+    throw new Error('Bun.spawn is unavailable in this runtime.');
+  }
+  return globalBun.spawn as unknown as BunSpawn;
+}
+
+async function readStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
+  if (!stream) return '';
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let out = '';
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
+  return out;
+}
+
+/**
+ * Spawn a subprocess and capture its output with a hard timeout. The first
+ * element of `args` is the executable. Throws only on spawn failure; non-zero
+ * exit codes are returned in the result.
+ *
+ * On timeout the child is killed with SIGKILL and `child.exited` is awaited so
+ * no orphaned subprocess is left running after the timeout fires.
+ */
+export async function runProcess(options: RunOptions): Promise<RunResult> {
+  if (options.args.length === 0) {
+    throw new Error('runProcess requires at least one argument (the executable).');
+  }
+  const spawn = getBunSpawn();
+  const mergedEnv: Record<string, string | undefined> = {
+    ...process.env,
+    ...(options.env ?? {}),
+  };
+
+  const child = spawn(options.args, {
+    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    env: mergedEnv,
+    stdin: options.stdin !== undefined ? 'pipe' : 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  if (options.stdin !== undefined && child.stdin) {
+    child.stdin.write(options.stdin);
+    await child.stdin.end();
+  }
+
+  let timedOut = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // process may have already exited
+      }
+      resolve();
+    }, options.timeoutMs);
+  });
+
+  // Always await the child's real exit. On timeout we SIGKILL above, then the
+  // race resolves via child.exited (which settles once the kill takes effect),
+  // guaranteeing the subprocess is reaped rather than orphaned.
+  const [stdout, stderr, exitCode] = await Promise.all([
+    readStream(child.stdout),
+    readStream(child.stderr),
+    Promise.race([child.exited, timeoutPromise.then(() => child.exited)]),
+  ]);
+
+  if (timer) clearTimeout(timer);
+
+  return {
+    exitCode: typeof exitCode === 'number' ? exitCode : -1,
+    stdout,
+    stderr,
+    timedOut,
+  };
+}