@neohm/nh-cli 1.0.0 → 1.1.0

package/README.md

@@ -12,9 +12,10 @@ Every generated artifact matches the conventions of the `nestjs-boilerplate`
 reference project:
 
 - **Filenames** are `dot.separated.lowercase` (no hyphens) — e.g.
-  `business.client.entity.ts`, `add.business.client.data.dto.ts`.
-- **Class names** are `PascalCase` — e.g. `BusinessClientEntity`,
-  `AddBusinessClientDataDto`.
+  `shape.entity.ts`, and a multi-word `RoundShape` becomes
+  `round.shape.entity.ts`.
+- **Class names** are `PascalCase` — e.g. `ShapeEntity`,
+  `AddShapeDataDto`.
 
 ## Installation
 
@@ -48,36 +49,56 @@ The project root is auto-detected by walking up from the current directory for a
 
 ```text
 $ nh gen
-? Module name (e.g. business): business
-? Entity name (e.g. BusinessClient): BusinessClient
-? Table name (e.g. nh_business_clients): nh_business_clients
-? Create controller (BusinessClientController)? Yes
-? Create DTO (AddBusinessClientDataDto)? Yes
-? Create data processor (BusinessClientDataProcessor)? Yes
-? Create migration (M-AddBusinessClientTable)? Yes
+? Module name (e.g. shape): shape
+? Entity name (e.g. Shape): Shape
+? Table name (e.g. nh_shapes): nh_shapes
+? Create controller (ShapeController)? Yes
+? Create DTO (AddShapeDataDto)? Yes
+? Create data processor (ShapeDataProcessor)? Yes
+? Create listing processor (ShapeListProcessor)? Yes
+? Create migration (M-AddShapeTable)? Yes
 ```
 
-Produces, under `src/business/`:
+Produces, under `src/shape/`:
 
 ```text
-business/
-  business.module.ts                 # BusinessModule (imports CommonModule, QueueModule, ...)
+shape/
+  shape.module.ts                    # ShapeModule (imports CommonModule, QueueModule, ...)
   es6.classes.ts                     # barrel of controllers/services/jobs/subscribers
-  controllers/business.client.controller.ts
-  dtos/add.business.client.data.dto.ts
-  entities/business.client.entity.ts
-  libraries/business.client.data.processor.ts
+  controllers/shape.controller.ts
+  dtos/add.shape.data.dto.ts
+  dtos/shape.list.filter.dto.ts
+  entities/shape.entity.ts
+  libraries/shape.data.processor.ts
+  libraries/shape.list.processor.ts
   enums/  jobs/  services/  subscribers/
 ```
 
-plus `src/database/migrations/<timestamp>M-AddBusinessClientTable.ts`, and it
-registers `BusinessModule` in `src/app.module.ts`.
+plus `src/database/migrations/<timestamp>M-AddShapeTable.ts`, and it
+registers `ShapeModule` in `src/app.module.ts`.
+
+It also registers the entity and its job in the project constant registries —
+`shapeJob: 'shape.job'` in `src/constants/job.constants.ts` (which the
+generated job references as `JobConstants.shapeJob`) and `shape: 'shape'` in
+`src/constants/entity.constants.ts` — and mirrors them in the
+identifier → class map registries: `[JobConstants.shapeJob]: ShapeJob` in
+`src/constants/job.maps.ts` and `[EntityConstants.shape]: ShapeEntity` in
+`src/constants/entity.maps.ts` (imports included). Missing registry files are
+created spreading `baseJobConstants` / `baseEntityConstants` /
+`baseJobMaps` / `baseEntityMaps` from `@neohm/nestend`; existing ones
+(whatever their export is named) just get the entry appended.
 
 Generated artifacts extend the `@neohm/nestend` base classes:
 
 - Entity → `CommonEntity` (with an empty `attributes` jsonb column)
 - DTO → `CommonPayloadDto`
 - Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`)
+- List filter DTO → `CommonListFilterDto` (plus a `custom_filter` example field)
+- Listing processor → `CommonListProcessor` (column allowlist config, `id` default sort, and an example custom filter)
+
+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).
 - Migration → `MigrationUtility`
 - Seed → `SeederUtility`
 
@@ -98,7 +119,7 @@ never silently dropped. The operation is idempotent.
 ```text
 $ nh check
 es6.classes barrels:
