platformforge 0.1.0__py3-none-any.whl

platformforge/optimize/scan.py

@@ -0,0 +1,196 @@
+"""Cycle 5 §204–205 — opportunity generation from analytics signals.
+
+`scan_fleet(data, graph)` feeds every analytics output into the
+OptimizationEngine as evidence-cited opportunities. Uncertainty is
+honest: a signal becomes `medium` only when its underlying measure
+was *observed* with enough support; otherwise it stays `high` and
+is suppressed from recommendations — visible in
+`portfolio().suppressed`, never silently dropped.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.analytics.capacity import (
+    CapacityDimension,
+    CapacitySnapshot,
+    capacity_risk,
+)
+from platformforge.analytics.finops_v4 import (
+    cost_hierarchy,
+    idle_resources,
+    rightsizing,
+)
+from platformforge.analytics.goldenpath import golden_path_analytics
+from platformforge.analytics.opsanalytics import (
+    operation_hotspots,
+    remediation_recurrence,
+)
+from platformforge.analytics.policyintel import (
+    false_positive_candidates,
+    policy_metrics,
+)
+from platformforge.analytics.reliability import build_profile, fleet_hotspots
+from platformforge.fleet.query import FLEET_QUESTIONS, fleet_query
+from platformforge.optimize.engine import OptimizationEngine
+from platformforge.optimize.models import OptimizationOpportunity
+
+_RISK_QUESTIONS = {
+    "public-services": "security",
+    "wildcard-iam": "security",
+    "unsupported-k8s": "standardization",
+    "unowned": "standardization",
+    "no-slo": "reliability",
+    "outside-golden-path": "platform-product",
+    "idle-high-cost": "cost",
+    "cross-env-deps": "reliability",
+}
+
+
+def capacity_snapshots(capacity: dict[str, Any]) -> dict[str, CapacitySnapshot]:
+    """capacity.yaml `members:` → member_id → CapacitySnapshot."""
+    return {
+        m["member_id"]: CapacitySnapshot(
+            member_id=m["member_id"],
+            dimensions=[CapacityDimension(
+                d["name"], d.get("used"), d.get("capacity"),
+                d.get("source", "observed"))
+                for d in m.get("dimensions", [])])
+        for m in capacity.get("members", [])}
+
+
+def scan_fleet(data: dict[str, Any], graph=None,
+               engine: OptimizationEngine | None = None,
+               coverage: float | None = None) -> OptimizationEngine:
+    """Generate opportunities from a loaded fleet bundle (same file
+    shapes as lab fixtures — see `fleet.loader.FLEET_FILES`)."""
+    eng = engine or OptimizationEngine()
+    n = [0]
+
+    def add(type_: str, scope: dict, evidence: list, uncertainty: str,
+            savings=None, unit="", refs=None) -> None:
+        n[0] += 1
+        eng.add_opportunity(OptimizationOpportunity(
+            opportunity_id=f"scan-{n[0]}",
+            type=type_, scope=scope, evidence=evidence,
+            pattern_refs=refs or [], estimated_savings=savings,
+            savings_unit=unit, uncertainty=uncertainty,
+            coverage=coverage))
+
+    costs = data.get("costs") or {}
+
+    # --- cost signals (§100–101: idle ≠ deletable — always review) ---
+    raw_res = {r.get("id"): r for r in costs.get("resources", [])}
+    for r in idle_resources(costs.get("resources", [])):
+        res = raw_res.get(r["resource"], {})
+        add("cost", {"resource": str(r["resource"])},
+            [f"idle:{r['resource']}",
+             *[f"{k}:{v}" for k, v in r["evidence"].items()]],
+            "medium" if len(r["evidence"]) >= 3 else "high",
+            savings=res.get("cost_monthly"), unit="cost_monthly")
+    for w in costs.get("workloads", []):
+        rs = rightsizing(w)
+        if rs:
+            add("cost", {"workload": str(rs["workload"])},
+                [f"rightsizing:{rs['workload']}:{rs['type']}",
+                 *[f"{k}:{v}" for k, v in rs["evidence"].items()]],
+                "medium" if rs["signals_used"] >= 3 else "high",
+                savings=w.get("cost_monthly"), unit="cost_monthly")
+    tree = cost_hierarchy(costs.get("allocations", []))
+    if tree["unallocated"]:
+        add("cost", {"fleet": "unallocated"},
+            [f"unallocated:{tree['unallocated']}",
+             f"unallocated_ratio:{tree['unallocated_ratio']}"],
+            "medium", savings=tree["unallocated"], unit="cost_monthly",
+            refs=["cost allocation coverage gap"])
+    by_svc = tree["by_level"].get("service", {})
+    if by_svc:
+        svc, d = max(by_svc.items(), key=lambda kv: kv[1]["amount"])
+        add("cost", {"service": svc},
+            [f"top-cost:{svc}={d['amount']}",
+             f"alloc-confidence:{d['confidence']}"], "medium")
+
+    # --- capacity ------------------------------------------------------
+    cap = data.get("capacity") or {}
+    meta = {m["member_id"]: m for m in cap.get("members", [])}
+    for mid, snap in capacity_snapshots(cap).items():
+        m = meta.get(mid, {})
+        risk = capacity_risk(
+            snap, criticality=m.get("criticality"),
+            autoscaling=m.get("autoscaling"),
+            failure_domains=m.get("failure_domains"))
+        if risk["risk"] == "high":
+            add("capacity", {"member": mid},
+                [f"saturated:{','.join(risk['factors']['saturated_dimensions'])}",
+                 f"criticality:{risk['factors']['criticality']}",
+                 f"failure_domains:{risk['factors']['failure_domains']}"],
+                "medium" if risk["confidence"] == "medium" else "high")
+
+    # --- reliability / operations --------------------------------------
+    ev = data.get("events") or {}
+    incidents = ev.get("incident", [])
+    deployments = ev.get("deployment", [])
+    rollbacks = ev.get("rollback", [])
+    services = sorted({i.get("service") for i in incidents
+                       if i.get("service")})
+    profiles = [build_profile(
+        s,
+        [i for i in incidents if i.get("service") == s],
+        [c for c in deployments if c.get("service") == s],
+        [r for r in rollbacks if r.get("service") == s])
+        for s in services]
+    for h in fleet_hotspots(profiles):
+        add("reliability", {"service": h["service_id"]},
+            [f"hotspot:{h['service_id']}",
+             *[f"ev:{e}" for e in h["evidence"]]],
+            "medium" if h["sample_size"] >= 5 else "high")
+    for h in operation_hotspots(ev.get("operation", [])):
+        add("operational",
+            {"service": h["service"], "action": h["action"]},
+            [f"repeated-operation:{h['action']}x{h['count']}"],
+            "medium" if h["count"] >= 4 else "high")
+    for r in remediation_recurrence(ev.get("remediation", [])):
+        add("operational", {"finding": r["finding"]},
+            [f"recurrence:{r['finding']}x{r['recurrences']}",
+             f"path:{r['suggested_path']}",
+             *[f"ref:{e}" for e in r["evidence"]]],
+            "medium" if r["recurrences"] >= 3 else "high")
+
+    # --- policies (review-only; never auto-applied) ----------------------
+    pol = data.get("policies") or {}
+    m = policy_metrics(pol.get("decisions", []),
+                       exceptions=pol.get("exceptions", []),
+                       overrides=pol.get("overrides", []))
+    for fp in false_positive_candidates(m, pol.get("outcomes", {})):
+        add("platform-product", {"policy": fp["policy"]},
+            [f"false-positive-candidate:{fp['policy']}",
+             *[f"{k}:{v}" for k, v in fp.items() if isinstance(v, (int, float))]],
+            "medium", refs=["policy review — humans change policy"])
+
+    # --- golden path -----------------------------------------------------
+    req = data.get("requests") or {}
+    gp = golden_path_analytics(req.get("requests", []),
+                               outcomes=req.get("outcomes", []),
+                               escapes=req.get("escapes", []))
+    for pid, pa in gp.get("paths", {}).items():
+        esc = pa.get("escape_reasons", {})
+        if esc:
+            reason, cnt = max(esc.items(), key=lambda kv: kv[1])
+            add("platform-product", {"golden_path": pid},
+                [f"escapes:{pid}:{reason}={cnt}",
+                 f"success_rate:{pa.get('success_rate')}"],
+                "medium" if sum(esc.values()) >= 2 else "high")
+
+    # --- graph questions ---------------------------------------------------
+    if graph is not None:
+        for q, type_ in _RISK_QUESTIONS.items():
+            if q not in FLEET_QUESTIONS:
+                continue
+            for it in fleet_query(graph, q).get("items", []):
+                node = it.get("node_id", "?")
+                fact_ids = it.get("fact_ids") or []
+                add(type_, {"node": node},
+                    [f"{q}:{node}", *[f"fact:{fi}" for fi in fact_ids]],
+                    "medium" if fact_ids else "high")
+    return eng

platformforge/plan/__init__.py

@@ -0,0 +1,107 @@
+"""Remediation planner (§7 `plan`, §156–157) — findings → change DAG.
+
+Ordering is not severity-only. Each step is scored on:
+
+    severity → blast radius → reversibility → prerequisites
+
+and wired into a DAG (`edges`/`depends_on`) when steps interact — e.g. a
+request/limits fix is a prerequisite of an HPA fix on the same workload.
+A step with no evidence is refused rather than planned.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_SEV = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
+
+# §157 — prerequisite edges between rule families. A rule id prefix in
+# `key` must land before any rule whose id is in `needs`.
+_PREREQS: dict[str, tuple[str, ...]] = {
+    "PF-K8S-003": ("PF-K8S-020",),          # requests before HPA targets
+    "PF-K8S-004": ("PF-K8S-020",),
+    "PF-SEC-020": ("PF-SEC-040",),          # fix image provenance first
+    "PF-IAM-001": ("PF-IAM-002",),          # kill wildcards before chains
+}
+
+# rules whose fix is intrinsically reversible (config-only, declarative)
+_REVERSIBLE_PREFIX = ("PF-K8S-", "PF-GITOPS-", "PF-FIN-", "PF-CICD-",
+                      "PF-SLO-")
+
+
+def remediation_plan(findings: list[dict],
+                     graph: Any | None = None,
+                     facts: list[dict] | None = None) -> dict[str, Any]:
+    violated = [f for f in findings if f.get("status") == "violated"]
+    refused = [f.get("rule_id") for f in findings
+               if f.get("status") == "violated" and not f.get("evidence")]
+
+    facts_by_id = {f.get("fact_id"): f for f in facts or []}
+    steps = []
+    for f in violated:
+        if not f.get("evidence"):
+            continue
+        blast_n = None
+        node = None
+        if graph is not None:
+            from platformforge.graph.query import blast_radius
+            for e in f["evidence"]:
+                nid = facts_by_id.get(e, {}).get("attrs", {}).get("node_id")
+                if nid and nid in graph.nodes:
+                    node = nid
+                    blast_n = max(blast_n or 0,
+                                  len(blast_radius(graph, nid)["nodes"]))
+        steps.append({"id": f"step-{len(steps):03d}",
+                      "rule_id": f["rule_id"], "title": f.get("title"),
+                      "severity": f.get("severity", "medium"),
+                      "evidence": f["evidence"], "node": node,
+                      "remediation": f.get("remediation", ""),
+                      "blast_size": blast_n,
+                      "reversible": f["rule_id"].startswith(
+                          _REVERSIBLE_PREFIX),
+                      "depends_on": [],                      # §157
+                      "rollback": "revert the change that violates "
+                                  f"{f['rule_id']}; verify with judge"})
+
+    # §156 scoring: severity → blast → irreversible last
+    steps.sort(key=lambda s: (_SEV.get(s["severity"], 9),
+                              -(s["blast_size"] or 0),
+                              not s["reversible"]))
+
+    # §157 — DAG edges: prerequisite rules (any step pair sharing the
+    # rule ids — a rule may fire on several facts)
+    by_rule: dict[str, list[str]] = {}
+    for s in steps:
+        by_rule.setdefault(s["rule_id"], []).append(s["id"])
+    edges = []
+    for prereq, needs in _PREREQS.items():
+        for need in needs:
+            for pre_id in by_rule.get(prereq, []):
+                for dep_id in by_rule.get(need, []):
+                    edges.append({"from": pre_id, "to": dep_id,
+                                  "why": f"{need} assumes {prereq} "
+                                         "is fixed"})
+                    for s in steps:
+                        if s["id"] == dep_id:
+                            s["depends_on"].append(pre_id)
+    # same-node steps are sequenced: later steps depend on the first fix
+    by_node: dict[str, list[dict]] = {}
+    for s in steps:
+        if s["node"]:
+            by_node.setdefault(s["node"], []).append(s)
+    for node, ns in by_node.items():
+        if len(ns) > 1:
+            first = ns[0]["id"]
+            for s in ns[1:]:
+                if first not in s["depends_on"]:
+                    s["depends_on"].append(first)
+                    edges.append({"from": first, "to": s["id"],
+                                  "why": f"same node {node}"})
+    return {"plan": "platformforge.remediation/v2",
+            "dag": {"steps": [s["id"] for s in steps], "edges": edges},
+            "steps": steps,
+            "counts": {"steps": len(steps), "refused": len(refused),
+                       "dag_edges": len(edges)},
+            "refused": refused,
+            "boundary": "plan is a proposal — apply lives host-side "
+                        "(platform.change.core_read_only)"}

