@sitar_fiercer4c/skills 0.1.0

package/skills/record-api-traffic/scripts/preflight.py

@@ -0,0 +1,528 @@
+#!/usr/bin/env python3
+"""Read-only preflight for the API traffic recorder.
+
+    python3 preflight.py <repo>
+
+Reports every blocker at once instead of dying on the first one, and says who
+holds each contended port so the caller can judge whether stopping it is safe.
+
+This script never kills a process, never writes a file, never edits config —
+not in the skill, and above all not in the repo. Diagnosis only; the decision
+to stop anything belongs to the user.
+
+Exit codes:  0 = clear to launch    1 = blockers found    2 = repo not found
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parent.parent
+WORKSPACE = SKILL.parent / "record-api-traffic-workspace" / "recordings"
+RECORDER = SKILL / "scripts" / "record-api-traffic.py"
+SCHEMA_CHECK = SKILL / "scripts" / "check-schema.mjs"
+DUMP_SCRIPTS = ("dump-quotation.mjs", "dump-source-excel.mjs")
+
+SCRATCH_PREFIX = "record-api-traffic-"
+LEGACY_SCRATCH = "Backend/.mitm-run"
+CHILD_MARKER = "RECORD_API_TRAFFIC_RUN"
+
+PROXY_PORT = 7100
+BACKEND_PORT = 7101
+OUTBOUND_PORT = 7102
+FRONTEND_PROXY_PORT = 4100
+FRONTEND_PORT = 4101
+FRONTEND_OUTBOUND_PORT = 4102
+
+PORT_ROLES = (
+    (FRONTEND_PROXY_PORT, "frontend proxy"),
+    (FRONTEND_PORT, "frontend"),
+    (FRONTEND_OUTBOUND_PORT, "frontend outbound proxy"),
+    (PROXY_PORT, "backend proxy"),
+    (BACKEND_PORT, "backend"),
+    (OUTBOUND_PORT, "backend outbound proxy"),
+)
+
+MITM_CA = Path.home() / ".mitmproxy" / "mitmproxy-ca-cert.pem"
+
+OK, WARN, FAIL = "ok", "warn", "FAIL"
+
+results = []
+blockers = []
+
+
+def add(status, check, detail, fix=None):
+    results.append((status, check, detail))
+    if status == FAIL:
+        blockers.append((check, detail, fix))
+
+
+def sh(argv, timeout=8):
+    try:
+        return subprocess.run(argv, capture_output=True, text=True, timeout=timeout).stdout
+    except Exception:
+        return ""
+
+
+# --------------------------------------------------------------------------
+# process / port helpers
+# --------------------------------------------------------------------------
+
+def cmdline(pid):
+    try:
+        raw = Path(f"/proc/{pid}/cmdline").read_bytes()
+        return " ".join(raw.decode("utf-8", "replace").split("\0")).strip()
+    except OSError:
+        return ""
+
+
+def proc_cwd(pid):
+    try:
+        return os.readlink(f"/proc/{pid}/cwd")
+    except OSError:
+        return ""
+
+
+def listeners(port):
+    """[(pid, name)] listening on port, via ss."""
+    out = sh(["ss", "-ltnpH", f"sport = :{port}"])
+    found = []
+    for match in re.finditer(r'\(\("([^"]+)",pid=(\d+)', out):
+        # Linux truncates comm to 15 chars, leaving names like "next-server (v1".
+        name = re.sub(r"\s*\(\S*$", "", match.group(1))
+        found.append((int(match.group(2)), name))
+    return found
+
+
+def proc_env_has(pid, key):
+    """Is `key` set in this process's environment?
+
+    The frontend child has to run with the repo as its working directory, so
+    the cwd and argv tests below cannot tell a leftover dev server of ours
+    from one the user started by hand. The marker the recorder exports into
+    every child can.
+    """
+    try:
+        raw = Path(f"/proc/{pid}/environ").read_bytes()
+    except OSError:
+        return False
+    return any(entry.startswith(f"{key}=") for entry in
+               raw.decode("utf-8", "replace").split("\0"))
+
+
+def classify(pid, repo):
+    """Is this process part of our recorder stack, the app, or something else?
+
+    Checked before the repo test, because the recorder's own children run with
+    a temp working directory and would otherwise read as foreign.
+    """
+    argv = cmdline(pid)
+    cwd = proc_cwd(pid)
+    blob = f"{argv} {cwd}"
+    if (RECORDER.name in argv or SCRATCH_PREFIX in blob or ".mitm-run" in blob
+            or proc_env_has(pid, CHILD_MARKER)):
+        return "ours", argv
+    if str(repo) in blob:
+        return "app", argv
+    return "foreign", argv
+
+
+# --------------------------------------------------------------------------
+# checks
+# --------------------------------------------------------------------------
+
+def check_skill_scripts():
+    missing = [p.name for p in
+               [RECORDER, SCHEMA_CHECK] + [SKILL / "scripts" / n for n in DUMP_SCRIPTS]
+               if not p.exists()]
+    if missing:
+        add(FAIL, "skill scripts", f"missing: {', '.join(missing)}",
+            "The skill's own scripts/ directory is incomplete.")
+    else:
+        add(OK, "skill scripts", f"recorder, schema check and {len(DUMP_SCRIPTS)} dumps present")
+
+
+def check_schema(repo):
+    """Do the dump scripts still match the app's model?
+
+    They used to live in the repo, where a schema change and the script that
+    reads it moved in the same commit. They no longer do, so nothing keeps
+    them honest but this. Drift is quiet: a renamed field reads as undefined
+    and dump-source-excel writes an empty file rather than failing.
+    """
+    if not SCHEMA_CHECK.exists():
+        return
+    if not shutil.which("node"):
+        add(WARN, "dump scripts", "alignment unverified — node not on PATH")
+        return
+    try:
+        proc = subprocess.run(
+            ["node", str(SCHEMA_CHECK), "--repo", str(repo), "--json"],
+            capture_output=True, text=True, timeout=120,
+        )
+    except subprocess.TimeoutExpired:
+        add(WARN, "dump scripts", "alignment check timed out after 120s")
+        return
+    if proc.returncode == 2:
+        try:
+            reason = json.loads(proc.stdout)["reason"]
+        except (ValueError, KeyError):
+            reason = (proc.stderr or proc.stdout or "").strip().split("\n")[-1]
+        add(WARN, "dump scripts", f"alignment unverified — {reason}")
+        return
+    try:
+        report = json.loads(proc.stdout)
+    except ValueError:
+        add(WARN, "dump scripts", "alignment check produced no report")
+        return
+
+    bad = [c for c in report["checks"] if c["status"] == FAIL]
+    warn = [c for c in report["checks"] if c["status"] == WARN]
+    if bad:
+        detail = "; ".join(f"{c['name']}: {c['detail']}" for c in bad)
+        add(FAIL, "dump scripts", f"out of sync with the app — {detail}",
+            "Update the dump scripts in the skill to match the model before "
+            "recording, or their artifacts will be empty or wrong.")
+    elif warn:
+        detail = "; ".join(f"{c['name']}: {c['detail']}" for c in warn)
+        add(WARN, "dump scripts", f"aligned, with caveats — {detail}")
+    else:
+        add(OK, "dump scripts", f"aligned with the app model ({len(report['checks'])} checks)")
+
+
+def check_tools():
+    mitm = shutil.which("mitmdump")
+    if not mitm:
+        add(FAIL, "mitmdump", "not on PATH",
+            "Install with: pipx install mitmproxy")
+    else:
+        version = ""
+        for line in sh([mitm, "--version"]).splitlines():
+            if line.lower().startswith("mitmproxy"):
+                version = line.split()[1]
+                break
+        add(OK, "mitmdump", f"{version or 'present'} at {mitm}")
+
+    missing = [t for t in ("node", "npm") if not shutil.which(t)]
+    if missing:
+        add(FAIL, "node / npm", f"missing: {', '.join(missing)}",
+            "Install Node before recording.")
+    else:
+        node_v = sh(["node", "--version"]).strip()
+        npm_v = sh(["npm", "--version"]).strip()
+        add(OK, "node / npm", f"{node_v} / {npm_v}")
+        major = int(re.match(r"v(\d+)", node_v).group(1)) if re.match(r"v(\d+)", node_v) else 0
+        if major < 24:
+            add(WARN, "outbound proxy", f"node {node_v} ignores NODE_USE_ENV_PROXY",
+                "Outbound Graph/Datalab calls will not be recorded. Run with "
+                "--no-outbound, or upgrade Node to 24+.")
+
+    if MITM_CA.exists():
+        add(OK, "mitm CA", str(MITM_CA))
+    else:
+        add(FAIL, "mitm CA", f"{MITM_CA} missing",
+            "mitmproxy writes it on its first run. Start mitmdump once to generate "
+            "it, or launch with --no-outbound.")
+
+
+def env_map(path):
+    values = {}
+    try:
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            values[key.strip()] = val.strip()
+    except OSError:
+        pass
+    return values
+
+
+def check_backend_env(repo):
+    path = repo / "Backend" / ".env"
+    if not path.exists():
+        add(FAIL, "backend env", f"missing {path}",
+            "The backend cannot start without Backend/.env.")
+        return None
+    env = env_map(path)
+    port = env.get("PORT", "(unset)")
+    notes = [f"PORT={port}"]
+    agree = []
+    for key in ("BACKEND_PUBLIC_URL", "AZURE_REDIRECT_URI"):
+        val = env.get(key, "")
+        if val and f":{PROXY_PORT}" not in val:
+            agree.append(f"{key}={val}")
+    if agree:
+        add(WARN, "backend env",
+            f"{', '.join(notes)}; not on :{PROXY_PORT}: {'; '.join(agree)}")
+    else:
+        add(OK, "backend env",
+            f"{', '.join(notes)}; public URL and OAuth redirect on :{PROXY_PORT}")
+    return env
+
+
+def check_frontend_env(repo):
+    """The highest-value check: a frontend pointed elsewhere records nothing."""
+    path = repo / "Frontend" / ".env.local"
+    if not path.exists():
+        add(FAIL, "frontend env", f"missing {path}",
+            "Frontend/.env.local must set NEXT_PUBLIC_API_URL.")
+        return
+    url = env_map(path).get("NEXT_PUBLIC_API_URL", "")
+    if not url:
+        add(FAIL, "frontend env", "NEXT_PUBLIC_API_URL unset",
+            f"Set it to http://localhost:{PROXY_PORT}/api or the recorder is bypassed.")
+    elif f":{PROXY_PORT}" not in url:
+        add(FAIL, "frontend env", f"NEXT_PUBLIC_API_URL={url} -> bypasses the recorder",
+            f"Point it at :{PROXY_PORT}. As set, the browser talks straight to the "
+            "backend and the recording comes out empty.")
+    else:
+        add(OK, "frontend env", url)
+
+
+def check_dev_script(repo):
+    """Can the dev server be moved off :4100 so the recorder can take it?
+
+    The frontend leg needs the same trick the backend gets: the recorder binds
+    the forwarded port and the server moves one up behind it. A Next dev script
+    normally pins its own port (`next dev -H 0.0.0.0 -p 4100`), and a pinned
+    CLI flag beats $PORT -- so the recorder appends a second `-p`, which both
+    parsers Next has shipped resolve to the last occurrence. That only holds
+    for a script that actually runs `next`.
+    """
+    path = repo / "Frontend" / "package.json"
+    try:
+        script = (json.loads(path.read_text()).get("scripts") or {}).get("dev", "")
+    except (OSError, ValueError) as exc:
+        add(FAIL, "frontend dev script", f"cannot read {path}: {exc}",
+            "The recorder starts the frontend with npm run dev.")
+        return
+    if not script:
+        add(FAIL, "frontend dev script", f"no dev script in {path}",
+            "The recorder starts the frontend with npm run dev.")
+    elif "next" in script:
+        add(OK, "frontend dev script",
+            f"{script!r} -> moved to :{FRONTEND_PORT} with -p")
+    else:
+        add(WARN, "frontend dev script",
+            f"{script!r} is not a Next dev script; the port move falls back to $PORT",
+            f"If that script pins its own port it will fight the recorder for "
+            f":{FRONTEND_PROXY_PORT}. Check it, or record with --no-frontend.")
+
+
+def check_deps(repo):
+    missing = [str(p.relative_to(repo)) for p in
+               (repo / "Backend" / "node_modules", repo / "Frontend" / "node_modules")
+               if not p.exists()]
+    if missing:
+        add(FAIL, "dependencies", f"missing {', '.join(missing)}",
+            "Run npm install in the affected directory.")
+    else:
+        add(OK, "dependencies", "Backend/node_modules, Frontend/node_modules present")
+
+
+def check_ports(repo):
+    for port, role in PORT_ROLES:
+        holders = listeners(port)
+        if not holders:
+            add(OK, f"port {port} ({role})", "free")
+            continue
+        described = []
+        kinds = set()
+        evidence = ""
+        for pid, name in holders:
+            kind, argv = classify(pid, repo)
+            kinds.add(kind)
+            described.append(f"{name} pid {pid} [{kind}]")
+            if kind == "foreign" and not evidence:
+                cwd = proc_cwd(pid)
+                snippet = argv if len(argv) <= 110 else argv[:107] + "..."
+                evidence = f"\n        cwd {cwd}\n        {snippet}"
+        add(FAIL, f"port {port} ({role})", "; ".join(described) + evidence,
+            port_fix(kinds))
+
+
+def port_fix(kinds):
+    if "foreign" in kinds:
+        return ("Belongs to something outside this repo. Show the user what it is and "
+                "get explicit agreement before stopping it — it may be someone's "
+                "in-progress work.")
+    if "ours" in kinds:
+        return "Left over from an earlier recorder run; safe to offer to stop."
+    return "The app's own dev server. Offer to stop it so the recorder can take the port."
+
+
+def check_orphans(repo):
+    """Leftovers from a previous run of THIS recorder.
+
+    Bracketed pattern so pgrep does not match the shell running the pattern.
+    """
+    out = sh(["pgrep", "-af", r"[r]ecord-api-traffic\.py"])
+    lines = [l for l in out.splitlines() if l.strip()]
+    orphan_children = []
+    for pattern in (r"[s]erver\.js", r"[n]ext", r"[m]itmdump"):
+        for entry in sh(["pgrep", "-af", pattern]).splitlines():
+            pid = entry.split()[0] if entry.split() else ""
+            if not pid.isdigit():
+                continue
+            cwd = proc_cwd(int(pid))
+            # The marker catches the frontend, which runs in the repo; the cwd
+            # test catches children of a recorder too old to set one.
+            if (proc_env_has(int(pid), CHILD_MARKER)
+                    or SCRATCH_PREFIX in cwd or ".mitm-run" in cwd):
+                orphan_children.append(entry)
+    total = lines + orphan_children
+    if total:
+        add(FAIL, "previous run", f"{len(total)} orphaned process(es) still alive",
+            "These are this recorder's own leftovers; safe to offer to stop.")
+    else:
+        add(OK, "previous run", "no orphans from this recorder")
+
+
+def check_scratch(repo):
+    """The backend's working directory is a temp dir, so nothing lands in the repo."""
+    notes = []
+    legacy = repo / LEGACY_SCRATCH
+    if legacy.exists():
+        notes.append(f"{legacy} is from an older version that wrote inside the repo; "
+                     "delete it yourself — this skill will not touch the repo")
+    stale = sorted(Path(tempfile.gettempdir()).glob(f"{SCRATCH_PREFIX}*"))
+    if stale:
+        notes.append(f"{len(stale)} temp scratch dir(s) left by crashed runs, "
+                     f"e.g. {stale[0]}")
+    if notes:
+        add(WARN, "scratch dir", "; ".join(notes))
+    else:
+        add(OK, "scratch dir", "clean (created under /tmp at launch, not in the repo)")
+
+
+def check_workspace(repo):
+    """Recordings live in the skill, so a run leaves the repo untouched."""
+    slug = re.sub(r"[^a-z0-9]+", "-",
+                  "-".join(repo.parts[-2:]).lower()).strip("-")
+    target = WORKSPACE / slug
+    runs = sorted(target.glob("run-*")) if target.exists() else []
+    detail = f"{target}"
+    if runs:
+        detail += f" ({len(runs)} previous run(s), newest {runs[-1].name})"
+    else:
+        detail += " (no previous runs)"
+    add(OK, "recordings", detail)
+
+
+def check_mongo(backend_env):
+    """Atlas hosts are SRV-only: a plain A/AAAA lookup fails even when healthy."""
+    if not backend_env:
+        return
+    uri = backend_env.get("MONGODB_URI") or backend_env.get("MONGO_URI") or ""
+    if not uri:
+        add(WARN, "mongodb", "no MONGODB_URI in Backend/.env")
+        return
+    match = re.match(r"mongodb(\+srv)?://[^@]*@?([^/?,]+)", uri)
+    if not match:
+        add(WARN, "mongodb", "could not parse MONGODB_URI")
+        return
+    is_srv, host = bool(match.group(1)), match.group(2).split(":")[0]
+    if is_srv:
+        out = sh(["dig", "+short", "SRV", f"_mongodb._tcp.{host}"])
+        hosts = [l for l in out.splitlines() if l.strip()]
+        if hosts:
+            add(OK, "mongodb", f"SRV resolves, {len(hosts)} host(s)")
+        elif not shutil.which("dig"):
+            add(WARN, "mongodb", "dig not installed; cannot verify SRV")
+        else:
+            add(FAIL, "mongodb", f"SRV lookup failed for {host}",
+                "The backend will never pass its health check and the recorder "
+                "aborts after 90s. Check network/DNS or the Atlas cluster state.")
+    else:
+        port = 27017
+        if ":" in match.group(2):
+            port = int(match.group(2).split(":")[1])
+        with socket.socket() as s:
+            s.settimeout(3)
+            if s.connect_ex((host, port)) == 0:
+                add(OK, "mongodb", f"{host}:{port} reachable")
+            else:
+                add(FAIL, "mongodb", f"{host}:{port} refused",
+                    "Start MongoDB, or the backend health check will time out.")
+
+
+def check_disk(repo):
+    usage = shutil.disk_usage(repo)
+    free_gb = usage.free / 1024 ** 3
+    detail = f"{free_gb:.0f}G free on {repo}"
+    if free_gb < 1:
+        add(FAIL, "disk", detail, "Free space before recording.")
+    elif free_gb < 5:
+        add(WARN, "disk", detail + " (low)")
+    else:
+        add(OK, "disk", detail)
+
+
+# --------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(description="Read-only preflight for the recorder.")
+    parser.add_argument("repo", help="path to the app repo")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    repo = Path(args.repo).expanduser().resolve()
+    if not repo.exists():
+        print(f"repo not found: {repo}", file=sys.stderr)
+        return 2
+    if not (repo / "Backend").is_dir():
+        print(f"not an app repo (no Backend/): {repo}", file=sys.stderr)
+        return 2
+
+    check_skill_scripts()
+    check_tools()
+    backend_env = check_backend_env(repo)
+    check_frontend_env(repo)
+    check_dev_script(repo)
+    check_deps(repo)
+    check_schema(repo)
+    check_ports(repo)
+    check_orphans(repo)
+    check_scratch(repo)
+    check_workspace(repo)
+    check_mongo(backend_env)
+    check_disk(repo)
+
+    if args.json:
+        print(json.dumps({
+            "repo": str(repo),
+            "blocked": bool(blockers),
+            "checks": [{"status": s, "check": c, "detail": d} for s, c, d in results],
+            "blockers": [{"check": c, "detail": d, "fix": f} for c, d, f in blockers],
+        }, indent=2))
+        return 1 if blockers else 0
+
+    width = max(len(c) for _, c, _ in results)
+    print(f"\n  PREFLIGHT — API traffic recorder\n  {repo}\n")
+    for status, check, detail in results:
+        print(f"  {status:<4}  {check:<{width}}  {detail}")
+
+    if not blockers:
+        print("\n  Clear to launch.\n")
+        return 0
+
+    print(f"\n  {len(blockers)} blocker(s):\n")
+    for check, detail, fix in blockers:
+        print(f"  - {check}: {detail}")
+        if fix:
+            print(f"      {fix}")
+    print()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())