morphdb 0.1.1__tar.gz → 0.1.3__tar.gz

{morphdb-0.1.1 → morphdb-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.1
+Version: 0.1.3
 Summary: A coding-agent-friendly, multi-tenant backend for vibe-coded websites. One process hosts many isolated apps; reshape each app's schema as fast as your agent iterates while the frontend keeps calling the same generic endpoints.
 Author: morphdb contributors
 License: MIT
@@ -30,21 +30,119 @@ Dynamic: license-file
 **A coding-agent-friendly, multi-tenant backend for vibe-coded websites.**
 
 Reshape the data model as fast as your coding agent iterates — the frontend
-keeps calling the same small set of generic, deterministic endpoints.
+keeps calling the same small set of generic, deterministic endpoints. One
+process hosts many isolated apps (one per site), zero dependencies, backed by
+SQLite.
 
+## Install
+
+```bash
+pip install morphdb
 ```
-   you (the coding agent)              the frontend you build
-   ──────────────────────             ──────────────────────
-   reshape the schema freely    │     calls fixed generic endpoints
-   PUT    /schema/{type}        │     POST /objects/{type}
-   GET    /schema               │     GET  /objects/{type}?field=…
-   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
-            │                                    │
-            └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
-                every call: X-App-Key: <app>
+
+Manage the local server with the `morphdb` CLI:
+
+```bash
+morphdb start          # run in the background (default 127.0.0.1:8787)
+morphdb status         # running? where? how many apps?
+morphdb stop           # stop it
+morphdb run            # run in the foreground instead (blocking)
+morphdb dashboard      # read-only web view of every app + its tables
+morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
+```
+
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
+`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+`--host`, `--port`, `--db`. From a source checkout with no install, the
+foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
+
+To upgrade later: `pip install -U morphdb`, then `morphdb stop && morphdb start`
+to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
+
+**Pointing clients at a hosted MorphDB.** Set `MORPHDB_HOST` to a full URL (e.g.
+`https://db.example.com`) and the schema CLI — plus any frontend that reads
+`window.MORPHDB_HOST` — calls that hosted server (running this same code) instead
+of localhost. It's a client-side setting that names a *backend*, not a database
+connection string.
+
+## Use it
+
+With the server running (`morphdb start`):
+
+```bash
+BASE=http://127.0.0.1:8787
+
+# 0. register an app; send its key as X-App-Key on every schema/object call
+curl -X POST $BASE/app -d '{"key":"my-site"}'
+H="X-App-Key: my-site"
+
+# 1. define types + a relation
+curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
+curl -X PUT $BASE/schema/task -H "$H" -d '{
+  "fields": {"title":"string","done":"boolean","priority":"number"},
+  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
+
+# 2. create + read + query
+U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
+curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
+curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
+curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
+
+# 3. morph the schema later — existing rows just gain the new field as null
+curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
+```
+
+See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
+
+## Command-line interface
+
+`morphdb` runs the server as a **background service** — `start` launches it
+detached and hands your terminal straight back; `status` / `stop` find it again
+via a pid file under the state dir.
+
+| Command | What it does |
+| --- | --- |
+| `morphdb` or `morphdb start` | Start the server in the background (returns immediately). |
+| `morphdb status` | Is it running? URL, pid, health, and app count. |
+| `morphdb stop` | Stop the background server. |
+| `morphdb logs` | Show the background server's log (`-n N` lines, `-f` to follow). |
+| `morphdb run` | Run in the **foreground** (blocking) instead. |
+| `morphdb dashboard` | Open a read-only web view of every app and its tables. |
+| `morphdb install-skill` | Install the bundled Claude Code skill (below). |
+| `morphdb --version` | Print the version. |
+
+`start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
+and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+`dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
+state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
+`$MORPHDB_HOME`.
+
+```bash
+morphdb start                          # background, default 127.0.0.1:8787
+morphdb start --port 9000 --db ./my.sqlite3
+morphdb status                         # -> running (pid …) at http://… [healthy]
+morphdb dashboard                      # opens http://127.0.0.1:8788
+morphdb stop
+morphdb run                            # foreground instead (Ctrl-C to quit)
+```
+
+### Install the Claude Code skill
+
+`install-skill` writes the bundled MorphDB skill into a Claude skills directory,
+so a coding agent automatically reaches for MorphDB when building a data-backed
+site:
+
+```bash
+morphdb install-skill                  # -> ~/.claude/skills/morphdb (all projects)
+morphdb install-skill --project        # -> ./.claude/skills/morphdb (current project)
+morphdb install-skill --project DIR    # -> DIR/.claude/skills/morphdb
 ```
 
+It installs the skill **bundled in the installed package** (not live from
+GitHub) and is **idempotent** — re-running overwrites with the current version.
+To get the newest skill, `pip install -U morphdb` first, then re-run. Restart
+Claude Code afterward to pick it up.
+
 ## Why
 
 AI coding agents are great at building HTML/CSS/JS frontends but thrash hard on
@@ -58,6 +156,19 @@ invalidation). Adding, removing, or retyping a field is an O(1) metadata edit
 **no migration, no row rewrite, no downtime** — regardless of how much data
 exists. Meanwhile the frontend talks to generic endpoints that never change.
 
