morphdb 0.1.2__tar.gz → 0.1.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.2
+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
@@ -126,63 +237,6 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-```bash
-pip install morphdb
-```
-
-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`.
-
-Then: `curl http://127.0.0.1:8787/help` for a live reference.
-
-**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.
-
-## 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.2 → 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
@@ -99,63 +210,6 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-```bash
-pip install morphdb
-```
-
-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`.
-
-Then: `curl http://127.0.0.1:8787/help` for a live reference.
-
-**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.
-
-## 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.2 → 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.2"
+__version__ = "0.1.3"

{morphdb-0.1.2 → morphdb-0.1.3}/morphdb/cli/__init__.py

@@ -6,12 +6,14 @@ 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 run          run in the foreground (blocking; for dev)
-    morphdb dashboard    open a read-only web view of every app + its tables
+    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

{morphdb-0.1.2 → morphdb-0.1.3}/morphdb/cli/main.py

@@ -1,17 +1,20 @@
 """``morphdb`` console-script entry point: a small process/admin CLI.
 
-    morphdb            start the server in the background (alias of `start`)
-    morphdb start      start the server in the background
-    morphdb status     show whether it is running, where, and how many apps
-    morphdb stop       stop the background server
-    morphdb run        run the server in the foreground (blocking)
-    morphdb dashboard  open the read-only admin dashboard
+    morphdb               start the server in the background (alias of `start`)
+    morphdb start         start the server in the background
+    morphdb status        show whether it is running, where, and how many apps
+    morphdb stop          stop the background server
+    morphdb logs          show the background server's log (-f to follow)
+    morphdb run           run the server in the foreground (blocking)
+    morphdb dashboard     open the read-only admin dashboard
+    morphdb install-skill install the bundled Claude Code skill
 
 ``python -m morphdb`` remains the plain foreground server (what `start` and the
 skill spawn under the hood); this CLI only wraps it.
 """
 
 import argparse
+import os
 import sys
 
 from . import dashboard, service
@@ -60,6 +63,39 @@ def cmd_stop(args):
     return 0
 
 
+def cmd_logs(args):
+    path = service.log_file()
+    if not os.path.exists(path):
+        print(f"No log yet at {path}. Has the server run? Try `morphdb start`.")
+        return 1
+    with open(path, "r", errors="replace") as f:
+        lines = f.readlines()
+    tail = lines[-args.lines:] if args.lines and args.lines > 0 else lines
+    sys.stdout.write("".join(tail))
+    if tail and not tail[-1].endswith("\n"):
+        sys.stdout.write("\n")
+    if args.follow:
+        _follow(path)
+    return 0
+
+
+def _follow(path):
+    """Stream new lines appended to the log, like `tail -f`, until Ctrl-C."""
+    import time
+    with open(path, "r", errors="replace") as f:
+        f.seek(0, os.SEEK_END)
+        try:
+            while True:
+                line = f.readline()
+                if line:
+                    sys.stdout.write(line)
+                    sys.stdout.flush()
+                else:
+                    time.sleep(0.3)
+        except KeyboardInterrupt:
+            pass
+
+
 def cmd_dashboard(args):
     dashboard.serve(args.db or service.default_db(), port=args.port,
                     open_browser=not args.no_open)
@@ -68,16 +104,14 @@ def cmd_dashboard(args):
 
 def cmd_install_skill(args):
     try:
-        dest = skill_mod.install_skill(project=args.project, force=args.force)
-    except FileExistsError as e:
-        print(f"Skill already installed at {e}. Re-run with --force to overwrite.")
-        return 1
+        dest, existed = skill_mod.install_skill(project=args.project)
     except (FileNotFoundError, OSError) as e:
         print(f"Could not install skill: {e}")
         return 1
