munim 0.1.0__py3-none-any.whl

munim/adapters/__init__.py

@@ -0,0 +1,3 @@
+from munim.adapters.cloudflare import Cloudflare  # noqa: F401
+from munim.adapters.resend import Resend  # noqa: F401
+from munim.adapters.vercel import Vercel  # noqa: F401

munim/adapters/cloudflare.py

@@ -0,0 +1,173 @@
+"""Cloudflare DNS: read, and write.
+
+Every mutation here is **read-before-write, upserted on (type, name)**. That is
+not tidiness. Re-running a launch that failed halfway would otherwise add a
+second SPF record beside the first, and two SPF records means receivers ignore
+both - the exact fault this product exists to catch. A tool that causes the bug
+it reports is worse than no tool.
+
+Writes are also idempotent for a second reason: a launch polls DNS and can
+outlive one tool call, so it must be safe to resume.
+"""
+
+from dataclasses import dataclass
+
+from munim.container import Container
+from munim.runlog import RunLog
+
+
+class CloudflareError(RuntimeError):
+    pass
+
+
+@dataclass
+class Record:
+    id: str
+    type: str
+    name: str
+    content: str
+    ttl: int = 1
+    proxied: bool = False
+
+    @classmethod
+    def from_api(cls, payload: dict) -> "Record":
+        return cls(id=payload["id"], type=payload["type"], name=payload["name"],
+                   content=payload["content"], ttl=payload.get("ttl", 1),
+                   proxied=payload.get("proxied", False))
+
+
+def _ok(payload: dict) -> dict:
+    if not payload.get("success", False):
+        errors = "; ".join(e.get("message", str(e)) for e in payload.get("errors", []))
+        raise CloudflareError(errors or "Cloudflare rejected the request")
+    return payload
+
+
+class Cloudflare:
+    """One client's Cloudflare account, reached through their container.
+
+    The container vends an authenticated HTTP client, so no token ever becomes
+    a value in this file (D6).
+    """
+
+    name = "cloudflare"
+
+    def __init__(self, container: Container, log: RunLog | None = None) -> None:
+        self._container = container
+        self._log = log
+
+    def _note(self, kind: str, text: str, **detail) -> None:
+        if self._log:
+            self._log.append(client=self._container.client, stage="dns",
+                             kind=kind, human_text=text, detail=detail)
+
+    async def zone_id(self, domain: str) -> str:
+        async with self._container.http("cloudflare") as http:
+            payload = _ok((await http.get("/zones", params={"name": domain})).json())
+        zones = payload.get("result") or []
+        if not zones:
+            raise CloudflareError(
+                f"{domain} is not a zone in this client's Cloudflare account. "
+                "Either the nameservers are not delegated here, or the wrong "
+                "client was named."
+            )
+        return zones[0]["id"]
+
+    async def records(self, zone: str, *, type: str = "", name: str = "") -> list[Record]:
+        params = {"per_page": 100}
+        if type:
+            params["type"] = type
+        if name:
+            params["name"] = name
+        async with self._container.http("cloudflare") as http:
+            payload = _ok((await http.get(f"/zones/{zone}/dns_records", params=params)).json())
+        return [Record.from_api(r) for r in payload.get("result", [])]
+
+    async def upsert(self, zone: str, *, type: str, name: str, content: str,
+                     ttl: int = 1, proxied: bool = False) -> tuple[Record, str]:
+        """Create or update. Returns the record and what happened.
+
+        Read-before-write on (type, name): identical content is left alone, a
+        differing single record is updated in place, and only a genuinely new
+        (type, name) is created. Nothing is ever blindly appended.
+        """
+        existing = [r for r in await self.records(zone, type=type, name=name)]
+
+        for record in existing:
+            if record.content == content:
+                self._note("observation", f"{type} record for {name} is already correct",
+                           check="dns_write", action="unchanged", record=name)
+                return record, "unchanged"
+
+        body = {"type": type, "name": name, "content": content,
+                "ttl": ttl, "proxied": proxied}
+
+        if len(existing) == 1:
+            async with self._container.http("cloudflare") as http:
+                payload = _ok((await http.put(
+                    f"/zones/{zone}/dns_records/{existing[0].id}", json=body)).json())
+            self._note("mutation", f"Updated the {type} record for {name}",
+                       check="dns_write", action="updated", record=name)
+            return Record.from_api(payload["result"]), "updated"
+
+        if len(existing) > 1:
+            # Appending here is what creates the duplicate-SPF fault. Refuse and
+            # let the caller decide, because merging is a judgement call.
+            raise CloudflareError(
+                f"{len(existing)} {type} records already exist for {name}. "
+                "Adding another would leave several in place; decide how to "
+                "combine them before writing."
+            )
+
+        async with self._container.http("cloudflare") as http:
+            payload = _ok((await http.post(f"/zones/{zone}/dns_records", json=body)).json())
+        self._note("mutation", f"Created the {type} record for {name}",
+                   check="dns_write", action="created", record=name)
+        return Record.from_api(payload["result"]), "created"
+
+    async def merge_spf(self, zone: str, domain: str, merged: str) -> tuple[Record, str]:
+        """Replace every SPF record with one. The only safe way to end up with
+        a single policy when a domain already carries more than one.
+
+        Order matters, though not where it first appears to. A failed *delete*
+        is equally bad either way: two policies remain and receivers ignore
+        both. The orders differ when the *write* fails. Write first and nothing
+        has been removed yet, so the domain keeps every policy it had and mail
+        stays broken. Delete first and the leftovers are already gone, so what
+        remains is one intact policy: not the merge that was wanted, but a
+        working one. That is the most a partial write can be.
+
+        The read-back at the end is separate, and covers the case neither order
+        helps with: an API that answers 200 without changing anything. Two
+        successful responses are not evidence that one policy is left, and one
+        policy is the only thing this function promises.
+        """
+        spf = [r for r in await self.records(zone, type="TXT", name=domain)
+               if r.content.lower().startswith("v=spf1")]
+        if not spf:
+            return await self.upsert(zone, type="TXT", name=domain, content=merged)
+
+        survivor, leftovers = spf[0], spf[1:]
+        async with self._container.http("cloudflare") as http:
+            for extra in leftovers:
+                _ok((await http.delete(f"/zones/{zone}/dns_records/{extra.id}")).json())
+            payload = _ok((await http.put(
+                f"/zones/{zone}/dns_records/{survivor.id}",
+                json={"type": "TXT", "name": domain, "content": merged, "ttl": 1})).json())
+
+        # Read back rather than trust the writes. A merge that silently left two
+        # policies is indistinguishable, from the caller's side, from one that
+        # worked, and the whole point of this function is that there is one.
+        remaining = [r for r in await self.records(zone, type="TXT", name=domain)
+                     if r.content.lower().startswith("v=spf1")]
+        if len(remaining) != 1:
+            raise CloudflareError(
+                f"{domain} has {len(remaining)} sender policies after the merge, "
+                f"not one. Nothing further was written. The records now are: "
+                + "; ".join(r.content for r in remaining)
+            )
+
+        self._note("mutation",
+                   f"Merged {len(spf)} sender policies into one",
+                   check="spf_single", action="merged", removed=len(leftovers))
+        return Record.from_api(payload["result"]), "merged"

