@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/commands/module/generate.ts

@@ -0,0 +1,35 @@
+import path from "node:path";
+import { defineCommand, arg } from "politty";
+import { z } from "zod";
+import { runGenerateCode } from "../../generator/generate-code";
+
+const cwd = process.cwd();
+
+const codeCommand = defineCommand({
+  name: "code",
+  description: "Generate errors, permissions, command shells, and query shells from docs",
+  args: z.object({
+    root: arg(z.string(), {
+      alias: "r",
+      description: "Path to modules directory",
+    }),
+    module: arg(z.string(), {
+      positional: true,
+      description: "Module name (e.g., primitives, item-management)",
+    }),
+  }),
+  run: (args) => {
+    const modulePath = path.resolve(cwd, args.root, args.module);
+    console.log(`Generating code for ${args.module}...`);
+    const exitCode = runGenerateCode(modulePath, args.module);
+    process.exit(exitCode);
+  },
+});
+
+export const generateCommand = defineCommand({
+  name: "generate",
+  description: "Generate code from model definitions and docs",
+  subCommands: {
+    code: codeCommand,
+  },
+});

package/src/commands/module/index.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { defineCommand, arg } from "politty";
+import { runCheck } from "../check";
+import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
+import { runScaffold, MODULE_TYPES, type ScaffoldType } from "../scaffold";
+import { runModuleList } from "./list";
+import { generateCommand } from "./generate";
+
+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,
+    generate: generateCommand,
+  },
+});

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

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { listModules, formatModuleList } from "./list";
+
+describe("listModules", () => {
+  it("returns the built-in modules with counts", () => {
+    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", () => {
+    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", () => {
+    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", () => {
+    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", () => {
+    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", () => {
+    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";
+
+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-templates.ts

@@ -0,0 +1,65 @@
+export type TemplateEntry =
+  | { type: "dir"; path: string }
+  | { type: "file"; path: string; content: (moduleName: string) => string };
+
+export function getModuleSrcTemplates(): TemplateEntry[] {
+  return [
+    { type: "dir", path: "db" },
+    { type: "dir", path: "command" },
+    { type: "dir", path: "executor" },
+    { type: "dir", path: "generated" },
+    { type: "dir", path: "query" },
+    { type: "file", path: "module.ts", content: () => MODULE_TEMPLATE },
+    { type: "file", path: "index.ts", content: () => INDEX_TEMPLATE },
+    { type: "file", path: "permissions.ts", content: (n) => permissionsTemplate(n) },
+    { type: "file", path: "tailor.config.ts", content: (n) => tailorConfigTemplate(n) },
+    { type: "file", path: "lib/errors.ts", content: () => ERRORS_TEMPLATE },
+    { type: "file", path: "lib/types.ts", content: () => TYPES_TEMPLATE },
+    { type: "file", path: "testing/fixtures.ts", content: () => FIXTURES_TEMPLATE },
+  ];
+}
+
+const MODULE_TEMPLATE = `export const defineModule = () => {
+  return {
+    db: {},
+    commands: {},
+    queries: {},
+  };
+};
+`;
+
+const INDEX_TEMPLATE = `export { defineModule } from "./module";
+export { permissions, own, all } from "./permissions";
+`;
+
+const ERRORS_TEMPLATE = `import { createDomainError } from "../../shared/internal";\n`;
+
+const TYPES_TEMPLATE = `import type { InferSchema, Selectable, Insertable, Updateable } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type Schema = InferSchema<DB>;
+`;
+
+const FIXTURES_TEMPLATE = `// Add test fixtures here\n`;
+
+function permissionsTemplate(moduleName: string): string {
+  return `import { definePermissions } from "../shared/internal";
+
+export const { permissions, own, all } = definePermissions("${moduleName}", [] as const);
+`;
+}
+
+function tailorConfigTemplate(moduleName: string): string {
+  return `import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+
+export default defineConfig({
+  name: "${moduleName}",
+  db: { "main-db": { files: [\`./db/*.ts\`] } },
+});
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: \`./generated/kysely-tailordb.ts\` }],
+  ["@tailor-platform/enum-constants", { distPath: "./generated/enums.ts" }],
+);
+`;
+}

package/src/commands/scaffold.test.ts

@@ -1,5 +1,17 @@
-import { describe, it, expect } from "vitest";
-import { resolveScaffoldPath } from "./scaffold.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  type Diagnostic,
+  DiagnosticCategory,
+  flattenDiagnosticMessageText,
+  ModuleKind,
+  ScriptTarget,
+  transpileModule,
+} from "typescript";
+import { describe, it, expect, afterEach } from "vitest";
+import { resolveScaffoldPath, scaffoldModuleSrc } from "./scaffold";
+import { getModuleSrcTemplates } from "./scaffold-templates";
 
 describe("resolveScaffoldPath", () => {
   // Module types
@@ -61,6 +73,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(
@@ -74,3 +91,81 @@ describe("resolveScaffoldPath", () => {
     );
   });
 });
+
+describe("scaffoldModuleSrc", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("creates expected directories and files", () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "scaffold-test-"));
+    const moduleDir = path.join(tmpDir, "test-module");
+    fs.mkdirSync(moduleDir, { recursive: true });
+
+    scaffoldModuleSrc(moduleDir, "test-module");
+
+    // Verify directories exist directly under module root (flat structure)
+    for (const dir of ["db", "command", "executor", "generated", "lib", "query", "testing"]) {
+      expect(fs.existsSync(path.join(moduleDir, dir))).toBe(true);
+    }
+
+    // Verify .gitkeep in empty directories
+    for (const dir of ["db", "command", "executor", "generated", "query"]) {
+      expect(fs.existsSync(path.join(moduleDir, dir, ".gitkeep"))).toBe(true);
+    }
+
+    // Verify starter files exist
+    const expectedFiles = [
+      "module.ts",
+      "index.ts",
+      "permissions.ts",
+      "tailor.config.ts",
+      "lib/errors.ts",
+      "lib/types.ts",
+      "testing/fixtures.ts",
+    ];
+    for (const file of expectedFiles) {
+      expect(fs.existsSync(path.join(moduleDir, file))).toBe(true);
+    }
+
+    // Verify module name is used in content
+    const permissions = fs.readFileSync(path.join(moduleDir, "permissions.ts"), "utf-8");
+    expect(permissions).toContain('definePermissions("test-module"');
+
+    const config = fs.readFileSync(path.join(moduleDir, "tailor.config.ts"), "utf-8");
+    expect(config).toContain('name: "test-module"');
+
+    const moduleFile = fs.readFileSync(path.join(moduleDir, "module.ts"), "utf-8");
+    expect(moduleFile).toContain("defineModule");
+    expect(moduleFile).toContain("commands");
+    expect(moduleFile).toContain("queries");
+  });
+
+  it("generates syntactically valid TypeScript for all file templates", () => {
+    const templates = getModuleSrcTemplates();
+    const fileTemplates = templates.filter((t) => t.type === "file");
+
+    for (const entry of fileTemplates) {
+      const source = entry.content("test-module");
+      const result = transpileModule(source, {
+        reportDiagnostics: true,
+        compilerOptions: { target: ScriptTarget.ESNext, module: ModuleKind.ESNext },
+      });
+      const errors = (result.diagnostics ?? []).filter(
+        (d) => d.category === DiagnosticCategory.Error,
+      );
+      expect(
+        errors,
+        `syntax errors in template "${entry.path}": ${formatDiagnostics(errors)}`,
+      ).toHaveLength(0);
+    }
+  });
+});
+
+function formatDiagnostics(diagnostics: Diagnostic[]): string {
+  return diagnostics.map((d) => flattenDiagnosticMessageText(d.messageText, "\n")).join("; ");
+}