-    where = "this project" if args.project else "your home (~/.claude)"
-    print(f"Installed the 'morphdb' Claude skill to {dest}\n"
-          f"  ({where}). Restart Claude Code (or reload skills) to pick it up.")
+    verb = "Updated" if existed else "Installed"
+    where = "this project" if args.project else "~/.claude"
+    print(f"{verb} the 'morphdb' Claude skill at {dest} ({where}).\n"
+          f"  Restart Claude Code (or reload skills) to pick it up.")
     return 0
 
 
@@ -112,6 +146,13 @@ def build_parser():
     sub.add_parser("stop", help="stop the background server"
                    ).set_defaults(func=cmd_stop)
 
+    sp = sub.add_parser("logs", help="show the background server's log")
+    sp.add_argument("-n", "--lines", type=int, default=200,
+                    help="number of trailing lines to show (default 200)")
+    sp.add_argument("-f", "--follow", action="store_true",
+                    help="stream new log lines until Ctrl-C")
+    sp.set_defaults(func=cmd_logs)
+
     sp = sub.add_parser("dashboard", help="open the read-only admin dashboard")
     sp.add_argument("--port", type=int, default=8788, help="dashboard port (default 8788)")
     sp.add_argument("--db", default=None, help="database to inspect (default the server's)")
@@ -119,12 +160,11 @@ def build_parser():
     sp.set_defaults(func=cmd_dashboard)
 
     sp = sub.add_parser("install-skill",
-                        help="install the MorphDB skill into Claude Code")
+                        help="install/update the bundled Claude Code skill")
     sp.add_argument("--project", nargs="?", const=".", default=None,
                     metavar="DIR",
                     help="install into a project's .claude (DIR, default cwd) "
                          "instead of ~/.claude")
-    sp.add_argument("--force", action="store_true", help="overwrite if it exists")
     sp.set_defaults(func=cmd_install_skill)
 
     return p

{morphdb-0.1.2 → morphdb-0.1.3}/morphdb/cli/skill.py

@@ -25,30 +25,32 @@ def _copy_tree(src, dst):
             f.write(src.read_bytes())
 
 
-def install_skill(claude_dir=None, project=None, force=False):
+def install_skill(claude_dir=None, project=None):
     """Copy the packaged skill into a `.claude/skills/morphdb` directory.
 
+    Idempotent: re-running overwrites the destination with the skill bundled in
+    the *currently installed* ``morphdb`` package, so it always lands the version
+    you have (run ``pip install -U morphdb`` first to refresh to the latest). It
+    reads from package data, not from GitHub.
+
     ``project`` (a path, or "." for cwd) installs into that project's
     ``.claude``; otherwise it installs into ``~/.claude`` (all projects).
     ``claude_dir`` overrides the `.claude` location outright (used by tests).
-    Returns the destination path. Raises FileExistsError if it already exists
-    and ``force`` is false.
+    Returns ``(dest_path, existed_before)``.
     """
     if claude_dir is None:
         base = os.path.abspath(project) if project else os.path.expanduser("~")
         claude_dir = os.path.join(base, ".claude")
     dest = os.path.join(claude_dir, "skills", SKILL_NAME)
 
-    if os.path.exists(dest) and not force:
-        raise FileExistsError(dest)
-
     src = resources.files("morphdb") / "skill"
     if not src.is_dir():
         raise FileNotFoundError(
             "packaged skill not found (morphdb/skill missing from the install).")
 
-    if os.path.exists(dest) and force:
+    existed = os.path.exists(dest)
+    if existed:
         import shutil
         shutil.rmtree(dest)
     _copy_tree(src, dest)
-    return dest
+    return dest, existed

{morphdb-0.1.2 → morphdb-0.1.3}/morphdb/skill/SKILL.md

@@ -61,8 +61,9 @@ API).
 
 **Debug tip:** if the frontend can't reach the backend (connection refused, a
 `fetch` throws) and you're running locally, the server is probably down — run
