@tailor-platform/erp-kit 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @tailor-platform/erp-kit
 
+## 0.3.0
+
+### Minor Changes
+
+- a8462ee: Reorganize scaffold into init/generate and update README
+
+  - Refactor: replace `module scaffold` and `app scaffold` with `init` + `generate doc` / `generate code` subcommands
+  - Feat: add `erp-kit-app-shared` skill consolidating duplicated references across app skills
+  - Feat: add db stub generation and `reset:module` script
+  - Refactor: run generate before impl agents in `erp-kit-module-5-impl`
+  - Docs: rewrite README to align with current CLI commands, flags, skills (17), and testing exports
+
+## 0.2.2
+
+### Patch Changes
+
+- 980a1f0: Add app-level scaffold with template files
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @tailor-platform/erp-kit
 
-CLI tool for validating, scaffolding, syncing module documentation, and managing mock API servers.
+CLI tool for validating, generating, syncing module documentation, and managing mock API servers.
 
 ## Install
 
@@ -11,23 +11,29 @@ npm install @tailor-platform/erp-kit
 ## Quick Start
 
 ```bash
-# Set up your repo (agent skills)
+# Set up your repo (agent skills, workflows, configs)
 erp-kit init
 
+# Update framework resources
+erp-kit update
+
 # List available modules
 erp-kit module list
 
 # Validate module docs against schemas
-erp-kit module check --root src/modules
+erp-kit module check --path src/modules
 
 # Check source ↔ doc correspondence
-erp-kit module sync-check --root src/modules
+erp-kit module sync-check --path src/modules
+
+# Bootstrap a new module
+erp-kit module init inventory src/modules
 
 # Generate a new module doc from template
-erp-kit module scaffold command inventory createOrder --root src/modules
+erp-kit module generate doc --path src/modules/inventory command createOrder
 
 # Validate app docs
-erp-kit app check --root examples
+erp-kit app check --path examples
 
 # Check dependency licenses
 erp-kit license check --config license.config.json
@@ -44,6 +50,38 @@ erp-kit mock validate
 
 ## Commands
 
+### `init`
+
+First-time setup for consumer repos. Fails if already initialized — use `erp-kit update` to refresh resources.
+
+```bash
+erp-kit init
+```
+
+This will:
+
+1. Copy agent skills to `.agents/skills/`
+2. Create symlink `.claude/skills` → `.agents/skills/`
+3. Copy workflows to `.github/workflows/`
+4. Copy config files
+
+### `update`
+
+Refresh framework resources. Removes stale skills and copies latest versions.
+
+```bash
+# Update everything (skills + workflows)
+erp-kit update
+
+# Update specific resources
+erp-kit update skills
+erp-kit update workflows
+```
+
+**Arguments:**
+
+- `[resources...]` — (optional) Resources to update (`skills`, `workflows`). Defaults to all.
+
 ### `module`
 
 Module documentation management.
@@ -61,7 +99,7 @@ erp-kit module list
 Validates module markdown documentation against YAML schemas.
 
 ```bash
-erp-kit module check --root src/modules
+erp-kit module check --path src/modules
 ```
 
 #### `module sync-check`
@@ -69,40 +107,45 @@ erp-kit module check --root src/modules
 Ensures every source file has a corresponding doc and vice versa.
 
 ```bash
-erp-kit module sync-check --root src/modules
+erp-kit module sync-check --path src/modules
 ```
 
-#### `module scaffold`
+#### `module init`
 
-Generates documentation files from schema templates.
-
-When the type is `module`, it also creates a starter `src/` directory with the following structure:
+Bootstraps a new module with directory structure and README.
 
+```bash
+erp-kit module init inventory src/modules
 ```
-src/
-├── db/              (.gitkeep)
-├── command/         (.gitkeep)
-├── executor/        (.gitkeep)
-├── generated/       (.gitkeep)
-├── query/           (.gitkeep)
-├── lib/
-│   ├── errors.ts
-│   └── types.ts
-├── testing/
-│   └── fixtures.ts
-├── module.ts
-├── index.ts
-├── permissions.ts
-└── tailor.config.ts
+
+**Arguments:**
+
+- `<name>` — Module name
+- `<dir>` — Parent directory where the module will be created
+
+#### `module generate doc`
+
+Creates a documentation file from a schema template.
+
+```bash
+erp-kit module generate doc --path src/modules/inventory feature stock-tracking
+erp-kit module generate doc --path src/modules/inventory command createOrder
+erp-kit module generate doc --path src/modules/inventory model StockItem
+erp-kit module generate doc --path src/modules/inventory query getStockLevel
 ```
 
-Templates for these files are defined in `src/commands/scaffold-templates.ts`.
+**Arguments:**
+
+- `--path, -p <path>` — Path to the module directory (required)
+- `<type>` — Doc type (`feature`, `command`, `model`, `query`)
+- `<name>` — Item name
+
+#### `module generate code`
+
+Generates boilerplate, implementation stubs, and generated code from docs.
 
 ```bash
