Merge pull request #83 from LAA-Software-Engineering/feat/cli-inspect-command

feat(cli): agentctl inspect (effective normalized resource)

Author: leo-aa88

internal/cli/diff.go

@@ -37,44 +37,6 @@ Exit codes (§11.2):
 	}
 }
 
-func parseDiffResourceRef(s string) (spec.ResourceID, error) {
-	s = strings.TrimSpace(s)
-	if s == "" {
-		return spec.ResourceID{}, fmt.Errorf("empty Kind/name")
-	}
-	i := strings.IndexByte(s, '/')
-	if i <= 0 || i == len(s)-1 {
-		return spec.ResourceID{}, fmt.Errorf("resource must be Kind/name (e.g. Policy/default), got %q", s)
-	}
-	kindIn, name := s[:i], s[i+1:]
-	kind, err := normalizeKindName(kindIn)
-	if err != nil {
-		return spec.ResourceID{}, err
-	}
-	if strings.TrimSpace(name) == "" {
-		return spec.ResourceID{}, fmt.Errorf("resource name is empty in %q", s)
-	}
-	return spec.ResourceID{Kind: kind, Name: name}, nil
-}
-
-func normalizeKindName(s string) (string, error) {
-	s = strings.TrimSpace(s)
-	known := []string{
-		spec.KindProject,
-		spec.KindAgent,
-		spec.KindTool,
-		spec.KindWorkflow,
-		spec.KindPolicy,
-		spec.KindEnvironment,
-	}
-	for _, k := range known {
-		if strings.EqualFold(s, k) {
-			return k, nil
-		}
-	}
-	return "", fmt.Errorf("unknown resource kind %q (want Project, Agent, Tool, Workflow, Policy, or Environment)", s)
-}
-
 func desiredContainsID(ids []spec.ResourceID, id spec.ResourceID) bool {
 	for _, x := range ids {
 		if x.Kind == id.Kind && x.Name == id.Name {
@@ -171,7 +133,7 @@ func runDiff(cmd *cobra.Command, args []string) error {
 	appliedByKey := appliedIndex(appliedList)
 
 	if len(args) == 1 {
-		id, err := parseDiffResourceRef(args[0])
+		id, err := ParseResourceRef(args[0])
 		if err != nil {
 			return NewExitError(ExitValidationError, fmt.Errorf("diff: %w", err))
 		}

internal/cli/doc.go

@@ -6,6 +6,9 @@
 // The validate command (section 10.2) loads the project, applies defaults and optional environment
 // overlays, then runs [spec.ValidateProjectGraph].
 //
+// The inspect command (section 10.2) uses the same preparation pipeline and prints one effective
+// normalized resource envelope (Kind/name) as JSON, YAML, or indented JSON for table output.
+//
 // The plan command compares that prepared graph to the SQLite deployment store (default
 // .agentic/state.db, or project.spec.state.dsn / --state) and prints a diff plus risk delta
 // via [plan.ComputePlan] and [plan.FormatPlan].

internal/cli/inspect.go

@@ -0,0 +1,150 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/spec"
+	"github.com/spf13/cobra"
+)
+
+func newInspectCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "inspect Kind/name",
+		Short: "Print the effective normalized resource (after defaults and env overlay)",
+		Long: `Load the project the same way as validate, plan, and run (defaults, optional -e / --env
+overlay via Environment resources, then validation), then print one resource.
+
+Argument must be Kind/name (e.g. Agent/reviewer, workflow/demo). Kind is matched case-insensitively.
+
+Output is the full resource envelope: apiVersion, kind, metadata, and spec (design doc §6.1).
+
+Exit code 2 for validation failure, unknown resource, or bad Kind/name (§11.2).`,
+		Example: `  agentctl inspect Workflow/pr-review
+  agentctl inspect Agent/reviewer -o yaml
+  agentctl inspect Policy/default -e staging -o json`,
+		SilenceUsage: true,
+		RunE:         runInspect,
+	}
+}
+
+func environmentLabel(g *Global) string {
+	if g == nil || strings.TrimSpace(g.Env) == "" {
+		return "(none)"
+	}
+	return strings.TrimSpace(g.Env)
+}
+
+// lookupEffectiveResource returns the in-memory resource after normalization and environment merge.
+func lookupEffectiveResource(g *spec.ProjectGraph, id spec.ResourceID) (any, error) {
+	if g == nil {
+		return nil, fmt.Errorf("inspect: nil project graph")
+	}
+	switch id.Kind {
+	case spec.KindProject:
+		want := strings.TrimSpace(id.Name)
+		got := strings.TrimSpace(g.Meta.Name)
+		if want == "" || got == "" || want != got {
+			return nil, fmt.Errorf("inspect: unknown resource %s (project metadata.name is %q)", id.String(), got)
+		}
+		return &spec.ProjectResource{
+			APIVersion: spec.APIVersionV0,
+			Kind:       spec.KindProject,
+			Metadata:   g.Meta,
+			Spec:       g.Spec,
+		}, nil
+	case spec.KindAgent:
+		a := g.Agents[id.Name]
+		if a == nil {
+			return nil, fmt.Errorf("inspect: unknown resource %s", id.String())
+		}
+		return a, nil
+	case spec.KindTool:
+		t := g.Tools[id.Name]
+		if t == nil {
+			return nil, fmt.Errorf("inspect: unknown resource %s", id.String())
+		}
+		return t, nil
+	case spec.KindWorkflow:
+		w := g.Workflows[id.Name]
+		if w == nil {
+			return nil, fmt.Errorf("inspect: unknown resource %s", id.String())
+		}
+		return w, nil
+	case spec.KindPolicy:
+		p := g.Policies[id.Name]
+		if p == nil {
+			return nil, fmt.Errorf("inspect: unknown resource %s", id.String())
+		}
+		return p, nil
+	case spec.KindEnvironment:
+		e := g.Environments[id.Name]
+		if e == nil {
+			return nil, fmt.Errorf("inspect: unknown resource %s", id.String())
+		}
+		return e, nil
+	default:
+		return nil, fmt.Errorf("inspect: unsupported kind %q", id.Kind)
+	}
+}
+
+func runInspect(cmd *cobra.Command, args []string) error {
+	if len(args) != 1 {
+		return NewExitError(ExitValidationError, fmt.Errorf("inspect: requires exactly one Kind/name argument"))
+	}
+	id, err := ParseResourceRef(args[0])
+	if err != nil {
+		return NewExitError(ExitValidationError, fmt.Errorf("inspect: %w", err))
+	}
+	gl := Globals()
+	graph, _, err := prepareProjectGraph(gl.ProjectRoot, gl)
+	if err != nil {
+		return NewExitError(ExitValidationError, err)
+	}
+	res, err := lookupEffectiveResource(graph, id)
+	if err != nil {
+		return NewExitError(ExitValidationError, err)
+	}
+	return writeInspectOutput(cmd, id.String(), res, gl)
+}
+
+func writeInspectOutput(cmd *cobra.Command, target string, resource any, g *Global) error {
+	out := cmd.OutOrStdout()
+	env := environmentLabel(g)
+	switch g.Output {
+	case render.FormatJSON:
+		raw, err := json.Marshal(resource)
+		if err != nil {
+			return err
+		}
+		var resObj map[string]any
+		if err := json.Unmarshal(raw, &resObj); err != nil {
+			return err
+		}
+		return render.WriteJSON(out, map[string]any{
+			"environment": env,
+			"resource":    resObj,
+		})
+	case render.FormatYAML:
+		return render.WriteYAML(out, map[string]any{
+			"environment": env,
+			"resource":    resource,
+		})
+	default:
+		if _, err := fmt.Fprintf(out, "Resource: %s\nEnvironment: %s\n\n", target, env); err != nil {
+			return err
+		}
+		b, err := json.MarshalIndent(resource, "", "  ")
+		if err != nil {
+			return err
+		}
+		_, err = out.Write(b)
+		if err != nil {
+			return err
+		}
+		_, err = out.Write([]byte("\n"))
+		return err
+	}
+}