generator

func AppendFrontendToConfig ¶

func AppendFrontendToConfig(projectRoot, frontendName string, port int) error

AppendFrontendToConfig reads the project config at the given project root, appends a new frontend entry, and writes it back. It uses yaml.Node round-tripping so that unknown keys, comments, and field ordering added by the user are preserved.

func AppendFrontendToConfigWithKind ¶

func AppendFrontendToConfigWithKind(projectRoot, frontendName string, port int, kind string) error

AppendFrontendToConfigWithKind is like AppendFrontendToConfig but accepts a kind parameter ("web" or "mobile") to select the frontend type.

func AppendServiceToConfig ¶

func AppendServiceToConfig(projectRoot, serviceName string, port int) error

AppendServiceToConfig is RETIRED: forge no longer writes a components.json manifest — services are discovered from the proto descriptor. It stays as a no-op because it is part of the ConfigService contract (interface + mock); callers in the add/new flow may still invoke it, but it never touches disk.

func EnsureCoreComponents ¶

func EnsureCoreComponents(frontendDir string) error

EnsureCoreComponents installs any missing core components into an existing frontend directory. Safe to call repeatedly — only writes files that don't already exist.

func ForUpgrade ¶

func ForUpgrade(cfg *config.ProjectConfig, projectDir string) projectTemplateData

ForUpgrade builds the render payload for the upgrade / Tier-1 regeneration lane from a *config.ProjectConfig. It reproduces, verbatim, the derivations the old buildTemplateData performed.

projectDir (when non-empty) is used to read the project's go.mod `go` directive so upgrade doesn't silently retarget the project to the host's Go version, to parse proto/config for the live ConfigFields set, and to detect the dev-mode .forge-pkg/ vendoring state. When projectDir is empty or go.mod can't be parsed, we fall back to the host's detected version.

func GenerateBinaryFiles ¶

func GenerateBinaryFiles(root, modulePath, binaryName string) error

GenerateBinaryFiles emits the files that make up a non-server long-running binary scaffold:

• cmd/<package>/main.go thin standalone main (own cmd/<bin>/ tree)
• internal/<package>/<package>.go main loop with Start/Stop/Run lifecycle
• internal/<package>/contract.go Deps, Service interface, New(deps)
• internal/<package>/<package>_test.go basic lifecycle test

The shape is deliberately opinionated: the scaffold solves the boilerplate (signal handling, graceful shutdown, config loading) so the user can hand-write only the binary's actual business logic.

Each binary gets its OWN cmd/<bin>/ tree (devspace idiom): the primary server binary lives under cmd/<server>/ with the full command tree, and each secondary binary added here gets cmd/<package>/main.go — a thin, self-contained main rather than a subcommand of the server. At deploy time KCL emits one Deployment per binary, each running its own image.

CLI/display name (which may contain hyphens) is translated to a Go- package-safe form for the directory and `package` declaration; the hyphenated form is preserved on the cobra `Use:` field.

func GenerateCRDFiles ¶

func GenerateCRDFiles(in CRDGenInput) error

GenerateCRDFiles scaffolds a single CRD into an existing operator:

• api/<version>/<lower-name>_types.go — CRD spec/status types
• internal/operators/<operator>/<lower-name>_controller.go — thin shim
• internal/operators/<operator>/<lower-name>_controller_test.go — fake-client unit test

The operator must already exist; generation is idempotent in the sense that re-running with the same inputs overwrites the three generated files (no merge), but it does NOT rebuild the operator's types.go (placeholder CRD or otherwise).

func GenerateE2ETests ¶

func GenerateE2ETests(projectDir, serviceName, modulePath, projectName string, methods []E2EMethodInfo) error

GenerateE2ETests renders E2E test templates into e2e/<servicePackage>/ under projectDir. It does not overwrite existing files — only creates new ones.

func GenerateEntitySeeds ¶

func GenerateEntitySeeds(entities []SeedEntity, outputDir string) error

GenerateEntitySeeds generates SQL seed files and JSON fixture files for the given entities. SQL files go to <outputDir>/db/seeds/0002_<table>.sql and JSON files go to <outputDir>/db/fixtures/<table>.json.

func GenerateFrontendFiles ¶

func GenerateFrontendFiles(root, modulePath, projectName, frontendName string, apiPort int, kind string) error

