chore: simplify Phase 2 code and bump version to v0.2.0

- Fix compile error: mgr.List() → mgr.List(ListOptions{All: true}) in integration test
- Add identity source constants (SourceTailscale, SourceEnv) replacing raw strings
- Use config.DefaultWorkspacesRoot constant in integration tests
- Collapse double-scan in port registry Allocate into single pass
- Move os.MkdirAll to NewFileRegistry constructor, use json.Marshal for state file
- Replace O(k) hyphen-collapse loop with single regex pass in identity.Sanitize
- Combine two SSH calls into one in ServerResources
- Extract portListenerCount helper to deduplicate AssertPortListening/AssertPortFree
- Update CLAUDE.md architecture section with Phase 2 packages
- Bump version to v0.2.0

Author: chuongld20

CLAUDE.md

@@ -3,14 +3,19 @@ Go CLI tool that turns any Linux machine into a ready-to-use dev environment in
 
 ## Architecture
 - `cmd/devbox/` — CLI entry point, all cobra commands defined in main.go
-- `internal/config/` — devbox.yaml parsing and validation
-- `internal/workspace/` — Workspace model and Manager interface (lifecycle: create/start/stop/destroy/list/ssh)
+- `internal/config/` — devbox.yaml parsing, validation, Resources, PortRangeConfig
+- `internal/identity/` — User identity resolution (Tailscale login → username, DEVBOX_USER fallback)
+- `internal/port/` — Port auto-allocation registry with conflict detection
+- `internal/server/` — Server pool management (add/remove/list/health), least-loaded selector
+- `internal/workspace/` — Workspace model, Manager interface, resource limits, user-scoped naming
 - `internal/tailscale/` — Tailscale Manager interface (serve/unserve/status)
+- `internal/integration/` — Multi-user integration tests (build tag: integration)
+- `internal/testutil/` — Shared test helpers for SSH, Docker, assertions
 - `.claude/specs/` — Product vision and design documents
 
 ## Key Patterns
 - **Cobra CLI**: All commands defined as funcs returning `*cobra.Command`, wired in `main()`
-- **Interface-driven**: `workspace.Manager` and `tailscale.Manager` define contracts; implementations are TBD (Phase 0 skeleton)
+- **Interface-driven**: `workspace.Manager`, `tailscale.Manager`, `identity.Resolver`, `port.Registry`, `server.Pool` define contracts
 - **Config**: Per-project `devbox.yaml` parsed into `DevboxConfig` struct with yaml tags; `name` and `server` are required fields
 - **Error wrapping**: `fmt.Errorf("context: %w", err)` for all error propagation
 - **Single binary**: No runtime dependencies, cross-compile with `GOOS`/`GOARCH`
@@ -25,6 +30,7 @@ Go CLI tool that turns any Linux machine into a ready-to-use dev environment in
 go build -o devbox ./cmd/devbox/   # Build binary
 go test ./...                       # Run all tests
 go vet ./...                        # Lint
