gini-toolkit 6.0.1.dev0__tar.gz

gini_toolkit-6.0.1.dev0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: gini-toolkit
+Version: 6.0.1.dev0
+Summary: GINI gBuilder — next-generation topology builder for computer networks and cloud computing experimentation
+Author: GINI Toolkit
+License: GPL-3.0-or-later
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6-Essentials>=6.6
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: agent
+Requires-Dist: mcp>=1.0; extra == "agent"
+Provides-Extra: graph
+Requires-Dist: matplotlib>=3.7; extra == "graph"
+Requires-Dist: numpy>=1.24; extra == "graph"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-qt>=4; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+
+# GINI gBuilder — next generation
+
+A ground-up rewrite of the GINI gBuilder frontend on **PySide6 (Qt 6) / Python 3**, expanding
+GINI from a computer-networks lab into an **ultimate experimentation toolkit** spanning both
+**computer networks** and **cloud computing**, with a first-class **AI agent layer** so agents can
+build, inspect, and explain topologies for students.
+
+## What's here
+
+```
+frontend-ng/
+├── pyproject.toml
+├── src/gini/
+│   ├── __main__.py          launch the app  (python -m gini)
+│   ├── domain/              pure-Python model — NO Qt
+│   │   ├── devices.py       device/element registry (networking + cloud)
+│   │   └── topology.py      Topology, DeviceInstance, Link
+│   ├── app/
+│   │   └── context.py       AppContext + typed event bus (replaces global singletons)
+│   ├── ui/
+│   │   ├── main_window.py   shell: toolbar, palette, canvas, inspector, console, assistant
+│   │   ├── canvas.py        QGraphicsView scene + node/edge items
+│   │   ├── palette.py       searchable, categorized device palette
+│   │   ├── inspector.py     tabbed property inspector
+│   │   ├── assistant.py     in-app "Ask GINI" AI assistant panel
+│   │   └── theme/
+│   │       ├── tokens.py    themeable design tokens (dark / light / brand)
+│   │       ├── manager.py   token → QSS generator + ThemeManager
+│   │       └── icons.py     license-safe flat SVG icon set, recolored per category
+│   └── agent/
+│       ├── api.py           programmatic GiniAPI: build / inspect / explain / run
+│       └── mcp_server.py    MCP server exposing GiniAPI to external agents
+└── tests/
+```
+
+## Run it
+
+```bash
+cd frontend-ng
+pip install -e .
+gbuilder                 # or:  python -m gini
+```
+
+Headless smoke test (no display needed):
+
+```bash
+QT_QPA_PLATFORM=offscreen python -m gini --selftest
+```
+
+## Status
+
+Early scaffold (Phase 2 of the evolution plan). The UI shell, themeable design system, icon
+system, the expanded device taxonomy, and the agent API/MCP scaffold are in place and runnable.
+The legacy `.gsav`/compiler/protocol services are being ported behind `services/` next.
+
+See `../GINI Project/GINI_Frontend_Evolution_Plan.md` for the full roadmap.

gini_toolkit-6.0.1.dev0/README.md

