spaceforge 1.1.5__tar.gz → 1.1.6__tar.gz

{spaceforge-1.1.5 → spaceforge-1.1.6}/.github/workflows/ci.yml

@@ -39,28 +39,60 @@ jobs:
       run: |
         ./test.sh
 
+  check-plugin-yaml:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+
+    - name: Regenerate plugin YAML files
+      run: ./regenerate_plugins.sh
+
+    - name: Check for uncommitted changes
+      run: |
+        if ! git diff --exit-code; then
+          echo "❌ Plugin YAML files are out of date!"
+          echo ""
+          echo "Please run './regenerate_plugins.sh' and commit the changes."
+          echo ""
+          echo "Files that need to be updated:"
+          git diff --name-only
+          exit 1
+        fi
+        echo "✅ All plugin YAML files are up to date"
+
   build:
     needs: test
     runs-on: ubuntu-latest
-    
+
     steps:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0  # Fetch full history for setuptools-scm
-    
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
         python-version: '3.11'
-    
+
     - name: Install build dependencies
       run: |
         python -m pip install --upgrade pip
         pip install build setuptools-scm[toml]
-    
+
     - name: Build package
       run: python -m build
-    
+
     - name: Check distribution
       run: |
         pip install twine

spaceforge-1.1.5/README.md → spaceforge-1.1.6/CONTRIBUTING.md

@@ -1,18 +1,30 @@
-# Spaceforge - Build Spacelift Plugins in Python
+# Spaceforge Contributing Guide
 
-Spaceforge is a Python framework that makes it easy to build powerful Spacelift plugins using a declarative, hook-based approach. Define your plugin logic in Python, and spaceforge automatically generates the plugin manifest for Spacelift.
+## Reporting an Issue
 
