@tailor-platform/erp-kit 0.2.2 → 0.4.0

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 { 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");
+}

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");
+  });
+});

package/src/generator/stub-templates.ts

@@ -0,0 +1,145 @@
+function toPascal(name: string): string {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+const templates = {
+  command: {
+    render: (name: string) => {
+      const inputType = `${toPascal(name)}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({});
+}
+`;
+    },
+  },
+  commandTest: {
+    render: (name: string) => {
+      const pascal = toPascal(name);
+      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 "./${name}";
+
+describe("${name} - test scenario", () => {
+  const ctx: CommandContext = {
+    actorId: "test-actor",
+    permissions: ["TODO:${name}"],
+  };
+
+  it("should be implemented", async () => {
+    const { db } = createMockDb<Transaction>();
+    const result = await run(db, {} as ${pascal}Input, ctx);
+    expect(result.ok).toBe(true);
+  });
+});
+`;
+    },
+  },
+  query: {
+    render: (name: string) => {
+      const inputType = `${toPascal(name)}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 {};
+}
+`;
+    },
+  },
+  queryTest: {
+    render: (name: string) => {
+      const pascal = toPascal(name);
+      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 "./${name}";
+
+describe("${name}", () => {
+  it("should be implemented", async () => {
+    const { db } = createMockDb<DB>();
+    const result = await run(db, {} as ${inputType});
+    expect(result).toBeDefined();
+  });
+});
+`;
+    },
+  },
+  db: {
+    render: (name: string) => {
+      return `import { db, unsafeAllowAllGqlPermission, unsafeAllowAllTypePermission } from "@tailor-platform/sdk";
+
+export const ${name} = db
+  .type("${toPascal(name)}", {
+    // TODO: define fields
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+`;
+    },
+  },
+  resolver: {
+    render: (name: string) => {
+      return `import { createResolver, t } from "@tailor-platform/sdk";
+import { createContext } from "@tailor-platform/erp-kit/app";
+import { getDB } from "@/generated/kysely-tailordb";
+
+export default createResolver({
+  name: "${name}",
+  operation: "mutation",
+  input: {
+    // TODO: define input fields
+  },
+  body: async (context) => {
+    const db = getDB("main-db");
+    return db.transaction().execute(async (trx) => {
+      // TODO: implement
+      return {};
+    });
+  },
+  output: t
+    .object({
+      // TODO: define output fields
+    })
+    .description("${toPascal(name)} response"),
+});
+`;
+    },
+  },
+  resolverTest: {
+    render: (name: string) => {
+      return `import { describe, expect, it } from "vitest";
+
+describe("${name}", () => {
+  it("should be implemented", async () => {
+    const resolver = await import("./${name}");
+    expect(resolver.default).toBeDefined();
+    expect(resolver.default.name).toBe("${name}");
+  });
+});
+`;
+    },
+  },
+} as const;
+
+export type StubType = keyof typeof templates;
+
+export function renderStub(type: StubType, name: string): string {
+  return templates[type].render(name);
+}

package/src/integration.test.ts

