@tailor-platform/erp-kit 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {

package/schemas/module/command.yml

@@ -35,6 +35,7 @@ structure:
       # Error handling - REQUIRED
       # How errors are handled
       - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
         lists:
           - min: 0
             type: unordered

package/schemas/module/model.yml

@@ -37,6 +37,15 @@ structure:
                 type: unordered
                 min_items: 0
 
+          - heading: "### Query Definitions"
+            description: |
+              Definitions of queries this domain model supports.
+              Should match with the queries defined in modules/**/docs/queries/*.md and link to them.
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
           - heading: "### Models"
             description: |
               Actual database models necessary for the domain model.

package/schemas/module/query.yml

@@ -0,0 +1,53 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this query does - REQUIRED
+      - heading: "## Overview"
+
+      # Business rules - REQUIRED
+      # Rules, constraints, and validation logic
+      - heading: "## Business Rules"
+        allow_additional: true
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # How it works - REQUIRED
+      # Step-by-step flow or workflow
+      - heading: "## Process Flow"
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # External dependencies - OPTIONAL
+      # Queries from other modules that this query depends on
+      - heading: "## External Dependencies"
+        description: "e.g. `- [inventory::getStockLevel](../../inventory/queries/getStockLevel.md) - Get current stock level`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Error handling - REQUIRED
+      # How errors are handled
+      - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/src/cli.ts

@@ -2,94 +2,13 @@
 
 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";
+import { moduleCommand } from "./commands/module/index.js";
+import { appCommand } from "./commands/app/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 with framework skills",
@@ -107,13 +26,12 @@ const initCommand = defineCommand({
 
 const main = defineCommand({
   name: "erp-kit",
-  description: "Documentation validation and scaffolding tool",
+  description: "ERP module framework CLI",
   subCommands: {
-    check: checkCommand,
-    "sync-check": syncCheckCommand,
-    scaffold: scaffoldCommand,
-    init: initCommand,
+    module: moduleCommand,
+    app: appCommand,
     mock: mockCommand,
+    init: initCommand,
   },
 });
 

package/src/commands/app/index.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { runCheck } from "../check.js";
+import { runSyncCheck, formatSyncCheckReport } from "../sync-check.js";
+import { runScaffold, APP_TYPES, type ScaffoldType } from "../scaffold.js";
+
+const cwd = process.cwd();
+
+const rootArgs = z.object({
+  root: arg(z.string(), {
+    alias: "r",
+    description: "Path to app-compose directory",
+  }),
+});
+
+const checkCommand = defineCommand({
+  name: "check",
+  description: "Validate app docs against schemas",
+  args: rootArgs,
+  run: async (args) => {
+    const exitCode = await runCheck({ appRoot: args.root }, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const syncCheckCommand = defineCommand({
+  name: "sync-check",
+  description: "Validate source <-> doc correspondence",
+  args: rootArgs,
+  run: async (args) => {
+    const result = await runSyncCheck({ appRoot: args.root }, cwd);
+    console.log(formatSyncCheckReport(result));
+    process.exit(result.exitCode);
+  },
+});
+
+const scaffoldCommand = defineCommand({
+  name: "scaffold",
+  description: "Generate app doc from schema template",
+  args: rootArgs.extend({
+    type: arg(z.enum(APP_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Scaffold type (${APP_TYPES.join(", ")})`,
+    }),
+    parent: arg(z.string(), {
+      positional: true,
+      description: "App name",
+    }),
+    name: arg(z.string().optional(), {
+      positional: true,
+      description: "Item name (required for most types)",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runScaffold(
+      args.type as ScaffoldType,
+      args.parent,
+      args.name,
+      args.root,
+      cwd,
+    );
+    process.exit(exitCode);
+  },
+});
+
+export const appCommand = defineCommand({
+  name: "app",
+  description: "App-compose management",
+  subCommands: {
+    check: checkCommand,
+    "sync-check": syncCheckCommand,
+    scaffold: scaffoldCommand,
+  },
+});

package/src/commands/check.test.ts

@@ -8,6 +8,7 @@ describe("buildCheckTargets", () => {
       { 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]*/docs/queries/*.md", schemaKey: "query" },
       { glob: "modules/[a-zA-Z]*/README.md", schemaKey: "module" },
     ]);
   });
