@neohm/nh-cli 1.1.4 → 1.2.0

package/src/lib/templates.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const {
+  toWords,
   toDotCase,
   toPascalCase,
   toKebabCase,
@@ -16,6 +17,17 @@ const {
  * across nestjs-boilerplate.
  */
 
+/**
+ * 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 +44,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 +56,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 +75,26 @@ function names(base) {
 
 function entity(base, tableName) {
   const n = names(base);
-  return `import { Column, Entity } from 'typeorm';
-import { CommonEntity } from '@neohm/nestend';
+  return `import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
+import { CommonEntity, TenantEntity } from '@neohm/nestend';
 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,32 +107,259 @@ 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, '@neohm/nestend'),
+    `import { ${n.serviceClass} } from '../services/${n.dot}.service';`,
+  ];
+  if (processor) {
+    imports.push(
+      `import { ${n.dtoClass} } from '../dtos/add.${n.dot}.data.dto';`,
+    );
+  }
 
+  const methods = [
+    `  @Get(':id')
+  async get${n.pascal}(@Param() params: CommonParamsDto) {
+    const { user } = await this.authService.validateAccess(
+      'add-scope',
+      'add-role',
+    );
+
+    return this.${svcProp}.get(user, params.id);
+  }`,
+  ];
+
+  if (processor) {
+    methods.push(`  @Post()
+  async upsert${n.pascal}(@Body() body: ${n.dtoClass}) {
+    await this.authService.validateAccess('add-scope', 'add-role');
+
+    return this.${svcProp}.upsert(body);
+  }`);
+  }
+
+  if (listProcessor) {
+    methods.push(`  @Post('list')
+  async list(@Body() body: CommonListFilterDto) {
+    const { user } = await this.authService.validateAccess(
+      'add-scope',
+      'add-role',
+    );
+    return this.${svcProp}.list(user, body);
+  }`);
+  }
+
+  return `${imports.join('\n')}
+
+// TODO: replace 'add-scope' / 'add-role' with this module's scope and role.
 @ApiTags('${n.kebab}')
+@ApiBearerAuth()
 @Controller('api/v1/${n.kebab}')
 export class ${n.controllerClass} {
-  constructor() {}
+  constructor(
+    private readonly ${svcProp}: ${n.serviceClass},
+    private readonly authService: AuthService,
+  ) {}
+
+${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, '@neohm/nestend'),
+    `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) {}`,
+    );
   }
-  return `import { Body, Controller, Post } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
-import { CommonListFilterDto, SqlService } from '@neohm/nestend';
-import { ${n.listProcessorClass} } from '../libraries/${n.dot}.list.processor';
 
-@ApiTags('${n.kebab}')
-@Controller('api/v1/${n.kebab}')
+  // The tenant scope is part of the lookup, not a check after it: a row
+  // belonging to another tenant must read as "not found", never as "forbidden".
+  members.push(`  async get(user: UserEntity, id: string) {
+    const ${n.camel} = await ${n.entityClass}.findOne({
+      where: { id, tenant_id: user.organization_id },
+    });
+    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 '@neohm/nestend';
+
+@ApiTags('${routePath}')
+@ApiBearerAuth()
+@Controller('api/v1/${routePath}')
 export class ${n.controllerClass} {
-  constructor(private readonly sqlService: SqlService) {}
+  constructor(private readonly authService: AuthService) {}
 
-  @Post('list')
-  async list(@Body() body: CommonListFilterDto) {
-    return new ${n.listProcessorClass}(this.sqlService).process(body);
+  @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 '@neohm/nestend';
+
+@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 '@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(data: unknown): Promise<void> {
+    return;
   }
 }
 `;
@@ -111,12 +375,16 @@ export class ${n.dtoClass} extends CommonDataDto {
 `;
 }
 
-function processor(base) {
+function processor(base, { external = false } = {}) {
   const n = names(base);
+  // An external processor sits one level deeper (external/libraries/), so its
+  // reach back into the module's dtos/ gains a segment.
+  const up = external ? '../..' : '..';
+  const cls = external ? n.externalProcessorClass : n.processorClass;
   return `import { CommonDataProcessor } from '@neohm/nestend';
-import { ${n.dtoClass} } from '../dtos/add.${n.dot}.data.dto';
+import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
 
-export class ${n.processorClass} extends CommonDataProcessor {
+export class ${cls} extends CommonDataProcessor {
   protected payload: ${n.dtoClass};
 
   async process(data: ${n.dtoClass}) {
@@ -139,33 +407,63 @@ 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,
   CommonListProcessor,
+  FilterValueTypeEnum,
+  ListFilterService,
   SortDirection,
-  SqlService,
+  UserEntity,
 } from '@neohm/nestend';
 
 /**
- * Lists / filters ${n.pascal}. The \`columns\` config below is the allowlist:
- * an identifier must appear here before a caller can filter or sort on it.
- * Mark a column \`searchable: true\` to include it in the free-text \`str\` sweep.
+ * Lists / filters ${n.pascal}.
+ *
+ * Two separate surfaces, and it matters which one a rule belongs to:
+ *
+ *  - \`columns\` is the caller's allowlist. An identifier must appear here
+ *    before a request can filter or sort on it, and \`searchable: true\` adds
+ *    it to the free-text \`str\` sweep. Everything here is public. Declare a
+ *    \`type\`: it decides how a caller's value is cast and which operators the
+ *    column accepts — add \`operators\` to narrow that further.
+ *
+ *  - \`predicates\` and \`applyCustomPredicates()\` are yours. Both compile
+ *    inside the relation — before any join aggregate or LATERAL runs — and
+ *    carry no public identifier, so a payload cannot name, weaken or compete
+ *    with them. Lifecycle and tenant scoping belong here, never in
+ *    \`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: [
-      { key: 'a.id', identifier: 'id' },
-      { key: 'a.attributes', identifier: 'attributes' },
-      { key: 'a.created_at', identifier: 'created_at' },
+      { key: 'a.id', identifier: 'id', type: FilterValueTypeEnum.UUID },
+      {
+        key: 'a.attributes',
+        identifier: 'attributes',
+        type: FilterValueTypeEnum.JSON,
+      },
+      {
+        key: 'a.created_at',
+        identifier: 'created_at',
+        type: FilterValueTypeEnum.DATETIME,
+      },
     ],
-    defaultSort: { field: 'id', direction: SortDirection.DESC },
+    // Soft-deleted rows are never listed. \`deleted_at\` is deliberately not a
+    // declared column: there is nothing a caller should be doing with it.
+    predicates: ['a.deleted_at is null'],
+    defaultSort: { field: 'created_at', direction: SortDirection.DESC },
   };
 
-  constructor(protected readonly sqlService: SqlService) {
+  constructor(
+    protected readonly listFilterService: ListFilterService,
+    private readonly user: UserEntity,
+  ) {
     super();
   }
 
@@ -174,6 +472,11 @@ export class ${n.listProcessorClass} extends CommonListProcessor {
 
     return this.handle();
   }
+
+  protected applyCustomPredicates() {
+    // Filter for the caller's tenant/organization
+    this.predicates.add('a.tenant_id = :tenant_id', this.user.organization_id);
+  }
 }
 `;
 }
@@ -241,10 +544,19 @@ export class ${className} extends MigrationUtility {
 
   process() {
     this.rootPrimary();
+
+    this.foreign({ name: 'tenant_id', foreignTable: 'sys_tenants' });
     this.foreign({ name: 'created_by', foreignTable: 'sys_users' });
-    // TODO: add columns matching ${n.entityClass} attributes.
+    this.foreign({ name: 'updated_by', foreignTable: 'sys_users' });
+
+    // TODO: add columns matching ${n.entityClass}.
+
     this.json('attributes');
     this.timestamps();
+
+    this.index('tenant_id');
+    this.index('created_by');
+    this.index('updated_by');
   }
 }
 `;
@@ -384,6 +696,11 @@ module.exports = {
   entity,
   attributesDto,
   controller,
+  service,
+  bareController,
+  bareExternalController,
+  bareService,
+  additionalJob,
   dto,
   processor,
   listProcessor,