forge: Add natural language command classification

Route unrecognized CLI input through Claude to classify intent and
map it to the appropriate forge subcommand. Includes recursion guard,
dynamic context injection (plan files + run IDs), and comprehensive
tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shahar-caura

cmd/forge/cmd_nl.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+
+	"github.com/shahar-caura/forge/internal/intent"
+	"github.com/spf13/cobra"
+)
+
+func runNaturalLanguage(cmd *cobra.Command, logger *slog.Logger, args []string) error {
+	if len(args) == 0 {
+		return cmd.Help()
+	}
+
+	// Recursion guard: prevent classify → execute → classify loops.
+	if os.Getenv("FORGE_NL_CLASSIFIED") == "1" {
+		return fmt.Errorf("unknown command %q", args[0])
+	}
+
+	query := strings.Join(args, " ")
+	logger.Info("classifying natural language input", "query", query)
+
+	result, err := intent.Classify(cmd.Context(), query)
+	if err != nil {
+		if errors.Is(err, intent.ErrNoClaude) {
+			return fmt.Errorf("unknown command %q (install claude CLI to enable natural language mode)", args[0])
+		}
+		return fmt.Errorf("could not interpret %q as a forge command: %w", query, err)
+	}
+
+	// Validate that the resolved subcommand actually exists.
+	sub := result.Argv[0]
+	found := false
+	for _, c := range cmd.Root().Commands() {
+		if c.Name() == sub {
+			found = true
+			break
+		}
+	}
+	if !found {
+		return fmt.Errorf("could not interpret %q as a forge command (resolved to unknown subcommand %q)", query, sub)
+	}
+
+	fmt.Fprintf(os.Stderr, "=> forge %s\n", strings.Join(result.Argv, " "))
+
+	os.Setenv("FORGE_NL_CLASSIFIED", "1")
+	defer os.Unsetenv("FORGE_NL_CLASSIFIED")
+
+	cmd.Root().SetArgs(result.Argv)
+	return cmd.Root().Execute()
+}

internal/intent/classify.go

@@ -0,0 +1,90 @@
+package intent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os/exec"
+	"strings"
+	"time"
+)
+
+// CommandContext is the function used to create exec.Cmd. Override in tests.
+var CommandContext = exec.CommandContext
+
+// Classify interprets a natural language query as a forge command.
+func Classify(ctx context.Context, query string) (*Result, error) {
+	if _, err := exec.LookPath("claude"); err != nil {
+		return nil, ErrNoClaude
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+
+	dc := GatherContext()
+	prompt := BuildPrompt(query, dc)
+
+	cmd := CommandContext(ctx, "claude", "-p", prompt, "--output-format", "json", "--max-tokens", "256")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		if ctx.Err() == context.DeadlineExceeded {
+			return nil, fmt.Errorf("%w: timed out after 30s", ErrClassificationFailed)
+		}
+		return nil, fmt.Errorf("%w: %s", ErrClassificationFailed, string(out))
+	}
+
+	return parseResponse(string(out))
+}
+
+// parseResponse extracts a Result from the claude CLI JSON output.
+// Handles the JSON envelope ({"result":"..."}) and strips accidental code fences.
+func parseResponse(raw string) (*Result, error) {
+	// First, try to unwrap claude's JSON envelope.
+	text := extractResultField(raw)
+
+	// Strip accidental code fences (```json ... ```).
+	text = stripCodeFences(text)
+	text = strings.TrimSpace(text)
+
+	var r Result
+	if err := json.Unmarshal([]byte(text), &r); err != nil {
+		return nil, fmt.Errorf("%w: invalid JSON: %s", ErrClassificationFailed, err)
+	}
+
+	if len(r.Argv) == 0 {
+		return nil, fmt.Errorf("%w: empty argv", ErrClassificationFailed)
+	}
+
+	return &r, nil
+}
+
+// extractResultField unwraps claude's {"result":"..."} envelope.
+// Falls back to the raw string if parsing fails.
+func extractResultField(raw string) string {
+	var envelope struct {
+		Result string `json:"result"`
+	}
+	if err := json.Unmarshal([]byte(raw), &envelope); err != nil {
+		return raw
+	}
+	if envelope.Result == "" {
+		return raw
+	}
+	return envelope.Result
+}
+
+// stripCodeFences removes markdown code fences wrapping JSON.
+func stripCodeFences(s string) string {
+	s = strings.TrimSpace(s)
+	if strings.HasPrefix(s, "```") {
+		// Remove opening fence line.
+		if idx := strings.Index(s, "\n"); idx != -1 {
+			s = s[idx+1:]
+		}
+		// Remove closing fence.
+		if idx := strings.LastIndex(s, "```"); idx != -1 {
+			s = s[:idx]
+		}
+	}
+	return strings.TrimSpace(s)
+}

