fix(cli): move top-level command routing into folders

AGENTS.md

@@ -64,6 +64,7 @@ Do not hand-wave command behavior from memory when the docs are meant to reflect
 - **Scope:** Change only what the task needs; do not “clean up” unrelated files. Match naming and patterns in the nearest similar code.
 - **Tests:** Add or adjust tests in the same package when behavior changes. For CLI output, expect golden file updates.
 - **Branch names:** Use `component/feature_name` for task branches. Pick the component from the same scope list used for commit messages, and write the feature name in lowercase snake_case, for example `doc/commit_message_guidance`, `cli/registry_status`, or `operator/ingress_defaults`.
+- **Agent branch / PR flow:** Agents must create and push changes on a new branch, and open or update a PR from that branch. Agents must not push directly to `main`.
 - **Commit messages:** Use `fix(<component>): ...` for bug fixes and `feat(<component>): ...` for user-facing behavior. Use `doc: ...` for README / AGENTS / docs-only edits, and `website: ...` for `website/` changes. Prefer components that match repo areas, such as `cli`, `operator`, `api`, `crd`, `access`, `policy`, `k8sclient`, `manifest`, `metadata`, `sentinel`, `registry`, `ingress`, `services-api`, `ui`, `ingest`, `processor`, `mcp-proxy`, `traefik-plugin`, `config`, `examples`, `test`, or `ci`. Keep the subject concise and imperative; add a body only when the reason, risk, or verification needs context.
 - **Docs you were not asked to edit:** Avoid adding new top-level docs unless the task needs them; this file, `README`, and existing doc trees are the defaults for agents.
 - **Secrets and prod:** This repo is **alpha**; do not hardcode real credentials. Use the existing secret and env patterns documented below.

internal/cli/access.go

@@ -31,145 +31,9 @@ func DefaultAccessManager(logger *zap.Logger) *AccessManager {
 	return NewAccessManager(kubectlClient, logger)
 }
 
