movehat 0.1.8 → 0.2.0

package/src/utils/childProcessAdapter.ts

@@ -0,0 +1,215 @@
+import { spawn } from 'node:child_process';
+import type { Readable, Writable } from 'node:stream';
+
+/**
+ * Injectable abstraction over `child_process.spawn`.
+ *
+ * Tests inject a fake adapter; production code uses `defaultChildProcessAdapter`.
+ * Higher-level helpers (see `runCli`) wrap this with redaction and error handling.
+ *
+ * Two affordances:
+ *   - `run` for one-shot commands whose stdout/stderr fit in memory.
+ *   - `spawn` for long-running children where the caller wants to stream
+ *     output incrementally and decide when to kill the process.
+ */
+export interface ChildProcessAdapter {
+  run(input: RunInput): Promise<RunResult>;
+  spawn(input: SpawnInput): SpawnedProcess;
+}
+
+export interface RunInput {
+  command: string;
+  args: readonly string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  stdin?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  /**
+   * When `true`, the child inherits the parent's stdio (stdout, stderr,
+   * stdin go straight to the terminal). The resulting `RunResult.stdout`
+   * and `RunResult.stderr` will be empty strings because nothing is
+   * captured. Useful for interactive commands like `mocha`, `tsx`, or
+   * `pnpm install` where the user expects to see live output.
+   *
+   * If `inheritStdio` is `true`, `stdin` on this input is ignored — the
+   * child reads directly from the parent's stdin.
+   *
+   * Default: `false`.
+   */
+  inheritStdio?: boolean;
+}
+
+export interface RunResult {
+  /**
+   * Numeric exit code from the child. `-1` when the child was terminated by
+   * a signal (no numeric exit code available) — in that case `signal` is
+   * populated.
+   */
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  /**
+   * Populated when the child died from a signal (e.g. external abort, kill
+   * during shutdown). `undefined` for normal exits.
+   */
+  signal?: NodeJS.Signals;
+}
+
+/**
+ * Input for `spawn()`. Mirrors the subset of `RunInput` that applies to
+ * long-running children: no `stdin`, no `timeoutMs`, no `signal`. Callers
+ * control the lifecycle via the returned `SpawnedProcess`.
+ */
+export interface SpawnInput {
+  command: string;
+  args: readonly string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  /**
+   * `'pipe'` (default) makes stdout/stderr/stdin streams available on the
+   * returned `SpawnedProcess`. `'ignore'` silences the child entirely
+   * (streams are `null`). For `'inherit'`, use `run` with `inheritStdio: true`
+   * instead — the spawn handle isn't useful when the parent owns stdio.
+   */
+  stdio?: 'pipe' | 'ignore';
+}
+
+/**
+ * Handle returned by `spawn()`. Callers can listen on streams, kill the
+ * process, or await `exited` for the final exit code and signal.
+ */
+export interface SpawnedProcess {
+  pid: number | undefined;
+  stdout: Readable | null;
+  stderr: Readable | null;
+  stdin: Writable | null;
+  kill(signal?: NodeJS.Signals): boolean;
+  /**
+   * Resolves once when the child exits, regardless of how the caller
+   * triggered it (natural exit, `kill`, or process death). Safe to await
+   * multiple times.
+   */
+  exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+}
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+class DefaultChildProcessAdapter implements ChildProcessAdapter {
+  run(input: RunInput): Promise<RunResult> {
+    // Skip the default 5-minute timeout when the caller wires stdio
+    // through to the terminal — interactive sessions (mocha, tsx scripts,
+    // `movement move test`, `pnpm install`) routinely exceed 5 minutes and
+    // SIGTERM'ing them silently is a regression vs the direct-spawn code
+    // these callers used before M1.3a. An explicitly-passed `timeoutMs`
+    // is always honored, regardless of `inheritStdio`.
+    const timeoutMs =
+      input.timeoutMs ?? (input.inheritStdio ? undefined : DEFAULT_TIMEOUT_MS);
+
+    return new Promise<RunResult>((resolve, reject) => {
+      const child = spawn(input.command, [...input.args], {
+        cwd: input.cwd,
+        env: input.env ?? process.env,
+        stdio: input.inheritStdio ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+      });
+
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+
+      // Streams are null when stdio is 'inherit'; the `?.` covers that.
+      child.stdout?.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+      child.stderr?.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+
+      let timeoutHandle: NodeJS.Timeout | undefined;
+      const clearTimer = () => {
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+      };
+
+      if (timeoutMs !== undefined) {
+        timeoutHandle = setTimeout(() => {
+          child.kill('SIGTERM');
+          reject(new Error(`Command timed out after ${timeoutMs}ms: ${input.command}`));
+        }, timeoutMs);
+      }
+
+      const onAbort = () => {
+        child.kill('SIGTERM');
+      };
+
+      if (input.signal) {
+        if (input.signal.aborted) {
+          clearTimer();
+          child.kill('SIGTERM');
+          reject(new Error('Command aborted before start'));
+          return;
+        }
+        input.signal.addEventListener('abort', onAbort, { once: true });
+      }
+
+      child.on('error', (err) => {
+        clearTimer();
+        input.signal?.removeEventListener('abort', onAbort);
+        reject(err);
+      });
+
+      child.on('close', (code, signal) => {
+        clearTimer();
+        input.signal?.removeEventListener('abort', onAbort);
+        const result: RunResult = {
+          exitCode: code !== null ? code : -1,
+          stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+          stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        };
+        if (signal) {
+          result.signal = signal;
+        }
+        resolve(result);
+      });
+
+      // Under inheritStdio, child.stdin is null and the parent's stdin
+      // is wired through; we just skip the close call. Otherwise, end()
+      // either with the provided string or empty to close stdin cleanly.
+      if (!input.inheritStdio) {
+        if (input.stdin !== undefined) {
+          child.stdin?.end(input.stdin);
+        } else {
+          child.stdin?.end();
+        }
+      }
+    });
+  }
+
+  spawn(input: SpawnInput): SpawnedProcess {
+    const stdio = input.stdio ?? 'pipe';
+    const child = spawn(input.command, [...input.args], {
+      cwd: input.cwd,
+      env: input.env ?? process.env,
+      stdio,
+    });
+
+    // `exited` must settle whether the child dies via natural exit, kill,
+    // or a spawn-time `error` (e.g. ENOENT). Both events resolve once;
+    // a settled guard prevents double-resolve if both happen to fire.
+    const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+      let settled = false;
+      const finish = (code: number | null, signal: NodeJS.Signals | null) => {
+        if (settled) return;
+        settled = true;
+        resolve({ code, signal });
+      };
+      child.on('exit', (code, signal) => finish(code, signal));
+      child.on('error', () => finish(null, null));
+    });
+
+    return {
+      pid: child.pid,
+      stdout: child.stdout,
+      stderr: child.stderr,
+      stdin: child.stdin,
+      kill: (signal?: NodeJS.Signals) => child.kill(signal),
+      exited,
+    };
+  }
+}
+
+export const defaultChildProcessAdapter: ChildProcessAdapter = new DefaultChildProcessAdapter();

