templates

type BuildImagesWorkflowData struct {
	ProjectName string
	// BuildEnv is the env the once-per-commit image is built for: the first
	// deploy env in promotion order, whose KCL-declared registry the image
	// is pushed to. The workflow names no registry — forge reads it from
	// deploy/kcl/<BuildEnv>/main.k.
	BuildEnv string
	// No frontend fields: frontend IMAGES are per-env (each renders that
	// env's config.js), so deploy.yml builds them, and `forge build <env>
	// --target <project>` builds the project image alone — no frontend's
	// `npm run build` — so this job needs no Node toolchain.
	VulnDocker bool // trivy scanning

	// Hosted says BuildEnv pushes to the PLATFORM registry, which changes
	// what the job has to supply: nothing. forge authenticates that registry
	// with the control-plane credential it already resolves (ADR-0003 F3), so
	// a hosted job carries FORGE_CONTROL_PLANE_TOKEN — which it needs anyway
	// — and no registry credential, no --username and no --password-stdin.
	//
	// It is a per-env fact and not a project-wide one: a project may build
	// its per-commit image for a cluster env and promote releases through
	// hosted ones, and only the env this job builds for decides.
	Hosted bool
}

type CIWorkflowData struct {
	ProjectName  string
	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"

	// 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.
	VerifyGenerated bool
	// RunsBufGenerate is true when `forge generate` runs `buf generate` on
	// this project. verify-generated reruns generate, so it installs buf
	// exactly then. The mapper sets it from the generate pipeline's own
	// gate condition, whatever the project kind.
	RunsBufGenerate bool

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

	// Legacy fields used by other CI templates (build-images, deploy, dependabot)
	Module       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

	// GolangciLintVersion is the golangci-lint release the lint job pins.
	// Left empty by every caller and filled by withDefaults with
	// GolangciLintVersion, so a new construction site cannot ship `latest`.
	GolangciLintVersion string

	// BufVersion is the buf release the checks job installs. Filled by
	// withDefaults with BufVersion for the same reason.
	BufVersion string
}

type DependabotData struct {
	// FrontendName is the first frontend's name. Empty emits no npm entry.
	FrontendName string
	// RunsProtocGenGo is true when `forge generate` runs protoc-gen-go —
	// a service-kind project with codegen on. Only then does a
	// google.golang.org/protobuf bump change generated output, so only
	// then is it kept out of Dependabot.
	RunsProtocGenGo bool
}

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 are the envs the project DECLARES (deploy/kcl/<env>/main.k,
	// dev excluded), ordered along the promotion path. Never a hard-coded
	// list: a job for an env with no main.k fails on every run.
	Environments []DeployEnv
	HasFrontends bool
	// FrontendPath is the first frontend's directory: setup-node reads its
	// package.json `engines.node`, and its frozen install there installs
	// what `forge build <env>` needs to build it.
	FrontendPath string
	// Frontend is that first frontend, for its package manager.
	Frontend         FrontendCIConfig
	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
	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
	// Frontend is that first frontend, for its package manager.
	Frontend FrontendCIConfig
}

type EnvTemplateData struct {
	// Roots is a composition-graph project: a workload's config env comes
	// from config_gen.workloadEnvMap, which gives one bound to a root
	// (`root = "server"`) exactly what the root reaches.
	Roots       bool
	ProjectName string
	EnvName     string
	// PrimaryWorkload names the workload holding the dev env's
	// `<project>-<env>-api` port key — the port the frontend's dev config
	// reads. The API, `_api` (codegen.APIWorkloadName), unless a caller says
	// otherwise.
	PrimaryWorkload string
	// IngressEnabled wires the dev env's Gateway. A hosted env has no
	// ingress of its own (the platform allocates every public hostname), so
	// the cloud template only points at its ingress.k for a cluster you
	// operate.
	IngressEnabled bool
	HasFrontend    bool
	// DatabaseDisabled omits database infrastructure in a database-free project.
	DatabaseDisabled bool
	FrontendName     string
	// FrontendIdent is the KCL identifier of that frontend: the cloud env
	// declares it once as `_<ident>_frontend` and binds it on one line
	// (`_hosted_frontend(_<ident>_frontend)`), the line `forge env new
	// --bind` rewrites.
	FrontendIdent  string
	FrontendRoutes []string
	// FrontendPath is the frontend's directory relative to the project root:
	// frontends/<name> for a scaffolded one, "." for a site adopted in place
	// (`forge project new --in-place --kind site`), whose app IS the root.
	FrontendPath string
	// FrontendType is the KCL forge.Frontend.type to declare ("vite",
	// "nextjs"); empty leaves the schema default (nextjs) implicit.
	FrontendType string
	// FrontendPublicDir is where the static build lands, relative to
	// FrontendPath: "out" for a Next.js static export, "dist" for Vite.
	FrontendPublicDir string
	// Bindings is the body of the env's `_workloads = [...]` list: one
	// `        _<binder>(wl.<ident>)` line per workload. EnvBinding renders one.
	Bindings string
	// APIWorkload is a hosted env's `_api` declaration — the project
	// binary's `server` as the one workload serving every service
	// (codegen.APIWorkloadStanza). The cloud template only.
	APIWorkload string
	// Claimable is a prod env scaffolded for an anonymous deploy (`forge
	// project new --claimable`): `control_plane` declares `claimable = True`
	// and the hosted binder sizes services and jobs to the claimable plan.
	// The cloud template only.
	Claimable bool
	// ClaimableResources is the body of that plan's largest shape as a KCL
	// fw.Resources block (deploy.ClaimableLimitsFallback), filled by withDefaults
	// so the template states no number of its own.
	ClaimableResources string
	// ClaimableShape is that shape for prose ("125m / 128 MiB"), and
	// ClaimableDatabaseStorageGiB the database storage it declares.
	ClaimableShape              string
	ClaimableDatabaseStorageGiB int32
	// ClaimableDBConnections is that database's max_connections, and
	// ClaimableDBPool the pool each workload is held to inside it.
	ClaimableDBConnections int
	ClaimableDBPool        int
	// Capacity floor of the cloud envs' (unused as scaffolded) `_on_cluster`
	// binder.
	Replicas         int
	CPURequest       string
	CPULimit         string
	MemoryRequestMiB int
	MemoryLimitMiB   int
}

