Documentation
¶
Overview ¶
Package templates provides Go template definitions and data structures used by the generator to produce CLI command scaffolding, registration code (cmd.go), and implementation stubs (main.go). Template data types like CommandData carry the resolved configuration for each generated command.
Index ¶
- Constants
- Variables
- func Catalogue() []props.FeatureDescriptor
- func CatalogueEntry(name string) (props.FeatureDescriptor, bool)
- func CatalogueIn(e props.Enumerator) []props.FeatureDescriptor
- func CommandConfigValidation(data CommandData) string
- func CommandExecution(data CommandData) string
- func CommandInitializer(data CommandData) *jen.File
- func CommandRegistration(data CommandData) *jen.File
- func ConfigLayerConstName(name string) string
- func ExternalArgExpr(token string) jen.Code
- func FlagTypes() []string
- func FrameworkLinks() []props.FeatureDescriptor
- func IsExternalArgToken(tok string) bool
- func SkeletonChatProviders(providers, modules []string, withDefaults bool) *jen.File
- func SkeletonConfigFormats(modules []string) *jen.File
- func SkeletonExternalAdapter() string
- func SkeletonForgeAdapters(forges, modules []string) *jen.File
- func SkeletonInternalVersion() *jen.File
- func SkeletonLink(d props.FeatureDescriptor) *jen.File
- func SkeletonMain(modulePath string) *jen.File
- func SkeletonRoot(data SkeletonRootData) *jen.File
- func SkeletonSigning(data SkeletonSigningData) *jen.File
- func SkeletonTrustKeys() *jen.File
- type CommandData
- type CommandFlag
- type ConfigSourceData
- type SkeletonExternalCommand
- type SkeletonRootData
- type SkeletonSigningData
- type SkeletonSubcommand
Constants ¶
const SkeletonConfig = `` /* 625-byte string literal not displayed */
Variables ¶
var ExternalArgTokens = []string{"logger", "props", "config", "fs", "version"}
ExternalArgTokens is the closed injection vocabulary for the declarative external-command channel. Each token names a well-known dependency the generator can derive from the *props.Props value (p) when rendering an external constructor call onto the generated root.
The set is deliberately CLOSED (see https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0182-external-command-attachment): keeping it a fixed vocabulary — rather than a free-form Go expression — keeps the generated root type-safe and reviewable and prevents the manifest from becoming an arbitrary-code injection vector. Anything the vocabulary cannot express uses the adapter channel instead.
It is the SINGLE source of truth for the valid token set: the manifest validator (generator.validateExternalAttach) checks membership against it, and ExternalArgExpr renders each token, so the two sides cannot drift.
Functions ¶
func Catalogue ¶ added in v0.43.0
func Catalogue() []props.FeatureDescriptor
Catalogue is the ordered name<->constant<->default table for every scaffoldable feature, derived from the feature registry rather than written out (spec 0199 D6). The SetFeatures renderer, the manifest scanner, the feature toggles and the forge chooser all read it, so the mapping has one origin. The order is the snapshot's: built-ins as their constant block declares them, then the rest by kind and ID.
It was a hand-written table until the registry stopped sealing on read: deriving it at package init would have made every later RegisterFeature panic. A snapshot is safe to take at any time.
func CatalogueEntry ¶ added in v0.43.0
func CatalogueEntry(name string) (props.FeatureDescriptor, bool)
CatalogueEntry returns the catalogue row for name, if it is scaffoldable.
func CatalogueIn ¶ added in v0.43.0
func CatalogueIn(e props.Enumerator) []props.FeatureDescriptor
CatalogueIn is Catalogue over an enumeration of the caller's choosing.
func CommandConfigValidation ¶
func CommandConfigValidation(data CommandData) string
CommandConfigValidation generates the content for a config.go file containing a Config struct stub and a ValidateConfig function for per-package schema validation.
func CommandExecution ¶
func CommandExecution(data CommandData) string
func CommandInitializer ¶
func CommandInitializer(data CommandData) *jen.File
func CommandRegistration ¶
func CommandRegistration(data CommandData) *jen.File
func ConfigLayerConstName ¶
ConfigLayerConstName maps a manifest layer name to its exported props constant. Exported so the mapping can be asserted directly rather than only through rendered output.
func ExternalArgExpr ¶
ExternalArgExpr renders one injection token to the Go expression, derived from the props value p, that is passed to an external constructor. It is the render counterpart of ExternalArgTokens; an unknown token (which the manifest validator rejects before render) falls back to p so the render can never panic. The token set here and in ExternalArgTokens must stay in lockstep — guarded by a test.
func FlagTypes ¶ added in v0.43.0
func FlagTypes() []string
FlagTypes lists every manifest flag type the templates render, sorted. The empty type means "string" and is not listed.
func FrameworkLinks ¶ added in v0.43.0
func FrameworkLinks() []props.FeatureDescriptor
FrameworkLinks are the catalogue's link kinds that name a package to blank-import: the features a scaffold turns on by carrying cmd/<name>/<id>.go (keychain, mcp). A generated adapter link (chat-*, forge-*) names no package; the scaffold's own chat.go and forge.go declare those beside the imports they record (spec 0202 D6).
func IsExternalArgToken ¶
IsExternalArgToken reports whether tok is a member of the closed vocabulary.
func SkeletonChatProviders ¶ added in v0.42.0
SkeletonChatProviders generates cmd/<name>/chat.go: one blank import per chat provider module the manifest's chat.providers selects, and an init that declares the chosen providers as link features so the running tool knows the author's exact choice rather than everything the modules carry (#81). Deleting the file drops every chat SDK from the linked binary; regenerate rewrites it from the manifest (spec 0194 D6).
With withDefaults the file also embeds the sibling chat/ directory and registers it as an ai defaults bundle. The bundle is re-rooted with fs.Sub so its assets/config.yaml sits at the path the framework's defaults layer opens, the way the framework's own feature bundles are (spec 0196 D4).
func SkeletonConfigFormats ¶ added in v0.46.0
SkeletonConfigFormats renders cmd/<name>/config.go: one blank import per config format the tool links beyond YAML and per config source kind it declares (spec 0204 D2, D3).
func SkeletonExternalAdapter ¶
func SkeletonExternalAdapter() string
SkeletonExternalAdapter returns the source of the external-command adapter escape hatch (pkg/cmd/external/attach.go). Unlike most generated files this is author-owned: gtb scaffolds it once and never overwrites it (it is preserved across regenerate), so the author can attach external command trees of any shape the declarative vocabulary cannot express. The generated root spreads external.Commands(p) into NewCmdRoot, so returned commands still pick up the framework middleware pipeline.
func SkeletonForgeAdapters ¶ added in v0.42.0
SkeletonForgeAdapters generates cmd/<name>/forge.go: one blank import per forge adapter the manifest's enabled forge features need, and an init that declares those forges as link features (#81). Deleting the file drops every forge SDK from the linked binary; regenerate rewrites it from the manifest (spec 0194 D4, D6).
func SkeletonInternalVersion ¶
SkeletonInternalVersion generates the internal/version/version.go file for scaffolded projects, mirroring gtb's own internal/version pattern.
func SkeletonLink ¶ added in v0.43.0
func SkeletonLink(d props.FeatureDescriptor) *jen.File
SkeletonLink generates cmd/<name>/<id>.go for a framework link: a main package file whose only statement is the blank import of the package the descriptor names. The file is the feature: the manifest's entry writes or removes it through the shared sync, and a build without it links nothing the package reaches, which build info on the artefact can verify.
func SkeletonMain ¶
SkeletonMain generates the cmd/<name>/main.go for scaffolded projects. It uses the internal/version package to retrieve version info and passes it to the root command constructor. Execution is delegated to gtbRoot.Execute, which runs the command tree with a signal-aware context: SIGINT, SIGTERM and SIGHUP cancel cmd.Context() for graceful shutdown, a second signal ends the run at once, and a run a signal ended dies by that signal once drained, so a shell sees 128+signum.
func SkeletonRoot ¶
func SkeletonRoot(data SkeletonRootData) *jen.File
func SkeletonSigning ¶
func SkeletonSigning(data SkeletonSigningData) *jen.File
SkeletonSigning generates pkg/cmd/root/signing.go for scaffolded projects with signing enabled. It mirrors go-tool-base's own internal/cmd/root/signing.go split: an init() that sets the pkg/setup enforcement defaults, kept in a sibling file to the templated root command. The values come from the manifest signing block rather than being hand-written, so the author tunes posture via `gtb enable signing` flags, not by editing generated code.
Only non-default values are emitted, so a freshly enabled project (no email, require_signature off, default key source) produces an init() that does nothing until the author configures a posture.
func SkeletonTrustKeys ¶
SkeletonTrustKeys generates internal/trustkeys/trustkeys.go for scaffolded projects with signing enabled. It mirrors go-tool-base's own internal/trustkeys/trustkeys.go: a //go:embed of the keys directory plus a Keys() [][]byte accessor that walks keys/*.asc.
The package is generated and regeneration-protected; the author adds their minted release public key(s) as files under keys/, never by editing this .go. With no keys present Keys returns nil, so signature verification stays dormant until a real key is dropped in.
Types ¶
type CommandData ¶
type CommandData struct {
Package string
PascalName string
Name string
Aliases []string
Args string
Short string
Long string
Hidden bool
WithAssets bool
Flags []CommandFlag
PersistentFlags []CommandFlag
AncestralPersistentFlags []CommandFlag
MutuallyExclusive [][]string
RequiredTogether [][]string
Logic string
Imports []string
// ModulePath is the project's module, so its own packages sort into the
// local import group the scaffold's goimports config expects.
ModulePath string
FullFileContent string
TestCode string
Recommendations []string
PersistentPreRun bool
PreRun bool
HasSubcommands bool
// PureGroup marks a command that only groups its subcommands and so has no
// run logic of its own — see Generator.pureGroup for how it is decided.
// Such a command gets no Run<Name>, and its RunE is the framework's.
PureGroup bool
WithInitializer bool
WithConfigValidation bool
Hashes map[string]string
// MCPExposure controls whether the generated command stamps a
// setup.ExcludeFromMCP / setup.IncludeInMCP marker. The zero value
// (Inherit) emits nothing.
MCPExposure setup.MCPExposure
// MCPHints are rendered as one setup.AnnotateMCP call after the exposure
// marker, listing only the fields that are set. Zero emits nothing.
MCPHints setup.MCPHints
}
type CommandFlag ¶
type ConfigSourceData ¶ added in v0.46.0
ConfigSourceData is one declared config source slot as the root renders it.
type SkeletonExternalCommand ¶
type SkeletonExternalCommand struct {
ImportPath string // e.g. "gitlab.com/phpboyscout/go/signing-cli"
PkgAlias string // e.g. "signingcli"
Constructor string // e.g. "NewCmdSign"
Args []string // injection tokens, e.g. ["logger"]
Wrap bool // wrap in setup.Wrap("", …)
}
SkeletonExternalCommand describes one external constructor (the declarative attachment channel) to render as an argument to NewCmdRoot. Args are injection tokens from the closed vocabulary (ExternalArgTokens); the template resolves each via ExternalArgExpr. When Wrap is true the constructor returns *cobra.Command and is wrapped in setup.Wrap("", …); otherwise it returns *setup.Command and is attached directly. Declarative attachments are un-gated, so the wrap label is always the empty string.
type SkeletonRootData ¶
type SkeletonRootData struct {
Name string
Description string
ReleaseProvider string
ReleaseBaseURL string // the static channel's base URL (spec 0203 D1)
Host string
Org string
RepoName string
Private bool
DisabledFeatures []string
EnabledFeatures []string
HelpType string // "slack", "teams", or ""
SlackChannel string
SlackTeam string
TeamsChannel string
TeamsTeam string
TelemetryEndpoint string
TelemetryOTelEndpoint string
EnvPrefix string
// ConfigLayers wires props.Tool.ConfigLayers in the generated root. Empty
// means the project states nothing and inherits the framework default, so
// no field is emitted — keeping generated output byte-identical for every
// project that does not care.
ConfigLayers []string
// ConfigFormat is the tool's own config format; empty is YAML.
ConfigFormat string
// ConfigKeyCase is the config stack's key mode. Only "exact" emits a
// field: folded is the default, so a folded root renders as before.
ConfigKeyCase string
// ConfigSources are the declared config source slots (spec 0204 D15).
ConfigSources []ConfigSourceData
// UpdatePolicy wires props.Tool.UpdatePolicy in the generated root. Empty
// (or "disabled") leaves the field off so the framework default applies;
// "prompt"/"enabled" emit the matching props.UpdatePolicy* constant.
UpdatePolicy string
// UpdateCheckInterval wires props.Tool.UpdateCheckInterval as a Go duration
// string (e.g. "24h"). Empty, unparseable, or non-positive values leave the
// field off so the framework default (24h) applies.
UpdateCheckInterval string
// MCPMode wires props.Tool.MCP. Only "direct" emits a field: compact is the
// zero value, so every root generated before the field says compact.
MCPMode string
// SigningEnabled gates the Signing: props.SigningConfig{...} block.
// When true the generated tool wires trustkeys.Keys() as its embedded
// trust anchor; ModulePath supplies the import path for that package.
SigningEnabled bool
ModulePath string
// AutoInitialise wires props.Tool.Bootstrap.AutoInitialise. When true the
// generated tool auto-runs a non-interactive init if config is missing.
AutoInitialise bool
// SkipConfigCheck wires props.Tool.Bootstrap.SkipConfigCheck — commands
// (by Name() or full CommandPath()) whose missing-config gate is relaxed.
SkipConfigCheck []string
// AuxiliaryCommands wires props.Tool.Bootstrap.AuxiliaryCommands, the
// commands that take the root pre-run's fast path (spec 0197 D4).
AuxiliaryCommands []string
// RequireChecksum wires props.Tool.Signing.RequireChecksum when the author
// set it; false leaves the framework default (spec 0197 D4).
RequireChecksum bool
Subcommands []SkeletonSubcommand
// ExternalCommands are declarative external-module attachments rendered as
// additional NewCmdRoot arguments (see the external-command-attachment spec).
ExternalCommands []SkeletonExternalCommand
// ExternalAdapter, when true, spreads external.Commands(p) — the user-owned
// adapter escape hatch at <ModulePath>/pkg/cmd/external — into NewCmdRoot.
ExternalAdapter bool
}
type SkeletonSigningData ¶
type SkeletonSigningData struct {
ExternalKeyEmail string
RequireSignature bool
KeySource string // "embedded" | "external" | "both"; empty → framework default
RequireExternalCrosscheck bool
}
SkeletonSigningData carries the manifest signing posture into the generated signing.go enforcement defaults.
type SkeletonSubcommand ¶
type SkeletonSubcommand struct {
ImportPath string // e.g. "github.com/org/repo/pkg/cmd/serve"
PkgAlias string // e.g. "serve"
Constructor string // e.g. "NewCmdServe"
}
SkeletonSubcommand describes a top-level command that must be registered in the generated NewCmdRoot function.
Source Files