agentopolis 0.6.0__py3-none-any.whl

agentopolis/cli.py

@@ -0,0 +1,72 @@
+"""agentopolis — run from any git repo to watch agents build its city."""
+import argparse
+import subprocess
+import threading
+import time
+import webbrowser
+
+import uvicorn
+
+from . import hooks, nation, server
+
+
+def free_port(port: int) -> None:
+    holders = lambda: subprocess.run(["lsof", "-ti", f":{port}"],
+                                     capture_output=True, text=True).stdout.split()
+    pids = holders()
+    if not pids:
+        return
+    print(f"freeing port {port} (pid {', '.join(pids)})")
+    for sig in ("-TERM", "-KILL"):
+        subprocess.run(["kill", sig, *pids], capture_output=True)
+        for _ in range(20):
+            if not holders():
+                return
+            time.sleep(.1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="agentopolis",
+        description="Habbo-style visualization of Claude Code agents building your repo as a city.")
+    parser.add_argument("command", nargs="?", default="serve", choices=["serve", "attach", "detach"],
+                        help="serve the city (default), or attach/detach Claude Code hooks")
+    parser.add_argument("--repo", default=".", help="git repo to map as the city (default: cwd)")
+    parser.add_argument("--zone", help="zoning manifest (default: <repo>/.agentopolis.json, else auto-zoned)")
+    parser.add_argument("--root", help="map every git repo under this dir as a nation of cities")
+    parser.add_argument("--port", type=int, default=4242)
+    parser.add_argument("--no-open", action="store_true", help="don't open the city in a browser")
+    args = parser.parse_args()
+
+    if args.command == "attach":
+        hooks.attach(args.port)
+    elif args.command == "detach":
+        hooks.detach()
+    else:
+        free_port(args.port)
+        server.configure(args.repo, args.zone)
+        root = args.root or (nation.is_mother(args.repo) and args.repo)   # a mother repo is a nation
+        if root:
+            server.configure_nation(root, None)
+        where = f"nation: {root}" if root else f"repo: {args.repo}"
+        url = f"http://localhost:{args.port}"
+        print(f"Agentopolis {'Nation' if root else 'City'} on {url} ({where})")
+        if not hooks.is_attached():
+            print("tip: run `agentopolis attach` so Claude Code sessions report to the city")
+        if not args.no_open:
+            opener = threading.Timer(1, lambda: webbrowser.open(url))
+            opener.daemon = True
+            opener.start()
+        # SSE streams watch runner.should_exit so open browsers don't block Ctrl+C;
+        # the graceful-shutdown timeout is the backstop for any other slow request
+        runner = uvicorn.Server(uvicorn.Config(server.app, port=args.port,
+                                               log_level="warning", timeout_graceful_shutdown=2))
+        server.runner = runner
+        try:
+            runner.run()
+        except KeyboardInterrupt:           # uvicorn re-raises the Ctrl+C after shutdown
+            pass
+
+
+if __name__ == "__main__":
+    main()

agentopolis/hooks.py

@@ -0,0 +1,69 @@
+"""Attach/detach the city to Claude Code via ~/.claude/settings.json hooks.
+
+Hooks fire-and-forget to localhost with a 1s timeout, so Claude Code is
+never blocked when the city isn't running.
+"""
+import json
+from pathlib import Path
+
+SETTINGS = Path.home() / ".claude" / "settings.json"
+BACKUP = SETTINGS.with_suffix(".json.agentopolis.bak")
+EVENTS = [
+    "SessionStart",
+    "UserPromptSubmit",
+    "Notification",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "SessionEnd",
+]
+def command(port: int) -> str:
+    return (
+        f"curl -sf -m 1 -X POST http://localhost:{port}/hook "
+        "-H 'Content-Type: application/json' --data-binary @- "
+        ">/dev/null 2>&1 || true"
+    )
+
+
+def has_hotel_hook(entries: list) -> bool:
+    return any(
+        "/hook" in hook.get("command", "") and "curl" in hook.get("command", "")
+        for entry in entries
+        for hook in entry.get("hooks", [])
+    )
+
+
+def is_attached() -> bool:
+    if not SETTINGS.exists():
+        return False
+    hooks = json.loads(SETTINGS.read_text()).get("hooks", {})
+    return any(has_hotel_hook(entries) for entries in hooks.values())
+
+
+def attach(port: int = 4242) -> None:
+    settings = json.loads(SETTINGS.read_text()) if SETTINGS.exists() else {}
+    BACKUP.write_text(json.dumps(settings, indent=2))
+    hooks = settings.setdefault("hooks", {})
+    added = 0
+    for event in EVENTS:
+        entries = hooks.setdefault(event, [])
+        if not has_hotel_hook(entries):
+            entries.append({"matcher": "", "hooks": [{"type": "command", "command": command(port)}]})
+            added += 1
+    SETTINGS.write_text(json.dumps(settings, indent=2) + "\n")
+    print(f"attached {added} events ({SETTINGS}, backup at {BACKUP.name})")
+    print("new Claude Code sessions will now report to the city")
+
+
+def detach() -> None:
+    if not SETTINGS.exists():
+        return
+    settings = json.loads(SETTINGS.read_text())
+    hooks = settings.get("hooks", {})
+    for event in list(hooks):
+        hooks[event] = [e for e in hooks[event] if not has_hotel_hook([e])]
+        if not hooks[event]:
+            del hooks[event]
+    SETTINGS.write_text(json.dumps(settings, indent=2) + "\n")
+    print("detached — agentopolis hooks removed")

