boxdown 1.2.0 → 1.3.0

package/src/container-runtime.ts

@@ -0,0 +1,295 @@
+import { performance } from 'node:perf_hooks'
+
+import { runBuffered, type CommandResult } from './process.ts'
+
+export type ContainerRuntimeReason =
+  | 'docker-cli-unavailable'
+  | 'docker-daemon-unavailable'
+  | 'buildx-builder-unavailable'
+
+export type ContainerRuntimeMode = 'buildx' | 'fallback'
+export type ContainerRuntimeCommandResult = CommandResult
+export type ContainerRuntimeCommandRunner = (
+  command: string,
+  args: string[],
+  timeoutMs?: number
+) => Promise<ContainerRuntimeCommandResult>
+
+export interface ContainerRuntimeFailure {
+  reason: ContainerRuntimeReason
+  command: string[]
+  detail: string
+  timedOut?: true
+}
+
+export type ContainerRuntimeProbe =
+  | { state: 'ready', mode: ContainerRuntimeMode, warnings: string[] }
+  | { state: 'waiting', failure: ContainerRuntimeFailure }
+  | { state: 'failed', failure: ContainerRuntimeFailure }
+
+const BUILDX_FALLBACK_WARNING = 'Docker Buildx is unavailable; the Dev Containers CLI will use its classic-build fallback.'
+
+async function runContainerRuntimeCommand (
+  command: string,
+  args: string[],
+  timeoutMs?: number
+): Promise<ContainerRuntimeCommandResult> {
+  return runBuffered(command, args, {
+    mirrorStdout: false,
+    mirrorStderr: false,
+    timeoutMs
+  })
+}
+
+function compactCommandOutput (result: ContainerRuntimeCommandResult): string {
+  const output = result.stderr.trim().length > 0 ? result.stderr : result.stdout
+  const compact = output.trim().replace(/\s+/gu, ' ').slice(0, 500)
+  return compact.length > 0 ? compact : `Command exited with code ${result.code}`
+}
+
+function failure (
+  reason: ContainerRuntimeReason,
+  command: string[],
+  result: ContainerRuntimeCommandResult
+): ContainerRuntimeFailure {
+  return {
+    reason,
+    command,
+    detail: compactCommandOutput(result),
+    ...(result.timedOut === true ? { timedOut: true as const } : {})
+  }
+}
+
+export async function probeContainerRuntime (
+  runCommand: ContainerRuntimeCommandRunner = runContainerRuntimeCommand
+): Promise<ContainerRuntimeProbe> {
+  const dockerVersionCommand = ['docker', '--version']
+  const dockerVersion = await runCommand(dockerVersionCommand[0] as string, dockerVersionCommand.slice(1))
+  if (dockerVersion.code !== 0) {
+    return {
+      state: 'failed',
+      failure: failure('docker-cli-unavailable', dockerVersionCommand, dockerVersion)
+    }
+  }
+
+  const dockerInfoCommand = ['docker', 'info']
+  const dockerInfo = await runCommand(dockerInfoCommand[0] as string, dockerInfoCommand.slice(1))
+  if (dockerInfo.code !== 0) {
+    return {
+      state: 'waiting',
+      failure: failure('docker-daemon-unavailable', dockerInfoCommand, dockerInfo)
+    }
+  }
+
+  const buildxVersionCommand = ['docker', 'buildx', 'version']
+  const buildxVersion = await runCommand(buildxVersionCommand[0] as string, buildxVersionCommand.slice(1))
+  if (buildxVersion.timedOut === true) {
+    return {
+      state: 'waiting',
+      failure: failure('buildx-builder-unavailable', buildxVersionCommand, buildxVersion)
+    }
+  }
+  if (buildxVersion.code !== 0) {
+    return {
+      state: 'ready',
+      mode: 'fallback',
+      warnings: [BUILDX_FALLBACK_WARNING]
+    }
+  }
+
+  const buildxInspectCommand = ['docker', 'buildx', 'inspect', '--bootstrap']
+  const buildxInspect = await runCommand(buildxInspectCommand[0] as string, buildxInspectCommand.slice(1))
+  if (buildxInspect.code !== 0) {
+    return {
+      state: 'waiting',
+      failure: failure('buildx-builder-unavailable', buildxInspectCommand, buildxInspect)
+    }
+  }
+
+  return { state: 'ready', mode: 'buildx', warnings: [] }
+}
+
+export type ContainerRuntimeWaitResult =
+  | { state: 'ready', mode: ContainerRuntimeMode, warnings: string[] }
+  | {
+      state: 'failed'
+      failure: ContainerRuntimeFailure
+      timedOut: boolean
+      timeoutMs: number
+    }
+
+export interface WaitForContainerRuntimeOptions {
+  runCommand?: ContainerRuntimeCommandRunner
+  onTransition?: (probe: ContainerRuntimeProbe) => void
+}
+
+/** @internal */
+export interface InternalContainerRuntimeWaitOptions extends WaitForContainerRuntimeOptions {
+  timeoutMs?: number
+  pollIntervalMs?: number
+  now?: () => number
+  sleep?: (milliseconds: number) => Promise<void>
+}
+
+function defaultSleep (milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+function transitionKey (probe: ContainerRuntimeProbe): string {
+  return probe.state === 'ready' ? 'ready' : `${probe.state}:${probe.failure.reason}`
+}
+
+class ContainerRuntimeDeadlineError extends Error {
+  readonly command: string[]
+
+  constructor (command: string[]) {
+    super(`Container runtime deadline expired before ${command.join(' ')}`)
+    this.command = command
+  }
+}
+
+function deadlineFailure (command: string[]): ContainerRuntimeFailure {
+  const reason: ContainerRuntimeReason = command[1] === 'info'
+    ? 'docker-daemon-unavailable'
+    : command[1] === 'buildx'
+      ? 'buildx-builder-unavailable'
+      : 'docker-cli-unavailable'
+
+  return {
+    reason,
+    command,
+    detail: `Readiness deadline expired before ${command.join(' ')} could start.`,
+    timedOut: true
+  }
+}
+
+/** @internal */
+export async function waitForContainerRuntimeInternal (
+  options: InternalContainerRuntimeWaitOptions = {}
+): Promise<ContainerRuntimeWaitResult> {
+  const timeoutMs = options.timeoutMs ?? 60_000
+  const pollIntervalMs = options.pollIntervalMs ?? 1_000
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0 || timeoutMs > 60_000) {
+    throw new Error('timeoutMs must be a finite number between 0 and 60000 milliseconds')
+  }
+  if (pollIntervalMs !== 1_000) {
+    throw new Error('pollIntervalMs must be exactly 1000 milliseconds')
+  }
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? defaultSleep
+  const deadline = now() + timeoutMs
+  let lastTransition: string | undefined
+  let lastWaitingFailure: ContainerRuntimeFailure | undefined
+
+  while (true) {
+    if (lastWaitingFailure !== undefined && deadline - now() <= 0) {
+      return { state: 'failed', failure: lastWaitingFailure, timedOut: true, timeoutMs }
+    }
+
+    const runCommand = options.runCommand ?? runContainerRuntimeCommand
+    let lastStartedCommand: string[] | undefined
+    let probe: ContainerRuntimeProbe
+    try {
+      probe = await probeContainerRuntime(async (command, args) => {
+        const commandArgs = [command, ...args]
+        const remainingMs = Math.floor(deadline - now())
+        if (remainingMs <= 0) throw new ContainerRuntimeDeadlineError(commandArgs)
+        lastStartedCommand = commandArgs
+        return runCommand(command, args, remainingMs)
+      })
+    } catch (error) {
+      if (!(error instanceof ContainerRuntimeDeadlineError)) throw error
+      return {
+        state: 'failed',
+        failure: lastWaitingFailure ?? deadlineFailure(error.command),
+        timedOut: true,
+        timeoutMs
+      }
+    }
+
+    if (deadline - now() <= 0) {
+      const currentFailure = probe.state === 'ready'
+        ? deadlineFailure(lastStartedCommand ?? ['docker', '--version'])
+        : probe.failure
+      return {
+        state: 'failed',
+        failure: lastWaitingFailure ?? currentFailure,
+        timedOut: true,
+        timeoutMs
+      }
+    }
+
+    if (probe.state === 'ready') return probe
+
+    const currentTransition = transitionKey(probe)
+    if (currentTransition !== lastTransition) {
+      options.onTransition?.(probe)
+      lastTransition = currentTransition
+    }
+
+    if (probe.state === 'failed') {
+      return {
+        state: 'failed',
+        failure: probe.failure,
+        timedOut: probe.failure.timedOut === true,
+        timeoutMs
+      }
+    }
+
+    lastWaitingFailure = probe.failure
+
+    const remainingMs = deadline - now()
+    if (remainingMs <= 0) {
+      return { state: 'failed', failure: probe.failure, timedOut: true, timeoutMs }
+    }
+
+    await sleep(Math.min(pollIntervalMs, remainingMs))
+  }
+}
+
+export async function waitForContainerRuntime (
+  options: WaitForContainerRuntimeOptions = {}
+): Promise<ContainerRuntimeWaitResult> {
+  return waitForContainerRuntimeInternal({
+    runCommand: options.runCommand,
+    onTransition: options.onTransition,
+    timeoutMs: 60_000,
+    pollIntervalMs: 1_000,
+    now: () => performance.now(),
+    sleep: defaultSleep
+  })
+}
+
+function commandText (command: readonly string[]): string {
+  return command.join(' ')
+}
+
+export function formatContainerRuntimeFailure (
+  result: Extract<ContainerRuntimeWaitResult, { state: 'failed' }>,
+  options: { logPath?: string } = {}
+): string {
+  const seconds = result.timeoutMs / 1_000
+  const descriptions: Record<ContainerRuntimeReason, string> = {
+    'docker-cli-unavailable': 'Docker CLI is required but was not available.',
+    'docker-daemon-unavailable': result.timedOut
+      ? `Docker daemon did not become ready within ${seconds} seconds.`
+      : 'Docker daemon is required but was not reachable.',
+    'buildx-builder-unavailable': result.timedOut
+      ? `Docker Buildx builder did not become ready within ${seconds} seconds.`
+      : 'Docker Buildx builder was not operational.'
+  }
+  const manualCheck = result.failure.reason === 'buildx-builder-unavailable'
+    ? 'docker buildx inspect'
+    : result.failure.reason === 'docker-daemon-unavailable'
+      ? 'docker info'
+      : 'docker --version'
+  const lines = [
+    descriptions[result.failure.reason],
+    `Last check: ${commandText(result.failure.command)}`,
+    `Detail: ${result.failure.detail}`,
+    `Check ${result.failure.reason === 'buildx-builder-unavailable' ? 'Buildx' : 'Docker'} with: ${manualCheck}`
+  ]
+
+  if (options.logPath !== undefined) lines.push(`Command log: ${options.logPath}`)
+  return lines.join('\n')
+}

