npmctl 0.3.1__tar.gz

npmctl-0.3.1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: npmctl
+Version: 0.3.1
+Summary: Owner-scoped plan/apply/adopt controller for Nginx Proxy Manager resources.
+Keywords: nginx-proxy-manager,reverse-proxy,gitops,controller,ssl-certificates,access-lists
+Author: npmctl contributors
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: requests>=2.32.0
+Requires-Python: >=3.11, <3.14
+Project-URL: Homepage, https://github.com/groupsum/npmctl
+Project-URL: Documentation, https://github.com/groupsum/npmctl/tree/master/docs
+Project-URL: Issues, https://github.com/groupsum/npmctl/issues
+Project-URL: Repository, https://github.com/groupsum/npmctl
+Description-Content-Type: text/markdown
+
+# npmctl
+
+`npmctl` is the Python package and console script for owner-scoped Nginx Proxy Manager automation. It validates desired-state YAML, computes safe plans, applies clean changes, and adopts unmanaged resources only when explicitly requested.
+
+## Install
+
+Use `pipx` for an isolated CLI install:
+
+```bash
+pipx install npmctl
+npmctl --version
+```
+
+Use `uv` if you manage tools with uv:
+
+```bash
+uv tool install npmctl
+npmctl --help
+```
+
+Use `pip` inside an existing virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install npmctl
+npmctl --help
+```
+
+PowerShell activation:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install npmctl
+npmctl --help
+```
+
+## Configure NPM
+
+Set Nginx Proxy Manager API credentials as environment variables:
+
+```bash
+export NPM_BASE_URL=http://127.0.0.1:81/api
+export NPM_IDENTITY=admin@example.com
+export NPM_SECRET=changeme
+```
+
+Or pass them directly:
+
+```bash
+npmctl --base-url http://127.0.0.1:81/api --identity admin@example.com --secret changeme health
+```
+
+## Desired State
+
+Every managed resource needs npmctl ownership metadata:
+
+```yaml
+apiVersion: npmctl.io/v1
+schemaVersion: 1
+proxy_hosts:
+  - domain_names: [app.example.com]
+    forward_scheme: http
+    forward_host: app
+    forward_port: 3000
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: proxy.app
+```
+
+References use `resource_id` values:
+
+```yaml
+apiVersion: npmctl.io/v1
+schemaVersion: 1
+certificates:
+  - name: wildcard-example
+    domain_names: ["*.example.com", example.com]
+    certificate_type: letsencrypt
+    api_payload:
+      provider: letsencrypt
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: cert.wildcard-example
+access_lists:
+  - name: private-admins
+    api_payload:
+      satisfy_any: 0
+      items: []
+      clients: []
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: acl.private-admins
+proxy_hosts:
+  - domain_names: [app.example.com]
+    forward_host: app
+    forward_port: 3000
+    certificate_ref: cert.wildcard-example
+    access_list_ref: acl.private-admins
+    ssl_forced: 1
+    allow_websocket_upgrade: 1
+    caching_enabled: 1
+    block_exploits: 1
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: proxy.app
+```
+
+## Commands
+
+Validate files without calling the NPM API:
+
+```bash
+npmctl validate ./desired-state
+npmctl --output json validate ./desired-state
+```
+
+Check or write desired-state schema migrations:
+
+```bash
+npmctl migrate ./desired-state --check
+npmctl migrate ./desired-state --write
+```
+
+Check the target NPM API:
+
+```bash
+npmctl health
+npmctl schema fetch --write npm-openapi.json
+npmctl schema capabilities
+npmctl schema check
+```
+
+Plan and apply by owner:
+
+```bash
+npmctl plan ./desired-state --owner workload-a
+npmctl apply ./desired-state --owner workload-a
+```
+
+Preview apply without mutation:
+
+```bash
+npmctl apply ./desired-state --owner workload-a --dry-run
+```
+
+Prune owned resources absent from desired state:
+
+```bash
+npmctl apply ./desired-state --owner workload-a --prune-owned
+```
+
+Adopt unmanaged matching resources:
+
+```bash
+npmctl adopt ./desired-state --owner workload-a
+npmctl adopt ./desired-state --owner workload-a --allow-field-drift
+```
+
+## Exit Codes
+
+- `0`: success
+- `1`: plan conflict
+- `2`: usage, validation, or migration error
+- `3`: API error
+- `4`: endpoint capability error
+
+## More Documentation
+
+The source repository includes detailed docs and examples:
+
+- https://github.com/groupsum/npmctl
+- https://github.com/groupsum/npmctl/tree/master/examples/desired-state
+- https://github.com/groupsum/npmctl/tree/master/docs

