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

> Proprietary software — see [License](#license).

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

# 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/`)

### License checks

The scaffolded `.github/workflows/erp-kit-check.yml` checks dependency licenses via [`tailor-platform/actions/check-licenses`](https://github.com/tailor-platform/actions/tree/main/check-licenses), reading its inputs from `license.config.json`:

```json
{
  "groups": ["reciprocal", "notice", "unencumbered"],
  "allow": ["BlueOak-1.0.0", "Unknown", "OFL-1.1"],
  "deny": [],
  "packageExceptions": {}
}
```

| Field               | Description                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `groups`            | Google licenseclassifier categories to allow (`reciprocal`, `notice`, `unencumbered`)       |
| `allow`             | Extra individual SPDX license identifiers to allow                                          |
| `deny`              | Licenses to reject even if part of a selected group                                         |
| `packageExceptions` | Approve one specific dependency route to an otherwise-disallowed license — see [`package-exceptions`](https://github.com/tailor-platform/actions/tree/main/check-licenses#package-exceptions). Always yours to manage: erp-kit doesn't know your project's dependencies, so this key is never touched by the org policy embedding below. |

`groups`/`allow`/`deny` ship with the tailor-platform org's current policy baked in: at publish time, `prepack` overwrites them from the `LICENSE_GROUPS` / `ALLOWED_LICENSES` / `DENIED_LICENSES` GitHub Variables (see `scripts/embed-license-policy.js`), since a scaffolded project can't read those org-level variables itself. Edit the generated file directly to diverge from the org default.

### `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 actor 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 (`actor`, `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
```

### `verify`

Runs the deterministic checks across the modules directory and each app, and exits non-zero on any violation:

- **versions** — version consistency across package manifests
- **structure** — required directories and file naming rules

```bash
erp-kit verify --modules-root modules --apps-root apps
```

**Arguments:**

- `--modules-root, -m <path>` — Path to the modules directory (default: `modules`)
- `--apps-root, -a <path>` — Path to the apps directory; each child is one app (default: `apps`)

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

## 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`)         |
| `--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`, `actor`, `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/mock-server` export stands up a Mockoon mock API for integration and e2e tests. It runs a real HTTP server, so use it from a `node` test environment:

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

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 { createKyselyMock } from "@tailor-platform/sdk/vitest";
import { testNotFound, testPermissionDenied, testIdempotent } from "@tailor-platform/erp-kit/testing";
```

- `createKyselyMock()` — Creates a mock database for unit testing commands and queries (run commands via `mock.withTx`, queries via `mock.db`)
- `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
```

## License

Tailor Platform ERP Kit License

Copyright (c) 2026 Tailor Technologies, Inc. All rights reserved.

This software is the proprietary property of Tailor Technologies, Inc.
("Tailor"). It is made available solely for use by customers and partners of
Tailor Platform, and only in accordance with a separate written agreement with
Tailor. Where such an agreement exists, its terms govern your use of this
software and prevail over this notice.

Absent such an agreement, no license or other right is granted to you, and you
may not use, copy, modify, distribute, or create derivative works of this
software, in whole or in part.

Without limiting the foregoing, you may not (a) reverse engineer, decompile, or
disassemble this software, or (b) use this software, or any information or
insight derived from it, to develop, provide, or support any product or service
that competes with this software or with any product or service offered by
Tailor or its affiliates.

No license under any patent, trademark, or other intellectual property right --
whether express, implied, by estoppel, or otherwise -- is granted by Tailor or
its affiliates with respect to this software.

Tailor retains all right, title, and interest in and to this software,
including all intellectual property rights therein. The fact that this software
is publicly visible does not constitute a grant, waiver, or forfeiture of any
of the foregoing rights.

Licensing inquiries: legal@tailor.tech