@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/skills/erp-kit-module-shared/references/commands.md

@@ -0,0 +1,203 @@
+# 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>)`
+
+```typescript
+export async function run<CF extends Record<string, unknown>>(
+  db: DB,
+  input: CreateXInput & CF,
+  ctx: CommandContext,
+) {
+  const { name, ...customFields } = input;
+  await db
+    .insertInto("X")
+    .values({ ...(customFields as Record<string, unknown>), name })
+    .execute();
+}
+```
+
+### module.ts wiring
+
+Use instantiation expressions to lock `CF` to the module's custom field type:
+
+```typescript
+const createXTyped = createX<FieldsToInsertable<F>>;
+return { commands: { createX: createXTyped } };
+```
+
+### 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.
+
+## Config-Taking Commands
+
+Commands that need external config (cross-module queries, settings) accept config as leading params before `(db, input, ctx)`:
+
+```typescript
+export async function run<CF extends Record<string, unknown>>(
+  primitivesQueries: Pick<PrimitivesQueries, "getUnit">,
+  db: DB, input: CreateItemInput & CF, ctx: CommandContext,
+) { ... }
+```
+
+module.ts wires with `.bind()` after instantiation:
+
+```typescript
+const createItemTyped = createItem<FieldsToInsertable<IF>>;
+return { commands: { createItem: createItemTyped.bind(null, queries) } };
+```
+
+## Command-Side Reads (CQRS Separation)
+
+Following CQRS principles, commands own their reads for same-module data. Cross-module reads use injected query functions to preserve module boundaries.
+
+### Why
+
+- **Query functions** use `ReadonlyDB` — shaped for API consumers, can't `forUpdate()`
+- **Command reads** are shaped for enforcing invariants — need locking, may need different filters or joins
+- **Independence** — query-side changes (pagination, field selection) must not affect command behavior
+- **Module composition** — modules nest at multiple depths; parent modules inject child queries to maintain explicit dependency contracts
+
+### Rule
+
+> **Same-module reads**: Commands inline their own `selectFrom()` calls using `db` (full `DB`). Never import or call query functions from `query/` within the same module — the command owns its reads and can apply locking.
+>
+> **Cross-module reads**: Commands receive query functions from other modules via dependency injection (leading params). This keeps module boundaries explicit and supports nested module composition.
+>
+> **Status preconditions**: Commands enforce status checks inline (e.g., "only DRAFT items can be deleted", "only ACTIVE users can be assigned roles"). Status filtering belongs to the command's invariant logic, not to query-side defaults. See [Status-Aware Query Rules](queries.md#status-aware-query-rules) for the read-side conventions.
+
+### Examples
+
+**Correct** — same-module read inlined with locking:
+
+```typescript
+// command/deactivateUnit.ts
+const unit = await db
+  .selectFrom("Unit")
+  .selectAll()
+  .where("id", "=", input.unitId)
+  .forUpdate()
+  .executeTakeFirst();
+if (!unit) return err(new UnitNotFoundError(input.unitId));
+```
+
+**Correct** — cross-module read via injected query:
+
+```typescript
+// command/createItem.ts (item-management validating a primitives entity)
+export async function run<CF extends Record<string, unknown>>(
+  primitivesQueries: Pick<PrimitivesQueries, "getUnit">,
+  db: DB,
+  input: CreateItemInput & CF,
+  ctx: CommandContext,
+) {
+  const { unit } = await primitivesQueries.getUnit(db, { id: input.unitId }, ctx);
+  if (!unit?.isActive) return err(new UnitNotFoundError(input.unitId));
+  // ...
+}
+```
+
+**Wrong** — calling same-module query function:
+
+```typescript
+// command/deactivateUnit.ts
+import { getUnit } from "../query/getUnit"; // ← don't do this
+const unit = await getUnit(db, { id: input.unitId }, ctx);
+```
+
+## Select Locking
+
+Commands that read then write must lock rows with `forUpdate()` to prevent concurrent requests from causing race conditions.
+
+### When to lock
+
+| Pattern                                                     | Lock? | Example                                                                               |
+| ----------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------- |
+| Read a record, then update/delete it                        | Yes   | `deactivateUnit`: reads unit, then sets `isActive = false`                            |
+| Read a record to check uniqueness before insert             | Yes   | `createUnit`: checks symbol uniqueness, then inserts                                  |
+| Read multiple related records, then update them             | Yes   | `setReferenceUnit`: reads all units in category, recalculates factors                 |
+| Read a record only for validation (no write to that record) | No    | Reading a category to verify it exists before inserting a unit into a different table |
+| Insert-only with no prior read                              | No    | `logAuditEvent`: pure insert                                                          |
+
+### Rule
+
+> Lock a `SELECT` when the command **writes to the same record it reads**, or when it **reads to enforce a uniqueness constraint** before inserting. The lock scope should be the narrowest set of rows needed — lock only the rows that participate in the read-then-write cycle.
+
+### Code pattern
+
+Chain `.forUpdate()` on the select query:
+
+```typescript
+const unit = await db
+  .selectFrom("Unit")
+  .selectAll()
+  .where("id", "=", input.unitId)
+  .forUpdate()
+  .executeTakeFirst();
+```
+
+### Batch locking
+
+When a command reads multiple rows then updates them (e.g., `setReferenceUnit`), lock the entire set:
+
+```typescript
+const units = await db
+  .selectFrom("Unit")
+  .selectAll()
+  .where("categoryId", "=", input.categoryId)
+  .forUpdate()
+  .execute();
+```
+
+## Implementation Considerations
+
+- **Error handling**: Use `ok()` / `err()` from `shared/internal` — do not throw
+- **Validation**: Check referenced entities exist before operating, return `err()` if not found
+
+## 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-shared/references/errors.md