package/src/commands/scaffold.ts

@@ -1,9 +1,10 @@
 import path from "node:path";
 import fs from "node:fs";
-import { runMdschema } from "../mdschema.js";
-import { ALL_SCHEMAS } from "../schemas.js";
+import { runMdschema } from "../mdschema";
+import { ALL_SCHEMAS } from "../schemas";
+import { getModuleSrcTemplates } from "./scaffold-templates";
 
-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 +21,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> = {
@@ -115,5 +117,24 @@ export async function runScaffold(
   if (stdout.trim()) console.log(stdout);
   if (stderr.trim()) console.error(stderr);
 
+  if (exitCode !== 0) return exitCode;
+
+  if (type === "module") {
+    scaffoldModuleSrc(path.dirname(absoluteOutput), parentName);
+  }
+
   return exitCode;
 }
+
+export function scaffoldModuleSrc(moduleDir: string, moduleName: string): void {
+  for (const entry of getModuleSrcTemplates()) {
+    const fullPath = path.join(moduleDir, entry.path);
+    if (entry.type === "dir") {
+      fs.mkdirSync(fullPath, { recursive: true });
+      fs.writeFileSync(path.join(fullPath, ".gitkeep"), "");
+    } else {
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, entry.content(moduleName));
+    }
+  }
+}

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

