@tailor-platform/erp-kit 0.2.1 → 0.2.2

package/skills/erp-kit-module-5-impl-review/SKILL.md

@@ -1,410 +0,0 @@
----
-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.
----
-
-# Implementation Parity Review Workflow
-
-Review **implementation consistency** between documentation and actual code.
-
-## Purpose
-
-Verify that TDD implementation (models, commands, tests) properly implements what's documented in model docs and command docs.
-
-```
-Model Docs (Schema)     →db/*.ts (Implementation)
-     ↓                           ↓
-  Fields                    createEntityType()
-  Relationships             Foreign keys
-  State Transitions         Status enums
-
-Command Docs (Spec)     →command/*.ts (Implementation)
-     ↓                           ↓
-  Business Rules            Validation logic
-  Error Scenarios           Error classes
-  Process Flows             Branching logic
-
-Command Docs (Spec)     →command/*.test.ts (Tests)
-     ↓                           ↓
-  Process Flow branches     Test cases
-  Error scenarios           Error assertions
-  Idempotent paths          Return existing tests
-```
-
-## When to Use
-
-- After TDD implementation (step 4), verify it matches documentation
-- Before merging feature branches
-- Quality check during code review
-
-## Workflow
-
-```
-MODEL DOCS → MODEL CODE → COMMAND DOCS → COMMAND CODE → TESTS → COMPARE → REPORT
-```
-
-## Step-by-Step
-
-### 1. Read Model Documentation
-
-Read ALL model docs:
-
-```
-modules/<module-name>/docs/models/*.md
-```
-
-Extract for each model:
-
-- Field names and types
-- Required vs optional fields
-- Relationships (foreign keys)
-- State transitions (if stateful)
-- Constraints
-
-### 2. Read Model Implementation
-
-Read ALL model files:
-
-```
-modules/<module-name>/db/*.ts
-```
-
-Extract for each model:
-
-- Fields in `createEntityType()`
-- Status enums (base + additional)
-- Foreign key references
-- Field descriptions
-
-### 3. Read Command Documentation
-
-Read ALL command docs:
-
-```
-modules/<module-name>/docs/commands/*.md
-```
-
-Extract for each command:
-
-- Business rules
-- Error scenarios (with codes)
-- Process flow branches
-- Input/output types
-
-### 4. Read Command Implementation
-
-Read ALL command files:
-
-```
-modules/<module-name>/command/*.ts
-```
-
-Extract for each command:
-
-- Validation logic implemented
-- Error classes returned via Result
-- Branching paths (if/else, early returns)
-- Input interface fields
-- Return type structure
-
-### 5. Read Error Implementation
-
-Read generated error definitions:
-
-```
-modules/<module-name>/lib/errors.generated.ts
-```
-
-Extract:
-
-- Error class names (generated from doc error codes)
-- Error codes
-- Error message patterns
-
-### 6. Read Test Implementation
-
-Read ALL test files:
-
-```
-modules/<module-name>/command/*.test.ts
-```
-
-Extract for each command:
-
-- Test case descriptions
-- Error assertions
-- Happy path coverage
-- Edge case coverage
-
-### 7. Model Doc → Model Code Parity Check
-
-| Check Item         | Question                                                         |
-| ------------------ | ---------------------------------------------------------------- |
-| Field coverage     | Does code include all fields from model doc?                     |
-| Type accuracy      | Do field types match doc specification?                          |
-| Required fields    | Are required fields enforced (no default, not nullable)?         |
-| Relationship impl  | Are foreign key fields implemented for documented relationships? |
-| State transitions  | Does status enum include all documented states?                  |
-| Field descriptions | Do `.description()` calls match doc field descriptions?          |
-
-### 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 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
-
-| Check Item            | Question                                                   |
-| --------------------- | ---------------------------------------------------------- |
-| Process flow coverage | Does each branch in process flow have a test case?         |
-| Error scenario tests  | Does each documented error scenario have a test assertion? |
-| Happy path tests      | Are success paths tested?                                  |
-| Idempotent path tests | If doc shows "already exists → return", is this tested?    |
-
-### 10. Report Findings
-
-```markdown
-## Implementation Parity Review Report
-
-**Module:** <module-name>
-
----
-
-### 1. Model Doc → Model Code Coverage
-
-| Model Doc | Fields Documented | Fields Implemented | Gap                 |
-| --------- | ----------------- | ------------------ | ------------------- |
-| <Model-A> | N fields          | N fields           | ✅                  |
-| <Model-B> | N fields          | N-1 fields         | ❌ `fieldX` missing |
-
----
-
-### 2. Model State Transitions
-
-| Model     | Documented States        | Implemented States | Gap                |
-| --------- | ------------------------ | ------------------ | ------------------ |
-| <Model-A> | PENDING, ACTIVE, REMOVED | PENDING, ACTIVE    | ❌ REMOVED missing |
-| <Model-B> | ACTIVE, INACTIVE         | ACTIVE, INACTIVE   | ✅                 |
-
----
-
-### 3. Command Doc → Command Code Coverage
-
-| Command Doc | Business Rules | Implemented | Gap                              |
-| ----------- | -------------- | ----------- | -------------------------------- |
-| <cmd-a>     | 3 rules        | 3 rules     | ✅                               |
-| <cmd-b>     | 4 rules        | 3 rules     | ❌ "rule X validation" not found |
-
----
-
-### 4. Error Scenario Implementation
-
-| 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     |
-
----
-
-### 5. Process Flow → Test Coverage
-
-| Command Doc | Process Flow Branches | Test Cases | Gap                              |
-| ----------- | --------------------- | ---------- | -------------------------------- |
-| <cmd-a>     | 3 branches            | 3 tests    | ✅                               |
-| <cmd-b>     | 4 branches            | 2 tests    | ❌ Missing "already exists" test |
-
----
-
-### 6. Implementation Pattern Compliance
-
-| Command | Generated Shell           | Input Interface Exported | JSDoc Present |
-| ------- | ------------------------- | ------------------------ | ------------- |
-| <cmd-a> | ✅ `.generated.ts` exists | ✅                       | ✅            |
-| <cmd-b> | ❌ Missing shell          | ✅                       | ❌            |
-
----
-
-### 7. Missing Implementation
-
-#### Missing in Model Code
-
-| Model Doc | Missing Item | Type   | Doc Reference               |
-| --------- | ------------ | ------ | --------------------------- |
-| <Model-A> | `fieldX`     | Field  | "fieldX: uuid, required"    |
-| <Model-A> | `REMOVED`    | Status | State diagram shows REMOVED |
-
-#### Missing in Command Code
-
-| Command Doc | Missing Item     | Type          | Doc Reference            |
-| ----------- | ---------------- | ------------- | ------------------------ |
-| <cmd-b>     | validation for X | Business rule | "Rule: X must be unique" |
-
-#### Missing Error Classes
-
-| Command Doc | Error Code    | Expected Class    |
-| ----------- | ------------- | ----------------- |
-| <cmd-a>     | INVALID_STATE | InvalidStateError |
-
-#### Missing Tests
-
-| Command Doc | Missing Test Case                | Doc Reference         |
-| ----------- | -------------------------------- | --------------------- |
-| <cmd-b>     | "entity already exists → return" | Process flow branch 2 |
-| <cmd-b>     | "returns DUPLICATE_ENTRY"        | Error scenario 3      |
-
----
-
-### 8. Inconsistencies
-
-| Type                | Location       | Issue                                       |
-| ------------------- | -------------- | ------------------------------------------- |
-| Type mismatch       | Model-A.fieldX | Doc: string, Code: number                   |
-| Error code mismatch | cmd-a          | Doc: USER_NOT_FOUND, Code: ENTITY_NOT_FOUND |
-| Missing description | Model-B.fieldY | No `.description()` but doc has description |
-
----
-
-### 9. Summary
-
-| Aspect                        | Status | Details                           |
-| ----------------------------- | ------ | --------------------------------- |
-| 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 returned   |
-| Test Coverage                 | ⚠️     | X/Y process branches have tests   |
-| Pattern Compliance            | ✅     | All commands use generated shells |
-
-### 10. Recommendations
-
-1. **Add missing model fields:**
-   - Model-A: add `fieldX` field
-
-2. **Add missing status values:**
-   - Model-A: add `REMOVED` to status enum
-
-3. **Implement missing business rules:**
-   - cmd-b: add validation for "X must be unique"
-
-4. **Define missing error classes:**
-   - 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"
-   - cmd-b: test "throws DUPLICATE_ENTRY on duplicate"
-
-6. **Fix inconsistencies:**
-   - Model-A.fieldX: change type to string per doc
-```
-
-## Common Gaps
-
-### Model Doc → Model Code
-
-- **Missing fields**: Doc specifies field but not in code
-- **Type mismatches**: Doc says string, code uses number
-- **Missing status values**: State diagram shows state not in enum
-- **Missing relationships**: Doc shows FK but not implemented
-- **Missing descriptions**: Doc has field description but no `.description()`
-
-### Command Doc → Command Code
-
-- **Unimplemented business rules**: Rule in doc but no validation code
-- **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 generated shell**: No `.generated.ts` file for command
-
-### Command Doc → Tests
-
-- **Uncovered process branches**: Flowchart branch has no test
-- **Missing error tests**: Error scenario has no assertion
-- **Missing idempotent tests**: "Return existing" path untested
-- **Missing edge cases**: Boundary conditions not tested
-
-## Quick Reference: Extraction Patterns
-
-### From Model Docs
-
-```markdown
-## Fields
-
-| Field    | Type   | Required |
-| -------- | ------ | -------- | ---------------------------------------- |
-| id       | uuid   | yes      | → Check: field exists, type matches      |
-| name     | string | yes      | → Check: not nullable                    |
-| status   | enum   | yes      | → Check: enum values match state diagram |
-| parentId | uuid   | yes      | → Check: foreign key implemented         |
-
-## State Diagram
-
-PENDING → ACTIVE → REMOVED
-→ Check: all states in enum
-```
-
-### From Command Docs
-
-```markdown
-## Business Rules
-
-1. Entity must exist → Check: validation in code
-2. Status must be ACTIVE → Check: status check in code
-
-## Error Scenarios
-
-| Code           | Condition      |
-| -------------- | -------------- | ------------------------------------------ |
-| NOT_FOUND      | Entity missing | → Check: error class + return err() + test |
-| INVALID_STATUS | Wrong status   | → Check: error class + return err() + test |
-
-## Process Flow (mermaid)
-
-graph TD
-A[Start] --> B{Exists?}
-B -->|Yes| C[Return] → Check: test for "already exists"
-B -->|No| D[Create] → Check: test for "create new"
-```
-
-### From Implementation
-
-```typescript
-// Model: check fields match doc
-export function createEntityType(params) {
-  return {
-    fields: {
-      /* verify each field */
-    },
-  };
-}
-
-// Command: check business rules (run function pattern)
-export async function run(db, input, ctx) {
-  // Check: validation for each business rule
-  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("returns NOT_FOUND when missing"); // Check: error scenario
-});
-```
-
-## References
-
-- [Command patterns](references/commands.md)
-- [Error patterns](references/errors.md)
-- [Testing patterns](references/testing.md)

