advancedcatalog

package
v0.46.5 Latest Latest
Warning

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

 Go to latest Published: Sep 25, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package advancedcatalog is the single source of truth for the Advanced operations catalog (stackkit.advanced-operations/v1): every Advanced operation an orchestrator such as Techstack may dispatch to the stackkit CLI, with its exact argv template, admission requirements, input and result contracts, rollout event phases and denial envelope.

The catalog is rendered to docs/data/advanced-operations/latest.json by `stackkit docs emit-advanced-operations` and shipped in every release archive. The command package tests prove that every available entry's argv resolves to a registered command and flags, so the catalog cannot drift from the CLI.

Index

Constants

View Source 
const (
	SchemaVersion = "stackkit.advanced-operations/v1"
	// DefaultPath is the committed catalog, relative to the repository root
	// and to the root of every release archive.
	DefaultPath = "docs/data/advanced-operations/latest.json"
	// SchemaPath is the JSON Schema of the catalog document.
	SchemaPath = "schemas/stackkit-advanced-operations-v1.schema.json"
	Program    = "stackkit"

	// SincePending marks an entry that no published release carries yet.
	SincePending = "pending"

	StatusAvailable = "available"
	StatusPlanned   = "planned"

	// Non-capability operation IDs. Capability operation IDs are the
	// internal/advancedcapability constants.
	OperationTrustImport         = "advanced.trust.import"
	OperationTrustInspect        = "advanced.trust.inspect"
	OperationDriftDetectAdvanced = "drift.detect.advanced"
)
View Source 
const (
	AdmissionAllowed       = "allowed"
	AdmissionDenied        = "denied"
	AdmissionCapability    = "capability"
	AdmissionOwnerApproval = "owner-approval"
)

Mode admission values.

View Source 
const (
	CommandResultSchemaVersion      = "stackkit.command-result/v1"
	CommandResultSchema             = "schemas/stackkit-command-result-v1.schema.json"
	RolloutEventSchemaVersion       = "stackkit.rollout-event/v1"
	RolloutEventSchema              = "schemas/stackkit-rollout-event.schema.json"
	OperationDenialSchemaVersion    = "stackkit.operation-denial/v1"
	OperationDenialSchema           = "schemas/stackkit-operation-denial-v1.schema.json"
	ActionableErrorSchemaVersion    = "stackkit.actionable-error/v1"
	ActionableErrorSchema           = "schemas/stackkit-actionable-error-v1.schema.json"
	TrustBundleSchemaVersion        = advancedcapability.TrustBundleSchemaVersion
	TrustBundleSchema               = "schemas/stackkit-advanced-trust-bundle-v1.schema.json"
	LocalTrustSchemaVersion         = "stackkit.local-advanced-trust/v1"
	LocalTrustSchema                = "schemas/stackkit-local-advanced-trust-v1.schema.json"
	CapabilitySchemaVersion         = advancedcapability.SchemaVersion
	CapabilitySchema                = "schemas/stackkit-advanced-capability-v1.schema.json"
	ChangeSetSchemaVersion          = "stackkit.advanced-change-set/v2"
	ChangeSetRecordSchema           = "schemas/stackkit-advanced-change-set-v2.schema.json"
	ChangeSetCreateResultSchema     = "schemas/stackkit-advanced-change-set-create-result-v2.schema.json"
	AdvancedMutationSchemaVersion   = "stackkit.advanced-mutation/v1"
	AdvancedMutationSchema          = "schemas/stackkit-advanced-mutation-v1.schema.json"
	ChangeSetResultSchemaVersion    = "stackkit.change-set-result/v1"
	ChangeSetResultSchema           = "schemas/stackkit-change-set-result-v1.schema.json"
	DriftReportSchemaVersion        = "stackkit.drift-report/v1"
	DriftReportSchema               = "schemas/stackkit-drift-report-v1.schema.json"
	RestoreDrillReportSchemaVersion = "stackkit.restore-drill-report/v1"
	RestoreDrillReportSchema        = "schemas/stackkit-restore-drill-report-v1.schema.json"
)

Contract schema versions and their schema files, relative to the repository and release archive root.

View Source 
const (
	RollbackResultSchemaVersion = "stackkit.rollback-result/v1"
	RollbackResultSchema        = "schemas/stackkit-rollback-result-v1.schema.json"
)

Variables

This section is empty.

Functions

