@tailor-platform/erp-kit 0.2.2 → 0.3.0

package/src/commands/app/index.ts

@@ -1,14 +1,17 @@
+import path from "node:path";
 import { z } from "zod";
 import { defineCommand, arg } from "politty";
 import { runCheck } from "../check";
 import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
-import { runScaffold, APP_TYPES, type ScaffoldType } from "../scaffold";
+import { runGenerateDoc, APP_DOC_TYPES, type DocType } from "../generate-doc";
+import { runGenerateAppCode } from "../../generator/generate-code";
+import { runInitAppWithReadme } from "../init-module";
 
 const cwd = process.cwd();
 
-const rootArgs = z.object({
-  root: arg(z.string(), {
-    alias: "r",
+const pathArgs = z.object({
+  path: arg(z.string(), {
+    alias: "p",
     description: "Path to app-compose directory",
   }),
 });
@@ -16,9 +19,9 @@ const rootArgs = z.object({
 const checkCommand = defineCommand({
   name: "check",
   description: "Validate app docs against schemas",
-  args: rootArgs,
+  args: pathArgs,
   run: async (args) => {
-    const exitCode = await runCheck({ appRoot: args.root }, cwd);
+    const exitCode = await runCheck({ appRoot: args.path }, cwd);
     process.exit(exitCode);
   },
 });
@@ -26,25 +29,40 @@ const checkCommand = defineCommand({
 const syncCheckCommand = defineCommand({
   name: "sync-check",
   description: "Validate source <-> doc correspondence",
-  args: rootArgs,
+  args: pathArgs,
   run: async (args) => {
-    const result = await runSyncCheck({ appRoot: args.root }, cwd);
+    const result = await runSyncCheck({ appRoot: args.path }, 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[]]), {
+const initCommand = defineCommand({
+  name: "init",
+  description: "Bootstrap a new app with directory structure and README",
+  args: z.object({
+    name: arg(z.string(), {
       positional: true,
-      description: `Scaffold type (${APP_TYPES.join(", ")})`,
+      description: "App name",
     }),
-    parent: arg(z.string(), {
+    dir: arg(z.string(), {
       positional: true,
-      description: "App name",
+      description: "Parent directory where the app will be created",
+    }),
+  }),
+  run: async (args) => {
+    const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const docCommand = defineCommand({
+  name: "doc",
+  description: "Create a documentation file from a schema template",
+  args: pathArgs.extend({
+    type: arg(z.enum(APP_DOC_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Doc type (${APP_DOC_TYPES.join(", ")})`,
     }),
     name: arg(z.string().optional(), {
       positional: true,
@@ -52,23 +70,38 @@ const scaffoldCommand = defineCommand({
     }),
   }),
   run: async (args) => {
-    const exitCode = await runScaffold(
-      args.type as ScaffoldType,
-      args.parent,
-      args.name,
-      args.root,
-      cwd,
-    );
+    const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const codeCommand = defineCommand({
+  name: "code",
+  description: "Generate boilerplate source files from docs",
+  args: pathArgs,
+  run: (args) => {
+    const appPath = path.resolve(cwd, args.path);
+    const exitCode = runGenerateAppCode(appPath);
     process.exit(exitCode);
   },
 });
 
+const generateCommand = defineCommand({
+  name: "generate",
+  description: "Generate docs and code for an app",
+  subCommands: {
+    doc: docCommand,
+    code: codeCommand,
+  },
+});
+
 export const appCommand = defineCommand({
   name: "app",
   description: "App-compose management",
   subCommands: {
     check: checkCommand,
     "sync-check": syncCheckCommand,
-    scaffold: scaffoldCommand,
+    init: initCommand,
+    generate: generateCommand,
   },
 });

package/src/commands/generate-doc.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from "vitest";
+import { resolveDocPath } from "./generate-doc";
+
+describe("resolveDocPath", () => {
+  it("resolves command doc path", () => {
+    const result = resolveDocPath("command", "CreateOrder", "modules/inventory");
+    expect(result).toBe("modules/inventory/docs/commands/CreateOrder.md");
+  });
+
+  it("resolves feature doc path", () => {
+    const result = resolveDocPath("feature", "stock-tracking", "modules/inventory");
+    expect(result).toBe("modules/inventory/docs/features/stock-tracking.md");
+  });
+
+  it("resolves model doc path", () => {
+    const result = resolveDocPath("model", "StockItem", "modules/inventory");
+    expect(result).toBe("modules/inventory/docs/models/StockItem.md");
+  });
+
+  it("resolves query doc path", () => {
+    const result = resolveDocPath("query", "ConvertQuantity", "modules/inventory");
+    expect(result).toBe("modules/inventory/docs/queries/ConvertQuantity.md");
+  });
+
+  it("resolves actors doc path", () => {
+    const result = resolveDocPath("actors", "admin", "examples/my-app");
+    expect(result).toBe("examples/my-app/docs/actors/admin.md");
+  });
+
+  it("resolves business-flow doc path", () => {
+    const result = resolveDocPath("business-flow", "onboarding", "examples/my-app");
+    expect(result).toBe("examples/my-app/docs/business-flow/onboarding/README.md");
+  });
+
+  it("resolves story doc path with flow/name format", () => {
+    const result = resolveDocPath("story", "onboarding/admin--create-user", "examples/my-app");
+    expect(result).toBe(
+      "examples/my-app/docs/business-flow/onboarding/story/admin--create-user.md",
+    );
+  });
+
+  it("resolves screen doc path", () => {
+    const result = resolveDocPath("screen", "supplier-list", "examples/my-app");
+    expect(result).toBe("examples/my-app/docs/screen/supplier-list.md");
+  });
+
+  it("resolves resolver doc path", () => {
+    const result = resolveDocPath("resolver", "create-supplier", "examples/my-app");
+    expect(result).toBe("examples/my-app/docs/resolver/create-supplier.md");
+  });
+
+  it("throws when name is missing", () => {
+    expect(() => resolveDocPath("command", undefined, "modules/inventory")).toThrow(
+      "Name is required",
+    );
+  });
+
+  it("throws when story name is not flow/name format", () => {
+    expect(() => resolveDocPath("story", "bad-name", "examples/my-app")).toThrow(
+      "Story name must be",
+    );
+  });
+});

package/src/commands/generate-doc.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+import fs from "node:fs";
+import { runMdschema } from "../mdschema";
+import { ALL_SCHEMAS } from "../schemas";
+
+export const MODULE_DOC_TYPES = ["feature", "command", "model", "query"] as const;
+export const APP_DOC_TYPES = ["actors", "business-flow", "story", "screen", "resolver"] as const;
+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",
+};
+
+const APP_DIR_MAP: Record<string, string> = {
+  actors: "docs/actors",
+  "business-flow": "docs/business-flow",
+  screen: "docs/screen",
+  resolver: "docs/resolver",
+};
+
+export function resolveDocPath(
+  type: DocType,
+  name: string | undefined,
+  modulePath: string,
+): string {
+  if (!name) {
+    throw new Error(`Name is required for doc type "${type}"`);
+  }
+
+  if (type === "business-flow") {
+    return path.join(modulePath, "docs/business-flow", name, "README.md");
+  }
+
+  if (type === "story") {
+    const parts = name.split("/");
+    if (parts.length !== 2) {
+      throw new Error(
+        `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`);
+  }
+
+  if (MODULE_DIR_MAP[type]) {
+    return path.join(modulePath, MODULE_DIR_MAP[type], `${name}.md`);
+  }
+
+  if (APP_DIR_MAP[type]) {
+    return path.join(modulePath, APP_DIR_MAP[type], `${name}.md`);
+  }
+
+  throw new Error(`Unknown doc type: ${type}`);
+}
+
+export async function runGenerateDoc(
+  type: DocType,
+  name: string | undefined,
+  modulePath: string,
+  cwd: string,
+): Promise<number> {
+  const outputPath = resolveDocPath(type, name, modulePath);
+  const absoluteOutput = path.resolve(cwd, outputPath);
+
+  if (fs.existsSync(absoluteOutput)) {
+    console.error(`File already exists: ${outputPath}`);
+    return 1;
+  }
+
+  const schemaPath = ALL_SCHEMAS[type];
+  if (!schemaPath) {
+    console.error(`No schema found for type: ${type}`);
+    return 2;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(absoluteOutput), { recursive: true });
+  } catch (err) {
+    console.error(
+      `Failed to create directory: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return 1;
+  }
+
+  const { exitCode, stdout, stderr } = await runMdschema(
+    ["generate", "--schema", schemaPath, "--output", absoluteOutput],
+    cwd,
+  );
+
+  if (stdout.trim()) console.log(stdout);
+  if (stderr.trim()) console.error(stderr);
+
+  return exitCode;
+}

package/src/commands/init-module.test.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect, afterEach } from "vitest";
+import { runInitModule, runInitApp } from "./init-module";
+
+describe("runInitModule", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("creates module directory", () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "init-module-test-"));
+    const moduleDir = path.join(tmpDir, "my-module");
+    fs.mkdirSync(moduleDir, { recursive: true });
+
+    const exitCode = runInitModule("my-module", tmpDir);
+    expect(exitCode).toBe(1); // should fail — dir exists
+  });
+});
+
+describe("runInitApp", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  it("errors if app directory already exists", () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "init-app-test-"));
+    const appDir = path.join(tmpDir, "my-app");
+    fs.mkdirSync(appDir, { recursive: true });
+
+    const exitCode = runInitApp("my-app", tmpDir);
+    expect(exitCode).toBe(1);
+  });
+});

package/src/commands/init-module.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import fs from "node:fs";
+import { runMdschema } from "../mdschema";
+import { MODULE_SCHEMAS, APP_COMPOSE_SCHEMAS } from "../schemas";
+
+export function runInitModule(name: string, dir: string): number {
+  const moduleDir = path.resolve(dir, name);
+
+  if (fs.existsSync(moduleDir)) {
+    console.error(`Directory already exists: ${moduleDir}`);
+    return 1;
+  }
+
+  fs.mkdirSync(moduleDir, { recursive: true });
+  return 0;
+}
+
+export async function runInitModuleWithReadme(
+  name: string,
+  dir: string,
+  cwd: string,
+): Promise<number> {
+  const initResult = runInitModule(name, dir);
+  if (initResult !== 0) return initResult;
+
+  const moduleDir = path.resolve(cwd, dir, name);
+  const readmePath = path.join(moduleDir, "README.md");
+  const schemaPath = MODULE_SCHEMAS.module;
+
+  const { exitCode, stdout, stderr } = await runMdschema(
+    ["generate", "--schema", schemaPath, "--output", readmePath],
+    cwd,
+  );
+
+  if (stdout.trim()) console.log(stdout);
+  if (stderr.trim()) console.error(stderr);
+
+  return exitCode;
+}
+
+export function runInitApp(name: string, dir: string): number {
+  const appDir = path.resolve(dir, name);
+
+  if (fs.existsSync(appDir)) {
+    console.error(`Directory already exists: ${appDir}`);
+    return 1;
+  }
+
+  fs.mkdirSync(appDir, { recursive: true });
+  return 0;
+}
+
+export async function runInitAppWithReadme(
+  name: string,
+  dir: string,
+  cwd: string,
+): Promise<number> {
+  const initResult = runInitApp(name, dir);
+  if (initResult !== 0) return initResult;
+
+  const appDir = path.resolve(cwd, dir, name);
+  const readmePath = path.join(appDir, "README.md");
+  const schemaPath = APP_COMPOSE_SCHEMAS.app;
+
+  const { exitCode, stdout, stderr } = await runMdschema(
+    ["generate", "--schema", schemaPath, "--output", readmePath],
+    cwd,
+  );
+
+  if (stdout.trim()) console.log(stdout);
+  if (stderr.trim()) console.error(stderr);
+
+  return exitCode;
+}

package/src/commands/module/generate.ts

@@ -2,34 +2,54 @@ import path from "node:path";
 import { defineCommand, arg } from "politty";
 import { z } from "zod";
 import { runGenerateCode } from "../../generator/generate-code";
+import { runGenerateDoc, MODULE_DOC_TYPES, type DocType } from "../generate-doc";
 
 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",
+const pathArgs = z.object({
+  path: arg(z.string(), {
+    alias: "p",
+    description: "Path to the module directory",
+  }),
+});
+
+const docCommand = defineCommand({
+  name: "doc",
+  description: "Create a documentation file from a schema template",
+  args: pathArgs.extend({
+    type: arg(z.enum(MODULE_DOC_TYPES as unknown as [string, ...string[]]), {
+      positional: true,
+      description: `Doc type (${MODULE_DOC_TYPES.join(", ")})`,
     }),
-    module: arg(z.string(), {
+    name: arg(z.string().optional(), {
       positional: true,
-      description: "Module name (e.g., primitives, item-management)",
+      description: "Item name (required for all types)",
     }),
   }),
+  run: async (args) => {
+    const exitCode = await runGenerateDoc(args.type as DocType, args.name, args.path, cwd);
+    process.exit(exitCode);
+  },
+});
+
+const codeCommand = defineCommand({
+  name: "code",
+  description: "Generate boilerplate, implementation stubs, and generated code from docs",
+  args: pathArgs,
   run: (args) => {
-    const modulePath = path.resolve(cwd, args.root, args.module);
-    console.log(`Generating code for ${args.module}...`);
-    const exitCode = runGenerateCode(modulePath, args.module);
+    const modulePath = path.resolve(cwd, args.path);
+    const moduleName = path.basename(modulePath);
+    console.log(`Generating code for ${moduleName}...`);
+    const exitCode = runGenerateCode(modulePath, moduleName);
     process.exit(exitCode);
   },
 });
 
 export const generateCommand = defineCommand({
   name: "generate",
-  description: "Generate code from model definitions and docs",
+  description: "Generate docs and code for a module",
   subCommands: {
+    doc: docCommand,
     code: codeCommand,
   },
 });

package/src/commands/module/index.ts

@@ -1,16 +1,16 @@
 import { z } from "zod";
 import { defineCommand, arg } from "politty";
 import { runCheck } from "../check";
+import { runInitModuleWithReadme } from "../init-module";
 import { runSyncCheck, formatSyncCheckReport } from "../sync-check";
-import { runScaffold, MODULE_TYPES, type ScaffoldType } from "../scaffold";
-import { runModuleList } from "./list";
 import { generateCommand } from "./generate";
+import { runModuleList } from "./list";
 
 const cwd = process.cwd();
 
-const rootArgs = z.object({
-  root: arg(z.string(), {
-    alias: "r",
+const pathArgs = z.object({
+  path: arg(z.string(), {
+    alias: "p",
     description: "Path to modules directory",
   }),
 });
@@ -27,9 +27,9 @@ const listCommand = defineCommand({
 const checkCommand = defineCommand({
   name: "check",
   description: "Validate module docs against schemas",
-  args: rootArgs,
+  args: pathArgs,
   run: async (args) => {
-    const exitCode = await runCheck({ modulesRoot: args.root }, cwd);
+    const exitCode = await runCheck({ modulesRoot: args.path }, cwd);
     process.exit(exitCode);
   },
 });
@@ -37,39 +37,29 @@ const checkCommand = defineCommand({
 const syncCheckCommand = defineCommand({
   name: "sync-check",
   description: "Validate source <-> doc correspondence",
-  args: rootArgs,
+  args: pathArgs,
   run: async (args) => {
-    const result = await runSyncCheck({ modulesRoot: args.root }, cwd);
+    const result = await runSyncCheck({ modulesRoot: args.path }, 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(), {
+const initCommand = defineCommand({
+  name: "init",
+  description: "Bootstrap a new module with directory structure and README",
+  args: z.object({
+    name: arg(z.string(), {
       positional: true,
       description: "Module name",
     }),
-    name: arg(z.string().optional(), {
+    dir: arg(z.string(), {
       positional: true,
-      description: "Item name (required for feature, command, model)",
+      description: "Parent directory where the module will be created",
     }),
   }),
   run: async (args) => {
-    const exitCode = await runScaffold(
-      args.type as ScaffoldType,
-      args.parent,
-      args.name,
-      args.root,
-      cwd,
-    );
+    const exitCode = await runInitModuleWithReadme(args.name, args.dir, cwd);
     process.exit(exitCode);
   },
 });
@@ -81,7 +71,7 @@ export const moduleCommand = defineCommand({
     list: listCommand,
     check: checkCommand,
     "sync-check": syncCheckCommand,
-    scaffold: scaffoldCommand,
+    init: initCommand,
     generate: generateCommand,
   },
 });