munim/adapters/resend.py

@@ -0,0 +1,165 @@
+"""Resend: create a sending domain and hand back the records it needs.
+
+This is one end of the handoff the whole project is about. Resend emits DKIM,
+SPF and return-path records; they have to be written into Cloudflare, which is a
+different company and a different login. Get the A record wrong and the site does
+not load. Get these wrong and nothing breaks - the client's mail simply stops
+arriving, and nobody notices for weeks.
+
+Resend publishes no OAuth authorization endpoint, so it authenticates with an API
+key. That is Resend offering nothing else, not a preference (see connect/oauth.py,
+where it is deliberately absent from the provider table).
+"""
+
+from dataclasses import dataclass
+
+from munim.container import Container
+from munim.runlog import RunLog
+
+
+class ResendError(RuntimeError):
+    pass
+
+
+@dataclass
+class DnsRecord:
+    """A record Resend needs published, in the shape Cloudflare wants it.
+
+    Translating between the two vocabularies here is the point: Resend says
+    `record: "SPF", type: "TXT", name: "send"`, Cloudflare wants a type, a fully
+    qualified name and a content string. Doing it by hand is the copy-paste that
+    goes wrong.
+    """
+    purpose: str            # SPF, DKIM, or the tracking/return-path record
+    type: str               # TXT, CNAME, MX
+    name: str               # as Resend gives it, often relative
+    value: str
+    priority: int | None = None
+    status: str = "not_started"
+
+    def fqdn(self, domain: str) -> str:
+        """Resend returns names relative to the domain; Cloudflare wants them
+        absolute. Getting this wrong publishes a record nobody can find."""
+        if not self.name or self.name in ("@", domain):
+            return domain
+        if self.name.endswith(domain):
+            return self.name
+        return f"{self.name}.{domain}"
+
+    @classmethod
+    def from_api(cls, payload: dict) -> "DnsRecord":
+        return cls(
+            purpose=payload.get("record", "").upper(),
+            type=payload.get("type", "TXT").upper(),
+            name=payload.get("name", ""),
+            value=payload.get("value", ""),
+            priority=payload.get("priority"),
+            status=payload.get("status", "not_started"),
+        )
+
+
+@dataclass
+class Domain:
+    id: str
+    name: str
+    status: str
+    records: list[DnsRecord]
+
+    @property
+    def verified(self) -> bool:
+        return self.status == "verified"
+
+
+class Resend:
+    name = "resend"
+
+    def __init__(self, container: Container, log: RunLog | None = None) -> None:
+        self._container = container
+        self._log = log
+
+    def _note(self, kind: str, text: str, **detail) -> None:
+        if self._log:
+            self._log.append(client=self._container.client, stage="mail",
+                             kind=kind, human_text=text, detail=detail)
+
+    @staticmethod
+    def _ok(response) -> dict:
+        if response.status_code >= 400:
+            body = {}
+            try:
+                body = response.json()
+            except Exception:
+                pass
+            raise ResendError(body.get("message") or response.text[:160]
+                              or f"Resend returned {response.status_code}")
+        return response.json()
+
+    async def domains(self) -> list[Domain]:
+        async with self._container.http("resend") as http:
+            payload = self._ok(await http.get("/domains"))
+        return [Domain(id=d["id"], name=d["name"], status=d.get("status", ""),
+                       records=[DnsRecord.from_api(r) for r in d.get("records", [])])
+                for d in payload.get("data", [])]
+
+    async def find(self, domain: str) -> Domain | None:
+        for existing in await self.domains():
+            if existing.name.lower() == domain.lower():
+                return existing
+        return None
+
+    async def ensure_domain(self, domain: str, region: str = "us-east-1") -> tuple[Domain, str]:
+        """Create the sending domain, or return the one already there.
+
+        Idempotent for the same reason every mutation here is: a launch that
+        failed halfway and is re-run must not create a second sending domain and
+        a second set of DKIM keys, which would leave the client with records that
+        do not match the keys their mail is signed with.
+        """
+        existing = await self.find(domain)
+        if existing is not None:
+            self._note("observation", f"{domain} is already set up for sending",
+                       check="resend_domain", action="unchanged")
+            return existing, "unchanged"
+
+        async with self._container.http("resend") as http:
+            payload = self._ok(await http.post(
+                "/domains", json={"name": domain, "region": region}))
+
+        created = Domain(
+            id=payload["id"], name=payload["name"],
+            status=payload.get("status", "not_started"),
+            records=[DnsRecord.from_api(r) for r in payload.get("records", [])],
+        )
+        self._note("mutation",
+                   f"Created the sending domain and got {len(created.records)} "
+                   "records to publish",
+                   check="resend_domain", action="created",
+                   records=[r.purpose for r in created.records])
+        return created, "created"
+
+    async def verify(self, domain_id: str) -> str:
+        async with self._container.http("resend") as http:
+            payload = self._ok(await http.post(f"/domains/{domain_id}/verify"))
+        return payload.get("status", "unknown")
+
+    @staticmethod
+    def cloudflare_records(domain: Domain) -> list[dict]:
+        """Translate Resend's records into what Cloudflare's API wants.
+
+        This function is the handoff. Everything it does by rule is what an
+        operator otherwise does by eye, between two browser tabs, once per
+        client - and it is where the mistake that breaks nothing visible gets
+        made.
+        """
+        out = []
+        for record in domain.records:
+            entry = {
+                "type": record.type,
+                "name": record.fqdn(domain.name),
+                "content": record.value,
+                "purpose": record.purpose,
+            }
+            if record.priority is not None:
+                entry["priority"] = record.priority
+            out.append(entry)
+        return out

