@neohm/nh-cli 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# @neohm/nh-cli — `nh`
+
+A scaffolding CLI that accelerates development on **neohm. NestJS projects**
+built on top of the shared [`@neohm/nestend`](../nestend) library.
+
+`nh` generates fully wired modules, entities, controllers, DTOs, data
+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:
+
+- **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`.
+
+## Installation
+
+```bash
+# from the neohm-cli directory
+npm install
+npm link            # exposes `nh` globally
+
+# or run without linking
+npx nh --help
+```
+
+Run `nh` from **inside** a target NestJS project (e.g. `nestjs-boilerplate`).
+The project root is auto-detected by walking up from the current directory for a
+`package.json` next to a `src/` folder.
+
+## Commands
+
+| Command               | Description                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `nh gen`              | Interactive wizard: scaffold a module + entity + optional controller/DTO/processor/migration, then auto-wire it. |
+| `nh migration`        | Generate a standalone migration `<timestamp>M-<Name>.ts`.                                                        |
+| `nh seed`             | Generate a seed file `<timestamp>S-<Name>.ts`.                                                                   |
+| `nh sync`             | Rebuild every `es6.classes.ts` barrel and register modules in `app.module.ts`.                                   |
+| `nh check`            | Dry-run of `sync` — show what would change without writing.                                                      |
+| `nh list`             | List scaffolded modules with their entities and providers.                                                       |
+| `nh remove <name>`    | Safely remove a scaffolded module and de-register it (migrations are preserved).                                 |
+| `nh --help` / `nh -v` | Help and version.                                                                                                |
+
+### `nh gen`
+
+```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
+```
+
+Produces, under `src/business/`:
+
+```text
+business/
+  business.module.ts                 # BusinessModule (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
+  enums/  jobs/  services/  subscribers/
+```
+
+plus `src/database/migrations/<timestamp>M-AddBusinessClientTable.ts`, and it
+registers `BusinessModule` in `src/app.module.ts`.
+
+Generated artifacts extend the `@neohm/nestend` base classes:
+
+- Entity → `CommonEntity` (with an empty `attributes` jsonb column)
+- DTO → `CommonPayloadDto`
+- Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`)
+- Migration → `MigrationUtility`
+- Seed → `SeederUtility`
+
+Re-running `gen` for an existing module reuses it and only adds new files —
+existing files are never overwritten.
+
+### `nh sync` and `nh check`
+
+`sync` scans every module under `src/` and regenerates its `es6.classes.ts`
+barrel from the files actually present in `controllers/`, `services/`, `jobs/`
+and `subscribers/`, then ensures each module is imported and listed in
+`app.module.ts`. Files are classified by their **folder** and the presence of an
+exported class — not by a fragile filename suffix — so non-standard names are
+never silently dropped. The operation is idempotent.
+
+`check` performs the same analysis but only **prints** what would change:
+
+```text
+$ nh check
+es6.classes barrels:
+  ok      src/business/es6.classes.ts
+  update  src/test/es6.classes.ts
+            + services: TestService
+
+app.module.ts:
+  ok      src/app.module.ts
+```
+
+## Project layout
+
+```text
+neohm-cli/
+  bin/nh.js                 # executable entry
+  src/index.js              # commander program
+  src/commands/             # gen, migration, seed, sync, check, list, remove
+  src/lib/naming.js         # word-splitting + case conversions
+  src/lib/paths.js          # project-root detection
+  src/lib/templates.js      # code templates
+  src/lib/sync.engine.js    # module scan + barrel + app.module wiring
+  src/lib/fs.utils.js       # safe writes + console reporting
+```
+
+See [`documentation.tex`](./documentation.tex) for the full technical
+reference.
+
+## Requirements
+
+- Node.js (active LTS) and a recent npm
+- A target project that depends on `@neohm/nestend`
+
+```
+
+```

package/bin/nh.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { program } = require('../src/index');
+
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@neohm/nh-cli",
+  "version": "1.0.0",
+  "description": "nh — Command Line Interface for neohm. NestJS projects",
+  "main": "src/index.js",
+  "bin": {
+    "nh": "bin/nh.js"
+  },
+  "scripts": {
+    "start": "node bin/nh.js",
+    "prepublishOnly": "find bin src -name '*.js' | xargs node --check"
+  },
+  "packageManager": "yarn@1.22.22",
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "nestjs",
+    "cli",
+    "scaffold",
+    "neohm",
+    "nestend"
+  ],
+  "author": "Ashim Baral",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "inquirer": "^8.2.6"
+  }
+}

