factory

type AuditAPI struct {
	// Ingress computes the ingress category: renders the dev-env KCL and
	// cross-checks routes against forge.yaml backends.
	Ingress func(cfg *config.ProjectConfig, projectDir string) audittype.Category

	// ExternalBuilds computes the external-builds category: renders dev-env
	// KCL, enumerates build_cmd services, cross-checks cwd / env-key
	// conflicts / recorded build state.
	ExternalBuilds func(cfg *config.ProjectConfig, projectDir string) audittype.Category

	// Prerequisites computes the declared-external-prerequisites category:
	// renders dev-env KCL, enumerates forge.ExternalSecret / forge.DNSRecord
	// declarations, and surfaces the checklist + the cross-secret byte-match
	// group consistency.
	Prerequisites func(cfg *config.ProjectConfig, projectDir string) audittype.Category

	// ListEnvs lists the project's declared environments (deploy/kcl/<env>).
	ListEnvs func(projectDir string) ([]string, error)

	// ProjectDefinesConnectServices reports whether the project declares any
	// Connect service (drives whether the shape category parses RPC counts).
	ProjectDefinesConnectServices func(projectDir string) bool

	// ScanProjectDriftPaths returns the project-relative paths of forge-
	// certified files whose embedded hash no longer matches (user-edited gen
	// files), for the codegen category.
	ScanProjectDriftPaths func(projectDir string, cs *generator.FileChecksums) []string

	// LoadProjectStoreFrom loads a ProjectStore from an explicit forge.yaml
	// path (audit resolves the path itself rather than walking up).
	LoadProjectStoreFrom func(path string) (*projectstore.Store, error)
}

type CmdFactory func(f *Factory) *cobra.Command

type Factory struct {
	// Out is the writer for user-facing stdout output.
	Out io.Writer
	// Err is the writer for diagnostics / stderr output.
	Err io.Writer
	// In is the reader for interactive prompts.
	In io.Reader

	// LoadProjectStore loads forge.yaml (walking up from cwd) into a
	// ProjectStore — the single read+mutate surface. The heavy config-parsing
	// logic lives in internal/cli (config.go); the factory carries it as a
	// function value so group subpackages can read project config without
	// importing internal/cli (which would cycle: internal/cli blank-imports
	// the groups). internal/cli wires this in factory.New's caller via
	// SetProjectStoreLoader.
	LoadProjectStore func() (*projectstore.Store, error)

	// Gen is the clean, narrow surface over the generate pipeline + service
	// registry that the dir-nested `add` group calls. The heavy
	// implementation (the ~80-file generate pipeline, the services.go AST
	// parser) lives in internal/cli; the factory carries it as function
	// values so internal/cli/scaffold can trigger codegen and read the
	// registration view without importing internal/cli (which would cycle —
	// internal/cli blank-imports the groups). internal/cli registers the
	// concrete implementation via SetGenAPI from its init().
	Gen GenAPI

	// Audit is the narrow surface the dir-nested `audit` group calls for the
	// categories it cannot compute without package-cli internals — the
	// KCL-entity-typed ingress / external-builds categories (which depend on
	// the KCL render + entity structs shared by ~12 cli files), plus the
	// service-registry / env-discovery / drift / connect-service helpers.
	// Each field keeps the heavy impl in internal/cli; the group gets
	// neutral results (audittype.Category, []string, …). internal/cli
	// registers the concrete implementation via SetAuditAPI from its init().
	Audit AuditAPI
}

type GenAPI struct {
	// HoldProjectLock takes the project's cross-process generate lock
	// (.forge/forge.lock) and returns its release. It blocks — printing one
	// line naming the holder — while another forge generate or scaffold run
	// in the same project holds it. The scaffold group holds it for each
	// command's whole run, so the command's own writes and the pipeline run
	// it ends with never interleave with another run's. Not reentrant.
	HoldProjectLock func(projectDir string) (release func(), err error)

	// ObserveProjectLock is HoldProjectLock for a run that writes nothing
	// (--dry-run): it waits while a writer holds the lock and keeps writers
	// out until release, but creates no .forge/forge.lock and records no
	// holder, so the dry run leaves the tree byte-identical.
	ObserveProjectLock func(projectDir string) (release func(), err error)

	// RunPipeline runs the FULL generate pipeline for the project rooted at
	// projectDir (the equivalent of `forge generate`), serialized under the
	// internal/cli generate mutex. The caller must already hold
	// HoldProjectLock for projectDir — every scaffold command does. Used by
	// `scaffold service` / `scaffold operator`.
	//
	// A run that reached the end with failed steps returns a
	// *StepsFailedError: its writes stand, so a caller must not undo its
	// own writes as it would after a run that aborted and rolled back.
	RunPipeline func(projectDir string) error

	// RunPipelineBootstrapOnly runs the generate pipeline narrowed to the
	// "bootstrap-only" step preset (regenerates pkg/app/{bootstrap,testing,
	// migrate}.go and nothing else), serialized under the generate mutex.
	// Same lock contract as RunPipeline. Used by `scaffold worker`.
	RunPipelineBootstrapOnly func(projectDir string) error

	// LoadServiceRegistry parses the user-owned pkg/app/services.go and
	// returns the registration view. Used by `scaffold service` / `scaffold webhook` /
	// `scaffold rpc` to print accurate registration nudges and to gate the
	// types-only (tombstoned) case.
	LoadServiceRegistry func(projectDir string) (ServiceRegistry, error)

	// ServiceRegistryRelPath is the project-relative path of the user-owned
	// registration file (pkg/app/services.go), surfaced so the group's
	// messages name it without duplicating the constant.
	ServiceRegistryRelPath string

	// IsConnectServiceConfig reports whether a component is a Connect
	// service (vs worker/cron/operator/binary). Used by `scaffold webhook` to
	// gate the registration nudge to serving binaries.
	IsConnectServiceConfig func(c config.ComponentConfig) bool

	// WriteScenariosIndex regenerates the frontend mock-scenario barrel
	// (scenarios/index) at the project-relative scenariosRel inside root.
	// Used by `scaffold scenario`. The barrel is Tier-1 — regenerated
	// whenever the directory's contents change — so it is written through
	// the certification chokepoint and needs the project's ownership state.
	WriteScenariosIndex func(root, scenariosRel string, cs *generator.FileChecksums) error

	// RunPackageNew is the `forge package new` RunE, reused verbatim by
	// `scaffold package` and `scaffold adapter` (which pre-sets --type).
	RunPackageNew func(cmd *cobra.Command, args []string) error
}

type ServiceRegistry interface {
	// Exists reports whether the registration file is present. When false,
	// every service reads as registered (fail-open pre-migration behavior).
	Exists() bool
	// Registered reports whether this binary serves the named service.
	Registered(name string) bool
	// Tombstoned reports whether the named service is deliberately retired
	// (mentioned in a comment but with no serviceRow reference).
	Tombstoned(name string) bool
}

type StepsFailedError struct {
	// Steps names each failed step, in the order they failed.
	Steps []string
}