@neohm/nh-cli 1.3.0 → 1.4.0

package/README.md

@@ -105,7 +105,8 @@ shape/
 ```
 
 plus `src/database/migrations/<timestamp>M-AddShapeTable.ts`, and it
-registers `ShapeModule` in `src/app.module.ts`.
+registers `ShapeModule` in `src/app.module.ts` — appended to the `@Module()`
+`imports` array without disturbing comments inside it.
 
 It also registers the entity and its job in the project constant registries —
 `shapeJob: 'shape.job'` in `src/constants/job.constants.ts` (which the
@@ -120,15 +121,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
@@ -141,12 +148,14 @@ 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` |
+| `remove(user, id)` | always | `DELETE /api/v1/shape/:id` |
+| `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
-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
+`get()` and `remove()` keep their logic in the service — no processor: `remove()`
+soft-deletes through the same owner-scoped lookup as `get()`. A module that
+declines both processors still gets a service that reads and deletes (and a
+controller with just the `GET` and `DELETE`). 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
@@ -162,9 +171,38 @@ 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.
+### Scope and role enums
+
+`nh gen` registers the entity's scope and default roles in auto-maintained enums
+under `src/global/enums/` (created if missing, appended to otherwise — comments
+and existing members are left alone). For entity `Billing`:
+
+```ts
+// scope.enum.ts
+export enum ScopeEnum {
+  BILLING = 'billing',
+}
+
+// role.enum.ts (nh only — nhx has no roles)
+export enum RoleEnum {
+  BILLING_ADMIN = 'billing.admin', // priority 1 — the scope's top role
+  BILLING_MANAGER = 'billing.manager', // priority 2
+  BILLING_READER = 'billing.reader', // priority 3
+}
+```
+
+The controller gates each endpoint at the lowest role that should reach it — a
+senior role satisfies a junior one in nestend's scoped RBAC:
+
+| Endpoint | Gate |
+| --- | --- |
+| `GET :id`, `POST list` | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_READER)` |
+| `POST` (upsert) | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_MANAGER)` |
+| `DELETE :id` | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_ADMIN)` |
+
+Under `nhx` the gate is `validateAccess(ScopeEnum.BILLING)`. The enums name the
+identifiers only: create the `sys_scopes` row and the three `sys_roles` rows
+(scope `billing`, priorities 1/2/3) in the back office so the checks can pass.
 
 ## Flag generation
 
@@ -215,9 +253,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neohm/nh-cli",
-  "version": "1.3.0",
-  "description": "nh / nhx \u2014 Command Line Interface for neohm. NestJS projects",
+  "version": "1.4.0",
+  "description": "nh / nhx — Command Line Interface for neohm. NestJS projects",
   "main": "src/index.js",
   "bin": {
     "nh": "bin/nh.js",

package/src/commands/gen.flag.js

@@ -283,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));

package/src/commands/gen.js

