platformforge 0.1.0__py3-none-any.whl

platformforge/live/store.py

@@ -0,0 +1,256 @@
+"""ObservationStore — .platformforge/observations/ layout (cycle §206):
+
+    .platformforge/observations/
+      index.db                    # sqlite index (§210–211)
+      <observation_id>/
+        manifest.json             # envelope sans objects
+        objects.json              # redacted object list
+        receipt.json              # collector receipt
+        facts.json                # extracted facts (when computed)
+        artifacts/<sha>           # large raw blobs via ArtifactStore refs
+
+Content-addressed hashing dedups identical snapshots (§96); the sqlite
+index makes time-range/provider/scope/resource lookups fast (§212).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.redaction import redact_text
+from platformforge.core.store import ArtifactStore
+from platformforge.live.envelope import validate_envelope
+from platformforge.live.models import ObservationEnvelope
+
+OBS_DIR = ".platformforge/observations"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS observations (
+    observation_id TEXT PRIMARY KEY,
+    provider TEXT, source_type TEXT, captured_at TEXT,
+    coverage TEXT, freshness TEXT, scope TEXT, objects INTEGER,
+    bytes INTEGER, envelope_hash TEXT, stored_at REAL);
+CREATE TABLE IF NOT EXISTS resources (
+    observation_id TEXT, resource_id TEXT, resource_type TEXT,
+    provider TEXT, cluster TEXT, account TEXT, region TEXT,
+    namespace TEXT, name TEXT, content_hash TEXT, lifecycle TEXT);
+CREATE INDEX IF NOT EXISTS res_by_id ON resources(resource_id);
+CREATE INDEX IF NOT EXISTS res_by_obs ON resources(observation_id);
+CREATE INDEX IF NOT EXISTS obs_by_ts ON observations(captured_at);
+"""
+
+
+class ObservationStore:
+    def __init__(self, root: str | Path):
+        self.root = Path(root) / OBS_DIR
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.artifacts = ArtifactStore(root)
+        self.db = sqlite3.connect(str(self.root / "index.db"))
+        self.db.executescript(_SCHEMA)
+        self.db.commit()
+
+    # ── write path ───────────────────────────────────────────
+    def put(self, env: ObservationEnvelope,
+            facts: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+        """Validate → redact → persist. Refuses invalid envelopes."""
+        doc = env.to_dict()
+        errors = validate_envelope(doc)
+        if errors:
+            return {"refusal": "PF-LIVE-INVALID-ENVELOPE",
+                    "unlock": "fix envelope against "
+                              "platformforge/observation/v1",
+                    "errors": errors}
+        odir = self.root / env.observation_id
+        odir.mkdir(parents=True, exist_ok=True)
+        manifest = {k: v for k, v in doc.items() if k != "objects"}
+        (odir / "manifest.json").write_text(json.dumps(
+            manifest, indent=2, sort_keys=True, default=str) + "\n")
+        (odir / "objects.json").write_text(json.dumps(
+            env.objects, indent=2, sort_keys=True, default=str) + "\n")
+        if env.receipt:
+            (odir / "receipt.json").write_text(json.dumps(
+                env.receipt, indent=2, sort_keys=True, default=str) + "\n")
+        if facts is not None:
+            (odir / "facts.json").write_text(json.dumps(
+                {"facts": facts}, indent=2, sort_keys=True,
+                default=str) + "\n")
+        self._index(env)
+        return {"observation_id": env.observation_id,
+                "envelope_hash": env.signature(),
+                "objects": len(env.objects), "path": str(odir)}
+
+    def _index(self, env: ObservationEnvelope) -> None:
+        cov = (env.coverage or {}).get("status", "unknown")
+        self.db.execute(
+            "INSERT OR REPLACE INTO observations VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+            (env.observation_id, env.provider, env.source_type,
+             env.captured_at, cov,
+             env.freshness_status_at(),
+             json.dumps(env.scope, sort_keys=True, default=str),
+             len(env.objects), env.bytes, env.signature(), time.time()))
+        self.db.execute("DELETE FROM resources WHERE observation_id=?",
+                        (env.observation_id,))
+        for o in env.objects:
+            self.db.execute(
+                "INSERT INTO resources VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+                (env.observation_id, o.get("resource_id", ""),
+                 o.get("resource_type", ""), o.get("provider", env.provider),
+                 o.get("cluster", ""), o.get("account", ""),
+                 o.get("region", ""), o.get("namespace", ""),
+                 o.get("name", ""), o.get("content_hash", ""),
+                 o.get("lifecycle", "present")))
+        self.db.commit()
+
+    # ── read path ────────────────────────────────────────────
+    def get(self, observation_id: str) -> ObservationEnvelope | None:
+        odir = self.root / observation_id
+        mp, op = odir / "manifest.json", odir / "objects.json"
+        if not mp.exists():
+            return None
+        doc = json.loads(mp.read_text())
+        doc["objects"] = (json.loads(op.read_text())
+                          if op.exists() else [])
+        return ObservationEnvelope.from_dict(doc)
+
+    def manifest(self, observation_id: str) -> dict[str, Any] | None:
+        p = self.root / observation_id / "manifest.json"
+        return json.loads(p.read_text()) if p.exists() else None
+
+    def facts(self, observation_id: str) -> list[dict[str, Any]]:
+        p = self.root / observation_id / "facts.json"
+        if not p.exists():
+            return []
+        return json.loads(p.read_text()).get("facts", [])
+
+    def receipts(self, observation_id: str) -> dict[str, Any] | None:
+        p = self.root / observation_id / "receipt.json"
+        return json.loads(p.read_text()) if p.exists() else None
+
+    def list(self, provider: str | None = None, since: str | None = None,
+             until: str | None = None, limit: int = 100) -> list[dict[str, Any]]:
+        q = ("SELECT observation_id, provider, source_type, captured_at, "
+             "coverage, objects, envelope_hash FROM observations WHERE 1=1")
+        args: list[Any] = []
+        if provider:
+            q += " AND provider=?"; args.append(provider)
+        if since:
+            q += " AND captured_at>=?"; args.append(since)
+        if until:
+            q += " AND captured_at<=?"; args.append(until)
+        q += " ORDER BY captured_at DESC LIMIT ?"; args.append(limit)
+        return [dict(zip(("observation_id", "provider", "source_type",
+                          "captured_at", "coverage", "objects",
+                          "envelope_hash"), r, strict=True))
+                for r in self.db.execute(q, args)]
+
+    def find_resource(self, resource_id: str | None = None,
+                      cluster: str | None = None, account: str | None = None,
+                      resource_type: str | None = None,
+                      name: str | None = None,
+                      limit: int = 100) -> list[dict[str, Any]]:
+        q = ("SELECT observation_id, resource_id, resource_type, cluster, "
+             "account, region, namespace, name, lifecycle, content_hash "
+             "FROM resources WHERE 1=1")
+        args: list[Any] = []
+        for col, val in (("resource_id", resource_id), ("cluster", cluster),
+                         ("account", account), ("resource_type", resource_type),
+                         ("name", name)):
+            if val:
+                q += f" AND {col}=?"; args.append(val)
+        q += " ORDER BY observation_id DESC LIMIT ?"; args.append(limit)
+        cols = ("observation_id", "resource_id", "resource_type", "cluster",
+                "account", "region", "namespace", "name", "lifecycle",
+                "content_hash")
+        return [dict(zip(cols, r, strict=True)) for r in self.db.execute(q, args)]
+
+    def latest(self, provider: str | None = None) -> dict[str, Any] | None:
+        rows = self.list(provider=provider, limit=1)
+        return rows[0] if rows else None
+
+    def status(self) -> dict[str, Any]:
+        obs = self.list(limit=50)
+        providers: dict[str, dict[str, Any]] = {}
+        for o in obs:
+            p = providers.setdefault(o["provider"], {
+                "observations": 0, "last": "", "coverage": set()})
+            p["observations"] += 1
+            p["last"] = max(p["last"], o["captured_at"])
+            p["coverage"].add(o["coverage"])
+        for p in providers.values():
+            p["coverage"] = sorted(p["coverage"])
+        return {"observations": len(obs), "providers": providers,
+                "store": str(self.root),
+                "artifact_store": self.artifacts.stats()}
+
+
+def redact_for_output(text: str) -> str:
+    """Boundary helper: nothing leaving the store carries raw secrets."""
+    return redact_text(text)
+
+
+CHANGE_JOURNAL = ".platformforge/live/changes.jsonl"
+
+
+class ChangeJournal:
+    """Append-only journal of provider-observed ChangeEvents (§78).
+
+    JSONL, deduped by event_id, GC-able by age or count. Read path is
+    used by `live drift`/incident correlation to attach causal change
+    evidence to drift events."""
+
+    def __init__(self, root: str | Path):
+        self.path = Path(root) / CHANGE_JOURNAL
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def append(self, events: list[Any]) -> dict[str, int]:
+        """Append ChangeEvents (dedup on event_id). Returns counts."""
+        from platformforge.live.models import ChangeEvent
+        existing = {e.get("event_id") for e in self.read()}
+        kept = 0
+        with self.path.open("a") as fh:
+            for e in events:
+                d = e.to_dict() if isinstance(e, ChangeEvent) else dict(e)
+                if d.get("event_id") in existing:
+                    continue
+                fh.write(json.dumps(d, sort_keys=True, default=str)
+                         + "\n")
+                existing.add(d.get("event_id"))
+                kept += 1
+        return {"appended": kept, "total": len(self.read())}
+
+    def read(self, *, since: str = "", resource: str = "",
+             limit: int = 1000) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        out: list[dict[str, Any]] = []
+        for line in self.path.read_text().splitlines():
+            if not line.strip():
+                continue
+            e = json.loads(line)
+            if since and e.get("timestamp", "") < since:
+                continue
+            if resource and resource not in e.get("resource_ids", []):
+                continue
+            out.append(e)
+        return out[-limit:]
+
+    def gc(self, *, max_events: int = 10000,
+           max_age_days: int = 90) -> dict[str, int]:
+        """Journal GC: keep newest `max_events` and nothing older than
+        `max_age_days`. Returns {removed, kept}."""
+        from datetime import datetime, timedelta, timezone
+        cutoff = (datetime.now(timezone.utc)
+                  - timedelta(days=max_age_days)).isoformat()
+        events = self.read(limit=1_000_000)
+        kept = [e for e in events
+                if e.get("timestamp", "") >= cutoff][-max_events:]
+        removed = len(events) - len(kept)
+        if removed:
+            self.path.write_text("".join(
+                json.dumps(e, sort_keys=True, default=str) + "\n"
+                for e in kept))
+        return {"removed": removed, "kept": len(kept)}

