@neohm/nh-cli 1.2.0 → 1.3.1

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, 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.
 
@@ -46,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
@@ -93,15 +120,21 @@ created spreading `baseJobConstants` / `baseEntityConstants` /
 
 Generated artifacts extend the `@neohm/nestend` base classes:
 
-- Entity → `CommonEntity` (a `tenant_id` column with its `TenantEntity`
-  relation, plus an empty `attributes` jsonb column)
+- Entity → `CommonTenantEntity` under `nh` (it carries `tenant_id` and the
+  `TenantEntity` relation, and `TenantScopeSubscriber` stamps and guards it),
+  `CommonEntity` under `nhx`; both with an empty `attributes` jsonb column
 - DTO → `CommonDataDto`
 - Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`),
-  reached through the service's `upsert()`
+  reached through the service's `upsert()`. It takes the caller and, on edit,
+  loads the row scoped to them — another owner's `id` is a field error, never an
+  update.
 - 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.
 
 ### Controller → service → processor
 
+Generated controllers run under `@UsePipes(StrictValidationPipe)`, take ids
+with `ParseUUIDPipe`, and describe every route with `@ApiOperation`.
+
 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
@@ -114,7 +147,7 @@ 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` |
+| `upsert(user, 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
@@ -188,9 +221,9 @@ Only one target flag per run; the module is created if it does not exist yet.
 
 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`.
+load-bearing: it mounts at `api/e/v1/<path>`, it documents the key header to
+swagger with `@ApiHeader`, 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

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.2.0",
-  "description": "nh — Command Line Interface for neohm. NestJS projects",
+  "version": "1.3.1",
+  "description": "nh / nhx — 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.`);
   }
 }
 

package/src/commands/gen.flag.js

