prvng_kcl/gitea.k

"""
Gitea Integration Configuration Schemas

This module defines schemas for Gitea service configuration, including:
- Local and remote Gitea deployment options
- Repository management
- Workspace integration
- Extension publishing
- Locking mechanism

Version: 1.0.0
KCL Version: 0.11.3+
"""

schema GiteaConfig:
    """
    Main Gitea service configuration

    Supports both local (self-hosted) and remote Gitea instances.
    Local mode can deploy via Docker or binary.

    Examples:
        # Local Docker deployment
        GiteaConfig {
            mode = "local"
            local = LocalGitea {
                enabled = True
                deployment = "docker"
                port = 3000
                auto_start = True
            }
        }

        # Remote Gitea instance
        GiteaConfig {
            mode = "remote"
            remote = RemoteGitea {
                enabled = True
                url = "https://gitea.example.com"
                api_url = "https://gitea.example.com/api/v1"
            }
        }
    """
    mode: "local" | "remote"

    local?: LocalGitea
    remote?: RemoteGitea

    auth: GiteaAuth

    repositories: GiteaRepositories = GiteaRepositories {}

    workspace_features: WorkspaceFeatures = WorkspaceFeatures {}

    check:
        mode == "local" and local != None or mode == "remote" and remote != None, \
            "Must configure local or remote based on mode"

        mode == "local" and local.enabled or mode == "remote" and remote.enabled, \
            "Selected Gitea mode must be enabled"

schema LocalGitea:
    """
    Local Gitea deployment configuration

    Supports Docker container or binary deployment.
    """
    enabled: bool = False
    deployment: "docker" | "binary"
    port: int = 3000
    data_dir: str = "~/.provisioning/gitea"
    auto_start: bool = False

    docker?: DockerGitea
    binary?: BinaryGitea

    check:
        enabled, "Local Gitea must be enabled if configured"

        port > 0 and port < 65536, \
            "Port must be between 1 and 65535"

        len(data_dir) > 0, "Data directory required"

        deployment == "docker" and docker != None or \
        deployment == "binary" and binary != None, \
            "Must configure docker or binary based on deployment type"

schema DockerGitea:
    """Docker-based Gitea deployment"""
    image: str = "gitea/gitea:1.21"
    container_name: str = "provisioning-gitea"
    ssh_port: int = 222
    environment: {str: str} = {
        "USER_UID" = "1000"
        "USER_GID" = "1000"
        "GITEA__database__DB_TYPE" = "sqlite3"
    }
    volumes: [str] = [
        "gitea-data:/data"
        "/etc/timezone:/etc/timezone:ro"
        "/etc/localtime:/etc/localtime:ro"
    ]
    restart_policy: str = "unless-stopped"

    check:
        len(image) > 0, "Docker image required"
        len(container_name) > 0, "Container name required"
        ssh_port > 0 and ssh_port < 65536, "SSH port must be 1-65535"

schema BinaryGitea:
    """Binary-based Gitea deployment"""
    binary_path: str
    config_path: str
    version: str = "1.21.0"
    user: str = "git"
    group: str = "git"

    check:
        len(binary_path) > 0, "Binary path required"
        len(config_path) > 0, "Config path required"

schema RemoteGitea:
    """
    Remote Gitea instance configuration

    Points to existing Gitea server.
    """
    enabled: bool = False
    url: str
    api_url: str

    check:
        enabled, "Remote Gitea must be enabled if configured"

        len(url) > 0 and url.startswith("http"), \
            "URL must start with http:// or https://"

        len(api_url) > 0 and api_url.startswith("http"), \
            "API URL must start with http:// or https://"

schema GiteaAuth:
    """
    Gitea authentication configuration

    Token-based authentication for API access.
    Token should be stored in encrypted file (SOPS).
    """
    token_path: str
    username?: str

    check:
        len(token_path) > 0, "Token path required"