@@ -2,7 +2,7 @@ import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { runSyncCheck } from "./sync-check.js";
+import { runSyncCheck, checkStaleness } from "./sync-check";
 
 describe("runSyncCheck", () => {
   let tmpDir: string;
@@ -103,6 +103,60 @@ 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("matches generated query files to docs by stripping .generated suffix", 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, "getCurrency.generated.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "GetCurrency.md"), "# GetCurrency");
+
+    const result = await runSyncCheck({ modulesRoot: "modules", appRoot: "examples" }, tmpDir);
+    expect(result.exitCode).toBe(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it("excludes generated command files from source matching", async () => {
+    const srcDir = path.join(tmpDir, "modules", "foo", "command");
+    const docDir = path.join(tmpDir, "modules", "foo", "docs", "commands");
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.mkdirSync(docDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, "createOrder.ts"), "export {}");
+    fs.writeFileSync(path.join(srcDir, "createOrder.generated.ts"), "export {}");
+    fs.writeFileSync(path.join(docDir, "createOrder.md"), "# CreateOrder");
+
+    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,
@@ -123,3 +177,36 @@ describe("runSyncCheck", () => {
     expect(result.errors).toHaveLength(0);
   });
 });
+
+describe("checkStaleness", () => {
+  it("reports stale when doc mtime > generated mtime", () => {
+    const errors = checkStaleness(
+      [{ docPath: "docs/commands/CreateItem.md", docMtime: 2000 }],
+      [{ genPath: "lib/errors.generated.ts", genMtime: 1000 }],
+    );
+
+    expect(errors).toHaveLength(1);
+    expect(errors[0].type).toBe("stale-generation");
+  });
+
+  it("reports no staleness when generated is newer", () => {
+    const errors = checkStaleness(
+      [{ docPath: "docs/commands/CreateItem.md", docMtime: 1000 }],
+      [{ genPath: "lib/errors.generated.ts", genMtime: 2000 }],
+    );
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns empty when no generated files", () => {
+    const errors = checkStaleness([{ docPath: "docs/commands/CreateItem.md", docMtime: 1000 }], []);
+
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns empty when no doc files", () => {
+    const errors = checkStaleness([], [{ genPath: "lib/errors.generated.ts", genMtime: 1000 }]);
+
+    expect(errors).toHaveLength(0);
+  });
+});

package/src/commands/sync-check.ts

@@ -33,7 +33,7 @@ function moduleCategories(root: string): CategoryConfig[] {
       name: "command",
       sourcePattern: `${root}/*/command/*.ts`,
       docPattern: `${root}/*/docs/commands/*.md`,
-      exclusions: [/\.test\.ts$/],
+      exclusions: [/\.test\.ts$/, /\.generated\.ts$/],
     },
     {
       name: "model",
@@ -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$/],
+    },
   ];
 }
 
@@ -85,7 +91,10 @@ export async function runSyncCheck(
     for (const sourcePath of sources) {
       const fileName = path.basename(sourcePath);
       if (shouldExclude(fileName, category.exclusions)) continue;
-      const basename = path.basename(sourcePath, path.extname(sourcePath));
+      let basename = path.basename(sourcePath, path.extname(sourcePath));
+      if (basename.endsWith(".generated")) {
+        basename = basename.slice(0, -".generated".length);
+      }
       sourceBasenames.set(basename.toLowerCase(), sourcePath);
     }
 
@@ -131,6 +140,36 @@ export async function runSyncCheck(
   };
 }
 
+export interface StalenessError {
+  type: "stale-generation";
+  docPath: string;
+  genPath: string;
+}
+
+export function checkStaleness(
+  docs: { docPath: string; docMtime: number }[],
+  generated: { genPath: string; genMtime: number }[],
+): StalenessError[] {
+  const errors: StalenessError[] = [];
+
+  if (generated.length === 0 || docs.length === 0) return errors;
+
+  const latestDocMtime = Math.max(...docs.map((d) => d.docMtime));
+  const oldestGenMtime = Math.min(...generated.map((g) => g.genMtime));
+
+  if (latestDocMtime > oldestGenMtime) {
+    const newestDoc = docs.find((d) => d.docMtime === latestDocMtime)!;
+    const oldestGen = generated.find((g) => g.genMtime === oldestGenMtime)!;
+    errors.push({
+      type: "stale-generation",
+      docPath: newestDoc.docPath,
+      genPath: oldestGen.genPath,
+    });
+  }
+
+  return errors;
+}
+
 export function formatSyncCheckReport(result: SyncCheckResult): string {
   const lines: string[] = [];
   lines.push(chalk.bold("docs-sync-check: Checking source-documentation correspondence...\n"));