@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/monorepo/.claude/skills/catalyst-cli/references/origin-conciliation.md

@@ -0,0 +1,152 @@
+# Origin reconciliation — three-way merge algorithm
+
+This document goes deep on what `SKILL.md` summarizes: when `catalyst generate` leaves `.origin` files behind, the AI agent must reconcile three potential authors of the divergent content. Read this before acting on `.origin` files in any non-trivial regen.
+
+---
+
+## Mental model
+
+After a regen with `--force` (or after any regen that ran on a file with a hash mismatch), the filesystem looks like this:
+
+```
+<file>                  ← current content on disk. Untouched by this regen.
+                          Was authored by some combination of:
+                          (a) a previous codegen run
+                          (b) a human developer
+                          (c) you, the AI, this session
+
+<file>.origin.<ext>     ← what catalyst proposes to write now. Already merged
+                          with the user's preservation-region bodies from
+                          <file>, but the skeleton is the new template output.
+```
+
+Your job is to decide which version wins, possibly per hunk. The right answer depends on which of the three potential authors contributed which hunk.
+
+### Why `.origin` exists at all
+
+The codegen tracks, per file, a `skeleton hash` in the lockfile (`<bc>.<module>.<scope>.lock.json`). The skeleton is the file content with preservation regions stripped out. On every regen:
+
+1. The current skeleton hash on disk is computed.
+2. If it matches the stored hash → the file is regenerated transparently (preservation regions preserved; skeleton replaced; new skeleton hash stored). No `.origin`.
+3. If it does NOT match → someone edited the file outside the preservation regions. The codegen does **not** touch `<file>`; it writes the proposal to `<file>.origin.<ext>` and lets you reconcile.
+
+So the existence of a `.origin` file is a signal: **the skeleton of this file diverged from what the codegen thinks it produced**. Something happened outside the safe preservation regions.
+
+---
+
+## Who wrote what — the three authors
+
+| Author | Typical signature | How to detect |
+|---|---|---|
+| **Codegen** (previous run) | Boilerplate, type imports, module scaffolding, signal API shells, exported class declarations, route resolver shape | These are the parts that match the surrounding code style and pattern. They tend to live on the "skeleton" side. |
+| **User** (human developer) | Business logic, custom validators, domain-specific labels, integration code, comments that explain *why* not *what*, anything inside `AURORA:*-START/END` markers | `git log -p <file>` shows the developer's commits. `git blame <file>` attributes lines. |
+| **AI session** (you, now) | Anything that landed in `<file>` during this conversation, before the regen ran | Check the conversation history. Also: `git diff HEAD <file>` — if the file is modified but not committed and the diff aligns with what you wrote, it is yours. |
+
+The three are not always cleanly separable. A user might have edited code that the AI wrote earlier; the AI might have refactored code originally produced by the codegen. The point of the analysis is not to assign blame — it is to decide which version is the *better starting point* for the file going forward.
+
+---
+
+## The reconciliation algorithm
+
+For each `.origin` file:
+
+### Step 1 — Categorize the divergence
+
+Run `catalyst origin diff <path>` and read the unified patch end-to-end. Mentally tag each hunk:
+
+- **(C) Codegen-style** — looks like template output: imports, type annotations, scaffolding boilerplate, new shape introduced because the template evolved.
+- **(U) User-custom** — looks like hand-written domain logic, custom labels, business rule code, comments authored by a human.
+- **(A) AI-this-session** — recognise content you wrote during this conversation.
+- **(?) Unknown** — cannot tell.
+
+### Step 2 — Apply the decision matrix
+
+| Composition of hunks | Recommended action |
+|---|---|
+| All (C) | `catalyst origin accept <path>` — pure template improvement, adopt outright |
+| All (U) | `catalyst origin reject <path>` — user code that the new template would clobber; keep current |
+| All (A) | If the AI hunks belong inside a preservation region that exists in the new proposal → `accept` (the merge already preserved them). If they live OUTSIDE preservation regions and the new template overlaps them → do the three-way merge (Step 3). If the AI work is no longer needed → `reject`. |
+| Mix of (C) and (U) | Three-way merge (Step 3). Default to safety: rather lose the template improvement than lose user code. |
+| Mix of (C) and (A) | Three-way merge (Step 3). The AI knows what it wrote, so re-applying is feasible. |
+| Mix of (U) and (A) | Three-way merge (Step 3). |
+| Contains any (?) | **Stop. Ask the user.** Do not guess. |
+
+### Step 3 — The three-way merge
+
+When the divergence mixes authorship, the correct procedure is:
+
+```
+1. Save what you have:
+     git stash push <path>         # or commit to a wip branch
+     # this saves the current modified state, leaving HEAD content on disk
+
+2. Adopt the codegen proposal:
+     catalyst origin accept <path>
+     # <file>.origin.<ext> is renamed over <file>; you now have the fresh
+     # template output as your starting point
+
+3. Re-apply the saved hunks on top of the new scaffolding:
+     git stash pop                  # or git checkout wip-branch -- <path>
+     # this attempts the merge; resolve conflicts manually
+
+4. Verify the result:
+     - The user/AI hunks are preserved
+     - The codegen improvements are present
+     - The file compiles (run the typecheck or test for the touched module)
+```
+
+If step 3 produces merge conflicts you cannot confidently resolve, stop and ask the user. A bad three-way merge is worse than a missed template improvement — the latter is recoverable on the next regen, the former destroys work.
+
+---
+
+## Session-aware merge — when YOU wrote some of the divergence
+
+This is the case the original CLAUDE.md emphasises and the easiest one to get wrong.
+
+If the AI made changes to a file during the current conversation and then regenerated the module, the regen's `.origin` will contain the new template proposal **without** the AI's session edits. The AI has perfect knowledge of what it wrote this session — it can see the conversation. So:
+
+1. **Inventory**: list the files you (the AI) touched this session. `git status --short` shows everything modified vs HEAD; cross-reference with the messages where you used `Edit`/`Write`.
+2. **For each `.origin` pair on a file you touched**:
+   - Read the conversation. What was your intent in editing this file? Was it:
+     - **A**: a customization that should now go into the YAML schema? → put it in the YAML, accept the `.origin`, regenerate.
+     - **B**: a customization that has no YAML home (genuine business logic in a service, etc.)? → three-way merge: stash your edits, accept origin, re-apply.
+     - **C**: a fix for a bug in the previous codegen output that the new template also fixes? → just `accept`. Your fix was made redundant by the template improvement.
+3. **Document** in the conversation what you concluded for each file, so the user can audit.
+
+The most common mistake: blindly running `catalyst origin accept` on a subtree after a regen, thereby erasing edits the AI itself made minutes earlier. **Never bulk-accept** in a session that included edits to generated files. Run `git status` first; if files you edited appear among the `.origin` companions, treat them individually.
+
+---
+
+## When to `origin ignore` instead
+
+`catalyst origin ignore <path>` prepends an `// ignored file` (or `<!-- -->`, `# ` depending on extension) marker and deletes the `.origin`. The next regen will skip the file entirely. Use it when:
+
+- The file has diverged so far from the codegen that there is no useful overlap left.
+- The file is now wholly hand-maintained code that just happens to live where the codegen used to emit something.
+- You have decided to fork this file permanently from the template.
+
+**Do not** use `ignore` to escape from a reconciliation you found inconvenient. If the divergence is "the user changed the icon by hand", the right answer is to put the icon in the YAML and regenerate — not to ignore the file forever.
+
+---
+
+## Pitfalls
+
+- **The `.origin` file already contains user preservation regions.** The codegen merges them in *before* writing `.origin`, so the proposal you see is not the raw template output. If a region's body is identical in current and origin, it is because the merge preserved it — that hunk is not a divergence the merge engine cares about.
+- **`accept` is atomic on POSIX**, non-atomic on Windows (`fs.renameSync` does not overwrite there; the implementation falls back to `unlink` + `rename`). If you are on Windows and the host crashes mid-`accept`, the current file may be missing for a millisecond. Acceptable; documented.
+- **A `noop` from `accept`/`reject`/`ignore` is not an error**, it means there was no `.origin` at the path (idempotent). If you expected one and got `noop`, the file was already reconciled or never had divergence.
+- **`origin review` (interactive) and `origin <verb>` call the same domain functions.** A bug fix in one applies to both. They are not parallel implementations.
+
+---
+
+## Worst-case escape hatch
+
+If a reconciliation goes wrong and you are not sure what state the filesystem is in:
+
+```
+git status --short                     # see what is modified vs HEAD
+git diff <file>                        # see what changed
+git checkout <file>                    # discard all changes, return to HEAD
+catalyst generate <scope> module --name=<bc>/<module>   # regenerate from scratch
+```
+
+`git` is the safety net. The `.origin` files are not tracked (unless you committed them by mistake — clean them out: `find . -name '*.origin.*' -delete` is brute but effective).