-## Installation
+If you spot a problem with Spaceforge, [search if an issue already exists](https://github.com/spacelift-io/plugins/issues). If not, please [open a new issue](https://github.com/spacelift-io/plugins/issues/new).
 
-Install spaceforge from PyPI:
+## Creating a Plugin
+
+Creating a plugin involves five steps:
+
+1. **Install spaceforge:** `pip install spaceforge`
+2. **Create your plugin:** Start with the quick start example.
+3. **Test locally:** Use the `run` command to test your hooks.
+4. **Generate manifest:** Use the `generate` command to create plugin.yaml.
+5. **Upload to Spacelift:** Add your plugin manifest to your Spacelift account.
+
+Detailed instructions for each step are below.
+
+### Quick Start
+
+#### 1. Install spaceforge
 
 ```bash
 pip install spaceforge
 ```
 
-## Quick Start
-
-### 1. Create Your Plugin
+#### 2. Create Your Plugin
 
 Create a Python file (e.g., `plugin.py`) and inherit from `SpaceforgePlugin`:
 
@@ -76,17 +88,7 @@ class MyPlugin(SpaceforgePlugin):
         self.logger.info("Security scan passed!")
 ```
 
-### 2. Generate Plugin Manifest
-
-Generate the Spacelift plugin YAML manifest:
-
-```bash
-spaceforge generate plugin.py
-```
-
-This creates `plugin.yaml` that you can upload to Spacelift.
-
-### 3. Test Your Plugin
+#### 3. Test Your Plugin
 
 Test individual hooks locally:
 
@@ -99,21 +101,30 @@ export ENVIRONMENT="staging"
 spaceforge run after_plan
 ```
 
-## Available Hooks
+#### 4. Generate Plugin Manifest
 
-Override these methods in your plugin to add custom logic:
+Generate the Spacelift plugin `plugin.yaml` manifest that you can upload to Spacelift.
+
+```bash
+spaceforge generate plugin.py
+```
 
-- `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
+#### 5. Upload your Plugin to Spacelift
+
+For more advanced examples, see the [plugins](plugins/) directory in this repository.
+
+### Available Hooks
+
+Implement these methods in your plugin to add custom logic before and after specific run phases:
+
+- **Initialization** (`before_init()` and `after_init()`)
+- **Planning** (`before_plan()` and `after_plan()`)
+- **Applying** (`before_apply()` and `after_apply()`)
+- **Destroying** (`before_destroy()` and `after_destroy()`)
+    - Used during module test cases.
+    - Used by stacks during destruction with corresponding `stack_destructor_resource`.
+- **Performing** (`before_perform()` and `after_perform()`): Used during stack tasks execution.
+- **Finally** (`after_run()`): Executed after each actively processed run, regardless of its outcome. These hooks have access to an environment variable called `TF_VAR_spacelift_final_run_state`, which indicates the final state of the run.
 
 ## Plugin Components
 
@@ -126,6 +137,27 @@ class MyPlugin(SpaceforgePlugin):
     __labels__ = ["security", "monitoring", "compliance"]
 ```
 
+### Binaries
+
+Automatically download and install external tools:
+
+```python
+__binaries__ = [
+    Binary(
+        name="kubectl",
+        download_urls={
+            "amd64": "https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl",
+            "arm64": "https://dl.k8s.io/release/v1.28.0/bin/linux/arm64/kubectl"
+        }
+    )
+]
+```
+
+**Notes**:
+- Only open-source-licensed binaries can be used in plugins unless Spacelift has authorized them.
+- `.tar.bz2`, `.tar.gz`, and `.zip` archives are extracted automatically.
+- Archives must contain a file matching the binary name. All other files are ignored.
+
 ### Parameters
 
 Define user-configurable parameters:
@@ -149,13 +181,13 @@ __parameters__ = [
 ]
 ```
 
-**Parameter Notes:**
-- Parameter `name` is displayed in the Spacelift UI
-- Parameter `id` (optional) is used for programmatic reference
-- `value_from_parameter` can reference either the `id` (if present) or the `name`
-- Parameters are made available as environment variables through Variable definitions
-- Default values must be strings
-- Required parameters cannot have default values
+**Notes:**
+- Parameter `name` is displayed in the Spacelift UI.
+- Parameter `id` (optional) is used for programmatic reference.
+- `value_from_parameter` can reference either the `id` (if present) or the `name`.
+- Parameters are made available as environment variables through Variable definitions.
+- Default values must be strings.
+- Required parameters cannot have default values.
 
 ### Contexts
 
@@ -188,22 +220,6 @@ __contexts__ = [
 ]
 ```
 
-### Binaries
-
-Automatically download and install external tools:
-
-```python
-__binaries__ = [
-    Binary(
-        name="kubectl",
-        download_urls={
-            "amd64": "https://dl.k8s.io/release/v1.28.0/bin/linux/amd64/kubectl",
-            "arm64": "https://dl.k8s.io/release/v1.28.0/bin/linux/arm64/kubectl"
-        }
-    )
-]
-```
-
 **Context Priority System:**
 
 Control the execution order of contexts using the `priority` field:
@@ -229,13 +245,13 @@ __contexts__ = [
 ]
 ```
 
-**Priority Notes:**
-- Default priority is `0`
-- Lower numbers execute first (0, then 1, then 2, etc.)
-- Useful for ensuring setup contexts run before main execution contexts
+**Notes:**
+- Default priority is `0`.
+- Lower numbers execute first (0, then 1, then 2, etc.).
+- Useful for ensuring setup contexts run before main execution contexts.
 
 **Binary PATH Management:**
-- When using Python hook methods (e.g., `def before_apply()`), binaries are automatically available in PATH
+- When using Python hook methods (e.g., `def before_apply()`), binaries are automatically available in `$PATH`.
 - When using raw context hooks, you must manually export the PATH:
 
 ```python
@@ -280,11 +296,11 @@ __contexts__ = [
 ]
 ```
 
-**MountedFile Notes:**
-- Files are created at the specified path when the context is applied
-- Content is written exactly as provided
-- Use `sensitive=True` for files containing secrets or sensitive data
-- path is from `/mnt/workspace/`. An example would be `tmp/config.json` which would be mounted at `/mnt/workspace/tmp/config.json`
+**Notes:**
+- Files are created at the specified path when the context is applied.
+- Content is written exactly as provided.
+- Use `sensitive=True` for files containing secrets or sensitive data.
+- path is from `/mnt/workspace/`. An example would be `tmp/config.json` which would be mounted at `/mnt/workspace/tmp/config.json`.
 
 ### Policies
 
@@ -398,11 +414,11 @@ def before_plan(self):
         self.logger.info(f"Authenticated as: {result['viewer']['login']}")
 ```
 
-**User Token Notes:**
-- Allows plugins to act on behalf of a specific user
-- Useful for operations requiring user-specific permissions
-- User tokens may have different access levels than service tokens
-- Call `use_user_token()` before making API requests
+**Notes:**
+- Allows plugins to act on behalf of a specific user.
+- Useful for operations requiring user-specific permissions.
+- User tokens may have different access levels than service tokens.
+- Call `use_user_token()` before making API requests.
 
 ### Access Plan and State
 
@@ -423,7 +439,7 @@ def after_plan(self):
 
 ### Send Rich Output
 
-Send formatted markdown to the Spacelift UI:
+Send formatted Markdown to the Spacelift UI:
 
 ```python
 def after_plan(self):
@@ -442,8 +458,6 @@ def after_plan(self):
 
 ### Add to Policy Input
 
-Add custom data to the OPA policy input:
-
 The following example will create input available via `input.third_party_metadata.custom.my_custom_data` in your OPA policies:
 ```python
 def after_plan(self):
@@ -455,44 +469,9 @@ def after_plan(self):
     })
 ```
 
-## CLI Commands
-
-### Generate Plugin Manifest
-
-```bash
-# Generate from plugin.py (default filename)
-spaceforge generate
-
-# Generate from specific file  
-spaceforge generate my_plugin.py
-
-# Specify output file
-spaceforge generate my_plugin.py -o custom-output.yaml
-
-# Get help
-spaceforge generate --help
-```
-
-### Test Plugin Hooks
-
-```bash
-# Set parameters for local testing (parameters are normally provided by Spacelift)
-export API_KEY="test-key" 
-export TIMEOUT="60"
-
-# Test specific hook
-spaceforge run after_plan
-
-# Test with specific plugin file
-spaceforge run --plugin-file my_plugin.py before_apply
-
-# Get help
-spaceforge run --help
-```
-
 ## Plugin Development Tips
 
-### 1. Handle Dependencies
+### Handle Dependencies
 
 If your plugin needs Python packages, create a `requirements.txt` file. Spaceforge automatically adds a `before_init` hook to install them:
 
@@ -512,7 +491,7 @@ def after_plan(self):
     self.logger.info(f"Processing run {run_id} for stack {stack_id}")
 ```
 