@@ -6,6 +6,7 @@ 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 {
@@ -170,6 +171,7 @@ async function genFlag(target, { external = false } = {}) {
   }
 
   const paths = projectPaths();
+  assertFlavourMatchesProject(paths.root);
   log.info(`Project: ${paths.root}\n`);
 
   const touched = [];
@@ -281,7 +283,13 @@ async function genFlag(target, { external = false } = {}) {
       break;
 
     case 'dataProcessor':
-      write(dest, tpl.processor(rawName, { external }));
+      write(
+        dest,
+        tpl.processor(rawName, {
+          external,
+          withEntity: fs.existsSync(path.join(moduleDir, 'entities', n.entityFile)),
+        }),
+      );
       // 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));
@@ -346,7 +354,9 @@ async function genFlag(target, { external = false } = {}) {
   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.'),
+    chalk.dim(
+      `Run \`${cli()} sync\` anytime to re-wire imports after manual edits.`,
+    ),
   );
 }
 

package/src/commands/gen.js

@@ -6,6 +6,7 @@ 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");
@@ -15,6 +16,7 @@ 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.
@@ -133,7 +135,7 @@ async function gen() {
     report(writeFile(dtoPath, tpl.dto(entityName)), dtoPath, paths.root);
 
     const procPath = path.join(moduleDir, "libraries", n.processorFile);
-    report(writeFile(procPath, tpl.processor(entityName)), procPath, paths.root);
+    report(writeFile(procPath, tpl.processor(entityName, { withEntity: true })), procPath, paths.root);
   }
 
   // 6. Optional: listing processor (takes CommonListFilterDto directly) ------
@@ -215,7 +217,9 @@ async function gen() {
 
   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,14 +18,21 @@ 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');
 
-// `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.
+// `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'],
@@ -50,15 +58,15 @@ program
     '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`,
+  ${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) => {

package/src/lib/flavour.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Which package the generated code is written against.
+ *
+ * The two share every convention this CLI encodes — dot.separated filenames,
+ * the processor lifecycle, es6.classes barrels, the migration utility — and
+ * differ in what a record belongs to. `nestend` is the tenanted model: rows
+ * carry a `tenant_id`, access is a scope *and* a role. `nestendx` is the B2C
+ * one: users register themselves and hold scopes alone, so a row belongs to the
+ * user who created it and access is a scope.
+ *
+ * `nh` generates the first, `nhx` the second. Everything that does not generate
+ * code — sync, check, list, remove — is the same command either way.
+ */
+const FLAVOURS = {
+  nestend: {
+    key: 'nestend',
+    cli: 'nh',
+    package: '@neohm/nestend',
+    /** Rows belong to a tenant; the scope check carries a role beside it. */
+    tenantScoped: true,
+  },
+  nestendx: {
+    key: 'nestendx',
+    cli: 'nhx',
+    package: '@neohm/nestendx',
+    tenantScoped: false,
+  },
+};
+
+let active = FLAVOURS.nestend;
+
+/** Set by the bin entrypoint before anything else is required. */
+function setFlavour(key) {
+  const flavour = FLAVOURS[key];
+  if (!flavour) throw new Error(`Unknown flavour "${key}".`);
+  active = flavour;
+  return active;
+}
+
+function current() {
+  return active;
+}
+
+/** The package specifier generated imports are written against. */
+function pkg() {
+  return active.package;
+}
+
+/** The command the person actually typed, for help text and hints. */
+function cli() {
+  return active.cli;
+}
+
+/**
+ * Which package a project depends on, read from its package.json. Returns null
+ * when it depends on neither — a project that has not installed one yet is not
+ * an error, it is simply not evidence either way.
+ */
+function detectFlavour(projectRoot) {
+  const manifest = path.join(projectRoot, 'package.json');
+  let deps;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    deps = { ...parsed.dependencies, ...parsed.devDependencies };
+  } catch {
+    return null;
+  }
+
+  // nestendx first: "@neohm/nestend" is a prefix of it, and a project can only
+  // sensibly depend on one.
+  if (deps[FLAVOURS.nestendx.package]) return FLAVOURS.nestendx.key;
+  if (deps[FLAVOURS.nestend.package]) return FLAVOURS.nestend.key;
+  return null;
+}
+
+/**
+ * Refuse to scaffold against the wrong package. Generating tenanted code into a
+ * nestendx project produces files that import a package that is not there and
+ * columns no table has — a failure the person would meet later, in a compiler
+ * error, with nothing pointing back here.
+ */
+function assertFlavourMatchesProject(projectRoot) {
+  const detected = detectFlavour(projectRoot);
+  if (!detected || detected === active.key) return;
+
+  const wanted = FLAVOURS[detected];
+  throw new Error(
+    `This project depends on ${wanted.package}, but you ran ${active.cli}, ` +
+      `which generates ${active.package} code.\n  Use \`${wanted.cli}\` here instead.`,
+  );
+}
+
+module.exports = {
+  FLAVOURS,
+  setFlavour,
+  current,
+  pkg,
+  cli,
+  detectFlavour,
+  assertFlavourMatchesProject,
+};

package/src/lib/templates.js

@@ -1,5 +1,6 @@
 "use strict";
 
+const { pkg, current } = require('./flavour');
 const {
   toWords,
   toDotCase,
@@ -11,10 +12,17 @@ const {
 
 /**
  * Code templates. All generated code imports shared base classes from the
- * published library `@neohm/nestend` (verified exports: CommonEntity,
- * CommonDataDto, CommonDataProcessor, MigrationUtility, SeederUtility, etc.)
- * and matches the dot.separated filename / PascalCase class conventions used
- * across nestjs-boilerplate.
+ * package the active flavour names — `@neohm/nestend` under `nh`,
+ * `@neohm/nestendx` under `nhx` (verified exports: CommonEntity, CommonDataDto,
+ * CommonDataProcessor, MigrationUtility, SeederUtility, etc.) — and matches the
+ * dot.separated filename / PascalCase class conventions used across the
+ * boilerplates.
+ *
+ * The two differ in what a record belongs to, and that difference is read from
+ * `current().tenantScoped` rather than branched on a package name: tenanted
+ * code scopes rows by `tenant_id` and checks a scope with a role beside it,
+ * while the B2C model scopes by the user who created the row and checks the
+ * scope alone.
  */
 
 /**
@@ -75,26 +83,40 @@ function names(base) {
 
 function entity(base, tableName) {
   const n = names(base);
-  return `import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
-import { CommonEntity, TenantEntity } from '@neohm/nestend';
+
+  // Without tenants there is nothing extra to declare: CommonEntity already
+  // carries `created_by` and its relation, which is what a row belongs to.
+  if (!current().tenantScoped) {
+    return `import { Column, Entity } from 'typeorm';
+import { CommonEntity } from '${pkg()}';
 import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
 
 @Entity({ name: '${tableName}' })
 export class ${n.entityClass} extends CommonEntity {
-  // Tenant scope — the service and the list processor both filter on it.
-  @Column()
-  tenant_id: string;
-
   // TODO: declare the columns ${n.pascal} owns.
 
   @Column({ type: 'jsonb' })
   attributes: ${n.attributesDtoClass};
 
   // Relations and methods
+}
+`;
+  }
+
+  // CommonTenantEntity adds tenant_id + the tenant relation; TenantScopeSubscriber
+  // stamps it from the session and refuses cross-tenant writes.
+  return `import { Column, Entity } from 'typeorm';
+import { CommonTenantEntity } from '${pkg()}';
+import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
+
+@Entity({ name: '${tableName}' })
+export class ${n.entityClass} extends CommonTenantEntity {
+  // TODO: declare the columns ${n.pascal} owns.
+
+  @Column({ type: 'jsonb' })
+  attributes: ${n.attributesDtoClass};
 
-  @ManyToOne(() => TenantEntity)
-  @JoinColumn({ name: 'tenant_id' })
-  tenant: TenantEntity;
+  // Relations and methods
 }
 `;
 }
@@ -118,13 +140,13 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
   const hasPost = processor || listProcessor;
 
   // @nestjs/common members, alphabetised the way prettier leaves them.
-  const nestCommon = ['Controller', 'Get', 'Param'];
+  const nestCommon = ['Controller', 'Get', 'Param', 'ParseUUIDPipe', 'UsePipes'];
   if (hasPost) nestCommon.push('Body', 'Post');
   nestCommon.sort();
 
   const nestendImports = ['AuthService'];
   if (listProcessor) nestendImports.push('CommonListFilterDto');
-  nestendImports.push('CommonParamsDto');
+  nestendImports.push('StrictValidationPipe');
 
   const imports = [
     namedImport(nestCommon, '@nestjs/common'),
@@ -132,8 +154,8 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
     // DocumentBuilder call only registers the scheme (under its default name,
     // 'bearer') and draws the Authorize button — without the decorator
     // swagger-ui shows no padlock and never sends the Authorization header.
-    `import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';`,
-    namedImport(nestendImports, '@neohm/nestend'),
+    `import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';`,
+    namedImport(nestendImports, pkg()),
     `import { ${n.serviceClass} } from '../services/${n.dot}.service';`,
   ];
   if (processor) {
@@ -142,43 +164,54 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
     );
   }
 
+  // Tenanted access takes a scope and a role; the B2C model has no roles at
+  // all, so the same call carries the scope alone.
+  const tenanted = current().tenantScoped;
+  const gate = (indent) =>
+    tenanted
+      ? `await this.authService.validateAccess(\n${indent}  'add-scope',\n${indent}  'add-role',\n${indent})`
+      : `await this.authService.validateAccess('add-scope')`;
+
   const methods = [
     `  @Get(':id')
-  async get${n.pascal}(@Param() params: CommonParamsDto) {
-    const { user } = await this.authService.validateAccess(
-      'add-scope',
-      'add-role',
-    );
+  @ApiOperation({ summary: 'One ${n.kebab} by id.' })
+  async get${n.pascal}(@Param('id', ParseUUIDPipe) id: string) {
+    const { user } = ${gate('    ')};
 
-    return this.${svcProp}.get(user, params.id);
+    return this.${svcProp}.get(user, id);
   }`,
   ];
 
   if (processor) {
     methods.push(`  @Post()
+  @ApiOperation({ summary: 'Create a ${n.kebab}, or update it when an id is sent.' })
   async upsert${n.pascal}(@Body() body: ${n.dtoClass}) {
-    await this.authService.validateAccess('add-scope', 'add-role');
+    const { user } = ${gate('    ')};
 
-    return this.${svcProp}.upsert(body);
+    return this.${svcProp}.upsert(user, body);
   }`);
   }
 
   if (listProcessor) {
     methods.push(`  @Post('list')
+  @ApiOperation({ summary: 'List, search and filter ${n.kebab}.' })
   async list(@Body() body: CommonListFilterDto) {
-    const { user } = await this.authService.validateAccess(
-      'add-scope',
-      'add-role',
-    );
+    const { user } = ${gate('    ')};
+
     return this.${svcProp}.list(user, body);
   }`);
   }
 
+  const gateTodo = tenanted
+    ? `// TODO: replace 'add-scope' / 'add-role' with this module's scope and role.`
+    : `// TODO: replace 'add-scope' with this module's scope — a granted parent\n// scope reaches its children, so name the one the feature is filed under.`;
+
   return `${imports.join('\n')}
 
-// TODO: replace 'add-scope' / 'add-role' with this module's scope and role.
+${gateTodo}
 @ApiTags('${n.kebab}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${n.kebab}')
 export class ${n.controllerClass} {
   constructor(
@@ -210,7 +243,7 @@ function service(base, { processor = false, listProcessor = false } = {}) {
   nestendImports.push('NotFoundException', 'UserEntity');
 
   const imports = [
-    namedImport(nestendImports, '@neohm/nestend'),
+    namedImport(nestendImports, pkg()),
     `import { Injectable } from '@nestjs/common';`,
   ];
   if (listProcessor) {
@@ -235,11 +268,15 @@ function service(base, { processor = false, listProcessor = false } = {}) {
     );
   }
 
-  // The tenant scope is part of the lookup, not a check after it: a row
-  // belonging to another tenant must read as "not found", never as "forbidden".
+  // Ownership is part of the lookup, not a check after it: a row belonging to
+  // someone else must read as "not found", never as "forbidden". Tenanted rows
+  // carry the organization; without tenants it is the user who created it.
+  const owner = current().tenantScoped
+    ? 'tenant_id: user.organization_id'
+    : 'created_by: user.id';
   members.push(`  async get(user: UserEntity, id: string) {
     const ${n.camel} = await ${n.entityClass}.findOne({
-      where: { id, tenant_id: user.organization_id },
+      where: { id, ${owner} },
     });
     if (!${n.camel}) throw new NotFoundException('Invalid ${label} id');
 
@@ -249,8 +286,8 @@ function service(base, { processor = false, listProcessor = false } = {}) {
   if (processor) {
     // Insert or update: CommonDataDto carries an optional `id`, and the data
     // processor decides which of the two the payload asks for.
-    members.push(`  async upsert(data: ${n.dtoClass}) {
-    return new ${n.processorClass}().process(data);
+    members.push(`  async upsert(user: UserEntity, data: ${n.dtoClass}) {
+    return new ${n.processorClass}(user).process(data);
   }`);
   }
 
@@ -290,12 +327,13 @@ ${members.join('\n\n')}
  */
 function bareController(base, routePath) {
   const n = names(base);
-  return `import { Controller, Get } from '@nestjs/common';
+  return `import { Controller, Get, UsePipes } from '@nestjs/common';
 import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
-import { AuthService } from '@neohm/nestend';
+import { AuthService, StrictValidationPipe } from '${pkg()}';
 
 @ApiTags('${routePath}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${routePath}')
 export class ${n.controllerClass} {
   constructor(private readonly authService: AuthService) {}
@@ -314,12 +352,13 @@ export class ${n.controllerClass} {
  */
 function bareExternalController(base, routePath) {
   const n = names(base);
-  return `import { Controller, Get } from '@nestjs/common';
-import { ApiSecurity, ApiTags } from '@nestjs/swagger';
-import { ApiKeyService } from '@neohm/nestend';
+  return `import { Controller, Get, UsePipes } from '@nestjs/common';
+import { ApiHeader, ApiTags } from '@nestjs/swagger';
+import { ApiKeyService, StrictValidationPipe } from '${pkg()}';
 
 @ApiTags('external-${routePath} (Api key)')
-@ApiSecurity('api-key')
+@ApiHeader({ name: 'x-api-key', required: true })
+@UsePipes(StrictValidationPipe)
 @Controller('api/e/v1/${routePath}')
 export class ${n.externalControllerClass} {
   constructor(private readonly apiKeyService: ApiKeyService) {}
@@ -348,7 +387,7 @@ export class ${cls} {}
  */
 function additionalJob(base) {
   const n = names(base);
-  return `import { CommonJob, QueueService } from '@neohm/nestend';
+  return `import { CommonJob, QueueService } from '${pkg()}';
 import { Injectable } from '@nestjs/common';
 import { JobConstants } from '../../constants/job.constants';
 
@@ -367,7 +406,7 @@ export class ${n.jobClass} extends CommonJob {
 
 function dto(base) {
   const n = names(base);
-  return `import { CommonDataDto } from '@neohm/nestend';
+  return `import { CommonDataDto } from '${pkg()}';
 
 export class ${n.dtoClass} extends CommonDataDto {
   // TODO: declare validated payload fields for ${n.pascal}.
@@ -375,13 +414,14 @@ export class ${n.dtoClass} extends CommonDataDto {
 `;
 }
 
-function processor(base, { external = false } = {}) {
+function processor(base, { external = false, withEntity = false } = {}) {
   const n = names(base);
   // An external processor sits one level deeper (external/libraries/), so its
   // reach back into the module's dtos/ gains a segment.
   const up = external ? '../..' : '..';
   const cls = external ? n.externalProcessorClass : n.processorClass;
-  return `import { CommonDataProcessor } from '@neohm/nestend';
+  if (external) {
+    return `import { CommonDataProcessor } from '${pkg()}';
 import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
 
 export class ${cls} extends CommonDataProcessor {
@@ -404,6 +444,80 @@ export class ${cls} extends CommonDataProcessor {
     // TODO: persist ${n.pascal} using this.payload.
   }
 }
+`;
+  }
+
+  // Edits load the caller's own row: another owner's id reads as not found.
+  const owner = current().tenantScoped
+    ? 'tenant_id: this.user.organization_id'
+    : 'created_by: this.user.id';
+  const label = toWords(base).join(' ');
+  const entityImport = withEntity
+    ? `\nimport { ${n.entityClass} } from '${up}/entities/${n.dot}.entity';`
+    : '';
+  const existingField = withEntity
+    ? `\n  private existing: ${n.entityClass} | null = null;`
+    : '';
+  const load = withEntity
+    ? `    if (this.payload.id) {
+      this.existing = await ${n.entityClass}.findOne({
+        where: { id: this.payload.id, ${owner} },
+      });
+      if (!this.existing) this.setColumnError('id', 'Invalid ${label} id');
+    }
+
+`
+    : `    // TODO: on edit (payload.id), load the row scoped to the caller
+    // ({ id, ${owner} }) and record an 'id' error when it is not found.
+
+`;
+  const set = withEntity
+    ? `  private set(): Promise<${n.entityClass}> {
+    const ${n.camel} = this.existing ?? ${n.entityClass}.create();
+    // TODO: assign fields from this.payload explicitly — never spread the DTO.
+
+    return ${n.camel}.save();
+  }`
+    : `  private set(): void {
+    // TODO: persist ${n.pascal} from this.payload, assigning fields explicitly.
+  }`;
+  return `import { CommonDataProcessor, UserEntity } from '${pkg()}';
+import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';${entityImport}
+
+export class ${cls} extends CommonDataProcessor {
+  protected payload: ${n.dtoClass};${existingField}
+
+  constructor(private readonly user: UserEntity) {
+    super();
+  }
+
+${
+    withEntity
+      ? `  async process(data: ${n.dtoClass}) {
+    this.payload = data;
+
+    await this.validate();
+
+    return this.set();
+  }
+
+  private async validate() {`
+      : `  process(data: ${n.dtoClass}) {
+    this.payload = data;
+
+    this.validate();
+
+    return this.set();
+  }
+
+  private validate(): void {`
+  }
+${load}    // TODO: collect validation errors via this.addErrors({ column: 'message' }).
+    this.raiseExceptionOnValidationFailure();
+  }
+
+${set}
+}
 `;
 }
 
@@ -418,7 +532,7 @@ function listProcessor(base, tableName, { external = false } = {}) {
   ListFilterService,
   SortDirection,
   UserEntity,
-} from '@neohm/nestend';
+} from '${pkg()}';
 
 /**
  * Lists / filters ${n.pascal}.
@@ -474,8 +588,13 @@ export class ${cls} extends CommonListProcessor {
   }
 
   protected applyCustomPredicates() {
-    // Filter for the caller's tenant/organization
-    this.predicates.add('a.tenant_id = :tenant_id', this.user.organization_id);
+${
+  current().tenantScoped
+    ? `    // Filter for the caller's tenant/organization
+    this.predicates.add('a.tenant_id = :tenant_id', this.user.organization_id);`
+    : `    // Filter for the caller: rows belong to whoever created them.
+    this.predicates.add('a.created_by = :created_by', this.user.id);`
+}
   }
 }
 `;
@@ -483,7 +602,7 @@ export class ${cls} extends CommonListProcessor {
 
 function subscriber(base) {
   const n = names(base);
-  return `import { CommonSubscriber } from '@neohm/nestend';
+  return `import { CommonSubscriber } from '${pkg()}';
 import { EventSubscriber } from 'typeorm';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
 import { DataSource } from 'typeorm';
@@ -499,6 +618,9 @@ export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
     datasource.subscribers.push(this);
   }
 
+  // Jobs receive only \`id\` unless the columns they need are listed here.
+  protected readonly snapshotColumns: (keyof ${n.entityClass} & string)[] = [];
+
   listenTo() {
     return ${n.entityClass};
   }
@@ -508,7 +630,7 @@ export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
 
 function job(base) {
   const n = names(base);
-  return `import { CommonJob, QueueService, DatabaseEventDto } from '@neohm/nestend';
+  return `import { CommonJob, QueueService, DatabaseEventDto } from '${pkg()}';
 import { Injectable } from '@nestjs/common';
 import { JobConstants } from '../../constants/job.constants';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
@@ -534,7 +656,7 @@ export class ${n.jobClass} extends CommonJob {
 function genMigration(base, tableName, timestamp) {
   const n = names(base);
   const className = migrationClassName(n.migrationName, timestamp);
-  return `import { MigrationUtility } from '@neohm/nestend';
+  return `import { MigrationUtility } from '${pkg()}';
 
 export class ${className} extends MigrationUtility {
   constructor() {
@@ -545,8 +667,11 @@ export class ${className} extends MigrationUtility {
   process() {
     this.rootPrimary();
 
-    this.foreign({ name: 'tenant_id', foreignTable: 'sys_tenants' });
-    this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
+${
+  current().tenantScoped
+    ? `    this.foreign({ name: 'tenant_id', foreignTable: 'sys_tenants' });\n`
+    : ''
+}    this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
     this.foreign({ name: 'updated_by', foreignTable: 'sys_users' });
 
     // TODO: add columns matching ${n.entityClass}.
@@ -554,8 +679,7 @@ export class ${className} extends MigrationUtility {
     this.json('attributes');
     this.timestamps();
 
-    this.index('tenant_id');
-    this.index('created_by');
+${current().tenantScoped ? `    this.index('tenant_id');\n` : ''}    this.index('created_by');
     this.index('updated_by');
   }
 }
@@ -565,7 +689,7 @@ export class ${className} extends MigrationUtility {
 /** Standalone migration (`nh migration`). */
 function migration(migrationName, tableName, timestamp) {
   const className = migrationClassName(migrationName, timestamp);
-  return `import { MigrationUtility } from '@neohm/nestend';
+  return `import { MigrationUtility } from '${pkg()}';
 
 export class ${className} extends MigrationUtility {
   constructor() {
@@ -585,7 +709,7 @@ export class ${className} extends MigrationUtility {
 /** Seed file (`nh seed`). */
 function seed(seedName, tableName, timestamp) {
   const className = `${toPascalCase(seedName)}${timestamp}`;
-  return `import { SeederUtility } from '@neohm/nestend';
+  return `import { SeederUtility } from '${pkg()}';
 
 export class ${className} extends SeederUtility {
   constructor() {
@@ -604,7 +728,7 @@ export class ${className} extends SeederUtility {
 /** Fresh src/constants/job.constants.ts (first entry included). */
 function jobConstantsFile(base) {
   const n = names(base);
-  return `import { baseJobConstants } from '@neohm/nestend';
+  return `import { baseJobConstants } from '${pkg()}';
 
 export const JobConstants = {
   ...baseJobConstants,
@@ -616,7 +740,7 @@ export const JobConstants = {
 /** Fresh src/constants/entity.constants.ts (first entry included). */
 function entityConstantsFile(base) {
   const n = names(base);
-  return `import { baseEntityConstants } from '@neohm/nestend';
+  return `import { baseEntityConstants } from '${pkg()}';
 
 export const EntityConstants = {
   ...baseEntityConstants,
@@ -628,7 +752,7 @@ export const EntityConstants = {
 /** Fresh src/constants/job.maps.ts (first entry included). */
 function jobMapsFile(base, moduleDot, constants) {
   const n = names(base);
-  return `import { baseJobMaps } from '@neohm/nestend';
+  return `import { baseJobMaps } from '${pkg()}';
 import { ${n.jobClass} } from '../${moduleDot}/jobs/${n.dot}.job';
 import { ${constants.exportName} } from '${constants.importPath}';
 
@@ -642,7 +766,7 @@ export const JobMaps = {
 /** Fresh src/constants/entity.maps.ts (first entry included). */
 function entityMapsFile(base, moduleDot, constants) {
   const n = names(base);
-  return `import { baseEntityMaps } from '@neohm/nestend';
+  return `import { baseEntityMaps } from '${pkg()}';
 import { ${n.entityClass} } from '../${moduleDot}/entities/${n.dot}.entity';
 import { ${constants.exportName} } from '${constants.importPath}';
 
@@ -674,7 +798,7 @@ import {
   QueueModule,
   AuthModule,
   SystemPropertyModule,
-} from '@neohm/nestend';
+} from '${pkg()}';
 import { es6Classes } from './es6.classes';
 
 @Module({