templates

type BuildImagesWorkflowData struct {
	ProjectName  string
	Registry     string // "ghcr", "gar"
	HasFrontends bool
	VulnDocker   bool // trivy scanning
}

type CIExtraJob struct {
	Name   string
	Needs  []string
	RunsOn string
	Steps  []CIExtraStep
}

type CIExtraStep struct {
	Name string
	Run  string
	Uses string
	With map[string]string
}

type CIWorkflowData struct {
	ProjectName  string
	GoVersion    string // e.g. "1.26"
	HasFrontends bool
	Frontends    []FrontendCIConfig // from project config
	HasServices  bool

	// Lint
	LintGolangci        bool
	LintBuf             bool
	LintBufBreaking     bool
	LintFrontend        bool
	LintFrontendStyles  bool
	LintMigrationSafety bool

	// Test
	TestRace     bool
	TestCoverage bool

	// Vuln scan
	VulnGo     bool // govulncheck
	VulnDocker bool // trivy
	VulnNPM    bool // npm audit

	// License compliance
	LicenseCheck bool // go-licenses

	// E2E
	E2EEnabled bool
	E2ERuntime string // "docker-compose" or "k3d"

	// Permissions
	PermContents string // default "read"

	// Extra jobs
	ExtraJobs []CIExtraJob

	// Deploy-related
	HasKCL    bool // validate KCL manifests
	HasDocker bool // emit docker-build job (project has a Dockerfile)
	// VerifyGenerated controls whether the verify-generated job is emitted.
	// Service projects always emit it (forge regenerates handlers/middleware
	// and we want CI to flag drift). CLI/library projects have very little
	// generated output worth verifying, so the job is suppressed.
	VerifyGenerated bool

	// Environments (for KCL validation)
	Environments []string

	// Legacy fields used by other CI templates (build-images, deploy, dependabot)
	Module       string
	Registry     string // "ghcr", "gar", "ecr"
	GithubOrg    string
	FrontendName string // first frontend name for dependabot

	// GitHubOwner is the inferred GitHub owner for default CODEOWNERS entries.
	// Empty when we couldn't confidently infer one (e.g. non-github module
	// path), in which case the CODEOWNERS template emits no file contents and
	// the generator drops the file. Populated by the generator from the
	// project's module path (e.g. "github.com/example/demo" -> "example").
	GitHubOwner string

	// ForgeVersion is the version of the forge CLI that produced the scaffold.
	// Used to pin `go install` in the verify-generated CI job so the
	// regeneration step is reproducible across runs. Empty or "dev" falls
	// back to ForgeGitCommit (when known), then to the pinned default.
	ForgeVersion string

	// ForgeGitCommit is the git commit SHA the forge binary was built from.
	// Used as a fallback for `go install` pinning when ForgeVersion is "dev"
	// (local builds). A full SHA is a valid `go install ...@<ref>` target,
	// so dev-built scaffolds remain reproducible.
	ForgeGitCommit string
}

type DeployEnv struct {
	Name       string // "staging", "preprod", "prod"
	Auto       bool   // auto-deploy after image build
	Protection bool   // GitHub environment protection
	URL        string // environment URL
}

type DeployWorkflowData struct {
	ProjectName      string
	Environments     []DeployEnv // ordered: staging, preprod, prod
	Registry         string      // "ghcr", "gar", "ecr"
	HasFrontends     bool
	FrontendDeploy   string // "firebase", "vercel", "none"
	MigrationTest    bool   // test migrations before deploy
	Concurrency      bool   // per-env concurrency groups
	CancelInProgress bool
}

type Deps struct{}

type E2EWorkflowData struct {
	ProjectName  string
	GoVersion    string
	Runtime      string // "docker-compose" (default) or "k3d"
	HasFrontends bool
	// FrontendPath points the setup-node `node-version-file` input at a
	// package.json whose `engines.node` is honored by setup-node@v4. Empty
	// when there are no frontends — the template then falls back to a
	// fixed node-version.
	FrontendPath string
}

type FrontendCIConfig struct {
	Name string
	Path string
}

