bundle

Documentation

Overview

Package bundle walks an on-disk OPS/ tree and produces a flat list of (stack, scope, name, txcl, mock_req, mock_res) records suitable for POSTing to the admin /v1/ops/import endpoint.

Layout model: directories organize, the stack root is the only boundary

Under <root>/OPS/, a stack root is the path prefix up to (but excluding) the first *numbered* directory. Everything below that numbered directory is for developer organization — nested folders never create a new stack. A `.txcl` leaf may live at any depth beneath a numbered directory.

OPS/<stack>/<scope>/<name>.txcl
OPS/<stack>/<scope>_<LABEL>/<name>.txcl
OPS/<stack>/<scope>_<LABEL>/<org>/<name>.txcl          (org dir is cosmetic)
OPS/<stack>/<scope>_<LABEL>/<inner-scope>/<name>.txcl  (nearest number wins)

A numbered directory is any basename starting with digits, optionally followed by `_`, `-`, or whitespace and a human-facing label (ignored): `1000`, `1000_setup`, `1000-setup`, `1000 setup` all mean step 1000. Leading zeros are stripped (`0100` and `100` both mean 100).

Each leaf's effective step is its NEAREST numbered ancestor (the deepest one on its path); there is no stride arithmetic. Its name is the path from that numbered ancestor down to the file, with separators flattened to `_`, so a leaf directly under the numbered dir keeps its bare basename (the common, historical case parses byte-identically).

Examples:

OPS/website/100/resonator.txcl              -> stack=website,        scope=100,  name=resonator
OPS/website/0100_SETUP/init.txcl            -> stack=website,        scope=100,  name=init
OPS/website/0100_SETUP/audit.txcl           -> stack=website,        scope=100,  name=audit (parallel rule)
OPS/website/0100_SETUP/misc/normalize.txcl  -> stack=website,        scope=100,  name=misc_normalize
OPS/website/1000_setup/1010_config/load.txcl-> stack=website,        scope=1010, name=load (nearest wins)
OPS/website/canary/0100_SETUP/init.txcl     -> stack=website/canary, scope=100,  name=init

A `_`-prefixed organization directory below the numbered dir disables every leaf beneath it (park a draft in `_disabled/` to keep it out of the deploy).

A `.txcl` with no numbered ancestor cannot be placed (no step, and no way to split stack from path), and two leaves that flatten to the same (stack, scope, name) collide. Both are reported via WalkDiag so the deploy path can stop loudly instead of silently dropping or failing server-side. The plain Walk/WalkFS entry points discard diagnostics and keep their historical "skip what doesn't fit" behavior for read-only callers.

Optional sibling files `mock-request.json` and `mock-response.json` in the leaf's own directory attach to *all* rules in that directory.

Index

• func SystemSegment(stack string) (slug, rest string, ok bool)
• func WalkDiag(root string) ([]Op, []Diag, error)
• func WalkFSDiag(fsys fs.FS, root string) ([]Op, []Diag, error)
• type Diag
• type Op
  • func Walk(root string) ([]Op, error)
  • func WalkFS(fsys fs.FS, root string) ([]Op, error)
  • func WalkSystemFS(fsys fs.FS, root string) ([]Op, error)

Functions

func SystemSegment

func SystemSegment(stack string) (slug, rest string, ok bool)

SystemSegment splits a stack name whose first path segment is a `_`-prefixed chassis-local tenant (e.g. "_sys/boot" -> slug="_sys", rest="boot"). ok is false for ordinary application stacks and for a bare "_slug" with no stack under it. This is the single discriminator between the two load paths: `_*` stacks are loaded locally/trusted by the chassis (chassis/sysops); everything else is an application stack pushed through the admin API.

func WalkDiag

func WalkDiag(root string) ([]Op, []Diag, error)

WalkDiag is Walk plus the diagnostics (no-step leaves, name collisions) the deploy path surfaces as errors. ops are still returned alongside.

func WalkFSDiag

func WalkFSDiag(fsys fs.FS, root string) ([]Op, []Diag, error)

WalkFSDiag is WalkFS plus diagnostics.

Types

type Diag

type Diag struct {
	// Stack is the resolved stack when known (collisions), or "" when the
	// leaf has no numbered ancestor and therefore no derivable stack.
	Stack string
	// Path is the source `.txcl` path (within fsys).
	Path string
	// Msg is a human-facing, already-formatted explanation.
	Msg string
}

Diag is a non-fatal-at-walk-time finding about a `.txcl` leaf that could not be turned into a well-formed Op (no numbered ancestor) or that would collide with another leaf. The deploy path (apply/push) decides whether to treat it as an error; read-only callers via Walk/WalkFS ignore them.

type Op

type Op struct {
	Stack   string `json:"stack"`
	Scope   int    `json:"scope"`
	Name    string `json:"name"`
	Txcl    string `json:"txcl"`
	MockReq string `json:"mock_req,omitempty"`
	MockRes string `json:"mock_res,omitempty"`

	// SourcePath is the absolute path to the .txcl file. Set by Walk for
	// diagnostic purposes; not serialized into the wire format.
	SourcePath string `json:"-"`
}

Op is one row in a bundle. Mirrors the admin/ops.go OpRecord shape.

func Walk

func Walk(root string) ([]Op, error)

Walk discovers application rules under <root>/OPS/ on the local filesystem. `_`-prefixed system stacks (e.g. OPS/_sys/...) are excluded — they are loaded locally by the chassis, never pushed via the admin API, so every CLI/apply caller transparently skips them. Returns an empty slice (not an error) when OPS/ is missing. Diagnostics are discarded; use WalkDiag to surface them.

func WalkFS

func WalkFS(fsys fs.FS, root string) ([]Op, error)

WalkFS returns application ops only (system stacks excluded). Diagnostics are discarded; use WalkFSDiag to surface them.

func WalkSystemFS

func WalkSystemFS(fsys fs.FS, root string) ([]Op, error)

WalkSystemFS returns ONLY `_`-prefixed system ops (op.Stack keeps the full "_slug/stack" form; callers split via SystemSegment). Used by chassis/sysops to load trusted on-disk system opstacks from the same OPS/ tree. Diagnostics are discarded.