@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/generator/generate-code.ts

@@ -1,231 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
-import { PACKAGE_ROOT, readErpKitVersion } from "../util";
-import { parseCommandDoc, errorCodeToClassName, type ParsedCommandDoc } from "./parse-command-doc";
-
-export function moduleNameToPrefix(moduleName: string): string {
-  return moduleName.toUpperCase().replace(/-/g, "_");
-}
-
-export function generateErrors(moduleName: string, docs: ParsedCommandDoc[]): string {
-  const seen = new Set<string>();
-  const lines: string[] = [];
-  const prefix = moduleNameToPrefix(moduleName);
-
-  for (const doc of docs) {
-    for (const error of doc.errors) {
-      if (seen.has(error.code)) continue;
-      seen.add(error.code);
-
-      const className = errorCodeToClassName(error.code);
-      const prefixedCode = `${prefix}_${error.code}`;
-      lines.push(`export const ${className} = createDomainError(`);
-      lines.push(`  "${className}", "${prefixedCode}",`);
-      const escapedDesc = error.description.replace(/`/g, "'");
-      lines.push(`  (identifier: string) => \`${escapedDesc}: \${identifier}\`,`);
-      lines.push(`);`);
-      lines.push(``);
-    }
-  }
-
-  if (lines.length === 0) return "";
-
-  return `// @generated — do not edit
-import { createDomainError } from "../../../shared";
-
-${lines.join("\n")}`;
-}
-
-export function generateCommandStub(doc: ParsedCommandDoc): string {
-  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
-  const inputType = `${pascal}Input`;
-
-  return `import { ok, type CommandContext } from "../../../shared";
-import type { Transaction } from "../generated/kysely-tailordb";
-
-export interface ${inputType} {
-  // TODO: define input fields
-}
-
-export async function run(db: Transaction, input: ${inputType}, ctx: CommandContext) {
-  // TODO: implement
-  return ok({});
-}
-`;
-}
-
-export function generateTestStub(doc: ParsedCommandDoc): string {
-  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
-
-  return `import { describe, expect, it } from "vitest";
-import { createMockDb } from "../../../testing/index";
-import type { CommandContext } from "../../../shared";
-import type { Transaction } from "../generated/kysely-tailordb";
-import { run, ${pascal}Input } from "./${doc.commandName}";
-
-describe("${doc.commandName} - test scenario", () => {
-  const ctx: CommandContext = {
-    actorId: "test-actor",
-    permissions: ["TODO:${doc.commandName}"],
-  };
-
-  it("should be implemented", async () => {
-    const { db } = createMockDb<Transaction>();
-    const result = await run(db, {} as ${pascal}Input, ctx);
-    expect(result.ok).toBe(true);
-  });
-});
-`;
-}
-
-export function generateCommandShell(doc: ParsedCommandDoc): string {
-  const lines: string[] = [
-    `// @generated — do not edit`,
-    `import { defineCommand } from "../../../shared";`,
-    `import { permissions } from "../lib/permissions.generated";`,
-    `import { run } from "./${doc.commandName}";`,
-    ``,
-    `export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
-    ``,
-  ];
-
-  return lines.join("\n");
-}
-
-export function generateQueryShell(doc: ParsedCommandDoc): string {
-  const lines: string[] = [
-    `// @generated — do not edit`,
-    `import { defineQuery } from "../../../shared";`,
-    `import { run } from "./${doc.commandName}";`,
-    ``,
-    `export const ${doc.commandName} = defineQuery(run);`,
-    ``,
-  ];
-
-  return lines.join("\n");
-}
-
-export function generateQueryStub(doc: ParsedCommandDoc): string {
-  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
-  const inputType = `${pascal}Input`;
-
-  return `import type { ReadonlyDB } from "../../../shared";
-import type { DB } from "../generated/kysely-tailordb";
-
-export interface ${inputType} {
-  // TODO: define input fields
-}
-
-export async function run(db: ReadonlyDB<DB>, input: ${inputType}) {
-  // TODO: implement
-  return {};
-}
-`;
-}
-
-export function generateQueryTestStub(doc: ParsedCommandDoc): string {
-  const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
-  const inputType = `${pascal}Input`;
-
-  return `import { describe, expect, it } from "vitest";
-import { createMockDb } from "../../../testing/index";
-import type { DB } from "../generated/kysely-tailordb";
-import { run, type ${inputType} } from "./${doc.commandName}";
-
-describe("${doc.commandName}", () => {
-  it("should be implemented", async () => {
-    const { db } = createMockDb<DB>();
-    const result = await run(db, {} as ${inputType});
-    expect(result).toBeDefined();
-  });
-});
-`;
-}
-
-export function generateDbStub(modelName: string): string {
-  return `import { db, unsafeAllowAllGqlPermission, unsafeAllowAllTypePermission } from "@tailor-platform/sdk";
-
-export const ${modelName} = db
-  .type("${modelName.charAt(0).toUpperCase() + modelName.slice(1)}", {
-    // TODO: define fields
-    ...db.fields.timestamps(),
-  })
-  .permission(unsafeAllowAllTypePermission)
-  .gqlPermission(unsafeAllowAllGqlPermission);
-`;
-}
-
-export function generatePermissions(moduleName: string, commandNames: string[]): string {
-  const sorted = [...commandNames].sort();
-  const entries = sorted.map((name) => `  "${name}",`).join("\n");
-
-  return `// @generated — do not edit
-import { definePermissions } from "../../../shared";
-
-export const { permissions, own, all } = definePermissions("${moduleName}", [
-${entries}
-] as const);
-`;
-}
-
-// npm renames .gitignore during pack (npm/cli#5756).
-// prepack copies .gitignore to __dot__gitignore to preserve it.
-export function copyTemplateDir(
-  srcDir: string,
-  destDir: string,
-  replacements: Record<string, string>,
-  placeholderFiles: Set<string>,
-): void {
-  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-    const srcPath = path.join(srcDir, entry.name);
-    const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
-    const destPath = path.join(destDir, destName);
-
-    if (entry.isDirectory()) {
-      fs.mkdirSync(destPath, { recursive: true });
-      copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
-    } else {
-      if (fs.existsSync(destPath)) continue;
-      fs.mkdirSync(path.dirname(destPath), { recursive: true });
-      if (placeholderFiles.has(entry.name)) {
-        let content = fs.readFileSync(srcPath, "utf-8");
-        for (const [from, to] of Object.entries(replacements)) {
-          content = content.replaceAll(from, to);
-        }
-        fs.writeFileSync(destPath, content);
-      } else {
-        fs.copyFileSync(srcPath, destPath);
-      }
-    }
-  }
-}
-
-export function scaffoldModuleBoilerplate(moduleDir: string, moduleName: string): void {
-  const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "module");
-  const replacements = { "template-module": moduleName };
-  const placeholderFiles = new Set(["permissions.ts", "tailor.config.ts"]);
-  copyTemplateDir(templateDir, moduleDir, replacements, placeholderFiles);
-}
-
-export function scaffoldAppBoilerplate(appDir: string, appName: string): void {
-  const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
-  const erpKitVersion = readErpKitVersion();
-  const replacements = {
-    "template-app-frontend": `${appName}-frontend`,
-    "template-app-backend": appName,
-    "template-app": appName,
-    '"workspace:*"': `"${erpKitVersion}"`,
-  };
-  const placeholderFiles = new Set(["package.json", "tailor.config.ts", "index.html"]);
-  copyTemplateDir(templateDir, appDir, replacements, placeholderFiles);
-}
-
-export function runGenerateAppCode(appPath: string): number {
-  const appName = path.basename(appPath);
-  scaffoldAppBoilerplate(appPath, appName);
-  console.log(`Generated boilerplate for ${appName}`);
-  return 0;
-}
+import { parseCommandDoc, type ParsedCommandDoc } from "./parse-command-doc";
+import { generateErrors } from "./generate-errors";
+import { generatePermissions } from "./generate-permissions";
+import { generateCommandShell, generateQueryShell } from "./generate-shells";
+import {
+  generateCommandStub,
+  generateTestStub,
+  generateQueryStub,
+  generateQueryTestStub,
+  generateDbStub,
+} from "./generate-stubs";
+import { scaffoldModuleBoilerplate } from "./scaffold";
 
 export function runGenerateCode(modulePath: string, moduleName: string): number {
   scaffoldModuleBoilerplate(modulePath, moduleName);

package/src/generator/generate-errors.ts

@@ -0,0 +1,34 @@
+import { errorCodeToClassName, type ParsedCommandDoc } from "./parse-command-doc";
+
+export function moduleNameToPrefix(moduleName: string): string {
+  return moduleName.toUpperCase().replace(/-/g, "_");
+}
+
+export function generateErrors(moduleName: string, docs: ParsedCommandDoc[]): string {
+  const seen = new Set<string>();
+  const lines: string[] = [];
+  const prefix = moduleNameToPrefix(moduleName);
+
+  for (const doc of docs) {
+    for (const error of doc.errors) {
+      if (seen.has(error.code)) continue;
+      seen.add(error.code);
+
+      const className = errorCodeToClassName(error.code);
+      const prefixedCode = `${prefix}_${error.code}`;
+      lines.push(`export const ${className} = createDomainError(`);
+      lines.push(`  "${className}", "${prefixedCode}",`);
+      const escapedDesc = error.description.replace(/`/g, "'");
+      lines.push(`  (identifier: string) => \`${escapedDesc}: \${identifier}\`,`);
+      lines.push(`);`);
+      lines.push(``);
+    }
+  }
+
+  if (lines.length === 0) return "";
+
+  return `// @generated — do not edit
+import { createDomainError } from "@tailor-platform/erp-kit/module";
+
+${lines.join("\n")}`;
+}

package/src/generator/generate-permissions.ts

@@ -0,0 +1,12 @@
+export function generatePermissions(moduleName: string, commandNames: string[]): string {
+  const sorted = [...commandNames].sort();
+  const entries = sorted.map((name) => `  "${name}",`).join("\n");
+
+  return `// @generated — do not edit
+import { definePermissions } from "@tailor-platform/erp-kit/module";
+
+export const { permissions, own, all } = definePermissions("${moduleName}", [
+${entries}
+] as const);
+`;
+}

package/src/generator/generate-shells.ts

@@ -0,0 +1,28 @@
+import type { ParsedCommandDoc } from "./parse-command-doc";
+
+export function generateCommandShell(doc: ParsedCommandDoc): string {
+  const lines: string[] = [
+    `// @generated — do not edit`,
+    `import { permissions } from "../lib/permissions.generated";`,
+    `import { run } from "./${doc.commandName}";`,
+    `import { defineCommand } from "@tailor-platform/erp-kit/module";`,
+    ``,
+    `export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
+    ``,
+  ];
+
+  return lines.join("\n");
+}
+
+export function generateQueryShell(doc: ParsedCommandDoc): string {
+  const lines: string[] = [
+    `// @generated — do not edit`,
+    `import { run } from "./${doc.commandName}";`,
+    `import { defineQuery } from "@tailor-platform/erp-kit/module";`,
+    ``,
+    `export const ${doc.commandName} = defineQuery(run);`,
+    ``,
+  ];
+
+  return lines.join("\n");
+}

package/src/generator/generate-stubs.ts

@@ -0,0 +1,31 @@
+import { renderStub } from "./stub-templates";
+
+export function generateCommandStub(doc: { commandName: string }): string {
+  return renderStub("command", doc.commandName);
+}
+
+export function generateTestStub(doc: { commandName: string }): string {
+  return renderStub("commandTest", doc.commandName);
+}
+
+export function generateQueryStub(doc: { commandName: string }): string {
+  return renderStub("query", doc.commandName);
+}
+
+export function generateQueryTestStub(doc: { commandName: string }): string {
+  return renderStub("queryTest", doc.commandName);
+}
+
+export function generateDbStub(modelName: string): string {
+  return renderStub("db", modelName);
+}
+
+export function generateResolverStub(resolverName: string): string {
+  return renderStub("resolver", resolverName);
+}
+
+export function generateResolverTestStub(resolverName: string): string {
+  return renderStub("resolverTest", resolverName);
+}
+
+export { renderStub, type StubType } from "./stub-templates";

package/src/generator/parse-resolver-doc.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { parseResolverDoc } from "./parse-resolver-doc";
+
+describe("parseResolverDoc", () => {
+  it("parses module commands from list", () => {
+    const markdown = `# createItem
+
+## Overview
+
+Creates a new item.
+
+## Modules Commands Used
+
+- \`item-management.createItem\` — Creates a new item record
+- \`primitives.getUnit\` — Validates UoM reference
+`;
+
+    const result = parseResolverDoc("createItem", markdown);
+
+    expect(result.resolverName).toBe("createItem");
+    expect(result.moduleCommands).toEqual([
+      { module: "item-management", command: "createItem" },
+      { module: "primitives", command: "getUnit" },
+    ]);
+  });
+
+  it("parses error codes from exception handling table", () => {
+    const markdown = `# activateItem
+
+## Overview
+
+Activates an item.
+
+## Modules Commands Used
+
+- \`item-management.activateItem\` — Changes item status
+
+## Exception Handling
+
+| Error Code     | Description                       |
+| -------------- | --------------------------------- |
+| ITEM_NOT_FOUND | The specified item does not exist |
+| INVALID_STATUS | Item is already in ACTIVE status  |
+`;
+
+    const result = parseResolverDoc("activateItem", markdown);
+
+    expect(result.errors).toEqual([
+      { code: "ITEM_NOT_FOUND", description: "The specified item does not exist" },
+      { code: "INVALID_STATUS", description: "Item is already in ACTIVE status" },
+    ]);
+  });
+
+  it("handles missing exception handling section", () => {
+    const markdown = `# getMyProfile
+
+## Overview
+
+Gets user profile.
+
+## Modules Commands Used
+
+- \`user-management.getMyProfile\` — Fetches profile
+`;
+
+    const result = parseResolverDoc("getMyProfile", markdown);
+
+    expect(result.resolverName).toBe("getMyProfile");
+    expect(result.moduleCommands).toEqual([{ module: "user-management", command: "getMyProfile" }]);
+    expect(result.errors).toEqual([]);
+  });
+
+  it("camelCases filename with leading uppercase", () => {
+    const markdown = `# CreateItem
+
+## Overview
+
+Creates an item.
+
+## Modules Commands Used
+
+- \`item-management.createItem\` — Creates item
+`;
+
+    const result = parseResolverDoc("CreateItem", markdown);
+
+    expect(result.resolverName).toBe("createItem");
+  });
+});

package/src/generator/parse-resolver-doc.ts

@@ -0,0 +1,125 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { toString } from "mdast-util-to-string";
+import type { Heading, RootContent, Root } from "mdast";
+
+export interface ParsedModuleCommand {
+  module: string;
+  command: string;
+}
+
+export interface ParsedResolverError {
+  code: string;
+  description: string;
+}
+
+export interface ParsedResolverDoc {
+  resolverName: string;
+  moduleCommands: ParsedModuleCommand[];
+  errors: ParsedResolverError[];
+}
+
+const MODULE_COMMAND_PATTERN = /([a-z][\w-]*)\.(\w+)/;
+const TABLE_ROW_PATTERN = /^\|(.+)\|(.+)\|$/;
+
+export function parseResolverDoc(fileName: string, markdown: string): ParsedResolverDoc {
+  const resolverName = fileName.charAt(0).toLowerCase() + fileName.slice(1);
+  const tree = fromMarkdown(markdown);
+
+  return {
+    resolverName,
+    moduleCommands: parseModuleCommands(tree),
+    errors: parseExceptionHandlingFromRaw(markdown),
+  };
+}
+
+function isHeading(node: RootContent): node is Heading {
+  return node.type === "heading";
+}
+
+function getNodesUnderHeading(tree: Root, headingText: string): RootContent[] {
+  const nodes: RootContent[] = [];
+  let collecting = false;
+
+  for (const node of tree.children) {
+    if (isHeading(node)) {
+      if (collecting) break;
+      if (node.depth === 2 && toString(node) === headingText) {
+        collecting = true;
+        continue;
+      }
+    }
+    if (collecting) {
+      nodes.push(node);
+    }
+  }
+
+  return nodes;
+}
+
+function parseModuleCommands(tree: Root): ParsedModuleCommand[] {
+  const nodes = getNodesUnderHeading(tree, "Modules Commands Used");
+  const commands: ParsedModuleCommand[] = [];
+
+  for (const node of nodes) {
+    if (node.type !== "list") continue;
+
+    for (const item of node.children) {
+      const text = toString(item);
+      const match = MODULE_COMMAND_PATTERN.exec(text);
+      if (match) {
+        commands.push({ module: match[1], command: match[2] });
+      }
+    }
+  }
+
+  return commands;
+}
+
+function parseExceptionHandlingFromRaw(markdown: string): ParsedResolverError[] {
+  const lines = markdown.split("\n");
+  const errors: ParsedResolverError[] = [];
+
+  // Find the "## Exception Handling" heading
+  let inSection = false;
+  let headerSkipped = false;
+  let separatorSkipped = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith("## Exception Handling")) {
+      inSection = true;
+      continue;
+    }
+
+    if (!inSection) continue;
+
+    // Stop at next heading
+    if (trimmed.startsWith("#")) break;
+
+    // Skip empty lines
+    if (!trimmed) continue;
+
+    // Parse table rows
+    const match = TABLE_ROW_PATTERN.exec(trimmed);
+    if (!match) continue;
+
+    // Skip header row and separator row
+    if (!headerSkipped) {
+      headerSkipped = true;
+      continue;
+    }
+    if (!separatorSkipped) {
+      separatorSkipped = true;
+      continue;
+    }
+
+    const code = match[1].trim();
+    const description = match[2].trim();
+    if (code) {
+      errors.push({ code, description });
+    }
+  }
+
+  return errors;
+}

