@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/testing/smoke-http/cli/smoke-http/index.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * smoke-http/index.ts — Entry point.
+ * parse args → validate → execute probes → print JSON report on stdout.
+ */
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { validateArgs } from './validate.js';
+import { execute } from './execute.js';
+import type { SmokeHttpOutput } from './types.js';
+
+const program = new Command();
+
+program
+  .name('smoke-http')
+  .description('HTTP smoke prober — fetches a list of URLs and reports pass/fail status codes')
+  .option('--probes <json>', 'Inline JSON array of probes')
+  .option('--probes-file <path>', 'Path to a JSON file containing the probes array')
+  .option('--timeout-ms <ms>', 'Per-probe timeout', '5000')
+  .option('--retries <n>', 'Retry attempts per probe', '10')
+  .option('--retry-delay-ms <ms>', 'Base delay between retries', '500')
+  .option('--follow-redirects <bool>', 'Follow 3xx redirects', 'true')
+  .option('--concurrency <n>', 'Parallel probe count', '4')
+  .parse(process.argv);
+
+const opts = program.opts();
+
+function fail(errors: string[], exitCode = 1): never {
+  const output: SmokeHttpOutput = {
+    success: false,
+    command: 'smoke-http',
+    data: { totalProbes: 0, passed: 0, failed: 0, allPassed: false },
+    report: null,
+    errors,
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(exitCode);
+}
+
+let probesRaw: unknown;
+if (opts.probes && opts.probesFile) {
+  fail(['pass either --probes (inline) or --probes-file, not both.']);
+}
+if (opts.probes) {
+  try {
+    probesRaw = JSON.parse(opts.probes);
+  } catch (err) {
+    fail([`--probes is not valid JSON: ${err instanceof Error ? err.message : String(err)}`]);
+  }
+} else if (opts.probesFile) {
+  try {
+    probesRaw = JSON.parse(readFileSync(opts.probesFile, 'utf8'));
+  } catch (err) {
+    fail([`Failed to read/parse --probes-file: ${err instanceof Error ? err.message : String(err)}`]);
+  }
+} else {
+  fail(['Missing probes. Pass --probes <json> or --probes-file <path>.']);
+}
+
+const raw = {
+  probes: probesRaw,
+  timeoutMs: Number(opts.timeoutMs),
+  retries: Number(opts.retries),
+  retryDelayMs: Number(opts.retryDelayMs),
+  followRedirects: opts.followRedirects !== 'false',
+  concurrency: Number(opts.concurrency),
+};
+
+const validation = validateArgs(raw);
+if (!validation.valid || !validation.args) {
+  fail(validation.errors);
+}
+
+try {
+  const report = await execute(validation.args!);
+  const passed = report.results.filter((r) => r.status === 'pass').length;
+  const failed = report.results.filter((r) => r.status === 'fail').length;
+  const allPassed = failed === 0;
+
+  const nextSteps: string[] = [];
+  if (!allPassed) {
+    nextSteps.push(
+      `${failed} probe${failed > 1 ? 's' : ''} failed. Inspect the report and run fix-bug on the failing endpoint(s).`,
+    );
+    for (const r of report.results.filter((x) => x.status === 'fail')) {
+      nextSteps.push(`  - ${r.method} ${r.url} expected ${r.expect} got ${r.actual ?? 'no response'}`);
+    }
+  } else {
+    nextSteps.push(`All ${passed} probe(s) passed.`);
+  }
+
+  const output: SmokeHttpOutput = {
+    success: true,
+    command: 'smoke-http',
+    data: {
+      totalProbes: report.results.length,
+      passed,
+      failed,
+      allPassed,
+    },
+    report,
+    errors: [],
+    warnings: [],
+    nextSteps,
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(allPassed ? 0 : 1);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  fail([`Unexpected error during probe execution: ${message}`]);
+}

package/templates/skills/development/testing/smoke-http/cli/smoke-http/types.ts

@@ -0,0 +1,62 @@
+/**
+ * smoke-http/types.ts — CLI args + probe + report shape for the HTTP smoke prober.
+ */
+import { z } from 'zod';
+
+export const ProbeSchema = z.object({
+  url: z.string().url(),
+  expect: z.number().int().min(100).max(599).default(200),
+  method: z.enum(['GET', 'HEAD']).default('GET'),
+  label: z.string().optional(),
+});
+
+export type Probe = z.infer<typeof ProbeSchema>;
+
+export const SmokeHttpArgsSchema = z.object({
+  probes: z.array(ProbeSchema).min(1),
+  timeoutMs: z.number().int().min(100).max(60_000).default(5000),
+  retries: z.number().int().min(1).max(50).default(10),
+  retryDelayMs: z.number().int().min(50).max(10_000).default(500),
+  followRedirects: z.boolean().default(true),
+  concurrency: z.number().int().min(1).max(32).default(4),
+});
+
+export type SmokeHttpArgs = z.infer<typeof SmokeHttpArgsSchema>;
+
+// ─── Report ───────────────────────────────────────────────────────────────
+
+export type ProbeStatus = 'pass' | 'fail';
+
+export interface ProbeResult {
+  url: string;
+  label: string | null;
+  method: 'GET' | 'HEAD';
+  expect: number;
+  actual: number | null;
+  attempts: number;
+  durationMs: number;
+  status: ProbeStatus;
+  error?: string;
+  redirectChain?: string[];
+}
+
+export interface SmokeHttpReport {
+  results: ProbeResult[];
+}
+
+// ─── Output envelope ──────────────────────────────────────────────────────
+
+export interface SmokeHttpOutput {
+  success: boolean;
+  command: 'smoke-http';
+  data: {
+    totalProbes: number;
+    passed: number;
+    failed: number;
+    allPassed: boolean;
+  };
+  report: SmokeHttpReport | null;
+  errors: string[];
+  warnings: string[];
+  nextSteps: string[];
+}

package/templates/skills/development/testing/smoke-http/cli/smoke-http/validate.ts

@@ -0,0 +1,36 @@
+/**
+ * smoke-http/validate.ts — Args validation (Zod only — no I/O).
+ */
+import { SmokeHttpArgsSchema, type SmokeHttpArgs } from './types.js';
+
+export interface ArgsValidationResult {
+  valid: boolean;
+  args: SmokeHttpArgs | null;
+  errors: string[];
+}
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = SmokeHttpArgsSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      valid: false,
+      args: null,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+    };
+  }
+
+  const args = parsed.data;
+  const errors: string[] = [];
+
+  // Probes with duplicate URLs are probably a user mistake — warn (but not block).
+  const seen = new Set<string>();
+  for (const p of args.probes) {
+    const key = `${p.method} ${p.url}`;
+    if (seen.has(key)) {
+      errors.push(`duplicate probe: ${key} — each URL+method combo should appear once.`);
+    }
+    seen.add(key);
+  }
+
+  return { valid: errors.length === 0, args, errors };
+}

