generator

type CommandContext struct {
	// Identity
	Name       string
	ParentPath []string // empty = direct child of root

	// Display
	Short string
	Long  string

	// Routing / feature options
	Aliases                       []string
	Args                          string
	WithAssets                    bool
	WithInitializer               bool
	WithConfigValidation          bool
	WrapSubcommandsWithMiddleware bool
	PersistentPreRun              bool
	PreRun                        bool
	Protected                     *bool
	Hidden                        bool

	// Project-level settings (carried from the originating generator)
	ProjectPath string
	DryRun      bool
	Force       bool
	UpdateDocs  bool
}

type CommandFlag struct {
	Default       string
	DefaultIsCode bool
	Description   string
	Hidden        bool
	Name          string
	Persistent    bool
	Required      bool
	Shorthand     string
	Type          string
}

type CommandPipeline struct {
	// contains filtered or unexported fields
}

type Config struct {
	Agentless  bool
	AIModel    string
	AIProvider string
	// MaxSteps bounds the autonomous repair agent's ReAct loop. Zero uses the
	// framework default (chat.DefaultMaxSteps). Raise it for complex commands
	// the agent cannot finish within the default budget.
	MaxSteps int
	// NonInteractive withholds the repair agent's query_user tool so a
	// generation never blocks for input (CI / --non-interactive).
	NonInteractive bool
	Aliases        []string
	Args           string
	DryRun         bool
	// GitInit controls the post-generation git step on `generate project`
	// (init + stage + initial commit). It is opt-out: the CLI sets it true by
	// default and false under --no-git. Only honoured by GenerateSkeleton.
	GitInit bool
	// GitPush, when true (--push), adds the derived remote as origin and pushes
	// the initial commit. Opt-in; requires GitInit. Push failures are non-fatal.
	GitPush bool
	// GitBranch is the default branch the initial commit lands on (default
	// "main", overridable via --git-branch).
	GitBranch                     string
	Flags                         []string
	Force                         bool
	Hidden                        bool
	Overwrite                     string // allow, deny, or ask (default ask)
	Long                          string
	Name                          string
	Parent                        string
	Path                          string
	PersistentPreRun              bool
	PreRun                        bool
	Prompt                        string
	Protected                     *bool
	ScriptPath                    string
	Short                         string
	UpdateDocs                    bool
	WithAssets                    bool
	WithConfigValidation          bool
	WithInitializer               bool
	WrapSubcommandsWithMiddleware *bool
}

type DryRunResult struct {
	Created  []FilePreview `json:"created,omitempty"`
	Modified []FilePreview `json:"modified,omitempty"`
	// Actions describes non-file side effects the run would perform (e.g. the
	// post-generation git init/commit/push), surfaced as plain text lines.
	Actions []string `json:"actions,omitempty"`
}

type FilePreview struct {
	Path    string `json:"path"`
	Content []byte `json:"content,omitempty"`
	Diff    string `json:"diff,omitempty"`
}

type Generator struct {
	// contains filtered or unexported fields
}

type IgnoreRules struct {
	// contains filtered or unexported fields
}

type Manifest struct {
	Properties    ManifestProperties    `yaml:"properties"`
	ReleaseSource ManifestReleaseSource `yaml:"release_source"`
	Version       ManifestVersion       `yaml:"version"`
	Hashes        map[string]string     `yaml:"hashes,omitempty"` // project-level file hashes (relative path → SHA256)
	Commands      []ManifestCommand     `yaml:"commands,omitempty"`
}

type ManifestCI struct {
	// ComponentSource is the include base for the phpboyscout/cicd
	// components in the scaffolded .gitlab-ci.yml. Empty means "use the
	// framework default" (DefaultCICDComponentSource,
	// gitlab.com/phpboyscout/cicd); a mirrored/self-hosted downstream sets
	// this to repoint the include base. Defaulted on render so a manifest
	// with no ci block still produces a complete pipeline.
	ComponentSource string `yaml:"component_source,omitempty"`
}

