@atlashub/smartstack-cli 1.5.1 → 1.5.3

package/templates/commands/validate.md

@@ -1,233 +1,233 @@
----
-description: Validate SmartStack conventions using MCP
-agent: action
-model: sonnet
----
-
-# /validate - SmartStack Conventions Validator
-
-Validates the SmartStack project against established conventions using **SmartStack MCP**.
-
-**USAGE:** Before commits, PRs, or as part of CI/CD to ensure code quality.
-
-**INTEGRATION:** Uses `mcp__smartstack__validate_conventions` for comprehensive analysis.
-
----
-
-## Available Commands
-
-| Command | Description | Checks |
-|---------|-------------|--------|
-| `/validate` | Run all validations | All |
-| `/validate:tables` | Validate table naming | SQL schemas, prefixes |
-| `/validate:migrations` | Validate migration naming | Format, order |
-| `/validate:services` | Validate service pattern | I*Service interfaces |
-| `/validate:namespaces` | Validate namespace structure | Layer separation |
-
----
-
-## STEP 1: Invoke MCP validate_conventions
-
-> **MCP INTEGRATION:** This command uses the SmartStack MCP server for validation.
-
-**Claude instruction:** Call the MCP tool:
-
-```json
-{
-  "tool": "mcp__smartstack__validate_conventions",
-  "parameters": {
-    "checks": ["all"]
-  }
-}
-```
-
-For specific checks:
-
-```json
-{
-  "tool": "mcp__smartstack__validate_conventions",
-  "parameters": {
-    "checks": ["tables", "migrations"]
-  }
-}
-```
-
----
-
-## STEP 2: Parse MCP Response
-
-The MCP returns a `ValidationResult`:
-
-```typescript
-interface ValidationResult {
-  valid: boolean;
-  errors: ValidationIssue[];
-  warnings: ValidationIssue[];
-  summary: string;
-}
-
-interface ValidationIssue {
-  type: 'error' | 'warning';
-  category: 'tables' | 'migrations' | 'services' | 'namespaces';
-  message: string;
-  file?: string;
-  line?: number;
-  suggestion?: string;
-}
-```
-
----
-
-## STEP 3: Display Results
-
-**If `valid: true` with no warnings:**
-
-```
-================================================================================
-                    SMARTSTACK CONVENTIONS VALIDATION
-================================================================================
-
-STATUS: PASSED
-
-Checks performed: tables, migrations, services, namespaces
-Errors: 0
-Warnings: 0
-
-All conventions validated successfully!
-
-================================================================================
-```
-
-**If `valid: false` or has warnings:**
-
-```
-================================================================================
-                    SMARTSTACK CONVENTIONS VALIDATION
-================================================================================
-
-STATUS: {valid ? "PASSED (with warnings)" : "FAILED"}
-
-ERRORS ({errors.length})
---------------------------------------------------------------------------------
-{for each error in errors}
-  [{error.category}] {error.message}
-    File: {error.file}
-    Suggestion: {error.suggestion}
-{end for}
---------------------------------------------------------------------------------
-
-WARNINGS ({warnings.length})
---------------------------------------------------------------------------------
-{for each warning in warnings}
-  [{warning.category}] {warning.message}
-    File: {warning.file}
-    Suggestion: {warning.suggestion}
-{end for}
---------------------------------------------------------------------------------
-
-================================================================================
-```
-
----
-
-## Validation Rules
-
-### Tables (`checks: ["tables"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Schema | `core`, `extensions` | `dbo`, custom |
-| Prefix | `auth_Users`, `nav_Items` | `Users`, `Items` |
-
-**Valid prefixes:** `auth_`, `nav_`, `usr_`, `ai_`, `cfg_`, `wkf_`, `support_`, `entra_`, `ref_`, `loc_`, `lic_`
-
-### Migrations (`checks: ["migrations"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Format | `core_v1.0.0_001_AddUsers` | `AddUsersTable` |
-| Order | v1.0.0 before v1.1.0 | v1.1.0 before v1.0.0 |
-
-**Format:** `{context}_v{version}_{sequence}_{Description}`
-
-### Services (`checks: ["services"]`)
-
-| Rule | Valid | Invalid |
-|------|-------|---------|
-| Interface | `IUserService` | `UserServiceInterface` |
-| Implementation | `UserService : IUserService` | `UserService` (no interface) |
-
-### Namespaces (`checks: ["namespaces"]`)
-
-| Layer | Expected Namespace |
-|-------|-------------------|
-| Domain | `SmartStack.Domain.*` |
-| Application | `SmartStack.Application.*` |
-| Infrastructure | `SmartStack.Infrastructure.*` |
-| Api | `SmartStack.Api.*` |
-
----
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--fix` | Auto-fix simple issues (rename suggestions) |
-| `--json` | Output raw MCP JSON response |
-| `--strict` | Treat warnings as errors |
-
----
-
-## CI/CD Integration
-
-```yaml
-# GitHub Actions
-- name: Validate SmartStack conventions
-  run: |
-    OUTPUT=$(claude-code "/validate --json")
-    VALID=$(echo $OUTPUT | jq '.valid')
-    if [ "$VALID" != "true" ]; then
-      echo "::error::SmartStack convention violations detected"
-      exit 1
-    fi
-```
-
----
-
-## Pre-Commit Hook Integration
-
-Add to `.claude/hooks/PreToolUse`:
-
-```json
-{
-  "matcher": "Edit|Write",
-  "hooks": [{
-    "type": "command",
-    "command": "claude-code /validate:quick"
-  }]
-}
-```
-
----
-
-## MCP Tool Reference
-
-**Tool:** `mcp__smartstack__validate_conventions`
-
-**Description:** Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | string | Project path (default: auto-detect) |
-| `checks` | string[] | Types of checks: `tables`, `migrations`, `services`, `namespaces`, `all` |
-
----
-
-## Why MCP Integration?
-
-1. **Centralized Rules:** Convention rules defined once in MCP config
-2. **Consistency:** Same validation in CLI, CI/CD, and IDE
-3. **Extensibility:** Add new checks in MCP, available everywhere
-4. **Structured Output:** Typed responses for automation
+---
+description: Validate SmartStack conventions using MCP
+agent: action
+model: sonnet
+---
+
+# /validate - SmartStack Conventions Validator
+
+Validates the SmartStack project against established conventions using **SmartStack MCP**.
+
+**USAGE:** Before commits, PRs, or as part of CI/CD to ensure code quality.
+
+**INTEGRATION:** Uses `mcp__smartstack__validate_conventions` for comprehensive analysis.
+
+---
+
+## Available Commands
+
+| Command | Description | Checks |
+|---------|-------------|--------|
+| `/validate` | Run all validations | All |
+| `/validate:tables` | Validate table naming | SQL schemas, prefixes |
+| `/validate:migrations` | Validate migration naming | Format, order |
+| `/validate:services` | Validate service pattern | I*Service interfaces |
+| `/validate:namespaces` | Validate namespace structure | Layer separation |
+
+---
+
+## STEP 1: Invoke MCP validate_conventions
+
+> **MCP INTEGRATION:** This command uses the SmartStack MCP server for validation.
+
+**Claude instruction:** Call the MCP tool:
+
+```json
+{
+  "tool": "mcp__smartstack__validate_conventions",
+  "parameters": {
+    "checks": ["all"]
+  }
+}
+```
+
+For specific checks:
+
+```json
+{
+  "tool": "mcp__smartstack__validate_conventions",
+  "parameters": {
+    "checks": ["tables", "migrations"]
+  }
+}
+```
+
+---
+
+## STEP 2: Parse MCP Response
+
+The MCP returns a `ValidationResult`:
+
+```typescript
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  summary: string;
+}
+
+interface ValidationIssue {
+  type: 'error' | 'warning';
+  category: 'tables' | 'migrations' | 'services' | 'namespaces';
+  message: string;
+  file?: string;
+  line?: number;
+  suggestion?: string;
+}
+```
+
+---
+
+## STEP 3: Display Results
+
+**If `valid: true` with no warnings:**
+
+```
+================================================================================
+                    SMARTSTACK CONVENTIONS VALIDATION
+================================================================================
+
+STATUS: PASSED
+
+Checks performed: tables, migrations, services, namespaces
+Errors: 0
+Warnings: 0
+
+All conventions validated successfully!
+
+================================================================================
+```
+
+**If `valid: false` or has warnings:**
+
+```
+================================================================================
+                    SMARTSTACK CONVENTIONS VALIDATION
+================================================================================
+
+STATUS: {valid ? "PASSED (with warnings)" : "FAILED"}
+
+ERRORS ({errors.length})
+--------------------------------------------------------------------------------
+{for each error in errors}
+  [{error.category}] {error.message}
+    File: {error.file}
+    Suggestion: {error.suggestion}
+{end for}
+--------------------------------------------------------------------------------
+
+WARNINGS ({warnings.length})
+--------------------------------------------------------------------------------
+{for each warning in warnings}
+  [{warning.category}] {warning.message}
+    File: {warning.file}
+    Suggestion: {warning.suggestion}
+{end for}
+--------------------------------------------------------------------------------
+
+================================================================================
+```
+
+---
+
+## Validation Rules
+
+### Tables (`checks: ["tables"]`)
+
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Schema | `core`, `extensions` | `dbo`, custom |
+| Prefix | `auth_Users`, `nav_Items` | `Users`, `Items` |
+
+**Valid prefixes:** `auth_`, `nav_`, `usr_`, `ai_`, `cfg_`, `wkf_`, `support_`, `entra_`, `ref_`, `loc_`, `lic_`
+
+### Migrations (`checks: ["migrations"]`)
+
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Format | `core_v1.0.0_001_AddUsers` | `AddUsersTable` |
+| Order | v1.0.0 before v1.1.0 | v1.1.0 before v1.0.0 |
+
+**Format:** `{context}_v{version}_{sequence}_{Description}`
+
+### Services (`checks: ["services"]`)
+
+| Rule | Valid | Invalid |
+|------|-------|---------|
+| Interface | `IUserService` | `UserServiceInterface` |
+| Implementation | `UserService : IUserService` | `UserService` (no interface) |
+
+### Namespaces (`checks: ["namespaces"]`)
+
+| Layer | Expected Namespace |
+|-------|-------------------|
+| Domain | `SmartStack.Domain.*` |
+| Application | `SmartStack.Application.*` |
+| Infrastructure | `SmartStack.Infrastructure.*` |
+| Api | `SmartStack.Api.*` |
+
+---
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--fix` | Auto-fix simple issues (rename suggestions) |
+| `--json` | Output raw MCP JSON response |
+| `--strict` | Treat warnings as errors |
+
+---
+
+## CI/CD Integration
+
+```yaml
+# GitHub Actions
+- name: Validate SmartStack conventions
+  run: |
+    OUTPUT=$(claude-code "/validate --json")
+    VALID=$(echo $OUTPUT | jq '.valid')
+    if [ "$VALID" != "true" ]; then
+      echo "::error::SmartStack convention violations detected"
+      exit 1
+    fi
+```
+
+---
+
+## Pre-Commit Hook Integration
+
+Add to `.claude/hooks/PreToolUse`:
+
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [{
+    "type": "command",
+    "command": "claude-code /validate:quick"
+  }]
+}
+```
+
+---
+
+## MCP Tool Reference
+
+**Tool:** `mcp__smartstack__validate_conventions`
+
+**Description:** Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | string | Project path (default: auto-detect) |
+| `checks` | string[] | Types of checks: `tables`, `migrations`, `services`, `namespaces`, `all` |
+
+---
+
+## Why MCP Integration?
+
+1. **Centralized Rules:** Convention rules defined once in MCP config
+2. **Consistency:** Same validation in CLI, CI/CD, and IDE
+3. **Extensibility:** Add new checks in MCP, available everywhere
+4. **Structured Output:** Typed responses for automation