propt 0.1.0__tar.gz

propt-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: propt
+Version: 0.1.0
+Summary: Pre-action operational intelligence layer for infrastructure changes.
+Requires-Python: >=3.9
+Requires-Dist: kubernetes>=29.0.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: pyyaml>=6.0

propt-0.1.0/README.md

@@ -0,0 +1,183 @@
+# propt
+
+Pre-action operational intelligence for Kubernetes. `propt` wraps `kubectl`
+transparently — mutating commands (delete, scale, apply, patch, edit,
+replace, rollout) get a real, live-cluster impact check and a
+`Execute? [y/N]` prompt first. Read-only commands pass straight through
+with zero overhead.
+
+Built on real open-source signals, not a hardcoded risk table:
+- **kubernetes** Python client — live resource discovery
+- **networkx** — dependency graph from real `ownerReferences` and
+  label-selector matching (no invented relationships)
+- **Popeye** (derailed/popeye) — real, actively-maintained cluster
+  sanitizer, used as the operational risk knowledge source
+- **metrics-server** (optional) — real CPU usage, if installed
+
+Every decision is also logged as an auditable record to **Amazon S3**
+via `boto3` — see [AWS integration](#aws-integration-audit-logging) below.
+
+---
+
+## 1. Install (Windows 11 / PowerShell)
+
+### Python dependencies
+```powershell
+cd propt
+pip install -e .
+pip install pytest
+```
+
+### Popeye (Windows binary, no Go toolchain needed)
+1. Go to https://github.com/derailed/popeye/releases
+2. Download the latest `popeye_Windows_x86_64.tar.gz` (or `.zip` if offered)
+3. Extract `popeye.exe` somewhere on your PATH, e.g. `C:\tools\popeye.exe`
+4. Verify: `popeye version`
+
+If Popeye isn't found on PATH, `propt` still works — it just reports
+"popeye not available" in the Unknown/missing context section instead
+of fabricating findings.
+
+### Cluster
+Make sure `kubectl` points at your minikube cluster:
+```powershell
+minikube status
+kubectl get nodes
+```
+
+### metrics-server (optional, for real load data)
+```powershell
+minikube addons enable metrics-server
+```
+
+### AWS (for audit logging)
+`propt` writes every decision it makes to an S3 bucket as a timestamped
+JSON record, using your existing AWS CLI credentials (via `boto3` —
+no keys are stored or handled by propt itself).
+
+```powershell
+aws configure          # if not already set up
+aws s3 mb s3://<your-bucket-name> --region ap-south-1
+```
+Set the bucket name propt should use (defaults to `propt-audit-logs-sid-2026`
+if unset):
+```powershell
+$env:PROPT_AUDIT_BUCKET = "<your-bucket-name>"
+```
+If AWS isn't configured, `propt` still works — audit logging fails
+silently rather than blocking the actual kubectl operation.
+
+---
+
+## 2. Verify it's wired up
+```powershell
+pytest
+```
+These tests mock the cluster so they run without one — they document
+expected behavior (see `tests/test_engine.py`). The real proof is the
+live demo below.
+
+---
+
+## 3. Set up the demo scenario
+
+Deploy two contrasting workloads into your cluster:
+
+```powershell
+kubectl create deployment payment-api --image=nginx --replicas=3
+kubectl create deployment worker --image=nginx --replicas=10
+kubectl expose deployment payment-api --port=80 --name=payment-api
+
+# Simulate the understaffed condition
+kubectl scale deployment payment-api --replicas=3
+kubectl delete pod <one-of-the-payment-api-pods>   # bring it to 2/3 without propt, to set the stage
+```
+
+(Or just let `propt` itself do the second delete below — the first
+manual delete above is only to establish the "already short one
+replica" starting condition for the demo.)
+
+## 4. Run it
+
+```powershell
+propt kubectl delete pod <another-payment-api-pod-name>
+```
+Expect: **HIGH POTENTIAL IMPACT** — evidence should show available
+replicas below desired, plus any live Popeye findings for that
+deployment.
+
+```powershell
+propt kubectl delete pod <a-worker-pod-name>
+```
+Expect: **NONE / low impact** — same engine, different live state,
+different conclusion.
+
+```powershell
+propt kubectl get pods
+```
+Expect: passes straight through immediately, no analysis, no prompt.
+
+---
+
+## Architecture
+
+```
+kubectl command
+      |
+      v
+Common Change Model (propt/parser.py)
+      |
+      v
+Live Resource Graph (propt/k8s_graph.py) --- built from real ownerReferences + selectors
+      |
+      v
+Impact Inference Engine (propt/engine.py) --- combines graph + Popeye findings + metrics
+      |
+      v
+Explanation (propt/explain.py) --- printed to terminal, evidence-based, no opaque score
+      |
+      v
+Execute? [y/N] --- human decides
+      |
+      +---> Audit record written to Amazon S3 (propt/audit.py, via boto3)
+      |
+      v
+propt runs the ORIGINAL kubectl command as-is
+```
+
+
+## AWS integration: audit logging
+
+Every impact decision — the command, the target, the evidence, the
+consequence text, and whether the engineer chose to proceed — is
+written to Amazon S3 as a timestamped JSON object under
+`decisions/<timestamp>.json`. This gives a team a real, queryable
+history of infrastructure decisions and their reasoning, matching the
+"auditable, trust-first" principle from the original project spec
+(never silently change policy; keep evidence and outcomes reviewable).
+
+Example record:
+```json
+{
+  "timestamp": "2026-09-20T06:48:43.005997+00:00",
+  "command": "delete pod payment-api-85648675fb-6bj46",
+  "target": "pod/payment-api-85648675fb-6bj46",
+  "impact_level": "HIGH",
+  "evidence": ["deployment/payment-api: available replicas (5) below desired (6)"],
+  "consequence": "Potential reduction in capacity or degraded state propagating to: deployment/payment-api, replicaset/payment-api-85648675fb, service/payment-api.",
+  "executed": false
+}
+```
+
+Audit logging is intentionally fire-and-forget: if AWS credentials
+aren't configured or S3 is unreachable, `propt` degrades silently and
+the actual kubectl workflow is never blocked.
+
+## What this is not (by design, for the hackathon scope)
+- Not tied to a hardcoded command→risk table — risk comes from live
+  cluster state + Popeye's real findings.
+- Not a live "traffic" simulator — if metrics-server isn't installed,
+  it says so rather than inventing a number.
+- No LLM reasoning layer, no multi-provider adapters (Terraform etc.),
+  no auth/security hardening — explicitly out of scope for this build,
+  same as the original project spec.

propt-0.1.0/propt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

propt-0.1.0/propt/audit.py

@@ -0,0 +1,57 @@
+"""
+S3 audit logging.
+
+Every impact analysis propt performs gets written to S3 as a timestamped
+JSON record -- an auditable history of what was proposed, what evidence
+was found, and whether the engineer chose to proceed. This matches the
+"security/trust principles" in the original project spec: expose
+evidence, keep an auditable trail, never silently change policy.
+
+Uses boto3 (the AWS SDK) with the caller's existing AWS CLI credentials
+-- no keys are stored or handled by propt itself.
+"""
+import json
+import os
+import socket
+from datetime import datetime, timezone
+
+BUCKET = os.environ.get("PROPT_AUDIT_BUCKET", "propt-audit-logs-sid-2026")
+
+
+def log_decision(change, impact, executed: bool):
+    """
+    Fire-and-forget: failures here must NEVER block or crash the actual
+    kubectl operation. Audit logging is a bonus, not a dependency.
+    """
+    try:
+        import boto3
+    except ImportError:
+        return  # boto3 not installed -- skip silently, propt still works
+
+    try:
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "hostname": socket.gethostname(),
+            "command": " ".join(change.raw_args),
+            "target": change.target(),
+            "namespace": change.namespace,
+            "impact_level": impact.level,
+            "evidence": impact.evidence,
+            "context": impact.context,
+            "consequence": impact.consequence,
+            "unavailable_signals": impact.unavailable_signals,
+            "executed": executed,
+        }
+        key = f"decisions/{record['timestamp']}.json"
+        s3 = boto3.client("s3")
+        s3.put_object(
+            Bucket=BUCKET,
+            Key=key,
+            Body=json.dumps(record, indent=2).encode("utf-8"),
+            ContentType="application/json",
+        )
+    except Exception:
+        # Never let audit logging break the actual workflow -- this is
+        # the same "honest degradation" principle used for Popeye and
+        # metrics-server: missing signal, not a crash.
+        pass

propt-0.1.0/propt/cli.py

@@ -0,0 +1,60 @@
+"""
+propt CLI entrypoint.
+
+Usage:
+    propt kubectl delete pod payment-api-7d9f
+    propt kubectl get pods          <- passes straight through, no analysis
+
+The `propt` prefix is transparent: whatever command follows it runs
+exactly as normal (after an optional confirmation for mutating ops).
+"""
+import subprocess
+import sys
+
+from . import parser as change_parser
+from . import engine, explain, audit
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv:
+        print("Usage: propt <command> [args...]   e.g. propt kubectl delete pod foo")
+        sys.exit(1)
+
+    tool = argv[0]
+    rest = argv[1:]
+
+    if tool != "kubectl":
+        # Pass through untouched for non-kubectl commands (v1 scope is k8s-only)
+        _run(argv)
+        return
+
+    change = change_parser.parse_kubectl(rest)
+
+    if not change.is_mutating:
+        # Read-only command: don't slow the engineer down, just run it.
+        _run(argv)
+        return
+
+    impact = engine.analyze(change)
+    print(explain.format_impact(impact))
+    print()
+
+    answer = input("Execute? [y/N]: ").strip().lower()
+    executed = answer == "y"
+    audit.log_decision(change, impact, executed)
+
+    if executed:
+        _run(argv)
+    else:
+        print("Aborted. No changes made.")
+        sys.exit(0)
+
+
+def _run(argv):
+    result = subprocess.run(argv)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

propt-0.1.0/propt/engine.py

@@ -0,0 +1,107 @@
+"""
+Impact Inference Engine.
+
+Combines:
+  - the parsed Change
+  - the live dependency graph
+  - live context (replica counts, pod phase)
+  - real Popeye findings, filtered to the affected chain
+  - real metrics, if available
+
+...into a structured Impact result. No hardcoded per-command risk
+table -- risk comes from what's actually true in the cluster right now.
+"""
+from dataclasses import dataclass, field
+from typing import List
+
+from . import k8s_graph, popeye_runner, metrics
+
+
+@dataclass
+class Impact:
+    level: str  # "HIGH", "MEDIUM", "LOW", "NONE", "UNKNOWN"
+    target: str
+    affected: List[str] = field(default_factory=list)
+    evidence: List[str] = field(default_factory=list)
+    context: List[str] = field(default_factory=list)
+    consequence: str = ""
+    unavailable_signals: List[str] = field(default_factory=list)
+
+
+def analyze(change) -> Impact:
+    target_node = f"{change.resource_type}/{change.resource_name}" if change.resource_type and change.resource_name else None
+
+    if not change.is_mutating or not target_node:
+        return Impact(level="NONE", target=target_node or "unknown",
+                       consequence="Read-only or unrecognized operation; no impact analysis needed.")
+
+    try:
+        graph = k8s_graph.build_graph(change.namespace)
+    except Exception as e:
+        return Impact(level="UNKNOWN", target=target_node,
+                       consequence=f"Could not reach cluster: {e}",
+                       unavailable_signals=["cluster"])
+
+    if not graph.has_node(target_node):
+        return Impact(level="UNKNOWN", target=target_node,
+                       consequence="Resource not found in current cluster state.")
+
+    affected_nodes = k8s_graph.affected_chain(graph, target_node)
+    evidence = []      # signals that actually indicate risk -> drive the level
+    context = []       # informational signals -> shown, but never drive the level
+    unavailable = []
+
+    # 1. Live replica/context evidence -- a real risk signal
+    for node in [target_node] + affected_nodes:
+        ctx = k8s_graph.get_context(graph, node)
+        if ctx.get("kind") == "deployment":
+            desired = ctx.get("desired_replicas")
+            available = ctx.get("available_replicas")
+            if desired is not None and available is not None and available < desired:
+                evidence.append(
+                    f"{node}: available replicas ({available}) below desired ({desired})"
+                )
+
+    # 2. Popeye findings, filtered to affected chain -- Warning/Error are risk
+    #    signals; Info/OK-level notes are informational context only.
+    popeye_findings = popeye_runner.run_popeye(change.namespace)
+    if popeye_findings.get("_unavailable"):
+        unavailable.append(f"popeye ({popeye_findings.get('_reason')})")
+    else:
+        for node in [target_node] + affected_nodes:
+            for finding in popeye_findings.get(node, []):
+                line = f"Popeye [{finding['level']}] {node}: {finding['message']}"
+                if str(finding.get("level", "")).lower() in ("warning", "error", "critical"):
+                    evidence.append(line)
+                else:
+                    context.append(line)
+
+    # 3. Metrics: informational context only -- we don't have a resource
+    #    limit to compare against, so a raw usage number is context, not
+    #    a risk signal by itself.
+    if change.resource_type == "pod":
+        if metrics.metrics_available():
+            m = metrics.get_pod_metrics(change.namespace, change.resource_name)
+            if m.get("available"):
+                context.append(f"{target_node}: {m['cpu_millicores']}m CPU usage observed")
+        else:
+            unavailable.append("metrics-server")
+
+    level = "NONE"
+    consequence = "No significant impact detected from currently available signals."
+    if evidence:
+        level = "HIGH" if any("below desired" in e or "error" in e.lower() or "critical" in e.lower() for e in evidence) else "MEDIUM"
+        consequence = (
+            f"Potential reduction in capacity or degraded state propagating to: "
+            f"{', '.join(affected_nodes) if affected_nodes else target_node}."
+        )
+
+    return Impact(
+        level=level,
+        target=target_node,
+        affected=affected_nodes,
+        evidence=evidence,
+        context=context,
+        consequence=consequence,
+        unavailable_signals=unavailable,
+    )

propt-0.1.0/propt/explain.py

@@ -0,0 +1,29 @@
+from .engine import Impact
+
+
+def format_impact(impact: Impact) -> str:
+    lines = []
+    header = f"{impact.level} POTENTIAL IMPACT" if impact.level != "NONE" else "NO SIGNIFICANT IMPACT DETECTED"
+    lines.append(header)
+    lines.append("")
+    lines.append(f"Target: {impact.target}")
+    if impact.affected:
+        lines.append(f"Affected: {', '.join(impact.affected)}")
+    if impact.evidence:
+        lines.append("")
+        lines.append("Evidence:")
+        for e in impact.evidence:
+            lines.append(f" • {e}")
+    if impact.context:
+        lines.append("")
+        lines.append("Context:")
+        for c in impact.context:
+            lines.append(f" • {c}")
+    if impact.unavailable_signals:
+        lines.append("")
+        lines.append("Unknown / missing context:")
+        for u in impact.unavailable_signals:
+            lines.append(f" • {u} not available")
+    lines.append("")
+    lines.append(f"Potential consequence: {impact.consequence}")
+    return "\n".join(lines)

propt-0.1.0/propt/k8s_graph.py

@@ -0,0 +1,114 @@
+"""
+Live Kubernetes discovery + dependency graph.
+
+Builds a networkx.DiGraph of the current cluster state (in a given
+namespace) using real ownerReferences and label-selector matching --
+no hardcoded relationships. Edges point from a resource to the thing
+that depends on it (child -> parent-of-traffic direction), i.e.:
+
+    Pod --owned_by--> ReplicaSet --owned_by--> Deployment
+    Pod --selected_by--> Service --routed_by--> Ingress
+
+We traverse "upward" (toward things that would be affected) when
+analyzing impact of a change to a lower-level resource.
+"""
+import networkx as nx
+from kubernetes import client, config
+
+
+def load_cluster_client():
+    """Load kubeconfig (works with minikube's default context)."""
+    config.load_kube_config()
+    return client.CoreV1Api(), client.AppsV1Api(), client.NetworkingV1Api()
+
+
+def build_graph(namespace: str = "default") -> nx.DiGraph:
+    core, apps, net = load_cluster_client()
+    g = nx.DiGraph()
+
+    pods = core.list_namespaced_pod(namespace).items
+    rsets = apps.list_namespaced_replica_set(namespace).items
+    deployments = apps.list_namespaced_deployment(namespace).items
+    services = core.list_namespaced_service(namespace).items
+    try:
+        ingresses = net.list_namespaced_ingress(namespace).items
+    except Exception:
+        ingresses = []
+
+    # Nodes
+    for p in pods:
+        g.add_node(f"pod/{p.metadata.name}", kind="pod", raw=p)
+    for r in rsets:
+        g.add_node(f"replicaset/{r.metadata.name}", kind="replicaset", raw=r)
+    for d in deployments:
+        g.add_node(f"deployment/{d.metadata.name}", kind="deployment", raw=d)
+    for s in services:
+        g.add_node(f"service/{s.metadata.name}", kind="service", raw=s)
+    for i in ingresses:
+        g.add_node(f"ingress/{i.metadata.name}", kind="ingress", raw=i)
+
+    # Pod -> ReplicaSet (ownerReferences)
+    for p in pods:
+        for owner in (p.metadata.owner_references or []):
+            if owner.kind == "ReplicaSet":
+                node = f"replicaset/{owner.name}"
+                if g.has_node(node):
+                    g.add_edge(f"pod/{p.metadata.name}", node, relation="owned_by")
+
+    # ReplicaSet -> Deployment (ownerReferences)
+    for r in rsets:
+        for owner in (r.metadata.owner_references or []):
+            if owner.kind == "Deployment":
+                node = f"deployment/{owner.name}"
+                if g.has_node(node):
+                    g.add_edge(f"replicaset/{r.metadata.name}", node, relation="owned_by")
+
+    # Pod -> Service (label selector matching)
+    for s in services:
+        selector = s.spec.selector or {}
+        if not selector:
+            continue
+        for p in pods:
+            labels = p.metadata.labels or {}
+            if all(labels.get(k) == v for k, v in selector.items()):
+                g.add_edge(f"pod/{p.metadata.name}", f"service/{s.metadata.name}", relation="selected_by")
+
+    # Service -> Ingress (backend rules)
+    for i in ingresses:
+        rules = i.spec.rules or []
+        for rule in rules:
+            http = getattr(rule, "http", None)
+            if not http:
+                continue
+            for path in (http.paths or []):
+                backend = path.backend
+                svc = getattr(getattr(backend, "service", None), "name", None)
+                if svc and g.has_node(f"service/{svc}"):
+                    g.add_edge(f"service/{svc}", f"ingress/{i.metadata.name}", relation="routed_by")
+
+    return g
+
+
+def affected_chain(g: nx.DiGraph, target_node: str) -> list:
+    """Everything reachable upward (toward services/ingress) from target."""
+    if not g.has_node(target_node):
+        return []
+    return list(nx.descendants(g, target_node))
+
+
+def get_context(g: nx.DiGraph, node: str) -> dict:
+    """Pull live status fields for a node (replicas, ready state, etc.)."""
+    if not g.has_node(node):
+        return {}
+    kind = g.nodes[node]["kind"]
+    raw = g.nodes[node]["raw"]
+    ctx = {"kind": kind}
+    if raw is None:
+        return ctx
+    if kind == "deployment":
+        ctx["desired_replicas"] = raw.spec.replicas
+        ctx["available_replicas"] = raw.status.available_replicas or 0
+        ctx["ready_replicas"] = raw.status.ready_replicas or 0
+    if kind == "pod":
+        ctx["phase"] = raw.status.phase
+    return ctx

propt-0.1.0/propt/metrics.py

@@ -0,0 +1,49 @@
+"""
+Optional metrics-server integration.
+
+Pulls real CPU usage for pods via the Kubernetes metrics API, if
+metrics-server is installed in the cluster. If it isn't, we say so
+explicitly rather than inventing a "traffic" number -- consistent with
+the project's own principle of distinguishing observed facts from
+missing context.
+"""
+from kubernetes import client, config
+
+
+def metrics_available() -> bool:
+    try:
+        config.load_kube_config()
+        api = client.CustomObjectsApi()
+        api.list_cluster_custom_object("metrics.k8s.io", "v1beta1", "pods")
+        return True
+    except Exception:
+        return False
+
+
+def get_pod_metrics(namespace: str, pod_name: str) -> dict:
+    try:
+        config.load_kube_config()
+        api = client.CustomObjectsApi()
+        data = api.get_namespaced_custom_object(
+            "metrics.k8s.io", "v1beta1", namespace, "pods", pod_name
+        )
+        containers = data.get("containers", [])
+        cpu_total = 0
+        for c in containers:
+            cpu_str = c.get("usage", {}).get("cpu", "0")
+            cpu_total += _parse_cpu(cpu_str)
+        return {"cpu_millicores": cpu_total, "available": True}
+    except Exception as e:
+        return {"available": False, "reason": str(e)}
+
+
+def _parse_cpu(cpu_str: str) -> int:
+    """Convert k8s cpu strings ('100m', '1') to millicores."""
+    if cpu_str.endswith("n"):
+        return int(cpu_str[:-1]) // 1_000_000
+    if cpu_str.endswith("m"):
+        return int(cpu_str[:-1])
+    try:
+        return int(float(cpu_str) * 1000)
+    except ValueError:
+        return 0

propt-0.1.0/propt/parser.py

@@ -0,0 +1,116 @@
+"""
+Common Change Model + kubectl command parser.
+
+Turns a raw kubectl command (as a list of argv tokens, minus the
+leading `propt`) into a normalized Change object the rest of the
+engine can reason about.
+"""
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Operations we intercept for risk analysis. Anything else (get,
+# describe, logs, top, explain, ...) is treated as a read and passed
+# straight through without analysis.
+MUTATING_OPS = {"delete", "scale", "apply", "patch", "edit", "replace", "rollout"}
+
+# kubectl resource shorthands we normalize to a canonical singular form.
+RESOURCE_ALIASES = {
+    "po": "pod", "pods": "pod", "pod": "pod",
+    "deploy": "deployment", "deployments": "deployment", "deployment": "deployment",
+    "svc": "service", "services": "service", "service": "service",
+    "ing": "ingress", "ingresses": "ingress", "ingress": "ingress",
+    "rs": "replicaset", "replicasets": "replicaset", "replicaset": "replicaset",
+    "sts": "statefulset", "statefulsets": "statefulset", "statefulset": "statefulset",
+    "ds": "daemonset", "daemonsets": "daemonset", "daemonset": "daemonset",
+}
+
+
+@dataclass
+class Change:
+    actor: str
+    provider: str
+    operation: str
+    resource_type: Optional[str]
+    resource_name: Optional[str]
+    namespace: str
+    parameters: dict = field(default_factory=dict)
+    raw_args: list = field(default_factory=list)
+    is_mutating: bool = False
+
+    def target(self) -> str:
+        if self.resource_type and self.resource_name:
+            return f"{self.resource_type}/{self.resource_name}"
+        return self.resource_type or "unknown"
+
+
+def _extract_namespace(tokens: list) -> str:
+    for flag in ("-n", "--namespace"):
+        if flag in tokens:
+            idx = tokens.index(flag)
+            if idx + 1 < len(tokens):
+                return tokens[idx + 1]
+    return "default"
+
+
+def _extract_replicas(tokens: list) -> Optional[int]:
+    for tok in tokens:
+        if tok.startswith("--replicas"):
+            if "=" in tok:
+                try:
+                    return int(tok.split("=", 1)[1])
+                except ValueError:
+                    return None
+    return None
+
+
+def parse_kubectl(args: list) -> Change:
+    """
+    args: the kubectl invocation WITHOUT the leading 'kubectl' token,
+          e.g. ["delete", "pod", "payment-api-7d9f"]
+    """
+    if not args:
+        return Change(
+            actor="user", provider="kubernetes", operation="unknown",
+            resource_type=None, resource_name=None, namespace="default",
+            raw_args=args, is_mutating=False,
+        )
+
+    op = args[0].lower()
+    rest = [a for a in args[1:] if not a.startswith("-")]
+    # crude flag-value stripping: drop flag tokens and the value that follows
+    # a flag we recognize (namespace, replicas) so they don't get mistaken
+    # for resource type/name.
+    namespace = _extract_namespace(args)
+
+    resource_type = None
+    resource_name = None
+
+    if rest:
+        first = rest[0]
+        if "/" in first:
+            # e.g. `pod/payment-api-7d9f`
+            resource_type, resource_name = first.split("/", 1)
+        else:
+            resource_type = first
+            if len(rest) > 1:
+                resource_name = rest[1]
+
+    if resource_type:
+        resource_type = RESOURCE_ALIASES.get(resource_type.lower(), resource_type.lower())
+
+    parameters = {}
+    replicas = _extract_replicas(args)
+    if replicas is not None:
+        parameters["replicas"] = replicas
+
+    return Change(
+        actor="user",
+        provider="kubernetes",
+        operation=op,
+        resource_type=resource_type,
+        resource_name=resource_name,
+        namespace=namespace,
+        parameters=parameters,
+        raw_args=args,
+        is_mutating=op in MUTATING_OPS,
+    )

propt-0.1.0/propt/popeye_runner.py

@@ -0,0 +1,68 @@
+"""
+Popeye integration.
+
+Runs the open-source Popeye cluster sanitizer (https://github.com/derailed/popeye)
+against the live cluster and parses its JSON output into findings keyed
+by resource, so the impact engine can filter to just the resources in
+a change's dependency chain.
+
+Popeye must be installed and on PATH as `popeye`.
+"""
+import json
+import shutil
+import subprocess
+
+
+def popeye_available() -> bool:
+    return shutil.which("popeye") is not None
+
+
+def run_popeye(namespace: str = "default") -> dict:
+    """
+    Returns {"pod/name": [finding, ...], "deployment/name": [...], ...}
+    Falls back to an empty dict (with a note) if popeye isn't installed
+    or the scan fails -- we never fabricate findings.
+    """
+    if not popeye_available():
+        return {"_unavailable": True, "_reason": "popeye not found on PATH"}
+
+    try:
+        result = subprocess.run(
+            ["popeye", "-n", namespace, "-o", "json", "--force-exit-zero"],
+            capture_output=True, text=True, timeout=60,
+        )
+        data = json.loads(result.stdout)
+    except Exception as e:
+        return {"_unavailable": True, "_reason": str(e)}
+
+    findings = {}
+    try:
+        sanitizers = data.get("popeye", {}).get("sanitizers", [])
+        for section in sanitizers:
+            gvr = section.get("sanitizer", "")
+            for issue_group in section.get("issues", {}).items():
+                resource_name, issues = issue_group
+                # Popeye keys issues by "namespace/name"
+                short_name = resource_name.split("/")[-1]
+                kind = _gvr_to_kind(gvr)
+                key = f"{kind}/{short_name}"
+                findings.setdefault(key, [])
+                for issue in issues:
+                    findings[key].append({
+                        "level": issue.get("level"),
+                        "message": issue.get("message"),
+                    })
+    except Exception:
+        pass
+
+    return findings
+
+
+def _gvr_to_kind(sanitizer_name: str) -> str:
+    mapping = {
+        "pod": "pod", "po": "pod",
+        "deployment": "deployment", "dp": "deployment",
+        "service": "service", "svc": "service",
+        "replicaset": "replicaset", "rs": "replicaset",
+    }
+    return mapping.get(sanitizer_name.lower(), sanitizer_name.lower())

propt-0.1.0/propt.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: propt
+Version: 0.1.0
+Summary: Pre-action operational intelligence layer for infrastructure changes.
+Requires-Python: >=3.9
+Requires-Dist: kubernetes>=29.0.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: pyyaml>=6.0

propt-0.1.0/propt.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+propt/__init__.py
+propt/audit.py
+propt/cli.py
+propt/engine.py
+propt/explain.py
+propt/k8s_graph.py
+propt/metrics.py
+propt/parser.py
+propt/popeye_runner.py
+propt.egg-info/PKG-INFO
+propt.egg-info/SOURCES.txt
+propt.egg-info/dependency_links.txt
+propt.egg-info/entry_points.txt
+propt.egg-info/requires.txt
+propt.egg-info/top_level.txt
+tests/test_audit.py
+tests/test_engine.py
+tests/test_parser.py

propt-0.1.0/propt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

propt-0.1.0/propt.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+propt = propt.cli:main

propt-0.1.0/propt.egg-info/requires.txt

@@ -0,0 +1,5 @@
+kubernetes>=29.0.0
+networkx>=3.0
+click>=8.0
+requests>=2.28
+pyyaml>=6.0

propt-0.1.0/propt.egg-info/top_level.txt

@@ -0,0 +1 @@
+propt

propt-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "propt"
+version = "0.1.0"
+description = "Pre-action operational intelligence layer for infrastructure changes."
+requires-python = ">=3.9"
+dependencies = [
+    "kubernetes>=29.0.0",
+    "networkx>=3.0",
+    "click>=8.0",
+    "requests>=2.28",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+propt = "propt.cli:main"
+
+[tool.setuptools]
+packages = ["propt"]

propt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

propt-0.1.0/tests/test_audit.py

@@ -0,0 +1,30 @@
+from propt import audit
+from propt.parser import parse_kubectl
+from propt.engine import Impact
+
+
+def test_log_decision_never_raises_on_bad_credentials(monkeypatch):
+    """Audit logging must never crash the CLI, even if AWS is
+    unreachable, unconfigured, or boto3 throws."""
+    change = parse_kubectl(["delete", "pod", "payment-api-A"])
+    impact = Impact(level="HIGH", target="pod/payment-api-A", evidence=["test"])
+
+    # Should not raise even with no real AWS credentials configured
+    # in the test environment.
+    audit.log_decision(change, impact, executed=False)
+
+
+def test_log_decision_handles_missing_boto3(monkeypatch):
+    import builtins
+    real_import = builtins.__import__
+
+    def fake_import(name, *args, **kwargs):
+        if name == "boto3":
+            raise ImportError("no boto3")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", fake_import)
+
+    change = parse_kubectl(["delete", "pod", "payment-api-A"])
+    impact = Impact(level="HIGH", target="pod/payment-api-A")
+    audit.log_decision(change, impact, executed=False)  # must not raisepytest

propt-0.1.0/tests/test_engine.py

@@ -0,0 +1,71 @@
+"""
+These tests mock the cluster-facing layer (k8s_graph, popeye_runner,
+metrics) so the inference logic itself can be verified without a
+live cluster -- useful for CI, and for anyone reading this as
+documentation of expected behavior.
+
+Run the two demo scenarios against a REAL cluster with:
+    propt kubectl delete pod payment-api-A   (expect HIGH)
+    propt kubectl delete pod worker-A        (expect NONE/LOW)
+"""
+import networkx as nx
+import pytest
+
+from propt import engine
+from propt.parser import parse_kubectl
+
+
+class FakeDeployment:
+    def __init__(self, desired, available):
+        self.spec = type("Spec", (), {"replicas": desired})()
+        self.status = type("Status", (), {"available_replicas": available, "ready_replicas": available})()
+
+
+def make_fake_graph(desired, available):
+    g = nx.DiGraph()
+    g.add_node("pod/payment-api-A", kind="pod", raw=None)
+    g.add_node("replicaset/payment-api-rs", kind="replicaset", raw=None)
+    g.add_node("deployment/payment-api", kind="deployment", raw=FakeDeployment(desired, available))
+    g.add_node("service/payment-api", kind="service", raw=None)
+    g.add_edge("pod/payment-api-A", "replicaset/payment-api-rs", relation="owned_by")
+    g.add_edge("replicaset/payment-api-rs", "deployment/payment-api", relation="owned_by")
+    g.add_edge("pod/payment-api-A", "service/payment-api", relation="selected_by")
+    return g
+
+
+def test_high_impact_when_understaffed(monkeypatch):
+    monkeypatch.setattr(engine.k8s_graph, "build_graph", lambda ns: make_fake_graph(3, 2))
+    monkeypatch.setattr(engine.popeye_runner, "run_popeye", lambda ns: {"_unavailable": True, "_reason": "test"})
+    monkeypatch.setattr(engine.metrics, "metrics_available", lambda: False)
+
+    change = parse_kubectl(["delete", "pod", "payment-api-A"])
+    impact = engine.analyze(change)
+
+    assert impact.level == "HIGH"
+    assert any("below desired" in e for e in impact.evidence)
+    assert "deployment/payment-api" in impact.affected
+
+
+def test_no_impact_when_fully_staffed(monkeypatch):
+    monkeypatch.setattr(engine.k8s_graph, "build_graph", lambda ns: make_fake_graph(3, 3))
+    monkeypatch.setattr(engine.popeye_runner, "run_popeye", lambda ns: {"_unavailable": True, "_reason": "test"})
+    monkeypatch.setattr(engine.metrics, "metrics_available", lambda: False)
+
+    change = parse_kubectl(["delete", "pod", "payment-api-A"])
+    impact = engine.analyze(change)
+
+    assert impact.level == "NONE"
+
+
+def test_read_only_command_skips_analysis():
+    change = parse_kubectl(["get", "pods"])
+    impact = engine.analyze(change)
+    assert impact.level == "NONE"
+    assert "Read-only" in impact.consequence
+
+
+def test_unknown_resource_returns_unknown(monkeypatch):
+    monkeypatch.setattr(engine.k8s_graph, "build_graph", lambda ns: nx.DiGraph())
+    change = parse_kubectl(["delete", "pod", "does-not-exist"])
+    impact = engine.analyze(change)
+    assert impact.level == "UNKNOWN"

propt-0.1.0/tests/test_parser.py

@@ -0,0 +1,37 @@
+from propt.parser import parse_kubectl
+
+
+def test_delete_pod():
+    c = parse_kubectl(["delete", "pod", "payment-api-7d9f"])
+    assert c.operation == "delete"
+    assert c.resource_type == "pod"
+    assert c.resource_name == "payment-api-7d9f"
+    assert c.is_mutating is True
+    assert c.target() == "pod/payment-api-7d9f"
+
+
+def test_get_pods_is_not_mutating():
+    c = parse_kubectl(["get", "pods"])
+    assert c.is_mutating is False
+
+
+def test_resource_alias_normalization():
+    c = parse_kubectl(["delete", "po", "worker-A"])
+    assert c.resource_type == "pod"
+
+
+def test_slash_syntax():
+    c = parse_kubectl(["delete", "pod/payment-api-7d9f"])
+    assert c.resource_type == "pod"
+    assert c.resource_name == "payment-api-7d9f"
+
+
+def test_namespace_flag():
+    c = parse_kubectl(["delete", "pod", "foo", "-n", "prod"])
+    assert c.namespace == "prod"
+
+
+def test_scale_replicas_param():
+    c = parse_kubectl(["scale", "deployment", "worker", "--replicas=1"])
+    assert c.parameters.get("replicas") == 1
+    assert c.is_mutating is True