catl

README

[!IMPORTANT] The core catalog functionality is implemented. Dependency management, workspaces, packaging, integrity checks, and cache hardening are still in progress.

catl

catl is a package manager for declarative data. It's like cargo or go mod, but for directories of structured files instead of source code. It validates YAML and JSON manifests against JSON Schema, pins remote dependencies with cryptographic tree hashes, and gives you verified, offline access to catalog contents through a CLI or an embeddable Go library.

It's as a lightweight substrate for anything built on declarative data, such as AI agent runtimes, feature flag evaluators, headless CMSs, and policy engines, so you don't have to reinvent validation, locking, and integrity for every project.

Quick start

A catalog is a directory containing a catl.toml, JSON schemas, and collections of manifests:

catalog/
├── catl.toml                 # Name, collections, dependencies
├── schemas/
│   └── service.json          # JSON Schema Draft 2020-12
└── services/
    ├── auth.yaml             # Flat entity (ID: auth)
    └── billing/              # Bundle entity (ID: billing)
        ├── manifest.yaml
        └── runbook.md        # Companion file

Validate and query from the CLI

catl check                                      # Validate (silent on success)
catl list                                       # List entities
catl resolve services platform.billing          # Print manifest path
catl show services platform.billing runbook.md  # Stream a companion file

Read verified data in Go

package main

import (
    "context"
    "fmt"
    "io/fs"
    "log"

    "github.com/ju4n97/catl"
)

type Service struct {
    Owner string `json:"owner"`
    Tier  int    `json:"tier"`
}

func main() {
    ctx := context.Background()

    cat, err := catl.Open(ctx, "./catalog", catl.Options{})
    if err != nil {
        log.Fatal(err)
    }

    entity, err := cat.Resolve("services", "platform.billing")
    if err != nil {
        log.Fatal(err)
    }

    var svc Service
    if err := entity.Unmarshal(&svc); err != nil {
        log.Fatal(err)
    }

    runbook, err := fs.ReadFile(entity.FS(ctx), "runbook.md")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("%s (owner: %s) - %d bytes runbook\n",
    entity.QualifiedID(), svc.Owner, len(runbook))
}

Documentation

https://ju4n97.github.io/catl/

Examples

See the examples directory

License

MIT

Documentation

Index

• Variables
• type Catalog
  • func Open(ctx context.Context, dir string, opts Options) (*Catalog, error)
  • func OpenFS(ctx context.Context, fsys fs.FS, opts Options) (*Catalog, error)
  • func (c *Catalog) CollectionEntities(collection string) ([]*Entity, error)
  • func (c *Catalog) Entities() []*Entity
  • func (c *Catalog) FS() fs.FS
  • func (c *Catalog) Name() string
  • func (c *Catalog) Resolve(collection, qualifiedID string) (*Entity, error)
  • func (c *Catalog) RootPath() string
• type Entity
  • func (e *Entity) Collection() string
  • func (e *Entity) CompanionFiles() []string
  • func (e *Entity) FS(ctx context.Context) (fs.FS, error)
  • func (e *Entity) ID() string
  • func (e *Entity) ManifestPath() string
  • func (e *Entity) Namespace() string
  • func (e *Entity) QualifiedID() string
  • func (e *Entity) RawManifest() []byte
  • func (e *Entity) Shape() scan.EntityShape
  • func (e *Entity) Unmarshal(v any) error
• type Options

Variables

var (
	// ErrNotQualified is returned when an identifier does not contain a namespace prefix.
	ErrNotQualified = errors.New("identifier is not qualified (want namespace.id)")

	// ErrNotFound is returned when a requested entity, collection, or namespace does not exist.
	ErrNotFound = errors.New("entity or namespace not found")

	// ErrLockStale indicates that catl.lock does not match declared dependencies in catl.toml.
	ErrLockStale = errors.New("catl.lock is out of date; run 'catl update'")

	// ErrTamperedVendor indicates that content in .catl/vendor does not match the recorded tree hash.
	ErrTamperedVendor = errors.New("vendor directory content does not match tree hash")

	// ErrRequiresNewer indicates that the configuration requires a newer version of the catl tool.
	ErrRequiresNewer = errors.New("configuration requires a newer version of catl")
)

Types

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog represents an immutable, validated catalog loaded into memory.

func Open

func Open(ctx context.Context, dir string, opts Options) (*Catalog, error)

Open reads and validates a catalog from a directory on the local filesystem.

func OpenFS

func OpenFS(ctx context.Context, fsys fs.FS, opts Options) (*Catalog, error)

OpenFS reads and validates a catalog from an arbitrary fs.FS filesystem (such as testing/fstest.MapFS or embed.FS) without touching the local disk.

func (*Catalog) CollectionEntities

func (c *Catalog) CollectionEntities(collection string) ([]*Entity, error)

CollectionEntities returns entities belonging to a specific collection, sorted by ID.

func (*Catalog) Entities

func (c *Catalog) Entities() []*Entity

Entities returns all entities across collections sorted deterministically.

func (*Catalog) FS

func (c *Catalog) FS() fs.FS

FS returns the underlying read-only filesystem backing the catalog.

func (*Catalog) Name

func (c *Catalog) Name() string

Name returns the catalog's primary namespace as declared in catl.toml.

func (*Catalog) Resolve

func (c *Catalog) Resolve(collection, qualifiedID string) (*Entity, error)

Resolve retrieves an entity by collection name and qualified identifier (e.g. "app.dark-mode"). It returns ErrNotQualified if the caller supplies a bare ID without a namespace.

func (*Catalog) RootPath

func (c *Catalog) RootPath() string

RootPath returns the local directory path if opened from disk, or empty if opened via OpenFS.

type Entity

type Entity struct {
	// contains filtered or unexported fields
}

Entity represents an addressable declarative item within a catalog collection.

func (*Entity) Collection

func (e *Entity) Collection() string

Collection returns the collection name the entity belongs to (e.g. "flags").

func (*Entity) CompanionFiles

func (e *Entity) CompanionFiles() []string

CompanionFiles returns a slice of paths to companion files relative to the bundle directory. Returns an empty slice for flat entities.

func (*Entity) FS

func (e *Entity) FS(ctx context.Context) (fs.FS, error)

FS returns a read-only filesystem scoped to the bundle directory. It returns an error if called on a flat entity.

func (*Entity) ID

func (e *Entity) ID() string

ID returns the bare identifier of the entity (e.g. "dark-mode").

func (*Entity) ManifestPath

func (e *Entity) ManifestPath() string

ManifestPath returns the relative path from the catalog root to the manifest file.

func (*Entity) Namespace

func (e *Entity) Namespace() string

Namespace returns the namespace owning the entity (the catalog name).

func (*Entity) QualifiedID

func (e *Entity) QualifiedID() string

QualifiedID returns the canonical address of the entity: "namespace.id".

func (*Entity) RawManifest

func (e *Entity) RawManifest() []byte

RawManifest returns the raw unparsed bytes of the entity manifest.

func (*Entity) Shape

func (e *Entity) Shape() scan.EntityShape

Shape returns whether the entity is a flat single file or a bundle directory.

func (*Entity) Unmarshal

func (e *Entity) Unmarshal(v any) error

Unmarshal decodes the validated manifest content into a user-provided struct.

type Options

type Options struct {
	// Offline disables network calls and reads exclusively from local vendor directories or cache.
	Offline bool
}

Options configures runtime behavior when opening a catalog.