type FrontendCIConfig struct {
	Name string
	Path string
	// PackageManager owns the frontend's install: "pnpm", "npm" or "yarn".
	// Empty means pnpm, the manager a scaffolded frontend pins.
	PackageManager string
}

type FrontendTemplateData struct {
	FrontendName string
	ProjectName  string
	// Platform names the frontend template tree being rendered —
	// "nextjs", "vite-spa" or "react-native". It exists so a template
	// under frontend/shared* (rendered into every tree that claims it)
	// can gate the one or two lines that genuinely differ per platform
	// instead of being forked into N near-identical copies. Today the
	// only gate is the Next.js App Router's `"use client"` prologue.
	//
	// Set by the frontend scaffolder from the resolved tree name, so it
	// cannot drift from the roots being composed. Empty when a caller
	// renders a single per-kind template directly (nav, dashboard,
	// apiurl_gen, …) — those live under one tree and never gate on it.
	Platform string
	// APIURL and APIPackage are exposed to text/template files under
	// internal/templates/frontend/, so their Go field names are the
	// template variable names: a customized .tmpl referencing {{.ApiUrl}}
	// must be updated to {{.APIURL}}. forge carries no backwards
	// compatibility — the rename is the record.
	//
	// (ApiPort was removed when the hand-editable .env.local scaffolds were
	// ripped out — the only consumers were those templates'
	// `http://localhost:{{.ApiPort}}` lines; the regenerated apiurl_gen.ts
	// bakes the full APIURL instead.)
	APIURL string
	Module string
	Pages  []NavPageData
	// HasTypedConfig reports whether this frontend has a config message
	// bound to it by (forge.v1.frontend_config). When true, templates read
	// their settings through the generated src/lib/config_gen.ts — values
	// delivered at RUNTIME by the KCL-rendered config.js — instead of
	// build-time-inlined NEXT_PUBLIC_* / VITE_* env vars.
	//
	// It gates rather than replaces because frontend config is OPT-IN: a
	// project that declares no frontend-bound message keeps the previous
	// env-var behavior byte-for-byte, so adopting this is a proto edit and
	// nothing else.
	HasTypedConfig bool
	// Has<Field> reports which well-known fields that message actually
	// declares. A template cannot reference cfg.MOCK_API when the proto
	// never declared it — the generated module's type would not have the
	// key and `tsc` would fail — so each read is gated on its own field
	// being present.
	//
	// There is no OIDC gate here, and that is deliberate: browser sign-in
	// is NATIVE (credentials POSTed to this app's own API, HttpOnly cookie
	// back, server runs the OIDC flow), so no issuer, client id, redirect
	// URI, scope list or resource indicator is ever delivered to a bundle.
	// Handing the browser those values is what would let a browser-side
	// PKCE flow — and a script-readable token — come back.
	HasMockAPI bool
	// 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
	// WebRuntimeTypePins are the packages a frontend's tsconfig must pin
	// to its OWN copy, so tsc sees one identity per type.
	//
	// A plain []string, not a type from another package: this struct is a
	// TEMPLATE PAYLOAD, so its fields are the values the templates render
	// and nothing more. Whoever computes the list owns its meaning; this
	// package only writes it out.
	//
	// Left nil by every caller today, and filled by withDefaults. It stays
	// a field rather than a method so a caller CAN pin a different set —
	// which is what makes the default a default and not a wall.
	WebRuntimeTypePins []string
	// WebRuntimePinsHoisted selects WHICH node_modules the pins above point
	// at: the project root's (true) or the frontend's own (false, the
	// default).
	//
	// It exists because a `paths` value for a non-wildcard key must hold
	// EXACTLY ONE element — SWC panics `next build` otherwise — so the
	// emitter cannot list both layouts and let the toolchain choose. See
	// webruntimepeers.TypePinPath.
	//
	// True when an npm workspace hoists the frontend's dependencies to the
	// project root, which is what forge's own dev bridge creates.
	WebRuntimePinsHoisted 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
	// 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:
	//   - "static":     emit `output: "export"` gated on
	//     NODE_ENV=production (the scaffold default; callers resolve it
	//     before rendering). Dev server stays unchanged. The generated
	//     CRUD pages are static routes, so the export builds.
	//   - "standalone": emit `output: "standalone"` unconditionally —
	//     the Node server the standalone Dockerfile runs.
	//   - "server":     omit `output` entirely (full Next.js dev+prod).
	//
	// Empty string renders the standalone arm, which is what an empty
	// forge.yaml `output:` has always meant
	// (config.FrontendConfig.EffectiveOutput). A NEW frontend never
	// reaches the template empty: GenerateFrontendFilesWithOptions
	// resolves "" to config.FrontendOutputScaffoldDefault first.
	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().
	//   - Dockerfile mounts a static export under it, as the StaticSite
	//     deploy does.
	//
	// Already validated by config.LoadStrict (leading "/", no trailing
	// "/", [A-Za-z0-9._-] segments) — templates splice it verbatim into
	// TypeScript string literals.
	BasePath string
	// RepoPath is the frontend's directory relative to the project root
	// ("frontends/web"), slash-separated. The nextjs Dockerfile builds at
	// /src/<RepoPath> so every relative path the committed config carries —
	// tsconfig's `../../node_modules/…` pins above all — means inside the
	// image what it means in the repository. Empty falls back to
	// frontends/<FrontendName>, where the scaffolder writes every frontend.
	RepoPath string
	// Public renders the frontend WITHOUT a sign-in gate (auth_mode: none):
	// providers.tsx / routes.tsx mount no RouteGuard and the Vite tree
	// declares no /auth/sign-in route. See generator.FrontendGenOptions.Public.
	Public bool
}