type ManifestCommand struct {
	Name                          string            `yaml:"name"`
	Description                   MultilineString   `yaml:"description"`
	LongDescription               MultilineString   `yaml:"long_description,omitempty"`
	Aliases                       []string          `yaml:"aliases,omitempty"`
	Hidden                        bool              `yaml:"hidden,omitempty"`
	Args                          string            `yaml:"args,omitempty"`
	Hash                          string            `yaml:"hash,omitempty"` // Deprecated: use Hashes
	Hashes                        map[string]string `yaml:"hashes,omitempty"`
	WithAssets                    bool              `yaml:"with_assets,omitempty"`
	WithInitializer               bool              `yaml:"with_initializer,omitempty"`
	WithConfigValidation          bool              `yaml:"with_config_validation,omitempty"`
	WrapSubcommandsWithMiddleware bool              `yaml:"wrap_subcommands_with_middleware,omitempty"`
	Protected                     *bool             `yaml:"protected,omitempty"`

	PersistentPreRun  bool              `yaml:"persistent_pre_run,omitempty"`
	PreRun            bool              `yaml:"pre_run,omitempty"`
	MutuallyExclusive [][]string        `yaml:"mutually_exclusive,omitempty"`
	RequiredTogether  [][]string        `yaml:"required_together,omitempty"`
	Flags             []ManifestFlag    `yaml:"flags,omitempty"`
	Commands          []ManifestCommand `yaml:"commands,omitempty"`
	Warning           string            `yaml:"-"` // Used for comments
}

type ManifestCommandUpdate struct {
	Name                          string
	Description                   string
	LongDescription               string
	Aliases                       []string
	Args                          string
	Hashes                        map[string]string
	Flags                         []ManifestFlag
	WithAssets                    bool
	WithInitializer               bool
	WithConfigValidation          bool
	WrapSubcommandsWithMiddleware *bool
	PersistentPreRun              bool
	PreRun                        bool
	Protected                     *bool
	Hidden                        bool
}

type ManifestFeature struct {
	Name    string `yaml:"name"`
	Enabled bool   `yaml:"enabled"`
}

type ManifestFlag struct {
	Name          string          `yaml:"name"`
	Type          string          `yaml:"type"`
	Description   MultilineString `yaml:"description"`
	Persistent    bool            `yaml:"persistent,omitempty"`
	Shorthand     string          `yaml:"shorthand,omitempty"`
	Default       string          `yaml:"default,omitempty"`
	DefaultIsCode bool            `yaml:"default_is_code,omitempty"`
	Required      bool            `yaml:"required,omitempty"`
	Hidden        bool            `yaml:"hidden,omitempty"`
	Warning       string          `yaml:"-"` // Used for comments
}

type ManifestHelp struct {
	Type         string `yaml:"type,omitempty"`
	SlackChannel string `yaml:"slack_channel,omitempty"`
	SlackTeam    string `yaml:"slack_team,omitempty"`
	TeamsChannel string `yaml:"teams_channel,omitempty"`
	TeamsTeam    string `yaml:"teams_team,omitempty"`
}

type ManifestProperties struct {
	Name        string            `yaml:"name"`
	Description MultilineString   `yaml:"description"`
	Features    []ManifestFeature `yaml:"features"`
	EnvPrefix   string            `yaml:"env_prefix,omitempty"`
	// UpdatePolicy is the generated tool's self-update posture baseline
	// (disabled / prompt / enabled). Empty = framework default (disabled).
	UpdatePolicy string `yaml:"update_policy,omitempty"`
	// UpdateCheckInterval is the generated tool's baseline self-update-check
	// throttle as a Go duration string (e.g. "24h"). Empty = framework
	// default (24h).
	UpdateCheckInterval string            `yaml:"update_check_interval,omitempty"`
	Help                ManifestHelp      `yaml:"help,omitempty"`
	Telemetry           ManifestTelemetry `yaml:"telemetry,omitempty"`
	Signing             ManifestSigning   `yaml:"signing,omitempty"`
	CI                  ManifestCI        `yaml:"ci,omitempty"`
	// Templates records the custom template-overlay sources applied to the
	// project, in render (layer) order: embedded base → templates[0] →
	// templates[1] → … (last writer wins for a shared path). Each entry is
	// provenance + pinning only; suppression behaviour lives in the source's
	// own gtb-template.yaml descriptor. See
	// docs/development/specs/2026-06-15-generator-custom-partial-templates.md.
	Templates []TemplateSource `yaml:"templates,omitempty"`
}

