@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/audit-dev-wire/cli/audit-dev-wire/index.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+//
+// audit-dev-wire / index.ts — Entry point.
+//
+// Static parity check between the generated frontend service URLs and the
+// generated backend controller routes. Phase 3e gate of /ba-develop.
+//
+// Usage:
+//
+//   npx tsx skills/development/audit-dev-wire/cli/audit-dev-wire/index.ts \
+//     --project-path  "<backend-root>" \
+//     --web-path      "<web-root>"     \
+//     --module-code   "<MODULE>" \
+//     --app-code      "<APP>" \
+//     --mode audit
+//
+// Exit code: 0 when no `err` findings, 1 otherwise.
+import { Command } from 'commander'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { validateArgs } from './validate.js'
+import { audit, reportPath } from './audit.js'
+import type { AuditDevWireOutput, Finding } from './types.js'
+
+const program = new Command()
+
+program
+  .name('audit-dev-wire')
+  .description('Static parity check between generated frontend URLs and backend routes (DEV-WIRE-001). Phase 3e gate of /ba-develop.')
+  .requiredOption('--project-path <path>', 'Absolute path to the .NET backend root (src/<Ns>.Api/Controllers/**)')
+  .option('--web-path <path>', 'Absolute path to the web project root (src/features/**). Defaults to <project-path>/web/<appCode>-web.')
+  .requiredOption('--module-code <code>', 'Active module code (PRD scope)')
+  .requiredOption('--app-code <code>', 'Active application code (PRD scope)')
+  .option('--mode <mode>', 'audit | apply (apply is a stub in MVP)', 'audit')
+  .option('--rules <list>', 'Comma-separated rule codes (e.g. DEV-WIRE-001). Default = all implemented rules')
+  .option('--no-write-report', 'Skip writing _audit/dev-wire-<module>.md (stdout only)')
+  .parse(process.argv)
+
+const opts = program.opts()
+
+const webPathDefault = path.join(opts.projectPath as string, 'web', `${(opts.appCode as string).toLowerCase()}-web`)
+const raw = {
+  backendPath: opts.projectPath as string,
+  webPath: (opts.webPath as string | undefined) ?? webPathDefault,
+  moduleCode: opts.moduleCode as string,
+  appCode: opts.appCode as string,
+  mode: opts.mode as string,
+  rules: typeof opts.rules === 'string'
+    ? (opts.rules as string).split(',').map((s) => s.trim()).filter(Boolean)
+    : [],
+}
+const writeReport = opts.writeReport !== false
+
+const validation = validateArgs(raw)
+if (!validation.valid || !validation.args) {
+  const output: AuditDevWireOutput = {
+    success: false,
+    command: 'audit-dev-wire',
+    data: { mode: (raw.mode as 'audit' | 'apply') ?? 'audit', rulesRun: [], valid: false },
+    report: null,
+    auditReport: null,
+    filesModified: [],
+    errors: validation.errors,
+    warnings: [],
+    nextSteps: ['Fix the CLI arguments and retry.'],
+  }
+  console.log(JSON.stringify(output, null, 2))
+  process.exit(1)
+}
+
+const args = validation.args
+
+async function main(): Promise<void> {
+  try {
+    const report = await audit(args)
+
+    if (writeReport) {
+      const dest = reportPath(args.backendPath, args.moduleCode)
+      await mkdir(path.dirname(dest), { recursive: true })
+      await writeFile(dest, report.markdown, 'utf8')
+    }
+
+    const valid = report.counts.errors === 0
+    const rulesRun = args.rules.length > 0 ? args.rules : Object.keys(report.byRule)
+
+    const stripped = report.findings.map((f: Finding) => ({
+      dimension: f.dimension,
+      code: f.code,
+      severity: f.severity,
+      label: f.label,
+      params: f.params,
+      solution: f.solution,
+      fixSkill: f.fixSkill,
+      fixPhaseKey: f.fixPhaseKey,
+    }))
+
+    const nextSteps: string[] = []
+    if (report.counts.errors > 0) {
+      nextSteps.push(`${report.counts.errors} ERROR finding(s) — blocking Phase 3e gate of /ba-develop.`)
+      nextSteps.push('Re-run /ba-develop after re-invoking the missing backend scaffolder.')
+    }
+
+    const output: AuditDevWireOutput = {
+      success: true,
+      command: 'audit-dev-wire',
+      data: { mode: args.mode, rulesRun, valid },
+      report,
+      auditReport: {
+        scope: 'devWire',
+        applicationCode: args.appCode,
+        moduleCode: args.moduleCode,
+        findings: stripped,
+      },
+      filesModified: [],
+      errors: [],
+      warnings: [],
+      nextSteps,
+    }
+    console.log(JSON.stringify(output, null, 2))
+    process.exit(valid ? 0 : 1)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    const output: AuditDevWireOutput = {
+      success: false,
+      command: 'audit-dev-wire',
+      data: { mode: args.mode, rulesRun: [], valid: false },
+      report: null,
+      auditReport: null,
+      filesModified: [],
+      errors: [`Unexpected error: ${message}`],
+      warnings: [],
+      nextSteps: ['Review the error and retry.'],
+    }
+    console.log(JSON.stringify(output, null, 2))
+    process.exit(1)
+  }
+}
+
+void main()