package/src/utils/parseCliOutput.ts

@@ -0,0 +1,27 @@
+/**
+ * Helpers for extracting fields out of Movement CLI stdout / stderr.
+ *
+ * @internal — not exported from `src/index.ts`.
+ */
+
+/**
+ * Extract the transaction hash from a `movement` CLI subcommand's stdout.
+ *
+ * Tries the context-bearing pattern first (`transaction hash: 0x…`,
+ * `txn hash: 0x…`, `hash: 0x…`) and falls back to any 64-char hex
+ * literal in the buffer. Returns `undefined` if no candidate matches.
+ *
+ * Shared by `core/Publisher.ts` (publish), `harness/codeObject.ts`
+ * (deploy-object / upgrade-object), and `harness/script.ts`
+ * (run-script). All three CLI subcommands emit the txHash in the same
+ * shape — keep this helper as the single source of truth so a future
+ * CLI-format change is a one-line fix.
+ */
+export function parseTxHash(stdout: string): string | undefined {
+  const withContext = stdout.match(
+    /(?:transaction\s*(?:hash)?|txn\s*(?:hash)?|hash):\s*(0x[a-fA-F0-9]{64})\b/i
+  );
+  if (withContext?.[1]) return withContext[1];
+  const fallback = stdout.match(/\b(0x[a-fA-F0-9]{64})\b/);
+  return fallback?.[1];
+}