-func NewAccessCmd(logger *zap.Logger) *cobra.Command {
-	mgr := DefaultAccessManager(logger)
-	return NewAccessCmdWithManager(mgr)
-}
-
-func NewAccessCmdWithManager(mgr *AccessManager) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "access",
-		Short: "Manage grants and agent sessions",
-		Long: `Commands for managing MCPAccessGrant and MCPAgentSession resources that feed the gateway policy layer.
-
-With mcp-runtime auth login, commands use the platform API by default. Use --use-kube
-to target the cluster with kubectl and a kubeconfig (cluster admin path).`,
-	}
-
-	cmd.PersistentFlags().BoolVar(&mgr.useKube, "use-kube", false, "Use kubectl and local kubeconfig instead of the platform API for supported commands")
-
-	cmd.AddCommand(mgr.newAccessGrantCmd())
-	cmd.AddCommand(mgr.newAccessSessionCmd())
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessGrantCmd() *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "grant",
-		Short: "Manage MCPAccessGrant resources",
-	}
-
-	cmd.AddCommand(m.newAccessListCmd(accessGrantResource, "grants"))
-	cmd.AddCommand(m.newAccessGetCmd(accessGrantResource, "grant"))
-	cmd.AddCommand(m.newAccessApplyCmd(accessGrantResource, "grant"))
-	cmd.AddCommand(m.newAccessDeleteCmd(accessGrantResource, "grant"))
-	cmd.AddCommand(m.newAccessToggleCmd(accessGrantResource, "disable", "Disable a grant", true))
-	cmd.AddCommand(m.newAccessToggleCmd(accessGrantResource, "enable", "Enable a grant", false))
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessSessionCmd() *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "session",
-		Short: "Manage MCPAgentSession resources",
-	}
-
-	cmd.AddCommand(m.newAccessListCmd(accessSessionResource, "sessions"))
-	cmd.AddCommand(m.newAccessGetCmd(accessSessionResource, "session"))
-	cmd.AddCommand(m.newAccessApplyCmd(accessSessionResource, "session"))
-	cmd.AddCommand(m.newAccessDeleteCmd(accessSessionResource, "session"))
-	cmd.AddCommand(m.newAccessToggleCmd(accessSessionResource, "revoke", "Revoke an agent session", true))
-	cmd.AddCommand(m.newAccessToggleCmd(accessSessionResource, "unrevoke", "Clear the revoked flag on an agent session", false))
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessListCmd(resource, label string) *cobra.Command {
-	var namespace string
-	var allNamespaces bool
-
-	cmd := &cobra.Command{
-		Use:   "list",
-		Short: fmt.Sprintf("List access %s", label),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return m.ListAccessResources(resource, namespace, allNamespaces)
-		},
-	}
-
-	cmd.Flags().StringVar(&namespace, "namespace", "", "Namespace to inspect")
-	cmd.Flags().BoolVar(&allNamespaces, "all-namespaces", true, "List resources across all namespaces when no namespace is specified")
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessGetCmd(resource, label string) *cobra.Command {
-	var namespace string
-
-	cmd := &cobra.Command{
-		Use:   "get [name]",
-		Short: fmt.Sprintf("Get an access %s", label),
-		Args:  cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return m.GetAccessResource(resource, args[0], namespace)
-		},
-	}
-
-	cmd.Flags().StringVar(&namespace, "namespace", NamespaceMCPServers, "Namespace")
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessApplyCmd(resource, label string) *cobra.Command {
-	var file string
-
-	cmd := &cobra.Command{
-		Use:   "apply",
-		Short: fmt.Sprintf("Apply a %s manifest", label),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return m.ApplyAccessResource(file)
-		},
-	}
-
-	cmd.Flags().StringVar(&file, "file", "", "Manifest file to apply")
-	_ = cmd.MarkFlagRequired("file")
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessDeleteCmd(resource, label string) *cobra.Command {
-	var namespace string
-
-	cmd := &cobra.Command{
-		Use:   "delete [name]",
-		Short: fmt.Sprintf("Delete an access %s", label),
-		Args:  cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return m.DeleteAccessResource(resource, args[0], namespace)
-		},
-	}
-
-	cmd.Flags().StringVar(&namespace, "namespace", NamespaceMCPServers, "Namespace")
-
-	return cmd
-}
-
-func (m *AccessManager) newAccessToggleCmd(resource, use, short string, value bool) *cobra.Command {
-	var namespace string
-
-	cmd := &cobra.Command{
-		Use:   use + " [name]",
-		Short: short,
-		Args:  cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return m.ToggleAccessResource(resource, args[0], namespace, value)
-		},
-	}
-
-	cmd.Flags().StringVar(&namespace, "namespace", NamespaceMCPServers, "Namespace")
-
-	return cmd
+// BindUseKubeFlag wires the shared --use-kube flag onto the command.
+func (m *AccessManager) BindUseKubeFlag(cmd *cobra.Command) {
+	cmd.PersistentFlags().BoolVar(&m.useKube, "use-kube", false, "Use kubectl and local kubeconfig instead of the platform API for supported commands")
 }
 
 func (m *AccessManager) accessListQueryNamespace(namespace string, allNamespaces bool) string {

internal/cli/access/access.go

@@ -3,12 +3,132 @@ package access
 
 import (
 	"github.com/spf13/cobra"
-	"go.uber.org/zap"
 
 	"mcp-runtime/internal/cli"
 )
 
+const (
+	grantResource   = "mcpaccessgrant"
+	sessionResource = "mcpagentsession"
+)
+
 // New returns the access command.
-func New(logger *zap.Logger) *cobra.Command {
-	return cli.NewAccessCmd(logger)
+func New(runtime *cli.Runtime) *cobra.Command {
+	return NewWithManager(runtime.AccessManager())
+}
+
+// NewWithManager returns the access command using the provided manager.
+func NewWithManager(mgr *cli.AccessManager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "access",
+		Short: "Manage grants and agent sessions",
+		Long: `Commands for managing MCPAccessGrant and MCPAgentSession resources that feed the gateway policy layer.
+
+With mcp-runtime auth login, commands use the platform API by default. Use --use-kube
+to target the cluster with kubectl and a kubeconfig (cluster admin path).`,
+	}
+
+	mgr.BindUseKubeFlag(cmd)
+
+	cmd.AddCommand(newGrantCmd(mgr), newSessionCmd(mgr))
+	return cmd
+}
+
+func newGrantCmd(mgr *cli.AccessManager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "grant",
+		Short: "Manage MCPAccessGrant resources",
+	}
+	cmd.AddCommand(newListCmd(mgr, grantResource, "grants"))
+	cmd.AddCommand(newGetCmd(mgr, grantResource, "grant"))
+	cmd.AddCommand(newApplyCmd(mgr, "grant"))
+	cmd.AddCommand(newDeleteCmd(mgr, grantResource, "grant"))
+	cmd.AddCommand(newToggleCmd(mgr, grantResource, "disable", "Disable a grant", true))
+	cmd.AddCommand(newToggleCmd(mgr, grantResource, "enable", "Enable a grant", false))
+	return cmd
+}
+
+func newSessionCmd(mgr *cli.AccessManager) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "session",
+		Short: "Manage MCPAgentSession resources",
+	}
+	cmd.AddCommand(newListCmd(mgr, sessionResource, "sessions"))
+	cmd.AddCommand(newGetCmd(mgr, sessionResource, "session"))
+	cmd.AddCommand(newApplyCmd(mgr, "session"))
+	cmd.AddCommand(newDeleteCmd(mgr, sessionResource, "session"))
+	cmd.AddCommand(newToggleCmd(mgr, sessionResource, "revoke", "Revoke an agent session", true))
+	cmd.AddCommand(newToggleCmd(mgr, sessionResource, "unrevoke", "Clear the revoked flag on an agent session", false))
+	return cmd
+}
+
+func newListCmd(mgr *cli.AccessManager, resource, label string) *cobra.Command {
+	var namespace string
+	var allNamespaces bool
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List access " + label,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return mgr.ListAccessResources(resource, namespace, allNamespaces)
+		},
+	}
+	cmd.Flags().StringVar(&namespace, "namespace", "", "Namespace to inspect")
+	cmd.Flags().BoolVar(&allNamespaces, "all-namespaces", true, "List resources across all namespaces when no namespace is specified")
+	return cmd
+}
+
+func newGetCmd(mgr *cli.AccessManager, resource, label string) *cobra.Command {
+	var namespace string
+	cmd := &cobra.Command{
+		Use:   "get [name]",
+		Short: "Get an access " + label,
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return mgr.GetAccessResource(resource, args[0], namespace)
+		},
+	}
+	cmd.Flags().StringVar(&namespace, "namespace", cli.NamespaceMCPServers, "Namespace")
+	return cmd
+}
+
+func newApplyCmd(mgr *cli.AccessManager, label string) *cobra.Command {
+	var file string
+	cmd := &cobra.Command{
+		Use:   "apply",
+		Short: "Apply a " + label + " manifest",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return mgr.ApplyAccessResource(file)
+		},
+	}
+	cmd.Flags().StringVar(&file, "file", "", "Manifest file to apply")
+	_ = cmd.MarkFlagRequired("file")
+	return cmd
+}
+
+func newDeleteCmd(mgr *cli.AccessManager, resource, label string) *cobra.Command {
+	var namespace string
+	cmd := &cobra.Command{
+		Use:   "delete [name]",
+		Short: "Delete an access " + label,
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return mgr.DeleteAccessResource(resource, args[0], namespace)
+		},
+	}
+	cmd.Flags().StringVar(&namespace, "namespace", cli.NamespaceMCPServers, "Namespace")
+	return cmd
+}
+
+func newToggleCmd(mgr *cli.AccessManager, resource, use, short string, value bool) *cobra.Command {
+	var namespace string
+	cmd := &cobra.Command{
+		Use:   use + " [name]",
+		Short: short,
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return mgr.ToggleAccessResource(resource, args[0], namespace, value)
+		},
+	}
+	cmd.Flags().StringVar(&namespace, "namespace", cli.NamespaceMCPServers, "Namespace")
+	return cmd
 }

internal/cli/access_test.go

@@ -8,28 +8,6 @@ import (
 	"go.uber.org/zap"
 )
 
-func TestNewAccessCmd(t *testing.T) {
-	cmd := NewAccessCmd(zap.NewNop())
-	if cmd == nil {
-		t.Fatal("NewAccessCmd should not return nil")
-	}
-	if cmd.Use != "access" {
-		t.Fatalf("expected Use='access', got %q", cmd.Use)
-	}
-
-	expected := map[string]bool{"grant": false, "session": false}
-	for _, sub := range cmd.Commands() {
-		if _, ok := expected[sub.Use]; ok {
-			expected[sub.Use] = true
-		}
-	}
-	for name, found := range expected {
-		if !found {
-			t.Fatalf("expected subcommand %q not found", name)
-		}
-	}
-}
-
 func TestAccessManager_ListAccessResources(t *testing.T) {
 	mock := &MockExecutor{}
 	kubectl := &KubectlClient{exec: mock, validators: nil}