@tailor-platform/erp-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,74 @@
+---
+name: 4-module-tdd-implementation
+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
+- Adding database models with `@tailor-platform/sdk`
+- Creating tests with `@tailor-platform/erp-kit` testing utilities
+- Implementing business logic (CRUD, state transitions, relationships)
+
+## Workflow
+
+```
+MODELS → ERRORS → FIXTURES → TESTS → IMPLEMENT → EXPORT → VERIFY
+```
+
+## Step-by-Step
+
+### 1. Database Models (`src/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.
+
+### 2. Error Classes (`src/lib/errors.ts`)
+
+**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`)
+
+**Read [testing rules](references/testing.md) before writing fixtures or tests.**
+
+### 4. Write Tests First (`src/command/*.test.ts`)
+
+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`)
+
+**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`)
+
+**Read [exports rules](references/exports.md) for export order.**
+
+### 7. 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](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/skills/4-module-tdd-implementation/references/db-relations.md

@@ -0,0 +1,69 @@
+# Database Relations
+
+## Relation Pattern
+
+Use `.relation()` for foreign keys instead of plain `db.uuid()`:
+
+```typescript
+userId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user },
+  backward: "userRoles",
+}).description("Foreign key to User"),
+```
+
+### Parameters
+
+- `type`: `"n-1"` (many-to-one), `"1-1"` (one-to-one), or `"keyOnly"` (FK only, no navigation)
+- `toward.type`: The related type definition (import it)
+- `backward`: Field name for reverse navigation from the related type
+
+### Benefits over plain `db.uuid()`
+
+- Foreign key constraints (referential integrity)
+- Forward navigation: `UserRole.user`
+- Backward navigation: `User.userRoles`
+- GraphQL relational queries
+
+## Junction Tables (Many-to-Many)
+
+Junction tables need relations on both foreign keys plus a composite unique index:
+
+```typescript
+import { user } from "./user";
+import { role } from "./role";
+
+db.type("UserRole", {
+  userId: db.uuid().relation({
+    type: "n-1",
+    toward: { type: user },
+    backward: "userRoles",
+  }),
+  roleId: db.uuid().relation({
+    type: "n-1",
+    toward: { type: role },
+    backward: "userRoles",
+  }),
+}).indexes({
+  fields: ["userId", "roleId"],
+  unique: true,
+  name: "user_role_unique_idx",
+});
+```
+
+### Naming Conventions
+
+- `backward` field: Use plural of the junction table name (e.g., `"userRoles"`, `"rolePermissions"`)
+- Index name: `{table}_unique_idx` pattern
+
+## Composite Indexes
+
+Use `.indexes()` (not `.uniqueIndex()`) for multi-column constraints:
+
+```typescript
+.indexes({
+  fields: ["fieldA", "fieldB"],
+  unique: true,
+  name: "descriptive_idx_name",
+})
+```

package/skills/4-module-tdd-implementation/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/4-module-tdd-implementation/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/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