GenerateFrontendFiles generates the frontend directory and files. kind selects the template set: "" or "web" for Next.js, "mobile" for React Native. Both the "new" project flow and the "add frontend" flow delegate here so the output is always identical.

This thin shim preserves the original signature for backward compatibility with the Service contract; new call sites should prefer GenerateFrontendFilesWithOptions when they have access to the project-level Frontend config.

func GenerateFrontendFilesWithOptions ¶

func GenerateFrontendFilesWithOptions(root, modulePath, projectName, frontendName string, apiPort int, kind string, opts FrontendGenOptions) error

GenerateFrontendFilesWithOptions is GenerateFrontendFiles with an extra FrontendGenOptions param for project-level toggles (today only Workspaces). The default-zero opts struct produces output byte-identical to GenerateFrontendFiles so existing callers and snapshot tests are unaffected.

func GenerateGrafanaDashboards ¶

func GenerateGrafanaDashboards(projectName, projectDir string) error

GenerateGrafanaDashboards is the standalone entry point callable from both `forge new` (via ProjectGenerator) and `forge generate`. It writes Grafana dashboards and provisioning config into deploy/observability/grafana/.

func GenerateOperatorBinaryOnly ¶

func GenerateOperatorBinaryOnly(root, modulePath, name, group, version string) error

GenerateOperatorBinaryOnly scaffolds an operator package WITHOUT a placeholder CRD. CRDs are added via `forge add crd <name>` instead, which produces per-CRD shims that delegate to forge/pkg/controller.

The generator emits two files:

• internal/operators/<package>/doc.go — package documentation that explains the operator's role and points users at `forge add crd`.

• internal/operators/<package>/operator.go — the wiring symbols (Controller, Deps, New, AddToScheme) that the bootstrap template expects every operator package to export. The Controller type is a thin holder for the manager-level deps and is not itself a reconciler — per-CRD reconcilers live in <crd>_controller.go and are wired in cmd/<op>/main.go.

The operator's main.go (the cmd binary entrypoint) is generated by the standard project bootstrap step.

func GenerateOperatorFiles ¶

func GenerateOperatorFiles(root, modulePath, name, group, version string) error

GenerateOperatorFiles generates all files for a single operator:

• internal/operators/<package>/types.go (from operator/types.go.tmpl)
• internal/operators/<package>/controller.go (from operator/controller.go.tmpl)
• internal/operators/<package>/controller_test.go (from operator/controller_test.go.tmpl)

The CLI/display name (which may contain hyphens) is translated to a Go-package-safe form for the directory and `package` declaration.

Both the "new project" and "add operator" flows delegate here so the generated output is always identical.

func GenerateOperatorFilesWithAPI ¶

func GenerateOperatorFilesWithAPI(root, modulePath, name, group, version, apiPackage, crdType string) error

GenerateOperatorFilesWithAPI is GenerateOperatorFiles with explicit overrides for the CRD type's Go package name and type name. This is the path used when the operator name and CRD type diverge — e.g. a `workspace-controller` operator reconciling a `Workspace` CRD. When apiPackage and crdType are both empty this behaves identically to GenerateOperatorFiles.

apiPackage selects the Go-package directory + `package` declaration for the CRD types. When empty, the CRD types live in the operator's own package (the original shape). When set, types are written to api/<version>/<apiPackage>/types.go with `package <apiPackage>`, and the controller imports them from there. crdType selects the Go type name; when empty it defaults to PascalCase(apiPackage) when apiPackage is set, or PascalCase(name) otherwise (preserving original behaviour).

func GeneratePlanORM ¶

func GeneratePlanORM(root, modulePath, serviceName string, entities []config.PlanEntity, cs *FileChecksums) error

GeneratePlanORM writes internal/db/<snake_name>_orm.go for each entity defined in the plan. The generated files provide a Bun-tagged entity struct (a projection of the applied schema) and standalone CRUD functions built on Bun's query builder (reached via orm.Context.Bun()). CRUD is emitted as package-level functions that take an orm.Context, so the same functions run inside or outside a transaction.

cs is the project's checksum tracker: every output is recorded as a Tier-1 manifest entry so `forge disown` can transfer ownership of an ORM file (kalshi fr-4dfef712e9: disown refused on internal/db/*_orm.go because nothing registered them) and `forge audit` doesn't see the files as orphans. A nil cs is tolerated (files written, not tracked).

