pulice 0.1.0__tar.gz

pulice-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: pulice
+Version: 0.1.0
+Summary: A framework for managing infrastructure-as-code components via Pulumi with tenant isolation, async execution, and pluggable backends.
+Author: mk.fshr
+License-Expression: MIT
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: pulumi>=3.215.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: typer>=0.21.1
+Requires-Dist: textual>=3.0.0 ; extra == 'admin'
+Requires-Dist: textual-serve>=1.1.0 ; extra == 'admin'
+Requires-Dist: fastapi>=0.115.0 ; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'api'
+Requires-Dist: huey>=2.5.0 ; extra == 'api'
+Requires-Dist: pulumi-aws>=7.15.0 ; extra == 'aws'
+Requires-Dist: celery[redis]>=5.4.0 ; extra == 'celery'
+Requires-Python: >=3.13
+Provides-Extra: admin
+Provides-Extra: api
+Provides-Extra: aws
+Provides-Extra: celery
+Description-Content-Type: text/markdown
+
+# Pulice
+
+A Python framework for managing infrastructure-as-code components via [Pulumi](https://www.pulumi.com/) with tenant isolation, async execution, and pluggable backends.
+
+## Features
+
+- **Component model** — Define cloud resources as `ManagedComponent` subclasses with Pydantic-validated inputs
+- **Tenant isolation** — Named boundaries ensure stacks belonging to different environments never collide
+- **9 lifecycle operations** — create, read, update, delete, refresh, list, status, export, import
+- **CLI + HTTP API** — Synchronous CLI for interactive use; async FastAPI server for automation
+- **Pluggable task backends** — Huey (SQLite, zero-dep) or Celery (Redis, distributed)
+- **Passphrase-protected stacks** — scrypt-hashed passphrases validated before any Pulumi call
+- **Advisory locking** — Prevents concurrent mutating operations on the same stack
+- **Provider-agnostic** — Works with any Pulumi provider (AWS, GCP, Azure, Kubernetes, etc.)
+
+## Installation
+
+```bash
+pip install pulice
+```
+
+With optional extras:
+
+```bash
+pip install pulice[api]      # FastAPI server + Huey worker
+pip install pulice[celery]   # Celery backend for distributed deployments
+pip install pulice[aws]      # AWS provider
+```
+
+## Quick Start
+
+Define a component:
+
+```python
+from pulice import ComponentArgs, ManagedComponent
+from pydantic import Field
+import pulumi
+import pulumi_aws as aws
+
+class BucketArgs(ComponentArgs):
+    region: str = Field(description="AWS region")
+
+class Bucket(ManagedComponent):
+    args_model = BucketArgs
+
+    def __init__(self, name: str, args: BucketArgs, opts=None, **kwargs):
+        super().__init__("pulice:aws:Bucket", name, {}, opts)
+        aws.s3.BucketV2(f"{name}-bucket", opts=pulumi.ResourceOptions(parent=self))
+```
+
+Register and run:
+
+```python
+from typer import Typer
+from pulice import PuliceCLI
+
+app = Typer()
+cli = PuliceCLI(app)
+cli.register_component(Bucket, name="bucket")
+
+if __name__ == "__main__":
+    cli()
+```
+
+Use it:
+
+```bash
+pulice tenant create --name dev
+pulice bucket create --name my-data --region eu-west-1 --tenant dev --passphrase secret
+pulice bucket list --tenant dev
+pulice bucket delete --stack-reference <ref> --tenant dev --passphrase secret
+```
+
+## HTTP API
+
+```bash
+pip install pulice[api]
+uvicorn pulice.api:create_api --factory --host 0.0.0.0 --port 8000
+huey_consumer pulice.worker.huey -w 2 -k process
+```
+
+Submit operations asynchronously:
+
+```bash
+curl -X POST http://localhost:8000/stacks/operations \
+  -H "Content-Type: application/json" \
+  -d '{"component_class": "myapp.Bucket", "operation": "create", "tenant": "dev", "passphrase": "secret", "args": {"name": "my-data", "region": "eu-west-1"}}'
+```
+
+## Documentation
+
+Full documentation is available at the [project site](https://your-org.github.io/pulice/) or can be built locally:
+
+```bash
+pip install pulice[docs]
+zensical serve
+```
+
+## License
+
+[MIT](LICENSE) — Mike Fischer and Dani Vela Calderón

pulice-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Pulice
+
+A Python framework for managing infrastructure-as-code components via [Pulumi](https://www.pulumi.com/) with tenant isolation, async execution, and pluggable backends.
+
+## Features
+
+- **Component model** — Define cloud resources as `ManagedComponent` subclasses with Pydantic-validated inputs
+- **Tenant isolation** — Named boundaries ensure stacks belonging to different environments never collide
+- **9 lifecycle operations** — create, read, update, delete, refresh, list, status, export, import
+- **CLI + HTTP API** — Synchronous CLI for interactive use; async FastAPI server for automation
+- **Pluggable task backends** — Huey (SQLite, zero-dep) or Celery (Redis, distributed)
+- **Passphrase-protected stacks** — scrypt-hashed passphrases validated before any Pulumi call
+- **Advisory locking** — Prevents concurrent mutating operations on the same stack
+- **Provider-agnostic** — Works with any Pulumi provider (AWS, GCP, Azure, Kubernetes, etc.)
+
+## Installation
+
+```bash
+pip install pulice
+```
+
+With optional extras:
+
+```bash
+pip install pulice[api]      # FastAPI server + Huey worker
+pip install pulice[celery]   # Celery backend for distributed deployments
+pip install pulice[aws]      # AWS provider
+```
+
+## Quick Start
+
+Define a component:
+
+```python
+from pulice import ComponentArgs, ManagedComponent
+from pydantic import Field
+import pulumi
+import pulumi_aws as aws
+
+class BucketArgs(ComponentArgs):
+    region: str = Field(description="AWS region")
+
+class Bucket(ManagedComponent):
+    args_model = BucketArgs
+
+    def __init__(self, name: str, args: BucketArgs, opts=None, **kwargs):
+        super().__init__("pulice:aws:Bucket", name, {}, opts)
+        aws.s3.BucketV2(f"{name}-bucket", opts=pulumi.ResourceOptions(parent=self))
+```
+
+Register and run:
+
+```python
+from typer import Typer
+from pulice import PuliceCLI
+
+app = Typer()
+cli = PuliceCLI(app)
+cli.register_component(Bucket, name="bucket")
+
+if __name__ == "__main__":
+    cli()
+```
+
+Use it:
+
+```bash
+pulice tenant create --name dev
+pulice bucket create --name my-data --region eu-west-1 --tenant dev --passphrase secret
+pulice bucket list --tenant dev
+pulice bucket delete --stack-reference <ref> --tenant dev --passphrase secret
+```
+
+## HTTP API
+
+```bash
+pip install pulice[api]
+uvicorn pulice.api:create_api --factory --host 0.0.0.0 --port 8000
+huey_consumer pulice.worker.huey -w 2 -k process
+```
+
+Submit operations asynchronously:
+
+```bash
+curl -X POST http://localhost:8000/stacks/operations \
+  -H "Content-Type: application/json" \
+  -d '{"component_class": "myapp.Bucket", "operation": "create", "tenant": "dev", "passphrase": "secret", "args": {"name": "my-data", "region": "eu-west-1"}}'
+```
+
+## Documentation
+
+Full documentation is available at the [project site](https://your-org.github.io/pulice/) or can be built locally:
+
+```bash
+pip install pulice[docs]
+zensical serve
+```
+
+## License
+
+[MIT](LICENSE) — Mike Fischer and Dani Vela Calderón

pulice-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "pulice"
+version = "0.1.0"
+description = "A framework for managing infrastructure-as-code components via Pulumi with tenant isolation, async execution, and pluggable backends."
+readme = "README.md"
+authors = [
+    {name = "mk.fshr"},
+]
+license = "MIT"
+requires-python = ">=3.13"
+dependencies = [
+    "pulumi>=3.215.0",
+    "pydantic>=2.12.5",
+    "typer>=0.21.1",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "License :: OSI Approved :: MIT License",
+]
+
+[tool.pyrefly]
+project-includes = ["src"]
+project-excludes = ["**/*venv/**/*", "examples/", "tests/"]
+
+[project.optional-dependencies]
+aws = ["pulumi-aws>=7.15.0"]
+api = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "huey>=2.5.0",
+]
+celery = [
+    "celery[redis]>=5.4.0",
+]
+admin = [
+    "textual>=3.0.0",
+    "textual-serve>=1.1.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-cov>=6.0.0",
+    "fastapi>=0.115.0",
+    "huey>=2.5.0",
+    "httpx>=0.28.0",
+]
+docs = [
+    "zensical>=0.0.37",
+    "mkdocstrings[python]>=0.29.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = ["-ra", "-q"]
+testpaths = ["tests"]
+
+[tool.uv.workspace]
+members = [
+    "examples/bootstrap-usecase",
+    "examples/static-website",
+    "examples/api-postgres",
+    "examples/kubernetes-deploy",
+]
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+docstring-code-format = true
+exclude = [
+    "build",
+    "dist",
+    ".eggs",
+]
+
+[tool.ruff.lint]
+ignore = [
+    "N801", # class names should use CapWords convention (class names)
+    "N812", # lowercase imported as non-lowercase (pyspark.sql functions as F)
+    "N818"  # Exception name should have Error suffix
+]
+
+select = [
+    "E",
+    "F",
+    "N",
+    "W",
+    "I001", # isort configuration for ruff "--profile", "black"
+]
+
+
+[tool.ruff.lint.isort.sections]
+typing = ["typing"]
+
+
+[tool.ruff.lint.isort]
+no-lines-before = ["future", "standard-library", "third-party", "first-party", "local-folder", "typing"]
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder", "typing"]
+
+[tool.bandit]
+skips = ["B601", "B608", "B101", "B110"] # B101 asserts used
+exclude_dirs = ["tests/", "examples/"]

pulice-0.1.0/src/pulice/__init__.py

@@ -0,0 +1,19 @@
+__version__ = '0.1.0'
+
+from pulice.cli.app import PuliceCLI
+from pulice.core.base import ComponentArgs, ManagedComponent
+from pulice.core.controllers import ComponentController, WorkspaceController
+from pulice.core.protocol import PuliceApp
+from pulice.core.tasks import TaskBackend, TaskResult, TaskStatus
+
+__all__ = [
+    'ComponentArgs',
+    'ComponentController',
+    'ManagedComponent',
+    'PuliceApp',
+    'PuliceCLI',
+    'TaskBackend',
+    'TaskResult',
+    'TaskStatus',
+    'WorkspaceController',
+]

pulice-0.1.0/src/pulice/admin/__init__.py

@@ -0,0 +1,13 @@
+"""Pulice Admin TUI — terminal and browser dashboard."""
+
+from __future__ import annotations
+
+
+def create_admin_app(
+    state_dir: str | None = None,
+    refresh_interval: int = 5,
+) -> 'PuliceAdmin':  # noqa: F821  # pyrefly: ignore
+    """Create and return the admin TUI application."""
+    from pulice.admin.app import PuliceAdmin
+
+    return PuliceAdmin(state_dir=state_dir, refresh_interval=refresh_interval)

pulice-0.1.0/src/pulice/admin/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running the admin TUI with: python -m pulice.admin"""
+
+import sys
+from pulice.admin.app import PuliceAdmin
+
+state_dir = sys.argv[1] if len(sys.argv) > 1 else None
+app = PuliceAdmin(state_dir=state_dir)
+app.run()

pulice-0.1.0/src/pulice/admin/app.py

@@ -0,0 +1,90 @@
+"""PuliceAdmin — main Textual application for the admin TUI."""
+
+from __future__ import annotations
+from pathlib import Path
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.widgets import Footer, Header, TabbedContent, TabPane
+from pulice.admin.data import AdminDataSource
+from pulice.admin.screens.dashboard import DashboardScreen
+from pulice.admin.screens.stacks import StacksScreen
+from pulice.admin.screens.system import SystemScreen
+from pulice.admin.screens.tasks import TasksScreen
+from pulice.admin.screens.tenants import TenantsScreen
+
+CSS_PATH = Path(__file__).parent / 'styles' / 'app.tcss'
+
+
+class PuliceAdmin(App):
+    """Pulice administrative dashboard TUI."""
+
+    TITLE = 'Pulice Admin'
+    CSS_PATH = CSS_PATH
+    BINDINGS = [
+        Binding('1', "switch_tab('dashboard')", 'Dashboard', show=False),
+        Binding('2', "switch_tab('tenants')", 'Tenants', show=False),
+        Binding('3', "switch_tab('stacks')", 'Stacks', show=False),
+        Binding('4', "switch_tab('tasks')", 'Tasks', show=False),
+        Binding('5', "switch_tab('system')", 'System', show=False),
+        Binding('r', 'force_refresh', 'Refresh'),
+        Binding('q', 'quit', 'Quit'),
+    ]
+
+    def __init__(
+        self,
+        state_dir: str | None = None,
+        refresh_interval: int = 5,
+        **kwargs,
+    ) -> None:
+        super().__init__(**kwargs)
+        self._state_dir = state_dir
+        self._refresh_interval = refresh_interval
+        self._data = AdminDataSource(state_dir=state_dir)
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Vertical(id='main'):
+            with TabbedContent(id='tabs'):
+                with TabPane('Dashboard', id='dashboard'):
+                    yield DashboardScreen(self._data)
+                with TabPane('Tenants', id='tenants'):
+                    yield TenantsScreen(self._data)
+                with TabPane('Stacks', id='stacks'):
+                    yield StacksScreen(self._data)
+                with TabPane('Tasks', id='tasks'):
+                    yield TasksScreen(self._data)
+                with TabPane('System', id='system'):
+                    yield SystemScreen(self._data)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._do_refresh()
+        if self._refresh_interval > 0:
+            self.set_interval(self._refresh_interval, self._do_refresh)
+
+    def _do_refresh(self) -> None:
+        self.run_worker(self._refresh_worker, exclusive=True)
+
+    async def _refresh_worker(self) -> None:
+        for screen_cls in (
+            DashboardScreen,
+            TenantsScreen,
+            StacksScreen,
+            TasksScreen,
+            SystemScreen,
+        ):
+            try:
+                widget = self.query_one(screen_cls)  # pyrefly: ignore
+                widget.refresh_data()
+            except Exception:  # noseq
+                pass
+
+    def action_switch_tab(self, tab_id: str) -> None:
+        tabs = self.query_one('#tabs', TabbedContent)
+        tabs.active = tab_id  # pyrefly: ignore
+        self._do_refresh()
+
+    def action_force_refresh(self) -> None:
+        self._do_refresh()
+        self.notify('Refreshed')

pulice-0.1.0/src/pulice/admin/data.py

@@ -0,0 +1,112 @@
+"""Read-only data provider for the admin TUI."""
+
+from __future__ import annotations
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+import pulice
+from pulice.core.stack import (
+    LocalStackReferenceStore,
+    SqliteBackendStorage,
+    StackReference,
+    Tenant,
+)
+from pulice.core.tasks import TaskBackend, TaskResult
+from typing import Any
+
+
+class AdminDataSource:
+    """Read-only data provider for the admin TUI.
+
+    Wraps existing storage APIs to provide data for all admin screens.
+    """
+
+    def __init__(self, state_dir: str | None = None) -> None:
+        self._state_dir = state_dir or os.getenv('PULICE_STATE_DIR')
+        self._storage = SqliteBackendStorage(root_dir=self._state_dir)
+        self._references = LocalStackReferenceStore(root_dir=self._state_dir)
+        self._task_backend: TaskBackend | None = None
+
+    def _get_task_backend(self) -> TaskBackend:
+        if self._task_backend is None:
+            from pulice.core.tasks import get_task_backend
+
+            self._task_backend = get_task_backend(state_dir=self._state_dir)
+        return self._task_backend
+
+    @property
+    def state_dir(self) -> str:
+        return str(self._storage._root)
+
+    def get_tenants(self) -> list[Tenant]:
+        return self._storage.list_tenants()
+
+    def get_stacks(self, tenant_id: str | None = None) -> list[dict[str, Any]]:
+        return self._storage.list_stacks(tenant_id=tenant_id)
+
+    def get_stack_references(self, tenant_id: str | None = None) -> list[StackReference]:
+        return self._references.list(tenant_id=tenant_id)
+
+    def get_locks(self) -> list[dict[str, Any]]:
+        with self._storage._connect() as conn:
+            rows = conn.execute(
+                'SELECT stack_name, holder, operation, locked_at FROM stack_locks'
+            ).fetchall()
+        now = datetime.now(timezone.utc)
+        results = []
+        for r in rows:
+            locked_at = datetime.fromisoformat(r[3])
+            age_seconds = (now - locked_at).total_seconds()
+            results.append(
+                {
+                    'stack_name': r[0],
+                    'holder': r[1],
+                    'operation': r[2],
+                    'locked_at': r[3],
+                    'age_seconds': age_seconds,
+                }
+            )
+        return results
+
+    def get_task_status(self, task_id: str) -> TaskResult:
+        return self._get_task_backend().get_status(task_id)
+
+    def get_system_info(self) -> dict[str, Any]:
+        state_path = Path(self.state_dir)
+        db_path = state_path / 'pulice_stacks.sqlite3'
+
+        total_size = sum(f.stat().st_size for f in state_path.rglob('*') if f.is_file())
+        db_size = db_path.stat().st_size if db_path.exists() else 0
+
+        tenants = self.get_tenants()
+        stacks = self.get_stacks()
+        locks = self.get_locks()
+
+        backend_type = os.getenv('PULICE_TASK_BACKEND', 'huey')
+
+        return {
+            'version': pulice.__version__,
+            'python': sys.version,
+            'state_dir': self.state_dir,
+            'state_dir_size': total_size,
+            'db_size': db_size,
+            'task_backend': backend_type,
+            'tenant_count': len(tenants),
+            'stack_count': len(stacks),
+            'lock_count': len(locks),
+            'locks': locks,
+        }
+
+    def delete_tenant(self, name: str) -> None:
+        self._storage.delete_tenant(name)
+
+    def release_lock(self, stack_name: str) -> None:
+        with self._storage._connect() as conn:
+            conn.execute('DELETE FROM stack_locks WHERE stack_name = ?', (stack_name,))
+
+    def cancel_task(self, task_id: str) -> bool:
+        return self._get_task_backend().cancel(task_id)
+
+    def retry_task(self, task_id: str) -> str:
+        return self._get_task_backend().retry(task_id)

pulice-0.1.0/src/pulice/admin/screens/__init__.py

@@ -0,0 +1,15 @@
+"""Admin TUI screens."""
+
+from pulice.admin.screens.dashboard import DashboardScreen
+from pulice.admin.screens.stacks import StacksScreen
+from pulice.admin.screens.system import SystemScreen
+from pulice.admin.screens.tasks import TasksScreen
+from pulice.admin.screens.tenants import TenantsScreen
+
+__all__ = [
+    'DashboardScreen',
+    'TenantsScreen',
+    'StacksScreen',
+    'TasksScreen',
+    'SystemScreen',
+]

pulice-0.1.0/src/pulice/admin/screens/dashboard.py

@@ -0,0 +1,61 @@
+"""Dashboard screen — summary view with key metrics."""
+
+from __future__ import annotations
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Static
+from pulice.admin.widgets.stat_card import StatCard
+
+if __name__ != '__main__':
+    from typing import TYPE_CHECKING
+
+    if TYPE_CHECKING:
+        from pulice.admin.data import AdminDataSource
+
+
+class DashboardScreen(Static):
+    """Summary dashboard showing key metrics at a glance."""
+
+    DEFAULT_CSS = """
+    DashboardScreen {
+        height: 1fr;
+        padding: 1 2;
+    }
+    DashboardScreen .metrics-row {
+        height: 7;
+        margin-bottom: 1;
+    }
+    DashboardScreen .info-section {
+        height: auto;
+        padding: 1;
+    }
+    """
+
+    def __init__(self, data_source: 'AdminDataSource') -> None:
+        super().__init__()
+        self._data = data_source
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(classes='metrics-row'):
+            yield StatCard('Tenants', '0', id='stat-tenants')
+            yield StatCard('Stacks', '0', id='stat-stacks')
+            yield StatCard('Active Locks', '0', id='stat-locks')
+        with Horizontal(classes='metrics-row'):
+            yield StatCard('Pending Tasks', '—', id='stat-pending')
+            yield StatCard('Running Tasks', '—', id='stat-running')
+            yield StatCard('Failed Tasks', '—', id='stat-failed')
+        with Vertical(classes='info-section'):
+            yield Static(id='system-info')
+
+    def refresh_data(self) -> None:
+        info = self._data.get_system_info()
+        self.query_one('#stat-tenants', StatCard).update_value(str(info['tenant_count']))
+        self.query_one('#stat-stacks', StatCard).update_value(str(info['stack_count']))
+        self.query_one('#stat-locks', StatCard).update_value(str(info['lock_count']))
+
+        info_text = (
+            f'[bold]Pulice[/bold] v{info["version"]}  |  '
+            f'Backend: {info["task_backend"]}  |  '
+            f'State: {info["state_dir"]}'
+        )
+        self.query_one('#system-info', Static).update(info_text)