boxdown 1.2.1 → 1.3.0

package/src/process.ts

@@ -12,12 +12,25 @@ export interface BufferedCommandOptions {
   logger?: WorkspaceCommandLogger
   onStdout?: (chunk: Buffer) => void
   onStderr?: (chunk: Buffer) => void
+  timeoutMs?: number
+  timeoutControl?: BufferedTimeoutControl
 }
 
 export interface CommandResult {
   code: number
   stdout: string
   stderr: string
+  timedOut?: boolean
+}
+
+export interface BufferedTimeoutControl {
+  schedule: (callback: () => void, milliseconds: number) => unknown
+  cancel: (handle: unknown) => void
+}
+
+const realTimeoutControl: BufferedTimeoutControl = {
+  schedule: (callback, milliseconds) => setTimeout(callback, milliseconds),
+  cancel: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)
 }
 
 function mergedEnv (env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -84,6 +97,10 @@ function writeChunk (target: 'stdout' | 'stderr' | false, chunk: Buffer): void {
 }
 
 export function runBuffered (command: string, args: string[], options: BufferedCommandOptions = {}): Promise<CommandResult> {
+  if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+    throw new Error('timeoutMs must be a finite non-negative number')
+  }
+
   return new Promise((resolve) => {
     const loggedCommand = options.logger?.startCommand(command, args, { cwd: options.cwd })
     const child = spawn(command, args, {
@@ -94,8 +111,13 @@ export function runBuffered (command: string, args: string[], options: BufferedC
 
     const stdoutChunks: Buffer[] = []
     const stderrChunks: Buffer[] = []
+    let settled = false
+    let timeoutHandle: unknown
+    let timeoutScheduled = false
+    const timeoutControl = options.timeoutControl ?? realTimeoutControl
 
     child.stdout.on('data', (chunk: Buffer) => {
+      if (settled) return
       stdoutChunks.push(chunk)
       loggedCommand?.stream('stdout', chunk)
       options.onStdout?.(chunk)
@@ -103,20 +125,18 @@ export function runBuffered (command: string, args: string[], options: BufferedC
     })
 
     child.stderr.on('data', (chunk: Buffer) => {
+      if (settled) return
       stderrChunks.push(chunk)
       loggedCommand?.stream('stderr', chunk)
       options.onStderr?.(chunk)
       writeChunk(options.mirrorStderr ?? 'stderr', chunk)
     })
 
-    let resolved = false
-
     child.on('error', (error) => {
-      if (resolved) {
-        return
-      }
+      if (settled) return
 
-      resolved = true
+      settled = true
+      if (timeoutScheduled) timeoutControl.cancel(timeoutHandle)
       loggedCommand?.error(error)
       loggedCommand?.finish(127)
       resolve({
@@ -127,11 +147,10 @@ export function runBuffered (command: string, args: string[], options: BufferedC
     })
 
     child.on('close', (code) => {
-      if (resolved) {
-        return
-      }
+      if (settled) return
 
-      resolved = true
+      settled = true
+      if (timeoutScheduled) timeoutControl.cancel(timeoutHandle)
       loggedCommand?.finish(code ?? 1)
       resolve({
         code: code ?? 1,
@@ -140,6 +159,27 @@ export function runBuffered (command: string, args: string[], options: BufferedC
       })
     })
 
+    if (options.timeoutMs !== undefined) {
+      timeoutHandle = timeoutControl.schedule(() => {
+        if (settled) return
+
+        settled = true
+        const message = `Command timed out after ${options.timeoutMs as number} milliseconds.`
+        const stdout = Buffer.concat(stdoutChunks).toString('utf8')
+        const stderr = Buffer.concat(stderrChunks).toString('utf8')
+        loggedCommand?.error(new Error(message))
+        loggedCommand?.finish(124)
+        child.kill('SIGKILL')
+        resolve({
+          code: 124,
+          stdout,
+          stderr: `${stderr}${stderr.length > 0 && !stderr.endsWith('\n') ? '\n' : ''}${message}\n`,
+          timedOut: true
+        })
+      }, options.timeoutMs)
+      timeoutScheduled = true
+    }
+
     if (options.input !== undefined) {
       child.stdin.end(options.input)
     } else {

package/src/progress.ts

@@ -178,6 +178,16 @@ export class ProgressReporter {
     this.#writeLine(`${promptRail()}  ${color(message, 'dim')}`)
   }
 
+  status (message: string): void {
+    if (this.mode === 'none') return
+    if (this.mode === 'verbose') {
+      this.#write(this.target, message)
+      return
+    }
+
+    this.#writeInteractiveLine(`${promptRail()}  ${color(message, 'dim')}`)
+  }
+
   warn (message: string): void {
     if (this.mode === 'none') {
       return
@@ -188,7 +198,7 @@ export class ProgressReporter {
       return
     }
 
-    this.#writeLine(`${promptRail()}  ${color('!', 'dim')} ${message}`)
+    this.#writeInteractiveLine(`${promptRail()}  ${color('!', 'dim')} ${message}`)
   }
 
   marker (message: string): void {
@@ -329,6 +339,18 @@ export class ProgressReporter {
     this.#write(this.target, message)
   }
 
+  #writeInteractiveLine (message: string): void {
+    if (this.#isTTY && this.#renderedStepLineCount > 0) {
+      this.#writeRaw(this.target, `\u001B[${this.#renderedStepLineCount}A\r\u001B[2K`)
+      this.#write(this.target, message)
+      this.#renderedStepLineCount = 0
+      this.#renderChecklist()
+      return
+    }
+
+    this.#writeLine(message)
+  }
+
   #renderSpinner (): void {
     const spinner = this.#spinner
     if (spinner === undefined) {
@@ -505,18 +527,38 @@ function outputWithoutProgressMarkers (output: string): string {
     .join('\n')
 }
 
-function tailLines (output: string, maxLines: number): string[] {
+export interface CommandFailureOptions {
+  tailLines?: number
+  logPath?: string
+}
+
+function outputLines (output: string): string[] {
   return output
     .split(/\r?\n/u)
     .map((line) => line.trimEnd())
     .filter((line) => line.trim().length > 0)
-    .slice(-maxLines)
 }
 
-export function formatCommandFailure (label: string, result: CommandResult, options: { tailLines?: number } = {}): string {
+function isDevcontainerErrorEnvelope (line: string): boolean {
+  try {
+    const value = JSON.parse(line) as { outcome?: unknown, message?: unknown }
+    return value !== null && typeof value === 'object' &&
+      value.outcome === 'error' && typeof value.message === 'string'
+  } catch {
+    return false
+  }
+}
+
+export function formatCommandFailure (label: string, result: CommandResult, options: CommandFailureOptions = {}): string {
   const maxLines = options.tailLines ?? DEFAULT_FAILURE_TAIL_LINES
-  const stderrTail = tailLines(outputWithoutProgressMarkers(result.stderr), maxLines)
-  const stdoutTail = tailLines(outputWithoutProgressMarkers(result.stdout), Math.max(0, maxLines - stderrTail.length))
+  const stderrLines = outputLines(outputWithoutProgressMarkers(result.stderr))
+  const stderrTail = maxLines <= 0 ? [] : stderrLines.slice(-maxLines)
+  const stdoutLines = outputLines(outputWithoutProgressMarkers(result.stdout))
+  const wrapperPresent = stdoutLines.some(isDevcontainerErrorEnvelope)
+  const specificStdout = stdoutLines.filter((line) => !isDevcontainerErrorEnvelope(line))
+  const hasSpecificDiagnostic = stderrLines.length > 0 || specificStdout.length > 0
+  const stdoutBudget = Math.max(0, maxLines - stderrTail.length)
+  const stdoutTail = stdoutBudget === 0 ? [] : specificStdout.slice(-stdoutBudget)
   const lines = [
     `${label} failed with exit code ${result.code}.`,
     'Rerun with --verbose to see full command output.'
@@ -530,6 +572,14 @@ export function formatCommandFailure (label: string, result: CommandResult, opti
     lines.push('', 'stdout tail:', ...stdoutTail.map((line) => `  ${line}`))
   }
 
+  if (wrapperPresent && !hasSpecificDiagnostic) {
+    lines.push('', 'The Dev Containers CLI reported a nested command failure without diagnostic output.')
+  }
+
+  if (options.logPath !== undefined) {
+    lines.push('', `Command log: ${options.logPath}`)
+  }
+
   return lines.join('\n')
 }
 
@@ -586,8 +636,13 @@ export async function runProgressCommand (
   }
 }
 
-export function assertProgressCommandSucceeded (label: string, result: CommandResult, message: string): void {
+export function assertProgressCommandSucceeded (
+  label: string,
+  result: CommandResult,
+  message: string,
+  options: CommandFailureOptions = {}
+): void {
   if (result.code !== 0) {
-    throw new Error(`${message}\n${formatCommandFailure(label, result)}`)
+    throw new Error(`${message}\n${formatCommandFailure(label, result, options)}`)
   }
 }