-  ok      src/business/es6.classes.ts
+  ok      src/shape/es6.classes.ts
   update  src/test/es6.classes.ts
             + services: TestService
 

package/package.json

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

package/src/commands/gen.js

@@ -1,15 +1,21 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const inquirer = require('inquirer');
-const chalk = require('chalk');
-
-const { projectPaths, MODULE_SUBFOLDERS } = require('../lib/paths');
-const naming = require('../lib/naming');
-const tpl = require('../lib/templates');
-const { writeFile, report, log, ensureDir } = require('../lib/fs.utils');
-const sync = require('../lib/sync.engine');
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const inquirer = require("inquirer");
+const chalk = require("chalk");
+
+const { projectPaths, MODULE_SUBFOLDERS } = require("../lib/paths");
+const naming = require("../lib/naming");
+const tpl = require("../lib/templates");
+const { writeFile, report, log, ensureDir } = require("../lib/fs.utils");
+const sync = require("../lib/sync.engine");
+const {
+  ensureConstantEntry,
+  ensureMapEntry,
+  detectExportName,
+  entityConstantsPath,
+} = require("../lib/constants.engine");
 
 async function gen() {
   const paths = projectPaths();
@@ -18,10 +24,10 @@ async function gen() {
   // 1. Module ---------------------------------------------------------------
   const { moduleNameRaw } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'moduleNameRaw',
-      message: 'Module name (e.g. business):',
-      validate: (v) => (v && v.trim() ? true : 'Module name is required'),
+      type: "input",
+      name: "moduleNameRaw",
+      message: "Module name:",
+      validate: (v) => (v && v.trim() ? true : "Module name is required"),
     },
   ]);
   const moduleDot = naming.toDotCase(moduleNameRaw);
@@ -44,20 +50,16 @@ async function gen() {
     path.join(moduleDir, `${moduleDot}.module.ts`),
     paths.root,
   );
-  const es6Path = path.join(moduleDir, 'es6.classes.ts');
-  report(
-    writeFile(es6Path, tpl.emptyEs6Classes()),
-    es6Path,
-    paths.root,
-  );
+  const es6Path = path.join(moduleDir, "es6.classes.ts");
+  report(writeFile(es6Path, tpl.emptyEs6Classes()), es6Path, paths.root);
 
   // 2. Entity ---------------------------------------------------------------
   const { entityName } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'entityName',
-      message: 'Entity name (e.g. BusinessClient):',
-      validate: (v) => (v && v.trim() ? true : 'Entity name is required'),
+      type: "input",
+      name: "entityName",
+      message: "Entity name (PascalCase):",
+      validate: (v) => (v && v.trim() ? true : "Entity name is required"),
     },
   ]);
   const n = tpl.names(entityName);
@@ -65,66 +67,183 @@ async function gen() {
   // 3. Table ----------------------------------------------------------------
   const { tableName } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'tableName',
-      message: 'Table name (e.g. nh_business_clients):',
-      default: `nh_${naming.toWords(entityName).join('_')}s`,
-      validate: (v) => (v && v.trim() ? true : 'Table name is required'),
+      type: "input",
+      name: "tableName",
+      message: "Table name:",
+      default: `nh_${naming.toWords(entityName).join("_")}s`,
+      validate: (v) => (v && v.trim() ? true : "Table name is required"),
     },
   ]);
 
-  const entityPath = path.join(moduleDir, 'entities', n.entityFile);
+  // Always generate: attributes DTO, entity, subscriber, job
+  const attrDtoPath = path.join(moduleDir, "dtos", n.attributesDtoFile);
+  report(writeFile(attrDtoPath, tpl.attributesDto(entityName)), attrDtoPath, paths.root);
+
+  const entityPath = path.join(moduleDir, "entities", n.entityFile);
   report(
     writeFile(entityPath, tpl.entity(entityName, tableName)),
     entityPath,
     paths.root,
   );
 
-  // 4-7. Optional artifacts -------------------------------------------------
-  const answers = await inquirer.prompt([
-    { type: 'confirm', name: 'controller', message: `Create controller (${n.controllerClass})?`, default: true },
-    { type: 'confirm', name: 'dto', message: `Create DTO (${n.dtoClass})?`, default: true },
-    { type: 'confirm', name: 'processor', message: `Create data processor (${n.processorClass})?`, default: true },
-    { type: 'confirm', name: 'migration', message: `Create migration (M-Add${n.pascal}Table)?`, default: true },
-  ]);
+  const jobPath = path.join(moduleDir, "jobs", n.jobFile);
+  report(writeFile(jobPath, tpl.job(entityName)), jobPath, paths.root);
+
+  const subscriberPath = path.join(moduleDir, "subscribers", n.subscriberFile);
+  report(writeFile(subscriberPath, tpl.subscriber(entityName)), subscriberPath, paths.root);
 