schema GiteaRepositories:
    """
    Repository organization and naming configuration

    Defines organization structure and repository names.
    """
    organization: str = "provisioning"
    core_repo: str = "provisioning-core"
    extensions_repo: str = "provisioning-extensions"
    platform_repo: str = "provisioning-platform"
    workspaces_org: str = "workspaces"

    check:
        len(organization) > 0, "Organization name required"
        len(core_repo) > 0, "Core repo name required"
        len(extensions_repo) > 0, "Extensions repo name required"
        len(platform_repo) > 0, "Platform repo name required"
        len(workspaces_org) > 0, "Workspaces org name required"

schema WorkspaceFeatures:
    """
    Workspace integration feature flags

    Controls which Gitea features are enabled for workspaces.
    """
    git_integration: bool = True
    locking_enabled: bool = True
    webhooks_enabled: bool = False
    auto_sync: bool = False
    branch_protection: bool = False

    check:
        git_integration or not locking_enabled, \
            "Locking requires git integration"

schema GiteaRepository:
    """
    Gitea repository metadata

    Used for creating and managing repositories.
    """
    name: str
    owner: str
    description?: str
    private: bool = False
    auto_init: bool = True
    default_branch: str = "main"
    gitignore?: str
    license?: str
    readme?: str

    check:
        len(name) > 0, "Repository name required"
        len(owner) > 0, "Repository owner required"

schema GiteaRelease:
    """
    Gitea release configuration

    Used for publishing extensions and versioned artifacts.
    """
    tag_name: str
    release_name: str
    body?: str
    draft: bool = False
    prerelease: bool = False
    target_commitish: str = "main"

    check:
        len(tag_name) > 0, "Tag name required"
        len(release_name) > 0, "Release name required"

schema GiteaIssue:
    """
    Gitea issue configuration

    Used for workspace locking mechanism.
    """
    title: str
    body: str
    labels: [str] = []
    assignee?: str
    milestone?: int

    check:
        len(title) > 0, "Issue title required"

schema WorkspaceLock:
    """
    Workspace lock metadata

    Stored as Gitea issue for distributed locking.
    """
    workspace_name: str
    lock_type: "read" | "write" | "deploy"
    user: str
    timestamp: str
    operation?: str
    expiry?: str
    force_unlock: bool = False

    check:
        len(workspace_name) > 0, "Workspace name required"
        len(user) > 0, "User required"
        len(timestamp) > 0, "Timestamp required"

schema ExtensionPublishConfig:
    """
    Extension publishing configuration

    Defines how extensions are packaged and published to Gitea.
    """
    extension_path: str
    version: str
    release_notes?: str
    include_patterns: [str] = ["*.nu", "*.k", "*.toml", "*.md"]
    exclude_patterns: [str] = ["*.tmp", "*.log", ".git/*"]
    compression: "tar.gz" | "zip" = "tar.gz"

    check:
        len(extension_path) > 0, "Extension path required"
        len(version) > 0, "Version required"

schema GiteaWebhook:
    """
    Gitea webhook configuration

    For future integration with automated workflows.
    """
    url: str
    content_type: "json" | "form" = "json"
    secret?: str
    events: [str] = ["push", "pull_request", "release"]
    active: bool = True

    check:
        len(url) > 0 and url.startswith("http"), \
            "Webhook URL must start with http:// or https://"

# Example configurations
_local_docker_gitea = GiteaConfig {
    mode = "local"
    local = LocalGitea {
        enabled = True
        deployment = "docker"
        port = 3000
        data_dir = "~/.provisioning/gitea"
        auto_start = True
        docker = DockerGitea {
            image = "gitea/gitea:1.21"
            container_name = "provisioning-gitea"
        }
    }
    auth = GiteaAuth {
        token_path = "~/.provisioning/secrets/gitea-token.enc"
        username = "provisioning"
    }
}

_remote_gitea = GiteaConfig {
    mode = "remote"
    remote = RemoteGitea {
        enabled = True
        url = "https://gitea.example.com"
        api_url = "https://gitea.example.com/api/v1"
    }
    auth = GiteaAuth {
        token_path = "~/.provisioning/secrets/gitea-token.enc"
        username = "provisioning"
    }
}