+```
+   you (the coding agent)              the frontend you build
+   ──────────────────────             ──────────────────────
+   reshape the schema freely    │     calls fixed generic endpoints
+   PUT    /schema/{type}        │     POST /objects/{type}
+   GET    /schema               │     GET  /objects/{type}?field=…
+   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
+            │                                    │
+            └──────────────  MorphDB  ───────────┘
+            (one process · many apps · SQLite)
+                every call: X-App-Key: <app>
+```
+
 ## The shape of it
 
 One MorphDB process hosts **many apps** (one per website), fully isolated from
@@ -120,58 +231,12 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **Query layer**: filter operators, sorting, pagination — all generic.
 - **Multi-tenant by app** — one process backs many isolated sites; every call is scoped by an `X-App-Key`, and deleting an app cascades away all its data.
 - **Wide-open CORS** so any frontend origin can call it in dev.
-- **A Claude Code skill** (`skill/SKILL.md`) with a schema CLI so the agent edits the model without hand-writing curl.
+- **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
+- **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-No install required:
-
-```bash
-python3 -m morphdb --port 8787 --db ./app.sqlite3
-```
-
-Or install the console script:
-
-```bash
-pip install -e .
-morphdb --port 8787 --db ./app.sqlite3
-```
-
-Flags: `--host` (default `127.0.0.1`), `--port` (default `8787`),
-`--db` (default `morphdb.sqlite3`; use `:memory:` for ephemeral).
-
-Then: `curl http://127.0.0.1:8787/help` for a live reference.
-
-## Quickstart
-
-```bash
-BASE=http://127.0.0.1:8787
-
-# 0. register an app; send its key as X-App-Key on every schema/object call
-curl -X POST $BASE/app -d '{"key":"my-site"}'
-H="X-App-Key: my-site"
-
-# 1. define types + a relation
-curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
-curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
-  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
-
-# 2. create + read + query
-U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
-curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
-curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
-curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
-
-# 3. morph the schema later — existing rows just gain the new field as null
-curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
-```
-
-See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
-
 ## Data model
 
 | Concept | What it is |

{morphdb-0.1.1 → morphdb-0.1.3}/README.md

@@ -3,21 +3,119 @@
 **A coding-agent-friendly, multi-tenant backend for vibe-coded websites.**
 
 Reshape the data model as fast as your coding agent iterates — the frontend
-keeps calling the same small set of generic, deterministic endpoints.
+keeps calling the same small set of generic, deterministic endpoints. One
+process hosts many isolated apps (one per site), zero dependencies, backed by
+SQLite.
 
+## Install
+
+```bash
+pip install morphdb
 ```
