npmctl 0.3.1__py3-none-any.whl

npmctl/__init__.py

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

npmctl/__main__.py

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

npmctl/adoption.py

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

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

npmctl/cli.py

@@ -0,0 +1,407 @@
+"""Command-line interface for npmctl."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+from typing import Any, Sequence
+
+from npmctl import __version__
+from npmctl.apply import ApplyEngine
+from npmctl.client import NpmClient
+from npmctl.config import apply_config, load_config
+from npmctl.diagnostics import doctor_report, environment_report
+from npmctl.errors import ApiError, CapabilityError, ConflictError, MigrationError, NpmctlError, ValidationError
+from npmctl.loader import load_desired_state
+from npmctl.migrations import migrate_path
+from npmctl.operational import (
+    compliance_artifacts,
+    drift_report,
+    rollback_plan,
+    transaction_report,
+    validate_compliance_gate,
+    validate_plan_output,
+    write_json,
+    write_state_backup,
+)
+from npmctl.output import format_plan_text, write_error, write_output
+from npmctl.plugins import PluginRegistry
+from npmctl.planner import PlannerOptions, compute_plan
+from npmctl.schema import Capabilities, load_openapi_schema
+
+EXIT_OK = 0
+EXIT_CONFLICT = 1
+EXIT_USAGE_OR_VALIDATION = 2
+EXIT_API = 3
+EXIT_CAPABILITY = 4
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="npmctl",
+        description="Owner-scoped plan/apply/adopt controller for Nginx Proxy Manager resources.",
+    )
+    parser.add_argument("--version", action="version", version=f"npmctl {__version__}")
+    parser.add_argument("--config", help="TOML config file with [npmctl] settings")
+    parser.add_argument("--base-url", default=os.getenv("NPM_BASE_URL"), help="NPM API URL, e.g. http://host:81/api")
+    parser.add_argument("--identity", default=os.getenv("NPM_IDENTITY"), help="NPM login identity")
+    parser.add_argument("--secret", default=os.getenv("NPM_SECRET"), help="NPM login secret")
+    parser.add_argument(
+        "--timeout",
+        default=float(os.getenv("NPM_TIMEOUT_S")) if os.getenv("NPM_TIMEOUT_S") else None,
+        type=float,
+        help="HTTP timeout seconds",
+    )
+    parser.add_argument("--output", choices=("text", "json"), default="text", help="Output format")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    validate = sub.add_parser("validate", help="Validate desired state")
+    validate.add_argument("desired_state")
+
+    migrate = sub.add_parser("migrate", help="Migrate desired-state schema")
+    migrate.add_argument("path")
+    migrate.add_argument("--write", action="store_true", help="Write migrated files")
+    migrate.add_argument("--check", action="store_true", help="Fail if migration is needed")
+
+    health = sub.add_parser("health", help="Call NPM API health endpoint")
+    health.set_defaults(needs_api=True)
+
+    doctor = sub.add_parser("doctor", help="Diagnose config, API reachability, and capabilities")
+    doctor.set_defaults(needs_api=False)
+
+    env = sub.add_parser("env", help="Show redacted npmctl environment diagnostics")
+    env.set_defaults(needs_api=False)
+
+    version = sub.add_parser("version", help="Show machine-readable version metadata")
+    version.add_argument("--json", action="store_true", help="Emit JSON version metadata")
+
+    completion = sub.add_parser("completion", help="Generate shell completion script")
+    completion.add_argument("shell", choices=("bash", "powershell", "zsh"))
+
+    schema = sub.add_parser("schema", help="OpenAPI schema commands")
+    schema_sub = schema.add_subparsers(dest="schema_command", required=True)
+    fetch = schema_sub.add_parser("fetch", help="Fetch /schema from NPM")
+    fetch.add_argument("--write", help="Write schema JSON to path")
+    fetch.set_defaults(needs_api=True)
+    caps = schema_sub.add_parser("capabilities", help="Show detected endpoint capabilities")
+    caps.add_argument("--schema", help="Schema JSON path; fetches from NPM when omitted")
+    caps.set_defaults(needs_api_optional_schema=True)
+    check = schema_sub.add_parser("check", help="Validate required endpoint capabilities")
+    check.add_argument("--schema", help="Schema JSON path; fetches from NPM when omitted")
+    check.set_defaults(needs_api_optional_schema=True)
+
+    plan = sub.add_parser("plan", help="Compute owner-scoped CRUD plan")
+    _add_reconcile_args(plan)
+    plan.add_argument("--validate-output", action="store_true", help="Validate plan output against npmctl schema")
+    plan.set_defaults(needs_api=True)
+
+    apply = sub.add_parser("apply", help="Apply a clean owner-scoped CRUD plan")
+    _add_reconcile_args(apply)
+    apply.add_argument("--dry-run", action="store_true", help="Plan but do not mutate NPM")
+    apply.add_argument("--backup-dir", help="Write remote state backup before apply")
+    apply.add_argument("--report", help="Write structured apply transaction report")
+    apply.add_argument("--rollback-plan", help="Write best-effort rollback plan")
+    apply.add_argument("--audit-log", dest="audit_log_path", help="Write local audit log JSON for this apply")
+    apply.add_argument("--validate-output", action="store_true", help="Validate plan output against npmctl schema")
+    apply.set_defaults(needs_api=True)
+
+    adopt = sub.add_parser("adopt", help="Adopt unmanaged matching resources by writing metadata")
+    _add_reconcile_args(adopt)
+    adopt.add_argument("--allow-field-drift", action="store_true", help="Allow adopting resources whose fields differ")
+    adopt.add_argument("--force", action="store_true", help="Alias for --allow-field-drift with explicit intent")
+    adopt.add_argument("--validate-output", action="store_true", help="Validate plan output against npmctl schema")
+    adopt.set_defaults(needs_api=True, adopt=True)
+
+    drift = sub.add_parser("drift", help="Report remote drift without applying mutations")
+    _add_reconcile_args(drift)
+    drift.set_defaults(needs_api=True)
+
+    audit = sub.add_parser("audit-log", help="Read NPM audit log entries")
+    audit.add_argument("--since", help="Optional since filter passed to NPM")
+    audit.set_defaults(needs_api=True)
+
+    compliance = sub.add_parser("compliance", help="Compliance artifact commands")
+    compliance_sub = compliance.add_subparsers(dest="compliance_command", required=True)
+    artifacts = compliance_sub.add_parser(
+        "artifacts", help="Generate SBOM, provenance, scan, and release-gate artifacts"
+    )
+    artifacts.add_argument("--output-dir", required=True)
+    artifacts.add_argument("--source-dir", default=".")
+    artifacts.add_argument("--dist-dir")
+    gate = compliance_sub.add_parser("gate", help="Validate generated compliance artifacts")
+    gate.add_argument("--artifact-dir", required=True)
+
+    plugins = sub.add_parser("plugins", help="Inspect runtime plugin discovery")
+    plugins_sub = plugins.add_subparsers(dest="plugins_command", required=True)
+    plugins_sub.add_parser("list", help="List discovered plugin providers")
+
+    return parser
+
+
+def _add_reconcile_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("desired_state")
+    parser.add_argument("--owner", help="Limit operation to one owner scope")
+    parser.add_argument("--no-updates", action="store_true", help="Conflict on owned drift instead of updating")
+    parser.add_argument("--prune-owned", action="store_true", help="Delete owned resources absent from desired state")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        apply_config(args, load_config(getattr(args, "config", None)))
+        return _dispatch(args, parser)
+    except ValidationError as exc:
+        write_error(args.output, "validation_error", str(exc))
+        return EXIT_USAGE_OR_VALIDATION
+    except MigrationError as exc:
+        write_error(args.output, "migration_error", str(exc))
+        return EXIT_USAGE_OR_VALIDATION
+    except ConflictError as exc:
+        write_error(args.output, "conflict_error", str(exc))
+        return EXIT_CONFLICT
+    except CapabilityError as exc:
+        write_error(args.output, "capability_error", _redact_cli_message(str(exc), args))
+        return EXIT_CAPABILITY
+    except ApiError as exc:
+        write_error(args.output, "api_error", _redact_cli_message(str(exc), args))
+        return EXIT_API
+    except NpmctlError as exc:
+        write_error(args.output, "npmctl_error", str(exc))
+        return EXIT_USAGE_OR_VALIDATION
+
+
+def _dispatch(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
+    if args.command == "validate":
+        desired = load_desired_state(args.desired_state)
+        payload = _desired_summary(desired)
+        write_output(args.output, payload, _format_validate_text(payload))
+        return EXIT_OK
+
+    if args.command == "env":
+        payload = {"ok": True, "environment": environment_report(dict(os.environ))}
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+
+    if args.command == "version":
+        payload = {"package": "npmctl", "version": __version__, "schema_version": 1, "api_profile": "npm-2.10.4"}
+        text = json.dumps(payload, indent=2, sort_keys=True) if args.json or args.output == "json" else __version__
+        write_output("json" if args.json else args.output, payload, text)
+        return EXIT_OK
+
+    if args.command == "completion":
+        payload = {"ok": True, "shell": args.shell}
+        write_output(args.output, payload, _completion_script(args.shell))
+        return EXIT_OK
+
+    if args.command == "compliance":
+        if args.compliance_command == "gate":
+            payload = validate_compliance_gate(args.artifact_dir)
+            write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+            return EXIT_OK if payload["ok"] else EXIT_USAGE_OR_VALIDATION
+        paths = compliance_artifacts(
+            args.output_dir,
+            package_name="npmctl",
+            version=__version__,
+            source_dir=args.source_dir,
+            dist_dir=args.dist_dir,
+        )
+        payload = {"ok": True, "artifacts": [str(path) for path in paths]}
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+
+    if args.command == "plugins":
+        registry = PluginRegistry.discover()
+        payload = {"ok": True, "plugins": registry.to_dict()}
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+
+    if args.command == "migrate":
+        if args.write and args.check:
+            raise ValidationError("migrate --write and --check cannot be combined")
+        results = migrate_path(args.path, write=args.write)
+        changed = [result for result in results if result.changed]
+        payload = {
+            "ok": not bool(changed and args.check),
+            "changed": len(changed),
+            "files": [str(result.path) for result in changed],
+            "written": bool(args.write),
+        }
+        write_output(args.output, payload, f"migrations needed: {len(changed)}\nwritten: {str(args.write).lower()}")
+        return EXIT_USAGE_OR_VALIDATION if changed and args.check else EXIT_OK
+
+    client: NpmClient | None = None
+    if getattr(args, "needs_api", False) or (
+        getattr(args, "needs_api_optional_schema", False) and not getattr(args, "schema", None)
+    ):
+        _require_api_args(args, parser)
+        client = NpmClient(
+            base_url=args.base_url, identity=args.identity, secret=args.secret, timeout_s=args.timeout or 15.0
+        )
+
+    if args.command == "doctor":
+        health = None
+        capabilities = None
+        if args.base_url and args.identity and args.secret:
+            client = NpmClient(
+                base_url=args.base_url,
+                identity=args.identity,
+                secret=args.secret,
+                timeout_s=args.timeout or 15.0,
+            )
+            health = client.health()
+            capabilities = client.capabilities().to_dict()
+        payload = doctor_report(args=args, health=health, capabilities=capabilities)
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK if payload["ok"] else EXIT_USAGE_OR_VALIDATION
+
+    if args.command == "health":
+        assert client is not None
+        payload = client.health()
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+
+    if args.command == "schema":
+        return _schema_command(args, client)
+
+    if args.command == "audit-log":
+        assert client is not None
+        payload = {"ok": True, "entries": client.audit_log(since=args.since)}
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+
+    if args.command in {"plan", "apply", "adopt", "drift"}:
+        assert client is not None
+        desired = load_desired_state(args.desired_state)
+        capabilities = client.capabilities()
+        existing = client.existing_state(
+            include_certificates=capabilities.certificates.list,
+            include_access_lists=capabilities.access_lists.list,
+        )
+        options = PlannerOptions(
+            owner=args.owner,
+            allow_updates=not args.no_updates,
+            prune_owned=args.prune_owned,
+            adopt=args.command == "adopt",
+            strict_adopt=not (getattr(args, "allow_field_drift", False) or getattr(args, "force", False)),
+            allow_field_drift=getattr(args, "allow_field_drift", False) or getattr(args, "force", False),
+        )
+        plan = compute_plan(desired=desired, existing=existing, capabilities=capabilities, options=options)
+        if args.command == "drift":
+            payload = drift_report(plan)
+            write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+            return EXIT_OK if payload["ok"] else EXIT_CONFLICT
+        plan_payload = plan.to_dict()
+        if getattr(args, "validate_output", False):
+            try:
+                validate_plan_output(plan_payload)
+            except ValueError as exc:
+                raise ValidationError(str(exc)) from exc
+        if args.command == "plan" or getattr(args, "dry_run", False):
+            write_output(args.output, plan_payload, format_plan_text(plan))
+            return EXIT_OK if plan.ok else EXIT_CONFLICT
+        if not plan.ok:
+            write_output(args.output, plan_payload, format_plan_text(plan))
+            return EXIT_CONFLICT
+        if getattr(args, "backup_dir", None):
+            write_state_backup(args.backup_dir, existing)
+        result = ApplyEngine(client=client, capabilities=capabilities).apply(plan)
+        payload = transaction_report(plan, result)
+        if getattr(args, "report", None):
+            write_json(args.report, payload)
+        if getattr(args, "rollback_plan", None):
+            write_json(args.rollback_plan, rollback_plan(plan))
+        if getattr(args, "audit_log_path", None):
+            write_json(args.audit_log_path, {"ok": True, "operation": "apply", "summary": payload["summary"]})
+        text = format_plan_text(plan) + f"\napplied: true\nmutations: {len(result.mutations)}"
+        write_output(args.output, payload, text)
+        return EXIT_OK
+
+    parser.error(f"unsupported command: {args.command}")  # pragma: no cover - argparse exits
+    return EXIT_USAGE_OR_VALIDATION  # pragma: no cover
+
+
+def _schema_command(args: argparse.Namespace, client: NpmClient | None) -> int:
+    if args.schema_command == "fetch":
+        assert client is not None
+        payload = client.openapi_schema()
+        if args.write:
+            Path(args.write).write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK
+    schema_doc = load_openapi_schema(args.schema) if args.schema else client.openapi_schema()  # type: ignore[union-attr]
+    capabilities = Capabilities.from_openapi(schema_doc)
+    payload = capabilities.to_dict()
+    if args.schema_command == "check":
+        required = [
+            capabilities.proxy_hosts.list,
+            capabilities.proxy_hosts.create,
+            capabilities.proxy_hosts.update,
+            capabilities.proxy_hosts.delete,
+        ]
+        payload["ok"] = all(required)
+        write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_OK if payload["ok"] else EXIT_CAPABILITY
+    write_output(args.output, payload, json.dumps(payload, indent=2, sort_keys=True))
+    return EXIT_OK
+
+
+def _require_api_args(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    if not (args.base_url and args.identity and args.secret):
+        parser.error("--base-url, --identity, and --secret are required, or set NPM_BASE_URL/NPM_IDENTITY/NPM_SECRET")
+
+
+def _desired_summary(desired: Any) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "schemaVersion": desired.schema_version,
+        "proxy_hosts": len(desired.proxy_hosts),
+        "certificates": len(desired.certificates),
+        "access_lists": len(desired.access_lists),
+        "redirection_hosts": len(desired.redirection_hosts),
+        "dead_hosts": len(desired.dead_hosts),
+        "streams": len(desired.streams),
+        "users": len(desired.users),
+        "settings": len(desired.settings),
+        "source_files": list(desired.source_files),
+    }
+
+
+def _format_validate_text(payload: dict[str, Any]) -> str:
+    return (
+        "desired state valid\n"
+        f"proxy hosts: {payload['proxy_hosts']}\n"
+        f"certificates: {payload['certificates']}\n"
+        f"access lists: {payload['access_lists']}\n"
+        f"redirection hosts: {payload['redirection_hosts']}\n"
+        f"dead hosts: {payload['dead_hosts']}\n"
+        f"streams: {payload['streams']}\n"
+        f"users: {payload['users']}\n"
+        f"settings: {payload['settings']}"
+    )
+
+
+def _redact_cli_message(message: str, args: argparse.Namespace) -> str:
+    redacted = message
+    for value in (getattr(args, "identity", None), getattr(args, "secret", None)):
+        if value:
+            redacted = redacted.replace(str(value), "***")
+    return redacted
+
+
+def _completion_script(shell: str) -> str:
+    commands = "validate migrate health doctor env version completion schema plan apply adopt drift audit-log compliance plugins"
+    if shell == "powershell":
+        return f"Register-ArgumentCompleter -Native -CommandName npmctl -ScriptBlock {{ param($wordToComplete) '{commands}'.Split(' ') | Where-Object {{ $_ -like \"$wordToComplete*\" }} }}\n"
+    if shell == "zsh":
+        return f"#compdef npmctl\n_arguments '1:command:({commands})'\n"
+    return f'complete -W "{commands}" npmctl\n'
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

npmctl/client/__init__.py

@@ -0,0 +1,5 @@
+"""NPM API client package."""
+
+from npmctl.client.base import NpmClient
+
+__all__ = ["NpmClient"]

npmctl/client/access_lists.py

@@ -0,0 +1,10 @@
+"""Access-list client helpers."""
+
+from npmctl.client.base import NpmClient
+from npmctl.models import ResourceKind
+
+
+def list_access_lists(client: NpmClient):
+    """List access lists."""
+
+    return client.list_resource(ResourceKind.ACCESS_LIST)