@happier-dev/stack 0.2.1-preview.1775586714.26562 → 0.2.11

package/scripts/utils/proc/proc.mjs

@@ -1,6 +1,22 @@
 import { spawn } from 'node:child_process';
-import { createWriteStream, mkdirSync } from 'node:fs';
+import {
+  closeSync,
+  createWriteStream,
+  mkdirSync,
+  openSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
 import { join } from 'node:path';
+import { Writable } from 'node:stream';
+
+import { terminateProcessGroup } from './terminate.mjs';
+
+const plannedExitMarker = Symbol('happier.stack.plannedExit');
+const DEFAULT_TEE_MAX_BYTES = 16 * 1024 * 1024;
 
 export function resolveDefaultShellForCommand(cmd, { platform = process.platform } = {}) {
   if (platform !== 'win32') return false;
@@ -15,6 +31,62 @@ export function resolveDefaultShellForCommand(cmd, { platform = process.platform
   return normalized.endsWith('.cmd') || normalized.endsWith('.bat') || normalized.endsWith('.ps1');
 }
 
+function normalizePlannedExitReason(reason) {
+  const cleaned = String(reason ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return cleaned || 'planned';
+}
+
+export function markSpawnedProcessPlannedExit(child, reason = 'planned') {
+  if (!child || (typeof child !== 'object' && typeof child !== 'function')) {
+    return () => {};
+  }
+
+  const marker = { reason: normalizePlannedExitReason(reason) };
+  try {
+    Object.defineProperty(child, plannedExitMarker, {
+      value: marker,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  } catch {
+    try {
+      child[plannedExitMarker] = marker;
+    } catch {
+      return () => {};
+    }
+  }
+
+  return () => {
+    try {
+      if (child[plannedExitMarker] === marker) {
+        delete child[plannedExitMarker];
+      }
+    } catch {
+      // ignore cleanup failures; the marker only affects best-effort log wording
+    }
+  };
+}
+
+export function getSpawnedProcessPlannedExitReason(child) {
+  const reason = child?.[plannedExitMarker]?.reason;
+  return typeof reason === 'string' && reason ? reason : null;
+}
+
+function formatSpawnedProcessExitLine(prefix, code, sig, child) {
+  const plannedReason = getSpawnedProcessPlannedExitReason(child);
+  const trimmedPrefix = String(prefix ?? '').trimEnd();
+  if (plannedReason) {
+    return `${trimmedPrefix} planned ${plannedReason} exit (code=${code}, sig=${sig})\n`;
+  }
+  return `${trimmedPrefix} exited (code=${code}, sig=${sig})\n`;
+}
+
 function nextLineBreakIndex(s) {
   const n = s.indexOf('\n');
   const r = s.indexOf('\r');
@@ -29,22 +101,39 @@ function consumeLineBreak(buf) {
   return buf;
 }
 
-function writeWithPrefix(stream, prefix, bufState, chunk) {
+function consumeLineChunk(bufState, chunk) {
   const s = chunk.toString();
   bufState.buf += s;
+  const lines = [];
   while (true) {
     const idx = nextLineBreakIndex(bufState.buf);
     if (idx < 0) break;
     const line = bufState.buf.slice(0, idx);
     bufState.buf = consumeLineBreak(bufState.buf.slice(idx));
+    lines.push(line);
+  }
+  return lines;
+}
+
+function writePrefixedLines(stream, prefix, lines) {
+  for (const line of lines) {
     stream.write(`${prefix}${line}\n`);
   }
 }
 
-function flushPrefixed(stream, prefix, bufState) {
-  if (!bufState.buf) return;
-  stream.write(`${prefix}${bufState.buf}\n`);
+function writeWithPrefix(stream, prefix, bufState, chunk) {
+  writePrefixedLines(stream, prefix, consumeLineChunk(bufState, chunk));
+}
+
+function flushLineBuffer(bufState) {
+  if (!bufState.buf) return [];
+  const line = bufState.buf;
   bufState.buf = '';
+  return [line];
+}
+
+function flushPrefixed(stream, prefix, bufState) {
+  writePrefixedLines(stream, prefix, flushLineBuffer(bufState));
 }
 
 function sanitizeLogFileToken(raw) {
@@ -53,11 +142,137 @@ function sanitizeLogFileToken(raw) {
   return cleaned || 'proc';
 }
 
+function createWritableFinishController(stream) {
+  if (!stream) {
+    return { endAndWait: async () => {} };
+  }
+  let settle;
+  const completion = new Promise((resolve) => {
+    settle = resolve;
+  });
+  stream.once('finish', settle);
+  stream.once('close', settle);
+  stream.on('error', settle);
+  let endRequested = false;
+  return {
+    async endAndWait() {
+      if (!endRequested) {
+        endRequested = true;
+        try {
+          stream.end();
+        } catch {
+          settle();
+        }
+      }
+      await completion;
+    },
+  };
+}
+
+function createBoundedTeeStream(filePath, maxBytes) {
+  const normalizedMaxBytes = Number.isFinite(maxBytes) && maxBytes > 0
+    ? Math.trunc(maxBytes)
+    : DEFAULT_TEE_MAX_BYTES;
+  const rotatedPath = `${filePath}.1`;
+  let size = 0;
+  try {
+    size = statSync(filePath).size;
+  } catch {
+    size = 0;
+  }
+  if (size > normalizedMaxBytes) {
+    let descriptor = null;
+    try {
+      const tail = Buffer.allocUnsafe(normalizedMaxBytes);
+      descriptor = openSync(filePath, 'r');
+      const bytesRead = readSync(
+        descriptor,
+        tail,
+        0,
+        normalizedMaxBytes,
+        size - normalizedMaxBytes,
+      );
+      closeSync(descriptor);
+      descriptor = null;
+      rmSync(rotatedPath, { force: true });
+      writeFileSync(rotatedPath, tail.subarray(0, bytesRead));
+      writeFileSync(filePath, '');
+      size = 0;
+    } catch {
+      if (descriptor != null) {
+        try {
+          closeSync(descriptor);
+        } catch {
+          // Ignore cleanup failure; normal stream error handling remains authoritative.
+        }
+      }
+    }
+  }
+  let writer = null;
+  const openDestination = (flags) => {
+    const stream = createWriteStream(filePath, { flags });
+    stream.on('error', (error) => {
+      if (writer && !writer.destroyed) writer.destroy(error);
+    });
+    return stream;
+  };
+  let destination = openDestination('a');
+
+  writer = new Writable({
+    write(chunk, _encoding, callback) {
+      let bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      if (bytes.length > normalizedMaxBytes) {
+        bytes = bytes.subarray(bytes.length - normalizedMaxBytes);
+      }
+
+      const writeCurrent = () => {
+        size += bytes.length;
+        destination.write(bytes, callback);
+      };
+      if (size + bytes.length <= normalizedMaxBytes) {
+        writeCurrent();
+        return;
+      }
+
+      destination.end(() => {
+        try {
+          rmSync(rotatedPath, { force: true });
+          renameSync(filePath, rotatedPath);
+        } catch {
+          // Rotation is best-effort. Reopening with `w` below still bounds the active file.
+        }
+        destination = openDestination('w');
+        size = 0;
+        writeCurrent();
+      });
+    },
+    final(callback) {
+      destination.end(callback);
+    },
+  });
+  return writer;
+}
+
+function writeChildStdinBestEffort(child, input) {
+  const stdin = child?.stdin;
+  if (!stdin) return;
+  // Pipe errors are emitted asynchronously, so a try/catch around write/end is insufficient.
+  // The child exit code remains the command outcome when it intentionally closes stdin early.
+  stdin.on('error', () => {});
+  try {
+    stdin.end(String(input));
+  } catch {
+    // The child may exit synchronously before its stdin stream is writable.
+  }
+}
+
 export function spawnProc(label, cmd, args, env, options = {}) {
   const {
     silent = false,
     teeFile,
     teeLabel,
+    teeMaxBytes = DEFAULT_TEE_MAX_BYTES,
+    onLine,
     ...spawnOptions
   } = options ?? {};
 
@@ -81,15 +296,25 @@ export function spawnProc(label, cmd, args, env, options = {}) {
       teePath = join(teeDir, `${sanitizeLogFileToken(label)}.log`);
     }
   }
-  const teeStream = teePath ? createWriteStream(teePath, { flags: 'a' }) : null;
-  const teeOutState = { buf: '' };
-  const teeErrState = { buf: '' };
+  const teeStream = teePath ? createBoundedTeeStream(teePath, teeMaxBytes) : null;
+  const teeFinish = createWritableFinishController(teeStream);
   const teePrefix = (() => {
     const t = typeof teeLabel === 'string' ? teeLabel.trim() : '';
     if (t) return `[${t}] `;
     return outPrefix;
   })();
 
+  const emitLines = (stream, lines) => {
+    if (typeof onLine !== 'function') return;
+    for (const line of lines) {
+      try {
+        onLine({ stream, line });
+      } catch {
+        // ignore observer failures; child process logging should stay best-effort
+      }
+    }
+  };
+
   const child = spawn(cmd, args, {
     env,
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -98,38 +323,53 @@ export function spawnProc(label, cmd, args, env, options = {}) {
     detached: process.platform !== 'win32',
     ...spawnOptionsRest,
   });
+  let spawnError = null;
+  child.on('error', (error) => {
+    spawnError ??= error;
+  });
 
   child.stdout?.on('data', (d) => {
-    if (!silent) writeWithPrefix(process.stdout, outPrefix, outState, d);
-    if (teeStream) writeWithPrefix(teeStream, teePrefix, teeOutState, d);
+    const lines = consumeLineChunk(outState, d);
+    emitLines('stdout', lines);
+    if (!silent) writePrefixedLines(process.stdout, outPrefix, lines);
+    if (teeStream) writePrefixedLines(teeStream, teePrefix, lines);
   });
   child.stderr?.on('data', (d) => {
-    if (!silent) writeWithPrefix(process.stderr, errPrefix, errState, d);
-    if (teeStream) writeWithPrefix(teeStream, teePrefix, teeErrState, d);
+    const lines = consumeLineChunk(errState, d);
+    emitLines('stderr', lines);
+    if (!silent) writePrefixedLines(process.stderr, errPrefix, lines);
+    if (teeStream) writePrefixedLines(teeStream, teePrefix, lines);
   });
-  child.on('close', () => {
+  child.completion = new Promise((resolve) => child.on('close', async (code, signal) => {
+    child.__happierClosed = true;
+    const outLines = flushLineBuffer(outState);
+    const errLines = flushLineBuffer(errState);
+    emitLines('stdout', outLines);
+    emitLines('stderr', errLines);
     if (!silent) {
-      flushPrefixed(process.stdout, outPrefix, outState);
-      flushPrefixed(process.stderr, errPrefix, errState);
+      writePrefixedLines(process.stdout, outPrefix, outLines);
+      writePrefixedLines(process.stderr, errPrefix, errLines);
     }
     if (teeStream) {
-      flushPrefixed(teeStream, teePrefix, teeOutState);
-      flushPrefixed(teeStream, teePrefix, teeErrState);
-      try {
-        teeStream.end();
-      } catch {
-        // ignore
-      }
+      writePrefixedLines(teeStream, teePrefix, outLines);
+      writePrefixedLines(teeStream, teePrefix, errLines);
     }
-  });
+    await teeFinish.endAndWait();
+    resolve({
+      code: spawnError ? null : code,
+      signal: signal ?? null,
+      ...(spawnError ? { error: spawnError } : {}),
+    });
+  }));
   child.on('exit', (code, sig) => {
     if (code !== 0) {
+      const streamLine = formatSpawnedProcessExitLine(`[${label}]`, code, sig, child);
       if (!silent) {
-        process.stderr.write(`[${label}] exited (code=${code}, sig=${sig})\n`);
+        process.stderr.write(streamLine);
       }
       if (teeStream) {
         try {
-          teeStream.write(`${teePrefix.trimEnd()} exited (code=${code}, sig=${sig})\n`);
+          teeStream.write(formatSpawnedProcessExitLine(teePrefix, code, sig, child));
         } catch {
           // ignore
         }
@@ -140,21 +380,27 @@ export function spawnProc(label, cmd, args, env, options = {}) {
   return child;
 }
 
-export function killProcessTree(child, signal) {
-  if (!child || child.exitCode != null || !child.pid) {
-    return;
+export async function killProcessTree(child, signal, { graceMs = 800, boundary } = {}) {
+  if (!child) {
+    return { ok: true, alreadyExited: true };
+  }
+  const platform = boundary?.platform ?? process.platform;
+  if (
+    platform === 'win32'
+    && (child.exitCode != null || child.signalCode != null || child.__happierClosed === true)
+  ) {
+    return { ok: false, reason: 'leader_absent_without_tree_proof' };
   }
 
-  try {
-    if (process.platform !== 'win32') {
-      // Kill the process group.
-      process.kill(-child.pid, signal);
-    } else {
-      child.kill(signal);
+  if (!child.pid) {
+    try {
+      return { ok: child.kill?.(signal) !== false, signal };
+    } catch {
+      return { ok: false, reason: 'missing_pid_kill_failed' };
     }
-  } catch {
-    // ignore
   }
+
+  return await terminateProcessGroup(child.pid, { graceMs, signal, boundary });
 }
 
 export async function run(cmd, args, options = {}) {
@@ -171,12 +417,7 @@ export async function run(cmd, args, options = {}) {
 
     const proc = spawn(cmd, args, { shell, ...spawnOptions, stdio });
     if (input != null && proc.stdin) {
-      try {
-        proc.stdin.write(String(input));
-        proc.stdin.end();
-      } catch {
-        // ignore
-      }
+      writeChildStdinBestEffort(proc, input);
     }
     const t =
       Number.isFinite(timeoutMs) && timeoutMs > 0
@@ -200,12 +441,40 @@ export async function run(cmd, args, options = {}) {
 }
 
 export async function runCapture(cmd, args, options = {}) {
-  const { timeoutMs, shell: shellOverride, stdio: _stdioOverride, ...spawnOptions } = options ?? {};
+  const { timeoutMs, signal, shell: shellOverride, stdio: _stdioOverride, ...spawnOptions } = options ?? {};
   const shell = typeof shellOverride === 'boolean' ? shellOverride : resolveDefaultShellForCommand(cmd);
   return await new Promise((resolvePromise, rejectPromise) => {
     const proc = spawn(cmd, args, { shell, ...spawnOptions, stdio: ['ignore', 'pipe', 'pipe'] });
     let out = '';
     let err = '';
+    let settled = false;
+    const abortError = () => {
+      const error = new Error(`${cmd} ${args.join(' ')} aborted`);
+      error.code = 'ABORT_ERR';
+      error.out = out;
+      error.err = err;
+      return error;
+    };
+    const cleanup = () => {
+      if (t) clearTimeout(t);
+      signal?.removeEventListener?.('abort', onAbort);
+    };
+    const rejectOnce = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      rejectPromise(error);
+    };
+    const resolveOnce = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolvePromise(value);
+    };
+    const onAbort = () => {
+      try { proc.kill('SIGKILL'); } catch {}
+      rejectOnce(abortError());
+    };
     const t =
       Number.isFinite(timeoutMs) && timeoutMs > 0
         ? setTimeout(() => {
@@ -218,16 +487,20 @@ export async function runCapture(cmd, args, options = {}) {
             e.code = 'ETIMEDOUT';
             e.out = out;
             e.err = err;
-            rejectPromise(e);
+            rejectOnce(e);
           }, timeoutMs)
         : null;
+    if (signal?.aborted) {
+      onAbort();
+    } else {
+      signal?.addEventListener?.('abort', onAbort, { once: true });
+    }
     proc.stdout?.on('data', (d) => (out += d.toString()));
     proc.stderr?.on('data', (d) => (err += d.toString()));
-    proc.on('error', rejectPromise);
+    proc.on('error', rejectOnce);
     proc.on('exit', (code, signal) => {
-      if (t) clearTimeout(t);
       if (code === 0) {
-        resolvePromise(out);
+        resolveOnce(out);
       } else {
         const e = new Error(
           `${cmd} ${args.join(' ')} failed (code=${code ?? 'null'}, sig=${signal ?? 'null'}): ${err.trim()}`
@@ -237,7 +510,7 @@ export async function runCapture(cmd, args, options = {}) {
         e.signal = signal;
         e.out = out;
         e.err = err;
-        rejectPromise(e);
+        rejectOnce(e);
       }
     });
   });
@@ -268,14 +541,19 @@ export async function runCaptureResult(cmd, args, options = {}) {
       return '';
     })();
     const teeStream = shouldTee ? createWriteStream(teePath, { flags: 'a' }) : null;
+    const teeFinish = createWritableFinishController(teeStream);
     const keepaliveEveryMs = Number.isFinite(heartbeatMs) && heartbeatMs > 0 ? heartbeatMs : 0;
+    let terminalOverride = null;
+    let resolved = false;
 
     function writeKeepaliveLine(line) {
       if (shouldStream) process.stdout.write(`${prefix}${line}\n`);
       if (shouldTee && teeStream) teeStream.write(`${teePrefix}${line}\n`);
     }
 
-    function resolveWith(res) {
+    async function resolveWith(res) {
+      if (resolved) return;
+      resolved = true;
       if (shouldStream) {
         flushPrefixed(process.stdout, prefix, outState);
         flushPrefixed(process.stderr, prefix, errState);
@@ -283,12 +561,8 @@ export async function runCaptureResult(cmd, args, options = {}) {
       if (shouldTee && teeStream) {
         flushPrefixed(teeStream, teePrefix, teeOutState);
         flushPrefixed(teeStream, teePrefix, teeErrState);
-        try {
-          teeStream.end();
-        } catch {
-          // ignore
-        }
       }
+      await teeFinish.endAndWait();
       resolvePromise(res);
     }
     const hb =
@@ -301,23 +575,13 @@ export async function runCaptureResult(cmd, args, options = {}) {
     const t =
       Number.isFinite(timeoutMs) && timeoutMs > 0
         ? setTimeout(() => {
+            terminalOverride = { kind: 'timeout' };
             try {
               proc.kill('SIGKILL');
             } catch {
               // ignore
             }
             if (hb) clearInterval(hb);
-            resolveWith({
-              ok: false,
-              exitCode: null,
-              signal: null,
-              out,
-              err,
-              timedOut: true,
-              startedAt,
-              finishedAt: Date.now(),
-              durationMs: Date.now() - startedAt,
-            });
           }, timeoutMs)
         : null;
     proc.stdout?.on('data', (d) => {
@@ -332,41 +596,30 @@ export async function runCaptureResult(cmd, args, options = {}) {
     });
 
     if (input != null && proc.stdin) {
-      try {
-        proc.stdin.write(String(input));
-        proc.stdin.end();
-      } catch {
-        // ignore
-      }
+      writeChildStdinBestEffort(proc, input);
     }
     proc.on('error', (e) => {
       if (t) clearTimeout(t);
       if (hb) clearInterval(hb);
-      resolveWith({
-        ok: false,
-        exitCode: null,
-        signal: null,
-        out,
-        err: err + (err.endsWith('\n') || !err ? '' : '\n') + String(e) + '\n',
-        timedOut: false,
-        startedAt,
-        finishedAt: Date.now(),
-        durationMs: Date.now() - startedAt,
-      });
+      terminalOverride = { kind: 'error', error: e };
     });
     proc.on('close', (code, signal) => {
       if (t) clearTimeout(t);
       if (hb) clearInterval(hb);
+      const finishedAt = Date.now();
+      const errorSuffix = terminalOverride?.kind === 'error'
+        ? (err.endsWith('\n') || !err ? '' : '\n') + String(terminalOverride.error) + '\n'
+        : '';
       resolveWith({
-        ok: code === 0,
-        exitCode: code,
-        signal: signal ?? null,
+        ok: terminalOverride == null && code === 0,
+        exitCode: terminalOverride ? null : code,
+        signal: terminalOverride ? null : signal ?? null,
         out,
-        err,
-        timedOut: false,
+        err: err + errorSuffix,
+        timedOut: terminalOverride?.kind === 'timeout',
         startedAt,
-        finishedAt: Date.now(),
-        durationMs: Date.now() - startedAt,
+        finishedAt,
+        durationMs: finishedAt - startedAt,
       });
     });
   });