feat(cli): root global flags, render helpers, exit codes (#24)

- Root persistent flags: -e/--env, -o/--output (table|json|yaml), --project,
  --state, --no-color (design doc 11.1)
- render: format constants, WriteJSON with sorted map keys, WriteTable,
  WriteYAML
- cli: ExitError + ExitCodeOf mapping (11.2), Main() for app wiring
- version respects -o json|yaml|table; JSON uses stable struct keys
- App.Run returns exit code; main uses RunAndExit
- Tests: help lists globals, JSON version shape, invalid output -> code 2

Closes #24

Made-with: Cursor

Author: leo-aa88

cmd/agentctl/main.go

@@ -1,15 +1,7 @@
 package main
 
-import (
-	"fmt"
-	"os"
-
-	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/app"
-)
+import "github.com/LAA-Software-Engineering/agentic-control-plane/internal/app"
 
 func main() {
-	if err := app.New().Run(); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
+	app.New().RunAndExit()
 }

internal/app/app.go

@@ -1,5 +1,7 @@
 package app
 
+import "os"
+
 // App is the composition root for agentctl. Subsystems (stores, planner,
 // runtime) will be assembled here in later phases.
 type App struct{}
@@ -9,7 +11,12 @@ func New() *App {
 	return &App{}
 }
 
-// Run starts the CLI and blocks until the root command finishes.
-func (a *App) Run() error {
+// Run starts the CLI and returns a process exit code (design doc section 11.2).
+func (a *App) Run() int {
 	return runCLI()
 }
+
+// RunAndExit runs the CLI and terminates the process (convenience for main).
+func (a *App) RunAndExit() {
+	os.Exit(a.Run())
+}

internal/app/wiring.go

@@ -2,6 +2,6 @@ package app
 
 import "github.com/LAA-Software-Engineering/agentic-control-plane/internal/cli"
 
-func runCLI() error {
-	return cli.Execute()
+func runCLI() int {
+	return cli.Main()
 }

internal/cli/config.go

@@ -0,0 +1,45 @@
+package cli
+
+import (
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
+	"github.com/spf13/cobra"
+)
+
+// Global holds root persistent flags shared by all subcommands (design doc section 11.1).
+type Global struct {
+	Env         string
+	Output      string
+	ProjectRoot string
+	StatePath   string
+	NoColor     bool
+}
+
+var global Global
+
+// Globals returns the process-wide CLI global options after flags are parsed.
+func Globals() *Global {
+	return &global
+}
+
+// BindPersistentFlags registers -e/--env, -o/--output, --project, --state, --no-color on cmd.
+func BindPersistentFlags(cmd *cobra.Command) {
+	f := cmd.PersistentFlags()
+	f.StringVarP(&global.Env, "env", "e", "", "environment name (target context)")
+	f.StringVarP(&global.Output, "output", "o", render.FormatTable, "output format: table, json, or yaml")
+	f.StringVar(&global.ProjectRoot, "project", ".", "project root directory (contains project.yaml)")
+	f.StringVar(&global.StatePath, "state", "", "path to SQLite state database (optional override)")
+	f.BoolVar(&global.NoColor, "no-color", false, "disable color output")
+}
+
+// ValidateGlobals checks flag values after parsing.
+func ValidateGlobals() error {
+	if !render.ValidFormat(global.Output) {
+		return NewExitErrorf(ExitValidationError, "invalid --output %q (want table, json, or yaml)", global.Output)
+	}
+	return nil
+}
+
+// ResetGlobalsForTest resets global flags (for tests only).
+func ResetGlobalsForTest() {
+	global = Global{}
+}

internal/cli/doc.go

@@ -0,0 +1,3 @@
+// Package cli defines agentctl commands, global flags (design doc section 11.1), and exit-code
+// mapping (section 11.2). Output formatting lives in [render].
+package cli

internal/cli/exit.go

@@ -0,0 +1,62 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+)
+
+// Exit codes (design doc section 11.2).
+const (
+	ExitSuccess           = 0
+	ExitGenericFailure    = 1
+	ExitValidationError   = 2
+	ExitPlanApplyConflict = 3
+	ExitExecutionError    = 4
+	ExitPolicyDenied      = 5
+)
+
+// ExitError carries a non-zero exit status for [ExitCodeOf].
+type ExitError struct {
+	Code int
+	Err  error
+}
+
+func (e *ExitError) Error() string {
+	if e == nil || e.Err == nil {
+		return "exit error"
+	}
+	return e.Err.Error()
+}
+
+// Unwrap returns the underlying error.
+func (e *ExitError) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.Err
+}
+
+// ExitCodeOf maps errors to process exit codes. Unknown errors use [ExitGenericFailure].
+func ExitCodeOf(err error) int {
+	if err == nil {
+		return ExitSuccess
+	}
+	var ee *ExitError
+	if errors.As(err, &ee) && ee != nil && ee.Code >= 0 && ee.Code <= 255 {
+		return ee.Code
+	}
+	return ExitGenericFailure
+}
+
+// NewExitError wraps err with a specific exit code.
+func NewExitError(code int, err error) error {
+	if err == nil {
+		return nil
+	}
+	return &ExitError{Code: code, Err: err}
+}
+
+// NewExitErrorf is like [fmt.Errorf] with an exit code.
+func NewExitErrorf(code int, format string, a ...any) error {
+	return &ExitError{Code: code, Err: fmt.Errorf(format, a...)}
+}

internal/cli/root.go

@@ -2,7 +2,9 @@ package cli
 
 import (
 	"fmt"
+	"os"
 
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
 	"github.com/spf13/cobra"
 )
 
@@ -11,18 +13,25 @@ var Version = "0.0.0-dev"
 
 // Execute runs the root command.
 func Execute() error {
-	return newRootCmd().Execute()
+	return NewRootCmd().Execute()
 }
 
-func newRootCmd() *cobra.Command {
+// NewRootCmd builds the agentctl command tree (exposed for tests).
+func NewRootCmd() *cobra.Command {
+	global = Global{}
 	root := &cobra.Command{
-		Use:   "agentctl",
-		Short: "Declarative control plane for agent systems",
-		Long:  "agentctl validates, plans, applies, and runs declarative agent systems defined as YAML.",
+		Use:           "agentctl",
+		Short:         "Declarative control plane for agent systems",
+		Long:          "agentctl validates, plans, applies, and runs declarative agent systems defined as YAML.",
+		SilenceErrors: true,
 		Run: func(cmd *cobra.Command, args []string) {
 			_ = cmd.Help()
 		},
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			return ValidateGlobals()
+		},
 	}
+	BindPersistentFlags(root)
 	root.AddCommand(newVersionCmd())
 	return root
 }
@@ -31,8 +40,36 @@ func newVersionCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "version",
 		Short: "Print version information",
-		Run: func(cmd *cobra.Command, args []string) {
-			fmt.Println(Version)
+		RunE: func(cmd *cobra.Command, args []string) error {
+			g := Globals()
+			out := cmd.OutOrStdout()
+			switch g.Output {
+			case render.FormatJSON:
+				payload := struct {
+					Version string `json:"version"`
+				}{Version: Version}
+				if err := render.WriteJSON(out, payload); err != nil {
+					return err
+				}
+			case render.FormatYAML:
+				if err := render.WriteYAML(out, map[string]string{"version": Version}); err != nil {
+					return err
+				}
+			default:
+				if _, err := render.Fprintf(out, "%s\n", Version); err != nil {
+					return err
+				}
+			}
+			return nil
 		},
 	}
 }
