@neohm/nh-cli 1.1.5 → 1.3.0

package/src/commands/gen.flag.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+
+const { projectPaths, MODULE_SUBFOLDERS } = require('../lib/paths');
+const { assertFlavourMatchesProject, cli } = require('../lib/flavour');
+const naming = require('../lib/naming');
+const tpl = require('../lib/templates');
+const {
+  writeFile,
+  report: reportFile,
+  log,
+  ensureDir,
+} = require('../lib/fs.utils');
+const sync = require('../lib/sync.engine');
+const { formatFiles } = require('../lib/format');
+const { registerJob, registerEntity } = require('../lib/registry');
+const { findConflict, describeConflict } = require('../lib/collision');
+
+/**
+ * Single-artifact generation: `nh gen -c`, `-s`, `-dp`, `-lp`, `-e`, `-j`, and
+ * the `-x` (external, API-key surface) variants of the first four.
+ *
+ * Bare `nh gen` still runs the full wizard — this path exists for adding one
+ * more file to a module that already exists, which is most of the work after
+ * the initial scaffold.
+ */
+
+// Short noun, used in the name prompt and error messages.
+const LABELS = {
+  controller: 'controller',
+  service: 'service',
+  dataProcessor: 'data processor',
+  listProcessor: 'list processor',
+  entity: 'entity',
+  job: 'job',
+};
+
+// What the target actually writes, for the header line.
+const DESCRIBES = {
+  controller: 'controller',
+  service: 'service',
+  dataProcessor: 'data processor (+ its payload DTO)',
+  listProcessor: 'list processor',
+  entity: 'entity, its job and subscriber, and a migration',
+  job: 'job',
+};
+
+// `-x` mirrors a target under <module>/external/. Entities are tables and jobs
+// are queue workers — neither has an inward/outward face, so neither takes -x.
+const EXTERNAL_CAPABLE = new Set([
+  'controller',
+  'service',
+  'dataProcessor',
+  'listProcessor',
+]);
+
+const FLAG = {
+  controller: '-c',
+  service: '-s',
+  dataProcessor: '-dp',
+  listProcessor: '-lp',
+  entity: '-e',
+  job: '-j',
+};
+
+/**
+ * The files a target owns, as {className, file} pairs.
+ *
+ * "Owns" excludes anything reused rather than claimed: the payload DTO for
+ * -dp, the attributes DTO for -e, and the timestamped migration. Those are
+ * shared or unique-by-construction, so they are created when absent and left
+ * alone when present — only the artifacts listed here are name-checked.
+ *
+ * An entity owns three files, not one: TypeORM drives the job through the
+ * subscriber, so an entity without them is a table nothing reacts to. The
+ * wizard has always written all three together; -e does the same.
+ */
+function primaryArtifacts(target, moduleDir, n, external) {
+  const at = (...parts) =>
+    external
+      ? path.join(moduleDir, 'external', ...parts)
+      : path.join(moduleDir, ...parts);
+  const one = (className, ...parts) => [{ className, file: at(...parts) }];
+
+  switch (target) {
+    case 'controller':
+      return external
+        ? one(
+            n.externalControllerClass,
+            'controllers',
+            n.externalControllerFile,
+          )
+        : one(n.controllerClass, 'controllers', n.controllerFile);
+    case 'service':
+      return external
+        ? one(n.externalServiceClass, 'services', n.externalServiceFile)
+        : one(n.serviceClass, 'services', n.serviceFile);
+    case 'dataProcessor':
+      return external
+        ? one(n.externalProcessorClass, 'libraries', n.externalProcessorFile)
+        : one(n.processorClass, 'libraries', n.processorFile);
+    case 'listProcessor':
+      return external
+        ? one(
+            n.externalListProcessorClass,
+            'libraries',
+            n.externalListProcessorFile,
+          )
+        : one(n.listProcessorClass, 'libraries', n.listProcessorFile);
+    case 'entity':
+      return [
+        {
+          className: n.entityClass,
+          file: path.join(moduleDir, 'entities', n.entityFile),
+        },
+        {
+          className: n.jobClass,
+          file: path.join(moduleDir, 'jobs', n.jobFile),
+        },
+        {
+          className: n.subscriberClass,
+          file: path.join(moduleDir, 'subscribers', n.subscriberFile),
+        },
+      ];
+    case 'job':
+      return [
+        {
+          className: n.jobClass,
+          file: path.join(moduleDir, 'jobs', n.jobFile),
+        },
+      ];
+    default:
+      throw new Error(`Unknown target "${target}".`);
+  }
+}
+
+/** Create the module skeleton if this is the first file going into it. */
+function ensureModule(paths, moduleDot, external, report) {
+  const moduleDir = paths.moduleDir(moduleDot);
+  const existed = fs.existsSync(moduleDir);
+
+  for (const sub of MODULE_SUBFOLDERS) ensureDir(path.join(moduleDir, sub));
+  if (external) {
+    for (const sub of ['controllers', 'libraries', 'services']) {
+      ensureDir(path.join(moduleDir, 'external', sub));
+    }
+  }
+
+  const modulePath = path.join(moduleDir, `${moduleDot}.module.ts`);
+  const es6Path = path.join(moduleDir, 'es6.classes.ts');
+  const a = writeFile(modulePath, tpl.moduleFile(moduleDot));
+  const b = writeFile(es6Path, tpl.emptyEs6Classes());
+  if (a !== 'skipped') report(a, modulePath, paths.root);
+  if (b !== 'skipped') report(b, es6Path, paths.root);
+
+  if (!existed) log.info(`Created module "${moduleDot}".`);
+  return moduleDir;
+}
+
+async function genFlag(target, { external = false } = {}) {
+  if (!LABELS[target]) throw new Error(`Unknown target "${target}".`);
+  if (external && !EXTERNAL_CAPABLE.has(target)) {
+    throw new Error(
+      `-x is not supported for ${LABELS[target]} — external applies to ` +
+        `-c, -s, -dp and -lp only. Run \`nh gen ${FLAG[target]}\` without -x.`,
+    );
+  }
+
+  const paths = projectPaths();
+  assertFlavourMatchesProject(paths.root);
+  log.info(`Project: ${paths.root}\n`);
+
+  const touched = [];
+  const report = (result, filePath, root) => {
+    if (result !== 'skipped') touched.push(filePath);
+    reportFile(result, filePath, root);
+  };
+
+  log.info(`Generating: ${external ? 'external ' : ''}${DESCRIBES[target]}.`);
+
+  // 1. Module ---------------------------------------------------------------
+  const known = sync.scanModules(paths).map((m) => m.moduleDot);
+  const { moduleNameRaw } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'moduleNameRaw',
+      message: known.length
+        ? `Module name (existing: ${known.join(', ')}):`
+        : 'Module name:',
+      validate: (v) => (v && v.trim() ? true : 'Module name is required'),
+    },
+  ]);
+  const moduleDot = naming.toDotCase(moduleNameRaw);
+
+  // 2. Name -----------------------------------------------------------------
+  const { rawName } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'rawName',
+      message: `${LABELS[target].replace(/^./, (c) => c.toUpperCase())} name (PascalCase):`,
+      validate: (v) => (v && v.trim() ? true : 'Name is required'),
+    },
+  ]);
+  const n = tpl.names(rawName);
+
+  // 3. Target-specific answers ---------------------------------------------
+  let routePath;
+  if (target === 'controller') {
+    ({ routePath } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'routePath',
+        message: external
+          ? 'Route path (mounted at api/e/v1/<path>):'
+          : 'Route path (mounted at api/v1/<path>):',
+        default: n.kebab,
+        validate: (v) => (v && v.trim() ? true : 'Route path is required'),
+      },
+    ]));
+    routePath = routePath.trim().replace(/^\/+|\/+$/g, '');
+  }
+
+  let tableName;
+  if (target === 'listProcessor' || target === 'entity') {
+    ({ tableName } = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'tableName',
+        message:
+          target === 'entity' ? 'Table name:' : 'Table to list (table name):',
+        default: `nh_${naming.toWords(rawName).join('_')}s`,
+        validate: (v) => (v && v.trim() ? true : 'Table name is required'),
+      },
+    ]));
+    tableName = tableName.trim();
+  }
+
+  // 4. Refuse to shadow a name that is already taken ------------------------
+  // Checked for every artifact up front, so a target that writes three files
+  // does not create the first and then abort on the second.
+  const artifacts = primaryArtifacts(
+    target,
+    paths.moduleDir(moduleDot),
+    n,
+    external,
+  );
+  for (const artifact of artifacts) {
+    const conflict = findConflict(paths.srcDir, {
+      className: artifact.className,
+      fileName: path.basename(artifact.file),
+    });
+    if (conflict) {
+      throw new Error(
+        `${describeConflict(conflict, paths.root)}.\n` +
+          `  Pick a different name, or edit that file instead — ` +
+          `nothing was generated.`,
+      );
+    }
+  }
+  const dest = artifacts[0].file;
+
+  // 5. Write ----------------------------------------------------------------
+  const moduleDir = ensureModule(paths, moduleDot, external, report);
+  const write = (filePath, content) =>
+    report(writeFile(filePath, content), filePath, paths.root);
+
+  switch (target) {
+    case 'controller':
+      write(
+        dest,
+        external
+          ? tpl.bareExternalController(rawName, routePath)
+          : tpl.bareController(rawName, routePath),
+      );
+      break;
+
+    case 'service':
+      write(dest, tpl.bareService(rawName, { external }));
+      break;
+
+    case 'dataProcessor':
+      write(dest, tpl.processor(rawName, { external }));
+      // The processor's payload DTO lives in the module's dtos/ either way —
+      // created here only if it is not already there.
+      write(path.join(moduleDir, 'dtos', n.dtoFile), tpl.dto(rawName));
+      break;
+
+    case 'listProcessor':
+      write(dest, tpl.listProcessor(rawName, tableName, { external }));
+      break;
+
+    case 'entity': {
+      write(
+        path.join(moduleDir, 'dtos', n.attributesDtoFile),
+        tpl.attributesDto(rawName),
+      );
+      write(dest, tpl.entity(rawName, tableName));
+
+      // The entity's lifecycle hook and the job it drives. Same pair the
+      // wizard writes: the subscriber listens to the entity and hands each
+      // event to the job, which is why the job takes a DatabaseEventDto here
+      // rather than the loose payload `nh gen -j` scaffolds.
+      write(path.join(moduleDir, 'jobs', n.jobFile), tpl.job(rawName));
+      write(
+        path.join(moduleDir, 'subscribers', n.subscriberFile),
+        tpl.subscriber(rawName),
+      );
+
+      const ts = Date.now();
+      const migrationPath = path.join(
+        paths.migrationsDir,
+        naming.migrationFileName(n.migrationName, ts),
+      );
+      write(migrationPath, tpl.genMigration(rawName, tableName, ts));
+
+      registerEntity(paths, rawName, moduleDot, report);
+      registerJob(paths, rawName, moduleDot, report);
+      break;
+    }
+
+    case 'job':
+      write(dest, tpl.additionalJob(rawName));
+      registerJob(paths, rawName, moduleDot, report);
+      break;
+  }
+
+  // 6. Wire it into the barrel + app.module, then format -------------------
+  log.info('\nWiring imports...');
+  const mod = sync.scanModule(
+    moduleDir,
+    path.join(moduleDir, `${moduleDot}.module.ts`),
+  );
+  const written = sync.applyPlan(sync.buildPlan(paths, [mod]));
+  for (const w of written) report('overwritten', w, paths.root);
+  if (!written.length) log.info('  (already in sync)');
+
+  const formatted = await formatFiles(touched, paths.root);
+  if (formatted === null) {
+    log.info('  (prettier not installed — files left unformatted)');
+  } else if (formatted) {
+    log.info(`  formatted ${formatted} file(s)`);
+  }
+
+  const made = artifacts.map((a) => a.className).join(', ');
+  log.done(`${made} generated in "${moduleDot}".`);
+  console.log(
+    chalk.dim(
+      `Run \`${cli()} sync\` anytime to re-wire imports after manual edits.`,
+    ),
+  );
+}
+
+module.exports = genFlag;