-  if (answers.controller) {
-    const p = path.join(moduleDir, 'controllers', n.controllerFile);
-    report(writeFile(p, tpl.controller(entityName)), p, paths.root);
+  // Register the entity + job identifiers in the project constant registries
+  // (the generated job references JobConstants.<name>Job, so the entry must exist).
+  const jobConstantsPath = path.join(paths.constantsDir, "job.constants.ts");
+  const jobEntry = ensureConstantEntry(
+    jobConstantsPath,
+    tpl.jobConstantsFile(entityName),
+    `${n.camel}Job`,
+    `${n.dot}.job`,
+  );
+  if (jobEntry === "failed") {
+    log.warn(`Could not update ${path.relative(paths.root, jobConstantsPath)} — add ${n.camel}Job: '${n.dot}.job' manually.`);
+  } else {
+    report(jobEntry, jobConstantsPath, paths.root);
   }
 
-  // A processor depends on its DTO type, so generate the DTO when either the
-  // DTO step or the processor step is selected.
-  if (answers.dto || answers.processor) {
-    if (!answers.dto) {
-      log.warn(`DTO ${n.dtoClass} is generated because the data processor depends on it.`);
-    }
-    const p = path.join(moduleDir, 'dtos', n.dtoFile);
-    report(writeFile(p, tpl.dto(entityName)), p, paths.root);
+  const entityConstants = entityConstantsPath(paths.constantsDir);
+  const entityEntry = ensureConstantEntry(
+    entityConstants,
+    tpl.entityConstantsFile(entityName),
+    n.camel,
+    n.dot,
+  );
+  if (entityEntry === "failed") {
+    log.warn(`Could not update ${path.relative(paths.root, entityConstants)} — add ${n.camel}: '${n.dot}' manually.`);
+  } else {
+    report(entityEntry, entityConstants, paths.root);
   }
 
-  if (answers.processor) {
-    const p = path.join(moduleDir, 'libraries', n.processorFile);
-    report(writeFile(p, tpl.processor(entityName)), p, paths.root);
+  // ...and mirror them in the identifier → class map registries.
+  const jobConstantsRef = {
+    exportName: detectExportName(jobConstantsPath) || "JobConstants",
+    importPath: "./job.constants",
+  };
+  const jobMapsPath = path.join(paths.constantsDir, "job.maps.ts");
+  const jobMapEntry = ensureMapEntry(
+    jobMapsPath,
+    tpl.jobMapsFile(entityName, moduleDot, jobConstantsRef),
+    `[${jobConstantsRef.exportName}.${n.camel}Job]`,
+    n.jobClass,
+    [
+      { className: n.jobClass, importPath: `../${moduleDot}/jobs/${n.dot}.job` },
+      { className: jobConstantsRef.exportName, importPath: jobConstantsRef.importPath },
+    ],
+  );
+  if (jobMapEntry === "failed") {
+    log.warn(`Could not update ${path.relative(paths.root, jobMapsPath)} — map ${n.jobClass} manually.`);
+  } else {
+    report(jobMapEntry, jobMapsPath, paths.root);
   }
 
-  if (answers.migration) {
-    const ts = Date.now();
-    const file = `${ts}M-Add${n.pascal}Table.ts`;
-    const p = path.join(paths.migrationsDir, file);
-    report(writeFile(p, tpl.genMigration(entityName, tableName, ts)), p, paths.root);
+  const entityConstantsRef = {
+    exportName: detectExportName(entityConstants) || "EntityConstants",
+    importPath: `./${path.basename(entityConstants, ".ts")}`,
+  };
+  const entityMapsPath = path.join(paths.constantsDir, "entity.maps.ts");
+  const entityMapEntry = ensureMapEntry(
+    entityMapsPath,
+    tpl.entityMapsFile(entityName, moduleDot, entityConstantsRef),
+    `[${entityConstantsRef.exportName}.${n.camel}]`,
+    n.entityClass,
+    [
+      { className: n.entityClass, importPath: `../${moduleDot}/entities/${n.dot}.entity` },
+      { className: entityConstantsRef.exportName, importPath: entityConstantsRef.importPath },
+    ],
+  );
+  if (entityMapEntry === "failed") {
+    log.warn(`Could not update ${path.relative(paths.root, entityMapsPath)} — map ${n.entityClass} manually.`);
+  } else {
+    report(entityMapEntry, entityMapsPath, paths.root);
+  }
+
+  // 4. Optional: controller -------------------------------------------------
+  const { controller } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "controller",
+      message: `Create controller (${n.controllerClass})?`,
+      default: true,
+    },
+  ]);
+
+  // (written after the listing-processor prompt — the answer decides whether
+  // the controller ships with a POST list endpoint)
+
+  // 5. Optional: data processor (includes Add*DataDto) ----------------------
+  const { processor } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "processor",
+      message: `Create data processor (${n.processorClass})?`,
+      default: true,
+    },
+  ]);
+
+  if (processor) {
+    const dtoPath = path.join(moduleDir, "dtos", n.dtoFile);
+    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);
+  }
+
+  // 6. Optional: listing processor (includes *ListFilterDto) -----------------
+  const { listProcessor } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "listProcessor",
+      message: `Create listing processor (${n.listProcessorClass})?`,
+      default: true,
+    },
+  ]);
+
+  if (listProcessor) {
+    const listDtoPath = path.join(moduleDir, "dtos", n.listFilterDtoFile);
+    report(
+      writeFile(listDtoPath, tpl.listFilterDto(entityName)),
+      listDtoPath,
+      paths.root,
+    );
+
+    const listProcPath = path.join(moduleDir, "libraries", n.listProcessorFile);
+    report(
+      writeFile(listProcPath, tpl.listProcessor(entityName, tableName)),
+      listProcPath,
+      paths.root,
+    );
+  }
+
+  if (controller) {
+    const p = path.join(moduleDir, "controllers", n.controllerFile);
+    report(
+      writeFile(p, tpl.controller(entityName, { listProcessor })),
+      p,
+      paths.root,
+    );
   }
 
   // Auto-wire: rebuild this module's barrel and register it in app.module.ts.