package/templates/skills/development/testing/ui-test/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: development-testing-ui-test
+description: >
+  Phase 5 UI tests — drives dev-browser to navigate every scaffolded page,
+  submit forms with role-based seeded users, and auto-correct failures via
+  the existing fix-bug skill loop (max 50 iterations per test). Runs after
+  the frontend scaffolders complete (routes + component + api-client +
+  extension-config) and verifies the full backend ↔ frontend round-trip.
+phase: development/testing
+cli: cli/run-ui-test
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Phase 5 — UI Test (dev-browser, auto-correction)
+
+After Phase 4 (seed-data) and Phase 4f (frontend scaffolders), Phase 5 verifies
+that every page actually works with a real backend, real users, and real DB.
+The previous phases produce code that COMPILES; Phase 5 ensures it RUNS.
+
+## When to use
+
+- Right after `scaffold-component` + `scaffold-routes` + `scaffold-api-client`
+  finish for a module
+- Whenever the user reports "the new page doesn't work" — Phase 5 reproduces
+  + auto-fixes most 400/401/403/404/500/blank-page bugs
+- Before announcing a module as "done"
+
+## Prerequisites
+
+1. **dev-runner is running** — backend + frontend must be live. The CLI does
+   NOT spawn them (that's `dev-runner.ts`'s job). It pings `/health` first
+   and fails clear if either is down.
+2. **`tests/ui-test/test-users.json` exists** — produced by `scaffold-seed`
+   when `testUsers[]` is non-empty. One user per role.
+3. **`tests/ui-test/manifest.json` exists** — produced by `build-manifest` from
+   the same spec that drove scaffold-controller + scaffold-component. Lists
+   one test per (entity × scenario × role) tuple.
+4. **`dev-browser` installed** — `npm install --save-dev dev-browser@0.2.7
+   && npx dev-browser install` (downloads bundled Chromium via Playwright).
+
+## Two CLIs in this skill
+
+### `cli/build-manifest/` (generate sub-pattern)
+
+Reads a self-contained spec (entities + roles per scenario + fixtures) and
+emits `tests/ui-test/manifest.json`. Invoke after frontend scaffolders for a
+module, before run-ui-test.
+
+```bash
+npx tsx skills/development/testing/ui-test/cli/build-manifest/index.ts \
+  --spec '{"module":"hrm","appCode":"myapp","projectPath":"/abs/path","entities":[
+    {"name":"Employee","section":"employees","plural":"employees",
+     "rolesWithRead":["admin","manager"],
+     "rolesWithCreate":["admin"],
+     "rolesWithUpdate":["admin"],
+     "rolesWithDelete":["admin"],
+     "rolesWithoutAccess":["viewer"],
+     "fixture":{"firstName":"Alice","lastName":"Test","email":"alice@t.local"}}
+  ]}'
+```
+
+### `cli/run-ui-test/` (execute sub-pattern)
+
+Runs each test ONCE via `dev-browser --headless`, emits an envelope on stdout
+with all results. Auto-correction is NOT in this CLI — it lives in the Studio
+runner (`src/backend/application/runners/ui-test-runner.ts`) which wraps the
+CLI in a 50-iteration retry loop with `claude -p fix-bug` between iterations.
+
+```bash
+npx tsx skills/development/testing/ui-test/cli/run-ui-test/index.ts \
+  --project-path /abs/path \
+  --frontend-url http://localhost:5173 \
+  --api-url http://localhost:5142 \
+  --module hrm
+```
+
+## Auto-correction loop (Studio runner only)
+
+`runUiTestSession()` in `src/backend/application/runners/ui-test-runner.ts`:
+
+1. Spawn `run-ui-test` CLI for the whole manifest.
+2. For each failing test:
+   - Spawn `claude -p fix-bug` with the runtime capture (HTTP, console, screenshot path).
+   - Re-spawn the CLI with `--test-id <single>` to verify the fix.
+   - Loop until pass, OR same fix proposed 5× (convergence-fail), OR 50 iterations (max-iter).
+3. On convergence-fail or max-iter: auto-create a `StudioBug` with `source='ui-test'` + the runtime context. The existing audit-bug pipeline picks up the bug when the user clicks "Lancer l'audit".
+
+## Six scenarios
+
+Each entity × eligible role produces tests in these scenarios. Templates are at
+`cli/run-ui-test/templates/{scenario}.js.hbs`.
+
+| Scenario | What it does | Common failures it catches |
+|----------|--------------|----------------------------|
+| `list` | Login, navigate to list, assert no 4xx/5xx + table renders | Missing RolePermission, wrong API path, ComponentKey mismatch |
+| `detail` | Open list, click first row, assert detail loads | Wrong route param shape (`:id` vs `:slug`), broken detail loader |
+| `form-submit` | Open create form, fill fixture, submit, expect 201 | DTO validator mismatch, wrong POST path, missing form-field testIds |
+| `edit` | Open list, click edit row, modify field, submit, expect 200/204 | Same as create + missing PUT route |
+| `delete` | Open list, click delete, confirm, expect 204 | Missing DELETE route, missing confirm testId |
+| `permission-negative` | Login as denied role, navigate, expect 403 OR PermissionGuard fallback | Permission constants applied to wrong role; PermissionGuard not wired |
+
+## data-testid contract
+
+Templates assume the component scaffolder emits these testIds. If a test fails
+with "selector not found", the scaffolder is missing a testId — fix the
+scaffolder, not the test.
+
+| Testid | Where | Required by |
+|--------|-------|-------------|
+| `login-email` / `login-password` / `login-submit` | login page | every scenario |
+| `{section}-list-table` | list page | list scenario |
+| `{section}-list-row` (per row) | list page | detail/edit/delete (clicks first row) |
+| `row-edit` (per row, inside) | list row | edit scenario |
+| `row-delete` (per row, inside) | list row | delete scenario |
+| `confirm-delete` | confirm modal | delete scenario |
+| `{section}-detail` | detail page | detail scenario |
+| `form-field-{key}` | create/edit form | form-submit/edit (per fixture key) |
+| `form-submit` | create/edit form | form-submit/edit |
+| `{section}-permission-denied` | guarded routes for denied roles | permission-negative |
+
+## Output → Studio UI
+
+The Studio's "UI Tests" pages (`/projects/:projectId/ui-tests` + run detail)
+display every run, every result, every iteration, with screenshots and
+iteration log. Live updates via `ui_test_*` broadcast events.
+
+Auto-bugs created from convergence-fail / max-iter appear in the existing
+bugs UI with `source='ui-test'` badge.

