@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/skills/erp-kit-module-4-tdd/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: erp-kit-module-4-tdd
+description: Use when implementing features in any module under modules/. Triggers on TDD workflow, domain command implementation, adding new database models, creating test fixtures, or implementing business logic commands.
+---
+
+# TDD Implementation for Module Development
+
+Guide for implementing features in modules using Test-Driven Development.
+
+## When to Use
+
+- Implementing new domain commands in any module
+- Implementing read-only queries in any module
+- Adding database models with `@tailor-platform/sdk`
+- Creating tests with `@tailor-platform/erp-kit` testing utilities
+- Implementing business logic (CRUD, state transitions, relationships)
+
+## Workflow
+
+```
+DOCS → MODELS → GENERATE → FIXTURES → TESTS → IMPLEMENT → EXPORT → VERIFY
+```
+
+## Step-by-Step
+
+### 1. Write Command/Query Docs
+
+Write markdown specs under `docs/commands/*.md` and `docs/queries/*.md`. These are the source of truth for error scenarios, permissions, and generated code. See erp-kit-module-1-docs, erp-kit-module-2-feature-breakdown, and erp-kit-module-3-doc-review for documentation workflow.
+
+### 2. Database Models (`db/`)
+
+**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.
+
+### 3. Generate Code
+
+**Read [generated code rules](references/generated-code.md) for what gets generated and what you write by hand.**
+
+```bash
+# Generate kysely types from models
+pnpm generate
+
+# Generate errors, permissions, and command/query shells from docs
+erp-kit module generate code --root <root> <module>
+```
+
+Generated `.generated.ts` files provide: error classes, permission definitions, and command/query shells. Never edit these files.
+
+### 4. Test Fixtures (`testing/fixtures.ts`)
+
+**Read [testing rules](../erp-kit-module-shared/references/testing.md) before writing fixtures or tests.**
+
+### 5. Write Tests First (`command/*.test.ts`)
+
+Same reference: [testing rules](../erp-kit-module-shared/references/testing.md).
+
+Key patterns: `createMockDb<DB>()`, fixed IDs `"entity-1"`, cover all doc branches.
+
+### 6. Implement Commands (`command/*.ts`)
+
+**Read [commands rules](../erp-kit-module-shared/references/commands.md) before implementing.**
+
+Key patterns: export `run` function, generated shell wraps with `defineCommand(permissions.xxx, run)`, generic `CF` for custom fields, validate → query → mutate.
+
+### 7. Implement Queries (`query/*.ts`)
+
+**Read [queries rules](../erp-kit-module-shared/references/queries.md) before implementing.**
+
+Key patterns: `defineQuery`, `ReadonlyDB<DB>`, `QueryContext`. Generated queries handle simple lookups; write custom queries for joins, aggregations, complex filters.
+
+### 8. Export (`index.ts`)
+
+**Read [exports rules](references/exports.md) for export order.**
+
+### 9. Verify
+
+```bash
+pnpm generate   # Regenerate types if models changed
+pnpm lint       # Check code style
+pnpm typecheck  # Verify TypeScript types
+pnpm test       # Run all tests
+```
+
+## References
+
+- [Module structure](../erp-kit-module-shared/references/structure.md)
+- [Model patterns](references/models.md)
+- [Database relations](references/db-relations.md)
+- [Command patterns](../erp-kit-module-shared/references/commands.md)
+- [Query patterns](../erp-kit-module-shared/references/queries.md)
+- [Generated code](references/generated-code.md)
+- [Testing patterns](../erp-kit-module-shared/references/testing.md)
+- [Export order](references/exports.md)

package/skills/erp-kit-module-4-tdd/references/cross-module-dependency.md