@@ -12,7 +12,11 @@ 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 {
+  registerJob,
+  registerEntity,
+  registerAccess,
+} = require("../lib/registry");
 
 async function gen() {
   const paths = projectPaths();
@@ -103,6 +107,9 @@ async function gen() {
   // (the generated job references JobConstants.<name>Job, so the entry must exist).
   registerJob(paths, entityName, moduleDot, report);
   registerEntity(paths, entityName, moduleDot, report);
+  // The entity's scope and, tenanted, its default roles (admin > manager >
+  // reader) in src/global/enums — what the generated controller gates on.
+  const enums = registerAccess(paths, entityName, report);
 
   // 4. Optional: controller -------------------------------------------------
   const { controller } = await inquirer.prompt([
@@ -135,7 +142,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) ------
@@ -167,7 +174,10 @@ async function gen() {
   if (controller) {
     const p = path.join(moduleDir, "controllers", n.controllerFile);
     report(
-      writeFile(p, tpl.controller(entityName, { processor, listProcessor })),
+      writeFile(
+        p,
+        tpl.controller(entityName, { processor, listProcessor, enums }),
+      ),
       p,
       paths.root,
     );

package/src/lib/access.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const { toWords, toDotCase } = require('./naming');
+
+/**
+ * The scope and default roles `nh gen` registers for an entity. Roles rank
+ * within the scope by priority (1 = most senior) and a senior role satisfies a
+ * junior requirement, so each endpoint is gated at the lowest role that should
+ * reach it: reader for get/list, manager for upsert, admin for delete. The
+ * admin role is the scope's top role — its holders grant the scope's roles.
+ */
+const ROLE_LEVELS = [
+  { level: 'admin', priority: 1 },
+  { level: 'manager', priority: 2 },
+  { level: 'reader', priority: 3 },
+];
+
+/** BILLING_ITEM */
+function toConstantCase(input) {
+  return toWords(input).join('_').toUpperCase();
+}
+
+/** Enum keys and identifiers for `base`, e.g. Billing → BILLING: 'billing'. */
+function accessNames(base) {
+  const scopeKey = toConstantCase(base);
+  const scopeValue = toDotCase(base);
+  const roles = {};
+  for (const { level, priority } of ROLE_LEVELS) {
+    roles[level] = {
+      key: `${scopeKey}_${level.toUpperCase()}`,
+      value: `${scopeValue}.${level}`,
+      priority,
+    };
+  }
+  return { scopeKey, scopeValue, roles };
+}
+
+module.exports = { ROLE_LEVELS, toConstantCase, accessNames };

package/src/lib/constants.engine.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 
 const { writeFile } = require('./fs.utils');
+const scan = require('./source.scan');
 
 /**
  * Keeps the project-level constant registries (src/constants/job.constants.ts
@@ -26,36 +27,14 @@ function ensureConstantEntry(filePath, freshContent, key, value) {
   }
 
   const content = fs.readFileSync(filePath, 'utf8');
-  if (new RegExp(`(^|[^\\w])${escapeRe(key)}\\s*:`).test(content)) {
-    return 'skipped';
-  }
-
-  // First exported object literal in the file, e.g. `export const JobConstants = {`.
-  const open = content.search(/export\s+const\s+\w+\s*(?::[^=]+)?=\s*{/);
-  if (open === -1) return 'failed';
-  const braceStart = content.indexOf('{', open);
-
-  // Walk to the matching closing brace (entries are flat string values, but
-  // stay correct if a nested object ever appears).
-  let depth = 0;
-  let close = -1;
-  for (let i = braceStart; i < content.length; i++) {
-    if (content[i] === '{') depth++;
-    else if (content[i] === '}') {
-      depth--;
-      if (depth === 0) {
-        close = i;
-        break;
-      }
-    }
-  }
-  if (close === -1) return 'failed';
+  const literal = exportedLiteral(content, EXPORT_OBJECT);
+  if (!literal) return 'failed';
+  if (hasMember(content, literal, `${escapeRe(key)}\\s*:`)) return 'skipped';
 
-  const before = content.slice(0, close).replace(/\s*$/, '');
-  const entry = `${before.endsWith(',') || before.endsWith('{') ? '' : ','}\n  ${key}: '${value}',\n`;
-  const next = before + entry + content.slice(close);
-
-  fs.writeFileSync(filePath, next);
+  fs.writeFileSync(
+    filePath,
+    scan.appendMember(content, literal.open, literal.close, `${key}: '${value}',`, '  '),
+  );
   return 'overwritten';
 }
 
@@ -71,40 +50,64 @@ function ensureMapEntry(filePath, freshContent, entryKey, entryValue, imports) {
   }
 
   let content = fs.readFileSync(filePath, 'utf8');
-  if (content.includes(entryKey)) return 'skipped';
-
-  const open = content.search(/export\s+const\s+\w+\s*(?::[^=]+)?=\s*{/);
-  if (open === -1) return 'failed';
+  const existing = exportedLiteral(content, EXPORT_OBJECT);
+  if (!existing) return 'failed';
+  if (hasMember(content, existing, escapeRe(entryKey))) return 'skipped';
 
   for (const imp of imports) {
     content = ensureImportLine(content, imp.className, imp.importPath);
   }
 
   // Re-locate the object after import insertion shifted offsets.
-  const braceStart = content.indexOf(
-    '{',
-    content.search(/export\s+const\s+\w+\s*(?::[^=]+)?=\s*{/),
+  const literal = exportedLiteral(content, EXPORT_OBJECT);
+  fs.writeFileSync(
+    filePath,
+    scan.appendMember(content, literal.open, literal.close, `${entryKey}: ${entryValue},`, '  '),
   );
-  let depth = 0;
-  let close = -1;
-  for (let i = braceStart; i < content.length; i++) {
-    if (content[i] === '{') depth++;
-    else if (content[i] === '}') {
-      depth--;
-      if (depth === 0) {
-        close = i;
-        break;
-      }
-    }
+  return 'overwritten';
+}
+
+/**
+ * Ensure `KEY = 'value',` is a member of the enum exported by `filePath`.
+ * Creates the file with `freshContent` when absent. Returns 'created' |
+ * 'skipped' | 'overwritten' | 'failed'.
+ */
+function ensureEnumMember(filePath, freshContent, key, value) {
+  if (!fs.existsSync(filePath)) {
+    return writeFile(filePath, freshContent);
   }
-  if (close === -1) return 'failed';
 
-  const before = content.slice(0, close).replace(/\s*$/, '');
-  const entry = `${before.endsWith(',') || before.endsWith('{') ? '' : ','}\n  ${entryKey}: ${entryValue},\n`;
-  fs.writeFileSync(filePath, before + entry + content.slice(close));
+  const content = fs.readFileSync(filePath, 'utf8');
+  const literal = exportedLiteral(content, EXPORT_ENUM);
+  if (!literal) return 'failed';
+  if (hasMember(content, literal, `${escapeRe(key)}\\s*=`)) return 'skipped';
+
+  fs.writeFileSync(
+    filePath,
+    scan.appendMember(content, literal.open, literal.close, `${key} = '${value}',`, '  '),
+  );
   return 'overwritten';
 }
 
+const EXPORT_OBJECT = /export\s+const\s+\w+\s*(?::[^=]+)?=\s*{/;
+const EXPORT_ENUM = /export\s+enum\s+\w+\s*{/;
+
+/** Brace positions of the first exported literal matching `declaration`; null if none. */
+function exportedLiteral(content, declaration) {
+  const mask = scan.codeMask(content);
+  const found = scan.findInCode(content, declaration, 0, mask);
+  if (!found) return null;
+  const open = content.indexOf('{', found.index);
+  const close = scan.matchingClose(content, open, mask);
+  return close === -1 ? null : { open, close };
+}
+
+/** Whether the literal's code (comments ignored) has a member starting with `pattern`. */
+function hasMember(content, literal, pattern) {
+  const inner = scan.codeOnly(content, literal.open + 1, literal.close);
+  return new RegExp(`(^|[\\s,{])${pattern}`).test(inner);
+}
+
 function ensureImportLine(content, className, importPath) {
   if (new RegExp(`from\\s+['"]${escapeRe(importPath)}['"]`).test(content)) {
     return content;
@@ -131,6 +134,15 @@ function detectExportName(filePath) {
   return match ? match[1] : null;
 }
 
+/** Name of the first `export enum X {` in the file (null if unreadable). */
+function detectEnumName(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const match = fs
+    .readFileSync(filePath, 'utf8')
+    .match(/export\s+enum\s+(\w+)\s*{/);
+  return match ? match[1] : null;
+}
+
 /**
  * Resolve the entity constants file, tolerating the legacy misspelled
  * `enity.constants.ts` some projects carry — an existing registry is updated
@@ -150,6 +162,8 @@ function escapeRe(str) {
 module.exports = {
   ensureConstantEntry,
   ensureMapEntry,
+  ensureEnumMember,
   detectExportName,
+  detectEnumName,
   entityConstantsPath,
 };

package/src/lib/paths.js

@@ -41,6 +41,7 @@ function projectPaths(root = requireProjectRoot()) {
     appModule: path.join(srcDir, 'app.module.ts'),
     migrationsDir: path.join(srcDir, 'database', 'migrations'),
     constantsDir: path.join(srcDir, 'constants'),
+    enumsDir: path.join(srcDir, 'global', 'enums'),
     moduleDir: (moduleDot) => path.join(srcDir, moduleDot),
   };
 }

package/src/lib/registry.js

@@ -7,9 +7,13 @@ const { log } = require('./fs.utils');
 const {
   ensureConstantEntry,
   ensureMapEntry,
+  ensureEnumMember,
   detectExportName,
+  detectEnumName,
   entityConstantsPath,
 } = require('./constants.engine');
+const { accessNames } = require('./access');
+const { current } = require('./flavour');
 
 /**
  * The project-wide identifier registries.
@@ -117,4 +121,58 @@ function registerEntity(paths, base, moduleDot, report) {
   }
 }
 
-module.exports = { registerJob, registerEntity };
+/**
+ * Register `<base>`'s scope in src/global/enums/scope.enum.ts and, for the
+ * tenanted flavour, its default roles (admin, manager, reader) in role.enum.ts.
+ * Returns the enum names the generated controller imports.
+ */
+function registerAccess(paths, base, report) {
+  const a = accessNames(base);
+  const enums = { scope: 'ScopeEnum', role: 'RoleEnum' };
+
+  const scopePath = path.join(paths.enumsDir, 'scope.enum.ts');
+  const scope = ensureEnumMember(
+    scopePath,
+    tpl.scopeEnumFile(base),
+    a.scopeKey,
+    a.scopeValue,
+  );
+  if (scope === 'failed')
+    log.warn(
+      `Could not update ${path.relative(paths.root, scopePath)} — add ${a.scopeKey} = '${a.scopeValue}' manually.`,
+    );
+  else report(scope, scopePath, paths.root);
+  enums.scope = detectEnumName(scopePath) || enums.scope;
+
+  // The B2C model has scopes and no roles.
+  if (!current().tenantScoped) return enums;
+
+  const rolePath = path.join(paths.enumsDir, 'role.enum.ts');
+  const results = [];
+  for (const role of Object.values(a.roles)) {
+    const result = ensureEnumMember(
+      rolePath,
+      tpl.roleEnumFile(base),
+      role.key,
+      role.value,
+    );
+    if (result === 'failed') {
+      log.warn(
+        `Could not update ${path.relative(paths.root, rolePath)} — add ${role.key} = '${role.value}' manually.`,
+      );
+      break;
+    }
+    results.push(result);
+  }
+  // A fresh file already carries every default role, so later calls skip.
+  const summary = results.includes('created')
+    ? 'created'
+    : results.includes('overwritten')
+      ? 'overwritten'
+      : 'skipped';
+  if (results.length) report(summary, rolePath, paths.root);
+  enums.role = detectEnumName(rolePath) || enums.role;
+  return enums;
+}
+
+module.exports = { registerJob, registerEntity, registerAccess };

package/src/lib/source.scan.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * Comment- and string-aware scanning of TypeScript source, so the CLI can edit
+ * array and object literals without being fooled by a `,`, `]` or `}` that sits
+ * inside a comment or a string. Every edit that inserts into an existing literal
+ * goes through here.
+ */
+
+/** `mask[i]` is true when `content[i]` is code (not inside a comment or string). */
+function codeMask(content) {
+  return scanMask(content, true);
+}
+
+/** `mask[i]` is true unless `content[i]` is inside a comment (strings count). */
+function commentMask(content) {
+  return scanMask(content, false);
+}
+
+function scanMask(content, maskStrings) {
+  const mask = new Array(content.length).fill(true);
+  let i = 0;
+  while (i < content.length) {
+    const ch = content[i];
+    const next = content[i + 1];
+    let end = -1;
+    let isString = false;
+    if (ch === '/' && next === '/') {
+      end = content.indexOf('\n', i);
+      if (end === -1) end = content.length;
+    } else if (ch === '/' && next === '*') {
+      end = content.indexOf('*/', i + 2);
+      end = end === -1 ? content.length : end + 2;
+    } else if (ch === "'" || ch === '"' || ch === '`') {
+      isString = true;
+      end = i + 1;
+      while (end < content.length && content[end] !== ch) {
+        if (content[end] === '\\') end++;
+        end++;
+      }
+      end = Math.min(end + 1, content.length);
+    }
+    if (end === -1) {
+      i++;
+      continue;
+    }
+    if (!isString || maskStrings)
+      for (let k = i; k < end; k++) mask[k] = false;
+    i = end;
+  }
+  return mask;
+}
+
+/** First match of `regex` (global flag added) whose start is code; -1 if none. */
+function findInCode(content, regex, from = 0, mask = codeMask(content)) {
+  const re = new RegExp(regex.source, regex.flags.includes('g') ? regex.flags : `${regex.flags}g`);
+  re.lastIndex = from;
+  let match;
+  while ((match = re.exec(content))) {
+    if (mask[match.index]) return { index: match.index, match };
+    re.lastIndex = match.index + 1;
+  }
+  return null;
+}
+
+/** Index of the bracket closing the one at `openIdx` (any of `([{`), skipping comments and strings. */
+function matchingClose(content, openIdx, mask = codeMask(content)) {
+  const pairs = { '(': ')', '[': ']', '{': '}' };
+  const stack = [];
+  for (let i = openIdx; i < content.length; i++) {
+    if (!mask[i]) continue;
+    const ch = content[i];
+    if (pairs[ch]) stack.push(pairs[ch]);
+    else if (ch === ')' || ch === ']' || ch === '}') {
+      if (stack.pop() !== ch) return -1;
+      if (!stack.length) return i;
+    }
+  }
+  return -1;
+}
+
+/** Index of the last non-whitespace character `mask` marks true in [from, to); -1 if none. */
+function lastCodeChar(content, from, to, mask = codeMask(content)) {
+  for (let i = to - 1; i >= from; i--) {
+    if (mask[i] && !/\s/.test(content[i])) return i;
+  }
+  return -1;
+}
+
+/** `content` between `from` and `to` with comments and strings blanked out. */
+function codeOnly(content, from, to, mask = codeMask(content)) {
+  let out = '';
+  for (let i = from; i < to; i++) out += mask[i] ? content[i] : ' ';
+  return out;
+}
+
+/**
+ * Insert `entryLine` (no indentation, no trailing newline) as the last member of
+ * the literal whose brackets sit at `open`/`close`. A missing comma after the
+ * current last member is added right after its code — never inside a trailing
+ * comment — and comments in the literal stay exactly where they were.
+ */
+function appendMember(content, open, close, entryLine, indent) {
+  const last = lastCodeChar(content, open + 1, close, commentMask(content));
+  let next = content;
+  let closeAt = close;
+  if (last !== -1 && content[last] !== ',' && last !== open) {
+    next = next.slice(0, last + 1) + ',' + next.slice(last + 1);
+    closeAt++;
+  }
+  // Insert before the whitespace that leads to the closing bracket.
+  let insertAt = closeAt;
+  while (insertAt > 0 && /[ \t]/.test(next[insertAt - 1])) insertAt--;
+  const closingIndent = next.slice(insertAt, closeAt);
+  const lead = next[insertAt - 1] === '\n' ? '' : '\n';
+  return (
+    next.slice(0, insertAt) +
+    `${lead}${indent}${entryLine}\n` +
+    closingIndent +
+    next.slice(closeAt)
+  );
+}
+
+module.exports = {
+  codeMask,
+  commentMask,
+  findInCode,
+  matchingClose,
+  lastCodeChar,
+  codeOnly,
+  appendMember,
+};

package/src/lib/sync.engine.js

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const scan = require('./source.scan');
+
 /**
  * The sync engine is the single brain behind `nh sync`, `nh check` and the
  * auto-wiring step of `nh gen`. It scans scaffolded modules, regenerates each
@@ -178,21 +180,37 @@ function ensureImportLine(content, className, importPath) {
   return lines.join('\n');
 }
 
+/**
+ * Add `className` to the `imports: [...]` array of the @Module() decorator.
+ * The array is located and edited through the comment-aware scanner: splitting
+ * it on commas used to break any comment holding a comma, turning the rest of
+ * that comment into code.
+ */
 function ensureInImportsArray(content, className) {
-  const idx = content.indexOf('imports:');
-  if (idx === -1) return content;
-  const open = content.indexOf('[', idx);
-  const close = content.indexOf(']', open);
-  if (open === -1 || close === -1) return content;
-  const inner = content.slice(open + 1, close);
-  const items = inner
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
-  if (items.includes(className)) return content;
-  items.push(className);
-  const rebuilt = '\n    ' + items.join(',\n    ') + ',\n  ';
-  return content.slice(0, open + 1) + rebuilt + content.slice(close);
+  const mask = scan.codeMask(content);
+  const decorator = scan.findInCode(content, /@Module\s*\(/, 0, mask);
+  const key = scan.findInCode(
+    content,
+    /\bimports\s*:/,
+    decorator ? decorator.index : 0,
+    mask,
+  );
+  if (!key) return content;
+  const open = scan.findInCode(content, /\[/, key.index, mask);
+  if (!open) return content;
+  const close = scan.matchingClose(content, open.index, mask);
+  if (close === -1) return content;
+
+  const inner = scan.codeOnly(content, open.index + 1, close, mask);
+  if (new RegExp(`(^|[^\\w.])${escapeRe(className)}\\b`).test(inner))
+    return content;
+  return scan.appendMember(
+    content,
+    open.index,
+    close,
+    `${className},`,
+    '    ',
+  );
 }
 
 function escapeRe(str) {

package/src/lib/templates.js

@@ -9,6 +9,7 @@ const {
   toCamelCase,
   migrationClassName,
 } = require("./naming");
+const { accessNames } = require('./access');
 
 /**
  * Code templates. All generated code imports shared base classes from the
@@ -103,26 +104,20 @@ export class ${n.entityClass} extends CommonEntity {
 `;
   }
 
-  return `import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
-import { CommonEntity, TenantEntity } from '${pkg()}';
+  // 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 CommonEntity {
-  // Tenant scope — the service and the list processor both filter on it.
-  @Column()
-  tenant_id: string;
-
+export class ${n.entityClass} extends CommonTenantEntity {
   // TODO: declare the columns ${n.pascal} owns.
 
   @Column({ type: 'jsonb' })
   attributes: ${n.attributesDtoClass};
 
   // Relations and methods
-
-  @ManyToOne(() => TenantEntity)
-  @JoinColumn({ name: 'tenant_id' })
-  tenant: TenantEntity;
 }
 `;
 }
@@ -140,19 +135,32 @@ function attributesDto(base) {
  * delegate to the module's service — so the HTTP surface stays readable and
  * the same operation is reusable from a job, a subscriber or another service.
  */
-function controller(base, { processor = false, listProcessor = false } = {}) {
+function controller(
+  base,
+  { processor = false, listProcessor = false, enums = {} } = {},
+) {
   const n = names(base);
+  const a = accessNames(base);
+  const scopeEnum = enums.scope || 'ScopeEnum';
+  const roleEnum = enums.role || 'RoleEnum';
   const svcProp = `${n.camel}Service`;
   const hasPost = processor || listProcessor;
 
   // @nestjs/common members, alphabetised the way prettier leaves them.
-  const nestCommon = ['Controller', 'Get', 'Param'];
+  const nestCommon = [
+    'Controller',
+    'Delete',
+    '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'),
@@ -160,7 +168,7 @@ 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';`,
+    `import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';`,
     namedImport(nestendImports, pkg()),
     `import { ${n.serviceClass} } from '../services/${n.dot}.service';`,
   ];
@@ -170,50 +178,73 @@ 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.
+  // Tenanted access takes the entity's scope and the lowest role that should
+  // reach the endpoint (a senior role satisfies a junior one); the B2C model
+  // has no roles, 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')`;
+  imports.push(
+    `import { ${scopeEnum} } from '../../global/enums/scope.enum';`,
+  );
+  if (tenanted)
+    imports.push(`import { ${roleEnum} } from '../../global/enums/role.enum';`);
+  const scopeRef = `${scopeEnum}.${a.scopeKey}`;
+  const gate = (indent, level) => {
+    if (!tenanted) {
+      const call = `await this.authService.validateAccess(${scopeRef})`;
+      return `${indent}const { user } = ${call};`.length <= 80
+        ? call
+        : `await this.authService.validateAccess(\n${indent}  ${scopeRef},\n${indent})`;
+    }
+    const roleRef = `${roleEnum}.${a.roles[level].key}`;
+    const call = `await this.authService.validateAccess(${scopeRef}, ${roleRef})`;
+    return `${indent}const { user } = ${call};`.length <= 80
+      ? call
+      : `await this.authService.validateAccess(\n${indent}  ${scopeRef},\n${indent}  ${roleRef},\n${indent})`;
+  };
 
   const methods = [
     `  @Get(':id')
-  async get${n.pascal}(@Param() params: CommonParamsDto) {
-    const { user } = ${gate('    ')};
+  @ApiOperation({ summary: 'One ${n.kebab} by id.' })
+  async get${n.pascal}(@Param('id', ParseUUIDPipe) id: string) {
+    const { user } = ${gate('    ', 'reader')};
 
-    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}) {
-    ${tenanted ? `await this.authService.validateAccess('add-scope', 'add-role');` : `await this.authService.validateAccess('add-scope');`}
+    const { user } = ${gate('    ', 'manager')};
 
-    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 } = ${gate('    ')};
+    const { user } = ${gate('    ', 'reader')};
 
     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.`;
+  methods.push(`  @Delete(':id')
+  @ApiOperation({ summary: 'Delete one ${n.kebab} by id.' })
+  async remove${n.pascal}(@Param('id', ParseUUIDPipe) id: string) {
+    const { user } = ${gate('    ', 'admin')};
+
+    return this.${svcProp}.remove(user, id);
+  }`);
 
   return `${imports.join('\n')}
 
-${gateTodo}
 @ApiTags('${n.kebab}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${n.kebab}')
 export class ${n.controllerClass} {
   constructor(
@@ -285,11 +316,19 @@ function service(base, { processor = false, listProcessor = false } = {}) {
     return ${n.camel};
   }`);
 
+  // Soft delete, through the same ownership-scoped lookup as get().
+  members.push(`  async remove(user: UserEntity, id: string) {
+    const ${n.camel} = await this.get(user, id);
+    await ${n.entityClass}.softRemove(${n.camel});
+
+    return { id, deleted: true, deleted_by: user.id };
+  }`);
+
   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);
   }`);
   }
 
@@ -329,12 +368,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 '${pkg()}';
+import { AuthService, StrictValidationPipe } from '${pkg()}';
 
 @ApiTags('${routePath}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${routePath}')
 export class ${n.controllerClass} {
   constructor(private readonly authService: AuthService) {}
@@ -353,12 +393,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 '${pkg()}';
+  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) {}
@@ -414,13 +455,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 '${pkg()}';
+  if (external) {
+    return `import { CommonDataProcessor } from '${pkg()}';
 import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
 
 export class ${cls} extends CommonDataProcessor {
@@ -443,6 +485,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}
+}
 `;
 }
 
@@ -543,6 +659,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};
   }
@@ -699,6 +818,33 @@ export const EntityMaps = {
 `;
 }
 
+/** Fresh src/global/enums/scope.enum.ts (first entry included). */
+function scopeEnumFile(base) {
+  const a = accessNames(base);
+  return `/** Scope identifiers (sys_scopes.identifier) the app checks. */
+export enum ScopeEnum {
+  ${a.scopeKey} = '${a.scopeValue}',
+}
+`;
+}
+
+/** Fresh src/global/enums/role.enum.ts (the entity's default roles included). */
+function roleEnumFile(base) {
+  const a = accessNames(base);
+  const members = Object.values(a.roles)
+    .map((role) => `  ${role.key} = '${role.value}',`)
+    .join('\n');
+  return `/**
+ * Tenant role identifiers (sys_roles.identifier) the app checks. Each scope's
+ * defaults rank admin (priority 1) > manager (2) > reader (3) — create the
+ * catalogue rows with those priorities under the matching scope.
+ */
+export enum RoleEnum {
+${members}
+}
+`;
+}
+
 /** A freshly scaffolded module before any es6.classes content exists. */
 function emptyEs6Classes() {
   return `export const es6Classes = {
@@ -739,6 +885,8 @@ export class ${pascal}Module {}
 
 module.exports = {
   names,
+  scopeEnumFile,
+  roleEnumFile,
   entity,
   attributesDto,
   controller,