quickdbd-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -55,6 +55,7 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
+  - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -148,6 +149,17 @@ python scripts/gen_font_metrics.py  # regenerate font width table
 
 Design notes: `docs/superpowers/specs/2026-10-17-qdbd-design.md`.
 
+### Releasing
+
+Put PyPI credentials in `.env` (gitignored):
+
+```
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-...
+```
+
+Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `PATH="$PWD/.venv/bin:$PATH" scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
+
 ## License
 
 Apache-2.0. Bundled third-party files are listed in [NOTICE](NOTICE).

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/README.md

@@ -30,6 +30,7 @@ Not affiliated with QuickDBD. It reads the same text syntax, so schemas move fre
   - click a table to focus on it and its neighbours
   - collapse tables: full / keys only / names only
   - hover a column to highlight its relationship
+  - hover a dotted-underlined table or column to read its `#` doc comments
   - PNG/SVG export buttons
 - **Live editing:** `qdbd serve` reloads when you save, has a browser editor pane with autosave, and remembers where you drag tables.
 - **Many files, one diagram:** point it at a folder and foreign keys can cross files.
@@ -123,6 +124,17 @@ python scripts/gen_font_metrics.py  # regenerate font width table
 
 Design notes: `docs/superpowers/specs/2026-10-17-qdbd-design.md`.
 
+### Releasing
+
+Put PyPI credentials in `.env` (gitignored):
+
+```
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-...
+```
+
+Bump `version` in `pyproject.toml` and `src/quickdbd_cli/__init__.py`, commit, then run `PATH="$PWD/.venv/bin:$PATH" scripts/release.sh`. It builds, uploads to PyPI, tags `vX.Y.Z` and creates the GitHub release.
+
 ## License
 
 Apache-2.0. Bundled third-party files are listed in [NOTICE](NOTICE).

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/examples/synthetic/qdbd.layout.json