agentopolis/nation.py

@@ -0,0 +1,129 @@
+"""Nation view: many repos as one map, grouped into states.
+
+discover_repos() finds git repos one level under a root. summarize() reads
+cheap git stats per repo (no file-content reads, so it scales to dozens).
+load_nation() folds in an optional .agentopolis-nation.json that names the
+states (repo clusters).
+"""
+import json
+import time
+from collections import Counter
+from pathlib import Path
+
+from .seed import git, tracked
+
+PALETTE = ["#16a085", "#5b8dd9", "#c0395b", "#d4a953", "#8e5d9f",
+           "#b5651d", "#2980b9", "#4a6b5c", "#c9b78a", "#5c6b73"]
+
+FAMILY_NAMES = {
+    "backend":  "Logic Highlands",
+    "frontend": "Interface Coast",
+    "infra":    "Iron Province",
+    "data":     "The Mines",
+    "docs":     "The Scriptorium",
+    "neutral":  "The Hinterlands",
+}
+FAMILY_COLOR = {
+    "backend":  "#2980b9",
+    "frontend": "#27ae60",
+    "infra":    "#7f8c8d",
+    "data":     "#d4a953",
+    "docs":     "#c9b78a",
+    "neutral":  "#7d6b8a",
+}
+
+# extension → archetype family; picks the family with the most tracked files (assets ignored)
+FAMILY_EXT = {
+    "backend": {"py", "go", "rb", "rs", "java", "php", "cs", "kt", "scala", "ex", "clj"},
+    "frontend": {"js", "ts", "jsx", "tsx", "vue", "svelte"},
+    "docs": {"md", "rst", "txt", "adoc"},
+    "infra": {"tf", "yml", "yaml", "sh", "toml", "dockerfile"},
+    "data": {"sql", "csv", "parquet", "ipynb"},
+}
+
+
+def family_of(exts: Counter) -> str:
+    best, score = "neutral", 0
+    for fam, group in FAMILY_EXT.items():
+        n = sum(exts[e] for e in group)
+        if n > score:
+            best, score = fam, n
+    return best
+
+
+def discover_repos(root: str) -> list[str]:
+    out = []
+    for entry in sorted(Path(root).iterdir()):
+        if entry.is_symlink() or not entry.is_dir():
+            continue
+        if (entry / ".git").exists():
+            out.append(entry.name)
+    return out
+
+
+def is_mother(repo: str) -> bool:
+    """A git repo that nests ≥2 git repos of its own — a metropolis, not a city."""
+    return (Path(repo) / ".git").exists() and len(discover_repos(repo)) >= 2
+
+
+def summarize(repo: str, exclude: set | None = None) -> dict:
+    files = tracked(repo, exclude)
+    last = git(repo, "log", "-1", "--format=%ct").strip()
+    commits = git(repo, "rev-list", "--count", "HEAD").strip()
+    exts = Counter(Path(f).suffix.lstrip(".").lower() for f in files if "." in f)
+    age = round((time.time() - int(last)) / 86400) if last else 9999
+    low = [f.lower() for f in files]
+    return {"files": len(files), "commits": int(commits or 0), "age_days": age,
+            "lang": (exts.most_common(1) or [("", 0)])[0][0],
+            "family": family_of(exts),
+            "hasInfra": any(f.endswith(".tf") or f.rsplit("/", 1)[-1].startswith("dockerfile")
+                            or ".github/workflows/" in f for f in low),
+            "hasFrontend": any(f.endswith((".html", ".css", ".jsx", ".tsx", ".scss", ".vue")) for f in low),
+            "hasDocs": any(f.endswith(".md") for f in low)}
+
+
+CAPITAL = "."                                  # capital city id == the mother repo's own path
+
+
+def mother_nation(root: str) -> dict:
+    """A mother repo as a one-state metropolis: a capital (its own glue) + each subrepo a city."""
+    subs = discover_repos(root)
+    name = Path(root).resolve().name
+    cities = [{"repo": CAPITAL, "name": "⊙ capital", "state": name, **summarize(root, set(subs))}]
+    cities += [{"repo": r, "state": name, **summarize(str(Path(root) / r))} for r in subs]
+    states = [{"id": name, "name": name, "color": PALETTE[0], "repos": [CAPITAL, *subs]}]
+    return {"root": name, "states": states, "cities": cities}
+
+
+def load_nation(root: str, manifest_path: str | None) -> dict:
+    path = Path(manifest_path) if manifest_path else Path(root) / ".agentopolis-nation.json"
+    if not path.exists() and is_mother(root):   # an explicit manifest wins; a bare mother is a metropolis
+        return mother_nation(root)
+    repos = discover_repos(root)
+    man = json.loads(path.read_text()) if path.exists() else {}
+
+    summaries = {r: summarize(str(Path(root) / r)) for r in repos}
+
+    state_of, states = {}, []
+    for i, st in enumerate(man.get("states", [])):
+        members = [r for r in st["repos"] if r in repos]
+        if not members:
+            continue
+        for r in members:
+            state_of[r] = st["id"]
+        states.append({"id": st["id"], "name": st.get("name", st["id"]),
+                       "color": st.get("color", PALETTE[i % len(PALETTE)]), "repos": members})
+
+    by_family: dict[str, list[str]] = {}
+    for r in repos:
+        if r not in state_of:
+            by_family.setdefault(summaries[r]["family"], []).append(r)
+    for fam, members in sorted(by_family.items()):
+        sid = f"auto_{fam}"
+        for r in members:
+            state_of[r] = sid
+        states.append({"id": sid, "name": FAMILY_NAMES[fam],
+                       "color": FAMILY_COLOR[fam], "repos": members})
+
+    cities = [{"repo": r, "state": state_of[r], **summaries[r]} for r in repos]
+    return {"root": Path(root).resolve().name, "states": states, "cities": cities}

