@neohm/nh-cli 1.1.4 → 1.2.0

package/src/commands/gen.js

@@ -8,19 +8,24 @@ const chalk = require("chalk");
 const { projectPaths, MODULE_SUBFOLDERS } = require("../lib/paths");
 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();
   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 +99,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 +112,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 +155,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,6 +204,15 @@ 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."),

package/src/index.js

@@ -22,10 +22,65 @@ program
   .description('nh — scaffolding CLI for neohm. NestJS projects (built on @neohm/nestend)')
   .version(pkg.version, '-v, --version', 'output the current version');
 
+// `nh 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:
+  nh gen                 full wizard: module, entity, controller, service, ...
+  nh gen -c              controller only (asks module, name, route path)
+  nh gen -s              bare injectable service
+  nh gen -dp             data processor (+ its Add<Name>DataDto if missing)
+  nh gen -lp             listing processor
+  nh gen -e              entity + migration, registered in the constants/maps
+  nh gen -j              job, registered in job.constants/job.maps
+  nh gen -x -c           external controller under <module>/external/controllers
+  nh 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')

package/src/lib/collision.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Name-collision guard for the flag generators.
+ *
+ * `nh gen -j Order` must not quietly land next to an existing OrderJob: the
+ * job identifier registries (job.constants / job.maps) are project-wide, so a
+ * second class of the same name is a genuine conflict rather than a shadowed
+ * local. The same holds for controllers, services and processors, where two
+ * identically named providers in one Nest container is a bug that surfaces
+ * far from its cause.
+ *
+ * So before writing anything, look for the target *anywhere* under src/ —
+ * by filename and by exported class name — and report what is already there
+ * instead of creating a near-duplicate.
+ */
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage', '.git']);
+
+/** Every .ts file under `dir`, recursively. */
+function walkTs(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walkTs(path.join(dir, entry.name), out);
+    } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+  return out;
+}
+
+function exportedClassNames(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return [...content.matchAll(/export\s+(?:abstract\s+)?class\s+(\w+)/g)].map(
+    (m) => m[1],
+  );
+}
+
+/**
+ * Look for `className` / `fileName` under srcDir.
+ *
+ * Returns `null` when the name is free, otherwise
+ * `{ kind: 'class' | 'file', file }` describing the first conflict found —
+ * a class match is reported ahead of a filename match, since it is the one
+ * that actually breaks at runtime.
+ */
+function findConflict(srcDir, { className, fileName }) {
+  const files = walkTs(srcDir);
+
+  if (className) {
+    for (const file of files) {
+      if (exportedClassNames(file).includes(className)) {
+        return { kind: 'class', file, name: className };
+      }
+    }
+  }
+
+  if (fileName) {
+    for (const file of files) {
+      if (path.basename(file) === fileName) {
+        return { kind: 'file', file, name: fileName };
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Human-readable one-liner for a conflict, relative to the project root. */
+function describeConflict(conflict, root) {
+  const rel = path.relative(root, conflict.file);
+  return conflict.kind === 'class'
+    ? `a class named ${conflict.name} already exists in ${rel}`
+    : `a file named ${conflict.name} already exists at ${rel}`;
+}
+
+module.exports = { walkTs, exportedClassNames, findConflict, describeConflict };

package/src/lib/format.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Format generated files with the *target project's* prettier, honouring its
+ * own .prettierrc.
+ *
+ * The boilerplate lints with `prettier/prettier: error`, so a scaffold that is
+ * merely valid TypeScript is not good enough — it has to land already
+ * formatted, or `yarn lint` fails on freshly generated code. Templates aim to
+ * emit prettier-clean output on their own; this is the backstop that keeps
+ * that true for entity names long enough to push a line past 80 columns.
+ *
+ * Best-effort by design: a project without prettier installed still gets its
+ * files, just unformatted.
+ */
+function loadPrettier(root) {
+  try {
+    return require(require.resolve('prettier', { paths: [root] }));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format `files` in place. Returns the count actually rewritten, or null when
+ * prettier could not be resolved from the project.
+ */
+async function formatFiles(files, root) {
+  const prettier = loadPrettier(root);
+  if (!prettier) return null;
+
+  let changed = 0;
+  for (const file of new Set(files)) {
+    if (!file || !fs.existsSync(file)) continue;
+    if (!['.ts', '.js', '.json'].includes(path.extname(file))) continue;
+    try {
+      const source = fs.readFileSync(file, 'utf8');
+      const config = (await prettier.resolveConfig(file)) || {};
+      const next = await prettier.format(source, { ...config, filepath: file });
+      if (next !== source) {
+        fs.writeFileSync(file, next);
+        changed++;
+      }
+    } catch {
+      // A file prettier cannot parse is left exactly as generated.
+    }
+  }
+  return changed;
+}
+
+module.exports = { formatFiles, loadPrettier };

package/src/lib/registry.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const path = require('path');
+
+const tpl = require('./templates');
+const { log } = require('./fs.utils');
+const {
+  ensureConstantEntry,
+  ensureMapEntry,
+  detectExportName,
+  entityConstantsPath,
+} = require('./constants.engine');
+
+/**
+ * The project-wide identifier registries.
+ *
+ * Entities and jobs are addressed by string identifier at runtime, so each one
+ * has to appear twice: as `<name>: '<dot.name>'` in the constants file, and as
+ * `[Constants.<name>]: <Class>` in the map beside it. A generated job
+ * references `JobConstants.<name>Job` directly, so a missing entry is a
+ * compile error rather than a latent one.
+ *
+ * Shared by the `nh gen` wizard and the `nh gen -e` / `nh gen -j` flags so
+ * both register identically. Registration is best-effort: a registry the
+ * engine cannot parse produces a warning telling you the one line to add, not
+ * a failed run that has already written half a module.
+ */
+
+/** Register `<base>Job` in job.constants.ts and job.maps.ts. */
+function registerJob(paths, base, moduleDot, report) {
+  const n = tpl.names(base);
+
+  const constantsPath = path.join(paths.constantsDir, 'job.constants.ts');
+  const entry = ensureConstantEntry(
+    constantsPath,
+    tpl.jobConstantsFile(base),
+    `${n.camel}Job`,
+    `${n.dot}.job`,
+  );
+  if (entry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, constantsPath)} — add ${n.camel}Job: '${n.dot}.job' manually.`,
+    );
+  } else {
+    report(entry, constantsPath, paths.root);
+  }
+
+  const constantsRef = {
+    exportName: detectExportName(constantsPath) || 'JobConstants',
+    importPath: './job.constants',
+  };
+  const mapsPath = path.join(paths.constantsDir, 'job.maps.ts');
+  const mapEntry = ensureMapEntry(
+    mapsPath,
+    tpl.jobMapsFile(base, moduleDot, constantsRef),
+    `[${constantsRef.exportName}.${n.camel}Job]`,
+    n.jobClass,
+    [
+      { className: n.jobClass, importPath: `../${moduleDot}/jobs/${n.dot}.job` },
+      { className: constantsRef.exportName, importPath: constantsRef.importPath },
+    ],
+  );
+  if (mapEntry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, mapsPath)} — map ${n.jobClass} manually.`,
+    );
+  } else {
+    report(mapEntry, mapsPath, paths.root);
+  }
+}
+
+/** Register `<base>` in entity.constants.ts and entity.maps.ts. */
+function registerEntity(paths, base, moduleDot, report) {
+  const n = tpl.names(base);
+
+  // The boilerplate ships this file misspelled in some projects, so the
+  // engine reports whichever spelling is actually on disk.
+  const constantsPath = entityConstantsPath(paths.constantsDir);
+  const entry = ensureConstantEntry(
+    constantsPath,
+    tpl.entityConstantsFile(base),
+    n.camel,
+    n.dot,
+  );
+  if (entry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, constantsPath)} — add ${n.camel}: '${n.dot}' manually.`,
+    );
+  } else {
+    report(entry, constantsPath, paths.root);
+  }
+
+  const constantsRef = {
+    exportName: detectExportName(constantsPath) || 'EntityConstants',
+    importPath: `./${path.basename(constantsPath, '.ts')}`,
+  };
+  const mapsPath = path.join(paths.constantsDir, 'entity.maps.ts');
+  const mapEntry = ensureMapEntry(
+    mapsPath,
+    tpl.entityMapsFile(base, moduleDot, constantsRef),
+    `[${constantsRef.exportName}.${n.camel}]`,
+    n.entityClass,
+    [
+      {
+        className: n.entityClass,
+        importPath: `../${moduleDot}/entities/${n.dot}.entity`,
+      },
+      { className: constantsRef.exportName, importPath: constantsRef.importPath },
+    ],
+  );
+  if (mapEntry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, mapsPath)} — map ${n.entityClass} manually.`,
+    );
+  } else {
+    report(mapEntry, mapsPath, paths.root);
+  }
+}
+
+module.exports = { registerJob, registerEntity };

