aurora-cli

When to Use

• User asks to "regenerate", "load", or "generate" a frontend module
• User wants to add a package (oauth, iam, common, etc.)
• User needs to create a new Aurora frontend project
• After YAML schema changes that require code regeneration
• User mentions "aurora cli", "aurora load front", or "regenerate"

---

Critical Patterns

Command Structure

Action	Command	When to Use
Regenerate module	aurora load front module -n=<bc>/<module>	After YAML changes
Force regenerate	aurora load front module -n=<bc>/<module> -f	Override protection
Overwrite interfaces	aurora load front module -n=<bc>/<module> -w	Update interfaces
Add package	aurora add front <package>	Install package
New project	aurora new front <name>	Create project

Hash Protection System

Aurora tracks file modifications via hash. Files with custom changes are protected by default:

• Without -f: Modified files are preserved
• With -f: All files are overwritten (use with caution)
• With -w: Only interfaces are overwritten

CRITICAL: Handling .origin files after regeneration

When Aurora detects that a file was manually modified (different hash), it creates .origin.ts (and .origin.html) files instead of overwriting. The CLI asks: Do you want to manage origin files? (Y/n).

Non-interactive execution (from Claude Code or scripts):

The CLI enters an interactive arrow-key menu that cannot be automated with pipes. Use expect to answer Y and then Ctrl+C to exit the menu, preserving the .origin files on disk:

expect -c '
spawn aurora load front module -n=<bc>/<module> -fw
expect "Do you want to manage origin files?"
send "Y\r"
expect "Select file to manage"
send "\x03"
expect eof
'

IMPORTANT: Do NOT answer n — that deletes all .origin files.

After the CLI finishes, invoke the aurora-origin-merge skill to handle all .origin files. That skill contains the complete merge workflow, rules by file type, and conflict resolution.

---

Execution Flow

1. Identify Action

Ask the user what they want to do:

1. Generate/Regenerate module - Regenerate code from existing YAML
2. Add package - Install preconfigured package
3. Create project - Create new Aurora frontend project (rare)

2. Gather Information

For Generate/Regenerate Module:

1. Ask which bounded context and module to regenerate
2. ONLY if you can't identify them, list available YAMLs in cliter/ using Glob
3. Ask about flags:
   • --force (overwrite existing files)
   • --overwriteInterface (overwrite TypeScript interfaces)
   • --verbose (detailed output)

For Add Package:

1. Show available packages (see list below)
2. Ask which package to install
3. Ask if --force is needed

For Create Project:

1. Ask for project name
2. Confirm before executing

3. Execute Command

# Regenerate module
aurora load front module -n=<bounded-context>/<module> [-f] [-w] [-v]

# Add package
aurora add front <package> [-f]

# Create project
aurora new front <app-name>

4. Report Results

Command executed successfully
aurora load front module -n=common/country -fw

Regenerated Files:
  - src/app/modules/admin/apps/common/country/...
  - src/app/modules/admin/apps/common/country/country.graphql.ts
  - src/app/modules/admin/apps/common/country/country.columns-config.ts

Preserved Files (modified hash):
  - src/app/modules/admin/apps/common/country/country-detail.component.ts
  (These files have custom modifications and were not overwritten)

Origin Files Created:
  - src/app/modules/admin/apps/common/country/country-detail.component.origin.ts
  - src/app/modules/admin/apps/common/country/country.graphql.origin.ts
  (These require manual merge — invoke `aurora-origin-merge` skill)

Summary:
  - X files regenerated
  - Y files preserved
  - Z .origin files created (need merge)

IMPORTANT: If .origin.ts files are created after regeneration, you MUST invoke the aurora-origin-merge skill to merge the schema delta into the existing files. Run fd ".origin.ts" to check.

Before invoking the merge skill, run git diff HEAD -- cliter/<bc>/<module>.aurora.yaml to identify NEW, MODIFIED, and DELETED fields. The merge skill's Step 0 requires this YAML diff to distinguish schema changes from intentional custom removals.

