generator

func AdvisoryPaths ¶ added in v0.1.45

func AdvisoryPaths(files []AdvisoryFile) []string

AdvisoryPaths returns the project-relative paths of a row set, in order. `forge project upgrade --force <path>` validates its arguments against this plus the Tier-2 managed set.

func CIWorkflowAbsenceReason ¶ added in v0.1.45

func CIWorkflowAbsenceReason(relPath string) string

CIWorkflowAbsenceReason explains why a project has no file at a CI-mapper path, in the terms of the switch that would give it one.

func CIWorkflowDataFor ¶ added in v0.1.45

func CIWorkflowDataFor(root string, cfg *config.ProjectConfig, in CIInputs) templates.CIWorkflowData

CIWorkflowDataFor returns what the scaffolded ci.yml renders with: which lints, scanners and jobs this project has. `forge ci gate` plans its checks from the same struct, so a forge.yaml toggle means the same thing to the workflow and to the local gate.

func CIWorkflowFileFor ¶ added in v0.1.45

func CIWorkflowFileFor(projectDir string, cfg *config.ProjectConfig, in CIInputs, relPath string) (content []byte, ok bool, err error)

CIWorkflowFileFor renders one of the project's CI files through the single CI mapper, reporting ok=false when this project has no such file.

This is the authority rescaffold consults for .github/workflows/* and .github/dependabot.yml: CIWorkflows decides which workflows a project HAS (e2e.yml only with an e2e suite feature), and a staging render of `forge project new` must never smuggle in one it would not emit.

func CaseCollision ¶ added in v1.0.0

func CaseCollision(dir, fileName string) string

CaseCollision reports a file already in dir whose name equals fileName case-insensitively but not exactly — `Button.tsx` when forge is about to write `button.tsx`.

Such a pair is not two files on the filesystems that matter. macOS (APFS, HFS+) and Windows fold case, so the second write replaces the first, and the desktop app built on a Mac ships whichever landed last. On Linux the pair does coexist, and TypeScript refuses it instead: TS1261 "Already included file name differs from file name only in casing". reliant's web app has Button/Modal/Input/Card/Badge.tsx; forge's starter set installed button/modal/input/card/badge.tsx beside them, five TS1261s on the first generate. Every forge write of a component goes through this check.

Returns the colliding name, or "" when there is none (an unreadable dir has no entries to collide with).

func CaseCollisionError ¶ added in v1.0.0

func CaseCollisionError(dir, fileName, existing string) error

CaseCollisionError is the refusal for one colliding component write.

func EmitFixtureFreshnessSurface ¶ added in v0.1.45

func EmitFixtureFreshnessSurface(root, feRel string, fixtures int, files, cfg seedplan.Fingerprint, cs *FileChecksums) error

EmitFixtureFreshnessSurface writes the two files that make a stale fixture a LOUD failure instead of a silent one, into <feRel>/src/mocks/:

• fixture-manifest_gen.ts — the provenance record: which schema the fixtures beside it were generated from.
• fixture-freshness_gen.test.ts — a vitest that re-derives that fingerprint from db/migrations on disk and fails when the two disagree.

Why a fingerprint rather than fixtures computed at runtime ¶

Computing the fixtures where they are USED would be strictly better, and it is not possible. Their values come from seedplan.Plan, which is built from []schemadef.Table, which exists only by applying db/migrations to a real postgres and introspecting it. The two consumers — a browser in mock mode and vitest under `npm test` — have no database and, in the browser's case, cannot have one. Emitting the fixtures as literals is therefore forced.

What is NOT forced is emitting them with no way to tell when they went out of date. The values need a database; the QUESTION they answer is a hash of two files, and anything that can read the project directory can recompute that. So the fixtures stay a cache, and this is the cache's validity tag: a schema edit without a regenerate now fails `npm test` (and `task test` in CI) with the fix command, instead of silently serving rows for a schema the project no longer has.

Why it is emitted only beside fixtures ¶

fixtures is how many per-entity fixture modules EmitFrontendMockSurface just wrote for this frontend. With none, the pair is not emitted, and a copy left by an earlier run is retired through the ownership test (codegen. RetireGenerated): a certified copy goes, a disowned or hand-edited one stays.

The guard is a cache's validity tag, and a frontend with no fixtures has no cache. That is the common shape of an ADOPTED frontend: its services are custom rpcs with no CRUD entity, so its mock transport dispatches nothing from src/mocks/<entity>_gen.ts. Emitting the pair anyway did not check anything; it made every migration a change to a generated frontend file, and a branch that merged main's migrations without a regenerate turned the frontend's `npm test` red over a fingerprint that described nothing. With parallel lanes landing migrations, that was every few merges.

The file set therefore changes shape when the first entity fixture lands — the same generate that writes the fixtures writes their tag.

files is the digest of the seed INPUT FILES alone, and cfg the same digest with the seed config folded in (codegen.SeedFingerprints returns the pair). They are separate parameters, and separate constants in the emitted manifest, because only ONE of them is reproducible without a database:

• files is what the TypeScript guard recomputes. It hashes migrations and vocab.yaml, which a vitest process can read.
• cfg additionally covers the salt and row counts out of forge.yaml, which the guard has no way to reach.

Recording cfg where the guard expects files makes the comparison fail on every clean tree. That is not hypothetical: this shipped that way once, and `npm test` on a freshly generated project reported STALE MOCK FIXTURES against fixtures that had just been written.

func EmitFrontendMockSurface ¶ added in v0.1.45

func EmitFrontendMockSurface(root, feRel string, services []codegen.ServiceDef, entities []codegen.EntityDef, seed *codegen.SeedProjection, cs *FileChecksums) (int, error)

EmitFrontendMockSurface writes the mock/scenario surface for ONE browser frontend, rooted at root (the project directory) under the project-relative feRel (e.g. "frontends/dashboard"), and returns the number of per-entity fixture files written.

Every file it emits except the seeded `scenarios/default.ts` is Tier-1 — it carries the "Code generated by forge. DO NOT EDIT." banner and IS rewritten on every `forge generate` — so all of them go through the certification chokepoint (WriteGeneratedFileTier1) that stamps the embedded forge:hash marker. Until they did, the header on every one of them named a command that refused the file:

forge project disown frontends/web/src/mocks/products.ts
Error: 1 path(s) carry no forge certification …
Fix: … scaffold-once files are yours from birth

— an answer that was false about a file forge overwrites on every run, while the drift lint reported "no hand-edits to forge-generated files" for a tree in which every one of these had been hand-edited. A plain os.WriteFile emits the claim without the evidence for it.

The surface is:

• src/lib/mock-transport.ts — the transport carrying scenario dispatch, hybrid passthrough, and the Unimplemented fallback.
• src/mocks/<entity>_gen.ts — per-entity fixtures, carrying the values the project's own seed plan writes into the dev database for those rows. There is deliberately no barrel over them: mock-transport_gen.ts imports each module by name (see retireMocksIndex).
• src/mocks/scenario-types.ts, src/mocks/scenario-rpcs_gen.ts, and src/mocks/scenarios/{default,index}.ts — the scenarios scaffolding. See docs/adr/0002-frontend-scenarios.md.

It has TWO callers, and the split is the point:

• GenerateFrontendFilesWithOptions calls it with no services/entities as part of the scaffold. `connect.ts` references "@/lib/mock-transport" statically (Vite ESM) or via a literal `require()` (Next.js/webpack), so a scaffold that omits the module leaves a tree that does not typecheck (`tsc`: TS2307) and does not build (`next build`: "Module not found"). The scaffold emits what the scaffold imports.
• The `forge generate` frontend-mocks step calls it with the project's parsed services + entities, re-rendering the same files with the real fixture dispatch table.

seed is the project's dev dataset (codegen.BuildSeedProjection), the source every per-entity fixture value is read from so the mocks and the seeded database hold the same rows. The scaffold-time caller has no entities and passes nil.

Scenario support is DECOUPLED from entity-CRUD: the transport's scenario-dispatch pipeline depends only on the scenarios scaffolding (always emitted), not on entity fixtures. The per-entity fixture switch is the ONLY part gated on entities — with none, the template omits that section, leaving a fully scenario-capable transport (never a do-nothing stub that would silently drop the scenario mechanism) that also carries no `@/gen/...` imports, so the scaffold-time render stands alone before the TypeScript stubs exist.

func EmitScenarioScaffolding ¶ added in v0.1.45

func EmitScenarioScaffolding(root, mocksRel string, services []codegen.ServiceDef, cs *FileChecksums) error

EmitScenarioScaffolding writes the scenarios files under the project-relative <mocksRel>/scenarios/ inside root:

• scenario-types.ts (Tier-1 — the contract type)
• scenario-rpcs_gen.ts (Tier-1 — typed per-RPC handler map derived from the proto descriptor; empty-but-valid when the project has no services yet)
• default.ts (scaffold-once; yours from birth, safe to hand-edit)
• index.ts (Tier-1 — regenerated by walking the directory for *.ts)

The tier split is what each file's own header already claims, and the writer is now the thing that makes the claim true: the three Tier-1 files go through WriteGeneratedFileTier1 (stamped, disownable, drift-covered) and default.ts through WriteScaffoldIfMissing (written once, never touched again).

scenario-types.ts and scenario-rpcs_gen.ts are emitted one level up at <mocksRel>/ so user scenarios can `import { defineScenario } from "../scenario-types"`. The regeneration is idempotent: running `forge generate` twice produces the same output.

User-authored scenarios (created with `forge scaffold scenario`) are NEVER touched here — the registry just re-exports them.

func EnsureBrowserTelemetryDependencies ¶ added in v0.1.45

func EnsureBrowserTelemetryDependencies(projectDir, feRelDir, feName string)

EnsureBrowserTelemetryDependencies declares the packages the generated src/lib/otel_gen.ts needs in a web frontend's package.json.

A project scaffolded before web-runtime 0.4.0 has none of them, and `forge generate` rewrites otel_gen.ts (Tier-1) to import the SDK, so without this the first build after upgrading fails to resolve "@hyperdx/browser".

Add-only: a version the project already declares is its own decision, and the peer is exact-pinned, so a different one is reported by npm, not rewritten here. The specifier is the runtime's own (webruntimepeers.PeerSpec).

func EnsureCoreComponents ¶

func EnsureCoreComponents(frontendDir string) error

EnsureCoreComponents installs any missing core components into an existing frontend directory's src/components/ui/. See EnsureCoreComponentsIn.

func EnsureCoreComponentsIn ¶ added in v1.0.0

func EnsureCoreComponentsIn(frontendDir, componentsRel string) error

EnsureCoreComponentsIn installs any missing core components into componentsRel (relative to frontendDir; "" = src/components/ui). Safe to call repeatedly.

Each component is scaffold-once by the birth ledger, not by presence: one the user deleted stays deleted, the way every other "yours" file does. Outside a forge project there is no ledger, and presence decides. A component whose name collides case-insensitively with a file already in the directory is refused (CaseCollision) while the rest still install; the refusals come back together as one error.

func EnsureDevWebRuntimeLink ¶ added in v0.1.45

func EnsureDevWebRuntimeLink(projectDir string)

EnsureDevWebRuntimeLink reconciles the gitignored dev bridge for projectDir.

No-op unless the project's Go build is bridged to a forge checkout and that checkout actually carries web-runtime. Every failure is a warning: a bridge is a convenience for forge maintainers, and no dev-loop nicety justifies failing somebody's generate.

func EnsureScaffoldNPMExemptions ¶ added in v0.1.46

func EnsureScaffoldNPMExemptions(projectDir, frontendType string, now time.Time)

EnsureScaffoldNPMExemptions makes forge.yaml accept the no-fix npm advisories a newly scaffolded frontend of frontendType carries, so the project's vuln-npm gate is green on the day the frontend is born.

It only ever ADDS, and only what is missing: an id the project already lists — accepted, disputed with a different reason, or re-dated — is the project's decision and is left exactly as it is.

forge.yaml is the user's file, so the edit is an append of a whole `ci:` section, made only when the file has no `ci:` section yet; that cannot reorder, reformat or lose anything already there. When a `ci:` section exists, merging into it would mean re-serializing the user's YAML, so forge prints the entry to paste instead and touches nothing. Every failure is a printed warning: no bookkeeping here justifies failing a scaffold.

func EnsureWebRuntimeDependency ¶ added in v0.1.45

func EnsureWebRuntimeDependency(projectDir, feRelDir, feName string) bool

EnsureWebRuntimeDependency reconciles the @reliantlabs/forge-web-runtime entry in frontends/<name>/package.json so that npm — not forge — owns the link under node_modules.

It runs at scaffold time (before the first `npm install`, so the very first install resolves the bridge) and again on every `forge generate`, which is what keeps it honest when a project is moved on disk or picked up by a differently-built forge. The edit is surgical: the entry's VALUE is replaced in place, so a hand-formatted, hand-extended package.json survives untouched, and a run that changes nothing writes nothing.

Every failure is a warning. A frontend whose package.json forge cannot parse is the user's file to fix, and no dependency bookkeeping justifies failing their build.

It reports whether it rewrote the manifest.

func EnsureWorkspaceHooksWebRuntimeDependency ¶ added in v0.1.45

func EnsureWorkspaceHooksWebRuntimeDependency(projectDir string) bool

EnsureWorkspaceHooksWebRuntimeDependency reconciles the same entry in packages/hooks/package.json — the workspace-mode home of the generated hooks. Those hooks type every error as ConnectClientError, imported from the runtime package, and a type-only import still has to RESOLVE: under pnpm's strict node_modules an undeclared package is simply not there. Declaring it is what makes the workspace layout typecheck.

No-op when the manifest does not exist, so a non-workspace project calls it harmlessly.

func FixtureMarkerPath ¶ added in v1.0.11

func FixtureMarkerPath(feRel string) string

FixtureMarkerPath is the project-relative marker of the frontend at feRel.

func FrontendConfigMessageName ¶ added in v0.1.45

func FrontendConfigMessageName(frontend string) string

FrontendConfigMessageName is the proto message declaring a frontend's config. It names the generated KCL schema and the TypeScript type, so it is derived once here rather than spelled independently at each site.

func FrontendConfigProtoRelPath ¶ added in v0.1.45

func FrontendConfigProtoRelPath(layout configproto.Layout, frontend string) string

FrontendConfigProtoRelPath is where a frontend's config message is declared, relative to the project root: <name>_config.proto beside the project's root config.proto, in layout.Dir().

ONE FILE PER CONSUMER, ONE SHARED PACKAGE. The file is per-frontend so that adding a frontend WRITES a new file rather than editing a file that already has content in it — which is what makes `forge scaffold frontend` safe on an existing project without parsing or rewriting anyone's proto.

The DIRECTORY is shared (layout.Dir(), proto/<project>/config/v1/), so every config message stays in the project's one config package and therefore in one generated Go package. That is not tidiness: buf's STANDARD lint enforces PACKAGE_DIRECTORY_MATCH, so a per-consumer directory forces a per-consumer proto package, which forces a per-consumer Go package — and pkg/config/config_gen.go imports exactly one generated config package and names every config message through it. A directory-per-consumer layout does not merely reorganize files; it stops the generated Go config shim from compiling.

Sharing the package also keeps shared DEFINITIONS free: a block declared in config.proto composes onto a message here by bare name, with no cross-package import, so one fact declared once projects into both the backend's config and the browser's.

The base name goes through naming.GoPackage, not naming.ToSnakeCase. ToSnakeCase splits camelCase/PascalCase boundaries but passes a HYPHEN straight through, and `forge scaffold frontend` accepts hyphenated names (ValidateFrontendName rejects only a leading "-"). A frontend named "internal-console" therefore produced "internal-console_config.proto", which buf's STANDARD lint rejects with `Filename ... should be lower_snake_case.proto` — a red `buf lint` in the generated CI workflow on the project's first push, fixable only by renaming the frontend or hand-editing a forge-owned path. GoPackage is the canonical CLI-name → snake_case identifier rule (hyphens fold, repeated separators collapse), already used for the Go package, the KCL binding and the handler dir, so routing through it keeps this filename agreeing with them by construction.

func FrontendDependencyNotices ¶ added in v1.0.0

func FrontendDependencyNotices(projectDir, feRelDir string) []string

FrontendDependencyNotices is the read-only counterpart of EnsureWebRuntimeDependency + EnsureBrowserTelemetryDependencies, for a frontend whose package.json the project DISOWNED (`forge project disown <frontend>/package.json`): it reports what those would change instead of changing it, one line each.

It used to be what every ADOPTED frontend got. That left an adopted app below the runtime floor after each forge bump that raised it — reliant's web app regenerated hooks calling runtime APIs its declared range did not have, and had to bump the range by hand every time. Adopted frontends are reconciled like scaffolded ones now; disowning the manifest is the opt-out. A dev forge build's `file:` bridge is never reported: it is machine-local by definition.

func FrontendTypeHasMockSurface ¶ added in v0.1.45

func FrontendTypeHasMockSurface(feType string) bool

FrontendTypeHasMockSurface is frontendKindHasMockSurface keyed by the forge.yaml `frontends[].type` (nextjs / vite-spa / react-native) rather than by the `--kind` flag the scaffold takes. Used by the `forge generate` frontend-mocks step, which reads the persisted config. An unrecognised type gets nothing — the surface is rendered from templates that only the two browser kinds import.

func GenerateBinaryFiles ¶

func GenerateBinaryFiles(root, modulePath, binaryName string) error

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

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

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

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

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

func GenerateCRDFiles ¶

func GenerateCRDFiles(in CRDGenInput) error

GenerateCRDFiles scaffolds a single CRD into an existing operator:

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

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

func GenerateE2ETests ¶

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

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

func GenerateFrontendFiles ¶

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

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

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

func GenerateFrontendFilesWithOptions ¶

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

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

func GenerateOperatorBinaryOnly ¶

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

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

The generator emits two files:

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

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

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

func GenerateOperatorFiles ¶

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

GenerateOperatorFiles generates all files for a single operator:

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

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

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

func GenerateOperatorFilesWithAPI ¶

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

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

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

func GeneratePlanORM ¶

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

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

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

orm places the projection (database.orm.package, default internal/db): every file lands in that directory and declares its package.

func GeneratePlanProtoFile ¶

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

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

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

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

func GenerateServiceFiles ¶

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

GenerateServiceFiles generates all files for a single Go service:

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

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

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

No handler file is emitted at scaffold time: with zero RPC methods there is nothing for one to contain. Once RPCs are added to the proto file, `forge generate` scaffolds each missing stub into its own user-owned rpc_<name>.go (codegen.GenerateMissingHandlerStubs).

There is no per-service port: every service mounts onto the one Connect mux the binary serves, and the listener reads the AppConfig `port` field (env PORT, default 8080) set per environment in deploy/kcl/<env>/config.k.

func GenerateServiceFilesWithMode ¶

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

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

func GenerateWebhookFiles ¶

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

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

• internal/handlers/<service>/webhook_<name>.go (handler + signature verification + dedup)
• internal/handlers/<service>/webhook_<name>_test.go (tests)

Every symbol a handler needs is either its own (uniquely named per webhook) or comes from forge/pkg/middleware, so each webhook is one self-contained pair of files and adding a second webhook to a service cannot collide with the first.

func GenerateWorkerFiles ¶

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

GenerateWorkerFiles generates all files for a single worker:

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

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

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

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

func HashContent ¶

func HashContent(content []byte) string

HashContent returns the sha256 hex digest of content.

func InstalledDeclarationEntry ¶ added in v0.1.45

func InstalledDeclarationEntry(feDir, pkg string, hoisted bool) string

InstalledDeclarationEntry reads the declaration entry of pkg's TYPES package as installed under feDir's node_modules for the given layout, or "" when no manifest is there to read.

func IsCIMapperPath ¶ added in v0.1.45

func IsCIMapperPath(relPath string) bool

IsCIMapperPath reports whether relPath is a file the CI mapper owns — any GitHub Actions workflow template forge ships, plus dependabot.yml — whether or not THIS project has it.

func IsForgeGenerated ¶ added in v0.1.45

func IsForgeGenerated(content []byte) bool

IsForgeGenerated reports whether content carries forge's generated-file banner — a Tier-1 file `forge generate` re-renders, as opposed to a scaffold the user owns.

func IsForgeManagedGitHook ¶ added in v0.1.45

func IsForgeManagedGitHook(script []byte) bool

IsForgeManagedGitHook reports whether script is a git hook forge wrote (generateGitHooks) rather than one the project owns. It reads only the line after the shebang, where every forge hook carries forgeManagedHookHeader, so a project hook that merely mentions forge is still the project's.

Forge activates .githooks (core.hooksPath) only for its own hooks. An in-place adopted repository keeps the hooks it already had, and pointing git at them is that project's decision, made by its own setup step.

func IsFrontendManagedPath ¶ added in v0.1.45

func IsFrontendManagedPath(rel string) bool

IsFrontendManagedPath reports whether a project-relative path is a per-frontend managed file, by SHAPE rather than by membership.

The stale-artifact sweep needs this. That sweep deletes any file carrying forge's certification marker that the current `forge generate` run did not write: the pristine ones outright, the hand-edited ones under `--force-cleanup`. A Tier-2 managed file is stamped and is written by `forge project upgrade`, not by `forge generate`, so it lands in the sweep's crosshairs exactly as the command-tree files did — the data-loss incident UpgradeManagedPaths documents at length.

UpgradeManagedPaths answers that question from a static union over (kind, binary), computed with no project config. These paths depend on the frontends a project declares, so they cannot appear in that union. A shape test is the honest way to express "frontends/<any>/eslint.config.mjs belongs to the upgrade lane" without a config in hand.

func IsTier2Managed ¶ added in v0.1.45

func IsTier2Managed(relPath string) bool

IsTier2Managed reports whether relPath's canonical template tier is Tier-2 (user-owned after the first write). Hand-edits there are sanctioned and must never be reported as drift.

func ManagedPathsFor ¶ added in v0.1.45

func ManagedPathsFor(cfg *config.ProjectConfig) []string

ManagedPathsFor returns the project-relative paths `forge project upgrade` manages for THIS project, in manifest order.

UpgradeManagedPaths is the union over every (kind, binary) combination — the right question for the stale-artifact sweep, which must not flag a file just because detection guessed a different shape. This is the narrower question a user-facing path argument needs: "is this a file upgrade can write HERE", answered against the project's own kind, binary mode, and binary name.

func ReadProjectConfig ¶

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

ReadProjectConfig reads a forge.yaml from the given path with strict validation: unknown keys, missing required fields, and type mismatches are surfaced together via config.ValidationError rather than failing fast on the first issue. forge.yaml is project-global only: what the project CONTAINS is read from the code that declares it (codegen.DiscoverProjectComponents), and the project kind is derived from the tree beside forge.yaml (see config.LoadProject). See config.LoadStrict for the full validation semantics.

func ReconcileFrontendTsconfigPeers ¶ added in v0.1.45

func ReconcileFrontendTsconfigPeers(projectDir string)

ReconcileFrontendTsconfigPeers retargets every frontend's tsconfig peer pins to the node_modules layout the install forge just ran produced, and aims each at its package's installed declaration entry. It is the SCAFFOLD-time pass (`forge project new --frontend` and `forge scaffold frontend`, right after their npm install) and reads node_modules on purpose — see ObserveInstalledPinLayout. `forge generate` has its own pass that reads declarations only. Best-effort and non-fatal: a missing or unrecognised tsconfig is skipped rather than failed, a project whose layout cannot be identified is left untouched, and a file already correct is left byte-identical so a re-run reports nothing.

func ReconcileTsconfigPins ¶ added in v0.1.45

func ReconcileTsconfigPins(path string, decide PinDecision) bool

ReconcileTsconfigPins rewrites every present, forge-shaped peer pin in path to whatever decide returns for it, leaving every other byte of the file alone. Reports whether the file changed.

A pin forge does not recognise (another prefix, several candidates, a multi-line value) is left exactly as written: it is a shape a human chose.

func RecordFrozenChecksums ¶

func RecordFrozenChecksums(projectDir, binary, kind string) error

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

func RegenerateInfraFiles ¶

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

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

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

func RegenerateInfraFilesTracked ¶

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

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

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

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

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

func RenderAdvisoryFile ¶ added in v0.1.45

func RenderAdvisoryFile(projectDir string, cfg *config.ProjectConfig, relPath string) (content []byte, ok bool, err error)

RenderAdvisoryFile renders a scaffold-once advisory row (a frontend's shared mechanism module, a .github starter) — the bytes `forge project upgrade --force <path>` adopts — reporting ok=false when relPath is not one.

func RenderUpgradeManagedFile ¶ added in v0.1.45

func RenderUpgradeManagedFile(projectDir string, cfg *config.ProjectConfig, relPath string) (content []byte, tier int, ok bool, err error)

RenderUpgradeManagedFile renders relPath the way `forge project upgrade` would write it into this project today, reporting ok=false when relPath is not an upgrade-managed file here. tier is the file's ownership tier: a Tier-1 file is regenerated by `forge generate`, not re-scaffolded.

func SaveChecksums ¶

func SaveChecksums(root string, cs *FileChecksums) error

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

func ScaffoldIdentityKCL ¶ added in v0.1.46

func ScaffoldIdentityKCL(projectDir, projectName string) error

ScaffoldIdentityKCL writes deploy/kcl/identity.k, the one ManagedIdentity declaration every env imports. Write-if-absent: it is the project's from birth, and nothing regenerates it.

func ScaffoldProjectInto ¶ added in v0.1.45

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

ScaffoldProjectInto renders the `forge project new` scaffold of the project described by cfg (rooted at projectDir) into dst, which must be empty.

Nothing under projectDir is written. dst is a staging tree: the caller copies out the paths it wants and discards the rest.

The shape comes from forge.yaml and the tree, never from flags:

• kind, binary mode, harness and features from cfg (the loader has already derived what forge.yaml leaves unset);
• the first frontend from cfg.Frontends;
• the first server component discovered in the tree, which is what the scaffold would have been given as --service. Its e2e harness is what makes e2e.yml part of the project (see CIWorkflows).

Render-time facts that depend on the TREE (the deploy envs the CI mapper reads, the go directive) come from projectDir via the projectDir-aware helpers, so a staged file matches this project rather than a fresh one.

func ScaffoldWorkloadsKCL ¶ added in v0.1.45

func ScaffoldWorkloadsKCL(projectDir, modulePath, projectName string, components codegen.Inventory, migrations bool) error

ScaffoldWorkloadsKCL writes deploy/kcl/workloads.k when the project does not already have one, seeded with the workloads discovered so far.

It is a NO-OP when the file exists. That is the whole contract: the file is user-owned, so the only safe automatic write is the FIRST one. Drift between the tree and this file afterwards is REPORTED by `forge lint` (which prints the exact stanza to paste) rather than silently repaired — forge cannot know whether a component missing from an env is an oversight or a deliberate choice.

Callers that run before the proto descriptor exists should skip an empty inventory rather than write an empty file, or that empty file becomes the one automatic write and the real components never land (see the call in generateKCLDeploy).

func ScaffoldedFrontendConfig ¶ added in v0.1.45

func ScaffoldedFrontendConfig(frontend string, apiPort int) codegen.FrontendConfig

ScaffoldedFrontendConfig is the codegen view of that same declaration: the FrontendConfig `forge generate` would derive from the descriptor once the proto above has been compiled.

It exists because the two are needed at the SAME moment and only one of them used to be produced. `forge scaffold frontend` renders templates that import the typed module (src/lib/auth/session-provider.ts does so unconditionally: `import ... from "@/lib/config_gen"`), and it gates that on ScaffoldedFrontendTypedConfig — but it never wrote the module those imports name, because writing it lived only in the generate pipeline's "frontend typed config" step. The add verb deliberately does NOT run generate (staging a frontend must not trigger project-wide codegen churn), so a freshly added frontend shipped a tree that could not typecheck: `Cannot find module '@/lib/config_gen'`, from the scaffold's own files, before the user had written a line. This is the same bug class as connect.ts referencing a mock-transport only generate emitted.

The field set is derived from frontendConfigEnvVars so it cannot drift from the proto beside it; the values here mirror the template's own declarations. `forge generate` later re-derives this from the compiled descriptor and rewrites the module — the point is only that the tree is coherent before it does.

func SetProjectConfigScalar ¶ added in v0.1.45

func SetProjectConfigScalar(path, key string, value any) error

SetProjectConfigScalar sets a single top-level scalar key in the forge.yaml at path, rewriting ONLY the bytes that hold that value and leaving the rest of the document untouched — comments, key order, blank lines, quoting style and any key the Go struct does not model all survive byte-for-byte.

This is the write path for "change one field on a file the user owns". It exists because forge.yaml is a hand-editable manifest, not a serialization of a Go value. See WriteProjectConfigFile for what the whole-struct alternative destroys.

The key is LOCATED through yaml.Node rather than by pattern-matching text, so a same-named key nested inside another block, or one mentioned in a comment, is not mistaken for the top-level one. Only the located value's own bytes are replaced; a trailing end-of-line comment on that line is preserved with its original spacing.

If the key is absent it is appended to the document. If the value is already correct the file is not written at all.

func SetProjectConfigScalarPath ¶ added in v0.1.45

func SetProjectConfigScalarPath(path string, keys []string, value any) error

SetProjectConfigScalarPath is SetProjectConfigScalar for a nested key: it sets the scalar at keys (e.g. {"ci","provider"}) in the forge.yaml at path, rewriting only that value's own bytes.

Blocks along the path that do not exist are created — appended at the end of their parent, so nothing already in the file is shifted or reindented. A path whose parent exists but is not a mapping is an error rather than a silent overwrite of whatever the user put there.

func SiteStarterKindNames ¶ added in v1.0.0

func SiteStarterKindNames() []string

SiteStarterKindNames lists the kinds SiteStarterFrontend accepts, sorted.

func StagedScaffoldBirthHash ¶ added in v0.1.45

func StagedScaffoldBirthHash(stagingRoot, relPath string) string

StagedScaffoldBirthHash returns the birth hash the staging render recorded for relPath, or "" when it recorded none. A few scaffolds (the frontend nav and dashboard) keep refreshing until the user edits them, and that rests on the ledger knowing the bytes forge wrote; a re-emitted copy must carry the same record or it would read as edited from the moment it lands.

func SyncFrontendLock ¶ added in v1.0.0

func SyncFrontendLock(projectDir, feRelDir string) error

SyncFrontendLock brings the lockfile that governs feRelDir's package.json back in step with the dependency ranges forge manages there (WebRuntimePackage, browserSDKPackage).

The Ensure* functions above rewrite those ranges in package.json and nothing else, so a project with a lockfile is left with one that records the OLD range: `npm ci` then fails ("package.json and package-lock.json are not in sync") until someone runs an install by hand. This runs the package manager's lockfile-only refresh (no node_modules, no lifecycle scripts) when, and only when, the lockfile disagrees about one of those packages. A project with no lockfile has nothing to refresh, and a lockfile that already agrees is never rewritten.

It returns an error when the refresh could not run (no package manager on PATH, registry unreachable), naming the frontend and the exact command, so the inconsistency is never silent. FORGE_SKIP_NPM_INSTALL opts out of running a package manager; the command is printed instead.

func Tier2ManagedPaths ¶

func Tier2ManagedPaths() map[string]bool

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

Two sources:

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

.github/workflows/e2e.yml and .github/dependabot.yml belong to that second group. They were excluded from this set on the grounds that `forge generate`'s CI step re-renders them — which stopped being true when the CI workflows became write-once scaffolds (writeCIScaffold in internal/cli/generate_ci.go): every one of them is now written at most once and is the user's from birth, carrying no marker at all.

The exclusion outliving that change is what produced the worst shape a guard can take. A project scaffolded by an older forge still has the Tier-1 forge:hash marker its e2e.yml was born with; editing that file is now sanctioned, but the drift scan still read it as a hand-edited generated file and aborted `forge generate` WHOLESALE — including runs that touched nothing near CI. And because no emitter rewrites the file, the drift report had no extension point to name and said so ("NO EXTENSION POINT EXISTS"), which is forge telling the user their only remaining options are to discard their fix or disown the file forever. Both were wrong: the edit was legitimate and the tier was not.

func UpgradeManagedPaths ¶

func UpgradeManagedPaths() map[string]bool

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

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

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

Keys are slash-separated, the form of every ownership key the sweep compares them to (checksums.ScanMarkers). destPath is a native path — cmdTreePath joins with filepath — so on Windows the unnormalized set never matched and the sweep flagged these files as stale again. Every key goes through add, so the extra list below cannot skip the normalization: it once did, and on Windows the sweep marked the scaffold-once cmd/cmd/*.go files stale and deleted them.

func WriteFrontendConfigProto ¶ added in v0.1.45

func WriteFrontendConfigProto(root string, layout configproto.Layout, modulePath, frontend string, apiPort int) error

WriteFrontendConfigProto declares the named frontend's public runtime config, with the message-level (forge.v1.frontend_config) annotation that activates the three projections: the typed zod module the bundle imports, the KCL schema per-env values are authored against, and the config.js document the browser reads at boot.

Without this file the config system is complete and unreachable — every generator keys on the annotation, so a project that declares none correctly emits nothing and its frontend keeps reading build-time process.env.NEXT_PUBLIC_*.

APPEND-ONLY BY CONSTRUCTION. Adding a frontend to an existing project writes a NEW file, so no existing config content is read, rewritten or reordered — the failure mode the workloads.k append helper has to guard against does not arise here, because there is nothing to append INTO.

It refuses to overwrite an existing file. A project that already declares this frontend's config has values in it (an issuer, a client id) that a re-scaffold must not silently discard.

func WriteFrontendWorkspaceFiles ¶

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

WriteFrontendWorkspaceFiles emits the workspace-layout scaffolding:

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

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

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

func WriteGeneratedFile ¶

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

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

func WriteGeneratedFileTier1 ¶

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

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

func WriteRescaffoldedFile ¶ added in v0.1.45

func WriteRescaffoldedFile(root, relPath string, content []byte, mode os.FileMode, birthHash string) error

WriteRescaffoldedFile writes a re-emitted scaffold-once file and records its birth, preserving mode (scripts/bootstrap.sh is executable). birthHash is non-empty only for the scaffolds that refresh until touched (see StagedScaffoldBirthHash).

func WriteScaffoldIfMissing ¶

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

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

func WriteScaffoldedFrontendConfigTS ¶ added in v0.1.45

func WriteScaffoldedFrontendConfigTS(root, projectName, frontend, platform string, apiPort int) error

WriteScaffoldedFrontendConfigTS writes src/lib/config_gen.ts for a just-scaffolded frontend, so the templates that import "@/lib/config_gen" resolve in the tree the add verb leaves behind.

platform is the same label the generate pipeline passes (nextjs / vite-spa / react-native): it selects how the module reads its values server-side, so it must match the frontend's kind.

Written through the Tier-1 writer with a nil checksum tracker, exactly as the generate step does — the next `forge generate` re-derives the module from the compiled descriptor and overwrites this one, which is why nothing here needs to be preserved.

func WriteScenariosIndex ¶ added in v0.1.45

func WriteScenariosIndex(root, scenariosRel string, cs *FileChecksums) error

WriteScenariosIndex walks the project-relative <scenariosRel> inside root for *.ts files (excluding index.ts itself) and renders scenarios-index.ts.tmpl with one entry per file. Ordering is alphabetical for deterministic output — re-running `forge generate` on the same set of files produces the same bytes.

The barrel is Tier-1: it carries the generated banner and is rewritten whenever the directory's contents change, so it goes through the certification chokepoint like every other regenerated file.

func WriteSiteScaffold ¶ added in v1.0.0

func WriteSiteScaffold(dir, projectName string, harness Harness, fe SiteFrontend) error

WriteSiteScaffold writes a static site's forge files into dir: forge.yaml, deploy/kcl/kcl.mod and the dev / staging / prod envs, each declaring the root frontend (`path = "."`) and binding it — to its dev server in dev, to hosted static hosting (forge.OnHosted) in staging and prod.

That is the whole project. A site has no Go module, so there is no cmd/, go.mod, proto/, Dockerfile or server to scaffold; every forge command reads the absent go.mod (config.ProjectConfig.HasGoModule) and skips its Go steps. The frontend's own files are never touched: the app was there first and stays exactly as it was.

dir is normally a staging directory the caller merges into the project (the in-place rule that an existing file is kept unless --force).

func WriteSiteStarter ¶ added in v1.0.0

func WriteSiteStarter(dir, projectName string, fe SiteFrontend) error

WriteSiteStarter writes the starter app of a greenfield static site into dir (its root): the template tree internal/templates/frontend/site/<type> plus the files it reuses from the app frontend of that framework. fe is what SiteStarterFrontend returned; WriteSiteScaffold then writes the forge files declaring it.

func WriteUINativePackageFiles ¶

func WriteUINativePackageFiles(projectDir string, layout FrontendWorkspaceLayout) error

WriteUINativePackageFiles emits the packages/ui-native/ scaffold:

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

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

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

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

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

func WriteUIWebPackageFiles ¶

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

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

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

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