@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-business
+ * Responsabilité : Generate CQRS pattern for an entity
+ */
+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-business'
+
+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) }, warnings: validation.warnings }))
+    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, fileCount: written.length },
+    filesCreated: written,
+    warnings: validation.warnings,
+    nextSteps: [
+      'Run dotnet build',
+      `Register service DI: services.AddScoped<I${spec.name}Service, ${spec.name}Service>();`,
+      'Register MediatR handlers: services.AddMediatR(cfg => cfg.RegisterServicesFromAssemblies(typeof(Program).Assembly));',
+      'Register validators: services.AddValidatorsFromAssembly(typeof(Program).Assembly);',
+      '(Each of the three DI lines above is idempotent — add once per project, not per entity.)',
+    ],
+  }))
+}
+
+main()

package/templates/skills/development/backend/business-layer/cli/scaffold-business/types.ts

@@ -0,0 +1,112 @@
+/**
+ * cli:scaffold-business — types.ts
+ */
+import { z } from 'zod'
+
+export const FieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1),
+  required: z.boolean().default(true),
+  maxLength: z.number().optional(),
+  isKey: z.boolean().default(false),
+  /**
+   * Optional C# expression deriving this field from other (non-computed) fields
+   * of the SAME entity. When set, the field becomes read-only:
+   * - included in `${e}ListDto` and `${e}DetailDto`
+   * - excluded from `Create${e}Dto`, `Update${e}Dto`, Commands and Validators
+   * - injected into the LINQ projection of `Get${e}` and `Get${plural}` queries
+   *   (one SQL query, no N+1)
+   * Tokens in the formula must be PascalCase property names of the same entity
+   * (e.g. `(InitialAmount - CurrentBalance) / InitialAmount`). Cross-entity
+   * references are rejected at the BA level by audit DM-016.
+   */
+  formula: z.string().optional(),
+})
+
+export const BusinessRuleSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  // Raw FluentValidation rule body — anything valid inside `AbstractValidator<T>.ctor`.
+  // Example: `RuleFor(x => x.StartDate).LessThan(x => x.EndDate).WithMessage("Start must precede end")`
+  // When omitted, generate.ts falls back to simple heuristics (NotEmpty, range, pattern)
+  // based on description, then emits a TODO comment if nothing matches.
+  expression: z.string().optional(),
+  validExamples: z.array(z.string()).default([]),
+  invalidExamples: z.array(z.string()).default([]),
+})
+
+/**
+ * Per-page mode (Step 4 of the per-page vertical-slice refactor): every
+ * non-CRUD action declared in the BA's `BaScreen.Config.actions[]` becomes
+ * one extra Command + Handler + service method beyond the standard CRUD.
+ *
+ * The `code` field is the single source of truth across all 4 layers
+ * (controller URL segment, MediatR Command name, service method, frontend
+ * hook). scaffold-controller (Step 3) emits the matching HTTP route.
+ *
+ * Canonical recipes (auto-emitted, no UC body needed) :
+ *  - `archive`     → entity.Status = 'archived'
+ *  - `restore`     → entity.Status = 'active'
+ *  - `activate`    → entity.IsActive = true
+ *  - `deactivate`  → entity.IsActive = false
+ *  - `duplicate`   → reflection-clone + new Guid + Add()
+ *
+ * Unknown codes fall back to `throw new NotImplementedException` with a
+ * comment pointing to the linked UC so the developer knows where to find
+ * the business specification.
+ */
+export const BusinessCustomActionSchema = z.object({
+  code: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'code must be kebab-case'),
+  scope: z.enum(['row', 'bulk', 'header']).default('row'),
+  payloadDto: z.string().nullable().optional(),
+  responseDto: z.string().min(1).default('NoContent'),
+  /** Optional UC code (e.g. `UC-BUD-014`) — emitted as a comment on the stub
+   *  body when the recipe is non-canonical, so devs can trace the spec. */
+  ucReference: z.string().optional(),
+  // ─── Workflow metadata (SK-001 / SK-002) ────────────────────────────
+  /** Current status the entity must be in before this action can fire.
+   *  When provided, the generator emits a guard: `if (entity.Status != fromStatus) throw …` */
+  fromStatus: z.string().optional(),
+  /** Status the entity transitions to after this action succeeds.
+   *  When provided, the generator emits `entity.Status = toStatus` + SaveChanges. */
+  toStatus: z.string().optional(),
+  /** Business rule IDs that gate this transition (e.g. `["BR-001","BR-003"]`).
+   *  Emitted as guard comments referencing the rule. */
+  guardRules: z.array(z.string()).optional(),
+  /** Extra parameter names extracted from UC flow steps (e.g. `["motif","tacheIds"]`).
+   *  When present AND payloadDto is null, the generator creates an inline DTO
+   *  with these string properties. */
+  flowParameters: z.array(z.string()).optional(),
+  // ─── Cross-module metadata (SK-004 / SK-005) ────────────────────────
+  /** Module dependencies that must be delivered before this action can be
+   *  fully implemented. Generates `// BLOCKED: depends on module '{dep}'` TODOs. */
+  crossModuleDeps: z.array(z.string()).optional(),
+})
+
+export const ScaffoldBusinessInputSchema = z.object({
+  name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/),
+  pluralName: z.string().optional(),
+  module: z.string().min(1),
+  appCode: z.string().min(1),
+  namespace: z.string().optional(),
+  fields: z.array(FieldSchema).min(1),
+  businessRules: z.array(BusinessRuleSchema).default([]),
+  customActions: z.array(BusinessCustomActionSchema).default([]),
+  projectPath: z.string().min(1),
+  /**
+   * Optional PascalCase property name used to project `{Entity}RefDto.DisplayName`
+   * in `GetLookupAsync`. When omitted, the generator picks the first stored
+   * string field in this order: `Name` → `Label` → `Code` → `Title` → first
+   * remaining string. Computed (formula) fields are excluded — the lookup
+   * projection must be SQL-translatable. Used by `ba-develop` Phase 2 which
+   * derives the value from `entité.md`'s `**Affichage** :` line when present.
+   */
+  displayNameExpr: z.string().optional(),
+})
+
+export type Field = z.infer<typeof FieldSchema>
+export type BusinessRule = z.infer<typeof BusinessRuleSchema>
+export type BusinessCustomAction = z.infer<typeof BusinessCustomActionSchema>
+export type ScaffoldBusinessInput = z.infer<typeof ScaffoldBusinessInputSchema>
+export interface GeneratedFile { path: string; content: string }
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }

package/templates/skills/development/backend/business-layer/cli/scaffold-business/validate.ts

@@ -0,0 +1,24 @@
+/**
+ * cli:scaffold-business — validate.ts
+ */
+import { ScaffoldBusinessInputSchema, type ScaffoldBusinessInput, type ValidationResult } from './types.js'
+
+export function validateStructure(raw: unknown): ValidationResult {
+  const result = ScaffoldBusinessInputSchema.safeParse(raw)
+  if (result.success) return { valid: true, errors: [], warnings: [] }
+  return { valid: false, errors: result.error.issues.map(i => `[${i.path.join('.')}] ${i.message}`), warnings: [] }
+}
+
+export function validateBusinessRules(spec: ScaffoldBusinessInput): ValidationResult {
+  const warnings: string[] = []
+  if (spec.businessRules.length === 0) {
+    warnings.push('No business rules provided — validator will only have basic field validation')
+  }
+  return { valid: true, errors: [], warnings }
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const structural = validateStructure(raw)
+  if (!structural.valid) return structural
+  return validateBusinessRules(raw as ScaffoldBusinessInput)
+}

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

@@ -0,0 +1,154 @@
+---
+name: backend-controller
+description: >
+  Generates the **integration-strata** API controller (generic CRUD under
+  /api/v1/integration/, Swagger group "integration") with NavRoute,
+  RequirePermission, auto-mapped DTO → Command conversions, and module-scoped
+  permission classes. Consumes NuGet packages (SmartStack.Core, SmartStack.Api,
+  MediatR). The companion **screen-driven strata** lives in
+  /api/screens/... and is generated by `scaffold-screen-controller`.
+phase: development/backend
+cli: cli/scaffold-controller
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Integration Controller — API Layer (generic strata)
+
+Generates the **integration-strata** REST controller for an entity. This is the
+controller machine-to-machine consumers talk to: imports/exports, ETL, BI,
+third-party integrations, batch jobs, Postman/Swagger exploration, dev tooling.
+
+> **Two strata, one business layer.** SmartStack splits the public surface in two:
+>
+> | Strata | Generator | Route | Swagger group | Consumer |
+> |--------|-----------|-------|---------------|----------|
+> | **Integration** | `scaffold-controller` *(this skill)* | `/api/v1/integration/{plural}` | `integration` | Machine-to-machine (ETL, BI, batch, scripts) |
+> | **Screens** | `scaffold-screen-controller` *(Phase 2b — fan-out per section)* | `/api/screens/{plural}/{action}` | `screens` | The generated React app — one endpoint per screen, payload shaped from the pagespec |
+>
+> Both strata call the **same Business layer** (`I{Entity}Service`). Business
+> rules never duplicate — only the DTO shape + URL contract differ.
+
+## When to Use
+
+- Phase 2a (API integration) of `/ba-develop`
+- When adding a generic CRUD endpoint over an entity for non-UI consumers
+- Custom actions / state transitions (archive, validate, …) coming from BA UCs
+  are still emitted here — the screens stratum calls them via the same Business
+  method, never reimplements them
+
+## Controller Pattern (output)
+
+```csharp
+/// <summary>
+/// Integration controller — exposes generic CRUD over the entity for
+/// machine-to-machine consumers. The screen-driven API lives under
+/// /api/screens/... and is generated by scaffold-screen-controller.
+/// </summary>
+[ApiController]
+[ApiExplorerSettings(GroupName = "integration")]
+[Route("api/v1/integration/[controller]")]
+[NavRoute("hrm.employees")]
+[Authorize]
+[Produces("application/json")]
+public class EmployeesController : ControllerBase
+{
+    private readonly IEmployeeService _service;
+    public EmployeesController(IEmployeeService service) => _service = service;
+
+    [HttpGet]
+    [RequirePermission(HrmPermissions.Employees.Read)]
+    public async Task<ActionResult<PaginatedResult<EmployeeListDto>>> GetAll(
+        [FromQuery] int page = 1, [FromQuery] int pageSize = 20,
+        [FromQuery] string? search = null, CancellationToken ct = default)
+    {
+        return Ok(await _service.GetAllAsync(new GetEmployeesQuery(page, pageSize, search), ct));
+    }
+
+    [HttpPost]
+    [RequirePermission(HrmPermissions.Employees.Create)]
+    public async Task<ActionResult<Guid>> Create([FromBody] CreateEmployeeDto dto, CancellationToken ct = default)
+    {
+        var command = new CreateEmployeeCommand(dto.FirstName, dto.LastName);
+        var id = await _service.CreateAsync(command, ct);
+        return CreatedAtAction(nameof(GetById), new { id }, id);
+    }
+
+    [HttpPut("{id:guid}")]
+    [RequirePermission(HrmPermissions.Employees.Update)]
+    public async Task<ActionResult> Update(Guid id, [FromBody] UpdateEmployeeDto dto, CancellationToken ct = default)
+    {
+        var command = new UpdateEmployeeCommand(id, dto.FirstName, dto.LastName);
+        await _service.UpdateAsync(command, ct);
+        return NoContent();
+    }
+}
+```
+
+## ⚠ BLOCKING — Roslyn Convention Rules
+
+**Any generated controller violating these rules MUST fail audit and be rewritten.**
+
+- **SS001**: Must inherit `ControllerBase` + have `[ApiController]`
+- **SS002**: Single service injection (no `DbContext`, `IRepository<T>`, `ILogger` as primary deps — use the service layer)
+- **SS003**: `[NavRoute]` present, format `module.section` (min 2 segments)
+- **SS004**: `[RequirePermission]` on EACH public endpoint (no "forgot" exceptions)
+- **SS005**: Return DTOs only — NEVER domain entities (`Employee`, `Order` etc.). Use `EmployeeListDto`, `OrderDetailDto`.
+- **SS006**: `CancellationToken ct` as the LAST parameter of every endpoint
+- **SS007**: `NavRoute` unique project-wide — grep before generating to ensure no collision
+- **SS008**: Return type is **always** `ActionResult<T>` for responses with a body, `ActionResult` for 204 NoContent. Never raw `IActionResult`.
+- **SS009**: No business logic in the controller — call `_service.XxxAsync(...)` and return
+- **SS010**: `[FromBody]` / `[FromQuery]` explicit on every DTO parameter (OpenAPI clarity)
+- **SS011**: `Create` endpoint returns `CreatedAtAction(nameof(GetById), new { id }, id)` — not `Ok(id)`
+- **SS012**: DTO → Command mapping is **fully materialised** in generated code — no `/* map dto fields */` placeholders
+
+## ⚠ BLOCKING — Clean Architecture layers
+
+- Controller (Api layer) imports ONLY from: `Application` (services, DTOs, commands), `Domain` (enums, value types), `SmartStack.Core.Navigation`, `SmartStack.Api.Authorization`. Never from `Infrastructure`.
+- Service (`Application` layer) imports from `Domain` + abstractions. Never from `Api` or `Infrastructure` directly — infrastructure implementations are injected via DI.
+- Violation → CS error or layer leak flagged by audit.
+
+## Module-scoped Permissions Class Pattern
+
+The CLI emits one Permissions file per section, placed under a module-scoped
+namespace so two modules sharing section names never collide:
+
+```csharp
+// src/{Ns}.Api/Permissions/Hrm/HrmPermissions.Employees.cs
+namespace {Ns}.Api.Permissions.Hrm;
+
+public static class HrmPermissions
+{
+    public static class Employees
+    {
+        public const string Access = "hrm.employees.access";
+        public const string Read = "hrm.employees.read";
+        public const string Create = "hrm.employees.create";
+        public const string Update = "hrm.employees.update";
+        public const string Delete = "hrm.employees.delete";
+    }
+}
+```
+
+## After generation — MANDATORY
+
+Once the CLI has finished writing the controller + permissions class, invoke
+the audit skill. Catches SS001–SS012 violations, missing permissions entries,
+DTO-vs-entity confusion, and cross-layer imports:
+
+```
+@.claude/skills/development/audit/SKILL.md
+Audit the controller + permissions class I just generated at
+src/{AppCode}.Api/Controllers/... and the service contract.
+```
+
+The audit MUST be green before declaring the generation "done".
+
+## Invocation
+
+```bash
+npx tsx skills/development/backend/controller/cli/scaffold-controller/index.ts \
+  --spec '{"name":"Employee","module":"hrm","appCode":"MyApp","section":"employees","navRoute":"hrm.employees","fields":[{"name":"firstName","type":"string","required":true},{"name":"lastName","type":"string","required":true}],"projectPath":"/path"}'
+```
+
+**Important**: the `fields` array is required — it drives the DTO → Command mapping
+generation. Without it, the CLI has no way to know which fields to pass through.