@@ -20,7 +21,7 @@ describe("buildCheckTargets", () => {
 
   it("generates both when both roots are set", () => {
     const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "examples" });
-    expect(targets).toHaveLength(10);
+    expect(targets).toHaveLength(11);
   });
 
   it("returns empty when neither root is set", () => {

package/src/commands/check.ts

@@ -17,6 +17,7 @@ export function buildCheckTargets(config: {
       { 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]*/docs/queries/*.md`, schemaKey: "query" },
       { glob: `${m}/[a-zA-Z]*/README.md`, schemaKey: "module" },
     );
   }

package/src/commands/module/index.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { runCheck } from "../check.js";
+import { runSyncCheck, formatSyncCheckReport } from "../sync-check.js";
+import { runScaffold, MODULE_TYPES, type ScaffoldType } from "../scaffold.js";
+import { runModuleList } from "./list.js";
+
+const cwd = process.cwd();
+
+const rootArgs = z.object({
+  root: arg(z.string(), {
+    alias: "r",
+    description: "Path to modules directory",
+  }),
+});
+
+const listCommand = defineCommand({
+  name: "list",
+  description: "List available modules",
+  run: () => {
+    const exitCode = runModuleList();
+    process.exit(exitCode);
+  },
+});
+
+const checkCommand = defineCommand({
+  name: "check",
+  description: "Validate module docs against schemas",
+  args: rootArgs,
+  run: async (args) => {
+    const exitCode = await runCheck({ modulesRoot: args.root }, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const syncCheckCommand = defineCommand({
+  name: "sync-check",
+  description: "Validate source <-> doc correspondence",
+  args: rootArgs,
+  run: async (args) => {
+    const result = await runSyncCheck({ modulesRoot: args.root }, cwd);
+    console.log(formatSyncCheckReport(result));
+    process.exit(result.exitCode);
+  },
+});
+
+const scaffoldCommand = defineCommand({
+  name: "scaffold",
+  description: "Generate module doc from schema template",
+  args: rootArgs.extend({
+    type: arg(z.enum(MODULE_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Scaffold type (${MODULE_TYPES.join(", ")})`,
+    }),
+    parent: arg(z.string(), {
+      positional: true,
+      description: "Module name",
+    }),
+    name: arg(z.string().optional(), {
+      positional: true,
+      description: "Item name (required for feature, command, model)",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runScaffold(
+      args.type as ScaffoldType,
+      args.parent,
+      args.name,
+      args.root,
+      cwd,
+    );
+    process.exit(exitCode);
+  },
+});
+
+export const moduleCommand = defineCommand({
+  name: "module",
+  description: "Module management",
+  subCommands: {
+    list: listCommand,
+    check: checkCommand,
+    "sync-check": syncCheckCommand,
+    scaffold: scaffoldCommand,
+  },
+});

package/src/commands/module/list.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+
+describe("listModules", () => {
+  it("returns the built-in modules with counts", async () => {
+    const { listModules } = await import("./list.js");
+    const modules = listModules();
+    expect(modules.length).toBeGreaterThan(0);
+
+    const primitives = modules.find((m) => m.name === "primitives");
+    expect(primitives).toBeDefined();
+    expect(primitives!.commands).toBeGreaterThan(0);
+    expect(primitives!.models).toBeGreaterThan(0);
+    expect(primitives!.features).toBeGreaterThan(0);
+  });
+
+  it("returns zero counts for stub modules", async () => {
+    const { listModules } = await import("./list.js");
+    const modules = listModules();
+    const inventory = modules.find((m) => m.name === "inventory");
+    expect(inventory).toBeDefined();
+    expect(inventory!.commands).toBe(0);
+    expect(inventory!.models).toBe(0);
+    expect(inventory!.features).toBe(0);
+  });
+
+  it("excludes shared and testing directories", async () => {
+    const { listModules } = await import("./list.js");
+    const modules = listModules();
+    const names = modules.map((m) => m.name);
+    expect(names).not.toContain("shared");
+    expect(names).not.toContain("testing");
+  });
+
+  it("returns modules in alphabetical order", async () => {
+    const { listModules } = await import("./list.js");
+    const modules = listModules();
+    const names = modules.map((m) => m.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+});
+
+describe("formatModuleList", () => {
+  it("formats modules with counts", async () => {
+    const { formatModuleList } = await import("./list.js");
+    const output = formatModuleList([
+      { name: "primitives", commands: 14, models: 4, features: 4 },
+      { name: "inventory", commands: 0, models: 0, features: 0 },
+    ]);
+    expect(output).toContain("primitives");
+    expect(output).toContain("14 commands");
+    expect(output).toContain("4 models");
+    expect(output).toContain("4 features");
+    expect(output).toContain("inventory");
+    expect(output).toContain("2 modules");
+  });
+
+  it("handles empty list", async () => {
+    const { formatModuleList } = await import("./list.js");
+    expect(formatModuleList([])).toBe("No modules found.");
+  });
+});

package/src/commands/module/list.ts

@@ -0,0 +1,64 @@
+import { readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { PACKAGE_ROOT } from "../../util.js";
+
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+
+export interface ModuleInfo {
+  name: string;
+  commands: number;
+  models: number;
+  features: number;
+}
+
+function countFiles(dir: string, pattern: RegExp, exclusions: RegExp[]): number {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => pattern.test(f) && !exclusions.some((p) => p.test(f)))
+    .length;
+}
+
+export function listModules(): ModuleInfo[] {
+  if (!existsSync(MODULES_DIR)) return [];
+  return readdirSync(MODULES_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name))
+    .map((d) => {
+      const modDir = join(MODULES_DIR, d.name);
+      return {
+        name: d.name,
+        commands: countFiles(join(modDir, "command"), /\.ts$/, [/\.test\.ts$/]),
+        models: countFiles(join(modDir, "db"), /\.ts$/, [/\.test\.ts$/, /^index\.ts$/]),
+        features: countFiles(join(modDir, "docs", "features"), /\.md$/, []),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function formatModuleList(modules: ModuleInfo[]): string {
+  if (modules.length === 0) return "No modules found.";
+
+  const lines: string[] = [];
+  lines.push(chalk.bold("Modules:\n"));
+
+  const nameWidth = Math.max(...modules.map((m) => m.name.length), 4);
+
+  for (const mod of modules) {
+    const counts = [
+      `${mod.commands} commands`,
+      `${mod.models} models`,
+      `${mod.features} features`,
+    ].join(", ");
+    lines.push(`  ${mod.name.padEnd(nameWidth)}  ${counts}`);
+  }
+
+  lines.push("");
+  lines.push(`${modules.length} modules`);
+  return lines.join("\n");
+}
+
+export function runModuleList(): number {
+  const modules = listModules();
+  console.log(formatModuleList(modules));
+  return 0;
+}

package/src/commands/scaffold.test.ts

@@ -61,6 +61,11 @@ describe("resolveScaffoldPath", () => {
     expect(result).toBe("examples/my-app/docs/resolver/create-supplier.md");
   });
 
+  it("resolves query scaffold path", () => {
+    const result = resolveScaffoldPath("query", "inventory", "ConvertQuantity", "modules");
+    expect(result).toBe("modules/inventory/docs/queries/ConvertQuantity.md");
+  });
+
   // Validation
   it("throws when name is required but missing", () => {
     expect(() => resolveScaffoldPath("command", "inventory", undefined, "modules")).toThrow(

package/src/commands/scaffold.ts

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import { runMdschema } from "../mdschema.js";
 import { ALL_SCHEMAS } from "../schemas.js";
 
-export const MODULE_TYPES = ["module", "feature", "command", "model"] as const;
+export const MODULE_TYPES = ["module", "feature", "command", "model", "query"] as const;
 export const APP_TYPES = [
   "requirements",
   "actors",
@@ -20,6 +20,7 @@ const MODULE_DIR_MAP: Record<string, string> = {
   feature: "docs/features",
   command: "docs/commands",
   model: "docs/models",
+  query: "docs/queries",
 };
 
 const APP_DIR_MAP: Record<string, string> = {

package/src/commands/sync-check.test.ts

@@ -103,6 +103,34 @@ describe("runSyncCheck", () => {
     expect(result.summary.totalSources).toBe(1);
   });
 
+  it("reports missing doc for query source without doc", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "query");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "convertAmount.ts"), "export {}");
+
+    const result = await runSyncCheck({ modulesRoot: "modules", appRoot: "examples" }, tmpDir);
+    expect(result.exitCode).toBe(1);
+    expect(result.errors).toContainEqual(
+      expect.objectContaining({
+        type: "missing-doc",
+        category: "query",
+        expectedBasename: "convertamount",
+      }),
+    );
+  });
+
+  it("returns 0 when query source and doc match", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "query");
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "queries");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "convertAmount.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "convertAmount.md"), "# ConvertAmount");
+
+    const result = await runSyncCheck({ modulesRoot: "modules", appRoot: "examples" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+  });
+
   it("checks only module patterns when appRoot is not set", async () => {
     const resolverSrcDir = path.join(
       tmpDir,

package/src/commands/sync-check.ts

@@ -41,6 +41,12 @@ function moduleCategories(root: string): CategoryConfig[] {
       docPattern: `${root}/*/docs/models/*.md`,
       exclusions: [/\.test\.ts$/, /^index\.ts$/],
     },
+    {
+      name: "query",
+      sourcePattern: `${root}/*/query/*.ts`,
+      docPattern: `${root}/*/docs/queries/*.md`,
+      exclusions: [/\.test\.ts$/],
+    },
   ];
 }
 

package/src/integration.test.ts

@@ -11,13 +11,11 @@ const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
 const skipReason = fs.existsSync(CLI_PATH) ? undefined : "Run `pnpm build` first";
 
 describe.skipIf(skipReason)("integration", () => {
-  it("check command runs against sdk-plugins modules", () => {
-    // mdschema may report validation errors in real docs, so we allow non-zero exit codes
-    // but verify the CLI itself doesn't crash with an unexpected error
+  it("module check command runs against sdk-plugins modules", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "check", "--modules-root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "check", "--root", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",
@@ -33,11 +31,11 @@ describe.skipIf(skipReason)("integration", () => {
     }
   });
 
-  it("sync-check command runs against sdk-plugins modules", () => {
+  it("module sync-check command runs against sdk-plugins modules", () => {
     try {
       const result = execFileSync(
         "node",
-        [CLI_PATH, "sync-check", "--modules-root", "packages/erp-kit/src/modules"],
+        [CLI_PATH, "module", "sync-check", "--root", "packages/erp-kit/src/modules"],
         {
           cwd: REPO_ROOT,
           encoding: "utf-8",
@@ -57,7 +55,7 @@ describe.skipIf(skipReason)("integration", () => {
       encoding: "utf-8",
     });
     expect(result).toContain("erp-kit");
-    expect(result).toContain("check");
-    expect(result).toContain("scaffold");
+    expect(result).toContain("module");
+    expect(result).toContain("app");
   });
 });

package/src/module.ts

@@ -1,9 +1,10 @@
 // shared/internal
 export { defineCommand, type Command } from "./modules/shared/defineCommand";
+export { defineQuery, type Query } from "./modules/shared/defineQuery";
 export { definePermissions } from "./modules/shared/definePermissions";
 export { requirePermission } from "./modules/shared/requirePermission";
 export { createDomainError, InsufficientPermissionError } from "./modules/shared/errors";
-export type { CommandContext } from "./modules/shared/types";
+export type { CommandContext, QueryContext, ReadonlyDB } from "./modules/shared/types";
 export type {
   InferSchema,
   Selectable,
@@ -43,13 +44,13 @@ export {
   SameCurrencyPairError,
   InvalidExchangeRateError,
 } from "./modules/primitives/lib/errors";
-export { type ConvertQuantityInput } from "./modules/primitives/command/convertQuantity";
+export { type ConvertQuantityInput } from "./modules/primitives/query/convertQuantity";
 export { type ActivateCategoryInput } from "./modules/primitives/command/activateCategory";
 export { type DeactivateCategoryInput } from "./modules/primitives/command/deactivateCategory";
 export { type SetReferenceUnitInput } from "./modules/primitives/command/setReferenceUnit";
 export { type ActivateUnitInput } from "./modules/primitives/command/activateUnit";
 export { type DeactivateUnitInput } from "./modules/primitives/command/deactivateUnit";
-export { type ConvertAmountInput } from "./modules/primitives/command/convertAmount";
+export { type ConvertAmountInput } from "./modules/primitives/query/convertAmount";
 export { type ActivateCurrencyInput } from "./modules/primitives/command/activateCurrency";
 export { type DeactivateCurrencyInput } from "./modules/primitives/command/deactivateCurrency";
 export { type SetBaseCurrencyInput } from "./modules/primitives/command/setBaseCurrency";

package/src/modules/primitives/docs/models/Currency.md

@@ -29,6 +29,10 @@ stateDiagram-v2
 - [deactivateCurrency](../commands/DeactivateCurrency.md)
 - [setBaseCurrency](../commands/SetBaseCurrency.md)
 
+### Query Definitions
+
+- [convertAmount](../queries/ConvertAmount.md)
+
 ### Models
 
 - Currency