Documentation
¶
Overview ¶
Package cmdframework parses, hashes, and tracks the bundled Claude slash-command markdowns that tai ships and that `tai install` writes into ~/.claude/commands/tai/.
What lives here:
- Frontmatter — strict line-oriented parser for the six-key YAML frontmatter shape every bundled command uses. Stdlib-only — a full YAML library is intentionally avoided per the foundation proposal's "stdlib first" rule.
- Body extractor — returns the body bytes (everything after the closing `---` line), preserving any trailing newline.
- Hash — sha256 over the body bytes, formatted as `sha256:<64-lower-hex>`. The deterministic identity for a command's content.
- Ledger — the access contract for the cumulative per-command hash history. The concrete storage and population mechanism is owned by add-install-command; this package only exposes `Ledger(verb)` returning the historical hashes, oldest-first.
The hash and ledger machinery exists so `tai install` can classify a target file as missing / up-to-date / stale-but-untouched / user-modified before deciding whether to overwrite (see add-install-command/specs/install/spec.md).
Index ¶
- Variables
- func Body(src []byte) ([]byte, error)
- func BundleBody(verb string) ([]byte, error)
- func BundleHash(verb string) (string, error)
- func BundleSource(verb string) ([]byte, error)
- func HashBody(body []byte) string
- func HashSource(src []byte) (string, error)
- func Ledger(verb string) []string
- func LedgerStrict(verb string) ([]string, error)
- func Verbs() []string
- type Frontmatter
Constants ¶
This section is empty.
Variables ¶
var BundleFS embed.FS
BundleFS is the embedded view of internal/cmdframework/commands/. The install command, the build-time hash invariant test, and the `Ledger` reader all walk through this single seam so production behaviour and the test suite exercise the same byte sequences.
The `all:` prefix is necessary so the directory is embedded even before any `<verb>.md` files exist — the README placeholder is always present and keeps the build green during bootstrap.
Functions ¶
func BundleBody ¶
BundleBody returns the body bytes of `commands/<verb>.md` (post-frontmatter, trailing newline preserved). Returns fs.ErrNotExist when verb is not a recognised bundled command.
func BundleHash ¶
BundleHash returns the sha256:<hex> body hash for verb's bundled markdown.
func BundleSource ¶
BundleSource returns the raw bytes of `commands/<verb>.md` (frontmatter + body, exactly as installed). Returns fs.ErrNotExist when verb is not a recognised bundled command.
func HashBody ¶
HashBody returns the sha256:<hex> identity for body bytes.
The body bytes are passed verbatim — no normalisation, no trim. A trailing newline produces a different hash from no trailing newline, because byte-level content is what `tai install` compares.
func HashSource ¶
HashSource parses src and returns HashBody of the extracted body.
func Ledger ¶
Ledger returns the cumulative history of content_hash values ever shipped for the named verb's slash-command markdown. Order is oldest-first; the LAST element is the hash of the current build's commands/<verb>.md body (a property the build-time test enforces).
Unknown verbs and corrupt ledgers return an empty slice — this preserves the foundation's pre-bundle API for callers that don't need diagnostic detail. Callers that need to surface a corrupt ledger to the user MUST call LedgerStrict.
func LedgerStrict ¶
LedgerStrict returns the cumulative hash history for verb, oldest-first, with full corruption diagnostics.
When the ledger file is absent, the returned slice is empty (this signals "no history" — every disk file is treated as user-modified). When the ledger IS present but malformed, the returned error is a *errcode.Error{Code: InstallLedgerCorrupt} so callers route the failure through the standard error contract.
func Verbs ¶
func Verbs() []string
Verbs returns the names of every bundled verb in this build, sorted alphabetically.
A verb is recognised when BOTH `commands/<verb>.md` and `commands/<verb>.ledger.json` are present in the embedded FS. The `README.md` placeholder is filtered out because it has no matching ledger file.
Types ¶
type Frontmatter ¶
type Frontmatter struct {
Name string
Description string
Category string
Tags []string
Version int
ContentHash string
}
Frontmatter is the structured shape of a bundled slash-command's frontmatter. Every bundled command MUST include exactly these six fields; extras are rejected at parse time.
func Parse ¶
func Parse(src []byte) (Frontmatter, []byte, error)
Parse splits a slash-command markdown blob into its frontmatter and body components. It returns the parsed Frontmatter, the body bytes (preserving any trailing newline, excluding the closing `---` line), and any error.
Errors:
- Missing leading `---` delimiter
- Missing closing `---` delimiter
- Unknown / extra top-level keys
- Missing required keys
- Malformed values (non-string where string expected; non-int version; content_hash not matching sha256:<64-lower-hex>)
- version < 1
Source Files