@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/backend/screen-controller/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: backend-screen-controller
+description: >
+  Generates the **screen-driven** API stratum: one controller per section
+  exposing one endpoint per screen, payload shaped from the pagespec. Routes
+  under /api/screens/{plural}/{action} with Swagger group "screens".
+  Companion of `scaffold-controller` (integration stratum). Both call the SAME
+  Business layer — rules never duplicate.
+phase: development/backend
+cli: cli/scaffold-screen-controller
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Screen Controller — API Layer (screen-driven stratum)
+
+Generates one **screen-driven controller per section**. Each pagespec
+(`pagespecs/<Entity>.<view>.md`) in the section produces one endpoint with a
+payload **shaped from the pagespec columns/fields** — not the full entity. This
+is the contract the generated React app consumes.
+
+> **Two strata, one Business layer.** See `backend-controller/SKILL.md` for the
+> integration stratum. Both call the same `I{Entity}Service` — never duplicate
+> business rules between them.
+
+## When to Use
+
+- Phase 2b (API screen-driven) of `/ba-develop` — fans out one agent per section
+- After Phase 2a (integration controller) — the screen controller calls the
+  same Business methods + emits its own DTOs
+
+## What it emits
+
+For section `{Section}` with N pagespecs:
+
+```
+src/{Ns}.Api/Controllers/{Module}/Screens/{Section}ScreenController.cs
+src/{Ns}.Application/{Module}/DTOs/Screens/{Entity}{View}ScreenDto.cs   × N (one per read screen)
+```
+
+## Controller pattern (output)
+
+```csharp
+[ApiController]
+[ApiExplorerSettings(GroupName = "screens")]
+[Route("api/screens/opportunities")]
+[Authorize]
+[Produces("application/json")]
+public class OpportunitiesScreenController : ControllerBase
+{
+    private readonly IOpportunityService _service;
+    public OpportunitiesScreenController(IOpportunityService service) => _service = service;
+
+    /// <summary>List screen — SCR-CRM-PIPELINE-OPPORTUNITES-001 (Opportunity list).</summary>
+    [HttpGet("list")]
+    [RequirePermission(PipelinePermissions.Opportunites.Read)]
+    public async Task<ActionResult<PaginatedResult<OpportunityListScreenDto>>> GetList(
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20,
+        [FromQuery] string? search = null,
+        CancellationToken ct = default)
+    {
+        var result = await _service.GetForListScreenAsync(new GetOpportunitiesListScreenQuery(page, pageSize, search), ct);
+        return Ok(result);
+    }
+
+    /// <summary>Detail screen — SCR-CRM-PIPELINE-OPPORTUNITES-002.</summary>
+    [HttpGet("detail/{id:guid}")]
+    [RequirePermission(PipelinePermissions.Opportunites.Read)]
+    public async Task<ActionResult<OpportunityDetailScreenDto>> GetDetail(Guid id, CancellationToken ct = default)
+    {
+        var result = await _service.GetForDetailScreenAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    /// <summary>Custom action — archive (row scope, from pagespec).</summary>
+    [HttpPost("detail/{id:guid}/archive")]
+    [RequirePermission(PipelinePermissions.Opportunites.Update)]
+    public async Task<ActionResult> Archive(Guid id, CancellationToken ct = default)
+    {
+        await _service.ArchiveAsync(id, ct);
+        return NoContent();
+    }
+}
+```
+
+## Route convention
+
+| pagespec.view | HTTP | Route | Suffix |
+|---------------|------|-------|--------|
+| `list` | GET | `/api/screens/{plural}/list` | — |
+| `detail` | GET | `/api/screens/{plural}/detail/{id:guid}` | — |
+| `form` (create) | POST | `/api/screens/{plural}/form` | — |
+| `form` (update) | PUT | `/api/screens/{plural}/form/{id:guid}` | — |
+| `dashboard` (consolidated) | GET | `/api/screens/{plural}/dashboard/consolidated` | Wave F3 |
+| `dashboard` (alerts) | GET | `/api/screens/{plural}/dashboard/alerts` | Wave F3 |
+| header action | `{httpMethod}` | `/api/screens/{plural}/{endpoint}` | from pagespec.endpoint |
+| row action | `{httpMethod}` | `/api/screens/{plural}/detail/{id:guid}/{endpoint}` | from pagespec.endpoint |
+| bulk action | `{httpMethod}` | `/api/screens/{plural}/bulk/{endpoint}` | from pagespec.endpoint |
+
+> **Dashboard view (Wave F3)**. When the section has a pagespec with
+> `view: "dashboard"`, the controller emits two endpoints that reuse the
+> integration-stratum service methods `GetDashboardConsolidatedAsync` +
+> `GetDashboardAlertsAsync` (scaffolded by `scaffold-business` when the entity
+> declares `hasDashboard: true`). The DTOs `${E}DashboardConsolidatedDto` +
+> `${E}DashboardAlertDto` live in the integration namespace —
+> `scaffold-screen-controller` does NOT re-emit them. Frontend consumes via
+> the existing `useDashboard${E}` hook from `scaffold-api-client`.
+
+> **Still unsupported (TODO)**. Views `kanban`, `card`, `app-home`,
+> `module-home`, `section-home` push a `[SCREEN-…]` marker to `todos[]`
+> instead of an endpoint — they require different aggregation primitives
+> than the four supported views and are queued for a future wave. The
+> controller is still emitted (with the other views' methods) so the build
+> doesn't break.
+
+> The `{plural}` segment is the **lowercase plural of the entity**, mirrored from
+> the integration controller's `[controller]` token. Sections sharing entity
+> plurals must be disambiguated upstream in the BA (section codes).
+
+## DTO contract
+
+For each `list` / `detail` pagespec, the scaffolder emits one DTO whose fields
+are taken **only** from the pagespec's `columns[]` (list) or fields exposed in
+the screen (detail). Computed columns become read-only `init` properties.
+
+The Business layer method signature stays canonical:
+
+| Endpoint | Service method |
+|----------|----------------|
+| `GET /list` | `_service.GetForListScreenAsync(GetXxxListScreenQuery q, ct)` |
+| `GET /detail/{id}` | `_service.GetForDetailScreenAsync(Guid id, ct)` |
+| `POST /form` | `_service.CreateAsync(...)` (reused from Phase 2a — never duplicate) |
+| `PUT /form/{id}` | `_service.UpdateAsync(...)` (reused from Phase 2a) |
+| custom action `{code}` | `_service.{Pascal(code)}Async(...)` (reused) |
+
+## ⚠ BLOCKING — Convention rules
+
+- **SCRN001**: `[ApiExplorerSettings(GroupName = "screens")]` on the class.
+- **SCRN002**: `[Route("api/screens/{plural}")]` — never `/api/...` or
+  `/api/v1/integration/...`.
+- **SCRN003**: One method per pagespec in the section. The doc comment carries
+  the `SCR-…` code verbatim.
+- **SCRN004**: `[RequirePermission(...)]` on every method — taken from
+  `pagespec.permission` (or `pagespec.action.permission` for custom actions).
+- **SCRN005**: The Business method called MUST exist. If the scaffolder finds
+  no matching method in the service interface, it emits a
+  `// TODO[SCREEN-{code}]:` marker — Phase 2b's audit blocks merge until filled.
+- **SCRN006**: Never emit business rules in the controller — call the service.
+- **SCRN007**: Read endpoints return `{Entity}{View}ScreenDto` — never the
+  domain entity, never `EntityListDto` from integration. The screen-driven
+  shape is allowed to drift from integration intentionally.
+
+## Invocation
+
+```bash
+npx tsx skills/development/backend/screen-controller/cli/scaffold-screen-controller/index.ts \
+  --spec '{
+    "section": "opportunites",
+    "sectionPlural": "opportunities",
+    "module": "pipeline",
+    "appCode": "crm",
+    "namespace": "Crm",
+    "moduleDir": ".smartstack/ba/CRM/PIPELINE",
+    "projectPath": "/path/to/project"
+  }'
+```
+
+The CLI reads `moduleDir/pagespecs/*.md` for the section (matching
+`pagespec.section === spec.section`) and emits all the files in one shot.

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

@@ -0,0 +1,329 @@
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import type { PageSpec, ScaffoldScreenControllerSpec } from '../types.js'
+
+function spec(overrides: Partial<ScaffoldScreenControllerSpec> = {}): ScaffoldScreenControllerSpec {
+  return {
+    section: 'opportunites',
+    entity: 'Opportunity',
+    module: 'pipeline',
+    appCode: 'crm',
+    namespace: 'Crm',
+    moduleDir: '/ba/CRM/PIPELINE',
+    projectPath: '/project',
+    ...overrides,
+  }
+}
+
+function pagespec(overrides: Partial<PageSpec> = {}): PageSpec {
+  return {
+    screenCode: 'SCR-CRM-PIPELINE-OPPORTUNITES-001',
+    appCode: 'crm',
+    module: 'pipeline',
+    section: 'opportunites',
+    entity: 'Opportunity',
+    view: 'list',
+    permission: 'pipeline.opportunites.read',
+    linkedUseCases: [],
+    linkedBusinessRules: [],
+    columns: [],
+    actions: [],
+    ...overrides,
+  } as PageSpec
+}
+
+function controllerOf(files: { path: string; content: string }[]): { path: string; content: string } | undefined {
+  return files.find(f => f.path.endsWith('ScreenController.cs'))
+}
+
+describe('scaffold-screen-controller / generate — controller-level attributes', () => {
+  it('emits a controller named {EntityPlural}ScreenController under Controllers/{Mod}/Screens/', () => {
+    const { files } = generate(spec(), [pagespec()])
+    const ctrl = controllerOf(files)
+    expect(ctrl?.path).toBe('src/Crm.Api/Controllers/Pipeline/Screens/OpportunitiesScreenController.cs')
+  })
+
+  it('tags the class with [ApiExplorerSettings(GroupName = "screens")]', () => {
+    const { files } = generate(spec(), [pagespec()])
+    expect(controllerOf(files)?.content).toMatch(/\[ApiExplorerSettings\(GroupName\s*=\s*"screens"\)\]/)
+  })
+
+  it('routes the controller under api/screens/{entityPluralLower}', () => {
+    const { files } = generate(spec(), [pagespec()])
+    expect(controllerOf(files)?.content).toMatch(/\[Route\("api\/screens\/opportunities"\)\]/)
+  })
+
+  it('injects I{Entity}Service as the only dependency', () => {
+    const { files } = generate(spec(), [pagespec()])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/private readonly IOpportunityService _service;/)
+    expect(c).toMatch(/public OpportunitiesScreenController\(IOpportunityService service\)/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — list view', () => {
+  it('emits [HttpGet("list")] with paginated dto + read permission', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'list' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpGet\("list"\)\]/)
+    expect(c).toMatch(/ActionResult<PaginatedResult<OpportunityListScreenDto>>/)
+    expect(c).toMatch(/\[RequirePermission\(PipelinePermissions\.Opportunites\.Read\)\]/)
+    expect(c).toMatch(/_service\.GetForListScreenAsync\(new GetOpportunityListScreenQuery\(page, pageSize, search\), ct\)/)
+  })
+
+  it('emits a {Entity}ListScreenDto record under DTOs/Screens/', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      columns: [
+        { key: 'amount', formatHint: 'currency' },
+        { key: 'name', formatHint: 'string' },
+      ],
+    })])
+    const dto = files.find(f => f.path.endsWith('OpportunityListScreenDto.cs'))!
+    expect(dto.path).toBe('src/Crm.Application/Pipeline/DTOs/Screens/OpportunityListScreenDto.cs')
+    expect(dto.content).toMatch(/public record OpportunityListScreenDto/)
+    expect(dto.content).toMatch(/public decimal Amount \{ get; init; \} = 0;/)
+    expect(dto.content).toMatch(/public string Name \{ get; init; \} = "";/)
+  })
+
+  it('handles list with no columns (safe minimum dto)', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'list', columns: [] })])
+    const dto = files.find(f => f.path.endsWith('OpportunityListScreenDto.cs'))!
+    expect(dto.content).toMatch(/public Guid Id \{ get; init; \}/)
+    expect(dto.content).toMatch(/No columns in pagespec/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — detail view', () => {
+  it('emits [HttpGet("detail/{id:guid}")] with NotFound branch', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'detail' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpGet\("detail\/\{id:guid\}"\)\]/)
+    expect(c).toMatch(/ActionResult<OpportunityDetailScreenDto>/)
+    expect(c).toMatch(/result is null \? NotFound\(\) : Ok\(result\)/)
+    expect(c).toMatch(/_service\.GetForDetailScreenAsync\(id, ct\)/)
+  })
+
+  it('emits a {Entity}DetailScreenDto record', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'detail', columns: [{ key: 'stage' }] })])
+    const dto = files.find(f => f.path.endsWith('OpportunityDetailScreenDto.cs'))!
+    expect(dto.content).toMatch(/public record OpportunityDetailScreenDto/)
+    expect(dto.content).toMatch(/public string Stage \{ get; init; \}/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — form view', () => {
+  it('emits POST /form and PUT /form/{id:guid}', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'form', permission: 'pipeline.opportunites.update' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpPost\("form"\)\]/)
+    expect(c).toMatch(/\[HttpPut\("form\/\{id:guid\}"\)\]/)
+    expect(c).toMatch(/CreateOpportunityDto dto/)
+    expect(c).toMatch(/UpdateOpportunityDto dto/)
+    expect(c).toMatch(/_service\.CreateAsync/)
+    expect(c).toMatch(/_service\.UpdateAsync/)
+  })
+
+  it('emits NO DTO for form (consumes integration Create/UpdateDto)', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'form' })])
+    const dto = files.find(f => f.path.includes('FormScreenDto'))
+    expect(dto).toBeUndefined()
+  })
+
+  it('emits CreatedAtAction pointing to GetDetail', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'form' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/CreatedAtAction\(nameof\(GetDetailRoute\)/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — custom actions on a list view', () => {
+  it('emits a row-scope POST action under detail/{id:guid}/{endpoint}', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      actions: [{
+        code: 'archive',
+        scope: 'row',
+        kind: 'api',
+        httpMethod: 'POST',
+        permission: 'pipeline.opportunites.update',
+      }],
+    })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpPost\("detail\/\{id:guid\}\/archive"\)\]/)
+    expect(c).toMatch(/public async Task<ActionResult> Archive\(Guid id, CancellationToken/)
+    expect(c).toMatch(/_service\.ArchiveAsync\(id, ct\)/)
+    expect(c).toMatch(/\[RequirePermission\(PipelinePermissions\.Opportunites\.Update\)\]/)
+  })
+
+  it('emits a bulk-scope action under bulk/{endpoint}', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      actions: [{
+        code: 'bulk-archive',
+        scope: 'bulk',
+        kind: 'api',
+        httpMethod: 'POST',
+        payloadDto: 'BulkArchiveRequest',
+        permission: 'pipeline.opportunites.update',
+      }],
+    })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpPost\("bulk\/bulk-archive"\)\]/)
+    expect(c).toMatch(/\[FromBody\] BulkArchiveRequest dto/)
+  })
+
+  it('emits a header-scope action under {endpoint} (no id)', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      actions: [{
+        code: 'syncFromPce',
+        scope: 'header',
+        kind: 'api',
+        endpoint: 'sync-from-proconcept',
+        httpMethod: 'POST',
+        permission: 'pipeline.opportunites.execute',
+      }],
+    })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpPost\("sync-from-proconcept"\)\]/)
+    expect(c).toMatch(/_service\.SyncFromPceAsync\(ct\)/)
+  })
+
+  it('omits [FromBody] on GET actions even when payloadDto is set', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      actions: [{
+        code: 'export',
+        scope: 'header',
+        kind: 'api',
+        httpMethod: 'GET',
+        payloadDto: 'ExportRequest',
+        responseDto: 'FileContentResult',
+        permission: 'pipeline.opportunites.read',
+      }],
+    })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpGet\("export"\)\]/)
+    expect(c).not.toMatch(/Export\([^)]*FromBody/)
+  })
+
+  it('skips navigation actions (kind="navigate") — those are pure frontend', () => {
+    const { files } = generate(spec(), [pagespec({
+      view: 'list',
+      actions: [{ code: 'open', kind: 'navigate', scope: 'row', targetScreen: 'SCR-X-001' }],
+    })])
+    const c = controllerOf(files)!.content
+    // Backend should NOT emit a method for a navigate action.
+    expect(c).not.toMatch(/public async Task<ActionResult> Open\(/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — unsupported views fall back gracefully', () => {
+  // Wave 1 of the URL-convention alignment (2026-05-27) reshaped this:
+  //   - dashboard       → fully supported (Wave F3)
+  //   - kanban / card   → MVP fallback: reuse the list endpoint + DTO so the
+  //                        frontend's getAll() call lands on a real route.
+  //                        A TODO marker still surfaces for the dedicated
+  //                        emitter that's still to be built.
+  //   - app/module/section-home → hub views; frontend emits NO API call, so
+  //                        backend emits NO endpoint and NO TODO. Absence is
+  //                        by design — see hub-views.test.ts for the lock.
+  it('reuses the list endpoint for kanban + surfaces a single TODO for the dedicated emitter', () => {
+    const { todos, files } = generate(spec(), [pagespec({ view: 'kanban' })])
+    expect(todos.length).toBe(1)
+    expect(todos[0]).toMatch(/view "kanban" reuses GET \/list as MVP fallback/)
+    const ctrl = controllerOf(files)!
+    // The kanban pagespec produces a real [HttpGet("list")] route so the
+    // frontend's GET ${API_PATH}/list call never 404s.
+    expect(ctrl.content).toMatch(/\[HttpGet\("list"\)\]/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — multiple pagespecs in one controller', () => {
+  it('emits all three views (list + detail + form) in one controller class', () => {
+    const { files } = generate(spec(), [
+      pagespec({ view: 'list', screenCode: 'SCR-A-001' }),
+      pagespec({ view: 'detail', screenCode: 'SCR-A-002' }),
+      pagespec({ view: 'form', screenCode: 'SCR-A-003', permission: 'pipeline.opportunites.update' }),
+    ])
+    const ctrls = files.filter(f => f.path.endsWith('ScreenController.cs'))
+    expect(ctrls.length).toBe(1) // ONE controller, not three
+    const c = ctrls[0].content
+    expect(c).toMatch(/HttpGet\("list"\)/)
+    expect(c).toMatch(/HttpGet\("detail\/\{id:guid\}"\)/)
+    expect(c).toMatch(/HttpPost\("form"\)/)
+    expect(c).toMatch(/SCR-A-001/)
+    expect(c).toMatch(/SCR-A-002/)
+    expect(c).toMatch(/SCR-A-003/)
+  })
+})
+
+describe('scaffold-screen-controller / generate — Wave F3 (dashboard view)', () => {
+  it('emits /dashboard/consolidated + /dashboard/alerts endpoints for view=dashboard', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'dashboard', screenCode: 'SCR-PIPE-DASH-001' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[HttpGet\("dashboard\/consolidated"\)\]/)
+    expect(c).toMatch(/\[HttpGet\("dashboard\/alerts"\)\]/)
+  })
+
+  it('returns the integration-stratum DashboardConsolidatedDto + DashboardAlertDto (no new DTO emitted)', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'dashboard' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/ActionResult<OpportunityDashboardConsolidatedDto>/)
+    expect(c).toMatch(/ActionResult<IReadOnlyList<OpportunityDashboardAlertDto>>/)
+    // Dashboard reuses the integration DTOs; no DTOs/Screens/* file emitted.
+    const dashDto = files.find(f => /DashboardConsolidatedDto\.cs$/.test(f.path) || /DashboardAlertDto\.cs$/.test(f.path))
+    expect(dashDto).toBeUndefined()
+  })
+
+  it('forwards startDate + endDate query params and calls _service.GetDashboardConsolidatedAsync', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'dashboard' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[FromQuery\] DateTime\? startDate = null/)
+    expect(c).toMatch(/\[FromQuery\] DateTime\? endDate = null/)
+    expect(c).toMatch(/_service\.GetDashboardConsolidatedAsync\(startDate, endDate, ct\)/)
+    expect(c).toMatch(/_service\.GetDashboardAlertsAsync\(ct\)/)
+  })
+
+  it('applies [RequirePermission] derived from the pagespec', () => {
+    const { files } = generate(spec(), [pagespec({ view: 'dashboard', permission: 'pipeline.opportunites.read' })])
+    const c = controllerOf(files)!.content
+    expect(c).toMatch(/\[RequirePermission\(PipelinePermissions\.Opportunites\.Read\)\]/)
+  })
+
+  it('does NOT push a TODO for view=dashboard (no longer unsupported)', () => {
+    const { todos } = generate(spec(), [pagespec({ view: 'dashboard' })])
+    expect(todos.find(t => /view "dashboard"/.test(t))).toBeUndefined()
+  })
+
+  it('TODO behaviour after Wave 1 URL alignment — kanban surfaces a TODO; hub views (app-home) do NOT', () => {
+    // kanban falls back to [HttpGet("list")] but pushes a TODO so the
+    // dedicated emitter remains on the audit radar. app-home / module-home /
+    // section-home are pure Slot containers on the frontend — no API call,
+    // no endpoint, no TODO (absence is by design, locked by hub-views.test.ts).
+    const { todos } = generate(spec(), [
+      pagespec({ view: 'kanban', screenCode: 'SCR-K-1' }),
+      pagespec({ view: 'app-home', screenCode: 'SCR-H-1' }),
+    ])
+    expect(todos.some(t => /view "kanban"/.test(t))).toBe(true)
+    expect(todos.some(t => /view "app-home"/.test(t))).toBe(false)
+  })
+
+  it('dashboard endpoints sit alongside list/detail/form in the same controller', () => {
+    const { files } = generate(spec(), [
+      pagespec({ view: 'list', screenCode: 'SCR-L' }),
+      pagespec({ view: 'detail', screenCode: 'SCR-D' }),
+      pagespec({ view: 'form', screenCode: 'SCR-F', permission: 'pipeline.opportunites.update' }),
+      pagespec({ view: 'dashboard', screenCode: 'SCR-DASH' }),
+    ])
+    const ctrls = files.filter(f => f.path.endsWith('ScreenController.cs'))
+    expect(ctrls.length).toBe(1)
+    const c = ctrls[0].content
+    expect(c).toMatch(/HttpGet\("list"\)/)
+    expect(c).toMatch(/HttpGet\("detail\/\{id:guid\}"\)/)
+    expect(c).toMatch(/HttpPost\("form"\)/)
+    expect(c).toMatch(/HttpGet\("dashboard\/consolidated"\)/)
+    expect(c).toMatch(/HttpGet\("dashboard\/alerts"\)/)
+  })
+})

