spaceforge 1.1.0__py3-none-any.whl → 1.1.1__py3-none-any.whl

spaceforge/_version_scm.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.1.1'
+__version_tuple__ = version_tuple = (1, 1, 1)
 
 __commit_id__ = commit_id = None

spaceforge/plugin.py

@@ -2,7 +2,6 @@
 Base plugin class for Spaceforge framework.
 """
 
-import inspect
 import json
 import logging
 import os
@@ -162,35 +161,6 @@ class SpaceforgePlugin(ABC):
         else:
             self.logger.error(f"API call returned no data: {resp}")
 
-    def get_available_hooks(self) -> List[str]:
-        """
-        Get list of hook methods available in this plugin.
-
-        Returns:
-            List of hook method names that are implemented
-        """
-        hook_methods = []
-        for method_name in dir(self):
-            if not method_name.startswith("_") and method_name != "get_available_hooks":
-                method = getattr(self, method_name)
-                if callable(method) and not inspect.isbuiltin(method):
-                    # Check if it's a hook method (not inherited from base class)
-                    if method_name in [
-                        "before_init",
-                        "after_init",
-                        "before_plan",
-                        "after_plan",
-                        "before_apply",
-                        "after_apply",
-                        "before_perform",
-                        "after_perform",
-                        "before_destroy",
-                        "after_destroy",
-                        "after_run",
-                    ]:
-                        hook_methods.append(method_name)
-        return hook_methods
-
     def run_cli(
         self, *command: str, expect_code: int = 0, print_output: bool = True
     ) -> Tuple[int, List[str], List[str]]:

spaceforge/templates/binary_install.sh.j2

@@ -8,8 +8,6 @@ if command -v {{binary.name}}; then
     return
 fi
 
-mkdir -p {{static_binary_directory}}
-
 echo "Installing {{binary.name}}..."
 mkdir -p {{static_binary_directory}}
 cd {{static_binary_directory}}

spaceforge/test_plugin_hooks.py

@@ -31,70 +31,3 @@ class TestSpaceforgePluginHooks:
             assert callable(hook_method)
             # Should be able to call without error (default implementation is pass)
             hook_method()
-
-    def test_should_return_all_available_hooks_for_base_class(self) -> None:
-        """Should detect and return all hook methods defined in base class."""
-        # Arrange
-        plugin = SpaceforgePlugin()
-        expected_hooks = [
-            "before_init",
-            "after_init",
-            "before_plan",
-            "after_plan",
-            "before_apply",
-            "after_apply",
-            "before_perform",
-            "after_perform",
-            "before_destroy",
-            "after_destroy",
-            "after_run",
-        ]
-
-        # Act
-        hooks = plugin.get_available_hooks()
-
-        # Assert
-        for expected_hook in expected_hooks:
-            assert expected_hook in hooks
-
-    def test_should_detect_overridden_hooks_in_custom_plugin(self) -> None:
-        """Should include all hooks including overridden ones in custom plugins."""
-
-        # Arrange
-        class TestPluginWithHooks(SpaceforgePlugin):
-            def after_plan(self) -> None:
-                pass
-
-            def before_apply(self) -> None:
-                pass
-
-            def custom_method(self) -> None:  # Not a hook
-                pass
-
-        plugin = TestPluginWithHooks()
-
-        # Act
-        hooks = plugin.get_available_hooks()
-
-        # Assert
-        assert "after_plan" in hooks
-        assert "before_apply" in hooks
-        assert "custom_method" not in hooks  # Not a recognized hook
-
-        # Should still have all the expected hooks from the base class
-        expected_hooks = [
-            "before_init",
-            "after_init",
-            "before_plan",
-            "after_plan",
-            "before_apply",
-            "after_apply",
-            "before_perform",
-            "after_perform",
-            "before_destroy",
-            "after_destroy",
-            "after_run",
-        ]
-
-        for expected_hook in expected_hooks:
-            assert expected_hook in hooks

{spaceforge-1.1.0.dist-info → spaceforge-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spaceforge
-Version: 1.1.0
+Version: 1.1.1
 Summary: A Python framework for building Spacelift plugins
 Home-page: https://github.com/spacelift-io/plugins
 Author: Spacelift
@@ -63,7 +63,7 @@ pip install spaceforge
 Create a Python file (e.g., `my_plugin.py`) and inherit from `SpaceforgePlugin`:
 
 ```python
-from spaceforge import SpaceforgePlugin, Parameter, Variable, Context
+from spaceforge import SpaceforgePlugin, Parameter, Variable, Context, Binary, Policy, Webhook, MountedFile
 import os
 
 class MyPlugin(SpaceforgePlugin):
@@ -71,17 +71,20 @@ class MyPlugin(SpaceforgePlugin):
     __plugin_name__ = "my-awesome-plugin"
     __version__ = "1.0.0"
     __author__ = "Your Name"
+    __labels__ = ["security", "monitoring"]  # Optional labels for categorization
     
     # Define plugin parameters
     __parameters__ = [
         Parameter(
-            name="api_key",
+            name="API Key",
+            id="api_key",  # Optional ID for parameter reference
             description="API key for external service",
             required=True,
             sensitive=True
         ),
         Parameter(
-            name="environment",
+            name="Environment",
+            id="environment",
             description="Target environment",
             required=False,
             default="production"
@@ -96,12 +99,12 @@ class MyPlugin(SpaceforgePlugin):
             env=[
                 Variable(
                     key="API_KEY",
-                    value_from_parameter="api_key",
+                    value_from_parameter="api_key",  # Matches parameter id or name
                     sensitive=True
                 ),
                 Variable(
                     key="ENVIRONMENT",
-                    value_from_parameter="environment"
+                    value_from_parameter="environment"  # Matches parameter id or name
                 )
             ]
         )
@@ -160,6 +163,15 @@ Override these methods in your plugin to add custom logic:
 
 ## Plugin Components
 
+### Labels
+
+Add optional labels to categorize your plugin:
+
+```python
+class MyPlugin(SpaceforgePlugin):
+    __labels__ = ["security", "monitoring", "compliance"]
+```
+
 ### Parameters
 
 Define user-configurable parameters:
@@ -167,21 +179,30 @@ Define user-configurable parameters:
 ```python
 __parameters__ = [
     Parameter(
-        name="database_url",
+        name="Database URL",
+        id="database_url",  # Optional: used for parameter reference
         description="Database connection URL",
         required=True,
-        sensitive=True,
-        default="postgresql://localhost:5432/mydb"
+        sensitive=True
     ),
     Parameter(
-        name="timeout", 
+        name="Timeout", 
+        id="timeout",
         description="Timeout in seconds",
         required=False,
-        default=30
+        default="30"  # Default values should be strings
     )
 ]
 ```
 
+**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
+
 ### Contexts
 
 Define Spacelift contexts with environment variables and custom hooks:
@@ -191,11 +212,11 @@ __contexts__ = [
     Context(
         name_prefix="production",
         description="Production environment context",
-        labels={"env": "prod"},
+        labels=["env:prod"],
         env=[
             Variable(
                 key="DATABASE_URL",
-                value_from_parameter="database_url",
+                value_from_parameter="database_url",  # Matches parameter id
                 sensitive=True
             ),
             Variable(
@@ -229,6 +250,88 @@ __binaries__ = [
 ]
 ```
 
+**Context Priority System:**
+
+Control the execution order of contexts using the `priority` field:
+
+```python
+__contexts__ = [
+    Context(
+        name_prefix="setup",
+        description="Setup context (runs first)",
+        priority=0,  # Lower numbers run first
+        hooks={
+            "before_init": ["echo 'Setting up environment'"]
+        }
+    ),
+    Context(
+        name_prefix="main", 
+        description="Main context (runs second)",
+        priority=1,  # Higher numbers run after lower ones
+        hooks={
+            "before_init": ["echo 'Main execution'"]
+        }
+    )
+]
+```
+
+**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
+
+**Binary PATH Management:**
+- 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
+__contexts__ = [
+    Context(
+        name_prefix="kubectl-setup",
+        description="Setup kubectl binary for raw hooks",
+        hooks={
+            "before_init": [
+                'export PATH="/mnt/workspace/plugins/plugin_binaries:$PATH"',
+                "kubectl version"
+            ]
+        }
+    )
+]
+```
+
+### Mounted Files
+
+Mount file content directly into contexts:
+
+```python
+from spaceforge import MountedFile
+
+__contexts__ = [
+    Context(
+        name_prefix="config",
+        description="Context with mounted configuration files",
+        mounted_files=[
+            MountedFile(
+                path="tmp/config.json",
+                content='{"environment": "production", "debug": false}',
+                sensitive=False
+            ),
+            MountedFile(
+                path="tmp/secret-config.yaml",
+                content="api_key: secret-value\nendpoint: https://api.example.com",
+                sensitive=True  # Marks content as sensitive
+            )
+        ]
+    )
+]
+```
+
+**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`
+
 ### Policies
 
 Define OPA policies for your plugin:
@@ -237,7 +340,7 @@ Define OPA policies for your plugin:
 __policies__ = [
     Policy(
         name_prefix="security-check",
-        type="notification",
+        type="NOTIFICATION",
         body="""
 package spacelift
 