package/src/commands/check.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+
+const { projectPaths } = require('../lib/paths');
+const engine = require('../lib/sync.engine');
+const { log } = require('../lib/fs.utils');
+
+/** Dry-run of `nh sync`: report what would change without writing anything. */
+async function check() {
+  const paths = projectPaths();
+  const modules = engine.scanModules(paths);
+
+  if (!modules.length) {
+    log.warn('No scaffolded modules found under src/.');
+    return;
+  }
+
+  const plan = engine.buildPlan(paths, modules);
+  let changes = 0;
+
+  console.log(chalk.bold('\nes6.classes barrels:'));
+  for (const p of plan.es6) {
+    const rel = path.relative(paths.root, p.path);
+    if (p.changed) {
+      changes++;
+      const verb = p.current === null ? 'create' : 'update';
+      console.log(`  ${chalk.yellow(verb.padEnd(7))} ${rel}`);
+      printArrayDiff(p);
+    } else {
+      console.log(`  ${chalk.green('ok'.padEnd(7))} ${rel}`);
+    }
+  }
+
+  console.log(chalk.bold('\napp.module.ts:'));
+  const am = plan.appModule;
+  const amRel = path.relative(paths.root, am.path);
+  if (am.missing) {
+    log.warn(`  not found at ${amRel}`);
+  } else if (am.changed) {
+    changes++;
+    console.log(`  ${chalk.yellow('update'.padEnd(7))} ${amRel}`);
+    for (const a of am.additions) console.log(`            ${chalk.green('+')} ${a}`);
+  } else {
+    console.log(`  ${chalk.green('ok'.padEnd(7))} ${amRel}`);
+  }
+
+  if (changes) {
+    console.log(chalk.yellow(`\n${changes} file(s) would change. Run \`nh sync\` to apply.`));
+  } else {
+    log.done('In sync — `nh sync` would make no changes.');
+  }
+}
+
+/** Show the registered class names a barrel would contain. */
+function printArrayDiff(p) {
+  for (const cat of engine.CATEGORIES) {
+    const re = new RegExp(`${cat.key}:\\s*\\[([^\\]]*)\\]`);
+    const next = (p.next.match(re) || [])[1] || '';
+    const cur = p.current ? (p.current.match(re) || [])[1] || '' : '';
+    const nextItems = split(next);
+    const curItems = split(cur);
+    const added = nextItems.filter((x) => !curItems.includes(x));
+    for (const a of added) console.log(`            ${chalk.green('+')} ${cat.key}: ${a}`);
+  }
+}
+
+function split(s) {
+  return s
+    .split(',')
+    .map((x) => x.trim())
+    .filter(Boolean);
+}
+
+module.exports = check;

package/src/commands/gen.js

@@ -0,0 +1,130 @@
+'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');
+
+async function gen() {
+  const paths = projectPaths();
+  log.info(`Project: ${paths.root}\n`);
+
+  // 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'),
+    },
+  ]);
+  const moduleDot = naming.toDotCase(moduleNameRaw);
+  const moduleDir = paths.moduleDir(moduleDot);
+  const moduleExisted = fs.existsSync(moduleDir);
+
+  if (moduleExisted) {
+    log.info(`Using existing module "${moduleDot}".`);
+  } else {
+    log.info(`Creating module "${moduleDot}".`);
+  }
+
+  // Always ensure the module skeleton (folders + module file + es6 barrel).
+  for (const sub of MODULE_SUBFOLDERS) ensureDir(path.join(moduleDir, sub));
+  report(
+    writeFile(
+      path.join(moduleDir, `${moduleDot}.module.ts`),
+      tpl.moduleFile(moduleDot),
+    ),
+    path.join(moduleDir, `${moduleDot}.module.ts`),
+    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'),
+    },
+  ]);
+  const n = tpl.names(entityName);
+
+  // 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'),
+    },
+  ]);
+
+  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 },
+  ]);
+
+  if (answers.controller) {
+    const p = path.join(moduleDir, 'controllers', n.controllerFile);
+    report(writeFile(p, tpl.controller(entityName)), p, 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);
+  }
+
+  if (answers.processor) {
+    const p = path.join(moduleDir, 'libraries', n.processorFile);
+    report(writeFile(p, tpl.processor(entityName)), p, 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);
+  }
+
+  // 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`));
+  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)');
+
+  log.done(`Module "${moduleDot}" scaffolded.`);
+  console.log(chalk.dim('Run `nh sync` anytime to re-wire imports after manual edits.'));
+}
+
+module.exports = gen;