agentopolis/seed.py

@@ -0,0 +1,263 @@
+"""Build a city snapshot from a git repo + zoning manifest.
+
+Per building: loc (mass), commits + age (attention), centrality (how many
+other components it has co-committed with). A component may set "group": N
+to aggregate files into one building per N-segment path prefix.
+"""
+import json
+import re
+import subprocess
+import time
+from collections import Counter
+from fnmatch import fnmatch
+from pathlib import Path
+
+CLASS = re.compile(r"^\s*(export |abstract |public |final )*(class|interface|struct|trait)\b")
+IMPORT = re.compile(r"^\s*(import|from|require|use|#include)\b|=\s*require\(")
+TODO = re.compile(r"TODO|FIXME|HACK")
+FROM = re.compile(r"^\s*FROM\s+(\S+)", re.I)
+FROM_AS = re.compile(r"\bAS\s+(\S+)", re.I)
+
+# A dependency name (substring match) marks the district that declares it as a cloud client.
+DEP_CLOUDS = [
+    ("AWS", ("boto3", "botocore", "aioboto3", "aws-sdk", "aws-cdk")),
+    ("GCP", ("google-cloud", "google-api-python-client", "firebase")),
+    ("Azure", ("azure-", "@azure/")),
+    ("Cloudflare", ("cloudflare", "wrangler")),
+    ("Supabase", ("supabase",)),
+    ("Vercel", ("@vercel",)),
+    ("Stripe", ("stripe",)),
+    ("OpenAI", ("openai",)),
+    ("Anthropic", ("anthropic",)),
+    ("Clerk", ("clerk",)),
+    ("Twilio", ("twilio",)),
+    ("Sentry", ("sentry",)),
+    ("Datadog", ("datadog", "ddtrace")),
+]
+# A file (glob on full path or basename) marks the district that owns it as a cloud user.
+FILE_CLOUDS = [
+    ("GitHub Actions", ("*.github/workflows/*",)),
+    ("Terraform", ("*.tf", "*.tf.json")),
+    ("Vercel", ("vercel.json",)),
+    ("Fly.io", ("fly.toml",)),
+    ("Render", ("render.yaml", "render.yml")),
+    ("Heroku", ("procfile",)),
+    ("Netlify", ("netlify.toml",)),
+    ("Cloudflare", ("wrangler.toml", "wrangler.json", "wrangler.jsonc")),
+]
+
+
+def git(repo: str, *args: str) -> str:
+    return subprocess.run(["git", "-C", repo, *args], capture_output=True, text=True).stdout
+
+
+def tracked(repo: str, exclude: set | None = None) -> list[str]:
+    files = git(repo, "ls-files").splitlines()
+    if exclude:                                  # drop nested-repo dirs when seeding a mother's capital
+        files = [f for f in files if f.split("/", 1)[0] not in exclude]
+    return files
+
+
+def component_of(path: str, components: list) -> str | None:
+    for c in components:
+        if any(fnmatch(path, g) for g in c["globs"]):
+            return c["id"]
+    return None
+
+
+def scan(path: Path) -> tuple[int, int, int, int]:
+    loc = classes = imports = todos = 0
+    try:
+        for line in open(path, errors="ignore"):
+            loc += 1
+            if CLASS.match(line):
+                classes += 1
+            elif IMPORT.search(line):
+                imports += 1
+            if TODO.search(line):
+                todos += 1
+    except OSError:
+        pass
+    return loc, classes, imports, todos
+
+
+def parse_deps(repo: str, files: list[str]) -> list[str]:
+    import tomllib
+    found = set()
+    for f in files:
+        name = f.rsplit("/", 1)[-1].lower()
+        if name not in ("package.json", "pyproject.toml") and \
+           not (name.startswith("requirements") and name.endswith(".txt")):
+            continue
+        try:
+            text = Path(repo, f).read_text(errors="ignore")
+            if name == "package.json":
+                data = json.loads(text)
+                found |= set(data.get("dependencies", {})) | set(data.get("devDependencies", {}))
+            elif name == "pyproject.toml":
+                reqs = tomllib.loads(text).get("project", {}).get("dependencies", [])
+                found |= {re.split(r"[<>=~!\[; ]", r, 1)[0] for r in reqs}
+            else:
+                found |= {re.split(r"[<>=~!\[; ]", li.strip(), 1)[0]
+                          for li in text.splitlines() if li.strip() and li.lstrip()[0] not in "#-"}
+        except (ValueError, OSError):            # fixture/vendored manifests may be malformed
+            continue
+    return sorted(found)
+
+
+def detect_clouds(repo: str, comp: dict[str, str | None]) -> list[dict]:
+    """Fingerprint cloud providers from deps + config files; tether each to its district."""
+    real = lambda c: c and c not in ("civic", "commons")
+    files = Counter(c for c in comp.values() if c)
+    default = next((c for c, _ in files.most_common() if real(c)),
+                   files.most_common(1)[0][0] if files else None)
+    votes: dict[str, Counter] = {}
+    for f, c in comp.items():
+        name = f.rsplit("/", 1)[-1].lower()
+        is_manifest = name in ("package.json", "pyproject.toml") or \
+            (name.startswith("requirements") and name.endswith(".txt"))
+        for dep in parse_deps(repo, [f]) if is_manifest else []:
+            for label, fps in DEP_CLOUDS:
+                if any(fp in dep for fp in fps):
+                    votes.setdefault(label, Counter())[c or default] += 1
+        for label, pats in FILE_CLOUDS:
+            if any(fnmatch(f, p) or fnmatch(name, p) for p in pats):
+                votes.setdefault(label, Counter())[c or default] += 1
+    clouds = []
+    for label, counter in votes.items():
+        ranked = [cid for cid, _ in counter.most_common() if cid]
+        tether = next((c for c in ranked if real(c)), (ranked or [default])[0])
+        if tether:
+            clouds.append({"name": label, "tether": tether})
+    return clouds
+
+
+def compose_services(repo: str, f: str) -> list[str]:
+    """Service keys under a compose file's top-level `services:` block (light indent parse, no yaml dep)."""
+    try:
+        lines = Path(repo, f).read_text(errors="ignore").splitlines()
+    except OSError:
+        return []
+    out: list[str] = []
+    in_services = indent = None
+    for line in lines:
+        body = line.strip()
+        if not body or body.startswith("#"):
+            continue
+        col = len(line) - len(line.lstrip())
+        if in_services is None:
+            in_services = body == "services:" or None
+        elif col == 0:                              # dedented out of the services block
+            break
+        else:
+            indent = col if indent is None else indent
+            if col == indent and body.endswith(":"):
+                out.append(body[:-1].strip())
+    return out
+
+
+def dockerfile_images(repo: str, f: str) -> list[str]:
+    out: list[str] = []
+    stages: set[str] = set()                        # multi-stage names so `FROM builder` isn't a base image
+    try:
+        for line in open(Path(repo, f), errors="ignore"):
+            m = FROM.match(line)
+            if not m:
+                continue
+            img = m.group(1).rsplit("/", 1)[-1].split("@")[0]
+            if img.lower() != "scratch" and img not in stages and img not in out:
+                out.append(img)
+            stage = FROM_AS.search(line)
+            if stage:
+                stages.add(stage.group(1))
+    except OSError:
+        pass
+    return out
+
+
+def docker_manifest(repo: str, files) -> list[dict]:
+    """Each compose/Dockerfile as a harbor ship; its items are the services / base images it runs."""
+    arts = []
+    for f in files:
+        name = f.rsplit("/", 1)[-1].lower()
+        if "compose.y" in name:
+            arts.append({"path": f, "kind": "compose", "items": compose_services(repo, f)})
+        elif "dockerfile" in name:
+            arts.append({"path": f, "kind": "image", "items": dockerfile_images(repo, f)})
+    return arts
+
+
+def dead_files(repo: str, alive: set[str]) -> list[dict]:
+    died: dict[str, int] = {}                   # path -> deletion commit time (newest deletion wins)
+    ts = 0
+    for line in git(repo, "log", "-M", "--diff-filter=D", "--name-only", "--pretty=%ct").splitlines():
+        if line.isdigit():
+            ts = int(line)
+        elif line and line not in alive and line not in died:
+            died[line] = ts
+            if len(died) == 24:                 # cemetery plot capacity
+                break
+    born: dict[str, int] = {}                   # earliest add: newest-first log, last write is oldest
+    ts = 0
+    for line in git(repo, "log", "--diff-filter=A", "--name-only", "--pretty=%ct").splitlines():
+        if line.isdigit():
+            ts = int(line)
+        elif line in died:
+            born[line] = ts
+    return [{"path": p, "born": born.get(p), "died": d} for p, d in died.items()]
+
+
+def seed(repo: str, zone: dict, exclude: set | None = None) -> dict:
+    comp = {f: component_of(f, zone["components"]) for f in tracked(repo, exclude)}
+    files = [f for f, c in comp.items() if c]
+    group = {c["id"]: c.get("group") for c in zone["components"]}
+
+    commits = dict.fromkeys(files, 0)
+    last = dict.fromkeys(files, 0)
+    cocomp = {f: set() for f in files}
+    timestamp = 0
+    touched: list[str] = []
+    for line in git(repo, "log", "--name-only", "--pretty=%ct").splitlines() + [""]:
+        if line.isdigit() or not line:                  # commit boundary: flush previous
+            comps = {comp[f] for f in touched}
+            for f in touched:
+                commits[f] += 1
+                last[f] = max(last[f], timestamp)
+                if len(touched) <= 15:                  # mega-commits aren't coupling signal
+                    cocomp[f] |= comps - {comp[f]}
+            touched = []
+            if line.isdigit():
+                timestamp = int(line)
+        elif line in commits:
+            touched.append(line)
+
+    buildings: dict[str, dict] = {}
+    exts: dict[str, Counter] = {}
+    now = time.time()
+    for f in sorted(files):
+        depth = group[comp[f]]
+        key = "/".join(f.split("/")[:depth]) if depth else f
+        b = buildings.setdefault(key, {"path": key, "component": comp[f], "loc": 0,
+                                       "commits": 0, "centrality": 0, "age_days": 9999, "files": 0,
+                                       "classes": 0, "imports": 0, "todos": 0})
+        loc, classes, imports, todos = scan(Path(repo, f))
+        b["loc"] += loc
+        b["classes"] += classes
+        b["imports"] += imports
+        b["todos"] += todos
+        b["commits"] += commits[f]
+        b["centrality"] = max(b["centrality"], len(cocomp[f]))
+        if last[f]:
+            b["age_days"] = min(b["age_days"], round((now - last[f]) / 86400))
+        b["files"] += 1
+        exts.setdefault(key, Counter())[Path(f).suffix.lstrip(".").lower()] += 1
+    for key, b in buildings.items():
+        b["ext"] = exts[key].most_common(1)[0][0]
+
+    docker = docker_manifest(repo, comp)
+    named = {c["name"].lower() for c in zone.get("clouds", [])}    # manual clouds win
+    zone["clouds"] = zone.get("clouds", []) + \
+        [c for c in detect_clouds(repo, comp) if c["name"].lower() not in named]
+    return {"zone": zone, "buildings": list(buildings.values()),
+            "deps": parse_deps(repo, list(comp)), "docker": docker,
+            "dead": dead_files(repo, set(comp))}