feat: add generation and templates packages (v0.2.0)

Promotes the shared AI generation retry loop and prompt template loading
logic from ctx-git/ctx-specs into the SDK so extensions can import them
instead of maintaining byte-for-byte copies.

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

Author: miohansen

generation/config.go

@@ -0,0 +1,31 @@
+// Package generation provides AI generation with retry and validation.
+package generation
+
+import (
+	"context"
+	"io"
+)
+
+// Format describes the expected output format.
+type Format string
+
+const (
+	FormatPlainText Format = "plaintext"
+	FormatJSON      Format = "json"
+)
+
+// Config drives a single generation call.
+type Config struct {
+	TypeName    string
+	Format      Format
+	Validator   Validator
+	AIFunc      func(ctx context.Context, prompt string) (string, error)
+	MaxAttempts int
+	Debug       io.Writer
+}
+
+// Result holds the outcome of a generation call.
+type Result struct {
+	Output   string
+	Attempts int
+}

generation/generate.go

@@ -0,0 +1,65 @@
+package generation
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+)
+
+func Generate(ctx context.Context, cfg *Config, prompt string) (*Result, error) {
+	maxAttempts := cfg.MaxAttempts
+	if maxAttempts <= 0 {
+		maxAttempts = defaultMaxAttempts
+	}
+
+	validator := cfg.Validator
+	if validator == nil {
+		validator = NoopValidator{}
+	}
+
+	currentPrompt := prompt
+	var lastOutput string
+	var lastErrs []ValidationError
+
+	for attempt := 1; attempt <= maxAttempts; attempt++ {
+		debugf(cfg.Debug, "=== attempt %d/%d ===\n", attempt, maxAttempts)
+		debugf(cfg.Debug, "--- prompt ---\n%s\n---\n", currentPrompt)
+
+		raw, err := cfg.AIFunc(ctx, currentPrompt)
+		if err != nil {
+			return nil, fmt.Errorf("%s: AI call failed (attempt %d): %w",
+				cfg.TypeName, attempt, err)
+		}
+
+		cleaned := cleanOutput(raw)
+		debugf(cfg.Debug, "--- response (cleaned) ---\n%s\n---\n", cleaned)
+
+		errs := validator.Validate(cleaned)
+		if len(errs) == 0 {
+			debugf(cfg.Debug, "validation passed on attempt %d\n", attempt)
+			return &Result{Output: cleaned, Attempts: attempt}, nil
+		}
+
+		lastOutput = cleaned
+		lastErrs = errs
+
+		if attempt < maxAttempts {
+			currentPrompt = buildRetryPrompt(currentPrompt, errs, attempt)
+		}
+	}
+
+	errMsgs := make([]string, len(lastErrs))
+	for i, e := range lastErrs {
+		errMsgs[i] = e.Message
+	}
+	return &Result{Output: lastOutput, Attempts: maxAttempts},
+		fmt.Errorf("%s: validation failed after %d attempts: %s",
+			cfg.TypeName, maxAttempts, strings.Join(errMsgs, "; "))
+}
+
+func debugf(w io.Writer, format string, args ...interface{}) {
+	if w != nil {
+		fmt.Fprintf(w, format, args...)
+	}
+}

generation/generation_test.go

