@neohm/nh-cli 1.3.0 → 1.3.1

package/README.md

@@ -120,15 +120,21 @@ created spreading `baseJobConstants` / `baseEntityConstants` /
 
 Generated artifacts extend the `@neohm/nestend` base classes:
 
-- Entity → `CommonEntity` (a `tenant_id` column with its `TenantEntity`
-  relation, plus an empty `attributes` jsonb column)
+- Entity → `CommonTenantEntity` under `nh` (it carries `tenant_id` and the
+  `TenantEntity` relation, and `TenantScopeSubscriber` stamps and guards it),
+  `CommonEntity` under `nhx`; both with an empty `attributes` jsonb column
 - DTO → `CommonDataDto`
 - Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`),
-  reached through the service's `upsert()`
+  reached through the service's `upsert()`. It takes the caller and, on edit,
+  loads the row scoped to them — another owner's `id` is a field error, never an
+  update.
 - Listing processor → `CommonListProcessor` (column allowlist config, `id` default sort). It takes `CommonListFilterDto` directly — no per-list DTO is generated, since paging, sorting, filters and free-text search all live on the base DTO and the filterable columns are declared in the processor's `columns` config.
 
 ### Controller → service → processor
 
+Generated controllers run under `@UsePipes(StrictValidationPipe)`, take ids
+with `ParseUUIDPipe`, and describe every route with `@ApiOperation`.
+
 Controllers hold no business logic. They authenticate with
 `AuthService.validateAccess()`, then delegate to the module's service — so the
 same operation is reusable from a job, a subscriber or another service, and the
@@ -141,7 +147,7 @@ answers you already gave:
 | Service method | Generated when | Controller endpoint |
 | --- | --- | --- |
 | `get(user, id)` | always | `GET /api/v1/shape/:id` |
-| `upsert(data)` | data processor: Yes | `POST /api/v1/shape` |
+| `upsert(user, data)` | data processor: Yes | `POST /api/v1/shape` |
 | `list(user, data)` | listing processor: Yes | `POST /api/v1/shape/list` |
 
 `get()` is the one operation that needs no processor, so a module that declines
@@ -215,9 +221,9 @@ Only one target flag per run; the module is created if it does not exist yet.
 
 External files take an `external.` filename prefix and an `External` class
 prefix. An external controller differs from an internal one in three ways, all
-load-bearing: it mounts at `api/e/v1/<path>`, it declares the key to swagger
-with `@ApiSecurity('api-key')`, and it authenticates through `ApiKeyService`
-rather than `AuthService`.
+load-bearing: it mounts at `api/e/v1/<path>`, it documents the key header to
+swagger with `@ApiHeader`, and it authenticates through `ApiKeyService` rather
+than `AuthService`.
 
 `-x` does not apply to `-e` or `-j`: a table and a queue worker have no
 inward/outward face, so there is nothing to mirror. Both refuse the flag rather

package/package.json

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

package/src/commands/gen.flag.js

@@ -283,7 +283,13 @@ async function genFlag(target, { external = false } = {}) {
       break;
 
     case 'dataProcessor':
-      write(dest, tpl.processor(rawName, { external }));
+      write(
+        dest,
+        tpl.processor(rawName, {
+          external,
+          withEntity: fs.existsSync(path.join(moduleDir, 'entities', n.entityFile)),
+        }),
+      );
       // The processor's payload DTO lives in the module's dtos/ either way —
       // created here only if it is not already there.
       write(path.join(moduleDir, 'dtos', n.dtoFile), tpl.dto(rawName));

package/src/commands/gen.js

@@ -135,7 +135,7 @@ async function gen() {
     report(writeFile(dtoPath, tpl.dto(entityName)), dtoPath, paths.root);
 
     const procPath = path.join(moduleDir, "libraries", n.processorFile);
-    report(writeFile(procPath, tpl.processor(entityName)), procPath, paths.root);
+    report(writeFile(procPath, tpl.processor(entityName, { withEntity: true })), procPath, paths.root);
   }
 
   // 6. Optional: listing processor (takes CommonListFilterDto directly) ------

package/src/lib/templates.js

@@ -103,26 +103,20 @@ export class ${n.entityClass} extends CommonEntity {
 `;
   }
 
-  return `import { Column, Entity, JoinColumn, ManyToOne } from 'typeorm';
-import { CommonEntity, TenantEntity } from '${pkg()}';
+  // CommonTenantEntity adds tenant_id + the tenant relation; TenantScopeSubscriber
+  // stamps it from the session and refuses cross-tenant writes.
+  return `import { Column, Entity } from 'typeorm';
+import { CommonTenantEntity } from '${pkg()}';
 import { ${n.attributesDtoClass} } from '../dtos/${n.dot}.attributes.dto';
 
 @Entity({ name: '${tableName}' })