-erp-kit module scaffold module inventory --root src/modules
-erp-kit module scaffold feature inventory stock-tracking --root src/modules
-erp-kit module scaffold command inventory createOrder --root src/modules
-erp-kit module scaffold model inventory StockItem --root src/modules
+erp-kit module generate code --path src/modules/inventory
 ```
 
 ### `app`
@@ -114,7 +157,7 @@ App-compose documentation management.
 Validates app documentation against YAML schemas.
 
 ```bash
-erp-kit app check --root examples
+erp-kit app check --path examples
 ```
 
 #### `app sync-check`
@@ -122,20 +165,46 @@ erp-kit app check --root examples
 Ensures every source file has a corresponding doc and vice versa.
 
 ```bash
-erp-kit app sync-check --root examples
+erp-kit app sync-check --path examples
 ```
 
-#### `app scaffold`
+#### `app init`
+
+Bootstraps a new app with directory structure and README.
+
+```bash
+erp-kit app init my-app examples
+```
+
+**Arguments:**
+
+- `<name>` — App name
+- `<dir>` — Parent directory where the app will be created
+
+#### `app generate doc`
+
+Creates a documentation file from a schema template.
+
+```bash
+erp-kit app generate doc --path examples/my-app actors admin
+erp-kit app generate doc --path examples/my-app business-flow onboarding
+erp-kit app generate doc --path examples/my-app story onboarding/admin--create-user
+erp-kit app generate doc --path examples/my-app screen supplier-list
+erp-kit app generate doc --path examples/my-app resolver create-supplier
+```
+
+**Arguments:**
+
+- `--path, -p <path>` — Path to the app-compose directory (required)
+- `<type>` — Doc type (`actors`, `business-flow`, `story`, `screen`, `resolver`)
+- `<name>` — Item name (for `story`, use `<flow>/<story>` format)
+
+#### `app generate code`
 
-Generates documentation files from schema templates.
+Generates boilerplate source files from docs.
 
 ```bash