package/templates/skills/development/backend/screen-controller/cli/scaffold-screen-controller/__tests__/hub-views.test.ts

@@ -0,0 +1,105 @@
+/**
+ * hub-views.test.ts — Locks the contract for non-CRUD pagespec views (Wave 1
+ * of the URL-convention alignment, 2026-05-27).
+ *
+ * Hub views (app-home / module-home / section-home) are pure Slot containers
+ * on the frontend — scaffold-component emits NO useService hook and NO
+ * api.get/post call. The screen controller therefore emits NO endpoint and
+ * NO TODO marker for them: the absence is by design, not technical debt.
+ *
+ * Kanban / card views read the same data set as `list` (different
+ * visualisation, same projection) — they fall back to the [HttpGet("list")]
+ * endpoint and push a TODO so audit-dev-api can track the pending
+ * dedicated emitter.
+ */
+import { describe, it, expect } from 'vitest'
+import { generate } from '../generate.js'
+import type { PageSpec, ScaffoldScreenControllerSpec } from '../types.js'
+
+function spec(overrides: Partial<ScaffoldScreenControllerSpec> = {}): ScaffoldScreenControllerSpec {
+  return {
+    section: 'accueil',
+    entity: 'Demande',
+    module: 'affaires',
+    appCode: 'gaf',
+    namespace: 'Gaf',
+    moduleDir: '/ba/affaires',
+    projectPath: '/api',
+    ...overrides,
+  } as ScaffoldScreenControllerSpec
+}
+
+function pagespec(view: string, overrides: Partial<PageSpec> = {}): PageSpec {
+  return {
+    screenCode: `SCR-AFFAIRES-DEMANDES-${view.toUpperCase()}`,
+    appCode: 'gaf',
+    module: 'affaires',
+    section: 'accueil',
+    entity: 'Demande',
+    view: view as PageSpec['view'],
+    permission: 'affaires.demandes.read',
+    linkedUseCases: [],
+    linkedBusinessRules: [],
+    columns: [],
+    actions: [],
+    ...overrides,
+  } as PageSpec
+}
+
+function controllerOf(files: { path: string; content: string }[]): { path: string; content: string } | undefined {
+  return files.find((f) => f.path.endsWith('ScreenController.cs'))
+}
+
+describe('scaffold-screen-controller — hub views (no endpoint, no debt)', () => {
+  for (const view of ['app-home', 'module-home', 'section-home'] as const) {
+    it(`view "${view}" emits NO method, NO DTO, NO TODO`, () => {
+      const { files, todos } = generate(spec(), [pagespec(view)])
+
+      // The controller scaffolding still emits the class shell (so other
+      // pagespecs of the same entity can attach to it), but the body must
+      // not carry the view's CRUD endpoints.
+      const ctrl = controllerOf(files)
+      expect(ctrl).toBeDefined()
+      expect(ctrl!.content).not.toMatch(/\[HttpGet\("list"\)\]/)
+      expect(ctrl!.content).not.toMatch(/\[HttpGet\("detail/)
+      expect(ctrl!.content).not.toMatch(/\[HttpPost\("form"\)\]/)
+      expect(ctrl!.content).not.toMatch(/\[HttpGet\("dashboard\/consolidated"\)\]/)
+
+      // No DTO file emitted for hub views.
+      expect(files.find((f) => f.path.includes('ListScreenDto'))).toBeUndefined()
+      expect(files.find((f) => f.path.includes('DetailScreenDto'))).toBeUndefined()
+
+      // No TODO — the absence of an endpoint is intentional, not debt.
+      expect(todos).toHaveLength(0)
+    })
+  }
+
+  it('hub view + sibling list view → ONE controller with the list endpoint only', () => {
+    const { files } = generate(spec(), [
+      pagespec('section-home'),
+      pagespec('list', { screenCode: 'SCR-AFFAIRES-DEMANDES-LIST' }),
+    ])
+    const ctrl = controllerOf(files)!
+    expect(ctrl.content).toMatch(/\[HttpGet\("list"\)\]/)
+    // The hub did not inject anything extra.
+    expect(ctrl.content).not.toMatch(/HomeDto/)
+  })
+})
+
+describe('scaffold-screen-controller — kanban / card fallback to list', () => {
+  for (const view of ['kanban', 'card'] as const) {
+    it(`view "${view}" reuses the list endpoint + DTO and tracks a TODO`, () => {
+      const { files, todos } = generate(spec(), [pagespec(view)])
+      const ctrl = controllerOf(files)!
+      expect(ctrl.content).toMatch(/\[HttpGet\("list"\)\]/)
+      expect(ctrl.content).toMatch(/PaginatedResult<DemandeListScreenDto>/)
+
+      // A list DTO must be emitted because the controller method references it.
+      const dto = files.find((f) => f.path.endsWith('DemandeListScreenDto.cs'))
+      expect(dto).toBeDefined()
+
+      // One TODO entry signalling the pending dedicated emitter.
+      expect(todos.some((t) => t.includes(view) && t.includes('MVP fallback'))).toBe(true)
+    })
+  }
+})