--- name: aurora-origin-merge description: > Handles .origin.ts file merges after Aurora CLI regeneration. Provides step-by-step workflow to surgically merge new schema code into files with custom modifications, preserving all business logic. Trigger: After aurora load back module creates .origin files, or when merging regenerated code with custom modifications. license: MIT metadata: author: aurora version: '1.2' auto_invoke: 'origin file merge, .origin.ts, merge after regeneration' scope: back allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Task --- ## When to Use Use this skill when: - Aurora CLI creates `.origin.ts` files after regeneration - You need to merge new schema-generated code into files with custom modifications - The CLI prompts "Do you want to manage origin files? (Y/n)" - You find `.origin.ts` files in the codebase after running `aurora load back module` **Always combine with:** - `aurora-cli` skill (triggers the regeneration) - `aurora-cqrs` skill (understand editable zones vs generated zones) - `prettier` skill (format after merge) ## Detailed References - [Merge Rules by File Type](merge-rules.md) — Mapper, handler, aggregate, model, API handler, resolver, DTO, event, seeder rules + conflict resolution scenarios --- ## Critical Concept: Why .origin Files Exist Aurora tracks every generated file via SHA1 hash in `*-lock.json` files. When you regenerate: ``` File hash matches lock? │ YES → Overwrite safely (no custom code) │ NO → File has custom modifications └→ Create filename.origin.ts (new generated version) Keep filename.ts intact (your custom code) ``` --- ## Step-by-Step Merge Workflow ### Step 0: Detect YAML Schema Delta (CRITICAL) **Before touching any `.origin` file, you MUST determine what changed in the YAML schema.** ```bash # Check if YAML has uncommitted changes git diff HEAD -- cliter//.aurora.yaml ``` - **If diff exists** → YAML changed, not yet committed → compare against `HEAD` - **If no diff** → YAML already committed → compare against previous commit ```bash # Flujo A: YAML not committed yet git show HEAD:cliter//.aurora.yaml > /tmp/old-schema.yaml # Flujo B: YAML already committed PREV_COMMIT=$(git log -2 --format="%H" -- cliter//.aurora.yaml | tail -1) git show $PREV_COMMIT:cliter//.aurora.yaml > /tmp/old-schema.yaml ``` ```bash # Compare to get delta diff /tmp/old-schema.yaml cliter//.aurora.yaml ``` | Delta | Action | | --- | --- | | New field in YAML | Merge from `.origin` into existing files | | Removed field in YAML | Remove from existing files | | Changed field type/properties | Update in existing files | | No change for a field | DO NOT touch | **GOLDEN RULE: Only merge code related to fields that CHANGED in the YAML delta. Never touch code for fields that didn't change.** ### Step 1: Find All .origin Files ```bash fd ".origin.ts" ``` ### Step 2: For EACH .origin File Read BOTH files side by side: 1. **Existing file** (has custom code + old schema) 2. **Origin file** (has NO custom code + new schema) ### Step 3: Merge Using the YAML Delta For each change identified in Step 0, apply the appropriate merge rule. See [Merge Rules by File Type](merge-rules.md) for detailed rules per file type. ### Step 4: Preserve ALL Custom Code - Custom class properties remain untouched - Custom logic in method bodies is preserved - Custom helper methods are kept - Custom imports are retained - Intentionally removed fields stay removed ### Step 5: Delete the .origin File ```bash rm path/to/file.origin.ts ``` ### Step 6: Verify No .origin Files Remain ```bash fd ".origin.ts" # Should return empty ``` --- ## Handling Parameter Order **CRITICAL:** Aurora generates parameters in the EXACT order defined in `.aurora.yaml`. When merging, the new field MUST be inserted in the correct position. This order MUST be reflected in: 1. `register()` parameters in Aggregate 2. `register()` arguments in Mapper's `makeAggregate()` 3. `Response` constructor parameters 4. `Response` constructor arguments in Mapper's `makeResponse()` 5. Command/Query payload fields 6. Event properties **How to determine position:** Look at the `.origin` file — Aurora already generated the correct order. --- ## Post-Merge Checklist - [ ] No `.origin.ts` files remain (`fd ".origin.ts"` returns empty) - [ ] All new imports are added (no missing Value Objects) - [ ] Parameter order matches `.aurora.yaml` field order - [ ] All custom logic is preserved (no overwrites) - [ ] Eager loading blocks include new relationships (if any) - [ ] Run Prettier to format (`npx prettier --write `) - [ ] TypeScript compiles without errors (`npx tsc --noEmit`) --- ## Common Mistakes | Mistake | Prevention | | --- | --- | | Skipping YAML delta detection | ALWAYS diff YAML before merging | | Adding intentionally removed fields | Check YAML delta — if field is NOT new, don't add it | | Replacing entire file with .origin | Always compare first | | Forgetting new imports | Check .origin imports section | | Wrong parameter order | Match YAML field order | | Leaving .origin files in codebase | Always delete after merge | | Not running Prettier after merge | Run prettier on modified files | --- ## Decision Tree: How Complex Is This Merge? ``` How many .origin files? │ 1 file ─────────────── Simple merge │ 2-5 files ──────────── Medium merge (review each) │ 5+ files ───────────── Complex merge (plan first) Does the existing file have custom logic? │ NO (just stale hash) → Replace entirely with .origin content │ YES, simple → Quick surgical merge │ YES, complex (50+ lines) → Careful line-by-line merge │ YES, very complex (500+ lines) → Read ENTIRE file, merge minimally ``` --- ## Commands ```bash fd ".origin.ts" # Find all .origin files code -d path/to/file.ts path/to/file.origin.ts # Compare side by side fd ".origin.ts" -x rm {} # Delete all after merge npx tsc --noEmit # Check TypeScript compiles npx prettier --write "src/@app/**/*.ts" # Format merged files ``` --- ## Related Skills | Skill | When to Use Together | | --- | --- | | `aurora-cli` | Triggers regeneration that creates .origin files | | `aurora-cqrs` | Understand editable zones vs generated zones | | `aurora-schema` | Understanding YAML field order for parameter positioning | | `prettier` | Format files after merge | | `conventional-commits` | Commit after successful merge |