@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/README.md

@@ -1,45 +1,213 @@
 # @tailor-platform/erp-kit
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+CLI tool for validating, scaffolding, syncing module documentation, and managing mock API servers.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Install
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @tailor-platform/erp-kit
+```
 
-## Purpose
+## Quick Start
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@tailor-platform/erp-kit`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```bash
+# Set up your repo (agent skills, rules)
+erp-kit init
 
-## What is OIDC Trusted Publishing?
+# Validate docs against schemas
+erp-kit check --modules-root modules
+erp-kit check --app-root examples
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+# Check source ↔ doc correspondence
+erp-kit sync-check --modules-root modules
 
-## Setup Instructions
+# Generate a new doc from template
+erp-kit scaffold --modules-root modules <type> <parent> [name]
 
-To properly configure OIDC trusted publishing for this package:
+# Start mock API servers
+erp-kit mock start
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+# Validate mock configs
+erp-kit mock validate
+```
 
-## DO NOT USE THIS PACKAGE
+## Commands
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### `check`
 
-## More Information
+Validates markdown documentation against YAML schemas.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```bash
+erp-kit check --modules-root modules
+erp-kit check --app-root examples
+erp-kit check --modules-root modules --app-root examples
+```
 
----
+### `sync-check`
 
-**Maintained for OIDC setup purposes only**
+Ensures every source file has a corresponding doc and vice versa. Detects missing and orphaned documentation.
+
+```bash
+erp-kit sync-check --modules-root modules
+erp-kit sync-check --app-root examples
+```
+
+### `scaffold`
+
+Generates documentation files from schema templates.
+
+**Module types:**
+
+```bash
+erp-kit scaffold --modules-root modules module inventory
+erp-kit scaffold --modules-root modules feature inventory stock-tracking
+erp-kit scaffold --modules-root modules command inventory CreateOrder
+erp-kit scaffold --modules-root modules model inventory StockItem
+```
+
+**App-compose types:**
+
+```bash
+erp-kit scaffold --app-root examples requirements my-app
+erp-kit scaffold --app-root examples actors my-app admin
+erp-kit scaffold --app-root examples business-flow my-app onboarding
+erp-kit scaffold --app-root examples story my-app onboarding/admin--create-user
+erp-kit scaffold --app-root examples screen my-app supplier-list
+erp-kit scaffold --app-root examples resolver my-app create-supplier
+```
+
+### `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
+```
+
+### `init`
+
+One-time setup for consumer repos. Idempotent — skips files that already exist.
+
+```bash
+erp-kit init
+```
+
+This will:
+
+1. Copy 12 agent skills to `.agents/skills/`
+2. Copy development rules to `.agents/rules/`
+
+## Options
+
+| Flag                    | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `--modules-root <path>` | Path to modules directory (required for module commands)  |
+| `--app-root <path>`     | Path to app-compose directory (required for app commands) |
+| `--mocks-root <path>`   | Path to mocks directory (default: `./mocks`)              |
+| `-p, --port <number>`   | Reverse proxy port for `mock start` (default: `3000`)     |
+
+At least one of `--modules-root` or `--app-root` is required for `check`, `sync-check`, and `scaffold`.
+
+## What's Bundled
+
+| Directory     | Contents                                                         |
+| ------------- | ---------------------------------------------------------------- |
+| `schemas/`    | YAML schema definitions for all doc types                        |
+| `sync-check/` | Source-to-doc mapping configs                                    |
+| `skills/`     | 12 agent skills for documentation, implementation, and mocking   |
+| `rules/`      | Development rules and best practices for modules and app-compose |
+
+### Schemas
+
+**Module:** `module`, `feature`, `command`, `model`
+
+**App-compose:** `requirements`, `actors`, `business-flow`, `story`, `screen`, `resolver`
+
+### Agent Skills
+
+Module workflow:
+
+1. `1-module-docs` — Create module documentation
+2. `2-module-feature-breakdown` — Break features into models and commands
+3. `3-module-doc-review` — Review feature-to-doc parity
+4. `4-module-tdd-implementation` — TDD implementation from docs
+5. `5-module-implementation-review` — Review implementation-to-doc parity
+
+App-compose workflow:
+
+1. `app-compose-1-requirement-analysis` — Tier 1-2: requirements, actors, business flows
+2. `app-compose-2-requirements-breakdown` — Tier 3: stories and screens
+3. `app-compose-3-doc-review` — Review doc parity
+4. `app-compose-4-design-mock` — Create UI mockups from screen specs
+5. `app-compose-5-design-mock-review` — Review mockups against specs
+6. `app-compose-6-implementation-spec` — Tier 4: resolver specs
+
+Mock workflow:
+
+1. `mock-scenario` — Scaffold a new Mockoon mock scenario with CRUD routes and error scenarios
+
+### Development Rules
+
+- `module-development/` — Structure, commands, models, executors, testing, exports, errors
+- `app-compose/` — App structure, frontend screens, components, auth patterns
+- `sdk-best-practices/` — Database relations, SDK documentation references
+
+## Programmatic Mock Server
+
+The `createMockServer` helper starts a Mockoon server from a `mock.json` file, useful 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();
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @tailor-platform/erp-kit build
+pnpm --filter @tailor-platform/erp-kit test
+```