package/templates/skills/development/testing/ui-test/cli/build-manifest/generate.ts

@@ -0,0 +1,129 @@
+/**
+ * cli:build-manifest — generate.ts
+ *
+ * For each entity × role matrix, emit one test entry per scenario.
+ * Output: tests/ui-test/manifest.json (single file).
+ */
+import type {
+  BuildManifestInput,
+  ManifestEntity,
+  ManifestTest,
+  Manifest,
+  GeneratedFile,
+} from './types.js';
+
+export function generate(spec: BuildManifestInput): GeneratedFile[] {
+  const tests: ManifestTest[] = [];
+
+  for (const entity of spec.entities) {
+    tests.push(...buildEntityTests(spec, entity));
+  }
+
+  const manifest: Manifest = {
+    generatedAt: new Date().toISOString(),
+    module: spec.module,
+    appCode: spec.appCode,
+    tests,
+  };
+
+  return [
+    {
+      path: 'tests/ui-test/manifest.json',
+      content: JSON.stringify(manifest, null, 2) + '\n',
+    },
+  ];
+}
+
+function buildEntityTests(spec: BuildManifestInput, entity: ManifestEntity): ManifestTest[] {
+  const tests: ManifestTest[] = [];
+  const plural = entity.plural ?? entity.section;
+  const basePath = `/${spec.module}/${plural}`;
+  const idPlaceholder = '__detail_id__'; // resolved at runtime by the runner from list.first
+
+  // ─── List + smoke (one test per role with read) ────────
+  for (const role of entity.rolesWithRead) {
+    tests.push({
+      id: `${spec.module}.${entity.section}.list.${role}`,
+      scenario: 'list',
+      page: basePath,
+      role,
+      expectations: {
+        httpStatus: [200],
+        noConsoleError: true,
+        rendersTestId: `${entity.section}-list-table`,
+      },
+    });
+
+    tests.push({
+      id: `${spec.module}.${entity.section}.detail.${role}`,
+      scenario: 'detail',
+      page: `${basePath}/${idPlaceholder}`,
+      role,
+      expectations: {
+        httpStatus: [200],
+        noConsoleError: true,
+        rendersTestId: `${entity.section}-detail`,
+      },
+    });
+  }
+
+  // ─── Form-submit per role with create ──────────────────
+  for (const role of entity.rolesWithCreate) {
+    tests.push({
+      id: `${spec.module}.${entity.section}.create.${role}`,
+      scenario: 'form-submit',
+      page: `${basePath}/create`,
+      role,
+      fixture: entity.fixture,
+      expectations: {
+        httpStatus: [201, 200],
+        redirectsTo: `${basePath}/:id`,
+      },
+    });
+  }
+
+  // ─── Edit per role with update ──────────────────────────
+  for (const role of entity.rolesWithUpdate) {
+    tests.push({
+      id: `${spec.module}.${entity.section}.edit.${role}`,
+      scenario: 'edit',
+      page: `${basePath}/${idPlaceholder}/edit`,
+      role,
+      fixture: entity.fixture,
+      expectations: {
+        httpStatus: [200, 204],
+      },
+    });
+  }
+
+  // ─── Delete per role with delete ────────────────────────
+  for (const role of entity.rolesWithDelete) {
+    tests.push({
+      id: `${spec.module}.${entity.section}.delete.${role}`,
+      scenario: 'delete',
+      page: `${basePath}/${idPlaceholder}`,
+      role,
+      expectations: {
+        httpStatus: [204, 200],
+      },
+    });
+  }
+
+  // ─── Permission-negative per role without access ───────
+  for (const role of entity.rolesWithoutAccess) {
+    tests.push({
+      id: `${spec.module}.${entity.section}.list.${role}-denied`,
+      scenario: 'permission-negative',
+      page: basePath,
+      role,
+      expectations: {
+        // Either the API rejects with 403 OR the frontend PermissionGuard
+        // renders a denied placeholder. The template handles both.
+        httpStatus: [403],
+        rendersTestId: `${entity.section}-permission-denied`,
+      },
+    });
+  }
+
+  return tests;
+}