@@ -0,0 +1,300 @@
+package generation
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// --- helpers ----------------------------------------------------------------
+
+// fixedAIFunc returns a sequence of responses in order. Once the sequence is
+// exhausted every subsequent call returns the last response.
+func fixedAIFunc(responses ...string) func(context.Context, string) (string, error) {
+	i := 0
+	return func(_ context.Context, _ string) (string, error) {
+		resp := responses[i]
+		if i < len(responses)-1 {
+			i++
+		}
+		return resp, nil
+	}
+}
+
+// errorAIFunc always returns the given error.
+func errorAIFunc(err error) func(context.Context, string) (string, error) {
+	return func(_ context.Context, _ string) (string, error) {
+		return "", err
+	}
+}
+
+// fixedValidator fails for a set of outputs and passes for everything else.
+type fixedValidator struct {
+	failOutputs map[string][]ValidationError
+}
+
+func (v *fixedValidator) Validate(output string) []ValidationError {
+	if errs, ok := v.failOutputs[output]; ok {
+		return errs
+	}
+	return nil
+}
+
+// --- Generate ----------------------------------------------------------------
+
+func TestGenerate_successFirstAttempt(t *testing.T) {
+	cfg := &Config{
+		TypeName: "TestType",
+		AIFunc:   fixedAIFunc("valid output"),
+		Validator: &fixedValidator{
+			failOutputs: map[string][]ValidationError{},
+		},
+	}
+
+	result, err := Generate(context.Background(), cfg, "prompt")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Attempts != 1 {
+		t.Errorf("Attempts = %d, want 1", result.Attempts)
+	}
+	if result.Output != "valid output" {
+		t.Errorf("Output = %q, want %q", result.Output, "valid output")
+	}
+}
+
+func TestGenerate_retryOnValidationError(t *testing.T) {
+	// First call returns "bad", second call returns "good".
+	cfg := &Config{
+		TypeName: "TestType",
+		AIFunc:   fixedAIFunc("bad", "good"),
+		Validator: &fixedValidator{
+			failOutputs: map[string][]ValidationError{
+				"bad": {{Message: "output is bad"}},
+			},
+		},
+	}
+
+	result, err := Generate(context.Background(), cfg, "prompt")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Attempts != 2 {
+		t.Errorf("Attempts = %d, want 2", result.Attempts)
+	}
+	if result.Output != "good" {
+		t.Errorf("Output = %q, want %q", result.Output, "good")
+	}
+}
+
+func TestGenerate_exhaustsMaxAttempts(t *testing.T) {
+	cfg := &Config{
+		TypeName:    "TestType",
+		MaxAttempts: 2,
+		AIFunc:      fixedAIFunc("always bad"),
+		Validator: &fixedValidator{
+			failOutputs: map[string][]ValidationError{
+				"always bad": {{Message: "still bad"}},
+			},
+		},
+	}
+
+	result, err := Generate(context.Background(), cfg, "prompt")
+	if err == nil {
+		t.Fatal("expected error but got nil")
+	}
+	if result == nil {
+		t.Fatal("expected non-nil Result even on failure")
+	}
+	if result.Attempts != 2 {
+		t.Errorf("Attempts = %d, want 2", result.Attempts)
+	}
+	if result.Output != "always bad" {
+		t.Errorf("Output = %q, want %q", result.Output, "always bad")
+	}
+	if !strings.Contains(err.Error(), "still bad") {
+		t.Errorf("error message %q does not contain validation error text", err.Error())
+	}
+}
+
+func TestGenerate_AIFuncError(t *testing.T) {
+	aiErr := errors.New("AI unavailable")
+	cfg := &Config{
+		TypeName: "TestType",
+		AIFunc:   errorAIFunc(aiErr),
+	}
+
+	_, err := Generate(context.Background(), cfg, "prompt")
+	if err == nil {
+		t.Fatal("expected error but got nil")
+	}
+	if !errors.Is(err, aiErr) {
+		t.Errorf("error %v does not wrap %v", err, aiErr)
+	}
+}
+
+func TestGenerate_defaultMaxAttempts(t *testing.T) {
+	// MaxAttempts=0 should fall back to defaultMaxAttempts (3).
+	// We count actual calls via a counter AIFunc that always returns invalid output.
+	calls := 0
+	cfg := &Config{
+		TypeName:    "TestType",
+		MaxAttempts: 0,
+		AIFunc: func(_ context.Context, _ string) (string, error) {
+			calls++
+			return "invalid", nil
+		},
+		Validator: &fixedValidator{
+			failOutputs: map[string][]ValidationError{
+				"invalid": {{Message: "invalid"}},
+			},
+		},
+	}
+
+	_, err := Generate(context.Background(), cfg, "prompt")
+	if err == nil {
+		t.Fatal("expected error but got nil")
+	}
+	if calls != defaultMaxAttempts {
+		t.Errorf("AIFunc called %d times, want %d (defaultMaxAttempts)", calls, defaultMaxAttempts)
+	}
+}
+
+func TestGenerate_nilValidator(t *testing.T) {
+	cfg := &Config{
+		TypeName:  "TestType",
+		Validator: nil,
+		AIFunc:    fixedAIFunc("output"),
+	}
+
+	// Should not panic — nil Validator must be treated as NoopValidator.
+	result, err := Generate(context.Background(), cfg, "prompt")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if result.Attempts != 1 {
+		t.Errorf("Attempts = %d, want 1", result.Attempts)
+	}
+}
+
+// --- cleanOutput -------------------------------------------------------------
+
+func TestCleanOutput_stripsFences(t *testing.T) {
+	input := "```json\n{\"key\":\"value\"}\n```"
+	got := cleanOutput(input)
+	want := `{"key":"value"}`
+	if got != want {
+		t.Errorf("cleanOutput() = %q, want %q", got, want)
+	}
+}
+
+func TestCleanOutput_noFences(t *testing.T) {
+	input := "plain text output"
+	got := cleanOutput(input)
+	if got != input {
+		t.Errorf("cleanOutput() = %q, want %q", got, input)
+	}
+}
+
+func TestCleanOutput_trimsWhitespace(t *testing.T) {
+	input := "  \n  trimmed  \n  "
+	got := cleanOutput(input)
+	want := "trimmed"
+	if got != want {
+		t.Errorf("cleanOutput() = %q, want %q", got, want)
+	}
+}
+
+// --- buildRetryPrompt --------------------------------------------------------
+
+func TestBuildRetryPrompt_format(t *testing.T) {
+	errs := []ValidationError{{Message: "field missing"}}
+	result := buildRetryPrompt("original prompt", errs, 1)
+
+	checks := []struct {
+		desc    string
+		contain string
+	}{
+		{"contains original prompt", "original prompt"},
+		{"contains numbered error", "1. field missing"},
+		{"contains attempt number", "attempt 1"},
+		{"contains correction header", "INSTRUCTIONS FOR CORRECTION"},
+		{"contains regenerate instruction", "Please regenerate the output"},
+	}
+
+	for _, c := range checks {
+		if !strings.Contains(result, c.contain) {
+			t.Errorf("%s: output does not contain %q\nFull output:\n%s", c.desc, c.contain, result)
+		}
+	}
+}
+
+func TestBuildRetryPrompt_multipleErrors(t *testing.T) {
+	errs := []ValidationError{
+		{Message: "first error"},
+		{Message: "second error"},
+		{Message: "third error"},
+	}
+	result := buildRetryPrompt("prompt", errs, 2)
+
+	for i, e := range errs {
+		numbered := strings.Join([]string{
+			// e.g. "1. first error"
+			string(rune('1'+i)) + ". " + e.Message,
+		}, "")
+		if !strings.Contains(result, numbered) {
+			t.Errorf("output does not contain %q\nFull output:\n%s", numbered, result)
+		}
+	}
+}
+
+// --- JSONValidator -----------------------------------------------------------
+
+func TestJSONValidator_valid(t *testing.T) {
+	v := JSONValidator{RequiredFields: []string{"name", "age"}}
+	errs := v.Validate(`{"name":"Alice","age":30}`)
+	if len(errs) != 0 {
+		t.Errorf("expected no errors, got %v", errs)
+	}
+}
+
+func TestJSONValidator_missingField(t *testing.T) {
+	v := JSONValidator{RequiredFields: []string{"name", "age"}}
+	errs := v.Validate(`{"name":"Alice"}`)
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if !strings.Contains(errs[0].Message, "age") {
+		t.Errorf("error message %q does not mention missing field %q", errs[0].Message, "age")
+	}
+}
+
+func TestJSONValidator_invalidJSON(t *testing.T) {
+	v := JSONValidator{}
+	errs := v.Validate("not json at all")
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if !strings.Contains(errs[0].Message, "invalid JSON") {
+		t.Errorf("error message %q does not indicate JSON parse failure", errs[0].Message)
+	}
+}
+
+// --- NoopValidator -----------------------------------------------------------
+
+func TestNoopValidator(t *testing.T) {
+	v := NoopValidator{}
+	inputs := []string{
+		"",
+		"some output",
+		"not json {{{",
+		"   ",
+	}
+	for _, input := range inputs {
+		errs := v.Validate(input)
+		if len(errs) != 0 {
+			t.Errorf("NoopValidator.Validate(%q) = %v, want nil", input, errs)
+		}
+	}
+}