package/src/commands/list.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+
+const { projectPaths } = require('../lib/paths');
+const engine = require('../lib/sync.engine');
+const { log } = require('../lib/fs.utils');
+
+/** List scaffolded modules and their entities/providers. */
+async function list() {
+  const paths = projectPaths();
+  const modules = engine.scanModules(paths);
+
+  if (!modules.length) {
+    log.warn('No scaffolded modules found under src/.');
+    return;
+  }
+
+  console.log(chalk.bold(`\nModules in ${path.relative(process.cwd(), paths.srcDir) || 'src'}:\n`));
+  for (const mod of modules) {
+    console.log(`${chalk.cyan.bold(mod.moduleDot)}  ${chalk.dim(`(${mod.moduleClass})`)}`);
+    printGroup('entities', mod.entities.map(base));
+    printGroup('controllers', mod.providers.controllers.map((x) => x.className));
+    printGroup('services', mod.providers.services.map((x) => x.className));
+    printGroup('jobs', mod.providers.jobs.map((x) => x.className));
+    printGroup('subscribers', mod.providers.subscribers.map((x) => x.className));
+    printGroup('dtos', mod.dtos.map(base));
+    console.log('');
+  }
+
+  console.log(chalk.dim(`${modules.length} module(s).`));
+}
+
+function base(file) {
+  return path.basename(file);
+}
+
+function printGroup(label, items) {
+  if (!items.length) return;
+  console.log(`  ${chalk.dim(label.padEnd(12))} ${items.join(', ')}`);
+}
+
+module.exports = list;

package/src/commands/migration.js

@@ -0,0 +1,36 @@
+'use strict';
+
+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');
+
+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: 'migrationName',
+      message: 'Migration name (e.g. AddBusinessClientTable):',
+      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);
+  log.done(`Migration created (${file}).`);
+}
+
+module.exports = migration;

package/src/commands/remove.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+
+const { projectPaths } = require('../lib/paths');
+const naming = require('../lib/naming');
+const engine = require('../lib/sync.engine');
+const { log } = require('../lib/fs.utils');
+
+/** Safely remove a scaffolded module and de-register it from app.module.ts. */
+async function remove(name) {
+  const paths = projectPaths();
+  const moduleDot = naming.toDotCase(name);
+  const moduleDir = paths.moduleDir(moduleDot);
+
+  if (!fs.existsSync(moduleDir) || !engine.scanModules(paths).some((m) => m.moduleDot === moduleDot)) {
+    log.warn(`Module "${moduleDot}" not found under src/.`);
+    return;
+  }
+
+  const mod = engine.scanModule(
+    moduleDir,
+    path.join(moduleDir, `${moduleDot}.module.ts`),
+  );
+
+  console.log(chalk.bold(`\nThis will permanently delete:`));
+  console.log(`  ${chalk.red(path.relative(paths.root, moduleDir))}/  ${chalk.dim('(entire module folder)')}`);
+  console.log(chalk.dim('Migrations/seeds in database/migrations are NOT touched.'));
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: `Remove module "${moduleDot}"?`,
+      default: false,
+    },
+  ]);
+  if (!confirm) {
+    log.info('Aborted.');
+    return;
+  }
+
+  // De-register from app.module.ts before deleting files.
+  if (fs.existsSync(paths.appModule) && mod.moduleClass) {
+    const before = fs.readFileSync(paths.appModule, 'utf8');
+    const after = deregister(before, mod.moduleClass, mod.moduleImportPath);
+    if (after !== before) {
+      fs.writeFileSync(paths.appModule, after);
+      log.removed(`${path.relative(paths.root, paths.appModule)} ${chalk.dim(`(-${mod.moduleClass})`)}`);
+    }
+  }
+
+  fs.rmSync(moduleDir, { recursive: true, force: true });
+  log.removed(`${path.relative(paths.root, moduleDir)}/`);
+
+  log.done(`Module "${moduleDot}" removed.`);
+}
+
+/** Strip a module's import line and its entry from the @Module imports array. */
+function deregister(content, className, importPath) {
+  let out = content
+    .split('\n')
+    .filter((line) => {
+      const isImport =
+        /^import\b/.test(line) &&
+        new RegExp(`from\\s+['"]${escapeRe(importPath)}['"]`).test(line);
+      return !isImport;
+    })
+    .join('\n');
+
+  const idx = out.indexOf('imports:');
+  if (idx !== -1) {
+    const open = out.indexOf('[', idx);
+    const close = out.indexOf(']', open);
+    if (open !== -1 && close !== -1) {
+      const items = out
+        .slice(open + 1, close)
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s && s !== className);
+      const rebuilt = '\n    ' + items.join(',\n    ') + ',\n  ';
+      out = out.slice(0, open + 1) + rebuilt + out.slice(close);
+    }
+  }
+  return out;
+}
+
+function escapeRe(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+module.exports = remove;

package/src/commands/seed.js

@@ -0,0 +1,38 @@
+'use strict';
+
+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');
+
+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: 'seedName',
+      message: 'Seed name (e.g. SeedBusinessClients):',
+      validate: (v) => (v && v.trim() ? true : 'Seed name is required'),
+    },
+  ]);
+
+  // The S- prefix (vs M- for migrations) distinguishes seeds visually in the
+  // shared database/migrations folder; both run through the TypeORM runner.
+  const ts = Date.now();
+  const file = `${ts}S-${naming.toPascalCase(seedName)}.ts`;
+  const p = path.join(paths.migrationsDir, file);
+  report(writeFile(p, tpl.seed(seedName, tableName, ts)), p, paths.root);
+  log.done(`Seed created (${file}).`);
+}
+
+module.exports = seed;