npmctl-0.3.1/README.md

@@ -0,0 +1,179 @@
+# npmctl
+
+`npmctl` is the Python package and console script for owner-scoped Nginx Proxy Manager automation. It validates desired-state YAML, computes safe plans, applies clean changes, and adopts unmanaged resources only when explicitly requested.
+
+## Install
+
+Use `pipx` for an isolated CLI install:
+
+```bash
+pipx install npmctl
+npmctl --version
+```
+
+Use `uv` if you manage tools with uv:
+
+```bash
+uv tool install npmctl
+npmctl --help
+```
+
+Use `pip` inside an existing virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install npmctl
+npmctl --help
+```
+
+PowerShell activation:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install npmctl
+npmctl --help
+```
+
+## Configure NPM
+
+Set Nginx Proxy Manager API credentials as environment variables:
+
+```bash
+export NPM_BASE_URL=http://127.0.0.1:81/api
+export NPM_IDENTITY=admin@example.com
+export NPM_SECRET=changeme
+```
+
+Or pass them directly:
+
+```bash
+npmctl --base-url http://127.0.0.1:81/api --identity admin@example.com --secret changeme health
+```
+
+## Desired State
+
+Every managed resource needs npmctl ownership metadata:
+
+```yaml
+apiVersion: npmctl.io/v1
+schemaVersion: 1
+proxy_hosts:
+  - domain_names: [app.example.com]
+    forward_scheme: http
+    forward_host: app
+    forward_port: 3000
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: proxy.app
+```
+
+References use `resource_id` values:
+
+```yaml
+apiVersion: npmctl.io/v1
+schemaVersion: 1
+certificates:
+  - name: wildcard-example
+    domain_names: ["*.example.com", example.com]
+    certificate_type: letsencrypt
+    api_payload:
+      provider: letsencrypt
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: cert.wildcard-example
+access_lists:
+  - name: private-admins
+    api_payload:
+      satisfy_any: 0
+      items: []
+      clients: []
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: acl.private-admins
+proxy_hosts:
+  - domain_names: [app.example.com]
+    forward_host: app
+    forward_port: 3000
+    certificate_ref: cert.wildcard-example
+    access_list_ref: acl.private-admins
+    ssl_forced: 1
+    allow_websocket_upgrade: 1
+    caching_enabled: 1
+    block_exploits: 1
+    meta:
+      managed_by: npmctl
+      owner: workload-a
+      resource_id: proxy.app
+```
+
+## Commands
+
+Validate files without calling the NPM API:
+
+```bash
+npmctl validate ./desired-state
+npmctl --output json validate ./desired-state
+```
+
+Check or write desired-state schema migrations:
+
+```bash
+npmctl migrate ./desired-state --check
+npmctl migrate ./desired-state --write
+```
+
+Check the target NPM API:
+
+```bash
+npmctl health
+npmctl schema fetch --write npm-openapi.json
+npmctl schema capabilities
+npmctl schema check
+```
+
+Plan and apply by owner:
+
+```bash
+npmctl plan ./desired-state --owner workload-a
+npmctl apply ./desired-state --owner workload-a
+```
+
+Preview apply without mutation:
+
+```bash
+npmctl apply ./desired-state --owner workload-a --dry-run
+```
+
+Prune owned resources absent from desired state:
+
+```bash
+npmctl apply ./desired-state --owner workload-a --prune-owned
+```
+
+Adopt unmanaged matching resources:
+
+```bash
+npmctl adopt ./desired-state --owner workload-a
+npmctl adopt ./desired-state --owner workload-a --allow-field-drift
+```
+
+## Exit Codes
+
+- `0`: success
+- `1`: plan conflict
+- `2`: usage, validation, or migration error
+- `3`: API error
+- `4`: endpoint capability error
+
+## More Documentation
+
+The source repository includes detailed docs and examples:
+
+- https://github.com/groupsum/npmctl
+- https://github.com/groupsum/npmctl/tree/master/examples/desired-state
+- https://github.com/groupsum/npmctl/tree/master/docs