func Render 

func Render() ([]byte, error)

Render returns the deterministic catalog bytes.

func ValidateJSON 

func ValidateJSON(schemasDir, schemaFile string, document []byte) error

ValidateJSON validates a JSON document against a schema file under schemasDir. Relative $refs resolve to sibling files in schemasDir, so the contract schemas are checked exactly as they ship.

Types

type Catalog 

type Catalog struct {
	SchemaVersion string         `json:"schemaVersion"`
	Program       string         `json:"program"`
	Description   string         `json:"description"`
	CommandResult CommandResult  `json:"commandResult"`
	RolloutEvents RolloutEvents  `json:"rolloutEvents"`
	Denial        Denial         `json:"denial"`
	GlobalArgs    []OptionalArgs `json:"globalArgs"`
	Placeholders  []Placeholder  `json:"placeholders"`
	Operations    []Operation    `json:"operations"`
}

Catalog is the stackkit.advanced-operations/v1 document.

func New 

func New() Catalog

New returns the catalog. Entries are sorted by operation ID.

type CommandResult 

type CommandResult struct {
	ContractRef
	Statuses []string `json:"statuses"`
	// NoEnvelope states what a missing envelope means.
	NoEnvelope string `json:"noEnvelope"`
}

CommandResult describes the stdout envelope of every `--json` invocation.

type ContractRef 

type ContractRef struct {
	SchemaVersion string `json:"schemaVersion"`
	Schema        string `json:"schema"`
}

ContractRef names a versioned JSON document and its schema file.

type Denial 

type Denial struct {
	ContractRef
	CommandResultStatus string       `json:"commandResultStatus"`
	ReasonCodes         []ReasonCode `json:"reasonCodes"`
}

Denial is the structured denial envelope an orchestrator must handle.

type EventPhase 

type EventPhase struct {
	Phase    string   `json:"phase"`
	Match    string   `json:"match"`
	Statuses []string `json:"statuses"`
}

EventPhase is one rollout event phase (exact) or phase family (prefix).

type Input 

type Input struct {
	Placeholder string `json:"placeholder"`
	ContractRef
	Description string `json:"description"`
}

Input binds an argv placeholder to the document contract it names.

type Modes 

type Modes struct {
	Standard string `json:"standard"`
	Advanced string `json:"advanced"`
}

Modes records admission per lifecycle mode: standard is the local Owner-governed mode without a capability, advanced is the capability-gated mode an orchestrator dispatches.

type Operation 

type Operation struct {
	Operation    string `json:"operation"`
	Status       string `json:"status"`
	SinceRelease string `json:"sinceRelease"`
	Summary      string `json:"summary"`
	// Command is the exact command path reported in the command-result
	// `command` field. Empty for planned entries.
	Command      string         `json:"command,omitempty"`
	Argv         []string       `json:"argv"`
	OptionalArgs []OptionalArgs `json:"optionalArgs"`
	Mutates      bool           `json:"mutates"`
	Requires     Requirements   `json:"requires"`
	Inputs       []Input        `json:"inputs"`
	Results      []Outcome      `json:"results"`
	Events       []EventPhase   `json:"events"`
	Modes        Modes          `json:"modes"`
}

type OptionalArgs 

type OptionalArgs struct {
	Argv        []string `json:"argv"`
	Description string   `json:"description"`
}

OptionalArgs are argv words an orchestrator may append.

type Outcome 

type Outcome struct {
	Status string `json:"status"`
	ContractRef
	Description string `json:"description,omitempty"`
}

Outcome is the data payload of one command-result status.

type Placeholder 

type Placeholder struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Pattern     string `json:"pattern,omitempty"`
}

type ReasonCode 

type ReasonCode struct {
	Code        string `json:"code"`
	Description string `json:"description"`
}

type Requirements 

type Requirements struct {
	Capability          bool   `json:"capability"`
	CapabilityOperation string `json:"capabilityOperation,omitempty"`
	TrustImported       bool   `json:"trustImported"`
	OwnerApproval       bool   `json:"ownerApproval"`
	CandidateSpec       bool   `json:"candidateSpec"`
	ChangeSet           bool   `json:"changeSet"`
}

type RolloutEvents 

type RolloutEvents struct {
	ContractRef
	Argv        []string `json:"argv"`
	Description string   `json:"description"`
}

RolloutEvents describes the JSONL progress stream.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.