@neohm/nh-cli 1.1.5 → 1.3.0

package/README.md

@@ -1,15 +1,37 @@
-# @neohm/nh-cli — `nh`
+# @neohm/nh-cli — `nh` and `nhx`
 
 A scaffolding CLI that accelerates development on **neohm. NestJS projects**
-built on top of the shared [`@neohm/nestend`](../nestend) library.
+built on top of the shared [`@neohm/nestend`](../nestend) library — or its B2C
+sibling [`@neohm/nestendx`](../nestendx).
 
-`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.
 
-Every generated artifact matches the conventions of the `nestjs-boilerplate`
-reference project:
+## Two flavours, one CLI
+
+`nh` writes code against **`@neohm/nestend`**, `nhx` against
+**`@neohm/nestendx`**. Same commands, same conventions, same wiring — they
+differ only where the two packages do:
+
+| | `nh` (nestend) | `nhx` (nestendx) |
+| ------------------------ | ------------------------------------------ | ----------------------------------------- |
+| Import specifier         | `@neohm/nestend`                           | `@neohm/nestendx`                         |
+| What a row belongs to    | a tenant (`tenant_id` + `TenantEntity`)    | the user who created it (`created_by`)    |
+| Access check             | `validateAccess(scope, role)`              | `validateAccess(scope)` — there are no roles |
+| Generated migration      | FK + index on `tenant_id`                  | no tenant column to key                   |
+
+Everything that does not write package-specific code — `sync`, `check`, `list`,
+`remove` — behaves identically under either name.
+
+Running the wrong one is refused rather than half-generated: both read the
+target project's `package.json`, and scaffolding tenanted code into a nestendx
+project (or the reverse) stops with a message naming the command to use instead.
+A project that depends on neither is taken at its word.
+
+Every generated artifact matches the conventions of the reference project for
+that flavour — `nestjs-boilerplate` for `nh`, `nestendx-boilerplate` for `nhx`:
 
 - **Filenames** are `dot.separated.lowercase` (no hyphens) — e.g.
   `shape.entity.ts`, and a multi-word `RoundShape` becomes
@@ -22,13 +44,15 @@ reference project:
 ```bash
 # from the neohm-cli directory
 npm install
-npm link            # exposes `nh` globally
+npm link            # exposes both `nh` and `nhx` globally
 
 # or run without linking
 npx nh --help
+npx nhx --help
 ```
 
-Run `nh` from **inside** a target NestJS project (e.g. `nestjs-boilerplate`).
+Run `nh` from **inside** a target NestJS project (e.g. `nestjs-boilerplate`),
+or `nhx` from inside a nestendx one (e.g. `nestendx-boilerplate`).
 The project root is auto-detected by walking up from the current directory for a
 `package.json` next to a `src/` folder.
 
@@ -36,7 +60,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`.                                   |
@@ -45,6 +70,9 @@ The project root is auto-detected by walking up from the current directory for a
 | `nh remove <name>`    | Safely remove a scaffolded module and de-register it (migrations are preserved).                                 |
 | `nh --help` / `nh -v` | Help and version.                                                                                                |
 
+Read `nhx` for `nh` throughout the table above when generating against
+`@neohm/nestendx`.
+
 ### `nh gen`
 
 ```text
@@ -66,11 +94,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 +120,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 +264,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/bin/nh.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
+// Generates @neohm/nestend code — the tenanted model. `nhx` is the same CLI
+// against @neohm/nestendx; the flavour is set before anything else loads,
+// because the templates read it while they are being defined.
+require('../src/lib/flavour').setFlavour('nestend');
+
 const { program } = require('../src/index');
 
 program.parseAsync(process.argv);

package/bin/nhx.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+'use strict';
+
+// The nestendx flavour of `nh`: same commands, same conventions, code written
+// against @neohm/nestendx — users hold scopes rather than roles, and a row
+// belongs to whoever created it rather than to a tenant.
+require('../src/lib/flavour').setFlavour('nestendx');
+
+const { program } = require('../src/index');
+
+program.parseAsync(process.argv);

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@neohm/nh-cli",
-  "version": "1.1.5",
-  "description": "nh — Command Line Interface for neohm. NestJS projects",
+  "version": "1.3.0",
+  "description": "nh / nhx \u2014 Command Line Interface for neohm. NestJS projects",
   "main": "src/index.js",
   "bin": {
-    "nh": "bin/nh.js"
+    "nh": "bin/nh.js",
+    "nhx": "bin/nhx.js"
   },
   "scripts": {
     "start": "node bin/nh.js",
-    "prepublishOnly": "find bin src -name '*.js' | xargs node --check"
+    "prepublishOnly": "find bin src -name '*.js' | xargs node --check",
+    "start:x": "node bin/nhx.js"
   },
   "packageManager": "yarn@1.22.22",
   "files": [
@@ -20,7 +22,8 @@
     "cli",
     "scaffold",
     "neohm",
-    "nestend"
+    "nestend",
+    "nestendx"
   ],
   "author": "Ashim Baral",
   "license": "MIT",

package/src/commands/check.js

@@ -2,6 +2,7 @@
 
 const path = require('path');
 const chalk = require('chalk');
+const { cli } = require('../lib/flavour');
 
 const { projectPaths } = require('../lib/paths');
 const engine = require('../lib/sync.engine');
@@ -47,9 +48,13 @@ async function check() {
   }
 
   if (changes) {
-    console.log(chalk.yellow(`\n${changes} file(s) would change. Run \`nh sync\` to apply.`));
+    console.log(
+      chalk.yellow(
+        `\n${changes} file(s) would change. Run \`${cli()} sync\` to apply.`,
+      ),
+    );
   } else {
-    log.done('In sync — `nh sync` would make no changes.');
+    log.done(`In sync — \`${cli()} sync\` would make no changes.`);
   }
 }