-`morphdb status`, then `morphdb start` if stopped. That's the first thing to
-check when a working app suddenly stops loading or saving data.
+`morphdb status`, then `morphdb start` if stopped, and `morphdb logs` (add `-f`
+to follow) to see errors. That's the first thing to check when a working app
+suddenly stops loading or saving data.
 
 ## Mental model
 

{morphdb-0.1.2 → morphdb-0.1.3}/morphdb.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphdb
-Version: 0.1.2
+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
@@ -126,63 +237,6 @@ curl -X PATCH $BASE/objects/user/<u> -d '{"tasks":["<t1>","<t2>"]}'
 > Scope: a localhost-scale developer tool. Not built for multi-tenant auth,
 > horizontal scale, or production durability guarantees.
 
-## Install / run
-
-```bash
-pip install morphdb
-```
-
-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`.
-
-Then: `curl http://127.0.0.1:8787/help` for a live reference.
-
-**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.
-
-## 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.2 → morphdb-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "morphdb"
-version = "0.1.2"
+version = "0.1.3"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.10"

{morphdb-0.1.2 → morphdb-0.1.3}/tests/test_cli.py

@@ -13,6 +13,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
 from morphdb import apps, db, objects, schema          # noqa: E402
 from morphdb.cli import dashboard, service              # noqa: E402
+from morphdb.cli import main as cli_main                # noqa: E402
 from morphdb.cli import skill as skill_mod              # noqa: E402
 
 
@@ -98,23 +99,54 @@ class TestDashboardGather(unittest.TestCase):
 class TestInstallSkill(unittest.TestCase):
     def test_install_copies_skill_files(self):
         d = tempfile.mkdtemp()
-        dest = skill_mod.install_skill(claude_dir=d)
+        dest, existed = skill_mod.install_skill(claude_dir=d)
+        self.assertFalse(existed)
         self.assertTrue(os.path.isfile(os.path.join(dest, "SKILL.md")))
         self.assertTrue(os.path.isfile(
             os.path.join(dest, "scripts", "morphdb_schema.py")))
-        # name + location
-        self.assertEqual(os.path.basename(dest), "morphdb")
         self.assertEqual(dest, os.path.join(d, "skills", "morphdb"))
 
-    def test_refuses_without_force_then_overwrites(self):
+    def test_reinstall_is_idempotent(self):
         d = tempfile.mkdtemp()
         skill_mod.install_skill(claude_dir=d)
-        with self.assertRaises(FileExistsError):
-            skill_mod.install_skill(claude_dir=d)
-        # force overwrites cleanly
-        dest = skill_mod.install_skill(claude_dir=d, force=True)
+        dest, existed = skill_mod.install_skill(claude_dir=d)   # re-run overwrites
+        self.assertTrue(existed)
         self.assertTrue(os.path.isfile(os.path.join(dest, "SKILL.md")))
 
 
+class TestLogs(unittest.TestCase):
+    def setUp(self):
+        self._old = os.environ.get("MORPHDB_HOME")
+        self.tmp = tempfile.mkdtemp()
+        os.environ["MORPHDB_HOME"] = self.tmp
+
+    def tearDown(self):
+        if self._old is None:
+            os.environ.pop("MORPHDB_HOME", None)
+        else:
+            os.environ["MORPHDB_HOME"] = self._old
+
+    def _run(self, argv):
+        import contextlib
+        import io
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            rc = cli_main.main(argv)
+        return rc, buf.getvalue()
+
+    def test_missing_log(self):
+        rc, out = self._run(["logs"])
+        self.assertEqual(rc, 1)
+        self.assertIn("No log yet", out)
+
+    def test_shows_tail(self):
+        with open(service.log_file(), "w") as f:
+            f.write("line1\nline2\nline3\n")
+        rc, out = self._run(["logs", "-n", "2"])
+        self.assertEqual(rc, 0)
+        self.assertIn("line3", out)
+        self.assertNotIn("line1", out)
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)