feat(docker): M2 network-ensure, container enumeration, compose driver (spec 03)

Extends the read-only Client and adds the lifecycle driver (DECISIONS D4/D5):

- Client.EnsureNetwork / NetworkExists: idempotent tool-owned external bridge
  network (devstack owns it because Compose refuses to create external networks).
- Client.ListManaged: label-filtered container enumeration with All=true and
  compose one-offs excluded — the basis for ref-count reconciliation from live
  reality; Container/PortBinding read-only projections.
- moby-backed impls (moby/moby/client) + in-memory MockClient so workspace
  reconcile/up logic is unit/race-testable without a daemon.
- Compose driver: `docker compose -p <project> -f <file>` up/down/stop/build via
  an injectable Runner; secrets pass through exec env (never a file, §7.5);
  failures wrap command + exit code + stderr (CmdError, §7.6).

Command construction + mock filtering are unit-tested.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gustavobertoi

internal/docker/compose.go

@@ -0,0 +1,128 @@
+package docker
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+// Runner executes external commands. It is injectable so compose command
+// construction is unit-testable without a real `docker` binary.
+type Runner interface {
+	// Run streams stdout/stderr to the user (image-pull/up progress).
+	Run(ctx context.Context, env []string, dir, name string, args ...string) error
+	// Output captures stdout (for `compose ps --format json` and friends).
+	Output(ctx context.Context, env []string, dir, name string, args ...string) ([]byte, error)
+}
+
+// ExecRunner runs commands via os/exec, inheriting the process env plus extra
+// env. Secrets are passed through env here and never written to a file (§7.5).
+// A failure is wrapped with the command + exit code + captured stderr so the
+// error is self-debuggable (ARCHITECTURE §7.6).
+type ExecRunner struct{}
+
+func (ExecRunner) Run(ctx context.Context, env []string, dir, name string, args ...string) error {
+	cmd := exec.CommandContext(ctx, name, args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), env...)
+	cmd.Stdout = os.Stdout
+	var stderr bytes.Buffer
+	cmd.Stderr = io.MultiWriter(os.Stderr, &stderr)
+	if err := cmd.Run(); err != nil {
+		return &CmdError{Cmd: name + " " + strings.Join(args, " "), Err: err, Stderr: strings.TrimSpace(stderr.String())}
+	}
+	return nil
+}
+
+func (ExecRunner) Output(ctx context.Context, env []string, dir, name string, args ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, name, args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), env...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	if err := cmd.Run(); err != nil {
+		return nil, &CmdError{Cmd: name + " " + strings.Join(args, " "), Err: err, Stderr: strings.TrimSpace(stderr.String())}
+	}
+	return stdout.Bytes(), nil
+}
+
+// CmdError carries the failed command, its error, and captured stderr.
+type CmdError struct {
+	Cmd    string
+	Stderr string
+	Err    error
+}
+
+func (e *CmdError) Error() string {
+	if e.Stderr != "" {
+		return fmt.Sprintf("`%s` failed: %v\n%s", e.Cmd, e.Err, e.Stderr)
+	}
+	return fmt.Sprintf("`%s` failed: %v", e.Cmd, e.Err)
+}
+
+func (e *CmdError) Unwrap() error { return e.Err }
+
+// Compose drives the `docker compose` CLI for a single stack with an explicit
+// project name and compose file (DECISIONS D5). Lifecycle verbs run here;
+// container enumeration stays on the read-only SDK Client.
+type Compose struct {
+	Project string   // -p <project>
+	File    string   // -f <compose file>
+	Dir     string   // working dir (build contexts resolve relative to it)
+	Env     []string // extra env (resolved secrets), appended to os.Environ
+	Runner  Runner
+}
+
+// NewCompose builds a Compose driver using the real exec runner.
+func NewCompose(project, file, dir string) *Compose {
+	return &Compose{Project: project, File: file, Dir: dir, Runner: ExecRunner{}}
+}
+
+func (c *Compose) base() []string {
+	return []string{"compose", "-p", c.Project, "-f", c.File}
+}
+
+// Up brings the stack (or the named subset of services) up detached. With no
+// services it brings the whole stack up. It does NOT pass --remove-orphans: the
+// shared stack is brought up service-by-service and stateful services must never
+// be disturbed implicitly (spec 03).
+func (c *Compose) Up(ctx context.Context, services ...string) error {
+	args := append(c.base(), "up", "-d")
+	args = append(args, services...)
+	return c.Runner.Run(ctx, c.Env, c.Dir, "docker", args...)
+}
+
+// Down stops and removes the stack's containers (and its default network).
+// Named external networks are NOT removed by compose — devstack owns those.
+// volumes=true also removes named volumes (destructive — caller confirms).
+func (c *Compose) Down(ctx context.Context, volumes bool) error {
+	args := append(c.base(), "down")
+	if volumes {
+		args = append(args, "--volumes")
+	}
+	return c.Runner.Run(ctx, c.Env, c.Dir, "docker", args...)
+}
+
+// Stop pauses the stack (or named services) without removing containers — used
+// by `shared gc`/autostop where the data volumes must survive.
+func (c *Compose) Stop(ctx context.Context, services ...string) error {
+	args := append(c.base(), "stop")
+	args = append(args, services...)
+	return c.Runner.Run(ctx, c.Env, c.Dir, "docker", args...)
+}
+
+// Build rebuilds the named services (with --no-cache for the selective-rebuild
+// contexts the generate ledger flagged). With no services, builds all.
+func (c *Compose) Build(ctx context.Context, noCache bool, services ...string) error {
+	args := append(c.base(), "build")
+	if noCache {
+		args = append(args, "--no-cache")
+	}
+	args = append(args, services...)
+	return c.Runner.Run(ctx, c.Env, c.Dir, "docker", args...)
+}

