@tailor-platform/erp-kit 0.1.0 → 0.1.2

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
+  "license": "MIT",
   "bin": {
     "erp-kit": "./dist/cli.js"
   },
   "files": [
+    "CHANGELOG.md",
     "dist",
-    "rules",
+    "LICENSE",
     "schemas",
     "skills",
     "src"

package/schemas/module/command.yml

@@ -35,6 +35,7 @@ structure:
       # Error handling - REQUIRED
       # How errors are handled
       - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
         lists:
           - min: 0
             type: unordered

package/schemas/module/model.yml

@@ -37,6 +37,15 @@ structure:
                 type: unordered
                 min_items: 0
 
+          - heading: "### Query Definitions"
+            description: |
+              Definitions of queries this domain model supports.
+              Should match with the queries defined in modules/**/docs/queries/*.md and link to them.
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
           - heading: "### Models"
             description: |
               Actual database models necessary for the domain model.

package/schemas/module/query.yml

@@ -0,0 +1,53 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this query does - REQUIRED
+      - heading: "## Overview"
+
+      # Business rules - REQUIRED
+      # Rules, constraints, and validation logic
+      - heading: "## Business Rules"
+        allow_additional: true
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # How it works - REQUIRED
+      # Step-by-step flow or workflow
+      - heading: "## Process Flow"
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # External dependencies - OPTIONAL
+      # Queries from other modules that this query depends on
+      - heading: "## External Dependencies"
+        description: "e.g. `- [inventory::getStockLevel](../../inventory/queries/getStockLevel.md) - Get current stock level`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Error handling - REQUIRED
+      # How errors are handled
+      - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/skills/1-module-docs/SKILL.md

@@ -105,3 +105,7 @@ Always run before completing:
 ```bash
 pnpm run module:doc:check
 ```
+
+## References
+
+- [Module structure](references/structure.md)

package/{rules/module-development → skills/1-module-docs/references}/structure.md

@@ -1,15 +1,10 @@
----
-paths:
-  - "modules/*/src/"
----
-
 # Module Directory Structure
 
 ```
 src/
 ├── db/           # Database models (one file per model)
 ├── executor/     # Async executors (record triggers, job functions)
-├── function/     # Domain functions + tests (*.test.ts co-located)
+├── command/      # Domain commands + tests (*.test.ts co-located)
 ├── lib/          # Internal shared code (errors.ts, types.ts)
 ├── testing/      # Test fixtures and helpers
 ├── generated/    # Auto-generated code (do not edit)
@@ -21,7 +16,7 @@ src/
 
 - `db/`: Only documentable model definitions, no helpers
 - `executor/`: Async executors as factory functions (see executors.md)
-- `function/`: Domain functions + co-located tests, no utilities
+- `command/`: Domain commands + co-located tests, no utilities
 - `lib/`: Internal errors and types (not documented)
 - `testing/`: Fixtures for tests only
 - Run `pnpm generate` after modifying `db/` models

package/skills/2-module-feature-breakdown/SKILL.md

@@ -64,3 +64,9 @@ Always run before completing:
 ```bash
 pnpm run module:doc:check
 ```
+
+## References
+
+- [Module structure](references/structure.md)
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)

package/{rules/module-development → skills/2-module-feature-breakdown/references}/commands.md

@@ -1,9 +1,3 @@
----
-paths:
-  - "modules/*/src/command/*.ts"
-  - "!modules/*/src/command/*.test.ts"
----
-
 # Command Implementation
 
 ## defineCommand Pattern

package/{rules/module-development → skills/2-module-feature-breakdown/references}/models.md

@@ -1,8 +1,3 @@
----
-paths:
-  - "modules/*/src/db/*.ts"
----
-
 # Database Models
 
 ## Factory Function Pattern

package/skills/2-module-feature-breakdown/references/structure.md

@@ -0,0 +1,22 @@
+# Module Directory Structure
+
+```
+src/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── command/      # Domain commands + tests (*.test.ts co-located)
+├── lib/          # Internal shared code (errors.ts, types.ts)
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated code (do not edit)
+├── index.ts      # Public exports
+└── module.ts     # Module definition
+```
+
+## Rules
+
+- `db/`: Only documentable model definitions, no helpers
+- `executor/`: Async executors as factory functions (see executors.md)
+- `command/`: Domain commands + co-located tests, no utilities
+- `lib/`: Internal errors and types (not documented)
+- `testing/`: Fixtures for tests only
+- Run `pnpm generate` after modifying `db/` models

package/skills/3-module-doc-review/SKILL.md

@@ -228,3 +228,9 @@ For each command doc:
 | "Deactivate X"    | deactivateX          |
 | "Assign X to Y"   | assignXToY           |
 | "Remove X from Y" | removeXFromY         |
+
+## References
+
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)
+- [Testing patterns](references/testing.md)

package/skills/3-module-doc-review/references/commands.md

@@ -0,0 +1,54 @@
+---
+paths:
+  - "packages/erp-kit/src/modules/*/command/*.ts"
+  - "!packages/erp-kit/src/modules/*/command/*.test.ts"
+---
+
+# Command Implementation
+
+## defineCommand Pattern
+
+Commands that don't need custom fields use `defineCommand` directly:
+
+```typescript
+export const myCommand = defineCommand(permissions.myCommand, async (db: DB, input: Input) => { ... });
+```
+
+## Factory Function Pattern (custom fields)
+
+Commands that insert into a table with user-extensible fields use a `makeCreateX<CF>()` factory:
+
+- Export only `makeCreateX` — no default instance
+- Generic `CF extends Record<string, unknown>` for custom fields
+- Input type: `CreateXInput & CF`
+- Destructure known fields, rest-spread custom fields into `.values()` before known fields
+- Cast custom fields: `...(customFields as Record<string, unknown>)`
+- `module.ts` wires with `makeCreateX<FieldsToInsertable<F>>()`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/skills/3-module-doc-review/references/models.md

@@ -0,0 +1,29 @@
+# Database Models
+
+## Factory Function Pattern
+
+Each model is a `createXType<const F>(params)` factory:
+
+- Params interface generic: `F extends Record<string, TailorAnyDBField>`
+- `fields?: F` — optional custom fields from parent modules
+- Spread as `...(params.fields ?? {}) as F` to preserve type information
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+- Export a default instance: `export const x = createXType({})`
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/{rules/module-development → skills/3-module-doc-review/references}/testing.md

@@ -1,9 +1,3 @@
----
-paths:
-  - "modules/*/src/command/*.test.ts"
-  - "modules/*/src/testing/*.ts"
----
-
 # Testing Patterns
 
 ## Test Coverage Goal

package/skills/4-module-tdd-implementation/SKILL.md

@@ -24,27 +24,35 @@ MODELS → ERRORS → FIXTURES → TESTS → IMPLEMENT → EXPORT → VERIFY
 
 ### 1. Database Models (`src/db/`)
 
-See: `.agents/rules/module-development/models.md`
+**Read [models rules](references/models.md) and [db-relations rules](references/db-relations.md) before writing any model.**
+
+Key patterns: factory function, `db.fields.timestamps()`, `.description()` on fields, `.relation()` for foreign keys.
 
 ### 2. Error Classes (`src/lib/errors.ts`)
 
-See: `.agents/rules/module-development/errors.md`
+**Read [errors rules](references/errors.md) before defining errors.**
+
+Key patterns: `name` as const = class name, `code` as const = SCREAMING_SNAKE_CASE.
 
 ### 3. Test Fixtures (`src/testing/fixtures.ts`)
 
-See: `.agents/rules/module-development/testing.md`
+**Read [testing rules](references/testing.md) before writing fixtures or tests.**
 
 ### 4. Write Tests First (`src/command/*.test.ts`)
 
-See: `.agents/rules/module-development/testing.md`
+Same reference: [testing rules](references/testing.md).
+
+Key patterns: `createMockDb<DB>()`, fixed IDs `"entity-1"`, cover all doc branches.
 
 ### 5. Implement Commands (`src/command/*.ts`)
 
-See: `.agents/rules/module-development/commands.md`
+**Read [commands rules](references/commands.md) before implementing.**
+
+Key patterns: dual function (`_fn` internal + `fn<T>` public), validate → query → mutate.
 
 ### 6. Export (`src/index.ts`)
 
-See: `.agents/rules/module-development/exports.md`
+**Read [exports rules](references/exports.md) for export order.**
 
 ### 7. Verify
 
@@ -54,3 +62,13 @@ pnpm lint       # Check code style
 pnpm typecheck  # Verify TypeScript types
 pnpm test       # Run all tests
 ```
+
+## References
+
+- [Module structure](references/structure.md)
+- [Model patterns](references/models.md)
+- [Database relations](references/db-relations.md)
+- [Command patterns](references/commands.md)
+- [Error patterns](references/errors.md)
+- [Testing patterns](references/testing.md)
+- [Export order](references/exports.md)

package/skills/4-module-tdd-implementation/references/commands.md

@@ -0,0 +1,45 @@
+# Command Implementation
+
+## Dual Function Pattern
+
+Two functions per operation: internal `_fn` and public `fn`.
+
+**Internal function (`_myFunction`):**
+
+- Takes concrete `DB` type from `generated/kysely-tailordb`
+- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
+- Contains actual implementation
+
+**Public function (`myFunction`):**
+
+- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
+- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
+- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/{rules/sdk-best-practices → skills/4-module-tdd-implementation/references}/db-relations.md

@@ -1,8 +1,3 @@
----
-paths:
-  - "modules/*/src/db/*.ts"
----
-
 # Database Relations
 
 ## Relation Pattern

package/{rules/module-development → skills/4-module-tdd-implementation/references}/errors.md

@@ -1,8 +1,3 @@
----
-paths:
-  - "modules/*/src/lib/errors.ts"
----
-
 # Error Classes
 
 Naming convention:

package/{rules/module-development → skills/4-module-tdd-implementation/references}/exports.md

@@ -1,8 +1,3 @@
----
-paths:
-  - "modules/*/src/index.ts"
----
-
 # Module Exports
 
 Export order:

package/skills/4-module-tdd-implementation/references/models.md

@@ -0,0 +1,30 @@
+# Database Models
+
+## Factory Function Pattern
+
+```typescript
+export function createEntityType(params: {
+  fields?: Record<string, unknown>;
+  additionalStatuses?: string[];
+});
+```
+
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/skills/4-module-tdd-implementation/references/structure.md

@@ -0,0 +1,22 @@
+# Module Directory Structure
+
+```
+src/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── command/      # Domain commands + tests (*.test.ts co-located)
+├── lib/          # Internal shared code (errors.ts, types.ts)
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated code (do not edit)
+├── index.ts      # Public exports
+└── module.ts     # Module definition
+```
+
+## Rules
+
+- `db/`: Only documentable model definitions, no helpers
+- `executor/`: Async executors as factory functions (see executors.md)
+- `command/`: Domain commands + co-located tests, no utilities
+- `lib/`: Internal errors and types (not documented)
+- `testing/`: Fixtures for tests only
+- Run `pnpm generate` after modifying `db/` models

package/skills/4-module-tdd-implementation/references/testing.md

@@ -0,0 +1,37 @@
+# Testing Patterns
+
+## Test Coverage Goal
+
+Tests should cover all paths in the corresponding `docs/commands/*.md`:
+
+- **Process Flow**: Each branch in the mermaid flowchart = one test case
+- **Error Scenarios**: Each error code listed = one test case
+- **Idempotent paths**: If flowchart shows "Already exists? → Return existing"
+
+## Mock Database
+
+```typescript
+const { db, spies } = createMockDb<DB>();
+
+// Single return
+spies.select.mockReturnValue(entity);
+
+// Sequential returns (in query execution order)
+spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
+```
+
+## Custom Fields Passthrough
+
+For `makeCreateX` factory commands, add one test verifying custom fields reach `.values()`:
+
+- Instantiate with concrete type: `makeCreateX<{ myField: string }>()`
+- Assert with `spies.values`: `expect(spies.values).toHaveBeenNthCalledWith(1, expect.objectContaining({ myField: "value" }))`
+- Use `toHaveBeenNthCalledWith(n, ...)` when multiple inserts occur (e.g., audit events)
+
+## Fixtures (`src/testing/fixtures.ts`)
+
+- Import `Schema` from `lib/types` (not `Namespace` from generated code)
+- Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`
+- Fixed IDs for traceability: `"entity-1"`
+- Consistent timestamp: `new Date("2024-01-01T00:00:00.000Z")`
+- `updatedAt: null` for base fixtures

package/skills/5-module-implementation-review/SKILL.md

@@ -398,3 +398,11 @@ describe("myCommand", () => {
   it("throws NOT_FOUND when missing"); // Check: error scenario
 });
 ```
+
+## References
+
+- [Model patterns](references/models.md)
+- [Command patterns](references/commands.md)
+- [Error patterns](references/errors.md)
+- [Testing patterns](references/testing.md)
+- [Export order](references/exports.md)

package/skills/5-module-implementation-review/references/commands.md

@@ -0,0 +1,45 @@
+# Command Implementation
+
+## Dual Function Pattern
+
+Two functions per operation: internal `_fn` and public `fn`.
+
+**Internal function (`_myFunction`):**
+
+- Takes concrete `DB` type from `generated/kysely-tailordb`
+- Return type uses `Schema` from `lib/types`: `Promise<{ entity: Entity<Schema> }>`
+- Contains actual implementation
+
+**Public function (`myFunction`):**
+
+- Generic signature: `<T extends { Entity: object }>(db: Kysely<T>, ...)`
+- Return type uses generic `T`: `Promise<{ entity: Entity<T> }>`
+- Delegates to internal with type casting: `_fn(db as unknown as DB, ...) as unknown as Result`
+
+## Implementation Considerations
+
+- **Validation**: Check referenced entities exist before operating
+- **Idempotency**: For assign/revoke, return existing instead of throwing
+- **Return format**: Wrap in object `{ entity }` not just `entity`
+
+## Conventions
+
+- Input types: exported interfaces (`export interface MyFunctionInput`)
+- Use `.executeTakeFirst()` for single results
+- Include JSDoc: `/** Function: name \n Description */`
+
+## State Transitions
+
+For commands that transition between statuses, accept `from?: string[]` with a default:
+
+```typescript
+from?: string[];  // Default: ["ACTIVE"]
+
+const validFromStatuses = input.from ?? ["ACTIVE"];
+if (!validFromStatuses.includes(user.status)) {
+  throw new InvalidStatusTransitionError(user.status, targetStatus);
+}
+```
+
+- Default `from` contains the base valid source status
+- Parent modules can override to allow transitions from additional statuses

package/skills/5-module-implementation-review/references/errors.md

@@ -0,0 +1,7 @@
+# Error Classes
+
+Naming convention:
+
+- `name`: Class name exactly, `as const`
+- `code`: SCREAMING_SNAKE_CASE, `as const`
+- Constructor includes context (IDs, values)

package/skills/5-module-implementation-review/references/exports.md

@@ -0,0 +1,8 @@
+# Module Exports
+
+Export order:
+
+1. `defineModule` from module.ts
+2. Generated types (enum values + types separately)
+3. Error classes (for typed catch blocks)
+4. Domain functions with input types

package/skills/5-module-implementation-review/references/models.md

@@ -0,0 +1,30 @@
+# Database Models
+
+## Factory Function Pattern
+
+```typescript
+export function createEntityType(params: {
+  fields?: Record<string, unknown>;
+  additionalStatuses?: string[];
+});
+```
+
+- Include `...db.fields.timestamps()`
+- Use `.description()` for field docs
+- Apply permissions at model level
+
+## Stateful Model Enums
+
+Status enums are tied to the module's state machine. Base module defines core statuses; parent callers can only **extend, not replace**.
+
+```typescript
+// Good: extension only
+const BASE_STATUSES = ["PENDING", "ACTIVE", "INACTIVE"] as const;
+const statuses = [...BASE_STATUSES, ...(params.additionalStatuses ?? [])];
+
+// Bad: allows replacement
+const statuses = params.statuses ?? ["PENDING", "ACTIVE", "INACTIVE"];
+```
+
+- Name parameter `additionalX` to signal extension-only
+- Parent modules handle their additional status transitions

package/skills/5-module-implementation-review/references/testing.md

@@ -0,0 +1,29 @@
+# Testing Patterns
+
+## Test Coverage Goal
+
+Tests should cover all paths in the corresponding `docs/commands/*.md`:
+
+- **Process Flow**: Each branch in the mermaid flowchart = one test case
+- **Error Scenarios**: Each error code listed = one test case
+- **Idempotent paths**: If flowchart shows "Already exists? → Return existing"
+
+## Mock Database
+
+```typescript
+const { db, spies } = createMockDb<DB>();
+
+// Single return
+spies.select.mockReturnValue(entity);
+
+// Sequential returns (in query execution order)
+spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
+```
+
+## Fixtures (`src/testing/fixtures.ts`)
+
+- Import `Schema` from `lib/types` (not `Namespace` from generated code)
+- Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`
+- Fixed IDs for traceability: `"entity-1"`
+- Consistent timestamp: `new Date("2024-01-01T00:00:00.000Z")`
+- `updatedAt: null` for base fixtures

package/skills/app-compose-1-requirement-analysis/SKILL.md

@@ -83,3 +83,7 @@ pnpm run app:doc:check
 ## Next Step
 
 After completing Tier 1-2, use `/app-compose-2-requirements-breakdown` to create Tier 3 documentation.
+
+## References
+
+- [Application structure](references/structure.md)