-erp-kit app scaffold requirements my-app --root examples
-erp-kit app scaffold actors my-app admin --root examples
-erp-kit app scaffold business-flow my-app onboarding --root examples
-erp-kit app scaffold story my-app onboarding/admin--create-user --root examples
-erp-kit app scaffold screen my-app supplier-list --root examples
-erp-kit app scaffold resolver my-app create-supplier --root examples
+erp-kit app generate code --path examples/my-app
 ```
 
 ### `mock start`
@@ -220,42 +289,25 @@ erp-kit license check --config license.config.json
 | `allow`  | Additional individual licenses to allow                                   |
 | `deny`   | Licenses to exclude (applied after groups + allow)                        |
 
-### `init`
-
-One-time setup for consumer repos. Idempotent — skips files that already exist.
-
-```bash
-erp-kit init
-
-# Overwrite existing skills
-erp-kit init --force
-```
-
-This will:
-
-1. Copy 12 agent skills to `.agents/skills/`
-2. Create symlink `.claude/skills` → `.agents/skills/`
-
 ## Options
 
-| Flag                  | Alias | Applies to                                  | Description                                  |
-| --------------------- | ----- | ------------------------------------------- | -------------------------------------------- |
-| `--root <path>`       | `-r`  | `module check/sync-check/scaffold`, `app *` | Path to modules or app-compose directory     |
-| `--mocks-root <path>` |       | `mock start`, `mock validate`               | Path to mocks directory (default: `./mocks`) |
-| `--port <number>`     | `-p`  | `mock start`                                | Reverse proxy port (default: `3000`)         |
-| `--config <path>`     | `-c`  | `license`                                   | Path to license config JSON file             |
-| `--force`             | `-f`  | `init`                                      | Overwrite existing files (default: `false`)  |
+| Flag                  | Alias | Applies to                                         | Description                                  |
+| --------------------- | ----- | -------------------------------------------------- | -------------------------------------------- |
+| `--path <path>`       | `-p`  | `module check/sync-check/generate`, `app *`        | Path to modules or app-compose directory     |
+| `--mocks-root <path>` |       | `mock start`, `mock validate`                      | Path to mocks directory (default: `./mocks`) |
+| `--port <number>`     | `-p`  | `mock start`                                       | Reverse proxy port (default: `3000`)         |
+| `--config <path>`     | `-c`  | `license`                                          | Path to license config JSON file             |
 
 ## What's Bundled
 
 | Directory  | Contents                                                       |
 | ---------- | -------------------------------------------------------------- |
 | `schemas/` | YAML schema definitions for all doc types                      |
-| `skills/`  | 12 agent skills for documentation, implementation, and mocking |
+| `skills/`  | 17 agent skills for documentation, implementation, and mocking |
 
 ### Schemas
 
-**Module:** `module`, `feature`, `command`, `model`
+**Module:** `module`, `feature`, `command`, `model`, `query`
 
 **App-compose:** `requirements`, `actors`, `business-flow`, `story`, `screen`, `resolver`
 
@@ -263,27 +315,33 @@ This will:
 
 Module workflow:
 
-1. `erp-kit-module-1-docs` — Create module documentation
-2. `erp-kit-module-2-feature-breakdown` — Break features into models and commands
-3. `erp-kit-module-3-doc-review` — Review feature-to-doc parity
-4. `erp-kit-module-4-tdd` — TDD implementation from docs
-5. `erp-kit-module-5-impl-review` — Review implementation-to-doc parity
+1. `erp-kit-module-1-requirements` — Create module requirements and feature documentation
+2. `erp-kit-module-2-requirements-review` — Review requirements quality and module boundaries
+3. `erp-kit-module-3-plan` — Break down features into model, command, and query docs
+4. `erp-kit-module-4-plan-review` — Review feature-to-doc parity
+5. `erp-kit-module-5-impl` — TDD implementation from docs
+6. `erp-kit-module-6-impl-review` — Review implementation-to-doc parity
 
 App-compose workflow:
 
 1. `erp-kit-app-1-requirements` — Tier 1-2: requirements, actors, business flows
-2. `erp-kit-app-2-breakdown` — Tier 3: stories and screens
-3. `erp-kit-app-3-doc-review` — Review doc parity
-4. `erp-kit-app-4-impl-spec` — Tier 4: resolver specs
-5. `erp-kit-app-5-implementation` — Implement backend and frontend
+2. `erp-kit-app-2-requirements-review` — Review requirements quality and consistency
+3. `erp-kit-app-3-plan` — Tier 3-4: stories, screens, resolvers
+4. `erp-kit-app-4-plan-review` — Review plan-to-requirements parity
+5. `erp-kit-app-5-impl-backend` — Implement backend resolvers and module wiring
+6. `erp-kit-app-6-impl-frontend` — Implement frontend pages and components
+7. `erp-kit-app-7-impl-review` — Review implementation-to-doc parity
 
-Mock workflow:
+Shared and utility:
 
-1. `erp-kit-mock-scenario` — Scaffold a new Mockoon mock scenario with CRUD routes and error scenarios
+- `erp-kit-module-shared` — Shared references for module skills
+- `erp-kit-app-shared` — Shared references for app skills
+- `erp-kit-update` — Route requirements changes to the correct skill
+- `erp-kit-mock-scenario` — Scaffold a new Mockoon mock scenario
 
-## Programmatic Mock Server
+## Programmatic Testing Helpers
 
-The `createMockServer` helper starts a Mockoon server from a `mock.json` file, useful for integration tests:
+The `@tailor-platform/erp-kit/testing` export provides helpers for integration tests:
 
 ```ts
 import { createMockServer } from "@tailor-platform/erp-kit/testing";
@@ -299,6 +357,22 @@ const res = await fetch(`${server.url}/admin/api/2024-01/products`);
 await server.stop();
 ```
 
+Additional testing utilities:
+
+```ts
+import {
+  createMockDb,
+  testNotFound,
+  testPermissionDenied,
+  testIdempotent,
+} from "@tailor-platform/erp-kit/testing";
+```
+
+- `createMockDb()` — Creates a mock database for unit testing commands and queries
+- `testNotFound()` — Helper to test "not found" error handling
+- `testPermissionDenied()` — Helper to test permission denial behavior
+- `testIdempotent()` — Helper to test idempotent command behavior
+
 ## Development
 
 ```bash