-   you (the coding agent)              the frontend you build
-   ──────────────────────             ──────────────────────
-   reshape the schema freely    │     calls fixed generic endpoints
-   PUT    /schema/{type}        │     POST /objects/{type}
-   GET    /schema               │     GET  /objects/{type}?field=…
-   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
-            │                                    │
-            └──────────────  MorphDB  ───────────┘
-            (one process · many apps · SQLite)
-                every call: X-App-Key: <app>
+
+Manage the local server with the `morphdb` CLI:
+
+```bash
+morphdb start          # run in the background (default 127.0.0.1:8787)
+morphdb status         # running? where? how many apps?
+morphdb stop           # stop it
+morphdb run            # run in the foreground instead (blocking)
+morphdb dashboard      # read-only web view of every app + its tables
+morphdb install-skill  # install the MorphDB Claude Code skill (into ~/.claude)
+```
+
+Data lives in `~/.morphdb/data.sqlite3` (change it with `--db PATH` or
+`--db :memory:`; move the state dir with `$MORPHDB_HOME`). Server flags:
+`--host`, `--port`, `--db`. From a source checkout with no install, the
+foreground server is `python3 -m morphdb --port 8787 --db ./app.sqlite3`.
+
+To upgrade later: `pip install -U morphdb`, then `morphdb stop && morphdb start`
+to reload the new code (data in `~/.morphdb` is preserved across `0.1.x`).
+
+**Pointing clients at a hosted MorphDB.** Set `MORPHDB_HOST` to a full URL (e.g.
+`https://db.example.com`) and the schema CLI — plus any frontend that reads
+`window.MORPHDB_HOST` — calls that hosted server (running this same code) instead
+of localhost. It's a client-side setting that names a *backend*, not a database
+connection string.
+
+## Use it
+
+With the server running (`morphdb start`):
+
+```bash
+BASE=http://127.0.0.1:8787
+
+# 0. register an app; send its key as X-App-Key on every schema/object call
+curl -X POST $BASE/app -d '{"key":"my-site"}'
+H="X-App-Key: my-site"
+
+# 1. define types + a relation
+curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
+curl -X PUT $BASE/schema/task -H "$H" -d '{
+  "fields": {"title":"string","done":"boolean","priority":"number"},
+  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
+
+# 2. create + read + query
+U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
+curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
+curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
+curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
+
+# 3. morph the schema later — existing rows just gain the new field as null
+curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
+```
+
+See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
+
+## Command-line interface
+
+`morphdb` runs the server as a **background service** — `start` launches it
+detached and hands your terminal straight back; `status` / `stop` find it again
+via a pid file under the state dir.
+
+| Command | What it does |
+| --- | --- |
+| `morphdb` or `morphdb start` | Start the server in the background (returns immediately). |
+| `morphdb status` | Is it running? URL, pid, health, and app count. |
+| `morphdb stop` | Stop the background server. |
+| `morphdb logs` | Show the background server's log (`-n N` lines, `-f` to follow). |
+| `morphdb run` | Run in the **foreground** (blocking) instead. |
+| `morphdb dashboard` | Open a read-only web view of every app and its tables. |
+| `morphdb install-skill` | Install the bundled Claude Code skill (below). |
+| `morphdb --version` | Print the version. |
+
+`start` / `run` accept `--host` (default `127.0.0.1`), `--port` (default `8787`),
+and `--db` (a SQLite path or `:memory:`; default `~/.morphdb/data.sqlite3`).
+`dashboard` accepts `--port` (default `8788`), `--db`, and `--no-open`. Service
+state (pid, log, the default db) lives under `~/.morphdb` — relocate it with
+`$MORPHDB_HOME`.
+
+```bash
+morphdb start                          # background, default 127.0.0.1:8787
+morphdb start --port 9000 --db ./my.sqlite3
+morphdb status                         # -> running (pid …) at http://… [healthy]
+morphdb dashboard                      # opens http://127.0.0.1:8788
+morphdb stop
+morphdb run                            # foreground instead (Ctrl-C to quit)
+```
+
+### Install the Claude Code skill
+
+`install-skill` writes the bundled MorphDB skill into a Claude skills directory,
+so a coding agent automatically reaches for MorphDB when building a data-backed
+site:
+
+```bash
+morphdb install-skill                  # -> ~/.claude/skills/morphdb (all projects)
+morphdb install-skill --project        # -> ./.claude/skills/morphdb (current project)
+morphdb install-skill --project DIR    # -> DIR/.claude/skills/morphdb
 ```
 
+It installs the skill **bundled in the installed package** (not live from
+GitHub) and is **idempotent** — re-running overwrites with the current version.
+To get the newest skill, `pip install -U morphdb` first, then re-run. Restart
+Claude Code afterward to pick it up.
+
 ## Why
 
 AI coding agents are great at building HTML/CSS/JS frontends but thrash hard on
@@ -31,6 +129,19 @@ invalidation). Adding, removing, or retyping a field is an O(1) metadata edit
 **no migration, no row rewrite, no downtime** — regardless of how much data
 exists. Meanwhile the frontend talks to generic endpoints that never change.
 
+```
+   you (the coding agent)              the frontend you build
+   ──────────────────────             ──────────────────────
+   reshape the schema freely    │     calls fixed generic endpoints
+   PUT    /schema/{type}        │     POST /objects/{type}
+   GET    /schema               │     GET  /objects/{type}?field=…
+   DELETE /schema/{type}        │     PATCH /objects/{type}/{guid}
+            │                                    │
+            └──────────────  MorphDB  ───────────┘
+            (one process · many apps · SQLite)
+                every call: X-App-Key: <app>
+```
+
 ## The shape of it
 
 One MorphDB process hosts **many apps** (one per website), fully isolated from
@@ -93,58 +204,12 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 - **Query layer**: filter operators, sorting, pagination — all generic.
 - **Multi-tenant by app** — one process backs many isolated sites; every call is scoped by an `X-App-Key`, and deleting an app cascades away all its data.
 - **Wide-open CORS** so any frontend origin can call it in dev.