-  log.info('\nWiring imports...');
-  const mod = sync.scanModule(moduleDir, path.join(moduleDir, `${moduleDot}.module.ts`));
+  log.info("\nWiring imports...");
+  const mod = sync.scanModule(
+    moduleDir,
+    path.join(moduleDir, `${moduleDot}.module.ts`),
+  );
   const plan = sync.buildPlan(paths, [mod]);
   const written = sync.applyPlan(plan);
-  for (const w of written) report('overwritten', w, paths.root);
-  if (!written.length) log.info('  (already in sync)');
+  for (const w of written) report("overwritten", w, paths.root);
+  if (!written.length) log.info("  (already in sync)");
 
   log.done(`Module "${moduleDot}" scaffolded.`);
-  console.log(chalk.dim('Run `nh sync` anytime to re-wire imports after manual edits.'));
+  console.log(
+    chalk.dim("Run `nh sync` anytime to re-wire imports after manual edits."),
+  );
 }
 
 module.exports = gen;

package/src/commands/migration.js

@@ -1,35 +1,39 @@
-'use strict';
+"use strict";
 
-const path = require('path');
-const inquirer = require('inquirer');
+const path = require("path");
+const inquirer = require("inquirer");
 
-const { projectPaths } = require('../lib/paths');
-const naming = require('../lib/naming');
-const tpl = require('../lib/templates');
-const { writeFile, report, log } = require('../lib/fs.utils');
+const { projectPaths } = require("../lib/paths");
+const naming = require("../lib/naming");
+const tpl = require("../lib/templates");
+const { writeFile, report, log } = require("../lib/fs.utils");
 
 async function migration() {
   const paths = projectPaths();
 
   const { tableName, migrationName } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'tableName',
-      message: 'Table name (e.g. nh_business_clients):',
-      validate: (v) => (v && v.trim() ? true : 'Table name is required'),
+      type: "input",
+      name: "tableName",
+      message: "Table name (e.g. nh_user_details):",
+      validate: (v) => (v && v.trim() ? true : "Table name is required"),
     },
     {
-      type: 'input',
-      name: 'migrationName',
-      message: 'Migration name (e.g. AddBusinessClientTable):',
-      validate: (v) => (v && v.trim() ? true : 'Migration name is required'),
+      type: "input",
+      name: "migrationName",
+      message: "Migration name (e.g. AddShapeTable):",
+      validate: (v) => (v && v.trim() ? true : "Migration name is required"),
     },
   ]);
 
   const ts = Date.now();
   const file = `${ts}M-${naming.toPascalCase(migrationName)}.ts`;
   const p = path.join(paths.migrationsDir, file);