package/templates/skills/development/testing/ui-test/cli/build-manifest/index.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * cli:build-manifest — index.ts
+ *
+ * Reads a JSON spec on --spec and writes tests/ui-test/manifest.json under
+ * --project-path (defaults to cwd). Emits a SmartStack envelope on stdout.
+ */
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { validate } from './validate.js';
+import { generate } from './generate.js';
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../../../lib/output.js';
+
+const COMMAND = 'build-manifest';
+
+async function main(): Promise<void> {
+  const args = parseArgs({
+    options: {
+      spec: { type: 'string' },
+      'project-path': { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  if (!args.values.spec) {
+    printEnvelope(failGenerate(COMMAND, ['--spec is required (JSON string)']));
+    process.exit(2);
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(args.values.spec);
+  } catch (err) {
+    printEnvelope(failGenerate(COMMAND, [`--spec is not valid JSON: ${err instanceof Error ? err.message : err}`]));
+    process.exit(2);
+  }
+
+  const result = validate(raw);
+  if (!result.valid || !result.data) {
+    printEnvelope(failGenerate(COMMAND, result.errors));
+    process.exit(2);
+  }
+
+  const projectPath = args.values['project-path'] ?? result.data.projectPath;
+
+  const files = generate(result.data);
+  const created: string[] = [];
+
+  for (const f of files) {
+    const fullPath = path.resolve(projectPath, f.path);
+    if (args.values['dry-run']) {
+      created.push(`(dry) ${f.path}`);
+      continue;
+    }
+    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    await fs.writeFile(fullPath, f.content, 'utf8');
+    created.push(f.path);
+  }
+
+  const envelope = generateEnvelope(COMMAND, {
+    filesCreated: created,
+    warnings: result.warnings,
+    nextSteps: [
+      'Verify tests/ui-test/test-users.json exists (regenerate seed if not).',
+      'Run Phase 5: npx tsx skills/development/testing/ui-test/cli/run-ui-test/index.ts --project-path <path>',
+    ],
+    data: {
+      module: result.data.module,
+      testCount: files[0]?.content ? JSON.parse(files[0].content).tests.length : 0,
+    },
+  });
+  printEnvelope(envelope);
+}
+
+main().catch((err: unknown) => {
+  printEnvelope(failGenerate(COMMAND, [err instanceof Error ? err.message : String(err)]));
+  process.exit(1);
+});

package/templates/skills/development/testing/ui-test/cli/build-manifest/types.ts

@@ -0,0 +1,72 @@
+/**
+ * cli:build-manifest — types.ts
+ * Generates tests/ui-test/manifest.json consumed by Phase 5 run-ui-test.
+ *
+ * Input is a self-contained spec (one entity per CRUD pair). The CLI does NOT
+ * read the filesystem registry/controllers — the orchestrator passes the same
+ * data that drove scaffold-routes + scaffold-component + scaffold-controller.
+ */
+import { z } from 'zod';
+
+export const ManifestEntitySchema = z.object({
+  /** PascalCase singular, e.g. "Employee". */
+  name: z.string().min(1),
+  /** Section code matching the seeded section, e.g. "employees". */
+  section: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'section must be kebab-case'),
+  /** URL plural (kebab). Defaults to section. */
+  plural: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'plural must be kebab-case').optional(),
+  /** Roles allowed to read/list — produces positive list+detail tests. */
+  rolesWithRead: z.array(z.string().min(1)).default([]),
+  /** Roles allowed to create — produces form-submit tests. */
+  rolesWithCreate: z.array(z.string().min(1)).default([]),
+  /** Roles allowed to update — produces edit tests. */
+  rolesWithUpdate: z.array(z.string().min(1)).default([]),
+  /** Roles allowed to delete — produces delete tests. */
+  rolesWithDelete: z.array(z.string().min(1)).default([]),
+  /** Roles that should be DENIED — produces permission-negative tests. */
+  rolesWithoutAccess: z.array(z.string().min(1)).default([]),
+  /** Sample form data for create/edit scenarios. Fields must match the form. */
+  fixture: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({}),
+});
+
+export const BuildManifestInputSchema = z.object({
+  module: z.string().min(1),
+  appCode: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'appCode must be kebab-case'),
+  projectPath: z.string().min(1),
+  entities: z.array(ManifestEntitySchema).min(1, 'At least one entity required'),
+});
+
+export type ManifestEntity = z.infer<typeof ManifestEntitySchema>;
+export type BuildManifestInput = z.infer<typeof BuildManifestInputSchema>;
+
+export interface ManifestTest {
+  id: string;
+  scenario: 'list' | 'detail' | 'form-submit' | 'edit' | 'delete' | 'permission-negative';
+  page: string;
+  role: string;
+  fixture?: Record<string, unknown>;
+  expectations: {
+    httpStatus?: number[];
+    noConsoleError?: boolean;
+    rendersTestId?: string;
+    redirectsTo?: string;
+  };
+}
+
+export interface Manifest {
+  generatedAt: string;
+  module: string;
+  appCode: string;
+  tests: ManifestTest[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export interface GeneratedFile {
+  path: string;
+  content: string;
+}

package/templates/skills/development/testing/ui-test/cli/build-manifest/validate.ts

@@ -0,0 +1,44 @@
+/**
+ * cli:build-manifest — validate.ts
+ */
+import { BuildManifestInputSchema, type BuildManifestInput, type ValidationResult } from './types.js';
+
+export function validate(raw: unknown): ValidationResult & { data?: BuildManifestInput } {
+  const result = BuildManifestInputSchema.safeParse(raw);
+  if (!result.success) {
+    const errors = result.error.issues.map((i) => `[${i.path.join('.')}] ${i.message}`);
+    return { valid: false, errors, warnings: [] };
+  }
+
+  const spec = result.data;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  for (const e of spec.entities) {
+    const allRoles = new Set([
+      ...e.rolesWithRead,
+      ...e.rolesWithCreate,
+      ...e.rolesWithUpdate,
+      ...e.rolesWithDelete,
+      ...e.rolesWithoutAccess,
+    ]);
+
+    if (allRoles.size === 0) {
+      warnings.push(`Entity ${e.name} has no roles defined — no tests will be emitted for it.`);
+    }
+
+    if (e.rolesWithCreate.length > 0 && Object.keys(e.fixture).length === 0) {
+      warnings.push(`Entity ${e.name} has create roles but no fixture — form-submit tests will submit an empty form (likely fail validators).`);
+    }
+
+    // Sanity: rolesWithoutAccess shouldn't overlap with read roles
+    const readSet = new Set(e.rolesWithRead);
+    for (const role of e.rolesWithoutAccess) {
+      if (readSet.has(role)) {
+        errors.push(`Entity ${e.name}: role "${role}" is in both rolesWithRead and rolesWithoutAccess — pick one.`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings, data: spec };
+}