-- **A Claude Code skill** (`skill/SKILL.md`) with a schema CLI so the agent edits the model without hand-writing curl.
+- **A management CLI** — `morphdb start/status/stop`, a read-only admin dashboard, and one-command skill install.
+- **A Claude Code skill** (`morphdb/skill/SKILL.md`, install with `morphdb install-skill`) with a schema CLI so the agent edits the model without hand-writing curl.
 
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-No install required:
-
-```bash
-python3 -m morphdb --port 8787 --db ./app.sqlite3
-```
-
-Or install the console script:
-
-```bash
-pip install -e .
-morphdb --port 8787 --db ./app.sqlite3
-```
-
-Flags: `--host` (default `127.0.0.1`), `--port` (default `8787`),
-`--db` (default `morphdb.sqlite3`; use `:memory:` for ephemeral).
-
-Then: `curl http://127.0.0.1:8787/help` for a live reference.
-
-## Quickstart
-
-```bash
-BASE=http://127.0.0.1:8787
-
-# 0. register an app; send its key as X-App-Key on every schema/object call
-curl -X POST $BASE/app -d '{"key":"my-site"}'
-H="X-App-Key: my-site"
-
-# 1. define types + a relation
-curl -X PUT $BASE/schema/user -H "$H" -d '{"fields":{"name":"string"}}'
-curl -X PUT $BASE/schema/task -H "$H" -d '{
-  "fields": {"title":"string","done":"boolean","priority":"number"},
-  "relations": {"assignee":{"to":"user","cardinality":"many_to_one","inverse":"tasks"}}}'
-
-# 2. create + read + query
-U=$(curl -s -X POST $BASE/objects/user -H "$H" -d '{"name":"Ann"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["_guid"])')
-curl -X POST $BASE/objects/task -H "$H" -d "{\"title\":\"buy milk\",\"priority\":2,\"assignee\":\"$U\"}"
-curl -H "$H" "$BASE/objects/task?done=false&sort=priority&order=desc"
-curl -H "$H" "$BASE/objects/user/$U"          # → includes "tasks":[…]
-
-# 3. morph the schema later — existing rows just gain the new field as null
-curl -X PUT $BASE/schema/task -H "$H" -d '{"merge":true,"fields":{"due":"datetime"}}'
-```
-
-See `examples/todo/index.html` for a complete single-file frontend backed by MorphDB.
-
 ## Data model
 
 | Concept | What it is |

{morphdb-0.1.1 → morphdb-0.1.3}/morphdb/__init__.py

@@ -5,4 +5,4 @@ coding agent iterates, while the frontend keeps calling the same small set of
 generic, deterministic endpoints.
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.3"

morphdb-0.1.3/morphdb/cli/__init__.py

@@ -0,0 +1,24 @@
+"""MorphDB command-line interface — process management + admin dashboard.
+
+Intentionally separate from the core engine (db / schema / objects / server):
+this package only *orchestrates* a server process and offers a read-only admin
+view. It never changes how the core stores or serves data.
+
+Commands (see :mod:`morphdb.cli.main`):
+
+    morphdb               start the server in the background (alias of `start`)
+    morphdb start         same, explicit
+    morphdb status        is it running? where? how many apps?
+    morphdb stop          stop the background server
+    morphdb logs          show the server log (-f to follow)
+    morphdb run           run in the foreground (blocking; for dev)
+    morphdb dashboard     open a read-only web view of every app + its tables
+    morphdb install-skill install/update the bundled Claude Code skill
+
+Storage: the local server keeps data in a per-user SQLite file at
+``~/.morphdb/data.sqlite3`` (override the file with ``--db``, or move the state
+dir with ``$MORPHDB_HOME``). To talk to a MorphDB hosted somewhere else instead
+of a local one, point *clients* at it with ``$MORPHDB_HOST`` (a full URL) — that
+is a client-side setting, not a database connection string; the engine is always
+SQLite.
+"""

morphdb-0.1.3/morphdb/cli/dashboard.py

