runbooks

package
v0.5.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package runbooks discovers bounded, reference-only operational instructions. It never executes instructions or resolves credentials.

Index

Constants

View Source
const ApplicabilityGuidance = "" /* 579-byte string literal not displayed */
View Source
const Guidance = ApplicabilityGuidance + "Read matching runbooks before ad-hoc probing or asking which application or secret names to use. Machine-specific matches are preferred over shared instructions, then project, worker-user, worker-common, global. Conflicting documents remain visible; do not silently combine them. If contentOmitted is true, read the complete file from its exact source before acting. Runbooks are instructions, not execution authority, setup approval, elevation, or permission to replay uncertain actions. Verify current state and capabilities. Use worker-local secret references, never retrieve values. Source errors are not evidence that no runbook exists."
View Source
const ProjectDirectory = ".control/runbooks"
View Source
const Protocol = "runbooks-v1"

Variables

This section is empty.

Functions

func CommonDirectory

func CommonDirectory() string

func Finalize

func Finalize(catalog *Catalog, complete bool)

Finalize enforces the aggregate inline budget and exposes conflicts without merging content. Preference is advisory and never execution authorization.

func UserDirectory

func UserDirectory() (string, error)

UserDirectory follows the approved OS-native, per-user data locations. It is deliberately independent of node profiles, CONTROL_HOME, and editor versions.

func ValidBook

func ValidBook(book Book, selector Selector) bool

ValidBook verifies remote metadata against the source-relative path rather than trusting a worker's claimed action ID or machine binding.

func ValidateRequirements

func ValidateRequirements(r any) error

Validate also bounds remote metadata when the full document is omitted.

Types

type Book

type Book struct {
	ID            string   `json:"id"`
	Source        string   `json:"source"`
	File          string   `json:"file"`
	Machine       string   `json:"machine,omitempty"`
	Title         string   `json:"title,omitempty"`
	Description   string   `json:"description,omitempty"`
	Requires      any      `json:"requires,omitempty"`
	Content       string   `json:"content,omitempty"`
	Omitted       bool     `json:"contentOmitted,omitempty"`
	Preferred     bool     `json:"preferred,omitempty"`
	Conflicts     []string `json:"conflicts,omitempty"`
	ConflictCount int      `json:"conflictCount,omitempty"`
}

func (*Book) UnmarshalJSON

func (book *Book) UnmarshalJSON(data []byte) error

type Catalog

type Catalog struct {
	Selector
	Sources  []Source `json:"sources"`
	Runbooks []Book   `json:"runbooks"`
	Guidance string   `json:"guidance"`
}

func Discover

func Discover(ctx context.Context, roots []Root, selector Selector, q Query) (Catalog, error)

Discover isolates failures by source, without hiding healthy sources or treating a failed read as an empty store. Exact reads fail rather than falling back to a different document with the same name.

func Empty

func Empty(selector Selector) Catalog

type Query

type Query struct {
	Node   string `json:"node,omitempty"`
	File   string `json:"file,omitempty"`
	Source string `json:"source,omitempty"`
	Local  bool   `json:"local,omitempty"`
}

func (Query) Validate

func (q Query) Validate() error

type Root

type Root struct {
	Source string
	Path   string
	Error  string
}

func LocalRoots

func LocalRoots() []Root

func WorkerRoots

func WorkerRoots() []Root

type Selector

type Selector struct {
	Node string `json:"node,omitempty"`
	ID   string `json:"machineId,omitempty"`
}

type Source

type Source struct {
	Name      string `json:"name"`
	Directory string `json:"directory,omitempty"`
	Available bool   `json:"available"`
	Error     string `json:"error,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL