@forgrit/codegen-types

Pure TypeScript type declarations for ForGrit's code-generation contracts.

Types only. The 49K-LOC codegen orchestration engine that produces these contracts stays proprietary inside ForGrit's monorepo. This package exists so external tools (CLIs, marketplace plugins, analytics, integration tests) can type-check their interop without depending on the foundry runtime.

Install

pnpm add -D @forgrit/codegen-types
# or
npm install --save-dev @forgrit/codegen-types

Note: -D / --save-dev because this package emits only .d.ts declarations and a tiny .js shim that re-exports enums. There is no runtime behavior to ship in production bundles.

What's in the box (~50 types)

| Sub-module | Key exports | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | code-plan | CodePlanContract, ComponentSpec, APIEndpointSpec, EntitySpec, EntityFieldSpec, StateSpec, Language | | navigation | NavigationContract, RouteSpec, NavItemSpec | | file-manifest | FileManifest, FileBatch, FileSpec, FileOwnership, FileKind | | frozen | FrozenCodePlanDTO (composite of the 3 contracts above + hashes) | | ui-screen | UIScreenContract, ScreenArchetype, LayoutSpec, ComponentInventory, ComponentType, DataRequirements, CrudOperation, FilterSpec, SortSpec, PaginationSpec, InteractionSpec, ActionSpec, ModalSpec, ValidationRule, AccessibilitySpec, DesignTokenUsage | | validation | ContractValidationResult, ContractValidationError, ContractValidationWarning | | integrations | IntegrationCategory + 7 per-category enums + IntegrationSelections + DEFAULT_INTEGRATIONS + IntegrationOptionMeta |

All types are re-exported from the package root for convenience:

import type {
  CodePlanContract,
  FrozenCodePlanDTO,
  UIScreenContract,
  IntegrationSelections,
} from '@forgrit/codegen-types';

Or scope by sub-module if you prefer narrower imports — sub-paths are NOT exposed in package.json#exports (kept to a single root export for stability; sub-paths may be added in 0.2.x if demand emerges).

What's NOT in this package (intentional moat boundary)

These belong to the codegen ENGINE, not the contract surface, and stay apps/api-local:

• Patch family: PatchSet, PatchOperation, PatchPrecondition, PatchApplicationResult — the cross-batch modification engine
• Module ownership graph: ModuleContract, ModuleType, ModuleOwnership, ModuleDependencies, ModuleExports, ModuleImports, TestRequirements, STANDARD_MODULES — the module orchestration model
• INTEGRATION_CATALOG: the 268-line catalog with display labels, npm package lists, and template fragment IDs — the curation IS competitive value
• ContractBundleV1: the legacy bundle format wired to ForGrit's internal storage layer
• Prisma JSON column shapes (JobMetadata, DesignSelectionContractJson, FrozenPromptContractJson, BudgetEstimateSnapshotJson) — ForGrit-internal persistence concerns
• live-demo.types, compliance-types, all stack-adapter types — apps/api-local orchestration concerns

If your use case needs any of the above as a contract, open an issue — the right answer is usually a SEPARATE narrow types package, not bundling them here.

Versioning

Semver from 0.1.0. Type shapes are considered stable for the major version; additive changes (new optional fields, new union variants) ship in minor versions; removals or required-field changes will bump major.

The four source files in apps/api/src/codegen/{codegen,contracts,contract-bundle,integration-options}.types.ts had zero 30-day churn at the time of extraction (2026-05-27), indicating the surface is stable enough for a v0.1 publish.

License

MIT. See LICENSE.

Related ForGrit packages

• @forgrit/blueprint — blueprint extraction + IA planning
• @forgrit/design-engine — design composition runtime
• @forgrit/contracts — shared contract types across all domains
• @forgrit/deploy-vercel — Vercel deployment provider
• @forgrit/deploy-neon — Neon Postgres provisioner

See plan #22 Path D for design rationale + the load-bearing "engine vs intelligence" decision.

Engines

Node ≥ 20. No runtime dependencies.

Issues

https://github.com/forgrit-ai/forgrit/issues