@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/backend/controller/cli/scaffold-controller/__tests__/generate.test.ts

@@ -0,0 +1,345 @@
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import type { ScaffoldControllerInput, ControllerCustomAction } from '../types.js'
+
+function fixture(overrides: Partial<ScaffoldControllerInput> = {}): ScaffoldControllerInput {
+  return {
+    name: 'Budget',
+    pluralName: 'Budgets',
+    module: 'budgets',
+    section: 'budgets',
+    appCode: 'TestV2',
+    namespace: 'TestV2',
+    navRoute: 'budgets.budgets',
+    permissionPrefix: 'budgets.budgets',
+    actions: ['read', 'create', 'update', 'delete'],
+    customActions: [],
+    fields: [
+      { name: 'code', type: 'string', required: true },
+      { name: 'label', type: 'string', required: true },
+    ],
+    projectPath: '/tmp/project',
+    ...overrides,
+  }
+}
+
+describe('scaffold-controller / generate — integration strata (Swagger + route prefix)', () => {
+  it('tags the controller with [ApiExplorerSettings(GroupName = "integration")]', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[ApiExplorerSettings\(GroupName\s*=\s*"integration"\)\]/)
+  })
+
+  it('routes the controller under api/v1/integration/{plural-kebab} (NOT /api/[controller])', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    // Wave 1 of the URL-convention alignment (2026-05-27): the explicit kebab
+    // plural replaces ASP.NET's [controller] token so the route MATCHES the
+    // frontend api-client's path one-to-one (kebab-case on both sides — was
+    // diverging on multi-word entities). buildIntegrationRoute('budgets') →
+    // '/api/v1/integration/budgets' → '[Route("api/v1/integration/budgets")]'.
+    expect(ctrl.content).toMatch(/\[Route\("api\/v1\/integration\/budgets"\)\]/)
+    // Belt-and-suspenders: the legacy [controller] token must be gone.
+    expect(ctrl.content).not.toMatch(/\[Route\("api\/\[controller\]"\)\]/)
+    expect(ctrl.content).not.toMatch(/\[controller\]/)
+  })
+
+  it('uses kebab-case plural for multi-word entities (OrderLines → order-lines)', () => {
+    // Regression guard for the historical multi-word divergence: the backend
+    // controller and the frontend api-client now both derive the URL segment
+    // via `pluralSegment` from lib/url-conventions.ts, so they always agree.
+    const files = generate(fixture({ name: 'OrderLine', pluralName: 'OrderLines' }))
+    const ctrl = files.find((f) => f.path.endsWith('OrderLinesController.cs'))!
+    expect(ctrl.content).toMatch(/\[Route\("api\/v1\/integration\/order-lines"\)\]/)
+  })
+
+  it('explains in a doc comment that the screen-driven API lives elsewhere', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/scaffold-screen-controller/)
+    expect(ctrl.content).toMatch(/machine-to-machine/)
+  })
+})
+
+describe('scaffold-controller / generate — standard CRUD', () => {
+  it('emits GET /api/budgets and GET /api/budgets/:id always', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpGet\]\s+\[RequirePermission\(BudgetsPermissions\.Budgets\.Read\)\]/)
+    expect(ctrl.content).toMatch(/\[HttpGet\("\{id:guid\}"\)\]/)
+  })
+
+  it('emits POST/PUT/DELETE conditionally on actions[]', () => {
+    const files = generate(fixture({ actions: ['read', 'create'] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\]/)
+    expect(ctrl.content).not.toMatch(/\[HttpPut\("\{id:guid\}"\)\]/)
+    expect(ctrl.content).not.toMatch(/\[HttpDelete\("\{id:guid\}"\)\]/)
+  })
+
+  it('emits the permissions class with one constant per action', () => {
+    const files = generate(fixture())
+    const perm = files.find((f) => f.path.includes('Permissions'))!
+    expect(perm.content).toMatch(/public const string Read\s*=\s*"budgets\.budgets\.read"/)
+    expect(perm.content).toMatch(/public const string Create\s*=\s*"budgets\.budgets\.create"/)
+    expect(perm.content).toMatch(/public const string Update\s*=\s*"budgets\.budgets\.update"/)
+    expect(perm.content).toMatch(/public const string Delete\s*=\s*"budgets\.budgets\.delete"/)
+  })
+})
+
+describe('scaffold-controller / generate — custom actions (per-page mode)', () => {
+  function archive(): ControllerCustomAction {
+    return {
+      code: 'archive',
+      scope: 'row',
+      payloadDto: null,
+      responseDto: 'NoContent',
+      permissionAction: 'update',
+    }
+  }
+
+  function duplicate(): ControllerCustomAction {
+    return {
+      code: 'duplicate',
+      scope: 'row',
+      payloadDto: null,
+      responseDto: 'BudgetDto',
+      permissionAction: 'create',
+    }
+  }
+
+  it('emits a row-scope custom action as POST /{id:guid}/{code}', () => {
+    const files = generate(fixture({ customActions: [archive()] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\("\{id:guid\}\/archive"\)\]/)
+    // Method binds id parameter and calls _service.ArchiveAsync(id, ct)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> Archive\(Guid id, CancellationToken/)
+    expect(ctrl.content).toMatch(/await _service\.ArchiveAsync\(id, ct\)/)
+    expect(ctrl.content).toMatch(/return NoContent\(\)/)
+  })
+
+  it('binds custom action permission to the {permissionAction} segment of the perm prefix', () => {
+    const files = generate(fixture({ customActions: [archive()] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    // archive uses permissionAction='update' → BudgetsPermissions.Budgets.Update
+    expect(ctrl.content).toMatch(/\[RequirePermission\(BudgetsPermissions\.Budgets\.Update\)\]/)
+  })
+
+  it('emits ActionResult<T> when responseDto is set (not NoContent)', () => {
+    const files = generate(fixture({ customActions: [duplicate()] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<BudgetDto>> Duplicate\(/)
+    expect(ctrl.content).toMatch(/var result = await _service\.DuplicateAsync\(id, ct\)/)
+    expect(ctrl.content).toMatch(/return Ok\(result\)/)
+  })
+
+  it('emits a bulk-scope custom action as POST /bulk/{code} (no id)', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'archive',
+        scope: 'bulk',
+        payloadDto: 'BulkArchiveRequest',
+        responseDto: 'NoContent',
+        permissionAction: 'update',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\("bulk\/archive"\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> Archive\(\[FromBody\] BulkArchiveRequest dto, CancellationToken/)
+    // No `Guid id` parameter on bulk methods
+    expect(ctrl.content).not.toMatch(/Archive\(Guid id, \[FromBody\] BulkArchiveRequest/)
+    expect(ctrl.content).toMatch(/await _service\.ArchiveAsync\(dto, ct\)/)
+  })
+
+  it('emits a header-scope custom action as POST /{code} (no id, optional payload)', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'export',
+        scope: 'header',
+        payloadDto: null,
+        responseDto: 'FileContentResult',
+        permissionAction: 'read',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\("export"\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<FileContentResult>> Export\(CancellationToken/)
+    expect(ctrl.content).toMatch(/\[RequirePermission\(BudgetsPermissions\.Budgets\.Read\)\]/)
+  })
+
+  it('pascalizes kebab-case codes for the C# method name', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'submit-for-review',
+        scope: 'row',
+        payloadDto: null,
+        responseDto: 'NoContent',
+        permissionAction: 'update',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> SubmitForReview\(Guid id, /)
+    expect(ctrl.content).toMatch(/await _service\.SubmitForReviewAsync\(id, ct\)/)
+    // URL keeps the kebab-case
+    expect(ctrl.content).toMatch(/\[HttpPost\("\{id:guid\}\/submit-for-review"\)\]/)
+  })
+
+  it('coexists peacefully with standard CRUD actions in one controller', () => {
+    const files = generate(fixture({
+      actions: ['read', 'create', 'update', 'delete'],
+      customActions: [{
+        code: 'archive',
+        scope: 'row',
+        payloadDto: null,
+        responseDto: 'NoContent',
+        permissionAction: 'update',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    // Standard CRUD methods present
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<Guid>> Create/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> Update/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> Delete/)
+    // Custom action also present
+    expect(ctrl.content).toMatch(/public async Task<ActionResult> Archive/)
+  })
+
+  it('emits NO custom action methods when customActions is empty (legacy default)', () => {
+    const files = generate(fixture({ customActions: [] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).not.toMatch(/Archive\(/)
+    expect(ctrl.content).not.toMatch(/Duplicate\(/)
+  })
+})
+
+describe('scaffold-controller / generate — custom actions httpMethod', () => {
+  it('emits [HttpGet] for a header-scope GET action with no body', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'analyze-impact',
+        scope: 'header',
+        httpMethod: 'GET',
+        payloadDto: null,
+        responseDto: 'ImpactReportDto',
+        permissionAction: 'read',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpGet\("analyze-impact"\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<ImpactReportDto>> AnalyzeImpact\(CancellationToken/)
+    // GET must NOT carry [FromBody], even if some caller pre-fills payloadDto
+    expect(ctrl.content).not.toMatch(/AnalyzeImpact\([^)]*FromBody/)
+  })
+
+  it('emits [HttpGet] for a row-scope GET action with Guid id and no body', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'impact',
+        scope: 'row',
+        httpMethod: 'GET',
+        payloadDto: null,
+        responseDto: 'ImpactReportDto',
+        permissionAction: 'read',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpGet\("\{id:guid\}\/impact"\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<ImpactReportDto>> Impact\(Guid id, CancellationToken/)
+    expect(ctrl.content).toMatch(/await _service\.ImpactAsync\(id, ct\)/)
+  })
+
+  it('emits [HttpPatch] for a row-scope PATCH action', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'rename',
+        scope: 'row',
+        httpMethod: 'PATCH',
+        payloadDto: 'RenameRequest',
+        responseDto: 'NoContent',
+        permissionAction: 'update',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPatch\("\{id:guid\}\/rename"\)\]/)
+    expect(ctrl.content).toMatch(/Rename\(Guid id, \[FromBody\] RenameRequest dto, CancellationToken/)
+  })
+
+  it('emits [HttpDelete] for a header-scope DELETE action', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'purge',
+        scope: 'header',
+        httpMethod: 'DELETE',
+        payloadDto: null,
+        responseDto: 'NoContent',
+        permissionAction: 'delete',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpDelete\("purge"\)\]/)
+    expect(ctrl.content).toMatch(/\[RequirePermission\(BudgetsPermissions\.Budgets\.Delete\)\]/)
+  })
+
+  it('preserves POST when httpMethod is omitted (legacy default)', () => {
+    const files = generate(fixture({
+      customActions: [{
+        code: 'archive',
+        scope: 'row',
+        payloadDto: null,
+        responseDto: 'NoContent',
+        permissionAction: 'update',
+      } as never], // httpMethod omitted on purpose
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\("\{id:guid\}\/archive"\)\]/)
+  })
+
+  it('emits a non-default endpoint (code != defaultEndpoint)', () => {
+    // BA code is `syncFromPce` but the legacy backend route is
+    // `sync-from-proconcept`. ba-develop passes the endpoint verbatim as
+    // `code` to scaffold-controller (the URL segment is the single source of
+    // truth). The method name is PascalCased from that — matches the service.
+    const files = generate(fixture({
+      customActions: [{
+        code: 'sync-from-proconcept',
+        scope: 'header',
+        httpMethod: 'POST',
+        payloadDto: null,
+        responseDto: 'SyncResultDto',
+        permissionAction: 'execute',
+      }],
+    }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpPost\("sync-from-proconcept"\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<SyncResultDto>> SyncFromProconcept\(CancellationToken/)
+    expect(ctrl.content).toMatch(/await _service\.SyncFromProconceptAsync\(ct\)/)
+  })
+})
+
+describe('scaffold-controller / generate — lookup endpoint (feeds <EntityLookup>)', () => {
+  it('emits GET /lookup with the Read permission and the right shape', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpGet\("lookup"\)\]/)
+    expect(ctrl.content).toMatch(/\[RequirePermission\(BudgetsPermissions\.Budgets\.Read\)\]/)
+    expect(ctrl.content).toMatch(/public async Task<ActionResult<PaginatedResult<BudgetRefDto>>> GetLookup/)
+    expect(ctrl.content).toMatch(/await _service\.GetLookupAsync\(new GetBudgetsLookupQuery\(search, page, pageSize\), ct\)/)
+  })
+
+  it('always emits the lookup endpoint, even when create/update/delete are disabled', () => {
+    const files = generate(fixture({ actions: ['read'] }))
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    expect(ctrl.content).toMatch(/\[HttpGet\("lookup"\)\]/)
+    expect(ctrl.content).not.toMatch(/\[HttpPost\]/)
+  })
+
+  it('places the lookup endpoint before the Create POST in the file (ASP.NET route ordering)', () => {
+    const files = generate(fixture())
+    const ctrl = files.find((f) => f.path.endsWith('BudgetsController.cs'))!
+    const lookupIdx = ctrl.content.indexOf('[HttpGet("lookup")]')
+    const createIdx = ctrl.content.indexOf('[HttpPost]')
+    expect(lookupIdx).toBeGreaterThan(0)
+    expect(createIdx).toBeGreaterThan(0)
+    expect(lookupIdx).toBeLessThan(createIdx)
+  })
+})

package/templates/skills/development/backend/controller/cli/scaffold-controller/generate.ts

@@ -0,0 +1,280 @@
+/**
+ * cli:scaffold-controller — generate.ts
+ * Generates API controller + module-scoped permissions class.
+ * Generated code consumes NuGet packages (SmartStack.Core, SmartStack.Application, SmartStack.Api).
+ *
+ * Per-page mode (post-Step 3 of the vertical-slice refactor):
+ *  When `spec.customActions[]` is non-empty, each entry produces ONE extra
+ *  controller method beyond the standard CRUD. Codes outside the canonical
+ *  REST set (create/update/delete) are emitted as POST routes following the
+ *  convention:
+ *    - row scope    → POST /api/{plural}/{id:guid}/{code}
+ *    - bulk scope   → POST /api/{plural}/bulk/{code}
+ *    - header scope → POST /api/{plural}/{code}
+ *  The bound service method is `_service.{Code}Async(...)` (canonical
+ *  cross-layer naming — same as the React hook + frontend service stub).
+ */
+import { buildIntegrationRoute, pluralSegment } from '../../../../../lib/url-conventions.js'
+import type {
+  ScaffoldControllerInput,
+  GeneratedFile,
+  ControllerField,
+  ControllerCustomAction,
+} from './types.js'
+
+export function generate(spec: ScaffoldControllerInput): GeneratedFile[] {
+  const ns = spec.namespace ?? spec.appCode
+  const mod = capitalize(spec.module)
+  const e = spec.name
+  const plural = spec.pluralName ?? e + 's'
+  // Kebab-case plural — single source of truth shared with the frontend
+  // api-client and with scaffold-screen-controller. Eliminates the historical
+  // camelCase/kebab divergence on multi-word entities (OrderLines vs order-lines).
+  const pluralKebab = pluralSegment(plural)
+  // ASP.NET Core expects route attributes WITHOUT a leading slash.
+  const integrationRouteAttr = buildIntegrationRoute(pluralKebab).replace(/^\//, '')
+  const section = capitalize(spec.section)
+  const permPrefix = spec.permissionPrefix ?? `${spec.module}.${spec.section}`
+  const userFields = spec.fields.filter(f => !isSystemField(f.name))
+  const createMapping = mapDtoToCommand(userFields, 'dto')
+  const updateMapping = mapDtoToCommand(userFields, 'dto', 'id')
+
+  const files: GeneratedFile[] = []
+
+  const customActionMethods = spec.customActions
+    .map(a => emitCustomActionMethod(a, mod, section, e))
+    .join('\n')
+
+  const controllerContent = `using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using SmartStack.Core.Navigation;
+using SmartStack.Api.Authorization;
+using ${ns}.Application.${mod}.DTOs;
+using ${ns}.Application.${mod}.Interfaces;
+using ${ns}.Application.${mod}.Commands;
+using ${ns}.Application.${mod}.Queries;
+using ${ns}.Api.Permissions.${mod};
+
+namespace ${ns}.Api.Controllers.${mod};
+
+/// <summary>
+/// Integration controller — exposes generic CRUD over the entity for
+/// machine-to-machine consumers (imports/exports, ETL, BI, third-party
+/// integrations, dev tooling). The screen-driven API lives under
+/// <c>/api/screens/...</c> and is generated by <c>scaffold-screen-controller</c>.
+/// Both strata call the SAME business layer — business rules never duplicate.
+/// </summary>
+[ApiController]
+[ApiExplorerSettings(GroupName = "integration")]
+[Route("${integrationRouteAttr}")]
+[NavRoute("${spec.navRoute}")]
+[Authorize]
+[Produces("application/json")]
+public class ${plural}Controller : ControllerBase
+{
+    private readonly I${e}Service _service;
+
+    public ${plural}Controller(I${e}Service service) => _service = service;
+
+    [HttpGet]
+    [RequirePermission(${mod}Permissions.${section}.Read)]
+    public async Task<ActionResult<PaginatedResult<${e}ListDto>>> GetAll(
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20,
+        [FromQuery] string? search = null,
+        CancellationToken ct = default)
+    {
+        var result = await _service.GetAllAsync(new Get${plural}Query(page, pageSize, search), ct);
+        return Ok(result);
+    }
+
+    [HttpGet("{id:guid}")]
+    [RequirePermission(${mod}Permissions.${section}.Read)]
+    public async Task<ActionResult<${e}DetailDto>> GetById(Guid id, CancellationToken ct = default)
+    {
+        var result = await _service.GetByIdAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    /// <summary>
+    /// Lookup endpoint feeding the frontend EntityLookup combobox. Returns
+    /// paginated {Id, DisplayName} pairs. Reuses the Read permission — anyone
+    /// allowed to list the entity is allowed to search it.
+    /// </summary>
+    [HttpGet("lookup")]
+    [RequirePermission(${mod}Permissions.${section}.Read)]
+    public async Task<ActionResult<PaginatedResult<${e}RefDto>>> GetLookup(
+        [FromQuery] string? search = null,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20,
+        CancellationToken ct = default)
+    {
+        var result = await _service.GetLookupAsync(new Get${plural}LookupQuery(search, page, pageSize), ct);
+        return Ok(result);
+    }
+${spec.actions.includes('create') ? `
+    [HttpPost]
+    [RequirePermission(${mod}Permissions.${section}.Create)]
+    public async Task<ActionResult<Guid>> Create([FromBody] Create${e}Dto dto, CancellationToken ct = default)
+    {
+        var command = new Create${e}Command(${createMapping});
+        var id = await _service.CreateAsync(command, ct);
+        return CreatedAtAction(nameof(GetById), new { id }, id);
+    }
+` : ''}${spec.actions.includes('update') ? `
+    [HttpPut("{id:guid}")]
+    [RequirePermission(${mod}Permissions.${section}.Update)]
+    public async Task<ActionResult> Update(Guid id, [FromBody] Update${e}Dto dto, CancellationToken ct = default)
+    {
+        var command = new Update${e}Command(${updateMapping});
+        await _service.UpdateAsync(command, ct);
+        return NoContent();
+    }
+` : ''}${spec.actions.includes('delete') ? `
+    [HttpDelete("{id:guid}")]
+    [RequirePermission(${mod}Permissions.${section}.Delete)]
+    public async Task<ActionResult> Delete(Guid id, CancellationToken ct = default)
+    {
+        await _service.DeleteAsync(id, ct);
+        return NoContent();
+    }
+` : ''}${customActionMethods}
+}
+`
+  files.push({ path: `src/${ns}.Api/Controllers/${mod}/${plural}Controller.cs`, content: controllerContent })
+
+  // Module-scoped namespace to avoid collisions across modules sharing section names.
+  // Custom actions reuse the canonical permPrefix.{permissionAction} key — no
+  // separate constant emitted because the action runs under an existing perm
+  // (typically Update). This mirrors how DB seeds register them.
+  const permContent = `namespace ${ns}.Api.Permissions.${mod};
+
+public static class ${mod}Permissions
+{
+    public static class ${section}
+    {
+        public const string Access = "${permPrefix}.access";
+${spec.actions.map(a => `        public const string ${capitalize(a)} = "${permPrefix}.${a}";`).join('\n')}
+    }
+}
+`
+  files.push({ path: `src/${ns}.Api/Permissions/${mod}/${mod}Permissions.${section}.cs`, content: permContent })
+
+  return files
+}
+
+// ─── Helpers ───
+
+function capitalize(s: string): string { return s.charAt(0).toUpperCase() + s.slice(1) }
+
+/** Convert a kebab-case action code (`bulk-archive`) to PascalCase
+ *  (`BulkArchive`) for C# method names. */
+function pascalizeCode(code: string): string {
+  return code
+    .split('-')
+    .map(part => capitalize(part))
+    .join('')
+}
+
+function isSystemField(name: string): boolean {
+  const systemFields = ['id', 'createdat', 'updatedat', 'deletedat', 'createdby', 'updatedby', 'tenantid']
+  return systemFields.includes(name.toLowerCase())
+}
+
+function mapDtoToCommand(fields: ControllerField[], dtoVar: string, prependId?: string): string {
+  const fieldArgs = fields.map(f => `${dtoVar}.${capitalize(f.name)}`)
+  if (prependId) {
+    return [prependId, ...fieldArgs].join(', ')
+  }
+  return fieldArgs.join(', ')
+}
+
+/**
+ * Map an HTTP verb to its `[HttpXxx]` route attribute.
+ *   POST   → [HttpPost(...)]
+ *   GET    → [HttpGet(...)]
+ *   PUT    → [HttpPut(...)]
+ *   PATCH  → [HttpPatch(...)]
+ *   DELETE → [HttpDelete(...)]
+ */
+function httpAttr(verb: string, route: string): string {
+  const pascal = verb.charAt(0).toUpperCase() + verb.slice(1).toLowerCase()
+  return `[Http${pascal}("${route}")]`
+}
+
+/**
+ * Emits a single custom-action controller method. Maps:
+ *   - row scope    → {VERB} {id:guid}/{code} with `Guid id` parameter
+ *   - bulk scope   → {VERB} bulk/{code}
+ *   - header scope → {VERB} {code} with no id
+ *
+ * The VERB defaults to POST but may be GET (compute / read-only endpoints
+ * like `analyze-impact`), PUT/PATCH (rare — partial updates) or DELETE.
+ * `[FromBody]` is OMITTED when the verb is GET, even if `payloadDto` is set
+ * (ASP.NET Core does not allow bodies on GET methods).
+ *
+ * The service call uses the canonical `_service.{Pascal}Async(...)` shape so
+ * scaffold-business (Step 4) can emit a matching method and the two layers
+ * line up by construction.
+ *
+ * Permission constant: `{Mod}Permissions.{Section}.{PermissionAction}` —
+ * defaults to the existing Update / Create / Delete perm for state mutations.
+ */
+function emitCustomActionMethod(
+  action: ControllerCustomAction,
+  mod: string,
+  section: string,
+  entity: string,
+): string {
+  const methodName = pascalizeCode(action.code)
+  const permConst = `${mod}Permissions.${section}.${capitalize(action.permissionAction)}`
+  const responseType = action.responseDto === 'NoContent'
+    ? 'ActionResult'
+    : `ActionResult<${action.responseDto}>`
+
+  // Defensive fallback — Zod's `.default('POST')` only fires on `.parse()`.
+  // Tests and legacy callers may instantiate the object literally; we keep
+  // POST as the implicit default to preserve the pre-httpMethod behaviour.
+  const verb = action.httpMethod ?? 'POST'
+  const allowBody = verb !== 'GET' && Boolean(action.payloadDto)
+
+  const params: string[] = []
+  let routeAttr: string
+  let serviceArgs: string
+
+  if (action.scope === 'row') {
+    routeAttr = httpAttr(verb, `{id:guid}/${action.code}`)
+    params.push('Guid id')
+    if (allowBody) params.push(`[FromBody] ${action.payloadDto} dto`)
+    serviceArgs = allowBody ? 'id, dto, ct' : 'id, ct'
+  } else if (action.scope === 'bulk') {
+    routeAttr = httpAttr(verb, `bulk/${action.code}`)
+    if (allowBody) params.push(`[FromBody] ${action.payloadDto} dto`)
+    serviceArgs = allowBody ? 'dto, ct' : 'ct'
+  } else {
+    // header scope
+    routeAttr = httpAttr(verb, action.code)
+    if (allowBody) params.push(`[FromBody] ${action.payloadDto} dto`)
+    serviceArgs = allowBody ? 'dto, ct' : 'ct'
+  }
+  params.push('CancellationToken ct = default')
+
+  // Body — call the service then return Ok(result) for typed responses,
+  // NoContent() for void endpoints.
+  const body = action.responseDto === 'NoContent'
+    ? `        await _service.${methodName}Async(${serviceArgs});
+        return NoContent();`
+    : `        var result = await _service.${methodName}Async(${serviceArgs});
+        return Ok(result);`
+
+  // Note: comment hints scaffold-business will produce the matching service
+  // method. The two layers stay in lockstep via the action.code single-source-of-truth.
+  return `
+    ${routeAttr}
+    [RequirePermission(${permConst})]
+    public async Task<${responseType}> ${methodName}(${params.join(', ')})
+    {
+${body}
+    }
+`
+}

package/templates/skills/development/backend/controller/cli/scaffold-controller/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-controller
+ * Responsabilité : Generate API controller + permissions class
+ */
+import { parseArgs } from 'node:util'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve, join } from 'node:path'
+import { validate } from './validate.js'
+import { generate } from './generate.js'
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js'
+
+const COMMAND = 'scaffold-controller'
+
+function main(): void {
+  const { values } = parseArgs({ options: { spec: { type: 'string' }, outdir: { type: 'string' }, dry_run: { type: 'boolean', default: false } }, strict: true })
+  if (!values.spec) { printEnvelope(failGenerate(COMMAND, ['--spec is required'])); process.exit(1) }
+
+  let raw: unknown
+  try { raw = JSON.parse(values.spec) } catch { printEnvelope(failGenerate(COMMAND, ['Invalid JSON'])); process.exit(1) }
+
+  const validation = validate(raw)
+  if (!validation.valid) { printEnvelope(failGenerate(COMMAND, validation.errors)); process.exit(1) }
+
+  const spec = raw as any
+  const files = generate(spec)
+
+  if (values.dry_run) {
+    printEnvelope(generateEnvelope(COMMAND, { data: { dryRun: true, files: files.map(f => f.path) } }))
+    process.exit(0)
+  }
+
+  const outdir = values.outdir ?? spec.projectPath
+  const written: string[] = []
+  for (const file of files) {
+    const fullPath = resolve(join(outdir, file.path))
+    mkdirSync(dirname(fullPath), { recursive: true })
+    writeFileSync(fullPath, file.content, 'utf-8')
+    written.push(fullPath)
+  }
+
+  printEnvelope(generateEnvelope(COMMAND, {
+    data: { entity: spec.name, navRoute: spec.navRoute, fileCount: written.length },
+    filesCreated: written,
+    nextSteps: ['Verify SS001-SS007 conventions', 'Run dotnet build'],
+  }))
+}
+
+main()