package/dist/templates/monorepo/.claude/skills/catalyst-cli/references/schema-versioning.md

@@ -0,0 +1,100 @@
+# Aurora schema versioning — how to discover and pin the current version
+
+The `*.aurora.yaml` schema is versioned via SchemaStore. The catalog at SchemaStore lists every published Aurora schema family with version metadata. The skill needs this when:
+
+- Validating a YAML against the canonical grammar.
+- Discovering newly published fields the catalog has added since the project was last bumped.
+- Pointing the user at the JSON Schema URL for editor IDE support.
+
+---
+
+## The catalog
+
+The SchemaStore catalog is a single JSON document:
+
+```
+https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/api/json/catalog.json
+```
+
+Inside, the Aurora entry looks like:
+
+```json
+{
+  "name": "Aurora Agile Meta-Framework",
+  "description": "Yaml for Aurora Agile Meta-Framework",
+  "fileMatch": ["*.aurora.yaml", "*.aurora.yml"],
+  "url": "https://www.schemastore.org/aurora-1.3.json",
+  "versions": {
+    "1.0": "https://www.schemastore.org/aurora-1.0.json",
+    "1.1": "https://www.schemastore.org/aurora-1.1.json",
+    "1.2": "https://www.schemastore.org/aurora-1.2.json",
+    "1.3": "https://www.schemastore.org/aurora-1.3.json"
+  }
+}
+```
+
+`url` always points at the **latest** version. `versions` lists every published minor.
+
+---
+
+## How to fetch the current version
+
+Use `WebFetch` (preferred) or `curl` to load the catalog and locate the Aurora entry:
+
+```bash
+# Quick lookup of the current version
+curl -fsS https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/api/json/catalog.json \
+  | jq -r '.schemas[] | select(.name == "Aurora Agile Meta-Framework") | .url'
+# → https://www.schemastore.org/aurora-1.3.json
+```
+
+From the URL, parse the major.minor (`1.3`) and either:
+
+- Validate the YAML against that exact schema (download the schema, run an Ajv-style validator).
+- Reference the schema in the YAML's IDE configuration (most editors auto-discover from `fileMatch`).
+
+---
+
+## When to consult the schema, not just `catalyst-schema`
+
+The [`catalyst-schema`](../../catalyst-schema/SKILL.md) skill encodes Aurora's editorial conventions (naming, descriptions, mandatory fields, DDD semantics). The published JSON schema encodes what is *structurally valid* — the union of every property name and type the codegen accepts.
+
+When designing a new feature or auditing a YAML edit, both must align:
+
+| Need | Source |
+|---|---|
+| Is field name `tenantId` correct, or should it be `tenant`? | `catalyst-schema` (style and DDD opinions) |
+| Is `widget.type: async-multiple-search-select` a valid value? | JSON schema (structural validity) |
+| What are the allowed values of `front.detailMode`? | JSON schema (`enum`) |
+| Is `front.embedSupport` documented and supported in 1.3? | JSON schema + check published version |
+| Should this aggregate have a description? | `catalyst-schema` (says yes) |
+
+If a field is **valid in the JSON schema** but **not yet supported by the codegen**, the gap should land as an OpenSpec proposal against the relevant capability. Likewise, if the codegen supports a field that has not yet made it into the JSON schema, the JSON schema needs a bump.
+
+---
+
+## Pinning the project to a specific version
+
+Most editor integrations pick up `*.aurora.yaml` files via the SchemaStore `fileMatch` automatically. To pin a project to a specific version (e.g. force editors to validate against `1.2` while you migrate to `1.3`), add a YAML directive at the top of each schema file:
+
+```yaml
+# yaml-language-server: $schema=https://www.schemastore.org/aurora-1.2.json
+version: 0.0.1
+boundedContextName: iam
+moduleName: account
+...
+```
+
+The `# yaml-language-server` line is honoured by VS Code's YAML extension and most YAML LSP clients. It overrides the SchemaStore catalog's "latest" pointer for this one file.
+
+---
+
+## What to do when the catalog has bumped but the codegen has not caught up
+
+A version bump in SchemaStore signals that the schema vocabulary has grown. The codegen may or may not have caught up. To check:
+
+1. Note the latest version from the catalog (e.g. `1.3`).
+2. Inspect `aurora-catalyst-cli/CHANGELOG.md` and `aurora-catalyst-cli/openspec/specs/` for recent capability additions.
+3. If a property exists in `aurora-1.3.json` but no spec or codegen path references it → that property is **forward-declared in the schema** but not yet emitted by the codegen. Edit the YAML to use it freely, but understand the regen will not act on it until the codegen catches up.
+
+This is rare in practice but it does happen during multi-version migrations.