internal/docker/compose_test.go

@@ -0,0 +1,82 @@
+package docker
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// fakeRunner records invocations so command construction can be asserted without
+// a real docker binary.
+type fakeRunner struct {
+	calls [][]string
+}
+
+func (f *fakeRunner) Run(_ context.Context, _ []string, _, name string, args ...string) error {
+	f.calls = append(f.calls, append([]string{name}, args...))
+	return nil
+}
+
+func (f *fakeRunner) Output(_ context.Context, _ []string, _, name string, args ...string) ([]byte, error) {
+	f.calls = append(f.calls, append([]string{name}, args...))
+	return nil, nil
+}
+
+func (f *fakeRunner) last() string { return strings.Join(f.calls[len(f.calls)-1], " ") }
+
+func newTestCompose() (*Compose, *fakeRunner) {
+	r := &fakeRunner{}
+	c := &Compose{Project: "devstack-api", File: "/ws/.devstack/docker-compose.yaml", Dir: "/ws/.devstack", Runner: r}
+	return c, r
+}
+
+func TestComposeUp(t *testing.T) {
+	c, r := newTestCompose()
+	if err := c.Up(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	want := "docker compose -p devstack-api -f /ws/.devstack/docker-compose.yaml up -d"
+	if got := r.last(); got != want {
+		t.Errorf("up = %q, want %q", got, want)
+	}
+}
+
+func TestComposeUpSubset(t *testing.T) {
+	c, r := newTestCompose()
+	c.Project = "devstack-shared"
+	_ = c.Up(context.Background(), "postgres", "redis")
+	if got := r.last(); !strings.HasSuffix(got, "up -d postgres redis") {
+		t.Errorf("subset up = %q", got)
+	}
+}
+
+func TestComposeDownAndStop(t *testing.T) {
+	c, r := newTestCompose()
+	_ = c.Down(context.Background(), false)
+	if got := r.last(); !strings.HasSuffix(got, "down") {
+		t.Errorf("down = %q", got)
+	}
+	_ = c.Down(context.Background(), true)
+	if got := r.last(); !strings.HasSuffix(got, "down --volumes") {
+		t.Errorf("down --volumes = %q", got)
+	}
+	_ = c.Stop(context.Background(), "postgres")
+	if got := r.last(); !strings.HasSuffix(got, "stop postgres") {
+		t.Errorf("stop = %q", got)
+	}
+}
+
+func TestComposeBuildNoCache(t *testing.T) {
+	c, r := newTestCompose()
+	_ = c.Build(context.Background(), true, "api")
+	if got := r.last(); !strings.HasSuffix(got, "build --no-cache api") {
+		t.Errorf("build = %q", got)
+	}
+}
+
+func TestCmdErrorMessage(t *testing.T) {
+	e := &CmdError{Cmd: "docker compose up", Stderr: "network not found", Err: context.Canceled}
+	if !strings.Contains(e.Error(), "network not found") || !strings.Contains(e.Error(), "docker compose up") {
+		t.Errorf("error message = %q", e.Error())
+	}
+}

internal/docker/docker.go

@@ -35,10 +35,41 @@ type Client interface {
 	// ContextName returns the active Docker context the client is bound to;
 	// this keys the state ledger.
 	ContextName() string
+	// EnsureNetwork idempotently ensures an external bridge network named `name`
+	// exists (inspect → create), applying labels on creation. devstack owns this
+	// network's lifecycle because Compose refuses to create external networks
+	// (ARCHITECTURE §4). Safe to call concurrently under the flock.
+	EnsureNetwork(ctx context.Context, name string, labels map[string]string) error
+	// NetworkExists reports whether a network with the exact name exists.
+	NetworkExists(ctx context.Context, name string) (bool, error)
+	// ListManaged returns containers carrying ALL of the given labels, with
+	// All=true (so stopped containers are visible) and compose one-offs excluded
+	// (DECISIONS D5) — the basis for ref-count reconciliation from live reality.
+	ListManaged(ctx context.Context, labels map[string]string) ([]Container, error)
 	// Close releases the underlying connection.
 	Close() error
 }
 
+// Container is the read-only projection of a container devstack cares about.
+type Container struct {
+	ID     string
+	Name   string // primary name, leading slash stripped
+	Labels map[string]string
+	State  string // running | exited | created | ...
+	Ports  []PortBinding
+}
+
+// Running reports whether the container is in the running state.
+func (c Container) Running() bool { return c.State == "running" }
+
+// PortBinding is one published host port mapping on a container.
+type PortBinding struct {
+	HostIP        string
+	HostPort      int
+	ContainerPort int
+	Protocol      string // tcp | udp | sctp
+}
+
 // Version is a simple major.minor for tool-version gating.
 type Version struct{ Major, Minor int }
 

internal/docker/inspect.go

@@ -0,0 +1,108 @@
+package docker
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	moby "github.com/moby/moby/client"
+)
+
+// networkDriver is the driver for the tool-owned shared bridge network.
+const networkDriver = "bridge"
+
+// composeOneoffLabel marks `compose run`/`exec` one-off containers; excluding
+// them keeps them from inflating ref counts (DECISIONS D5).
+const composeOneoffLabel = "com.docker.compose.oneoff"
+
+// EnsureNetwork idempotently ensures an external bridge network exists.
+func (m *mobyClient) EnsureNetwork(ctx context.Context, name string, labels map[string]string) error {
+	exists, err := m.NetworkExists(ctx, name)
+	if err != nil {
+		return err
+	}
+	if exists {
+		return nil
+	}
+	_, err = m.cli.NetworkCreate(ctx, name, moby.NetworkCreateOptions{
+		Driver:     networkDriver,
+		Attachable: true,
+		Labels:     labels,
+	})
+	if err != nil {
+		// Tolerate a concurrent creator (the flock makes this rare, but a foreign
+		// process or another engine client could still win the race).
+		if strings.Contains(strings.ToLower(err.Error()), "already exists") {
+			return nil
+		}
+		return fmt.Errorf("create network %q: %w", name, err)
+	}
+	return nil
+}
+
+// NetworkExists reports whether a network with the exact name exists. NetworkList
+// name filtering is a substring match, so the result is checked for an exact hit.
+func (m *mobyClient) NetworkExists(ctx context.Context, name string) (bool, error) {
+	res, err := m.cli.NetworkList(ctx, moby.NetworkListOptions{
+		Filters: moby.Filters{}.Add("name", name),
+	})
+	if err != nil {
+		return false, fmt.Errorf("list networks: %w", err)
+	}
+	for _, n := range res.Items {
+		if n.Name == name {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+// ListManaged returns containers carrying ALL the given labels, with stopped
+// containers included and compose one-offs excluded.
+func (m *mobyClient) ListManaged(ctx context.Context, labels map[string]string) ([]Container, error) {
+	f := moby.Filters{}
+	for k, v := range labels {
+		f = f.Add("label", k+"="+v)
+	}
+	res, err := m.cli.ContainerList(ctx, moby.ContainerListOptions{All: true, Filters: f})
+	if err != nil {
+		return nil, fmt.Errorf("list containers: %w", err)
+	}
+	out := make([]Container, 0, len(res.Items))
+	for _, s := range res.Items {
+		if s.Labels[composeOneoffLabel] == "True" || s.Labels[composeOneoffLabel] == "true" {
+			continue
+		}
+		c := Container{
+			ID:     s.ID,
+			Name:   primaryName(s.Names),
+			Labels: s.Labels,
+			State:  string(s.State),
+		}
+		for _, p := range s.Ports {
+			if p.PublicPort == 0 {
+				continue // not published to the host
+			}
+			ip := ""
+			if p.IP.IsValid() {
+				ip = p.IP.String()
+			}
+			c.Ports = append(c.Ports, PortBinding{
+				HostIP:        ip,
+				HostPort:      int(p.PublicPort),
+				ContainerPort: int(p.PrivatePort),
+				Protocol:      p.Type,
+			})
+		}
+		out = append(out, c)
+	}
+	return out, nil
+}
+
+// primaryName returns the first container name with the leading '/' stripped.
+func primaryName(names []string) string {
+	if len(names) == 0 {
+		return ""
+	}
+	return strings.TrimPrefix(names[0], "/")
+}