package/src/commands/gen.js

@@ -6,21 +6,28 @@ const inquirer = require("inquirer");
 const chalk = require("chalk");
 
 const { projectPaths, MODULE_SUBFOLDERS } = require("../lib/paths");
+const { assertFlavourMatchesProject, cli } = require("../lib/flavour");
 const naming = require("../lib/naming");
 const tpl = require("../lib/templates");
-const { writeFile, report, log, ensureDir } = require("../lib/fs.utils");
+const { writeFile, report: reportFile, log, ensureDir } = require("../lib/fs.utils");
 const sync = require("../lib/sync.engine");
-const {
-  ensureConstantEntry,
-  ensureMapEntry,
-  detectExportName,
-  entityConstantsPath,
-} = require("../lib/constants.engine");
+const { formatFiles } = require("../lib/format");
+const { registerJob, registerEntity } = require("../lib/registry");
 
 async function gen() {
   const paths = projectPaths();
+  assertFlavourMatchesProject(paths.root);
   log.info(`Project: ${paths.root}\n`);
 
+  // Every file this run writes or rewrites, formatted in one pass at the end.
+  // Each write is announced through report(), so recording paths here catches
+  // templates, the constant registries, the es6 barrel and app.module alike.
+  const touched = [];
+  const report = (result, filePath, root) => {
+    if (result !== "skipped") touched.push(filePath);
+    reportFile(result, filePath, root);
+  };
+
   // 1. Module ---------------------------------------------------------------
   const { moduleNameRaw } = await inquirer.prompt([
     {
@@ -94,74 +101,8 @@ async function gen() {
 
   // Register the entity + job identifiers in the project constant registries
   // (the generated job references JobConstants.<name>Job, so the entry must exist).
-  const jobConstantsPath = path.join(paths.constantsDir, "job.constants.ts");
-  const jobEntry = ensureConstantEntry(
-    jobConstantsPath,
-    tpl.jobConstantsFile(entityName),
-    `${n.camel}Job`,
-    `${n.dot}.job`,
-  );
-  if (jobEntry === "failed") {
-    log.warn(`Could not update ${path.relative(paths.root, jobConstantsPath)} — add ${n.camel}Job: '${n.dot}.job' manually.`);
-  } else {
-    report(jobEntry, jobConstantsPath, paths.root);
-  }
-
-  const entityConstants = entityConstantsPath(paths.constantsDir);
-  const entityEntry = ensureConstantEntry(
-    entityConstants,
-    tpl.entityConstantsFile(entityName),
-    n.camel,
-    n.dot,
-  );
-  if (entityEntry === "failed") {
-    log.warn(`Could not update ${path.relative(paths.root, entityConstants)} — add ${n.camel}: '${n.dot}' manually.`);
-  } else {
-    report(entityEntry, entityConstants, paths.root);
-  }
-
-  // ...and mirror them in the identifier → class map registries.
-  const jobConstantsRef = {
-    exportName: detectExportName(jobConstantsPath) || "JobConstants",
-    importPath: "./job.constants",
-  };
-  const jobMapsPath = path.join(paths.constantsDir, "job.maps.ts");
-  const jobMapEntry = ensureMapEntry(
-    jobMapsPath,
-    tpl.jobMapsFile(entityName, moduleDot, jobConstantsRef),
-    `[${jobConstantsRef.exportName}.${n.camel}Job]`,
-    n.jobClass,
-    [
-      { className: n.jobClass, importPath: `../${moduleDot}/jobs/${n.dot}.job` },
-      { className: jobConstantsRef.exportName, importPath: jobConstantsRef.importPath },
-    ],
-  );
-  if (jobMapEntry === "failed") {
-    log.warn(`Could not update ${path.relative(paths.root, jobMapsPath)} — map ${n.jobClass} manually.`);
-  } else {
-    report(jobMapEntry, jobMapsPath, paths.root);
-  }
-
-  const entityConstantsRef = {
-    exportName: detectExportName(entityConstants) || "EntityConstants",
-    importPath: `./${path.basename(entityConstants, ".ts")}`,
-  };
-  const entityMapsPath = path.join(paths.constantsDir, "entity.maps.ts");
-  const entityMapEntry = ensureMapEntry(
-    entityMapsPath,
-    tpl.entityMapsFile(entityName, moduleDot, entityConstantsRef),
-    `[${entityConstantsRef.exportName}.${n.camel}]`,
-    n.entityClass,
-    [
-      { className: n.entityClass, importPath: `../${moduleDot}/entities/${n.dot}.entity` },
-      { className: entityConstantsRef.exportName, importPath: entityConstantsRef.importPath },
-    ],
-  );
-  if (entityMapEntry === "failed") {
-    log.warn(`Could not update ${path.relative(paths.root, entityMapsPath)} — map ${n.entityClass} manually.`);
-  } else {
-    report(entityMapEntry, entityMapsPath, paths.root);
-  }
+  registerJob(paths, entityName, moduleDot, report);
+  registerEntity(paths, entityName, moduleDot, report);
 
   // 4. Optional: controller -------------------------------------------------
   const { controller } = await inquirer.prompt([
@@ -173,8 +114,11 @@ async function gen() {
     },
   ]);
 
-  // (written after the listing-processor prompt — the answer decides whether
-  // the controller ships with a POST list endpoint)
+  // The service is always generated — it is the layer the controller and any
+  // job, subscriber or sibling service goes through, never an opt-in. It is
+  // written after the processor prompts, because those answers decide which
+  // methods it (and the controller) ships with: `get()` always, `upsert()`
+  // with a data processor, `list()` with a listing processor.
 
   // 5. Optional: data processor (includes Add*DataDto) ----------------------
   const { processor } = await inquirer.prompt([
@@ -213,10 +157,17 @@ async function gen() {
     );
   }
 
+  const servicePath = path.join(moduleDir, "services", n.serviceFile);
+  report(
+    writeFile(servicePath, tpl.service(entityName, { processor, listProcessor })),
+    servicePath,
+    paths.root,
+  );
+
   if (controller) {
     const p = path.join(moduleDir, "controllers", n.controllerFile);
     report(
-      writeFile(p, tpl.controller(entityName, { listProcessor })),
+      writeFile(p, tpl.controller(entityName, { processor, listProcessor })),
       p,
       paths.root,
     );
@@ -255,9 +206,20 @@ async function gen() {
   for (const w of written) report("overwritten", w, paths.root);
   if (!written.length) log.info("  (already in sync)");
 
+  // The boilerplate lints with `prettier/prettier: error`, so hand the
+  // generated files to the project's own prettier before declaring done.
+  const formatted = await formatFiles(touched, paths.root);
+  if (formatted === null) {
+    log.info("  (prettier not installed — files left unformatted)");
+  } else if (formatted) {
+    log.info(`  formatted ${formatted} file(s)`);
+  }
+
   log.done(`Module "${moduleDot}" scaffolded.`);
   console.log(
-    chalk.dim("Run `nh sync` anytime to re-wire imports after manual edits."),
+    chalk.dim(
+      `Run \`${cli()} sync\` anytime to re-wire imports after manual edits.`,
+    ),
   );
 }
 

package/src/commands/migration.js

@@ -4,12 +4,14 @@ const path = require("path");
 const inquirer = require("inquirer");
 
 const { projectPaths } = require("../lib/paths");
+const { assertFlavourMatchesProject } = require("../lib/flavour");
 const naming = require("../lib/naming");
 const tpl = require("../lib/templates");
 const { writeFile, report, log } = require("../lib/fs.utils");
 
 async function migration() {
   const paths = projectPaths();
+  assertFlavourMatchesProject(paths.root);
 
   const { tableName, migrationName } = await inquirer.prompt([
     {

package/src/commands/seed.js

@@ -4,12 +4,14 @@ const path = require("path");
 const inquirer = require("inquirer");
 
 const { projectPaths } = require("../lib/paths");
+const { assertFlavourMatchesProject } = require("../lib/flavour");
 const naming = require("../lib/naming");
 const tpl = require("../lib/templates");
 const { writeFile, report, log } = require("../lib/fs.utils");
 
 async function seed() {
   const paths = projectPaths();
+  assertFlavourMatchesProject(paths.root);
 
   const { tableName, seedName } = await inquirer.prompt([
     {

package/src/index.js

@@ -3,6 +3,7 @@
 const { Command } = require('commander');
 const chalk = require('chalk');
 const pkg = require('../package.json');
+const flavour = require('./lib/flavour');
 
 const program = new Command();
 
@@ -17,15 +18,77 @@ function run(action) {
   };
 }
 
+// `nh` and `nhx` are the same program against different packages: the bin
+// entrypoint picks the flavour before this module is required, and everything
+// that generates code reads it from there.
+const { cli, package: packageName } = flavour.current();
+
 program
-  .name('nh')
-  .description('nh — scaffolding CLI for neohm. NestJS projects (built on @neohm/nestend)')
+  .name(cli)
+  .description(
+    `${cli} — scaffolding CLI for neohm. NestJS projects (built on ${packageName})`,
+  )
   .version(pkg.version, '-v, --version', 'output the current version');
 
+// `gen` with no target flag runs the full wizard; a target flag generates just
+// that one artifact. -x mirrors a target onto the module's external (API-key)
+// surface and applies to -c, -s, -dp and -lp only.
+const GEN_TARGETS = [
+  ['controller', 'controller'],
+  ['service', 'service'],
+  ['dataProcessor', 'dataProcessor'],
+  ['listProcessor', 'listProcessor'],
+  ['entity', 'entity'],
+  ['job', 'job'],
+];
+
 program
   .command('gen')
-  .description('interactive scaffolding wizard (module, entity, controller, dto, processor, migration)')
-  .action(run(() => require('./commands/gen')()));
+  .description(
+    'scaffolding wizard; with a flag, generate one artifact instead',
+  )
+  .option('-c, --controller', 'generate only a controller')
+  .option('-s, --service', 'generate only a service')
+  .option('-dp, --data-processor', 'generate only a data processor')
+  .option('-lp, --list-processor', 'generate only a listing processor')
+  .option('-e, --entity', 'generate an entity and its migration')
+  .option('-j, --job', 'generate only a job')
+  .option('-x, --external', 'put it on the external (api/e/v1) surface')
+  .addHelpText(
+    'after',
+    `
+Examples:
+  ${cli} gen                 full wizard: module, entity, controller, service, ...
+  ${cli} gen -c              controller only (asks module, name, route path)
+  ${cli} gen -s              bare injectable service
+  ${cli} gen -dp             data processor (+ its Add<Name>DataDto if missing)
+  ${cli} gen -lp             listing processor
+  ${cli} gen -e              entity + migration, registered in the constants/maps
+  ${cli} gen -j              job, registered in job.constants/job.maps
+  ${cli} gen -x -c           external controller under <module>/external/controllers
+  ${cli} gen -x -dp          external data processor under <module>/external/libraries`,
+  )
+  .action(
+    run((opts) => {
+      const chosen = GEN_TARGETS.filter(([key]) => opts[key]).map(
+        ([, target]) => target,
+      );
+      if (chosen.length > 1) {
+        throw new Error(
+          'Pick one target flag at a time (-c, -s, -dp, -lp, -e or -j).',
+        );
+      }
+      if (!chosen.length) {
+        if (opts.external) {
+          throw new Error('-x needs a target: -c, -s, -dp or -lp.');
+        }
+        return require('./commands/gen')();
+      }
+      return require('./commands/gen.flag')(chosen[0], {
+        external: Boolean(opts.external),
+      });
+    }),
+  );
 
 program
   .command('migration')