package/src/utils/redact.ts

@@ -0,0 +1,24 @@
+/**
+ * Patterns that match well-known secret shapes Movement tools emit on
+ * stderr / stdout / CLI arguments. Each match is replaced with
+ * `***REDACTED***` by `redactSecrets`.
+ *
+ * The labelled pattern (second entry) intentionally accepts bare `priv` and
+ * `key` prefixes. Over-redaction is fine; missing a real key is not.
+ */
+export const SECRET_PATTERNS: readonly RegExp[] = [
+  /ed25519-priv-0x[0-9a-fA-F]{64}/g,
+  /(private[_-]?key|priv[_-]?key|priv|key)\s*[:=]\s*0x[0-9a-fA-F]{32,}/gi,
+];
+
+/**
+ * Replaces every match of every known secret pattern with `***REDACTED***`.
+ * Idempotent: running it on already-redacted text is a no-op.
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  for (const pattern of SECRET_PATTERNS) {
+    out = out.replace(pattern, '***REDACTED***');
+  }
+  return out;
+}

package/src/utils/runCli.ts

@@ -0,0 +1,64 @@
+import { CliExecutionError } from '../errors.js';
+import {
+  defaultChildProcessAdapter,
+  type ChildProcessAdapter,
+  type RunInput,
+  type RunResult,
+} from './childProcessAdapter.js';
+import { redactSecrets } from './redact.js';
+
+export { redactSecrets } from './redact.js';
+
+const STDOUT_PREVIEW_CHARS = 2000;
+
+export interface RunCliOptions {
+  /** Override the child-process adapter (defaults to spawn-based). */
+  adapter?: ChildProcessAdapter | undefined;
+  /** When true (default), throw `CliExecutionError` on non-zero exit. */
+  throwOnNonZeroExit?: boolean | undefined;
+}
+
+/**
+ * Spawns a CLI command through the injectable adapter, redacts well-known
+ * secret shapes from stdout and stderr before returning, and throws
+ * `CliExecutionError` (with already-redacted payloads) on non-zero exits.
+ *
+ * Callers that need to inspect raw output should set `throwOnNonZeroExit:false`
+ * and consume the returned `RunResult` directly — fields are still redacted.
+ *
+ * Pass `input.inheritStdio: true` for interactive commands (mocha, tsx,
+ * package managers) where the user expects to see live output. Under that
+ * flag, `stdout` and `stderr` in the returned `RunResult` are empty strings
+ * (and so is `stdoutPreview` on any `CliExecutionError`), since the child
+ * writes directly to the terminal rather than to a captured buffer.
+ */
+export async function runCli(
+  input: RunInput,
+  options: RunCliOptions = {}
+): Promise<RunResult> {
+  const adapter = options.adapter ?? defaultChildProcessAdapter;
+  const throwOnNonZeroExit = options.throwOnNonZeroExit ?? true;
+
+  const raw = await adapter.run(input);
+  const result: RunResult = {
+    exitCode: raw.exitCode,
+    stdout: redactSecrets(raw.stdout),
+    stderr: redactSecrets(raw.stderr),
+  };
+  if (raw.signal) {
+    result.signal = raw.signal;
+  }
+
+  if (result.exitCode !== 0 && throwOnNonZeroExit) {
+    throw new CliExecutionError(
+      `Command failed with exit code ${result.exitCode}: ${input.command}`,
+      input.command,
+      input.args,
+      result.exitCode,
+      result.stderr,
+      result.stdout.slice(0, STDOUT_PREVIEW_CHARS)
+    );
+  }
+
+  return result;
+}