@@ -245,7 +348,7 @@ webhook[{"endpoint_id": "security-alerts"}] {
   input.run_updated.run.marked_unsafe == true
 }
         """,
-        labels={"type": "security"}
+        labels=["security"]
     )
 ]
 ```
@@ -258,11 +361,9 @@ Define webhooks to trigger external actions:
 __webhooks__ = [
     Webhook(
         name_prefix="security-alerts",
-        description="Send security alerts to external service",
         endpoint="https://alerts.example.com/webhook",
-        secrets=[
-            Variable(key="amazing", value="secret-value", sensitive=True)
-        ],
+        secretFromParameter="webhook_secret",  # Parameter id/name for webhook secret
+        labels=["security"]
     )
 ]
 ```
@@ -297,7 +398,7 @@ def before_apply(self):
 
 ### Spacelift API Integration
 
-Query the Spacelift GraphQL API (requires `SPACELIFT_API_TOKEN` and `SPACELIFT_DOMAIN`):
+Query the Spacelift GraphQL API (requires `SPACELIFT_API_TOKEN` and `TF_VAR_spacelift_graphql_endpoint`):
 
 ```python
 def after_plan(self):
@@ -317,6 +418,38 @@ def after_plan(self):
     self.logger.info(f"Stack state: {result['stack']['state']}")
 ```
 
+### User Token Authentication
+
+Use user API tokens instead of service tokens for Spacelift API access. This is useful because the token on the run may not have sufficient permissions for certain operations.
+
+```python
+def before_plan(self):
+    # Use user API token for authentication
+    user_id = os.environ.get('SPACELIFT_USER_ID')
+    user_secret = os.environ.get('SPACELIFT_USER_SECRET')
+    
+    if user_id and user_secret:
+        self.use_user_token(user_id, user_secret)
+        
+        # Now you can use the API with user permissions
+        result = self.query_api("""
+            query {
+                viewer {
+                    id
+                    login
+                }
+            }
+        """)
+        
+        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
+
 ### Access Plan and State
 
 Access Terraform plan and state data:
@@ -353,14 +486,14 @@ def after_plan(self):
     self.send_markdown(markdown)
 ```
 
-### Append to Policy Input
+### Add to Policy Input
 
-Append custom data to the OPA 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):
-    self.append_policy_input("my_custom_data", {
+    self.add_to_policy_input("my_custom_data", {
         "scan_results": {
             "passed": True,
             "issues": []
@@ -389,9 +522,9 @@ spaceforge generate --help
 ### Test Plugin Hooks
 
 ```bash
-# Set parameters via environment variables
-export SPACEFORGE_PARAM_API_KEY="test-key" 
-export SPACEFORGE_PARAM_TIMEOUT="60"
+# Set parameters for local testing (parameters are normally provided by Spacelift)
+export API_KEY="test-key" 
+export TIMEOUT="60"
 
 # Test specific hook
 spaceforge runner after_plan
@@ -420,8 +553,8 @@ Access Spacelift environment variables in your hooks:
 
 ```python
 def after_plan(self):
-    run_id = os.environ.get('SPACELIFT_RUN_ID')
-    stack_id = os.environ.get('SPACELIFT_STACK_ID')
+    run_id = os.environ.get('TF_VAR_spacelift_run_id')
+    stack_id = os.environ.get('TF_VAR_spacelift_stack_id') 
     self.logger.info(f"Processing run {run_id} for stack {stack_id}")
 ```
 
@@ -455,7 +588,7 @@ Here's a complete example of a security scanning plugin:
 ```python
 import os
 import json
-from spaceforge import SpaceforgePlugin, Parameter, Variable, Context, Binary
+from spaceforge import SpaceforgePlugin, Parameter, Variable, Context, Binary, Policy, MountedFile
 
 class SecurityScannerPlugin(SpaceforgePlugin):
     __plugin_name__ = "security-scanner"
@@ -474,13 +607,15 @@ class SecurityScannerPlugin(SpaceforgePlugin):
     
     __parameters__ = [
         Parameter(
-            name="api_token",
+            name="API Token",
+            id="api_token",
             description="Security service API token",
             required=True,
             sensitive=True
         ),
         Parameter(
-            name="severity_threshold", 
+            name="Severity Threshold", 
+            id="severity_threshold",
             description="Minimum severity level to report",
             required=False,
             default="medium"
@@ -581,8 +716,8 @@ Generate and test this plugin:
 spaceforge generate security_scanner.py
 
 # Test locally
-export SPACEFORGE_PARAM_API_TOKEN="your-token"
-export SPACEFORGE_PARAM_SEVERITY_THRESHOLD="high"
+export API_TOKEN="your-token"
+export SEVERITY_THRESHOLD="high"
 spaceforge runner after_plan
 ```
 

{spaceforge-1.1.0.dist-info → spaceforge-1.1.1.dist-info}/RECORD

@@ -2,11 +2,11 @@ spaceforge/README.md,sha256=8o1Nuyasb4OxX3E7ZycyducOrR4J19bZcHrLvFeoFNg,7730
 spaceforge/__init__.py,sha256=TU-vvm15dK1ucixNW0V42eTT72x3_hmKSyxP4MC1Occ,589
 spaceforge/__main__.py,sha256=c3nAw4WBnHXIcfMlRV6Ja7r87pEhSeK-SAqiSYIasIY,643
 spaceforge/_version.py,sha256=RP_LfUd4ODnrfwn9nam8wB6bR3lM4VwmoRxK08Tkiiw,2155
-spaceforge/_version_scm.py,sha256=ePNVzJOkxR8FY5bezqKQ_fgBRbzH1G7QTaRDHvGQRAY,704
+spaceforge/_version_scm.py,sha256=O2MwkHziz63f5tgvyTDcaX64UwyuPAN_tWOgO5wh1WI,704
 spaceforge/cls.py,sha256=oYW5t5_xs9ZM6Ne_b4trxCPxLHQrqbqgUeibeM8O4PU,6329
 spaceforge/conftest.py,sha256=U-xCavCsgRAQXqflIIOMeq9pcGbeqRviUNkEXgZol8g,2141
 spaceforge/generator.py,sha256=hCxtbOKmrGd7HCCz7HMaiK566kIre5MNxcJEx2TVURM,18430
-spaceforge/plugin.py,sha256=nNMus9cfVsazqvZG-buTWhK9CkeROdC5vQdOvc8EUQA,16129
+spaceforge/plugin.py,sha256=Ytm2B7nnJNH231V4gUFY1pBmwVNTpIg3YviUL_Bnf24,14963
 spaceforge/runner.py,sha256=EUZ98gmOiJ766zOSk7YcTTrLCtHfst1xf3iE2Xu7Tao,3172
 spaceforge/schema.json,sha256=89IROLVlCj8txGMiLt4Bbuo_2muSxKoZCyaXQ2vuA9c,10869
 spaceforge/test_cls.py,sha256=nXAgbnFnGdFxrtA7vNXiePjNUASuoYW-lEuQGx9WMGs,468
@@ -17,17 +17,17 @@ spaceforge/test_generator_hooks.py,sha256=2lJs8dYlFb7QehWcYF0O4qg38s5UudEpzJyBi1
 spaceforge/test_generator_parameters.py,sha256=77az9rcocFny2AC4O2eTzjCW712fR1DBHzGrgBKeR4w,1878
 spaceforge/test_plugin.py,sha256=rZ4Uv_0lIR0qb1GFHkiosGO3WHTWhO7epz8INDxV8Q0,13018
 spaceforge/test_plugin_file_operations.py,sha256=B0qvIo5EcfKMiHLhBv-hAnpSonn83ojcmJHXasydojA,3782
-spaceforge/test_plugin_hooks.py,sha256=rNCZZyd_SDMkm1x3yl5mjQ5tBMGm3YNd1U6h_niWRQs,2962
+spaceforge/test_plugin_hooks.py,sha256=ugaVdzH1-heRJSJN0lu8zoqLcLPC3tg_PzUX98qu9Sw,1038
 spaceforge/test_plugin_inheritance.py,sha256=WHfvU5s-2GtfcI9-1bHXH7bacr77ikq68V3Z3BBQKvQ,3617
 spaceforge/test_runner.py,sha256=fDnUf6gEuf1CNMxz6zs3xXvERQsQU3z8qy9KdUc0Wo4,17739
 spaceforge/test_runner_cli.py,sha256=Sf5X0O9Wc9EhGB5L8SzvlmO7QmgQZQoClSdNYefa-lQ,2299
 spaceforge/test_runner_core.py,sha256=eNR9YOwJwv7LsMtNQ4WXXMPIW6RE_A7hUp4bCpzz1Rk,3941
 spaceforge/test_runner_execution.py,sha256=GJhoECdhIY2M3MWcmTrIYfkJd2P5n86zixO3FY38_CQ,5344
-spaceforge/templates/binary_install.sh.j2,sha256=znz2G9mm3dOg0iqyxZoj4_ATBEi7HviMETMGRk5D7uM,536
+spaceforge/templates/binary_install.sh.j2,sha256=3vcKUSIpMxYWUuAfAWs3gP3tNr4ZnBIb2ELAqISViZo,498
 spaceforge/templates/ensure_spaceforge_and_run.sh.j2,sha256=g5BldIEve0IkZ-mCzTXfB_rFvyWqUJqymRRaaMrpp0s,550
-spaceforge-1.1.0.dist-info/licenses/LICENSE,sha256=wyljRrfnWY2ggQKkSCg3Nw2hxwPMmupopaKs9Kpgys8,1065
-spaceforge-1.1.0.dist-info/METADATA,sha256=pn-bRqlzGeEYFB-mqbrdgfYWOJUvy9pU3lGsbUuR-Ro,16803
-spaceforge-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-spaceforge-1.1.0.dist-info/entry_points.txt,sha256=qawuuKBSNTGg-njnQnhxxFldFvXYAPej6bF_f3iyQ48,56
-spaceforge-1.1.0.dist-info/top_level.txt,sha256=eVw-Lw4Th0oHM8Gx1Y8YetyNgbNbMBU00yWs-kwGeSs,11
-spaceforge-1.1.0.dist-info/RECORD,,
+spaceforge-1.1.1.dist-info/licenses/LICENSE,sha256=wyljRrfnWY2ggQKkSCg3Nw2hxwPMmupopaKs9Kpgys8,1065
+spaceforge-1.1.1.dist-info/METADATA,sha256=0Mc6aKdf5jOm3KwfG0mrn7-owmKGZTZ-H5DXAfRojnc,21164
+spaceforge-1.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+spaceforge-1.1.1.dist-info/entry_points.txt,sha256=qawuuKBSNTGg-njnQnhxxFldFvXYAPej6bF_f3iyQ48,56
+spaceforge-1.1.1.dist-info/top_level.txt,sha256=eVw-Lw4Th0oHM8Gx1Y8YetyNgbNbMBU00yWs-kwGeSs,11
+spaceforge-1.1.1.dist-info/RECORD,,