munim/adapters/vercel.py

@@ -0,0 +1,169 @@
+"""Vercel: what a project is doing, and what it is configured with.
+
+Read-first on purpose. The two failures worth catching here are quiet ones:
+
+  - An environment variable set but never applied, because Vercel bakes
+    build-time values in and setting one changes nothing until a redeploy. The
+    dashboard shows the new value; the running site uses the old one.
+  - A variable set on Preview instead of Production. It works when you test it
+    and is missing when a customer arrives.
+
+Both look correct in the dashboard, which is why nobody finds them by looking.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from munim.checks.dns import CheckResult
+from munim.container import Container
+
+
+class VercelError(RuntimeError):
+    pass
+
+
+@dataclass
+class Deployment:
+    uid: str
+    state: str
+    url: str
+    created_at: datetime
+    target: str | None = None
+
+    @classmethod
+    def from_api(cls, payload: dict) -> "Deployment":
+        return cls(
+            uid=payload.get("uid") or payload.get("id", ""),
+            state=payload.get("readyState") or payload.get("state", "UNKNOWN"),
+            url=payload.get("url", ""),
+            created_at=datetime.fromtimestamp(
+                payload.get("createdAt", 0) / 1000, tz=timezone.utc),
+            target=payload.get("target"),
+        )
+
+
+@dataclass
+class EnvVar:
+    key: str
+    targets: list[str]
+    created_at: datetime
+    # The value is deliberately absent. Reading configuration must not mean
+    # pulling every client's secrets into a coding agent's context (D6).
+
+
+class Vercel:
+    """One client's Vercel account, reached through their container."""
+
+    name = "vercel"
+
+    def __init__(self, container: Container, team_id: str = "") -> None:
+        self._container = container
+        self._team = team_id
+
+    def _params(self, **extra) -> dict:
+        params = {k: v for k, v in extra.items() if v not in (None, "")}
+        if self._team:
+            params["teamId"] = self._team
+        return params
+
+    async def _get(self, path: str, **params):
+        async with self._container.http("vercel") as http:
+            response = await http.get(path, params=self._params(**params))
+        if response.status_code >= 400:
+            raise VercelError(
+                f"Vercel returned {response.status_code} for {path}: "
+                f"{response.json().get('error', {}).get('message', response.text[:120])}"
+            )
+        return response.json()
+
+    async def projects(self) -> list[dict]:
+        payload = await self._get("/v9/projects", limit=100)
+        return [{"id": p["id"], "name": p["name"],
+                 "framework": p.get("framework"),
+                 "updated": p.get("updatedAt")}
+                for p in payload.get("projects", [])]
+
+    async def deployments(self, project: str, limit: int = 10) -> list[Deployment]:
+        payload = await self._get("/v6/deployments", projectId=project, limit=limit)
+        return [Deployment.from_api(d) for d in payload.get("deployments", [])]
+
+    async def env_vars(self, project: str) -> list[EnvVar]:
+        """Names and scopes only; never values."""
+        payload = await self._get(f"/v9/projects/{project}/env")
+        return [
+            EnvVar(key=e["key"], targets=e.get("target", []),
+                   created_at=datetime.fromtimestamp(
+                       e.get("createdAt", 0) / 1000, tz=timezone.utc))
+            for e in payload.get("envs", [])
+        ]
+
+    async def check_deploy_current(self, project: str) -> CheckResult:
+        """Is the site people see the site you last built?"""
+        deployments = await self.deployments(project, limit=10)
+        production = [d for d in deployments if d.target == "production"]
+        if not production:
+            return CheckResult("deploy_current", "skip",
+                               "No production deployment yet.", "")
+        latest = production[0]
+        if latest.state == "READY":
+            return CheckResult("deploy_current", "pass",
+                               f"Production is {latest.state}, deployed "
+                               f"{latest.created_at:%d %b %Y}.",
+                               "The site your customers see is the latest version.",
+                               evidence=latest.url)
+        failed = [d for d in production if d.state in ("ERROR", "CANCELED")]
+        return CheckResult(
+            "deploy_current", "fail",
+            f"Latest production deployment is {latest.state}; "
+            f"{len(failed)} of the last {len(production)} failed.",
+            "Your site is still showing an older version, because recent updates "
+            "did not go live.",
+            evidence=f"{latest.uid} {latest.state} {latest.created_at:%d %b %Y}",
+            detail={"state": latest.state, "failed": len(failed)})
+
+    async def check_env_applied(self, project: str) -> CheckResult:
+        """A variable set after the last deploy has not taken effect.
+
+        Vercel bakes build-time values in, so changing one in the dashboard
+        changes nothing on the running site until a rebuild.
+        """
+        env = await self.env_vars(project)
+        production = [e for e in env if "production" in e.targets]
+        if not production:
+            return CheckResult("env_applied", "skip", "No production variables.", "")
+        deployments = [d for d in await self.deployments(project, limit=10)
+                       if d.target == "production" and d.state == "READY"]
+        if not deployments:
+            return CheckResult("env_applied", "skip", "No successful production build.", "")
+
+        last_build = deployments[0].created_at
+        stale = [e for e in production if e.created_at > last_build]
+        if not stale:
+            return CheckResult("env_applied", "pass",
+                               "Every production variable predates the last build.",
+                               "Your settings are live on the site.")
+        return CheckResult(
+            "env_applied", "fail",
+            f"{len(stale)} production variable(s) changed after the last build "
+            f"({', '.join(e.key for e in stale)}); Vercel bakes build-time values "
+            "in, so the running site still uses the old ones.",
+            "A setting was changed but never applied - your live site is still "
+            "using the previous value.",
+            detail={"stale": [e.key for e in stale]})
+
+    async def check_env_scoped(self, project: str) -> CheckResult:
+        """A variable only on Preview works when you test and is missing live."""
+        env = await self.env_vars(project)
+        preview_only = [e for e in env
+                        if "preview" in e.targets and "production" not in e.targets]
+        if not preview_only:
+            return CheckResult("env_scoped", "pass",
+                               "No variables are preview-only.",
+                               "Your settings apply to the live site, not just to tests.")
+        return CheckResult(
+            "env_scoped", "fail",
+            f"{len(preview_only)} variable(s) exist only on Preview: "
+            f"{', '.join(e.key for e in preview_only)}.",
+            "Something is configured for your test site but not the real one, so "
+            "it works when we check it and not when a customer arrives.",
+            detail={"preview_only": [e.key for e in preview_only]})