package/dist/templates/monorepo/.claude/skills/catalyst-schema/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: catalyst-schema
+description: >
+  Aurora YAML schema analysis and editing. Validates field names, descriptions,
+  types, and module semantics following DDD best practices. Trigger: When
+  analyzing or editing *.aurora.yaml files, improving field naming, adding
+  descriptions, or validating schema semantics.
+license: MIT
+metadata:
+  author: aurora
+  version: '1.1'
+  auto_invoke:
+    'Analyzing or editing *.aurora.yaml files, schema validation, field
+    semantics'
+allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch, WebSearch, Task
+---
+
+## When to Use
+
+Use this skill when:
+
+- Analyzing `*.aurora.yaml` files for quality and consistency
+- Editing YAML schemas (creating, updating, or deleting fields)
+- Validating field naming conventions and descriptions
+- Ensuring module descriptions explain purpose and context
+- Reviewing data type appropriateness
+
+**Always combine with:**
+
+- `catalyst-cli` skill when regenerating after YAML changes
+- `aurora-project-structure` skill for locating YAML files
+- `conventional-commits` skill when committing schema changes
+
+## Detailed References
+
+- [Types & Varchar Standards](types-reference.md) — Type selection guide, byte-optimized varchar lengths
+- [Patterns & Workflow](patterns-workflow.md) — Common patterns, analysis/editing workflows, change log template
+
+---
+
+## Critical Patterns
+
+### Module Description (REQUIRED)
+
+Every `*.aurora.yaml` must have a `description` property **before** `aggregateProperties:`.
+
+```yaml
+# ✅ CORRECT
+version: 0.0.1
+boundedContextName: iam
+moduleName: permission
+description: >
+  Module containing the permissions associated with each bounded context, to be
+  used to manage access to each API.
+aggregateProperties:
+  - name: id
+```
+
+**Description should explain:** What the module contains, what it's used for, how it relates to other modules.
+
+---
+
+### Mandatory Fields (REQUIRED in all modules)
+
+**All modules MUST include these fields:**
+
+1. `rowId` (after `id`) — `bigint`, autoIncrement, unique
+2. `createdAt` (end) — `timestamp`, nullable
+3. `updatedAt` (end) — `timestamp`, nullable
+4. `deletedAt` (end) — `timestamp`, nullable
+
+**Field order:** `id` → `rowId` → ... module fields ... → `createdAt` → `updatedAt` → `deletedAt`
+
+---
+
+### Field Naming Conventions
+
+| Pattern               | Use For             | Examples                                |
+| --------------------- | ------------------- | --------------------------------------- |
+| `camelCase`           | All field names     | `firstName`, `orderDate`, `totalAmount` |
+| `is*`, `has*`, `can*` | Boolean flags       | `isActive`, `hasChildren`, `canEdit`    |
+| `*At`                 | Timestamps          | `createdAt`, `updatedAt`, `publishedAt` |
+| `*Date`               | Date-only fields    | `birthDate`, `startDate`, `endDate`     |
+| `*Id`                 | Foreign keys        | `authorId`, `categoryId`, `parentId`    |
+| `sort`                | Display/UI ordering | `sort` (NOT `displayOrder`, `order`)    |
+
+---
+
+### Field Descriptions (MANDATORY)
+
+**Every field MUST have a description that explains WHY, not WHAT:**
+
+```yaml
+# ❌ BAD
+- name: price
+  type: decimal
+  description: The price of the book
+
+# ✅ GOOD
+- name: price
+  type: decimal
+  decimals: [10, 2]
+  description: >
+    Retail price in the store's base currency. Does not include taxes or
+    discounts. Used as base for price calculations.
+```
+
+---
+
+### ID Fields (CRITICAL RULE)
+
+**Fields of type `id` MUST NOT have a `length` property.**
+
+```yaml
+# ✅ CORRECT
+- name: id
+  type: id
+  primaryKey: true
+
+# ❌ INCORRECT
+- name: id
+  type: id
+  length: 36  # ← DELETE THIS
+```
+
+---
+
+### Relationship Fields (CRITICAL RULE)
+
+| Side                      | Has FK? | Use                                      |
+| ------------------------- | ------- | ---------------------------------------- |
+| Child/Many (invoice-line) | YES     | `type: id` + `relationship` block inside |
+| Parent/One (invoice)      | NO      | `type: relationship` (navigation only)   |
+| Many-to-many              | NO      | `type: relationship` + `pivot` config    |
+
+**⚠️ NEVER define both `invoiceId` (type: id) AND `invoice` (type: relationship) in the SAME module.**
+
+```yaml
+# ✅ child.aurora.yaml - ONLY the FK field
+- name: parentId
+  type: id
+  relationship:
+    type: many-to-one
+    field: parent
+    aggregateName: MyParent
+    modulePath: my-context/parent
+
+# ✅ parent.aurora.yaml - ONLY the navigation property
+- name: children
+  type: relationship
+  relationship:
+    type: one-to-many
+    aggregateName: MyChild
+    modulePath: my-context/child
+    key: parentId
+```
+
+---
+
+### Web Component — `displayFields` (for `grid-select-element`)
+
+When a field uses `webComponent.type: grid-select-element`, define `displayFields` to control
+which fields from the related entity are shown in the readonly input.
+
+```yaml
+# ✅ CORRECT — displayFields defined
+- name: meterId
+  type: id
+  webComponent:
+    type: grid-select-element
+    displayFields:
+      - model
+      - serialNumber
+  relationship:
+    type: many-to-one
+    aggregateName: IsuMeter
+    modulePath: isu/meter
+    key: id
+    field: meter
+```
+
+**Rendering rules:**
+
+- 1 field → `selected()?.field1`
+- 2+ fields → `selected() ? selected().field1 + ' (' + selected().field2 + ')' : ''`
+- Not defined → falls back to `?.name` (backward compatible)
+
+**`displayFields` values MUST be valid field names from the related module.**
+
+---
+
+### Cross-Module Consistency
+
+Use the same field names across ALL modules:
+
+```yaml
+- name: id        # Not: ID, _id, uuid
+- name: createdAt # Not: created, createdDate
+- name: updatedAt # Not: updated, modifiedAt
+- name: deletedAt # Not: deleted, removedAt
+- name: isActive  # Not: active, enabled
+```
+
+---
+
+### Index Names (63-char limit) — MANDATORY VALIDATION
+
+PostgreSQL limits index names to **63 characters**. Aurora generates: `{boundedContext}_{module}_{fieldName}` (snake_case).
+
+**Every time you add `index: index` or `index: unique`, calculate the generated index name length.**
+
+```
+index_name = snake_case(boundedContextName) + "_" + snake_case(moduleName) + "_" + snake_case(fieldName)
+```
+
+**If length > 63 → MUST add `indexName` property with abbreviated name.**
+
+```yaml
+- name: administrativeAreaLevel1Id
+  type: id
+  index: index
+  indexName: bpp_partner_addr_admin_area_lvl1_id  # < 63 chars
+```
+
+**Abbreviation pattern:** `{BC_abbrev}_{short_module}_{short_field}`
+
+| Bounded Context           | Abbrev |
+| ------------------------- | ------ |
+| `production-planning`     | `pp`   |
+| `business-partner-portal` | `bpp`  |
+| `common`                  | `cmn`  |
+
+---
+
+## Decision Trees
+
+### What Type Should This Field Be?
+
+```
+Is it a UUID identifier? ────YES───> type: id (NO length!)
+      │
+      NO
+      │
+Is it true/false? ────YES───> type: boolean (use is*/has*/can* prefix)
+      │
+      NO
+      │
+Is it money? ────YES───> type: decimal with decimals: [12, 2]
+      │
+      NO
+      │
+Fixed set of options? ────YES───> type: enum with enumOptions
+      │
+      NO
+      │
+Date and time? ────YES───> type: timestamp
+      │
+      NO
+      │
+Short text (< 255 chars)? ────YES───> type: varchar with maxLength
+      │
+      NO
+      │
+Long text? ────YES───> type: text
+```
+
+### Should I Edit or Just Analyze?
+
+```
+User explicitly requested edit? ────YES───> Edit mode
+      │
+      NO → Analysis mode (generate report)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| ❌ Don't                                  | ✅ Do                                             |
+| ----------------------------------------- | ------------------------------------------------- |
+| Skip module description                   | Always add description before aggregateProperties |
+| Skip mandatory fields (rowId, timestamps) | Always include rowId, createdAt, updatedAt, deletedAt |
+| Use abbreviations (dt, qty, amt)          | Use full words (createdAt, quantity, amount)       |
+| Name booleans without prefix (active)     | Use semantic prefix (isActive, hasPermission)     |
+| Add `length` to `id` type fields          | Never specify length for id type                  |
+| Write "The price" as description          | Explain context: "Retail price in base currency..." |
+| Use `float` for money                     | Always use `decimal` with proper scale            |
+| Duplicate relationship definitions        | FK side uses `type: id`, inverse uses `type: relationship` |
+
+---
+
+## Resources
+
+- **Aurora Docs**: Check `aurora-cli` skill for regeneration commands
+- **Project Structure**: Use `aurora-project-structure` skill to locate YAMLs
+
+## Related Skills
+
+| Skill                      | When to Use Together                                          |
+| -------------------------- | ------------------------------------------------------------- |
+| `aurora-cli`               | After editing YAML, regenerate with `aurora load back module` |
+| `aurora-project-structure` | To locate YAML files in correct directories                   |
+| `conventional-commits`     | When committing schema changes                                |
+| `aurora-cqrs`              | Understanding how YAML generates commands/queries             |