quickdbd-cli 0.1.8__tar.gz → 0.1.10__tar.gz

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.8
+Version: 0.1.10
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://github.com/MarkPhamm/quickdbd-cli
 Author: Minh (Mark) Pham
@@ -121,7 +121,7 @@ A browser tab opens with the diagram and an editor pane.
 qdbd build schema.txt -o schema.html
 ```
 
-`schema.html` is a single self-contained file. Open it locally, email it, attach it to a ticket, or publish it on GitHub Pages ([7.1](#71-github-action)).
+`schema.html` is a single self-contained file. Open it locally, email it, attach it to a ticket, or publish it on GitHub Pages ([7.1](#71-github-action)). To send a link instead of the file, see [4.4](#44-share-a-link).
 
 ### 2.5 Export an image
 
@@ -290,6 +290,25 @@ qdbd path schema/ --from Invoice --to Campaign
 
 ![Path from Invoice to Campaign](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/path.png)
 
+### 4.4 Share a link
+
+`qdbd serve`'s address only works on your machine. To send someone a **link**:
+
+```bash
+qdbd share schema.txt          # needs the GitHub CLI: brew install gh && gh auth login
+```
+
+```text
+Shared 12 tables (secret gist https://gist.github.com/you/1a2b3c…)
+Link: https://gistpreview.github.io/?1a2b3c…
+```
+
+- The link opens the full interactive page. Running `qdbd share` again updates the same link.
+- Gists are secret (link-only) by default; `--public` lists it.
+- For a **live** view while you edit, run `qdbd serve schema.txt --read-only` (no editor, nothing written to disk) behind a tunnel such as `cloudflared tunnel --url http://127.0.0.1:8765`. Never tunnel a plain `qdbd serve`: viewers could edit your files.
+
+More: [Sharing a Link](https://markphamm.github.io/quickdbd-cli/sharing/).
+
 ## 5. dbt projects
 
 ### 5.1 Generate the schema from dbt
@@ -368,7 +387,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.8
+      - uses: MarkPhamm/quickdbd-cli@v0.1.10
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -391,7 +410,7 @@ Run your dbt setup first, then let the action generate the schema:
 
 ```yaml
       # … dbt deps && dbt build && dbt docs generate
-      - uses: MarkPhamm/quickdbd-cli@v0.1.8
+      - uses: MarkPhamm/quickdbd-cli@v0.1.10
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -406,7 +425,7 @@ Commit `erd/` so pull requests can be compared with `main`. Set `dbt-check: true
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.8
+    rev: v0.1.10
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$
@@ -431,8 +450,9 @@ Builds are deterministic (no timestamps or randomness), so the output only chang
 
 ```bash
 qdbd check  PATH... [--strict]                      # validate
-qdbd serve  PATH... [--port 8765]                   # live editor + drag to arrange
+qdbd serve  PATH... [--port 8765] [--read-only]     # live editor + drag to arrange
 qdbd build  PATH... -o diagram.html                 # interactive HTML
+qdbd share  PATH... [--public]                      # publish as a gist, print a link
 qdbd export PATH... -o out.png|.svg|.drawio [--focus T --depth 1]
 qdbd layout PATH... [--reset]                       # (re)write the layout file
 qdbd path   PATH... --from A --to B                 # shortest join path + SQL JOIN

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/README.md

@@ -93,7 +93,7 @@ A browser tab opens with the diagram and an editor pane.
 qdbd build schema.txt -o schema.html
 ```
 
-`schema.html` is a single self-contained file. Open it locally, email it, attach it to a ticket, or publish it on GitHub Pages ([7.1](#71-github-action)).
+`schema.html` is a single self-contained file. Open it locally, email it, attach it to a ticket, or publish it on GitHub Pages ([7.1](#71-github-action)). To send a link instead of the file, see [4.4](#44-share-a-link).
 
 ### 2.5 Export an image
 
@@ -262,6 +262,25 @@ qdbd path schema/ --from Invoice --to Campaign
 
 ![Path from Invoice to Campaign](https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/path.png)
 
+### 4.4 Share a link
+
+`qdbd serve`'s address only works on your machine. To send someone a **link**:
+
+```bash
+qdbd share schema.txt          # needs the GitHub CLI: brew install gh && gh auth login
+```
+
+```text
+Shared 12 tables (secret gist https://gist.github.com/you/1a2b3c…)
+Link: https://gistpreview.github.io/?1a2b3c…
+```
+
+- The link opens the full interactive page. Running `qdbd share` again updates the same link.
+- Gists are secret (link-only) by default; `--public` lists it.
+- For a **live** view while you edit, run `qdbd serve schema.txt --read-only` (no editor, nothing written to disk) behind a tunnel such as `cloudflared tunnel --url http://127.0.0.1:8765`. Never tunnel a plain `qdbd serve`: viewers could edit your files.
+
+More: [Sharing a Link](https://markphamm.github.io/quickdbd-cli/sharing/).
+
 ## 5. dbt projects
 
 ### 5.1 Generate the schema from dbt
@@ -340,7 +359,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.8
+      - uses: MarkPhamm/quickdbd-cli@v0.1.10
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -363,7 +382,7 @@ Run your dbt setup first, then let the action generate the schema:
 
 ```yaml
       # … dbt deps && dbt build && dbt docs generate
-      - uses: MarkPhamm/quickdbd-cli@v0.1.8
+      - uses: MarkPhamm/quickdbd-cli@v0.1.10
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -378,7 +397,7 @@ Commit `erd/` so pull requests can be compared with `main`. Set `dbt-check: true
 ```yaml
 repos:
   - repo: https://github.com/MarkPhamm/quickdbd-cli
-    rev: v0.1.8
+    rev: v0.1.10
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$
@@ -403,8 +422,9 @@ Builds are deterministic (no timestamps or randomness), so the output only chang
 
 ```bash
 qdbd check  PATH... [--strict]                      # validate
-qdbd serve  PATH... [--port 8765]                   # live editor + drag to arrange
+qdbd serve  PATH... [--port 8765] [--read-only]     # live editor + drag to arrange
 qdbd build  PATH... -o diagram.html                 # interactive HTML
+qdbd share  PATH... [--public]                      # publish as a gist, print a link
 qdbd export PATH... -o out.png|.svg|.drawio [--focus T --depth 1]
 qdbd layout PATH... [--reset]                       # (re)write the layout file
 qdbd path   PATH... --from A --to B                 # shortest join path + SQL JOIN

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.8"
+version = "0.1.10"
 description = "Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit."
 readme = "README.md"
 license = "Apache-2.0"

quickdbd_cli-0.1.10/src/quickdbd_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.10"

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/src/quickdbd_cli/cli.py

@@ -47,7 +47,8 @@ def cmd_check(args) -> int:
     return 0 if ok else 1
 
 
-def cmd_build(args) -> int:
+def _built_page(args) -> tuple[str, dict] | int:
+    """Compile, select and lay out like `build`; returns (html, model) or an exit code."""
     from .html import render_page
 
     project = _open(args)
@@ -80,13 +81,41 @@ def cmd_build(args) -> int:
             print(f"error: {e}", file=sys.stderr)
             return 2
         raise
+    return render_page(model, pos, _title(project)), model
+
+
+def cmd_build(args) -> int:
+    res = _built_page(args)
+    if isinstance(res, int):
+        return res
+    page, model = res
     out = Path(args.output)
     out.parent.mkdir(parents=True, exist_ok=True)
-    out.write_text(render_page(model, pos, _title(project)), encoding="utf-8")
+    out.write_text(page, encoding="utf-8")
     print(f"Wrote {out} ({len(model['tables'])} tables, {len(model['rels'])} relationships)")
     return 0
 
 
+def cmd_share(args) -> int:
+    from . import share
+
+    res = _built_page(args)
+    if isinstance(res, int):
+        return res
+    page, model = res
+    key = share.share_key(args.paths, selector_expr(args.select, args.exclude))
+    try:
+        r = share.publish(page, _title(_open(args)), key, public=args.public, new=args.new)
+    except share.ShareError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    verb = "Updated" if r.updated else "Shared"
+    print(f"{verb} {len(model['tables'])} tables ({'public' if r.public else 'secret'} gist {r.gist_url})")
+    print(f"Link: {r.link}")
+    print(f"  (if that doesn't load: {r.alt_link})")
+    return 0
+
+
 def cmd_export(args) -> int:
     from . import export
 
@@ -289,7 +318,9 @@ def cmd_serve(args) -> int:
     from .serve import serve
 
     project = _open(args)
-    return serve(project, port=args.port, open_browser=not args.no_open)
+    # Without --port, a busy 8765 (e.g. a second `qdbd serve`) moves on to the next free port.
+    port, tries = (args.port, 1) if args.port is not None else (8765, 20)
+    return serve(project, port=port, open_browser=not args.no_open, read_only=args.read_only, tries=tries)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -328,6 +359,19 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--strict", action="store_true")
     sp.set_defaults(func=cmd_build)
 
+    sp = sub.add_parser("share", help="publish the diagram as a GitHub gist and print a link (needs the gh CLI)")
+    paths(sp)
+    selectors(sp)
+    sp.add_argument(
+        "--diff-base", metavar="GIT_REF", help="colour tables/columns changed since this git ref (e.g. origin/main)"
+    )
+    sp.add_argument("--by-group", action="store_true", help=BY_GROUP_HELP)
+    sp.add_argument("--layout", help="layout sidecar file (default: next to the schema)")
+    sp.add_argument("--strict", action="store_true")
+    sp.add_argument("--public", action="store_true", help="list the gist publicly (default: secret, link-only)")
+    sp.add_argument("--new", action="store_true", help="make a new gist instead of updating the last one")
+    sp.set_defaults(func=cmd_share)
+
     sp = sub.add_parser("export", help="write a PNG, SVG or draw.io file")
     paths(sp)
     sp.add_argument("-o", "--output", required=True, help="out.png, out.svg or out.drawio")
@@ -395,9 +439,14 @@ def build_parser() -> argparse.ArgumentParser:
 
     sp = sub.add_parser("serve", help="live editor: reload on save, drag tables to arrange")
     paths(sp)
-    sp.add_argument("--port", type=int, default=8765)
+    sp.add_argument("--port", type=int, help="port to listen on (default: 8765, or the next free one)")
     sp.add_argument("--layout")
     sp.add_argument("--no-open", action="store_true", help="don't open a browser")
+    sp.add_argument(
+        "--read-only",
+        action="store_true",
+        help="live view only: no editor, nothing saved; safe to share through a tunnel",
+    )
     sp.set_defaults(func=cmd_serve)
     return p
 

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/src/quickdbd_cli/html.py

@@ -92,13 +92,27 @@ FILTER_HELP = (
 )
 
 
-def render_page(model: dict, positions: dict, title: str, serve: bool = False) -> str:
+# Read-only live view: refetch the model whenever the server's version changes. Relative URLs, so it
+# also works behind a tunnel or a path prefix.
+LIVE_JS = (
+    "(function(){var v=null;new EventSource('events').onmessage=function(e){"
+    "if(v!==null&&e.data!==v)fetch('state').then(function(r){return r.json();})"
+    ".then(function(s){window.qdbdViewer.setData(s.model,s.positions);});v=e.data;};})();"
+)
+
+
+def render_page(model: dict, positions: dict, title: str, serve: bool = False, live: bool = False) -> str:
+    """The self-contained page. ``serve``: editor pane and saved dragging. ``live``: read-only, but reloads
+    when the server's schema changes (``qdbd serve --read-only``)."""
     data = {"model": model, "positions": positions, "serve": serve, "title": title}
-    hint = (
-        "Drag tables to arrange them (saved). Click a table for details. Esc clears."
-        if serve
-        else "Drag tables to rearrange (not saved). Click a table for details. Scroll to zoom, drag empty space to pan."
-    )
+    if serve:
+        hint = "Drag tables to arrange them (saved). Click a table for details. Esc clears."
+    elif live:
+        hint = "Live, read-only view: updates when the schema changes. Drag tables to rearrange (not saved)."
+    else:
+        hint = (
+            "Drag tables to rearrange (not saved). Click a table for details. Scroll to zoom, drag empty space to pan."
+        )
     body = BODY.format(side=SIDE if serve else "", count=len(model["tables"]), hint=hint, filter_help=FILTER_HELP)
     head_extra = ""
     scripts = ""
@@ -109,6 +123,8 @@ def render_page(model: dict, positions: dict, title: str, serve: bool = False) -
             f'<script src="{CODEMIRROR}/addon/mode/simple.min.js"></script>'
             f"<script>{_asset('editor.js')}</script>"
         )
+    elif live:
+        scripts = f"<script>{LIVE_JS}</script>"
     return (
         '<!doctype html>\n<html lang="en"><head><meta charset="utf-8">'
         '<meta name="viewport" content="width=device-width, initial-scale=1">'

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/src/quickdbd_cli/serve.py

@@ -3,11 +3,13 @@
 Watches the schema files (mtime polling), recompiles on change and pushes a reload event to the
 page over Server-Sent Events. Dragged table positions are saved to the layout sidecar; the
 browser editor pane writes the .txt files, refusing to overwrite a file changed on disk since
-the browser last loaded it.
+the browser last loaded it. With ``read_only`` the page is the plain viewer plus live reload, and
+the server never writes anything.
 """
 
 from __future__ import annotations
 
+import errno
 import json
 import sys
 import threading
@@ -22,8 +24,9 @@ from .project import Project, discover, display_path
 
 
 class State:
-    def __init__(self, project: Project):
+    def __init__(self, project: Project, read_only: bool = False):
         self.project = project
+        self.read_only = read_only  # never write to disk: no editor saves, no layout file
         self.lock = threading.Condition()
         self.version = 0
         self.model: dict = {"style": {}, "tables": [], "rels": [], "zoom": None, "position": None}
@@ -61,7 +64,8 @@ class State:
                 pos = layout.resolve_positions(model, base, schema.layout)
                 self.model = model
                 self.positions = {k: [v[0], v[1]] for k, v in pos.items()}
-                self.project.save_positions(model, self.positions)
+                if not self.read_only:
+                    self.project.save_positions(model, self.positions)
             self.version += 1
             self.lock.notify_all()
         if not initial:
@@ -76,6 +80,8 @@ class State:
 
     def snapshot(self) -> dict:
         with self.lock:
+            if self.read_only:  # the model only: no file text, no diagnostics
+                return {"version": self.version, "model": self.model, "positions": self.positions}
             files = []
             for f in self.files:
                 p = display_path(f)
@@ -134,7 +140,10 @@ def _handler(state: State, title: str):
         def do_GET(self) -> None:
             if self.path == "/":
                 with state.lock:
-                    page = render_page(state.model, state.positions, title, serve=True)
+                    if state.read_only:
+                        page = render_page(state.model, state.positions, title, live=True)
+                    else:
+                        page = render_page(state.model, state.positions, title, serve=True)
                 self._send(200, page.encode(), "text/html; charset=utf-8")
             elif self.path == "/state":
                 self._json(200, state.snapshot())
@@ -161,14 +170,18 @@ def _handler(state: State, title: str):
                 self._send(404, b"not found", "text/plain")
 
         def do_POST(self) -> None:
-            if self.path == "/layout":
+            if state.read_only:
+                self._json(403, {"error": "read-only"})
+            elif self.path == "/layout":
                 state.save_layout(self._body())
                 self._json(200, {"ok": True})
             else:
                 self._send(404, b"not found", "text/plain")
 
         def do_PUT(self) -> None:
-            if self.path == "/file":
+            if state.read_only:
+                self._json(403, {"error": "read-only"})
+            elif self.path == "/file":
                 b = self._body()
                 code, obj = state.write_file(b.get("path", ""), b.get("text", ""), b.get("mtime"))
                 self._json(code, obj)
@@ -178,11 +191,29 @@ def _handler(state: State, title: str):
     return Handler
 
 
-def make_server(project: Project, port: int = 8765) -> tuple[ThreadingHTTPServer, State]:
-    """Bind the HTTP server (port 0 picks a free port) without starting it."""
-    state = State(project)
+class PortInUse(OSError):
+    pass
+
+
+def make_server(
+    project: Project, port: int = 8765, read_only: bool = False, tries: int = 1
+) -> tuple[ThreadingHTTPServer, State]:
+    """Bind the HTTP server without starting it. Port 0 picks a free port; with ``tries`` > 1, a busy port
+    moves on to the next one (port, port+1, ...)."""
+    state = State(project, read_only=read_only)
     title = project.inputs[0].stem if len(project.inputs) == 1 else "diagram"
-    server = ThreadingHTTPServer(("127.0.0.1", port), _handler(state, title))
+    server = None
+    for p in range(port, port + max(tries, 1)) if port else [0]:
+        try:
+            server = ThreadingHTTPServer(("127.0.0.1", p), _handler(state, title))
+            break
+        except OSError as e:
+            if e.errno != errno.EADDRINUSE:
+                raise
+    if server is None:
+        last = port + max(tries, 1) - 1
+        span = f"ports {port}-{last} are" if last > port else f"port {port} is"
+        raise PortInUse(f"{span} already in use (another qdbd serve?); pick one with --port")
     server.daemon_threads = True
     return server, state
 
@@ -198,12 +229,22 @@ def poll_once(state: State) -> bool:
     return True
 
 
-def serve(project: Project, port: int = 8765, open_browser: bool = True) -> int:
-    server, state = make_server(project, port)
+def serve(
+    project: Project, port: int = 8765, open_browser: bool = True, read_only: bool = False, tries: int = 1
+) -> int:
+    try:
+        server, state = make_server(project, port, read_only=read_only, tries=tries)
+    except PortInUse as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
     for d in state.diagnostics:
         print(d["text"], file=sys.stderr)
     url = f"http://127.0.0.1:{server.server_address[1]}/"
-    print(f"[qdbd] serving {len(state.files)} file(s) at {url}  (layout: {display_path(project.sidecar)})")
+    if read_only:
+        print(f"[qdbd] serving {len(state.files)} file(s) read-only at {url}")
+        print(f"[qdbd] nothing is written to disk. To share it: cloudflared tunnel --url {url}")
+    else:
+        print(f"[qdbd] serving {len(state.files)} file(s) at {url}  (layout: {display_path(project.sidecar)})")
     print("[qdbd] Ctrl+C to stop", flush=True)
 
     def watch() -> None:

quickdbd_cli-0.1.10/src/quickdbd_cli/share.py

@@ -0,0 +1,109 @@
+"""`qdbd share`: publish the built page as a GitHub gist and return a link to view it.
+
+Uses the GitHub CLI (``gh api``), so it inherits the user's login. Gists are secret (unlisted) unless
+``public``. The gist made for each input/selection is remembered in the user's cache directory, so
+sharing again updates the same gist and the link stays the same.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ShareError(Exception):
+    pass
+
+
+@dataclass
+class Shared:
+    link: str  # gistpreview: renders the gist's HTML, keeps the #view part of the URL
+    alt_link: str  # githack: serves the raw file as text/html (after a one-click confirmation page)
+    gist_url: str
+    public: bool
+    updated: bool
+
+
+def share_key(paths: list[str], select: str = "") -> str:
+    return "|".join(sorted(str(Path(p).resolve()) for p in paths)) + "#" + select
+
+
+def cache_file() -> Path:
+    if os.environ.get("QDBD_CACHE_DIR"):
+        base = Path(os.environ["QDBD_CACHE_DIR"])
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "qdbd"
+    return base / "shares.json"
+
+
+def _load() -> dict:
+    try:
+        return json.loads(cache_file().read_text(encoding="utf-8"))
+    except (FileNotFoundError, ValueError):
+        return {}
+
+
+def _save(data: dict) -> None:
+    f = cache_file()
+    f.parent.mkdir(parents=True, exist_ok=True)
+    f.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _gh(method: str, endpoint: str, payload: dict) -> dict:
+    try:
+        r = subprocess.run(
+            ["gh", "api", "--method", method, endpoint, "--input", "-"],
+            input=json.dumps(payload),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        raise ShareError(
+            "qdbd share needs the GitHub CLI: install it (brew install gh), then run gh auth login"
+        ) from None
+    if r.returncode != 0:
+        msg = (r.stderr or r.stdout).strip()
+        if "auth login" in msg or "not logged" in msg.lower():
+            raise ShareError("not logged in to GitHub: run gh auth login")
+        raise ShareError(f"gh api {method} {endpoint} failed: {msg}")
+    return json.loads(r.stdout)
+
+
+def _filename(title: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", title).strip("-.") or "diagram"
+    return f"{slug}.html"
+
+
+def publish(page: str, title: str, key: str, public: bool = False, new: bool = False) -> Shared:
+    cache = _load()
+    entry = None if new else cache.get(key)
+    desc = f"qdbd ERD: {title}"
+    gist = None
+    if entry:
+        try:
+            gist = _gh(
+                "PATCH", f"/gists/{entry['id']}", {"description": desc, "files": {entry["file"]: {"content": page}}}
+            )
+        except ShareError as e:
+            if "404" not in str(e) and "Not Found" not in str(e):
+                raise
+            entry = None  # the gist was deleted: make a new one
+    updated = gist is not None
+    fname = entry["file"] if entry else _filename(title)
+    if gist is None:
+        gist = _gh("POST", "/gists", {"description": desc, "public": public, "files": {fname: {"content": page}}})
+    owner = (gist.get("owner") or {}).get("login") or ""
+    cache[key] = {"id": gist["id"], "owner": owner, "file": fname}
+    _save(cache)
+    return Shared(
+        link=f"https://gistpreview.github.io/?{gist['id']}",
+        alt_link=f"https://gist.githack.com/{owner}/{gist['id']}/raw/{fname}",
+        gist_url=gist.get("html_url", ""),
+        public=bool(gist.get("public")),
+        updated=updated,
+    )

{quickdbd_cli-0.1.8 → quickdbd_cli-0.1.10}/tests/test_serve.py

@@ -158,3 +158,72 @@ def test_events_stream_announces_versions(srv):
     poll_once(state)
     t.join(timeout=10)
     assert len(got) == 2 and got[1] > got[0]
+
+
+# ------------------------------------------------------------------ --read-only
+
+
+@pytest.fixture
+def ro(tmp_path):
+    f = tmp_path / "shop.txt"
+    f.write_text(SCHEMA)
+    server, state = make_server(Project.open([f]), port=0, read_only=True)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{server.server_address[1]}", state, f
+    server.shutdown()
+    server.server_close()
+
+
+def test_read_only_page_has_no_editor_and_reloads_live(ro):
+    base, _, _ = ro
+    code, page = call(base, "/")
+    assert code == 200 and b'id="side"' not in page and b'"serve":false' in page
+    assert b"codemirror.min.js" not in page and b"EventSource('events')" in page
+    code, st = call(base, "/state")
+    assert code == 200 and set(st) == {"version", "model", "positions"}  # no file text
+
+
+def test_read_only_refuses_writes_and_never_touches_disk(ro):
+    base, state, f = ro
+    assert not f.with_name("shop.layout.json").exists()
+    assert call(base, "/file", "PUT", {"path": display_path(f), "text": "x", "mtime": None})[0] == 403
+    assert call(base, "/layout", "POST", {"Customer": [1, 2]})[0] == 403
+    assert f.read_text() == SCHEMA
+    f.write_text(SCHEMA + "\nProduct\n-\nProductId PK int\n")
+    bump_mtime(f)
+    assert poll_once(state)
+    assert [t["name"] for t in call(base, "/state")[1]["model"]["tables"]] == ["Customer", "Order", "Product"]
+    assert not f.with_name("shop.layout.json").exists()
+
+
+# ------------------------------------------------------------------ busy ports
+
+
+def test_busy_port_moves_to_the_next_free_one(tmp_path):
+    from quickdbd_cli.serve import PortInUse
+
+    f = tmp_path / "shop.txt"
+    f.write_text(SCHEMA)
+    first, _ = make_server(Project.open([f]), port=0)
+    busy = first.server_address[1]
+    try:
+        with pytest.raises(PortInUse, match=f"port {busy} is already in use"):
+            make_server(Project.open([f]), port=busy)
+        second, _ = make_server(Project.open([f]), port=busy, tries=20)
+        assert second.server_address[1] > busy
+        second.server_close()
+    finally:
+        first.server_close()
+
+
+def test_cli_explicit_busy_port_is_a_clean_error(tmp_path, capsys):
+    from quickdbd_cli.cli import main
+
+    f = tmp_path / "shop.txt"
+    f.write_text(SCHEMA)
+    first, _ = make_server(Project.open([f]), port=0)
+    try:
+        assert main(["serve", str(f), "--no-open", "--port", str(first.server_address[1])]) == 2
+        assert "already in use" in capsys.readouterr().err
+    finally:
+        first.server_close()

quickdbd_cli-0.1.10/tests/test_share.py

@@ -0,0 +1,116 @@
+"""`qdbd share`, with `gh api` faked (no network)."""
+
+import json
+import subprocess
+
+import pytest
+
+from quickdbd_cli import share
+from quickdbd_cli.cli import main
+
+SCHEMA = "Customer\n-\nId PK int\n\nOrder\n-\nId PK int\nCustomerId int FK >- Customer.Id\n"
+
+
+class FakeGh:
+    def __init__(self):
+        self.calls = []
+        self.gists = {}
+        self.fail = None
+
+    def __call__(self, cmd, input=None, **kw):
+        assert cmd[:3] == ["gh", "api", "--method"] and cmd[-2:] == ["--input", "-"]
+        method, endpoint, payload = cmd[3], cmd[4], json.loads(input)
+        self.calls.append((method, endpoint, payload))
+        if self.fail:
+            return subprocess.CompletedProcess(cmd, 1, "", self.fail)
+        if method == "POST":
+            gid = f"g{len(self.gists) + 1}"
+            self.gists[gid] = payload
+            body = {"id": gid, "html_url": f"https://gist.github.com/me/{gid}", "public": payload["public"]}
+        else:
+            gid = endpoint.rsplit("/", 1)[1]
+            if gid not in self.gists:
+                return subprocess.CompletedProcess(cmd, 1, "", "gh: Not Found (HTTP 404)")
+            self.gists[gid]["files"].update(payload["files"])
+            body = {"id": gid, "html_url": f"https://gist.github.com/me/{gid}", "public": self.gists[gid]["public"]}
+        body["owner"] = {"login": "me"}
+        return subprocess.CompletedProcess(cmd, 0, json.dumps(body), "")
+
+
+@pytest.fixture
+def gh(monkeypatch, tmp_path):
+    fake = FakeGh()
+    monkeypatch.setattr(share.subprocess, "run", fake)
+    monkeypatch.setenv("QDBD_CACHE_DIR", str(tmp_path / "cache"))
+    return fake
+
+
+@pytest.fixture
+def schema(tmp_path):
+    f = tmp_path / "shop.txt"
+    f.write_text(SCHEMA)
+    return f
+
+
+def test_share_creates_a_secret_gist_and_prints_links(gh, schema, capsys):
+    assert main(["share", str(schema)]) == 0
+    out = capsys.readouterr().out
+    method, endpoint, payload = gh.calls[0]
+    assert (method, endpoint, payload["public"]) == ("POST", "/gists", False)
+    assert list(payload["files"]) == ["shop.html"]
+    assert payload["files"]["shop.html"]["content"].startswith("<!doctype html>")
+    assert "Shared 2 tables (secret gist https://gist.github.com/me/g1)" in out
+    assert "Link: https://gistpreview.github.io/?g1" in out
+    assert "https://gist.githack.com/me/g1/raw/shop.html" in out
+
+
+def test_sharing_again_updates_the_same_gist(gh, schema, capsys):
+    main(["share", str(schema)])
+    schema.write_text(SCHEMA + "\nProduct\n-\nId PK int\n")
+    assert main(["share", str(schema)]) == 0
+    assert [c[0] for c in gh.calls] == ["POST", "PATCH"]
+    assert gh.calls[1][1] == "/gists/g1"
+    assert "Product" in gh.gists["g1"]["files"]["shop.html"]["content"]
+    assert "Updated 3 tables" in capsys.readouterr().out
+
+
+def test_new_and_selection_make_separate_gists(gh, schema):
+    main(["share", str(schema)])
+    main(["share", str(schema), "--new"])
+    main(["share", str(schema), "-s", "Order+"])
+    assert [c[0] for c in gh.calls] == ["POST", "POST", "POST"]
+    main(["share", str(schema), "-s", "Order+"])
+    assert gh.calls[-1][:2] == ("PATCH", "/gists/g3")
+
+
+def test_deleted_gist_is_recreated(gh, schema):
+    main(["share", str(schema)])
+    gh.gists.clear()
+    assert main(["share", str(schema)]) == 0
+    assert [c[0] for c in gh.calls] == ["POST", "PATCH", "POST"]
+
+
+def test_public_flag(gh, schema, capsys):
+    main(["share", str(schema), "--public"])
+    assert gh.calls[0][2]["public"] is True
+    assert "(public gist" in capsys.readouterr().out
+
+
+def test_errors(gh, schema, capsys, monkeypatch):
+    gh.fail = "To get started with GitHub CLI, please run:  gh auth login"
+    assert main(["share", str(schema)]) == 2
+    assert "run gh auth login" in capsys.readouterr().err
+
+    def missing(*a, **k):
+        raise FileNotFoundError
+
+    monkeypatch.setattr(share.subprocess, "run", missing)
+    assert main(["share", str(schema)]) == 2
+    assert "needs the GitHub CLI" in capsys.readouterr().err
+
+
+def test_schema_errors_stop_before_uploading(gh, tmp_path):
+    f = tmp_path / "bad.txt"
+    f.write_text("A\n-\nId int FK >- Nope.Id\n")
+    assert main(["share", str(f)]) == 1
+    assert gh.calls == []

quickdbd_cli-0.1.8/src/quickdbd_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.8"