@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/validation/conventions/cli/validate-conventions/execute.ts

@@ -0,0 +1,368 @@
+/**
+ * validate-conventions/execute.ts — Scan a SmartStack project for convention violations.
+ *
+ * Three checks are implemented (ported from SmartStack.cli/src/mcp/tools/validate-conventions.ts):
+ *   1. namespaces — each layer's .cs files should start with the expected namespace prefix
+ *   2. entities   — classes inheriting BaseEntity must implement a tenant interface,
+ *                   have a private ctor, and a Create() factory method
+ *   3. controllers — controllers should use [NavRoute], not a hardcoded [Route] attribute,
+ *                    and never both at once
+ *
+ * The report returned is a plain JSON object Claude reads from stdout.
+ */
+import path from 'node:path';
+import { findSmartStackStructure, type SmartStackStructure } from '../../../../lib/detector.js';
+import { findFiles, readText } from '../../../../lib/fs.js';
+import { findCsprojFiles, detectNamespaces, type NamespaceConfig } from '../../../../lib/dotnet.js';
+import { extractNavRoutes } from '../../../../lib/navroute-parser.js';
+import type {
+  ValidateConventionsArgs,
+  ValidateConventionsOutput,
+  Finding,
+  Category,
+  ConventionsReport,
+} from './types.js';
+
+// ─── Entry point ──────────────────────────────────────────────────────────
+
+export async function execute(
+  args: ValidateConventionsArgs,
+): Promise<ValidateConventionsOutput> {
+  const projectPath = args.projectPath || process.cwd();
+  const structure = await findSmartStackStructure(projectPath);
+
+  // Determine which checks to run
+  const expanded: Category[] =
+    args.checks.includes('all')
+      ? ['namespaces', 'entities', 'controllers']
+      : (args.checks.filter((c) => c !== 'all') as Category[]);
+
+  // Detect namespace config (used by the namespaces check).
+  const csprojFiles = await findCsprojFiles(projectPath);
+  const detectedNs = await detectNamespaces(csprojFiles);
+  const baseNamespace = args.baseNamespace ?? detectedNs?.baseNamespace ?? null;
+
+  const findings: Finding[] = [];
+  let filesInspected = 0;
+
+  // Run each check
+  if (expanded.includes('namespaces')) {
+    filesInspected += await checkNamespaces(structure, baseNamespace, findings);
+  }
+  if (expanded.includes('entities')) {
+    filesInspected += await checkEntities(structure, findings);
+  }
+  if (expanded.includes('controllers')) {
+    filesInspected += await checkControllers(structure, findings);
+  }
+
+  // Build the report
+  const counts = {
+    errors: findings.filter((f) => f.severity === 'error').length,
+    warnings: findings.filter((f) => f.severity === 'warning').length,
+    infos: findings.filter((f) => f.severity === 'info').length,
+  };
+
+  const byCategory: Record<Category, number> = {
+    namespaces: 0,
+    entities: 0,
+    controllers: 0,
+  };
+  for (const finding of findings) {
+    byCategory[finding.category]++;
+  }
+
+  const report: ConventionsReport = {
+    projectPath,
+    structure: {
+      domain: structure.domain ?? null,
+      application: structure.application ?? null,
+      infrastructure: structure.infrastructure ?? null,
+      api: structure.api ?? null,
+      web: structure.web ?? null,
+    },
+    checksRun: expanded,
+    filesInspected,
+    findings,
+    counts,
+    byCategory,
+  };
+
+  const valid = counts.errors === 0;
+  const summary =
+    valid
+      ? `All checks passed (${filesInspected} files inspected, ${counts.warnings} warnings, ${counts.infos} infos)`
+      : `${counts.errors} error(s), ${counts.warnings} warning(s), ${counts.infos} info(s) across ${filesInspected} files`;
+
+  const nextSteps: string[] = [];
+  if (counts.errors > 0) {
+    nextSteps.push('Fix the "error"-severity findings before proceeding — they break conventions that are enforced at runtime');
+  }
+  if (counts.warnings > 0) {
+    nextSteps.push('Review the warnings — they indicate drift from SmartStack conventions that may cause issues later');
+  }
+  if (valid && counts.warnings === 0) {
+    nextSteps.push('No action needed — the project fully complies with SmartStack conventions');
+  }
+
+  return {
+    success: true,
+    command: 'validate-conventions',
+    data: { valid, summary },
+    report,
+    errors: [],
+    warnings: [],
+    nextSteps,
+  };
+}
+
+// ─── Check 1: namespaces ──────────────────────────────────────────────────
+
+async function checkNamespaces(
+  structure: SmartStackStructure,
+  baseNamespace: string | null,
+  findings: Finding[],
+): Promise<number> {
+  if (!baseNamespace) {
+    findings.push({
+      severity: 'warning',
+      category: 'namespaces',
+      message:
+        'Could not detect a base namespace from .csproj files — skipping namespace checks',
+      suggestion: 'Pass --base-namespace <Name> if the project does not follow the *.Domain/*.Application/*.Infrastructure/*.Api layout',
+    });
+    return 0;
+  }
+
+  const expectedByLayer: Array<{
+    path: string | undefined;
+    expected: string;
+    layer: string;
+  }> = [
+    { path: structure.domain, expected: `${baseNamespace}.Domain`, layer: 'Domain' },
+    { path: structure.application, expected: `${baseNamespace}.Application`, layer: 'Application' },
+    { path: structure.infrastructure, expected: `${baseNamespace}.Infrastructure`, layer: 'Infrastructure' },
+    { path: structure.api, expected: `${baseNamespace}.Api`, layer: 'Api' },
+  ];
+
+  let inspected = 0;
+
+  for (const layer of expectedByLayer) {
+    if (!layer.path) continue;
+
+    const csFiles = await findFiles('**/*.cs', { cwd: layer.path });
+    // Inspect at most 30 files per layer to keep the audit fast.
+    const sample = csFiles.slice(0, 30);
+    inspected += sample.length;
+
+    for (const file of sample) {
+      const content = await readText(file);
+      const match = content.match(/namespace\s+([\w.]+)/);
+      if (!match) continue;
+      const ns = match[1];
+
+      if (!ns.startsWith(layer.expected)) {
+        // Downgrade to warning if the namespace still follows the Clean Architecture
+        // pattern ({Base}.{Layer}) — common for client extension projects.
+        const followsPattern =
+          ['Domain', 'Application', 'Infrastructure', 'Api'].some(
+            (l) => ns.includes(`.${l}`) || ns.endsWith(`.${l}`),
+          );
+        findings.push({
+          severity: followsPattern ? 'warning' : 'error',
+          category: 'namespaces',
+          message: `${layer.layer} file has namespace "${ns}" (expected prefix: "${layer.expected}")`,
+          file: path.relative(structure.root, file),
+          suggestion: followsPattern
+            ? `Namespace follows Clean Architecture pattern but differs from the detected base "${baseNamespace}". Expected to start with "${layer.expected}".`
+            : `Should start with "${layer.expected}"`,
+        });
+      }
+    }
+  }
+
+  return inspected;
+}
+
+// ─── Check 2: entities ────────────────────────────────────────────────────
+
+async function checkEntities(
+  structure: SmartStackStructure,
+  findings: Finding[],
+): Promise<number> {
+  if (!structure.domain) {
+    findings.push({
+      severity: 'warning',
+      category: 'entities',
+      message: 'Domain project not found — skipping entity validation',
+    });
+    return 0;
+  }
+
+  const csFiles = await findFiles('**/*.cs', { cwd: structure.domain });
+  let inspected = 0;
+
+  for (const file of csFiles) {
+    const fileName = path.basename(file, '.cs');
+
+    // Skip obvious non-entity files
+    if (
+      fileName.endsWith('Dto') ||
+      fileName.endsWith('Command') ||
+      fileName.endsWith('Query') ||
+      fileName.endsWith('Handler') ||
+      fileName.endsWith('Validator') ||
+      fileName.endsWith('Exception') ||
+      fileName.startsWith('I')
+    ) {
+      continue;
+    }
+
+    const content = await readText(file);
+    const classMatch = content.match(
+      /public\s+(?:class|record)\s+(\w+)(?:\s*:\s*([^{]+))?/,
+    );
+    if (!classMatch) continue;
+
+    inspected++;
+    const entityName = classMatch[1];
+    const inheritance = classMatch[2]?.trim() || '';
+
+    const hasBaseEntity = inheritance.includes('BaseEntity');
+    const hasSystemEntity = inheritance.includes('SystemEntity');
+    if (!hasBaseEntity && !hasSystemEntity) continue; // value object / other
+
+    const hasTenantInterface =
+      inheritance.includes('ITenantEntity') ||
+      inheritance.includes('IOptionalTenantEntity') ||
+      inheritance.includes('IScopedTenantEntity');
+
+    if (hasBaseEntity && !hasSystemEntity && !hasTenantInterface) {
+      findings.push({
+        severity: 'warning',
+        category: 'entities',
+        message: `Entity "${entityName}" inherits BaseEntity but does not implement any tenant interface`,
+        file: path.relative(structure.root, file),
+        suggestion:
+          'Add ITenantEntity (strict), IOptionalTenantEntity (cross-tenant), or IScopedTenantEntity (with scope)',
+      });
+    }
+
+    if (!content.includes(`private ${entityName}()`)) {
+      findings.push({
+        severity: 'warning',
+        category: 'entities',
+        message: `Entity "${entityName}" is missing a private constructor (required by EF Core)`,
+        file: path.relative(structure.root, file),
+        suggestion: `Add: private ${entityName}() { }`,
+      });
+    }
+
+    if (!content.includes(`public static ${entityName} Create(`)) {
+      findings.push({
+        severity: 'warning',
+        category: 'entities',
+        message: `Entity "${entityName}" is missing a factory method`,
+        file: path.relative(structure.root, file),
+        suggestion: `Add: public static ${entityName} Create(...)`,
+      });
+    }
+  }
+
+  return inspected;
+}
+
+// ─── Check 3: controllers ─────────────────────────────────────────────────
+
+async function checkControllers(
+  structure: SmartStackStructure,
+  findings: Finding[],
+): Promise<number> {
+  if (!structure.api) {
+    findings.push({
+      severity: 'warning',
+      category: 'controllers',
+      message: 'API project not found — skipping controller route validation',
+    });
+    return 0;
+  }
+
+  // System controllers that legitimately use hardcoded [Route] — whitelisted.
+  // Keep this list short; controllers not in the navigation hierarchy should
+  // migrate to [NavRoute] when possible.
+  const SYSTEM_CONTROLLERS = new Set([
+    'AuthController',
+    'RegistrationController',
+    'OnboardingController',
+    'NavigationController',
+    'LogsController',
+    'EntraController',
+    'PreferencesController',
+    'ApplicationTrackingController',
+    'NotificationsController',
+    'DashboardController',
+  ]);
+
+  const controllerFiles = await findFiles('**/Controllers/**/*Controller.cs', {
+    cwd: structure.api,
+  });
+  let inspected = 0;
+
+  for (const file of controllerFiles) {
+    const fileName = path.basename(file, '.cs');
+    if (SYSTEM_CONTROLLERS.has(fileName)) continue;
+
+    inspected++;
+    const content = await readText(file);
+    const hasNavRoute = content.includes('[NavRoute(');
+    const routeMatch = content.match(/\[Route\s*\(\s*"([^"]+)"\s*\)\]/);
+
+    if (hasNavRoute && routeMatch) {
+      findings.push({
+        severity: 'error',
+        category: 'controllers',
+        message: `Controller "${fileName}" has BOTH [NavRoute] and [Route("${routeMatch[1]}")]. Only [NavRoute] should be used.`,
+        file: path.relative(structure.root, file),
+        suggestion: `Remove [Route("${routeMatch[1]}")] — NavRoute resolves the path dynamically from the navigation database at startup`,
+      });
+    }
+
+    if (hasNavRoute) {
+      // Validate the structure of every [NavRoute(...)] attribute.
+      const parsed = extractNavRoutes(content);
+      for (const nr of parsed) {
+        const parts = nr.navRoute.split('.');
+        if (parts.length < 2) {
+          findings.push({
+            severity: 'error',
+            category: 'controllers',
+            message: `Controller "${fileName}" has a NavRoute with insufficient depth: "${nr.navRoute}"`,
+            file: path.relative(structure.root, file),
+            suggestion: 'NavRoute must have at least 2 segments: "application.module"',
+          });
+        }
+        if (parts.some((p) => p !== p.toLowerCase())) {
+          findings.push({
+            severity: 'error',
+            category: 'controllers',
+            message: `Controller "${fileName}" has a NavRoute with uppercase characters: "${nr.navRoute}"`,
+            file: path.relative(structure.root, file),
+            suggestion: 'NavRoute segments must be lowercase (e.g., "administration.users")',
+          });
+        }
+      }
+    } else if (routeMatch) {
+      // Hardcoded route without any NavRoute — flag as warning.
+      findings.push({
+        severity: 'warning',
+        category: 'controllers',
+        message: `Controller "${fileName}" uses hardcoded [Route("${routeMatch[1]}")] instead of [NavRoute]`,
+        file: path.relative(structure.root, file),
+        suggestion:
+          'Migrate to [NavRoute("module.section")] so the URL is driven by the navigation database. Alternatively, whitelist the controller if it is truly system-level.',
+      });
+    }
+  }
+
+  return inspected;
+}

package/templates/skills/validation/conventions/cli/validate-conventions/index.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * validate-conventions/index.ts — Entry point.
+ * parse args → validate → execute checks → print JSON on stdout.
+ *
+ * Invoked by Claude via Bash. See sibling SKILL.md for the invocation contract.
+ */
+import { Command } from 'commander';
+import { validateArgs } from './validate.js';
+import { execute } from './execute.js';
+import type { ValidateConventionsOutput } from './types.js';
+
+const program = new Command();
+
+program
+  .name('validate-conventions')
+  .description('Audit a SmartStack project for convention violations')
+  .option('--project-path <path>', 'Absolute path of the SmartStack project to audit (defaults to cwd)')
+  .option(
+    '--checks <list>',
+    'Comma-separated list of checks (namespaces, entities, controllers, all)',
+    'all',
+  )
+  .option('--base-namespace <name>', 'Override the detected base namespace')
+  .parse(process.argv);
+
+const opts = program.opts();
+
+const raw = {
+  projectPath: opts.projectPath as string | undefined,
+  checks: typeof opts.checks === 'string'
+    ? opts.checks.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : ['all'],
+  baseNamespace: opts.baseNamespace as string | undefined,
+};
+
+const validation = validateArgs(raw);
+if (!validation.valid || !validation.args) {
+  const output: ValidateConventionsOutput = {
+    success: false,
+    command: 'validate-conventions',
+    report: null,
+    errors: validation.errors,
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}
+
+try {
+  const result = await execute(validation.args);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.success && (result.data?.valid ?? false) ? 0 : 1);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const output: ValidateConventionsOutput = {
+    success: false,
+    command: 'validate-conventions',
+    report: null,
+    errors: [`Unexpected error: ${message}`],
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}

package/templates/skills/validation/conventions/cli/validate-conventions/types.ts

@@ -0,0 +1,91 @@
+/**
+ * validate-conventions/types.ts — CLI args + report shape for the conventions
+ * audit of a SmartStack project.
+ */
+import { z } from 'zod';
+
+export const CheckNames = [
+  'namespaces',
+  'entities',
+  'controllers',
+  'all',
+] as const;
+
+export type CheckName = (typeof CheckNames)[number];
+
+export const ValidateConventionsArgsSchema = z.object({
+  /** Absolute path of the SmartStack project to audit (defaults to cwd). */
+  projectPath: z.string().optional(),
+  /**
+   * Which checks to run. Defaults to ['all']. Each check scans a different
+   * aspect of the project and produces findings in the report.
+   */
+  checks: z
+    .array(z.enum(CheckNames))
+    .default(['all']),
+  /**
+   * Override the expected base namespace (e.g. "Acme.Corp"). When omitted,
+   * the CLI auto-detects from .csproj files.
+   */
+  baseNamespace: z.string().optional(),
+});
+
+export type ValidateConventionsArgs = z.infer<typeof ValidateConventionsArgsSchema>;
+
+// ─── Finding ──────────────────────────────────────────────────────────────
+
+export type Severity = 'error' | 'warning' | 'info';
+
+export type Category = 'namespaces' | 'entities' | 'controllers';
+
+export interface Finding {
+  severity: Severity;
+  category: Category;
+  message: string;
+  file?: string;
+  suggestion?: string;
+}
+
+// ─── Report ───────────────────────────────────────────────────────────────
+
+export interface ConventionsReport {
+  /** Absolute project path that was scanned. */
+  projectPath: string;
+  /** Detected SmartStack layer paths. */
+  structure: {
+    domain: string | null;
+    application: string | null;
+    infrastructure: string | null;
+    api: string | null;
+    web: string | null;
+  };
+  /** Checks that were actually executed (after 'all' expansion). */
+  checksRun: Category[];
+  /** Total number of files inspected across all checks. */
+  filesInspected: number;
+  /** Every finding produced by the checks. */
+  findings: Finding[];
+  /** Counts per severity. */
+  counts: {
+    errors: number;
+    warnings: number;
+    infos: number;
+  };
+  /** Counts per category. */
+  byCategory: Record<Category, number>;
+}
+
+// ─── Output envelope ──────────────────────────────────────────────────────
+
+export interface ValidateConventionsOutput {
+  success: boolean;
+  command: 'validate-conventions';
+  data?: {
+    valid: boolean;
+    summary: string;
+  };
+  report: ConventionsReport | null;
+  errors: string[];
+  warnings: string[];
+  nextSteps: string[];
+}

package/templates/skills/validation/conventions/cli/validate-conventions/validate.ts

@@ -0,0 +1,36 @@
+/**
+ * validate-conventions/validate.ts — Args validation (Zod only).
+ * No file I/O here — the actual checks live in execute.ts.
+ */
+import { ValidateConventionsArgsSchema, type ValidateConventionsArgs } from './types.js';
+
+export interface ArgsValidationResult {
+  valid: boolean;
+  args: ValidateConventionsArgs | null;
+  errors: string[];
+}
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = ValidateConventionsArgsSchema.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[] = [];
+
+  // If baseNamespace is provided, it should look like a proper .NET root namespace
+  if (args.baseNamespace !== undefined) {
+    if (!/^[A-Z][A-Za-z0-9]*(\.[A-Z][A-Za-z0-9]*)*$/.test(args.baseNamespace)) {
+      errors.push(
+        `baseNamespace "${args.baseNamespace}" should be dotted PascalCase (e.g. "SmartStack" or "Acme.Corp")`,
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, args, errors };
+}

package/templates/skills/validation/cross-validate/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cross-validate-stack
+description: Cross-stack validation backend .NET / frontend React — 5 coherence checks
+group: validation
+cli: cli/
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# Skill: Cross-Validate Stack
+
+> Verifies coherence between .NET backend and React frontend.
+> Analysis via file scanning + JSON specs — lightweight and fast.
+
+## When to use this skill
+
+- After backend + frontend code generation for a module
+- Before a merge/PR to verify both sides are aligned
+- To audit that no route, permission or resource is missing
+
+## The 5 Checks
+
+| # | Check | Source / Target |
+|---|-------|-----------------|
+| 1 | `routes-have-endpoints` | Each endpoint in JSON specs has a corresponding .NET controller |
+| 2 | `endpoints-are-consumed` | Each .NET endpoint is called by at least one React service |
+| 3 | `permissions-aligned` | `[RequirePermission]` .NET and `PermissionGuard`/`usePermission` React are aligned |
+| 4 | `resources-have-screens` | Each resource (meta.json) has a .NET controller and at least one .tsx page |
+| 5 | `rbac-consistent` | All permissions declared in permissions.json are used in code |
+
+## CLI Invocation
+
+```bash
+# Complete cross-stack validation
+npx tsx skills/validation/cross-validate/cli/index.ts --specs <specs-dir> --src <src-dir>
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `--specs` | Directory containing JSON specs (meta.json, endpoints.json, permissions.json) | Yes |
+| `--src` | Directory containing source code (.cs and .tsx/.ts) | Yes |
+| `--help` | Display help | No |
+
+## JSON Output
+
+```json
+{
+  "timestamp": "2026-03-31T...",
+  "checks": [
+    { "id": "routes-have-endpoints", "status": "ok", "count": 5 },
+    { "id": "permissions-aligned", "status": "error", "details": "crm.clients.Delete — .NET: ok, React: missing" }
+  ],
+  "errors": 1,
+  "warnings": 0
+}
+```
+
+## Expected Behavior
+
+1. User requests a cross-stack validation
+2. Claude Code identifies the specs directory and source directory
+3. Claude Code calls the CLI with `--specs` and `--src`
+4. CLI returns JSON with the results of 5 checks
+5. Claude Code presents results and suggests corrections
+
+## Conversation Example
+
+```
+User: Verify that my backend and frontend are coherent
+Claude Code: Launching cross-stack validation...
+> npx tsx skills/validation/cross-validate/cli/index.ts --specs ./specs --src ./src
+< { "checks": [...], "errors": 0, "warnings": 0 }
+Claude Code: All 5 cross-stack checks pass. Backend and frontend are aligned.
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success — no errors |
+| 1 | Errors detected |
+| 2 | Internal CLI error (invalid input, missing directory) |