forge-dev 0.1.0__py3-none-any.whl

forge_core/phases/context.py

@@ -0,0 +1,264 @@
+"""Context Phase — resolves the full project context.
+
+Takes detection results + user config + brief and produces
+a ProjectContext that captures all decisions for this project.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from forge_core.detector import ProjectDetection
+from forge_core.models import (
+    AIConfig,
+    APIConfig,
+    AuthPattern,
+    BackendFramework,
+    CICDConfig,
+    CloudProvider,
+    DatabaseType,
+    FrontendFramework,
+    ObservabilityConfig,
+    ProjectContext,
+    ProjectType,
+    Regulatory,
+    StandardsConfig,
+    UserConfig,
+)
+
+
+def resolve_context(
+    detection: ProjectDetection,
+    user_config: UserConfig,
+    project_name: str | None = None,
+    overrides: dict | None = None,
+) -> ProjectContext:
+    """Resolve the full project context from detection + user defaults + overrides.
+    
+    Priority order (highest wins):
+    1. Explicit overrides passed in
+    2. Detection results (what we found in the code)
+    3. User config defaults
+    
+    Args:
+        detection: What we found in the directory
+        user_config: Global user defaults
+        project_name: Override for project name
+        overrides: Explicit overrides for any field
+    """
+    overrides = overrides or {}
+
+    # Project name: override > directory name
+    name = project_name or overrides.get("name") or detection.path.name
+
+    # Backend: override > detected > user default (None means ask)
+    backend = _resolve_backend(detection, user_config, overrides)
+
+    # Frontend: override > detected > user default
+    frontend = _resolve_enum(
+        FrontendFramework,
+        overrides.get("frontend"),
+        detection.detected_stack.get("frontend"),
+        user_config.frontend,
+    )
+
+    context = ProjectContext(
+        name=name,
+        type=overrides.get("type", ProjectType.SAAS),
+        description=overrides.get("description", ""),
+        regulatory=_resolve_regulatory(overrides),
+        cloud=_resolve_enum(
+            CloudProvider,
+            overrides.get("cloud"),
+            None,
+            user_config.cloud,
+        ),
+        backend=backend,
+        frontend=frontend,
+        database=_resolve_enum(
+            DatabaseType,
+            overrides.get("database"),
+            None,
+            user_config.database,
+        ),
+        auth=_resolve_enum(
+            AuthPattern,
+            overrides.get("auth"),
+            None,
+            user_config.auth,
+        ),
+        ai=_merge_config(AIConfig, user_config.ai, overrides.get("ai", {})),
+        observability=_merge_config(
+            ObservabilityConfig, user_config.observability, overrides.get("observability", {})
+        ),
+        api=_merge_config(APIConfig, user_config.api, overrides.get("api", {})),
+        cicd=_merge_config(CICDConfig, user_config.cicd, overrides.get("cicd", {})),
+        standards=_merge_config(
+            StandardsConfig, user_config.standards, overrides.get("standards", {})
+        ),
+        forge_version=overrides.get("forge_version", "0.1.0"),
+        created_at=datetime.now(timezone.utc).isoformat(),
+    )
+
+    return context
+
+
+def save_context(context: ProjectContext, project_path: Path) -> Path:
+    """Save ProjectContext to .forge/context.yaml."""
+    forge_dir = project_path / ".forge"
+    forge_dir.mkdir(parents=True, exist_ok=True)
+
+    context_path = forge_dir / "context.yaml"
+    with open(context_path, "w") as f:
+        yaml.dump(
+            context.model_dump(mode="json"),
+            f,
+            default_flow_style=False,
+            sort_keys=False,
+        )
+
+    return context_path
+
+
+def load_context(project_path: Path) -> ProjectContext | None:
+    """Load an existing ProjectContext."""
+    context_path = project_path / ".forge" / "context.yaml"
+    if not context_path.exists():
+        return None
+    with open(context_path) as f:
+        data = yaml.safe_load(f) or {}
+    return ProjectContext(**data)
+
+
+def build_context_prompt(detection: ProjectDetection, user_config: UserConfig) -> str:
+    """Build a prompt for the LLM to help resolve context interactively.
+    
+    Used when forge init detects an empty directory and needs to
+    have a conversation with the user.
+    """
+    return f"""You are Forge, an AI development workflow engine. Help the user set up their project context.
+
+## Current Detection
+{detection.summary()}
+
+## User Defaults
+- Cloud: {user_config.cloud.value}
+- Backend: {user_config.backend.value if user_config.backend else 'Not set (ask each time)'}
+- Frontend: {user_config.frontend.value}
+- Database: {user_config.database.value}
+- Auth: {user_config.auth.value}
+- AI enabled: {user_config.ai.enabled}
+- Observability: {user_config.observability.apm} + {user_config.observability.metrics} + {user_config.observability.logs}
+
+## Instructions
+Based on the detection and user defaults, help resolve the project context.
+If the directory is empty, ask the user:
+1. What is this project? (name, description, type)
+2. Are there any regulatory requirements? (HIPAA, FERPA, etc.)
+3. Backend preference for this project? (user default is to ask each time)
+4. Any overrides to the defaults above?
+5. Does this project use AI capabilities?
+
+If the directory has code, confirm the detected stack and ask about anything not detected.
+
+Keep questions concise. One question at a time if in conversation mode.
+Suggest defaults based on the user's preferences — they can just confirm."""
+
+
+def get_questions_for_empty_project(user_config: UserConfig) -> list[dict]:
+    """Return the questions to ask for a brand new project."""
+    questions = [
+        {
+            "id": "mission",
+            "question": "What is this project? Give me a one-liner.",
+            "type": "text",
+            "required": True,
+        },
+        {
+            "id": "type",
+            "question": "What type of project is this?",
+            "type": "choice",
+            "options": [t.value for t in ProjectType],
+            "default": ProjectType.SAAS.value,
+        },
+        {
+            "id": "regulatory",
+            "question": "Any regulatory requirements?",
+            "type": "multi_choice",
+            "options": [r.value for r in Regulatory],
+            "default": [Regulatory.NONE.value],
+        },
+    ]
+
+    # Only ask about backend if user doesn't have a default
+    if user_config.backend is None:
+        questions.append({
+            "id": "backend",
+            "question": "Backend framework for this project?",
+            "type": "choice",
+            "options": [b.value for b in BackendFramework if b != BackendFramework.OTHER],
+            "default": BackendFramework.FASTAPI.value,
+        })
+
+    questions.append({
+        "id": "ai_enabled",
+        "question": "Does this project use AI capabilities internally?",
+        "type": "boolean",
+        "default": True,
+    })
+
+    return questions
+
+
+# ── Private helpers ────────────────────────────────────────────────────────
+
+def _resolve_backend(
+    detection: ProjectDetection, user_config: UserConfig, overrides: dict
+) -> BackendFramework:
+    """Resolve backend framework with priority: override > detected > user default."""
+    if "backend" in overrides:
+        return BackendFramework(overrides["backend"])
+    if "backend" in detection.detected_stack:
+        try:
+            return BackendFramework(detection.detected_stack["backend"])
+        except ValueError:
+            pass
+    if user_config.backend is not None:
+        return user_config.backend
+    # Default fallback
+    return BackendFramework.FASTAPI
+
+
+def _resolve_enum(enum_class, override, detected, default):
+    """Resolve an enum value with priority: override > detected > default."""
+    for val in (override, detected, default):
+        if val is not None:
+            try:
+                return enum_class(val)
+            except (ValueError, KeyError):
+                continue
+    return default
+
+
+def _resolve_regulatory(overrides: dict) -> list[Regulatory]:
+    """Resolve regulatory requirements from overrides."""
+    reg = overrides.get("regulatory", [])
+    if not reg:
+        return []
+    return [Regulatory(r) for r in reg if r != "none"]
+
+
+def _merge_config(model_class, base_config, overrides):
+    """Merge a base config with overrides, returning a new config instance."""
+    if isinstance(base_config, dict):
+        base_data = base_config
+    else:
+        base_data = base_config.model_dump(mode="json")
+    
+    if isinstance(overrides, dict):
+        base_data.update(overrides)
+    
+    return model_class(**base_data)