package/src/commands/sync.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+
+const { projectPaths } = require('../lib/paths');
+const engine = require('../lib/sync.engine');
+const { log } = require('../lib/fs.utils');
+
+async function sync() {
+  const paths = projectPaths();
+  const modules = engine.scanModules(paths);
+
+  if (!modules.length) {
+    log.warn('No scaffolded modules found under src/. Nothing to sync.');
+    return;
+  }
+
+  const plan = engine.buildPlan(paths, modules);
+  const written = engine.applyPlan(plan);
+
+  for (const p of plan.es6) {
+    const rel = path.relative(paths.root, p.path);
+    if (p.changed) log.overwritten(rel);
+    else console.log(`  ${chalk.dim('ok')}      ${rel}`);
+  }
+
+  const am = plan.appModule;
+  const amRel = path.relative(paths.root, am.path);
+  if (am.missing) {
+    log.warn(`app.module.ts not found at ${amRel} — skipped module registration.`);
+  } else if (am.changed) {
+    log.overwritten(`${amRel} ${chalk.dim(`(+${am.additions.join(', ')})`)}`);
+  } else {
+    console.log(`  ${chalk.dim('ok')}      ${amRel}`);
+  }
+
+  if (written.length) log.done(`Synced ${written.length} file(s).`);
+  else log.done('Everything already in sync.');
+}
+
+module.exports = sync;

package/src/index.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+function run(action) {
+  return async (...args) => {
+    try {
+      await action(...args);
+    } catch (err) {
+      console.error(chalk.red(`\n✗ ${err.message}`));
+      process.exitCode = 1;
+    }
+  };
+}
+
+program
+  .name('nh')
+  .description('nh — scaffolding CLI for neohm. NestJS projects (built on @neohm/nestend)')
+  .version(pkg.version, '-v, --version', 'output the current version');
+
+program
+  .command('gen')
+  .description('interactive scaffolding wizard (module, entity, controller, dto, processor, migration)')
+  .action(run(() => require('./commands/gen')()));
+
+program
+  .command('migration')
+  .description('generate a standalone migration file (<timestamp>M-<Name>.ts)')
+  .action(run(() => require('./commands/migration')()));
+
+program
+  .command('seed')
+  .description('generate a seed file (<timestamp>S-<Name>.ts)')
+  .action(run(() => require('./commands/seed')()));
+
+program
+  .command('sync')
+  .description('rebuild es6.classes barrels and register modules in app.module.ts')
+  .action(run(() => require('./commands/sync')()));
+
+program
+  .command('check')
+  .description('dry-run of sync — show what would change without writing')
+  .action(run(() => require('./commands/check')()));
+
+program
+  .command('list')
+  .description('list scaffolded modules and their entities/providers')
+  .action(run(() => require('./commands/list')()));
+
+program
+  .command('remove')
+  .argument('<name>', 'module name to remove')
+  .description('safely remove a scaffolded module and de-register it')
+  .action(run((name) => require('./commands/remove')(name)));
+
+module.exports = { program };