func GeneratePlanProtoFile ¶

func GeneratePlanProtoFile(root, modulePath, serviceName string, rpcs []config.PlanRPC, entities []config.PlanEntity) error

GeneratePlanProtoFile writes a populated proto file for a service based on plan RPC definitions and entity messages. It overwrites any existing proto stub at proto/services/<name>/v1/<name>.proto.

When entities are provided, their message definitions are emitted inline in the service proto (before the RPC request/response messages) so that CRUD RPCs can reference them by bare name.

When forge.yaml at `root` declares `api.rest: true`, CRUD-prefixed RPCs (Get/List/Create/Update/Delete<Entity>) are emitted with default `google.api.http` annotations so vanguard can transcode REST↔Connect at runtime. Non-CRUD RPCs are left unannotated and need the user to add annotations by hand. The `google/api/annotations.proto` import is added to the proto only when at least one CRUD RPC was annotated.

func GenerateServiceFiles ¶

func GenerateServiceFiles(root, modulePath, serviceName, projectName string, port int) error

GenerateServiceFiles generates all files for a single Go service:

• handlers/<servicePackage>/service.go (from service/service.go.tmpl)
• proto/services/<servicePackage>/v1/<servicePackage>.proto (inline stub, skipped if exists)

The display/CLI form of the service name (which may contain hyphens) is translated to a Go-package-safe form ("admin-server" -> "admin_server") for filesystem directories and Go/proto identifiers. Display strings keep the original spelling.

Both the "new project" and "add service" flows delegate here so the generated output is always identical.

handlers.go is intentionally not emitted at scaffold time: with zero RPC methods there is nothing for it to contain. Once RPCs are added to the proto file, `forge generate` produces handlers_gen.go; the user then moves those stubs to handlers.go (or any other file) as they implement them.

func GenerateServiceFilesWithMode ¶

func GenerateServiceFilesWithMode(root, modulePath, serviceName, projectName string, port int, mode ScaffoldMode, progress io.Writer) error

GenerateServiceFilesWithMode is the mode-aware form of GenerateServiceFiles. `mode` controls per-file overwrite/skip behavior so callers can support --resume (recover a partially-applied scaffold) and --force (re-stamp every output file). When non-nil, `progress` receives one human-readable line per scaffolding step so the CLI can render "skipped" / "overwriting" notices without re-implementing the existence check.

func GenerateWebhookFiles ¶

func GenerateWebhookFiles(root, modulePath, serviceName, webhookName string) error

GenerateWebhookFiles generates all files for a webhook endpoint within a service:

• internal/handlers/<service>/webhook_<name>.go (handler + signature verification)
• internal/handlers/<service>/webhook_<name>_test.go (tests)
• internal/handlers/<service>/webhook_store.go (idempotency store, only if not present)

func GenerateWorkerFiles ¶

func GenerateWorkerFiles(root, modulePath, workerName, kind, schedule string) error

GenerateWorkerFiles generates all files for a single worker:

• internal/workers/<package>/worker.go (from worker/worker.go.tmpl or worker-cron/worker.go.tmpl)
• internal/workers/<package>/worker_test.go (from worker/worker_test.go.tmpl or worker-cron/worker_test.go.tmpl)

The CLI/display name (which may contain hyphens) is translated to a Go-package-safe form for the directory and `package` declaration so hyphenated worker names like "email-sender" produce a buildable internal/workers/email_sender/ package.

When kind is "cron", the cron-specific templates are used and the schedule is embedded as a constant in the generated code.

Both the "new project" and "add worker" flows delegate here so the generated output is always identical.

func HashContent ¶

func HashContent(content []byte) string

HashContent returns the sha256 hex digest of content.

func ReadProjectConfig ¶

func ReadProjectConfig(path string) (*config.ProjectConfig, error)

ReadProjectConfig reads a forge.yaml from the given path with strict validation: unknown keys, missing required fields, and type mismatches are surfaced together via config.ValidationError rather than failing fast on the first issue. The per-component entities are read from the project-root components.json sibling of forge.yaml and the project kind is derived from them (see config.LoadProject). See config.LoadStrict for the full validation semantics.

func RecordFrozenChecksums ¶