-### 3. Error Handling
+### Error Handling
 
 Always handle errors gracefully:
 
@@ -528,168 +507,22 @@ def after_plan(self):
         exit(1)
 ```
 
-### 4. Testing and Debugging
+### Testing and Debugging
 
-- Set `SPACELIFT_DEBUG=true` to enable debug logging
-- Use the `run` command to test hooks during development
-- Test with different parameter combinations
-- Validate your generated YAML before uploading to Spacelift
+- Set `SPACELIFT_DEBUG=true` to enable debug logging.
+- Use the `run` command to test hooks during development.
+- Test with different parameter combinations.
+- Validate your generated YAML before uploading to Spacelift.
 
-## Example: Security Scanning Plugin
+### Speeding Up Plugin Execution
 
-Here's a complete example of a security scanning plugin:
+There are a few things you can do to speed up plugin execution:
 
-```python
-import os
-import json
-from spaceforge import SpaceforgePlugin, Parameter, Variable, Context, Binary, Policy, MountedFile
+- Ensure your runner has `spaceforge` preinstalled. This will avoid the overhead of installing it during the run. (15-30 seconds)
+- If you use binaries, we will only install the binary if its not found. You can gain a few seconds by ensuring its already on the runner.
+- If your plugin has a lot of dependencies, consider using a prebuilt runner image with your plugin and its dependencies installed. This avoids the overhead of installing them during each run.
+- Ensure your runner has enough core resources (CPU, memory) to handle the plugin execution efficiently. If your plugin is resource-intensive, consider using a more powerful runner.
 