forge_core/phases/intake.py

@@ -0,0 +1,340 @@
+"""Intake Phase — transforms any requirement into a normalized Forge Brief.
+
+This phase receives whatever the user has:
+- A PRD document
+- A user story or epic
+- A vague conversation or Slack message
+- A feature request
+
+And produces a ForgeBrief — a normalized document that all subsequent
+phases consume.
+
+The key insight: the output isn't just "what features to build" but
+"in what order should an AI coding agent implement them" — types first,
+then infra, then services, then endpoints, then UI.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from forge_core.models import ForgeBrief, RequirementType
+
+
+# ── AI-Optimized Implementation Ordering ───────────────────────────────────
+
+AI_IMPLEMENTATION_PHASES = [
+    {
+        "phase": 1,
+        "name": "types_and_contracts",
+        "title": "Types, Schemas & Contracts",
+        "description": (
+            "Define all TypeScript/Python types, Pydantic models, interfaces, "
+            "and OpenAPI schemas. This gives the AI agent complete context for "
+            "everything that follows — minimizing hallucinations in later phases."
+        ),
+        "examples": [
+            "Pydantic models for all domain entities",
+            "TypeScript interfaces for frontend state",
+            "OpenAPI 3.1 schema definitions",
+            "Database migration schemas",
+            "Event/message schemas for async communication",
+        ],
+    },
+    {
+        "phase": 2,
+        "name": "infrastructure",
+        "title": "Infrastructure & Configuration",
+        "description": (
+            "Set up cloud resources, IaC, environment configs, secrets management. "
+            "Everything the code will depend on at runtime."
+        ),
+        "examples": [
+            "Pulumi/Bicep IaC definitions",
+            "Environment configuration (dev/staging/prod)",
+            "Secrets management setup",
+            "Database provisioning",
+            "Container registry and orchestration",
+        ],
+    },
+    {
+        "phase": 3,
+        "name": "auth_and_security",
+        "title": "Authentication & Security Foundation",
+        "description": (
+            "Implement auth flows, RBAC, security middleware. This must exist "
+            "before any business logic so every endpoint is secure from the start."
+        ),
+        "examples": [
+            "Auth provider integration (Azure AD B2C, Auth0, etc.)",
+            "JWT validation middleware",
+            "RBAC/permission system",
+            "CORS configuration",
+            "Rate limiting setup",
+        ],
+    },
+    {
+        "phase": 4,
+        "name": "data_layer",
+        "title": "Data Layer & Persistence",
+        "description": (
+            "Database models, migrations, repositories, data access patterns. "
+            "The AI agent needs the data layer complete before writing business logic."
+        ),
+        "examples": [
+            "ORM models / database schemas",
+            "Migration scripts",
+            "Repository pattern implementations",
+            "Seed data for development",
+            "Database connection management",
+        ],
+    },
+    {
+        "phase": 5,
+        "name": "core_services",
+        "title": "Core Business Services",
+        "description": (
+            "Business logic services that operate on the data layer. "
+            "Pure logic, no HTTP concerns — these are reusable across "
+            "APIs, workers, and MCP tools."
+        ),
+        "examples": [
+            "Domain service classes",
+            "Business rule validation",
+            "Workflow/state machine implementations",
+            "Integration adapters for external services",
+            "Event handlers",
+        ],
+    },
+    {
+        "phase": 6,
+        "name": "api_layer",
+        "title": "API Endpoints & Controllers",
+        "description": (
+            "REST/GraphQL endpoints that expose core services. "
+            "OpenAPI-documented, versioned, MCP-ready."
+        ),
+        "examples": [
+            "Route definitions with OpenAPI decorators",
+            "Request/response validation",
+            "Error handling middleware",
+            "API versioning",
+            "Health check endpoints",
+        ],
+    },
+    {
+        "phase": 7,
+        "name": "frontend",
+        "title": "Frontend Implementation",
+        "description": (
+            "UI components, pages, state management. Built against "
+            "the typed API contracts from Phase 1."
+        ),
+        "examples": [
+            "Component library / design system",
+            "Page layouts and routing",
+            "State management (React Query, Zustand, etc.)",
+            "Form handling with validation",
+            "Error boundaries and loading states",
+        ],
+    },
+    {
+        "phase": 8,
+        "name": "observability",
+        "title": "Observability & Monitoring",
+        "description": (
+            "Instrument everything — APM, metrics, logs, dashboards, alerts. "
+            "Including AI-specific observability if the project uses AI."
+        ),
+        "examples": [
+            "APM instrumentation (App Insights, etc.)",
+            "Custom metrics (Prometheus)",
+            "Structured logging (Loki)",
+            "Grafana dashboard definitions",
+            "Alert rules and notification channels",
+            "AI cost/safety/session tracking (if applicable)",
+        ],
+    },
+    {
+        "phase": 9,
+        "name": "testing",
+        "title": "Testing & Quality Assurance",
+        "description": (
+            "Unit tests, integration tests, E2E tests. Written after the "
+            "implementation to validate against acceptance criteria."
+        ),
+        "examples": [
+            "Unit tests for services and utilities",
+            "Integration tests for API endpoints",
+            "E2E tests for critical user flows",
+            "Load testing configuration",
+            "Security testing (OWASP baseline)",
+        ],
+    },
+    {
+        "phase": 10,
+        "name": "cicd_and_deploy",
+        "title": "CI/CD & Deployment",
+        "description": (
+            "Pipeline definitions, deployment scripts, smoke tests. "
+            "Everything needed to go from merge to production."
+        ),
+        "examples": [
+            "GitHub Actions / Azure Pipelines definitions",
+            "Docker build and push workflows",
+            "Environment promotion workflows",
+            "Smoke test suites",
+            "Rollback procedures",
+        ],
+    },
+]
+
+
+def classify_requirement(content: str) -> RequirementType:
+    """Classify what type of requirement document this is.
+    
+    Uses simple heuristics — a more sophisticated version would use
+    an LLM, but this gives a reasonable first pass.
+    """
+    content_lower = content.lower()
+
+    # PRD indicators
+    prd_signals = ["product requirements", "prd", "problem statement", "success metrics",
+                   "user personas", "market analysis", "competitive analysis"]
+    if sum(1 for s in prd_signals if s in content_lower) >= 2:
+        return RequirementType.PRD
+
+    # Epic indicators
+    epic_signals = ["epic", "initiative", "objective", "key results", "okr"]
+    if sum(1 for s in epic_signals if s in content_lower) >= 2:
+        return RequirementType.EPIC
+
+    # User story indicators
+    story_signals = ["as a", "i want", "so that", "acceptance criteria",
+                     "given", "when", "then", "story points"]
+    if sum(1 for s in story_signals if s in content_lower) >= 2:
+        return RequirementType.USER_STORY
+
+    # Feature request
+    feature_signals = ["feature", "request", "would be nice", "enhancement"]
+    if sum(1 for s in feature_signals if s in content_lower) >= 2:
+        return RequirementType.FEATURE_REQUEST
+
+    # Bug fix
+    bug_signals = ["bug", "fix", "broken", "error", "crash", "regression"]
+    if sum(1 for s in bug_signals if s in content_lower) >= 2:
+        return RequirementType.BUG_FIX
+
+    return RequirementType.CONVERSATION
+
+
+def build_intake_prompt(content: str, requirement_type: RequirementType) -> str:
+    """Build the prompt for the LLM to analyze the requirement.
+    
+    This prompt is designed to produce a structured ForgeBrief
+    from any kind of requirement input.
+    """
+    return f"""You are Forge, an AI development workflow engine. Analyze the following requirement and produce a structured brief.
+
+## Requirement Type Detected: {requirement_type.value}
+
+## Input Requirement:
+{content}
+
+## Your Task:
+Analyze this requirement and produce a JSON object with exactly this structure:
+
+{{
+  "source_type": "{requirement_type.value}",
+  "completeness_score": <float 0-1, how complete/specific this requirement is>,
+  "objective": "<one paragraph: what this project/feature achieves>",
+  "users": ["<target user persona 1>", "<target user persona 2>"],
+  "features": [
+    {{
+      "name": "<feature name>",
+      "description": "<what it does>",
+      "mvp": <true/false>,
+      "priority": "<high/medium/low>"
+    }}
+  ],
+  "mvp_defined": <true if the input explicitly defines MVP scope, false if you inferred it>,
+  "mvp_features": ["<feature names that are MVP>"],
+  "external_dependencies": ["<external system or service this depends on>"],
+  "integrations": ["<third party integrations needed>"],
+  "regulatory_requirements": ["<hipaa/ferpa/gdpr/soc2/pci-dss/none>"],
+  "gaps": [
+    {{
+      "severity": "<critical/warning/info>",
+      "area": "<what area is missing info>",
+      "description": "<what's missing>",
+      "suggestion": "<what we'd recommend>"
+    }}
+  ],
+  "assumptions": ["<assumptions made to fill non-critical gaps>"],
+  "implementation_order": [
+    {{
+      "phase": <1-10>,
+      "name": "<phase_name>",
+      "title": "<Phase Title>",
+      "tasks": ["<specific task for this project in this phase>"]
+    }}
+  ]
+}}
+
+## Rules:
+1. Be thorough but honest — if information is missing, flag it as a gap
+2. Don't invent features that aren't in the requirement
+3. If MVP scope isn't explicitly defined, make a reasonable suggestion and set mvp_defined to false
+4. The implementation_order MUST follow the AI-optimized sequence:
+   1. types_and_contracts
+   2. infrastructure  
+   3. auth_and_security
+   4. data_layer
+   5. core_services
+   6. api_layer
+   7. frontend
+   8. observability
+   9. testing
+   10. cicd_and_deploy
+5. Only include phases that are relevant to this requirement
+6. Be specific in tasks — "Create User model with email, role, tenant fields" not "Create models"
+
+Respond with ONLY the JSON object. No markdown, no explanation."""
+
+
+def create_empty_brief() -> ForgeBrief:
+    """Create an empty brief for interactive filling."""
+    return ForgeBrief(
+        source_type=RequirementType.CONVERSATION,
+        implementation_order=AI_IMPLEMENTATION_PHASES,
+    )
+
+
+def save_brief(brief: ForgeBrief, project_path: Path) -> Path:
+    """Save a ForgeBrief to the project's .forge/ directory."""
+    forge_dir = project_path / ".forge"
+    forge_dir.mkdir(parents=True, exist_ok=True)
+
+    brief_path = forge_dir / "brief.yaml"
+    with open(brief_path, "w") as f:
+        yaml.dump(brief.model_dump(mode="json"), f, default_flow_style=False, sort_keys=False)
+
+    return brief_path
+
+
+def load_brief(project_path: Path) -> ForgeBrief | None:
+    """Load an existing ForgeBrief from the project."""
+    brief_path = project_path / ".forge" / "brief.yaml"
+    if not brief_path.exists():
+        return None
+    with open(brief_path) as f:
+        data = yaml.safe_load(f) or {}
+    return ForgeBrief(**data)
+
+
+def get_implementation_phases() -> list[dict[str, Any]]:
+    """Return the standard AI implementation phases for reference."""
+    return AI_IMPLEMENTATION_PHASES