+
+// Main is an optional entrypoint that maps errors to exit codes and writes diagnostics to stderr.
+func Main() int {
+	if err := Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		return ExitCodeOf(err)
+	}
+	return ExitSuccess
+}

internal/cli/root_test.go

@@ -0,0 +1,67 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestRootHelp_listsGlobalFlags(t *testing.T) {
+	ResetGlobalsForTest()
+	cmd := NewRootCmd()
+	var buf bytes.Buffer
+	cmd.SetOut(&buf)
+	cmd.SetErr(&buf)
+	cmd.SetArgs([]string{"--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	out := buf.String()
+	for _, flag := range []string{"--env", "-e", "--output", "-o", "--project", "--state", "--no-color"} {
+		if !strings.Contains(out, flag) {
+			t.Fatalf("help output missing %q\n%s", flag, out)
+		}
+	}
+}
+
+func TestVersion_JSON_stableKeys(t *testing.T) {
+	ResetGlobalsForTest()
+	cmd := NewRootCmd()
+	var buf bytes.Buffer
+	cmd.SetOut(&buf)
+	cmd.SetArgs([]string{"-o", "json", "version"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	raw := bytes.TrimSpace(buf.Bytes())
+	if !json.Valid(raw) {
+		t.Fatalf("invalid json: %s", raw)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if len(m) != 1 {
+		t.Fatalf("want single top-level key, got %v", m)
+	}
+	if _, ok := m["version"]; !ok {
+		t.Fatalf("missing version key: %v", m)
+	}
+}
+
+func TestInvalidOutput_exitCode2(t *testing.T) {
+	ResetGlobalsForTest()
+	cmd := NewRootCmd()
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"-o", "nope", "version"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if ExitCodeOf(err) != ExitValidationError {
+		t.Fatalf("code=%d err=%v", ExitCodeOf(err), err)
+	}
+}

internal/render/doc.go

@@ -1,2 +1,4 @@
-// Package render formats output as YAML, JSON, or tables.
+// Package render formats CLI output as tables, JSON, or YAML (design doc sections 5.1, 11.1, 18).
+//
+// JSON helpers sort object keys so machine-oriented output is stable (issue #24).
 package render

internal/render/format.go

@@ -0,0 +1,18 @@
+package render
+
+// Output format names (design doc section 11.1; issue #24 MVP uses table|json, yaml included for parity).
+const (
+	FormatTable = "table"
+	FormatJSON  = "json"
+	FormatYAML  = "yaml"
+)
+
+// ValidFormat reports whether s is a supported --output value.
+func ValidFormat(s string) bool {
+	switch s {
+	case FormatTable, FormatJSON, FormatYAML:
+		return true
+	default:
+		return false
+	}
+}