-class SecurityScannerPlugin(SpaceforgePlugin):
-    __plugin_name__ = "security-scanner"
-    __version__ = "1.0.0"
-    __author__ = "Security Team"
-    
-    __binaries__ = [
-        Binary(
-            name="security-cli",
-            download_urls={
-                "amd64": "https://releases.example.com/security-cli-linux-amd64",
-                "arm64": "https://releases.example.com/security-cli-linux-arm64"
-            }
-        )
-    ]
-    
-    __parameters__ = [
-        Parameter(
-            name="API Token",
-            id="api_token",
-            description="Security service API token",
-            required=True,
-            sensitive=True
-        ),
-        Parameter(
-            name="Severity Threshold", 
-            id="severity_threshold",
-            description="Minimum severity level to report",
-            required=False,
-            default="medium"
-        )
-    ]
-    
-    __contexts__ = [
-        Context(
-            name_prefix="security-scanner",
-            description="Security scanning context",
-            env=[
-                Variable(
-                    key="SECURITY_API_TOKEN",
-                    value_from_parameter="api_token",
-                    sensitive=True
-                ),
-                Variable(
-                    key="SEVERITY_THRESHOLD",
-                    value_from_parameter="severity_threshold"
-                )
-            ]
-        )
-    ]
-    
-    def after_plan(self):
-        """Run security scan after Terraform plan"""
-        self.logger.info("Starting security scan of Terraform plan")
-        
-        # Authenticate with security service
-        return_code, stdout, stderr = self.run_cli(
-            "security-cli", "auth", 
-            "--token", os.environ["SECURITY_API_TOKEN"]
-        )
-        
-        if return_code != 0:
-            self.logger.error("Failed to authenticate with security service")
-            exit(1)
-        
-        # Scan the Terraform plan
-        return_code, stdout, stderr = self.run_cli(
-            "security-cli", "scan", "terraform", 
-            "--plan-file", "spacelift.plan.json",
-            "--format", "json",
-            "--severity", os.environ.get("SEVERITY_THRESHOLD", "medium"),
-            print_output=False
-        )
-        
-        if return_code != 0:
-            self.logger.error("Security scan failed")
-            for line in stderr:
-                self.logger.error(line)
-            exit(1)
-        
-        # Parse scan results
-        try:
-            results = json.loads('\n'.join(stdout))
-            
-            # Generate markdown report
-            markdown = self._generate_report(results)
-            self.send_markdown(markdown)
-            
-            # Fail run if critical issues found
-            if results.get('critical_count', 0) > 0:
-                self.logger.error(f"Found {results['critical_count']} critical security issues")
-                exit(1)
-                
-            self.logger.info("Security scan completed successfully")
-            
-        except json.JSONDecodeError:
-            self.logger.error("Failed to parse scan results")
-            exit(1)
-    
-    def _generate_report(self, results):
-        """Generate markdown report from scan results"""
-        report = "# Security Scan Results\n\n"
-        
-        if results.get('total_issues', 0) == 0:
-            report += "✅ **No security issues found!**\n"
-        else:
-            report += f"Found {results['total_issues']} security issues:\n\n"
-            
-            for severity in ['critical', 'high', 'medium', 'low']:
-                count = results.get(f'{severity}_count', 0)
-                if count > 0:
-                    emoji = {'critical': '🔴', 'high': '🟠', 'medium': '🟡', 'low': '🟢'}[severity]
-                    report += f"- {emoji} **{severity.upper()}:** {count}\n"
-        
-        if results.get('report_url'):
-            report += f"\n[View detailed report]({results['report_url']})\n"
-            
-        return report
-```
-
-Generate and test this plugin:
+## Working on Spaceforge
 
-```bash
-# Generate the manifest
-spaceforge generate security_scanner.py
-
-# Test locally
-export API_TOKEN="your-token"
-export SEVERITY_THRESHOLD="high"
-spaceforge run after_plan
-```
-
-## Speeding up plugin execution
-
-There are a few things you can do to speed up plugin execution.
-
-1. Ensure your runner has `spaceforge` preinstalled. This will avoid the overhead of installing it during the run. (15-30 seconds)
-2. If youre using binaries, we will only install the binary if its not found. You can gain a few seconds by ensuring its already on the runner.
-3. If your plugin has a lot of dependencies, consider using a prebuilt runner image with your plugin and its dependencies installed. This avoids the overhead of installing them during each run.
-4. Ensure your runner has enough core resources (CPU, memory) to handle the plugin execution efficiently. If your plugin is resource-intensive, consider using a more powerful runner.
-
-## Next Steps
-
-1. **Install spaceforge:** `pip install spaceforge`
-2. **Create your plugin:** Start with the quick start example
-3. **Test locally:** Use the `run` command to test your hooks
-4. **Generate manifest:** Use the `generate` command to create plugin.yaml
-5. **Upload to Spacelift:** Add your plugin manifest to your Spacelift account
-
-For more advanced examples, see the [plugins](plugins/) directory in this repository.
+See the [README file](./spaceforge/README.md) in the `spaceforge` folder.

{spaceforge-1.1.5 → spaceforge-1.1.6}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Spacelift
+Copyright (c) 2025 Spacelift
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

spaceforge-1.1.6/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: spaceforge
+Version: 1.1.6
+Summary: A Python framework for building Spacelift plugins
+Author-email: Spacelift <support@spacelift.io>
+Maintainer-email: Spacelift <support@spacelift.io>
+License: MIT
+Project-URL: Homepage, https://github.com/spacelift-io/plugins
+Project-URL: Documentation, https://github.com/spacelift-io/plugins#readme
+Project-URL: Repository, https://github.com/spacelift-io/plugins
+Project-URL: Bug Reports, https://github.com/spacelift-io/plugins/issues
+Keywords: spacelift,plugin,framework,infrastructure,devops,spaceforge
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: Jinja2>=3.1.0
+Requires-Dist: mergedeep>=1.3.4
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: setuptools-scm[toml]>=6.2; extra == "dev"
+Requires-Dist: autoflake; extra == "dev"
+Dynamic: license-file
+
+# Spaceforge - Build Spacelift Plugins in Python
+
+Spaceforge is a Python framework for building powerful Spacelift plugins using a declarative, hook-based approach. Define your plugin logic in Python, and Spaceforge automatically generates the plugin manifest for Spacelift.
+
+## Usage
+
+For installation and usage instructions, see [our documentation](https://docs.spacelift.io/integrations/plugins).
+
+## Contributing
+
+To contribute to Spaceforge or create plugins, see our [CONTRIBUTING.md](./CONTRIBUTING.md) file.
+
+## License
+
+Spaceforge and Spacelift plugins are licensed under the [MIT license](./LICENSE).

spaceforge-1.1.6/README.md

@@ -0,0 +1,15 @@
+# Spaceforge - Build Spacelift Plugins in Python
+
+Spaceforge is a Python framework for building powerful Spacelift plugins using a declarative, hook-based approach. Define your plugin logic in Python, and Spaceforge automatically generates the plugin manifest for Spacelift.
+
+## Usage
+
+For installation and usage instructions, see [our documentation](https://docs.spacelift.io/integrations/plugins).
+
+## Contributing
+
+To contribute to Spaceforge or create plugins, see our [CONTRIBUTING.md](./CONTRIBUTING.md) file.
+
+## License
+
+Spaceforge and Spacelift plugins are licensed under the [MIT license](./LICENSE).