@atlashub/smartstack-cli 4.80.0 → 5.0.0

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

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * audit-dev-frontend/index.ts — Entry point.
+ *
+ * parse args → validate → dispatch to audit() or apply() → print envelope → exit code.
+ *
+ * Exit code: 0 if no `err` findings remain (after apply pass); 1 otherwise.
+ *
+ * Invoked by Claude (orchestrator subagent) via Bash. The Studio audit-reports
+ * UI also reads the `auditReport` field of the envelope to render rule checks.
+ */
+import { Command } from 'commander';
+import { validateArgs } from './validate.js';
+import { audit } from './audit.js';
+import { apply } from './apply.js';
+import type {
+  AuditDevFrontendMode,
+  AuditDevFrontendOutput,
+  Finding,
+} from './types.js';
+
+const program = new Command();
+
+program
+  .name('audit-dev-frontend')
+  .description('Audit / apply UI conformity fixes against the PRD slice on a generated SmartStack web app')
+  .requiredOption('--project-path <path>', 'Absolute path to the generated web root (holds src/pages)')
+  .requiredOption('--mode <mode>', 'audit | apply', 'audit')
+  .requiredOption('--module-code <code>', 'Active module code')
+  .requiredOption('--app-code <code>', 'Active application code')
+  .option('--prd-slice <path>', 'Path to the PRD frontend slice JSON')
+  .option('--inventory <path>', 'Path to a pre-built inventory JSON (otherwise self-built from disk)')
+  .option('--rules <list>', 'Comma-separated rule codes (e.g. DEV-UI-001,DEV-UI-005). Default = all')
+  .option('--regenerate-threshold <n>', 'Pages with ≥ N errors get rebuilt from template in apply mode (default 3, 0 = disable)', '3')
+  .option('--backend-path <path>', 'Path to the .NET project root (for DEV-UI-011 controller scan)')
+  .option('--core-navigation-seed-path <path>', 'Path to CoreNavigationSeedDataProvider.cs (for DEV-UI-012)')
+  .parse(process.argv);
+
+const opts = program.opts();
+
+const raw = {
+  projectPath: opts.projectPath as string,
+  mode: opts.mode as AuditDevFrontendMode,
+  moduleCode: opts.moduleCode as string,
+  appCode: opts.appCode as string,
+  prdSlice: opts.prdSlice as string | undefined,
+  inventory: opts.inventory as string | undefined,
+  rules: typeof opts.rules === 'string'
+    ? opts.rules.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : [],
+  regenerateThreshold: Number(opts.regenerateThreshold ?? 3),
+  backendPath: opts.backendPath as string | undefined,
+  coreNavigationSeedPath: opts.coreNavigationSeedPath as string | undefined,
+};
+
+const validation = validateArgs(raw);
+if (!validation.valid || !validation.args) {
+  const output: AuditDevFrontendOutput = {
+    success: false,
+    command: 'audit-dev-frontend',
+    data: { mode: (raw.mode ?? 'audit'), rulesRun: [], valid: false },
+    report: null,
+    auditReport: null,
+    filesModified: [],
+    errors: validation.errors,
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}
+
+try {
+  const report = validation.args.mode === 'apply'
+    ? await apply(validation.args)
+    : await audit(validation.args);
+
+  const valid = report.counts.errors === 0;
+  const rulesRun = validation.args.rules.length > 0 ? validation.args.rules : Object.keys(report.byRule);
+
+  // Build the system-prompt-shaped audit report for Studio audit-reports UI.
+  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 frontend audit gate.`);
+    if (validation.args.mode === 'audit') {
+      const fixable = report.findings.filter((f) => f.autoFixable && f.severity === 'err').length;
+      if (fixable > 0) nextSteps.push(`Run with --mode apply to auto-fix ${fixable} mechanical issue(s).`);
+    }
+  }
+  if (validation.args.mode === 'apply' && 'fixesApplied' in report) {
+    nextSteps.push(`Applied ${report.fixesApplied} fix(es) across ${report.filesModified.length} file(s). Re-run --mode audit to verify.`);
+    if (report.fixesSkipped.length > 0) {
+      nextSteps.push(`${report.fixesSkipped.length} finding(s) auto-fixable but could not be rewritten (file parse / ambiguous context). Resolve manually.`);
+    }
+  }
+
+  const output: AuditDevFrontendOutput = {
+    success: true,
+    command: 'audit-dev-frontend',
+    data: { mode: validation.args.mode, rulesRun, valid },
+    report,
+    auditReport: {
+      scope: 'devFrontend',
+      applicationCode: validation.args.appCode,
+      moduleCode: validation.args.moduleCode,
+      findings: stripped,
+    },
+    filesModified: 'filesModified' in report ? report.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: AuditDevFrontendOutput = {
+    success: false,
+    command: 'audit-dev-frontend',
+    data: { mode: validation.args.mode, rulesRun: [], valid: false },
+    report: null,
+    auditReport: null,
+    filesModified: [],
+    errors: [`Unexpected error: ${message}`],
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}

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

@@ -0,0 +1,218 @@
+/**
+ * audit-dev-frontend/types.ts — CLI args + finding + report shapes.
+ *
+ * Two finding shapes coexist:
+ * - System-prompt envelope (code/label/params/solution) — what the Studio
+ *   audit-reports UI consumes. The CLI emits this verbatim inside auditReport.
+ * - CLI-internal extension (file/line/autoFixable/snippet) — used by apply.ts
+ *   to locate and rewrite. Stripped before the system-prompt envelope is built.
+ *
+ * Severity vocabulary matches the existing audit-dev-* skills: 'err'|'warn'|'ok'.
+ * 'ok' findings are emitted for passing rules so the UI shows green checks.
+ */
+import { z } from 'zod';
+
+export const AuditDevFrontendModeSchema = z.enum(['audit', 'apply']);
+export type AuditDevFrontendMode = z.infer<typeof AuditDevFrontendModeSchema>;
+
+export const AuditDevFrontendArgsSchema = z.object({
+  /** Absolute path to the generated SmartStack web root (holds src/pages). */
+  projectPath: z.string().min(1),
+  /** `audit` = report only ; `apply` = mechanical rewrite of fixable findings. */
+  mode: AuditDevFrontendModeSchema,
+  /** Path to the PRD frontend slice JSON (parsed structured form, not Markdown). */
+  prdSlice: z.string().optional(),
+  /** Path to a pre-built inventory JSON. If omitted, self-built from disk. */
+  inventory: z.string().optional(),
+  /** Active module code (PRD scope). */
+  moduleCode: z.string().min(1),
+  /** Active application code (PRD scope). */
+  appCode: z.string().min(1),
+  /** Subset of rule codes to run (e.g. ['DEV-UI-001','DEV-UI-005']). Empty = all. */
+  rules: z.array(z.string()).default([]),
+  /**
+   * Regeneration threshold — in `apply` mode, any *Page.tsx file with ≥ this
+   * many ERROR findings remaining after mechanical fixes is REBUILT from
+   * scaffold-component template (OVERWRITES). Default 3, 0 to disable.
+   */
+  regenerateThreshold: z.number().int().min(0).max(100).default(3),
+  /** Optional path to the .NET project root (for DEV-UI-011 controller scan). */
+  backendPath: z.string().optional(),
+  /** Optional path to Persistence/Seeding/Core/CoreNavigationSeedDataProvider.cs (for DEV-UI-012). */
+  coreNavigationSeedPath: z.string().optional(),
+});
+
+export type AuditDevFrontendArgs = z.infer<typeof AuditDevFrontendArgsSchema>;
+
+// ─── Finding ──────────────────────────────────────────────────────────────
+
+export type Severity = 'err' | 'warn' | 'ok';
+
+/**
+ * A single audit finding. The first half is the system-prompt envelope shape
+ * (consumed by Studio audit-reports UI). The second half is CLI-internal
+ * metadata used by apply.ts to locate and rewrite the file.
+ */
+export interface Finding {
+  // ─── System-prompt envelope shape (do not rename) ───
+  /** Always 'devFrontend' for this skill. */
+  dimension: 'devFrontend';
+  /** Rule code, e.g. 'DEV-UI-001'. */
+  code: string;
+  severity: Severity;
+  /** Display label, e.g. 'DEV_UI_001_err'. */
+  label: string;
+  /** Rule-specific data (rendered into the solution / UI). */
+  params: Record<string, unknown>;
+  /** Mandatory on err/warn — user-facing remediation. */
+  solution: string;
+  /** Optional skill name to delegate the fix to. */
+  fixSkill?: string;
+  /** Optional phase key to re-run. */
+  fixPhaseKey?: string;
+
+  // ─── CLI-internal extension (stripped before system-prompt envelope) ───
+  /** Relative file path (from projectPath) where the finding lives. Optional for cross-cutting findings. */
+  file?: string;
+  line?: number;
+  autoFixable: boolean;
+  /** Source context for apply.ts to locate the violation. */
+  snippet?: string;
+}
+
+// ─── Inventory ────────────────────────────────────────────────────────────
+
+export interface PageEntry {
+  /** Relative file path from projectPath, e.g. 'src/pages/crm/contacts/ContactListPage.tsx'. */
+  file: string;
+  /** Inferred entity name from filename (e.g. 'Contact', null if not a *Page.tsx). */
+  entity: string | null;
+  /** Inferred page kind (list, detail, form, dashboard, home). */
+  kind: 'list' | 'detail' | 'form' | 'create' | 'edit' | 'dashboard' | 'home' | 'other';
+}
+
+export interface RegistryEntry {
+  /** Relative file path from projectPath. */
+  file: string;
+  /** Component keys registered (e.g. 'crm.contacts.directory'). */
+  keys: string[];
+  /** Lazy import targets resolved against registry file location. */
+  imports: Array<{ key: string; importPath: string; resolvedAbsPath: string | null }>;
+}
+
+export interface FrontendInventory {
+  pages: PageEntry[];
+  registries: RegistryEntry[];
+  i18n: {
+    locales: string[];
+    namespaces: string[];
+  };
+}
+
+// ─── PRD slice (structured) ───────────────────────────────────────────────
+
+export interface PrdScreen {
+  code: string;
+  entity?: string;
+  kind?: string;
+  /** SmartComponent type (SmartListView, SmartForm, etc.) */
+  smartComponent?: string;
+}
+
+export interface PrdUseCase {
+  code: string;
+  /** Optional reference to the entity primarily handled by the use case. */
+  entity?: string;
+  /** Optional sequence of screen codes the user navigates through. */
+  screens?: string[];
+}
+
+export interface PrdBusinessRule {
+  code: string;
+  description: string;
+  /** Where the rule must be enforced. 'ui' or 'both' means a UI-side check is mandatory. */
+  enforcedAt?: 'ui' | 'backend' | 'both';
+  /** Entity primarily affected (used to locate the form page). */
+  entity?: string;
+  validExamples?: unknown[];
+  invalidExamples?: unknown[];
+}
+
+export interface PrdPermission {
+  /** Permission key, e.g. 'crm.contacts.read'. */
+  code: string;
+  /** Optional related entity (used to map permission → page). */
+  entity?: string;
+  /** Optional related screen (used when entity-less). */
+  screen?: string;
+}
+
+export interface PrdRbacEntry {
+  /** Actor/role code, e.g. 'sales-rep'. */
+  actor: string;
+  /** Permission codes granted. */
+  grants: string[];
+}
+
+export interface PrdSliceFrontend {
+  applicationCode?: string;
+  moduleCode?: string;
+  screens?: PrdScreen[];
+  useCases?: PrdUseCase[];
+  businessRules?: PrdBusinessRule[];
+  permissions?: PrdPermission[];
+  rbac?: PrdRbacEntry[];
+}
+
+// ─── Reports ──────────────────────────────────────────────────────────────
+
+export interface AuditReport {
+  scope: 'devFrontend';
+  applicationCode: string;
+  moduleCode: string;
+  projectPath: string;
+  filesInspected: number;
+  findings: Finding[];
+  counts: { errors: number; warnings: number; oks: number };
+  byRule: Record<string, number>;
+}
+
+export interface ApplyReport extends AuditReport {
+  fixesApplied: number;
+  filesModified: string[];
+  fixesSkipped: Finding[];
+  regenerations?: Array<{ file: string; regenerated: boolean; reason: string }>;
+}
+
+// ─── Output envelope ──────────────────────────────────────────────────────
+
+/**
+ * The CLI prints this object on stdout. Two consumers:
+ * - Orchestrator (ba-develop subagent) reads `report.findings`
+ *   and decides whether the gate passes (counts.errors === 0 after apply).
+ * - Studio audit-reports UI reads `report.auditReport` (system-prompt-shaped)
+ *   to render green/red checks per rule.
+ *
+ * The two views are derived from the same internal `findings` array.
+ */
+export interface AuditDevFrontendOutput {
+  success: boolean;
+  command: 'audit-dev-frontend';
+  data: {
+    mode: AuditDevFrontendMode;
+    rulesRun: string[];
+    valid: boolean;
+  };
+  report: (AuditReport | ApplyReport) | null;
+  /** System-prompt-shaped envelope for Studio audit-reports UI. */
+  auditReport: {
+    scope: 'devFrontend';
+    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[];
+}

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

@@ -0,0 +1,80 @@
+/**
+ * audit-dev-frontend/validate.ts — Args validation (Zod + projectPath sanity check).
+ * No file I/O beyond verifying paths exist and look like the right shape.
+ */
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { AuditDevFrontendArgsSchema, type AuditDevFrontendArgs } from './types.js';
+
+export interface ArgsValidationResult {
+  valid: boolean;
+  args: AuditDevFrontendArgs | null;
+  errors: string[];
+}
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = AuditDevFrontendArgsSchema.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[] = [];
+
+  // projectPath must exist and contain a `src` directory.
+  const abs = path.resolve(args.projectPath);
+  if (!existsSync(abs)) {
+    errors.push(`projectPath does not exist: ${abs}`);
+  } else if (!statSync(abs).isDirectory()) {
+    errors.push(`projectPath is not a directory: ${abs}`);
+  } else if (!existsSync(path.join(abs, 'src'))) {
+    errors.push(`projectPath has no "src" folder — are you sure this is a React app root? ${abs}`);
+  }
+
+  // PRD slice path must exist if provided.
+  if (args.prdSlice) {
+    const prdAbs = path.resolve(args.prdSlice);
+    if (!existsSync(prdAbs)) {
+      errors.push(`prdSlice does not exist: ${prdAbs}`);
+    }
+  }
+
+  // Inventory path must exist if provided.
+  if (args.inventory) {
+    const invAbs = path.resolve(args.inventory);
+    if (!existsSync(invAbs)) {
+      errors.push(`inventory does not exist: ${invAbs}`);
+    }
+  }
+
+  // Backend path must be a directory if provided.
+  if (args.backendPath) {
+    const beAbs = path.resolve(args.backendPath);
+    if (!existsSync(beAbs)) {
+      errors.push(`backendPath does not exist: ${beAbs}`);
+    } else if (!statSync(beAbs).isDirectory()) {
+      errors.push(`backendPath is not a directory: ${beAbs}`);
+    }
+  }
+
+  // Core navigation seed path must be a file if provided.
+  if (args.coreNavigationSeedPath) {
+    const navAbs = path.resolve(args.coreNavigationSeedPath);
+    if (!existsSync(navAbs)) {
+      errors.push(`coreNavigationSeedPath does not exist: ${navAbs}`);
+    }
+  }
+
+  // Rule codes must look like DEV-UI-NNN.
+  for (const ruleId of args.rules) {
+    if (!/^DEV-UI-\d{3}$/.test(ruleId)) {
+      errors.push(`rule id "${ruleId}" must match /^DEV-UI-\\d{3}$/ (e.g. "DEV-UI-001")`);
+    }
+  }
+
+  return { valid: errors.length === 0, args, errors };
+}

package/templates/skills/development/audit-dev-tests/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: audit-dev-tests
+description: Audit acceptance-test coverage of BA Acceptance Criteria (DEV-TEST-001..003). Deterministic, runs after /ba-develop Phase 4 (Acceptance Tests). BLOCKING.
+group: D
+phase: devTests
+kind: audit
+audit_only: true
+section_label: 'AUDIT-DEV-TESTS (rules to apply against generated AC tests vs the BA use-case.md ACs)'
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# audit-dev-tests — Acceptance Tests Coverage Audit
+
+## Context
+
+You are auditing the output of **Phase 4 of `/ba-develop`** (Acceptance Tests).
+Compare the BA-declared Acceptance Criteria (`<UC-code>#AC-NN` pairs in every
+`<section>/use-case.md`) against the generated xUnit tests (`[Trait("AC","…")]`
+on each `[Fact]`), and ensure:
+
+1. Every BA AC has a generated `[Fact]`.
+2. No generated `[Fact]` references a stale (non-existent) BA AC.
+3. No `// TODO[AC-` marker remains in the generated test bodies (Phase 4 must
+   have filled them all).
+
+This is the **dev-readiness gate for vibecoded code** — it makes the BA
+acceptance criteria into a deterministic, executable contract.
+
+## Rules
+
+### DEV-TEST-001 — Every BA AC has a generated [Fact]
+For every `<UC-code>#AC-NN` declared in any `<moduleDir>/<section>/use-case.md`
+(under the UC's `**Acceptance Criteria**` field), the generated test code
+under `<projectPath>/Tests/**/*.cs` contains a `[Fact]` carrying
+`[Trait("AC", "<UC-code>#AC-NN")]`. A missing trait means an AC has no test —
+the BA contract is not enforceable.
+
+- **Severity**: **err** (BLOCKING).
+- **Fix**: re-run `/ba-develop` Phase 4, or invoke
+  `scaffold-tests-from-ac --spec '{"moduleDir":...,"projectPath":...,"appCode":...,"module":...}'`
+  manually, then commit.
+
+### DEV-TEST-002 — No `// TODO[AC-` marker remains
+Every generated AC test file MUST have its body filled — no
+`// TODO[AC-NN]:` marker may remain. The presence of even one means Phase 4's
+TODO-filling pass was incomplete or skipped, leaving an `Assert.Fail(...)`
+sentinel that does NOT actually assert the AC.
+
+- **Severity**: **err** (BLOCKING).
+- **Fix**: re-run Phase 4's TODO-filling subagent for the listed files, or
+  edit the offending test bodies by hand using the AC text in the file comment.
+
+### DEV-TEST-003 — Every test [Trait("AC",…)] resolves to a real BA AC
+The reverse direction of DEV-TEST-001: every `[Trait("AC", "<ref>")]` in
+generated code MUST point at a `<UC-code>#AC-NN` pair that still exists in
+the BA. Catches stale tests left over after an AC was deleted upstream.
+
+- **Severity**: **warn**.
+- **Fix**: delete the orphan `[Fact]` or restore the BA AC (re-run
+  `/ba-create-use-case`).
+
+## Invocation
+
+```bash
+npx tsx skills/development/audit-dev-tests/cli/audit-dev-tests/index.ts \
+  --spec '{"moduleDir":".smartstack/ba/CRM/PIPELINE","projectPath":"./generated/crm"}' \
+  --json
+```
+
+The CLI returns an `AuditReport` with `findings[]` (severity + rule code + the
+offending IDs + fix suggestion). Exit code is non-zero on `err`.
+
+## Notes
+
+- Parser reuse: this skill imports `parseAcFromUseCaseMd` from
+  `templates/skills/development/testing/cli/scaffold-tests-from-ac/parse-ac.ts`
+  (same canonical AC grammar — see `business-analyse/_workflow/doc-templates.md`).
+- Globs `Tests/**/*.cs` (not only `Tests/**/Acceptance/*.cs`) to also flag tests
+  written manually under other folders that carry `[Trait("AC",...)]`.
+- This audit is **read-only** — no `Edit`, no `Write`, no test re-generation.
+  Findings route back to `/ba-develop` Phase 4 (or `scaffold-tests-from-ac`
+  directly) for remediation.