package/src/lib/fs.utils.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * Write a generated file. Returns one of: 'created' | 'skipped' | 'overwritten'.
+ * Existing files are never silently clobbered unless `force` is set.
+ */
+function writeFile(filePath, content, { force = false } = {}) {
+  ensureDir(path.dirname(filePath));
+  const exists = fs.existsSync(filePath);
+  if (exists && !force) return 'skipped';
+  fs.writeFileSync(filePath, content);
+  return exists ? 'overwritten' : 'created';
+}
+
+function readFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+/** List files in a dir matching a suffix (e.g. '.controller.ts'). Safe if dir missing. */
+function listBySuffix(dir, suffix) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(suffix))
+    .map((f) => path.join(dir, f));
+}
+
+const log = {
+  created: (rel) => console.log(`  ${chalk.green('create')}  ${rel}`),
+  skipped: (rel) => console.log(`  ${chalk.yellow('skip')}    ${rel} ${chalk.dim('(exists)')}`),
+  overwritten: (rel) => console.log(`  ${chalk.cyan('update')}  ${rel}`),
+  removed: (rel) => console.log(`  ${chalk.red('remove')}  ${rel}`),
+  info: (msg) => console.log(chalk.dim(msg)),
+  warn: (msg) => console.log(chalk.yellow(`! ${msg}`)),
+  done: (msg) => console.log(chalk.green.bold(`\n✓ ${msg}`)),
+};
+
+/** Report a writeFile result against a path relative to the project root. */
+function report(result, filePath, root) {
+  const rel = path.relative(root, filePath);
+  if (result === 'created') log.created(rel);
+  else if (result === 'skipped') log.skipped(rel);
+  else if (result === 'overwritten') log.overwritten(rel);
+}
+
+module.exports = {
+  ensureDir,
+  writeFile,
+  readFile,
+  listBySuffix,
+  log,
+  report,
+};