package/templates/skills/development/audit-dev-wire/cli/audit-dev-wire/types.ts

@@ -0,0 +1,110 @@
+/**
+ * audit-dev-wire / types.ts — CLI args + finding + report shapes.
+ *
+ * Mirrors `audit-dev-api/types.ts` so the orchestrator UI renders both audits
+ * with one component. Single-rule MVP (DEV-WIRE-001 frontend-orphan); the
+ * other 2 rule slots (DEV-WIRE-002/003) are reserved in the schema for
+ * forward compatibility with the auto-healing failure kinds.
+ */
+import { z } from 'zod'
+
+export const AuditDevWireModeSchema = z.enum(['audit', 'apply'])
+export type AuditDevWireMode = z.infer<typeof AuditDevWireModeSchema>
+
+export const AuditDevWireArgsSchema = z.object({
+  /** Absolute path to the .NET backend root (holds src/<Ns>.Api/Controllers/**). */
+  backendPath: z.string().min(1),
+  /** Absolute path to the web project root (holds src/features/**). */
+  webPath: z.string().min(1),
+  /** `audit` = report only ; `apply` is a stub (no-op in MVP). */
+  mode: AuditDevWireModeSchema.default('audit'),
+  /** Active module code (PRD scope) — embedded in the markdown report. */
+  moduleCode: z.string().min(1),
+  /** Active application code (PRD scope) — embedded in the markdown report. */
+  appCode: z.string().min(1),
+  /** Subset of rule codes to run. Empty = all implemented rules. */
+  rules: z.array(z.string()).default([]),
+})
+
+export type AuditDevWireArgs = z.infer<typeof AuditDevWireArgsSchema>
+
+export type Severity = 'err' | 'warn' | 'ok'
+
+export interface Finding {
+  dimension: 'devWire'
+  code: string
+  severity: Severity
+  label: string
+  params: Record<string, unknown>
+  solution: string
+  fixSkill?: string
+  fixPhaseKey?: string
+  file?: string
+}
+
+// ─── Internal call/route shapes ──────────────────────────────────────────
+
+/** One URL call extracted from a frontend service or hook. */
+export interface FrontendCall {
+  /** Lowercase verb: 'get' / 'post' / 'put' / 'patch' / 'delete'. */
+  verb: string
+  /** Full URL path with `{id}` placeholders normalised. */
+  urlPath: string
+  /** Source file relative to webPath. */
+  file: string
+  /** Source line for navigation. */
+  line: number
+}
+
+/** One backend controller route. Mirrors audit-dev-api's ControllerEndpointEntry. */
+export interface BackendRoute {
+  verb: string
+  /** Full URL path (class route + method suffix), with `{id:guid}` → `{id}`. */
+  urlPath: string
+  /** Source file relative to backendPath. */
+  file: string
+  /** 'integration' / 'screens' / 'unknown'. */
+  stratum: 'integration' | 'screens' | 'unknown'
+}
+
+// ─── Report ──────────────────────────────────────────────────────────────
+
+export interface AuditReport {
+  scope: 'devWire'
+  applicationCode: string
+  moduleCode: string
+  backendPath: string
+  webPath: string
+  filesInspected: number
+  findings: Finding[]
+  counts: { errors: number; warnings: number; oks: number }
+  byRule: Record<string, number>
+  markdown: string
+}
+
+export interface AuditDevWireOutput {
+  success: boolean
+  command: 'audit-dev-wire'
+  data: {
+    mode: AuditDevWireMode
+    rulesRun: string[]
+    valid: boolean
+  }
+  report: AuditReport | null
+  auditReport: {
+    scope: 'devWire'
+    applicationCode: string
+    moduleCode: string
+    findings: Array<Pick<Finding, 'dimension' | 'code' | 'severity' | 'label' | 'params' | 'solution' | 'fixSkill' | 'fixPhaseKey'>>
+  } | null
+  filesModified: string[]
+  errors: string[]
+  warnings: string[]
+  nextSteps: string[]
+}
+
+export interface ArgsValidationResult {
+  valid: boolean
+  args: AuditDevWireArgs | null
+  errors: string[]
+}