@@ -0,0 +1,56 @@
+# GINI gBuilder — next generation
+
+A ground-up rewrite of the GINI gBuilder frontend on **PySide6 (Qt 6) / Python 3**, expanding
+GINI from a computer-networks lab into an **ultimate experimentation toolkit** spanning both
+**computer networks** and **cloud computing**, with a first-class **AI agent layer** so agents can
+build, inspect, and explain topologies for students.
+
+## What's here
+
+```
+frontend-ng/
+├── pyproject.toml
+├── src/gini/
+│   ├── __main__.py          launch the app  (python -m gini)
+│   ├── domain/              pure-Python model — NO Qt
+│   │   ├── devices.py       device/element registry (networking + cloud)
+│   │   └── topology.py      Topology, DeviceInstance, Link
+│   ├── app/
+│   │   └── context.py       AppContext + typed event bus (replaces global singletons)
+│   ├── ui/
+│   │   ├── main_window.py   shell: toolbar, palette, canvas, inspector, console, assistant
+│   │   ├── canvas.py        QGraphicsView scene + node/edge items
+│   │   ├── palette.py       searchable, categorized device palette
+│   │   ├── inspector.py     tabbed property inspector
+│   │   ├── assistant.py     in-app "Ask GINI" AI assistant panel
+│   │   └── theme/
+│   │       ├── tokens.py    themeable design tokens (dark / light / brand)
+│   │       ├── manager.py   token → QSS generator + ThemeManager
+│   │       └── icons.py     license-safe flat SVG icon set, recolored per category
+│   └── agent/
+│       ├── api.py           programmatic GiniAPI: build / inspect / explain / run
+│       └── mcp_server.py    MCP server exposing GiniAPI to external agents
+└── tests/
+```
+
+## Run it
+
+```bash
+cd frontend-ng
+pip install -e .
+gbuilder                 # or:  python -m gini
+```
+
+Headless smoke test (no display needed):
+
+```bash
+QT_QPA_PLATFORM=offscreen python -m gini --selftest
+```
+
+## Status
+
+Early scaffold (Phase 2 of the evolution plan). The UI shell, themeable design system, icon
+system, the expanded device taxonomy, and the agent API/MCP scaffold are in place and runnable.
+The legacy `.gsav`/compiler/protocol services are being ported behind `services/` next.
+
+See `../GINI Project/GINI_Frontend_Evolution_Plan.md` for the full roadmap.

