@tailor-platform/erp-kit 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @tailor-platform/erp-kit
+
+## 0.1.1
+
+### Patch Changes
+
+- 2f43392: Add MIT LICENSE and include CHANGELOG.md in published package

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 Tailor Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/cli.js

@@ -343,7 +343,6 @@ import fs3 from "fs";
 import path6 from "path";
 import chalk2 from "chalk";
 var SKILLS_SRC = path6.join(PACKAGE_ROOT, "skills");
-var RULES_SRC = path6.join(PACKAGE_ROOT, "rules");
 var FRAMEWORK_SKILLS = [
   "1-module-docs",
   "2-module-feature-breakdown",
@@ -358,61 +357,82 @@ var FRAMEWORK_SKILLS = [
   "app-compose-6-implementation-spec",
   "mock-scenario"
 ];
+function copyDirectoryRecursive(srcDir, destDir, force) {
+  let copied = 0;
+  let skipped = 0;
+  for (const entry of fs3.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path6.join(srcDir, entry.name);
+    const destPath = path6.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = copyDirectoryRecursive(srcPath, destPath, force);
+      copied += sub.copied;
+      skipped += sub.skipped;
+    } else {
+      if (!force && fs3.existsSync(destPath)) {
+        skipped++;
+        continue;
+      }
+      fs3.mkdirSync(destDir, { recursive: true });
+      fs3.copyFileSync(srcPath, destPath);
+      copied++;
+    }
+  }
+  return { copied, skipped };
+}
 function runInit(cwd2, force) {
   console.log(chalk2.bold("erp-kit init\n"));
   const skillsDest = path6.join(cwd2, ".agents", "skills");
   let copiedCount = 0;
   let skippedCount = 0;
   for (const skill of FRAMEWORK_SKILLS) {
-    const srcSkill = path6.join(SKILLS_SRC, skill, "SKILL.md");
+    const srcSkillDir = path6.join(SKILLS_SRC, skill);
+    if (!fs3.existsSync(srcSkillDir)) continue;
     const destDir = path6.join(skillsDest, skill);
-    const destSkill = path6.join(destDir, "SKILL.md");
-    if (!fs3.existsSync(srcSkill)) continue;
-    if (!force && fs3.existsSync(destSkill)) {
-      console.log(chalk2.yellow(`  Skipped ${skill}/SKILL.md (already exists)`));
-      skippedCount++;
-      continue;
+    const result = copyDirectoryRecursive(srcSkillDir, destDir, force);
+    copiedCount += result.copied;
+    if (result.skipped > 0) {
+      console.log(chalk2.yellow(`  Skipped ${skill}/ (${result.skipped} existing files)`));
+      skippedCount += result.skipped;
     }
-    fs3.mkdirSync(destDir, { recursive: true });
-    fs3.copyFileSync(srcSkill, destSkill);
-    copiedCount++;
   }
-  console.log(chalk2.green(`  Copied ${copiedCount} framework skills to .agents/skills/`));
+  console.log(chalk2.green(`  Copied ${copiedCount} skill files to .agents/skills/`));
   if (skippedCount > 0) {
     console.log(
-      chalk2.yellow(`  Skipped ${skippedCount} existing skills (use --force to overwrite)`)
+      chalk2.yellow(`  Skipped ${skippedCount} existing files (use --force to overwrite)`)
     );
   }
-  const rulesDest = path6.join(cwd2, ".agents", "rules");
-  let rulesCount = 0;
-  let rulesSkipped = 0;
-  if (fs3.existsSync(RULES_SRC)) {
-    const copyRulesRecursive = (srcDir, destDir) => {
-      for (const entry of fs3.readdirSync(srcDir, { withFileTypes: true })) {
-        const srcPath = path6.join(srcDir, entry.name);
-        const destPath = path6.join(destDir, entry.name);
-        if (entry.isDirectory()) {
-          copyRulesRecursive(srcPath, destPath);
-        } else {
-          if (!force && fs3.existsSync(destPath)) {
-            const rel = path6.relative(rulesDest, destPath);
-            console.log(chalk2.yellow(`  Skipped rule ${rel} (already exists)`));
-            rulesSkipped++;
-            continue;
-          }
-          fs3.mkdirSync(destDir, { recursive: true });
-          fs3.copyFileSync(srcPath, destPath);
-          rulesCount++;
-        }
+  const claudeSkills = path6.join(cwd2, ".claude", "skills");
+  const relTarget = path6.relative(path6.dirname(claudeSkills), skillsDest);
+  const claudeSkillsExists = (() => {
+    try {
+      fs3.lstatSync(claudeSkills);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  if (claudeSkillsExists) {
+    const stat2 = fs3.lstatSync(claudeSkills);
+    if (stat2.isSymbolicLink()) {
+      const current = fs3.readlinkSync(claudeSkills);
+      if (current === relTarget) {
+        console.log(chalk2.green("  .claude/skills -> .agents/skills/ (already linked)"));
+      } else if (force) {
+        fs3.unlinkSync(claudeSkills);
+        fs3.symlinkSync(relTarget, claudeSkills);
+        console.log(chalk2.green("  .claude/skills -> .agents/skills/ (relinked)"));
+      } else {
+        console.log(
+          chalk2.yellow(`  Skipped .claude/skills (symlink exists -> ${current}, use --force)`)
+        );
       }
-    };
-    copyRulesRecursive(RULES_SRC, rulesDest);
-  }
-  console.log(chalk2.green(`  Copied ${rulesCount} framework rules to .agents/rules/`));
-  if (rulesSkipped > 0) {
-    console.log(
-      chalk2.yellow(`  Skipped ${rulesSkipped} existing rules (use --force to overwrite)`)
-    );
+    } else {
+      console.log(chalk2.yellow("  Skipped .claude/skills (directory exists, not a symlink)"));
+    }
+  } else {
+    fs3.mkdirSync(path6.dirname(claudeSkills), { recursive: true });
+    fs3.symlinkSync(relTarget, claudeSkills);
+    console.log(chalk2.green("  .claude/skills -> .agents/skills/ (linked)"));
   }
   console.log(chalk2.bold.green("\nDone! Run `erp-kit check` to validate your docs."));
   return 0;
@@ -868,11 +888,11 @@ var scaffoldCommand = defineCommand2({
 });
 var initCommand = defineCommand2({
   name: "init",
-  description: "Set up consumer repo (skills, rules)",
+  description: "Set up consumer repo with framework skills",
   args: z2.object({
     force: arg2(z2.boolean().default(false), {
       alias: "f",
-      description: "Overwrite existing skills and rules"
+      description: "Overwrite existing skills"
     })
   }),
   run: (args) => {

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/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)