@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/commands/mock/start.ts

@@ -0,0 +1,179 @@
+import { createServer, request as httpRequest } from "node:http";
+import { createServer as createNetServer } from "node:net";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, relative, join } from "node:path";
+import { createMockServer, type MockServer } from "../../mockServer.js";
+
+interface MockEntry {
+  provider: string;
+  scenario: string;
+  mockPath: string;
+}
+
+interface RunningMock {
+  server: MockServer;
+  route: string;
+  provider: string;
+  scenario: string;
+}
+
+function readdirSafe(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+function discoverMocks(mocksDir: string, filters: string[]): MockEntry[] {
+  const mocks: MockEntry[] = [];
+
+  for (const provider of readdirSafe(mocksDir)) {
+    const providerDir = join(mocksDir, provider);
+    for (const scenario of readdirSafe(providerDir)) {
+      const mockPath = join(providerDir, scenario, "mock.json");
+      if (!existsSync(mockPath)) continue;
+      mocks.push({ provider, scenario, mockPath });
+    }
+  }
+
+  if (filters.length === 0) return mocks;
+
+  return mocks.filter(({ provider, scenario }) =>
+    filters.some((f) => f === provider || f === `${provider}/${scenario}`),
+  );
+}
+
+// Mockoon doesn't expose the actual listening port, so we can't use port 0 with readback.
+// This has a minor TOCTOU window between closing this server and Mockoon binding.
+function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createNetServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => resolve(port));
+    });
+    srv.on("error", reject);
+  });
+}
+
+async function startMock(mock: MockEntry): Promise<RunningMock> {
+  const port = await findFreePort();
+  const server = await createMockServer(mock.mockPath, port);
+  const route = `/${mock.provider}/${mock.scenario}`;
+  return { server, route, provider: mock.provider, scenario: mock.scenario };
+}
+
+function createProxy(routeTable: Map<string, RunningMock>) {
+  return createServer((req, res) => {
+    const match = req.url?.match(/^\/([^/?]+)\/([^/?]+)(\/[^?]*)?(\?.*)?$/);
+    if (!match) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not found. Use /{provider}/{scenario}/..." }));
+      return;
+    }
+
+    const [, provider, scenario] = match;
+    const key = `/${provider}/${scenario}`;
+    const target = routeTable.get(key);
+
+    if (!target) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: `Unknown route: ${key}`,
+          available: [...routeTable.keys()],
+        }),
+      );
+      return;
+    }
+
+    // Strip the /{provider}/{scenario} prefix, keep the rest including query string
+    const downstream = (req.url ?? "/").slice(key.length) || "/";
+
+    const proxyReq = httpRequest(
+      {
+        hostname: "127.0.0.1",
+        port: target.server.port,
+        path: downstream,
+        method: req.method,
+        headers: { ...req.headers, host: `127.0.0.1:${target.server.port}` },
+      },
+      (proxyRes) => {
+        res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+        proxyRes.pipe(res);
+      },
+    );
+
+    proxyReq.on("error", (err) => {
+      if (!res.headersSent) {
+        res.writeHead(502, { "Content-Type": "application/json" });
+      }
+      res.end(JSON.stringify({ error: "Bad gateway", detail: err.message }));
+    });
+
+    req.pipe(proxyReq);
+  });
+}
+
+export async function runMockStart(
+  mocksRoot: string,
+  filters: string[],
+  port: number,
+): Promise<number> {
+  const mocksDir = resolve(mocksRoot);
+  const mocks = discoverMocks(mocksDir, filters);
+
+  if (mocks.length === 0) {
+    console.error("No matching mocks found.");
+    if (filters.length > 0) {
+      console.error(`Filters: ${filters.join(", ")}`);
+      console.error(`Available mocks are under: ${relative(process.cwd(), mocksDir)}/`);
+    }
+    return 1;
+  }
+
+  console.log(`Starting ${mocks.length} mock(s)...\n`);
+
+  const running: RunningMock[] = [];
+  for (const mock of mocks) {
+    const info = await startMock(mock);
+    running.push(info);
+  }
+
+  const routeTable = new Map<string, RunningMock>();
+  for (const r of running) {
+    routeTable.set(r.route, r);
+  }
+
+  console.log("Route table:");
+  console.log("\u2500".repeat(50));
+  for (const [route, { server }] of routeTable) {
+    console.log(`  ${route}  \u2192  127.0.0.1:${server.port}`);
+  }
+  console.log("\u2500".repeat(50));
+
+  const proxy = createProxy(routeTable);
+  proxy.listen(port, () => {
+    console.log(`\nReverse proxy listening on http://localhost:${port}`);
+    console.log("Press Ctrl+C to stop all mocks.\n");
+  });
+
+  function shutdown() {
+    console.log("\nShutting down...");
+    proxy.close();
+    for (const { server } of running) {
+      void server.stop();
+    }
+    process.exit(0);
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Block until signal handler calls process.exit
+  return new Promise<number>(() => void 0);
+}

package/src/commands/mock/validate.test.ts

@@ -0,0 +1,185 @@
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { runMockValidate } from "./validate.js";
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "mock-validate-"));
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  vi.spyOn(console, "log").mockImplementation(() => {});
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+function minimalMockJson() {
+  return {
+    uuid: "f7a1b2c3-d4e5-4f6a-8b7c-9d0e1f2a3b4c",
+    lastMigration: 32,
+    name: "Test API",
+    endpointPrefix: "",
+    port: 3000,
+    hostname: "0.0.0.0",
+    latency: 0,
+    folders: [],
+    rootChildren: [{ type: "route", uuid: "c5d8e2f1-3a4b-4c6d-9e7f-1a2b3c4d5e6f" }],
+    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: [],
+    data: [
+      {
+        uuid: "a3e72f41-8b56-4c9d-a1e7-2f4b8c56d9e3",
+        id: "items",
+        name: "Items",
+        documentation: "",
+        value: "[]",
+      },
+    ],
+    routes: [
+      {
+        uuid: "c5d8e2f1-3a4b-4c6d-9e7f-1a2b3c4d5e6f",
+        type: "crud",
+        documentation: "CRUD items",
+        method: "",
+        endpoint: "items",
+        responseMode: null,
+        streamingMode: null,
+        streamingInterval: 0,
+        responses: [
+          {
+            uuid: "d6e9f3a2-4b5c-4d7e-8f1a-2b3c4d5e6f7a",
+            label: "CRUD Items",
+            statusCode: 200,
+            latency: 0,
+            headers: [{ key: "Content-Type", value: "application/json" }],
+            body: "",
+            bodyType: "DATABUCKET",
+            databucketID: "items",
+            filePath: "",
+            sendFileAsBody: false,
+            rules: [],
+            rulesOperator: "OR",
+            disableTemplating: false,
+            fallbackTo404: false,
+            default: true,
+            crudKey: "id",
+            callbacks: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+async function createScenario(
+  provider: string,
+  scenario: string,
+  mockData?: object,
+  includeReadme = true,
+) {
+  const scenarioDir = join(tempDir, provider, scenario);
+  await mkdir(scenarioDir, { recursive: true });
+  if (mockData) {
+    await writeFile(join(scenarioDir, "mock.json"), JSON.stringify(mockData));
+  }
+  if (includeReadme) {
+    await writeFile(join(scenarioDir, "README.md"), "# Test");
+  }
+}
+
+describe("runMockValidate", () => {
+  it("returns 0 for a valid scenario", async () => {
+    await createScenario("test-provider", "test-scenario", minimalMockJson());
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(0);
+  });
+
+  it("returns 1 when no scenarios found", async () => {
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("returns 1 when mock.json is missing", async () => {
+    await createScenario("test-provider", "test-scenario", undefined, true);
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("returns 1 when README.md is missing", async () => {
+    await createScenario("test-provider", "test-scenario", minimalMockJson(), false);
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("returns 1 for invalid JSON", async () => {
+    const scenarioDir = join(tempDir, "test-provider", "test-scenario");
+    await mkdir(scenarioDir, { recursive: true });
+    await writeFile(join(scenarioDir, "mock.json"), "not json");
+    await writeFile(join(scenarioDir, "README.md"), "# Test");
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("detects missing Content-Type header", async () => {
+    const data = minimalMockJson();
+    data.routes[0].responses[0].headers = [];
+    await createScenario("test-provider", "test-scenario", data);
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("detects empty response label", async () => {
+    const data = minimalMockJson();
+    data.routes[0].responses[0].label = "";
+    await createScenario("test-provider", "test-scenario", data);
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("detects broken databucket reference", async () => {
+    const data = minimalMockJson();
+    data.routes[0].responses[0].databucketID = "nonexistent";
+    await createScenario("test-provider", "test-scenario", data);
+    const exitCode = await runMockValidate(tempDir, []);
+    expect(exitCode).toBe(1);
+  });
+
+  it("validates specific paths when provided", async () => {
+    await createScenario("provider-a", "scenario-a", minimalMockJson());
+    await createScenario("provider-b", "scenario-b", minimalMockJson());
+
+    const exitCode = await runMockValidate(tempDir, [join(tempDir, "provider-a", "scenario-a")]);
+    expect(exitCode).toBe(0);
+  });
+
+  it("can be called multiple times without state leaking", async () => {
+    // First call: failing scenario
+    await createScenario("bad", "scenario", undefined, true);
+    const first = await runMockValidate(tempDir, [join(tempDir, "bad", "scenario")]);
+    expect(first).toBe(1);
+
+    // Second call: valid scenario — failures counter must be reset
+    await createScenario("good", "scenario", minimalMockJson());
+    const second = await runMockValidate(tempDir, [join(tempDir, "good", "scenario")]);
+    expect(second).toBe(0);
+  });
+});

package/src/commands/mock/validate.ts

@@ -0,0 +1,198 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve, relative, dirname, basename } from "node:path";
+import chalk from "chalk";
+
+interface ValidationContext {
+  failures: number;
+}
+
+function pass(msg: string) {
+  console.log(chalk.green(`\u2713 ${msg}`));
+}
+
+function fail(ctx: ValidationContext, msg: string) {
+  console.log(chalk.red(`\u2717 ${msg}`));
+  ctx.failures++;
+}
+
+async function subdirs(dir: string): Promise<string[]> {
+  const entries = await readdir(dir);
+  const dirs: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    const s = await stat(full);
+    if (s.isDirectory()) dirs.push(entry);
+  }
+  return dirs.sort();
+}
+
+function checkStructure(ctx: ValidationContext, entries: string[], label: string): boolean {
+  if (entries.includes("README.md")) {
+    pass(`${label}: has README.md`);
+  } else {
+    fail(ctx, `${label}: missing README.md`);
+  }
+
+  if (entries.includes("mock.json")) {
+    pass(`${label}: has mock.json`);
+    return true;
+  }
+  fail(ctx, `${label}: missing mock.json`);
+  return false;
+}
+
+async function checkSchema(ctx: ValidationContext, data: MockoonData, label: string) {
+  const commons = await import("@mockoon/commons");
+  // EnvironmentSchemaNoFix is a Joi schema typed as `any` in @mockoon/commons
+  const schema = commons.EnvironmentSchemaNoFix as {
+    validate: (
+      value: unknown,
+      options?: { abortEarly?: boolean },
+    ) => { error?: { details: { message: string }[] } };
+  };
+  const result = schema.validate(data, { abortEarly: false });
+  if (!result.error) {
+    pass(`${label}: valid Mockoon schema`);
+  } else {
+    for (const detail of result.error.details) {
+      fail(ctx, `${label}: schema — ${detail.message}`);
+    }
+  }
+}
+
+interface MockoonRoute {
+  uuid: string;
+  responses?: MockoonResponse[];
+}
+
+interface MockoonResponse {
+  uuid: string;
+  label?: string;
+  headers?: { key: string; value: string }[];
+  bodyType?: string;
+  databucketID?: string;
+}
+
+interface MockoonData {
+  uuid?: string;
+  name?: string;
+  port?: number;
+  routes?: MockoonRoute[];
+  data?: { id: string }[];
+}
+
+function checkResponseQuality(ctx: ValidationContext, data: MockoonData, label: string) {
+  const routes = data.routes ?? [];
+  for (const route of routes) {
+    for (const resp of route.responses ?? []) {
+      const respLabel = `${label} \u2192 ${route.uuid}/${resp.uuid}`;
+      const headers = resp.headers ?? [];
+      const hasContentType = headers.some((h) => h.key.toLowerCase() === "content-type");
+      if (hasContentType) {
+        pass(`${respLabel}: has Content-Type`);
+      } else {
+        fail(ctx, `${respLabel}: missing Content-Type header`);
+      }
+      if (resp.label && resp.label.trim().length > 0) {
+        pass(`${respLabel}: has label "${resp.label}"`);
+      } else {
+        fail(ctx, `${respLabel}: missing or empty label`);
+      }
+    }
+  }
+}
+
+function checkDatabucketRefs(ctx: ValidationContext, data: MockoonData, label: string) {
+  const bucketIds = new Set((data.data ?? []).map((d) => d.id));
+  for (const route of data.routes ?? []) {
+    for (const resp of route.responses ?? []) {
+      if (resp.bodyType === "DATABUCKET") {
+        const respLabel = `${label} \u2192 ${route.uuid}/${resp.uuid}`;
+        if (resp.databucketID && bucketIds.has(resp.databucketID)) {
+          pass(`${respLabel}: databucket "${resp.databucketID}" exists`);
+        } else {
+          fail(ctx, `${respLabel}: databucketID "${resp.databucketID}" not found in data array`);
+        }
+      }
+    }
+  }
+}
+
+async function discoverAllScenarios(mocksDir: string): Promise<string[]> {
+  const scenarios: string[] = [];
+  const providers = await subdirs(mocksDir);
+  for (const provider of providers) {
+    const providerDir = join(mocksDir, provider);
+    for (const scenario of await subdirs(providerDir)) {
+      scenarios.push(`${provider}/${scenario}`);
+    }
+  }
+  return scenarios;
+}
+
+function resolveScenarioDir(arg: string): string {
+  const abs = resolve(arg);
+  if (basename(abs) === "mock.json") return dirname(abs);
+  return abs;
+}
+
+async function validateScenario(ctx: ValidationContext, scenarioDir: string, mocksDir: string) {
+  const label = relative(mocksDir, scenarioDir);
+  console.log(chalk.bold(`\n\u2500\u2500 ${label} \u2500\u2500`));
+
+  let entries: string[];
+  try {
+    entries = await readdir(scenarioDir);
+  } catch {
+    fail(ctx, `${label}: directory not found`);
+    return;
+  }
+
+  const hasMock = checkStructure(ctx, entries, label);
+  if (!hasMock) return;
+
+  const mockPath = join(scenarioDir, "mock.json");
+
+  let data: MockoonData;
+  try {
+    data = JSON.parse(await readFile(mockPath, "utf-8")) as MockoonData;
+  } catch (err: unknown) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    fail(ctx, `${label}: invalid JSON \u2014 ${errMsg}`);
+    return;
+  }
+
+  await checkSchema(ctx, data, label);
+  checkResponseQuality(ctx, data, label);
+  checkDatabucketRefs(ctx, data, label);
+}
+
+export async function runMockValidate(mocksRoot: string, paths: string[]): Promise<number> {
+  const ctx: ValidationContext = { failures: 0 };
+  const mocksDir = resolve(mocksRoot);
+
+  const targets =
+    paths.length > 0
+      ? paths.map(resolveScenarioDir)
+      : (await discoverAllScenarios(mocksDir)).map((s) => join(mocksDir, s));
+
+  if (targets.length === 0) {
+    fail(ctx, "No scenarios found under mocks/");
+    return 1;
+  }
+
+  console.log(chalk.bold("\nValidating mock configs...\n"));
+
+  for (const target of targets) {
+    await validateScenario(ctx, target, mocksDir);
+  }
+
+  console.log(chalk.bold("\n\u2500\u2500 summary \u2500\u2500"));
+  if (ctx.failures === 0) {
+    console.log(chalk.green("\u2713 All checks passed"));
+  } else {
+    console.log(chalk.red(`\u2717 ${ctx.failures} check(s) failed`));
+  }
+
+  return ctx.failures === 0 ? 0 : 1;
+}

package/src/commands/scaffold.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest";
+import { resolveScaffoldPath } from "./scaffold.js";
+
+describe("resolveScaffoldPath", () => {
+  // Module types
+  it("resolves module scaffold path", () => {
+    const result = resolveScaffoldPath("module", "inventory", undefined, "modules");
+    expect(result).toBe("modules/inventory/README.md");
+  });
+
+  it("resolves command scaffold path", () => {
+    const result = resolveScaffoldPath("command", "inventory", "CreateOrder", "modules");
+    expect(result).toBe("modules/inventory/docs/commands/CreateOrder.md");
+  });
+
+  it("resolves feature scaffold path", () => {
+    const result = resolveScaffoldPath("feature", "inventory", "stock-tracking", "modules");
+    expect(result).toBe("modules/inventory/docs/features/stock-tracking.md");
+  });
+
+  it("resolves model scaffold path", () => {
+    const result = resolveScaffoldPath("model", "inventory", "StockItem", "modules");
+    expect(result).toBe("modules/inventory/docs/models/StockItem.md");
+  });
+
+  // App-compose types
+  it("resolves requirements scaffold path", () => {
+    const result = resolveScaffoldPath("requirements", "my-app", undefined, "examples");
+    expect(result).toBe("examples/my-app/README.md");
+  });
+
+  it("resolves actors scaffold path", () => {
+    const result = resolveScaffoldPath("actors", "my-app", "admin", "examples");
+    expect(result).toBe("examples/my-app/docs/actors/admin.md");
+  });
+
+  it("resolves business-flow scaffold path", () => {
+    const result = resolveScaffoldPath("business-flow", "my-app", "onboarding", "examples");
+    expect(result).toBe("examples/my-app/docs/business-flow/onboarding/README.md");
+  });
+
+  it("resolves story scaffold path with flow/name format", () => {
+    const result = resolveScaffoldPath(
+      "story",
+      "my-app",
+      "onboarding/admin--create-user",
+      "examples",
+    );
+    expect(result).toBe(
+      "examples/my-app/docs/business-flow/onboarding/story/admin--create-user.md",
+    );
+  });
+
+  it("resolves screen scaffold path", () => {
+    const result = resolveScaffoldPath("screen", "my-app", "supplier-list", "examples");
+    expect(result).toBe("examples/my-app/docs/screen/supplier-list.md");
+  });
+
+  it("resolves resolver scaffold path", () => {
+    const result = resolveScaffoldPath("resolver", "my-app", "create-supplier", "examples");
+    expect(result).toBe("examples/my-app/docs/resolver/create-supplier.md");
+  });
+
+  // Validation
+  it("throws when name is required but missing", () => {
+    expect(() => resolveScaffoldPath("command", "inventory", undefined, "modules")).toThrow(
+      "Name is required",
+    );
+  });
+
+  it("throws when story name is not flow/name format", () => {
+    expect(() => resolveScaffoldPath("story", "my-app", "bad-name", "examples")).toThrow(
+      "Story name must be",
+    );
+  });
+});