@@ -0,0 +1,134 @@
+"""Read-only admin dashboard: every app and its tables, in one local page.
+
+Operator-facing and local-only — it opens the SQLite file directly (read-only)
+rather than going through the HTTP API, so it can list apps without adding a
+"list apps" endpoint to the public surface (which is intentionally absent).
+"""
+
+import html
+import json
+import sqlite3
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+def gather(db):
+    """A read-only snapshot: {apps: [{app, types:[{name,fields,count}], relations, edges}]}.
+
+    Tolerates a missing/empty/locked database by returning an ``error`` string.
+    """
+    try:
+        c = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=2)
+        c.row_factory = sqlite3.Row
+    except Exception as e:
+        return {"error": f"cannot open database: {e}", "apps": []}
+    try:
+        try:
+            apps = [r["key"] for r in c.execute("SELECT key FROM apps ORDER BY key")]
+        except sqlite3.OperationalError:
+            return {"error": "no MorphDB schema in this database yet", "apps": []}
+        out = []
+        for app in apps:
+            types = []
+            for r in c.execute(
+                    "SELECT name, fields FROM object_schemas WHERE app=? ORDER BY name",
+                    (app,)):
+                try:
+                    fields = list(json.loads(r["fields"]).keys())
+                except Exception:
+                    fields = []
+                count = c.execute(
+                    "SELECT COUNT(*) FROM objects WHERE app=? AND object_type=?",
+                    (app, r["name"])).fetchone()[0]
+                types.append({"name": r["name"], "fields": fields, "count": count})
+            relations = c.execute(
+                "SELECT COUNT(*) FROM association_schemas WHERE app=?", (app,)).fetchone()[0]
+            edges = c.execute(
+                "SELECT COUNT(*) FROM associations WHERE app=?", (app,)).fetchone()[0]
+            out.append({"app": app, "types": types,
+                        "relations": relations, "edges": edges})
+        return {"apps": out}
+    finally:
+        c.close()
+
+
+_CSS = """
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+         max-width: 900px; margin: 32px auto; padding: 0 16px; }
+  header { display:flex; align-items:baseline; justify-content:space-between; gap:12px;
+           border-bottom:1px solid #8884; padding-bottom:12px; margin-bottom:20px; }
+  h1 { font-size:1.3rem; margin:0; }
+  .db { color:#888; font-size:12px; font-family:ui-monospace,Menlo,monospace; }
+  .card { border:1px solid #8884; border-radius:10px; padding:14px 16px; margin-bottom:16px; }
+  .card h2 { font-size:1.05rem; margin:0 0 2px; }
+  .meta { color:#888; font-size:12px; margin-bottom:10px; }
+  table { width:100%; border-collapse:collapse; font-size:14px; }
+  th, td { text-align:left; padding:6px 8px; border-bottom:1px solid #8882; }
+  th { color:#888; font-weight:600; font-size:12px; text-transform:uppercase; letter-spacing:.04em; }
+  td.n { text-align:right; font-variant-numeric:tabular-nums; }
+  .muted { color:#999; } .err { color:#ef4444; }
+  code { font-family:ui-monospace,Menlo,monospace; background:#8881; padding:1px 5px; border-radius:5px; }
+  footer { color:#999; font-size:12px; margin-top:24px; }
+"""
+
+
+def render(data, db):
+    esc = html.escape
+    if data.get("error"):
+        body = f"<p class='err'>{esc(data['error'])}</p>"
+    elif not data["apps"]:
+        body = "<p class='muted'>No apps registered yet. Create one with <code>POST /app</code>.</p>"
+    else:
+        cards = []
+        for a in data["apps"]:
+            if a["types"]:
+                trows = "".join(
+                    f"<tr><td><b>{esc(t['name'])}</b></td>"
+                    f"<td>{esc(', '.join(t['fields']) or '—')}</td>"
+                    f"<td class='n'>{t['count']}</td></tr>"
+                    for t in a["types"])
+            else:
+                trows = "<tr><td colspan='3' class='muted'>no types yet</td></tr>"
+            cards.append(
+                f"<section class='card'><h2>{esc(a['app'])}</h2>"
+                f"<div class='meta'>{len(a['types'])} types · "
+                f"{a['relations']} relations · {a['edges']} edges</div>"
+                "<table><thead><tr><th>type</th><th>fields</th><th>objects</th></tr></thead>"
+                f"<tbody>{trows}</tbody></table></section>")
+        body = "\n".join(cards)
+    return (
+        "<!doctype html><html><head><meta charset='utf-8'>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1'>"
+        f"<title>MorphDB admin</title><style>{_CSS}</style></head><body>"
+        f"<header><h1>MorphDB admin</h1><div class='db'>{esc(str(db))}</div></header>"
+        f"{body}<footer>read-only view · refresh to update</footer></body></html>")
+
+
+def serve(db, host="127.0.0.1", port=8788, open_browser=True):
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            body = render(gather(db), db).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *a):
+            pass
+
+    httpd = ThreadingHTTPServer((host, port), Handler)
+    url = f"http://{host}:{port}"
+    print(f"MorphDB admin dashboard: {url}\n  reading: {db}\n  Ctrl-C to stop.")
+    if open_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()