type FrontendTreeFile struct {
	// Rel is the path relative to the generated frontend root, with any
	// .tmpl suffix still attached (e.g. "src/lib/events.ts",
	// "src/lib/auth/context.tsx.tmpl").
	Rel string
	// Path is the path within the frontend template category, ready to
	// hand to FrontendTemplates().Render (e.g. "shared/src/lib/events.ts").
	Path 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
	// HasTotalCount / TotalCountField expose the List response's server-side
	// total ("totalCount") when the RPC declares one. The dashboard tile
	// counts with THIS, never with the length of the page it fetched: a
	// tile reading `data.tasks.length` reports the page size once the table
	// outgrows one page ("25" forever), and it is forge's own generated
	// exemplar that teaches the habit to everything downstream.
	HasTotalCount   bool
	TotalCountField string
	// HasPageSize reports whether the List request carries page_size. The
	// tile asks for ONE row when it does — the count comes from
	// total_count, so pulling a full page of entities to display a single
	// number is waste on every dashboard load.
	HasPageSize bool
	// ComponentIdent is a valid TS identifier for per-entity generated
	// components ("Tasks" → TasksTile).
	ComponentIdent string
}

type ReleaseStage struct {
	Env DeployEnv
	// Prev is the stage promoted from (empty for the first, which is
	// promoted by version). Its job's promotion id is --from-promotion.
	Prev string
	// Next is the stage after this one (empty for the last). This job
	// captures Next's current promotion BEFORE Next's approval wait, so
	// Next's deploy can assert it with --expect-current.
	Next string
	// Mixed is set for an env that also applies a cluster/compose part from
	// CI. Its stage always deploys client-side — a control plane converges
	// only what it hosts — and writes the kubeconfig that deploy needs.
	Mixed bool
}

type ReleaseWorkflowData struct {
	ProjectName string
	// BuildEnv is the hosted env the release's images are built and cut
	// against (the first in promotion order): its declared registry and
	// control plane are where the bytes and the release live.
	BuildEnv string
	// Stages are the hosted envs, in promotion order, one job each. The
	// first is promoted by version; every later one `--from` the stage
	// before it, so a release reaches prod exactly as it ran on the stage
	// before. Prev/Next are precomputed here rather than derived with index
	// arithmetic in YAML, so the chain is testable Go and the template stays
	// readable.
	Stages []ReleaseStage
}

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
	// ConfigImport is the import path of the config the service's Deps
	// takes (`Config *config.Config`), "" when it takes none; the test
	// passes a Config only then. ConfigImportAlias is "config" when the
	// path's last segment is not, so the test can spell config.Config.
	ConfigImport      string
	ConfigImportAlias string
}