@forinda/kickjs-cli 1.2.1 → 1.2.3

package/dist/cli.js

@@ -22,7 +22,13 @@ import { fileURLToPath } from "url";
 // src/utils/fs.ts
 import { writeFile, mkdir, access, readFile } from "fs/promises";
 import { dirname } from "path";
+var _dryRun = false;
+function setDryRun(enabled) {
+  _dryRun = enabled;
+}
+__name(setDryRun, "setDryRun");
 async function writeFileSafe(filePath, content) {
+  if (_dryRun) return;
   await mkdir(dirname(filePath), {
     recursive: true
   });
@@ -266,6 +272,7 @@ export default defineConfig({
   },
 })
 `);
+  await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
   if (options.initGit) {
     try {
       execSync("git init", {
@@ -423,6 +430,91 @@ bootstrap({
   }
 }
 __name(getEntryFile, "getEntryFile");
+function generateReadme(name, template, pm) {
+  const templateLabels = {
+    rest: "REST API",
+    graphql: "GraphQL API",
+    ddd: "Domain-Driven Design",
+    cqrs: "CQRS + Event-Driven",
+    minimal: "Minimal"
+  };
+  const packages = [
+    "@forinda/kickjs-core",
+    "@forinda/kickjs-http",
+    "@forinda/kickjs-config"
+  ];
+  if (template !== "minimal") {
+    packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
+  }
+  if (template === "graphql") packages.push("@forinda/kickjs-graphql");
+  if (template === "cqrs") {
+    packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws", "@forinda/kickjs-otel");
+  }
+  return `# ${name}
+
+A **${templateLabels[template] ?? "REST API"}** built with [KickJS](https://forinda.github.io/kick-js/) \u2014 a decorator-driven Node.js framework on Express 5 and TypeScript.
+
+## Getting Started
+
+\`\`\`bash
+${pm} install
+kick dev
+\`\`\`
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| \`kick dev\` | Start dev server with Vite HMR |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`${pm} run test\` | Run tests with Vitest |
+| \`kick g module <name>\` | Generate a DDD module |
+| \`kick g scaffold <name> <fields...>\` | Generate CRUD from field definitions |
+| \`kick add <package>\` | Add a KickJS package |
+
+## Project Structure
+
+\`\`\`
+src/
+\u251C\u2500\u2500 index.ts           # Application entry point
+\u251C\u2500\u2500 modules/           # Feature modules (controllers, services, repos)
+\u2502   \u2514\u2500\u2500 index.ts       # Module registry
+\u2514\u2500\u2500 ...
+\`\`\`
+
+## Packages
+
+${packages.map((p) => `- \`${p}\``).join("\n")}
+
+## Adding Features
+
+\`\`\`bash
+kick add auth          # Authentication (JWT, API key, OAuth)
+kick add swagger       # OpenAPI documentation
+kick add ws            # WebSocket support
+kick add queue         # Background job processing
+kick add mailer        # Email sending
+kick add cron          # Scheduled tasks
+kick add --list        # Show all available packages
+\`\`\`
+
+## Environment Variables
+
+Copy \`.env.example\` to \`.env\` and configure:
+
+| Variable | Default | Description |
+|---|---|---|
+| \`PORT\` | \`3000\` | Server port |
+| \`NODE_ENV\` | \`development\` | Environment |
+
+## Learn More
+
+- [KickJS Documentation](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+`;
+}
+__name(generateReadme, "generateReadme");
 
 // src/commands/init.ts
 function ask(question, defaultValue) {
@@ -1926,7 +2018,7 @@ function promptUser(question) {
 }
 __name(promptUser, "promptUser");
 async function generateModule(options) {
-  const { name, modulesDir, noEntity, noTests, repo = "inmemory", force } = options;
+  const { name, modulesDir, noEntity, noTests, repo = "inmemory", force, dryRun } = options;
   let pattern = options.pattern ?? "ddd";
   if (options.minimal) pattern = "minimal";
   const kebab = toKebabCase(name);
@@ -1938,6 +2030,10 @@ async function generateModule(options) {
   let overwriteAll = force ?? false;
   const write = /* @__PURE__ */ __name(async (relativePath, content) => {
     const fullPath = join2(moduleDir, relativePath);
+    if (dryRun) {
+      files.push(fullPath);
+      return;
+    }
     if (!overwriteAll && await fileExists(fullPath)) {
       const answer = await promptUser(`  File already exists: ${relativePath}
   Overwrite? (y/n/a = yes/no/all) `);
@@ -1979,7 +2075,9 @@ async function generateModule(options) {
       await generateDddFiles(ctx);
       break;
   }
-  await autoRegisterModule(modulesDir, pascal, plural);
+  if (!dryRun) {
+    await autoRegisterModule(modulesDir, pascal, plural);
+  }
   return files;
 }
 __name(generateModule, "generateModule");
@@ -3299,13 +3397,19 @@ async function loadKickConfig(cwd) {
 __name(loadKickConfig, "loadKickConfig");
 
 // src/commands/generate.ts
-function printGenerated(files) {
+function isDryRun(cmd) {
+  return cmd.parent?.opts()?.dryRun ?? false;
+}
+__name(isDryRun, "isDryRun");
+function printGenerated(files, dryRun = false) {
   const cwd = process.cwd();
+  const label = dryRun ? "Would generate" : "Generated";
   console.log(`
-  Generated ${files.length} file${files.length === 1 ? "" : "s"}:`);
+  ${label} ${files.length} file${files.length === 1 ? "" : "s"}:`);
   for (const f of files) {
     console.log(`    ${f.replace(cwd + "/", "")}`);
   }
+  if (dryRun) console.log("\n  (dry run \u2014 no files were written)");
   console.log();
 }
 __name(printGenerated, "printGenerated");
@@ -3369,14 +3473,16 @@ function printGeneratorList() {
 }
 __name(printGeneratorList, "printGeneratorList");
 function registerGenerateCommand(program) {
-  const gen = program.command("generate").alias("g").description("Generate code scaffolds").option("--list", "List all available generators").action((opts) => {
+  const gen = program.command("generate").alias("g").description("Generate code scaffolds").option("--list", "List all available generators").option("--dry-run", "Preview files that would be generated without writing them").action((opts) => {
     if (opts.list) {
       printGeneratorList();
     } else {
       gen.help();
     }
   });
-  gen.command("module <name>").description("Generate a module (structure depends on project pattern)").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("-f, --force", "Overwrite existing files without prompting").action(async (name, opts) => {
+  gen.command("module <name>").description("Generate a module (structure depends on project pattern)").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--repo <type>", "Repository implementation: inmemory | drizzle | prisma").option("--pattern <pattern>", "Override project pattern: rest | ddd | cqrs | minimal").option("--minimal", "Shorthand for --pattern minimal").option("--modules-dir <dir>", "Modules directory").option("-f, --force", "Overwrite existing files without prompting").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = opts.modulesDir ?? config?.modulesDir ?? "src/modules";
     const repo = opts.repo ?? config?.defaultRepo ?? "inmemory";
@@ -3389,18 +3495,23 @@ function registerGenerateCommand(program) {
       repo,
       minimal: opts.minimal,
       force: opts.force,
-      pattern
+      pattern,
+      dryRun
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("adapter <name>").description("Generate an AppAdapter with lifecycle hooks and middleware support").option("-o, --out <dir>", "Output directory", "src/adapters").action(async (name, opts) => {
+  gen.command("adapter <name>").description("Generate an AppAdapter with lifecycle hooks and middleware support").option("-o, --out <dir>", "Output directory", "src/adapters").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const files = await generateAdapter({
       name,
       outDir: resolve4(opts.out)
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("middleware <name>").description("Generate an Express middleware function\n  Use -m to scope it to a module: kick g middleware auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts) => {
+  gen.command("middleware <name>").description("Generate an Express middleware function\n  Use -m to scope it to a module: kick g middleware auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateMiddleware({
@@ -3410,9 +3521,11 @@ function registerGenerateCommand(program) {
       modulesDir,
       pattern: config?.pattern
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("guard <name>").description("Generate a route guard (auth, roles, etc.)\n  Use -m to scope it to a module: kick g guard admin -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts) => {
+  gen.command("guard <name>").description("Generate a route guard (auth, roles, etc.)\n  Use -m to scope it to a module: kick g guard admin -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateGuard({
@@ -3422,9 +3535,11 @@ function registerGenerateCommand(program) {
       modulesDir,
       pattern: config?.pattern
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("service <name>").description("Generate a @Service() class\n  Use -m to scope it to a module: kick g service payment -m orders").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts) => {
+  gen.command("service <name>").description("Generate a @Service() class\n  Use -m to scope it to a module: kick g service payment -m orders").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateService({
@@ -3434,9 +3549,11 @@ function registerGenerateCommand(program) {
       modulesDir,
       pattern: config?.pattern
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("controller <name>").description("Generate a @Controller() class with basic routes\n  Use -m to scope it to a module: kick g controller auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts) => {
+  gen.command("controller <name>").description("Generate a @Controller() class with basic routes\n  Use -m to scope it to a module: kick g controller auth -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateController2({
@@ -3446,9 +3563,11 @@ function registerGenerateCommand(program) {
       modulesDir,
       pattern: config?.pattern
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("dto <name>").description("Generate a Zod DTO schema\n  Use -m to scope it to a module: kick g dto create-user -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts) => {
+  gen.command("dto <name>").description("Generate a Zod DTO schema\n  Use -m to scope it to a module: kick g dto create-user -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateDto({
@@ -3458,9 +3577,11 @@ function registerGenerateCommand(program) {
       modulesDir,
       pattern: config?.pattern
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("test <name>").description("Generate a Vitest test scaffold\n  Use -m to scope it to a module: kick g test user-service -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module's __tests__/ folder").action(async (name, opts) => {
+  gen.command("test <name>").description("Generate a Vitest test scaffold\n  Use -m to scope it to a module: kick g test user-service -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module's __tests__/ folder").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const config = await loadKickConfig(process.cwd());
     const modulesDir = config?.modulesDir ?? "src/modules";
     const files = await generateTest({
@@ -3469,24 +3590,30 @@ function registerGenerateCommand(program) {
       moduleName: opts.module,
       modulesDir
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("resolver <name>").description("Generate a GraphQL @Resolver class with @Query and @Mutation methods").option("-o, --out <dir>", "Output directory", "src/resolvers").action(async (name, opts) => {
+  gen.command("resolver <name>").description("Generate a GraphQL @Resolver class with @Query and @Mutation methods").option("-o, --out <dir>", "Output directory", "src/resolvers").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const files = await generateResolver({
       name,
       outDir: resolve4(opts.out)
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("job <name>").description("Generate a @Job queue processor with @Process handlers").option("-o, --out <dir>", "Output directory", "src/jobs").option("-q, --queue <name>", "Queue name (default: <name>-queue)").action(async (name, opts) => {
+  gen.command("job <name>").description("Generate a @Job queue processor with @Process handlers").option("-o, --out <dir>", "Output directory", "src/jobs").option("-q, --queue <name>", "Queue name (default: <name>-queue)").action(async (name, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const files = await generateJob({
       name,
       outDir: resolve4(opts.out),
       queue: opts.queue
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text published:boolean?\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Append ? for optional fields: description:text?").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts) => {
+  gen.command("scaffold <name> [fields...]").description("Generate a full CRUD module from field definitions\n  Example: kick g scaffold Post title:string body:text published:boolean?\n  Types: string, text, number, int, float, boolean, date, email, url, uuid, json, enum:a,b,c\n  Append ? for optional fields: description:text?").option("--no-entity", "Skip entity and value object generation").option("--no-tests", "Skip test file generation").option("--modules-dir <dir>", "Modules directory").action(async (name, rawFields, opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     if (rawFields.length === 0) {
       console.error("\n  Error: At least one field is required.\n  Usage: kick g scaffold <name> <field:type> [field:type...]\n  Example: kick g scaffold Post title:string body:text published:boolean\n");
       process.exit(1);
@@ -3506,16 +3633,18 @@ function registerGenerateCommand(program) {
     for (const f of fields) {
       console.log(`    ${f.name}: ${f.type}${f.optional ? " (optional)" : ""}`);
     }
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
-  gen.command("config").description("Generate a kick.config.ts at the project root").option("--modules-dir <dir>", "Modules directory path", "src/modules").option("--repo <type>", "Default repository type: inmemory | drizzle | prisma", "inmemory").option("-f, --force", "Overwrite existing kick.config.ts without prompting").action(async (opts) => {
+  gen.command("config").description("Generate a kick.config.ts at the project root").option("--modules-dir <dir>", "Modules directory path", "src/modules").option("--repo <type>", "Default repository type: inmemory | drizzle | prisma", "inmemory").option("-f, --force", "Overwrite existing kick.config.ts without prompting").action(async (opts, cmd) => {
+    const dryRun = isDryRun(cmd);
+    setDryRun(dryRun);
     const files = await generateConfig({
       outDir: resolve4("."),
       modulesDir: opts.modulesDir,
       defaultRepo: opts.repo,
       force: opts.force
     });
-    printGenerated(files);
+    printGenerated(files, dryRun);
   });
 }
 __name(registerGenerateCommand, "registerGenerateCommand");