internal/intent/classify_test.go

@@ -0,0 +1,152 @@
+package intent
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"testing"
+)
+
+// testHelper is a test binary approach: when invoked as a subprocess, it
+// writes the value of TEST_CLAUDE_OUTPUT to stdout and exits with TEST_CLAUDE_EXIT.
+func TestHelperProcess(t *testing.T) {
+	if os.Getenv("GO_WANT_HELPER_PROCESS") != "1" {
+		return
+	}
+	out := os.Getenv("TEST_CLAUDE_OUTPUT")
+	_, _ = os.Stdout.WriteString(out)
+	if os.Getenv("TEST_CLAUDE_EXIT") == "1" {
+		os.Exit(1)
+	}
+	os.Exit(0)
+}
+
+func fakeCommandContext(output string, exitErr bool) func(ctx context.Context, name string, args ...string) *exec.Cmd {
+	return func(ctx context.Context, name string, args ...string) *exec.Cmd {
+		cs := []string{"-test.run=TestHelperProcess", "--"}
+		cs = append(cs, args...)
+		cmd := exec.CommandContext(ctx, os.Args[0], cs...)
+		cmd.Env = append(os.Environ(),
+			"GO_WANT_HELPER_PROCESS=1",
+			"TEST_CLAUDE_OUTPUT="+output,
+		)
+		if exitErr {
+			cmd.Env = append(cmd.Env, "TEST_CLAUDE_EXIT=1")
+		}
+		return cmd
+	}
+}
+
+func TestClassify_Success(t *testing.T) {
+	// Envelope wrapping actual JSON result.
+	envelope := `{"result":"{\"argv\":[\"run\",\"plans/auth.md\"],\"confidence\":0.95,\"reasoning\":\"user wants to run auth plan\"}"}`
+
+	orig := CommandContext
+	CommandContext = fakeCommandContext(envelope, false)
+	defer func() { CommandContext = orig }()
+
+	r, err := Classify(context.Background(), "run the auth plan")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(r.Argv) != 2 || r.Argv[0] != "run" || r.Argv[1] != "plans/auth.md" {
+		t.Fatalf("unexpected argv: %v", r.Argv)
+	}
+	if r.Confidence < 0.9 {
+		t.Fatalf("unexpected confidence: %f", r.Confidence)
+	}
+}
+
+func TestClassify_NoClaude(t *testing.T) {
+	// Override PATH so claude is not found.
+	orig := os.Getenv("PATH")
+	os.Setenv("PATH", "")
+	defer os.Setenv("PATH", orig)
+
+	_, err := Classify(context.Background(), "anything")
+	if !errors.Is(err, ErrNoClaude) {
+		t.Fatalf("expected ErrNoClaude, got: %v", err)
+	}
+}
+
+func TestClassify_ExitError(t *testing.T) {
+	orig := CommandContext
+	CommandContext = fakeCommandContext("something went wrong", true)
+	defer func() { CommandContext = orig }()
+
+	_, err := Classify(context.Background(), "do something")
+	if !errors.Is(err, ErrClassificationFailed) {
+		t.Fatalf("expected ErrClassificationFailed, got: %v", err)
+	}
+}
+
+func TestClassify_MalformedJSON(t *testing.T) {
+	orig := CommandContext
+	CommandContext = fakeCommandContext(`{"result":"not json at all"}`, false)
+	defer func() { CommandContext = orig }()
+
+	_, err := Classify(context.Background(), "do something")
+	if !errors.Is(err, ErrClassificationFailed) {
+		t.Fatalf("expected ErrClassificationFailed, got: %v", err)
+	}
+}
+
+func TestClassify_EmptyArgv(t *testing.T) {
+	orig := CommandContext
+	CommandContext = fakeCommandContext(`{"result":"{\"argv\":[],\"confidence\":0.1,\"reasoning\":\"unclear\"}"}`, false)
+	defer func() { CommandContext = orig }()
+
+	_, err := Classify(context.Background(), "do something")
+	if !errors.Is(err, ErrClassificationFailed) {
+		t.Fatalf("expected ErrClassificationFailed, got: %v", err)
+	}
+}
+
+func TestClassify_CodeFencedJSON(t *testing.T) {
+	// Claude sometimes wraps JSON in code fences.
+	fenced := "{\"result\":\"```json\\n{\\\"argv\\\":[\\\"runs\\\"],\\\"confidence\\\":0.9,\\\"reasoning\\\":\\\"list runs\\\"}\\n```\"}"
+
+	orig := CommandContext
+	CommandContext = fakeCommandContext(fenced, false)
+	defer func() { CommandContext = orig }()
+
+	r, err := Classify(context.Background(), "show my runs")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(r.Argv) != 1 || r.Argv[0] != "runs" {
+		t.Fatalf("unexpected argv: %v", r.Argv)
+	}
+}
+
+func TestParseResponse_DirectJSON(t *testing.T) {
+	// No envelope, direct JSON.
+	r, err := parseResponse(`{"argv":["status","abc123"],"confidence":0.85,"reasoning":"check status"}`)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(r.Argv) != 2 || r.Argv[0] != "status" {
+		t.Fatalf("unexpected argv: %v", r.Argv)
+	}
+}
+
+func TestStripCodeFences(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"no fences", `{"argv":["runs"]}`, `{"argv":["runs"]}`},
+		{"with fences", "```json\n{\"argv\":[\"runs\"]}\n```", `{"argv":["runs"]}`},
+		{"with bare fences", "```\n{\"argv\":[\"runs\"]}\n```", `{"argv":["runs"]}`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := stripCodeFences(tt.in)
+			if got != tt.want {
+				t.Fatalf("stripCodeFences(%q) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}

internal/intent/context.go

@@ -0,0 +1,58 @@
+package intent
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+
+	"github.com/shahar-caura/forge/internal/state"
+)
+
+// DynamicContext holds runtime information injected into the classification prompt.
+type DynamicContext struct {
+	PlanFiles []string
+	RunIDs    []string
+}
+
+// GatherContext collects plan files and recent run IDs for prompt injection.
+func GatherContext() DynamicContext {
+	var dc DynamicContext
+
+	plans, _ := filepath.Glob("plans/*.md")
+	for _, p := range plans {
+		dc.PlanFiles = append(dc.PlanFiles, filepath.Base(p))
+	}
+
+	runs, err := state.List()
+	if err == nil {
+		cap := min(10, len(runs))
+		for _, r := range runs[:cap] {
+			dc.RunIDs = append(dc.RunIDs, r.ID)
+		}
+	}
+
+	return dc
+}
+
+// FormatForPrompt renders dynamic context as markdown for inclusion in the prompt.
+func FormatForPrompt(dc DynamicContext) string {
+	var sb strings.Builder
+
+	if len(dc.PlanFiles) > 0 {
+		sb.WriteString("## Available plan files\n")
+		for _, f := range dc.PlanFiles {
+			fmt.Fprintf(&sb, "- plans/%s\n", f)
+		}
+		sb.WriteString("\n")
+	}
+
+	if len(dc.RunIDs) > 0 {
+		sb.WriteString("## Recent run IDs\n")
+		for _, id := range dc.RunIDs {
+			fmt.Fprintf(&sb, "- %s\n", id)
+		}
+		sb.WriteString("\n")
+	}
+
+	return sb.String()
+}