nself-plugin-sdk 1.2.5__tar.gz

nself_plugin_sdk-1.2.5/.github/workflows/sdk-py-publish.yml

@@ -0,0 +1,99 @@
+---
+name: Publish Python SDK
+
+# Triggers on:
+#   - sdk-scoped tag (sdk-py/v*)  -- publishes nself-plugin-sdk to PyPI
+#   - workflow_dispatch           -- manual publish with version input
+#
+# Publishes to https://pypi.org/project/nself-plugin-sdk/
+# Uses PyPI Trusted Publisher (OIDC) -- no API token required.
+# Configure the trusted publisher at https://pypi.org/manage/project/nself-plugin-sdk/settings/publishing/
+
+"on":
+  push:
+    tags:
+      - 'sdk-py/v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Publish version (e.g. 2.0.0). Used for release notes only.'
+        required: false
+        type: string
+
+permissions:
+  id-token: write   # required for PyPI Trusted Publisher (OIDC)
+  contents: write   # required to create GitHub release
+
+jobs:
+  publish:
+    name: Publish nself-plugin-sdk
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Derive version from tag
+        id: version
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/sdk-py/* ]]; then
+            echo "tag=${GITHUB_REF#refs/tags/sdk-py/}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=v${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Install dev dependencies
+        working-directory: sdk/py
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        working-directory: sdk/py
+        run: ruff check .
+
+      - name: Type-check
+        working-directory: sdk/py
+        run: mypy nself_plugin
+
+      - name: Test
+        working-directory: sdk/py
+        run: pytest -v
+
+      - name: Verify package version matches tag
+        working-directory: sdk/py
+        run: |
+          TAG="${{ steps.version.outputs.tag }}"
+          PKG_VERSION=$(python -c "import tomllib; f=open('pyproject.toml','rb'); d=tomllib.load(f); print(d['project']['version'])")
+          if [ "v${PKG_VERSION}" != "${TAG}" ]; then
+            echo "ERROR: pyproject.toml version 'v${PKG_VERSION}' does not match tag '${TAG}'"
+            exit 1
+          fi
+          echo "Version check passed: ${TAG}"
+
+      - name: Build distribution
+        working-directory: sdk/py
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdk/py/dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ steps.version.outputs.tag }}"
+          FULL_TAG="sdk-py/${TAG}"
+          NOTES=$(git tag -l --format='%(contents)' "${FULL_TAG}" 2>/dev/null || echo "Python SDK ${TAG} release.")
+          gh release create "${FULL_TAG}" \
+            --title "Python SDK ${TAG}" \
+            --notes "${NOTES}" \
+            --verify-tag

nself_plugin_sdk-1.2.5/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.DS_Store
+.mypy_cache/
+.pytest_cache/

nself_plugin_sdk-1.2.5/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: nself-plugin-sdk
+Version: 1.2.5
+Summary: Python plugin authoring SDK for nSelf. Parity with the Go SDK at github.com/nself-org/cli/sdk/go.
+License: MIT
+Keywords: nself,plugin,sdk,self-hosted
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: db
+Requires-Dist: asyncpg>=0.29; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nself-plugin
+
+Python plugin authoring SDK for [nSelf](https://nself.org). Parity with
+[plugin-sdk-go](https://github.com/nself-org/plugin-sdk-go) v0.1.0.
+
+## Install
+
+```bash
+pip install nself-plugin
+```
+
+For database migrations:
+
+```bash
+pip install 'nself-plugin[db]'
+```
+
+## Quick start
+
+```python
+from nself_plugin import Plugin, PluginContext, HealthStatus
+
+plugin = Plugin(name="my-notify", version="1.0.0")
+
+@plugin.install
+async def install(ctx: PluginContext) -> None:
+    ctx.env.require(["SMTP_HOST", "SMTP_PORT"])
+
+@plugin.start
+async def start(ctx: PluginContext) -> None:
+    app = ctx.http.create_app()
+    app.post("/notify/send")(handler)
+    await ctx.http.listen(ctx.port)
+
+@plugin.health
+async def health(ctx: PluginContext) -> HealthStatus:
+    return await ctx.http.ping("/notify/healthz")
+```
+
+## Scaffold a plugin
+
+```bash
+nself plugin new my-plugin --lang python
+```
+
+## License
+
+MIT

nself_plugin_sdk-1.2.5/README.md

@@ -0,0 +1,48 @@
+# nself-plugin
+
+Python plugin authoring SDK for [nSelf](https://nself.org). Parity with
+[plugin-sdk-go](https://github.com/nself-org/plugin-sdk-go) v0.1.0.
+
+## Install
+
+```bash
+pip install nself-plugin
+```
+
+For database migrations:
+
+```bash
+pip install 'nself-plugin[db]'
+```
+
+## Quick start
+
+```python
+from nself_plugin import Plugin, PluginContext, HealthStatus
+
+plugin = Plugin(name="my-notify", version="1.0.0")
+
+@plugin.install
+async def install(ctx: PluginContext) -> None:
+    ctx.env.require(["SMTP_HOST", "SMTP_PORT"])
+
+@plugin.start
+async def start(ctx: PluginContext) -> None:
+    app = ctx.http.create_app()
+    app.post("/notify/send")(handler)
+    await ctx.http.listen(ctx.port)
+
+@plugin.health
+async def health(ctx: PluginContext) -> HealthStatus:
+    return await ctx.http.ping("/notify/healthz")
+```
+
+## Scaffold a plugin
+
+```bash
+nself plugin new my-plugin --lang python
+```
+
+## License
+
+MIT

nself_plugin_sdk-1.2.5/nself_plugin/__init__.py

@@ -0,0 +1,54 @@
+"""
+nself-plugin — Python plugin authoring SDK for nSelf.
+
+Mirror of plugin-sdk-go v0.1.0: lifecycle hooks (install, start, health,
+migrate, uninstall), PluginContext with env/hasura/nginx/db/http/logger
+helpers, and a plugin.yaml manifest parser.
+
+Example::
+
+    from nself_plugin import Plugin, PluginContext, HealthStatus
+
+    plugin = Plugin(name="my-notify", version="1.0.0")
+
+    @plugin.install
+    async def install(ctx: PluginContext) -> None:
+        ctx.env.require(["SMTP_HOST", "SMTP_PORT"])
+
+    @plugin.start
+    async def start(ctx: PluginContext) -> None:
+        app = ctx.http.create_app()
+        app.get("/notify/healthz")(lambda: {"status": "ok"})
+        await ctx.http.listen(ctx.port)
+
+    @plugin.health
+    async def health(ctx: PluginContext) -> HealthStatus:
+        return await ctx.http.ping("/notify/healthz")
+"""
+
+from .plugin import Plugin, PluginInfo, HealthStatus
+from .context.env import EnvHelper
+from .context.hasura import HasuraHelper
+from .context.nginx import NginxHelper
+from .context.db import DatabaseHelper
+from .context.http import HttpHelper
+from ._manifest import PluginManifest, parse_manifest, parse_manifest_string, ManifestValidationError
+from ._runner import PluginContext
+
+__all__ = [
+    "Plugin",
+    "PluginInfo",
+    "HealthStatus",
+    "PluginContext",
+    "EnvHelper",
+    "HasuraHelper",
+    "NginxHelper",
+    "DatabaseHelper",
+    "HttpHelper",
+    "PluginManifest",
+    "parse_manifest",
+    "parse_manifest_string",
+    "ManifestValidationError",
+]
+
+__version__ = "0.1.0"

nself_plugin_sdk-1.2.5/nself_plugin/_manifest.py

@@ -0,0 +1,96 @@
+"""
+plugin.yaml manifest parser and validator.
+Mirrors the manifest parser in plugin-sdk-go (config/config.go + plugin.Info).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+class ManifestValidationError(ValueError):
+    """Raised when the plugin.yaml manifest is missing required fields or malformed."""
+
+    def __init__(self, message: str, field_name: Optional[str] = None) -> None:
+        self.field_name = field_name
+        super().__init__(f"plugin manifest: {message}")
+
+
+@dataclass
+class PluginManifest:
+    """Full plugin manifest shape as declared in plugin.yaml."""
+    name: str
+    version: str
+    tier: str  # "free" | "pro"
+    description: str = ""
+    bundle: str = ""
+    min_cli: str = ""
+    min_sdk: str = ""
+    port: int = 0
+    routes: list[dict[str, str]] = field(default_factory=list)
+    required_env: list[str] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+def parse_manifest(file_path: str = "plugin.yaml") -> PluginManifest:
+    """
+    Read and validate a plugin.yaml file.
+    Raises ManifestValidationError on missing required fields.
+    """
+    path = Path(file_path).resolve()
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestValidationError(f"cannot read file: {path}: {exc}") from exc
+    return parse_manifest_string(raw)
+
+
+def parse_manifest_string(content: str) -> PluginManifest:
+    """
+    Parse plugin.yaml content from a string. Useful in tests.
+    """
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError as exc:
+        raise ManifestValidationError(f"YAML parse error: {exc}") from exc
+
+    return _validate(data)
+
+
+def _validate(data: object) -> PluginManifest:
+    if not isinstance(data, dict):
+        raise ManifestValidationError("manifest must be a YAML object")
+
+    name = data.get("name")
+    if not name or not isinstance(name, str):
+        raise ManifestValidationError("name is required and must be a string", "name")
+
+    version = data.get("version")
+    if not version or not isinstance(version, str):
+        # pyyaml parses bare 1.0.0 as a float; coerce to string
+        if isinstance(version, (int, float)):
+            version = str(version)
+        else:
+            raise ManifestValidationError("version is required and must be a string", "version")
+
+    tier = data.get("tier")
+    if tier not in ("free", "pro"):
+        raise ManifestValidationError('tier must be "free" or "pro"', "tier")
+
+    return PluginManifest(
+        name=name,
+        version=version,
+        tier=tier,
+        description=data.get("description", ""),
+        bundle=data.get("bundle", ""),
+        min_cli=data.get("minCli", ""),
+        min_sdk=data.get("minSdk", ""),
+        port=int(data.get("port", 0)),
+        routes=data.get("routes") or [],
+        required_env=data.get("requiredEnv") or [],
+        metadata=data.get("metadata") or {},
+    )

nself_plugin_sdk-1.2.5/nself_plugin/_runner.py

@@ -0,0 +1,45 @@
+"""
+Lifecycle event orchestrator and PluginContext dataclass.
+Mirrors the runner.go concept in plugin-sdk-go.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from .context.env import EnvHelper
+from .context.hasura import HasuraHelper
+from .context.nginx import NginxHelper
+from .context.db import DatabaseHelper
+from .context.http import HttpHelper
+
+
+@dataclass
+class PluginContext:
+    """
+    Runtime context passed to every lifecycle hook.
+    Mirrors PluginContext in the spec and the helpers in plugin-sdk-go.
+    """
+
+    # TCP port the plugin should bind to (from NSELF_PLUGIN_PORT env var).
+    port: int
+
+    # Structured logger keyed to the plugin name.
+    logger: logging.Logger
+
+    # Env var helpers: require(), get(), get_int(), get_bool().
+    env: EnvHelper
+
+    # Hasura metadata API wrapper.
+    hasura: HasuraHelper
+
+    # Nginx route injection helper.
+    nginx: NginxHelper
+
+    # PostgreSQL helper for migration-time DDL only.
+    # Not for query-time use — plugins talk to Hasura GraphQL.
+    db: DatabaseHelper
+
+    # FastAPI app factory + httpx health client.
+    http: HttpHelper

nself_plugin_sdk-1.2.5/nself_plugin/context/__init__.py

@@ -0,0 +1 @@
+# context sub-package — individual helpers imported from their modules

nself_plugin_sdk-1.2.5/nself_plugin/context/db.py

@@ -0,0 +1,73 @@
+"""
+PostgreSQL helper — migration-time DDL only.
+Mirrors db.Pool in plugin-sdk-go: wraps asyncpg, exposes run_sql().
+NOT for query-time use — plugins must talk to Hasura GraphQL at runtime.
+asyncpg is an optional dependency (extras = ["db"]).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class SqlResult:
+    row_count: int
+    rows: list[dict[str, Any]]
+
+
+class DatabaseHelper:
+    """
+    PostgreSQL helper exposed in PluginContext.
+    Use only in install/migrate/uninstall hooks, never at request time.
+    """
+
+    def __init__(self, database_url: str) -> None:
+        self._database_url = database_url
+        self._pool: Any = None  # asyncpg.Pool, typed as Any to avoid hard dep
+
+    async def _get_pool(self) -> Any:
+        if self._pool is not None:
+            return self._pool
+        try:
+            import asyncpg  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise RuntimeError(
+                "plugin SDK: asyncpg is required for database operations. "
+                "Install with: pip install 'nself-plugin[db]'"
+            ) from exc
+        self._pool = await asyncpg.create_pool(self._database_url)
+        return self._pool
+
+    async def run_sql(self, sql: str, *params: Any) -> SqlResult:
+        """Execute raw SQL. Migration-time only."""
+        pool = await self._get_pool()
+        async with pool.acquire() as conn:
+            result = await conn.fetch(sql, *params)
+            rows = [dict(r) for r in result]
+        return SqlResult(row_count=len(rows), rows=rows)
+
+    async def close(self) -> None:
+        """Close the connection pool. Called by the runner on shutdown."""
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = None
+
+
+class DatabaseHelperStub(DatabaseHelper):
+    """
+    No-op stub for unit tests — no real DB required.
+    Usage::
+
+        ctx = PluginContext(..., db=DatabaseHelperStub())
+    """
+
+    def __init__(self) -> None:
+        super().__init__(database_url="")
+
+    async def run_sql(self, sql: str, *params: Any) -> SqlResult:
+        return SqlResult(row_count=0, rows=[])
+
+    async def close(self) -> None:
+        pass

nself_plugin_sdk-1.2.5/nself_plugin/context/env.py

@@ -0,0 +1,57 @@
+"""
+Env var helpers — mirrors config.Env / config.EnvRequired in plugin-sdk-go.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+
+class EnvHelper:
+    """
+    Env var helper exposed in PluginContext.
+    Mirrors config.Env, config.EnvRequired, etc. in plugin-sdk-go.
+    """
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        """Return the env var value or default."""
+        v = os.environ.get(key)
+        if v is not None and v != "":
+            return v
+        return default
+
+    def require(self, keys: list[str]) -> None:
+        """
+        Assert that all named env vars are non-empty.
+        Raises ValueError on first missing var — fail-fast at install/start time.
+        """
+        for key in keys:
+            if not os.environ.get(key):
+                raise ValueError(f"plugin SDK: required env var {key} is not set")
+
+    def get_int(self, key: str, default: int) -> int:
+        """Return the env var parsed as an integer, or default."""
+        v = os.environ.get(key)
+        if not v:
+            return default
+        try:
+            return int(v)
+        except ValueError:
+            return default
+
+    def get_bool(self, key: str, default: bool) -> bool:
+        """Return the env var parsed as boolean."""
+        v = (os.environ.get(key) or "").lower()
+        if v in ("true", "1", "yes", "y", "on"):
+            return True
+        if v in ("false", "0", "no", "n", "off"):
+            return False
+        return default
+
+    def get_list(self, key: str) -> list[str]:
+        """Split the env var on commas and trim whitespace. Empty → []."""
+        v = os.environ.get(key, "")
+        if not v:
+            return []
+        return [s.strip() for s in v.split(",") if s.strip()]

nself_plugin_sdk-1.2.5/nself_plugin/context/hasura.py

@@ -0,0 +1,97 @@
+"""
+Hasura metadata API wrapper for install/migrate/uninstall hooks.
+Mirrors HasuraHelper in the spec. Uses Hasura Metadata API v3 via httpx.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+@dataclass
+class TrackRelationshipOptions:
+    from_table: str
+    name: str
+    type: str  # "object" | "array"
+    to_table: str
+    from_column: str
+    to_column: str
+
+
+class HasuraHelper:
+    """
+    Hasura metadata API wrapper.
+    Async methods — use in async hooks (install, migrate, uninstall).
+    """
+
+    def __init__(self, admin_secret: str, endpoint: str) -> None:
+        self._admin_secret = admin_secret
+        self._endpoint = endpoint.rstrip("/")
+
+    async def _post(self, path: str, body: dict[str, Any]) -> Any:
+        url = f"{self._endpoint}{path}"
+        async with httpx.AsyncClient() as client:
+            res = await client.post(
+                url,
+                json=body,
+                headers={
+                    "Content-Type": "application/json",
+                    "x-hasura-admin-secret": self._admin_secret,
+                },
+                timeout=30,
+            )
+        if not res.is_success:
+            raise RuntimeError(
+                f"hasura: POST {path} failed ({res.status_code}): {res.text}"
+            )
+        return res.json()
+
+    async def add_table(self, table: str, schema: str = "public") -> None:
+        """Track a table in Hasura metadata."""
+        await self._post("/v1/metadata", {
+            "type": "pg_track_table",
+            "args": {"source": "default", "schema": schema, "name": table},
+        })
+
+    async def remove_table(self, table: str, schema: str = "public") -> None:
+        """Untrack a table from Hasura metadata."""
+        await self._post("/v1/metadata", {
+            "type": "pg_untrack_table",
+            "args": {"table": {"schema": schema, "name": table}, "cascade": False},
+        })
+
+    async def track_relationship(self, opts: TrackRelationshipOptions) -> None:
+        """Add a relationship between two tracked tables."""
+        api_type = (
+            "pg_create_object_relationship"
+            if opts.type == "object"
+            else "pg_create_array_relationship"
+        )
+        await self._post("/v1/metadata", {
+            "type": api_type,
+            "args": {
+                "source": "default",
+                "table": opts.from_table,
+                "name": opts.name,
+                "using": {
+                    "foreign_key_constraint_on": {
+                        "table": opts.to_table,
+                        "columns": [opts.to_column],
+                    }
+                },
+            },
+        })
+
+    async def run_metadata(self, type_: str, args: dict[str, Any]) -> Any:
+        """Raw Hasura metadata API request (escape hatch)."""
+        return await self._post("/v1/metadata", {"type": type_, "args": args})
+
+    async def run_sql(self, sql: str) -> None:
+        """Run a SQL migration via Hasura's run_sql API."""
+        await self._post("/v2/query", {
+            "type": "run_sql",
+            "args": {"source": "default", "sql": sql},
+        })

nself_plugin_sdk-1.2.5/nself_plugin/context/http.py

@@ -0,0 +1,101 @@
+"""
+HTTP helper: FastAPI app factory + httpx health client.
+Mirrors server.New() in plugin-sdk-go: auto-mounts /healthz, /readyz,
+/version on every plugin server.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional, cast
+
+import httpx
+from fastapi import FastAPI
+
+from ..plugin import HealthStatus
+
+
+class HttpHelper:
+    """HTTP helper exposed in PluginContext."""
+
+    def __init__(
+        self,
+        plugin_name: str,
+        plugin_version: str,
+        port: int,
+        health_check: Optional[Callable[[], Any]] = None,
+    ) -> None:
+        self._plugin_name = plugin_name
+        self._plugin_version = plugin_version
+        self._port = port
+        self._health_check = health_check
+        self._app: Optional[FastAPI] = None
+        self._logger = logging.getLogger(f"nself.{plugin_name}.http")
+
+    def create_app(self) -> FastAPI:
+        """
+        Return a FastAPI application pre-configured with:
+        - GET /healthz   → liveness (always 200)
+        - GET /readyz    → delegates to health_check
+        - GET /version   → plugin name + version JSON
+        """
+        if self._app is not None:
+            return self._app
+
+        app = FastAPI(title=self._plugin_name, version=self._plugin_version)
+
+        plugin_name = self._plugin_name
+        plugin_version = self._plugin_version
+        health_check = self._health_check
+
+        @app.get("/healthz")
+        async def healthz() -> dict[str, str]:
+            return {"status": "ok", "plugin": plugin_name, "version": plugin_version}
+
+        @app.get("/readyz")
+        async def readyz() -> dict[str, Any]:
+            if health_check is not None:
+                result = await health_check()
+                if isinstance(result, HealthStatus):
+                    return {"status": result.status, "message": result.message}
+                return cast(dict[str, Any], result)
+            return {"status": "ready"}
+
+        @app.get("/version")
+        async def version() -> dict[str, str]:
+            return {
+                "plugin": plugin_name,
+                "version": plugin_version,
+                "sdk": "nself-plugin",
+            }
+
+        self._app = app
+        return app
+
+    async def listen(self, port: int) -> None:
+        """Start the uvicorn server on the given port. Blocks until shutdown."""
+        import uvicorn
+
+        app = self.create_app()
+        config = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="info")
+        server = uvicorn.Server(config)
+        self._logger.info("plugin listening", extra={"port": port})
+        await server.serve()
+
+    async def ping(self, path: str) -> HealthStatus:
+        """
+        Send GET to path on localhost and return a HealthStatus.
+        Used in the health hook to check this plugin's own /healthz endpoint.
+        """
+        url = f"http://127.0.0.1:{self._port}{path}"
+        try:
+            async with httpx.AsyncClient() as client:
+                res = await client.get(url, timeout=5.0)
+            if res.is_success:
+                return HealthStatus(status="ok")
+            return HealthStatus(
+                status="degraded",
+                message=f"GET {path} returned HTTP {res.status_code}",
+            )
+        except Exception as exc:
+            return HealthStatus(status="unavailable", message=str(exc))

nself_plugin_sdk-1.2.5/nself_plugin/context/nginx.py

@@ -0,0 +1,39 @@
+"""
+Nginx route injection helper.
+Mirrors NginxHelper in the spec. Routes are declared in plugin.yaml;
+this helper is used in install hooks to validate / extend them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RouteOptions:
+    location: str   # e.g. "/notify/"
+    upstream: str   # e.g. "127.0.0.1:3850"
+    extra_directives: list[str] = field(default_factory=list)
+
+
+class NginxHelper:
+    """Nginx route injection helper exposed in PluginContext."""
+
+    def __init__(self) -> None:
+        self._routes: list[RouteOptions] = []
+
+    def add_route(self, opts: RouteOptions) -> None:
+        """Register a proxy_pass route to the plugin's upstream."""
+        if not opts.location.startswith("/"):
+            raise ValueError(
+                f"nginx: location must start with '/', got {opts.location!r}"
+            )
+        self._routes.append(opts)
+
+    def remove_route(self, location: str) -> None:
+        """Remove a previously registered route (used in uninstall)."""
+        self._routes = [r for r in self._routes if r.location != location]
+
+    def get_routes(self) -> list[RouteOptions]:
+        """Returns all routes registered in this session."""
+        return list(self._routes)

nself_plugin_sdk-1.2.5/nself_plugin/plugin.py

@@ -0,0 +1,113 @@
+"""
+Core Plugin class and related types.
+Mirrors plugin.Plugin interface and plugin.Info struct in plugin-sdk-go.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Awaitable, Callable, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._runner import PluginContext
+
+
+@dataclass
+class PluginInfo:
+    """Identity metadata for a plugin — mirrors plugin-sdk-go plugin.Info."""
+    name: str
+    version: str
+    description: str = ""
+    tier: str = "free"  # "free" | "pro"
+    bundle: str = ""
+    min_cli: str = ""
+    min_sdk: str = ""
+
+
+@dataclass
+class HealthStatus:
+    """Health check result returned by the health hook."""
+    status: str  # "ok" | "degraded" | "unavailable"
+    message: str = ""
+    checks: dict[str, bool] = field(default_factory=dict)
+
+
+# Type aliases for hook callables
+HookFn = Callable[["PluginContext"], Awaitable[None]]
+HealthFn = Callable[["PluginContext"], Awaitable[HealthStatus]]
+
+
+class Plugin:
+    """
+    Plugin is the primary authoring entry point for Python nSelf plugins.
+    Mirrors the definePlugin() function in @nself/plugin-sdk (TypeScript) and
+    the Plugin interface in plugin-sdk-go.
+
+    Usage::
+
+        plugin = Plugin(name="notify", version="1.0.0")
+
+        @plugin.install
+        async def install(ctx: PluginContext) -> None:
+            ctx.env.require(["SMTP_HOST"])
+
+        @plugin.start
+        async def start(ctx: PluginContext) -> None:
+            app = ctx.http.create_app()
+            await ctx.http.listen(ctx.port)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        version: str,
+        description: str = "",
+        tier: str = "free",
+        bundle: str = "",
+    ) -> None:
+        if not name:
+            raise ValueError("plugin SDK: name is required")
+        if not version:
+            raise ValueError("plugin SDK: version is required")
+        if tier not in ("free", "pro"):
+            raise ValueError(f"plugin SDK: tier must be 'free' or 'pro', got {tier!r}")
+
+        self.info = PluginInfo(
+            name=name,
+            version=version,
+            description=description,
+            tier=tier,
+            bundle=bundle,
+        )
+
+        self._install: Optional[HookFn] = None
+        self._start: Optional[HookFn] = None
+        self._health: Optional[HealthFn] = None
+        self._migrate: Optional[HookFn] = None
+        self._uninstall: Optional[HookFn] = None
+
+    # Decorator-based hook registration
+    def install(self, fn: HookFn) -> HookFn:
+        """Register the install hook (runs on `nself plugin install`)."""
+        self._install = fn
+        return fn
+
+    def start(self, fn: HookFn) -> HookFn:
+        """Register the start hook (runs when `nself start` brings the container up)."""
+        self._start = fn
+        return fn
+
+    def health(self, fn: HealthFn) -> HealthFn:
+        """Register the health hook (polled by `nself doctor`)."""
+        self._health = fn
+        return fn
+
+    def migrate(self, fn: HookFn) -> HookFn:
+        """Register the migrate hook (runs Hasura + SQL migrations on start)."""
+        self._migrate = fn
+        return fn
+
+    def uninstall(self, fn: HookFn) -> HookFn:
+        """Register the uninstall hook (runs on `nself plugin remove`)."""
+        self._uninstall = fn
+        return fn

nself_plugin_sdk-1.2.5/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nself-plugin-sdk"
+version = "1.2.5"
+description = "Python plugin authoring SDK for nSelf. Parity with the Go SDK at github.com/nself-org/cli/sdk/go."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["nself", "plugin", "sdk", "self-hosted"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.29",
+  "pyyaml>=6",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+db = ["asyncpg>=0.29"]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "mypy>=1.10",
+  "ruff>=0.4",
+  "asyncpg>=0.29",
+  "types-PyYAML>=6",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nself_plugin"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

nself_plugin_sdk-1.2.5/templates/main.py

@@ -0,0 +1,51 @@
+"""
+my-plugin — nSelf plugin built with the Python SDK.
+Generated by: nself plugin new my-plugin --lang python
+"""
+
+from nself_plugin import Plugin, PluginContext, HealthStatus
+
+plugin = Plugin(name="my-plugin", version="1.0.0")
+
+
+@plugin.install
+async def install(ctx: PluginContext) -> None:
+    ctx.logger.info("installing my-plugin")
+    # Verify required env vars
+    ctx.env.require([])
+    # Register Nginx route
+    from nself_plugin.context.nginx import RouteOptions
+    ctx.nginx.add_route(RouteOptions(
+        location="/my-plugin/",
+        upstream=f"127.0.0.1:{ctx.port}",
+    ))
+
+
+@plugin.start
+async def start(ctx: PluginContext) -> None:
+    ctx.logger.info(f"starting my-plugin on port {ctx.port}")
+    app = ctx.http.create_app()
+
+    # Add your routes here
+    @app.get("/my-plugin/hello")
+    async def hello() -> dict[str, str]:
+        return {"message": "Hello from my-plugin!"}
+
+    await ctx.http.listen(ctx.port)
+
+
+@plugin.health
+async def health(ctx: PluginContext) -> HealthStatus:
+    return await ctx.http.ping("/my-plugin/healthz")
+
+
+@plugin.migrate
+async def migrate(_ctx: PluginContext) -> None:
+    # Run Hasura metadata or SQL migrations here
+    pass
+
+
+@plugin.uninstall
+async def uninstall(ctx: PluginContext) -> None:
+    ctx.logger.info("uninstalling my-plugin")
+    ctx.nginx.remove_route("/my-plugin/")

nself_plugin_sdk-1.2.5/templates/plugin.yaml

@@ -0,0 +1,11 @@
+name: my-plugin
+version: "1.0.0"
+description: My nSelf plugin built with nself-plugin (Python SDK)
+tier: free
+port: 3851
+
+# Required environment variables (checked at install time)
+requiredEnv: []
+
+# Nginx routes this plugin exposes (populated by the CLI at build time)
+routes: []

nself_plugin_sdk-1.2.5/tests/test_env.py

@@ -0,0 +1,57 @@
+"""Tests for EnvHelper."""
+
+import pytest
+
+from nself_plugin.context.env import EnvHelper
+
+
+@pytest.fixture()
+def env() -> EnvHelper:
+    return EnvHelper()
+
+
+def test_get_returns_value(monkeypatch: pytest.MonkeyPatch, env: EnvHelper) -> None:
+    monkeypatch.setenv("TEST_VAR", "hello")
+    assert env.get("TEST_VAR") == "hello"
+
+
+def test_get_returns_default_when_missing(env: EnvHelper) -> None:
+    assert env.get("MISSING_VAR_XYZ", "default") == "default"
+
+
+def test_require_raises_on_missing(env: EnvHelper) -> None:
+    with pytest.raises(ValueError, match="REQUIRED_VAR"):
+        env.require(["REQUIRED_VAR"])
+
+
+def test_require_passes_when_all_set(monkeypatch: pytest.MonkeyPatch, env: EnvHelper) -> None:
+    monkeypatch.setenv("VAR_A", "a")
+    monkeypatch.setenv("VAR_B", "b")
+    env.require(["VAR_A", "VAR_B"])  # should not raise
+
+
+def test_get_int_parses(monkeypatch: pytest.MonkeyPatch, env: EnvHelper) -> None:
+    monkeypatch.setenv("MY_PORT", "3850")
+    assert env.get_int("MY_PORT", 3000) == 3850
+
+
+def test_get_int_returns_default_on_non_numeric(
+    monkeypatch: pytest.MonkeyPatch, env: EnvHelper
+) -> None:
+    monkeypatch.setenv("MY_PORT", "abc")
+    assert env.get_int("MY_PORT", 3000) == 3000
+
+
+def test_get_bool_true_variants(monkeypatch: pytest.MonkeyPatch, env: EnvHelper) -> None:
+    for v in ("true", "1", "yes", "y", "on"):
+        monkeypatch.setenv("BOOL_VAR", v)
+        assert env.get_bool("BOOL_VAR", False) is True
+
+
+def test_get_list_splits_commas(monkeypatch: pytest.MonkeyPatch, env: EnvHelper) -> None:
+    monkeypatch.setenv("LIST_VAR", "a, b, c")
+    assert env.get_list("LIST_VAR") == ["a", "b", "c"]
+
+
+def test_get_list_empty(env: EnvHelper) -> None:
+    assert env.get_list("UNSET_LIST_VAR") == []

nself_plugin_sdk-1.2.5/tests/test_manifest.py

@@ -0,0 +1,64 @@
+"""Tests for plugin.yaml manifest parser."""
+
+import pytest
+
+from nself_plugin import parse_manifest_string, ManifestValidationError
+
+VALID_YAML = """
+name: test-plugin
+version: "1.0.0"
+description: A test plugin
+tier: free
+port: 3850
+requiredEnv:
+  - DATABASE_URL
+"""
+
+PRO_YAML = """
+name: claw-plugin
+version: "2.1.0"
+tier: pro
+bundle: nClaw
+minCli: "1.0.0"
+"""
+
+
+def test_parses_valid_free_manifest() -> None:
+    m = parse_manifest_string(VALID_YAML)
+    assert m.name == "test-plugin"
+    assert m.version == "1.0.0"
+    assert m.tier == "free"
+    assert m.port == 3850
+    assert m.required_env == ["DATABASE_URL"]
+
+
+def test_parses_valid_pro_manifest() -> None:
+    m = parse_manifest_string(PRO_YAML)
+    assert m.name == "claw-plugin"
+    assert m.tier == "pro"
+    assert m.bundle == "nClaw"
+
+
+def test_raises_on_missing_name() -> None:
+    with pytest.raises(ManifestValidationError, match="name"):
+        parse_manifest_string("version: '1.0.0'\ntier: free\n")
+
+
+def test_raises_on_missing_version() -> None:
+    with pytest.raises(ManifestValidationError, match="version"):
+        parse_manifest_string("name: x\ntier: free\n")
+
+
+def test_raises_on_invalid_tier() -> None:
+    with pytest.raises(ManifestValidationError, match="tier"):
+        parse_manifest_string("name: x\nversion: '1.0.0'\ntier: enterprise\n")
+
+
+def test_raises_on_invalid_yaml() -> None:
+    with pytest.raises(ManifestValidationError):
+        parse_manifest_string("name: [unclosed")
+
+
+def test_raises_on_non_object() -> None:
+    with pytest.raises(ManifestValidationError, match="YAML object"):
+        parse_manifest_string("- item1\n- item2\n")

nself_plugin_sdk-1.2.5/tests/test_plugin.py

@@ -0,0 +1,99 @@
+"""Tests for Plugin class — lifecycle hook registration and validation."""
+
+import pytest
+
+from nself_plugin import Plugin, PluginContext, HealthStatus
+from nself_plugin.context.env import EnvHelper
+from nself_plugin.context.nginx import NginxHelper
+from nself_plugin.context.db import DatabaseHelperStub
+from nself_plugin.context.http import HttpHelper
+
+
+def make_ctx(port: int = 3850) -> PluginContext:
+    """Build a minimal PluginContext for testing."""
+    import logging
+    return PluginContext(
+        port=port,
+        logger=logging.getLogger("test"),
+        env=EnvHelper(),
+        hasura=None,  # type: ignore[arg-type]
+        nginx=NginxHelper(),
+        db=DatabaseHelperStub(),
+        http=HttpHelper("test-plugin", "1.0.0", port),
+    )
+
+
+def test_plugin_stores_info() -> None:
+    p = Plugin(name="test", version="1.0.0", tier="free")
+    assert p.info.name == "test"
+    assert p.info.version == "1.0.0"
+    assert p.info.tier == "free"
+
+
+def test_plugin_requires_name() -> None:
+    with pytest.raises(ValueError, match="name is required"):
+        Plugin(name="", version="1.0.0")
+
+
+def test_plugin_requires_version() -> None:
+    with pytest.raises(ValueError, match="version is required"):
+        Plugin(name="test", version="")
+
+
+def test_plugin_rejects_invalid_tier() -> None:
+    with pytest.raises(ValueError, match="tier"):
+        Plugin(name="test", version="1.0.0", tier="enterprise")
+
+
+async def test_install_hook_called() -> None:
+    plugin = Plugin(name="notify", version="1.0.0")
+    called: list[bool] = []
+
+    @plugin.install
+    async def install(ctx: PluginContext) -> None:
+        called.append(True)
+
+    ctx = make_ctx()
+    assert plugin._install is not None
+    await plugin._install(ctx)
+    assert called == [True]
+
+
+async def test_health_hook_returns_status() -> None:
+    plugin = Plugin(name="notify", version="1.0.0")
+
+    @plugin.health
+    async def health(ctx: PluginContext) -> HealthStatus:
+        return HealthStatus(status="ok")
+
+    ctx = make_ctx()
+    assert plugin._health is not None
+    result = await plugin._health(ctx)
+    assert result.status == "ok"
+
+
+async def test_all_hooks_can_be_registered() -> None:
+    plugin = Plugin(name="full", version="2.0.0", tier="pro", bundle="nClaw")
+
+    @plugin.install
+    async def install(ctx: PluginContext) -> None: pass
+
+    @plugin.start
+    async def start(ctx: PluginContext) -> None: pass
+
+    @plugin.health
+    async def health(ctx: PluginContext) -> HealthStatus:
+        return HealthStatus(status="ok")
+
+    @plugin.migrate
+    async def migrate(ctx: PluginContext) -> None: pass
+
+    @plugin.uninstall
+    async def uninstall(ctx: PluginContext) -> None: pass
+
+    assert plugin._install is not None
+    assert plugin._start is not None
+    assert plugin._health is not None
+    assert plugin._migrate is not None
+    assert plugin._uninstall is not None
+    assert plugin.info.bundle == "nClaw"