package/src/devcontainer.ts

@@ -5,7 +5,7 @@ import { buildGeneratedDevcontainerConfig, publishContainerPortFromConfig, write
 import { codingAgentBinary, type CodingAgentCli } from './coding-agents.ts'
 import { resolveDevcontainerCli } from './devcontainer-cli.ts'
 import { configureWorkspaceGithubGitAuth } from './github-git-auth.ts'
-import { resolveGitSigningPlan } from './git-signing.ts'
+import { reportGitSigningPlan, resolveGitSigningPlan } from './git-signing.ts'
 import type { WorkspaceCommandLogger } from './logging.ts'
 import { recordWorkspaceDockerImage } from './metadata.ts'
 import type { WorkspaceContext } from './paths.ts'
@@ -21,6 +21,7 @@ export interface StartOptions {
   progress?: ProgressReporter
   logger?: WorkspaceCommandLogger
   reuseRunning?: boolean
+  runDevcontainerUp?: typeof runProgressCommand
 }
 
 export interface ContainerCommandOptions {
@@ -43,10 +44,6 @@ export interface DockerImageInfo {
   name?: string
 }
 
-interface DockerInspectContainer {
-  Image?: unknown
-  Config?: unknown
-}
 
 function devcontainerWorkspaceArgs (context: WorkspaceContext): string[] {
   return [
@@ -142,36 +139,28 @@ export async function findRunningContainerId (context: WorkspaceContext, options
   return result.stdout.split(/\r?\n/).find((line) => line.length > 0)
 }
 
-function isRecord (value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-}
-
-function parseDockerInspectImage (output: string, containerId: string): DockerImageInfo | undefined {
-  const trimmed = output.trim()
+export function parseDockerInspectImage (output: string, containerId: string): DockerImageInfo | undefined {
+  const [rawId, rawName] = output.trim().split('|')
 
-  if (trimmed.length === 0) {
+  if (rawId === undefined || rawId.length === 0) {
     return undefined
   }
 
-  let parsed: DockerInspectContainer
+  let id: unknown
+  let name: unknown
 
   try {
-    parsed = JSON.parse(trimmed) as DockerInspectContainer
+    id = JSON.parse(rawId)
+    name = rawName === undefined || rawName.length === 0 ? undefined : JSON.parse(rawName)
   } catch (error) {
     throw new Error(`Could not parse docker inspect output for ${containerId}`, { cause: error })
   }
 
-  if (typeof parsed.Image !== 'string' || parsed.Image.length === 0) {
-    return undefined
-  }
-
-  const configImage = isRecord(parsed.Config) && typeof parsed.Config.Image === 'string' && parsed.Config.Image.length > 0
-    ? parsed.Config.Image
-    : undefined
+  if (typeof id !== 'string' || id.length === 0) return undefined
 
   return {
-    id: parsed.Image,
-    ...(configImage === undefined ? {} : { name: configImage })
+    id,
+    ...(typeof name === 'string' && name.length > 0 ? { name } : {})
   }
 }
 
@@ -179,7 +168,7 @@ export async function inspectContainerImage (containerId: string, options: { log
   const result = await runBuffered('docker', [
     'inspect',
     '--format',
-    '{{json .}}',
+    '{{json .Image}}|{{json .Config.Image}}',
     containerId
   ], {
     logger: options.logger,
@@ -320,7 +309,19 @@ export async function startDevcontainer (context: WorkspaceContext, options: Sta
     progress.detail(context.generatedConfigPath)
   }
   try {
-    writeGeneratedDevcontainerConfig(context, await resolveGitSigningPlan(context))
+    const signingPlan = await resolveGitSigningPlan(context)
+    reportGitSigningPlan(signingPlan, {
+      logger: options.logger,
+      quiet: proxyMode,
+      ...(progress === undefined
+        ? {}
+        : {
+            writeWarning: (message: string) => {
+              progress.warn(message.trimEnd())
+            }
+          })
+    })
+    writeGeneratedDevcontainerConfig(context, signingPlan)
     if (hasConfigStep) {
       progress?.completeStep('devcontainer-config')
     }
@@ -374,7 +375,7 @@ export async function startDevcontainer (context: WorkspaceContext, options: Sta
         mirrorStderr: 'stderr',
         logger: options.logger
       })
-    : await runProgressCommand('devcontainer up', cli.command, [...cli.argsPrefix, ...args], {
+    : await (options.runDevcontainerUp ?? runProgressCommand)('devcontainer up', cli.command, [...cli.argsPrefix, ...args], {
         progress,
         spinnerLabel: 'Starting devcontainer',
         stepId: 'devcontainer-start',
@@ -388,7 +389,12 @@ export async function startDevcontainer (context: WorkspaceContext, options: Sta
   }
 
   if (progress !== undefined) {
-    assertProgressCommandSucceeded('devcontainer up', result, `devcontainer up failed for ${context.workspaceFolder}`)
+    assertProgressCommandSucceeded(
+      'devcontainer up',
+      result,
+      `devcontainer up failed for ${context.workspaceFolder}`,
+      { logPath: options.logger?.logPath }
+    )
   }
 
   const containerId = parseContainerIdFromUpOutput(`${result.stdout}\n${result.stderr}`) ?? await findRunningContainerId(context, { logger: options.logger })
@@ -503,7 +509,12 @@ export async function ensureContainerSshRuntime (context: WorkspaceContext, opti
   }
 
   if (options.progress !== undefined) {
-    assertProgressCommandSucceeded('prepare SSH runtime', result, 'Failed to prepare devcontainer SSH runtime')
+    assertProgressCommandSucceeded(
+      'prepare SSH runtime',
+      result,
+      'Failed to prepare devcontainer SSH runtime',
+      { logPath: options.logger?.logPath }
+    )
   }
 }
 
@@ -590,7 +601,12 @@ export async function ensureContainerCodingAgentCli (
   }
 
   if (options.progress !== undefined) {
-    assertProgressCommandSucceeded(`prepare ${codingAgentBinary(agent)}`, result, `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`)
+    assertProgressCommandSucceeded(
+      `prepare ${codingAgentBinary(agent)}`,
+      result,
+      `Could not install or refresh ${codingAgentBinary(agent)} inside the devcontainer`,
+      { logPath: options.logger?.logPath }
+    )
   }
 }
 
@@ -669,7 +685,18 @@ export async function refreshContainerGhAuth (context: WorkspaceContext, options
       quiet: true,
       progress
     })
-    writeGeneratedDevcontainerConfig(context, await resolveGitSigningPlan(context))
+    const signingPlan = await resolveGitSigningPlan(context)
+    reportGitSigningPlan(signingPlan, {
+      logger: options.logger,
+      ...(progress === undefined
+        ? {}
+        : {
+            writeWarning: (message: string) => {
+              progress.warn(message.trimEnd())
+            }
+          })
+    })
+    writeGeneratedDevcontainerConfig(context, signingPlan)
     if (hasConfigStep) {
       progress?.completeStep('gh-auth-config')
     }