@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/commands/doc/modules.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { getModuleOverviews, formatModuleOverviews, runDocModules } from "./modules";
+
+describe("getModuleOverviews", () => {
+  it("returns modules with overview and counts", () => {
+    const modules = getModuleOverviews();
+    expect(modules.length).toBeGreaterThan(0);
+
+    const org = modules.find((m) => m.name === "organization");
+    expect(org).toBeDefined();
+    expect(org!.commandCount).toBeGreaterThan(0);
+    expect(org!.queryCount).toBeGreaterThan(0);
+    expect(org!.modelCount).toBeGreaterThan(0);
+    expect(org!.overview).toContain("Organization module");
+    expect(org!.dependencies).toContain("primitives");
+  });
+
+  it("returns empty dependencies for modules with none", () => {
+    const modules = getModuleOverviews();
+    const primitives = modules.find((m) => m.name === "primitives");
+    expect(primitives).toBeDefined();
+    expect(primitives!.dependencies).toEqual([]);
+  });
+
+  it("excludes shared and testing directories", () => {
+    const modules = getModuleOverviews();
+    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 = getModuleOverviews();
+    const names = modules.map((m) => m.name);
+    const sorted = [...names].sort();
+    expect(names).toEqual(sorted);
+  });
+});
+
+describe("formatModuleOverviews", () => {
+  it("formats modules with overview and counts", () => {
+    const output = formatModuleOverviews([
+      {
+        name: "test-module",
+        commandCount: 5,
+        queryCount: 3,
+        modelCount: 2,
+        overview: "Test module overview.",
+        dependencies: ["primitives"],
+      },
+    ]);
+    expect(output).toContain("# test-module (5 commands, 3 queries, 2 models)");
+    expect(output).toContain("Test module overview.");
+    expect(output).toContain("Dependencies: primitives");
+    expect(output).toContain("1 modules");
+  });
+
+  it("shows 'none' for modules with no dependencies", () => {
+    const output = formatModuleOverviews([
+      {
+        name: "standalone",
+        commandCount: 0,
+        queryCount: 0,
+        modelCount: 0,
+        overview: "",
+        dependencies: [],
+      },
+    ]);
+    expect(output).toContain("Dependencies: none");
+  });
+
+  it("handles empty list", () => {
+    expect(formatModuleOverviews([])).toBe("No modules found.");
+  });
+});
+
+describe("runDocModules", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("outputs valid JSON with --format json", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocModules("json");
+    expect(exitCode).toBe(0);
+
+    const parsed = JSON.parse(logs.join("\n")) as unknown[];
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.length).toBeGreaterThan(0);
+
+    const first = parsed[0] as Record<string, unknown>;
+    expect(first).toHaveProperty("name");
+    expect(first).toHaveProperty("commandCount");
+    expect(first).toHaveProperty("queryCount");
+    expect(first).toHaveProperty("modelCount");
+    expect(first).toHaveProperty("overview");
+    expect(first).toHaveProperty("dependencies");
+  });
+});

package/src/commands/doc/modules.ts

