@neohm/nh-cli 1.1.4 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@
 A scaffolding CLI that accelerates development on **neohm. NestJS projects**
 built on top of the shared [`@neohm/nestend`](../nestend) library.
 
-`nh` generates fully wired modules, entities, controllers, DTOs, data
+`nh` generates fully wired modules, entities, controllers, services, DTOs, data
 processors, migrations and seeds — and keeps your import barrels
 (`es6.classes.ts`) and `app.module.ts` registration in sync, so the project
 builds without any manual import wiring.
@@ -36,7 +36,8 @@ The project root is auto-detected by walking up from the current directory for a
 
 | Command               | Description                                                                                                      |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `nh gen`              | Interactive wizard: scaffold a module + entity + optional controller/DTO/processor/migration, then auto-wire it. |
+| `nh gen`              | Interactive wizard: scaffold a module + entity + optional controller/service/DTO/processor/migration, then auto-wire it. |
+| `nh gen <flag>`       | Generate one artifact instead of a whole module — see [Flag generation](#flag-generation). |
 | `nh migration`        | Generate a standalone migration `<timestamp>M-<Name>.ts`.                                                        |
 | `nh seed`             | Generate a seed file `<timestamp>S-<Name>.ts`.                                                                   |
 | `nh sync`             | Rebuild every `es6.classes.ts` barrel and register modules in `app.module.ts`.                                   |
@@ -66,11 +67,14 @@ shape/
   shape.module.ts                    # ShapeModule (imports CommonModule, QueueModule, ...)
   es6.classes.ts                     # barrel of controllers/services/jobs/subscribers
   controllers/shape.controller.ts
+  services/shape.service.ts
   dtos/add.shape.data.dto.ts
   entities/shape.entity.ts
   libraries/shape.data.processor.ts
   libraries/shape.list.processor.ts
-  enums/  jobs/  services/  subscribers/
+  enums/  jobs/  subscribers/
+  external/                          # optional API-key surface (nh gen -x ...)
+    controllers/  libraries/  services/
 ```
 
 plus `src/database/migrations/<timestamp>M-AddShapeTable.ts`, and it
@@ -89,14 +93,143 @@ created spreading `baseJobConstants` / `baseEntityConstants` /
 
 Generated artifacts extend the `@neohm/nestend` base classes:
 
-- Entity → `CommonEntity` (with an empty `attributes` jsonb column)
+- Entity → `CommonEntity` (a `tenant_id` column with its `TenantEntity`
+  relation, plus an empty `attributes` jsonb column)
 - DTO → `CommonDataDto`
-- Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`)
+- Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`),
+  reached through the service's `upsert()`
 - Listing processor → `CommonListProcessor` (column allowlist config, `id` default sort). It takes `CommonListFilterDto` directly — no per-list DTO is generated, since paging, sorting, filters and free-text search all live on the base DTO and the filterable columns are declared in the processor's `columns` config.
 
-When both a controller and a listing processor are generated, the controller
-ships with a `POST list` endpoint that runs the listing processor (with
-`SqlService` injected via the constructor).
+### Controller → service → processor
+
+Controllers hold no business logic. They authenticate with
+`AuthService.validateAccess()`, then delegate to the module's service — so the
+same operation is reusable from a job, a subscriber or another service, and the
+HTTP surface stays readable.
+
+The service owns single-record reads and hands write and listing work to the
+processors. It is **not** a prompt — it is always generated, prefilled from the
+answers you already gave:
+
+| Service method | Generated when | Controller endpoint |
+| --- | --- | --- |
+| `get(user, id)` | always | `GET /api/v1/shape/:id` |
+| `upsert(data)` | data processor: Yes | `POST /api/v1/shape` |
+| `list(user, data)` | listing processor: Yes | `POST /api/v1/shape/list` |
+
+`get()` is the one operation that needs no processor, so a module that declines
+both still gets a useful service with a single read method (and a controller
+with just the `GET`). Declining a processor drops the matching service method
+*and* its endpoint together, so the generated module always compiles.
+
+`upsert()` rather than `create()` because `CommonDataDto` carries an optional
+`id`: the same payload shape inserts when it is absent and updates when it is
+present, and the data processor decides which. That is also why the endpoint is
+a bare `@Post()` on the collection root rather than a `create` segment — one
+route covers both halves.
+
+`get()` scopes on the caller's tenant as part of the lookup —
+`where: { id, tenant_id: user.organization_id }` — so a row belonging to
+another tenant reads as *not found* rather than *forbidden*. (`organization_id`
+is what the tenant is called on `UserEntity`; `tenant_id` is what it is called
+on the row — the same value on two sides of one relation.) The listing
+processor applies the same scope as a private predicate.
+
+The generated scope and role identifiers are `'add-scope'` / `'add-role'`
+placeholders, flagged with a `TODO` on the controller — replace them with the
+`sys_scopes` identifier and role each endpoint actually sits behind.
+
+## Flag generation
+
+Bare `nh gen` scaffolds a whole module. Once that module exists, most work is
+adding *one* more file to it — which is what the target flags do. Each asks
+only what it cannot infer, refuses to shadow a name already in the project,
+registers the result in `es6.classes.ts`, and formats what it wrote.
+
+| Command | Generates | Asks |
+| --- | --- | --- |
+| `nh gen -c` | `controllers/<name>.controller.ts` | module, name, route path |
+| `nh gen -s` | `services/<name>.service.ts` | module, name |
+| `nh gen -dp` | `libraries/<name>.data.processor.ts` + `dtos/add.<name>.data.dto.ts` | module, name |
+| `nh gen -lp` | `libraries/<name>.list.processor.ts` | module, name, table name |
+| `nh gen -e` | `entities/<name>.entity.ts` + `dtos/<name>.attributes.dto.ts` + `jobs/<name>.job.ts` + `subscribers/<name>.subscriber.ts` + a migration | module, name, table name |
+| `nh gen -j` | `jobs/<name>.job.ts` | module, name |
+
+`-e` writes the same five files the wizard does, because an entity is not
+useful alone: TypeORM drives its job through its subscriber, so an entity
+without them is a table nothing reacts to. It registers in both sets of
+registries as a result — `entity.constants.ts` / `entity.maps.ts` for the
+entity, `job.constants.ts` / `job.maps.ts` for the job it brought along.
+`-j` registers in the job pair only.
+
+The two jobs are deliberately different shapes:
+
+| | Driven by | `handle()` takes |
+| --- | --- | --- |
+| the job `-e` brings along | the entity's subscriber | `event: DatabaseEventDto<<Name>Entity>` |
+| `nh gen -j` | an explicit `dispatch()` | `data: unknown` |
+
+So reach for `-j` when you want a queue worker that is not tied to a table's
+lifecycle.
+
+Only one target flag per run; the module is created if it does not exist yet.
+
+### `-x`: the external (API-key) surface
+
+`-x` mirrors a target onto the module's API-key surface, under
+`<module>/external/`:
+
+| Command | Generates |
+| --- | --- |
+| `nh gen -x -c` | `external/controllers/external.<name>.controller.ts` |
+| `nh gen -x -s` | `external/services/external.<name>.service.ts` |
+| `nh gen -x -dp` | `external/libraries/external.<name>.data.processor.ts` |
+| `nh gen -x -lp` | `external/libraries/external.<name>.list.processor.ts` |
+
+External files take an `external.` filename prefix and an `External` class
+prefix. An external controller differs from an internal one in three ways, all
+load-bearing: it mounts at `api/e/v1/<path>`, it declares the key to swagger
+with `@ApiSecurity('api-key')`, and it authenticates through `ApiKeyService`
+rather than `AuthService`.
+
+`-x` does not apply to `-e` or `-j`: a table and a queue worker have no
+inward/outward face, so there is nothing to mirror. Both refuse the flag rather
+than quietly ignoring it.
+
+External providers register into the *same* `es6.classes.ts` categories as
+their internal siblings, listed after them — so `nh sync` and `nh check` see
+`<module>/external/<folder>` as well as `<module>/<folder>`.
+
+### Name collisions
+
+A flag generator checks the whole of `src/` for the name it is about to take —
+both the exported class and the filename — and stops before writing if it is
+taken. Every artifact is checked up front, so `-e` cannot write the entity and
+then abort on the job:
+
+```text
+$ nh gen -j
+? Module name (existing: billing, inventory, service): billing
+? Job name (PascalCase): Cleanup
+✗ a class named CleanupJob already exists in src/inventory/jobs/cleanup.job.ts.
+  Pick a different name, or edit that file instead — nothing was generated.
+```
+
+The check is project-wide, not module-local, because the registries these
+feed are project-wide: two `CleanupJob` classes cannot both be
+`JobConstants.cleanupJob`, and two identically named providers in one Nest
+container is a bug that surfaces far from its cause. Dependency files are
+exempt — the payload DTO for `-dp`, the attributes DTO for `-e`, and the
+timestamped migration are reused when present and reported as `skip`.
+
+## Formatting
+
+The boilerplate lints with `prettier/prettier: error`, so `nh gen` runs the
+**target project's** prettier (honouring its `.prettierrc`) over everything it
+writes before finishing. Templates already aim to emit prettier-clean output;
+this keeps that true for entity names long enough to push a line past 80
+columns. A project without prettier installed still gets its files, just
+unformatted.
 
 - Migration → `MigrationUtility`
 - Seed → `SeederUtility`
@@ -104,11 +237,12 @@ ships with a `POST list` endpoint that runs the listing processor (with
 Re-running `gen` for an existing module reuses it and only adds new files —
 existing files are never overwritten.
 
-### `nh sync` and `nh check`
+## `nh sync` and `nh check`
 
-`sync` scans every module under `src/` and regenerates its `es6.classes.ts`
-barrel from the files actually present in `controllers/`, `services/`, `jobs/`
-and `subscribers/`, then ensures each module is imported and listed in
+`sync` scans every module under `src/` — including its `external/` mirror —
+and regenerates its `es6.classes.ts` barrel from the files actually present in
+`controllers/`, `services/`, `libraries/`, `dtos/`, `jobs/` and
+`subscribers/`, then ensures each module is imported and listed in
 `app.module.ts`. Files are classified by their **folder** and the presence of an
 exported class — not by a fragile filename suffix — so non-standard names are
 never silently dropped. The operation is idempotent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neohm/nh-cli",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "nh — Command Line Interface for neohm. NestJS projects",
   "main": "src/index.js",
   "bin": {

package/src/commands/gen.flag.js

@@ -0,0 +1,353 @@
+'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 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();
+  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 `nh sync` anytime to re-wire imports after manual edits.'),
+  );
+}
+
+module.exports = genFlag;