forgedev 1.2.0 → 1.4.0

package/src/utils.js

@@ -21,11 +21,6 @@ export function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
-export function copyFile(src, dest) {
-  ensureDir(path.dirname(dest));
-  fs.copyFileSync(src, dest);
-}
-
 export function writeFile(dest, content) {
   ensureDir(path.dirname(dest));
   fs.writeFileSync(dest, content, 'utf-8');
@@ -48,6 +43,12 @@ export function toPascalCase(str) {
     .join('');
 }
 
+export function copyEnvCmd() {
+  return process.platform === 'win32'
+    ? 'copy .env.example .env'
+    : 'cp .env.example .env';
+}
+
 export function toSnakeCase(str) {
   return str.replace(/[-\s]+/g, '_').toLowerCase();
 }
@@ -55,3 +56,159 @@ export function toSnakeCase(str) {
 export function toKebabCase(str) {
   return str.replace(/[\s_]+/g, '-').toLowerCase();
 }
+
+// ─── Single source of truth for all per-stack metadata ──────────────
+// Adding a new stack? Add one entry here. Nothing else to touch in utils.js.
+
+const STACK_METADATA = {
+  'nextjs-fullstack': {
+    description: 'Next.js full-stack application with TypeScript, Tailwind CSS, Prisma, and PostgreSQL',
+    extraIgnores: '',
+    port: '3000',
+    commands: {
+      LINT_COMMAND: 'npx eslint .',
+      TYPE_CHECK_COMMAND: 'npx tsc --noEmit',
+      TEST_COMMAND: 'npx vitest run',
+      BUILD_COMMAND: 'npm run build',
+      DEV_COMMAND: 'npm run dev',
+    },
+    setupCommands: () => `npm install
+${copyEnvCmd()}
+npx prisma db push
+npm run dev`,
+    availableScripts: `- \`npm run dev\`: Start development server
+- \`npm run build\`: Production build
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests
+- \`npx playwright test\`: Run E2E tests`,
+  },
+
+  'fastapi-backend': {
+    description: 'FastAPI backend service with SQLAlchemy, PostgreSQL, and Alembic',
+    extraIgnores: '\n# Python\n__pycache__/\n*.pyc\nvenv/\n.venv/\n*.egg-info/',
+    port: '8000',
+    commands: {
+      LINT_COMMAND: 'ruff check .',
+      TYPE_CHECK_COMMAND: 'pyright',
+      TEST_COMMAND: 'pytest',
+      BUILD_COMMAND: 'docker build -t app .',
+      DEV_COMMAND: 'uvicorn app.main:app --reload',
+    },
+    setupCommands: () => `cd backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+${copyEnvCmd()}
+uvicorn app.main:app --reload`,
+    availableScripts: `- \`uvicorn app.main:app --reload\`: Start dev server
+- \`pytest\`: Run tests
+- \`ruff check .\`: Run linter
+- \`alembic upgrade head\`: Run migrations`,
+  },
+
+  'polyglot-fullstack': {
+    description: 'Full-stack application with Next.js frontend and FastAPI backend',
+    extraIgnores: '\n# Python\n__pycache__/\n*.pyc\nvenv/\n.venv/\n*.egg-info/',
+    port: '3000',
+    commands: {
+      LINT_COMMAND: 'cd frontend && npx eslint . && cd ../backend && ruff check .',
+      TYPE_CHECK_COMMAND: 'cd frontend && npx tsc --noEmit',
+      TEST_COMMAND: 'cd frontend && npx vitest run && cd ../backend && pytest',
+      BUILD_COMMAND: 'docker compose build',
+      DEV_COMMAND: 'docker compose up',
+    },
+    setupCommands: () => `docker compose up -d postgres
+# Frontend
+cd frontend && npm install && npm run dev
+# Backend
+cd backend && pip install -r requirements.txt && uvicorn app.main:app --reload`,
+    availableScripts: `- \`docker compose up\`: Start all services
+- \`docker compose up -d postgres\`: Start database only
+- Frontend: \`cd frontend && npm run dev\`
+- Backend: \`cd backend && uvicorn app.main:app --reload\``,
+  },
+
+  'react-express': {
+    description: 'Full-stack application with React (Vite) frontend and Express backend',
+    extraIgnores: '\ndist/',
+    port: '3001', // Express backend port (frontend runs on Vite :5173)
+    commands: {
+      LINT_COMMAND: 'cd frontend && npx eslint . && cd ../backend && npx eslint .',
+      TYPE_CHECK_COMMAND: 'cd frontend && npx tsc --noEmit && cd ../backend && npx tsc --noEmit',
+      TEST_COMMAND: 'cd frontend && npx vitest run && cd ../backend && npx vitest run',
+      BUILD_COMMAND: 'cd frontend && npm run build && cd ../backend && npm run build',
+      DEV_COMMAND: 'npx concurrently "cd frontend && npm run dev" "cd backend && npm run dev"',
+    },
+    setupCommands: () => `# Frontend
+cd frontend && npm install && npm run dev
+# Backend (in a separate terminal)
+cd backend && npm install && ${copyEnvCmd()} && npx prisma db push && npm run dev`,
+    availableScripts: `- Frontend: \`cd frontend && npm run dev\` (Vite dev server)
+- Backend: \`cd backend && npm run dev\` (Express with tsx watch)
+- \`cd backend && npm run build\`: Build backend for production
+- \`cd frontend && npm run build\`: Build frontend for production
+- \`cd backend && npx prisma studio\`: Database GUI
+- \`cd frontend && npx vitest\`: Run frontend tests`,
+  },
+
+  'remix-fullstack': {
+    description: 'Full-stack Remix application with Vite, Tailwind CSS, and PostgreSQL',
+    extraIgnores: '\nbuild/',
+    port: '3000',
+    commands: {
+      LINT_COMMAND: 'npx eslint .',
+      TYPE_CHECK_COMMAND: 'npx tsc --noEmit',
+      TEST_COMMAND: 'npx vitest run',
+      BUILD_COMMAND: 'npm run build',
+      DEV_COMMAND: 'npm run dev',
+    },
+    setupCommands: () => `npm install
+${copyEnvCmd()}
+npx prisma db push
+npm run dev`,
+    availableScripts: `- \`npm run dev\`: Start Remix dev server
+- \`npm run build\`: Production build
+- \`npm run start\`: Start production server
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests`,
+  },
+
+  'hono-api': {
+    description: 'Hono API service with TypeScript, Prisma, and PostgreSQL',
+    extraIgnores: '\ndist/',
+    port: '3000',
+    commands: {
+      LINT_COMMAND: 'npx eslint .',
+      TYPE_CHECK_COMMAND: 'npx tsc --noEmit',
+      TEST_COMMAND: 'npx vitest run',
+      BUILD_COMMAND: 'npm run build',
+      DEV_COMMAND: 'npm run dev',
+    },
+    setupCommands: () => `npm install
+${copyEnvCmd()}
+npx prisma db push
+npm run dev`,
+    availableScripts: `- \`npm run dev\`: Start Hono dev server (tsx watch)
+- \`npm run build\`: Compile TypeScript
+- \`npm run start\`: Start production server
+- \`npm run lint\`: Run ESLint
+- \`npx prisma studio\`: Database GUI
+- \`npx vitest\`: Run unit tests`,
+  },
+};
+
+export function getStackMetadata(stackId) {
+  const meta = STACK_METADATA[stackId];
+  if (!meta) {
+    log.warn(`No stack metadata for "${stackId}" — using empty defaults`);
+    return null;
+  }
+  return meta;
+}
+
+export function getStackCommands(stackId) {
+  const meta = STACK_METADATA[stackId];
+  return meta ? { ...meta.commands } : {};
+}

package/templates/ai/guardrails-py/backend/app/ai/__init__.py

@@ -0,0 +1,29 @@
+"""AI Guardrails — {{PROJECT_NAME_PASCAL}}
+
+Central module for all AI safety infrastructure.
+
+Usage:
+    from app.ai import get_ai_client
+    ai = get_ai_client()
+    result = await ai.generate(prompt="...", schema=MyModel)
+
+Compliance: EU AI Act (2024/1689), NIST AI RMF 1.0
+"""
+
+from app.ai.client import AIClient, get_ai_client, AIResponse, AIClientConfig
+from app.ai.input_guard import validate_input, sanitize_input
+from app.ai.audit_log import ai_audit_log, AuditEntry
+from app.ai.health import ai_health_metrics, AIHealthStatus
+
+__all__ = [
+    "AIClient",
+    "get_ai_client",
+    "AIResponse",
+    "AIClientConfig",
+    "validate_input",
+    "sanitize_input",
+    "ai_audit_log",
+    "AuditEntry",
+    "ai_health_metrics",
+    "AIHealthStatus",
+]

package/templates/ai/guardrails-py/backend/app/ai/audit_log.py

@@ -0,0 +1,133 @@
+"""AI Audit Logger — Structured logging of all AI interactions.
+
+Compliance: EU AI Act Art. 12 (logging and traceability),
+            NIST AI RMF Manage 1.3 (monitoring)
+"""
+
+import json
+import logging
+import threading
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+logger = logging.getLogger("ai.audit")
+
+
+@dataclass
+class AuditEntry:
+    """A single AI interaction audit record."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    model: str = ""
+    purpose: str = "unspecified"
+    input_preview: str = ""
+    confidence: float = 0.0
+    needs_human_review: bool = False
+    latency_ms: float = 0.0
+    token_usage: dict[str, int] | None = None
+    success: bool = True
+    error: str | None = None
+    human_action: str | None = None  # approved | rejected | modified
+    human_reviewer_id: str | None = None
+
+
+class AIAuditLog:
+    """In-memory audit log with structured logging output."""
+
+    def __init__(self, max_entries: int = 1000):
+        self._entries: deque[AuditEntry] = deque(maxlen=max_entries)
+        self._lock = threading.Lock()
+
+    def log(self, entry: AuditEntry) -> None:
+        with self._lock:
+            self._entries.append(entry)
+
+        log_data = {
+            "type": "ai_interaction",
+            "id": entry.id,
+            "timestamp": entry.timestamp,
+            "model": entry.model,
+            "purpose": entry.purpose,
+            "confidence": entry.confidence,
+            "needs_human_review": entry.needs_human_review,
+            "latency_ms": round(entry.latency_ms, 1),
+            "success": entry.success,
+        }
+
+        if entry.error:
+            log_data["error"] = entry.error
+            logger.warning("[AI_AUDIT] %s", json.dumps(log_data))
+        elif entry.confidence < 0.5:
+            logger.warning("[AI_AUDIT] %s", json.dumps(log_data))
+        else:
+            logger.info("[AI_AUDIT] %s", json.dumps(log_data))
+
+    VALID_ACTIONS = {"approved", "rejected", "modified"}
+
+    def record_human_review(
+        self, audit_id: str, action: str, reviewer_id: str | None = None
+    ) -> None:
+        if action not in self.VALID_ACTIONS:
+            raise ValueError(f"Invalid action: {action}. Must be one of {self.VALID_ACTIONS}")
+
+        with self._lock:
+            for entry in self._entries:
+                if entry.id == audit_id:
+                    entry.human_action = action
+                    entry.human_reviewer_id = reviewer_id
+                    break
+            else:
+                logger.warning("[AI_AUDIT] audit_id not found: %s", audit_id)
+                return
+
+        # Log the review event without adding a duplicate to the buffer
+        log_data = {
+            "type": "ai_interaction_review",
+            "id": entry.id,
+            "purpose": f"human-review:{entry.purpose}",
+            "action": action,
+            "reviewer_id": reviewer_id,
+        }
+        logger.info("[AI_AUDIT] %s", json.dumps(log_data))
+
+    def get_recent_entries(self, count: int = 50) -> list[AuditEntry]:
+        with self._lock:
+            return list(self._entries)[-count:]
+
+    def get_stats(self, window_seconds: int = 3600) -> dict:
+        cutoff = datetime.now(timezone.utc) - timedelta(seconds=window_seconds)
+        with self._lock:
+            recent = [
+                e for e in self._entries
+                if datetime.fromisoformat(e.timestamp) >= cutoff
+            ]
+
+        if not recent:
+            return {
+                "total_calls": 0,
+                "success_rate": 1.0,
+                "avg_confidence": 0.0,
+                "avg_latency_ms": 0.0,
+                "human_review_rate": 0.0,
+                "error_rate": 0.0,
+            }
+
+        successes = [e for e in recent if e.success]
+        reviews = [e for e in recent if e.needs_human_review]
+
+        return {
+            "total_calls": len(recent),
+            "success_rate": len(successes) / len(recent),
+            "avg_confidence": sum(e.confidence for e in recent) / len(recent),
+            "avg_latency_ms": sum(e.latency_ms for e in recent) / len(recent),
+            "human_review_rate": len(reviews) / len(recent),
+            "error_rate": 1 - (len(successes) / len(recent)),
+        }
+
+
+# --- Singleton ---
+
+ai_audit_log = AIAuditLog()

package/templates/ai/guardrails-py/backend/app/ai/client.py.template

@@ -0,0 +1,323 @@
+"""AI Client — Central wrapper for all LLM interactions.
+
+Every AI call goes through this client, which provides:
+- Input validation and prompt injection detection
+- Output validation against Pydantic models
+- Confidence scoring with human review routing
+- Structured audit logging (EU AI Act Art. 12)
+- Health metrics collection (NIST AI RMF Manage 3.2)
+
+Compliance: EU AI Act (2024/1689), NIST AI RMF 1.0
+"""
+
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, TypeVar
+
+import anthropic
+from pydantic import BaseModel, ValidationError
+
+from app.ai.audit_log import ai_audit_log, AuditEntry
+from app.ai.input_guard import validate_input, InputValidationResult
+from app.ai.health import ai_health_metrics
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass
+class AIClientConfig:
+    """Configuration for the AI client."""
+
+    api_key: str = field(default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY", ""))
+    model: str = "claude-sonnet-4-20250514"
+    confidence_threshold: float = 0.7
+    max_input_length: int = 100_000
+    detect_injection: bool = True
+    audit_log: bool = True
+    moderator: Callable[[str], bool] | None = None
+
+    def __post_init__(self):
+        if not self.api_key:
+            raise ValueError("ANTHROPIC_API_KEY environment variable is required")
+
+
+@dataclass
+class AIResponse:
+    """Response from an AI call with metadata."""
+
+    data: Any
+    confidence: float
+    needs_human_review: bool
+    model: str
+    latency_ms: float
+    token_usage: dict[str, int] | None = None
+    ai_generated: bool = True
+    audit_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    error: str | None = None
+    blocked: bool = False
+
+
+class AIClient:
+    """Central AI client with guardrails, validation, and audit logging."""
+
+    def __init__(self, config: AIClientConfig | None = None):
+        self.config = config or AIClientConfig()
+        self.client = anthropic.AsyncAnthropic(api_key=self.config.api_key)
+
+    async def generate(
+        self,
+        prompt: str,
+        schema: type[T],
+        system_prompt: str | None = None,
+        context: str | None = None,
+        model: str | None = None,
+        confidence_threshold: float | None = None,
+        max_retries: int = 2,
+        purpose: str = "unspecified",
+    ) -> AIResponse:
+        """Generate a structured response validated against a Pydantic model.
+
+        Args:
+            prompt: The user prompt.
+            schema: Pydantic model class to validate output against.
+            system_prompt: Optional system prompt override.
+            context: Additional context appended to the prompt.
+            model: Override model for this call.
+            confidence_threshold: Override threshold for human review.
+            max_retries: Max retries on validation failure.
+            purpose: Business purpose tag for audit log.
+
+        Returns:
+            AIResponse with validated data, confidence score, and audit trail.
+        """
+        start_time = time.monotonic()
+        model = model or self.config.model
+        threshold = confidence_threshold if confidence_threshold is not None else self.config.confidence_threshold
+
+        # Step 1: Input validation
+        input_validation = self._validate_inputs(prompt, context)
+        if input_validation.blocked:
+            return self._build_blocked_response(input_validation, start_time, model, purpose)
+
+        # Step 2: Call model with retries
+        last_error: Exception | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                response = await self._call_model(prompt, system_prompt, context, model)
+
+                # Step 3: Parse and validate output
+                try:
+                    parsed = schema.model_validate_json(response["content"])
+                except (ValidationError, ValueError) as e:
+                    last_error = e
+                    if attempt < max_retries:
+                        continue
+                    break
+
+                # Step 4: Score confidence
+                confidence = self._score_confidence(response)
+                needs_review = confidence < threshold
+
+                # Step 5: Build response
+                result = AIResponse(
+                    data=parsed,
+                    confidence=confidence,
+                    needs_human_review=needs_review,
+                    model=model,
+                    latency_ms=(time.monotonic() - start_time) * 1000,
+                    token_usage=response.get("usage"),
+                    ai_generated=True,
+                )
+
+                # Step 6: Audit log
+                if self.config.audit_log:
+                    self._log_interaction(result, prompt, purpose)
+
+                # Step 7: Health metrics
+                ai_health_metrics.record_call(
+                    model=model,
+                    latency_ms=result.latency_ms,
+                    confidence=confidence,
+                    success=True,
+                    token_usage=response.get("usage"),
+                )
+
+                return result
+
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries:
+                    continue
+
+        # All retries exhausted
+        latency = (time.monotonic() - start_time) * 1000
+        ai_health_metrics.record_call(model=model, latency_ms=latency, confidence=0, success=False)
+
+        return AIResponse(
+            data=None,
+            confidence=0,
+            needs_human_review=True,
+            model=model,
+            latency_ms=latency,
+            error=str(last_error) if last_error else "AI call failed after retries",
+        )
+
+    def _validate_inputs(self, prompt: str, context: str | None) -> InputValidationResult:
+        full_input = f"{prompt}\n{context}" if context else prompt
+
+        if len(full_input) > self.config.max_input_length:
+            return InputValidationResult(
+                blocked=True,
+                reason=f"Input exceeds maximum length ({self.config.max_input_length} chars)",
+            )
+
+        if self.config.detect_injection:
+            result = validate_input(full_input)
+            if result.blocked:
+                return result
+
+        if self.config.moderator and self.config.moderator(full_input):
+            return InputValidationResult(blocked=True, reason="Content blocked by moderation policy")
+
+        return InputValidationResult(blocked=False)
+
+    async def _call_model(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        context: str | None,
+        model: str,
+    ) -> dict:
+        user_content = f"{prompt}\n\nContext:\n{context}" if context else prompt
+
+        response = await self.client.messages.create(
+            model=model,
+            max_tokens=4096,
+            system=system_prompt or (
+                f"You are an AI assistant for {{PROJECT_NAME}}. "
+                "Respond with valid JSON matching the requested schema. Be precise and factual."
+            ),
+            messages=[{"role": "user", "content": user_content}],
+        )
+
+        text = ""
+        for block in response.content:
+            if block.type == "text":
+                text = block.text
+                break
+
+        # Extract JSON from response
+        content = self._extract_json(text)
+
+        return {
+            "content": content,
+            "usage": {
+                "input_tokens": response.usage.input_tokens,
+                "output_tokens": response.usage.output_tokens,
+            },
+            "stop_reason": response.stop_reason,
+        }
+
+    def _extract_json(self, text: str) -> str:
+        """Extract JSON from model response, handling markdown code blocks."""
+        import re
+
+        text = text.strip()
+
+        # Try direct parse
+        if text.startswith("{") or text.startswith("["):
+            return text
+
+        # Extract from code blocks
+        match = re.search(r"```(?:json)?\s*\n?([\s\S]*?)\n?```", text)
+        if match:
+            return match.group(1).strip()
+
+        return text
+
+    def _score_confidence(self, response: dict) -> float:
+        score = 0.85
+
+        if response.get("stop_reason") == "max_tokens":
+            score -= 0.3
+
+        usage = response.get("usage", {})
+        output_tokens = usage.get("output_tokens", 0)
+
+        if output_tokens < 10:
+            score -= 0.2
+        if output_tokens > 3000:
+            score -= 0.1
+
+        return max(0.0, min(1.0, score))
+
+    def _log_interaction(self, result: AIResponse, prompt: str, purpose: str) -> None:
+        entry = AuditEntry(
+            id=result.audit_id,
+            model=result.model,
+            purpose=purpose,
+            input_preview=prompt[:100] + ("..." if len(prompt) > 100 else ""),
+            confidence=result.confidence,
+            needs_human_review=result.needs_human_review,
+            latency_ms=result.latency_ms,
+            token_usage=result.token_usage,
+            success=result.error is None,
+            error=result.error,
+        )
+        ai_audit_log.log(entry)
+
+    def _build_blocked_response(
+        self,
+        validation: InputValidationResult,
+        start_time: float,
+        model: str,
+        purpose: str,
+    ) -> AIResponse:
+        result = AIResponse(
+            data=None,
+            confidence=0,
+            needs_human_review=False,
+            model=model,
+            latency_ms=(time.monotonic() - start_time) * 1000,
+            ai_generated=False,
+            error=f"Input blocked: {validation.reason}",
+            blocked=True,
+        )
+
+        if self.config.audit_log:
+            ai_audit_log.log(AuditEntry(
+                id=result.audit_id,
+                model=model,
+                purpose=purpose,
+                input_preview="[BLOCKED]",
+                confidence=0,
+                needs_human_review=False,
+                latency_ms=result.latency_ms,
+                success=False,
+                error=validation.reason,
+            ))
+
+        return result
+
+
+# --- Singleton ---
+
+_default_client: AIClient | None = None
+
+
+def get_ai_client(config: AIClientConfig | None = None) -> AIClient:
+    """Get the singleton AI client. Call with config on first use only."""
+    global _default_client
+    if _default_client is None:
+        _default_client = AIClient(config)
+    elif config is not None:
+        import warnings
+        warnings.warn(
+            "AIClient already initialized; ignoring provided config. "
+            "Call get_ai_client() without arguments or use AIClient(config) directly.",
+            UserWarning,
+            stacklevel=2,
+        )
+    return _default_client