@@ -0,0 +1,98 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../util";
+import { MODULE_PATHS } from "../lib/paths";
+
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+
+interface ModuleOverview {
+  name: string;
+  commandCount: number;
+  queryCount: number;
+  modelCount: number;
+  overview: string;
+  dependencies: string[];
+}
+
+function countDocs(dir: string): number {
+  if (!existsSync(dir)) return 0;
+  return readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+}
+
+function extractOverview(readmePath: string): string {
+  if (!existsSync(readmePath)) return "";
+  const content = readFileSync(readmePath, "utf-8");
+  const overviewMatch = /## Overview\n\n([\s\S]*?)(?=\n##\s|\n$)/.exec(content);
+  if (!overviewMatch) return "";
+  const firstParagraph = overviewMatch[1].trim().split("\n\n")[0];
+  return firstParagraph;
+}
+
+function extractDependencies(readmePath: string): string[] {
+  if (!existsSync(readmePath)) return [];
+  const content = readFileSync(readmePath, "utf-8");
+  const depsMatch = /## Module Dependencies\n\n([\s\S]*?)(?=\n##\s|$)/.exec(content);
+  if (!depsMatch) return [];
+  const deps: string[] = [];
+  const linePattern = /^- \[([^\]]+)\]/;
+  for (const line of depsMatch[1].trim().split("\n")) {
+    const match = linePattern.exec(line);
+    if (match) deps.push(match[1]);
+  }
+  return deps;
+}
+
+export function getModuleOverviews(): ModuleOverview[] {
+  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);
+      const readmePath = join(modDir, "README.md");
+      return {
+        name: d.name,
+        commandCount: countDocs(join(modDir, MODULE_PATHS.docs.commands)),
+        queryCount: countDocs(join(modDir, MODULE_PATHS.docs.queries)),
+        modelCount: countDocs(join(modDir, MODULE_PATHS.docs.models)),
+        overview: extractOverview(readmePath),
+        dependencies: extractDependencies(readmePath),
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function formatModuleOverviews(modules: ModuleOverview[]): string {
+  if (modules.length === 0) return "No modules found.";
+
+  const lines: string[] = [];
+  for (const mod of modules) {
+    const counts = [
+      `${mod.commandCount} commands`,
+      `${mod.queryCount} queries`,
+      `${mod.modelCount} models`,
+    ].join(", ");
+    lines.push(`# ${mod.name} (${counts})`);
+    if (mod.overview) {
+      lines.push(mod.overview);
+    }
+    if (mod.dependencies.length > 0) {
+      lines.push(`Dependencies: ${mod.dependencies.join(", ")}`);
+    } else {
+      lines.push("Dependencies: none");
+    }
+    lines.push("");
+  }
+  lines.push(`${modules.length} modules`);
+  return lines.join("\n");
+}
+
+export function runDocModules(format = "text"): number {
+  const modules = getModuleOverviews();
+  if (format === "json") {
+    console.log(JSON.stringify(modules, null, 2));
+  } else {
+    console.log(formatModuleOverviews(modules));
+  }
+  return 0;
+}

package/src/commands/doc/search.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { searchModuleDocs, formatSearchResults, runDocSearch } from "./search";
+
+describe("searchModuleDocs", () => {
+  it("returns results for known content", () => {
+    const results = searchModuleDocs("Organization module");
+    expect(results.length).toBeGreaterThan(0);
+    const orgResults = results.filter((r) => r.module === "organization");
+    expect(orgResults.length).toBeGreaterThan(0);
+  });
+
+  it("is case-insensitive", () => {
+    const lower = searchModuleDocs("organization module");
+    const upper = searchModuleDocs("ORGANIZATION MODULE");
+    expect(lower.length).toBe(upper.length);
+    expect(lower.length).toBeGreaterThan(0);
+  });
+
+  it("filters by doc type", () => {
+    const readmeOnly = searchModuleDocs("Organization module", "readme");
+    expect(readmeOnly.length).toBeGreaterThan(0);
+    for (const r of readmeOnly) {
+      expect(r.type).toBe("readme");
+    }
+  });
+
+  it("returns empty array for no matches", () => {
+    const results = searchModuleDocs("xyzzy_nonexistent_term_12345");
+    expect(results).toEqual([]);
+  });
+
+  it("includes line numbers", () => {
+    const results = searchModuleDocs("Organization module");
+    for (const r of results) {
+      expect(r.line).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("formatSearchResults", () => {
+  it("formats results with module/type/name", () => {
+    const output = formatSearchResults([
+      { module: "org", type: "command", name: "Create", line: 5, excerpt: "Create an org" },
+    ]);
+    expect(output).toContain("org/command/Create:5: Create an org");
+    expect(output).toContain("1 matches");
+  });
+
+  it("handles empty results", () => {
+    expect(formatSearchResults([])).toBe("No results found.");
+  });
+});
+
+describe("runDocSearch", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("outputs valid JSON with --format json", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocSearch("Organization module", undefined, "json");
+    expect(exitCode).toBe(0);
+
+    const parsed = JSON.parse(logs.join("\n")) as unknown[];
+    expect(Array.isArray(parsed)).toBe(true);
+    expect(parsed.length).toBeGreaterThan(0);
+  });
+
+  it("returns exit code 1 for invalid type", () => {
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      errors.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocSearch("test", "invalid");
+    expect(exitCode).toBe(1);
+    expect(errors[0]).toContain("Unknown doc type");
+  });
+
+  it("outputs 'No results found' for no matches in text mode", () => {
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    });
+
+    const exitCode = runDocSearch("xyzzy_nonexistent_12345");
+    expect(exitCode).toBe(0);
+    expect(logs.join("\n")).toContain("No results found.");
+  });
+});

package/src/commands/doc/search.ts

@@ -0,0 +1,111 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../util";
+import { MODULE_PATHS } from "../lib/paths";
+
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+
+const DOC_TYPE_MAP: Record<string, string> = {
+  command: MODULE_PATHS.docs.commands,
+  query: MODULE_PATHS.docs.queries,
+  model: MODULE_PATHS.docs.models,
+  feature: MODULE_PATHS.docs.features,
+};
+
+export interface SearchResult {
+  module: string;
+  type: string;
+  name: string;
+  line: number;
+  excerpt: string;
+}
+
+function searchFile(
+  filePath: string,
+  query: string,
+  module: string,
+  type: string,
+  name: string,
+): SearchResult[] {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  const lowerQuery = query.toLowerCase();
+  const results: SearchResult[] = [];
+
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].toLowerCase().includes(lowerQuery)) {
+      results.push({
+        module,
+        type,
+        name,
+        line: i + 1,
+        excerpt: lines[i].trim(),
+      });
+    }
+  }
+  return results;
+}
+
+export function searchModuleDocs(query: string, typeFilter?: string): SearchResult[] {
+  if (!existsSync(MODULES_DIR)) return [];
+
+  const results: SearchResult[] = [];
+  const modules = readdirSync(MODULES_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const mod of modules) {
+    const modDir = join(MODULES_DIR, mod.name);
+
+    // Search README
+    if (!typeFilter || typeFilter === "readme") {
+      results.push(...searchFile(join(modDir, "README.md"), query, mod.name, "readme", "README"));
+    }
+
+    // Search doc type directories
+    for (const [type, subdir] of Object.entries(DOC_TYPE_MAP)) {
+      if (typeFilter && typeFilter !== type) continue;
+      const docsDir = join(modDir, subdir);
+      if (!existsSync(docsDir)) continue;
+
+      const files = readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+      for (const file of files) {
+        const name = file.replace(/\.md$/, "");
+        results.push(...searchFile(join(docsDir, file), query, mod.name, type, name));
+      }
+    }
+  }
+
+  return results;
+}
+
+export function formatSearchResults(results: SearchResult[]): string {
+  if (results.length === 0) return "No results found.";
+
+  const lines: string[] = [];
+  for (const r of results) {
+    lines.push(`${r.module}/${r.type}/${r.name}:${r.line}: ${r.excerpt}`);
+  }
+  lines.push("");
+  lines.push(`${results.length} matches`);
+  return lines.join("\n");
+}
+
+export function runDocSearch(query: string, type?: string, format = "text"): number {
+  if (type && type !== "readme" && !(type in DOC_TYPE_MAP)) {
+    console.error(`Unknown doc type: ${type}`);
+    console.error(`Available types: readme, ${Object.keys(DOC_TYPE_MAP).join(", ")}`);
+    return 1;
+  }
+
+  const results = searchModuleDocs(query, type);
+
+  if (format === "json") {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatSearchResults(results));
+  }
+  return 0;
+}

