Claude-skill-registry 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

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

# 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

.origin

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

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

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

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

aurora-cli

aurora-cqrs

aurora-schema

prettier

conventional-commits