platformforge/portable_cli.py

@@ -0,0 +1,199 @@
+"""Thin CLI adapter for portable distribution and workspace."""
+
+from __future__ import annotations
+
+
+def run_guided_install() -> int:
+    """Run guided install through the shared wizard and real service."""
+    from platformforge.install import service
+    from platformforge.ui.kit import UIContext
+    from platformforge.ui.wizard import run_wizard
+
+    return run_wizard(
+        forge_name="platform-forge",
+        install_fn=lambda **kw: service.install(root=None, **kw),
+        doctor_fn=lambda **kw: service.doctor(**kw),
+        ctx=UIContext.detect(),
+    )
+
+
+def register(sub, add_common, emit):
+    def install(a):
+        # forge/* contract surface: `install <op>` routes the shared
+        # lifecycle verbs; `apply` (default) keeps the legacy flags too —
+        # `--profile agentic` and `--host agents` pass straight through.
+        from platformforge.install import service
+
+        op = getattr(a, "op", "apply") or "apply"
+        hosts = a.host or ["all"]
+        try:
+            if op != "apply":
+                fn = {
+                    "status": lambda: service.status(scope=a.scope, root=a.repo),
+                    "doctor": lambda: service.doctor(scope=a.scope, root=a.repo),
+                    "repair": lambda: service.repair(scope=a.scope, root=a.repo, dry_run=a.dry_run),
+                    "uninstall": lambda: service.uninstall(
+                        scope=a.scope, root=a.repo, purge=a.purge, dry_run=a.dry_run
+                    ),
+                    "update": lambda: service.update(to=a.to, repo=None, dry_run=a.dry_run),
+                    "mcp-verify": service.mcp_verify,
+                }[op]
+                out = fn()
+            else:
+                comps = (
+                    tuple(c.strip() for c in a.components.split(",") if c.strip())
+                    if getattr(a, "components", None)
+                    else None
+                )
+
+                def call(*, yes: bool, dry_run: bool):
+                    return service.install(
+                        scope=a.scope,
+                        root=a.repo,
+                        host="all" if hosts == ["all"] else hosts[0] if len(hosts) == 1 else "all",
+                        profile=a.profile if a.profile in service.PROFILES else "recommended",
+                        gateway_profile=a.gateway_profile,
+                        yes=yes,
+                        dry_run=dry_run,
+                        components=comps,
+                    )
+
+                import sys
+
+                interactive = not a.yes and not a.dry_run and sys.stdin.isatty() and sys.stdout.isatty()
+                if interactive:
+                    # Interactive approval: render the real plan, confirm
+                    # once, apply — one command instead of dry-run + apply.
+                    from platformforge.ui.kit import NonInteractive, approve_plan
+
+                    try:
+                        approved = approve_plan(call(yes=False, dry_run=True))
+                    except NonInteractive:
+                        approved = False
+                    out = (
+                        call(yes=True, dry_run=False)
+                        if approved
+                        else {
+                            "schema": "forge/InstallReceipt/v1",
+                            "forge_id": "platform-forge",
+                            "operation": "install",
+                            "status": "declined",
+                            "checks": [],
+                            "managed_files": [],
+                            "verification": {"status": "UNVERIFIED"},
+                            "error": {"kind": "PF-INSTALL-DECLINED", "detail": "declined — nothing written"},
+                        }
+                    )
+                else:
+                    out = call(yes=a.yes, dry_run=a.dry_run)
+        except service.InstallRefusal as exc:
+            return emit({"status": "refused", "error": {"kind": exc.kind, "detail": exc.detail}}, a, 2)
+        rc = (
+            0
+            if str(out.get("status", "")).lower()
+            in ("ok", "completed", "planned", "healthy", "unverified", "pass")
+            else 1
+        )
+        return emit(out, a, rc)
+
+    def uninstall(a):
+        from platformforge.distribution import uninstall as fn
+
+        return emit(fn(a.repo, a.purge), a)
+
+    def upgrade(a):
+        from platformforge.distribution import upgrade as fn
+
+        return emit(fn(a.repo, a.profile or None, a.host or None, a.dry_run), a)
+
+    def portable(a):
+        from platformforge.distribution import build_bundle, doctor, install_bundle, verify_bundle
+
+        if a.portable_cmd == "build":
+            return emit(build_bundle(a.path, a.profile, a.host, a.offline_bundle), a)
+        if a.portable_cmd == "verify":
+            out = verify_bundle(a.path)
+            return emit(out, a, 0 if out["valid"] else 2)
+        if a.portable_cmd == "install":
+            out = install_bundle(a.path, a.repo)
+            return emit(out, a, 2 if out.get("refusal") else 0)
+        if a.portable_cmd == "doctor":
+            return emit(doctor(a.repo), a)
+        return emit({"refusal": "PF-DIST-UNKNOWN-COMMAND"}, a, 2)
+
+    def workspace(a):
+        from platformforge.workspace import add_repo, doctor, ensure_workspace, load_workspace, remove_repo
+
+        command = a.workspace_cmd
+        if command == "init":
+            return emit(ensure_workspace(a.repo, a.profile, a.host).to_dict(), a)
+        if command == "add":
+            return emit(add_repo(a.repo, a.path, a.name).to_dict(), a)
+        if command == "remove":
+            return emit(remove_repo(a.repo, a.name).to_dict(), a)
+        if command == "doctor":
+            return emit(doctor(a.repo), a)
+        if command == "status":
+            return emit(load_workspace(a.repo).to_dict(), a)
+        if command == "list":
+            return emit({"repos": load_workspace(a.repo).to_dict()["repos"]}, a)
+        return emit({"refusal": "PF-WORKSPACE-UNKNOWN-COMMAND"}, a, 2)
+
+    sp = sub.add_parser("install", help="install Platform Forge assets into a workspace")
+    add_common(sp)
+    sp.add_argument(
+        "op",
+        nargs="?",
+        default="apply",
+        choices=["apply", "status", "doctor", "repair", "uninstall", "update", "mcp-verify"],
+        help="forge/* lifecycle verb (default: apply)",
+    )
+    sp.add_argument(
+        "--profile", default="recommended", help="minimal|recommended|full (contract) or native profile name"
+    )
+    sp.add_argument(
+        "--host", action="append", choices=["agents", "claude", "codex", "devin", "copilot", "all"]
+    )
+    sp.add_argument("--scope", default="project", choices=["project", "workspace", "user"])
+    sp.add_argument("--yes", "-y", action="store_true", help="explicit approval — required for writes")
+    sp.add_argument("--purge", action="store_true", help="uninstall: also remove .platformforge state")
+    sp.add_argument("--to", default=None, help="update: pinned version — never 'latest'")
+    sp.add_argument(
+        "--components", default=None, help="optional components csv: skills,agents,mcp,tui,graph-studio"
+    )
+    sp.add_argument(
+        "--gateway-profile", default="balanced", choices=["economy", "balanced", "deep"],
+        help="execution profile: economy|balanced|deep",
+    )
+    sp.add_argument("--dry-run", action="store_true")
+    sp.set_defaults(func=install)
+
+    sp = sub.add_parser("uninstall", help="remove owned Platform Forge assets safely")
+    add_common(sp)
+    sp.add_argument("--purge", action="store_true")
+    sp.set_defaults(func=uninstall)
+
+    sp = sub.add_parser("upgrade", help="upgrade managed portable assets")
+    add_common(sp)
+    sp.add_argument("--profile", default="")
+    sp.add_argument("--host", action="append", choices=["agents", "claude", "codex", "devin"])
+    sp.add_argument("--dry-run", action="store_true")
+    sp.set_defaults(func=upgrade)
+
+    sp = sub.add_parser("portable", help="build/verify/doctor portable distributions")
+    add_common(sp)
+    sp.add_argument("portable_cmd", choices=["build", "verify", "install", "doctor"])
+    sp.add_argument("path", nargs="?", default="dist/platformforge-portable")
+    sp.add_argument("--profile", default="agentic")
+    sp.add_argument("--host", action="append", choices=["agents", "claude", "codex", "devin"])
+    sp.add_argument("--offline-bundle", action="store_true", default=True)
+    sp.set_defaults(func=portable)
+
+    sp = sub.add_parser("workspace", help="workspace lifecycle and multi-repo manifest")
+    add_common(sp)
+    sp.add_argument("workspace_cmd", choices=["init", "add", "remove", "list", "doctor", "status"])
+    sp.add_argument("path", nargs="?", default=".")
+    sp.add_argument("--name", default="")
+    sp.add_argument("--profile", default="agentic")
+    sp.add_argument("--host", action="append", choices=["agents", "claude", "codex", "devin"])
+    sp.set_defaults(func=workspace)