Markdown frontmatter parsing, import resolution, GitHub URL handling, and schema validation for agentic workflow files.

The parser package is responsible for extracting and processing YAML frontmatter from agentic workflow .md files. Frontmatter defines the workflow's entire configuration — triggers, permissions, tools, safe outputs, engine settings, network restrictions, and runtime overrides. The markdown body that follows the frontmatter serves as the AI agent's prompt text.

Beyond basic frontmatter extraction, the package provides a rich import system that resolves @import directives (local files, GitHub URLs, fragments), an include expander for @include directives in the markdown body, a schedule parser that converts natural-language schedules into cron expressions, MCP server configuration extraction, and JSON schema–backed validation with actionable error messages.

The package is designed for use both in the main CLI binary and in WebAssembly contexts (see *_wasm.go files). Build constraints separate platform-specific implementations for remote fetching and filesystem access.

content, _ := os.ReadFile("my-workflow.md")
result, err := parser.ExtractFrontmatterFromContent(string(content))
if err != nil {
    log.Fatal(err)
}
fmt.Println("Triggers:", result.Frontmatter["on"])
fmt.Println("Prompt:", result.MarkdownBody)

cache := parser.NewImportCache("/path/to/repo")
imports, err := parser.ProcessImportsFromFrontmatterWithSource(
    result.Frontmatter,
    filepath.Dir("my-workflow.md"),
    cache,
    "my-workflow.md",
    result.FrontmatterYAML,
)

cron, original, err := parser.ParseSchedule("every day at 9am")
// cron = "0 9 * * *"

err := parser.ValidateMainWorkflowFrontmatterWithSchemaAndLocation(
    frontmatter, "my-workflow.md",
)

servers, err := parser.ExtractMCPConfigurations(frontmatter, "")
for _, s := range servers {
    fmt.Printf("%s: type=%s\n", s.Name, s.Type)
}

The parsing pipeline for a workflow file proceeds as:

1. Read the raw markdown file content.
2. Extract the YAML frontmatter block between --- delimiters (ExtractFrontmatterFromContent).
3. Process imports: resolve all @import directives recursively, merge imported YAML configurations, and deduplicate (ProcessImportsFromFrontmatterWithSource).
4. Validate the merged frontmatter against the JSON schema (ValidateMainWorkflowFrontmatterWithSchemaAndLocation).
5. Expand includes in the markdown body (ExpandIncludesWithManifest).
6. Pass the merged frontmatter and markdown body to pkg/workflow for compilation.

Import caching is crucial for performance and cycle detection. The ImportCache tracks visited paths within a single compilation run to prevent infinite recursion.

Internal:

• pkg/console — parser-facing warning/error message formatting
• pkg/constants — shared parser constants and default values
• pkg/fileutil — file existence and path helper utilities
• pkg/gitutil — Git remote and host detection helpers
• pkg/types — BaseMCPServerConfig
• pkg/typeutil — safe type conversion helpers for dynamic frontmatter
• pkg/logger — debug logging
• pkg/sliceutil — slice helper utilities for validation and merging
• pkg/stringutil — string normalization and ANSI/format helpers

External:

• github.com/santhosh-tekuri/jsonschema/v5 — JSON schema validation
• go.yaml.in/yaml/v3 — YAML parsing
• goccy/go-yaml — YAML 1.1/1.2 compatible parsing (for GitHub Actions compatibility)

ImportCache is designed for use within a single goroutine per compilation run. Its internal map is not concurrency-safe. For concurrent compilations, create a separate ImportCache per compilation.

The DefaultFileReader variable is safe to read but MUST NOT be mutated after package initialization. Tests may replace it with a custom FileReader to inject virtual filesystem content.

This specification is automatically maintained by the spec-extractor workflow.