package/src/commands/scaffold-templates.ts

@@ -1,65 +0,0 @@
-export type TemplateEntry =
-  | { type: "dir"; path: string }
-  | { type: "file"; path: string; content: (moduleName: string) => string };
-
-export function getModuleSrcTemplates(): TemplateEntry[] {
-  return [
-    { type: "dir", path: "db" },
-    { type: "dir", path: "command" },
-    { type: "dir", path: "executor" },
-    { type: "dir", path: "generated" },
-    { type: "dir", path: "query" },
-    { type: "file", path: "module.ts", content: () => MODULE_TEMPLATE },
-    { type: "file", path: "index.ts", content: () => INDEX_TEMPLATE },
-    { type: "file", path: "permissions.ts", content: (n) => permissionsTemplate(n) },
-    { type: "file", path: "tailor.config.ts", content: (n) => tailorConfigTemplate(n) },
-    { type: "file", path: "lib/errors.ts", content: () => ERRORS_TEMPLATE },
-    { type: "file", path: "lib/types.ts", content: () => TYPES_TEMPLATE },
-    { type: "file", path: "testing/fixtures.ts", content: () => FIXTURES_TEMPLATE },
-  ];
-}
-
-const MODULE_TEMPLATE = `export const defineModule = () => {
-  return {
-    db: {},
-    commands: {},
-    queries: {},
-  };
-};
-`;
-
-const INDEX_TEMPLATE = `export { defineModule } from "./module";
-export { permissions, own, all } from "./permissions";
-`;
-
-const ERRORS_TEMPLATE = `import { createDomainError } from "../../shared/internal";\n`;
-
-const TYPES_TEMPLATE = `import type { InferSchema, Selectable, Insertable, Updateable } from "../../shared/internal";
-import type { DB } from "../generated/kysely-tailordb";
-
-export type Schema = InferSchema<DB>;
-`;
-
-const FIXTURES_TEMPLATE = `// Add test fixtures here\n`;
-
-function permissionsTemplate(moduleName: string): string {
-  return `import { definePermissions } from "../shared/internal";
-
-export const { permissions, own, all } = definePermissions("${moduleName}", [] as const);
-`;
-}
-
-function tailorConfigTemplate(moduleName: string): string {
-  return `import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
-
-export default defineConfig({
-  name: "${moduleName}",
-  db: { "main-db": { files: [\`./db/*.ts\`] } },
-});
-
-export const generators = defineGenerators(
-  ["@tailor-platform/kysely-type", { distPath: \`./generated/kysely-tailordb.ts\` }],
-  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
-);
-`;
-}

