feat(docker): stream build/compose progress live instead of on exit

The exec seam ran every docker subprocess with its stdout/stderr wired to
bytes.Buffers and only surfaced the output after the process exited, so a
`devcontainer build` (and the builds inside `up`) printed the whole BuildKit
log in one dump at the end with no visible progress.

Make streaming part of the Runner contract rather than a property of the
concrete OSRunner: Run now takes a `stream io.Writer` that, when non-nil,
receives the child's combined output live (OSRunner tees it to both the capture
buffer and the stream). The client passes this writer to whichever runner is
configured — real or fake — so there is no fake-vs-real branch and streaming is
exercised through the seam in tests.

docker.Client and ComposeClient gain a ProgressWriter; Build (and compose
build/up) opt into streaming, while Run/Config/Stop/Down stay buffered (compose
config's stdout is JSON the CLI parses and must not be streamed). The CLI sets
ProgressWriter to the log destination in text mode only — under --log-format
json a raw byte stream would corrupt the structured events, so that path keeps
emitting the buffered output as a log event.

Tests cover: OSRunner streams while still capturing; Build/compose-build stream
through the seam; streaming is opt-in (no ProgressWriter → nil stream); and
Run/compose-config never stream.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aledbf

internal/cli/build.go

@@ -182,6 +182,9 @@ func runBuild(ctx context.Context, out Output, opts *buildOpts) error {
 
 	// Setup Docker clients
 	dockerClient := docker.NewClient(opts.dockerPath, nil, logger)
+	// Stream `docker build` progress live to the terminal (text mode only; under
+	// --log-format json a raw byte stream would corrupt the structured events).
+	dockerClient.ProgressWriter = progressWriter(opts.logFormat, os.Stderr)
 
 	engine, err := docker.NewEngineClient(logger)
 	if err != nil {
@@ -429,7 +432,11 @@ func (r *buildRunner) buildDockerfile(ctx context.Context, cfg *config.DevContai
 		return nil, fmt.Errorf(msgDockerBuildFailed, result.ExitCode, string(result.Stderr))
 	}
 
-	logger.Write(string(result.Stderr), log.LevelInfo)
+	// When streaming, the build output already reached the terminal live; only
+	// emit the buffered copy when it did not (e.g. --log-format json).
+	if dockerClient.ProgressWriter == nil {
+		logger.Write(string(result.Stderr), log.LevelInfo)
+	}
 
 	// If config has features, extend the built image with features
 	if len(cfg.Features) > 0 {
@@ -598,7 +605,9 @@ func (r *buildRunner) buildImage(ctx context.Context, cfg *config.DevContainer,
 		if result.ExitCode != 0 {
 			return nil, fmt.Errorf(msgDockerBuildFailed, result.ExitCode, string(result.Stderr))
 		}
-		logger.Write(string(result.Stderr), log.LevelInfo)
+		if dockerClient.ProgressWriter == nil {
+			logger.Write(string(result.Stderr), log.LevelInfo)
+		}
 		return featureImageNames, nil
 	}
 
@@ -743,6 +752,7 @@ func (r *buildRunner) buildCompose(ctx context.Context, cfg *config.DevContainer
 	if err != nil {
 		return nil, fmt.Errorf("compose client: %w", err)
 	}
+	composeClient.ProgressWriter = progressWriter(opts.logFormat, os.Stderr)
 
 	composeConfig, err := composeClient.Config(ctx, composeFiles, "")
 	if err != nil {

internal/cli/output.go

@@ -36,3 +36,14 @@ func (c cmdOutput) Stderr() io.Writer { return c.cmd.ErrOrStderr() }
 
 // outputFor returns an Output backed by the given cobra command.
 func outputFor(cmd *cobra.Command) Output { return cmdOutput{cmd: cmd} }
+
+// progressWriter returns the writer that live subprocess progress (e.g. docker
+// build) should stream to: w in text mode, or nil under --log-format json where
+// a raw byte stream would corrupt the structured event stream (callers treat a
+// nil writer as "buffer and emit as a log event instead").
+func progressWriter(logFormat string, w io.Writer) io.Writer {
+	if logFormat == "json" {
+		return nil
+	}
+	return w
+}

internal/cli/up.go

@@ -377,6 +377,9 @@ func runUp(ctx context.Context, out Output, opts *upOpts) error {
 	}
 
 	dockerClient := docker.NewClient(opts.dockerPath, nil, logger)
+	// Stream `docker build` progress live to the log destination (text mode only;
+	// under --log-format json it would corrupt the structured event stream).
+	dockerClient.ProgressWriter = progressWriter(opts.logFormat, logDst)
 	run.docker = dockerClient
 
 	// Detect BuildKit
@@ -793,7 +796,11 @@ func (r *upRunner) fromDockerfile(ctx context.Context, cfg *config.DevContainer,
 		return "", fmt.Errorf(msgDockerBuildFailed, buildResult.ExitCode, string(buildResult.Stderr))
 	}
 
-	logger.Write(string(buildResult.Stderr), log.LevelInfo)
+	// When streaming, the build output already reached the terminal live; only
+	// emit the buffered copy when it did not (e.g. --log-format json).
+	if dockerClient.ProgressWriter == nil {
+		logger.Write(string(buildResult.Stderr), log.LevelInfo)
+	}
 
 	// Extend with features if any
 	if len(cfg.Features) > 0 {
@@ -1197,6 +1204,8 @@ func (r *upRunner) fromCompose(ctx context.Context, cfg *config.DevContainer, lo
 	if err != nil {
 		return "", fmt.Errorf("compose client: %w", err)
 	}
+	// Stream compose build/up progress to the same destination as docker builds.
+	composeClient.ProgressWriter = dockerClient.ProgressWriter
 
 	projectName := resolveComposeProjectName(ctx, cfg, env, composeFiles, composeClient)
 	logger.Write(fmt.Sprintf("Compose project: %s, service: %s", projectName, cfg.Service), log.LevelInfo)

internal/docker/argbuilders_test.go

@@ -2,6 +2,7 @@ package docker
 
 import (
 	"context"
+	"io"
 	"reflect"
 	"testing"
 
@@ -28,11 +29,15 @@ type cannedResponse struct {
 	code   int
 }
 
-func (r *recordingRunner) Run(_ context.Context, name string, args ...string) ([]byte, []byte, int, error) {
+func (r *recordingRunner) Run(_ context.Context, stream io.Writer, name string, args ...string) ([]byte, []byte, int, error) {
 	r.calls = append(r.calls, recordedCall{name: name, args: append([]string(nil), args...)})
 	if len(r.responses) > 0 {
 		resp := r.responses[0]
 		r.responses = r.responses[1:]
+		if stream != nil {
+			_, _ = stream.Write(resp.stdout)
+			_, _ = stream.Write(resp.stderr)
+		}
 		return resp.stdout, resp.stderr, resp.code, nil
 	}
 	return nil, nil, 0, nil

internal/docker/client.go

@@ -4,6 +4,7 @@ package docker
 import (
 	"context"
 	"fmt"
+	"io"
 	"regexp"
 	"strings"
 
@@ -20,6 +21,11 @@ type Client struct {
 	// Runner is the seam over process execution. When nil, a default OS-backed
 	// runner is used. Tests inject a fake to avoid shelling out.
 	Runner exec.Runner
+	// ProgressWriter, when set, receives `docker build` output live so the user
+	// sees progress as it happens instead of one dump on completion. Leave nil to
+	// keep output buffered (e.g. under --log-format json, where a raw byte stream
+	// would corrupt the structured event stream).
+	ProgressWriter io.Writer
 }
 
 // NewClient creates a Docker CLI client.
@@ -42,59 +48,49 @@ type ExecResult struct {
 }
 
 // runner returns the configured Runner, or a default OS-backed one carrying the
-// client's Env.
-func (c *Client) runner() exec.Runner {
+// client's Env plus extraEnv for this invocation.
+func (c *Client) runner(extraEnv []string) exec.Runner {
 	if c.Runner != nil {
 		return c.Runner
 	}
-	return exec.OSRunner{Env: c.Env}
+	return exec.OSRunner{Env: append(append([]string{}, c.Env...), extraEnv...)}
 }
 
-// Run executes a docker command and captures output. ctx cancels the subprocess
-// (e.g. on SIGINT), so a long-running `docker build` unwinds on Ctrl-C.
-func (c *Client) Run(ctx context.Context, args ...string) (*ExecResult, error) {
+// run executes a docker command and captures output. When stream is true and a
+// ProgressWriter is set, the child's output is also forwarded live through the
+// runner (a fake runner streams too, so the behavior is exercised in tests).
+// extraEnv is appended to the client's Env. ctx cancels the subprocess (e.g. on
+// SIGINT), so a long-running `docker build` unwinds on Ctrl-C.
+func (c *Client) run(ctx context.Context, stream bool, extraEnv []string, args ...string) (*ExecResult, error) {
 	c.Log.Write(fmt.Sprintf("Run: %s %s", c.DockerPath, strings.Join(args, " ")), log.LevelTrace)
 
-	stdout, stderr, exitCode, err := c.runner().Run(ctx, c.DockerPath, args...)
+	var live io.Writer
+	if stream {
+		live = c.ProgressWriter // nil unless the caller opted into live output
+	}
+	stdout, stderr, exitCode, err := c.runner(extraEnv).Run(ctx, live, c.DockerPath, args...)
 	if err != nil {
 		return nil, fmt.Errorf("exec docker: %w", err)
 	}
+	return &ExecResult{Stdout: stdout, Stderr: stderr, ExitCode: exitCode}, nil
+}
 
-	return &ExecResult{
-		Stdout:   stdout,
-		Stderr:   stderr,
-		ExitCode: exitCode,
-	}, nil
+// Run executes a docker command and captures output (no live streaming).
+func (c *Client) Run(ctx context.Context, args ...string) (*ExecResult, error) {
+	return c.run(ctx, false, nil, args...)
 }
 
-// Build runs `docker build` or `docker buildx build`. When opts.Env is set, those
-// entries are appended to the subprocess environment (used to point DOCKER_CONFIG
-// at a temporary credentials directory for private base-image pulls / --push /
-// --cache-to, without mutating the ambient environment).
+// Build runs `docker build` or `docker buildx build`, streaming progress to
+// ProgressWriter when set. When opts.Env is set, those entries are appended to
+// the subprocess environment (used to point DOCKER_CONFIG at a temporary
+// credentials directory for private base-image pulls / --push / --cache-to,
+// without mutating the ambient environment).
 func (c *Client) Build(ctx context.Context, opts BuildOptions) (*ExecResult, error) {
 	args := c.buildArgs(opts)
 	// Secret values reach BuildKit through the subprocess environment (referenced
 	// by `--secret id=KEY,env=KEY`), never on the command line.
 	extraEnv := append(append([]string{}, opts.Env...), opts.Secrets...)
-	if len(extraEnv) > 0 {
-		return c.runWithEnv(ctx, extraEnv, args...)
-	}
-	return c.Run(ctx, args...)
-}
-
-// runWithEnv is Run with extra environment entries appended for this invocation.
-func (c *Client) runWithEnv(ctx context.Context, extraEnv []string, args ...string) (*ExecResult, error) {
-	c.Log.Write(fmt.Sprintf("Run: %s %s", c.DockerPath, strings.Join(args, " ")), log.LevelTrace)
-
-	var r exec.Runner = exec.OSRunner{Env: append(append([]string{}, c.Env...), extraEnv...)}
-	if c.Runner != nil {
-		r = c.Runner // tests inject a fake; env is irrelevant there
-	}
-	stdout, stderr, exitCode, err := r.Run(ctx, c.DockerPath, args...)
-	if err != nil {
-		return nil, fmt.Errorf("exec docker: %w", err)
-	}
-	return &ExecResult{Stdout: stdout, Stderr: stderr, ExitCode: exitCode}, nil
+	return c.run(ctx, true, extraEnv, args...)
 }
 
 // BuildOptions configures a docker build.

internal/docker/compose.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	osexec "os/exec"
 	"strconv"
 	"strings"
@@ -22,6 +23,11 @@ type ComposeClient struct {
 	// Runner is the seam over process execution. When nil, a default OS-backed
 	// runner is used.
 	Runner exec.Runner
+	// ProgressWriter, when set, receives `docker compose build`/`up` output live
+	// so the user sees progress as it happens. Leave nil to keep output buffered
+	// (e.g. under --log-format json). `compose config` never streams — its stdout
+	// is JSON that the CLI parses.
+	ProgressWriter io.Writer
 }
 
 // NewComposeClient detects Compose v2 (`docker compose`) and returns a client.
@@ -45,8 +51,15 @@ func NewComposeClient(dockerPath, composePath string, env []string, logger log.L
 	return nil, fmt.Errorf("'docker compose' (v2) not found")
 }
 
-// Run executes a compose command. ctx cancels the subprocess (e.g. on SIGINT).
+// Run executes a compose command and captures output (no live streaming).
 func (c *ComposeClient) Run(ctx context.Context, args ...string) (*ExecResult, error) {
+	return c.run(ctx, false, args...)
+}
+
+// run executes a compose command. When stream is true and ProgressWriter is set,
+// the child's output is also forwarded live through the runner. ctx cancels the
+// subprocess.
+func (c *ComposeClient) run(ctx context.Context, stream bool, args ...string) (*ExecResult, error) {
 	fullArgs := append(c.Command[1:], args...)
 
 	// Emit a "Run:" start/stop pair around the subprocess, like the TS CLI wraps
@@ -56,11 +69,15 @@ func (c *ComposeClient) Run(ctx context.Context, args ...string) (*ExecResult, e
 	runLine := fmt.Sprintf("Run: %s %s", c.Command[0], strings.Join(fullArgs, " "))
 	startTS := c.Log.Start(runLine, log.LevelDebug)
 
-	runner := c.Runner
-	if runner == nil {
-		runner = exec.OSRunner{Env: c.Env}
+	var runner exec.Runner = exec.OSRunner{Env: c.Env}
+	if c.Runner != nil {
+		runner = c.Runner
+	}
+	var live io.Writer
+	if stream {
+		live = c.ProgressWriter
 	}
-	stdout, stderr, exitCode, err := runner.Run(ctx, c.Command[0], fullArgs...)
+	stdout, stderr, exitCode, err := runner.Run(ctx, live, c.Command[0], fullArgs...)
 	c.Log.Stop(runLine, startTS, log.LevelDebug)
 	if err != nil {
 		return nil, fmt.Errorf("exec compose: %w", err)
@@ -103,7 +120,7 @@ func (c *ComposeClient) Build(ctx context.Context, composeFiles []string, envFil
 	}
 	args = append(args, services...)
 
-	res, err := c.Run(ctx, args...)
+	res, err := c.run(ctx, true, args...)
 	if err != nil {
 		return err
 	}
@@ -126,7 +143,7 @@ func (c *ComposeClient) Up(ctx context.Context, composeFiles []string, envFile s
 	}
 	args = append(args, services...)
 
-	res, err := c.Run(ctx, args...)
+	res, err := c.run(ctx, true, args...)
 	if err != nil {
 		return err
 	}