@@ -15,7 +15,7 @@ describe.skipIf(skipReason)("integration", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "module", "check", "--root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "check", "--path", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",
@@ -35,7 +35,7 @@ describe.skipIf(skipReason)("integration", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "module", "sync-check", "--root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "sync-check", "--path", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",

package/src/modules/audit/README.md

@@ -0,0 +1,46 @@
+# README
+
+## Overview
+
+The Audit module provides a centralized, append-only audit trail for tracking data changes across all ERP modules. It records who or what performed an action, when it occurred, and what data changed — capturing both the old and new values at the field level. The module is designed as cross-cutting infrastructure: other modules emit structured audit events that the Audit module stores, indexes, and exposes for query. All audit entries are append-only and immutable once written, ensuring that stored records cannot be retroactively altered or deleted. Note: because ingestion is eventually consistent and decoupled from the emitting module's transaction, the module provides best-effort delivery — it does not guarantee that every mutation is captured (see [Audit Event Logging](docs/features/audit-event-logging.md) for the ingestion contract and failure semantics).
+
+The module supports both company-scoped entities (e.g., sales orders, invoices) and global entities (e.g., user accounts, currencies) — entries for global entities omit companyId and are queryable without company scope.
+
+Access to audit data and policy management is controlled by explicit permissions. Because audit entries can contain sensitive before/after values, viewing and administering the audit trail requires dedicated privileges separate from the permissions on the audited entities themselves. The module defines four coarse permissions: `viewAuditHistory` (query audit entries and change details), `viewAuditSummary` (view aggregated audit summaries without field-level details), `manageAuditPolicies` (create, update, activate, deactivate, delete audit policies, query policies, and register auditable entities), and `logAuditEvent` (ingest audit events from emitting modules). At runtime, command shells enforce per-command permission keys (e.g., `audit:createAuditPolicy`, `audit:registerAuditableEntity`), and policy query endpoints (`getAuditPolicy`, `listAuditPolicies`) require the coarse `audit:manageAuditPolicies` key directly. The `manageAuditPolicies` alias (defined in `permissions.ts`) expands to both the coarse `manageAuditPolicies` key itself and all per-command keys; the application's RBAC layer should use this alias when populating `ctx.permissions` to ensure both command and query authorization work correctly. Each permission is company-scoped — holders can only access entries and policies for their assigned companies — or global-scoped for company-unscoped entries and policies. The audit module does not define its own roles; it exposes permissions that the application's role-based access control system assigns to roles as needed.
+
+## Key Features
+
+- **Audit Event Logging** — Captures create, update, and delete operations as immutable audit entries with unique eventId, optional correlationId for operation grouping, actor identity (actorType + actorId), timestamp, entity reference, and operation type
+- **Field-Level Change Tracking** — Records old and new values for each changed field within an audit entry, with configurable sensitivity modes (capture, mask, hash, exclude) to protect sensitive data
+- **Audit Policy Configuration** — Allows administrators to define which entities, fields, and operation types are audited, controlling granularity, sensitivity handling, and performance impact
+
+## Module Scope
+
+### In Scope
+
+- Immutable storage of audit log entries (append-only, no update or delete)
+- Field-level change detail recording (old value / new value pairs) with sensitivity-aware value processing
+- Configurable audit policies at entity and field granularity with sensitivity modes
+- Query and filtering of audit logs by actor, entity, record, operation type, and date range
+- Record-level change history retrieval
+- Actor identity capture supporting multiple actor types (USER, SYSTEM, SERVICE) with optional delegation (onBehalfOf)
+- Company-scoped and global (company-unscoped) audit entries
+- Permission-based access control for audit viewing and policy administration
+
+### Out of Scope
+
+- User authentication and session tracking (owned by user-management / infrastructure layer)
+- Compliance framework mapping and automated evidence collection (application-level concern)
+- Anomaly detection, alerting, and real-time notifications
+- Log archival, long-term retention policies, and storage tiering
+- Dashboard visualizations and audit analytics
+
+### Scope Decision Rationale
+
+The module focuses on the foundational audit trail capabilities that all ERP deployments require: capturing changes, storing them immutably once written, and making them queryable. The ingestion contract is best-effort — applications that require guaranteed delivery for strict compliance scenarios should layer an outbox or replay mechanism on top of this module. Authentication logging is excluded because it belongs to the identity/infrastructure layer, not the domain data change layer. Compliance framework mapping, anomaly detection, and retention management are excluded as application-level or operational concerns that can be layered on top of the core audit trail. This separation keeps the module focused, testable, and reusable across different compliance contexts.
+
+## Module Dependencies
+
+- **user-management** — References userId as one type of actorId on audit entries (data reference only; no domain logic dependency)
+- **organization** — References companyId for multi-company scoping of company-bound audit entries (data reference only; companyId is optional for global entities)
+- **all emitting modules** (reverse dependency) — The audit module is cross-cutting: other modules depend on it, not the other way around. Emitting modules register their auditable entities (name, scope, field list) at initialization time and submit structured audit event payloads (including a unique `eventId` for idempotency) after committing their own transactions. The ingestion contract is idempotent on `eventId` for safe retries, and the audit module does not participate in the emitting module's transaction (eventually consistent). See the [Audit Event Logging](docs/features/audit-event-logging.md) feature documentation for the full ingestion contract.

package/src/modules/audit/command/activateAuditPolicy.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./activateAuditPolicy";
+
+export const activateAuditPolicy = defineCommand(permissions.activateAuditPolicy, run);