@@ -0,0 +1,35 @@
+# Error Classes
+
+Errors are **generated** from command/query documentation. Do not write `lib/errors.ts` manually.
+
+## How it works
+
+1. Write error scenarios in `docs/commands/*.md` as `CODE: Description` pairs
+2. Run `erp-kit module generate code` to produce `lib/errors.generated.ts`
+3. Import generated errors in your command implementations
+
+## Naming convention (in docs)
+
+- Error code: `SCREAMING_SNAKE_CASE` (e.g., `DUPLICATE_SKU`)
+- Generated class name: PascalCase + `Error` suffix (e.g., `DuplicateSkuError`)
+- Generated via `createDomainError()` with contextual message
+
+## Error category naming rules
+
+Use the **entity name** (not business-domain abbreviations) in error codes. Codes should be self-describing and consistent across modules.
+
+| Category          | Pattern                                 | Example                              |
+| ----------------- | --------------------------------------- | ------------------------------------ |
+| Not found         | `{ENTITY}_NOT_FOUND`                    | `UNIT_NOT_FOUND`, `ITEM_NOT_FOUND`   |
+| Duplicate         | `DUPLICATE_{FIELD}`                     | `DUPLICATE_SKU`, `DUPLICATE_BARCODE` |
+| Inactive / locked | `{FIELD}_LOCKED` or `{ENTITY}_INACTIVE` | `UOM_LOCKED`                         |
+| Invalid state     | `INVALID_{WHAT}`                        | `INVALID_STATE_TRANSITION`           |
+| No-op             | `NO_FIELDS_TO_UPDATE`                   | `NO_FIELDS_TO_UPDATE`                |
+
+### Cross-module foreign key errors
+
+When a command validates an entity from another module (e.g., item-management checking that a Unit from primitives exists), use `{ENTITY}_NOT_FOUND` — the same pattern as same-module not-found errors. The error code reflects what's missing, not where it lives.
+
+### Idempotent error policy
+
+If a command's outcome is already the current state (e.g., deactivating an already-inactive entity), return `ok()` — not an error. Only return errors for genuinely invalid operations.

package/skills/erp-kit-module-shared/references/queries.md

