@aws-amplify/cli-internal-gen2-migration-experimental-alpha 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [14.2.5](https://github.com/aws-amplify/amplify-cli/compare/@aws-amplify/cli-internal@14.2.4...@aws-amplify/cli-internal@14.2.5) (2026-01-26)
+
+**Note:** Version bump only for package @aws-amplify/cli-internal
+
+
+
+
+
+## [14.2.4](https://github.com/aws-amplify/amplify-cli/compare/@aws-amplify/cli-internal@14.2.3...@aws-amplify/cli-internal@14.2.4) (2026-01-22)
+
+**Note:** Version bump only for package @aws-amplify/cli-internal
+
+
+
+
+
 ## [14.2.3](https://github.com/aws-amplify/amplify-cli/compare/@aws-amplify/cli-internal@14.2.2...@aws-amplify/cli-internal@14.2.3) (2025-11-20)
 
 **Note:** Version bump only for package @aws-amplify/cli-internal

package/adr/001-refactor-gen2-migration-generate.md

@@ -0,0 +1,413 @@
+# Generate Command — Guideline Violations
+
+This document maps issues in `packages/amplify-cli/src/commands/gen2-migration/generate`
+to the guidelines in `CODING_GUIDELINES.md`.
+
+## Architecture & Structure
+
+### Point 1 — God modules
+
+`command-handlers.ts` (~730 lines) is the primary offender. It handles AWS client instantiation, code generation orchestration, amplify.yml updates, .gitignore updates, custom resource migration, dependency extraction, file copying, and npm install. These are unrelated concerns in a single file.
+
+`createGen2Renderer` in `migration-pipeline.ts` (~250 lines of function body) manually wires every category, builds cross-category data structures (`functionNamesAndCategory`, `functionsWithApiAccess`, `dynamoTriggers`), and populates `BackendRenderParameters` — acting as both orchestrator and implementor.
+
+`BackendSynthesizer` (~750 lines) generates the entire `backend.ts` file including OAuth flows, user pool client overrides, environment variable logic, DynamoDB table mappings, and custom resource registration.
+
+### Point 2 — Unjustified layer boundaries
+
+Data flows through four or five reshaping layers: SDK response → adapter output (e.g., `AuthDefinition`) → `Gen2RenderingOptions` → `BackendRenderParameters` → TypeScript AST. Each boundary manually maps properties with different names. For example, auth data goes from Cognito SDK types → `getAuthDefinition()` → `AuthDefinition` → `Gen2RenderingOptions.auth` → `BackendRenderParameters.auth` (cherry-picked subset). Adding a new auth field requires changes in five places.
+
+The adapter layer (`adapters/`) and the generator layer (`generators/`) could be collapsed — the adapter reshapes SDK data into a definition, then the generator reshapes the definition into AST nodes. Neither layer is expected to change independently.
+
+### Point 3 — File size and focus
+
+`command-handlers.ts`, `migration-pipeline.ts`, and `backend/synthesizer.ts` are all large files mixing multiple concerns. The auth generator (`generators/auth/index.ts`) is also large, handling login options, external providers, OIDC/SAML, user attributes, MFA, and secret generation in a single file.
+
+### Point 4 — Naming
+
+The `codegen-head/` folder name doesn't convey what it contains (definition fetchers, environment resolution, stack parsing, formatting utilities). The `renderers/` folder contains `EnsureDirectory`, `JsonRenderer`, and `TypescriptNodeArrayRenderer` — the first isn't a renderer in any meaningful sense.
+
+### Point 5 — Scattered API calls
+
+AWS SDK clients are instantiated in `prepare()` inside `command-handlers.ts` and passed to individual fetchers. However, each fetcher also independently calls `backendEnvironmentResolver.selectBackendEnvironment()` and `ccbFetcher.getCurrentCloudBackend()`. There's no centralized wrapper for Cognito, S3, Lambda, or CloudFormation calls — each fetcher makes its own SDK calls directly.
+
+## Mutability & State Management
+
+### Point 6 — Mutable state
+
+`BackendRenderParameters` is built incrementally via mutation in `createGen2Renderer` — properties are conditionally assigned across ~200 lines of code. `Gen2RenderingOptions` has many optional mutable fields. Neither interface uses `readonly`.
+
+### Point 7 — `let` over `const`
+
+`createGen2Renderer` uses mutable variables like `functionNames`, `functionNamesAndCategory`, `functionsWithApiAccess`, `functionsWithDataModelAccess` that are populated inside loops and conditionals, then consumed later. The `updateAmplifyYmlFile` function uses `let amplifyYml: any` assigned across three branches.
+
+## Interface Design
+
+### Point 8 — Properties that don't belong
+
+`StorageRenderParameters` contains `functionNamesAndCategories?: Map<string, string>` — function metadata that has nothing to do with storage. It's there because `renderStorage()` needs it for import path generation.
+
+### Point 9 — Excessive optionality
+
+`Gen2RenderingOptions` has 13 optional properties out of 15 total. `AuthDefinition` has 15 optional properties. `BackendRenderParameters` has all optional category blocks. Most of these are optional because not every Gen1 project has every category, but the optionality propagates through the entire pipeline rather than being resolved at the boundary.
+
+### Point 10 — Same information twice
+
+`functionNamesAndCategory` is derived from `functions` in `createGen2Renderer`, then passed separately to `StorageRenderParameters` and `BackendRenderParameters`. The same function-to-category mapping exists in three places. `backendEnvironmentName` is passed as a separate argument alongside objects that already contain it.
+
+### Point 11 — Dead inputs
+
+`command-handlers.ts` imports `UpdateAppCommand`, `AppContextLogger`, `AmplifyError`, `printer`, `format`, and `hasUncommentedDependency` — none of which are used. `getUsageDataMetric` is defined but never called. `Gen1ProjectConfig` in `types.ts` is an empty stub interface with `[key: string]: any`.
+
+### Point 13 — Catch-all types file
+
+`generate/types.ts` contains a single stub interface `Gen1ProjectConfig` with `[key: string]: any` — a dead, untyped placeholder that serves no purpose.
+
+## Error Handling
+
+### Point 16 — Fallbacks for invalid states
+
+Several fetchers in the generate module return `undefined` when categories don't exist — this is valid. However, `extractGen1FunctionDependencies` silently returns `{}` on any error, including permission failures or corrupted JSON.
+
+### Point 17 — `assert()` in production code
+
+`command-handlers.ts` uses `assert` ~15 times for values that should be validated with user-facing errors (e.g., `assert(backendEnvironment)`, `assert(accountId)`, `assert(resourceName)`). `app_auth_definition_fetcher.ts` and `app_functions_definition_fetcher.ts` also use `assert` extensively.
+
+## Control Flow & Logic
+
+### Point 18 — Repeated branching
+
+`createGen2Renderer` branches on category existence (`if (auth)`, `if (storage)`, `if (data)`, `if (functions)`, `if (analytics)`) in a long sequential block. Each block follows the same pattern (create directory, create renderer, populate `backendRenderOptions`) but the logic isn't consolidated.
+
+### Point 19 — Repeated derived values
+
+`amplify-meta.json` is independently read and parsed in `AppAuthDefinitionFetcher`, `AppStorageDefinitionFetcher`, `AppFunctionsDefinitionFetcher`, `AppAnalyticsDefinitionFetcher`, `DataDefinitionFetcher`, `AuthAccessAnalyzer`, and multiple times in `command-handlers.ts`. Each call site also independently resolves the backend environment via `backendEnvironmentResolver.selectBackendEnvironment()`.
+
+The function-to-category mapping is derived three times: once in `AppFunctionsDefinitionFetcher`, once in `createGen2Renderer` for storage, and once in `createGen2Renderer` for auth.
+
+## Function Design
+
+### Point 21 — Positional arguments
+
+`AppAuthDefinitionFetcher` constructor takes 6 positional arguments. `AppFunctionsDefinitionFetcher` takes 6. `getAuthDefinition()` adapter takes a single object (good), but `renderAuthNode()` takes `(auth, functions, functionCategories)` as separate positional arguments.
+
+### Point 22 — High argument count
+
+`prepare()` instantiates 8 AWS clients and passes a `CodegenCommandParameters` object with 14 fields to `generateGen2Code`. `CodegenCommandParameters` mixes infrastructure concerns (clients, environment) with domain concerns (fetchers, app ID).
+
+## Code Hygiene
+
+### Point 24 — Code duplication
+
+`readJsonFile` is independently defined in `app_auth_definition_fetcher.ts`, `data_definition_fetcher.ts`, and `app_storage_definition_fetcher.ts` — identical implementations in three files. Each fetcher independently resolves the backend environment and downloads the current cloud backend with the same boilerplate.
+
+### Point 25 — Duplicate constants
+
+`GEN1_CONFIGURATION_FILES` is exported from `command-handlers.ts` but the same file names appear as string literals elsewhere.
+
+### Point 27 — Dead code
+
+Unused imports: `UpdateAppCommand`, `AppContextLogger`, `AmplifyError`, `printer`, `format`. Unused function: `getUsageDataMetric`, `hasUncommentedDependency`. Dead type: `Gen1ProjectConfig` in `types.ts`. Commented-out import: `SSMClient`.
+
+---
+
+## Refactoring Requirements
+
+### R1. Generators have access to all Gen1 app information
+
+Every generator must have access to all Gen1 app information through a single facade. The facade provides methods for querying any aspect of the Gen1 app (auth config, storage config, functions, metadata, etc.) but fetches data lazily — only when a generator actually requests it. Results are cached so that multiple generators querying the same data get the same cached result without duplicate API calls or file reads. This makes the facade easy to mock in tests: a test for the auth generator only needs to stub the auth-related methods without constructing the entire Gen1 app state.
+
+### R2. Category generators can contribute to backend.ts
+
+Each category generator (auth, storage, data, functions, etc.) must be able to add imports, statements, and overrides to the `backend.ts` file directly. This eliminates the need for a centralized synthesizer that has to know about every category and reshapes data through an intermediate interface. The generator that understands the category's needs is the one that writes the backend.ts contributions for that category.
+
+### R3. Adding a new category doesn't require modifying existing code
+
+A new category generator should be pluggable without touching other category generators. Adding a category requires only creating the new generator and adding one line to `AmplifyMigrationGenerateStep.execute()` to instantiate it.
+
+### R4. Category generators are self-contained
+
+All logic for generating a category's output — both its `resource.ts` file and its `backend.ts` contributions — lives in one module. No category-specific logic is scattered across shared orchestration code or other category generators.
+
+### R5. Generators support dry run
+
+Each generator must be able to report what it will do without doing it. The description and execution logic must be structurally tied together so they can't diverge.
+
+---
+
+## Refactoring Plan
+
+### Target Directory Structure
+
+```
+generate/
+  gen1-app/
+    gen1-app.ts              # Facade — lazy-loading, caching access to all Gen1 app state
+    aws-clients.ts           # Single instantiation point for all AWS SDK clients
+    amplify-meta.ts          # Reads/caches amplify-meta.json with typed accessors
+    backend-environment.ts   # Backend environment resolution and caching
+    cloud-backend.ts         # Downloads/caches current cloud backend
+
+  auth/
+    auth.generator.ts        # Produces auth/resource.ts + backend.ts contributions
+    auth-triggers.ts         # Auth trigger connection parsing
+
+  storage/
+    storage.generator.ts     # Produces storage/resource.ts + backend.ts contributions
+    storage-access.ts        # S3/DynamoDB access pattern parsing
+
+  data/
+    data.generator.ts        # Produces data/resource.ts + backend.ts contributions
+    schema-reader.ts         # GraphQL schema reading
+
+  functions/
+    functions.generator.ts   # Produces resource.ts per function + backend.ts contributions
+    schedule-parser.ts       # CloudWatch schedule expression conversion
+    trigger-detector.ts      # DynamoDB/API trigger detection
+
+  analytics/
+    analytics.generator.ts   # Produces analytics/resource.ts + backend.ts contributions
+    kinesis-cfn-converter.ts # Kinesis CFN-to-CDK conversion
+
+  custom-resources/
+    custom.generator.ts      # Copies/transforms custom CDK stacks
+    amplify-helper-transformer.ts
+    dependency-merger.ts
+    file-converter.ts
+
+  backend.generator.ts              # Generator that runs last — accumulates contributions, writes backend.ts
+  root-package-json.generator.ts    # Writes root package.json, accumulates dependencies from category generators
+  backend-package-json.generator.ts # Writes amplify/package.json (static { type: 'module' })
+  tsconfig.generator.ts             # Writes amplify/tsconfig.json
+  amplify-yml.generator.ts   # Writes/updates amplify.yml buildspec
+  gitignore.generator.ts     # Writes/updates .gitignore
+  generator.ts               # Generator interface
+  ts-writer.ts               # TypeScript AST printing utility
+```
+
+### Key Abstractions
+
+**Generator interface** — Every generator implements this. Returns `AmplifyMigrationOperation[]` from `plan()`, reusing the existing operation interface that co-locates `describe()` and `execute()`. `AmplifyMigrationGenerateStep.execute()` collects all operations and returns them to the gen2-migration dispatcher, which already handles the describe-then-execute flow.
+
+```typescript
+interface Generator {
+  plan(): Promise<AmplifyMigrationOperation[]>;
+}
+```
+
+**Gen1App** — Lazy-loading facade passed to every generator. Each `fetch*` method calls AWS on first invocation and caches the result. Properties are initialized synchronously from local files in the constructor. Returns raw SDK types or parsed file contents directly — no custom intermediate interfaces. Easy to mock: stub only the methods your test needs.
+
+```typescript
+class Gen1App {
+  public readonly accountId: string;
+  public readonly region: string;
+  public readonly meta: Record<string, unknown>; // parsed amplify-meta.json
+  public readonly graphQLSchema: string | undefined; // raw file content
+
+  public fetchUserPool(): Promise<UserPoolType | undefined>; // raw SDK type
+  public fetchIdentityPool(): Promise<IdentityPoolType | undefined>; // raw SDK type
+  public fetchFunctionConfig(resourceName: string): Promise<FunctionConfiguration | undefined>; // raw SDK type
+  // ... other raw Gen1 state as needed
+}
+```
+
+**BackendGenerator** — Implements `Generator`. Other generators call `addImport()`, `addStatement()`, etc. during their execution. When run last, it writes `backend.ts` from the accumulated content.
+
+```typescript
+class BackendGenerator implements Generator {
+  public addImport(source: string, identifiers: string[]): void;
+  public addStatement(node: ts.Statement): void;
+  public plan(): Promise<AmplifyMigrationOperation[]>;
+}
+```
+
+**Category generators** — Each category has a generator that reads its entries from `Gen1App.meta`, and for each resource name dispatches to a resource-specific generator based on the `service` key. The category generators are:
+
+- `AuthGenerator` → dispatches to resource generators by service (Cognito, Cognito-UserPool-Groups)
+- `DataGenerator` → dispatches to resource generators by service (AppSync, API Gateway)
+- `StorageGenerator` → dispatches by service (S3, DynamoDB)
+- `FunctionsGenerator` → dispatches to `FunctionGenerator` per resource
+- `AnalyticsGenerator` → dispatches to resource generators by service (e.g., Kinesis, Pinpoint)
+- `CustomResourcesGenerator` → dispatches to `CustomResourceGenerator` per resource
+
+Each resource generator receives `Gen1App`, `BackendGenerator`, `RootPackageJsonGenerator`, the output directory, and the resource name. It writes its `resource.ts` and contributes to `BackendGenerator` and `RootPackageJsonGenerator`.
+
+**AmplifyMigrationGenerateStep.execute()** — The orchestration lives directly in the existing step class. Reads `Gen1App.meta` top-level keys to determine which categories exist. Creates one category generator per key. Collects all `AmplifyMigrationOperation[]` from generators and returns them to the parent dispatcher, which handles describe-then-execute.
+
+```typescript
+// Inside AmplifyMigrationGenerateStep
+public async execute(): Promise<AmplifyMigrationOperation[]> {
+  const gen1App = new Gen1App(/* aws clients, region, appId, etc. */);
+  const backendGenerator = new BackendGenerator(this.outputDir);
+  const rootPackageJsonGenerator = new RootPackageJsonGenerator(this.outputDir);
+  const generators: Generator[] = [];
+
+  if (gen1App.meta.auth) {
+    generators.push(new AuthGenerator(gen1App, backendGenerator, packageJsonGenerator, this.outputDir));
+  }
+  // ... other categories follow the same pattern
+
+  generators.push(backendGenerator);
+  generators.push(rootPackageJsonGenerator);
+  generators.push(new BackendPackageJsonGenerator(this.outputDir));
+  generators.push(new TsConfigGenerator(this.outputDir));
+  generators.push(new AmplifyYmlGenerator(this.outputDir));
+  generators.push(new GitIgnoreGenerator(this.outputDir));
+
+  const operations: AmplifyMigrationOperation[] = [];
+  for (const generator of generators) {
+    operations.push(...(await generator.plan()));
+  }
+  return operations;
+}
+```
+
+### Execution Flow
+
+```mermaid
+flowchart TD
+    STEP["AmplifyMigrationGenerateStep.execute()"] -->|Create| G1[Gen1App]
+    STEP -->|Create| BG[BackendGenerator]
+
+    G1 --> GEN[Create one CategoryGenerator per<br/>category present in Gen1App.meta]
+    BG --> GEN
+
+    GEN --> CAT["CategoryGenerator<br/>(Auth, Data, Storage, Functions,<br/>Analytics, CustomResources)"]
+
+    CAT -->|per resource name,<br/>dispatched by service key| RES[ResourceGenerator]
+    RES -->|writes| RES_F[amplify/category/resourceName/resource.ts]
+    RES -->|contributes| BG2[BackendGenerator]
+    RES -->|contributes deps| PKG[RootPackageJsonGenerator]
+
+    BG2 -->|writes last| BACK_F[amplify/backend.ts]
+
+    STEP -->|Create| PKG
+    PKG -->|writes| PKG_F[package.json]
+
+    STEP -->|Create| BPKG[BackendPackageJsonGenerator]
+    BPKG -->|writes| BPKG_F[amplify/package.json]
+
+    STEP -->|Create| TSC[TsConfigGenerator]
+    TSC -->|writes| TSC_F[amplify/tsconfig.json]
+
+    STEP -->|Create| YML[AmplifyYmlGenerator]
+    YML -->|writes| YML_F[amplify.yml]
+
+    STEP -->|Create| GIT[GitIgnoreGenerator]
+    GIT -->|writes| GIT_F[.gitignore]
+```
+
+### Phased Execution
+
+**Execution notes:** Each phase should be delegated to a `general-task-execution` sub-agent with a prompt that references this document (`REFACTORING_GENERATE.md`) and the specific phase. The sub-agent has access to all tools and can read this document for full context. Wait for each phase to complete and review its output before starting the next. Use `context-gatherer` at the start of each phase to re-orient on the current state of the codebase.
+
+**Work style:** Prefer large, cohesive refactoring changes over small incremental ones — don't waste time validating intermediate states you may end up discarding. Do not run `yarn test`, `jest`, or any test command for incremental validation during a phase. Commit freely as you work — no need to check in with the user before committing. Use your judgment on commit granularity.
+
+**No imports from old code:** Code in `generate-new/` must NOT import from the old `generate/` directory. If you need a utility or class that exists in the old code, duplicate it into `generate-new/`. This ensures `generate-new/` is fully self-contained and the old `generate/` directory can be cleanly deleted in Phase 5 without breaking anything.
+
+**Exit criteria (all phases):** `yarn build && yarn test` in the `amplify-cli` package must pass before moving on to the next phase.
+
+**Phase 1 — Foundation**
+Create a new `generate-new/` directory alongside the existing `generate/` directory. Build the foundation: `Gen1App` facade, `BackendGenerator`, `RootPackageJsonGenerator`, and `Generator` interface. The old `generate/` directory remains intact as reference throughout. Stop for review.
+
+The old code and its unit tests remain intact and must continue to pass. No new tests are needed for this phase since the new code has no entry point yet.
+
+**Phase 2 — Migrate categories**
+One category at a time, create the new generator in `generate-new/` (e.g., `auth/auth.generator.ts`). Copy over and restructure the relevant logic from the old code. Each generator reads from `Gen1App`, writes its `resource.ts`, and contributes to `BackendGenerator` and `RootPackageJsonGenerator`. The old code stays untouched as reference. Stop for review after each generator. Code does not need to compile at this stage.
+
+Same as Phase 1 — the old tests must still pass. No new tests yet since the new code is not wired in.
+
+**Phase 3 — Switch over**
+Once all generators are complete in `generate-new/`, update `generate.ts` (the `AmplifyMigrationGenerateStep` entry point) to use the new generator infrastructure instead of the old `prepare()` function. Use `generate.test.ts` (the snapshot tests) as the sole validation mechanism — these tests exercise the full generate pipeline end-to-end and compare output against known-good snapshots. Don't run or worry about the other unit tests in this phase; they test the old code's internal classes which are being replaced. Iterate until the snapshot tests are green.
+
+The snapshot test framework (MigrationApp, mocks, test harness) must not be modified. Only the import path for `prepare` should change to point at the new implementation. Minor test file changes are allowed only with clear justification.
+
+**Phase 4 — Review & simplify**
+All snapshot tests pass. Phase 3 was implementation-driven — decisions were made to match expected output, and code was added under time pressure. This phase steps back and reviews the result against the coding guidelines, the design in this document, and the refactoring requirements (R1–R5).
+
+Specifically:
+
+1. **Coding guidelines audit.** Read every file in `generate-new/` against `CODING_GUIDELINES.md`. Look for violations introduced during Phase 3: missing visibility modifiers, unnecessary optionality, dead imports, missing `readonly`, single-line JSDoc on public members, `assert()` usage, mutable state that should be `const`, repeated derived values, catch-all error handling, etc.
+
+2. **Design alignment.** Compare the actual code against the target directory structure and key abstractions described above. Flag any deviations — files that don't belong, abstractions that leaked, responsibilities that ended up in the wrong place. For example: does `prepare.ts` contain logic that should live in a generator? Does `BackendGenerator.earlyStatements` violate the design's intent? Are there cross-category dependencies that shouldn't exist?
+
+3. **Requirement check.** Verify each requirement (R1–R5) is met:
+
+   - R1: Do all generators access Gen1 app info through `Gen1App`? Or did Phase 3 introduce direct file reads or SDK calls outside the facade?
+   - R2: Do category generators contribute to `backend.ts` through `BackendGenerator`? Or did workarounds bypass it?
+   - R3: Can a new category be added without modifying existing generators? Or did Phase 3 introduce coupling?
+   - R4: Is each category generator self-contained? Or did cross-category logic creep in (e.g., functions generator knowing about auth, storage generator reading function templates)?
+   - R5: Do generators support dry run via `plan()` returning describable operations?
+
+4. **Simplification pass.** Remove anything that was added as a workaround but can now be done more cleanly. Collapse unnecessary indirection. Inline trivial helpers. Merge files that are too small to justify their existence. Reduce the surface area.
+
+5. **No imports from old code.** Verify that `generate-new/` has no imports from `generate/`. If Phase 3 introduced any (e.g., `auth_access_analyzer`), duplicate the needed logic or refactor it out.
+
+Exit criteria: all snapshot tests still pass, the code is clean against coding guidelines, and the design matches the intent of this document. Stop for review.
+
+**Phase 5 — Unit tests**
+Write unit tests for the new classes in `generate-new/`. Test individual components (generators, renderers, Gen1App, BackendGenerator) in isolation. Don't port old tests mechanically — write tests that cover the same ground with the new architecture. The old `generate/` directory and its tests remain intact. The old code stays as reference for future refactoring passes.
+
+Exit criteria: all snapshot tests still pass, new unit tests pass, old tests still pass.
+
+**Phase 6 — Merge**
+Merge the branch. The old `generate/` directory stays in the codebase but is no longer wired (generate.ts imports from `generate-new/`). This keeps the PR focused on the new code.
+
+**Phase 7 — Delete old code**
+In a separate PR: delete the old `generate/` directory and its tests. Rename `generate-new/` to `generate/`. Update all import paths. This is a clean deletion PR with no logic changes.
+
+---
+
+## Design Principles for AI Assistants
+
+When working on this codebase, follow these principles proactively — don't wait for the human to identify the issues.
+
+### Design toward a target structure, not incrementally from existing code
+
+Before making changes, define what the code should look like when you're done. Don't preserve existing patterns by default — question whether they belong in the target design. The existing code is a reference, not a constraint.
+
+### Gen1App is a thin, category-agnostic facade
+
+Gen1App provides generic access to the Gen1 project state. It must not contain category-specific logic (auth triggers, GraphQL schemas, REST API configs, function categories). If a method is only called by one generator, it belongs in that generator. Gen1App should look like the test framework's `MigrationApp` class in `_framework/app.ts` — eagerly resolved readonly fields, simple accessor methods, no caching of filesystem operations.
+
+### Generators follow a consistent structure
+
+Every generator has:
+
+1. A constructor accepting `gen1App`, `backendGenerator`, `outputDir`, and references to other generators it contributes to
+2. A renderer instance named `defineX` (e.g., `defineAuth`, `defineStorage`)
+3. One public `plan()` method
+4. Public methods to accept contributions from other generators (e.g., `addTrigger`, `addFunctionAuthAccess`)
+5. Private methods that contribute to other generators
+
+File length is fine as long as this structure is maintained. Don't split files based on line count — split based on responsibility.
+
+### Eliminate intermediate reshaping layers
+
+If data flows through an interface that just renames properties from the previous layer, that interface shouldn't exist. Renderers should accept raw SDK types directly. The test: if removing a layer only requires renaming properties at the boundary, the layer is pure overhead.
+
+### Each generator owns its domain knowledge
+
+A generator should derive everything it needs from `Gen1App` and its own inputs. It should not rely on other generators to parse data on its behalf. For example:
+
+- The function generator determines its own trigger event type (from the resource name suffix), not the auth generator
+- The data generator reads the GraphQL schema from the cloud backend, not Gen1App
+- The auth generator gets Cognito IDs from `metaOutput`, not from walking CloudFormation stacks
+
+### Prefer concrete identifiers over generic resource maps
+
+AWS SDK calls should accept the specific ID they need (user pool ID, bucket name, function name), not a generic `Record<string, StackResource>` that the callee searches through. The caller extracts the ID from `metaOutput` and passes it directly.
+
+### Don't add defensive checks for states that can't occur
+
+If a previous step validated that a resource exists, don't null-check it again downstream. If `singleResourceName` found the auth resource, `metaOutput('auth', name, 'UserPoolId')` will have a value — don't add `if (!userPoolId) return []`. The coding guidelines are explicit about this: "Only return fallbacks or branch for valid states."
+
+### Cross-generator contributions flow from producer to consumer
+
+When generator A needs information from generator B's domain, B contributes it to A — not the other way around. For example:
+
+- Function generators contribute trigger info and auth access permissions to the auth generator
+- Function generators contribute storage access to the S3 generator
+- All generators contribute imports and statements to the backend generator
+
+The consumer exposes `addX()` methods. The producer calls them during `plan()`.