package/src/modules/shared/index.ts

@@ -1 +0,0 @@
-export { createContext } from "./createContext";

package/src/modules/user-management/command/logAuditEvent.generated.ts

@@ -1,6 +0,0 @@
-// @generated — do not edit
-import { defineCommand } from "../../shared/internal";
-import { permissions } from "../lib/permissions.generated";
-import { run } from "./logAuditEvent";
-
-export const logAuditEvent = defineCommand(permissions.logAuditEvent, run);

package/src/modules/user-management/command/logAuditEvent.test.ts

@@ -1,187 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { type CommandContext } from "../../shared/internal";
-import { createMockDb } from "../../testing/index";
-import { DB } from "../generated/kysely-tailordb";
-import { InvalidEventTypeError, MissingRequiredFieldError } from "../lib/errors.generated";
-import { baseAuditEvent } from "../testing/fixtures";
-import { run } from "./logAuditEvent";
-
-describe("logAuditEvent", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["user-management:logAuditEvent"],
-  };
-
-  it("throws when actorId is empty", async () => {
-    const { db } = createMockDb<DB>();
-
-    const result = await run(
-      db,
-      {
-        eventType: "USER_CREATED",
-        actorId: "",
-      },
-      ctx,
-    );
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(MissingRequiredFieldError);
-    }
-  });
-
-  it("throws when eventType is invalid", async () => {
-    const { db } = createMockDb<DB>();
-
-    const result = await run(
-      db,
-      {
-        eventType: "INVALID_EVENT" as "USER_CREATED",
-        actorId: "user-1",
-      },
-      ctx,
-    );
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(InvalidEventTypeError);
-    }
-  });
-
-  it("creates audit event with minimal fields", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "USER_CREATED" as const,
-      actorId: "user-1",
-      targetId: null,
-      targetType: null,
-      payload: null,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "USER_CREATED",
-        actorId: "user-1",
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.eventType).toBe("USER_CREATED");
-      expect(result.value.auditEvent.actorId).toBe("user-1");
-    }
-    expect(spies.insert).toHaveBeenCalled();
-  });
-
-  it("creates audit event with target info", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "ROLE_ASSIGNED" as const,
-      actorId: "user-1",
-      targetId: "user-2",
-      targetType: "User",
-      payload: null,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "ROLE_ASSIGNED",
-        actorId: "user-1",
-        targetId: "user-2",
-        targetType: "User",
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.eventType).toBe("ROLE_ASSIGNED");
-      expect(result.value.auditEvent.targetId).toBe("user-2");
-      expect(result.value.auditEvent.targetType).toBe("User");
-    }
-  });
-
-  it("creates audit event with payload", async () => {
-    const { db, spies } = createMockDb<DB>();
-    const payload = JSON.stringify({ roleId: "role-1", userId: "user-2" });
-    const createdEvent = {
-      ...baseAuditEvent,
-      id: "new-event-id",
-      eventType: "ROLE_ASSIGNED" as const,
-      actorId: "user-1",
-      targetId: "user-2",
-      targetType: "User",
-      payload,
-    };
-
-    spies.insert.mockReturnValue(createdEvent);
-
-    const result = await run(
-      db,
-      {
-        eventType: "ROLE_ASSIGNED",
-        actorId: "user-1",
-        targetId: "user-2",
-        targetType: "User",
-        payload,
-      },
-      ctx,
-    );
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.value.auditEvent.payload).toBe(payload);
-    }
-  });
-
-  it("creates audit event for each valid event type", async () => {
-    const eventTypes = [
-      "USER_CREATED",
-      "USER_ACTIVATED",
-      "USER_DEACTIVATED",
-      "USER_REACTIVATED",
-      "ROLE_ASSIGNED",
-      "ROLE_REVOKED",
-      "PERMISSION_ASSIGNED",
-      "PERMISSION_REVOKED",
-    ] as const;
-
-    for (const eventType of eventTypes) {
-      const { db, spies } = createMockDb<DB>();
-      const createdEvent = {
-        ...baseAuditEvent,
-        id: "new-event-id",
-        eventType,
-        actorId: "user-1",
-        targetId: null,
-        targetType: null,
-        payload: null,
-      };
-
-      spies.insert.mockReturnValue(createdEvent);
-
-      const result = await run(
-        db,
-        {
-          eventType,
-          actorId: "user-1",
-        },
-        ctx,
-      );
-
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.value.auditEvent.eventType).toBe(eventType);
-      }
-    }
-  });
-});