forge-dev 0.1.0__py3-none-any.whl

forge_core/models.py

@@ -0,0 +1,332 @@
+"""Core configuration models for Forge.
+
+These models define the structure of all Forge configuration files:
+- Global user config (~/.forge/user/config.yaml)
+- Project context (.forge/context.yaml)
+- Standards and patterns
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ── Enums ──────────────────────────────────────────────────────────────────
+
+class CloudProvider(str, Enum):
+    AZURE = "azure"
+    AWS = "aws"
+    GCP = "gcp"
+    RAILWAY = "railway"
+    VERCEL = "vercel"
+    FLY = "fly"
+    OTHER = "other"
+
+
+class BackendFramework(str, Enum):
+    FASTAPI = "python/fastapi"
+    DJANGO = "python/django"
+    FLASK = "python/flask"
+    EXPRESS = "node/express"
+    FASTIFY = "node/fastify"
+    NESTJS = "node/nestjs"
+    OTHER = "other"
+
+
+class FrontendFramework(str, Enum):
+    REACT = "react"
+    NEXT = "nextjs"
+    VUE = "vue"
+    SVELTE = "svelte"
+    ANGULAR = "angular"
+    OTHER = "other"
+
+
+class DatabaseType(str, Enum):
+    POSTGRESQL = "postgresql"
+    MYSQL = "mysql"
+    MONGODB = "mongodb"
+    ORACLE = "oracle"
+    SQLSERVER = "sqlserver"
+    SQLITE = "sqlite"
+    COSMOSDB = "cosmosdb"
+    OTHER = "other"
+
+
+class AuthPattern(str, Enum):
+    AZURE_AD_B2C = "azure-ad-b2c"
+    AUTH0 = "auth0"
+    CLERK = "clerk"
+    SUPABASE_AUTH = "supabase-auth"
+    KEYCLOAK = "keycloak"
+    CUSTOM_JWT = "custom-jwt"
+    NONE = "none"
+
+
+class ProjectType(str, Enum):
+    SAAS = "saas"
+    API = "api"
+    INTERNAL_TOOL = "internal-tool"
+    LIBRARY = "library"
+    CLI = "cli"
+    MICROSERVICE = "microservice"
+    OTHER = "other"
+
+
+class Regulatory(str, Enum):
+    HIPAA = "hipaa"
+    FERPA = "ferpa"
+    GDPR = "gdpr"
+    SOC2 = "soc2"
+    PCI_DSS = "pci-dss"
+    NONE = "none"
+
+
+class RequirementType(str, Enum):
+    PRD = "prd"
+    USER_STORY = "user-story"
+    EPIC = "epic"
+    FEATURE_REQUEST = "feature-request"
+    BUG_FIX = "bug-fix"
+    CONVERSATION = "conversation"
+    UNKNOWN = "unknown"
+
+
+class ProjectState(str, Enum):
+    EMPTY = "empty"
+    HAS_DOCS = "has-docs"
+    HAS_CODE = "has-code"
+    HAS_FORGE = "has-forge"
+
+
+# ── Configuration Models ───────────────────────────────────────────────────
+
+class AIConfig(BaseModel):
+    """AI-specific configuration for projects that use AI internally."""
+    model_config = ConfigDict(extra="allow")
+
+    enabled: bool = Field(default=False, description="Whether the project uses AI capabilities")
+    providers: list[str] = Field(default_factory=list, description="AI providers used (anthropic, openai, etc.)")
+    observability: bool = Field(default=True, description="Track AI traces, costs, safety, sessions")
+    cost_alerts: bool = Field(default=True, description="Enable cost alerting for AI usage")
+    safety_checks: bool = Field(default=True, description="Enable prompt injection and safety monitoring")
+
+
+class ObservabilityConfig(BaseModel):
+    """Observability stack configuration."""
+    model_config = ConfigDict(extra="allow")
+
+    apm: str = Field(default="azure-app-insights", description="APM provider")
+    metrics: str = Field(default="prometheus", description="Metrics collection")
+    logs: str = Field(default="loki", description="Log aggregation")
+    dashboards: str = Field(default="grafana", description="Dashboard provider")
+    tracing: bool = Field(default=True, description="Distributed tracing enabled")
+
+
+class APIConfig(BaseModel):
+    """API design configuration."""
+    model_config = ConfigDict(extra="allow")
+
+    style: str = Field(default="rest", description="API style (rest, graphql)")
+    spec: str = Field(default="openapi-3.1", description="API specification format")
+    mcp_ready: bool = Field(default=True, description="APIs designed for MCP consumption")
+    versioning: str = Field(default="url-prefix", description="API versioning strategy")
+    rate_limiting: bool = Field(default=True, description="Enable rate limiting")
+
+
+class CICDConfig(BaseModel):
+    """CI/CD configuration."""
+    model_config = ConfigDict(extra="allow")
+
+    provider: str = Field(default="github-actions", description="CI/CD provider")
+    iac: str = Field(default="pulumi", description="Infrastructure as Code tool")
+    environments: list[str] = Field(
+        default_factory=lambda: ["dev", "staging", "production"],
+        description="Deployment environments"
+    )
+    auto_deploy_dev: bool = Field(default=True, description="Auto-deploy to dev on merge")
+
+
+class StandardsConfig(BaseModel):
+    """Code standards enforcement."""
+    model_config = ConfigDict(extra="allow")
+
+    type_checking: str = Field(default="strict", description="Type checking level")
+    linting: str = Field(default="enforced", description="Linting enforcement level")
+    test_coverage_min: int = Field(default=80, description="Minimum test coverage percentage")
+    patterns: list[str] = Field(default_factory=list, description="Approved patterns")
+    anti_patterns: list[str] = Field(default_factory=list, description="Prohibited patterns")
+
+
+class MCPEntry(BaseModel):
+    """An MCP server entry in the registry."""
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(..., description="MCP server name")
+    description: str = Field(default="", description="What this MCP provides")
+    url: str = Field(default="", description="MCP server URL or command")
+    transport: str = Field(default="stdio", description="Transport type (stdio, http)")
+    auto_suggest: bool = Field(default=False, description="Suggest when relevant dependencies detected")
+    conditions: list[str] = Field(
+        default_factory=list,
+        description="Conditions that trigger auto-suggestion"
+    )
+
+
+# ── Top-Level Configs ──────────────────────────────────────────────────────
+
+class UserConfig(BaseModel):
+    """Global user configuration (~/.forge/user/config.yaml).
+    
+    These are the user's defaults — applied to every new project unless overridden.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    cloud: CloudProvider = Field(default=CloudProvider.AZURE)
+    backend: BackendFramework | None = Field(
+        default=None,
+        description="Default backend. None means ask each time."
+    )
+    frontend: FrontendFramework = Field(default=FrontendFramework.REACT)
+    database: DatabaseType = Field(default=DatabaseType.POSTGRESQL)
+    auth: AuthPattern = Field(default=AuthPattern.AZURE_AD_B2C)
+    ai: AIConfig = Field(default_factory=AIConfig)
+    observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
+    api: APIConfig = Field(default_factory=APIConfig)
+    cicd: CICDConfig = Field(default_factory=CICDConfig)
+    standards: StandardsConfig = Field(default_factory=StandardsConfig)
+    mcps: list[MCPEntry] = Field(default_factory=list)
+
+
+class ProjectContext(BaseModel):
+    """Per-project context (.forge/context.yaml).
+    
+    Captures all decisions made for this specific project.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    # Project identity
+    name: str = Field(..., description="Project name")
+    type: ProjectType = Field(default=ProjectType.SAAS)
+    description: str = Field(default="", description="One-line project description")
+    regulatory: list[Regulatory] = Field(default_factory=list)
+
+    # Stack decisions
+    cloud: CloudProvider = Field(default=CloudProvider.AZURE)
+    backend: BackendFramework = Field(default=BackendFramework.FASTAPI)
+    frontend: FrontendFramework = Field(default=FrontendFramework.REACT)
+    database: DatabaseType = Field(default=DatabaseType.POSTGRESQL)
+    auth: AuthPattern = Field(default=AuthPattern.AZURE_AD_B2C)
+
+    # Feature configs
+    ai: AIConfig = Field(default_factory=AIConfig)
+    observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
+    api: APIConfig = Field(default_factory=APIConfig)
+    cicd: CICDConfig = Field(default_factory=CICDConfig)
+    standards: StandardsConfig = Field(default_factory=StandardsConfig)
+
+    # State
+    forge_version: str = Field(default="0.1.0", description="Forge version used to create")
+    created_at: str = Field(default="", description="ISO timestamp of creation")
+    last_audit: str = Field(default="", description="ISO timestamp of last audit")
+
+
+class ForgeBrief(BaseModel):
+    """Normalized requirement document produced by the Intake phase.
+    
+    This is what every requirement gets converted into, regardless of
+    whether the input was a PRD, user story, Slack message, or conversation.
+    """
+    model_config = ConfigDict(extra="allow")
+
+    # Classification
+    source_type: RequirementType = Field(default=RequirementType.UNKNOWN)
+    completeness_score: float = Field(
+        default=0.0, ge=0.0, le=1.0,
+        description="How complete the requirement is (0=vague, 1=fully specified)"
+    )
+
+    # Core content
+    objective: str = Field(default="", description="What this project/feature achieves")
+    users: list[str] = Field(default_factory=list, description="Target user personas")
+    features: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="List of features with name, description, mvp flag, priority"
+    )
+    
+    # Scope
+    mvp_defined: bool = Field(default=False, description="Whether MVP scope was defined in source")
+    mvp_features: list[str] = Field(default_factory=list, description="Features in MVP scope")
+    
+    # Dependencies & constraints
+    external_dependencies: list[str] = Field(default_factory=list)
+    integrations: list[str] = Field(default_factory=list)
+    regulatory_requirements: list[Regulatory] = Field(default_factory=list)
+    
+    # Gaps detected
+    gaps: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="Detected gaps: [{severity, area, description, suggestion}]"
+    )
+    assumptions: list[str] = Field(
+        default_factory=list,
+        description="Assumptions made to fill non-critical gaps"
+    )
+
+    # Implementation guidance for AI coding agents
+    implementation_order: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Ordered phases for AI-agent implementation"
+    )
+
+
+class ForgeTask(BaseModel):
+    """A single implementation task optimized for AI coding agents."""
+    model_config = ConfigDict(extra="allow")
+
+    id: str = Field(..., description="Task identifier (e.g., T001)")
+    phase: str = Field(..., description="Implementation phase this belongs to")
+    title: str = Field(..., description="What this task accomplishes")
+    description: str = Field(default="", description="Detailed description")
+    files_affected: list[str] = Field(default_factory=list, description="Files to create/modify")
+    dependencies: list[str] = Field(default_factory=list, description="Task IDs this depends on")
+    types_needed: list[str] = Field(
+        default_factory=list,
+        description="Types/interfaces that must exist before this task"
+    )
+    acceptance_criteria: list[str] = Field(
+        default_factory=list,
+        description="Verifiable criteria (tests that must pass)"
+    )
+    estimated_complexity: str = Field(default="medium", description="low/medium/high")
+    status: str = Field(default="pending", description="pending/in-progress/done/blocked")
+
+
+class MaturityReport(BaseModel):
+    """Assessment of an existing project against Forge standards."""
+    model_config = ConfigDict(extra="allow")
+
+    project_name: str = Field(...)
+    assessed_at: str = Field(default="", description="ISO timestamp")
+    forge_version: str = Field(default="0.1.0")
+    
+    overall_score: float = Field(default=0.0, ge=0.0, le=1.0)
+    
+    categories: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Scores by category: {category: {score, findings, recommendations}}"
+    )
+    
+    opportunities: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Improvement opportunities: [{priority, category, description, effort}]"
+    )
+    
+    plan: list[ForgeTask] = Field(
+        default_factory=list,
+        description="Suggested tasks to close gaps"
+    )

forge_core/phases/__init__.py

@@ -0,0 +1 @@
+"""Forge workflow phases."""

forge_core/phases/coherence.py

@@ -0,0 +1,293 @@
+"""Coherence Checker — validates standards, patterns, and workflow changes.
+
+When a new standard is added or the workflow is modified, the coherence
+checker verifies:
+1. No conflicts between standards
+2. No race conditions between agents
+3. No philosophical contradictions
+4. Impact on existing projects
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class CoherenceIssue:
+    """A detected coherence issue."""
+    severity: str  # error, warning, info
+    category: str  # conflict, race_condition, philosophy, impact
+    description: str
+    standard_a: str = ""
+    standard_b: str = ""
+    suggestion: str = ""
+
+
+@dataclass
+class CoherenceReport:
+    """Result of a coherence check."""
+    issues: list[CoherenceIssue] = field(default_factory=list)
+    passed: bool = True
+
+    def add_issue(self, issue: CoherenceIssue) -> None:
+        self.issues.append(issue)
+        if issue.severity == "error":
+            self.passed = False
+
+    def summary(self) -> str:
+        if not self.issues:
+            return "✓ No coherence issues detected."
+
+        lines = []
+        errors = [i for i in self.issues if i.severity == "error"]
+        warnings = [i for i in self.issues if i.severity == "warning"]
+        infos = [i for i in self.issues if i.severity == "info"]
+
+        if errors:
+            lines.append(f"✗ {len(errors)} error(s)")
+            for e in errors:
+                lines.append(f"  ERROR [{e.category}]: {e.description}")
+                if e.suggestion:
+                    lines.append(f"    → {e.suggestion}")
+
+        if warnings:
+            lines.append(f"⚠ {len(warnings)} warning(s)")
+            for w in warnings:
+                lines.append(f"  WARN [{w.category}]: {w.description}")
+                if w.suggestion:
+                    lines.append(f"    → {w.suggestion}")
+
+        if infos:
+            lines.append(f"ℹ {len(infos)} info(s)")
+            for i in infos:
+                lines.append(f"  INFO [{i.category}]: {i.description}")
+
+        return "\n".join(lines)
+
+
+def check_standards_coherence(standards: list[dict]) -> CoherenceReport:
+    """Check all standards for internal coherence.
+    
+    Looks for:
+    - Contradictory rules (e.g., "always use ORM" vs "always use raw SQL")
+    - Overlapping scope (two standards that govern the same area differently)
+    - Missing dependencies (standard A requires B but B doesn't exist)
+    """
+    report = CoherenceReport()
+
+    # Group standards by area/category
+    by_area: dict[str, list[dict]] = {}
+    for std in standards:
+        area = std.get("area", std.get("category", "general"))
+        by_area.setdefault(area, []).append(std)
+
+    # Check for overlapping areas with different rules
+    for area, stds in by_area.items():
+        if len(stds) > 1:
+            names = [s.get("name", s.get("_file", "unknown")) for s in stds]
+            report.add_issue(CoherenceIssue(
+                severity="warning",
+                category="overlap",
+                description=(
+                    f"Multiple standards govern '{area}': {names}. "
+                    f"Verify they don't contradict each other."
+                ),
+                suggestion="Review and consolidate or explicitly define precedence.",
+            ))
+
+    # Check for conflicting enforcement levels
+    enforcement_standards = [
+        s for s in standards
+        if "enforcement" in s or "level" in s
+    ]
+    for i, std_a in enumerate(enforcement_standards):
+        for std_b in enforcement_standards[i + 1:]:
+            area_a = std_a.get("area", "")
+            area_b = std_b.get("area", "")
+            if area_a == area_b:
+                level_a = std_a.get("enforcement", std_a.get("level", ""))
+                level_b = std_b.get("enforcement", std_b.get("level", ""))
+                if level_a != level_b:
+                    report.add_issue(CoherenceIssue(
+                        severity="error",
+                        category="conflict",
+                        description=(
+                            f"Conflicting enforcement for '{area_a}': "
+                            f"'{level_a}' vs '{level_b}'"
+                        ),
+                        standard_a=std_a.get("name", ""),
+                        standard_b=std_b.get("name", ""),
+                        suggestion="Resolve which enforcement level should apply.",
+                    ))
+
+    return report
+
+
+def check_new_standard(
+    new_standard: dict,
+    existing_standards: list[dict],
+) -> CoherenceReport:
+    """Check if a new standard is coherent with existing ones.
+    
+    This is called before adding a new standard to verify it
+    won't break anything.
+    """
+    report = CoherenceReport()
+
+    new_area = new_standard.get("area", new_standard.get("category", "general"))
+    new_name = new_standard.get("name", "new standard")
+
+    # Check for area conflicts
+    for existing in existing_standards:
+        ex_area = existing.get("area", existing.get("category", "general"))
+        ex_name = existing.get("name", existing.get("_file", "unknown"))
+
+        if ex_area == new_area:
+            report.add_issue(CoherenceIssue(
+                severity="warning",
+                category="overlap",
+                description=(
+                    f"New standard '{new_name}' covers the same area ('{new_area}') "
+                    f"as existing standard '{ex_name}'."
+                ),
+                standard_a=new_name,
+                standard_b=ex_name,
+                suggestion=(
+                    "Consider merging with the existing standard or "
+                    "explicitly defining how they interact."
+                ),
+            ))
+
+        # Check for keyword conflicts in rules
+        new_rules = set(_extract_keywords(new_standard))
+        ex_rules = set(_extract_keywords(existing))
+        conflicts = new_rules & ex_rules
+        if conflicts and ex_area == new_area:
+            report.add_issue(CoherenceIssue(
+                severity="info",
+                category="overlap",
+                description=(
+                    f"Overlapping keywords between '{new_name}' and "
+                    f"'{ex_name}': {conflicts}"
+                ),
+                suggestion="Verify these standards don't give contradictory guidance.",
+            ))
+
+    return report
+
+
+def check_workflow_change(
+    change_description: str,
+    current_standards: list[dict],
+) -> CoherenceReport:
+    """Check if a workflow-level change would cause issues.
+    
+    This is a higher-level check for when the workflow itself
+    changes (not just a standard).
+    """
+    report = CoherenceReport()
+
+    # Basic impact analysis — in a real implementation, this would
+    # be much more sophisticated, possibly using an LLM to analyze
+    # the change against the full workflow.
+    change_lower = change_description.lower()
+
+    # Check for phase ordering changes
+    if any(word in change_lower for word in ["reorder", "phase", "sequence", "before", "after"]):
+        report.add_issue(CoherenceIssue(
+            severity="warning",
+            category="philosophy",
+            description=(
+                "This change may affect the AI-optimized implementation order. "
+                "The current order (types → infra → auth → data → services → "
+                "api → frontend → observability → testing → cicd) is designed "
+                "to minimize AI hallucinations."
+            ),
+            suggestion=(
+                "Verify the new order still provides complete context at each "
+                "phase for the AI coding agent."
+            ),
+        ))
+
+    # Check for security changes
+    if any(word in change_lower for word in ["auth", "security", "rbac", "permission"]):
+        report.add_issue(CoherenceIssue(
+            severity="info",
+            category="impact",
+            description=(
+                "Security-related workflow changes may require re-auditing "
+                "all existing projects."
+            ),
+            suggestion="Run `forge assess` on existing projects after this change.",
+        ))
+
+    return report
+
+
+def build_impact_prompt(
+    change_description: str,
+    current_standards: list[dict],
+    affected_projects: list[str],
+) -> str:
+    """Build a prompt for the LLM to do a deep impact analysis.
+    
+    Used when the basic checks aren't enough and we need AI
+    to reason about the change's impact.
+    """
+    standards_summary = "\n".join(
+        f"- {s.get('name', 'unnamed')}: {s.get('description', '')}"
+        for s in current_standards
+    )
+
+    return f"""You are Forge's coherence analyzer. A workflow change is being proposed.
+
+## Proposed Change
+{change_description}
+
+## Current Standards
+{standards_summary}
+
+## Projects That May Be Affected
+{', '.join(affected_projects) if affected_projects else 'None tracked'}
+
+## Analyze For:
+1. **Conflicts**: Does this change contradict any existing standard?
+2. **Race Conditions**: Could this cause agents to produce conflicting outputs?
+3. **Philosophy Changes**: Does this shift the fundamental approach?
+4. **Implementation Impact**: What needs to change in existing projects?
+5. **Breaking Changes**: Will this break anything for users on older versions?
+
+Respond with a JSON object:
+{{
+  "issues": [
+    {{
+      "severity": "error|warning|info",
+      "category": "conflict|race_condition|philosophy|impact|breaking",
+      "description": "...",
+      "suggestion": "..."
+    }}
+  ],
+  "safe_to_apply": true/false,
+  "migration_needed": true/false,
+  "migration_steps": ["step 1", "step 2"]
+}}"""
+
+
+# ── Private helpers ────────────────────────────────────────────────────────
+
+def _extract_keywords(standard: dict) -> list[str]:
+    """Extract meaningful keywords from a standard for comparison."""
+    keywords = []
+    for key in ("rules", "requirements", "guidelines", "must", "must_not"):
+        val = standard.get(key, [])
+        if isinstance(val, list):
+            for item in val:
+                if isinstance(item, str):
+                    keywords.extend(item.lower().split())
+        elif isinstance(val, str):
+            keywords.extend(val.lower().split())
+    return [k for k in keywords if len(k) > 3]  # filter noise