gini_toolkit-6.0.1.dev0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gini-toolkit"
+dynamic = ["version"]        # derived from git tags by setuptools-scm (see [tool.setuptools_scm])
+description = "GINI gBuilder — next-generation topology builder for computer networks and cloud computing experimentation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "GPL-3.0-or-later" }
+authors = [{ name = "GINI Toolkit" }]
+# `pip install gini-toolkit` gives a runnable desktop app: engine + the PySide6/Qt GUI. The
+# container runtime (Docker/Colima) and images are brought in separately by the `gini-setup` command.
+dependencies = [
+    "PySide6-Essentials>=6.6",   # the Qt6 desktop GUI (gini.ui + the `gbuilder` entrypoint)
+    "PyYAML>=6.0",               # reads authored Lesson packs (Missions / Teaching Center)
+]
+
+[project.optional-dependencies]
+agent = [
+    "mcp>=1.0",          # Model Context Protocol server (in-app + external agents)
+]
+graph = [
+    "matplotlib>=3.7",   # router / instance statistics graphing
+    "numpy>=1.24",
+]
+dev = [
+    "pytest>=7",
+    "pytest-qt>=4",
+    "ruff>=0.4",
+    "mypy>=1.8",
+]
+
+[project.scripts]
+gbuilder = "gini.__main__:main"          # the desktop app
+gini-setup = "gini.setup.cli:main"       # one-time: bring in the container runtime + images
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"gini.ui" = ["assets/*.png", "assets/*.ico", "assets/*.icns"]
+"gini.domain" = ["missions/**/*.yaml"]
+
+# Version comes from git tags (e.g. `git tag v6.1.0` -> 6.1.0). The repo root is one level up from
+# this pyproject, hence root = "..". A generated _version.py is written into the package at build
+# time (gitignored). Untagged working trees get e.g. 6.1.0.dev3+g<hash>.
+[tool.setuptools_scm]
+root = ".."
+version_file = "src/gini/_version.py"
+# drop the "+g<hash>" local segment: tagged clean builds -> 6.0.0; between-tag builds -> 6.0.1.dev0
+local_scheme = "no-local-version"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gini_toolkit-6.0.1.dev0/scripts/build_kb_index.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Build the shipped semantic index for Ask GINI's L2 recall.
+
+Embeds every KB document (`agent.embed.kb_documents()`) via an Ollama `/api/embed` call and
+writes `src/gini/data/kb_index.json` (model tag + KB hash + id→vector). Run this whenever the
+concept notes, recipes, or element catalog change — a test (`test_kb_index_sync`) fails if the
+shipped index drifts from the live KB.
+
+Requires a running Ollama with the embed model pulled, e.g.:
+
+    ollama pull all-minilm
+    GINI_LLM_URL=http://localhost:11434 python scripts/build_kb_index.py
+
+Env: GINI_LLM_URL (default http://localhost:11434), GINI_EMBED_MODEL (default all-minilm).
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from gini.agent.embed import _INDEX_PATH, kb_documents, kb_hash   # noqa: E402
+from gini.agent.llm import OllamaBackend                          # noqa: E402
+
+
+def main() -> int:
+    url = os.environ.get("GINI_LLM_URL", "http://localhost:11434")
+    model = os.environ.get("GINI_EMBED_MODEL", "all-minilm")
+    backend = OllamaBackend(url, embed_model=model)
+    if not backend.available():
+        print(f"Ollama not reachable at {url} — start it and `ollama pull {model}`.")
+        return 1
+
+    docs = kb_documents()
+    ids = [d for d, _ in docs]
+    texts = [t for _, t in docs]
+    print(f"Embedding {len(texts)} KB documents with '{model}' …")
+
+    vectors: dict[str, list[float]] = {}
+    for i in range(0, len(texts), 32):                 # batch to be gentle on the server
+        chunk_ids = ids[i:i + 32]
+        chunk_vecs = backend.embed(texts[i:i + 32])
+        if len(chunk_vecs) != len(chunk_ids):
+            print(f"  embed returned {len(chunk_vecs)} vectors for {len(chunk_ids)} docs — aborting.")
+            return 2
+        for did, vec in zip(chunk_ids, chunk_vecs):
+            vectors[did] = [round(float(x), 6) for x in vec]
+
+    dim = len(next(iter(vectors.values()))) if vectors else 0
+    index = {"model": model, "dim": dim, "kb_hash": kb_hash(), "vectors": vectors}
+    _INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _INDEX_PATH.write_text(json.dumps(index))
+    print(f"Wrote {_INDEX_PATH} — {len(vectors)} vectors, dim {dim}.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gini_toolkit-6.0.1.dev0/scripts/gen_cue_shots.py

@@ -0,0 +1,193 @@
+"""Generate the Cue Cards feature-tour screenshots from the real gBuilder UI, per theme.
+
+Renders curated portions of the actual interface (no mockups) to PNGs under
+``src/gini/ui/assets/cue/<theme-slug>/<kind>.png`` — one set per theme, one image per card
+in cue_cards.FEATURE_CARDS — so the tour matches whatever theme GINI is running. Re-run
+after UI changes (best on macOS for native fonts)::
+
+    QT_QPA_PLATFORM=offscreen python -m scripts.gen_cue_shots
+"""
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from pathlib import Path
+
+os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")
+# write any settings to a throwaway home so the generator never changes the user's theme
+os.environ["GINI_HOME_DIR"] = tempfile.mkdtemp(prefix="gini-genshots-")
+
+SS = 2          # supersample factor — captures at 2x so the cards stay sharp on Retina
+
+from PySide6.QtCore import QPoint, QRectF, Qt
+from PySide6.QtGui import QImage, QPainter
+from PySide6.QtWidgets import QApplication
+
+OUT = Path(__file__).resolve().parents[1] / "src" / "gini" / "ui" / "assets" / "cue"
+THEMES = ("Dark", "Light", "GINI Brand", "High Contrast", "Sand", "Blue", "Green")
+
+
+def theme_slug(name: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", (name or "dark").lower()) or "dark"
+
+
+def _bg(theme) -> int:
+    c = theme.theme.bg
+    from gini.ui.cue_cards import _qcolor
+    return _qcolor(c).rgb()
+
+
+def _save(img: QImage, name: str, outdir: Path) -> None:
+    outdir.mkdir(parents=True, exist_ok=True)
+    img.save(str(outdir / f"{name}.png"))
+
+
+def _scene_shot(scene, name, outdir, bg, scale=2.8, pad=26) -> None:
+    rect = scene.itemsBoundingRect().adjusted(-pad, -pad, pad, pad)
+    img = QImage(max(1, int(rect.width() * scale)), max(1, int(rect.height() * scale)),
+                 QImage.Format_ARGB32)
+    img.fill(bg)
+    p = QPainter(img)
+    p.setRenderHint(QPainter.Antialiasing, True)
+    p.setRenderHint(QPainter.SmoothPixmapTransform, True)
+    p.setRenderHint(QPainter.TextAntialiasing, True)
+    scene.render(p, QRectF(img.rect()), rect); p.end()
+    _save(img, name, outdir)
+
+
+def _widget_shot(widget, name, outdir, bg, w, h) -> None:
+    # render through a painter scaled by SS so the PNG is high-res regardless of the
+    # platform's device-pixel-ratio (grab() alone is 1x offscreen on Linux).
+    widget.resize(w, h)
+    QApplication.processEvents()
+    sz = widget.size()                              # actual size (clamps to the size hint)
+    img = QImage(sz.width() * SS, sz.height() * SS, QImage.Format_ARGB32)
+    img.fill(bg)
+    p = QPainter(img)
+    p.scale(SS, SS)
+    widget.render(p, QPoint(0, 0))
+    p.end()
+    _save(img, name, outdir)
+
+
+def _clear_warnings(win) -> None:
+    win.ctx.warnings = {}
+    for n in win.canvas.scene_.nodes.values():
+        n.update()
+
+
+def _generate(win, app, outdir: Path) -> None:
+    """Render the full set of curated shots for the currently-applied theme."""
+    api = win.api
+    scene = win.canvas.scene_
+    bg = _bg(win.theme)
+
+    def reset():
+        for did in list(win.ctx.topology.devices):
+            api.remove_device(did)
+
+    # --- welcome / canvas / run: a small topology ---------------------------
+    reset()
+    h = api.add_device("host", x=-40, y=120)["id"]
+    s = api.add_device("switch", x=180, y=120)["id"]
+    r = api.add_device("router", x=400, y=120)["id"]
+    db = api.add_device("database", x=620, y=20)["id"]
+    wa = api.add_device("web_app", x=620, y=220)["id"]
+    for a, b in [(h, s), (s, r), (r, db), (r, wa)]:
+        win.ctx.topology.add_link(a, b)
+        win.ctx.bus.link_added.emit(list(win.ctx.topology.links)[-1])
+    app.processEvents(); _clear_warnings(win)
+    _scene_shot(scene, "welcome", outdir, bg)
+    _scene_shot(scene, "canvas", outdir, bg)
+    for n in scene.nodes.values():
+        n.set_status("running")
+    app.processEvents()
+    _scene_shot(scene, "run", outdir, bg)
+
+    # --- X-ray / Wizard: ghost ring around a router -------------------------
+    reset()
+    rr = api.add_device("router", x=120, y=120)["id"]
+    app.processEvents(); _clear_warnings(win)
+    try:
+        win.canvas._lp_node = scene.nodes[rr]
+        win.canvas._fire_xray(); app.processEvents()
+        _scene_shot(scene, "wizard", outdir, bg, scale=2.4)
+        win.canvas.clear_xray()
+    except Exception as e:
+        print("wizard skipped:", e)
+
+    # --- cloud & VPCs: a VPC box with services ------------------------------
+    reset()
+    vpc = api.add_device("vpc", x=20, y=20)["id"]
+    win.ctx.topology.devices[vpc].properties["Name"] = "prod"
+    api.add_device("database", x=150, y=150); api.add_device("cache", x=150, y=250)
+    app.processEvents(); _clear_warnings(win)
+    scene._on_device_changed(vpc)
+    _scene_shot(scene, "cloud", outdir, bg)
+
+    # --- serverless: the Function inspector ---------------------------------
+    reset()
+    fid = api.add_device("function")["id"]
+    api.set_property(fid, "Handler", "custom")
+    win.ctx.select(fid); win.inspector.set_live_running(True); app.processEvents()
+    _widget_shot(win.inspector, "serverless", outdir, bg, 360, 560)
+
+    # --- cost meter: the dashboard strip ------------------------------------
+    from gini.domain.pricing import bill
+    for tk in ("k8s_cluster", "pod", "function", "database", "host"):
+        api.add_device(tk)
+    win.dashboard.set_estimate(bill(win.ctx.topology, win.ctx.settings.prices))
+    app.processEvents()
+    _widget_shot(win.dashboard, "cost", outdir, bg, 760, 120)
+
+    # --- live metrics -------------------------------------------------------
+    try:
+        import math
+        from gini.ui.live_metrics import LiveMetrics
+        lm = LiveMetrics(win.theme)
+        for i in range(60):
+            lm.push(40 + 30 * math.sin(i / 6), 300 + 120 * math.sin(i / 9),
+                    50 + 40 * math.sin(i / 5), 8 + 5 * math.sin(i / 7))
+        _widget_shot(lm, "metrics", outdir, bg, 360, 300)
+    except Exception as e:
+        print("metrics skipped:", e)
+
+    # --- ask GINI: the assistant panel --------------------------------------
+    try:
+        _widget_shot(win.assistant, "ai", outdir, bg, 380, 420)
+    except Exception as e:
+        print("ai skipped:", e)
+
+    # --- settings: the tabbed dialog ----------------------------------------
+    from gini.ui.settings_dialog import SettingsDialog
+    dlg = SettingsDialog(win, win.ctx.settings)
+    _widget_shot(dlg, "settings", outdir, bg, 480, 360)
+
+    # --- router lab (best effort) -------------------------------------------
+    try:
+        reset()
+        rid = api.add_device("router")["id"]
+        win.ctx.select(rid); win._open_router_lab(rid)
+        _widget_shot(win._router_lab, "router", outdir, bg, 560, 420)
+        win._router_lab.close()
+    except Exception as e:
+        print("router skipped:", e)
+
+
+def main() -> int:
+    app = QApplication.instance() or QApplication([])
+    from gini.ui.main_window import MainWindow
+    win = MainWindow(app)
+    for name in THEMES:
+        win.theme.set_theme(name)
+        app.processEvents()
+        outdir = OUT / theme_slug(name)
+        _generate(win, app, outdir)
+        print("theme done:", name, "->", outdir.name)
+    print("all done ->", OUT)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gini_toolkit-6.0.1.dev0/scripts/image_report.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""image_report — what GINI actually ships, and what it costs.
+
+Two things worth separating, because they get conflated and they have different fixes:
+
+  * IMAGE SIZE — hurts the FIRST run on a machine (build + pull), disk, and CI. On a warm Mac with
+    the layers already cached it costs comparatively little per boot.
+  * BOOT TIME  — what a student actually feels. Driven by container create + whatever the entrypoint
+    does before it's useful (our shuttle, a database's initdb, k3s coming up), not by megabytes.
+
+So this prints BOTH: the size of every image the topology uses, and the wall-clock time from
+`docker compose up` to each service being up. Optimise what the numbers say, not what we assume.
+
+    python3 scripts/image_report.py              # sizes of every GINI image present
+    python3 scripts/image_report.py --boot       # …plus time a cold `up` of the running project
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import time
+
+# every image GINI can instantiate, and where it comes from
+GINI_BUILT = {
+    "gini-machine": "Host / Machine — python:3.12-slim + the full book toolkit (apt)",
+    "gini-fabric": "the L2 fabric (all switches multiplexed) — python:3.12-slim",
+    "gini-grouter": "Router / OVS — debian:bookworm-slim + zig + gcc (single-stage)",
+    "gini-pox": "SDN controller — python:3.9-slim + POX",
+    "gini-xv6": "Machine (xv6) — debian:bookworm-slim + riscv toolchain + qemu (single-stage)",
+    "gini-faas": "serverless runtime — python:3.12-slim + pika/nats/kafka",
+    "gini-cloudfabric": "telemetry agent — python:3.12-slim + psycopg2",
+    "gini-sg": "security group — alpine:3.20 + iptables   ← the lean one",
+}
+PULLED = {
+    "postgres:16-alpine": "Database", "redis:7-alpine": "Cache", "nginx:alpine": "Load Balancer",
+    "nats:latest": "Messaging", "nginxdemos/hello:latest": "Web App", "registry:2": "Registry",
+    "traefik:v3.1": "API Gateway / Proxy", "minio/minio:latest": "Object Store",
+    "rabbitmq:3-management-alpine": "Queue", "mongo:7": "NoSQL",
+    "redpandadata/redpanda:latest": "Stream", "prom/prometheus:latest": "Metrics",
+    "grafana/grafana:latest": "Dashboard", "jaegertracing/all-in-one:latest": "Tracing",
+    "fortio/fortio:latest": "Load Generator", "rancher/k3s:v1.30.6-k3s1": "K8s Cluster",
+    "gcr.io/cadvisor/cadvisor:v0.49.1": "container metrics",
+}
+
+
+def sh(cmd, cwd=None):
+    try:
+        r = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=60)
+        return r.returncode, (r.stdout or "") + (r.stderr or "")
+    except Exception as e:                                       # noqa: BLE001
+        return 127, str(e)
+
+
+def sizes() -> dict[str, str]:
+    code, out = sh(["docker", "images", "--format", "{{.Repository}}:{{.Tag}}\t{{.Size}}"])
+    if code != 0:
+        return {}
+    got = {}
+    for line in out.splitlines():
+        if "\t" not in line:
+            continue
+        name, size = line.split("\t", 1)
+        got[name.strip()] = size.strip()
+        got.setdefault(name.split(":")[0].strip(), size.strip())   # also match untagged lookups
+    return got
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--boot", action="store_true", help="also time the running project's services")
+    a = ap.parse_args()
+
+    have = sizes()
+    if not have:
+        print("Docker isn't answering — is it running?")
+        return 1
+
+    def table(title, entries):
+        print(f"\n\033[1m{title}\033[0m")
+        missing = []
+        for img, what in entries.items():
+            size = have.get(img) or have.get(img.split(":")[0])
+            if size is None:
+                missing.append(img)
+                continue
+            print(f"  {size:>9}   {img:<34} {what}")
+        for img in missing:
+            print(f"  {'—':>9}   {img:<34} (not built/pulled here yet)")
+
+    table("BUILT BY GINI (docker build, on your machine)", GINI_BUILT)
+    table("PULLED FROM UPSTREAM", PULLED)
+
+    print("\n\033[1mNotes\033[0m")
+    print("  · gini-machine is instantiated ONCE PER HOST — it's both the fattest and the most")
+    print("    replicated image, so it's where any optimisation pays off the most.")
+    print("  · gini-grouter and gini-xv6 are SINGLE-STAGE: the compilers (zig/gcc, riscv toolchain,")
+    print("    qemu build deps) are still inside the shipped image. A multi-stage build drops them.")
+    print("  · ':latest' tags are not reproducible — two students can get different bytes.")
+
+    if a.boot:
+        code, out = sh(["docker", "compose", "ls", "--format", "json"])
+        rows = json.loads(out or "[]") if code == 0 else []
+        running = [r for r in rows if "running" in str(r.get("Status", "")).lower()]
+        if not running:
+            print("\n(no running lab to time — start one, then re-run with --boot)")
+            return 0
+        proj = running[0]["Name"]
+        wd = (running[0].get("ConfigFiles") or "").split(",")[0].rsplit("/", 1)[0]
+        print(f"\n\033[1mBOOT TIME — restarting '{proj}' to measure\033[0m")
+        sh(["docker", "compose", "-p", proj, "down"], cwd=wd)
+        t0 = time.time()
+        code, _ = sh(["docker", "compose", "-p", proj, "up", "-d"], cwd=wd)
+        dt = time.time() - t0
+        print(f"  compose up returned in \033[1m{dt:.1f}s\033[0m (images already cached)")
+        print("  → if this is fast but the FIRST run on a fresh Mac is slow, the cost is image")
+        print("    build/pull, not boot: fix it with leaner images. If THIS is slow, the cost is")
+        print("    container startup, and leaner images will not help much.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())