package/templates/skills/development/audit-dev-wire/cli/audit-dev-wire/validate.ts

@@ -0,0 +1,16 @@
+/**
+ * audit-dev-wire / validate.ts — CLI arg validation.
+ */
+import { AuditDevWireArgsSchema, type ArgsValidationResult } from './types.js'
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = AuditDevWireArgsSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      valid: false,
+      args: null,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+    }
+  }
+  return { valid: true, args: parsed.data, errors: [] }
+}

package/templates/skills/development/backend/business-layer/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: backend-business-layer
+description: >
+  Generates full CQRS stack — Commands, Queries, Handlers, DTOs, Validators,
+  Service interface + implementation — on SmartStack NuGet abstractions
+  (ICoreDbContext, MediatR, FluentValidation).
+phase: development/backend
+cli: cli/scaffold-business
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Business Layer — CQRS + Services
+
+Generates the full application layer following the SmartStack CQRS pattern:
+commands, queries, **handlers** (one per command/query), DTOs, FluentValidation
+validators, service interface and service implementation.
+
+## When to Use
+
+- Phase 4 (business) of the development workflow
+- When adding business logic for a new entity
+
+## CQRS Pattern (output)
+
+### Commands (each with a matching handler)
+
+```csharp
+public record CreateEmployeeCommand(string FirstName, string LastName) : IRequest<Guid>;
+
+public class CreateEmployeeCommandHandler : IRequestHandler<CreateEmployeeCommand, Guid>
+{
+    private readonly IEmployeeService _service;
+    public CreateEmployeeCommandHandler(IEmployeeService service) => _service = service;
+    public Task<Guid> Handle(CreateEmployeeCommand request, CancellationToken cancellationToken)
+        => _service.CreateAsync(request, cancellationToken);
+}
+
+public class CreateEmployeeCommandValidator : AbstractValidator<CreateEmployeeCommand>
+{
+    public CreateEmployeeCommandValidator()
+    {
+        RuleFor(x => x.FirstName).NotEmpty().MaximumLength(100);
+        RuleFor(x => x.LastName).NotEmpty().MaximumLength(100);
+    }
+}
+```
+
+### Update/Delete commands return `IRequest<Unit>`
+
+MediatR 12 convention: void operations still need a response type. We use `Unit`:
+
+```csharp
+public record UpdateEmployeeCommand(Guid Id, string FirstName, string LastName) : IRequest<Unit>;
+
+public class UpdateEmployeeCommandHandler : IRequestHandler<UpdateEmployeeCommand, Unit>
+{
+    private readonly IEmployeeService _service;
+    public UpdateEmployeeCommandHandler(IEmployeeService service) => _service = service;
+    public async Task<Unit> Handle(UpdateEmployeeCommand request, CancellationToken cancellationToken)
+    {
+        await _service.UpdateAsync(request, cancellationToken);
+        return Unit.Value;
+    }
+}
+```
+
+### Queries
+
+```csharp
+public record GetEmployeeQuery(Guid Id) : IRequest<EmployeeDetailDto?>;
+public record GetEmployeesQuery(int Page = 1, int PageSize = 20, string? Search = null)
+    : IRequest<PaginatedResult<EmployeeListDto>>;
+
+// Handlers delegate to the service (thin)
+public class GetEmployeeQueryHandler : IRequestHandler<GetEmployeeQuery, EmployeeDetailDto?> { ... }
+public class GetEmployeesQueryHandler : IRequestHandler<GetEmployeesQuery, PaginatedResult<EmployeeListDto>> { ... }
+```
+
+### DTOs (immutable records)
+
+```csharp
+public record EmployeeListDto(Guid Id, string FirstName, string LastName, DateTime CreatedAt);
+public record EmployeeDetailDto(Guid Id, string FirstName, string LastName, /* all fields */, DateTime CreatedAt, DateTime UpdatedAt);
+public record CreateEmployeeDto(string FirstName, string LastName);
+public record UpdateEmployeeDto(string FirstName, string LastName);
+```
+
+### Service (uses `ICoreDbContext` — the SmartStack abstraction)
+
+```csharp
+public class EmployeeService : IEmployeeService
+{
+    private readonly ICoreDbContext _context;
+    public EmployeeService(ICoreDbContext context) => _context = context;
+
+    public async Task<Guid> CreateAsync(CreateEmployeeCommand command, CancellationToken ct = default)
+    {
+        var entity = Employee.Create(command.FirstName, command.LastName);
+        _context.Set<Employee>().Add(entity);
+        await _context.SaveChangesAsync(ct);
+        return entity.Id;
+    }
+    // UpdateAsync / DeleteAsync / GetByIdAsync / GetAllAsync…
+}
+```
+
+## ⚠ BLOCKING — Key Rules
+
+**Any generated file violating these rules MUST fail audit and be rewritten.**
+
+1. **Every command/query has a handler** — MediatR fails at runtime otherwise (unresolved `IRequestHandler<>`).
+2. **Commands modify state** — return `Guid` (created id) or `Unit` (void).
+3. **Queries are read-only** — return DTOs, NEVER domain entities.
+4. **Services take `ICoreDbContext`**, not `IApplicationDbContext` or the concrete `CoreDbContext`. This is the SmartStack abstraction boundary.
+5. **FluentValidation** — one validator per command, one rule per PRD business rule. Validators are wired via `services.AddValidatorsFromAssembly(...)` in the client's Program.cs; the CLI does NOT generate that DI line (client responsibility).
+6. **DTOs are records** — immutable, value equality, nullable-aware.
+7. **Service interface** — abstracts CQRS for controller consumption (`IEmployeeService`).
+8. **No cross-layer leak** — Application must NOT import from `{AppCode}.Api.*` or `{AppCode}.Infrastructure.*` concrete types (only abstractions).
+9. **`CancellationToken ct`** — propagated through every async method signature.
+10. **`isKey` fields excluded from Update** — an update command never receives the primary key as a mutable field.
+
+## Files emitted per entity
+
+```
+src/{Ns}.Application/{Mod}/
+├── Commands/Create{E}Command.cs          — IRequest<Guid>
+├── Commands/Update{E}Command.cs          — IRequest<Unit>
+├── Commands/Delete{E}Command.cs          — IRequest<Unit>
+├── Queries/Get{E}Query.cs                — IRequest<{E}DetailDto?>  + Get{Plural}Query
+├── Handlers/Create{E}CommandHandler.cs   — delegates to I{E}Service
+├── Handlers/Update{E}CommandHandler.cs
+├── Handlers/Delete{E}CommandHandler.cs
+├── Handlers/Get{E}QueryHandler.cs
+├── Handlers/Get{Plural}QueryHandler.cs
+├── Validators/Create{E}CommandValidator.cs
+├── Validators/Update{E}CommandValidator.cs
+├── Interfaces/I{E}Service.cs
+└── DTOs/{E}Dtos.cs
+
+src/{Ns}.Infrastructure/Services/{Mod}/
+└── {E}Service.cs                         — uses ICoreDbContext
+```
+
+## Business Rules → Validators
+
+Each business rule from the PRD becomes a FluentValidation rule:
+
+```csharp
+// PRD: "Start date must be before end date"
+RuleFor(x => x.StartDate).LessThan(x => x.EndDate)
+    .WithMessage("Start date must be before end date");
+```
+
+The CLI applies precedence: explicit `rule.expression` → description heuristics
+(required / range / pattern / comparison) → TODO comment fallback with the rule id.
+Each rule is emitted into **both** `Create{E}CommandValidator` and
+`Update{E}CommandValidator` — a business invariant holds on modification too, not
+only on creation.
+
+## Post-scaffold business-logic pass (MANDATORY)
+
+`scaffold-business` is deterministic and intentionally leaves the *hard* logic as
+explicit, greppable markers rather than guessing. After the CLI has emitted the
+CQRS stack, the dev agent (Phase 2 of `ba-develop`) **MUST** complete them — the
+API gate is **BLOCKING** on zero residual markers (see `ba-develop/SKILL.md`
+§ "After Phase 2 (API)") and audit `DEV-API-008/009` rejects any left behind.
+
+Read the module's `règles-métier.md` (rule expressions + valid/invalid examples)
+and its sections' `use-case.md` (main / alternative / exception flows), then:
+
+1. **`// TODO[BR-…]` in a validator** — a business rule the heuristics could not
+   translate. Replace it with the real enforcement:
+   - field / cross-field, expressible in FluentValidation → write the `RuleFor(...)`
+     in *both* `Create{E}CommandValidator` and `Update{E}CommandValidator`.
+   - **multi-entity, stateful or temporal** (e.g. "cannot approve a budget whose
+     parent is archived", "end date after start date and not in the past") →
+     FluentValidation cannot express it. Enforce it inside the **service method**
+     that performs the operation, throwing the domain exception the use case
+     expects (`ValidationException` or a domain-specific one).
+2. **`throw new NotImplementedException()` + `// TODO[UC-…]` in a service method** —
+   a non-canonical custom action (anything beyond archive / restore / activate /
+   deactivate / duplicate). Implement the body from the linked use case's main
+   flow: load the aggregate, apply the state change + invariants, persist, return
+   the response DTO. Keep the `// UC-…` trace comment.
+3. **Trace** every rule / use case you implement with a `// BR-…` / `// UC-…`
+   comment so the audit can confirm coverage.
+
+Never delete a marker without implementing it, and never weaken a test to make a
+stub pass. If a rule is genuinely unimplementable from the BA docs, halt and route
+back to `create-prd` / the owning BA phase — do not ship a stub.
+
+## Client DI registration (manual, once per project)
+
+Add to the client's `Program.cs` (or `Application/DependencyInjection.cs`):
+
+```csharp
+services.AddMediatR(cfg => cfg.RegisterServicesFromAssemblies(typeof(Program).Assembly));
+services.AddValidatorsFromAssembly(typeof(Program).Assembly);
+services.AddScoped<IEmployeeService, EmployeeService>();
+// One AddScoped per generated service.
+```
+
+## After generation — MANDATORY
+
+Once the CLI has written all files, invoke the audit skill:
+
+```
+@.claude/skills/development/audit/SKILL.md
+Audit the application layer I just generated in src/{AppCode}.Application/
+for the entity {Name}. Check CQRS conventions, validator coverage,
+DTO-vs-entity, handler presence, DI registrations.
+```
+
+The audit MUST be green before declaring the generation "done".
+
+## Invocation
+
+```bash
+npx tsx skills/development/backend/business-layer/cli/scaffold-business/index.ts \
+  --spec '{"name":"Employee","module":"hrm","appCode":"MyApp","fields":[{"name":"firstName","type":"string","required":true,"maxLength":100}],"businessRules":[...],"projectPath":"/path"}'
+```
+
+`fields[].isKey` marks a field that is part of the primary key — excluded from
+Update commands. Default is `false`.
+
+`fields[].formula` (optional, string) marks a **computed attribute**. When set,
+the generator treats the field as read-only :
+
+- `${E}ListDto` and `${E}DetailDto` include it.
+- `Create${E}Dto`, `Update${E}Dto`, `Create${E}Command`, `Update${E}Command` and
+  the FluentValidation validators **exclude** it (the user never writes the
+  value).
+- `Get${E}` and `Get${Plural}` LINQ projections inject the formula directly :
+  ```csharp
+  .Select(x => new BudgetListDto(
+      x.Id,
+      x.Label,
+      x.InitialAmount,
+      x.CurrentBalance,
+      (x.InitialAmount - x.CurrentBalance) / x.InitialAmount,  // consumptionRate
+      x.CreatedAt))
+  ```
+  → one SQL query, no N+1, no separate analysis endpoint.
+
+The formula syntax is a C# expression referencing **PascalCase property names**
+of the SAME entity (`InitialAmount`, `CurrentBalance`, …). The CLI rewrites
+each known property reference to `x.<Property>` so EF Core can translate it.
+Cross-entity references are forbidden at the BA level (audit DM-016) and never
+reach the dev pipeline.
+
+When the PRD slice declares a computed column (e.g. `domain.md` lists
+`Budget.consumptionRate (decimal) = (InitialAmount - CurrentBalance) / InitialAmount`),
+you MUST forward that formula via the `formula` field of the corresponding
+spec entry. Do NOT emit a stub helper or hand-roll the projection — the CLI
+output is the single source of truth.