@@ -29,8 +29,8 @@
       "y": 5795
     },
     "Agency": {
-      "x": 573,
-      "y": 3287
+      "x": 603,
+      "y": 3752
     },
     "Allocation": {
       "x": 1655,
@@ -245,8 +245,8 @@
       "y": 5393
     },
     "EmailOpen": {
-      "x": 3473,
-      "y": 2776
+      "x": 3395,
+      "y": 2767
     },
     "EmailSend": {
       "x": 1927,
@@ -325,8 +325,8 @@
       "y": 4608
     },
     "Holiday": {
-      "x": 3334,
-      "y": 3050
+      "x": 3280,
+      "y": 3035
     },
     "Impression": {
       "x": 2544,
@@ -393,8 +393,8 @@
       "y": 6657
     },
     "Ledger": {
-      "x": 3583,
-      "y": 2235
+      "x": 3541,
+      "y": 2427
     },
     "LedgerEntry": {
       "x": 2512,
@@ -573,16 +573,16 @@
       "y": 3695
     },
     "Reseller": {
-      "x": 3051,
-      "y": 2797
+      "x": 3043,
+      "y": 2791
     },
     "Reservation": {
       "x": 3614,
       "y": 1303
     },
     "Return": {
-      "x": 1231,
-      "y": 3991
+      "x": 1113,
+      "y": 3858
     },
     "Review": {
       "x": 604,
@@ -761,8 +761,8 @@
       "y": 5153
     },
     "hr.Training": {
-      "x": 1115,
-      "y": 4126
+      "x": 1357,
+      "y": 3813
     },
     "inventory.Container": {
       "x": 2503,

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.0"
+version = "0.1.2"
 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.2/scripts/release.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Build and upload the current version to PyPI using credentials from .env,
+# then tag and create the GitHub release.
+# Usage: bump `version` in pyproject.toml and src/quickdbd_cli/__init__.py, commit, then run
+#   PATH="$PWD/.venv/bin:$PATH" scripts/release.sh
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+[ -f .env ] || { echo "error: .env with TWINE_USERNAME/TWINE_PASSWORD not found" >&2; exit 1; }
+set -a; . ./.env; set +a
+
+version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+[ -z "$(git status --porcelain --untracked-files=no)" ] || { echo "error: uncommitted changes" >&2; exit 1; }
+
+rm -rf dist
+# uv-created venvs have no pip; only install the tools when they're missing.
+python3 -c "import build, twine" 2>/dev/null || {
+  if command -v uv >/dev/null; then uv pip install -q --python "$(command -v python3)" build twine
+  else python3 -m pip install -q --upgrade build twine; fi
+}
+python3 -m build
+python3 -m twine check dist/*
+python3 -m twine upload --non-interactive dist/*
+
+git tag -a "v$version" -m "qdbd v$version"
+git push origin "v$version"
+gh release create "v$version" dist/* --title "qdbd v$version" --generate-notes
+echo "Released v$version: https://pypi.org/project/quickdbd-cli/$version/"

quickdbd_cli-0.1.2/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/assets/render.js

@@ -66,13 +66,22 @@
       '<path d="M' + n(x + 6.5) + " " + n(cy) + "h7m-2 0v3m-2.5-3v2" + '"/></g>';
   }
 
-  function renderTable(model, t, g, p) {
+  /* Dotted underline marking text that has a doc comment (interactive viewer only). */
+  function docMark(x, y, w, color) {
+    return '<line class="dm" x1="' + n(x) + '" y1="' + n(y) + '" x2="' + n(x + w) + '" y2="' + n(y) +
+      '" stroke="' + color + '" stroke-width="1" stroke-dasharray="1.5 2"/>';
+  }
+
+  function renderTable(model, t, g, p, docMarks) {
     var st = model.style, w = g.w, h = g.h, out = [];
     out.push('<g class="t" data-id="' + esc(t.id) + '" transform="translate(' + n(p[0]) + "," + n(p[1]) + ')">');
     out.push('<rect class="tb" width="' + w + '" height="' + h + '" rx="2" fill="' + C.body + '" stroke="' + C.border + '"/>');
     out.push('<path class="th" d="M0 2a2 2 0 0 1 2-2h' + (w - 4) + "a2 2 0 0 1 2 2v" + (st.headerH - 2) + "h-" + w + 'z" fill="' + C.header + '"/>');
     out.push('<text x="' + st.padX + '" y="' + n(st.headerH / 2 + st.headerSize * 0.36) + '" fill="' + C.headerText +
       '" font-family="' + FONT + '" font-size="' + st.headerSize + '">' + esc(t.name) + "</text>");
+    if (docMarks && t.doc) {
+      out.push(docMark(st.padX, st.headerH / 2 + st.headerSize * 0.36 + 3, t.nameW, "rgba(255,255,255,.7)"));
+    }
     g.cols.forEach(function (c, i) {
       var y = st.headerH + i * st.rowH, cy = y + st.rowH / 2, base = n(cy + st.rowSize * 0.36);
       var weight = c.pk || c.fk ? ' font-weight="bold"' : "";
@@ -81,6 +90,7 @@
       out.push('<rect class="rb" y="' + y + '" width="' + w + '" height="' + st.rowH + '" fill="' + C.body + '" fill-opacity="0"/>');
       out.push('<text x="' + st.padX + '" y="' + base + '" fill="' + color + '" font-family="' + FONT + '" font-size="' +
         st.rowSize + '"' + weight + ">" + esc(c.name) + "</text>");
+      if (docMarks && c.doc) out.push(docMark(st.padX, cy + st.rowSize * 0.36 + 2.5, c.nameW, color));
       var bx = st.padX + c.nameW + 6;
       c.badges.forEach(function (b) {
         var bh = st.badgeSize + 5;
@@ -164,9 +174,10 @@
     return model.rels.map(function (r) { return renderEdge(model, geo, pos, r); }).join("");
   }
 
-  function renderInner(model, pos, mode) {
-    var geo = geometry(model, mode);
-    var tables = model.tables.map(function (t) { return pos[t.id] ? renderTable(model, t, geo[t.id], pos[t.id]) : ""; }).join("");
+  /* opts.docMarks: underline tables/columns that have doc comments (viewer only, not exports). */
+  function renderInner(model, pos, mode, opts) {
+    var geo = geometry(model, mode), marks = !!(opts && opts.docMarks);
+    var tables = model.tables.map(function (t) { return pos[t.id] ? renderTable(model, t, geo[t.id], pos[t.id], marks) : ""; }).join("");
     return '<g class="edges">' + renderEdges(model, pos, mode, geo) + '</g><g class="tables">' + tables + "</g>";
   }
 

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/assets/style.css

@@ -53,6 +53,15 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .minimap svg { width: 100%; height: 100%; display: block; }
 .minimap .vpr { fill: rgba(43,87,151,.12); stroke: var(--blue); stroke-width: 1.5; vector-effect: non-scaling-stroke; }
 
+/* doc-comment tooltip */
+.tip { position: absolute; display: none; max-width: 340px; background: #23272b; color: #eee; border-radius: 6px;
+  padding: 8px 10px; font-size: 12px; line-height: 1.45; pointer-events: none; box-shadow: 0 4px 14px rgba(0,0,0,.25);
+  z-index: 5; }
+.tip.open { display: block; }
+.tip .tt { font-weight: bold; margin-bottom: 3px; }
+.tip .tt span { font-weight: normal; color: #9aa4ad; margin-left: 8px; }
+.tip .td { white-space: pre-wrap; color: #d8dde2; }
+
 .hint { position: absolute; left: 16px; bottom: 14px; color: var(--muted); font-size: 12px; }
 
 /* serve: editor pane */

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/assets/viewer.js

@@ -24,7 +24,7 @@
 
   /* ------------------------------------------------------------- render */
   function render() {
-    vp.innerHTML = Q.renderInner(S.model, S.pos, S.mode);
+    vp.innerHTML = Q.renderInner(S.model, S.pos, S.mode, { docMarks: true });
     applyFocus();
     drawMinimap();
   }
@@ -124,7 +124,50 @@
       if (t) t.classList.add("hl");
     });
   });
-  vp.addEventListener("mouseleave", clearHover);
+  vp.addEventListener("mouseleave", function () { clearHover(); hideTip(); });
+
+  /* ------------------------------------------------------------- doc-comment tooltips */
+  var tip = document.getElementById("tip");
+  function hideTip() { tip.classList.remove("open"); }
+  function showTip(ev, title, sub, doc) {
+    tip.innerHTML = "";
+    var h = document.createElement("div");
+    h.className = "tt";
+    h.textContent = title;
+    if (sub) {
+      var s = document.createElement("span");
+      s.textContent = sub;
+      h.appendChild(s);
+    }
+    var d = document.createElement("div");
+    d.className = "td";
+    d.textContent = doc;
+    tip.appendChild(h);
+    tip.appendChild(d);
+    tip.classList.add("open");
+    moveTip(ev);
+  }
+  function moveTip(ev) {
+    var r = svg.getBoundingClientRect(), x = ev.clientX - r.left + 14, y = ev.clientY - r.top + 14;
+    var w = tip.offsetWidth, h = tip.offsetHeight;
+    if (x + w > r.width - 8) x = ev.clientX - r.left - w - 14;
+    if (y + h > r.height - 8) y = ev.clientY - r.top - h - 14;
+    tip.style.left = Math.max(8, x) + "px";
+    tip.style.top = Math.max(8, y) + "px";
+  }
+  vp.addEventListener("mousemove", function (ev) {
+    if (drag && drag.moved) { hideTip(); return; }
+    var tEl = ev.target.closest && ev.target.closest(".t");
+    if (!tEl) { hideTip(); return; }
+    var t = byId[tEl.getAttribute("data-id")], row = ev.target.closest(".r");
+    if (row) {
+      var cid = row.getAttribute("data-c"), c = t.cols.filter(function (x) { return x.id === cid; })[0];
+      if (c && c.doc) showTip(ev, t.name + "." + c.name, c.type, c.doc);
+      else hideTip();
+    } else if (t.doc && ev.target.closest(".th, text")) {
+      showTip(ev, t.name, t.aliases.length ? "as " + t.aliases.join(", ") : "", t.doc);
+    } else hideTip();
+  });
 
   /* ------------------------------------------------------------- pointer: pan, click, drag */
   var drag = null;
@@ -288,7 +331,7 @@
   }
   function exportSvg() {
     var only = S.focus ? Object.keys(neighbours(S.focus)) : null;
-    return Q.renderSvg(S.model, S.pos, { mode: S.mode, only: only, fontCss: data.fontCss });
+    return Q.renderSvg(S.model, S.pos, { mode: S.mode, only: only, fontCss: document.getElementById("qdbd-font").textContent });
   }
   document.getElementById("xsvg").onclick = function () {
     download((data.title || "diagram") + ".svg", new Blob([exportSvg()], { type: "image/svg+xml" }));

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/html.py

@@ -50,6 +50,7 @@ BODY = """
     <div class="minimap">
       <svg id="mini" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid meet"></svg>
     </div>
+    <div class="tip" id="tip" role="tooltip"></div>
     <div class="hint">{hint}</div>
   </div>
 </div>
@@ -67,7 +68,7 @@ SIDE = """
 
 
 def render_page(model: dict, positions: dict, title: str, serve: bool = False) -> str:
-    data = {"model": model, "positions": positions, "serve": serve, "title": title, "fontCss": font_css()}
+    data = {"model": model, "positions": positions, "serve": serve, "title": title}
     hint = (
         "Drag tables to move them (saved). Click a table to focus. Esc clears."
         if serve
@@ -88,7 +89,10 @@ def render_page(model: dict, positions: dict, title: str, serve: bool = False) -
         '<meta name="viewport" content="width=device-width, initial-scale=1">'
         '<meta name="generator" content="qdbd">'
         f"<title>{_escape(title)}</title>"
-        f"<style>{font_css()}{_asset('style.css')}</style>{head_extra}</head><body>"
+        # The font CSS lives in its own <style> so the viewer can reuse it for SVG/PNG export
+        # instead of embedding the fonts a second time.
+        f'<style id="qdbd-font">{font_css()}</style>'
+        f"<style>{_asset('style.css')}</style>{head_extra}</head><body>"
         f"{body}"
         f'<script type="application/json" id="qdbd-data">{_json_for_script(data)}</script>'
         f"<script>{_asset('render.js')}</script>"

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/measure.py

@@ -60,7 +60,7 @@ def _column_json(col: Column) -> dict:
     name_w = text_width(col.name, s["rowSize"], bold)
     bs = [{"t": b, "w": round(text_width(b, s["badgeSize"]) + 2 * s["badgePad"], 2)} for b in badges(col)]
     type_w = text_width(col.type or "", s["rowSize"])
-    return {
+    out = {
         "id": col.id,
         "name": col.name,
         "type": col.type or "",
@@ -75,12 +75,16 @@ def _column_json(col: Column) -> dict:
         "typeW": type_w,
         "badges": bs,
     }
+    if col.comments:
+        out["doc"] = "\n".join(col.comments)
+    return out
 
 
 def table_json(table: Table) -> dict:
     s = STYLE
     cols = [_column_json(c) for c in table.columns.values() if not c.virtual]
-    w = text_width(table.name, s["headerSize"]) + 2 * s["padX"]
+    name_w = text_width(table.name, s["headerSize"])
+    w = name_w + 2 * s["padX"]
     for c in cols:
         row = c["nameW"] + c["typeW"] + 2 * s["padX"] + s["gap"]
         row += sum(b["w"] + s["badgeGap"] for b in c["badges"])
@@ -89,7 +93,10 @@ def table_json(table: Table) -> dict:
         w = max(w, row)
     w = max(round(w), s["minW"])
     h = s["headerH"] + len(cols) * s["rowH"] + s["bottomPad"]
-    return {"id": table.id, "name": table.name, "aliases": table.aliases, "w": w, "h": h, "cols": cols}
+    out = {"id": table.id, "name": table.name, "aliases": table.aliases, "w": w, "h": h, "nameW": name_w, "cols": cols}
+    if table.comments:
+        out["doc"] = "\n".join(table.comments)
+    return out
 
 
 def model_json(schema: Schema) -> dict:

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/src/quickdbd_cli/serve.py

@@ -178,13 +178,30 @@ def _handler(state: State, title: str):
     return Handler
 
 
-def serve(project: Project, port: int = 8765, open_browser: bool = True) -> int:
+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)
-    for d in state.diagnostics:
-        print(d["text"], file=sys.stderr)
     title = project.inputs[0].stem if len(project.inputs) == 1 else "diagram"
     server = ThreadingHTTPServer(("127.0.0.1", port), _handler(state, title))
     server.daemon_threads = True
+    return server, state
+
+
+def poll_once(state: State) -> bool:
+    """Reload if any schema file changed; returns True when a reload happened."""
+    if not state.changed():
+        return False
+    try:
+        state.reload()
+    except Exception as e:  # keep serving on unexpected errors
+        print(f"[qdbd] reload failed: {e}", file=sys.stderr, flush=True)
+    return True
+
+
+def serve(project: Project, port: int = 8765, open_browser: bool = True) -> int:
+    server, state = make_server(project, port)
+    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)})")
     print("[qdbd] Ctrl+C to stop", flush=True)
@@ -192,11 +209,7 @@ def serve(project: Project, port: int = 8765, open_browser: bool = True) -> int:
     def watch() -> None:
         while True:
             time.sleep(0.3)
-            if state.changed():
-                try:
-                    state.reload()
-                except Exception as e:  # keep serving on unexpected errors
-                    print(f"[qdbd] reload failed: {e}", file=sys.stderr, flush=True)
+            poll_once(state)
 
     threading.Thread(target=watch, daemon=True).start()
     if open_browser:

{quickdbd_cli-0.1.0 → quickdbd_cli-0.1.2}/tests/test_pipeline.py

@@ -8,6 +8,7 @@ import pytest
 
 from quickdbd_cli import export, layout
 from quickdbd_cli.cli import main
+from quickdbd_cli.html import render_page
 from quickdbd_cli.measure import model_json, text_width
 from quickdbd_cli.parser import compile_text
 from quickdbd_cli.project import Project
@@ -138,6 +139,7 @@ def test_check_strict_warnings(tmp_path):
 def test_build_is_deterministic_and_does_not_write_sidecar(tmp_path):
     work = tmp_path / "s"
     shutil.copytree(SYNTH, work)
+    (work / "qdbd.layout.json").unlink(missing_ok=True)
     a, b = tmp_path / "a.html", tmp_path / "b.html"
     assert main(["build", str(work), "-o", str(a)]) == 0
     assert main(["build", str(work), "-o", str(b)]) == 0
@@ -159,6 +161,24 @@ def test_layout_command_writes_sidecar_and_reset(tmp_path):
     assert json.loads(side.read_text())["tables"]["Customer"] != {"x": 9999, "y": 9999}
 
 
+def test_build_uses_but_never_rewrites_committed_sidecar(tmp_path):
+    work = tmp_path / "s"
+    shutil.copytree(SYNTH, work)
+    side = work / "qdbd.layout.json"
+    before = side.read_bytes()
+    assert main(["build", str(work), "-o", str(tmp_path / "d.html")]) == 0
+    assert side.read_bytes() == before
+    html = (tmp_path / "d.html").read_text()
+    customer = layout.read_sidecar(side)["Customer"]
+    assert f'"Customer":[{customer[0]},{customer[1]}]' in html
+
+
+def test_html_embeds_font_once():
+    html = render_page(model_json(compile_text(SMALL)), {"Customer": [0, 0], "Order": [300, 0]}, "t")
+    assert html.count("@font-face") == 2  # regular + bold, once each
+    assert 'id="qdbd-font"' in html
+
+
 def test_missing_path(capsys):
     assert main(["check", "nope/does-not-exist.txt"]) == 2
 
@@ -166,3 +186,34 @@ def test_missing_path(capsys):
 @pytest.mark.parametrize("bad_suffix", ["out.jpg"])
 def test_export_rejects_unknown_format(tmp_path, bad_suffix):
     assert main(["export", str(SAMPLE), "-o", str(tmp_path / bad_suffix)]) == 2
+
+
+DOCS = """# Customers who placed at least one order
+Customer # one row per person
+-
+CustomerId PK int
+# Contact address
+Email string # verified
+Name string
+"""
+
+
+def test_doc_comments_in_model():
+    m = model_json(compile_text(DOCS))
+    t = m["tables"][0]
+    assert t["doc"] == "Customers who placed at least one order\none row per person"
+    cols = {c["id"]: c for c in t["cols"]}
+    assert cols["Email"]["doc"] == "Contact address\nverified"
+    assert "doc" not in cols["Name"]
+
+
+def test_doc_marks_only_in_viewer_not_exports():
+    from quickdbd_cli.jsrt import runtime
+
+    m = model_json(compile_text(DOCS))
+    pos = {"Customer": [0, 0]}
+    rt = runtime()
+    rt.load("render.js")
+    viewer = rt.call("qdbd.renderInner", m, pos, "full", {"docMarks": True})
+    assert viewer.count('class="dm"') == 2  # table header + Email
+    assert 'class="dm"' not in export.render_svg(m, pos, embed_font=False)

quickdbd_cli-0.1.2/tests/test_serve.py

@@ -0,0 +1,160 @@
+"""`qdbd serve` HTTP endpoints, driven without a browser."""
+
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+
+import pytest
+
+from quickdbd_cli import layout
+from quickdbd_cli.project import Project, display_path
+from quickdbd_cli.serve import make_server, poll_once
+
+SCHEMA = """Customer
+-
+CustomerId PK int
+Name string
+
+Order
+-
+OrderId PK int
+CustomerId int FK >- Customer.CustomerId
+"""
+
+
+@pytest.fixture
+def srv(tmp_path):
+    f = tmp_path / "shop.txt"
+    f.write_text(SCHEMA)
+    server, state = make_server(Project.open([f]), port=0)
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    base = f"http://127.0.0.1:{server.server_address[1]}"
+    yield base, state, f
+    server.shutdown()
+    server.server_close()
+
+
+def call(base, path, method="GET", body=None):
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(base + path, data=data, method=method, headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            raw = r.read()
+            return r.status, (json.loads(raw) if r.headers.get_content_type() == "application/json" else raw)
+    except urllib.error.HTTPError as e:
+        return e.code, json.loads(e.read())
+
+
+def bump_mtime(path):
+    st = path.stat()
+    os.utime(path, ns=(st.st_atime_ns, st.st_mtime_ns + 1_000_000_000))
+
+
+def test_page_and_state(srv):
+    base, _, f = srv
+    code, page = call(base, "/")
+    assert code == 200 and b'id="side"' in page and b'"serve":true' in page
+    code, st = call(base, "/state")
+    assert code == 200
+    assert [t["name"] for t in st["model"]["tables"]] == ["Customer", "Order"]
+    assert st["files"] == [{"path": display_path(f), "text": SCHEMA, "mtime": st["files"][0]["mtime"]}]
+    assert isinstance(st["files"][0]["mtime"], str)  # ns mtimes overflow JS numbers
+    assert st["diagnostics"] == []
+
+
+def test_initial_layout_written_to_sidecar(srv):
+    _, state, f = srv
+    side = layout.read_sidecar(f.with_name("shop.layout.json"))
+    assert set(side) == {"Customer", "Order"}
+
+
+def test_put_file_saves_and_returns_new_mtime(srv):
+    base, _, f = srv
+    _, st = call(base, "/state")
+    path, mtime = st["files"][0]["path"], st["files"][0]["mtime"]
+    new = SCHEMA + "\nProduct\n-\nProductId PK int\n"
+    code, res = call(base, "/file", "PUT", {"path": path, "text": new, "mtime": mtime})
+    assert code == 200 and res["mtime"] != mtime
+    assert f.read_text() == new
+
+
+def test_put_file_refuses_stale_write(srv):
+    base, _, f = srv
+    _, st = call(base, "/state")
+    path, mtime = st["files"][0]["path"], st["files"][0]["mtime"]
+    f.write_text(SCHEMA + "\n# edited elsewhere\n")
+    bump_mtime(f)
+    code, res = call(base, "/file", "PUT", {"path": path, "text": "clobber", "mtime": mtime})
+    assert code == 409
+    assert "# edited elsewhere" in res["text"]
+    assert "# edited elsewhere" in f.read_text()  # disk untouched
+
+
+def test_put_unknown_file(srv):
+    base, _, _ = srv
+    code, _ = call(base, "/file", "PUT", {"path": "nope.txt", "text": "x", "mtime": None})
+    assert code == 404
+
+
+def test_post_layout_updates_sidecar(srv):
+    base, state, f = srv
+    code, _ = call(base, "/layout", "POST", {"Customer": [1234, 567], "Unknown": [1, 1]})
+    assert code == 200
+    side = layout.read_sidecar(f.with_name("shop.layout.json"))
+    assert side["Customer"] == (1234, 567)
+    assert "Unknown" not in side
+    _, st = call(base, "/state")
+    assert st["positions"]["Customer"] == [1234, 567]
+
+
+def test_external_edit_reloads_and_places_new_table(srv):
+    base, state, f = srv
+    _, before = call(base, "/state")
+    f.write_text(SCHEMA + "\nLine\n-\nLineId PK int\nOrderId int FK >- Order.OrderId\n")
+    bump_mtime(f)
+    assert poll_once(state)
+    _, after = call(base, "/state")
+    assert after["version"] > before["version"]
+    assert "Line" in after["positions"]
+    # existing tables did not move
+    for t in ("Customer", "Order"):
+        assert after["positions"][t] == before["positions"][t]
+    assert not poll_once(state)  # nothing changed since
+
+
+def test_errors_keep_last_good_model(srv):
+    base, state, f = srv
+    f.write_text(SCHEMA + "\nBad\n-\nX int FK >- Nope.Id\n")
+    bump_mtime(f)
+    poll_once(state)
+    _, st = call(base, "/state")
+    assert [d["severity"] for d in st["diagnostics"]] == ["error"]
+    assert "Invalid relationship, the table 'Nope' does not exist" in st["diagnostics"][0]["text"]
+    assert [t["name"] for t in st["model"]["tables"]] == ["Customer", "Order"]
+
+
+def test_events_stream_announces_versions(srv):
+    base, state, f = srv
+    got = []
+
+    def listen():
+        with urllib.request.urlopen(base + "/events", timeout=10) as r:
+            for line in r:
+                line = line.decode().strip()
+                if line.startswith("data:"):
+                    got.append(int(line[5:]))
+                    if len(got) == 2:
+                        return
+
+    t = threading.Thread(target=listen, daemon=True)
+    t.start()
+    time.sleep(0.3)
+    f.write_text(SCHEMA + "\n# touch\n")
+    bump_mtime(f)
+    poll_once(state)
+    t.join(timeout=10)
+    assert len(got) == 2 and got[1] > got[0]

quickdbd_cli-0.1.0/src/quickdbd_cli/__init__.py

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