spaceforge 0.1.0.dev0__py3-none-any.whl

spaceforge/README.md

@@ -0,0 +1,279 @@
+# Spaceforge Framework
+
+A Python framework for building Spacelift plugins with hook-based functionality.
+
+## Overview
+
+Spaceforge provides a simple, declarative way to create Spacelift plugins by inheriting from the `SpaceforgePlugin` base class and implementing hook methods. The framework automatically handles parameter loading, logging, and YAML generation.
+
+## Architecture
+
+### Core Components
+
+- **SpaceforgePlugin** (`plugin.py`) - Base class with hook methods and utilities
+- **PluginRunner** (`runner.py`) - Executes hook methods, loads parameters from environment
+- **PluginGenerator** (`generator.py`) - Analyzes Python plugins and generates `plugin.yaml`
+- **CLI Interface** (`__main__.py`) - Click-based CLI with `generate` and `runner` subcommands
+- **Pydantic Dataclasses** (`cls.py`) - Type-safe data structures with validation
+
+### Data Validation
+
+The framework uses pydantic dataclasses for all plugin definitions, providing:
+- **Type safety**: All plugin components are strongly typed
+- **Automatic validation**: Data structures are validated during object creation
+- **JSON schema generation**: Plugin manifests include JSON schema for validation
+- **Runtime checks**: For example, Variables must have either `value` or `value_from_parameter`
+
+### Plugin Structure
+
+```python
+from spaceforge import SpaceforgePlugin, Parameter, Variable, Context, Webhook, Policy, MountedFile
+
+class MyPlugin(SpaceforgePlugin):
+    # Plugin metadata
+    __plugin_name__ = "my-plugin"
+    __version__ = "1.0.0"
+    __author__ = "Your Name"
+    
+    # Parameter definitions using pydantic dataclasses
+    __parameters__ = [
+        Parameter(
+            name="api_key",
+            description="API key for authentication",
+            required=True,
+            sensitive=True
+        )
+    ]
+    
+    # Context definitions using pydantic dataclasses
+    __contexts__ = [
+        Context(
+            name="main",
+            description="Main plugin context",
+            env=[
+                Variable(
+                    key="API_KEY",
+                    value_from_parameter="api_key",
+                    sensitive=True
+                )
+            ],
+            hooks={
+                "after_plan": ["echo 'Custom command here'"]
+            },
+            mounted_files=[
+                MountedFile(
+                    path="config.yaml",
+                    content="key: value",
+                    sensitive=False
+                )
+            ]
+        )
+    ]
+    
+    # Webhook definitions using pydantic dataclasses
+    __webhooks__ = [
+        Webhook(
+            name="my_webhook",
+            endpoint="https://example.com/webhook",
+            secrets=[
+                Variable(
+                    key="WEBHOOK_SECRET",
+                    value_from_parameter="api_key"
+                )
+            ]
+        )
+    ]
+    
+    # Policy definitions using pydantic dataclasses  
+    __policies__ = [
+        Policy(
+            name="my_policy",
+            type="notification",
+            body="package spacelift\n# Policy content here",
+            labels={"type": "security"}
+        )
+    ]
+    
+    def after_plan(self):
+        self.logger.info("Running after plan")
+        # Your plugin logic here
+```
+
+## Available Hooks
+
+Override these methods in your plugin:
+
+- `before_init()` - Before Terraform init
+- `after_init()` - After Terraform init
+- `before_plan()` - Before Terraform plan
+- `after_plan()` - After Terraform plan
+- `before_apply()` - Before Terraform apply
+- `after_apply()` - After Terraform apply
+- `before_perform()` - Before the run performs
+- `after_perform()` - After the run performs
+- `before_destroy()` - Before Terraform destroy
+- `after_destroy()` - After Terraform destroy
+- `after_run()` - After the run completes
+
+## Plugin Features
+
+### Logging
+
+Built-in colored logging with run ID and plugin name:
+
+```python
+self.logger.info("Information message")
+self.logger.debug("Debug message")  # Only shown when SPACELIFT_DEBUG=true
+self.logger.warning("Warning message")
+self.logger.error("Error message")
+```
+
+### CLI Execution
+
+Run external commands with logging:
+
+```python
+self.run_cli("terraform", "plan", "-out=tfplan")
+```
+
+### Spacelift API Integration
+
+Query the Spacelift GraphQL API:
+
+```python
+# Requires SPACELIFT_API_TOKEN and SPACELIFT_DOMAIN environment variables
+result = self.query_api("""
+    query {
+        stack(id: "stack-id") {
+            name
+            state
+        }
+    }
+""")
+```
+
+### Plan and State Access
+
+Access Terraform plan and state data:
+
+```python
+plan = self.get_plan_json()  # Returns parsed spacelift.plan.json
+state = self.get_state_before_json()  # Returns parsed spacelift.state.before.json
+```
+
+## Parameter System
+
+Parameters are defined using the `Parameter` pydantic dataclass and automatically loaded from environment variables:
+
+```python
+from spaceforge import Parameter
+
+__parameters__ = [
+    Parameter(
+        name="database_url",
+        description="Database connection URL",
+        required=True,
+        sensitive=True,
+        default="postgresql://localhost:5432/mydb"
+    )
+]
+```
+
+Parameters are interpolated by spacelift at install time, allowing you to reference them in contexts and hooks using `${param.name}` syntax.
+
+## Context System
+
+Contexts define Spacelift environments using the `Context` pydantic dataclass:
+
+```python
+from spaceforge import Context, Variable, MountedFile
+
+__contexts__ = [
+    Context(
+        name="production",
+        description="Production environment",
+        labels={
+            "environment": "production"
+        },
+        env=[
+            Variable(
+                key="DATABASE_URL",
+                value_from_parameter="database_url",
+                sensitive=True
+            )
+        ],
+        hooks={
+            "after_plan": [
+                "echo 'Running production validation'"
+            ]
+        },
+        mounted_files=[
+            MountedFile(
+                path="app.conf",
+                content="production config",
+                sensitive=False
+            )
+        ]
+    )
+]
+```
+
+**Important**: Variables must have either a `value` or `value_from_parameter` field. The framework automatically validates this during plugin generation.
+
+## CLI Usage
+
+### Generate Plugin YAML
+
+```bash
+# Generate from plugin.py (default)
+python -m spaceforge generate
+
+# Generate from specific file
+python -m spaceforge generate my_plugin.py
+
+# Specify output file
+python -m spaceforge generate my_plugin.py -o my_plugin.yaml
+```
+
+### Test Plugin Hooks
+
+```bash
+# Set plugin parameters
+export API_KEY="your-key"
+
+# Run specific hook
+python -m spaceforge runner after_plan
+
+# Run with specific plugin file
+python -m spaceforge runner --plugin-file my_plugin.py before_apply
+```
+
+### Get Help
+
+```bash
+python -m spaceforge --help
+python -m spaceforge generate --help
+python -m spaceforge runner --help
+```
+
+## Generated YAML Structure
+
+The framework automatically generates standard Spacelift plugin YAML:
+
+## Development Tips
+
+1. **Requirements**: If your plugin has dependencies, create a `requirements.txt` file. The generator will automatically add a `before_init` hook to install them.
+
+2. **Testing**: Use the runner command to test individual hooks during development.
+
+3. **Debugging**: Set `SPACELIFT_DEBUG=true` to enable debug logging.
+
+4. **API Access**: Export `SPACELIFT_API_TOKEN` and `SPACELIFT_DOMAIN` to enable Spacelift API queries.
+
+## Error Handling
+
+The framework provides built-in error handling:
+- Failed CLI commands are logged with return codes
+- API errors are logged and returned in the response
+- Missing files and import errors are handled gracefully
+- Hook execution errors are caught and re-raised with context