---

Available Packages (Front)

Package	Description
auditing	HTTP communication and side effects
common	Countries, langs, attachments
environments	Environment configurations
iam	Identity and Access Management
message	Inbox, outbox, messaging
msEntraId	Microsoft Entra ID authentication
oAuth	OAuth clients, tokens, scopes

---

Available Bounded Contexts

Based on cliter/ directory:

Bounded Context	Modules
common	lang, country, administrative-area-level-, attachment-
iam	account, user, role, permission, tenant, tag, bounded-context
o-auth	client, application, scope, access-token, refresh-token
auditing	http-communication, side-effect
message	inbox, outbox, message, inbox-setting
queue-manager	queue, job-registry
search-engine	collection, field
support	issue, comment
tools	key-value, migration, procedure, webhook, webhook-log
business-partner-portal	business-partner, partner-, sales-invoice-, etc.

---

Commands Reference

# Regenerate module from YAML
aurora load front module -n=common/country

# Regenerate with force (overwrite all)
aurora load front module -n=common/country -f

# Regenerate with interface overwrite
aurora load front module -n=common/country -w

# Regenerate with force + interface overwrite + verbose
aurora load front module -n=common/country -fwv

# Add package
aurora add front oAuth

# Show available packages (interactive)
aurora add front

# Create new frontend project
aurora new front my-admin-panel

---

Flags

Flag	Short	Description
--force	-f	Overwrite existing files (ignore hash)
--overwriteInterface	-w	Overwrite TypeScript interfaces
--noGraphQLTypes	-g	Avoid generating GraphQL types
--verbose	-v	Show detailed CLI output
--help	-h	Show CLI help

---

Generated File Structure

When regenerating a module, Aurora generates:

src/app/modules/admin/apps/<bounded-context>/<module>/
├── <module>.columns-config.ts     # Grid column configuration
├── <module>.graphql.ts            # GraphQL queries/mutations
├── <module>.routes.ts             # Angular routes
├── <module>.service.ts            # Service with GraphQL operations
├── <module>.types.ts              # TypeScript interfaces
├── <module>-detail.component.ts   # Detail/edit form component
├── <module>-detail.component.html # Detail template
├── <module>-list.component.ts     # List/grid component
└── <module>-list.component.html   # List template

---

Error Handling

Error	Solution
CLI not found	Install with npm i -g @aurorajs.dev/cli
YAML not found	Check cliter/<bc>/<module>.aurora.yaml exists
Permission error	Check file permissions
Module not found	Verify bounded-context/module name spelling

---

Common Workflows

After YAML Schema Changes

# 1. Edit the YAML file
# cliter/common/country.aurora.yaml

# 2. Regenerate the module
aurora load front module -n=common/country

# 3. If you need to update interfaces too
aurora load front module -n=common/country -w

# 4. Check YAML diff to know what changed
git diff HEAD -- cliter/<bc>/<module>.aurora.yaml

# 5. Check for .origin files and merge them
fd ".origin.ts"
# If any .origin files exist -> invoke aurora-origin-merge skill
# Pass the YAML diff context (new/modified/deleted fields) to the merge

Adding New Package

# 1. Add the package
aurora add front iam

# 2. The CLI will generate all necessary files
# 3. Configure routes if needed

Full Regeneration (Caution)

# Only use when you want to discard all customizations
aurora load front module -n=common/country -f

---

Related Skills

Skill	When to Use Together
aurora-schema	Before regenerating, validate YAML
aurora-origin-merge	After regeneration creates .origin files
aurora-project-structure	Understand where files are generated
conventional-commits	Commit after successful regeneration

---

Resources

• YAML Definitions: cliter/<bounded-context>/<module>.aurora.yaml
• Generated Code: src/app/modules/admin/apps/<bounded-context>/<module>/
• CLI Version: aurora --version
• CLI Help: aurora --help