package/src/lib/naming.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * 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
+ * turning a raw user input (PascalCase, kebab-case, snake_case, spaced, or
+ * dotted) into the canonical word list both conventions are derived from.
+ */
+
+/** Split any reasonable input into lowercase words. */
+function toWords(input) {
+  if (!input) return [];
+  return String(input)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ACRONYMBoundary
+    .split(/[\s._\-]+/)
+    .map((w) => w.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/** business.client */
+function toDotCase(input) {
+  return toWords(input).join('.');
+}
+
+/** BusinessClient */
+function toPascalCase(input) {
+  return toWords(input)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('');
+}
+
+/** businessClient */
+function toCamelCase(input) {
+  const pascal = toPascalCase(input);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/** business-client (used for HTTP route segments / swagger tags) */
+function toKebabCase(input) {
+  return toWords(input).join('-');
+}
+
+module.exports = {
+  toWords,
+  toDotCase,
+  toPascalCase,
+  toCamelCase,
+  toKebabCase,
+};

package/src/lib/paths.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Locate the NestJS project root by walking up from the current working
+ * directory looking for a package.json that sits next to a `src/` folder.
+ * `nh` commands are expected to run from inside the target project
+ * (e.g. nestjs-boilerplate).
+ */
+function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  while (true) {
+    const pkg = path.join(dir, 'package.json');
+    const src = path.join(dir, 'src');
+    if (fs.existsSync(pkg) && fs.existsSync(src)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function requireProjectRoot() {
+  const root = findProjectRoot();
+  if (!root) {
+    throw new Error(
+      'Could not locate a NestJS project (no package.json next to a src/ folder). ' +
+        'Run nh from inside your project, e.g. nestjs-boilerplate.',
+    );
+  }
+  return root;
+}
+
+/** Resolve the canonical paths used by every command. */
+function projectPaths(root = requireProjectRoot()) {
+  const srcDir = path.join(root, 'src');
+  return {
+    root,
+    srcDir,
+    appModule: path.join(srcDir, 'app.module.ts'),
+    migrationsDir: path.join(srcDir, 'database', 'migrations'),
+    moduleDir: (moduleDot) => path.join(srcDir, moduleDot),
+  };
+}
+
+/** Sub-folders every scaffolded module owns. */
+const MODULE_SUBFOLDERS = [
+  'controllers',
+  'subscribers',
+  'services',
+  'enums',
+  'jobs',
+  'libraries',
+  'entities',
+  'dtos',
+];
+
+module.exports = {
+  findProjectRoot,
+  requireProjectRoot,
+  projectPaths,
+  MODULE_SUBFOLDERS,
+};

package/src/lib/sync.engine.js

@@ -0,0 +1,241 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 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
+ * module's es6.classes.ts barrel from the files actually present on disk, and
+ * registers every module in app.module.ts — so the project builds without any
+ * manual import wiring.
+ */
+
+// Provider categories registered through es6.classes.ts. Files are classified
+// by the folder they live in (not by a fragile filename suffix) so that
+// non-standard names — e.g. the boilerplate's `test.service..ts` — are still
+// picked up and never silently dropped from the barrel.
+const CATEGORIES = [
+  { key: 'controllers', folder: 'controllers' },
+  { key: 'services', folder: 'services' },
+  { key: 'jobs', folder: 'jobs' },
+  { key: 'subscribers', folder: 'subscribers' },
+];
+
+// Files in a category folder that are not providers themselves.
+const NON_PROVIDER_FILES = new Set(['es6.classes.ts', 'index.ts']);
+
+function exportedClassName(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match = content.match(/export\s+class\s+(\w+)/);
+  return match ? match[1] : null;
+}
+
+/** Every .ts file in `dir` that exports a class (skips barrels/helpers). */
+function listClassFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.ts') && !NON_PROVIDER_FILES.has(f))
+    .sort()
+    .map((f) => path.join(dir, f))
+    .filter((f) => exportedClassName(f));
+}
+
+/** .ts files in `dir` matching a suffix (used for display-only listings). */
+function listTsFiles(dir, suffix) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(suffix))
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+/** Is this src sub-folder a scaffolded module (has its own *.module.ts)? */
+function moduleFileIn(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null;
+  const found = fs
+    .readdirSync(dir)
+    .find((f) => f.endsWith('.module.ts'));
+  return found ? path.join(dir, found) : null;
+}
+
+/** Discover every scaffolded module under src/ (excludes the root app.module.ts). */
+function scanModules(paths) {
+  const result = [];
+  if (!fs.existsSync(paths.srcDir)) return result;
+  for (const name of fs.readdirSync(paths.srcDir).sort()) {
+    const dir = path.join(paths.srcDir, name);
+    const modFile = moduleFileIn(dir);
+    if (!modFile) continue;
+    result.push(scanModule(dir, modFile));
+  }
+  return result;
+}
+
+function scanModule(dir, modFile) {
+  const moduleDot = path.basename(dir);
+  const providers = {};
+  for (const cat of CATEGORIES) {
+    providers[cat.key] = listClassFiles(path.join(dir, cat.folder)).map(
+      (file) => ({
+        file,
+        className: exportedClassName(file),
+        importPath: `./${cat.folder}/${path.basename(file, '.ts')}`,
+      }),
+    );
+  }
+  return {
+    moduleDot,
+    dir,
+    moduleFile: modFile,
+    moduleClass: exportedClassName(modFile),
+    moduleImportPath: `./${moduleDot}/${path.basename(modFile, '.ts')}`,
+    es6Path: path.join(dir, 'es6.classes.ts'),
+    providers,
+    entities: listTsFiles(path.join(dir, 'entities'), '.entity.ts'),
+    dtos: listTsFiles(path.join(dir, 'dtos'), '.dto.ts'),
+  };
+}
+
+/** Render the es6.classes.ts content for a scanned module. */
+function buildEs6Content(mod) {
+  const importLines = [];
+  const arrayLines = [];
+  for (const cat of CATEGORIES) {
+    const entries = mod.providers[cat.key];
+    for (const e of entries) {
+      importLines.push(`import { ${e.className} } from '${e.importPath}';`);
+    }
+    const classes = entries.map((e) => e.className).join(', ');
+    arrayLines.push(`  ${cat.key}: [${classes}],`);
+  }
+  const header = importLines.length ? importLines.join('\n') + '\n\n' : '';
+  return `${header}export const es6Classes = {\n${arrayLines.join('\n')}\n};\n`;
+}
+
+/** Plan the es6.classes.ts rewrite for one module. */
+function planEs6(mod) {
+  const next = buildEs6Content(mod);
+  const current = fs.existsSync(mod.es6Path)
+    ? fs.readFileSync(mod.es6Path, 'utf8')
+    : null;
+  return {
+    type: 'es6',
+    moduleDot: mod.moduleDot,
+    path: mod.es6Path,
+    current,
+    next,
+    changed: current !== next,
+  };
+}
+
+// ---- app.module.ts registration --------------------------------------------
+
+function ensureImportLine(content, className, importPath) {
+  if (new RegExp(`from\\s+['"]${escapeRe(importPath)}['"]`).test(content)) {
+    return content; // already imported
+  }
+  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');
+}
+
+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);
+}
+
+function escapeRe(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Plan app.module.ts additions for the given modules. */
+function planAppModule(paths, modules) {
+  if (!fs.existsSync(paths.appModule)) {
+    return {
+      type: 'appModule',
+      path: paths.appModule,
+      current: null,
+      next: null,
+      changed: false,
+      additions: [],
+      missing: true,
+    };
+  }
+  const current = fs.readFileSync(paths.appModule, 'utf8');
+  let next = current;
+  const additions = [];
+  for (const mod of modules) {
+    if (!mod.moduleClass) continue;
+    const before = next;
+    next = ensureImportLine(next, mod.moduleClass, mod.moduleImportPath);
+    next = ensureInImportsArray(next, mod.moduleClass);
+    if (next !== before) additions.push(mod.moduleClass);
+  }
+  return {
+    type: 'appModule',
+    path: paths.appModule,
+    current,
+    next,
+    changed: next !== current,
+    additions,
+    missing: false,
+  };
+}
+
+/** Full plan: every module's es6 barrel + app.module registration. */
+function buildPlan(paths, modules = scanModules(paths)) {
+  return {
+    modules,
+    es6: modules.map(planEs6),
+    appModule: planAppModule(paths, modules),
+  };
+}
+
+function applyPlan(plan) {
+  const written = [];
+  for (const p of plan.es6) {
+    if (p.changed) {
+      fs.writeFileSync(p.path, p.next);
+      written.push(p.path);
+    }
+  }
+  if (plan.appModule.changed) {
+    fs.writeFileSync(plan.appModule.path, plan.appModule.next);
+    written.push(plan.appModule.path);
+  }
+  return written;
+}
+
+module.exports = {
+  CATEGORIES,
+  scanModules,
+  scanModule,
+  buildEs6Content,
+  planEs6,
+  planAppModule,
+  buildPlan,
+  applyPlan,
+};

package/src/lib/templates.js

@@ -0,0 +1,209 @@
+'use strict';
+
+const { toDotCase, toPascalCase, toKebabCase } = require('./naming');
+
+/**
+ * Code templates. All generated code imports shared base classes from the
+ * published library `@neohm/nestend` (verified exports: CommonEntity,
+ * CommonPayloadDto, CommonDataProcessor, MigrationUtility, SeederUtility, etc.)
+ * and matches the dot.separated filename / PascalCase class conventions used
+ * across nestjs-boilerplate.
+ */
+
+/** Build the canonical names for a given entity-ish base (e.g. "BusinessClient"). */
+function names(base) {
+  const dot = toDotCase(base);
+  const pascal = toPascalCase(base);
+  return {
+    dot,
+    pascal,
+    kebab: toKebabCase(base),
+    entityClass: `${pascal}Entity`,
+    entityFile: `${dot}.entity.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`,
+  };
+}
+
+function entity(base, tableName) {
+  const n = names(base);
+  return `import { Column, Entity } from 'typeorm';
+import { CommonEntity } from '@neohm/nestend';
+
+@Entity({ name: '${tableName}' })
+export class ${n.entityClass} extends CommonEntity {
+  // TODO: declare columns for ${n.pascal}.
+  @Column({ type: 'jsonb' })
+  attributes: Record<string, any>;
+}
+`;
+}
+
+function controller(base) {
+  const n = names(base);
+  return `import { Controller } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+
+@ApiTags('${n.kebab}')
+@Controller('api/v1/${n.kebab}')
+export class ${n.controllerClass} {
+  constructor() {}
+}
+`;
+}
+
+function dto(base) {
+  const n = names(base);
+  return `import { CommonPayloadDto } from '@neohm/nestend';
+
+export class ${n.dtoClass} extends CommonPayloadDto {
+  // TODO: declare validated payload fields for ${n.pascal}.
+}
+`;
+}
+
+function processor(base) {
+  const n = names(base);
+  return `import { CommonDataProcessor } from '@neohm/nestend';
+import { ${n.dtoClass} } from '../dtos/add.${n.dot}.data.dto';
+
+export class ${n.processorClass} extends CommonDataProcessor {
+  protected payload: ${n.dtoClass};
+
+  async process(data: ${n.dtoClass}) {
+    this.payload = data;
+
+    await this.validate();
+
+    return this.set();
+  }
+
+  private async validate() {
+    // TODO: collect validation errors via this.addColumnError(...).
+    this.throwPresentErrors();
+  }
+
+  private async set() {
+    // TODO: persist ${n.pascal} using this.payload.
+  }
+}
+`;
+}
+
+/**
+ * Migration generated as part of `nh gen`, stubbed with the columns the
+ * generated entity carries (rootPrimary + created_by FK from CommonEntity,
+ * attributes JSON, timestamps).
+ */
+function genMigration(base, tableName, timestamp) {
+  const n = names(base);
+  const className = `Add${n.pascal}Table${timestamp}`;
+  return `import { MigrationUtility } from '@neohm/nestend';
+
+export class ${className} extends MigrationUtility {
+  constructor() {
+    super('${tableName}');
+    this.process();
+  }
+
+  process() {
+    this.rootPrimary();
+    this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
+    // TODO: add columns matching ${n.entityClass} attributes.
+    this.json('attributes');
+    this.timestamps();
+  }
+}
+`;
+}
+
+/** Standalone migration (`nh migration`). */
+function migration(migrationName, tableName, timestamp) {
+  const className = `${toPascalCase(migrationName)}${timestamp}`;
+  return `import { MigrationUtility } from '@neohm/nestend';
+
+export class ${className} extends MigrationUtility {
+  constructor() {
+    super('${tableName}');
+    this.process();
+  }
+
+  process() {
+    this.rootPrimary();
+    // TODO: define columns for ${tableName}.
+    this.timestamps();
+  }
+}
+`;
+}
+
+/** Seed file (`nh seed`). */
+function seed(seedName, tableName, timestamp) {
+  const className = `${toPascalCase(seedName)}${timestamp}`;
+  return `import { SeederUtility } from '@neohm/nestend';
+
+export class ${className} extends SeederUtility {
+  constructor() {
+    super('${tableName}');
+    this.process();
+  }
+
+  process() {
+    // TODO: seed rows, e.g.
+    // this.addRecord({ id: 1, name: 'Example' });
+  }
+}
+`;
+}
+
+/** A freshly scaffolded module before any es6.classes content exists. */
+function emptyEs6Classes() {
+  return `export const es6Classes = {
+  controllers: [],
+  services: [],
+  jobs: [],
+  subscribers: [],
+};
+`;
+}
+
+function moduleFile(moduleBase) {
+  const pascal = toPascalCase(moduleBase);
+  return `import { Module } from '@nestjs/common';
+import {
+  CommonModule,
+  QueueModule,
+  AuthModule,
+  SystemPropertyModule,
+} from '@neohm/nestend';
+import { es6Classes } from './es6.classes';
+
+@Module({
+  imports: [CommonModule, QueueModule, AuthModule, SystemPropertyModule],
+  controllers: [...es6Classes.controllers],
+  providers: [
+    ...es6Classes.services,
+    ...es6Classes.jobs,
+    ...es6Classes.subscribers,
+  ],
+})
+export class ${pascal}Module {}
+`;
+}
+
+module.exports = {
+  names,
+  entity,
+  controller,
+  dto,
+  processor,
+  genMigration,
+  migration,
+  seed,
+  emptyEs6Classes,
+  moduleFile,
+};