spaceforge/__init__.py

@@ -0,0 +1,23 @@
+"""
+Spaceforge - Spacelift Plugin Framework
+
+A Python framework for building Spacelift plugins with hook-based functionality.
+"""
+
+from ._version import get_version
+from .cls import Binary, Context, MountedFile, Parameter, Policy, Variable, Webhook
+from .plugin import SpaceforgePlugin
+from .runner import PluginRunner
+
+__version__ = get_version()
+__all__ = [
+    "SpaceforgePlugin",
+    "PluginRunner",
+    "Parameter",
+    "Variable",
+    "Context",
+    "Webhook",
+    "Policy",
+    "MountedFile",
+    "Binary",
+]

spaceforge/__main__.py

@@ -0,0 +1,33 @@
+"""
+Main entry point for spaceforge module.
+"""
+
+import click
+
+from ._version import get_version
+from .generator import generate_command
+from .runner import runner_command
+
+
+@click.group()
+@click.version_option(version=get_version(), prog_name="spaceforge")
+def cli() -> None:
+    """Spaceforge - Spacelift Plugin Framework
+
+    A Python framework for building Spacelift plugins with hook-based functionality.
+    """
+    pass
+
+
+# Add subcommands
+cli.add_command(generate_command)
+cli.add_command(runner_command)
+
+
+def main() -> None:
+    """Main entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

spaceforge/_version.py

@@ -0,0 +1,81 @@
+"""
+Dynamic version detection from git tags.
+"""
+
+import subprocess
+import sys
+from typing import Optional
+
+
+def get_git_version() -> Optional[str]:
+    """
+    Get version from git tags.
+
+    Returns:
+        Version string (without 'v' prefix) or None if not available
+    """
+    try:
+        # Try to get the current tag
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--exact-match"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        tag = result.stdout.strip()
+        # Remove 'v' prefix if present
+        return tag[1:] if tag.startswith("v") else tag
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        # Fall back to describe with commit info
+        try:
+            result = subprocess.run(
+                ["git", "describe", "--tags", "--always"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            tag = result.stdout.strip()
+            # Remove 'v' prefix if present
+            return tag[1:] if tag.startswith("v") else tag
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return None
+
+
+def get_version() -> str:
+    """
+    Get the package version.
+
+    Tries git tags first, then setuptools-scm, falls back to default version.
+
+    Returns:
+        Version string
+    """
+    # Try git version first
+    git_version = get_git_version()
+    if git_version:
+        return git_version
+
+    # Try setuptools-scm generated version file
+    try:
+        from ._version_scm import version  # type: ignore[import-not-found]
+
+        return str(version)
+    except ImportError:
+        pass
+
+    # Try setuptools-scm directly
+    try:
+        from setuptools_scm import (
+            get_version as scm_get_version,  # type: ignore[import-untyped]
+        )
+
+        result = scm_get_version(root="..", relative_to=__file__)
+        return str(result)
+    except ImportError:
+        pass
+    except Exception:
+        # setuptools_scm might fail in various ways, ignore
+        pass
+
+    # Fall back to default version for development
+    return "0.1.0-dev"

spaceforge/cls.py

@@ -0,0 +1,198 @@
+from typing import Dict, List, Literal, Optional
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass as pydantic_dataclass
+
+# For truly optional fields without default: null in schema
+optional_field = Field(default_factory=lambda: None, exclude=True)
+
+BinaryType = Literal[
+    "amd64",
+    "arm64",
+]
+
+
+@pydantic_dataclass
+class Binary:
+    """
+    A class to represent a binary file.
+
+    Attributes:
+        name (str): The name of the binary file.
+        path (str): The path to the binary file.
+        sensitive (bool): Whether the binary file is sensitive.
+    """
+
+    name: str
+    download_urls: Dict[BinaryType, str]
+
+
+@pydantic_dataclass
+class Parameter:
+    """
+    A class to represent a parameter with a name and value.
+
+    Attributes:
+        name (str): The name of the parameter.
+        description (str): A description of the parameter.
+        sensitive (bool): Whether the parameter contains sensitive information.
+        required (bool): Whether the parameter is required.
+        default (Optional[str]): The default value of the parameter, if any. (required if sensitive is False)
+    """
+
+    name: str
+    description: str
+    sensitive: bool = False
+    required: bool = False
+    default: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not self.required and self.default is None:
+            raise ValueError(
+                f"Default value for parameter {self.name} should be set if parameter is optional."
+            )
+
+
+@pydantic_dataclass
+class Variable:
+    """
+    A class to represent an environment variable.
+
+    Attributes:
+        key (str): The key of the environment variable.
+        value (Optional[str]): The value of the environment variable, if set.
+        value_from_parameter (Optional[str]): The name of the plugin variable to use as the value.
+        sensitive (bool): Whether the environment variable is sensitive.
+    """
+
+    key: str
+    value: Optional[str] = optional_field
+    value_from_parameter: Optional[str] = optional_field
+    sensitive: bool = False
+
+    def __post_init__(self) -> None:
+        if self.value is None and self.value_from_parameter is None:
+            raise ValueError(
+                "Either value or value_from_parameter must be set for EnvVariable."
+            )
+
+
+@pydantic_dataclass
+class MountedFile:
+    """
+    A class to represent a mounted file.
+
+    Attributes:
+        path (str): The path of the mounted file.
+        content (str): The content of the mounted file.
+        sensitive (bool): Whether the content of the file is sensitive.
+    """
+
+    path: str
+    content: str
+    sensitive: bool = False
+
+
+HookType = Literal[
+    "before_init",
+    "after_init",
+    "before_plan",
+    "after_plan",
+    "before_apply",
+    "after_apply",
+    "before_perform",
+    "after_perform",
+    "before_destroy",
+    "after_destroy",
+    "after_run",
+]
+
+
+@pydantic_dataclass
+class Context:
+    """
+    A class to represent a context for a plugin.
+
+    Attributes:
+        name_prefix (str): The name of the context, will be appended with a unique ID.
+        description (str): A description of the context.
+        labels (dict): Labels associated with the context.
+        env (list): List of variables associated with the context.
+        hooks (dict): Hooks associated with the context.
+    """
+
+    name_prefix: str
+    description: str
+    env: Optional[List[Variable]] = optional_field
+    mounted_files: Optional[List[MountedFile]] = optional_field
+    hooks: Optional[Dict[HookType, List[str]]] = optional_field
+    labels: Optional[Dict[str, str]] = optional_field
+
+
+@pydantic_dataclass
+class Webhook:
+    """
+    A class to represent a webhook configuration.
+
+    Attributes:
+        name_prefix (str): The name of the webhook, will be appended with a unique ID.
+        endpoint (str): The URL endpoint for the webhook.
+        labels (Optional[dict]): Labels associated with the webhook.
+        secrets (Optional[list[Variable]]): List of secrets associated with the webhook.
+    """
+
+    name_prefix: str
+    endpoint: str
+    labels: Optional[Dict[str, str]] = optional_field
+    secrets: Optional[List[Variable]] = optional_field
+
+
+@pydantic_dataclass
+class Policy:
+    """
+    A class to represent a policy configuration.
+
+    Attributes:
+        name_prefix (str): The name of the policy, will be appended with a unique ID.
+        type (str): The type of the policy (e.g., "terraform", "kubernetes").
+        body (str): The body of the policy, typically a configuration or script.
+        labels (Optional[dict[str, str]]): Labels associated with the policy.
+    """
+
+    name_prefix: str
+    type: str
+    body: str
+    labels: Optional[Dict[str, str]] = optional_field
+
+
+@pydantic_dataclass
+class PluginManifest:
+    """
+    A class to represent the manifest of a Spacelift plugin.
+
+    Attributes:
+        name_prefix (str): The name of the plugin, will be appended with a unique ID.
+        description (str): A description of the plugin.
+        author (str): The author of the plugin.
+        parameters (list[Parameter]): List of parameters for the plugin.
+        contexts (list[Context]): List of contexts for the plugin.
+        webhooks (list[Webhook]): List of webhooks for the plugin.
+        policies (list[Policy]): List of policies for the plugin.
+    """
+
+    name_prefix: str
+    version: str
+    description: str
+    author: str
+    parameters: Optional[List[Parameter]] = optional_field
+    contexts: Optional[List[Context]] = optional_field
+    webhooks: Optional[List[Webhook]] = optional_field
+    policies: Optional[List[Policy]] = optional_field
+
+
+if __name__ == "__main__":
+    import json
+
+    from pydantic import TypeAdapter
+
+    print(json.dumps(TypeAdapter(PluginManifest).json_schema(), indent=2))

spaceforge/cls_test.py

@@ -0,0 +1,17 @@
+import pytest
+
+from spaceforge import Parameter, Variable
+
+
+def test_ensure_optional_parameters_require_default_values() -> None:
+    with pytest.raises(ValueError):
+        Parameter(
+            name="optional_default",
+            description="default value",
+            required=False,
+        )
+
+
+def test_ensure_variables_have_either_value_or_value_from_parameter() -> None:
+    with pytest.raises(ValueError):
+        Variable(key="test_var", sensitive=False)