type ManifestReleaseSource struct {
	Type    string `yaml:"type"`
	Host    string `yaml:"host"`
	Owner   string `yaml:"owner"`
	Repo    string `yaml:"repo"`
	Private bool   `yaml:"private,omitempty"`
}

type ManifestSigning struct {
	// Enabled gates all signing scaffolding. Defaults to false; set true
	// by `gtb enable signing` or `gtb generate project --signing`.
	Enabled bool `yaml:"enabled,omitempty"`
	// ExternalKeyEmail derives the WKD URL and enables the external
	// (WKD) trust-anchor leg. Empty leaves verification embedded-only.
	ExternalKeyEmail string `yaml:"external_key_email,omitempty"`
	// RequireSignature fails an update closed when no valid signature is
	// present. Stays false until a signed release has shipped (the N+1
	// rollout); only ever flipped via `gtb enable signing --require-signature`.
	RequireSignature bool `yaml:"require_signature,omitempty"`
	// KeySource selects the trust-anchor source: "embedded", "external"
	// or "both" (the framework default when empty).
	KeySource string `yaml:"key_source,omitempty"`
	// RequireExternalCrosscheck fails closed when the external (WKD)
	// resolver is unreachable, rather than degrading to embedded-only.
	RequireExternalCrosscheck bool `yaml:"require_external_crosscheck,omitempty"`
	// Backend selects the `gtb sign` backend the generated release
	// pipeline signs with (e.g. "aws-kms", "local"). Defaults to
	// "aws-kms" when a key id is recorded. Drives the GoReleaser signs
	// block; backend-specific args (e.g. kms_region) are emitted only for
	// the backends that take them.
	Backend string `yaml:"backend,omitempty"`
	// KeyID is the backend-specific signing key identifier passed to
	// `gtb sign --key-id` (a KMS id/ARN/alias, or a PEM path for the
	// local backend). Recording it is what turns the GoReleaser signs
	// block on; empty leaves the release pipeline untouched.
	KeyID string `yaml:"key_id,omitempty"`
	// KMSRegion is the AWS region for the aws-kms backend
	// (`gtb sign --kms-region`). Defaults to "eu-west-2". Ignored by
	// backends that don't take a region.
	KMSRegion string `yaml:"kms_region,omitempty"`
	// PublicKey is the path to the armored public-key file the signature
	// identifies (`gtb sign --public-key`), relative to the project root.
	// Defaults to the embedded-key convention
	// internal/trustkeys/keys/signing-key-v1.asc.
	PublicKey string `yaml:"public_key,omitempty"`
}

type ManifestTelemetry struct {
	Endpoint     string `yaml:"endpoint,omitempty"`
	OTelEndpoint string `yaml:"otel_endpoint,omitempty"`
}

type ManifestVersion struct {
	GoToolBase string `yaml:"gtb"`
}

type MultilineString string

type PipelineOptions struct {
	SkipAssets        bool // do not generate asset files
	SkipDocumentation bool // do not run documentation generation
	SkipRegistration  bool // do not modify the parent cmd.go
}

type PipelineResult struct {
	Warnings []StepWarning
}

