# @tailor-platform/erp-kit

CLI tool for validating, generating, syncing module documentation, and managing mock API servers.

## Install

```bash
npm install @tailor-platform/erp-kit
```

## Quick Start

```bash
# Set up your repo (agent skills, workflows, project structure)
erp-kit init my-project

# Update framework resources
erp-kit update

# Browse module documentation
erp-kit doc modules
erp-kit doc module organization
erp-kit doc module organization command CreateCompany

# Validate module docs against schemas
erp-kit module check --path src/modules

# Check source ↔ doc correspondence
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 generate doc --path src/modules/inventory command createOrder

# Validate app docs
erp-kit app check --path apps/my-app

# Check dependency licenses
erp-kit license check --config license.config.json

# List available license groups
erp-kit license list

# Start mock API servers
erp-kit mock start

# Validate mock configs
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 <name>
```

**Arguments:**

- `<name>` — Project name (used in `package.json`)

This will:

1. Copy agent skills to `.agents/skills/`
2. Create symlink `.claude/skills` → `.agents/skills/`
3. Copy workflows to `.github/workflows/`
4. Scaffold project structure (`package.json`, `pnpm-workspace.yaml`, `.gitignore`, `license.config.json`, `apps/`, `modules/`)

### `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.

### `doc`

Browse module documentation. Outputs existing docs with minimal transformation — docs are the source of truth.

#### `doc modules`

Lists all modules with overview, counts, and dependencies.

```bash
erp-kit doc modules
erp-kit doc modules --format json
```

#### `doc module`

Shows documentation for a specific module. Without type/name, outputs the full README and lists available docs. With type and name, outputs the raw doc content.

```bash
erp-kit doc module organization
erp-kit doc module organization command CreateCompany
erp-kit doc module organization query GetCompany
erp-kit doc module organization model Company
erp-kit doc module organization feature company-lifecycle
erp-kit doc module organization --format json
```

**Arguments:**

- `<name>` — Module name
- `[type]` — Doc type (`command`, `query`, `model`, `feature`)
- `[docName]` — Doc name
- `--format, -f` — Output format (`text` or `json`, default: `text`)

### `module`

Module documentation management.

#### `module check`

Validates module markdown documentation against YAML schemas.

```bash
erp-kit module check --path src/modules
```

#### `module sync-check`

Ensures every source file has a corresponding doc and vice versa.

```bash
erp-kit module sync-check --path src/modules
```

#### `module init`

Bootstraps a new module with directory structure and README.

```bash
erp-kit module init inventory src/modules
```

**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
```

**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 generate code --path src/modules/inventory
```

### `app`

Application management.

#### `app check`

Validates application documentation against YAML schemas.

```bash
erp-kit app check --path apps/my-app
```

#### `app sync-check`

Ensures every source file has a corresponding doc and vice versa.

```bash
erp-kit app sync-check --path apps/my-app
```

#### `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 apps/my-app actors admin
erp-kit app generate doc --path apps/my-app business-flow onboarding
erp-kit app generate doc --path apps/my-app story onboarding/admin--create-user
erp-kit app generate doc --path apps/my-app screen supplier-list
erp-kit app generate doc --path apps/my-app resolver create-supplier
```

**Arguments:**

- `--path, -p <path>` — Path to the app directory (required)
- `<type>` — Doc type (`actors`, `business-flow`, `story`, `screen`, `resolver`)
- `<name>` — Item name (for `story`, use `<flow>/<story>` format)

#### `app generate code`

Generates boilerplate source files from docs.

```bash
erp-kit app generate code --path apps/my-app
```

### `mock start`

Starts Mockoon-based mock API servers behind a reverse proxy. Each mock scenario (`mocks/{provider}/{scenario}/mock.json`) runs on an auto-assigned port and is accessible through the proxy at `http://localhost:{port}/{provider}/{scenario}/...`.

**Arguments:**

- `[filter...]` — (optional) Filter by provider or provider/scenario. If omitted, all mocks are started.
- `--mocks-root <path>` — Path to mocks directory (default: `./mocks`)
- `-p, --port <number>` — Reverse proxy port (default: `3000`)

```bash
# Start all mocks
erp-kit mock start

# Custom proxy port
erp-kit mock start --port 4000

# Filter by provider or provider/scenario
erp-kit mock start qbo
erp-kit mock start shopify/admin-api sendgrid/send-email

# Custom mocks directory
erp-kit mock start --mocks-root ./my-mocks
```

### `mock validate`

Validates mock scenario configs against the Mockoon schema and checks for common issues (missing `Content-Type` headers, empty response labels, broken databucket references).

**Arguments:**

- `[paths...]` — (optional) Specific scenario paths to validate. If omitted, all scenarios are validated.
- `--mocks-root <path>` — Path to mocks directory (default: `./mocks`)

```bash
# Validate all scenarios
erp-kit mock validate

# Validate specific scenarios
erp-kit mock validate mocks/shopify/admin-api mocks/sendgrid/send-email
```

### `license`

License management. Uses [Google licenseclassifier](https://github.com/google/licenseclassifier) categories as built-in groups.

#### `license list`

Lists available license groups and their licenses.

```bash
erp-kit license list
```

#### `license check`

Checks dependency licenses against a config-driven allowlist. Requires `pnpm` (uses `pnpm licenses list` under the hood).

**Arguments:**

- `-c, --config <path>` — Path to license config JSON file (required)

```bash
erp-kit license check --config license.config.json
```

**Config format:**

```json
{
  "groups": ["reciprocal", "notice", "unencumbered"],
  "allow": ["BlueOak-1.0.0", "WTFPL"],
  "deny": ["BSD-4-Clause"]
}
```

| Field    | Description                                                               |
| -------- | ------------------------------------------------------------------------- |
| `groups` | Built-in license groups to allow (`reciprocal`, `notice`, `unencumbered`) |
| `allow`  | Additional individual licenses to allow                                   |
| `deny`   | Licenses to exclude (applied after groups + allow)                        |

## Options

| Flag                  | Alias | Applies to                                         | Description                                  |
| --------------------- | ----- | -------------------------------------------------- | -------------------------------------------- |
| `--path <path>`       | `-p`  | `module check/sync-check/generate`, `app *`        | Path to module or app 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             |
| `--format <format>`   | `-f`  | `doc modules`, `doc module`                        | Output format: `text` or `json`              |

## What's Bundled

| Directory  | Contents                                                       |
| ---------- | -------------------------------------------------------------- |
| `schemas/` | YAML schema definitions for all doc types                      |
| `skills/`  | 17 agent skills for documentation, implementation, and mocking |

### Schemas

**Module:** `module`, `feature`, `command`, `model`, `query`

**App:** `requirements`, `actors`, `business-flow`, `story`, `screen`, `resolver`

### Agent Skills

Module workflow:

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

Application workflow:

1. `erp-kit-app-1-requirements` — Tier 1-2: requirements, actors, business flows
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

Shared and utility:

- `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 Testing Helpers

The `@tailor-platform/erp-kit/testing` export provides helpers for integration tests:

```ts
import { createMockServer } from "@tailor-platform/erp-kit/testing";

const server = await createMockServer("./mocks/shopify/admin-api/mock.json");
// server.url  → "http://127.0.0.1:{port}"
// server.port → assigned port number

// Use server.url as base URL in your tests
const res = await fetch(`${server.url}/admin/api/2024-01/products`);

// Clean up
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
pnpm install
pnpm --filter @tailor-platform/erp-kit build
pnpm --filter @tailor-platform/erp-kit test
```
