@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * cli:scaffold-controller — types.ts
+ */
+import { z } from 'zod'
+
+export const ControllerFieldSchema = z.object({
+  name: z.string().min(1),
+  type: z.string().min(1),
+  required: z.boolean().default(true),
+})
+
+/**
+ * Per-page mode (Step 3 of the per-page vertical-slice refactor): every
+ * non-CRUD action declared in the BA's `BaScreen.Config.actions[]` becomes
+ * one custom controller endpoint. Codes outside the standard REST set
+ * (create/update/delete) are passed here and emitted as
+ * `[HttpPost("{id:guid}/{code}")]` (row scope), `[HttpPost("bulk/{code}")]`
+ * (bulk scope), or `[HttpPost("{code}")]` (header scope).
+ *
+ * The legacy `actions[]` enum stays untouched for permission constants and
+ * for backwards compat with batch-entity callers; `customActions` is the
+ * additive per-page input.
+ */
+export const ControllerCustomActionSchema = z.object({
+  /** Action code (kebab/lowercase) — single source of truth across the whole
+   *  vertical slice (URL segment, service method, hook). Examples: `archive`,
+   *  `duplicate`, `approve`, `sync-from-proconcept`.
+   *  Per-page mode: ba-develop derives this directly from
+   *  `pageSpec.actions[].endpoint` (the verbatim URL segment) so frontend and
+   *  backend cannot drift. @see lib/page-spec-actions.ts. */
+  code: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'code must be kebab-case'),
+  scope: z.enum(['row', 'bulk', 'header']).default('row'),
+  /** HTTP verb. Defaults POST (state mutations). Set GET for read-only
+   *  compute endpoints (`analyze-impact`, `validate`, …) — the generator omits
+   *  `[FromBody]` automatically. */
+  httpMethod: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('POST'),
+  /** C# DTO type name expected in the request body, or null when there's no
+   *  body. Set by build-page-context.ts when the linked BR has parameters.
+   *  Ignored when `httpMethod === 'GET'` (no body on GETs). */
+  payloadDto: z.string().nullable().optional(),
+  /** C# response type name. `NoContent` for 204 endpoints (state mutations
+   *  like archive that return nothing). */
+  responseDto: z.string().min(1).default('NoContent'),
+  /** Permission action segment ({app}.{module}.{section}.{permissionAction})
+   *  — defaults to `update` because most state-transition actions
+   *  (archive/restore/activate/deactivate) reuse the existing Update perm. */
+  permissionAction: z.string().min(1).default('update'),
+})
+
+export const ScaffoldControllerInputSchema = z.object({
+  name: z.string().min(1).regex(/^[A-Z][A-Za-z0-9]*$/),
+  pluralName: z.string().optional(),
+  module: z.string().min(1),
+  section: z.string().min(1),
+  appCode: z.string().min(1),
+  namespace: z.string().optional(),
+  navRoute: z
+    .string()
+    .regex(/^[\w]+(\.[\w]+)+$/, 'NavRoute must be dot-separated hierarchy: module.section[.resource...]')
+    .refine(v => !v.endsWith('.') && !v.startsWith('.'), 'NavRoute cannot start or end with a dot'),
+  permissionPrefix: z.string().optional(),
+  actions: z.array(z.enum(['read', 'create', 'update', 'delete', 'export', 'import', 'approve', 'reject', 'assign', 'execute'])).default(['read', 'create', 'update', 'delete']),
+  customActions: z.array(ControllerCustomActionSchema).default([]),
+  fields: z.array(ControllerFieldSchema).default([]),
+  projectPath: z.string().min(1),
+})
+
+export type ControllerField = z.infer<typeof ControllerFieldSchema>
+export type ControllerCustomAction = z.infer<typeof ControllerCustomActionSchema>
+export type ScaffoldControllerInput = z.infer<typeof ScaffoldControllerInputSchema>
+export interface GeneratedFile { path: string; content: string }
+export interface ValidationResult { valid: boolean; errors: string[]; warnings: string[] }

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