@@ -0,0 +1,168 @@
+# Query Implementation
+
+## Generated Query Shells
+
+Run `erp-kit module generate code` to generate query shells from `docs/queries/*.md`. Each generated shell wraps your `run` function with `defineQuery`.
+
+### Generated shell example
+
+```typescript
+// @generated — do not edit
+import { defineQuery } from "../../shared/internal";
+import { run } from "./getItem";
+
+export const getItem = defineQuery(run);
+```
+
+### Hand-written implementation
+
+```typescript
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type GetItemInput = { id: string } | { sku: string };
+
+export async function run(db: ReadonlyDB<DB>, input: GetItemInput) {
+  let query = db.selectFrom("Item").selectAll();
+
+  if ("id" in input) {
+    query = query.where("id", "=", input.id);
+  } else {
+    query = query.where("sku", "=", input.sku);
+  }
+
+  const item = await query.executeTakeFirst();
+  return { item: item ?? null };
+}
+```
+
+## Custom Queries
+
+For queries beyond simple lookups (joins, aggregations, complex filters), write them by hand in `query/*.ts`:
+
+```typescript
+import type { ReadonlyDB } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export interface ListActiveItemsByCategoryInput {
+  categoryId: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: ListActiveItemsByCategoryInput) {
+  const items = await db
+    .selectFrom("Item")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .where("status", "=", "ACTIVE")
+    .execute();
+
+  return { items };
+}
+```
+
+## Conventions
+
+- `defineQuery` wraps all queries via generated shells
+- `ReadonlyDB<DB>` ensures read-only access
+- Get queries return `{ entity: T | null }` using `executeTakeFirst()`
+- List queries return `{ entities: T[] }` using `execute()`
+- Input types: `type` for union inputs (get), `interface` for single-shape inputs (list)
+- `.generated.ts` files are always overwritten — never edit them
+
+## Status-Aware Query Rules
+
+Models with a status lifecycle (Stateful models with `status` enum, or simple models with `isActive` bool) follow specific naming and filtering conventions. The core principle: **if a status filter is a business use case, put it in the query name. If it's a search parameter, put it in the input.**
+
+### Naming Convention
+
+| Query type                     | Pattern                              | Returns                                     |
+| ------------------------------ | ------------------------------------ | ------------------------------------------- |
+| **Get (single lookup)**        | `get{Entity}`                        | Any status — caller already has a reference |
+| **List (status-filtered)**     | `list{Status}{Entities}`             | Only records matching the named status      |
+| **List (unfiltered)**          | `list{Entities}`                     | All records, all statuses                   |
+| **Search (admin/exploratory)** | `search{Entities}({ status?, ... })` | Ad-hoc filtering via input params           |
+
+### Examples
+
+```typescript
+// Business use case — status baked into the name
+export async function run(db: ReadonlyDB<DB>, input: ListActiveItemsByCategoryInput) {
+  const items = await db
+    .selectFrom("Item")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .where("status", "=", "ACTIVE")
+    .execute();
+  return { items };
+}
+
+// Unfiltered — no status filter, returns everything
+export async function run(db: ReadonlyDB<DB>, input: ListItemsByCategoryInput) {
+  const items = await db
+    .selectFrom("Item")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .execute();
+  return { items };
+}
+
+// Single lookup — status-unaware, returns any status
+export async function run(db: ReadonlyDB<DB>, input: GetItemInput) {
+  const item = await db
+    .selectFrom("Item")
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+  return { item: item ?? null };
+}
+
+// Admin/exploratory — parametric status filter
+export interface SearchItemsInput {
+  status?: string;
+  categoryId?: string;
+}
+
+export async function run(db: ReadonlyDB<DB>, input: SearchItemsInput) {
+  let query = db.selectFrom("Item").selectAll();
+  if (input.status) {
+    query = query.where("status", "=", input.status);
+  }
+  if (input.categoryId) {
+    query = query.where("categoryId", "=", input.categoryId);
+  }
+  const items = await query.execute();
+  return { items };
+}
+```
+
+### `isActive` (bool) Models
+
+The same naming rules apply. For models using `isActive` instead of a `status` enum (e.g., Currency, Unit, UomCategory):
+
+```typescript
+// Business use case — active units only
+// listActiveUnitsByCategory
+export async function run(db: ReadonlyDB<DB>, input: ListActiveUnitsByCategoryInput) {
+  const units = await db
+    .selectFrom("Unit")
+    .selectAll()
+    .where("categoryId", "=", input.categoryId)
+    .where("isActive", "=", true)
+    .execute();
+  return { units };
+}
+```
+
+### Anti-patterns
+
+- **Silent defaults**: `listItems()` returning only ACTIVE without the name saying so — hidden behavior violates the principle of least surprise
+- **"listAll" prefix**: `listAllItems()` implies the unfiltered variant is the exception — use `listItems()` for unfiltered instead
+- **Fat queries with many optional filters for business use cases**: prefer purpose-built queries with intent in the name over swiss-army-knife queries
+
+### Status preconditions in commands
+
+Status checks that guard mutations (e.g., "only DRAFT items can be deleted") belong in commands, not queries. See [CQRS command-side read rule](commands.md#command-side-reads-cqrs-separation).
+
+## See Also
+
+- [CQRS command-side read rule](commands.md#command-side-reads-cqrs-separation) — queries are read-side only; commands inline own reads

package/skills/erp-kit-module-shared/references/structure.md

@@ -0,0 +1,36 @@
+# Module Directory Structure
+
+This structure is automatically scaffolded by `erp-kit module scaffold module <name>`.
+
+```
+{module}/
+├── db/           # Database models (one file per model)
+├── executor/     # Async executors (record triggers, job functions)
+├── command/      # Domain commands + tests (*.test.ts co-located)
+│   ├── *.ts              # Hand-written business logic (run function)
+│   ├── *.generated.ts    # Generated command shells (do not edit)
+│   └── *.test.ts         # Tests
+├── query/        # Read-only query handlers
+│   ├── *.ts              # Hand-written custom queries
+│   └── *.generated.ts    # Generated get/list queries (do not edit)
+├── lib/
+│   ├── errors.generated.ts    # Generated error classes (do not edit)
+│   ├── permissions.generated.ts # Generated permissions (do not edit)
+│   └── types.ts               # Hand-written types
+├── testing/      # Test fixtures and helpers
+├── generated/    # Auto-generated kysely types (do not edit)
+├── index.ts      # Public exports
+├── tailor.config.ts # Module config and generators
+└── 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
+- `query/`: Read-only query handlers
+- `lib/`: Generated errors/permissions + hand-written types
+- `testing/`: Fixtures for tests only
+- `.generated.ts` files are always overwritten — never edit them
+- Run `pnpm generate` after modifying `db/` models

package/skills/{3-module-doc-review → erp-kit-module-shared}/references/testing.md

@@ -22,13 +22,14 @@ spies.select.mockReturnValueOnce(first).mockReturnValueOnce(second);
 
 ## Custom Fields Passthrough
 
-For `makeCreateX` factory commands, add one test verifying custom fields reach `.values()`:
+For commands with generic `CF`, add one test verifying custom fields reach `.values()`:
 
-- Instantiate with concrete type: `makeCreateX<{ myField: string }>()`
+- Import from `./createX.generated` (the generated shell that wires permissions)
+- Pass extra fields in the input: `await createX(db, { name: "Test", myField: "value" }, ctx)`
 - 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`)
+## 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-update/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: erp-kit-update
+description: Route requirements changes to the correct erp-kit skill. Use when requirements change midway — adding features, modifying business flows, updating screens, changing module specs, or when unsure which erp-kit skill to re-run after a change.
+---
+
+# Requirements Update Router
+
+Route mid-workflow changes to the correct erp-kit skill. Dynamically discovers available skills — no hardcoded routing tables.
+
+## Workflow
+
+```
+IDENTIFY → DISCOVER → ROUTE → CASCADE → INVOKE
+```
+
+## Phase 1: Identify
+
+Ask the user:
+
+1. **What changed?** (free-text description of the change)
+2. **Where?** Determine domain from the target:
+   - `examples/<app>/` → **App workflow** (skills matching `erp-kit-app-*`)
+   - `modules/<module>/` → **Module workflow** (skills matching `erp-kit-module-*`)
+
+If the user names a specific app or module, confirm the path. If ambiguous, check both directories.
+
+## Phase 2: Discover
+
+Dynamically discover available erp-kit skills:
+
+1. Glob for `erp-kit-app-*/SKILL.md` or `erp-kit-module-*/SKILL.md` files (based on domain from Phase 1) in the skills directory
+2. Read each SKILL.md's frontmatter `name` and `description`
+3. Skip `erp-kit-module-shared` (not directly invocable)
+4. Sort skills by their numeric step (extract number from name, e.g. `erp-kit-app-2-breakdown` → step 2)
+
+This builds the routing table at runtime — new or renamed skills are picked up automatically.
+
+## Phase 3: Route
+
+Match the user's change description against each discovered skill's `description` field. Select the **earliest** skill whose description matches the type of change.
+
+**When ambiguous:** Route to the earliest possible skill in the chain. Earlier skills cascade forward naturally.
+
+## Phase 4: Cascade
+
+After identifying the entry point, warn about downstream skills that need re-running. Use the sorted skill list from Phase 2 — all skills with a higher step number than the routed skill are potential downstream candidates.
+
+Show: "Starting from `<routed-skill>`. After this completes, you'll likely need to re-run: `<downstream-skills>`."
+
+Only list downstream skills that are plausibly affected by the change.
+
+## Phase 5: Invoke
+
+Use the `Skill` tool to invoke the routed skill. Pass the app or module name as the argument.
+
+Example: `Skill: erp-kit-app-2-breakdown, args: "inventory-management"`
+
+## Multiple Changes
+
+If the user describes multiple changes spanning different skills or domains:
+
+1. Group by domain (app vs module)
+2. Within each domain, route to the **earliest** affected skill
+3. The cascade will naturally cover later skills

package/src/cli.doc.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, beforeAll } from "vitest";
+import {
+  assertDocMatch,
+  initDocFile,
+  collectAllCommands,
+  type GenerateDocConfig,
+  type FileMapping,
+} from "politty/docs";
+import { mainCommand } from "./commands/index";
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+async function buildFilesFromCommand(): Promise<FileMapping> {
+  const allCommands = await collectAllCommands(mainCommand);
+  const files: FileMapping = {};
+
+  // Single-file full reference
+  files["docs/cli.md"] = { commands: [""], title: "CLI Reference" };
+
+  // Per-command sub-files
+  for (const [path, info] of allCommands) {
+    if (info.depth !== 2) continue;
+
+    const title =
+      info.subCommands.length > 0 ? `${capitalize(path)} Commands` : `${capitalize(path)} Command`;
+
+    files[`docs/cli/${path}.md`] = { commands: [path], title };
+  }
+
+  return files;
+}
+
+const files = await buildFilesFromCommand();
+const targetCommands = Object.values(files).flatMap((f) =>
+  typeof f === "object" && "commands" in f ? f.commands : f,
+);
+
+const config: GenerateDocConfig = {
+  command: mainCommand,
+  files,
+  format: {
+    headingLevel: 2,
+    optionStyle: "table",
+    generateAnchors: true,
+    includeSubcommandDetails: true,
+  },
+};
+
+describe("CLI documentation", () => {
+  beforeAll(() => {
+    initDocFile(config);
+  });
+
+  for (const cmd of targetCommands) {
+    test(`${cmd || "root"}`, async () => {
+      await assertDocMatch({ ...config, targetCommands: [cmd] });
+    });
+  }
+
+  test("all", async () => {
+    await assertDocMatch(config);
+  });
+});