@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/skills/mock-scenario/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: mock-scenario
+description: Scaffold a new Mockoon mock scenario with CRUD routes, error scenarios, and registry updates
+---
+
+# Mock Scenario Scaffolder
+
+Generate a complete Mockoon mock API config for a new provider scenario and wire it into the registry.
+
+## Workflow
+
+### Step 1: Identify target API
+
+Ask the user for:
+
+- **Provider name** (e.g. `stripe`, `github`, `twilio`)
+- **Scenario name** (e.g. `admin-api`, `payments-api`, `product-sync`)
+- **Key resources to mock** (e.g. customers, invoices, messages)
+- **Scenario to test** (e.g. initial full sync, incremental sync, webhook-triggered update, error recovery)
+
+### Step 2: Research real API
+
+Use web search to find:
+
+- Base URL and API version
+- Authentication scheme (API key, OAuth, bearer token)
+- Endpoint patterns and HTTP methods
+- Response shapes for the key resources
+- Error response format (status codes, error body structure)
+- Rate limit headers
+
+### Step 3: Generate Mockoon JSON
+
+Create `mocks/{provider}/{scenario}/mock.json` following the Shopify admin-api mock as the canonical reference (`mocks/shopify/admin-api/mock.json`).
+
+The config must include:
+
+- **uuid**: a valid UUID v4
+- **name**: Human-readable API name
+- **endpointPrefix**: Match the real API's base path
+- **port**: `3000` (overridden at runtime by the reverse proxy launcher)
+- **hostname**: `0.0.0.0`
+- **latency**: `0`
+- **folders**: `[]`
+- **rootChildren**: `[]`
+- **proxyMode**: `false`
+- **proxyHost**: `""`
+- **proxyRemovePrefix**: `false`
+- **tlsOptions**: `{ "enabled": false, "type": "CERT", "pfxPath": "", "certPath": "", "keyPath": "", "caPath": "", "passphrase": "" }`
+- **cors**: `true`
+- **headers**: `[{ "key": "Content-Type", "value": "application/json" }]`
+- **proxyReqHeaders**: `[]`
+- **proxyResHeaders**: `[]`
+- **callbacks**: `[]`
+
+All UUIDs (environment, routes, responses, data buckets) must be valid UUID v4 values.
+
+**Data buckets** — for each stateful/CRUD resource:
+
+- 2–3 seed records with realistic field values
+- Use the `id` field matching Mockoon's `"id"` property for CRUD lookup
+
+**Routes:**
+
+1. **CRUD routes** — for mutable resources:
+
+   ```json
+   {
+     "type": "crud",
+     "endpoint": "{resource}",
+     "responses": [
+       {
+         "label": "CRUD {Resource}",
+         "statusCode": 200,
+         "headers": [{ "key": "Content-Type", "value": "application/json" }],
+         "bodyType": "DATABUCKET",
+         "databucketID": "{resource-bucket-id}"
+       }
+     ]
+   }
+   ```
+
+2. **Static routes** — for read-only endpoints:
+   - List endpoints returning JSON arrays
+   - Single-item endpoints using `{{urlParam 'id'}}` interpolation
+
+3. **Error scenarios** — triggered via `X-Test-Scenario` header:
+   - `unauthorized` → 401
+   - `not-found` → 404
+   - `rate-limit` → 429 with `Retry-After` header
+   - `server-error` → 500
+
+4. **Catch-all** — `*` endpoint returning 500 when `X-Test-Scenario: server-error`
+
+**Every route must have:** `type`, `documentation`, `responseMode: null`, `streamingMode: null`, `streamingInterval: 0`
+
+**Every response must have:** `latency: 0`, `bodyType`, `databucketID`, `filePath: ""`, `sendFileAsBody: false`, `rules`, `rulesOperator: "OR"`, `disableTemplating: false`, `fallbackTo404: false`, `default`, `crudKey: "id"`, `callbacks: []`, a `Content-Type` header, and a non-empty `label`
+
+**Every rule must have:** `target`, `modifier`, `value`, `operator`, `invert: false`
+
+### Step 4: Generate scenario README
+
+Create `mocks/{provider}/{scenario}/README.md` with:
+
+- Title and one-line description
+- Quick start with both methods: `erp-kit mock start` (proxy) and direct `npx @mockoon/cli start`
+- Endpoints table (method, path, scenarios)
+- CRUD workflow example with curl commands using proxy URL (`http://localhost:3000/{provider}/{scenario}/...`)
+- Error scenario examples
+- Test data description
+
+### Step 5: Validate
+
+```bash
+erp-kit mock validate
+```
+
+Fix any failures before finishing.

