codegen

func APIWorkloadStanza ¶ added in v0.1.45

func APIWorkloadStanza(modulePath, projectName string, extraSecrets ...string) string

APIWorkloadStanza renders a hosted env's `_api` declaration: the project binary's `server` as one service workload. The facts are the ones WorkloadStanza gives every component of that binary — the image, the build, the `http` port, the credential the DI graph reads — with `server` as the subcommand, so `_api` and the services it runs cannot disagree about them.

extraSecrets are credentials THIS env hands the API beyond the database — the dev env's login-broker token, which only an env running the dev IdP has. They are an env fact, not a workload fact, so the caller passes them.

func AppendWorkloadStanza ¶ added in v0.1.45

func AppendWorkloadStanza(projectDir, modulePath, projectName string, c config.ComponentConfig) (applied bool, err error)

AppendWorkloadStanza adds one workload to a project's deploy/kcl/workloads.k — its declaration, and its name in the `ALL` list — and reports whether it did.

ADDITIVE ONLY. Existing content is never rewritten, reformatted or reordered: the file is user-owned, so the only edits forge makes to it are the new declaration (above the ALL list's comment block) and the one new list entry, written in the style the list already uses. Every other byte, comment and line break stays where the user left it.

It returns applied=false, with no error and no write, when the file is missing, the workload is already declared, or the ALL list cannot be located unambiguously. The caller then PRINTS the stanza for the user to paste.

func AssignBootstrapAliases ¶

func AssignBootstrapAliases(services []BootstrapServiceData, packages []BootstrapPackageData, workers []BootstrapWorkerData, operators []BootstrapOperatorData)

AssignBootstrapAliases populates the Alias field on every BootstrapComponentData across services, packages, workers, and operators. When the .Package fields are unique across all four roles, each Alias equals its Package (default Go import alias — preserves the original codegen output). When two roles share a .Package value (e.g. service "billing" + internal package "billing"), the conflicting component(s) get a role-prefixed alias ("svcBilling", "pkgBilling", "wkrBilling", "opBilling") so the import line in bootstrap.go can alias the import and every reference site can use the alias unambiguously.

This is purely additive — when there's no collision the default alias matches Package and the rendered bootstrap is identical to pre-aliasing output.

Internally delegates to ResolveCollisionNaming so wire_gen and bootstrap derive their function/field names from the same rule.

func AssignsContain ¶ added in v0.1.45

func AssignsContain(assigns []string, tok string) bool

AssignsContain reports whether any of the create-path assignments contains tok. The create closure is built per METHOD, not per entity, so its import needs are gated separately from the conversion pair's.

func AttachEntityMeta ¶

func AttachEntityMeta(page *PageTemplateData, entity EntityDef, svc ServiceDef)

AttachEntityMeta enriches a PageTemplateData with typed field metadata from the matched proto entity definition. The page generator calls this after pairing a CRUD RPC group with its EntityDef — the same pairing that gates page emission — so templates can emit fully typed columns, search fields, and detail rows. svc supplies the deep type graph needed to resolve enum COLUMNS to their protobuf-es TS type (which the badge cell passes to StatusBadge); an unresolvable enum column degrades to the enum-like string path (String(item.field)).

func AttachForeignKeys ¶ added in v0.1.45

func AttachForeignKeys(page *PageTemplateData, referents map[string]PageFieldFK)

AttachForeignKeys marks every create/update form field and every detail column of `page` that is a foreign key onto one of `referents`.

A field qualifies when its proto name ends in `_id`, the remaining owner resolves to a referent, and the field is a plain string — an integer `*_id` is not pointing at a forge entity (whose primary key is TEXT), and a repeated or enum field is not a single reference.

A self-reference (`parent_id` on Category resolving to Category) is left alone: the picker would browse the very rows being edited, and a tree parent picker is a domain decision, not a generated default.

func BuildEntityConv ¶

func BuildEntityConv(svc ServiceDef, entity EntityDef) (EntityConvTemplateData, []UnmappedField)

BuildEntityConv builds the conversion data for one entity, plus every (wire field, column) pair it could not map.

func BuildFKReferents ¶ added in v0.1.45

func BuildFKReferents(pages []PageTemplateData) map[string]PageFieldFK

BuildFKReferents indexes the project's CRUD pages by the entity name a `<owner>_id` field would name, so field resolution is a map lookup.

Pages MUST have been through AttachEntityMeta — DisplayField and PkFieldCamel come from there. An entity without BOTH a List and a Get RPC is skipped: the picker browses with List and the closed-state label resolves with Get, so a half-CRUD entity cannot back one.

func CRDLambdaName ¶ added in v0.1.45

func CRDLambdaName(kind string) string

CRDLambdaName maps a CR kind to its generated KCL lambda name: "ManagedDatabase" -> "manageddatabase_crd". Lowercasing the whole kind (rather than snake-casing it) matches the hand-authored spelling this generator replaces, so an existing project's call sites keep working unchanged.

func CRDSourceRoots ¶ added in v0.1.45

func CRDSourceRoots(projectDir string) ([]string, error)

CRDSourceRoots returns the package patterns whose CRD types a project installs:

• "./api/..." when the project has an api/ directory (its own kinds);
• ForgeTierAPIPackage when the project REGISTERS forge's tier kinds, i.e. it references that package's AddToScheme.

The second source is derived from the code rather than configured. That is deliberate: registering the kinds in a scheme is exactly what a process that reconciles them must do, so a separate opt-in could only disagree with it. A reconciler whose CRD is never installed fails only at runtime, with "no matches for kind". A plain IMPORT is not the signal. A package that only uses a constant or Validate() from the tier types (the secret materializer does) does not reconcile anything, and treating that as "install the CRDs" collided with a project's own same-named kinds.

func CRUDAuthSeam ¶ added in v0.1.45

func CRUDAuthSeam() string

CRUDAuthSeam returns the qualified app-owned function a handler calls to demand a principal ("middleware.GetUser"). It is the same value the scaffold renders into every CRUD shim header, exported so analyses that ask "does this handler resolve the caller?" resolve the seam from the generator rather than hardcoding a name the generator could rename out from under them.

func CRUDAuthSeamFuncs ¶ added in v0.1.45

func CRUDAuthSeamFuncs() map[string]bool

CRUDAuthSeamFuncs is the set of function names that mean "this code resolved the caller" — the seam itself plus the claims accessor the seam package re-exports. Returned as a fresh map so callers cannot mutate the generator's view of its own seam.

func CRUDDelegatePkgName ¶ added in v0.1.45

func CRUDDelegatePkgName() string

CRUDDelegatePkgName is the package selector a delegating CRUD shim calls through ("crud", the last segment of crudLibImport). Derived from the import the shim actually stamps, so moving the delegate package moves this with it.

func CRUDProjectionReferences ¶ added in v0.1.45

func CRUDProjectionReferences(dir string, methods []Method) (map[string]CRUDProjectionReference, error)

CRUDProjectionReferences reports, per method (keyed by Go method name), the first place the handler package at dir uses a symbol forge generates for that rpc only while it is CRUD: its op (crud<Method>Op), and for a Create-named rpc its create-request factory (New<Request>), which the scaffolded lifecycle test calls. Tests are read too — a test calling either breaks `go test` as surely as a handler breaks the build. Forge's own generated files (handlersGeneratedFiles, *_gen.go, *_gen_test.go) are not read: they DECLARE these symbols, they are not demand for them. Methods nothing references are absent. A missing dir is no references.

It answers the question a `// forge:custom` rpc raises when it was CRUD before: forge stops generating both, so code still using them fails after the whole generate ran.

func CRUDShape ¶ added in v0.1.45

func CRUDShape(m Method) (operation, entityName string)

CRUDShape is the one answer to "does this rpc's DECLARATION claim CRUD, and on which entity name?" — every projection that classifies an rpc asks it, so the server wiring, the entity set, the frontend, the seed scope and the audit cannot disagree about one rpc.

An rpc claims CRUD when it is unary, named Create<E>/Get<E>/Update<E>/ Delete<E>/List<Es>, and carries no `// forge:custom` marker (ProtoMarkerCustom). The claim is not the verdict: the rpc is CRUD only when <E> also has a table and a wire message, which MatchCRUDMethods and BuildSchemaEntities decide. Everything CRUDShape refuses is custom.

The entity name is as written — List's plural is NOT singularized here, because each caller resolves it against a different inventory.

func CanonicalGoTypeOK ¶ added in v0.1.45

func CanonicalGoTypeOK(canonical string, isArray bool) (goType string, ok bool)

CanonicalGoTypeOK maps a canonical schema type (the closed vocabulary schemadef.MapDeclaredType produces) to the Go type a column projects to on the generated entity struct — the NOT NULL variant; a nullable column adds a pointer, and an array column never does because a slice already carries nil.

This is the SINGLE definition. There used to be three: this one, the CRUD conversion generator's dbBaseGoType, and internal/generator's planFieldGoType. They disagreed exactly where it mattered — dbBaseGoType collapsed every array column that was not BIGINT[] to []string, so a BYTEA[] column projected to []string in the half that decides whether a wire field pairs with it and to something else in the half that declares the struct field. Two projections of one column is one projection too many; the other two now route here.

A json ARRAY column (jsonb[]) projects to []string: each element is a document, the same way a scalar json column projects to the document text.

ok=false means the string is not a canonical schema type and the "string" answer is a FALLBACK rather than a mapping — the same distinction, for the same reason, that schemadef.MapDeclaredType draws with its `known` return. Every caller holds a type that is supposed to be canonical, so ok=false is a forge bug and each one reports it by name rather than declaring the field as text.

The `default:` arm this used to end with covered "string, json, unknown" in one breath, which is the defect in miniature: `string` and `json` are MAPPED to Go string, and "unknown" is a type forge has no projection for. Collapsing the three meant a canonical type added upstream without a projection here became a Go `string` field in silence.

func CheckDuplicateConfigFields ¶ added in v0.1.45

func CheckDuplicateConfigFields(fields []ConfigField, module, schemaName string) error

CheckDuplicateConfigFields refuses a field set that would declare the same field name twice inside ONE generated KCL schema.

KCL accepts a repeated field in a schema suite silently and the LAST declaration wins, so the first field's default is discarded with no diagnostic. That is not a style problem — it is a value the operator never wrote appearing in a rendered manifest. Observed in production: a config proto declared `app_url = "http://localhost:3000"` and a second config proto, flattened into the same AppConfig, declared `app_url = ""`. The empty string won, three prod workloads shipped `APP_URL: ”`, and the consumer gated a browser auth redirect on the value being non-empty — so the collision silently downgraded that redirect to a bare 401. Nothing in any diff showed it, because config_gen.k is generated and nobody reads it.

The refusal is per SCHEMA, never across schemas. A project with per-binary configs emits AdminConfig, GatewayConfig and so on into the same module, and those legitimately share field names — `port` on both binaries is two separate declarations in two separate suites, which is the whole point of splitting them. Only a repeat WITHIN one suite shadows anything.

Block-reference fields (MessageType set) are exempt: they project to a comment rather than a schema field, so two of them cannot shadow each other. They are still checked against SCALAR fields of the same name, because that pair does produce one real declaration plus a confusing comment, and it means the proto author has two different fields fighting over one name.

module names the KCL module the schema lands in (ConfigSchemaModule, FrontendConfigModule, …) so the message points at the file that would actually have carried the shadowed field.

func ClosestFrom ¶ added in v0.1.45

func ClosestFrom(name string, vocabulary []string) string

ClosestFrom returns the entry of vocabulary nearest to name by Levenshtein distance, or "" when nothing is close enough to be worth suggesting. The cutoff scales with the name's length (a third of it, minimum 1), so a genuine typo earns a suggestion while an unrelated token does not get an arbitrary entry pinned on it.

Exported as the vocabulary-agnostic core of ClosestProtoMarker so the checks that validate a DIFFERENT forge vocabulary — the annotation OPTION fields in internal/cli/lint/lint_proto_options.go, read off the compiled descriptors — score near-misses by exactly the same rule rather than growing a second, subtly different one.

func ClosestProtoMarker ¶ added in v0.1.45

func ClosestProtoMarker(name string) string

ClosestProtoMarker returns the known proto marker nearest to name by Levenshtein distance, or "" when nothing is close enough to be worth suggesting. The cutoff scales with the name's length (a third of it, minimum 1) so a genuine typo — `forge:read-only`, `forge:etnity` — earns a suggestion while unrelated prose that happens to start with `forge:` does not get an arbitrary marker pinned on it.

A removed spelling is deliberately NOT resolved here; RemovedProtoMarkers carries a better answer than edit distance can, and the caller checks it first.

func CmdServiceCommand ¶ added in v0.1.45

func CmdServiceCommand(name string) (runtime, ctor string, ok bool)

CmdServiceCommand describes the services/ group command `forge generate` emits for a raw service-name spelling: the runtime (kebab) name — which is both the cobra Use value and the <name>.go filename stem under cmd/<bin>/cmd/services/ — and the exported constructor cmd/<bin>/main.go must name to ship it.

ok is false for a name the command tree RESERVES (see reservedSubcommandNames): those get no subcommand file at all, so there is nothing to wire into the composition root.

It exists so callers that TALK about the command (the `forge scaffold service` wiring instruction) derive the symbol from the same place the generator does, and can never print a constructor that was not emitted.

func CollisionCounts ¶

func CollisionCounts(services []BootstrapServiceData, packages []BootstrapPackageData, workers []BootstrapWorkerData, operators []BootstrapOperatorData) map[string]int

CollisionCounts returns a map of Go-package-name → occurrence count across services, packages, workers, and operators. A count > 1 means a cross-role collision (e.g. service "billing" + internal package "billing") and is the trigger for role-prefixed aliasing in AssignBootstrapAliases. Exposed so wire_gen and other generators can derive the SAME collision-aware FieldName that bootstrap uses without duplicating the bookkeeping.

func CommentMarksCustom ¶ added in v0.1.45

func CommentMarksCustom(comment string) bool

CommentMarksCustom reports whether an rpc's comment text (slashes already stripped, the descriptor path's shape) carries ProtoMarkerCustom.

func CommentMarksUnmanaged ¶ added in v0.1.45

func CommentMarksUnmanaged(comment string) bool

CommentMarksUnmanaged reports whether a service's comment text (slashes already stripped, the descriptor path's shape) carries ProtoMarkerUnmanaged.

func ComponentTestHelperRelPath ¶ added in v0.1.45

func ComponentTestHelperRelPath(handlerLeaf string) string

ComponentTestHelperRelPath is the project-relative path of a service's generated test-helper file. Exposed so tests (and callers reasoning about generated output) name the location in one place rather than rebuilding the "internal/handlers/<leaf>/helpers_gen_test.go" string each time.

func ComputeTestHelperName ¶

func ComputeTestHelperName(servicePkg, projectDir string) string

ComputeTestHelperName returns the suffix used by the `app.NewTest<X>` and `app.NewTest<X>Server` factories generated into pkg/app/testing.go. When the service's Go-package name collides with a WIRED internal component of the same name (e.g. service `billing` + component `internal/billing/`), the bootstrap testing generator disambiguates by prefixing "Svc" (NewTestSvcBilling). This helper mirrors that rule so test scaffolds emit the same identifier the factory actually has.

The collision test is IsWiredComponentDir — "does this package occupy a factory-namespace slot" — not "does a directory of this name exist". Those are different questions, and answering the second one made this function disagree with the generator it is supposed to mirror; see IsWiredComponentDir.

projectDir may be empty (no project context); in that case there's no collision detection possible and the result is the no-collision form.

func ConfigFieldNamesFromMessages ¶

func ConfigFieldNamesFromMessages(messages []ConfigMessage) map[string]bool

ConfigFieldNamesFromMessages returns a map of Go field names present in the given config messages. Used by templates to conditionally include code blocks that reference specific config fields.

func ConfigPackageDeclaresDefaults ¶ added in v0.1.46

func ConfigPackageDeclaresDefaults(projectDir, modulePath, importPath string) bool

ConfigPackageDeclaresDefaults reports whether the project package at importPath declares a package-level `func Defaults()` returning one value — the generated pkg/config's constructor for the config Load yields with nothing set (config.go.tmpl). The test harness defaults a component's config to it when it exists. It is read from the source rather than assumed from the path: a CLI's stub pkg/config, a hand-written one, or a config package outside pkg/config declares Config without it, and a harness calling a function that does not exist would not compile.

The config loader step runs before the harness step, so a generate that (re)writes pkg/config/config_gen.go is seen by the harness in the same run.

func ConvNeedsFmt ¶ added in v0.1.45

func ConvNeedsFmt(convs []EntityConvTemplateData) bool

ConvNeedsFmt reports whether any conversion emits a guard that calls fmt.Errorf — the corrupt-enum read, or either half of a json/jsonb pairing. The ops file imports fmt only then; otherwise the import would be unused. (goimports would also correct this post-write, but gating it keeps the rendered file correct on its own.)

func ConvNeedsORM ¶ added in v0.1.45

func ConvNeedsORM(convs []EntityConvTemplateData) bool

ConvNeedsORM reports whether any conversion calls into pkg/orm — today the json/jsonb encoders. Gated for the same reason as ConvNeedsFmt: an entity with no json column must not pull in the import.

func ConvNeedsTime ¶ added in v0.1.45

func ConvNeedsTime(convs []EntityConvTemplateData) bool

ConvNeedsTime reports whether any conversion reaches the stdlib `time` package — today only the legacy-TEXT timestamp pairing, which formats and parses time.RFC3339Nano. Gated for the same reason as ConvNeedsFmt: an entity with no such column must not pull in the import.

func ConvNeedsTimestamppb ¶

func ConvNeedsTimestamppb(convs []EntityConvTemplateData) bool

ConvNeedsTimestamppb reports whether any assignment uses timestamppb. Comment-only entries (the wire-only and forge:secret explanations) are ignored: a comment naming *timestamppb.Timestamp must not pull in an import no code uses.

func CustomMarkerNearMiss ¶ added in v0.1.45

func CustomMarkerNearMiss(comment string) string

CustomMarkerNearMiss returns the first `forge:*` token in an rpc's comment that is a misspelling of ProtoMarkerCustom (`forge:cusotm`, `forge:custom-rpc`), or "" when there is none. Refused for the reason UnmanagedMarkerNearMiss gives: a misspelled forge:custom leaves the rpc CRUD, and the next generate wires generic CRUD over the logic the marker was written to protect.

func DeclaredCallerResolvers ¶ added in v0.1.45

func DeclaredCallerResolvers(projectDir string) ([]CallerResolver, []IgnoredResolverMarker)

DeclaredCallerResolvers finds every function in projectDir's main module declared with ResolvesCallerDirective. It reads non-test .go files only, and skips hidden directories, node_modules, vendor, testdata and nested modules (a directory with its own go.mod is another module's code). A file is parsed only when its bytes mention the directive, so the walk costs little more than reading the tree.

Results are sorted by import path, then name. A project without a go.mod declares nothing.

func DeclaredWorkloads ¶ added in v0.1.45

func DeclaredWorkloads(src string) map[string]DeclaredWorkload

DeclaredWorkloads parses each workload literal in a workloads.k, keyed by its declared name.

Docstrings and comments are stripped first (StripKCLProse), because the scaffolded workloads.k DOCUMENTS the shape it expects, including worked examples, and an example is not a declaration. A literal this cannot read is simply absent.

A build bound to a top-level variable (`build = _cp_build`, where `_cp_build = forge.GoBuild {...}`) is resolved, because stating the one project build once and naming it from every workload is how a project with several workloads on one binary writes it.

func DeclaresServes ¶ added in v0.1.45

func DeclaresServes(declared map[string]DeclaredWorkload) bool

DeclaresServes reports whether any workload in the file declares `serves` — the project's own statement that it runs several components through one subcommand. In such a project a new component may belong to one of those processes, which forge cannot see, so `forge scaffold` shows the choice instead of declaring a workload the project most likely does not want.

func DefaultConfigFieldNames ¶

func DefaultConfigFieldNames() map[string]bool

DefaultConfigFieldNames returns the field names from the default scaffold config proto. Used at initial project scaffold time before the config proto has been parsed by the generator.

func DepsLiteralKeys ¶ added in v0.1.45

func DepsLiteralKeys(dir string) (keys map[string]bool, found bool)

DepsLiteralKeys returns every field name a `<pkg>.Deps{…}` composite literal may legally key for the Deps struct declared in dir, plus whether a Deps struct was FOUND there at all.

This is a DIFFERENT question from ParseServiceDeps, and the difference is the whole point. ParseServiceDeps answers "what must forge WIRE?" — so it drops unexported and embedded fields, which forge cannot address. DepsLiteralKeys answers "what may the literal legally NAME?" — the full key set, embedded and unexported included. compose.go's reconciler uses it to drop a key that is provably not a field, and it must never mistake a key forge does not emit (an embedded `Base:` the author wired by hand) for a dead one. The wiring set is a subset of the key set, so the two can never disagree about a key forge itself emitted.

The `found` bool is the guard that keeps the removal case from becoming a licence to destroy. An empty key set is AMBIGUOUS: it means either "the Deps struct genuinely has no fields" or "the package is mid-edit and did not parse" — this walk, like ParseServiceDeps, skips a file it cannot parse. Only `found` distinguishes them, and a caller that deletes on the strength of an absent field must act only on a set that was positively read.

func DescriptorSourceHash ¶ added in v0.1.45

func DescriptorSourceHash(projectDir string) string

DescriptorSourceHash fingerprints every .proto under <projectDir>/proto by path and content. Order-independent by construction (paths are sorted), so the same tree always hashes the same regardless of walk order.

Content, not mtime: a checkout, a rebase or a `cp -R` rewrites mtimes without changing meaning, and would invalidate a descriptor that is perfectly good. Hashing the bytes answers the question actually being asked — "was this extracted from THESE protos?"

func DetectConstructorName ¶ added in v0.1.45

func DetectConstructorName(dir string) string

DetectConstructorName returns the name of the package's component constructor: the `// forge:constructor`-marked func under whatever name its author chose, else `New`.

This is the EMIT-side counterpart of IsComponentConstructor. Freeing the name on the discovery side alone would be worse than not freeing it at all: lint would bless `// forge:constructor func Open(Deps) (Mailer, error)` while the injector kept emitting `pkg.New(pkg.Deps{...})`, so `forge generate` would write a compile-broken internal/app/compose.go pointing the user at generated code they don't own. Detection and emission read the same marker.

Falls back to DefaultConstructorName whenever the directory is missing, unparseable, or declares no constructor — the caller then emits the shape a freshly scaffolded package has, which is the correct guess.

func DetectConstructorType ¶

func DetectConstructorType(dir string) (string, error)

DetectConstructorType returns the pretty-printed FIRST return type of the exported `func New(...)` in dir — the type the constructor produces. For a handler service whose New returns (*Service, error) it is "*Service"; for an internal package whose New returns Service (the contract interface) it is "Service". The qualifier prefix (the package selector) is added by the caller from the component's import alias.

Returns "" when the directory has no parseable New or the result list is empty — the caller falls back to the bootstrap default (*Service).

This is what makes the generated Services registry field type AND the inject_gen local-var assignment match the constructor exactly, regardless of whether the component exposes a concrete *Service struct (handlers) or a Service interface (internal packages) — closing the `*item.Service` vs `item.Service` assignability mismatch.

func DetectDepsConfigImport ¶ added in v0.1.45

func DetectDepsConfigImport(dir string) string

DetectDepsConfigImport returns the import path of the package that declares the type of the component's `Deps.Config` field, when that field is a pointer to a type named Config from another package (`Config *config.Config`, usually the project's generated pkg/config). It returns "" when Deps has no such field.

The test harness hands a component a config only through this field, so this is the one fact that decides whether the harness needs a config import at all, and which. It used to import `<module>/pkg/config` unconditionally: a project with no typed config (no proto/config, so no pkg/config) got a helpers_gen_test.go that did not compile for every component, whether or not any of them took a config.

func DetectDepsDBField ¶

func DetectDepsDBField(dir string) (bool, error)

DetectDepsDBField checks whether the Deps struct in the given directory has a field of type orm.Context (indicating the service needs a database). It parses all non-test .go files and looks for a type Deps struct with a field whose type is orm.Context. Returns true if the Deps struct has a DB field, false otherwise.

func DetectFallibleConstructor ¶

func DetectFallibleConstructor(dir string) (bool, error)

DetectFallibleConstructor checks whether the exported New function in the given directory returns an error as its last result (i.e. returns (T, error)). It parses all non-test .go files and looks for a top-level func New(...). Returns true if the constructor is fallible, false otherwise. If the directory doesn't exist or contains no New function, returns false.

func DetectObserveChainSeam ¶ added in v0.1.45

func DetectObserveChainSeam(dir string) bool

DetectObserveChainSeam reports whether the component package at dir declares the OWNED observability seam `func newObserveChain(...) ...` in a non- generated, non-test source file. Its presence is the per-package opt-in signal for the generated decorator (and, paired with an interface-returning New, for the wrapped compose emission).

Returns false for a missing/unparseable dir. Generated (_gen.go) and test files are ignored, so the generated decorator's own reference to the seam never counts as the seam itself.

func DetectServiceInterfaceName ¶ added in v0.1.45

func DetectServiceInterfaceName(dir string) string

DetectServiceInterfaceName returns the name of the package's Service contract interface — the type key a consumer's by-type Deps field is matched against, and the interface the contract-name lint accepts:

• "Service" — a type named `Service` exists (interface OR struct): the zero-annotation canonical path, unchanged and always preferred.
• <name> — no `Service` type, but an interface carries the `//forge:service` / `//forge:contract` marker: the marker frees the interface's name (Gateway / Provider / Dispatcher …).
• "" — neither; the caller defaults to "Service".

The canonical `Service` always wins over a marker (a package with both keeps `Service`), so existing projects are byte-for-byte unaffected. Among multiple marked interfaces the first in deterministic order (file name, then source position) is chosen; marking two interfaces is a user error the lint can surface separately. Non-test, non-generated files only. Unreadable/unparseable dirs return "".

func DiscoverInternalPackageNames ¶ added in v0.1.45

func DiscoverInternalPackageNames(projectDir string) ([]string, error)

DiscoverInternalPackageNames is DiscoverInternalPackages projected to the nested names the bootstrap/injector codegen keys on.

func EnsureFrontendConfigInstances ¶ added in v0.1.45

func EnsureFrontendConfigInstances(configs []FrontendConfig, kclDirAbs, envName, projectName string) ([]string, error)

EnsureFrontendConfigInstances makes sure an env's user-owned config.k declares one typed VALUES instance per frontend config — the half the runtime projection reads.

It appends rather than scaffolding a whole file, because config.k is shared with the backend's app_config and is written once (write-if-absent). A frontend annotated AFTER the env was created — the normal order, since a project scaffolds its envs long before it declares a frontend config — would otherwise never get an instance, leaving the projection nothing to project and every environment silently on proto defaults.

Only MISSING instances are appended, matched by schema name, so this is idempotent and never touches values an author has edited. Returns the frontends it added an instance for.

func EntityConstraintsToPlan ¶ added in v0.1.45

func EntityConstraintsToPlan(cs []EntityConstraint) []config.PlanEntityConstraint

EntityConstraintsToPlan converts introspected constraints to the plan shape the ORM generator consumes.

func EntityDefToPlanEntity ¶

func EntityDefToPlanEntity(entity EntityDef) config.PlanEntity

EntityDefToPlanEntity converts an EntityDef to the PlanEntity shape the ORM generator consumes.

The field source is the entity's COLUMNS — the introspected applied schema — never the wire message. A column added by a hand-written migration appears here (and on the generated struct) without any proto involvement; a wire-only field never reaches the database layer. SQL is the schema truth.

func EntityDefsToPlanEntities ¶

func EntityDefsToPlanEntities(entities []EntityDef) []config.PlanEntity

EntityDefsToPlanEntities converts a slice of EntityDef to a slice of PlanEntity.

func EntityRPCs ¶ added in v0.1.46

func EntityRPCs(projectDir string, services []ServiceDef, entities []string) map[string][]EntityRPC

EntityRPCs returns, for each entity name asked about, the declared rpcs that claim it — by the same rule entitiesForTables applies, so they are exactly the rpcs whose `// forge:custom` would make the table plain schema. It is what the advice for keeping a table off forge's ORM must name: the rpcs the project HAS, not the five a CRUD quintet would have.

func EntityWireKey ¶ added in v0.1.45

func EntityWireKey(e EntityDef) (field string, ok bool)

EntityWireKey is the field the frontend keys an entity's rows by, and ok=false when the wire message offers no real key. In order: the DB primary key when the message carries it, else the conventional `<singular table>_id` domain key (a table can hold a surrogate `id` while the published proto exposes `usage_event_id` instead). Picking "the first field" or a literal "id" is a guess, not a key, and is deliberately not offered here.

func EnvBinder ¶ added in v0.1.45

func EnvBinder(env, kind string) string

EnvBinder names the binder a freshly scaffolded env uses for a workload of kind. In the local loop: a host process where one can run, and the local cluster where it cannot (a cron is scheduled by Kubernetes, an operator watches its API). Elsewhere: the forge control plane for every kind it admits, and a cluster you operate for the kinds it refuses (HostedRefusal). A tool is never run anywhere.

func EnvBinding ¶ added in v0.1.45

func EnvBinding(env, kind, workloadName string) string

EnvBinding is one line of an env's `_workloads` list, as a fresh scaffold writes it.

func EnvBindingHint ¶ added in v0.1.45

func EnvBindingHint(env, kind, workloadName string) string

EnvBindingHint is the message shown when a binding could not be appended.

func EnvDeclaresNoCluster ¶ added in v0.1.45

func EnvDeclaresNoCluster(projectDir, env string) bool

EnvDeclaresNoCluster reports whether an env's main.k still carries the scaffold's `_cluster = None`: a workload bound `_on_cluster` there fails the render, naming itself, until the author declares the cluster.

func EnvSecretsFileName ¶ added in v0.1.45

func EnvSecretsFileName(envName string) string

EnvSecretsFileName is the per-env secret store the `file` secret provider reads: `secrets/<env>.yaml`, keyed by ENV-VAR NAME (the convention internal/secrets resolves on). It is gitignored — it holds secret VALUES, the half that never lives in git.

It is deliberately NOT a dotenv. The `dotenv` provider was removed (it handed every host service the whole file, so a value went live without ever being declared in KCL), and `forge lint`'s no-dotenv rule now REJECTS a `.env*` file. A scaffold that still wrote one failed its own linter on the first run of a brand-new project.

func EnvServerWorkload ¶ added in v0.1.45

func EnvServerWorkload(content, projectName string) (string, bool)

EnvServerWorkload returns the identifier of a workload an env's main.k declares FOR ITSELF that runs the project binary's `server` — a hosted env's `_api`. Read from the source, like DeclaredWorkloads, so scaffold and `forge env new` need no render. Comments and docstrings are stripped first, so the worked examples in a scaffolded file are not mistaken for one.

func ExciseUnwiredStubs ¶ added in v0.1.45

func ExciseUnwiredStubs(projectDir, dir string, methods map[string]bool) ([]string, error)

ExciseUnwiredStubs removes, from the user-owned handler files in dir, every *Service method whose name is in `methods` that is still a pristine forge-emitted unwired stub. Returns the method names it removed (sorted by discovery order). Non-test, non-_gen.go files only — the marker only ever lands in the user-owned handler files. A missing dir is not an error (nothing to excise).

func ExtractPlaceholderType ¶

func ExtractPlaceholderType(text string) string

ExtractPlaceholderType returns the target type from a `forge:placeholder: <Type>` comment marker, or "" when no marker is present.

Recognition is line-based after stripping leading `//`, leading/ trailing whitespace; the marker must be the whole line:

// forge:placeholder: user.Repository
UserRepo any

Or the inline-comment slot:

UserRepo any // forge:placeholder: user.Repository

Both forms are accepted — same convention as `// forge:optional-dep`. The colon is required (it carries data, unlike optional-dep which is a bare directive). Whitespace after the colon is tolerated.

Exported so the wire-coverage lint can share the exact same recognition logic — the rule is "if the field has a placeholder AND the field's declared type is `any`, the placeholder is unresolved and lint must error."

func ExtractPlaceholderTypeCommentGroup ¶

func ExtractPlaceholderTypeCommentGroup(cg *ast.CommentGroup) string

ExtractPlaceholderTypeCommentGroup is the AST-level analog of ExtractPlaceholderType. Same parity reason as HasOptionalDepMarkerCommentGroup: Go's CommentGroup.Text() drops the no-space directive form, so a comment written as `//forge:placeholder: user.Repository` (without the space) would be silently invisible to the .Text()-based scan. Iterating cg.List and trimming the raw markers preserves both shapes.

Returns the placeholder target type, or "" when no marker is present.

func FillHandlerColumns ¶ added in v0.1.45

func FillHandlerColumns(entity EntityDef) []string

FillHandlerColumns names the entity's columns declaring `forge:fill=handler` — the exact set FindUnsatisfiableColumns would have flagged but for that declaration (NOT NULL, no DB DEFAULT, forge:read-only, not the PK, not GENERATED). Used to seed the handlers_crud.go Create scaffold's op.Entity wrapper (see ensureCRUDShimFile) with a named reminder of what the handler author still has to stamp.

func GenerateAPIDeepCopy ¶ added in v0.1.45

func GenerateAPIDeepCopy(projectDir string) ([]string, error)

GenerateAPIDeepCopy regenerates zz_generated.deepcopy.go for every package under the project's api/ directory, in-process, with the controller-tools version pinned in forge's go.mod.

WHY forge OWNS THIS. forge already projects the CRDs (crd_gen.k) from these same Go types, but it never regenerated their deepcopy. So deleting a type — the normal way to retire a kind — left a deepcopy file referencing it, the package stopped compiling, and the only way out was a controller-gen binary the project had no pinned version of. One source (the Go types), both projections, one command.

THE STALE FILE IS REMOVED BEFORE LOADING, because it is exactly what makes the package fail to type-check after a type is deleted. It is restored if generation fails, so a failed run never leaves the tree worse than it found it. It returns the paths it wrote, relative to projectDir.

func GenerateAuthSetup ¶ added in v0.1.45

func GenerateAuthSetup(modulePath, projectDir string) error

GenerateAuthSetup scaffolds internal/app/auth.go ONCE — the OWNED, user-editable SetupAuth() that picks the request authenticator in CODE (default: a JWT validator built from the typed config's jwt_* fields). It replaces the retired forge-owned auth_gen.go validator codegen: authentication is a code-wiring choice (which validator) reading per-deployment values that are ordinary config fields, not a static forge.yaml block.

Scaffold-once, never overwritten after first emit (os.Stat guard) — the user owns the bytes. The generated cmd serve wiring calls app.SetupAuth and threads the returned validator into the auth interceptor.

func GenerateAuthSetupData ¶ added in v0.1.46

func GenerateAuthSetupData(projectDir string, data AuthSetupTemplateData) error

GenerateAuthSetupData is GenerateAuthSetup with the whole template input: a project in graph mode passes Graph and HasDatabase.

func GenerateBootstrapTesting ¶

func GenerateBootstrapTesting(in BootstrapTestingGenInput) error

func GenerateCRDKCL ¶ added in v0.1.45

func GenerateCRDKCL(docs []CRDDoc, controllerGenVersion string) (string, error)

GenerateCRDKCL renders the complete deploy/kcl/lib/crd_gen.k module: one `<lower>_crd = lambda -> any { ... }` per CRD, in deterministic kind order.

The generated lambdas take no arguments and close over nothing, exactly like the hand-authored module they replace, so every call site keeps its shape.

controllerGenVersion is stamped into each CRD's controller-gen.kubebuilder.io/version annotation. It names the schema SEMANTICS the output was produced under, which is the one piece of provenance that matters when a future controller-tools bump changes how some Go construct projects.

func GenerateCmdCommands ¶

func GenerateCmdCommands(targetDir, bin string) error

GenerateCmdCommands scaffolds cmd/<bin>/cmd/commands.go — the user-owned cobra extension point newRootCmd consumes (userCommands(deps)). Written ONCE; never overwritten (Tier-2: the user owns the file the moment it exists). Second binaries register here as code with opt-in serverkit pieces instead of a parallel hand-rolled main().

bin is the primary binary name (the cmd/<bin>/cmd directory leaf). The template references it for accurate doc paths and the {{.Name}} display.

func GenerateCmdGroups ¶

func GenerateCmdGroups(in CmdServiceGroupInput, targetDir string, cs *checksums.FileChecksums) error

GenerateCmdGroups renders the dir-nested command groups under cmd/<bin>/cmd (devspace idiom): ONE FILE PER SERVICE in the services/ SUBPACKAGE, each `New<X>Cmd(cmd.Deps)` whose RunE calls cmd.Serve() with a TYPED (*app.Components).Mount<Svc> selection. Each of the services/, workers/, and operators/ groups gets an anchor file so the package compiles with zero items. The services anchor is Tier-1 (register_gen.go) because it projects an input — the built-in collision NOTEs; the workers/ and operators/ anchors are SCAFFOLD-ONCE (register.go) because they project nothing. Selection is compile-time typed — no string positional arg, no string→inventory lookup.

It ALSO scaffolds cmd/<bin>/main.go — the composition root — ONCE (write-if-absent) from the service rows. main.go is OWNED code thereafter: `forge scaffold worker/operator` appends the constructor ref by hand. The per-worker/operator subcommand files are NOT emitted here — they are scaffold-once OWNED code (ScaffoldWorkerCmd / ScaffoldOperatorCmd).

cs is the project's checksum tracker — passing it keeps the (proto-derived) service files out of `forge project audit`'s orphan list. A nil cs is tolerated.

func GenerateCmdMainRoot ¶

func GenerateCmdMainRoot(targetDir, bin string, cs *checksums.FileChecksums) error

GenerateCmdMainRoot renders ONLY cmd/<bin>/main.go — the composition root — as a bare cmd.Execute() with no component constructors. The generate pipeline emits main.go via GenerateCmdGroups (which knows the full inventory); this exported entry lets the scaffold drop a composition root for a service project that has no proto pipeline (features.codegen=false), preserving the pre-refactor contract that main.go is always scaffolded for service kind.

func GenerateCmdServer ¶

func GenerateCmdServer(messages []ConfigMessage, targetDir string, cs *checksums.FileChecksums) error

GenerateCmdServer re-renders cmd/server.go with config field awareness. Called during `forge generate` so that cmd/server.go stays in sync with the actual config proto fields.

cs is the project's checksum tracker — passing it keeps cmd/server.go out of `forge project audit`'s orphan/user-edited lists. A nil cs is tolerated.

func GenerateCmdServerWithFields ¶

func GenerateCmdServerWithFields(configFields map[string]bool, targetDir string, cs *checksums.FileChecksums) error

GenerateCmdServerWithFields renders cmd/server.go using a pre-built config field map (e.g. with migration fields stripped when the migrations feature is disabled).

func GenerateCompose ¶

func GenerateCompose(in InjectGenInput) error

GenerateCompose emits internal/app/compose.go: the EXPLICIT per-binary component construction site (the Components typed bag + NewComponents) that REPLACES the retired generated injector (inject_gen.go + app_services_gen.go). It constructs every registered component in TYPE-topological order and fills each Deps field BY TYPE — from another constructed component, from a field on the owned *Infra struct (providers.go), or from the conventional Logger/Config sources.

Returns an error listing every MissingProvider when a required collaborator field resolves to no producer and the matcher PROVES the Infra struct has no assignable field.

This is the live composition path: cmd-server composes OpenInfra → NewComponents → mount via the typed Mount<Svc> methods + AllWorkers / AllOperators. There is no by-type injector and no *Services god-struct.

func GenerateConfigKCL ¶ added in v0.1.45

func GenerateConfigKCL(fields []ConfigField, projectName string) (string, error)

GenerateConfigKCL emits the ONE generated config module — deploy/kcl/config_gen.k — carrying both halves of the projection: the TYPE (`schema ConfigSecretRef` + `schema AppConfig`) and the BEHAVIOR (`appConfigEnvMap`).

They were two files (config_schema.k + config_projection.k) on the premise that a KCL module cannot hold a schema and a lambda together. It can — forge's own kcl/workload.k interleaves schemas and lambdas in one file. Since both halves are projected from the same proto by the same run and are only ever valid as a pair, splitting them bought nothing and cost a second Tier-1 file, a second hash guard and a second diff entry in every change. Merging also removes the cross-module import: the lambda now names `AppConfig` directly instead of `config_schema.AppConfig`.

Layout is TYPE first, then BEHAVIOR — the lambda's signature references AppConfig, and reading the shape before the projection over it is the order that explains itself.

Fields are visited in proto order by both halves. A field with an empty env_var (a component config-block reference, or any field with no env binding) is skipped by the projection — mirroring the runtime loader, which binds env only for fields that declare an env_var.

func GenerateConfigKCLPerBinary ¶ added in v0.1.45

func GenerateConfigKCLPerBinary(rootFields []ConfigField, perBinary []BinaryConfigFields, projectName string) (string, error)

GenerateConfigKCLPerBinary emits the config module for a project that declares PER-BINARY configs: one typed schema plus one env-projection lambda per binary, all in the single generated config_gen.k.

Each pair is projected from ONLY that binary's fields, which is what makes the deploy story disjoint: an env authoring `AdminConfig { ... }` can set only fields admin reads (anything else is a KCL type error), and the workload env built from adminConfigEnvMap carries only admin's env vars — so gateway's Deployment does not carry admin's credentials.

rootFields is the project-global AppConfig's field set. It is still emitted when non-empty, because a project mid-migration (or one that keeps a shared AppConfig alongside per-binary ones) has env files and main.k modules that reference AppConfig/appConfigEnvMap, and those are user-owned scaffold-once files forge does not rewrite.

func GenerateConfigKScaffold ¶

func GenerateConfigKScaffold(fields []ConfigField, projectName, kclDirAbs, envName string) (bool, error)

GenerateConfigKScaffold emits deploy/kcl/<envName>/config.k — the per-env, user-owned typed AppConfig VALUES instance — ONLY when it does not already exist. Returns true when a fresh file was written, false when an existing user-owned file was left untouched.

func GenerateConfigKScaffoldPerBinary ¶ added in v0.1.45

func GenerateConfigKScaffoldPerBinary(rootFields []ConfigField, perBinary []BinaryConfigFields, projectName, kclDirAbs, envName string) (bool, error)

GenerateConfigKScaffoldPerBinary emits the per-env, user-owned config.k for a project with PER-BINARY configs: one typed instance per binary (`admin_config: config_gen.AdminConfig = {...}`), each carrying only the values that binary reads.

rootFields is the project-global AppConfig's field set, still emitted as `app_config` when non-empty so a project keeping a shared AppConfig alongside per-binary ones has both. Write-if-absent, exactly like the single-config scaffolder: forge writes it once and never clobbers edits.

func GenerateConfigLoader ¶

func GenerateConfigLoader(messages []ConfigMessage, targetDir string, cs *checksums.FileChecksums) error

GenerateConfigLoader generates pkg/config/config.go from parsed config messages.

cs is the project's checksum tracker. Passing it ensures the generated pkg/config/config.go is recorded so `forge project audit` doesn't flag it as an orphan. A nil cs is tolerated (file is still written).

func GenerateConfigNativeShared ¶

func GenerateConfigNativeShared(fields []ConfigField, projectName, projectDir, kclDirAbs string, cs *checksums.FileChecksums) error

GenerateConfigNativeShared emits the project-level, forge-owned KCL module that backs the config path — <kclDirAbs>/config_gen.k — from the proto-derived config fields, and withdraws the two files it replaced.

projectDir is the project root (for the checksum-relative path); kclDirAbs is the absolute deploy/kcl directory; cs is the checksum ledger. When cs is nil or the path can't be made relative, the files are still written (untracked).

func GenerateConfigNativeSharedPerBinary ¶ added in v0.1.45

func GenerateConfigNativeSharedPerBinary(rootFields []ConfigField, perBinary []BinaryConfigFields, projectName, projectDir, kclDirAbs string, cs *checksums.FileChecksums) error

GenerateConfigNativeSharedPerBinary is the per-binary form of GenerateConfigNativeShared: it emits the project-level, forge-owned config_gen.k carrying one typed schema + one env-projection lambda PER BINARY, so each workload's env is built from only its own binary's fields.

rootFields is the project-global AppConfig's field set, still emitted when non-empty (a project may keep a shared AppConfig alongside per-binary ones, and mid-migration every existing env file still names it).

func GenerateConfigSchemaKCL ¶

func GenerateConfigSchemaKCL(fields []ConfigField, projectName string) (string, error)

GenerateConfigSchemaKCL emits a KCL file declaring `schema AppConfig`, one field per proto config field in proto order. Each field's KCL type is mapped from its proto type (see kclTypeForProtoConfig) and its default is projected from the proto annotation (see kclConfigDefaultLiteral). Fields with a description get a leading `#` doc comment.

Component config-block references — a message-typed field whose target message carries its OWN config fields — arrive from forge's descriptor extractor as ProtoType == "message" WITH MessageType set to the block's name (e.g. "TraderConfig") and NO env_var of their own. They carry no scalar KCL type and env binds on the referenced message's leaves, so they are skipped with a comment marking the omission.

NOTE the discriminator is MessageType, not ProtoType == "message": forge's extractor (internal/cli/forge_descriptor.go) collapses EVERY message kind to ProtoType "message", so a `google.protobuf.Duration` LEAF field also has ProtoType "message" (with GoType "string", MessageType unset, env_var set). Those are real scalar-carried config leaves and MUST be emitted (as `str`), not skipped — keying the skip on MessageType is what tells the two apart.

func GenerateEntityFactories ¶ added in v0.1.45

func GenerateEntityFactories(projectDir, modulePath string, services []ServiceDef, cs *checksums.FileChecksums) error

GenerateEntityFactories writes one forge-owned factories_gen_test.go per handler package, holding the typed New<Entity> row factories for the entities that package's CRUD RPCs own, and the New<CreateRequest> request factories for its create RPCs (create_request_factory.go).

Forge-owned + checksum-tracked, and regenerated on every run from the APPLIED schema. A project with no schema to model writes nothing. A schema that cannot be READ (an unreachable shadow server, a migration that does not apply) also writes nothing — the file on disk is left as it was rather than rewritten from no information — and only an embedded-postgres fetch failure is returned, so the caller can say why. A factory forge cannot derive a valid row or request for is still EMITTED, with a body that fails the calling test naming postgres's reason, and that reason is printed here as a warning: the scaffold-once lifecycle test calls these by name, so leaving one out would break compilation of every test beside it.

An entity whose CRUD RPCs no service declares is SKIPPED rather than parked in a shared package. The factory's whole value is being callable from the test that exercises that entity's handlers, and Go's in-package-_test.go visibility rule means it can only be called from the directory it lands in — so an entity with no owning handler package has no directory that could use it. Emitting one anyway would reintroduce exactly the importable-from- anywhere non-test package this move removed.

func GenerateEnvSecretsScaffold ¶ added in v0.1.45

func GenerateEnvSecretsScaffold(fields []ConfigField, projectName, projectDir, envName string) (bool, error)

GenerateEnvSecretsScaffold emits the gitignored `secrets/<envName>.yaml` that backs the env's `file` secret provider — ONLY for a LOCAL env, and ONLY when the file does not already exist. Returns true when a fresh file was written.

One key per SENSITIVE config field, keyed by env-var NAME, every one seeded EMPTY as a labelled slot to fill. That includes DATABASE_URL: the env's KCL declares the dev connection string from the port it resolves per render, so a copy here could only go stale — see devSecretValue for the full rationale. `forge env up` stays turnkey because the KCL declaration supplies the value.

Only local envs get one. A cloud env declares `forge.ExternalSecrets {}` — forge never sees those values, so scaffolding a store there would create a second, unread place to put a production credential.

func GenerateFrontendConfigJS ¶ added in v0.1.45

func GenerateFrontendConfigJS(frontend, env string, valuesJSON string) string

GenerateFrontendConfigJS renders the runtime config document for ONE environment — the artifact KCL's projection feeds and the browser loads.

It is a classic script (not a module) assigning a global, so a blocking <script src> in the document head guarantees the value exists before any bundle code runs. values is the rendered projection: env_var name -> value.

func GenerateFrontendConfigKCL ¶ added in v0.1.45

func GenerateFrontendConfigKCL(configs []FrontendConfig, projectName string) (string, error)

GenerateFrontendConfigKCL emits the frontend config module: one typed schema + one runtime projection lambda per frontend.

The projection returns a plain dict — the exact JSON object the browser receives as window.__FORGE_CONFIG__ — keyed by the field's env_var name where it declares one, falling back to the proto field name. Using the env_var as the key keeps ONE spelling of each fact across the proto, the KCL and the generated TypeScript, so a rename cannot half-land.

Sensitive fields never appear here: ValidateFrontendConfigs refuses them before generation reaches this point, which is why (unlike the backend schema) there is no ConfigSecretRef in the emitted module.

func GenerateFrontendConfigNative ¶ added in v0.1.45

func GenerateFrontendConfigNative(configs []FrontendConfig, projectName, projectDir, kclDirAbs string, cs *checksums.FileChecksums) error

GenerateFrontendConfigNative emits the project-level, forge-owned frontend config module at <kclDirAbs>/frontend_config_gen.k.

It mirrors GenerateConfigNativeShared's ownership handling so both KCL config modules land under the same tier and the same checksum ledger. When no frontend is annotated, any previously-emitted module is removed rather than left behind stale.

func GenerateFrontendConfigTS ¶ added in v0.1.45

func GenerateFrontendConfigTS(fc FrontendConfig, projectName, platform string) (string, error)

GenerateFrontendConfigTS emits the typed TypeScript module a frontend imports INSTEAD of touching process.env / import.meta.env.

── Why a runtime document rather than build-time inlining ──────────────

Next.js and Vite both inline NEXT_PUBLIC_* / VITE_* at BUILD time: the value becomes a string literal in the bundle. That makes a built artifact environment-SPECIFIC — it carries staging's issuer forever — which is exactly what `forge env deploy` exists to avoid. Promoting a bundle built against staging into production would point real users at the staging IdP.

So the values arrive at RUNTIME instead, as a small JS document (config.js) that assigns a global before any bundle code runs. The document is a static asset: KCL renders one per environment, and promoting an artifact means shipping the same bundle beside a different config.js. Nothing is rebuilt.

A blocking classic <script src> is what makes this safe to depend on at module scope. The alternative — fetch("/config.json") at boot — is asynchronous, so every consumer would have to await it, and the OIDC provider needs its issuer during module initialization to decide whether auth is even configured. A synchronous global removes that ordering problem entirely.

── Server rendering ────────────────────────────────────────────────────

A Next.js `standalone` build also renders on the server, where there is no window. There the module reads process.env, which in a deployed workload is populated from the SAME KCL config — so both paths have one source and cannot disagree. This is not a dotenv fallback: no .env file is read, written, or consulted.

func GenerateGraph ¶ added in v0.1.46

func GenerateGraph(in GraphGenInput) error

GenerateGraph emits the composition graph for a project in graph mode (GraphComposition): compose.go reconciled, graph_gen.go and routes_gen.go regenerated.

func GenerateGraphProviders ¶ added in v0.1.46

func GenerateGraphProviders(modulePath, databaseDriver, projectDir string) error

GenerateGraphProviders scaffolds a graph-mode project's owned internal/app/providers.go (the default providers: the database pool and ORM, the outbound HTTP client, the user audience's authenticator, chain and API listener, pprof) and auth.go, each exactly once.

func GenerateInventory ¶

func GenerateInventory(in InventoryGenInput) error

GenerateInventory emits internal/app/mounts_services.go: the typed per-service Mount<Svc> methods over *Components, the typed MountByName map, MountAll, and the data-only `var Inventory = []ComponentInfo{...}` that introspection (forge project map / audit / services listing) reads. It is ALWAYS written when internal/app is emitted (no len(Services)==0 early-return): cmd/server.go references app.Inventory / the typed mounts unconditionally, so the symbols must exist even with no Connect services.

func GenerateK3dPorts ¶

func GenerateK3dPorts(in K3dPortsGenInput) error

GenerateK3dPorts writes deploy/k3d-ports.yaml. Returns nil when there are no listeners — the caller is expected to ensure a stale file is removed in that case (handled in the pipeline gate, not here).

The function is idempotent: same input → byte-identical output. Listeners are sorted by (port, gateway, name) so a hand-rearranged ingress.k doesn't produce a no-op diff.

func GenerateLifecycle ¶

func GenerateLifecycle(in InjectGenInput) error

GenerateLifecycle emits internal/app/lifecycle.go: the supervised- component surface (typed Worker<X>()/Operator<X>() accessors + AllWorkers / AllOperators / HasOperators / RunOperators) over the constructed *Components. Where mounts_services.go is the HTTP surface, this is the worker/operator surface the cmd layer registers onto serverkit.Server. Always written (no len==0 early-return) so cmd/server.go's references resolve even with zero supervised components.

func GenerateLoginBroker ¶ added in v0.1.45

func GenerateLoginBroker(modulePath, projectName, projectDir string) error

GenerateLoginBroker scaffolds internal/app/login_broker.go ONCE — the OWNED server half of the API-only sign-in flow, which lets an app render its own sign-in screen instead of redirecting the user to the identity provider's login pages.

WHY IT IS SCAFFOLDED UNCONDITIONALLY rather than behind a config check. Whether a project uses this flow is decided by config at RUN time (idp_login_uri), and config is per-environment: the same build serves an environment that uses the issuer's pages and one that does not. Emitting the file only when some environment happens to set the field would make the code's existence depend on which env file was read at generate time, which is exactly the kind of spooky action this generator avoids.

The file costs nothing when unused — nothing calls RegisterLoginBroker unless the project wires it — and a project that will never use it deletes the file, which the scaffold-once guard respects permanently.

Scaffold-once, never overwritten after first emit: the user owns the bytes, including the security-critical handler that decides which credentials get checked. See the template's header for what must not be changed carelessly.

func GenerateMigrate ¶

func GenerateMigrate(targetDir string, modulePath string, hasMigrations bool, cs *checksums.FileChecksums) error

GenerateMigrate writes db/embed.go — the project's embedded migration set — and retires the pkg/app/migrate.go that used to sit beside it.

WHAT MOVED, AND WHY. pkg/app/migrate.go was 86 lines of Tier-1 golang-migrate ceremony: read the embedded dir, build a source driver, bind the pool, read the version, refuse a dirty schema, fold ErrNoChange. Not one line of it was derived from anything the user wrote — the ONLY project-specific value in the whole file was the identifier `forgedb.MigrationsFS`. A file that is byte-identical in every project except one symbol is library code parked in the user's tree: regenerating it cannot keep it correct, because it was never a function of the inputs.

So the ceremony is now migratekit.AutoMigrate(fs, dir), and the project keeps only the call site — a single expression in the serve.go it already owns, naming its own embedded FS. Improvements to the migration logic now arrive through a forge/pkg bump instead of a re-render.

db/embed.go STAYS generated, and is the reason this function still exists: the `//go:embed migrations/*.sql` directive can only live in the db/ package beside the SQL, and whether it can be written at all is a fact re-read from disk on every run (the directive does not compile against an empty match). That is a genuine projection of user input, which is exactly what Tier-1 is for.

cs is the project's checksum tracker — db/embed.go is recorded so `forge project audit` doesn't flag drift on it. A nil cs is tolerated.

func GenerateProviders ¶

func GenerateProviders(modulePath, databaseDriver string, ormEnabled bool, projectDir string) error

GenerateProviders writes internal/app/providers.go ONCE — the owned Infra + OpenInfra (scaffold-once, never overwritten; os.Stat guard below). compose.go (NewComponents) wires each component's Deps INLINE off these Infra fields; the user grows this file as NewComponents reports missing providers.

func GenerateServiceStub ¶

func GenerateServiceStub(svc ServiceDef, targetDir string, crudMethodNames ...map[string]bool) error

GenerateServiceStub generates service.go plus one handler file per custom RPC (RPCHandlerFileName) for a new service, using the embedded FS templates. crudMethodNames lists methods that CRUD gen will implement; these are excluded from the initial stubs.

func GenerateTierKCL ¶ added in v0.1.45

func GenerateTierKCL(in *TierSchemas, pkgPath string) (string, error)

GenerateTierKCL renders the KCL module text. It is pure: the same schemas always produce byte-identical output.

func GeneratedMarkerExpr ¶ added in v0.1.45

func GeneratedMarkerExpr(comment string) (expr string, found bool)

GeneratedMarkerExpr returns the SQL expression carried by a `forge:generated` marker in comment, trimmed, and whether comment carries the marker at all. A marker with nothing after it reports ("", true): the caller refuses that, since a GENERATED column with no expression is not a column postgres can create.

The expression is the REST OF THE LINE, verbatim. Prose cannot share the line — there is no telling where SQL ends — so a comment explaining the derivation goes on its own line above.

func GetModulePath ¶

func GetModulePath(dir string) (string, error)

GetModulePath reads the module path from go.mod in the given directory.

func GoPackageForProtoFile ¶ added in v0.1.45

func GoPackageForProtoFile(protoFile, modulePath string) string

GoPackageForProtoFile derives the generated Go import path for a proto file under the buf module root. The buf module root is "proto/", and the go_package convention forge projects use is `<module>/gen/<dir>` where <dir> is the proto file's directory relative to "proto/" (e.g. "reliant/v1/daemon_registry.proto" → "<module>/gen/reliant/v1"). Returns "" when modulePath is empty or the path has no directory component.

func GraphComposition ¶ added in v0.1.46

func GraphComposition(projectDir string) bool

GraphComposition reports whether the project composes with the composition graph: true for a new project and for one whose internal/app has no legacy composition (`type Infra struct` or `func NewComponents`) in an owned file.

func GuardTargets ¶ added in v0.1.45

func GuardTargets(comment string) []string

GuardTargets returns every `<table>.<column>` a comment declares with ProtoMarkerGuards, in declaration order. Trailing prose after the target is tolerated (`forge:guards invoices.amount_paid_cents — refuses overpayment`), a bare `forge:guards` with no target yields nothing, and a longer token that merely starts with the marker (`forge:guardsmen`) is refused — the same exactness the rest of the registry enforces, for the same reason: a marker that half-matches changes generated output on a spelling its author never wrote.

A field may carry several, which is the shape a multi-column guard actually takes: ScheduleJob owns crew_id, scheduled_start AND scheduled_end together, and declaring them one per line keeps each target individually greppable.

func HasConfigProtos ¶ added in v0.1.45

func HasConfigProtos(projectDir string) bool

HasConfigProtos reports whether proto/config holds a .proto file — the input the config loader generates pkg/config from. A proto/config directory with no proto in it (a CLI scaffold leaves an empty proto/config/v1) is not one: generating the loader from forge's default fields there writes a pkg/config importing gen/config/v1, which nothing will ever generate.

func HasConstructorMarker ¶ added in v0.1.45

func HasConstructorMarker(dir string) bool

HasConstructorMarker reports whether the package rooted at dir carries the `// forge:constructor` marker on its `func New` doc comment — the opt-in signal for the generated observability decorator.

func HasConstructorMarkerOn ¶ added in v0.1.45

func HasConstructorMarkerOn(fn *ast.FuncDecl) bool

HasConstructorMarkerOn reports whether THIS declaration carries `// forge:constructor`, as opposed to the package containing one somewhere (HasConstructorMarker).

The per-decl answer is what tells a lint whether the marker is advice the author has already taken. The marker frees a constructor's NAME and has never affected its signature, so prescribing it for a signature gap on a func that already carries it is advice that cannot work — and an author who tries it concludes the rule is unsatisfiable.

func HasExcludeContractDirective ¶

func HasExcludeContractDirective(dir string) bool

HasExcludeContractDirective reports whether the package rooted at dir declares `//forge:exclude-contract` in any of its non-test .go files, in either the reasoned form (`//forge:exclude-contract: <why>`) or the bare one. A package carrying this directive opts OUT of contract codegen — the per-package equivalent of forge.yaml `contracts.exclude`.

The bare form still EXCLUDES here, deliberately: codegen must never break a project over the spelling of an opt-out. It is `forge lint` that refuses a bare marker (see internal/linter/contract/exclude_directive.go), because a reason is what turns the cheapest way to silence the contract rules into a decision a reviewer can evaluate.

func HasExternalComponentDirective ¶

func HasExternalComponentDirective(dir string) bool

HasExternalComponentDirective reports whether the package rooted at dir declares `//forge:external-component` (or `//forge:provided`) in any of its non-test .go files. A package carrying this directive is skipped by the Build injector (it is hand-wired in providers.go / OpenInfra) but STILL gets its contract/mock codegen.

func HasNotAComponentDirective ¶ added in v0.1.45

func HasNotAComponentDirective(dir string) bool

HasNotAComponentDirective reports whether the package rooted at dir declares `//forge:not-a-component` in any of its non-test .go files, with or without a reason. Such a package keeps its contract codegen (mock, and the decorator if it opts in) but is not a component of the server composition: compose.go never constructs it and never resolves its Deps.

The bare form counts here for the same reason a bare exclude-contract does: codegen must never break a project over the spelling of a marker. `forge lint` refuses the bare form (forge-not-a-component-reason).

func HasOptionalDepMarker ¶

func HasOptionalDepMarker(text string) bool

HasOptionalDepMarker returns true if any line in the comment text is *exactly* the `forge:optional-dep` directive (after stripping leading slashes / whitespace and trailing whitespace). The strict match — directive must be the whole line, not embedded inside surrounding prose — prevents documentation that references the marker (e.g. an example block in the scaffolded service.go that says "tag it with the `// forge:optional-dep` marker on the line above") from being interpreted as the marker itself.

Exported so the lint rule (forgeconv-optional-dep-marker-position) can share the exact same recognition logic the parser uses — the rule is "the marker is on a Deps field; anywhere else is a typo / misuse" and the lint check needs to scan for the marker in places it shouldn't be.

IMPORTANT: callers parsing an *ast.CommentGroup should prefer HasOptionalDepMarkerCommentGroup over passing `cg.Text()` here. Go's ast.CommentGroup.Text() silently drops `//directive` form comments (the no-space variant — same shape as `//go:generate`, `//go:noinline`, etc.) which means `//forge:optional-dep` written without a space would be invisible to this function when fed via .Text(). HasOptionalDepMarkerCommentGroup iterates cg.List directly and recognizes both spaced (`// forge:optional-dep`) and unspaced (`//forge:optional-dep`) forms, matching the user's intent.

func HasOptionalDepMarkerCommentGroup ¶

func HasOptionalDepMarkerCommentGroup(cg *ast.CommentGroup) bool

HasOptionalDepMarkerCommentGroup returns true when any comment in the group is the `forge:optional-dep` marker. Unlike HasOptionalDepMarker (which takes the post-.Text() string), this helper inspects the raw c.Text of each *ast.Comment in cg.List, so it recognizes both the spaced form (`// forge:optional-dep`) and the unspaced directive form (`//forge:optional-dep`).

The unspaced form is otherwise invisible to ast.CommentGroup.Text() because Go treats `//<no-space><alnum>` as a compiler/linter directive (same shape as `//go:generate`, `//go:noinline`, `//nolint:...`) and strips it from the joined text. That stripping is a silent footgun for forge users who omit the space — the marker looks present in source but the parser would never see it, so the field would be treated as required, validateDeps would reject nil, and the user's "I marked it optional" intent would be ignored.

Both shapes are accepted; the marker must still be the whole comment (after stripping `//`, `/*`, `*/`, and leading/trailing whitespace). A nil group returns false. Inline /* … */ blocks are honored too — the parser logic is symmetric across both Comment kinds.

func HasOutboundIODirective ¶ added in v0.1.45

func HasOutboundIODirective(dir string) bool

HasOutboundIODirective reports whether the package rooted at dir declares `//forge:outbound-io` in any of its non-test .go files — the marker the adapter scaffold stamps on contract.go. It asserts one property: this package calls OUT to a third-party system and nothing calls in. Two mechanisms read it — the outbound-io-no-rpc contract check (an inbound handler contradicts the claim) and the enforce-component-observe lint's I/O heuristic (an outbound boundary does I/O by definition, so a component depending on one touches I/O).

func HasPackageNoObserveDirective ¶ added in v0.1.45

func HasPackageNoObserveDirective(dir string) bool

HasPackageNoObserveDirective reports whether the package rooted at dir opts OUT of observability at the PACKAGE level via `// forge:no-observe` (on the constructor, package doc, or contract interface). Method-level opt-outs are not reported here — see MethodDef.SkipObserve.

func HasServiceContractMarker ¶ added in v0.1.45

func HasServiceContractMarker(groups ...*ast.CommentGroup) bool

HasServiceContractMarker reports whether any of the given comment groups carries the `//forge:service` or `//forge:contract` marker. The marker must be the WHOLE comment line (after stripping comment syntax + whitespace), matching every other forge directive, so prose that merely mentions it is never a false match. Both spaced (`// forge:service`) and unspaced (`//forge:service`) forms are recognized. Shared by DetectServiceInterfaceName (codegen) and the contract-name lint (contractcheck) so the two never drift on what counts as marked.

func HostedRefusal ¶ added in v0.1.45

func HostedRefusal(kind string) string

HostedRefusal is why the hosted runtime's Restricted profile refuses a workload of kind, or "" when it admits it. The control plane is the authority (deploytarget.PreflightHosted runs its admission at render); this names the kinds a SCAFFOLD must not bind there, so a new workload is never bound somewhere it cannot run.

func InstanceName ¶ added in v0.1.45

func InstanceName(messageName string) string

InstanceName is the member a config's instance takes on the bundle, and the name the per-env config.k scaffold declares it under: `ApiServerConfig` -> `api_server_config`.

func IntrospectComponentNames ¶

func IntrospectComponentNames(projectDir string) []string

IntrospectComponentNames is the flat service-name list (e.g. a "did you mean" hint). Order matches IntrospectComponents.

func IntrospectComponents ¶

func IntrospectComponents(projectDir string) []config.ComponentConfig

IntrospectComponents enumerates a project's Connect SERVICES from the proto descriptor — the single authoritative, non-brittle source (the same one all of codegen reads via ParseServicesFromProtos). It is the shared seam every read-only diagnostic consumer (audit, graph, api, dev info, architecture docs, run, doctor parity, debug) reads a project's services through.

It enumerates SERVICES only. The supervised kinds (worker, operator) and secondary binaries have no proto contract, so they are discovered from their package directories instead — see DiscoverProjectComponents, which unions the two into an Inventory and is what every caller that needs the project's FULL component set goes through.

Each entry carries only Name, Kind=server, and the conventional handler Path. Ports are a DEPLOY fact (they live in KCL), left unset. Best-effort: a missing or unparsable descriptor yields no services (not an error), so the surface it decorates degrades gracefully rather than failing.

func IsComponentConstructor ¶ added in v0.1.45

func IsComponentConstructor(fn *ast.FuncDecl) bool

IsComponentConstructor reports whether fn is a constructor forge should treat as a component entry point.

The rule, in priority order:

1. a func carrying `// forge:constructor` IS one, whatever it is named;
2. otherwise a func named `New` is one, so an unmarked package still works.

WHY THIS EXISTS. Three separate scanners used to spell this as `fn.Name.Name != "New"`, which made `// forge:constructor` unreadable on any other name — the marker whose entire job is to identify a constructor was gated on the constructor already being called `New`. Tagging `NewReadOnly`, `Open` or `Connect` did nothing, silently.

It also forced a name. forge detects the CONTRACT name (DetectServiceInterfaceName, with `Service` only as a fallback) precisely so a package can call its interface `Mailer` or `Repository`; the constructor deserves the same freedom. forge is meant to promote good practice, not to require that every component be `New` returning `Service`.

func IsKnownProtoMarker ¶ added in v0.1.45

func IsKnownProtoMarker(name string) bool

IsKnownProtoMarker reports whether name is a marker forge reads out of a proto comment. The comparison is EXACT: `forge:read-only-ish` is not `forge:read-only`, the same discipline the column-marker check enforces so a longer marker cannot pass as a shorter one it merely starts with.

func IsLocallyDeclaredInterface ¶

func IsLocallyDeclaredInterface(typeExpr string, locals map[string]LocalInterface) bool

IsLocallyDeclaredInterface reports whether typeExpr (as printed by printType — a bare identifier or selector) names an interface declared in locals. The Deps field type is matched ignoring surrounding pointer/array decoration: only fields with type "T" where "T" is a local interface name are auto-stubbable. Pointer-to- interface (`*Repository`) is not idiomatic and is left to the hand-roll path.

func IsProtoScalarKind ¶ added in v0.1.45

func IsProtoScalarKind(kind string) bool

IsProtoScalarKind reports whether the token names one of the fifteen proto scalar kinds.

It reads the closed table rather than carrying a set of its own, so the scanner's notion of "this token is a scalar, not a type name" and the projections' notion of "I have an answer for this kind" are the same notion. When they were two, a kind either table omitted was classified as a message type name by one and projected to `string` by the other, and neither said anything.

func IsScaffoldTestFile ¶ added in v0.1.45

func IsScaffoldTestFile(name string) bool

IsScaffoldTestFile reports whether a bare filename is one of forge's born per-RPC scaffold tests. It also accepts the single-file `handlers_scaffold_test.go` that projects born before the per-RPC split still have: that file is on real users' disks and the consumers of this predicate (stale-pb-reference detection, test-helper reconciliation) have to keep working on it.

func IsUnmanagedMarkerLine ¶ added in v0.1.45

func IsUnmanagedMarkerLine(line string) bool

IsUnmanagedMarkerLine reports whether one raw proto source line is the `// forge:unmanaged` marker, by the same rule the raw scan applies — for line scanners outside this package that track their own declarations.

func IsWiredComponentDir ¶ added in v0.1.45

func IsWiredComponentDir(dir string) bool

IsWiredComponentDir reports whether dir is a forge-WIRED component — the single predicate that decides whether a package occupies a slot in the generated test-factory namespace (`app.NewTest<X>`).

A wired component is a package forge itself constructs, which means all four of:

• it declares a contract.go (the Service/Deps/New triple lives there);
• it is not opted out with `//forge:exclude-contract` — a types-only package (internal/db, internal/deploy) carries this precisely because there is nothing to construct;
• it is not `//forge:external-component` — hand-built in providers.go / OpenInfra, so forge emits no factory for it either;
• it is not `//forge:not-a-component` — the server composition does not construct it at all (a CLI- or daemon-only package), so there is no forge-wired instance for a factory to stand in for. It keeps its mock_gen.go, which is the seam its consumers test against.

WHY THIS EXISTS AS ONE FUNCTION. The name is derived by two generators — the helpers generator (which builds its namespace from real components) and ComputeTestHelperName (which drives the scaffold tests). They used to ask DIFFERENT questions: the helpers generator asked "is this a component", ComputeTestHelperName asked only `os.Stat(internal/<pkg>)`, "does a directory exist". A types-only internal/deploy answered no to the first and yes to the second, so testing.go declared NewTestDeploy while sixteen scaffold tests referenced NewTestSvcDeploy, and the package did not compile. Routing both through this predicate is what makes that disagreement unrepresentable rather than merely fixed once.

The forge.yaml `contracts.exclude` list is deliberately NOT consulted here: it is a whole-subtree opt-out read by DiscoverInternalPackages, which removes those packages from the inventory before either generator sees them. A path that never reaches the namespace cannot collide with it.

func KCLAllSensitiveName ¶ added in v0.1.45

func KCLAllSensitiveName(schemaName string) string

KCLAllSensitiveName maps a config SCHEMA name to the generated constant listing every sensitive ENV_VAR that schema declares: `AppConfig` -> `APP_CONFIG_SENSITIVE_ENV`.

It exists so the one caller that legitimately wants EVERY credential — forge's own host-mode config probe, which resolves what the env's config evaluates to for `forge env up`, the parity report and the seed gate — can say so by name instead of hand-listing vars that would go stale the moment a field is added. A cluster WORKLOAD must never use it: naming the whole set is precisely the broadcast this design removed.

func KCLConfigName ¶ added in v0.1.45

func KCLConfigName(messageName string) (schema, lambda string)

KCLConfigName maps a config MESSAGE name to the KCL schema and lambda it projects to: `AdminConfig` -> schema `AdminConfig`, lambda `adminConfigEnvMap`. The lambda name is the schema name lower-camelled with the `EnvMap` suffix, matching the existing appConfigEnvMap spelling so the per-binary names read as the same family.

func KCLFrontendConfigName ¶ added in v0.1.45

func KCLFrontendConfigName(messageName string) (schema, lambda string)

KCLFrontendConfigName maps a frontend-bound config MESSAGE name to the KCL schema and projection lambda it generates: `WebConfig` -> schema `WebConfig`, lambda `webConfigRuntime`. The `Runtime` suffix (rather than the backend's `EnvMap`) says what the projection produces: the runtime config document the bundle reads, not a set of env vars.

func KCLOptionalSecretsName ¶ added in v0.1.45

func KCLOptionalSecretsName(schemaName string) string

KCLOptionalSecretsName maps a config SCHEMA name to the generated constant listing every sensitive ENV_VAR that schema marks `optional: true`: `AppConfig` -> `APP_CONFIG_OPTIONAL_SECRET_ENV`.

It is the seam the secret PRE-FLIGHT reads. `forge env up` validates every declared secret_ref against the store before anything starts, and it works from the rendered entities — it has no proto and no descriptor in hand. So the proto's `optional` annotation is projected to KCL here and travels with the render, which keeps the dependency running one way: the secrets package never learns what a config message is.

Emitted even when empty so a reference resolves in a project that marks nothing optional.

func LegacyConfigModules ¶ added in v0.1.45

func LegacyConfigModules() []string

LegacyConfigModules names the pre-merge KCL modules that config_gen.k replaced: the TYPE half (config_schema.k) and the BEHAVIOR half (config_projection.k), which were two Tier-1 files, two hash guards and two diff entries for one projection. Existing projects have them on disk; RemoveLegacyConfigModules withdraws forge's own copies once the merged file is in place.

func MigrateArgs ¶ added in v0.1.45

func MigrateArgs() []string

MigrateArgs returns the subcommand of the project binary that applies its embedded migrations (`db migrate up`, cmd-tree-db.go.tmpl).

It is the workload's `args`, not a container argv: the image's ENTRYPOINT is the binary (Dockerfile.tmpl), and the host runtime derives `go run ./cmd/<project> db migrate up` from the same build + args. One declaration selects the subcommand on every runtime, so it cannot drift from the image or the host process it runs in.

This is a SCAFFOLD-TIME default only. It is written literally into deploy/kcl/workloads.k once, and the project owns it from then on: how a system migrates is an operational decision that differs per environment and changes over time (an env may migrate out of band, or run a different tool entirely). forge does not re-derive it.

func MigrateConfigBlockReferences ¶ added in v0.1.45

func MigrateConfigBlockReferences(kclDirAbs string, instances []ConfigInstanceBlocks) ([]string, error)

MigrateConfigBlockReferences rewrites flat block-leaf references in each env's config.k and main.k under kclDirAbs to their nested paths, for the given instances. Returns the project-relative files it rewrote.

func MigrateWorkloadStanza ¶ added in v0.1.45

func MigrateWorkloadStanza(modulePath, projectName string) string

MigrateWorkloadStanza renders the deploy-time migration step as the KCL literal that belongs in deploy/kcl/workloads.k.

It is an ORDINARY WORKLOAD — `kind = "job"` with the broadcast `before` — and that is the entire point. Migration used to be a bespoke `migrate: [str]` field on WorkloadEnv that the render layer had special knowledge of. It is now one instance of the one-shot primitive, so it reads, refines, and can be dropped exactly like anything else the project ships.

`before = [fw.BEFORE_ALL]` rather than an enumerated list of dependents is the load-bearing choice. An enumerated list is a list that goes STALE: add a workload six months from now and the list still renders, still passes every check, and silently does not gate the new one — a pod serving traffic against a schema it does not have. The broadcast selector has nothing to forget to update.

The `build` names the project's own binary, the same GoBuild every component declares: forge builds a (cmd, output) pair once however many workloads name it, so this compiles nothing extra. It is what lets the host runtime derive `go run ./cmd/<project> db migrate up`, and the cluster runtime pick the image, from one declaration.

`config_secrets = ["DATABASE_URL"]`: the job needs the DSN and nothing else, so it is the one credential projected into it.

func MockRelPath ¶ added in v0.1.45

func MockRelPath(svc ServiceDef) string

MockRelPath is the project-relative path of svc's generated mock — the one name both GenerateMock's write and generate's progress line use, so the log can never name a file the run did not write (it said <svc>_mock.go after the file became <svc>_mock_gen.go).

func OptionalSecretEnvVars ¶ added in v0.1.45

func OptionalSecretEnvVars(messages []ConfigMessage) []string

OptionalSecretEnvVars returns the env-var names of every sensitive field marked optional, across all messages.

This is the seam the secret pre-flight consumes: it works in terms of env names (that is what a secret_ref carries by the time it reaches the store), so the proto-level annotation is reduced to a name set here rather than teaching the secrets package about config messages. The dependency runs one way — secrets knows nothing about proto.

Non-sensitive optional fields are deliberately NOT included. `optional` on an ordinary field already means "no value needed" everywhere it matters, and nothing pre-flights it; returning it here would only invite a caller to think this set means something broader than it does.

func OwnerColumn ¶ added in v0.1.45

func OwnerColumn(entity EntityDef) string

OwnerColumn returns the entity's `forge:owner` column name, or "" when the table declares none. See CRUDMethodTemplateData.OwnerColumn.

func ParseCRUDOperation ¶

func ParseCRUDOperation(methodName string) (operation, entityName string)

ParseCRUDOperation extracts the CRUD operation and entity name from a method NAME alone. Returns ("", "") if the name doesn't match a CRUD pattern. Name-only, so it cannot see `// forge:custom` or streaming: classify an rpc you hold as a Method with CRUDShape instead.

func ParseExcludeContractComment ¶ added in v0.1.45

func ParseExcludeContractComment(raw string) (reason string, ok bool)

ParseExcludeContractComment reports whether one raw comment IS the exclude-contract directive, and its reason. Accepted, spaced or not:

//forge:exclude-contract: <why>   → ok, reason "<why>"
//forge:exclude-contract          → ok, reason "" (bare — lint refuses it)

Anything else — prose that mentions the directive, `forge:exclude-contract, forge:outbound-io, …` lists, a different separator — is not the directive, matching every other forge marker's whole-line rule.

func ParseLocalInterfaces ¶

func ParseLocalInterfaces(dir string) (map[string]LocalInterface, error)

ParseLocalInterfaces returns every interface type declared in non- test .go files under dir. The set is keyed by interface name so callers can index by the Deps field's pretty-printed type.

Returns an empty map (never nil) and no error if dir doesn't exist — callers treat the absent case the same as "no local interfaces to stub" and fall back to nil for that field.

func ParseNotAComponentComment ¶ added in v0.1.45

func ParseNotAComponentComment(raw string) (reason string, ok bool)

ParseNotAComponentComment reports whether one raw comment IS the not-a-component directive, and its reason — the same two accepted spellings as ParseExcludeContractComment.

func ParsePackageClause ¶

func ParsePackageClause(dir string) (string, error)

ParsePackageClause returns the Go package name declared by the .go files directly inside dir (PackageClauseOnly parse — cheap; no type checking, no imports). _test.go files and files starting with "." or "_" are skipped, matching the go tool's build-file rules; external test packages ("foo_test") therefore can't pollute the result.

Errors are diagnostics, not soft fallbacks:

• dir unreadable or containing no buildable .go file → error telling the user the directory can't be used as a component source dir;
• files disagreeing on the package clause → error listing each file:line with its declared package so the user can fix the stray clause directly.

func PascalToKebab ¶

func PascalToKebab(s string) string

PascalToKebab converts PascalCase to kebab-case, respecting Go initialisms (LLM, API, URL, JSON, …) so that "LLMGateway" produces "llm-gateway" rather than "l-l-m-gateway".

Thin wrapper around naming.ToKebabCase — kept here for backwards compatibility with existing callers (frontend_pages, frontend_mocks, related tests). New code should call naming.ToKebabCase directly.

func PendingServiceMount ¶ added in v0.1.45

func PendingServiceMount(root, bin, runtimeName string) string

PendingServiceMount reports the `(*Components).Mount<Svc>` method the service's generated mount file is waiting for — non-empty exactly when that file is the MountMissing placeholder (see cmd-svc-mount-gen.go.tmpl). It reads the file generate just wrote rather than re-deriving the answer, so the scaffold's report can never disagree with what was emitted.

func ProjectBinaries ¶ added in v0.1.45

func ProjectBinaries(projectDir string) []string

ProjectBinaries lists the binaries a (forge.v1.binary_config).binary may name: the directory leaves under projectDir/cmd.

A project with no cmd/ directory has NO binaries (an empty, non-nil slice), so a binding there is refused. nil means UNKNOWN — cmd/ exists but could not be read — and the existence check is then skipped rather than reporting every binding as dangling: "forge could not tell" must never render as "it does not exist".

func ProjectBinaryRuns ¶ added in v0.1.45

func ProjectBinaryRuns(projectName, buildCmd string) bool

ProjectBinaryRuns reports whether a workload declared with build command buildCmd runs the project's primary binary — the `./cmd/<project>` GoBuild every scaffolded stanza names (projectGoBuild).

func ProjectHasSQLMigrations ¶ added in v0.1.45

func ProjectHasSQLMigrations(projectDir string) bool

ProjectHasSQLMigrations reports whether db/migrations/ contains at least one .sql file — the ONE predicate every consumer of "does this project ship migrations" reads, so they cannot disagree:

• GenerateMigrate embeds db/embed.go's MigrationsFS
• component_test_helpers.go.tmpl imports forgedb (which only exists when GenerateMigrate saw migrations)
• cmd-tree-db.go.tmpl compiles `db migrate` against the EMBEDDED set
• the scaffolded per-env `migrate` argv, which the env render turns into a migration initContainer

func ProjectHasTypedConfig ¶ added in v0.1.45

func ProjectHasTypedConfig(projectDir string) bool

ProjectHasTypedConfig reports whether the project has the typed config a scaffolded component's `Deps.Config *config.Config` names: config protos the loader turns into pkg/config, or a pkg/config that already declares Config (a CLI's stub, a hand-written one).

A project adopted in place often has neither — its configuration lives in its own package. A component scaffolded there takes no Config: importing <module>/pkg/config would not compile, and a placeholder package configuring nothing is an empty default every caller would have to construct and pass. The project adds the field when it has config to give.

func ProtoFileToTSImportPath ¶

func ProtoFileToTSImportPath(protoFile string) string

ProtoFileToTSImportPath converts a proto file path to the TypeScript import path used by the buf ES plugin. For example:

"proto/services/users/v1/users.proto" → "services/users/v1/users_pb"

The buf ES plugin strips the leading proto/ directory and replaces the .proto extension with _pb.

func ProtoMarkerAnyCommentRE ¶ added in v0.1.45

func ProtoMarkerAnyCommentRE(markers []string) *regexp.Regexp

ProtoMarkerAnyCommentRE is ProtoMarkerAnyLineRE for comment text buf has already stripped the `//` from — the descriptor path's shape.

func ProtoMarkerAnyLineRE ¶ added in v0.1.45

func ProtoMarkerAnyLineRE(markers []string) *regexp.Regexp

ProtoMarkerAnyLineRE builds a recognizer matching ANY of markers in a `//`-prefixed proto comment, with the same spacing/trailing-prose rules as the single-marker builder. Alternation is over quoted marker names, so a longer token that merely starts with one of them is still refused.

func ProtoMarkerCommentRE ¶ added in v0.1.45

func ProtoMarkerCommentRE(marker string) *regexp.Regexp

ProtoMarkerCommentRE builds the recognizer for a marker read out of a comment buf has ALREADY stripped the `//` from — the shape protogen hands to the descriptor path in internal/cli/forge_descriptor.go. Spacing and trailing prose are tolerated as above; `(?m)` lets it match any line of a multi-line comment block.

Exported because its callers live outside this package, unlike the two raw-source builders above.

func ProtoScalarGoType ¶ added in v0.1.45

func ProtoScalarGoType(kind string) (string, bool)

ProtoScalarGoType returns the Go type protoc-gen-go generates for a proto SCALAR kind. ok=false for anything else ("message", "enum", "map", a well-known type name) — callers branch on those before asking, and an unknown kind must never silently answer `string`, which is indistinguishable from the correct answer for the one kind that really is a string.

func ProtoScalarKinds ¶ added in v0.1.45

func ProtoScalarKinds() []string

ProtoScalarKinds returns the closed proto scalar vocabulary, sorted — the exact key set of the table above, never a restatement of it.

It is exported for the end-to-end corpus, which has to answer a question no unit test can: which kinds actually travelled scaffold → generate → proto → TypeScript → tsc. That corpus previously carried a hand-written list of field types, which is a guard that cannot fail — it covers the kinds someone remembered, and `bytes` was not one of them, so a `bytes` column shipped green and produced 33 tsc errors in a generated frontend. Deriving the corpus's obligation from this table instead means a kind added here is either exercised end-to-end or fails a test by name.

func ProtoTypeToGoType ¶

func ProtoTypeToGoType(protoType string) string

ProtoTypeToGoType converts a proto SCALAR kind to the Go type protoc-gen-go generates for it.

This is not forge's choice to make: the generated `pb` package already declares the field, and every projection that disagrees with it produces code that either refuses a legal shape or does not compile. Nine of the fifteen kinds used to answer "string" here — every unsigned, zigzag and fixed-width integer, plus `bytes` — with two different consequences:

• `bytes` and the eight integer kinds were rejected by the CRUD conversion gate, so an app declaring one could not run `forge generate` at all;
• `repeated bytes` PASSED, because the wire side answered []string and the column side (dbBaseGoType, collapsing every non-BIGINT[] array) also answered []string. Two wrong answers agreeing looked exactly like a mapped pairing, and the generator emitted `append([]string(nil), m.Chunks...)` against protoc-gen-go's real [][]byte field.

A non-scalar kind ("message", "enum", "map", "group") has no scalar Go type; callers branch on those BEFORE reaching here (see schemaFieldToEntityField, classifyFilterField), and the "string" answer is the inert fallback for a kind that never should have arrived. It is spelled here, at the one site that needs it, rather than as a `default:` arm on the table: a fallback inside the projection is reached by an unrecognised kind too, and cannot be told apart from a mapping.

func RPCHandlerFileName ¶ added in v0.1.45

func RPCHandlerFileName(rpc string) string

RPCHandlerFileName is the born handler file for one custom RPC — `rpc_<snake_name>.go`.

Same rule, same reason, as ScaffoldTestFileName next door: the name is derived from the RPC alone, so the mapping is total and reversible without a manifest, and two authors implementing two RPCs of the same service have nothing to merge. `forge scaffold rpc` has always written this name for an RPC that is not in the proto yet (internal/cli/scaffold/rpc.go); the generate pipeline now writes it too, so the two paths agree instead of disagreeing by which order the user happened to do things in.

There is no legacy-name predicate to go with it (no RPCHandlerFile analogue of IsScaffoldTestFile) because nothing needs one: every reader of these files — ScanExistingMethods, ScanUnwiredStubMethods, ExciseUnwiredStubs, `forge project audit`, mock_gen — walks the handler directory and is already indifferent to filenames. Projects born before the split keep their handlers.go and keep working, untouched.

func ReadOnlyColumns ¶ added in v0.1.45

func ReadOnlyColumns(entity EntityDef) []string

ReadOnlyColumns returns, in column order, every column of entity whose wire field is marked `forge:read-only` or `forge:computed` (EntityField .ReadOnly covers both — see ReadOnlyProtoMarkers). The primary key is left out: it addresses the row rather than being written by it.

A read-only wire field with no column is not a column anyone can write, and a column with no wire field is not one a client can name, so both are outside the answer.

func ReconcileConfigModuleImports ¶ added in v0.1.45

func ReconcileConfigModuleImports(kclDirAbs string) ([]string, error)

ReconcileConfigModuleImports rewrites references to the superseded config_schema / config_projection KCL modules to the merged config_gen across the USER-OWNED files that name them: each env's config.k (which does `import config_schema` and types its instance `config_schema.AppConfig`) and each env's main.k (`import config_projection`, `config_projection.appConfigEnvMap(...)`).

Rewriting user-owned files needs justifying, since forge's rule is that it does not touch them. The alternative is worse: the module those files import no longer exists, so a project that regenerates without this fix gets a KCL tree that does not load at all — `forge env up`, `forge env deploy` and every render fail on an unresolved import until the user hand-edits every env. This is the same reconciliation ReconcileScaffoldTestHelperName performs when a forge-owned identifier a scaffold references gets renamed: forge renamed the symbol, so forge fixes the references it caused to dangle.

The rewrite is deliberately narrow — the module NAME only, on the import statement and on qualified references. Values, comments the user wrote, and every other line are preserved byte-for-byte. Returns the project-relative paths it rewrote, for the caller to report.

func ReconcileScaffoldTestHelperName ¶ added in v0.1.45

func ReconcileScaffoldTestHelperName(projectDir, servicePkg, targetDir string) (bool, error)

ReconcileScaffoldTestHelperName re-points the born scaffold tests' references to the forge-generated `app.NewTest<X>` / `app.With<X>Deps` factories at the collision-aware helper name pkg/app/testing.go actually emits for this service, and reports whether it rewrote anything.

It sweeps every scaffold test in the directory (IsScaffoldTestFile), not one fixed filename: the scaffold is one file per RPC.

GenerateServiceStub writes the scaffold test ONCE, at `forge project new` / `forge scaffold service`, using whatever ComputeTestHelperName resolved THEN — before any same-named domain package exists, so the plain form (`NewTestWidget`). When the RPC-vertical sweep later creates the `internal/<svc>` domain package, GenerateBootstrapTesting / ComputeTestHelperName flip the factory to the Svc-prefixed form (`NewTestSvcWidget`) to disambiguate it from the domain package's own `NewTestPkg<X>` factory — but the scaffold-once test is frozen on the stale name, an undefined reference that fails `go vet` on the very next generate. Reconciling ONLY these forge-owned factory identifiers on every generate keeps the owned scaffold test in lockstep with the regenerated testing.go, without touching the user's own test logic. It is idempotent (a no-op once the names already agree) and symmetric — it also rewrites back to the plain form if the domain package is later removed.

func RegenerateServiceFile ¶

func RegenerateServiceFile(svc ServiceDef, targetDir string) error

RegenerateServiceFile regenerates only service.go for an existing service directory, using the proto-derived HandlerName so that Connect RPC references (Unimplemented*Handler, New*Handler) match the actual proto service name.

func RemoveK3dPorts ¶

func RemoveK3dPorts(projectDir string) error

RemoveK3dPorts deletes deploy/k3d-ports.yaml when present. Used by the generator gate when the ingress feature is off, or when the dev env has no gateways — the previous-generate's file would otherwise become a stale port-mapping the user might forget about.

func RemoveLegacyConfigModules ¶ added in v0.1.45

func RemoveLegacyConfigModules(kclDirAbs string) error

RemoveLegacyConfigModules deletes the pre-merge config_schema.k / config_projection.k once config_gen.k supersedes them.

This is the same withdrawal RemoveK3dPorts performs for a generated file forge stops emitting: the files are Tier-1 forge output that nothing imports anymore, and leaving them would be worse than deleting them — they would sit in the tree as a stale second definition of AppConfig that no longer tracks the proto, and (being in the same KCL package as the merged file) would collide on the very symbols it declares.

Only forge's OWN renders are removed: a file whose generated-by stamp is missing has been taken over by the user, and it is left in place. It is deliberately NOT gated on the checksum manifest — a project regenerated by an older binary, or one whose ledger was rebuilt, still needs the collision cleared.

func RenderOpenProcedures ¶ added in v0.1.45

func RenderOpenProcedures(services []ServiceDef, modulePath string) ([]byte, error)

RenderOpenProcedures renders pkg/middleware/procedures_gen.go.

func RenderScopedCRUDShim ¶ added in v0.1.45

func RenderScopedCRUDShim(method, inputType, outputType, entity, ownerColumn string) (string, error)

RenderScopedCRUDShim renders the owner-scoping handler wrapper for one CRUD RPC: the caller resolution, the placeholder owner expression, and the op-seam override that puts ownerColumn into the query.

It is the same template, through the same renderer, that ensureCRUDShimFile uses at a handler file's birth — so what a user pastes into an existing handlers_crud.go and what a greenfield project is scaffolded are identical.

method must be a CRUD RPC name (Create/Get/List/Update/Delete + entity) and ownerColumn must be non-empty; anything else is an error rather than a guess.

func ResolveCollisionNaming ¶

func ResolveCollisionNaming(pkg, fallbackFieldName, rolePrefix string, counts map[string]int) (alias, fieldName string)

ResolveCollisionNaming returns the (Alias, FieldName) pair for a component given its raw Package name, a fallback FieldName the caller already computed for the no-collision case, the cross-role collision counts, and the component's role-short-name prefix ("svc", "pkg", "wkr", "op"). When the package collides cross-role, the result is (rolePrefix + Package, RolePrefix + Package) — alias is lower-camel, field name is upper-camel. Otherwise (Package, fallbackFieldName) — preserving the caller's per-role naming convention (services use ToPascalCase; workers/operators also use ToPascalCase so snake_case names produce idiomatic exported identifiers (`Workers.CalibratorRefit` rather than `Workers.Calibrator_refit`); nested packages use a path-encoded form via ToExportedFieldName).

Single source of truth for the wire_gen ↔ bootstrap naming agreement: both files derive their `wireXxxDeps` function name + `Services.Xxx` field reference from this helper, so the two stay in lockstep when a service package collides with an internal-package import.

func RetireGenerated ¶ added in v0.1.45

func RetireGenerated(projectDir, relPath string, cs *checksums.FileChecksums)

RetireGenerated deletes a generated file forge has STOPPED EMITTING outright — no successor, no rename, the output simply no longer exists.

This is the sibling of RetireRenamedGenerated, and the distinction is the carry-over. A rename has a destination, so a disowned copy is MOVED to the new name (the user's ownership survives forge's bookkeeping). A removal has no destination to carry anything to: the file is either forge's, in which case it goes, or the user's, in which case it stays exactly where it is and becomes an ordinary hand-maintained module. Routing a removal through the rename helper would invent a `_gen` twin nothing writes and move the user's file to a name they never chose.

Ownership is read from the file, never assumed — same test as every other retirement path: a verifying forge:hash marker certifies the bytes as forge's own render and it is removed; a Modified marker means hand-edited and it is kept; a disowned path is never touched. A path that does not exist is the common case (a project scaffolded after the removal) and is silently fine.

func RetireRenamedGenerated ¶ added in v0.1.45

func RetireRenamedGenerated(projectDir, oldRelPath string, cs *checksums.FileChecksums)

RetireRenamedGenerated deletes the OLD path of a generated file that forge has renamed, so the project is left with one copy under the new name rather than two that drift apart.

WHY A RENAME NEEDS THIS AT ALL. A generated file's old copy is still on disk after the emitter starts writing a new name, and it still carries forge's "Code generated — DO NOT EDIT" banner and hash marker. Nothing emits it anymore, which makes it exactly what the stale-artifact sweep deletes — but the sweep runs after every emitter, and before it the package has two declarations of the same symbols and does not compile. Reclaiming it here, in the emitter that supersedes it, is what makes a rename a single atomic-looking change to the user.

OWNERSHIP IS READ FROM THE FILE, never assumed. A copy that still verifies as forge's own render is forge's to remove; a hand-edited one is the user's work and is LEFT ALONE, even though that means the project keeps a stale file. Deleting a file forge did not write is not a tradeoff worth making to tidy a rename: the user can remove it, and forge cannot un-delete it.

A DISOWNED path is neither deleted nor ignored: it is CARRIED. The user disowned forge's output; the fact that forge later renamed that output is forge's own bookkeeping, not a user action that should void their ownership. Leaving the record on the old path was the fr-disown-rename bug: the new path looked unowned, so the emitter wrote a second file declaring the same symbols beside the user's, silently, and the package stopped compiling. CarryDisownAcrossRename moves the user's file (and its record) to the new name BEFORE the emitter writes, so the emitter's own disown check skips it and a collision cannot occur. See checksums/disown_rename.go for the full rationale and the refusal case.

Files with no marker at all fall back to the legacy banner check, which is what reaches projects generated before markers existed.

It is deliberately quiet about a path that does not exist — that is the common case (a project scaffolded after the rename) and not an event.

func RetiredEntityFactoryRelPath ¶ added in v0.1.45

func RetiredEntityFactoryRelPath() string

RetiredEntityFactoryRelPath is the pre-move location of the entity factories: their own non-test package, which every project scaffolded before this change still carries. GenerateEntityFactories' caller retires it so an upgrading project does not end up with both copies — the old one being a non-test .go file that imports `testing`, which is the shape this move exists to remove.

func RunsBuiltinSubcommand ¶ added in v0.1.45

func RunsBuiltinSubcommand(args []string) bool

RunsBuiltinSubcommand reports whether args, handed to the project binary, select a command the generated cmd tree itself owns rather than a component: `server` (every component in one process), `version`, `db …` (the scaffolded migrate job),

Judged by the FIRST arg, the top-level subcommand, so every leaf under a built-in (`db migrate status`, a later `auth` verb) counts without being listed. The set is derived, not restated: the top-level names the cmd tree reserves (reservedSubcommandNames) plus the command each scaffolded job's args select (MigrateArgs).

func RunsInServer ¶ added in v0.1.45

func RunsInServer(kind string) bool

RunsInServer reports whether a workload of kind is part of what the project binary's `server` runs: a service (mounted on its mux) or a worker (supervised beside it). Jobs run to completion on their own; an operator needs the Kubernetes API, which a hosted `server` does not have (it logs that operators are disabled and serves without them); a tool never runs.

func SameWorkload ¶ added in v0.1.46

func SameWorkload(a, b string) bool

SameWorkload reports whether two names spell the same workload: a declared `name` and a component name, in any of their forms.

func ScaffoldImageRef ¶ added in v0.1.45

func ScaffoldImageRef(modulePath, projectName string) string

ScaffoldImageRef is the image reference a scaffolded workload declares: the FULL reference, registry host included, because that is the only place a registry is declared — no environment carries one.

The registry is derived from the module path's GitHub owner (github.com/acme/shop → ghcr.io/acme/shop), which a GitHub-hosted project can push to with nothing but its workflow token.

A module path that names no GitHub owner gets a placeholder HOST rather than a bare name, and the shape of that placeholder is load-bearing:

• It must contain a dot, so it parses as a registry host. A bare `REPLACE_ME_REGISTRY/shop` does NOT — Docker's rule is that the first segment is a host only if it has a `.` or `:` — so the render would refuse the scaffold forge itself just wrote, and `forge env new --check` could not compile a fresh project.
• It must be obviously unreal. `.invalid` is reserved by RFC 2606 and can never resolve, so a scaffold that reaches a real push fails at the placeholder instead of silently pushing somewhere that happens to exist.

So the tree compiles, the value is visibly a placeholder, and the failure — if anyone tries to push it — names a host that provably belongs to nobody.

func ScaffoldOperatorCmd ¶

func ScaffoldOperatorCmd(targetDir, bin, name string) (bool, error)

ScaffoldOperatorCmd is the operator-side analog of ScaffoldWorkerCmd — writes cmd/<bin>/cmd/operators/<name>.go once for a single operator.

func ScaffoldTestFileName ¶ added in v0.1.45

func ScaffoldTestFileName(rpc string) string

ScaffoldTestFileName is the born unit-test file for one RPC.

One RPC per file, and the name is derived from the RPC alone, so the mapping is total and reversible without a manifest: a reader seeing handlers_scaffold_ship_order_test.go knows exactly which RPC it covers, and a second author implementing a different RPC in the same package has nothing to merge.

The prefix is stable and is what every consumer matches on (IsScaffoldTestFile) — including the pre-split `handlers_scaffold_test.go` that older projects still carry on disk.

func ScaffoldWorkerCmd ¶

func ScaffoldWorkerCmd(targetDir, bin, name string) (bool, error)

ScaffoldWorkerCmd writes the scaffold-once per-worker subcommand file cmd/<bin>/cmd/workers/<name>.go for a SINGLE worker, write-if-absent. This is the `forge scaffold worker` counterpart to the retired generate-time worker loop: one new component, known by name, scaffolded once as OWNED code (the dev then hand-wires it into main.go / lifecycle.go / compose.go). Returns true when it wrote a fresh file (false when one already existed).

func ScanExistingMethods ¶ added in v0.1.45

func ScanExistingMethods(dir string, includeGeneratedStubs bool) (map[string]bool, error)

ScanExistingMethods reads all .go files in dir and returns a set of method names that are already implemented on *Service. It uses go/parser so that multi-line receivers, comments, and strings containing "*Service" are handled correctly.

This is the dedup that lets a user's `handlers.go` claim a method (e.g. `func (s *Service) CreateUser(...) ...`) and have the next `forge generate` automatically drop the matching stub from `handlers_gen.go`. Same shape closes the FORGE_REVIEW_PROCESS.md §2.3 git_credential drift class — gen-files and user-files share the `*Service` receiver, so a method declared in either is sufficient signal that the proto RPC is implemented.

An individual file that fails to parse is skipped with a warning rather than failing the whole pass: a transient syntax error in a sibling file must not brick the dedup for the entire package, since losing dedup means the user's just-written `CreateUser` would be re-stubbed in handlers_gen.go and the package would fail to compile (duplicate method).

Exported for internal/scaffold (the typed RPC vertical shares this hand-implemented-method detection with the stub generator).

func ScanHandlersCrudMethods ¶ added in v0.1.45

func ScanHandlersCrudMethods(dir string) map[string]bool

ScanHandlersCrudMethods returns the set of *Service method names declared in handlers_crud.go specifically. ScanExistingMethods skips that file wholesale (its delegating shims must not suppress ops regen); this lets the stub generator look inside it to find HAND-WRITTEN (non-CRUD) impls that DO need to suppress a duplicate stub. Returns an empty set if the file is absent or unparseable — losing this signal only risks a duplicate-method compile error surfacing at the validate step, never a silent wrong result.

func ScanUnwiredStubMethods ¶ added in v0.1.45

func ScanUnwiredStubMethods(dir string) map[string]bool

ScanUnwiredStubMethods returns the set of RPC method names in one handler directory that still carry the unwired-stub marker — i.e. the generated CodeUnimplemented stubs nobody has implemented yet. Non-test, non-_gen.go files only (the marker only ever lands in the user-owned handler files). Unreadable dirs return an empty set.

func SeedFingerprint ¶ added in v0.1.45

func SeedFingerprint(projectDir string, cfg seedplan.Config) (files, withConfig seedplan.Fingerprint)

SeedFingerprint identifies the schema + seed config the project's fixtures are derived FROM, for the generated guard that has to notice when those inputs move without a regenerate.

It is deliberately NOT a method on SeedProjection, and that is the whole point of its existence. A projection requires a reachable postgres to build; the fingerprint requires only files on disk. Hanging it off the projection would delete the guard in exactly the case that needs it most — no shadow server, so BuildSeedProjection returns nil, every fixture degrades to a synthetic placeholder, and the project would then also carry no record of which schema those placeholders stood in for. Reading the inputs directly means the fixtures and the claim about them fail independently. It returns BOTH digests, and the caller must keep them straight:

• files hashes the migrations and vocab.yaml only. This is the one a process with no database can recompute — the emitted TypeScript guard reads exactly these files.
• withConfig additionally folds in the seed salt and row counts from forge.yaml, which change every fixture value without touching a migration, and which nothing outside Go can see.

They are returned as a pair rather than selected by a flag because the mistake this API exists to prevent is using one where the other belongs.

func ServesChoiceHint ¶ added in v0.1.45

func ServesChoiceHint(modulePath, projectName string, c config.ComponentConfig) string

ServesChoiceHint is what `forge scaffold` prints, in place of writing, when the project declares `serves` and the new component is in none.

func ServesHint ¶ added in v0.1.45

func ServesHint(componentName string) string

ServesHint is the one sentence `forge lint` and `forge scaffold` both use to say how a component served by another workload's process is marked as such.

func ServiceHasWebhooks ¶

func ServiceHasWebhooks(handlerDir string) bool

ServiceHasWebhooks reports whether a service's directory carries any webhook_<name>.go handler file.

func ServiceNameFromProtoFile ¶

func ServiceNameFromProtoFile(protoFile string) string

ServiceNameFromProtoFile extracts the service name (snake_case) from an entity's proto file path. For example, "proto/services/patients/v1/patients.proto" returns "patients".

func ServiceRowFuncName ¶

func ServiceRowFuncName(svcName string) string

ServiceRowFuncName returns the canonical (no-collision) row constructor name for a service, accepting any spelling the codebase uses (proto "AdminServerService", forge.yaml "admin-server", snake "admin_server"). Used for user-facing messages ("add this line:"); when a cross-role package collision renames the FieldName (rare), the emitted constructor carries the collision-aware name instead and the registration parser's normalized matching still resolves it.

func ServingWorkload ¶ added in v0.1.45

func ServingWorkload(declared map[string]DeclaredWorkload, projectName string, c config.ComponentConfig) (string, bool)