platformforge/live/topology.py

@@ -0,0 +1,249 @@
+"""Runtime topology (cycle §117–§125) — OTel / Hubble / EndpointSlice →
+runtime edges with temporal windows + behavior classes.
+
+Rules that keep this honest:
+- §121 — runtime edges are `provenance=observed` + `source_type=runtime`
+  (measured evidence); they never overwrite declared edges — the v2
+  evidence list keeps both layers.
+- §123 — only whitelisted attributes survive extraction: service names,
+  namespaces, ports, protocols, verdicts. URLs, headers, db.statement,
+  user ids, payloads are dropped at the boundary (§208).
+- §92 — a runtime edge with no samples in a window is "not recently
+  observed", never "the dependency does not exist".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.graph.model import node_id
+from platformforge.live.models import BEHAVIOR_CLASSES, now_iso
+
+# §123/§208 — extraction whitelist. Anything not listed is dropped.
+SAFE_RESOURCE_ATTRS = ("service.name", "service.namespace",
+                       "k8s.namespace.name", "k8s.deployment.name",
+                       "k8s.pod.name")
+SAFE_SPAN_ATTRS = ("peer.service", "server.address", "network.peer.name",
+                   "db.system", "db.name", "messaging.system",
+                   "messaging.destination.name", "rpc.service",
+                   "server.port", "url.template")
+DROP_ATTR_MARKERS = ("url", "header", "statement", "query", "user",
+                     "password", "token", "secret", "body", "payload",
+                     "cookie", "authorization")
+
+
+def _attrs_of(span_or_resource: dict[str, Any]) -> dict[str, Any]:
+    """OTLP attributes[] → plain dict, whitelist-filtered."""
+    raw = span_or_resource.get("attributes") or {}
+    if isinstance(raw, list):
+        raw = {a.get("key"): (a.get("value") or {})
+               for a in raw if isinstance(a, dict)}
+    out = {}
+    for k, v in raw.items():
+        lk = str(k).lower()
+        if any(m in lk for m in DROP_ATTR_MARKERS) and \
+                lk not in SAFE_SPAN_ATTRS:
+            continue
+        if k in SAFE_RESOURCE_ATTRS or k in SAFE_SPAN_ATTRS:
+            out[k] = v.get("stringValue") or v.get("intValue") \
+                if isinstance(v, dict) else v
+    return out
+
+
+def _service_node(attrs: dict[str, Any]) -> str:
+    name = attrs.get("service.name") or attrs.get("service") or "unknown"
+    ns = attrs.get("service.namespace") or \
+        attrs.get("k8s.namespace.name") or ""
+    return node_id("service", f"{ns}/{name}" if ns else str(name))
+
+
+def _peer_node(attrs: dict[str, Any]) -> tuple[str, str]:
+    """Resolve a span's remote peer to (node_id, edge_kind)."""
+    if attrs.get("db.system"):
+        return node_id("database", str(attrs.get("db.name")
+                                            or attrs["db.system"])), "calls"
+    if attrs.get("messaging.system"):
+        return node_id("queue", str(
+            attrs.get("messaging.destination.name")
+            or attrs["messaging.system"])), "consumes"
+    peer = attrs.get("peer.service") or attrs.get("server.address") or \
+        attrs.get("rpc.service") or attrs.get("network.peer.name")
+    if peer:
+        return node_id("service", str(peer)), "calls"
+    return "", ""
+
+
+def edges_from_otel(docs: list[dict[str, Any]], *,
+                    window_start: str = "", window_end: str = ""
+                    ) -> list[dict[str, Any]]:
+    """OTLP span docs → runtime edge records {src,dst,kind,temporal,
+    evidence,attrs}. Accepts `resourceSpans` trees and pre-flattened
+    {service, peer, ...} dicts."""
+    pairs: dict[tuple[str, str, str], dict[str, Any]] = {}
+    flat: list[dict[str, Any]] = []
+    for d in docs:
+        if "resourceSpans" in d:
+            for rs in d["resourceSpans"]:
+                res_attrs = _attrs_of(rs.get("resource", {}))
+                svc = _service_node(res_attrs)
+                for ss in rs.get("scopeSpans", []):
+                    for sp in ss.get("spans", []):
+                        flat.append({"service_node": svc,
+                                     "attrs": _attrs_of(sp)})
+        else:
+            flat.append(d)
+    for s in flat:
+        svc = s.get("service_node") or _service_node(
+            s.get("attrs", {}) or s)
+        peer, kind = _peer_node(s.get("attrs", {}) or s)
+        if not svc or not peer or svc == peer:
+            continue
+        key = (svc, peer, kind)
+        rec = pairs.setdefault(key, {"src": svc, "dst": peer,
+                                     "kind": kind, "sample_count": 0,
+                                     "first_seen": "", "last_seen": ""})
+        rec["sample_count"] += 1
+    out = []
+    for rec in pairs.values():
+        rec["first_seen"] = window_start or now_iso()
+        rec["last_seen"] = window_end or now_iso()
+        rec["provenance"] = "observed"
+        rec["source_type"] = "otel"
+        out.append(rec)
+    return sorted(out, key=lambda r: (r["src"], r["dst"], r["kind"]))
+
+
+def _hubble_ep(ep: dict[str, Any]) -> str:
+    pod = ep.get("pod_name") or ""
+    ns = ep.get("namespace") or ""
+    if pod:
+        return node_id("pod", f"{ns}/{pod}" if ns else pod)
+    for l in ep.get("labels", []) or []:
+        if l.startswith(("k8s:app=", "k8s:name=")):
+            return node_id("workload", l.split("=", 1)[1])
+    return node_id("service", f"ext:{ep.get('ip')}") \
+        if ep.get("ip") else ""
+
+
+def edges_from_hubble(flows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Hubble flow docs → runtime edges; verdicts kept as evidence."""
+    pairs: dict[tuple[str, str], dict[str, Any]] = {}
+    for f in flows:
+        fl = f.get("flow", f)
+        src = _hubble_ep(fl.get("source", {}))
+        dst = _hubble_ep(fl.get("destination", {}))
+        if not src or not dst or src == dst:
+            continue
+        key = (src, dst)
+        rec = pairs.setdefault(key, {"src": src, "dst": dst,
+                                     "kind": "calls", "sample_count": 0,
+                                     "verdicts": {}, "ports": set(),
+                                     "first_seen": "", "last_seen": ""})
+        rec["sample_count"] += 1
+        v = fl.get("verdict", "")
+        if v:
+            rec["verdicts"][v] = rec["verdicts"].get(v, 0) + 1
+        port = ((fl.get("l4") or {}).get("TCP") or {}).get(
+            "destination_port")
+        if port:
+            rec["ports"].add(port)
+        t = f.get("time") or fl.get("time", "")
+        if t:
+            rec["first_seen"] = min(t, rec["first_seen"] or t)
+            rec["last_seen"] = max(t, rec["last_seen"] or t)
+    out = []
+    for rec in pairs.values():
+        rec["provenance"] = "observed"
+        rec["source_type"] = "hubble"
+        rec["attrs"] = {"ports": sorted(rec.pop("ports")),
+                        "verdicts": rec.pop("verdicts")}
+        out.append(rec)
+    return sorted(out, key=lambda r: (r["src"], r["dst"]))
+
+
+def edges_from_endpointslices(objects: list[dict[str, Any]]
+                              ) -> list[dict[str, Any]]:
+    """EndpointSlice k8s objects → workload→service membership edges."""
+    out = []
+    for o in objects:
+        # accept raw k8s EndpointSlice or projected ObservedObject
+        eps = o.get("endpoints") or \
+            (o.get("attributes", {}).get("endpoints") or [])
+        labels = o.get("metadata", {}).get("labels", {}) or \
+            o.get("attributes", {}).get("labels", {})
+        svc = (labels.get("kubernetes.io/service-name")
+               or o.get("service_name") or "")
+        ns = o.get("metadata", {}).get("namespace", "") or \
+            o.get("namespace", "")
+        if not svc:
+            continue
+        for ep in eps:
+            ref = ep.get("targetRef", {})
+            if ref.get("kind") != "Pod":
+                continue
+            pod = node_id("pod", f"{ref.get('namespace') or ns}/"
+                                 f"{ref.get('name')}")
+            out.append({"src": pod,
+                        "dst": node_id("service", f"{ns}/{svc}"),
+                        "kind": "exposes", "provenance": "observed",
+                        "source_type": "endpointslice",
+                        "sample_count": 1})
+    return sorted(out, key=lambda r: (r["src"], r["dst"]))
+
+
+def classify_behavior(runtime_edges: list[dict[str, Any]],
+                      declared_edge_ids: set[str],
+                      *, window_fresh: bool = True) -> list[dict[str, Any]]:
+    """§125 — declared-vs-runtime behavior class per runtime edge."""
+    out = []
+    for e in runtime_edges:
+        eid = f"{e['src']}->{e['dst']}:{e['kind']}"
+        declared = eid in declared_edge_ids
+        if declared:
+            cls = "declared-and-observed"
+        else:
+            cls = "observed-undeclared"
+        if not window_fresh and declared:
+            cls = "declared-not-seen-in-window"
+        assert cls in BEHAVIOR_CLASSES
+        out.append({**e, "edge_id": eid, "behavior": cls})
+    return out
+
+
+def runtime_temporal(e: dict[str, Any]) -> dict[str, Any]:
+    """Normalize an edge record into a v2 temporal block."""
+    return {k: v for k, v in {
+        "first_seen": e.get("first_seen"),
+        "last_seen": e.get("last_seen"),
+        "window_start": e.get("window_start") or e.get("first_seen"),
+        "window_end": e.get("window_end") or e.get("last_seen"),
+        "sample_count": e.get("sample_count", 0)}.items()
+        if v not in (None, "")}
+
+
+def apply_runtime_edges(graph, edges: list[dict[str, Any]]) -> int:
+    """Fold runtime edge records into a v2 graph: nodes auto-created as
+    `external`/`workload` placeholders when missing; the edge carries a
+    `source_type` evidence record + temporal window (§121). Returns the
+    number of edges applied."""
+    from platformforge.graph.model import Edge, Node
+    applied = 0
+    for e in edges:
+        for nid in (e["src"], e["dst"]):
+            if nid not in graph.nodes:
+                kind = nid.split("/", 1)[0] or "workload"
+                graph.add_node(Node(nid, kind, nid.split("/")[-1]))
+        applied_e = graph.add_edge(Edge(
+            e["src"], e["dst"], e.get("kind", "calls"),
+            provenance="observed",
+            confidence=float(e.get("confidence", 1.0)),
+            source_fact_ids=tuple(e.get("fact_ids", [])),
+            attrs=e.get("attrs", {}),
+            evidence=({"provenance": "observed",
+                       "source_type": e.get("source_type", "runtime"),
+                       "fact_ids": list(e.get("fact_ids", [])),
+                       "observed_at": e.get("last_seen", "")},),
+            temporal=runtime_temporal(e)))
+        if applied_e:
+            applied += 1
+    return applied

platformforge/mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP adapter — capability registry → bounded tools. CLI and MCP invoke
+the same core; MCP adds only transport + output bounding."""
+
+from platformforge.mcp.registry import CAPABILITIES, Capability
+from platformforge.mcp.tools import call_tool
+
+__all__ = ["CAPABILITIES", "Capability", "call_tool"]

platformforge/mcp/parity.py

@@ -0,0 +1,69 @@
+"""Host parity — emit integration config per host. Same server, same core,
+host-specific transport config only. Detach removes cleanly."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+SERVER_CMD = ["python", "-m", "platformforge", "mcp", "serve"]
+
+
+def integrate(host: str, root: str | Path) -> dict[str, Any]:
+    root = Path(root)
+    entry = {"command": SERVER_CMD[0],
+             "args": SERVER_CMD[1:],
+             "env": {}}
+    if host == "claude":
+        p = root / ".mcp.json"
+        cfg = json.loads(p.read_text()) if p.exists() else {"mcpServers": {}}
+        cfg.setdefault("mcpServers", {})["platformforge"] = entry
+        p.write_text(json.dumps(cfg, indent=2) + "\n")
+        return {"host": host, "wrote": str(p)}
+    if host == "codex":
+        p = root / ".codex" / "config.toml"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("a") as fh:
+            fh.write('\n[mcp_servers.platformforge]\n'
+                     f'command = "{SERVER_CMD[0]}"\n'
+                     f'args = {json.dumps(SERVER_CMD[1:])}\n')
+        return {"host": host, "wrote": str(p)}
+    if host == "devin":
+        p = root / ".devin" / "mcp_config.local.json"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        cfg = json.loads(p.read_text()) if p.exists() else {"mcpServers": {}}
+        cfg.setdefault("mcpServers", {})["platformforge"] = entry
+        p.write_text(json.dumps(cfg, indent=2) + "\n")
+        return {"host": host, "wrote": str(p),
+                "note": "local-only file — never commit secrets here"}
+    if host == "copilot":
+        p = root / ".vscode" / "mcp.json"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        cfg = json.loads(p.read_text()) if p.exists() else {"servers": {}}
+        cfg.setdefault("servers", {})["platformforge"] = {
+            "type": "stdio", "command": SERVER_CMD[0],
+            "args": SERVER_CMD[1:]}
+        p.write_text(json.dumps(cfg, indent=2) + "\n")
+        return {"host": host, "wrote": str(p)}
+    return {"host": "generic",
+            "snippet": {"mcpServers": {"platformforge": entry}},
+            "note": "merge into your host's MCP config"}
+
+
+def detach(host: str, root: str | Path) -> dict[str, Any]:
+    root = Path(root)
+    targets = {"claude": root / ".mcp.json",
+               "devin": root / ".devin" / "mcp_config.local.json",
+               "copilot": root / ".vscode" / "mcp.json"}
+    p = targets.get(host)
+    if p is None:
+        return {"host": host, "detached": False,
+                "note": "generic host has nothing to remove"}
+    if not p.exists():
+        return {"host": host, "detached": False, "note": "not integrated"}
+    cfg = json.loads(p.read_text())
+    key = "mcpServers" if "mcpServers" in cfg else "servers"
+    removed = cfg.get(key, {}).pop("platformforge", None)
+    p.write_text(json.dumps(cfg, indent=2) + "\n")
+    return {"host": host, "detached": removed is not None}