npmctl-0.3.1/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "npmctl"
+version = "0.3.1"
+description = "Owner-scoped plan/apply/adopt controller for Nginx Proxy Manager resources."
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+license = "Apache-2.0"
+authors = [{ name = "npmctl contributors" }]
+keywords = [
+  "nginx-proxy-manager",
+  "reverse-proxy",
+  "gitops",
+  "controller",
+  "ssl-certificates",
+  "access-lists",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+  "Topic :: System :: Systems Administration",
+  "Typing :: Typed",
+]
+dependencies = [
+  "PyYAML>=6.0.2",
+  "requests>=2.32.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/groupsum/npmctl"
+Documentation = "https://github.com/groupsum/npmctl/tree/master/docs"
+Issues = "https://github.com/groupsum/npmctl/issues"
+Repository = "https://github.com/groupsum/npmctl"
+
+[project.scripts]
+npmctl = "npmctl.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12"]
+build-backend = "uv_build"

npmctl-0.3.1/src/npmctl/__init__.py

@@ -0,0 +1,3 @@
+"""npmctl: owner-scoped controller for Nginx Proxy Manager."""
+
+__version__ = "0.3.1"

npmctl-0.3.1/src/npmctl/__main__.py

@@ -0,0 +1,5 @@
+"""python -m npmctl entry point."""
+
+from npmctl.cli import main
+
+raise SystemExit(main())

npmctl-0.3.1/src/npmctl/adoption.py

@@ -0,0 +1,5 @@
+"""Adoption helpers."""
+
+from npmctl.planner import PlannerOptions, compute_plan
+
+__all__ = ["PlannerOptions", "compute_plan"]

npmctl-0.3.1/src/npmctl/apply.py

