@neohm/nh-cli 1.1.5 → 1.3.0

package/src/lib/templates.js

@@ -1,6 +1,8 @@
 "use strict";
 
+const { pkg, current } = require('./flavour');
 const {
+  toWords,
   toDotCase,
   toPascalCase,
   toKebabCase,
@@ -10,12 +12,30 @@ const {
 
 /**
  * Code templates. All generated code imports shared base classes from the
- * published library `@neohm/nestend` (verified exports: CommonEntity,
- * CommonDataDto, CommonDataProcessor, MigrationUtility, SeederUtility, etc.)
- * and matches the dot.separated filename / PascalCase class conventions used
- * across nestjs-boilerplate.
+ * package the active flavour names — `@neohm/nestend` under `nh`,
+ * `@neohm/nestendx` under `nhx` (verified exports: CommonEntity, CommonDataDto,
+ * CommonDataProcessor, MigrationUtility, SeederUtility, etc.) — and matches the
+ * dot.separated filename / PascalCase class conventions used across the
+ * boilerplates.
+ *
+ * The two differ in what a record belongs to, and that difference is read from
+ * `current().tenantScoped` rather than branched on a package name: tenanted
+ * code scopes rows by `tenant_id` and checks a scope with a role beside it,
+ * while the B2C model scopes by the user who created the row and checks the
+ * scope alone.
  */
 
+/**
+ * A named import, wrapped the way prettier's 80-column printer would: one line
+ * while it fits, one member per line once it doesn't. Generated files are
+ * committed as-is, so they have to come out already formatted.
+ */
+function namedImport(members, from) {
+  const oneLine = `import { ${members.join(', ')} } from '${from}';`;
+  if (oneLine.length <= 80) return oneLine;
+  return `import {\n${members.map((m) => `  ${m},`).join('\n')}\n} from '${from}';`;
+}
+
 /** Build the canonical names for a given entity-ish base (e.g. "Shape"). */
 function names(base) {
   const dot = toDotCase(base);
@@ -32,6 +52,8 @@ function names(base) {
     attributesDtoFile: `${dot}.attributes.dto.ts`,
     controllerClass: `${pascal}Controller`,
     controllerFile: `${dot}.controller.ts`,
+    serviceClass: `${pascal}Service`,
+    serviceFile: `${dot}.service.ts`,
     dtoClass: `Add${pascal}DataDto`,
     dtoFile: `add.${dot}.data.dto.ts`,
     processorClass: `${pascal}DataProcessor`,
@@ -42,6 +64,17 @@ function names(base) {
     subscriberFile: `${dot}.subscriber.ts`,
     jobClass: `${pascal}Job`,
     jobFile: `${dot}.job.ts`,
+    // External (API-key) surface. Mirrors the internal names with an
+    // `external.` filename prefix and an `External` class prefix, matching
+    // external/controllers/external.test.controller.ts in the boilerplate.
+    externalControllerClass: `External${pascal}Controller`,
+    externalControllerFile: `external.${dot}.controller.ts`,
+    externalServiceClass: `External${pascal}Service`,
+    externalServiceFile: `external.${dot}.service.ts`,
+    externalProcessorClass: `External${pascal}DataProcessor`,
+    externalProcessorFile: `external.${dot}.data.processor.ts`,
+    externalListProcessorClass: `External${pascal}ListProcessor`,
+    externalListProcessorFile: `external.${dot}.list.processor.ts`,
     // Fed through naming.migrationFileName/migrationClassName so the migration
     // `nh gen` writes is named exactly like one from `nh migration`.
     migrationName: `Add${pascal}Table`,
@@ -50,14 +83,46 @@ function names(base) {
 
 function entity(base, tableName) {
   const n = names(base);
-  return `import { Column, Entity } from 'typeorm';
-import { CommonEntity } from '@neohm/nestend';
+
+  // Without tenants there is nothing extra to declare: CommonEntity already
+  // carries `created_by` and its relation, which is what a row belongs to.
+  if (!current().tenantScoped) {
+    return `import { Column, Entity } from 'typeorm';
+import { CommonEntity } from '${pkg()}';
+import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
+
+@Entity({ name: '${tableName}' })
+export class ${n.entityClass} extends CommonEntity {
+  // TODO: declare the columns ${n.pascal} owns.
+
+  @Column({ type: 'jsonb' })
+  attributes: ${n.attributesDtoClass};
+
+  // Relations and methods
+}
+`;
+  }
+
+  return `import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { CommonEntity, TenantEntity } from '${pkg()}';
 import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
 
 @Entity({ name: '${tableName}' })
 export class ${n.entityClass} extends CommonEntity {
+  // Tenant scope — the service and the list processor both filter on it.
+  @Column()
+  tenant_id: string;
+
+  // TODO: declare the columns ${n.pascal} owns.
+
   @Column({ type: 'jsonb' })
   attributes: ${n.attributesDtoClass};
+
+  // Relations and methods
+
+  @ManyToOne(() => TenantEntity)
+  @JoinColumn({ name: 'tenant_id' })
+  tenant: TenantEntity;
 }
 `;
 }
@@ -70,46 +135,270 @@ function attributesDto(base) {
 `;
 }
 
-function controller(base, { listProcessor = false } = {}) {
+/**
+ * Controllers hold no business logic. They authenticate the caller, then
+ * 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 } = {}) {
   const n = names(base);
-  if (!listProcessor) {
-    return `import { Controller } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
+  const svcProp = `${n.camel}Service`;
+  const hasPost = processor || listProcessor;
+
+  // @nestjs/common members, alphabetised the way prettier leaves them.
+  const nestCommon = ['Controller', 'Get', 'Param'];
+  if (hasPost) nestCommon.push('Body', 'Post');
+  nestCommon.sort();
+
+  const nestendImports = ['AuthService'];
+  if (listProcessor) nestendImports.push('CommonListFilterDto');
+  nestendImports.push('CommonParamsDto');
+
+  const imports = [
+    namedImport(nestCommon, '@nestjs/common'),
+    // @ApiBearerAuth() attaches the requirement to these operations. The
+    // DocumentBuilder call only registers the scheme (under its default name,
+    // 'bearer') and draws the Authorize button — without the decorator
+    // swagger-ui shows no padlock and never sends the Authorization header.
+    `import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';`,
+    namedImport(nestendImports, pkg()),
+    `import { ${n.serviceClass} } from '../services/${n.dot}.service';`,
+  ];
+  if (processor) {
+    imports.push(
+      `import { ${n.dtoClass} } from '../dtos/add.${n.dot}.data.dto';`,
+    );
+  }
 
-@ApiTags('${n.kebab}')
-@Controller('api/v1/${n.kebab}')
-export class ${n.controllerClass} {
-  constructor() {}
-}
-`;
+  // Tenanted access takes a scope and a role; the B2C model has no roles at
+  // all, so the same call carries the scope alone.
+  const tenanted = current().tenantScoped;
+  const gate = (indent) =>
+    tenanted
+      ? `await this.authService.validateAccess(\n${indent}  'add-scope',\n${indent}  'add-role',\n${indent})`
+      : `await this.authService.validateAccess('add-scope')`;
+
+  const methods = [
+    `  @Get(':id')
+  async get${n.pascal}(@Param() params: CommonParamsDto) {
+    const { user } = ${gate('    ')};
+
+    return this.${svcProp}.get(user, params.id);
+  }`,
+  ];
+
+  if (processor) {
+    methods.push(`  @Post()
+  async upsert${n.pascal}(@Body() body: ${n.dtoClass}) {
+    ${tenanted ? `await this.authService.validateAccess('add-scope', 'add-role');` : `await this.authService.validateAccess('add-scope');`}
+
+    return this.${svcProp}.upsert(body);
+  }`);
   }
-  return `import { Body, Controller, Post } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
-import {
-  AuthService,
-  CommonListFilterDto,
-  ListFilterService,
-} from '@neohm/nestend';
-import { ${n.listProcessorClass} } from '../libraries/${n.dot}.list.processor';
 
+  if (listProcessor) {
+    methods.push(`  @Post('list')
+  async list(@Body() body: CommonListFilterDto) {
+    const { user } = ${gate('    ')};
+
+    return this.${svcProp}.list(user, body);
+  }`);
+  }
+
+  const gateTodo = tenanted
+    ? `// TODO: replace 'add-scope' / 'add-role' with this module's scope and role.`
+    : `// TODO: replace 'add-scope' with this module's scope — a granted parent\n// scope reaches its children, so name the one the feature is filed under.`;
+
+  return `${imports.join('\n')}
+
+${gateTodo}
 @ApiTags('${n.kebab}')
+@ApiBearerAuth()
 @Controller('api/v1/${n.kebab}')
 export class ${n.controllerClass} {
   constructor(
-    private readonly listFilterService: ListFilterService,
+    private readonly ${svcProp}: ${n.serviceClass},
     private readonly authService: AuthService,
   ) {}
 
-  @Post('list')
-  async list(@Body() body: CommonListFilterDto) {
-    // Open by default: authenticate explicitly. validateAccess() gates the
-    // feature on the caller's organization, and guarantees the
-    // organization_id the processor scopes on — a tenantless user is
-    // refused here rather than reaching the query with a null scope.
-    // TODO: replace with the sys_scopes identifier this endpoint sits behind.
-    const { user } = await this.authService.validateAccess('add-scope', 'add-role');
-
-    return new ${n.listProcessorClass}(this.listFilterService, user).process(body);
+${methods.join('\n\n')}
+}
+`;
+}
+
+/**
+ * The module's service layer, always generated: single-record reads live here,
+ * and write / list work is handed to the processors. Injected into the
+ * controller, so nothing downstream has to know how a record is fetched.
+ *
+ * `get()` is unconditional — it is the one operation that needs no processor.
+ * `upsert()` appears with a data processor, `list()` with a listing processor.
+ */
+function service(base, { processor = false, listProcessor = false } = {}) {
+  const n = names(base);
+  const label = toWords(base).join(' ');
+
+  const nestendImports = [];
+  if (listProcessor) {
+    nestendImports.push('CommonListFilterDto', 'ListFilterService');
+  }
+  nestendImports.push('NotFoundException', 'UserEntity');
+
+  const imports = [
+    namedImport(nestendImports, pkg()),
+    `import { Injectable } from '@nestjs/common';`,
+  ];
+  if (listProcessor) {
+    imports.push(
+      `import { ${n.listProcessorClass} } from '../libraries/${n.dot}.list.processor';`,
+    );
+  }
+  if (processor) {
+    imports.push(
+      `import { ${n.dtoClass} } from '../dtos/add.${n.dot}.data.dto';`,
+      `import { ${n.processorClass} } from '../libraries/${n.dot}.data.processor';`,
+    );
+  }
+  imports.push(
+    `import { ${n.entityClass} } from '../entities/${n.dot}.entity';`,
+  );
+
+  const members = [];
+  if (listProcessor) {
+    members.push(
+      `  constructor(protected readonly listFilterService: ListFilterService) {}`,
+    );
+  }
+
+  // Ownership is part of the lookup, not a check after it: a row belonging to
+  // someone else must read as "not found", never as "forbidden". Tenanted rows
+  // carry the organization; without tenants it is the user who created it.
+  const owner = current().tenantScoped
+    ? 'tenant_id: user.organization_id'
+    : 'created_by: user.id';
+  members.push(`  async get(user: UserEntity, id: string) {
+    const ${n.camel} = await ${n.entityClass}.findOne({
+      where: { id, ${owner} },
+    });
+    if (!${n.camel}) throw new NotFoundException('Invalid ${label} id');
+
+    return ${n.camel};
+  }`);
+
+  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);
+  }`);
+  }
+
+  if (listProcessor) {
+    // Emit the call already wrapped the way prettier's 80-column printer
+    // would, so a long entity name doesn't leave the generated file dirty.
+    // Prettier's three tiers: keep the fluent one-liner; else break the
+    // .process() argument; else break the constructor arguments too.
+    const call = `new ${n.listProcessorClass}(this.listFilterService, user)`;
+    const oneLine = `    return ${call}.process(data);`;
+    const brokenArg = `    return ${call}.process(`;
+    let body;
+    if (oneLine.length <= 80) {
+      body = oneLine;
+    } else if (brokenArg.length <= 80) {
+      body = `${brokenArg}\n      data,\n    );`;
+    } else {
+      body = `    return new ${n.listProcessorClass}(\n      this.listFilterService,\n      user,\n    ).process(data);`;
+    }
+    members.push(`  async list(user: UserEntity, data: CommonListFilterDto) {
+${body}
+  }`);
+  }
+
+  return `${imports.join('\n')}
+
+@Injectable()
+export class ${n.serviceClass} {
+${members.join('\n\n')}
+}
+`;
+}
+
+/**
+ * Bare controller for `nh gen -c`: swagger tag, the caller-supplied route
+ * under api/v1, AuthService on hand, and one empty `check()` to build on.
+ */
+function bareController(base, routePath) {
+  const n = names(base);
+  return `import { Controller, Get } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { AuthService } from '${pkg()}';
+
+@ApiTags('${routePath}')
+@ApiBearerAuth()
+@Controller('api/v1/${routePath}')
+export class ${n.controllerClass} {
+  constructor(private readonly authService: AuthService) {}
+
+  @Get('check')
+  async check() {}
+}
+`;
+}
+
+/**
+ * Bare external controller for `nh gen -x -c`. The API-key surface differs
+ * from the internal one in three ways, all of them load-bearing: the route is
+ * api/e/v1, the key is declared to swagger with @ApiSecurity('api-key'), and
+ * access is checked through ApiKeyService rather than AuthService.
+ */
+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()}';
+
+@ApiTags('external-${routePath} (Api key)')
+@ApiSecurity('api-key')
+@Controller('api/e/v1/${routePath}')
+export class ${n.externalControllerClass} {
+  constructor(private readonly apiKeyService: ApiKeyService) {}
+
+  @Get('check')
+  async check() {}
+}
+`;
+}
+
+/** Bare injectable service for `nh gen -s` / `nh gen -x -s`. */
+function bareService(base, { external = false } = {}) {
+  const n = names(base);
+  const cls = external ? n.externalServiceClass : n.serviceClass;
+  return `import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class ${cls} {}
+`;
+}
+
+/**
+ * Standalone job for `nh gen -j`. Unlike the entity job the wizard scaffolds,
+ * this one is not driven by a subscriber, so it takes no DatabaseEventDto and
+ * references no entity — whatever `dispatch()` was handed arrives as `data`.
+ */
+function additionalJob(base) {
+  const n = names(base);
+  return `import { CommonJob, QueueService } from '${pkg()}';
+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(data: unknown): Promise<void> {
+    return;
   }
 }
 `;
@@ -117,7 +406,7 @@ export class ${n.controllerClass} {
 
 function dto(base) {
   const n = names(base);
-  return `import { CommonDataDto } from '@neohm/nestend';
+  return `import { CommonDataDto } from '${pkg()}';
 
 export class ${n.dtoClass} extends CommonDataDto {
   // TODO: declare validated payload fields for ${n.pascal}.
@@ -125,12 +414,16 @@ export class ${n.dtoClass} extends CommonDataDto {
 `;
 }
 
-function processor(base) {
+function processor(base, { external = false } = {}) {
   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 {
+  // 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()}';
+import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
+
+export class ${cls} extends CommonDataProcessor {
   protected payload: ${n.dtoClass};
 
   async process(data: ${n.dtoClass}) {
@@ -153,8 +446,9 @@ export class ${n.processorClass} extends CommonDataProcessor {
 `;
 }
 
-function listProcessor(base, tableName) {
+function listProcessor(base, tableName, { external = false } = {}) {
   const n = names(base);
+  const cls = external ? n.externalListProcessorClass : n.listProcessorClass;
   return `import {
   CommonListFilterConfig,
   CommonListFilterDto,
@@ -163,7 +457,7 @@ function listProcessor(base, tableName) {
   ListFilterService,
   SortDirection,
   UserEntity,
-} from '@neohm/nestend';
+} from '${pkg()}';
 
 /**
  * Lists / filters ${n.pascal}.
@@ -183,7 +477,7 @@ function listProcessor(base, tableName) {
  *    \`columns\`. Standing literal clauses go in \`predicates\`; anything
  *    carrying a value goes in the method, where add() binds it.
  */
-export class ${n.listProcessorClass} extends CommonListProcessor {
+export class ${cls} extends CommonListProcessor {
   protected config: CommonListFilterConfig = {
     query: '${tableName} a',
     columns: [
@@ -219,11 +513,13 @@ export class ${n.listProcessorClass} extends CommonListProcessor {
   }
 
   protected applyCustomPredicates() {
-  // Filter for specific user's tenant/organization
-    this.predicates.add(
-      'a.organization_id = :organization_id',
-      this.user.organization_id,
-    );
+${
+  current().tenantScoped
+    ? `    // Filter for the caller's tenant/organization
+    this.predicates.add('a.tenant_id = :tenant_id', this.user.organization_id);`
+    : `    // Filter for the caller: rows belong to whoever created them.
+    this.predicates.add('a.created_by = :created_by', this.user.id);`
+}
   }
 }
 `;
@@ -231,7 +527,7 @@ export class ${n.listProcessorClass} extends CommonListProcessor {
 
 function subscriber(base) {
   const n = names(base);
-  return `import { CommonSubscriber } from '@neohm/nestend';
+  return `import { CommonSubscriber } from '${pkg()}';
 import { EventSubscriber } from 'typeorm';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
 import { DataSource } from 'typeorm';
@@ -256,7 +552,7 @@ export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
 
 function job(base) {
   const n = names(base);
-  return `import { CommonJob, QueueService, DatabaseEventDto } from '@neohm/nestend';
+  return `import { CommonJob, QueueService, DatabaseEventDto } from '${pkg()}';
 import { Injectable } from '@nestjs/common';
 import { JobConstants } from '../../constants/job.constants';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
@@ -282,7 +578,7 @@ export class ${n.jobClass} extends CommonJob {
 function genMigration(base, tableName, timestamp) {
   const n = names(base);
   const className = migrationClassName(n.migrationName, timestamp);
-  return `import { MigrationUtility } from '@neohm/nestend';
+  return `import { MigrationUtility } from '${pkg()}';
 
 export class ${className} extends MigrationUtility {
   constructor() {
@@ -292,10 +588,21 @@ export class ${className} extends MigrationUtility {
 
   process() {
     this.rootPrimary();
-    this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
-    // TODO: add columns matching ${n.entityClass} attributes.
+
+${
+  current().tenantScoped
+    ? `    this.foreign({ name: 'tenant_id', foreignTable: 'sys_tenants' });\n`
+    : ''
+}    this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
+    this.foreign({ name: 'updated_by', foreignTable: 'sys_users' });
+
+    // TODO: add columns matching ${n.entityClass}.
+
     this.json('attributes');
     this.timestamps();
+
+${current().tenantScoped ? `    this.index('tenant_id');\n` : ''}    this.index('created_by');
+    this.index('updated_by');
   }
 }
 `;
@@ -304,7 +611,7 @@ export class ${className} extends MigrationUtility {
 /** Standalone migration (`nh migration`). */
 function migration(migrationName, tableName, timestamp) {
   const className = migrationClassName(migrationName, timestamp);
-  return `import { MigrationUtility } from '@neohm/nestend';
+  return `import { MigrationUtility } from '${pkg()}';
 
 export class ${className} extends MigrationUtility {
   constructor() {
@@ -324,7 +631,7 @@ export class ${className} extends MigrationUtility {
 /** Seed file (`nh seed`). */
 function seed(seedName, tableName, timestamp) {
   const className = `${toPascalCase(seedName)}${timestamp}`;
-  return `import { SeederUtility } from '@neohm/nestend';
+  return `import { SeederUtility } from '${pkg()}';
 
 export class ${className} extends SeederUtility {
   constructor() {
@@ -343,7 +650,7 @@ export class ${className} extends SeederUtility {
 /** Fresh src/constants/job.constants.ts (first entry included). */
 function jobConstantsFile(base) {
   const n = names(base);
-  return `import { baseJobConstants } from '@neohm/nestend';
+  return `import { baseJobConstants } from '${pkg()}';
 
 export const JobConstants = {
   ...baseJobConstants,
@@ -355,7 +662,7 @@ export const JobConstants = {
 /** Fresh src/constants/entity.constants.ts (first entry included). */
 function entityConstantsFile(base) {
   const n = names(base);
-  return `import { baseEntityConstants } from '@neohm/nestend';
+  return `import { baseEntityConstants } from '${pkg()}';
 
 export const EntityConstants = {
   ...baseEntityConstants,
@@ -367,7 +674,7 @@ export const EntityConstants = {
 /** Fresh src/constants/job.maps.ts (first entry included). */
 function jobMapsFile(base, moduleDot, constants) {
   const n = names(base);
-  return `import { baseJobMaps } from '@neohm/nestend';
+  return `import { baseJobMaps } from '${pkg()}';
 import { ${n.jobClass} } from '../${moduleDot}/jobs/${n.dot}.job';
 import { ${constants.exportName} } from '${constants.importPath}';
 
@@ -381,7 +688,7 @@ export const JobMaps = {
 /** Fresh src/constants/entity.maps.ts (first entry included). */
 function entityMapsFile(base, moduleDot, constants) {
   const n = names(base);
-  return `import { baseEntityMaps } from '@neohm/nestend';
+  return `import { baseEntityMaps } from '${pkg()}';
 import { ${n.entityClass} } from '../${moduleDot}/entities/${n.dot}.entity';
 import { ${constants.exportName} } from '${constants.importPath}';
 
@@ -413,7 +720,7 @@ import {
   QueueModule,
   AuthModule,
   SystemPropertyModule,
-} from '@neohm/nestend';
+} from '${pkg()}';
 import { es6Classes } from './es6.classes';
 
 @Module({
@@ -435,6 +742,11 @@ module.exports = {
   entity,
   attributesDto,
   controller,
+  service,
+  bareController,
+  bareExternalController,
+  bareService,
+  additionalJob,
   dto,
   processor,
   listProcessor,