munim/agent/across.py

@@ -0,0 +1,81 @@
+"""One question, answered across every client at once.
+
+This is the capability D15 says nothing else does, and until now it was a
+deterministic DNS sweep: useful, but it could only answer questions the check
+catalogue already asked. With a session per client against the providers' own
+MCP servers, the same shape answers questions nobody wrote a check for, because
+the provider's own tools are there.
+
+The safety property is structural, not instructed. Every toolset here is built
+read-only, so a tool that changes anything is not present to be called. "Read
+across, write within" (D5) stops depending on the model doing as it is told.
+"""
+
+from strands import Agent
+
+from munim.agent.model import build_model
+from munim.remote.servers import SERVERS
+from munim.remote.storage import KeychainTokenStorage
+from munim.remote.toolsets import toolsets_for
+
+SYSTEM = """You answer one question about several clients at once.
+
+You have each client's own tools, named with that client's prefix. A tool named
+acme_ltd_* acts on Acme Ltd's account and no other. Never assume two clients
+share anything.
+
+Every tool you have is read-only. If answering would require changing something,
+say what would have to change and which client it belongs to. Do not claim you
+changed it.
+
+Name the client beside every fact. A finding without a client attached is
+useless to someone who looks after a dozen of them.
+
+Be brief. No preamble."""
+
+
+def connected_clients(clients, provider: str, backend=None) -> list:
+    """Those with a session for this provider. Asking about the rest would open
+    a browser, which is not a thing a question gets to do.
+
+    Takes client records, not names: the session is filed under the identity,
+    and looking it up by label found nothing at all once the two were split.
+    """
+    def has_session(client) -> bool:
+        key = getattr(client, "id", client)
+        store = (KeychainTokenStorage(key, provider, backend) if backend
+                 else KeychainTokenStorage(key, provider))
+        return store._read("tokens") is not None
+
+    return [c for c in clients if has_session(c)]
+
+
+async def ask(question: str, clients: list[str], *, backend=None) -> str:
+    """Answer `question` using every connected client's read-only tools."""
+    toolsets = []
+    reached: dict[str, list[str]] = {}
+    for provider in sorted(SERVERS):
+        present = connected_clients(clients, provider, backend)
+        if not present:
+            continue
+        reached[provider] = present
+        toolsets += toolsets_for(present, provider, backend=backend,
+                                 read_only=True)
+
+    if not toolsets:
+        return ("No client has a session with a provider yet, so there is "
+                "nothing to read across. Connect one with "
+                "`munim connect \"<client>\" cloudflare`.")
+
+    model, _ = build_model()
+    agent = Agent(model=model, tools=toolsets, system_prompt=SYSTEM,
+                  callback_handler=None)
+
+    roster = "\n".join(
+        f"- {p}: {', '.join(getattr(c, 'name', str(c)) for c in cs)}"
+        for p, cs in sorted(reached.items()))
+    reply = await agent.invoke_async(
+        f"Clients and the providers each is connected to:\n{roster}\n\n"
+        f"Question: {question}"
+    )
+    return str(reply)