prvng_kcl/generator/declaration.k

"""
Workspace Declaration Schema

Defines the structure of a provisioning workspace declaration.
A declaration is a complete specification of infrastructure requirements,
including detected technologies, taskservs, and deployment configuration.

This enables:
- Declarative IaC (infrastructure-as-code)
- Incremental updates (merge with existing declarations)
- Version tracking
- Reproducible deployments
"""

import regex

# ============================================================================
# Metadata and Versioning
# ============================================================================

schema Metadata:
    """
    Workspace metadata: identification, versioning, authorship
    """
    name: str
    version: str              # Semantic versioning (e.g., "1.0.0")
    description?: str
    author?: str
    created_at?: str          # ISO 8601 timestamp
    updated_at?: str          # ISO 8601 timestamp

    check:
        len(name) > 0, "Name required"
        len(name) <= 128, "Name too long (max 128 chars)"
        # Simple semver pattern: MAJOR.MINOR.PATCH
        regex.match(version, r"^\d+\.\d+\.\d+$"), \
            "Version must be semantic (e.g., 1.0.0)"


# ============================================================================
# Technology Detection and Requirements
# ============================================================================

schema TechnologyDetection:
    """
    Detected technology in the project (e.g., Node.js, PostgreSQL)
    """
    name: str                 # e.g., "nodejs", "postgres"
    version?: str             # Detected or specified version
    confidence: float         # 0.0-1.0 confidence score
    detected_from?: [str]     # Files/patterns that led to detection

    check:
        confidence >= 0.0 and confidence <= 1.0, \
            "Confidence must be between 0 and 1"


schema TaskservRequirement:
    """
    Infrastructure taskserv requirement (e.g., redis, postgres-backup)
    """
    name: str                 # Taskserv name (e.g., "redis", "postgres")
    version?: str             # Min or exact version
    profile: "default" | "minimal" | "HA" = "default"
    required: bool = False    # true = must install, false = optional
    confidence: float = 1.0   # How confident in this requirement
    reason?: str              # Why this taskserv is needed

    check:
        len(name) > 0, "Taskserv name required"
        confidence >= 0.0 and confidence <= 1.0, \
            "Confidence must be between 0 and 1"


# ============================================================================
# Deployment Configuration
# ============================================================================

schema ServerConfig:
    """
    Server definition for deployment
    """
    name: str
    provider: str             # e.g., "upcloud", "aws", "local"
    flavor?: str              # Machine type/size
    region?: str
    taskservs: [str] = []     # Taskservs to install on this server

    check:
        len(name) > 0, "Server name required"


schema DeploymentConfig:
    """
    Deployment mode and infrastructure layout
    """
    mode: "solo" | "multiuser" | "cicd" | "enterprise" = "multiuser"
    servers: [ServerConfig] = []
    ha_enabled: bool = False

    check:
        mode == "solo" or len(servers) > 0, \
            "Servers required for non-solo deployments"


# ============================================================================
# Main Declaration
# ============================================================================

schema WorkspaceDeclaration:
    """
    Complete workspace declaration.

    A declaration specifies all infrastructure requirements for a project:
    - Metadata (name, version, author)
    - Detected technologies (Node.js, PostgreSQL, etc.)
    - Required taskservs (what to install)
    - Deployment config (where/how to deploy)
    - Custom configuration (user-specific settings)

    Example:
        declaration = WorkspaceDeclaration {
            metadata: {
                name: "my-api"
                version: "1.0.0"
                author: "user@example.com"
            }

            detections: [
                TechnologyDetection {
                    name: "nodejs"
                    version: "20.0.0"
                    confidence: 0.95
                }
            ]

            requirements: [
                TaskservRequirement {
                    name: "postgres"
                    version: "16.0"
                    required: True
                    reason: "Database detected in code"
                }
                TaskservRequirement {
                    name: "redis"
                    profile: "default"
                    required: False
                    confidence: 0.85
                    reason: "Node.js APIs benefit from caching"
                }
            ]

            deployment: {
                mode: "multiuser"
                servers: [
                    ServerConfig {
                        name: "app-db"
                        provider: "upcloud"
                        flavor: "2xCPU-4GB"
                        taskservs: ["postgres"]
                    }
                    ServerConfig {
                        name: "app-server"
                        provider: "upcloud"
                        flavor: "2xCPU-4GB"
                        taskservs: ["nodejs", "redis"]
                    }
                ]
            }
        }
    """

    # Identification
    metadata: Metadata

    # Auto-detected technologies
    detections: [TechnologyDetection] = []

    # Infrastructure requirements (from detection + inference)
    requirements: [TaskservRequirement] = []

    # Deployment configuration
    deployment: DeploymentConfig = {
        mode: "multiuser"
    }

    # User customizations (preserved during updates)
    custom_config?: {str: str}

    check:
        # At least one requirement if detections exist
        len(detections) == 0 or len(requirements) > 0, \
            "Detections found but no requirements specified"


# ============================================================================
# Changelog Entry (for tracking updates)
# ============================================================================

schema ChangelogEntry:
    """
    Single changelog entry for versioning
    """
    version: str
    timestamp: str            # ISO 8601
    author?: str
    changes: [str] = []
    breaking_changes?: [str]


schema Changelog:
    """
    Workspace changelog for tracking all versions
    """
    entries: [ChangelogEntry] = []


# ============================================================================
# Complete Workspace with History
# ============================================================================

schema Workspace:
    """
    Complete workspace including current declaration + history
    """
    declaration: WorkspaceDeclaration
    changelog: Changelog = { entries: [] }

    check:
        len(declaration.metadata.name) > 0, "Workspace name required"