ServingWorkload names the declared workload whose process ALREADY runs component c, when that workload is not c's own declaration. Two cases, and both are facts forge can read rather than guess:

• A workload that lists c in `serves`. A subcommand that mounts several components (control-plane's `admin-api` mounts six admin services) is ONE workload; `serves` is how it says which components it runs. forge cannot see that from Go — the mount set lives in the project's own code — so the declaration states it.
• A workload running the project binary's `server` command, which runs every service, worker and operator in one process (cmd-tree-server's MountAll + AllWorkers + AllOperators). A secondary binary is its own program and is never served by it.

Such a component needs no workload of its own: declaring one would deploy it a second time, as its own Deployment, beside the process that already serves it.

func ShouldInstrumentComponent ¶ added in v0.1.45

func ShouldInstrumentComponent(dir, ctorType, ifaceName string) bool

ShouldInstrumentComponent reports whether the component package at dir gets the generated observability decorator (and, at the composition site, the wrapped `pkg.New<Concrete>WithForgeMiddleware(pkg.New(...))` emission). It is THE single instrument decision — the compose assembler and the generate walk both route through it so they can never disagree.

ctorType is DetectConstructorType(dir); ifaceName is the component's Service-contract interface name (serviceIfaceOrDefault). A package is instrumented when ALL hold:

1. the constructor RETURNS the Service interface (ctorType == ifaceName). Handler-shaped packages return a concrete *Service and are never wrapped — otelconnect owns the RPC edge, and wrapping *Service would change the Components field type.
2. it has NOT opted out via a package-level `// forge:no-observe` (HasPackageNoObserveDirective) — the opt-out wins over every opt-in.
3. it has opted IN — either the Phase-2 `// forge:constructor` marker (HasConstructorMarker) OR, for backward compatibility, the legacy owned observe_chain.go seam (DetectObserveChainSeam). Scaffolds stamp the marker AND the seam, so new packages are born instrumented; the seam keeps pre-marker projects working unchanged.

func StripKCLProse ¶ added in v0.1.45

func StripKCLProse(src string) string

StripKCLProse removes """docstrings""" and # comments from KCL source, so a scan for real declarations is not fooled by prose that illustrates them.

func SyncLegacyRootGen ¶ added in v0.1.45

func SyncLegacyRootGen(projectDir, modulePath, bin string, cs *checksums.FileChecksums) error

SyncLegacyRootGen keeps a pre-retirement command tree compiling, and reclaims root_gen.go once the tree no longer needs it.

Both directions run on every generate, so the file tracks the project's real state: a legacy project keeps a correct root_gen.go (including the migration source flipping to the embedded set when it writes its first .sql), and a project whose root.go has moved to the new shape loses the file on the next run rather than carrying a stale copy that redeclares ServiceName.

func ToCamelCaseFromPascalExport ¶

func ToCamelCaseFromPascalExport(s string) string

ToCamelCaseFromPascalExport is the exported wrapper around the package-internal helper. Callers outside this package (the frontend hooks barrel generator deriving a namespace alias from a service name) use it so the camelCase rules stay in lockstep across packages.

func UnfilledDepsFor ¶ added in v0.1.45

func UnfilledDepsFor(handlerDir string) []string

UnfilledDepsFor describes each required Deps field of the handler in handlerDir that the test harness cannot construct, as "Deps.SQL (*sql.DB)". The scaffolded handler tests read it: a service with any such field gets tests that pass WithPlaceholderDeps(), so the file forge writes passes as written.

func UnmanagedMarkerNearMiss ¶ added in v0.1.45

func UnmanagedMarkerNearMiss(comment string) string

UnmanagedMarkerNearMiss returns the first `forge:*` token in a service's comment that is a misspelling of ProtoMarkerUnmanaged (`forge:unmanged`, `forge:un-managed`), or "" when there is none.

The proto-markers lint reports an unknown marker as a warning, because one is usually prose. On a service this one is not: a misspelled forge:unmanaged leaves the service managed, and the next generate scaffolds a stub for every one of its rpcs — the exact outcome the marker was written to prevent. So the descriptor path refuses a near miss outright. Known markers and tokens nowhere near this one stay prose.

func UnmappedFieldsError ¶ added in v0.1.45

func UnmappedFieldsError(fields []UnmappedField) error

UnmappedFieldsError renders a set of unmappable pairings as the error `forge generate` fails with. nil for an empty set. Every pair is listed rather than just the first, so one run tells the author about every dead field instead of one per regenerate.

func UnsatisfiableColumnsError ¶ added in v0.1.45

func UnsatisfiableColumnsError(cols []UnsatisfiableColumn) error

UnsatisfiableColumnsError renders a set of UnsatisfiableColumn findings as the error `forge generate` fails with. nil for an empty set. Every column is listed rather than just the first, so one run names every broken column instead of one per regenerate.

func UnversionableEntitiesError ¶ added in v0.1.45

func UnversionableEntitiesError(entities []UnversionableEntity) error

UnversionableEntitiesError renders findings as the error `forge generate` fails with. nil for an empty set.

This fails the build rather than warning, for the same reason UnsatisfiableColumnsError does: the generated code would compile and pass a smoke test, and only wedge on the SECOND update of a row — long after anyone would connect it to the migration that added the marker.

func UnwiredStubMarkerComment ¶ added in v0.1.45

func UnwiredStubMarkerComment(servicePkg, method string) string

UnwiredStubMarkerComment returns the whole marker doc-comment line for one handler method — `// forge:gen unwired-stub symbol=<pkg>.<Method>`. It goes LAST in the method's doc comment: revive's `exported` rule requires the FIRST line to start with the method name, so the marker cannot lead.

func ValidateBinaryConfigBindings ¶ added in v0.1.45

func ValidateBinaryConfigBindings(messages []ConfigMessage, binaries []string) error

ValidateBinaryConfigBindings refuses every (forge.v1.binary_config) binding that cannot mean what it says:

• binary names no cmd/<name> directory. binaries is the set ProjectBinaries returned; nil skips this check (see ProjectBinaries).
• command is set without a binary, or an element is not ONE command name (empty, contains whitespace, or is a flag).
• two messages bind the same (binary, command). A process has ONE config at each level — one Load<Msg>, one KCL schema its env is projected from — so a second message for it has no defined meaning, and the projection silently used whichever came first.
• a binary's root config and one of its command configs declare the same env var or flag. The process running that command loads both, so it would read one value from two declarations that can drift, and its env projection would carry the key twice.
• a binary's root config and one of its command configs declare a top-level field of the same name. The process reads both from ONE config file, flat across the two (forge/pkg/config's file layer), so the file could not say which of them a key sets.

It reports EVERY offender rather than the first, for the reason ValidateFrontendConfigs does: a renamed binary takes several messages with it, and fixing them one generate-run at a time is miserable.

func ValidateConfigEnvAliases ¶ added in v0.1.45

func ValidateConfigEnvAliases(messages []ConfigMessage) error

ValidateConfigEnvAliases refuses every env_var_aliases entry that cannot mean what it says:

• its name is empty or not an env var name;
• the field has no env_var — an alias is a fallback FOR env_var;
• it repeats the field's own env_var, or another alias of the field;
• it names a variable another field of the same process reads, as an env_var or an alias. A process is a binary's root config, a command config together with its binary's root config (the process loads both), or the project-global config (every unbound root message);
• the field belongs to a frontend config, whose values come from the rendered config document, never from an environment.

Two fields sharing an env_var with no alias involved is not this check's business: ValidateBinaryConfigBindings already refuses the root/command case, and the rest predates aliases.

func ValidateConfigOptionality ¶ added in v0.1.45

func ValidateConfigOptionality(messages []ConfigMessage) error

ValidateConfigOptionality refuses a field annotated `required: true` AND `optional: true`.

The two are direct contradictions — one says startup fails without a value, the other says absence is fine — and forge refuses rather than picking a winner. Either precedence would be a silent behaviour that an author has to learn from source: resolving toward `required` makes `optional` decorative on the field that most needs it to work, and resolving toward `optional` silently disables a check someone asked for. A proto author who writes both has not decided yet, and the fix is one line either way.

It reports EVERY offender rather than the first, for the reason ValidateFrontendConfigs does: these arrive in batches when a config block is split or copied, and fixing them one generate-run at a time is miserable.

func ValidateFieldOptions ¶ added in v0.1.45

func ValidateFieldOptions(optsText string) string

ValidateFieldOptions returns an inline-options block carrying ONLY the `(buf.validate.field)` options found in optsText (a field's raw `[...]` block, brackets optional), spelled as the author wrote them and collapsed to one line:

[(buf.validate.field).string.min_len = 1, (buf.validate.field).string.max_len = 120]

It returns "" when the text declares no protovalidate rule. Non-validate options in the same block (`deprecated = true`, a custom extension) are dropped — the caller is copying VALIDATION onto another message, not the field's whole option set.

Verbatim, rather than re-rendering FieldConstraints: FieldConstraints is deliberately the lossy SQL/zod-projectable SUBSET, but the wire's target IS proto, so nothing needs to be dropped. Copying the text carries the rules forge does not project either — CEL, uuid/hostname/ip and the other string formats, in/not_in, const, repeated/map/duration rules — so a rule declared once is enforced on the wire wherever the field travels.

Only FIELD options are carried. Message-level rules (`option (buf.validate.message).cel`) are the one shape that can name sibling fields, and are never lifted onto a request that carries a different field set.

func ValidateFrontendConfigs ¶ added in v0.1.45

func ValidateFrontendConfigs(messages []ConfigMessage) error

ValidateFrontendConfigs refuses a `sensitive` field that reaches a frontend config.

This is the highest-value rule in the frontend config system, and it is an ERROR rather than a warning on purpose. Everything a browser reads is public: a frontend's config is delivered to the client, so a secret in it is a published secret the moment the artifact ships. A warning would be read after the fact — and a leaked credential cannot be un-leaked, so the only useful moment to refuse is before the value is ever written into a bundle, a config.js, or a rendered KCL plan.

It reports EVERY offender rather than the first, because a config split gone wrong tends to produce several at once and fixing them one generate-run at a time is miserable.

The message is a runbook: it names the field, where it was declared (following composition into shared blocks, which is where this mistake actually happens — a BaseConfig holding both an issuer and a client secret, composed onto a frontend), and what to do about it.

func WebhookNamesForService ¶

func WebhookNamesForService(handlerDir string) []string

WebhookNamesForService discovers a service's webhooks from the REAL source — the webhook_<name>.go handler files under its directory — rather than a declared config list. `forge scaffold webhook` scaffolds webhook_<name>.go (+ _test.go); the file IS the declaration, so nothing needs to cache the name in forge.yaml or a components manifest. This mirrors how forge discovers services themselves.

handlerDir is the service's on-disk directory (e.g. internal/handlers/foo, resolved via ResolveServiceComponent). Returns the webhook names sorted for stable codegen. Best-effort: a missing directory yields nil.

Three exclusions, and two are load-bearing. forge's OWN output for this discovery is webhook_routes_gen.go, which sits in the same directory and matches the same webhook_*.go prefix. Without the *_gen.go exclusion the second `forge generate` discovers a phantom webhook named "routes_gen" and emits a route for s.handleWebhookRoutesGen, which nothing declares:

internal/handlers/widget/webhook_routes_gen.go:17:67:
    s.handleWebhookRoutesGen undefined

webhook_store.go is excluded for the same reason on a longer timescale: the dedupe store now lives in forge/pkg/middleware and is no longer scaffolded, but projects generated before that still carry the file on disk, and it would otherwise be read as a webhook named "store".

func WorkloadDeclared ¶ added in v0.1.45

func WorkloadDeclared(content, name string) bool

WorkloadDeclared reports whether workloads.k content declares a workload by that name, ignoring prose that merely mentions it.

Exported for callers that need to ask what a project DECLARES rather than what it has on disk in some other format.

func WorkloadKindFor ¶ added in v0.1.45

func WorkloadKindFor(componentKind string) string

WorkloadKindFor maps a scaffolded component kind onto the KCL workload kind that deploys it.

The two axes are NOT the same, which is the whole reason this function exists rather than a cast:

• config.ComponentKindServer names a Connect-RPC surface — a code fact. It deploys as a `service` (Deployment + Service).

• config.ComponentKindBinary names a second cmd/<name>/main.go — a build fact. It deploys as a `tool`: forge builds it into the image, but nothing schedules it. It is run on demand (`kubectl exec`, a CI step), which is exactly what the old `binary` deploy kind meant in practice — its manifests were an unscheduled Deployment nobody addressed.

• config.ComponentKindCron is a worker whose process runs an IN-PROCESS scheduler (worker-cron: robfig/cron, Start blocks until shutdown). It deploys as a long-running `worker`. A Kubernetes CronJob would start that process on the schedule and wait for an exit that never comes.

An unrecognized kind falls back to `service`: a plain Deployment+Service is the least surprising thing to render for something forge has no name for.

func WorkloadName ¶ added in v0.1.46

func WorkloadName(component string) string

WorkloadName is the `name` a component's workload declares in deploy/kcl/workloads.k: the component name as a DNS-1123 label, which fw.Workload requires because it becomes every object's name. A component is named like a Go package (`engine_shadow`, `admin_server`); its workload is `engine-shadow`, declared under the KCL identifier `engine_shadow`.

KCLIdentifier(WorkloadName(c)) == KCLIdentifier(c) for every component name, so code that matches a declared workload to a component compares the two through KCLIdentifier (SameWorkload) and never depends on the spelling.

func WorkloadStanza ¶ added in v0.1.45

func WorkloadStanza(modulePath, projectName string, c config.ComponentConfig) string

WorkloadStanza renders ONE workload as the typed KCL literal that belongs in deploy/kcl/workloads.k. It is the single formatter behind both the initial scaffold and `forge scaffold <kind>`'s append, so a workload added later is indistinguishable from one the project was born with.

The emitted declaration is COMPLETE and RUNTIME-INDEPENDENT (ADR 0002): the build, the subcommand in `args`, the ports, the credentials it reads. It says nothing about WHERE it runs — each env binds it to a runtime (`forge.OnHost`, `OnCluster`, `OnHosted`, ...) and the same `args` select the subcommand on every one: `go run ./cmd/<p> <args>` on the host, the image's ENTRYPOINT `/app/<p>` plus `<args>` in a pod. Per-env facts (replicas, resources, env values) are refined in deploy/kcl/<env>/main.k.

No probes: the lowering writes `/readyz` + `/healthz` on the `http` port into the spec of every service forge builds, on every runtime, which is exactly what serverkit serves.

func WorkloadStanzaHint ¶ added in v0.1.45

func WorkloadStanzaHint(modulePath, projectName string, c config.ComponentConfig) string

WorkloadStanzaHint is the message shown when the stanza could not be appended automatically: the exact text to paste, and where.

func WorkloadsKCLExists ¶ added in v0.1.45

func WorkloadsKCLExists(projectDir string) bool

WorkloadsKCLExists reports whether the project already declares its workloads. Callers use it to decide between scaffolding the file and appending to it; neither path ever overwrites existing content.

func WriteTierKCL ¶ added in v0.1.45

func WriteTierKCL(forgeRoot, pkgPath string) (string, error)

WriteTierKCL regenerates kcl/tiers/tiers_gen.k in forgeRoot.