aurora-origin-merge

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 — 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.

# Check if YAML has uncommitted changes
git diff HEAD -- cliter/<bc>/<module>.aurora.yaml

• If diff exists → YAML changed, not yet committed → compare against HEAD
• If no diff → YAML already committed → compare against previous commit

# Flujo A: YAML not committed yet
git show HEAD:cliter/<bc>/<module>.aurora.yaml > /tmp/old-schema.yaml

# Flujo B: YAML already committed
PREV_COMMIT=$(git log -2 --format="%H" -- cliter/<bc>/<module>.aurora.yaml | tail -1)
git show $PREV_COMMIT:cliter/<bc>/<module>.aurora.yaml > /tmp/old-schema.yaml

# Compare to get delta
diff /tmp/old-schema.yaml cliter/<bc>/<module>.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

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 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

rm path/to/file.origin.ts

Step 6: Verify No .origin Files Remain

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 <files>)
• [ ] 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

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 |