@tailor-platform/erp-kit 0.2.1 → 0.3.0

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/commands/scaffold.test.ts

@@ -1,171 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import {
-  type Diagnostic,
-  DiagnosticCategory,
-  flattenDiagnosticMessageText,
-  ModuleKind,
-  ScriptTarget,
-  transpileModule,
-} from "typescript";
-import { describe, it, expect, afterEach } from "vitest";
-import { resolveScaffoldPath, scaffoldModuleSrc } from "./scaffold";
-import { getModuleSrcTemplates } from "./scaffold-templates";
-
-describe("resolveScaffoldPath", () => {
-  // Module types
-  it("resolves module scaffold path", () => {
-    const result = resolveScaffoldPath("module", "inventory", undefined, "modules");
-    expect(result).toBe("modules/inventory/README.md");
-  });
-
-  it("resolves command scaffold path", () => {
-    const result = resolveScaffoldPath("command", "inventory", "CreateOrder", "modules");
-    expect(result).toBe("modules/inventory/docs/commands/CreateOrder.md");
-  });
-
-  it("resolves feature scaffold path", () => {
-    const result = resolveScaffoldPath("feature", "inventory", "stock-tracking", "modules");
-    expect(result).toBe("modules/inventory/docs/features/stock-tracking.md");
-  });
-
-  it("resolves model scaffold path", () => {
-    const result = resolveScaffoldPath("model", "inventory", "StockItem", "modules");
-    expect(result).toBe("modules/inventory/docs/models/StockItem.md");
-  });
-
-  // App-compose types
-  it("resolves requirements scaffold path", () => {
-    const result = resolveScaffoldPath("requirements", "my-app", undefined, "examples");
-    expect(result).toBe("examples/my-app/README.md");
-  });
-
-  it("resolves actors scaffold path", () => {
-    const result = resolveScaffoldPath("actors", "my-app", "admin", "examples");
-    expect(result).toBe("examples/my-app/docs/actors/admin.md");
-  });
-
-  it("resolves business-flow scaffold path", () => {
-    const result = resolveScaffoldPath("business-flow", "my-app", "onboarding", "examples");
-    expect(result).toBe("examples/my-app/docs/business-flow/onboarding/README.md");
-  });
-
-  it("resolves story scaffold path with flow/name format", () => {
-    const result = resolveScaffoldPath(
-      "story",
-      "my-app",
-      "onboarding/admin--create-user",
-      "examples",
-    );
-    expect(result).toBe(
-      "examples/my-app/docs/business-flow/onboarding/story/admin--create-user.md",
-    );
-  });
-
-  it("resolves screen scaffold path", () => {
-    const result = resolveScaffoldPath("screen", "my-app", "supplier-list", "examples");
-    expect(result).toBe("examples/my-app/docs/screen/supplier-list.md");
-  });
-
-  it("resolves resolver scaffold path", () => {
-    const result = resolveScaffoldPath("resolver", "my-app", "create-supplier", "examples");
-    expect(result).toBe("examples/my-app/docs/resolver/create-supplier.md");
-  });
-
-  it("resolves query scaffold path", () => {
-    const result = resolveScaffoldPath("query", "inventory", "ConvertQuantity", "modules");
-    expect(result).toBe("modules/inventory/docs/queries/ConvertQuantity.md");
-  });
-
-  // Validation
-  it("throws when name is required but missing", () => {
-    expect(() => resolveScaffoldPath("command", "inventory", undefined, "modules")).toThrow(
-      "Name is required",
-    );
-  });
-
-  it("throws when story name is not flow/name format", () => {
-    expect(() => resolveScaffoldPath("story", "my-app", "bad-name", "examples")).toThrow(
-      "Story name must be",
-    );
-  });
-});
-
-describe("scaffoldModuleSrc", () => {
-  let tmpDir: string;
-
-  afterEach(() => {
-    if (tmpDir) {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-    }
-  });
-
-  it("creates expected directories and files", () => {
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "scaffold-test-"));
-    const moduleDir = path.join(tmpDir, "test-module");
-    fs.mkdirSync(moduleDir, { recursive: true });
-
-    scaffoldModuleSrc(moduleDir, "test-module");
-
-    // Verify directories exist directly under module root (flat structure)
-    for (const dir of ["db", "command", "executor", "generated", "lib", "query", "testing"]) {
-      expect(fs.existsSync(path.join(moduleDir, dir))).toBe(true);
-    }
-
-    // Verify .gitkeep in empty directories
-    for (const dir of ["db", "command", "executor", "generated", "query"]) {
-      expect(fs.existsSync(path.join(moduleDir, dir, ".gitkeep"))).toBe(true);
-    }
-
-    // Verify starter files exist
-    const expectedFiles = [
-      "module.ts",
-      "index.ts",
-      "permissions.ts",
-      "tailor.config.ts",
-      "lib/errors.ts",
-      "lib/types.ts",
-      "testing/fixtures.ts",
-    ];
-    for (const file of expectedFiles) {
-      expect(fs.existsSync(path.join(moduleDir, file))).toBe(true);
-    }
-
-    // Verify module name is used in content
-    const permissions = fs.readFileSync(path.join(moduleDir, "permissions.ts"), "utf-8");
-    expect(permissions).toContain('definePermissions("test-module"');
-
-    const config = fs.readFileSync(path.join(moduleDir, "tailor.config.ts"), "utf-8");
-    expect(config).toContain('name: "test-module"');
-
-    const moduleFile = fs.readFileSync(path.join(moduleDir, "module.ts"), "utf-8");
-    expect(moduleFile).toContain("defineModule");
-    expect(moduleFile).toContain("commands");
-    expect(moduleFile).toContain("queries");
-  });
-
-  it("generates syntactically valid TypeScript for all file templates", () => {
-    const templates = getModuleSrcTemplates();
-    const fileTemplates = templates.filter((t) => t.type === "file");
-
-    for (const entry of fileTemplates) {
-      const source = entry.content("test-module");
-      const result = transpileModule(source, {
-        reportDiagnostics: true,
-        compilerOptions: { target: ScriptTarget.ESNext, module: ModuleKind.ESNext },
-      });
-      const errors = (result.diagnostics ?? []).filter(
-        (d) => d.category === DiagnosticCategory.Error,
-      );
-      expect(
-        errors,
-        `syntax errors in template "${entry.path}": ${formatDiagnostics(errors)}`,
-      ).toHaveLength(0);
-    }
-  });
-});
-
-function formatDiagnostics(diagnostics: Diagnostic[]): string {
-  return diagnostics.map((d) => flattenDiagnosticMessageText(d.messageText, "\n")).join("; ");
-}