-export class ${n.entityClass} extends CommonEntity {
-  // Tenant scope — the service and the list processor both filter on it.
-  @Column()
-  tenant_id: string;
-
+export class ${n.entityClass} extends CommonTenantEntity {
   // TODO: declare the columns ${n.pascal} owns.
 
   @Column({ type: 'jsonb' })
   attributes: ${n.attributesDtoClass};
 
   // Relations and methods
-
-  @ManyToOne(() => TenantEntity)
-  @JoinColumn({ name: 'tenant_id' })
-  tenant: TenantEntity;
 }
 `;
 }
@@ -146,13 +140,13 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
   const hasPost = processor || listProcessor;
 
   // @nestjs/common members, alphabetised the way prettier leaves them.
-  const nestCommon = ['Controller', 'Get', 'Param'];
+  const nestCommon = ['Controller', 'Get', 'Param', 'ParseUUIDPipe', 'UsePipes'];
   if (hasPost) nestCommon.push('Body', 'Post');
   nestCommon.sort();
 
   const nestendImports = ['AuthService'];
   if (listProcessor) nestendImports.push('CommonListFilterDto');
-  nestendImports.push('CommonParamsDto');
+  nestendImports.push('StrictValidationPipe');
 
   const imports = [
     namedImport(nestCommon, '@nestjs/common'),
@@ -160,7 +154,7 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
     // DocumentBuilder call only registers the scheme (under its default name,
     // 'bearer') and draws the Authorize button — without the decorator
     // swagger-ui shows no padlock and never sends the Authorization header.
-    `import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';`,
+    `import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';`,
     namedImport(nestendImports, pkg()),
     `import { ${n.serviceClass} } from '../services/${n.dot}.service';`,
   ];