@@ -0,0 +1,133 @@
+# Cross-Module Dependency
+
+## Overview
+
+Each module's `defineModule()` returns `{ db, commands, queries }`. Other modules can reference any of these through the return type. Use `import type` and relative paths — all modules live in the same package.
+
+```typescript
+import type { defineModule as definePrimitivesModule } from "../primitives";
+
+type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
+type PrimitivesDB = PrimitivesModule["db"];
+type PrimitivesCommands = PrimitivesModule["commands"];
+type PrimitivesQueries = PrimitivesModule["queries"];
+```
+
+## DB Type Injection (`db/*.ts`)
+
+Inject another module's DB type to create a foreign-key relation:
+
+- Accept external type via `CreateTypeParams` as required param (e.g., `unitType: TailorAnyDBType`)
+- Use it directly in `.relation()`:
+  - `db.uuid().relation({ type: "n-1", toward: { type: param }, backward: "..." })`
+- Define stub types for cross-module dependencies in `lib/_db_deps.ts` (codegen only — replaced at runtime by `defineModule()` params):
+  ```typescript
+  // lib/_db_deps.ts
+  import {
+    db,
+    unsafeAllowAllGqlPermission,
+    unsafeAllowAllTypePermission,
+  } from "@tailor-platform/sdk";
+  export const unit = db
+    .type("Unit", {})
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+  ```
+- Import the stub and export a default instance at file bottom:
+  ```typescript
+  // db/item.ts
+  import { unit as unitStub } from "../lib/_db_deps";
+  export const item = createItemType({ unitType: unitStub });
+  ```
+- Add `lib/_db_deps.ts` to `tailor.config.ts` files so codegen can resolve the type:
+  ```typescript
+  db: { "main-db": { files: [`./db/*.ts`, `./lib/_db_deps.ts`] } }
+  ```
+
+## Command References
+
+A module can accept another module's commands as a dependency and call them internally:
+
+- Accept commands via `DefineModuleParams` as dependencies
+- Derive the type from the source module's return type
+
+```typescript
+// Types
+type ConvertQuantity = PrimitivesCommands["convertQuantity"];
+
+// DefineModuleParams
+export interface DefineModuleParams {
+  primitives: {
+    commands: {
+      convertQuantity: ConvertQuantity;
+    };
+  };
+}
+
+// Usage in a command
+const convertQuantity = params.primitives.commands.convertQuantity;
+const result = await convertQuantity(db, input, ctx);
+```
+
+## Query References
+
+Same pattern as commands — accept queries via `DefineModuleParams`. See [CQRS read rule](../../erp-kit-module-shared/references/commands.md#command-side-reads-cqrs-separation) for when commands use injected queries vs inline reads.
+
+```typescript
+type ConvertAmount = PrimitivesQueries["convertAmount"];
+
+export interface DefineModuleParams {
+  primitives: {
+    queries: {
+      convertAmount: ConvertAmount;
+    };
+  };
+}
+```
+
+## Module Wiring (`module.ts`)
+
+Group all external dependencies (db, commands, queries) under a named key in `DefineModuleParams`:
+
+```typescript
+export interface DefineModuleParams<IF extends Record<string, TailorAnyDBField>> {
+  item?: CreateItemTypeParams<IF>;
+  primitives: {
+    db: { unit: PrimitivesDB["unit"] };
+    commands: { convertQuantity: PrimitivesCommands["convertQuantity"] };
+    queries: { convertAmount: PrimitivesQueries["convertAmount"] };
+  };
+}
+
+export const defineModule = <const IF extends Record<string, TailorAnyDBField> = EmptyFields>(
+  params: DefineModuleParams<IF>,
+) => {
+  const item = createItemType({
+    ...params.item,
+    unitType: params.primitives.db.unit,
+  });
+
+  return {
+    db: { item },
+    commands: {
+      createItem: makeCreateItem({
+        convertQuantity: params.primitives.commands.convertQuantity,
+      }),
+    },
+  };
+};
+```
+
+## Permission Dependencies
+
+Declare cross-module permission dependencies via `definePermissions`:
+
+```typescript
+export const { permissions, own, all } = definePermissions(
+  "itemManagement",
+  ["createItem", "updateItem", ...] as const,
+  { deps: primitivesPermissions.all },
+);
+```
+
+The `all` export merges own permissions with dependency permissions, so consumers get a complete permission set.

package/skills/{4-module-tdd-implementation → erp-kit-module-4-tdd}/references/db-relations.md

@@ -14,7 +14,7 @@ userId: db.uuid().relation({
 
 ### Parameters
 
-- `type`: `"n-1"` (many-to-one), `"1-1"` (one-to-one), or `"keyOnly"` (FK only, no navigation)
+- `type`: `"n-1"` (many-to-one), `"1-1"` (one-to-one), or `"keyOnly"` (FK only, no navigation),`"self"` ( self-reference )
 - `toward.type`: The related type definition (import it)
 - `backward`: Field name for reverse navigation from the related type
 
@@ -25,6 +25,10 @@ userId: db.uuid().relation({
 - Backward navigation: `User.userRoles`
 - GraphQL relational queries
 
+## Cross-Module Foreign Keys
+
+When a FK references a type from another module, use the DB type injection pattern from [cross-module-dependency.md](cross-module-dependency.md#db-type-injection-srcdbts):
+
 ## Junction Tables (Many-to-Many)
 
 Junction tables need relations on both foreign keys plus a composite unique index:

package/skills/{4-module-tdd-implementation → erp-kit-module-4-tdd}/references/exports.md

@@ -4,5 +4,5 @@ Export order:
 
 1. `defineModule` from module.ts
 2. Generated types (enum values + types separately)
-3. Error classes (for typed catch blocks)
+3. Error classes from `lib/errors.generated` (for typed catch blocks)
 4. Domain functions with input types

package/skills/erp-kit-module-4-tdd/references/generated-code.md

@@ -0,0 +1,32 @@
+# Generated Code
+
+## Overview
+
+Run `erp-kit module generate code --root <modules-dir> <module-name>` to generate deterministic `.generated.ts` files from command and query documentation.
+
+## What gets generated
+
+- `lib/errors.generated.ts` — Domain error classes from Error Scenarios sections
+- `lib/permissions.generated.ts` — Permission definitions from command doc filenames
+- `command/<name>.generated.ts` — Command shells wiring permissions + `run` function
+- `query/<name>.generated.ts` — Query shells wrapping `run` function
+
+## File convention
+
+- `.generated.ts` files are always overwritten — never edit them
+- Custom logic goes in `.ts` files (same base name) that import from `.generated.ts`
+
+## Workflow
+
+1. Write command/query docs (skills 1-3)
+2. Write db models (skill 4, step 2)
+3. Run `pnpm generate` for kysely types
+4. Run `erp-kit module generate code --root <root> <module>`
+5. Implement business logic in `.ts` files importing from `.generated.ts`
+
+## What you still write by hand
+
+- Input interface field definitions (in `.generated.ts` they're stubs)
+- Command handler business logic (validation, mutations, state transitions)
+- Test assertions
+- Complex queries beyond simple lookups

package/skills/{5-module-implementation-review → erp-kit-module-5-impl-review}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 5-module-implementation-review
+name: erp-kit-module-5-impl-review
 description: Review implementation parity between documentation and code. Use when validating that TDD implementation (step 4) matches model docs, command docs, and test coverage requirements.
 ---
 
@@ -12,19 +12,19 @@ Review **implementation consistency** between documentation and actual code.
 Verify that TDD implementation (models, commands, tests) properly implements what's documented in model docs and command docs.
 
 ```
-Model Docs (Schema)     →  src/db/*.ts (Implementation)
+Model Docs (Schema)     →db/*.ts (Implementation)
      ↓                           ↓
   Fields                    createEntityType()
   Relationships             Foreign keys
   State Transitions         Status enums
 
-Command Docs (Spec)     →  src/command/*.ts (Implementation)
+Command Docs (Spec)     →command/*.ts (Implementation)
      ↓                           ↓
   Business Rules            Validation logic
   Error Scenarios           Error classes
   Process Flows             Branching logic
 
-Command Docs (Spec)     →  src/command/*.test.ts (Tests)
+Command Docs (Spec)     →command/*.test.ts (Tests)
      ↓                           ↓
   Process Flow branches     Test cases
   Error scenarios           Error assertions
@@ -66,7 +66,7 @@ Extract for each model:
 Read ALL model files:
 
 ```
-modules/<module-name>/src/db/*.ts
+modules/<module-name>/db/*.ts
 ```
 
 Extract for each model:
@@ -96,28 +96,28 @@ Extract for each command:
 Read ALL command files:
 
 ```
-modules/<module-name>/src/command/*.ts
+modules/<module-name>/command/*.ts
 ```
 
 Extract for each command:
 
 - Validation logic implemented
-- Error classes thrown
+- Error classes returned via Result
 - Branching paths (if/else, early returns)
 - Input interface fields
 - Return type structure
 
 ### 5. Read Error Implementation
 
-Read error definitions:
+Read generated error definitions:
 
 ```
-modules/<module-name>/src/lib/errors.ts
+modules/<module-name>/lib/errors.generated.ts
 ```
 
 Extract:
 
-- Error class names
+- Error class names (generated from doc error codes)
 - Error codes
 - Error message patterns
 
@@ -126,7 +126,7 @@ Extract:
 Read ALL test files:
 
 ```
-modules/<module-name>/src/command/*.test.ts
+modules/<module-name>/command/*.test.ts
 ```
 
 Extract for each command:
@@ -149,15 +149,15 @@ Extract for each command:
 
 ### 8. Command Doc → Command Code Parity Check
 
-| Check Item              | Question                                                   |
-| ----------------------- | ---------------------------------------------------------- |
-| Business rule impl      | Is each documented business rule implemented in code?      |
-| Error scenario coverage | Does code throw errors for all documented error scenarios? |
-| Error code accuracy     | Do error codes in code match documented codes?             |
-| Process flow alignment  | Do code branches match documented process flow?            |
-| Input type coverage     | Does input interface include all documented inputs?        |
-| Return type accuracy    | Does return type match documented output?                  |
-| Dual function pattern   | Does command follow `_fn` internal / `fn` public pattern?  |
+| Check Item              | Question                                                    |
+| ----------------------- | ----------------------------------------------------------- |
+| Business rule impl      | Is each documented business rule implemented in code?       |
+| Error scenario coverage | Does code return errors for all documented error scenarios? |
+| Error code accuracy     | Do error codes in code match documented codes?              |
+| Process flow alignment  | Do code branches match documented process flow?             |
+| Input type coverage     | Does input interface include all documented inputs?         |
+| Return type accuracy    | Does return type match documented output?                   |
+| Generated shell pattern | Does command export `run` with a `.generated.ts` shell?     |
 
 ### 9. Command Doc → Test Coverage Check
 
@@ -206,11 +206,11 @@ Extract for each command:
 
 ### 4. Error Scenario Implementation
 
-| Command Doc | Error Code       | Implemented in errors.ts | Thrown in command | Test assertion |
-| ----------- | ---------------- | ------------------------ | ----------------- | -------------- |
-| <cmd-a>     | ENTITY_NOT_FOUND | ✅ EntityNotFoundError   | ✅                | ✅             |
-| <cmd-a>     | INVALID_STATE    | ❌ Not defined           | ❌                | ❌             |
-| <cmd-b>     | DUPLICATE_ENTRY  | ✅ DuplicateEntryError   | ✅                | ❌ No test     |
+| Command Doc | Error Code       | Generated in errors.generated.ts | Returned in command | Test assertion |
+| ----------- | ---------------- | -------------------------------- | ------------------- | -------------- |
+| <cmd-a>     | ENTITY_NOT_FOUND | ✅ EntityNotFoundError           | ✅                  | ✅             |
+| <cmd-a>     | INVALID_STATE    | ❌ Not defined                   | ❌                  | ❌             |
+| <cmd-b>     | DUPLICATE_ENTRY  | ✅ DuplicateEntryError           | ✅                  | ❌ No test     |
 
 ---
 
@@ -225,10 +225,10 @@ Extract for each command:
 
 ### 6. Implementation Pattern Compliance
 
-| Command | Dual Function Pattern | Input Interface Exported | JSDoc Present |
-| ------- | --------------------- | ------------------------ | ------------- |
-| <cmd-a> | ✅ `_cmdA` + `cmdA`   | ✅                       | ✅            |
-| <cmd-b> | ❌ Only `cmdB`        | ✅                       | ❌            |
+| Command | Generated Shell           | Input Interface Exported | JSDoc Present |
+| ------- | ------------------------- | ------------------------ | ------------- |
+| <cmd-a> | ✅ `.generated.ts` exists | ✅                       | ✅            |
+| <cmd-b> | ❌ Missing shell          | ✅                       | ❌            |
 
 ---
 
@@ -258,7 +258,7 @@ Extract for each command:
 | Command Doc | Missing Test Case                | Doc Reference         |
 | ----------- | -------------------------------- | --------------------- |
 | <cmd-b>     | "entity already exists → return" | Process flow branch 2 |
-| <cmd-b>     | "throws DUPLICATE_ENTRY"         | Error scenario 3      |
+| <cmd-b>     | "returns DUPLICATE_ENTRY"        | Error scenario 3      |
 
 ---
 
@@ -278,9 +278,9 @@ Extract for each command:
 | ----------------------------- | ------ | --------------------------------- |
 | Model Doc → Code Coverage     | ⚠️     | X/Y models fully implemented      |
 | Command Doc → Code Coverage   | ⚠️     | X/Y commands fully implemented    |
-| Error Scenario Implementation | ❌     | X/Y errors defined and thrown     |
+| Error Scenario Implementation | ❌     | X/Y errors defined and returned   |
 | Test Coverage                 | ⚠️     | X/Y process branches have tests   |
-| Pattern Compliance            | ✅     | All commands follow dual function |
+| Pattern Compliance            | ✅     | All commands use generated shells |
 
 ### 10. Recommendations
 
@@ -294,7 +294,7 @@ Extract for each command:
    - cmd-b: add validation for "X must be unique"
 
 4. **Define missing error classes:**
-   - Add `InvalidStateError` in errors.ts
+   - Add `INVALID_STATE` error scenario to command doc + re-run `erp-kit module generate code`
 
 5. **Add missing test cases:**
    - cmd-b: test "entity already exists → return existing"
@@ -317,10 +317,10 @@ Extract for each command:
 ### Command Doc → Command Code
 
 - **Unimplemented business rules**: Rule in doc but no validation code
-- **Missing error throws**: Error scenario documented but not thrown
+- **Missing error returns**: Error scenario documented but not returned
 - **Wrong error codes**: Code and doc use different error codes
 - **Missing process branches**: Flowchart branch not in code logic
-- **Missing dual function**: Only public function, no internal `_fn`
+- **Missing generated shell**: No `.generated.ts` file for command
 
 ### Command Doc → Tests
 
@@ -360,9 +360,9 @@ PENDING → ACTIVE → REMOVED
 ## Error Scenarios
 
 | Code           | Condition      |
-| -------------- | -------------- | ----------------------------------- |
-| NOT_FOUND      | Entity missing | → Check: error class + throw + test |
-| INVALID_STATUS | Wrong status   | → Check: error class + throw + test |
+| -------------- | -------------- | ------------------------------------------ |
+| NOT_FOUND      | Entity missing | → Check: error class + return err() + test |
+| INVALID_STATUS | Wrong status   | → Check: error class + return err() + test |
 
 ## Process Flow (mermaid)
 
@@ -384,25 +384,27 @@ export function createEntityType(params) {
   };
 }
 
-// Command: check business rules
-export async function _myCommand(db, input) {
+// Command: check business rules (run function pattern)
+export async function run(db, input, ctx) {
   // Check: validation for each business rule
-  if (!entity) throw new EntityNotFoundError(); // Check: matches doc error
+  if (!entity) return err(new EntityNotFoundError()); // Check: matches doc error
   // Check: each branch matches process flow
 }
 
+// Generated shell: check it exists
+// myCommand.generated.ts
+export const myCommand = defineCommand(permissions.myCommand, run);
+
 // Test: check coverage
 describe("myCommand", () => {
   it("creates entity when valid"); // Check: happy path
   it("returns existing if found"); // Check: idempotent path
-  it("throws NOT_FOUND when missing"); // Check: error scenario
+  it("returns 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/erp-kit-module-5-impl-review/references/commands.md

@@ -0,0 +1,62 @@
+# Command Implementation
+
+## Unified Pattern: `run` + generated shell
+
+All commands follow the same pattern — export a `run` function, and the generated shell wraps it with `defineCommand`:
+
+**Implementation file** (`command/myCommand.ts`):
+
+```typescript
+export async function run(db: DB, input: MyCommandInput, ctx: CommandContext) {
+  // validate → query → mutate
+  return ok({ entity });
+}
+```
+
+**Generated shell** (`command/myCommand.generated.ts`):
+
+```typescript
+export const myCommand = defineCommand(permissions.myCommand, run);
+```
+
+## Custom Fields (generic CF)
+
+Commands that **write** (insert or update) into a table with user-extensible fields make `run` generic:
+
+- Generic `CF extends Record<string, unknown>` on the `run` function
+- Input type: `CreateXInput & CF` or `UpdateXInput & Partial<CF>`
+- Destructure known fields, rest-spread custom fields
+- Cast custom fields: `...(customFields as Record<string, unknown>)`
+- module.ts locks CF via instantiation expression: `const createXTyped = createX<FieldsToInsertable<F>>;`
+
+### Rule: when to use generic CF
+
+> If a model uses `fields?: F` for custom fields, **every command that writes those fields** must have a generic `CF`. This includes create, update, and any other write command. The determining factor is whether the command writes to a table with custom fields, not just whether it inserts new rows.
+
+## 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)) {
+  return err(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/erp-kit-module-5-impl-review/references/errors.md

@@ -0,0 +1,10 @@
+# Error Classes
+
+Errors are **generated** from command/query documentation into `lib/errors.generated.ts`.
+
+## What to review
+
+- Every error code in `docs/commands/*.md` has a corresponding class in `lib/errors.generated.ts`
+- Command implementations import errors from `../lib/errors.generated`
+- Error codes in code match documented codes exactly
+- If errors are missing, re-run `erp-kit module generate code`

package/skills/{5-module-implementation-review → erp-kit-module-5-impl-review}/references/testing.md

@@ -20,7 +20,7 @@ spies.select.mockReturnValue(entity);
 spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
 ```
 
-## Fixtures (`src/testing/fixtures.ts`)
+## Fixtures (`testing/fixtures.ts`)
 
 - Import `Schema` from `lib/types` (not `Namespace` from generated code)
 - Pattern: `export const baseEntity = { ... } as const satisfies Entity<Schema>`

package/skills/erp-kit-module-shared/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: erp-kit-module-shared
+description: Shared references for erp-kit module skills. Not invoked directly — referenced by erp-kit-module-1 through erp-kit-module-5.
+---
+
+# erp-kit-module-shared
+
+Canonical reference files shared across module skills. Individual skills reference these instead of maintaining their own copies.
+
+## References
+
+- [Module structure](references/structure.md)
+- [Command patterns](references/commands.md)
+- [Query patterns](references/queries.md)
+- [Error patterns](references/errors.md)
+- [Testing patterns](references/testing.md)