@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/development/testing/cli/test-report/execute.ts

@@ -0,0 +1,140 @@
+/**
+ * cli:test-report — execute.ts
+ * Runs test suites and produces a structured report.
+ */
+import { execSync } from 'node:child_process'
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import type { TestReportInput, TestReportResult, LayerResult, TestFailure } from './types.js'
+
+const BACKEND_CATEGORIES = ['Seed', 'Domain', 'Business', 'Integration']
+
+export function execute(input: TestReportInput): { report: TestReportResult; reportPath: string } {
+  const projectPath = resolve(input.projectPath)
+  const start = Date.now()
+  const byLayer: Record<string, LayerResult> = {}
+  const failures: TestFailure[] = []
+
+  // Run backend tests by category
+  if (input.includeBackend) {
+    for (const category of BACKEND_CATEGORIES) {
+      const result = runDotnetTests(projectPath, category)
+      byLayer[category.toLowerCase()] = result.layerResult
+      failures.push(...result.failures)
+    }
+  }
+
+  // Run frontend tests
+  if (input.includeFrontend) {
+    const result = runFrontendTests(projectPath, input.module)
+    byLayer['frontend'] = result.layerResult
+    failures.push(...result.failures)
+  }
+
+  // Aggregate summary
+  const summary = {
+    total: Object.values(byLayer).reduce((s, l) => s + l.total, 0),
+    passed: Object.values(byLayer).reduce((s, l) => s + l.passed, 0),
+    failed: Object.values(byLayer).reduce((s, l) => s + l.failed, 0),
+    skipped: Object.values(byLayer).reduce((s, l) => s + l.skipped, 0),
+  }
+
+  const report: TestReportResult = {
+    module: input.module,
+    timestamp: new Date().toISOString(),
+    duration: Date.now() - start,
+    summary,
+    byLayer,
+    failures,
+    coverage: { line: 0, branch: 0 }, // TODO: integrate with coverage tools
+  }
+
+  // Write report
+  const reportsDir = join(projectPath, '.ralph', 'reports')
+  mkdirSync(reportsDir, { recursive: true })
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+  const reportPath = join(reportsDir, `TEST-${input.module}-${ts}.json`)
+  writeFileSync(reportPath, JSON.stringify(report, null, 2), 'utf-8')
+
+  return { report, reportPath }
+}
+
+function runDotnetTests(projectPath: string, category: string): { layerResult: LayerResult; failures: TestFailure[] } {
+  try {
+    const output = execSync(
+      `dotnet test --no-build --filter Category=${category} --verbosity normal --logger "trx;LogFileName=${category}.trx"`,
+      { cwd: projectPath, encoding: 'utf-8', timeout: 300_000, stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+
+    // Parse test counts from output
+    const passed = parseInt(output.match(/Passed:\s+(\d+)/)?.[1] ?? '0')
+    const failed = parseInt(output.match(/Failed:\s+(\d+)/)?.[1] ?? '0')
+    const skipped = parseInt(output.match(/Skipped:\s+(\d+)/)?.[1] ?? '0')
+    const total = passed + failed + skipped
+
+    return {
+      layerResult: { total, passed, failed, skipped },
+      failures: [],
+    }
+  } catch (err: any) {
+    const output = (err.stdout ?? '') + (err.stderr ?? '')
+    const passed = parseInt(output.match(/Passed:\s+(\d+)/)?.[1] ?? '0')
+    const failed = parseInt(output.match(/Failed:\s+(\d+)/)?.[1] ?? '0')
+    const skipped = parseInt(output.match(/Skipped:\s+(\d+)/)?.[1] ?? '0')
+    const total = passed + failed + skipped
+
+    // Extract failure details
+    const failureMatches = output.matchAll(/Failed\s+(\S+)\s+\[.*?\]\s*\n\s*(.+)/g)
+    const failures: TestFailure[] = []
+    for (const match of failureMatches) {
+      failures.push({
+        test: match[1],
+        layer: category.toLowerCase(),
+        error: match[2]?.trim() ?? 'Unknown error',
+        file: '',
+      })
+    }
+
+    return {
+      layerResult: { total: Math.max(total, 1), passed, failed: Math.max(failed, 1), skipped },
+      failures,
+    }
+  }
+}
+
+function runFrontendTests(projectPath: string, module: string): { layerResult: LayerResult; failures: TestFailure[] } {
+  try {
+    const output = execSync(
+      `npm test -- --reporter=json --filter ${module}`,
+      { cwd: projectPath, encoding: 'utf-8', timeout: 300_000, stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+
+    // Attempt JSON parse of vitest output
+    try {
+      const json = JSON.parse(output)
+      const passed = json.numPassedTests ?? 0
+      const failed = json.numFailedTests ?? 0
+      const total = json.numTotalTests ?? passed + failed
+
+      return {
+        layerResult: { total, passed, failed, skipped: 0 },
+        failures: (json.testResults ?? [])
+          .filter((t: any) => t.status === 'failed')
+          .map((t: any) => ({
+            test: t.name ?? 'unknown',
+            layer: 'frontend',
+            error: t.message ?? 'Test failed',
+            file: t.file ?? '',
+          })),
+      }
+    } catch {
+      // Fallback: assume pass if exit 0
+      return { layerResult: { total: 1, passed: 1, failed: 0, skipped: 0 }, failures: [] }
+    }
+  } catch (err: any) {
+    return {
+      layerResult: { total: 1, passed: 0, failed: 1, skipped: 0 },
+      failures: [{ test: 'frontend-suite', layer: 'frontend', error: (err.stderr ?? 'Test suite failed').slice(0, 500), file: '' }],
+    }
+  }
+}

package/templates/skills/development/testing/cli/test-report/index.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * cli:test-report
+ * Responsabilité : Run tests and produce structured report
+ * Appelé par Claude Code via skill:development-testing
+ *
+ * Usage :
+ *   npx tsx skills/development/testing/cli/test-report/index.ts \
+ *     --spec '{"projectPath":"/path","module":"hrm"}'
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { execute } from './execute.js'
+import { executeEnvelope, failExecute, printEnvelope } from '../../../../lib/output.js'
+
+const COMMAND = 'test-report'
+
+function main(): void {
+  const { values } = parseArgs({
+    options: {
+      spec: { type: 'string' },
+    },
+    strict: true,
+  })
+
+  if (!values.spec) {
+    printEnvelope(failExecute(COMMAND, ['--spec is required']))
+    process.exit(1)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(values.spec)
+  } catch {
+    printEnvelope(failExecute(COMMAND, ['Invalid JSON in --spec']))
+    process.exit(1)
+  }
+
+  const validation = validate(raw)
+  if (!validation.valid) {
+    printEnvelope(failExecute(COMMAND, validation.errors))
+    process.exit(1)
+  }
+
+  try {
+    const { report, reportPath } = execute(raw as any)
+
+    // Studio UI event channel — separate from the envelope, parsed by the
+    // Studio renderer to update the live test panel without waiting for the
+    // CLI to exit.
+    console.log(JSON.stringify({
+      __studio_event__: 'test_report',
+      module: report.module,
+      summary: report.summary,
+      byLayer: report.byLayer,
+      failures: report.failures,
+    }))
+
+    const failed = report.summary.failed
+    printEnvelope({
+      ...(failed === 0
+        ? executeEnvelope(COMMAND, {
+            data: {
+              module: report.module,
+              total: report.summary.total,
+              passed: report.summary.passed,
+              failed,
+              skipped: report.summary.skipped,
+              reportPath,
+            },
+            report,
+            nextSteps: ['All tests passing. Proceed to next phase.'],
+          })
+        : {
+            ...failExecute(COMMAND, [`${failed} test(s) failed`]),
+            data: {
+              module: report.module,
+              total: report.summary.total,
+              passed: report.summary.passed,
+              failed,
+              skipped: report.summary.skipped,
+              reportPath,
+            },
+            report,
+            nextSteps: ['Fix failing tests and re-run'],
+          }),
+    })
+
+    process.exit(failed > 0 ? 1 : 0)
+  } catch (err) {
+    printEnvelope(failExecute(COMMAND, [`Internal error: ${err instanceof Error ? err.message : String(err)}`]))
+    process.exit(2)
+  }
+}
+
+main()

package/templates/skills/development/testing/cli/test-report/types.ts

@@ -0,0 +1,52 @@
+/**
+ * cli:test-report — types.ts
+ * Source de vérité unique : test report execution schemas
+ */
+import { z } from 'zod'
+
+export const TestReportInputSchema = z.object({
+  projectPath: z.string().min(1, 'Project path is required'),
+  module: z.string().min(1, 'Module name is required'),
+  includeBackend: z.boolean().default(true),
+  includeFrontend: z.boolean().default(true),
+})
+
+export type TestReportInput = z.infer<typeof TestReportInputSchema>
+
+export interface LayerResult {
+  total: number
+  passed: number
+  failed: number
+  skipped: number
+}
+
+export interface TestFailure {
+  test: string
+  layer: string
+  error: string
+  file: string
+}
+
+export interface TestReportResult {
+  module: string
+  timestamp: string
+  duration: number
+  summary: {
+    total: number
+    passed: number
+    failed: number
+    skipped: number
+  }
+  byLayer: Record<string, LayerResult>
+  failures: TestFailure[]
+  coverage: {
+    line: number
+    branch: number
+  }
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}

package/templates/skills/development/testing/cli/test-report/validate.ts

@@ -0,0 +1,26 @@
+/**
+ * cli:test-report — validate.ts
+ */
+import { TestReportInputSchema, type TestReportInput, type ValidationResult } from './types.js'
+import { existsSync } from 'node:fs'
+
+export function validateStructure(raw: unknown): ValidationResult {
+  const result = TestReportInputSchema.safeParse(raw)
+  if (result.success) return { valid: true, errors: [], warnings: [] }
+  const errors = result.error.issues.map(i => `[${i.path.join('.')}] ${i.message}`)
+  return { valid: false, errors, warnings: [] }
+}
+
+export function validateBusinessRules(spec: TestReportInput): ValidationResult {
+  const errors: string[] = []
+  if (!existsSync(spec.projectPath)) {
+    errors.push(`Project path not found: ${spec.projectPath}`)
+  }
+  return { valid: errors.length === 0, errors, warnings: [] }
+}
+
+export function validate(raw: unknown): ValidationResult {
+  const structural = validateStructure(raw)
+  if (!structural.valid) return structural
+  return validateBusinessRules(raw as TestReportInput)
+}

package/templates/skills/development/testing/fix-build/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: development-testing-fix-build
+description: >
+  Auto-correct a SINGLE compilation error surfaced by the Studio's Dev Runner
+  (dotnet CS####, tsc TS####, vite resolve). The caller provides one
+  `BuildError` with file/line/column/code/message. Your job is to apply the
+  MINIMUM patch to make that specific error go away, without refactoring
+  surrounding code. Invoked by `build-fix-runner.ts` in a retry loop (max 15
+  iterations, convergence guard, rebuild-and-reparse after each attempt).
+phase: development/testing
+cli: (none — invoked via `claude -p` from build-fix-runner)
+allowed-tools: [Read, Edit, Write, Glob, Grep, Bash]  # Bash: diagnostic commands
+---
+
+# Fix-Build — targeted single-error remediation
+
+You receive ONE compilation error from the Studio's Dev Runner. The goal is a
+precise patch, not a refactor.
+
+## Input contract
+
+The caller ships a `BUILD_ERROR_CONTEXT` block containing:
+
+```
+SOURCE: dotnet | tsc | vite
+CODE: CS0103 (or TS2322, VITE_IMPORT, ESBUILD, ...)
+FILE: <absolute path>
+LINE: <1-based>
+COLUMN: <1-based>
+MESSAGE: <raw compiler diagnostic>
+PREVIOUS_ATTEMPTS: <N>
+```
+
+Plus the current contents of the faulty file (or an excerpt around the error
+line) already loaded into your context.
+
+## Process
+
+1. **Read** the faulty file in full. Inspect the line reported + ±10 lines of
+   context.
+2. **Diagnose** — resolve the diagnostic into one of the usual suspects:
+   - `CS0103` (name not found) → missing using, typo, out-of-scope
+   - `CS1061` (missing member) → wrong type, missing property on DTO
+   - `CS0246` (type not found) → missing namespace/package reference
+   - `TS2322` (type mismatch) → narrow the value, adjust the destination type
+   - `TS2339` (property missing) → extend the interface OR use the correct property
+   - `VITE_IMPORT` / `ESBUILD` (resolve failure) → fix import path or create the missing file
+3. **Patch minimum** — touch only what's strictly necessary. Do NOT reformat,
+   reorder usings, rename variables, or fix adjacent unrelated warnings.
+4. **Do not add** new abstractions, base classes, or "cleaner" versions.
+5. **Commit** the change with a one-line message: `fix(build): <CODE> in <file>:<line>`.
+6. Emit a JSON envelope on stdout when done:
+
+   ```json
+   { "applied": true, "summary": "<one-liner>", "touched": ["<path>"] }
+   ```
+
+## Guardrails
+
+- If the error cannot be fixed in the target file alone (e.g. it requires
+  creating a new file or editing a dependency), say so in the JSON:
+  ```json
+  { "applied": false, "reason": "requires cross-file change not in scope" }
+  ```
+  and do NOT commit. The caller will escalate to a broader fix loop or
+  surface a `StudioBug`.
+- Never bypass compiler errors by casting to `any`, adding `#pragma warning
+  disable`, or commenting-out the faulty code. The patch must address the
+  root cause.
+- If the previous attempt count is ≥3, prefer a different approach than the
+  last one — re-reading the error message is a useful reset.
+
+## Tools allowed
+
+Read, Edit, Write, Glob, Grep, Bash (for `git add` + `git commit` only).
+
+## Not allowed
+
+- AskUserQuestion (fully autonomous loop)
+- Skill (don't recurse into other skills)
+- Background tasks

package/templates/skills/development/testing/smoke-http/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: smoke-http
+description: >
+  HTTP smoke prober for generated SmartStack applications. Given a list of URLs
+  (frontend routes + backend API endpoints), fetches each one, follows redirects,
+  applies retry-on-startup, and returns a JSON report of 200/non-200 results.
+  Invoked after Phase 4 of ba-develop to detect broken routes and
+  missing API endpoints before the user ever sees a 404 in the browser.
+phase: development/testing
+cli: smoke-http
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# smoke-http
+
+Fetches a list of URLs and reports which ones return the expected status code.
+Designed for the `frontend_smoke` gate after `ba-develop` Phase 4,
+but usable standalone to probe any app.
+
+## Contract
+
+The CLI is a pure HTTP prober. It does NOT:
+- spawn the app (the caller must ensure backend+frontend are running on the
+  probed ports),
+- interpret response bodies (only status codes + redirect chain),
+- know anything about SmartStack conventions beyond the JSON input shape.
+
+This keeps it composable: the Studio's `ba-prd-develop-handlers` wires
+`dev-runner.ts testPorts={api:7030, frontend:9030}` then calls this CLI with
+the URL list derived from the PRD.
+
+## When to use
+
+- **Gate after Phase 4** of ba-develop: the Studio has spawned
+  the generated app on ports 7030/9030 and wants to verify every route + API
+  endpoint advertised in the PRD actually responds.
+- **Regression probe**: after any change to navigation or routing, re-run on
+  the existing app to ensure nothing broke.
+- **Standalone smoke**: any CI pipeline wanting a tiny URL reachability
+  check — no Playwright/browser involved.
+
+## Invocation
+
+```bash
+npx tsx skills/development/testing/smoke-http/cli/smoke-http/index.ts \
+  --probes '[
+    { "url": "http://localhost:9030/", "expect": 200 },
+    { "url": "http://localhost:9030/crm/prospection/", "expect": 200 },
+    { "url": "http://localhost:7030/api/prospects", "expect": 200 }
+  ]' \
+  --timeout-ms 5000 \
+  --retries 10 \
+  --retry-delay-ms 500
+```
+
+Or load the probes from a file (`--probes-file probes.json`) when the JSON is large.
+
+## Arguments
+
+| Arg | Type | Required | Default | Description |
+|-----|------|----------|---------|-------------|
+| `--probes` | JSON string | one of | — | Inline array of probe objects. |
+| `--probes-file` | string path | one of | — | Path to a JSON file containing an array of probes. |
+| `--timeout-ms` | integer | no | `5000` | Per-probe request timeout. |
+| `--retries` | integer | no | `10` | How many times to retry a failing probe. Useful for app boot. |
+| `--retry-delay-ms` | integer | no | `500` | Delay between retries (with exponential back-off from attempt 3). |
+| `--follow-redirects` | boolean | no | `true` | Whether to follow 3xx redirects (up to 5 hops). |
+| `--concurrency` | integer | no | `4` | How many probes to run in parallel. |
+
+## Probe shape
+
+```typescript
+{
+  "url": string,            // required — full URL including scheme + port
+  "expect"?: number,        // default 200
+  "method"?: "GET" | "HEAD", // default GET — HEAD avoids transferring bodies for static assets
+  "label"?: string           // optional human-readable label for the report
+}
+```
+
+## Output envelope
+
+```json
+{
+  "success": true,
+  "command": "smoke-http",
+  "data": {
+    "totalProbes": 3,
+    "passed": 2,
+    "failed": 1,
+    "allPassed": false
+  },
+  "report": {
+    "results": [
+      { "url": "http://localhost:9030/", "label": null, "expect": 200, "actual": 200, "attempts": 1, "durationMs": 43, "status": "pass" },
+      { "url": "http://localhost:9030/crm/prospection/", "label": null, "expect": 200, "actual": 200, "attempts": 3, "durationMs": 2110, "status": "pass" },
+      { "url": "http://localhost:7030/api/prospects", "label": null, "expect": 200, "actual": 404, "attempts": 10, "durationMs": 4800, "status": "fail", "error": "expected 200 got 404" }
+    ]
+  },
+  "errors": [],
+  "warnings": [],
+  "nextSteps": [
+    "1 probe failed. Inspect the report and run fix-bug on the failing endpoint(s)."
+  ]
+}
+```
+
+Exit code: `0` if all probes pass, `1` otherwise.
+
+## Retry heuristic
+
+- Attempts 1–2: immediate retry after `retryDelayMs` — catches race conditions during app boot.
+- Attempts 3–N: exponential back-off (`delay * 2^(attempt-2)`, capped at 30 s).
+- A probe is considered failed when all N retries exhaust without a matching
+  status code. Errors thrown (network refused, DNS failure, timeout) count as
+  retries; no special treatment.
+
+## Design constraints
+
+- No external HTTP library — uses `fetch` (Node ≥18 native).
+- No Playwright / browser involvement — this is a pure reachability probe,
+  not a UI test (ui-test covers browser scenarios).
+- Stateless: one invocation = one report, no daemon mode.

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

@@ -0,0 +1,129 @@
+/**
+ * smoke-http/execute.ts — Run probes with retry/back-off, return a report.
+ *
+ * Uses native Node 18+ fetch — no external HTTP lib. Probes execute with
+ * bounded concurrency. Timeout enforced per-attempt via AbortController.
+ * Retry policy: immediate for attempts 1-2, exponential back-off from 3+.
+ */
+import type {
+  Probe,
+  ProbeResult,
+  SmokeHttpArgs,
+  SmokeHttpReport,
+} from './types.js';
+
+// ─── Single probe with retry ──────────────────────────────────────────────
+
+async function probeOnce(
+  probe: Probe,
+  timeoutMs: number,
+  followRedirects: boolean,
+): Promise<{ status: number | null; error?: string; redirectChain: string[] }> {
+  const redirectChain: string[] = [];
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetch(probe.url, {
+      method: probe.method,
+      signal: controller.signal,
+      redirect: followRedirects ? 'follow' : 'manual',
+    });
+    if (res.redirected) {
+      redirectChain.push(res.url);
+    }
+    return { status: res.status, redirectChain };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { status: null, error: msg, redirectChain };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function probeWithRetry(
+  probe: Probe,
+  args: SmokeHttpArgs,
+): Promise<ProbeResult> {
+  const start = Date.now();
+  let attempts = 0;
+  let lastStatus: number | null = null;
+  let lastError: string | undefined;
+  let redirectChain: string[] = [];
+
+  while (attempts < args.retries) {
+    attempts++;
+    const result = await probeOnce(probe, args.timeoutMs, args.followRedirects);
+    lastStatus = result.status;
+    lastError = result.error;
+    redirectChain = result.redirectChain;
+
+    if (lastStatus === probe.expect) {
+      return {
+        url: probe.url,
+        label: probe.label ?? null,
+        method: probe.method,
+        expect: probe.expect,
+        actual: lastStatus,
+        attempts,
+        durationMs: Date.now() - start,
+        status: 'pass',
+        redirectChain: redirectChain.length > 0 ? redirectChain : undefined,
+      };
+    }
+
+    // Back-off: immediate for attempts 1-2, exponential from 3+.
+    if (attempts < args.retries) {
+      const base = args.retryDelayMs;
+      const delay = attempts <= 2 ? base : Math.min(base * Math.pow(2, attempts - 2), 30_000);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+
+  return {
+    url: probe.url,
+    label: probe.label ?? null,
+    method: probe.method,
+    expect: probe.expect,
+    actual: lastStatus,
+    attempts,
+    durationMs: Date.now() - start,
+    status: 'fail',
+    error: lastError ?? `expected ${probe.expect} got ${lastStatus ?? 'no response'}`,
+    redirectChain: redirectChain.length > 0 ? redirectChain : undefined,
+  };
+}
+
+// ─── Bounded concurrency runner ───────────────────────────────────────────
+
+async function runWithConcurrency<T, R>(
+  items: T[],
+  concurrency: number,
+  worker: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let next = 0;
+
+  async function loop() {
+    while (true) {
+      const idx = next++;
+      if (idx >= items.length) return;
+      results[idx] = await worker(items[idx]);
+    }
+  }
+
+  const loops = Array.from({ length: Math.min(concurrency, items.length) }, () => loop());
+  await Promise.all(loops);
+  return results;
+}
+
+// ─── Entry point ──────────────────────────────────────────────────────────
+
+export async function execute(args: SmokeHttpArgs): Promise<SmokeHttpReport> {
+  const results = await runWithConcurrency(
+    args.probes,
+    args.concurrency,
+    (probe) => probeWithRetry(probe, args),
+  );
+  return { results };
+}