package/src/lib/sync.engine.js

@@ -27,6 +27,14 @@ const CATEGORIES = [
 // Files in a category folder that are not providers themselves.
 const NON_PROVIDER_FILES = new Set(['es6.classes.ts', 'index.ts']);
 
+// A module may expose an API-key surface from `<module>/external/<folder>`
+// (e.g. external/controllers/external.test.controller.ts). Those classes are
+// providers of the same categories as their internal siblings and belong in
+// the same es6.classes arrays — listed after the internal ones — so the
+// scanner has to walk both roots or `nh sync` would strip them from the
+// barrel.
+const EXTERNAL_DIR = 'external';
+
 function exportedClassName(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
   const match = content.match(/export\s+class\s+(\w+)/);
@@ -80,12 +88,17 @@ function scanModule(dir, modFile) {
   const moduleDot = path.basename(dir);
   const providers = {};
   for (const cat of CATEGORIES) {
-    providers[cat.key] = listClassFiles(path.join(dir, cat.folder)).map(
-      (file) => ({
+    // Internal first, then the external/ mirror of the same category.
+    const roots = [
+      { base: dir, prefix: '' },
+      { base: path.join(dir, EXTERNAL_DIR), prefix: `${EXTERNAL_DIR}/` },
+    ];
+    providers[cat.key] = roots.flatMap(({ base, prefix }) =>
+      listClassFiles(path.join(base, cat.folder)).map((file) => ({
         file,
         className: exportedClassName(file),
-        importPath: `./${cat.folder}/${path.basename(file, '.ts')}`,
-      }),
+        importPath: `./${prefix}${cat.folder}/${path.basename(file, '.ts')}`,
+      })),
     );
   }
   return {
@@ -101,7 +114,15 @@ function scanModule(dir, modFile) {
   };
 }
 
-/** Render the es6.classes.ts content for a scanned module. */
+/**
+ * Render the es6.classes.ts content for a scanned module.
+ *
+ * The array literals are wrapped exactly the way prettier's 80-column printer
+ * would: inline while they fit, one class per line once they don't. `nh gen`
+ * formats what it writes, so if this emitted a single long line instead,
+ * every later `nh check` would report the barrel as drifted purely because
+ * prettier had reflowed it.
+ */
 function buildEs6Content(mod) {
   const importLines = [];
   const arrayLines = [];
@@ -110,8 +131,13 @@ function buildEs6Content(mod) {
     for (const e of entries) {
       importLines.push(`import { ${e.className} } from '${e.importPath}';`);
     }
-    const classes = entries.map((e) => e.className).join(', ');
-    arrayLines.push(`  ${cat.key}: [${classes}],`);
+    const classes = entries.map((e) => e.className);
+    const inline = `  ${cat.key}: [${classes.join(', ')}],`;
+    arrayLines.push(
+      inline.length <= 80
+        ? inline
+        : `  ${cat.key}: [\n${classes.map((c) => `    ${c},`).join('\n')}\n  ],`,
+    );
   }
   const header = importLines.length ? importLines.join('\n') + '\n\n' : '';
   return `${header}export const es6Classes = {\n${arrayLines.join('\n')}\n};\n`;
@@ -233,6 +259,7 @@ function applyPlan(plan) {
 
 module.exports = {
   CATEGORIES,
+  EXTERNAL_DIR,
   scanModules,
   scanModule,
   buildEs6Content,