docs(run): run workspace roots honour the environment's exclude-services; regression orders every root

The standing rule: a behaviour change updates docs/ in the same PR.
`docs/commands.md` now says, under `codefly run workspace`, that the selected
environment's `exclude-services` removes services from the composition roots —
a module withdrawn whole contributes none, its service-entry included — and
that CLI and run-profile exclusions still apply on top.

The regression builds an isolated two-module workspace, selects `local` (which
withdraws worker/witness) and `staging` (which does not), applies CLI and
profile exclusions beside them, calls the real CompositionRoots, builds the
real Core dependency graph with the same selected-environment filter the flow
uses, and orders to every selected root — the exact shape that failed on main:
`cannot topologically sort to <worker/witness>: service worker/witness is not
in the graph`. Red on the pre-fix CompositionRoots, green on this branch
(independent review, codex-cli1204-exclusion-review).

Patch authored by the Codex independent reviewer; adopted unchanged after
reading it, with `go test ./cmd/run/` and golangci-lint clean.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: antoinetoussaint-byte

cmd/run/workspace_environment_exclusions_test.go

@@ -0,0 +1,98 @@
+package run
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/codefly-dev/cli/pkg/environments"
+	"github.com/codefly-dev/cli/pkg/orchestration"
+	"github.com/codefly-dev/core/architecture"
+	"github.com/codefly-dev/core/resources"
+	"github.com/stretchr/testify/require"
+)
+
+// A composition root must survive the same selected-environment exclusions
+// that orchestration applies when it builds the dependency graph.
+func TestCompositionRootsRespectSelectedEnvironmentExclusions(t *testing.T) {
+	oldEnv, oldProfile, oldExcluded := environmentName, profile, excludeDependencies
+	t.Cleanup(func() { environmentName, profile, excludeDependencies = oldEnv, oldProfile, oldExcluded })
+	profile = "small"
+	excludeDependencies = []string{"host/admin", "worker/cli-only"}
+	root := t.TempDir()
+	workspaceYAML := `name: roots
+layout: modules
+modules:
+  - name: host
+  - name: worker
+run-profiles:
+  small:
+    exclude-dependencies: [worker/profile-only]
+environments:
+  - name: local
+    host:
+      coordinate: example/local/cell
+      component: host
+      domain: example
+      audience: host
+      trust_domain: cluster.example
+      delivery: host/web/rest
+    ingress:
+      - name: web
+        service: web
+        endpoint: rest
+        hosts: [web.example.test]
+      - name: admin
+        service: admin
+        endpoint: rest
+        hosts: [admin.example.test]
+    exclude-services:
+      - service: worker/witness
+  - name: staging
+`
+	for module, names := range map[string][]string{
+		"host":   {"web", "admin"},
+		"worker": {"api", "witness", "cli-only", "profile-only"},
+	} {
+		dir := filepath.Join(root, "modules", module)
+		require.NoError(t, os.MkdirAll(dir, 0o755))
+		doc := "kind: module\nname: " + module + "\nservices:\n"
+		for _, name := range names {
+			doc += "  - name: " + name + "\n"
+			serviceDir := filepath.Join(dir, "services", name)
+			require.NoError(t, os.MkdirAll(serviceDir, 0o755))
+			service := fmt.Sprintf("kind: service\nname: %s\nmodule: %s\nversion: 0.0.0\nagent:\n  kind: runtime::service\n  name: go\n  version: 0.0.1\n  publisher: codefly.ai\nendpoints:\n  - name: rest\n    api: rest\n    visibility: public\n    exposure: none\n", name, module)
+			require.NoError(t, os.WriteFile(filepath.Join(serviceDir, "service.codefly.yaml"), []byte(service), 0o600))
+		}
+		require.NoError(t, os.WriteFile(filepath.Join(dir, "module.codefly.yaml"), []byte(doc), 0o600))
+	}
+	require.NoError(t, os.WriteFile(filepath.Join(root, "workspace.codefly.yaml"), []byte(workspaceYAML), 0o600))
+	workspace, err := resources.LoadWorkspaceFromDir(t.Context(), root)
+	require.NoError(t, err)
+	for _, tc := range []struct {
+		env  string
+		want []string
+	}{
+		{"local", []string{"host/web", "worker/api"}},
+		{"staging", []string{"host/web", "worker/api", "worker/witness"}},
+	} {
+		t.Run(tc.env, func(t *testing.T) {
+			environmentName = tc.env
+			roots, err := CompositionRoots(t.Context(), workspace)
+			require.NoError(t, err)
+			env, err := orchestration.SelectEnvironment(workspace, tc.env)
+			require.NoError(t, err)
+			require.NoError(t, environments.ValidateEnvironmentExclusions(t.Context(), workspace, env))
+			graph, err := architecture.NewServiceDependencies(t.Context(), workspace, architecture.ExcludeServices(env.ExcludedServiceUniques()...))
+			require.NoError(t, err)
+			for _, root := range roots {
+				_, err = graph.OrderTo(t.Context(), root)
+				if err != nil {
+					t.Errorf("selected composition root %s cannot be ordered: %v", root, err)
+				}
+			}
+			require.Equal(t, tc.want, roots)
+		})
+	}
+}

docs/commands.md

@@ -118,7 +118,10 @@ service` that do not name one root service — `--naming-scope`,
 `--temporary-ports`, `--output-env`, `--runtime-context`, `--set` among them,
 never `--stand-alone` or `--exclude-root`; `--exclude-dependency` and
 `--exclude-workspace-configuration` leave a service or a configuration group
-out. The deterministic port hash folds every endpoint into a few thousand
+out. The selected environment's `exclude-services` also removes services from
+the composition roots; a module withdrawn whole contributes no root, including
+its service-entry. CLI and run-profile exclusions still apply on top.
+The deterministic port hash folds every endpoint into a few thousand
 buckets, so a `--naming-scope` can hash two endpoints to one port and abort
 the run; `--temporary-ports` sidesteps the hash, under the ordering its
 allocation needs — a workspace configuration reference to a service that has