package/src/commands/generate-doc.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { runMdschema } from "../mdschema";
 import { ALL_SCHEMAS } from "../schemas";
+import { MODULE_PATHS, APP_PATHS } from "./lib/paths";
 
 export const MODULE_DOC_TYPES = ["feature", "command", "model", "query"] as const;
 export const APP_DOC_TYPES = ["actors", "business-flow", "story", "screen", "resolver"] as const;
@@ -10,17 +11,17 @@ export const ALL_DOC_TYPES = [...MODULE_DOC_TYPES, ...APP_DOC_TYPES] as const;
 export type DocType = (typeof ALL_DOC_TYPES)[number];
 
 const MODULE_DIR_MAP: Record<string, string> = {
-  feature: "docs/features",
-  command: "docs/commands",
-  model: "docs/models",
-  query: "docs/queries",
+  feature: MODULE_PATHS.docs.features,
+  command: MODULE_PATHS.docs.commands,
+  model: MODULE_PATHS.docs.models,
+  query: MODULE_PATHS.docs.queries,
 };
 
 const APP_DIR_MAP: Record<string, string> = {
-  actors: "docs/actors",
-  "business-flow": "docs/business-flow",
-  screen: "docs/screen",
-  resolver: "docs/resolver",
+  actors: APP_PATHS.docs.actors,
+  "business-flow": APP_PATHS.docs.businessFlow,
+  screen: APP_PATHS.docs.screen,
+  resolver: APP_PATHS.docs.resolver,
 };
 
 export function resolveDocPath(
@@ -33,7 +34,7 @@ export function resolveDocPath(
   }
 
   if (type === "business-flow") {
-    return path.join(modulePath, "docs/business-flow", name, "README.md");
+    return path.join(modulePath, APP_PATHS.docs.businessFlow, name, "README.md");
   }
 
   if (type === "story") {
@@ -43,7 +44,13 @@ export function resolveDocPath(
         `Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`,
       );
     }
-    return path.join(modulePath, "docs/business-flow", parts[0], "story", `${parts[1]}.md`);
+    return path.join(
+      modulePath,
+      APP_PATHS.docs.businessFlow,
+      parts[0],
+      APP_PATHS.storySegment,
+      `${parts[1]}.md`,
+    );
   }
 
   if (MODULE_DIR_MAP[type]) {

package/src/commands/index.ts

@@ -6,10 +6,13 @@ import { runLicenseCheck, runLicenseList } from "./license";
 import { moduleCommand } from "./module/index";
 import { appCommand } from "./app/index";
 import { mockCommand } from "./mock/index";
+import { docCommand } from "./doc/index";
+import { executeCommand, success, silentFailure } from "./lib/command-result";
 
 export { moduleCommand } from "./module/index";
 export { appCommand } from "./app/index";
 export { mockCommand } from "./mock/index";
+export { docCommand } from "./doc/index";
 
 const cwd = process.cwd();
 
@@ -17,8 +20,10 @@ export const initCommand = defineCommand({
   name: "init",
   description: "First-time setup for a consumer repo",
   run: () => {
-    const exitCode = runInit(cwd);
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const exitCode = runInit(cwd);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -32,8 +37,10 @@ export const updateCommand = defineCommand({
     }),
   }),
   run: (args) => {
-    const exitCode = runUpdate(cwd, args.resources);
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const exitCode = runUpdate(cwd, args.resources);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -47,8 +54,10 @@ const licenseCheckCommand = defineCommand({
     }),
   }),
   run: (args) => {
-    const exitCode = runLicenseCheck(args.config);
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const exitCode = runLicenseCheck(args.config);
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -56,8 +65,10 @@ const licenseListCommand = defineCommand({
   name: "list",
   description: "List available license groups",
   run: () => {
-    const exitCode = runLicenseList();
-    process.exit(exitCode);
+    return executeCommand(() => {
+      const exitCode = runLicenseList();
+      return exitCode === 0 ? success() : silentFailure(exitCode);
+    });
   },
 });
 
@@ -77,6 +88,7 @@ export const mainCommand = defineCommand({
     module: moduleCommand,
     app: appCommand,
     mock: mockCommand,
+    doc: docCommand,
     init: initCommand,
     update: updateCommand,
     license: licenseCommand,

package/src/commands/lib/command-result.ts

@@ -0,0 +1,30 @@
+export type CommandResult = { exitCode: 0 } | { exitCode: number; message: string };
+
+export function success(): CommandResult {
+  return { exitCode: 0 };
+}
+
+export function failure(message: string, exitCode = 1): CommandResult {
+  return { exitCode, message };
+}
+
+export function silentFailure(exitCode = 1): CommandResult {
+  return { exitCode, message: "" };
+}
+
+export async function runCommand(
+  fn: () => CommandResult | Promise<CommandResult>,
+): Promise<CommandResult> {
+  const result = await fn();
+  if (result.exitCode !== 0 && "message" in result && result.message) {
+    console.error(result.message);
+  }
+  return result;
+}
+
+export async function executeCommand(
+  fn: () => CommandResult | Promise<CommandResult>,
+): Promise<never> {
+  const result = await runCommand(fn);
+  process.exit(result.exitCode);
+}

package/src/commands/lib/discovery.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import {
+  moduleCategories,
+  appComposeCategories,
+  testCaseCategories,
+  buildCheckTargets,
+} from "./discovery";
+
+describe("moduleCategories", () => {
+  it("produces command/model/query categories with correct patterns", () => {
+    const cats = moduleCategories("modules");
+    expect(cats).toHaveLength(3);
+
+    const command = cats.find((c) => c.name === "command")!;
+    expect(command.sourcePattern).toBe("modules/*/command/*.ts");
+    expect(command.docPattern).toBe("modules/*/docs/commands/*.md");
+    expect(command.exclusions).toEqual([/\.test\.ts$/, /\.generated\.ts$/]);
+
+    const model = cats.find((c) => c.name === "model")!;
+    expect(model.sourcePattern).toBe("modules/*/db/*.ts");
+    expect(model.docPattern).toBe("modules/*/docs/models/*.md");
+
+    const query = cats.find((c) => c.name === "query")!;
+    expect(query.sourcePattern).toBe("modules/*/query/*.ts");
+    expect(query.docPattern).toBe("modules/*/docs/queries/*.md");
+  });
+});
+
+describe("appComposeCategories", () => {
+  it("produces resolver category", () => {
+    const cats = appComposeCategories("apps");
+    expect(cats).toHaveLength(1);
+    expect(cats[0].name).toBe("resolver");
+    expect(cats[0].docPattern).toBe("apps/*/docs/resolver/*.md");
+  });
+});
+
+describe("testCaseCategories", () => {
+  it("produces command and query test case categories", () => {
+    const cats = testCaseCategories("modules");
+    expect(cats).toHaveLength(2);
+    expect(cats[0].testDir).toBe("command");
+    expect(cats[1].testDir).toBe("query");
+  });
+});
+
+describe("buildCheckTargets", () => {
+  it("builds module check targets", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules" });
+    expect(targets).toHaveLength(5);
+    expect(targets.map((t) => t.schemaKey)).toEqual([
+      "feature",
+      "command",
+      "model",
+      "query",
+      "module",
+    ]);
+    expect(targets[0].glob).toBe("modules/[a-zA-Z]*/docs/features/*.md");
+  });
+
+  it("builds app check targets", () => {
+    const targets = buildCheckTargets({ appRoot: "apps" });
+    expect(targets).toHaveLength(6);
+    expect(targets.map((t) => t.schemaKey)).toContain("screen");
+    expect(targets.find((t) => t.schemaKey === "screen")!.glob).toBe(
+      "apps/[a-zA-Z]*/docs/screen/*.md",
+    );
+  });
+
+  it("builds both when both roots provided", () => {
+    const targets = buildCheckTargets({ modulesRoot: "modules", appRoot: "apps" });
+    expect(targets).toHaveLength(11);
+  });
+});