type SkeletonConfig struct {
	Name                  string
	Repo                  string
	Host                  string
	Description           string
	Path                  string
	GoVersion             string // overrides autodetected version when set
	Features              []ManifestFeature
	Private               bool   // true if the repository requires authentication to access
	HelpType              string // "slack", "teams", or ""
	SlackChannel          string
	SlackTeam             string
	TeamsChannel          string
	TeamsTeam             string
	TelemetryEndpoint     string          // populated from manifest telemetry.endpoint
	TelemetryOTelEndpoint string          // populated from manifest telemetry.otel_endpoint
	EnvPrefix             string          // environment variable prefix for config overrides
	Signing               ManifestSigning // self-update signature-verification posture (disabled by default)
	// UpdatePolicy is the generated tool's self-update posture baseline
	// (disabled / prompt / enabled). Empty leaves it unset so the framework
	// default (disabled) applies; wired into the generated root command's
	// props.Tool.UpdatePolicy. See docs/development/specs/2026-06-16-forced-update-feature.md.
	UpdatePolicy string
	// UpdateCheckInterval is the generated tool's baseline self-update-check
	// throttle as a Go duration string (e.g. "24h"). Empty leaves it unset so
	// the framework default (24h) applies; wired into the generated root
	// command's props.Tool.UpdateCheckInterval.
	UpdateCheckInterval string
	// CIComponentSource overrides the phpboyscout/cicd include base in the
	// scaffolded GitLab pipeline. Empty falls back to
	// DefaultCICDComponentSource. GitLab-only; ignored for GitHub projects.
	CIComponentSource string
	// Templates carries the custom template-overlay sources (in layer order)
	// through generation. The wizard/flags populate it and
	// writeSkeletonManifest persists it.
	Templates []TemplateSource
}

type StepWarning struct {
	Step string
	Err  error
}

type TemplateContractData struct {
	Name              string
	Description       string
	Repo              string
	Host              string
	Org               string
	RepoName          string
	ModulePath        string
	ReleaseProvider   string
	GoVersion         string
	GoToolBaseVersion string
	EnvPrefix         string
	EnabledFeatures   []string
	DisabledFeatures  []string
	Private           bool
	// SigningEnabled / HelpType expose only presence/shape, never secrets.
	SigningEnabled bool
	HelpType       string
}

type TemplateDescriptor struct {
	// Contract is the data-contract version the set targets. Zero is treated
	// as version 1 (the only version) for descriptors that omit it; any
	// value above supportedContractVersion is rejected.
	Contract int `yaml:"contract"`
	// Description is a human-facing summary of the template set.
	Description string `yaml:"description"`
	// Replaces names the embedded scaffolds this set supersedes. Each entry
	// must be a known alias in suppressibleAliases.
	Replaces []string `yaml:"replaces"`
}

type TemplateSource struct {
	// Name is an optional operator-assigned handle used by
	// `gtb template update/remove <name>`. Defaults to the repo/dir base
	// name when unset.
	Name string `yaml:"name,omitempty"`
	// Type is "git" or "local".
	Type TemplateSourceType `yaml:"type"`
	// Location is the forge repo path (org/repo, nested GitLab groups
	// supported) or a full clone URL for git sources, or a filesystem path
	// for local sources.
	Location string `yaml:"location"`
	// Ref is the branch/tag/commit the operator specified, recorded verbatim
	// (provenance). Empty/"" defaults to the source's default branch.
	Ref string `yaml:"ref,omitempty"`
	// Resolved is the commit SHA Ref resolved to at generate time — the pin
	// regenerate reproduces from. Empty for local sources.
	Resolved string `yaml:"resolved,omitempty"`
	// Fingerprint is a content fingerprint of a local source's tree at
	// generate time, so regenerate can warn when the on-disk source drifts.
	// Empty for git sources (the resolved SHA is the pin).
	Fingerprint string `yaml:"fingerprint,omitempty"`
	// Hashes records each rendered overlay file's SHA256 keyed by output
	// relative path, so a source's footprint is self-contained and can be
	// removed cleanly (D5).
	Hashes map[string]string `yaml:"hashes,omitempty"`
}

type TemplateSourceType string