feat(spec): YAML loader and parser with structured errors (#3)

- Add LoadResourceFile and ParseResourceFromBytes (single-document yaml.v3 decode)
- Enforce apiVersion, kind, metadata, metadata.name, and non-null spec (§6.1)
- Map kind to typed *Resource envelopes; ErrUnknownKind / ErrMultipleDocuments
- LoadError carries path and best-effort YAML line from parser messages
- Tests: all MVP kinds load from disk; missing metadata.name; invalid YAML path; multi-doc; unknown kind

Closes #3

Made-with: Cursor

Author: leo-aa88

internal/spec/doc.go

@@ -1,3 +1,3 @@
-// Package spec defines resource envelopes and MVP kind structs (design doc §6–§7).
-// Parsing, defaults, and validation live in future packages.
+// Package spec defines resource envelopes, MVP kind structs (§6–§7), and YAML loading.
+// Defaults, reference resolution, and semantic validation are out of scope for now.
 package spec

internal/spec/errors.go

@@ -0,0 +1,68 @@
+package spec
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+	"strconv"
+)
+
+// Sentinel errors for resource loading.
+var (
+	ErrMultipleDocuments = errors.New("expected exactly one YAML document")
+	ErrUnknownKind       = errors.New("unknown resource kind")
+)
+
+// LoadError records a resource load or decode failure with file context (issue #3).
+type LoadError struct {
+	Path   string
+	Line   int // 1-based; 0 if unknown
+	Column int // 1-based; 0 if unknown
+	Msg    string
+	Err    error
+}
+
+func (e *LoadError) Error() string {
+	if e == nil {
+		return ""
+	}
+	prefix := ""
+	switch {
+	case e.Path != "" && e.Line > 0 && e.Column > 0:
+		prefix = fmt.Sprintf("%s:%d:%d: ", e.Path, e.Line, e.Column)
+	case e.Path != "" && e.Line > 0:
+		prefix = fmt.Sprintf("%s:%d: ", e.Path, e.Line)
+	case e.Path != "":
+		prefix = e.Path + ": "
+	}
+	return prefix + e.Msg
+}
+
+// Unwrap returns the underlying error for errors.Is / errors.As.
+func (e *LoadError) Unwrap() error { return e.Err }
+
+var yamlLineHint = regexp.MustCompile(`line (\d+)`)
+
+func yamlLocationHint(err error) (line, col int) {
+	if err == nil {
+		return 0, 0
+	}
+	m := yamlLineHint.FindStringSubmatch(err.Error())
+	if len(m) < 2 {
+		return 0, 0
+	}
+	line, _ = strconv.Atoi(m[1])
+	return line, col
+}
+
+// wrapLoadError attaches path and best-effort YAML line/column from parser errors.
+func wrapLoadError(path, msg string, err error) error {
+	if err == nil {
+		return &LoadError{Path: path, Msg: msg}
+	}
+	line, col := yamlLocationHint(err)
+	return &LoadError{
+		Path: path, Line: line, Column: col,
+		Msg: msg, Err: err,
+	}
+}

internal/spec/loader.go

@@ -0,0 +1,14 @@
+package spec
+
+import (
+	"os"
+)
+
+// LoadResourceFile reads path and decodes exactly one YAML MVP resource.
+func LoadResourceFile(path string) (*Decoded, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, &LoadError{Path: path, Msg: "read file", Err: err}
+	}
+	return ParseResourceFromBytes(data, path)
+}

internal/spec/loader_test.go

@@ -0,0 +1,138 @@
+package spec
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+func TestLoadResourceFile_validKinds(t *testing.T) {
+	cases := []struct {
+		name string
+		doc  any
+	}{
+		{"Project", sampleProject()},
+		{"Agent", sampleAgent()},
+		{"Tool_MCP", sampleToolMCP()},
+		{"Tool_HTTP", sampleToolHTTP()},
+		{"Workflow", sampleWorkflow()},
+		{"Policy", samplePolicy()},
+		{"Environment", sampleEnvironment()},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			data, err := yaml.Marshal(tc.doc)
+			if err != nil {
+				t.Fatal(err)
+			}
+			dir := t.TempDir()
+			p := filepath.Join(dir, "res.yaml")
+			if err := os.WriteFile(p, data, 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			got, err := LoadResourceFile(p)
+			if err != nil {
+				t.Fatalf("LoadResourceFile: %v", err)
+			}
+			if got.Path != p {
+				t.Fatalf("Path = %q, want %q", got.Path, p)
+			}
+			if !reflect.DeepEqual(got.Resource, tc.doc) {
+				t.Fatalf("resource mismatch\n got %#v\nwant %#v", got.Resource, tc.doc)
+			}
+		})
+	}
+}
+
+func TestParseResourceFromBytes_missingMetadataName(t *testing.T) {
+	const y = `
+apiVersion: agentic.dev/v0
+kind: Agent
+metadata: {}
+spec: {}
+`
+	_, err := ParseResourceFromBytes([]byte(y), "/tmp/agent.yaml")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	var le *LoadError
+	if !errors.As(err, &le) {
+		t.Fatalf("want *LoadError, got %T: %v", err, err)
+	}
+	if !strings.Contains(le.Error(), "/tmp/agent.yaml") {
+		t.Fatalf("error should mention path: %q", le.Error())
+	}
+	if !strings.Contains(le.Error(), "metadata.name") {
+		t.Fatalf("error should mention metadata.name: %q", le.Error())
+	}
+}
+
+func TestLoadResourceFile_invalidYAML_wrapsPath(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "bad.yaml")
+	// Line 2: invalid indentation triggers a parser error with a line hint.
+	content := "apiVersion: x\n kind: Agent\nmetadata: {name: a}\nspec: {}\n"
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := LoadResourceFile(p)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	var le *LoadError
+	if !errors.As(err, &le) {
+		t.Fatalf("want *LoadError, got %T: %v", err, err)
+	}
+	if le.Path != p {
+		t.Fatalf("LoadError.Path = %q, want %q", le.Path, p)
+	}
+	if !strings.Contains(le.Error(), p) {
+		t.Fatalf("error string should contain path: %q", le.Error())
+	}
+	_ = le.Line // best-effort from yaml error text; message always includes path
+}
+
+func TestParseResourceFromBytes_multipleDocuments(t *testing.T) {
+	y := `
+apiVersion: agentic.dev/v0
+kind: Project
+metadata: {name: a}
+spec: {}
+---
+apiVersion: agentic.dev/v0
+kind: Project
+metadata: {name: b}
+spec: {}
+`
+	_, err := ParseResourceFromBytes([]byte(y), "multi.yaml")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !errors.Is(err, ErrMultipleDocuments) {
+		t.Fatalf("want ErrMultipleDocuments in chain, got %v", err)
+	}
+}
+
+func TestParseResourceFromBytes_unknownKind(t *testing.T) {
+	y := `
+apiVersion: agentic.dev/v0
+kind: NotAKind
+metadata: {name: x}
+spec: {}
+`
+	_, err := ParseResourceFromBytes([]byte(y), "x.yaml")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !errors.Is(err, ErrUnknownKind) {
+		t.Fatalf("want ErrUnknownKind in chain, got %v", err)
+	}
+}