-  report(writeFile(p, tpl.migration(migrationName, tableName, ts)), p, paths.root);
+  report(
+    writeFile(p, tpl.migration(migrationName, tableName, ts)),
+    p,
+    paths.root,
+  );
   log.done(`Migration created (${file}).`);
 }
 

package/src/commands/seed.js

@@ -1,28 +1,28 @@
-'use strict';
+"use strict";
 
-const path = require('path');
-const inquirer = require('inquirer');
+const path = require("path");
+const inquirer = require("inquirer");
 
-const { projectPaths } = require('../lib/paths');
-const naming = require('../lib/naming');
-const tpl = require('../lib/templates');
-const { writeFile, report, log } = require('../lib/fs.utils');
+const { projectPaths } = require("../lib/paths");
+const naming = require("../lib/naming");
+const tpl = require("../lib/templates");
+const { writeFile, report, log } = require("../lib/fs.utils");
 
 async function seed() {
   const paths = projectPaths();
 
   const { tableName, seedName } = await inquirer.prompt([
     {
-      type: 'input',
-      name: 'tableName',
-      message: 'Table name (e.g. nh_business_clients):',
-      validate: (v) => (v && v.trim() ? true : 'Table name is required'),
+      type: "input",
+      name: "tableName",
+      message: "Table name (e.g. nh_user_details):",
+      validate: (v) => (v && v.trim() ? true : "Table name is required"),
     },
     {
-      type: 'input',
-      name: 'seedName',
-      message: 'Seed name (e.g. SeedBusinessClients):',
-      validate: (v) => (v && v.trim() ? true : 'Seed name is required'),
+      type: "input",
+      name: "seedName",
+      message: "Seed name (e.g. SeedShapes):",
+      validate: (v) => (v && v.trim() ? true : "Seed name is required"),
     },
   ]);
 

package/src/lib/constants.engine.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { writeFile } = require('./fs.utils');
+
+/**
+ * Keeps the project-level constant registries (src/constants/job.constants.ts
+ * and src/constants/entity.constants.ts) in step with `nh gen`: every
+ * generated job references JobConstants.<camel>Job, so the entry has to exist
+ * for the project to compile. Missing files are created spreading the
+ * corresponding base object from @neohm/nestend; existing files get the new
+ * entry appended to their exported object (whatever it is named — older
+ * projects use e.g. `entityMap`).
+ */
+
+/**
+ * Ensure `key: 'value',` exists inside the object exported by `filePath`.
+ * Creates the file with `freshContent` when absent. Returns a writeFile-style
+ * result: 'created' | 'skipped' | 'overwritten' | 'failed'.
+ */
+function ensureConstantEntry(filePath, freshContent, key, value) {
+  if (!fs.existsSync(filePath)) {
+    return writeFile(filePath, freshContent);
+  }
+
+  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 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);
+  return 'overwritten';
+}
+
+/**
+ * Ensure a map entry (`[Constants.key]: ClassName,`) plus the import lines it
+ * needs exist in `filePath`. Creates the file with `freshContent` when absent.
+ * `imports` is a list of { className, importPath }. Returns 'created' |
+ * 'skipped' | 'overwritten' | 'failed'.
+ */
+function ensureMapEntry(filePath, freshContent, entryKey, entryValue, imports) {
+  if (!fs.existsSync(filePath)) {
+    return writeFile(filePath, freshContent);
+  }
+
+  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';
+
+  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*{/),
+  );
+  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 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));
+  return 'overwritten';
+}
+
+function ensureImportLine(content, className, importPath) {
+  if (new RegExp(`from\\s+['"]${escapeRe(importPath)}['"]`).test(content)) {
+    return content;
+  }
+  const importLine = `import { ${className} } from '${importPath}';`;
+  const lines = content.split('\n');
+  let lastImport = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^import\b/.test(lines[i]) || /^\s*}\s+from\s+/.test(lines[i])) {
+      lastImport = i;
+    }
+  }
+  if (lastImport === -1) return importLine + '\n' + content;
+  lines.splice(lastImport + 1, 0, importLine);
+  return lines.join('\n');
+}
+
+/** Name of the first `export const X = {...}` in the file (null if unreadable). */
+function detectExportName(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const match = fs
+    .readFileSync(filePath, 'utf8')
+    .match(/export\s+const\s+(\w+)\s*(?::[^=]+)?=\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
+ * rather than shadowed by a second file.
+ */
+function entityConstantsPath(constantsDir) {
+  const legacy = path.join(constantsDir, 'enity.constants.ts');
+  const canonical = path.join(constantsDir, 'entity.constants.ts');
+  if (!fs.existsSync(canonical) && fs.existsSync(legacy)) return legacy;
+  return canonical;
+}
+
+function escapeRe(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = {
+  ensureConstantEntry,
+  ensureMapEntry,
+  detectExportName,
+  entityConstantsPath,
+};

package/src/lib/naming.js

@@ -2,8 +2,8 @@
 
 /**
  * Naming helpers. Every generated filename follows the dot.separated.lowercase
- * convention (e.g. business.client.entity.ts) and every class name is PascalCase
- * (e.g. BusinessClientEntity). These helpers are the single source of truth for
+ * convention (e.g. round.shape.entity.ts) and every class name is PascalCase
+ * (e.g. RoundShapeEntity). These helpers are the single source of truth for
  * turning a raw user input (PascalCase, kebab-case, snake_case, spaced, or
  * dotted) into the canonical word list both conventions are derived from.
  */
@@ -19,25 +19,25 @@ function toWords(input) {
     .filter(Boolean);
 }
 
-/** business.client */
+/** round.shape */
 function toDotCase(input) {
   return toWords(input).join('.');
 }
 
-/** BusinessClient */
+/** RoundShape */
 function toPascalCase(input) {
   return toWords(input)
     .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
     .join('');
 }
 
-/** businessClient */
+/** roundShape */
 function toCamelCase(input) {
   const pascal = toPascalCase(input);
   return pascal.charAt(0).toLowerCase() + pascal.slice(1);
 }
 
-/** business-client (used for HTTP route segments / swagger tags) */
+/** round-shape (used for HTTP route segments / swagger tags) */
 function toKebabCase(input) {
   return toWords(input).join('-');
 }

package/src/lib/paths.js

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

package/src/lib/sync.engine.js

@@ -18,6 +18,8 @@ const path = require('path');
 const CATEGORIES = [
   { key: 'controllers', folder: 'controllers' },
   { key: 'services', folder: 'services' },
+  { key: 'libraries', folder: 'libraries' },
+  { key: 'dtos', folder: 'dtos' },
   { key: 'jobs', folder: 'jobs' },
   { key: 'subscribers', folder: 'subscribers' },
 ];

package/src/lib/templates.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { toDotCase, toPascalCase, toKebabCase } = require('./naming');
+const { toDotCase, toPascalCase, toKebabCase, toCamelCase } = require('./naming');
 
 /**
  * Code templates. All generated code imports shared base classes from the
@@ -10,22 +10,34 @@ const { toDotCase, toPascalCase, toKebabCase } = require('./naming');
  * across nestjs-boilerplate.
  */
 
-/** Build the canonical names for a given entity-ish base (e.g. "BusinessClient"). */
+/** Build the canonical names for a given entity-ish base (e.g. "Shape"). */
 function names(base) {
   const dot = toDotCase(base);
   const pascal = toPascalCase(base);
+  const camel = toCamelCase(base);
   return {
     dot,
     pascal,
+    camel,
     kebab: toKebabCase(base),
     entityClass: `${pascal}Entity`,
     entityFile: `${dot}.entity.ts`,
+    attributesDtoClass: `${pascal}AttributesDto`,
+    attributesDtoFile: `${dot}.attributes.dto.ts`,
     controllerClass: `${pascal}Controller`,
     controllerFile: `${dot}.controller.ts`,
     dtoClass: `Add${pascal}DataDto`,
     dtoFile: `add.${dot}.data.dto.ts`,
     processorClass: `${pascal}DataProcessor`,
     processorFile: `${dot}.data.processor.ts`,
+    listFilterDtoClass: `${pascal}ListFilterDto`,
+    listFilterDtoFile: `${dot}.list.filter.dto.ts`,
+    listProcessorClass: `${pascal}ListProcessor`,
+    listProcessorFile: `${dot}.list.processor.ts`,
+    subscriberClass: `${pascal}Subscriber`,
+    subscriberFile: `${dot}.subscriber.ts`,
+    jobClass: `${pascal}Job`,
+    jobFile: `${dot}.job.ts`,
   };
 }
 
@@ -33,19 +45,28 @@ function entity(base, tableName) {
   const n = names(base);
   return `import { Column, Entity } from 'typeorm';
 import { CommonEntity } from '@neohm/nestend';
+import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
 
 @Entity({ name: '${tableName}' })
 export class ${n.entityClass} extends CommonEntity {
-  // TODO: declare columns for ${n.pascal}.
   @Column({ type: 'jsonb' })
-  attributes: Record<string, any>;
+  attributes: ${n.attributesDtoClass};
 }
 `;
 }
 
-function controller(base) {
+function attributesDto(base) {
   const n = names(base);
-  return `import { Controller } from '@nestjs/common';
+  return `export class ${n.attributesDtoClass} {
+  // TODO: declare attribute fields for ${n.pascal}.
+}
+`;
+}
+
+function controller(base, { listProcessor = false } = {}) {
+  const n = names(base);
+  if (!listProcessor) {
+    return `import { Controller } from '@nestjs/common';
 import { ApiTags } from '@nestjs/swagger';
 
 @ApiTags('${n.kebab}')
@@ -53,6 +74,24 @@ import { ApiTags } from '@nestjs/swagger';
 export class ${n.controllerClass} {
   constructor() {}
 }
+`;
+  }
+  return `import { Body, Controller, Post } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { SqlService } from '@neohm/nestend';
+import { ${n.listFilterDtoClass} } from '../dtos/${n.dot}.list.filter.dto';
+import { ${n.listProcessorClass} } from '../libraries/${n.dot}.list.processor';
+
+@ApiTags('${n.kebab}')
+@Controller('api/v1/${n.kebab}')
+export class ${n.controllerClass} {
+  constructor(private readonly sqlService: SqlService) {}
+
+  @Post('list')
+  async list(@Body() body: ${n.listFilterDtoClass}) {
+    return new ${n.listProcessorClass}(this.sqlService).process(body);
+  }
+}
 `;
 }
 
@@ -83,8 +122,8 @@ export class ${n.processorClass} extends CommonDataProcessor {
   }
 
   private async validate() {
-    // TODO: collect validation errors via this.addColumnError(...).
-    this.throwPresentErrors();
+    // TODO: collect validation errors via this.addErrors({ column: 'message' }).
+    this.throwExceptionOnError();
   }
 
   private async set() {
@@ -94,6 +133,113 @@ export class ${n.processorClass} extends CommonDataProcessor {
 `;
 }
 
+function listFilterDto(base) {
+  const n = names(base);
+  return `import { CommonListFilterDto } from '@neohm/nestend';
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString } from 'class-validator';
+
+export class ${n.listFilterDtoClass} extends CommonListFilterDto {
+  @Expose()
+  @IsOptional()
+  @IsString()
+  custom_filter?: string;
+}
+`;
+}
+
+function listProcessor(base, tableName) {
+  const n = names(base);
+  return `import {
+  CommonListFilterConfig,
+  CommonListProcessor,
+  SortDirection,
+  SqlService,
+} from '@neohm/nestend';
+import { ${n.listFilterDtoClass} } from '../dtos/${n.dot}.list.filter.dto';
+
+export class ${n.listProcessorClass} extends CommonListProcessor {
+  protected config: CommonListFilterConfig = {
+    query: '${tableName} a',
+    columns: [
+      { key: 'a.id', identifier: 'id' },
+      { key: 'a.attributes', identifier: 'attributes' },
+      { key: 'a.created_at', identifier: 'created_at' },
+    ],
+    defaultSort: { field: 'id', direction: SortDirection.DESC },
+  };
+
+  constructor(protected readonly sqlService: SqlService) {
+    super();
+  }
+
+  async process(payload: ${n.listFilterDtoClass}) {
+    this.payload = payload;
+
+    this.applyCustomFilters(payload);
+
+    return this.handle();
+  }
+
+  private async applyCustomFilters(payload: ${n.listFilterDtoClass}) {
+    this.applyCustomFilter(payload.custom_filter);
+  }
+
+  private async applyCustomFilter(custom_filter: string) {
+    if (!custom_filter) return;
+
+    // Example of a hand-rolled condition beyond the config-driven filters.
+    // TODO: replace test_column with a real filterable column of ${n.pascal}.
+    this.conditions.push(\`test_column ilike '%\${custom_filter}%'\`);
+  }
+}
+`;
+}
+
+function subscriber(base) {
+  const n = names(base);
+  return `import { CommonSubscriber } from '@neohm/nestend';
+import { EventSubscriber } from 'typeorm';
+import { ${n.entityClass} } from '../entities/${n.dot}.entity';
+import { DataSource } from 'typeorm';
+import { ${n.jobClass} } from '../jobs/${n.dot}.job';
+
+@EventSubscriber()
+export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
+  constructor(
+    protected readonly datasource: DataSource,
+    protected readonly entityJob: ${n.jobClass},
+  ) {
+    super();
+    datasource.subscribers.push(this);
+  }
+
+  listenTo() {
+    return ${n.entityClass};
+  }
+}
+`;
+}
+
+function job(base) {
+  const n = names(base);
+  return `import { CommonJob, QueueService } from '@neohm/nestend';
+import { Injectable } from '@nestjs/common';
+import { JobConstants } from '../../constants/job.constants';
+
+@Injectable()
+export class ${n.jobClass} extends CommonJob {
+  constructor(protected readonly queueService: QueueService) {
+    super(JobConstants.${n.camel}Job);
+  }
+
+  async handle(event: any): Promise<void> {
+    return;
+  }
+}
+`;
+}
+
 /**
  * Migration generated as part of `nh gen`, stubbed with the columns the
  * generated entity carries (rootPrimary + created_by FK from CommonEntity,
@@ -160,11 +306,65 @@ 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';
+
+export const JobConstants = {
+  ...baseJobConstants,
+  ${n.camel}Job: '${n.dot}.job',
+};
+`;
+}
+
+/** Fresh src/constants/entity.constants.ts (first entry included). */
+function entityConstantsFile(base) {
+  const n = names(base);
+  return `import { baseEntityConstants } from '@neohm/nestend';
+
+export const EntityConstants = {
+  ...baseEntityConstants,
+  ${n.camel}: '${n.dot}',
+};
+`;
+}
+
+/** Fresh src/constants/job.maps.ts (first entry included). */
+function jobMapsFile(base, moduleDot, constants) {
+  const n = names(base);
+  return `import { baseJobMaps } from '@neohm/nestend';
+import { ${n.jobClass} } from '../${moduleDot}/jobs/${n.dot}.job';
+import { ${constants.exportName} } from '${constants.importPath}';
+
+export const JobMaps = {
+  ...baseJobMaps,
+  [${constants.exportName}.${n.camel}Job]: ${n.jobClass},
+};
+`;
+}
+
+/** Fresh src/constants/entity.maps.ts (first entry included). */
+function entityMapsFile(base, moduleDot, constants) {
+  const n = names(base);
+  return `import { baseEntityMaps } from '@neohm/nestend';
+import { ${n.entityClass} } from '../${moduleDot}/entities/${n.dot}.entity';
+import { ${constants.exportName} } from '${constants.importPath}';
+
+export const EntityMaps = {
+  ...baseEntityMaps,
+  [${constants.exportName}.${n.camel}]: ${n.entityClass},
+};
+`;
+}
+
 /** A freshly scaffolded module before any es6.classes content exists. */
 function emptyEs6Classes() {
   return `export const es6Classes = {
   controllers: [],
   services: [],
+  libraries: [],
+  dtos: [],
   jobs: [],
   subscribers: [],
 };
@@ -187,6 +387,7 @@ import { es6Classes } from './es6.classes';
   controllers: [...es6Classes.controllers],
   providers: [
     ...es6Classes.services,
+    ...es6Classes.libraries,
     ...es6Classes.jobs,
     ...es6Classes.subscribers,
   ],
@@ -198,12 +399,21 @@ export class ${pascal}Module {}
 module.exports = {
   names,
   entity,
+  attributesDto,
   controller,
   dto,
   processor,
+  listFilterDto,
+  listProcessor,
+  subscriber,
+  job,
   genMigration,
   migration,
   seed,
+  jobConstantsFile,
+  entityConstantsFile,
+  jobMapsFile,
+  entityMapsFile,
   emptyEs6Classes,
   moduleFile,
 };