@@ -180,24 +174,27 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
 
   const methods = [
     `  @Get(':id')
-  async get${n.pascal}(@Param() params: CommonParamsDto) {
+  @ApiOperation({ summary: 'One ${n.kebab} by id.' })
+  async get${n.pascal}(@Param('id', ParseUUIDPipe) id: string) {
     const { user } = ${gate('    ')};
 
-    return this.${svcProp}.get(user, params.id);
+    return this.${svcProp}.get(user, id);
   }`,
   ];
 
   if (processor) {
     methods.push(`  @Post()
+  @ApiOperation({ summary: 'Create a ${n.kebab}, or update it when an id is sent.' })
   async upsert${n.pascal}(@Body() body: ${n.dtoClass}) {
-    ${tenanted ? `await this.authService.validateAccess('add-scope', 'add-role');` : `await this.authService.validateAccess('add-scope');`}
+    const { user } = ${gate('    ')};
 
-    return this.${svcProp}.upsert(body);
+    return this.${svcProp}.upsert(user, body);
   }`);
   }
 
   if (listProcessor) {
     methods.push(`  @Post('list')
+  @ApiOperation({ summary: 'List, search and filter ${n.kebab}.' })
   async list(@Body() body: CommonListFilterDto) {
     const { user } = ${gate('    ')};
 
@@ -214,6 +211,7 @@ function controller(base, { processor = false, listProcessor = false } = {}) {
 ${gateTodo}
 @ApiTags('${n.kebab}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${n.kebab}')
 export class ${n.controllerClass} {
   constructor(
@@ -288,8 +286,8 @@ function service(base, { processor = false, listProcessor = false } = {}) {
   if (processor) {
     // Insert or update: CommonDataDto carries an optional `id`, and the data
     // processor decides which of the two the payload asks for.
-    members.push(`  async upsert(data: ${n.dtoClass}) {
-    return new ${n.processorClass}().process(data);
+    members.push(`  async upsert(user: UserEntity, data: ${n.dtoClass}) {
+    return new ${n.processorClass}(user).process(data);
   }`);
   }
 
@@ -329,12 +327,13 @@ ${members.join('\n\n')}
  */
 function bareController(base, routePath) {
   const n = names(base);
-  return `import { Controller, Get } from '@nestjs/common';
+  return `import { Controller, Get, UsePipes } from '@nestjs/common';
 import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
-import { AuthService } from '${pkg()}';
+import { AuthService, StrictValidationPipe } from '${pkg()}';
 
 @ApiTags('${routePath}')
 @ApiBearerAuth()
+@UsePipes(StrictValidationPipe)
 @Controller('api/v1/${routePath}')
 export class ${n.controllerClass} {
   constructor(private readonly authService: AuthService) {}
@@ -353,12 +352,13 @@ export class ${n.controllerClass} {
  */
 function bareExternalController(base, routePath) {
   const n = names(base);
-  return `import { Controller, Get } from '@nestjs/common';
-import { ApiSecurity, ApiTags } from '@nestjs/swagger';
-import { ApiKeyService } from '${pkg()}';
+  return `import { Controller, Get, UsePipes } from '@nestjs/common';
+import { ApiHeader, ApiTags } from '@nestjs/swagger';
+import { ApiKeyService, StrictValidationPipe } from '${pkg()}';
 
 @ApiTags('external-${routePath} (Api key)')
-@ApiSecurity('api-key')
+@ApiHeader({ name: 'x-api-key', required: true })
+@UsePipes(StrictValidationPipe)
 @Controller('api/e/v1/${routePath}')
 export class ${n.externalControllerClass} {
   constructor(private readonly apiKeyService: ApiKeyService) {}
@@ -414,13 +414,14 @@ export class ${n.dtoClass} extends CommonDataDto {
 `;
 }
 
-function processor(base, { external = false } = {}) {
+function processor(base, { external = false, withEntity = false } = {}) {
   const n = names(base);
   // An external processor sits one level deeper (external/libraries/), so its
   // reach back into the module's dtos/ gains a segment.
   const up = external ? '../..' : '..';
   const cls = external ? n.externalProcessorClass : n.processorClass;
-  return `import { CommonDataProcessor } from '${pkg()}';
+  if (external) {
+    return `import { CommonDataProcessor } from '${pkg()}';
 import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
 
 export class ${cls} extends CommonDataProcessor {
@@ -443,6 +444,80 @@ export class ${cls} extends CommonDataProcessor {
     // TODO: persist ${n.pascal} using this.payload.
   }
 }
+`;
+  }
+
+  // Edits load the caller's own row: another owner's id reads as not found.
+  const owner = current().tenantScoped
+    ? 'tenant_id: this.user.organization_id'
+    : 'created_by: this.user.id';
+  const label = toWords(base).join(' ');
+  const entityImport = withEntity
+    ? `\nimport { ${n.entityClass} } from '${up}/entities/${n.dot}.entity';`
+    : '';
+  const existingField = withEntity
+    ? `\n  private existing: ${n.entityClass} | null = null;`
+    : '';
+  const load = withEntity
+    ? `    if (this.payload.id) {
+      this.existing = await ${n.entityClass}.findOne({
+        where: { id: this.payload.id, ${owner} },
+      });
+      if (!this.existing) this.setColumnError('id', 'Invalid ${label} id');
+    }
+
+`
+    : `    // TODO: on edit (payload.id), load the row scoped to the caller
+    // ({ id, ${owner} }) and record an 'id' error when it is not found.
+
+`;
+  const set = withEntity
+    ? `  private set(): Promise<${n.entityClass}> {
+    const ${n.camel} = this.existing ?? ${n.entityClass}.create();
+    // TODO: assign fields from this.payload explicitly — never spread the DTO.
+
+    return ${n.camel}.save();
+  }`
+    : `  private set(): void {
+    // TODO: persist ${n.pascal} from this.payload, assigning fields explicitly.
+  }`;
+  return `import { CommonDataProcessor, UserEntity } from '${pkg()}';
+import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';${entityImport}
+
+export class ${cls} extends CommonDataProcessor {
+  protected payload: ${n.dtoClass};${existingField}
+
+  constructor(private readonly user: UserEntity) {
+    super();
+  }
+
+${
+    withEntity
+      ? `  async process(data: ${n.dtoClass}) {
+    this.payload = data;
+
+    await this.validate();
+
+    return this.set();
+  }
+
+  private async validate() {`
+      : `  process(data: ${n.dtoClass}) {
+    this.payload = data;
+
+    this.validate();
+
+    return this.set();
+  }
+
+  private validate(): void {`
+  }
+${load}    // TODO: collect validation errors via this.addErrors({ column: 'message' }).
+    this.raiseExceptionOnValidationFailure();
+  }
+
+${set}
+}
 `;
 }
 
@@ -543,6 +618,9 @@ export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
     datasource.subscribers.push(this);
   }
 
+  // Jobs receive only \`id\` unless the columns they need are listed here.
+  protected readonly snapshotColumns: (keyof ${n.entityClass} & string)[] = [];
+
   listenTo() {
     return ${n.entityClass};
   }