package/src/generator/scaffold.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PACKAGE_ROOT, readErpKitVersion } from "../util";
+
+// npm renames .gitignore during pack (npm/cli#5756).
+// prepack copies .gitignore to __dot__gitignore to preserve it.
+export function copyTemplateDir(
+  srcDir: string,
+  destDir: string,
+  replacements: Record<string, string>,
+  placeholderFiles: Set<string>,
+): void {
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
+    const destPath = path.join(destDir, destName);
+
+    if (entry.name === "node_modules") continue;
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
+    } else {
+      if (fs.existsSync(destPath)) continue;
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      if (placeholderFiles.has(entry.name)) {
+        let content = fs.readFileSync(srcPath, "utf-8");
+        for (const [from, to] of Object.entries(replacements)) {
+          content = content.replaceAll(from, to);
+        }
+        fs.writeFileSync(destPath, content);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+export function scaffoldModuleBoilerplate(moduleDir: string, moduleName: string): void {
+  const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "module");
+  const replacements = { "template-module": moduleName };
+  const placeholderFiles = new Set(["permissions.ts", "tailor.config.ts"]);
+  copyTemplateDir(templateDir, moduleDir, replacements, placeholderFiles);
+}
+
+export function scaffoldAppBoilerplate(appDir: string, appName: string): void {
+  const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
+  const erpKitVersion = readErpKitVersion();
+  const replacements = {
+    "template-app-frontend": `${appName}-frontend`,
+    "template-app-backend": appName,
+    "template-app": appName,
+    '"workspace:*"': `"${erpKitVersion}"`,
+  };
+  const placeholderFiles = new Set(["package.json", "tailor.config.ts", "index.html"]);
+  copyTemplateDir(templateDir, appDir, replacements, placeholderFiles);
+}

package/src/generator/stub-templates.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { renderStub } from "./stub-templates";
+
+describe("renderStub", () => {
+  it("command: generates input interface and run function", () => {
+    const result = renderStub("command", "createItem");
+    expect(result).toContain("export interface CreateItemInput");
+    expect(result).toContain(
+      "export async function run(db: Transaction, input: CreateItemInput, ctx: CommandContext)",
+    );
+    expect(result).toContain("return ok({})");
+  });
+
+  it("commandTest: generates test with createMockDb", () => {
+    const result = renderStub("commandTest", "createItem");
+    expect(result).toContain('describe("createItem - test scenario"');
+    expect(result).toContain("createMockDb<Transaction>()");
+    expect(result).toContain("CreateItemInput");
+  });
+
+  it("query: generates ReadonlyDB-based stub", () => {
+    const result = renderStub("query", "getProduct");
+    expect(result).toContain("export interface GetProductInput");
+    expect(result).toContain("ReadonlyDB<DB>");
+  });
+
+  it("queryTest: generates test with DB type", () => {
+    const result = renderStub("queryTest", "getProduct");
+    expect(result).toContain('describe("getProduct"');
+    expect(result).toContain("createMockDb<DB>()");
+    expect(result).toContain("type GetProductInput");
+  });
+
+  it("db: generates model type definition", () => {
+    const result = renderStub("db", "item");
+    expect(result).toContain("export const item = db");
+    expect(result).toContain('.type("Item"');
+    expect(result).toContain("unsafeAllowAllTypePermission");
+  });
+
+  it("resolver: generates createResolver stub with SDK imports", () => {
+    const result = renderStub("resolver", "createItem");
+    expect(result).toContain("createResolver");
+    expect(result).toContain('name: "createItem"');
+    expect(result).toContain('operation: "mutation"');
+    expect(result).toContain('getDB("main-db")');
+  });
+
+  it("resolverTest: generates test that imports resolver", () => {
+    const result = renderStub("resolverTest", "createItem");
+    expect(result).toContain('describe("createItem"');
+    expect(result).toContain('import("./createItem")');
+    expect(result).toContain("resolver.default");
+  });
+});