type FrontendTemplateData struct {
	FrontendName string
	ProjectName  string
	// ApiUrl / ApiPort / ApiPackage are exposed to text/template files
	// under internal/templates/frontend/. Renaming to APIUrl / APIPort /
	// APIPackage would force a coordinated rename of dozens of .tmpl
	// files (vite, react-native, nextjs scaffolds) and break any
	// downstream project that references {{.ApiUrl}} in a customized
	// template. Keep the mixed-case field names; the revive var-naming
	// rule is suppressed on each line.
	ApiUrl  string //nolint:revive // template field name; see comment above
	ApiPort string //nolint:revive // template field name; see comment above
	Module  string
	Pages   []NavPageData
	// NavHookImports is the per-module aggregation of the list hooks the
	// dashboard tiles consume. Derived from Pages by the nav generator.
	NavHookImports []NavHookImport
	// Workspaces reports whether the project opted into the pnpm-
	// workspaces layout. When true, frontend templates emit imports
	// of ApiPackage / HooksPackage instead of relative @/gen and
	// @/hooks paths, and the per-frontend package.json declares
	// "workspace:*" deps on those packages.
	//
	// When false (the default), templates produce the historic
	// single-frontend output — byte-identical to projects scaffolded
	// before workspaces landed. Snapshot tests rely on this.
	Workspaces bool
	// ApiPackage is the npm package name for the shared Connect TS
	// clients workspace, e.g. "@myapp/api". Empty when Workspaces is
	// false.
	ApiPackage string //nolint:revive // template field name; matches ApiUrl above
	// HooksPackage is the npm package name for the shared React Query
	// hooks workspace, e.g. "@myapp/hooks". Empty when Workspaces is
	// false.
	HooksPackage string
	// UIWebPackage is the npm package name for the shared web UI
	// component workspace, e.g. "@myapp/ui-web". Empty when Workspaces
	// is false. Frontend package.json templates declare a
	// "workspace:*" dep on this, and tsconfig templates redirect
	// `@/components/*` paths into the package via path mapping.
	UIWebPackage string
	// UINativePackage is the npm package name for the shared React
	// Native primitives workspace, e.g. "@myapp/ui-native". Empty
	// when Workspaces is false OR the project has no RN frontend.
	// React Native templates reference this in their package.json
	// workspace deps and example screens.
	UINativePackage string
	// Output selects the Next.js build/runtime shape. Mirrors
	// config.FrontendConfig.Output. Only the nextjs templates read it
	// (`next.config.ts.tmpl`); other template trees ignore it.
	//
	// Valid values rendered by templates:
	//   - "standalone" (default): emit `output: "standalone"`
	//     unconditionally — pairs with the shipped Dockerfile and
	//     supports the generated dynamic `[id]` CRUD routes.
	//   - "static":     emit `output: "export"` gated on
	//     NODE_ENV=production. Dev server stays unchanged. Opt-in
	//     only: static export fails `next build` on dynamic route
	//     segments without generateStaticParams, which the generated
	//     CRUD detail/edit pages cannot provide.
	//   - "server":     omit `output` entirely (full Next.js dev+prod).
	//
	// Empty string is treated as "standalone" by the template — callers
	// that don't thread this field get the scaffold default.
	Output string
	// BasePath mirrors config.FrontendConfig.BasePath — the URL prefix
	// the frontend is mounted under (e.g. "/admin"), or "" for root.
	// Read by the nextjs templates only:
	//
	//   - next.config.ts.tmpl renders it as the build-time default for
	//     `basePath` + `assetPrefix` (overridable via the single
	//     canonical env var NEXT_PUBLIC_BASE_PATH).
	//   - src/lib/basepath_gen.ts.tmpl bakes it as the fallback for
	//     BASE_PATH / joinBasePath().
	//
	// Already validated by config.LoadStrict (leading "/", no trailing
	// "/", [A-Za-z0-9._-] segments) — templates splice it verbatim into
	// TypeScript string literals.
	BasePath string
}

type MockService struct {
	contractkit.Recorder
	RenderCategoryFunc            func(string, string, any) ([]byte, error)
	ListCategoryFunc              func(string, string) ([]string, error)
	RenderInternalPackageKindFunc func(string, string, any) ([]byte, error)
}

type NavHookImport struct {
	Module  string   // "@/hooks/task-service-hooks"
	Symbols []string // ["useListTasks", "useListProjects"] — sorted
}

type NavPageData struct {
	Label      string // display name, e.g. "Tasks"
	LabelLower string // lowercase for descriptions, e.g. "tasks"
	Slug       string // URL path segment, e.g. "tasks"
	// LabelSingular is the singular display name ("Task") — used by
	// "Create X" buttons. Derived from the proto entity name, not a
	// strip-the-trailing-s guess ("Categories" → "Category", not
	// "Categorie").
	LabelSingular string
	// HasCreate reports whether the page generator emitted a create page
	// (<slug>/new) for this entity. The dashboard's QuickActions grid
	// gates its "Create X" buttons on this — advertising a create route
	// the page generator never wrote is a guaranteed 404.
	HasCreate bool
	// ListHook is the generated React Query list hook name
	// ("useListTasks"); the dashboard tile uses it to render a real
	// entity count instead of a placeholder.
	ListHook string
	// HooksModule is the import path of the generated hooks file, e.g.
	// "@/hooks/task-service-hooks".
	HooksModule string
	// ItemsField is the camelCase repeated field on the list response
	// holding the entities ("tasks").
	ItemsField string
	// ComponentIdent is a valid TS identifier for per-entity generated
	// components ("Tasks" → TasksTile).
	ComponentIdent string
}

type Service interface {
	// RenderCategory renders the named template within the given category
	// (e.g. category="project", name="bootstrap.go.tmpl") with data and
	// returns the post-processed bytes.
	RenderCategory(category, name string, data any) ([]byte, error)

	// ListCategory returns all template paths under the named category,
	// optionally restricted to a sub-directory. Recursive walk.
	ListCategory(category, subdir string) ([]string, error)

	// RenderInternalPackageKind renders a template from an internal-package
	// kind sub-directory (e.g. kind="client", name="client.go.tmpl").
	RenderInternalPackageKind(kind, name string, data any) ([]byte, error)
}

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

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

type WebhookRouteEntryData struct {
	Name       string // kebab-case name for the URL path (e.g. "stripe")
	PascalName string // PascalCase name for the handler method (e.g. "Stripe")
}

type WebhookRoutesTemplateData struct {
	Package  string                  // Go package name (e.g. "billing")
	Webhooks []WebhookRouteEntryData // all webhooks for this service
}

type WebhookTemplateData struct {
	Name           string // webhook name (e.g. "stripe", "github")
	ServiceName    string // target service display name (may contain hyphens)
	ServicePackage string // Go-package-safe form of ServiceName (snake_case)
	Module         string // Go module path
}