@@ -0,0 +1,14 @@
+/**
+ * cli:scaffold-controller — validate.ts
+ */
+import { ScaffoldControllerInputSchema, type ScaffoldControllerInput, type ValidationResult } from './types.js'
+
+export function validateStructure(raw: unknown): ValidationResult {
+  const result = ScaffoldControllerInputSchema.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 validate(raw: unknown): ValidationResult {
+  return validateStructure(raw)
+}

package/templates/skills/development/backend/core-seed/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: backend-core-seed
+description: >
+  Phase 0 of /ba-develop — generates one Core Foundation Seed
+  bundle per declared application (5 IClientSeedDataProvider classes per app
+  covering navigation + roles + permissions + role-permission mappings + dev
+  test users) by invoking the deterministic `scaffold-core-seed` CLI. Zero
+  creative work for the agent: the spec is built by the Studio backend
+  (`prepareCoreSeedContext`) from the BA menu / actors / permissions and
+  dropped to a temp file before this skill runs.
+phase: development/backend
+cli: cli/scaffold-core-seed
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Core Foundation Seed — Phase 0 of develop pipeline
+
+This is the FIRST phase of `/ba-develop`. It generates the
+per-application foundation that every subsequent phase (Entities, API,
+Frontend) depends on:
+
+For each application declared in the BA menu tree (one or more):
+
+- Application + every Module + every Section + every Resource declared in
+  the BA menu tree, in
+  `Seeding/Applications/{AppPascal}/Core/{AppPascal}CoreNavigationSeedDataProvider.cs`
+- One `Role` per actor × `applicationCode`, in
+  `{AppPascal}CoreRolesSeedDataProvider.cs`
+- One `NavigationPermission` per `structured.permissions[]` row, in
+  `{AppPascal}CorePermissionsSeedDataProvider.cs`
+- Role → permission wiring in `{AppPascal}CoreRolePermissionsSeedDataProvider.cs`
+- One dev test user per role (gated by `IHostEnvironment.IsDevelopment()`)
+  in `{AppPascal}CoreTestUsersSeedDataProvider.cs`
+- Each application's 5 providers registered in `DependencyInjection.cs`
+  between `<<< CORE-SEED-DI-{AppPascal} BEGIN/END >>>` markers (one block
+  per app)
+
+## Why this skill exists
+
+The previous per-module seeding pattern allowed a module to ship with 9
+entities + 2 controllers but **empty navigation / roles / permissions**
+(observed in TestV2/ba-002, Budget module). Each per-module agent only saw
+its own slice, so the global navigation tree was never assembled
+deterministically.
+
+This skill moves seeding to a **single per-application deterministic generator**
+that sees the full BA state for that app in one shot. Each `ApplicationSpec`'s
+`modules[]` field is load-bearing: the CLI's `validate.ts` and the runtime gate
+`verifyCoreFoundationSeed` both refuse to pass if any declared module lacks
+nav + ≥ 1 role + ≥ 2 permissions in its owning application.
+
+Multi-application projects (e.g. CRM + Budgeting in the same .NET solution)
+get one Core bundle per app, with class names prefixed by the PascalCase app
+code to avoid collisions and DI markers scoped per app for idempotent re-runs.
+
+## Your job
+
+The Studio backend has already assembled the spec and written it to a temp
+file. Your job is exactly three steps:
+
+1. **Invoke the CLI** with the spec file path provided in the prompt:
+
+   ```bash
+   npx tsx skills/development/backend/core-seed/cli/scaffold-core-seed/index.ts \
+     --spec-file <SPEC_FILE_PATH> \
+     --outdir <PROJECT_PATH>
+   ```
+
+2. **Verify the output envelope** — the CLI prints a JSON envelope on
+   stdout. Confirm `success: true` and that:
+   - `filesCreated` lists `5 × N_apps` `{AppPascal}Core*SeedDataProvider.cs`
+     files (and the test users manifest, if present)
+   - `filesModified` lists the patched `DependencyInjection.cs`
+   - `data.diPatched === true` (otherwise the providers will not be
+     resolved at startup)
+   - `data.appsPatched` lists every application code from the spec
+   - `warnings[]` is empty (or only minor — review them)
+
+3. **Emit a SHORT final report**, then STOP:
+   ```
+   Created: 5 × N apps Core providers + DI patch | Apps: <list> | Warnings: 0
+   ```
+
+## What you MUST NOT do
+
+- Do not edit any of the generated `.cs` files. They are deterministic;
+  any change you make will be overwritten on the next Phase 0 run.
+- Do not regenerate the spec yourself. The backend builds it from the BA
+  tables; agent-built specs reintroduce the drift this phase exists to kill.
+- Do not run `dotnet build` from this skill — the runtime gate
+  (`verifyCoreFoundationSeed` + `dotnet build`) runs after your phase ends.
+- Do not add navigation / roles / permissions inline into module-specific
+  seed providers in Phase 1. Phase 1's `scaffold-seed` is for **reference
+  data only** (lookup tables, enum codes), placed under
+  `Seeding/Applications/{AppPascal}/Modules/{ModuleCode}/`.
+
+## Spec contract — what the CLI consumes
+
+See `cli/scaffold-core-seed/types.ts` for the full Zod schema. The shape is:
+
+```jsonc
+{
+  "appCode": "TestV2",                  // PascalCase — used in src/{AppCode}.Infrastructure/...
+  "projectPath": "/path/to/target/app",
+  "applications": [
+    {
+      "code": "crm",                    // kebab-case — must equal the application-level nav entry
+      "modules": ["contacts", "prospecting"],   // gate verifies each is covered
+      "navigation": [
+        { "level": "application", "code": "crm", "label": "CRM", "route": "/crm" },
+        { "level": "module", "code": "contacts", "parentCode": "crm", "label": "Contacts", "route": "/crm/contacts" },
+        { "level": "section", "code": "directory", "parentCode": "contacts", "label": "Directory", "route": "/crm/contacts/directory" }
+      ],
+      "roles": [
+        { "code": "admin", "name": "Administrator", "applicationCode": "crm", "isDefault": false }
+      ],
+      "permissions": [
+        { "path": "crm.contacts.directory.access", "action": "access", "sectionCode": "directory" },
+        { "path": "crm.contacts.directory.read",   "action": "read",   "sectionCode": "directory" }
+      ],
+      "rolePermissions": [
+        { "roleCode": "admin", "permissionPath": "crm.contacts.directory.access" }
+      ],
+      "testUsers": [{ "roleCode": "admin" }]
+    },
+    {
+      "code": "budgeting",
+      "modules": ["budget"],
+      "navigation": [/* … */],
+      "roles": [/* … */],
+      "permissions": [/* … */],
+      "rolePermissions": [/* … */],
+      "testUsers": [/* … */]
+    }
+  ],
+  "testUserPassword": "DevTest!2026Secure",
+  "testUserEmailDomain": "smartstack.local",
+  "emitDevCredentialsManifest": true
+}
+```
+
+## Output structure (in the target app)
+
+```
+src/{AppCode}.Infrastructure/
+├── DependencyInjection.cs              ← patched: one block per app
+└── Persistence/Seeding/Applications/
+    ├── {AppPascalA}/Core/
+    │   ├── {AppPascalA}CoreNavigationSeedDataProvider.cs       (Order = 10)
+    │   ├── {AppPascalA}CoreRolesSeedDataProvider.cs            (Order = 20)
+    │   ├── {AppPascalA}CorePermissionsSeedDataProvider.cs      (Order = 30)
+    │   ├── {AppPascalA}CoreRolePermissionsSeedDataProvider.cs  (Order = 40)
+    │   └── {AppPascalA}CoreTestUsersSeedDataProvider.cs        (Order = 50, IsDevelopment-gated)
+    └── {AppPascalB}/Core/
+        └── (5 more, prefixed with {AppPascalB}…)
+```
+
+C# namespaces are scoped per app:
+`{AppCode}.Infrastructure.Persistence.Seeding.Applications.{AppPascal}.Core`.
+
+## Idempotence — safe to re-run
+
+GUIDs are deterministic (`Guid.Parse` with stable hash keys derived from
+`nav:{appCode}:{level}:{code}`), so re-running the CLI does NOT churn
+database row IDs. The DI patch uses `<<< CORE-SEED-DI-{AppPascal} BEGIN/END >>>`
+markers (one pair per application) — each block is replaced wholesale on
+re-runs without touching surrounding registrations or other apps' blocks.
+
+## Invocation summary
+
+```bash
+npx tsx skills/development/backend/core-seed/cli/scaffold-core-seed/index.ts \
+  --spec-file /tmp/core-seed-spec-<runId>.json \
+  --outdir /path/to/target/app
+```
+
+Optional: `--dry-run` prints what would be generated without writing.

package/templates/skills/development/backend/core-seed/cli/scaffold-core-seed/__tests__/build-spec.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { buildCoreSeedSpec, type BuildCoreSeedSpecInput } from '../build-spec.js';
+
+function baseInput(): BuildCoreSeedSpecInput {
+  return {
+    appCode: 'TestV2',
+    projectPath: '/tmp/x',
+    applications: [{ code: 'crm', label: 'CRM' }],
+    modules: [
+      { code: 'contacts', label: 'Contacts', applicationCode: 'crm' },
+      { code: 'budgeting', label: 'Budget', applicationCode: 'crm' },
+    ],
+    sections: [
+      { code: 'directory', label: 'Annuaire', moduleCode: 'contacts' },
+      { code: 'overview', label: 'Vue d\'ensemble', moduleCode: 'budgeting' },
+    ],
+    resources: [],
+    actors: [
+      { code: 'admin', name: 'Administrator', applicationCode: 'crm' },
+      { code: 'commercial', name: 'Commercial', applicationCode: 'crm', isDefault: true },
+    ],
+    permissions: [
+      { path: 'crm.contacts.directory.access', roles: ['admin'] },
+      { path: 'crm.contacts.directory.read', roles: ['admin', 'commercial'] },
+      { path: 'crm.budgeting.overview.access', roles: ['admin'] },
+      { path: 'crm.budgeting.overview.read', roles: ['admin'] },
+    ],
+  };
+}
+
+function multiAppInput(): BuildCoreSeedSpecInput {
+  return {
+    appCode: 'TestV2',
+    projectPath: '/tmp/x',
+    applications: [
+      { code: 'crm', label: 'CRM' },
+      { code: 'budgeting', label: 'Budget' },
+    ],
+    modules: [
+      { code: 'contacts', label: 'Contacts', applicationCode: 'crm' },
+      { code: 'budget', label: 'Budget', applicationCode: 'budgeting' },
+    ],
+    sections: [
+      { code: 'directory', label: 'Annuaire', moduleCode: 'contacts' },
+      { code: 'overview', label: 'Vue d\'ensemble', moduleCode: 'budget' },
+    ],
+    resources: [],
+    actors: [
+      { code: 'admin', name: 'Administrator', applicationCode: 'crm' },
+      { code: 'controller', name: 'Controller', applicationCode: 'budgeting' },
+    ],
+    permissions: [
+      { path: 'crm.contacts.directory.access', roles: ['admin'] },
+      { path: 'crm.contacts.directory.read', roles: ['admin'] },
+      { path: 'budgeting.budget.overview.access', roles: ['controller'] },
+      { path: 'budgeting.budget.overview.read', roles: ['controller'] },
+    ],
+  };
+}
+
+describe('buildCoreSeedSpec', () => {
+  it('produces one ApplicationSpec per declared application', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    expect(spec.applications).toHaveLength(1);
+    expect(spec.applications[0].code).toBe('crm');
+  });
+
+  it('flattens applications + modules + sections + resources into the per-app navigation array', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    const levels = spec.applications[0].navigation.map((n) => n.level);
+    expect(levels).toEqual(['application', 'module', 'module', 'section', 'section']);
+  });
+
+  it('extracts modules[] for the gate from input.modules (deduped)', () => {
+    const input = baseInput();
+    input.modules.push({ code: 'contacts', label: 'Contacts (dup)', applicationCode: 'crm' });
+    const spec = buildCoreSeedSpec(input);
+    expect(spec.applications[0].modules).toEqual(['contacts', 'budgeting']);
+  });
+
+  it('parses 4-segment permission paths into action + sectionCode', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    expect(spec.applications[0].permissions).toHaveLength(4);
+    expect(spec.applications[0].permissions[0]).toEqual({
+      path: 'crm.contacts.directory.access',
+      action: 'access',
+      sectionCode: 'directory',
+    });
+  });
+
+  it('expands each permission.roles[] into a role-permission mapping (per app)', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    const directoryRead = spec.applications[0].rolePermissions.filter(
+      (rp) => rp.permissionPath === 'crm.contacts.directory.read',
+    );
+    expect(directoryRead).toHaveLength(2);
+    expect(directoryRead.map((rp) => rp.roleCode).sort()).toEqual(['admin', 'commercial']);
+  });
+
+  it('drops permissions with malformed paths instead of throwing', () => {
+    const input = baseInput();
+    input.permissions.push({ path: 'broken.path', roles: ['admin'] });
+    const spec = buildCoreSeedSpec(input);
+    expect(spec.applications[0].permissions.find((p) => p.path === 'broken.path')).toBeUndefined();
+  });
+
+  it('emits one test user per actor (Phase 5 RBAC needs one per role)', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    expect(spec.applications[0].testUsers).toHaveLength(2);
+    expect(spec.applications[0].testUsers.map((tu) => tu.roleCode)).toEqual(['admin', 'commercial']);
+  });
+
+  it('defaults icon/iconType/route fields when the input is sparse', () => {
+    const spec = buildCoreSeedSpec(baseInput());
+    const moduleEntry = spec.applications[0].navigation.find((n) => n.code === 'contacts')!;
+    expect(moduleEntry.icon).toBe('Circle');
+    expect(moduleEntry.iconType).toBe('Lucide');
+    expect(moduleEntry.route).toBe('/crm/contacts');
+  });
+
+  it('passes through testUserPassword and testUserEmailDomain overrides', () => {
+    const input = { ...baseInput(), testUserPassword: 'CustomPass!2026', testUserEmailDomain: 'example.local' };
+    const spec = buildCoreSeedSpec(input);
+    expect(spec.testUserPassword).toBe('CustomPass!2026');
+    expect(spec.testUserEmailDomain).toBe('example.local');
+  });
+
+  it('groups modules + actors + permissions by their owning application (multi-app)', () => {
+    const spec = buildCoreSeedSpec(multiAppInput());
+    expect(spec.applications).toHaveLength(2);
+
+    const crm = spec.applications.find((a) => a.code === 'crm')!;
+    const budgeting = spec.applications.find((a) => a.code === 'budgeting')!;
+
+    expect(crm.modules).toEqual(['contacts']);
+    expect(crm.roles.map((r) => r.code)).toEqual(['admin']);
+    expect(crm.permissions.map((p) => p.path)).toEqual([
+      'crm.contacts.directory.access',
+      'crm.contacts.directory.read',
+    ]);
+
+    expect(budgeting.modules).toEqual(['budget']);
+    expect(budgeting.roles.map((r) => r.code)).toEqual(['controller']);
+    expect(budgeting.permissions.map((p) => p.path)).toEqual([
+      'budgeting.budget.overview.access',
+      'budgeting.budget.overview.read',
+    ]);
+  });
+
+  it('does not leak permissions across apps when section codes happen to repeat across apps', () => {
+    // Edge case: two apps both have a section called "overview". The builder
+    // must use the section→module→app chain to attribute permissions correctly,
+    // not just the section code.
+    const input = multiAppInput();
+    input.sections.push({ code: 'overview', label: 'CRM Overview', moduleCode: 'contacts' });
+    input.permissions.push({ path: 'crm.contacts.overview.read', roles: ['admin'] });
+    const spec = buildCoreSeedSpec(input);
+    const crm = spec.applications.find((a) => a.code === 'crm')!;
+    const budgeting = spec.applications.find((a) => a.code === 'budgeting')!;
+    expect(crm.permissions.find((p) => p.path === 'crm.contacts.overview.read')).toBeDefined();
+    expect(budgeting.permissions.find((p) => p.path === 'crm.contacts.overview.read')).toBeUndefined();
+  });
+});