mdreg

Documentation

Overview

Package mdreg provides the shared foundation for jungi's markdown-plus- frontmatter "content registries": agentreg, promptreg, and skillreg. Each of those packages loads a set of named items (agents, prompts, skills) from markdown files with a YAML frontmatter block, and merges multiple sources (embedded, project, user) with first-wins precedence.

mdreg owns the parts that are identical across all three: generic name-keyed storage with insertion order, first-wins merge with kind-labeled warnings, frontmatter splitting, and FS/OS directory loaders. Each adapter package supplies only its value type, YAML struct, directory layout, and a parse callback that turns a frontmatter block and body into its value type.

Index

• func LoadDir[T any](dir, kind string, layout Layout, parse ParseFunc[T]) (*Registry[T], []Warning, error)
• func LoadFS[T any](fsys fs.FS, dir, kind string, layout Layout, parse ParseFunc[T]) (*Registry[T], []Warning, error)
• func Merge[T any](kind string, regs ...*Registry[T]) (*Registry[T], []Warning)
• func SplitFrontmatter(content []byte) (yaml []byte, body string, err error)
• type Layout
• type ParseFunc
• type Registry
  • func Empty[T any]() *Registry[T]
  • func MustLoadEmbedded[T any](fsys fs.FS, dir, kind string, layout Layout, parse ParseFunc[T]) *Registry[T]
  • func (r *Registry[T]) Get(name string) (T, bool)
  • func (r *Registry[T]) List() []T
• type Warning

Functions

func LoadDir

func LoadDir[T any](dir, kind string, layout Layout, parse ParseFunc[T]) (*Registry[T], []Warning, error)

LoadDir reads items from a real OS directory. dir is the directory to scan; kind labels warnings; layout selects flat vs subdir scanning.

A missing dir is not an error: the returned Registry is empty and no warnings are generated. Other I/O errors are returned directly.

func LoadFS

func LoadFS[T any](fsys fs.FS, dir, kind string, layout Layout, parse ParseFunc[T]) (*Registry[T], []Warning, error)

LoadFS reads items from an fs.FS-rooted tree. dir is the directory inside fsys to scan; kind labels warnings (e.g. "agent", "prompt", "skill"); and layout selects flat vs subdir scanning.

A missing dir is not an error: the returned Registry is empty and no warnings are generated. Other I/O errors are returned directly.

func Merge

func Merge[T any](kind string, regs ...*Registry[T]) (*Registry[T], []Warning)

Merge returns a new Registry[T] combining the items from each input in order, with first-wins semantics on name collision: a later registry's item is dropped (and warned about) if an earlier registry already provided one with the same name.

kind labels the duplicate-name warnings (e.g. "agent", "prompt", "skill") so callers sharing this helper across adapters get distinguishable messages. nil registries are tolerated and treated as empty.

func SplitFrontmatter

func SplitFrontmatter(content []byte) (yaml []byte, body string, err error)

SplitFrontmatter splits content into its YAML frontmatter block and body.

The file must begin with a line containing exactly "---" and the YAML block must be terminated by another "---" line; both fence lines may end in \r\n (only the trailing \r is trimmed for the comparison — it is not otherwise treated specially). The returned yaml is the raw bytes between the fences (excluding both fence lines). The returned body is everything after the closing fence line's terminating newline, preserved verbatim — blank lines, tabs, and line-ending style are not altered.

There is no size cap: callers that need one should enforce it themselves before calling SplitFrontmatter.

Types

type Layout

type Layout struct {
	File string
}

Layout describes how a source directory is structured.

The zero value is a flat layout: every direct child of the directory ending in ".md" is an item file. Setting File to a filename (e.g. "SKILL.md" or "AGENT.md") switches to a subdir layout: every direct subdirectory containing a file with that name is an item.

type ParseFunc

type ParseFunc[T any] func(yamlBlock []byte, body, dir string) (name string, item T, err error)

ParseFunc turns a split frontmatter YAML block and body into a named item of type T. dir is the real filesystem directory the item was loaded from — populated only for subdir-layout items loaded via LoadDir; it is empty for flat-layout items and for anything loaded via LoadFS (embedded sources have no real filesystem directory).

type Registry

type Registry[T any] struct {
	// contains filtered or unexported fields
}

Registry holds a name-keyed set of items of type T, built once and read many times over the lifetime of a session. It preserves the order items were added in, independent of map iteration order.

func Empty

func Empty[T any]() *Registry[T]

Empty returns a Registry[T] with no items. Used when a source directory is missing or unreadable so callers can avoid nil checks.

func MustLoadEmbedded

func MustLoadEmbedded[T any](fsys fs.FS, dir, kind string, layout Layout, parse ParseFunc[T]) *Registry[T]

MustLoadEmbedded loads items from an embedded fs.FS via LoadFS and panics on any load error or warning.

It is meant for jungi-bundled content packages (e.g. internal/agents, internal/prompts, internal/skills) whose //go:embed'd files are static: any failure to parse them is a build defect, not a runtime condition, so panicking surfaces it immediately (ideally in CI) rather than shipping a half-broken built-in set.

func (*Registry[T]) Get

func (r *Registry[T]) Get(name string) (T, bool)

Get returns the item registered under name and a boolean indicating whether it was found.

func (*Registry[T]) List

func (r *Registry[T]) List() []T

List returns the registered items in insertion order. The returned slice is freshly allocated and safe to mutate.

type Warning

type Warning struct {
	Path   string
	Reason string
}

Warning describes a file that was skipped during registry construction — due to an I/O error, malformed frontmatter, an invalid name, or a duplicate name. Warnings are returned alongside the registry so the caller can surface them through whatever logging mechanism it uses, rather than mdreg (or its adapters) taking a logger dependency.