func RecordFrozenChecksums(projectDir, binary, kind string) error

RecordFrozenChecksums re-stamps the embedded forge:hash marker on every marker-bearing managed file at projectDir. Exposed publicly so callers outside the scaffold path (e.g. `forge new` after `bootstrapGeneratedCode` runs goimports and reformats files) can re-certify the post-formatting bytes — otherwise the hashes stamped at scaffold time would not match the on-disk content, and the drift guard / `forge upgrade --dry-run` would flag every formatted file as user-modified.

func RegenerateInfraFiles ¶

func RegenerateInfraFiles(projectDir string, cfg *config.ProjectConfig) error

RegenerateInfraFiles regenerates all Tier 1 (always-overwrite) infrastructure files. Called by forge generate to keep infrastructure in sync with templates.

The cmd/<bin>/cmd command tree (root.go, serve.go, server.go, version.go, db.go) is part of this Tier-1 set, keyed off the project name so the per-binary destPaths resolve. cmd/<bin>/main.go is NOT — it is the composition root, owned by the generate pipeline (GenerateCmdGroups), which has the component inventory this path lacks.

func RegenerateInfraFilesTracked ¶

func RegenerateInfraFilesTracked(projectDir string, cfg *config.ProjectConfig, cs *FileChecksums) error

RegenerateInfraFilesTracked is RegenerateInfraFiles routed through the checksums chokepoint. With a non-nil cs every Tier-1 infra write:

• honors disowned entries (the user ran `forge disown`: the write is skipped while the file exists — the raw os.WriteFile path this replaces violated the "forge never regenerates user-owned files" contract for cmd/*.go and friends);
• records the render hash + WrittenThisRun so the stale sweep and the next run's drift guard see an accurate manifest;
• tags the entry Tier-1 (these files ARE regenerated every run).

force=true preserves the historical always-overwrite semantics for forge-owned files: the Tier-1 stomp guard ran earlier in the pipeline, so any surviving drift was already adjudicated (--force / disown).

A nil cs falls back to untracked writes (legacy callers).

func SaveChecksums ¶

func SaveChecksums(root string, cs *FileChecksums) error

SaveChecksums persists the project ownership state. Empty state deletes the files — no bookkeeping churn in the steady state.

func Tier2ManagedPaths ¶

func Tier2ManagedPaths() map[string]bool

Tier2ManagedPaths returns the set of project-relative paths whose canonical template tier is Tier-2 (scaffold-once, user-owned after the first write). It is the source of truth for `forge generate`'s tier-migration step (generate_tier_migrate.go in internal/cli): a `.forge/checksums.json` entry for one of these paths that still carries tier=1 (or the legacy unset tier=0) predates the template's reclassification and must be flipped to tier=2 so the file stops being drift-guarded and stops surfacing as a "fork".

Two sources:

• The managed-file registry entries tagged Tier2. A destPath's tier is invariant across the (kind, binary) matrix — only the source template varies — so the union over combinations is safe (same posture as UpgradeManagedPaths).
• The one-shot .github scaffolds written once at `forge new` time (project_ci.go) and never re-emitted by `forge generate`. CODEOWNERS even carries the `yours: scaffolded once ... (starter)` banner; recording them as Tier-1 was a historical accident that made hand-editing your own CODEOWNERS trip the Tier-1 stomp guard. (FRICTION 2026-06-05, cp-forge: users worked around the misclassification by hand-flipping `forked: true`.)

Deliberately NOT in this set: .github/workflows/e2e.yml and .github/dependabot.yml — those are re-rendered by `forge generate`'s CI step when enabled, so Tier-1 is their honest tier.

func UpgradeManagedPaths ¶

func UpgradeManagedPaths() map[string]bool

UpgradeManagedPaths returns the set of project-relative paths that `forge upgrade` (not `forge generate`) is responsible for emitting. Used by `forge generate`'s stale-artifact sweep to exclude these paths from the "stale codegen" candidate list: they're tracked in `.forge/checksums.json` but only re-rendered by upgrade, so seeing them missing from this run's WrittenThisRun set is the expected state, not a stale signal.

The set is the union over every (kind, binary) combination. Forge only ships a small number of these combinations so the union is cheap; computing the union (rather than asking the caller for the project's specific kind/binary) keeps the helper signature simple and means a kind/binary mismatch in detection doesn't accidentally flag a managed file as stale.

FRICTION 2026-06-05 (cp-forge audit-cleanup agent): `forge generate` warned 7 "stale" files — .github/CODEOWNERS, .golangci.yml, cmd/main.go, cmd/db.go, cmd/version.go, .github/workflows/e2e.yml, .github/pull_request_template.md — all of which are managed by `forge upgrade`. The user worked around it by hand-flipping `forked: true` in checksums.json, which silenced the warnings but also disconnected the files from the upgrade pipeline. The right fix is for the stale-sweep to know about the upgrade-managed set.

func WriteFrontendWorkspaceFiles ¶

func WriteFrontendWorkspaceFiles(projectDir, projectName string, workspaces bool) error

WriteFrontendWorkspaceFiles emits the workspace-layout scaffolding:

• pnpm-workspace.yaml at the project root
• packages/api/package.json + tsconfig.json + .gitignore
• packages/hooks/package.json + tsconfig.json + use-api-{query,mutation}.ts
• packages/ui-web/package.json + tsconfig.json + src/components/*.tsx

Idempotent: writes files only if they do not already exist, so re- running `forge generate` after the user customizes (e.g.) the packages/api/package.json does not clobber their edits.

Returns nil immediately when workspaces is disabled — callers can invoke unconditionally and let this function decide whether work is needed.

func WriteGeneratedFile ¶

func WriteGeneratedFile(root, relPath string, content []byte, cs *FileChecksums, force bool) (bool, error)

WriteGeneratedFile writes a Tier-1 file through the certification chokepoint. See checksums.WriteGeneratedFile for full semantics.

func WriteGeneratedFileTier1 ¶

func WriteGeneratedFileTier1(root, relPath string, content []byte, cs *FileChecksums, force bool) (bool, error)

WriteGeneratedFileTier1 writes a Tier-1 (regenerated-every-run, self-certifying) file. See checksums.WriteGeneratedFileTier1.

func WriteProjectConfigFile ¶

func WriteProjectConfigFile(cfg *config.ProjectConfig, path string) error

WriteProjectConfig writes a config.ProjectConfig to the given path. The config is normalized first (config.NormalizeForWrite): values that match their shape-derived defaults are dropped so load → mutate → write round-trips keep forge.yaml minimal instead of materializing every derived default back into the file. Explicit overrides (values differing from derivation) always survive.

func WriteScaffoldIfMissing ¶

func WriteScaffoldIfMissing(root, relPath string, content []byte) (bool, error)

WriteScaffoldIfMissing writes a scaffold ("yours", user-owned) file only when it does not already exist; once on disk forge never overwrites it. See checksums.WriteScaffoldIfMissing.

func WriteUINativePackageFiles ¶

func WriteUINativePackageFiles(projectDir string, layout FrontendWorkspaceLayout) error

WriteUINativePackageFiles emits the packages/ui-native/ scaffold:

• packages/ui-native/package.json (workspace member)
• packages/ui-native/tsconfig.json (no DOM lib, React JSX)
• packages/ui-native/src/tokens.ts (design tokens)
• packages/ui-native/src/index.ts (re-export barrel)
• packages/ui-native/src/components/<primitive>.tsx (one per primitive)
• packages/ui-native/README.md

Idempotent: write-if-missing throughout. Once a user edits a primitive (or rewrites the tokens), `forge generate` will not clobber the edit — the package is effectively scaffolded once and owned by the project after.

Guarded by the two preconditions documented at the call sites in generate_pipeline.go and add.go:

1. `frontend.workspaces: true`
2. At least one frontend with `type: react-native`

When either is false this function should not be called (callers gate); calling it directly still works but emits files that have no consumer.

func WriteUIWebPackageFiles ¶

func WriteUIWebPackageFiles(projectDir, projectName string, workspaces bool) error

WriteUIWebPackageFiles emits packages/ui-web/ — the shared web-UI component library workspace. Idempotent (write-if-missing); safe to call from `forge generate` cycles after the user customizes the scaffolded files.

No-op when workspaces is false so existing single-frontend projects regenerate byte-identically.

Split from WriteFrontendWorkspaceFiles so callers that want to refresh just the ui-web scaffold (e.g. ensure-step in `forge generate`) don't have to touch the api/hooks packages.