@@ -0,0 +1,238 @@
+"""Apply owner-scoped plans to NPM."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from npmctl.client import NpmClient
+from npmctl.errors import ApiError, ConflictError, ValidationError
+from npmctl.metadata import merge_managed_meta
+from npmctl.models import (
+    DesiredAccessList,
+    DesiredCertificate,
+    DesiredGenericResource,
+    DesiredProxyHost,
+    ExistingResource,
+    PlanAction,
+    ResourceKind,
+)
+from npmctl.planner import Plan, PlanOperation
+from npmctl.schema import Capabilities
+
+
+@dataclass(slots=True)
+class ApplyResult:
+    """Result of applying a plan."""
+
+    applied: bool
+    mutations: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"applied": self.applied, "mutations": list(self.mutations)}
+
+
+class ApplyEngine:
+    """Executes a validated plan in dependency order."""
+
+    def __init__(self, *, client: NpmClient, capabilities: Capabilities) -> None:
+        self.client = client
+        self.capabilities = capabilities
+        self.created_by_resource_id: dict[str, ExistingResource] = {}
+
+    def apply(self, plan: Plan) -> ApplyResult:
+        """Apply the plan. Conflicts prevent all mutations."""
+
+        if plan.conflicts:
+            raise ConflictError("refusing to apply plan with conflicts")
+        for operation in plan.operations:
+            if operation.desired is not None and operation.existing is not None:
+                self.created_by_resource_id.setdefault(operation.desired.identity.resource_id, operation.existing)
+        result = ApplyResult(applied=True)
+        for operation in _ordered_operations(plan.operations):
+            if operation.action == PlanAction.NOOP:
+                continue
+            mutation = self._apply_operation(operation)
+            result.mutations.append(mutation)
+        return result
+
+    def _apply_operation(self, operation: PlanOperation) -> dict[str, Any]:
+        if operation.action == PlanAction.CREATE:
+            return self._create(operation)
+        if operation.action == PlanAction.UPDATE:
+            return self._update(operation)
+        if operation.action == PlanAction.ADOPT:
+            return self._adopt(operation)
+        if operation.action == PlanAction.DELETE:
+            return self._delete(operation)
+        raise ValidationError(f"unsupported apply operation {operation.action}")
+
+    def _create(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        payload = self._payload_for(desired)
+        created = self.client.create_resource(desired.kind, payload)
+        self.created_by_resource_id[desired.identity.resource_id] = created
+        return {
+            "action": "create",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": created.id,
+        }
+
+    def _update(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        existing = _require_existing(operation)
+        payload = self._merge_existing_with_desired(existing, desired)
+        cap = self.capabilities.for_kind(desired.kind)
+        updated = self.client.update_resource(desired.kind, existing.id, payload, method=cap.update_method or "put")
+        return {
+            "action": "update",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": updated.id,
+        }
+
+    def _adopt(self, operation: PlanOperation) -> dict[str, Any]:
+        desired = _require_desired(operation)
+        existing = _require_existing(operation)
+        payload = _updateable_existing_payload(existing)
+        payload["meta"] = merge_managed_meta(payload.get("meta"), desired.meta)
+        cap = self.capabilities.for_kind(desired.kind)
+        updated = self.client.update_resource(desired.kind, existing.id, payload, method=cap.update_method or "put")
+        return {
+            "action": "adopt",
+            "kind": desired.kind.value,
+            "resource_id": desired.identity.resource_id,
+            "id": updated.id,
+        }
+
+    def _delete(self, operation: PlanOperation) -> dict[str, Any]:
+        existing = _require_existing(operation)
+        deleted = self.client.delete_resource(existing.kind, existing.id)
+        if not deleted:
+            raise ApiError(f"delete failed for {existing.kind.value} id={existing.id}")
+        resource_id = existing.identity.resource_id if existing.identity else None
+        return {"action": "delete", "kind": existing.kind.value, "resource_id": resource_id, "id": existing.id}
+
+    def _merge_existing_with_desired(
+        self,
+        existing: ExistingResource,
+        desired: DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource,
+    ) -> dict[str, Any]:
+        payload = self._payload_for(desired)
+        payload["meta"] = merge_managed_meta(existing.raw.get("meta"), desired.meta)
+        return payload
+
+    def _payload_for(
+        self, desired: DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource
+    ) -> dict[str, Any]:
+        if isinstance(desired, DesiredProxyHost):
+            certificate_id = self._resolve_reference(desired.certificate_ref, ResourceKind.CERTIFICATE)
+            access_list_id = self._resolve_reference(desired.access_list_ref, ResourceKind.ACCESS_LIST)
+            return desired.to_payload(certificate_id=certificate_id, access_list_id=access_list_id)
+        return desired.to_payload()
+
+    def _resolve_reference(self, ref: str | None, kind: ResourceKind) -> int | None:
+        if ref is None:
+            return None
+        created = self.created_by_resource_id.get(ref)
+        if created is not None:
+            if created.kind != kind:
+                raise ValidationError(f"reference {ref!r} resolved to {created.kind.value}, expected {kind.value}")
+            return created.id
+        raise ValidationError(f"unresolved {kind.value} reference: {ref}")
+
+
+def _ordered_operations(operations: tuple[PlanOperation, ...]) -> list[PlanOperation]:
+    creates_updates_adopts = [
+        op for op in operations if op.action in {PlanAction.CREATE, PlanAction.UPDATE, PlanAction.ADOPT}
+    ]
+    deletes = [op for op in operations if op.action == PlanAction.DELETE]
+    order = {
+        ResourceKind.CERTIFICATE: 0,
+        ResourceKind.ACCESS_LIST: 1,
+        ResourceKind.REDIRECTION_HOST: 2,
+        ResourceKind.DEAD_HOST: 2,
+        ResourceKind.STREAM: 2,
+        ResourceKind.USER: 2,
+        ResourceKind.SETTING: 2,
+        ResourceKind.PROXY_HOST: 3,
+    }
+    delete_order = {
+        ResourceKind.PROXY_HOST: 0,
+        ResourceKind.REDIRECTION_HOST: 1,
+        ResourceKind.DEAD_HOST: 1,
+        ResourceKind.STREAM: 1,
+        ResourceKind.USER: 1,
+        ResourceKind.SETTING: 1,
+        ResourceKind.ACCESS_LIST: 2,
+        ResourceKind.CERTIFICATE: 3,
+    }
+    return sorted(creates_updates_adopts, key=lambda op: order[op.kind]) + sorted(
+        deletes, key=lambda op: delete_order[op.kind]
+    )
+
+
+def _require_desired(
+    operation: PlanOperation,
+) -> DesiredProxyHost | DesiredCertificate | DesiredAccessList | DesiredGenericResource:
+    if operation.desired is None:
+        raise ValidationError(f"operation {operation.action} requires desired resource")
+    return operation.desired
+
+
+def _require_existing(operation: PlanOperation) -> ExistingResource:
+    if operation.existing is None:
+        raise ValidationError(f"operation {operation.action} requires existing resource")
+    return operation.existing
+
+
+def _updateable_existing_payload(existing: ExistingResource) -> dict[str, Any]:
+    fields = {
+        ResourceKind.PROXY_HOST: (
+            "domain_names",
+            "forward_scheme",
+            "forward_host",
+            "forward_port",
+            "certificate_id",
+            "ssl_forced",
+            "hsts_enabled",
+            "hsts_subdomains",
+            "http2_support",
+            "block_exploits",
+            "caching_enabled",
+            "allow_websocket_upgrade",
+            "access_list_id",
+            "advanced_config",
+            "enabled",
+            "locations",
+            "meta",
+        ),
+        ResourceKind.ACCESS_LIST: ("name", "satisfy_any", "pass_auth", "items", "clients", "meta"),
+        ResourceKind.CERTIFICATE: ("provider", "nice_name", "domain_names", "meta"),
+        ResourceKind.REDIRECTION_HOST: ("domain_names", "forward_domain_name", "meta"),
+        ResourceKind.DEAD_HOST: ("domain_names", "meta"),
+        ResourceKind.STREAM: ("incoming_port", "forward_host", "forward_port", "protocol", "meta"),
+        ResourceKind.USER: ("name", "email", "roles", "is_disabled", "meta"),
+        ResourceKind.SETTING: ("name", "value", "meta"),
+    }[existing.kind]
+    payload = {field: existing.raw[field] for field in fields if field in existing.raw}
+    if existing.kind == ResourceKind.PROXY_HOST:
+        defaults = {
+            "access_list_id": 0,
+            "certificate_id": 0,
+            "ssl_forced": 0,
+            "hsts_enabled": 0,
+            "hsts_subdomains": 0,
+            "http2_support": 0,
+            "block_exploits": 0,
+            "caching_enabled": 0,
+            "allow_websocket_upgrade": 0,
+            "advanced_config": "",
+            "enabled": 1,
+            "locations": [],
+        }
+        for field, default in defaults.items():
+            if payload.get(field) is None:
+                payload[field] = default
+    return payload