package/src/app.ts

@@ -0,0 +1 @@
+export { createContext } from "./modules/shared/createContext";

package/src/cli.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { z } from "zod";
+import { defineCommand, runMain, arg } from "politty";
+import { runCheck } from "./commands/check.js";
+import { runSyncCheck, formatSyncCheckReport } from "./commands/sync-check.js";
+import { runScaffold, ALL_TYPES, isModuleType, type ScaffoldType } from "./commands/scaffold.js";
+import { runInit } from "./commands/init.js";
+import { mockCommand } from "./commands/mock/index.js";
+
+const cwd = process.cwd();
+
+const rootArgs = z.object({
+  modulesRoot: arg(z.string().optional(), {
+    alias: "m",
+    description: "Path to modules directory",
+  }),
+  appRoot: arg(z.string().optional(), {
+    alias: "a",
+    description: "Path to app-compose directory (apps/ or examples/)",
+  }),
+});
+
+function requireRoot(args: { modulesRoot?: string; appRoot?: string }) {
+  const paths = { modulesRoot: args.modulesRoot, appRoot: args.appRoot };
+  if (!paths.modulesRoot && !paths.appRoot) {
+    console.error("At least one of --modules-root or --app-root is required.");
+    process.exit(2);
+  }
+  return paths;
+}
+
+const checkCommand = defineCommand({
+  name: "check",
+  description: "Validate docs against schemas",
+  args: rootArgs,
+  run: async (args) => {
+    const paths = requireRoot(args);
+    const exitCode = await runCheck(paths, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const syncCheckCommand = defineCommand({
+  name: "sync-check",
+  description: "Validate source <-> doc correspondence",
+  args: rootArgs,
+  run: async (args) => {
+    const paths = requireRoot(args);
+    const result = await runSyncCheck(paths, cwd);
+    console.log(formatSyncCheckReport(result));
+    process.exit(result.exitCode);
+  },
+});
+
+const scaffoldCommand = defineCommand({
+  name: "scaffold",
+  description: "Generate doc file from schema template",
+  args: rootArgs.extend({
+    type: arg(z.enum(ALL_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Scaffold type (${ALL_TYPES.join(", ")})`,
+    }),
+    parent: arg(z.string(), {
+      positional: true,
+      description: "Parent name (module or app name)",
+    }),
+    name: arg(z.string().optional(), {
+      positional: true,
+      description: "Item name (required for most types)",
+    }),
+  }),
+  run: async (args) => {
+    const paths = requireRoot(args);
+    const root = isModuleType(args.type) ? paths.modulesRoot : paths.appRoot;
+    if (!root) {
+      console.error(
+        `--${isModuleType(args.type) ? "modules-root" : "app-root"} is required for scaffold type "${args.type}".`,
+      );
+      process.exit(2);
+    }
+    const exitCode = await runScaffold(
+      args.type as ScaffoldType,
+      args.parent,
+      args.name,
+      root,
+      cwd,
+    );
+    process.exit(exitCode);
+  },
+});
+
+const initCommand = defineCommand({
+  name: "init",
+  description: "Set up consumer repo (skills, rules)",
+  args: z.object({
+    force: arg(z.boolean().default(false), {
+      alias: "f",
+      description: "Overwrite existing skills and rules",
+    }),
+  }),
+  run: (args) => {
+    const exitCode = runInit(cwd, args.force);
+    process.exit(exitCode);
+  },
+});
+
+const main = defineCommand({
+  name: "erp-kit",
+  description: "Documentation validation and scaffolding tool",
+  subCommands: {
+    check: checkCommand,
+    "sync-check": syncCheckCommand,
+    scaffold: scaffoldCommand,
+    init: initCommand,
+    mock: mockCommand,
+  },
+});
+
+void runMain(main);

package/src/commands/check.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { buildCheckTargets } from "./check.js";
+
+describe("buildCheckTargets", () => {
+  it("generates module targets when modulesRoot is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: undefined });
+    expect(targets).toEqual([
+      { glob: "modules/[a-zA-Z]*/docs/features/*.md", schemaKey: "feature" },
+      { glob: "modules/[a-zA-Z]*/docs/commands/*.md", schemaKey: "command" },
+      { glob: "modules/[a-zA-Z]*/docs/models/*.md", schemaKey: "model" },
+      { glob: "modules/[a-zA-Z]*/README.md", schemaKey: "module" },
+    ]);
+  });
+
+  it("generates app-compose targets when appRoot is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: "apps" });
+    expect(targets[0].glob).toBe("apps/[a-zA-Z]*/README.md");
+    expect(targets).toHaveLength(6);
+  });
+
+  it("generates both when both roots are set", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples" });
+    expect(targets).toHaveLength(10);
+  });
+
+  it("returns empty when neither root is set", () => {
+    const targets = buildCheckTargets({ modulesRoot: undefined, appRoot: undefined });
+    expect(targets).toHaveLength(0);
+  });
+});

package/src/commands/check.ts

@@ -0,0 +1,66 @@
+import { runMdschema } from "../mdschema.js";
+import { ALL_SCHEMAS } from "../schemas.js";
+export interface CheckTarget {
+  glob: string;
+  schemaKey: string;
+}
+
+export function buildCheckTargets(config: {
+  modulesRoot?: string;
+  appRoot?: string;
+}): CheckTarget[] {
+  const targets: CheckTarget[] = [];
+
+  if (config.modulesRoot) {
+    const m = config.modulesRoot;
+    targets.push(
+      { glob: `${m}/[a-zA-Z]*/docs/features/*.md`, schemaKey: "feature" },
+      { glob: `${m}/[a-zA-Z]*/docs/commands/*.md`, schemaKey: "command" },
+      { glob: `${m}/[a-zA-Z]*/docs/models/*.md`, schemaKey: "model" },
+      { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
+    );
+  }
+
+  if (config.appRoot) {
+    const a = config.appRoot;
+    targets.push(
+      { glob: `${a}/[a-zA-Z]*/README.md`, schemaKey: "requirements" },
+      { glob: `${a}/[a-zA-Z]*/docs/actors/*.md`, schemaKey: "actors" },
+      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/README.md`, schemaKey: "business-flow" },
+      { glob: `${a}/[a-zA-Z]*/docs/business-flow/*/story/*.md`, schemaKey: "story" },
+      { glob: `${a}/[a-zA-Z]*/docs/screen/*.md`, schemaKey: "screen" },
+      { glob: `${a}/[a-zA-Z]*/docs/resolver/*.md`, schemaKey: "resolver" },
+    );
+  }
+
+  return targets;
+}
+
+export async function runCheck(
+  config: { modulesRoot?: string; appRoot?: string },
+  cwd: string,
+): Promise<number> {
+  const targets = buildCheckTargets(config);
+
+  const results = await Promise.all(
+    targets.map(async (target) => {
+      const schemaPath = ALL_SCHEMAS[target.schemaKey];
+      if (!schemaPath) {
+        console.error(`Unknown schema key: ${target.schemaKey}`);
+        return 2;
+      }
+      const { exitCode, stdout, stderr } = await runMdschema(
+        ["check", target.glob, "--schema", schemaPath],
+        cwd,
+      );
+
+      if (stdout.trim()) console.log(stdout);
+      if (stderr.trim()) console.error(stderr);
+
+      return exitCode;
+    }),
+  );
+
+  if (results.includes(2)) return 2;
+  return results.some((code) => code !== 0) ? 1 : 0;
+}

package/src/commands/init.test.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { runInit } from "./init.js";
+
+describe("runInit", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "init-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("copies framework skills to .agents/skills/", () => {
+    runInit(tmpDir, false);
+    const skillPath = path.join(tmpDir, ".agents", "skills", "1-module-docs", "SKILL.md");
+    expect(fs.existsSync(skillPath)).toBe(true);
+  });
+
+  it("does not overwrite project-specific skills", () => {
+    const customSkillDir = path.join(tmpDir, ".agents", "skills", "my-custom-skill");
+    fs.mkdirSync(customSkillDir, { recursive: true });
+    fs.writeFileSync(path.join(customSkillDir, "SKILL.md"), "# Custom");
+    runInit(tmpDir, false);
+    const content = fs.readFileSync(path.join(customSkillDir, "SKILL.md"), "utf-8");
+    expect(content).toBe("# Custom");
+  });
+
+  it("does not overwrite existing framework skills", () => {
+    const skillDir = path.join(tmpDir, ".agents", "skills", "1-module-docs");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), "# Customized");
+    runInit(tmpDir, false);
+    const content = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf-8");
+    expect(content).toBe("# Customized");
+  });
+
+  it("overwrites existing framework skills with --force", () => {
+    const skillDir = path.join(tmpDir, ".agents", "skills", "1-module-docs");
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), "# Customized");
+    runInit(tmpDir, true);
+    const content = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf-8");
+    expect(content).not.toBe("# Customized");
+  });
+
+  it("copies framework rules to .agents/rules/", () => {
+    runInit(tmpDir, false);
+    const rulePath = path.join(tmpDir, ".agents", "rules", "module-development", "structure.md");
+    expect(fs.existsSync(rulePath)).toBe(true);
+    // Also check nested subdirectory
+    const nestedRule = path.join(tmpDir, ".agents", "rules", "app-compose", "frontend", "auth.md");
+    expect(fs.existsSync(nestedRule)).toBe(true);
+  });
+
+  it("does not overwrite existing rules", () => {
+    const ruleDir = path.join(tmpDir, ".agents", "rules", "module-development");
+    fs.mkdirSync(ruleDir, { recursive: true });
+    fs.writeFileSync(path.join(ruleDir, "structure.md"), "# Custom Rule");
+    runInit(tmpDir, false);
+    const content = fs.readFileSync(path.join(ruleDir, "structure.md"), "utf-8");
+    expect(content).toBe("# Custom Rule");
+  });
+
+  it("overwrites existing rules with --force", () => {
+    const ruleDir = path.join(tmpDir, ".agents", "rules", "module-development");
+    fs.mkdirSync(ruleDir, { recursive: true });
+    fs.writeFileSync(path.join(ruleDir, "structure.md"), "# Custom Rule");
+    runInit(tmpDir, true);
+    const content = fs.readFileSync(path.join(ruleDir, "structure.md"), "utf-8");
+    expect(content).not.toBe("# Custom Rule");
+  });
+});

package/src/commands/init.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { PACKAGE_ROOT } from "../util.js";
+
+const SKILLS_SRC = path.join(PACKAGE_ROOT, "skills");
+const RULES_SRC = path.join(PACKAGE_ROOT, "rules");
+
+const FRAMEWORK_SKILLS = [
+  "1-module-docs",
+  "2-module-feature-breakdown",
+  "3-module-doc-review",
+  "4-module-tdd-implementation",
+  "5-module-implementation-review",
+  "app-compose-1-requirement-analysis",
+  "app-compose-2-requirements-breakdown",
+  "app-compose-3-doc-review",
+  "app-compose-4-design-mock",
+  "app-compose-5-design-mock-review",
+  "app-compose-6-implementation-spec",
+  "mock-scenario",
+];
+
+export function runInit(cwd: string, force: boolean): number {
+  console.log(chalk.bold("erp-kit init\n"));
+
+  const skillsDest = path.join(cwd, ".agents", "skills");
+  let copiedCount = 0;
+  let skippedCount = 0;
+  for (const skill of FRAMEWORK_SKILLS) {
+    const srcSkill = path.join(SKILLS_SRC, skill, "SKILL.md");
+    const destDir = path.join(skillsDest, skill);
+    const destSkill = path.join(destDir, "SKILL.md");
+
+    if (!fs.existsSync(srcSkill)) continue;
+    if (!force && fs.existsSync(destSkill)) {
+      console.log(chalk.yellow(`  Skipped ${skill}/SKILL.md (already exists)`));
+      skippedCount++;
+      continue;
+    }
+
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(srcSkill, destSkill);
+    copiedCount++;
+  }
+  console.log(chalk.green(`  Copied ${copiedCount} framework skills to .agents/skills/`));
+  if (skippedCount > 0) {
+    console.log(
+      chalk.yellow(`  Skipped ${skippedCount} existing skills (use --force to overwrite)`),
+    );
+  }
+
+  const rulesDest = path.join(cwd, ".agents", "rules");
+  let rulesCount = 0;
+  let rulesSkipped = 0;
+  if (fs.existsSync(RULES_SRC)) {
+    const copyRulesRecursive = (srcDir: string, destDir: string) => {
+      for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+          copyRulesRecursive(srcPath, destPath);
+        } else {
+          if (!force && fs.existsSync(destPath)) {
+            const rel = path.relative(rulesDest, destPath);
+            console.log(chalk.yellow(`  Skipped rule ${rel} (already exists)`));
+            rulesSkipped++;
+            continue;
+          }
+          fs.mkdirSync(destDir, { recursive: true });
+          fs.copyFileSync(srcPath, destPath);
+          rulesCount++;
+        }
+      }
+    };
+    copyRulesRecursive(RULES_SRC, rulesDest);
+  }
+  console.log(chalk.green(`  Copied ${rulesCount} framework rules to .agents/rules/`));
+  if (rulesSkipped > 0) {
+    console.log(
+      chalk.yellow(`  Skipped ${rulesSkipped} existing rules (use --force to overwrite)`),
+    );
+  }
+
+  console.log(chalk.bold.green("\nDone! Run `erp-kit check` to validate your docs."));
+  return 0;
+}

package/src/commands/mock/index.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { runMockStart } from "./start.js";
+import { runMockValidate } from "./validate.js";
+
+const startCommand = defineCommand({
+  name: "start",
+  description: "Start mock API servers with reverse proxy",
+  args: z.object({
+    mocksRoot: arg(z.string().default("./mocks"), {
+      description: "Path to mocks directory",
+    }),
+    port: arg(z.coerce.number().default(3000), {
+      alias: "p",
+      description: "Reverse proxy port",
+    }),
+    filter: arg(z.array(z.string()).default([]), {
+      positional: true,
+      description: "Filter by provider or provider/scenario",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
+    process.exit(exitCode);
+  },
+});
+
+const validateCommand = defineCommand({
+  name: "validate",
+  description: "Validate mock scenario configs",
+  args: z.object({
+    mocksRoot: arg(z.string().default("./mocks"), {
+      description: "Path to mocks directory",
+    }),
+    paths: arg(z.array(z.string()).default([]), {
+      positional: true,
+      description: "Specific scenario paths to validate",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runMockValidate(args.mocksRoot, args.paths);
+    process.exit(exitCode);
+  },
+});
+
+export const mockCommand = defineCommand({
+  name: "mock",
+  description: "Mock API server management",
+  subCommands: {
+    start: startCommand,
+    validate: validateCommand,
+  },
+});