-./devbox up [project]               # Start workspace
-./devbox stop|list|destroy|ssh      # Other commands (stubs in Phase 0)
+./devbox up [project]               # Start workspace (auto-selects server, resolves user)
+./devbox stop|list|destroy|ssh      # Workspace lifecycle commands
+./devbox server add|remove|list     # Server pool management
 ```

cmd/devbox/main.go

@@ -25,7 +25,7 @@ import (
 )
 
 var (
-	version = "0.1.0"
+	version = "0.2.0"
 	verbose bool
 	noColor bool
 )

internal/identity/identity.go

@@ -9,10 +9,16 @@ import (
 	"github.com/junixlabs/devbox/internal/tailscale"
 )
 
+// Source constants for identity resolution.
+const (
+	SourceTailscale = "tailscale"
+	SourceEnv       = "env"
+)
+
 // Identity represents a resolved user identity.
 type Identity struct {
 	Username string
-	Source   string // "tailscale" or "env"
+	Source   string
 }
 
 // Resolver resolves the current user identity.
@@ -32,15 +38,16 @@ func NewResolver(ts tailscale.Manager) Resolver {
 // unsafeChars matches characters not in [a-z0-9-].
 var unsafeChars = regexp.MustCompile(`[^a-z0-9-]`)
 
+// multiHyphen collapses consecutive hyphens into one.
+var multiHyphen = regexp.MustCompile(`-{2,}`)
+
 // Sanitize normalizes a username to lowercase alphanumeric + hyphens only.
 func Sanitize(username string) string {
 	s := strings.ToLower(username)
 	s = strings.ReplaceAll(s, ".", "-")
 	s = strings.ReplaceAll(s, "_", "-")
 	s = unsafeChars.ReplaceAllString(s, "")
-	for strings.Contains(s, "--") {
-		s = strings.ReplaceAll(s, "--", "-")
-	}
+	s = multiHyphen.ReplaceAllString(s, "-")
 	s = strings.Trim(s, "-")
 	return s
 }
@@ -60,15 +67,15 @@ func (r *resolver) Current() (*Identity, error) {
 		if err == nil && status.UserLogin != "" {
 			username := UsernameFromLogin(status.UserLogin)
 			if username != "" {
-				return &Identity{Username: username, Source: "tailscale"}, nil
+				return &Identity{Username: username, Source: SourceTailscale}, nil
 			}
 		}
 	}
 
 	if envUser := os.Getenv("DEVBOX_USER"); envUser != "" {
 		username := Sanitize(envUser)
 		if username != "" {
-			return &Identity{Username: username, Source: "env"}, nil
+			return &Identity{Username: username, Source: SourceEnv}, nil
 		}
 	}
 

internal/identity/identity_test.go

@@ -70,8 +70,8 @@ func TestResolver_Tailscale(t *testing.T) {
 	if id.Username != "dev" {
 		t.Errorf("Username = %q, want %q", id.Username, "dev")
 	}
-	if id.Source != "tailscale" {
-		t.Errorf("Source = %q, want %q", id.Source, "tailscale")
+	if id.Source != SourceTailscale {
+		t.Errorf("Source = %q, want %q", id.Source, SourceTailscale)
 	}
 }
 
@@ -86,8 +86,8 @@ func TestResolver_EnvFallback(t *testing.T) {
 	if id.Username != "envuser" {
 		t.Errorf("Username = %q, want %q", id.Username, "envuser")
 	}
-	if id.Source != "env" {
-		t.Errorf("Source = %q, want %q", id.Source, "env")
+	if id.Source != SourceEnv {
+		t.Errorf("Source = %q, want %q", id.Source, SourceEnv)
 	}
 }
 
@@ -101,8 +101,8 @@ func TestResolver_NilTailscale_EnvFallback(t *testing.T) {
 	if id.Username != "testuser" {
 		t.Errorf("Username = %q, want %q", id.Username, "testuser")
 	}
-	if id.Source != "env" {
-		t.Errorf("Source = %q, want %q", id.Source, "env")
+	if id.Source != SourceEnv {
+		t.Errorf("Source = %q, want %q", id.Source, SourceEnv)
 	}
 }
 

internal/integration/multi_workspace_test.go

@@ -97,7 +97,7 @@ func TestConcurrentWorkspaceCreation(t *testing.T) {
 	}
 
 	// Verify list returns all 3.
-	list, err := mgr.List()
+	list, err := mgr.List(workspace.ListOptions{All: true})
 	if err != nil {
 		t.Fatalf("List(): %v", err)
 	}
@@ -211,8 +211,8 @@ func TestUserIsolation(t *testing.T) {
 	testutil.WaitForContainer(t, server, cB, 60*time.Second)
 
 	// Verify workspace directories are separate.
-	testutil.AssertDirExists(t, server, "/workspaces/"+wsA.Name)
-	testutil.AssertDirExists(t, server, "/workspaces/"+wsB.Name)
+	testutil.AssertDirExists(t, server, config.DefaultWorkspacesRoot+"/"+wsA.Name)
+	testutil.AssertDirExists(t, server, config.DefaultWorkspacesRoot+"/"+wsB.Name)
 
 	// Verify containers run in separate Docker Compose projects.
 	projectA := testutil.DockerInspect(t, server, cA, "{{index .Config.Labels \"com.docker.compose.project\"}}")
@@ -275,7 +275,7 @@ func TestCleanupAfterDestroy(t *testing.T) {
 		t.Fatalf("Create: %v", err)
 	}
 	testutil.WaitForContainer(t, server, containerName(ws.Name), 60*time.Second)
-	testutil.AssertDirExists(t, server, "/workspaces/"+ws.Name)
+	testutil.AssertDirExists(t, server, config.DefaultWorkspacesRoot+"/"+ws.Name)
 
 	// Destroy the workspace.
 	if err := mgr.Destroy(ws.Name); err != nil {
@@ -295,7 +295,7 @@ func TestCleanupAfterDestroy(t *testing.T) {
 	testutil.AssertPortFree(t, server, port)
 
 	// Verify workspace directory is gone.
-	testutil.AssertDirNotExists(t, server, "/workspaces/"+ws.Name)
+	testutil.AssertDirNotExists(t, server, config.DefaultWorkspacesRoot+"/"+ws.Name)
 
 	// Verify workspace is removed from state.
 	_, err = mgr.Get(ws.Name)

internal/port/registry.go

@@ -19,6 +19,8 @@ type fileRegistry struct {
 // TODO: In-process mutex only protects single-process access. For concurrent
 // devbox processes, file-level locking (flock) would be needed.
 func NewFileRegistry(path string, portRange PortRange) Registry {
+	// Ensure state directory exists once at creation time.
+	_ = os.MkdirAll(filepath.Dir(path), 0o755)
 	return &fileRegistry{
 		path:      path,
 		portRange: portRange,
@@ -34,15 +36,12 @@ func (r *fileRegistry) Allocate(workspace, service string, override *int) (int,
 		return 0, err
 	}
 
-	// Check if this workspace+service already has an allocation.
+	// Single pass: check for existing allocation and build used-ports map.
+	usedPorts := make(map[int]string, len(allocs)) // port → workspace
 	for _, a := range allocs {
 		if a.WorkspaceName == workspace && a.ServiceName == service {
 			return a.Port, nil
 		}
-	}
-
-	usedPorts := make(map[int]string) // port → workspace
-	for _, a := range allocs {
 		usedPorts[a.Port] = a.WorkspaceName
 	}
 
@@ -186,11 +185,7 @@ func (r *fileRegistry) load() ([]Allocation, error) {
 
 // save writes allocations to the state file, creating directories if needed.
 func (r *fileRegistry) save(allocs []Allocation) error {
-	if err := os.MkdirAll(filepath.Dir(r.path), 0o755); err != nil {
-		return fmt.Errorf("creating port state directory: %w", err)
-	}
-
-	data, err := json.MarshalIndent(allocs, "", "  ")
+	data, err := json.Marshal(allocs)
 	if err != nil {
 		return fmt.Errorf("marshalling port state: %w", err)
 	}

internal/testutil/testutil.go

@@ -104,28 +104,36 @@ func WaitForContainer(t *testing.T, host, containerName string, timeout time.Dur
 	t.Fatalf("container %s not running after %v", containerName, timeout)
 }
 
+// portListenerCount returns the number of listeners on a port via ss.
+func portListenerCount(host string, port int) (string, error) {
+	cmd := fmt.Sprintf("ss -tlnp 2>/dev/null | grep -c ':%d ' || true", port)
+	out, err := SSHRunE(host, cmd)
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(out), nil
+}
+
 // AssertPortListening verifies that a port is bound on the remote host.
 func AssertPortListening(t *testing.T, host string, port int) {
 	t.Helper()
-	cmd := fmt.Sprintf("ss -tlnp 2>/dev/null | grep -c ':%d ' || true", port)
-	out, err := SSHRunE(host, cmd)
+	count, err := portListenerCount(host, port)
 	if err != nil {
 		t.Fatalf("AssertPortListening: %v", err)
 	}
-	if strings.TrimSpace(out) == "0" {
+	if count == "0" {
 		t.Errorf("expected port %d to be listening on %s", port, host)
 	}
 }
 
 // AssertPortFree verifies that a port is NOT bound on the remote host.
 func AssertPortFree(t *testing.T, host string, port int) {
 	t.Helper()
-	cmd := fmt.Sprintf("ss -tlnp 2>/dev/null | grep -c ':%d ' || true", port)
-	out, err := SSHRunE(host, cmd)
+	count, err := portListenerCount(host, port)
 	if err != nil {
 		t.Fatalf("AssertPortFree: %v", err)
 	}
-	if strings.TrimSpace(out) != "0" {
+	if count != "0" {
 		t.Errorf("expected port %d to be free on %s, but it's in use", port, host)
 	}
 }

internal/workspace/manager.go

@@ -327,15 +327,15 @@ func (m *remoteManager) ServerResources(host string) (*ServerResourceInfo, error
 	defer sshExec.Close()
 
 	ctx := context.Background()
-	cpuOut, _, err := sshExec.Run(ctx, host, "nproc")
+	combined, _, err := sshExec.Run(ctx, host, "nproc && echo '---SEPARATOR---' && cat /proc/meminfo")
 	if err != nil {
-		return nil, fmt.Errorf("running nproc on %s: %w", host, err)
+		return nil, fmt.Errorf("querying server resources on %s: %w", host, err)
 	}
-	memOut, _, err := sshExec.Run(ctx, host, "cat /proc/meminfo")
-	if err != nil {
-		return nil, fmt.Errorf("reading /proc/meminfo on %s: %w", host, err)
+	parts := strings.SplitN(combined, "---SEPARATOR---", 2)
+	if len(parts) != 2 {
+		return nil, fmt.Errorf("unexpected server resources output from %s", host)
 	}
-	return ParseServerResources(cpuOut, memOut)
+	return ParseServerResources(strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1]))
 }
 
 // mustGet returns a workspace by name, or a WorkspaceError if not found.