quickdbd-cli 0.3.5__tar.gz → 0.4.0__tar.gz

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.3.5
+Version: 0.4.0
 Summary: Compile QuickDBD-syntax schema files into interactive HTML ER diagrams, with no table limit.
 Project-URL: Homepage, https://qdbd.dev/
 Project-URL: Documentation, https://qdbd.dev/guide/
@@ -65,10 +65,10 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/hero.png" alt="The AdventureWorks sample database as a qdbd diagram, with the SalesOrderHeader table selected" width="760"></a>
+  <a href="https://qdbd.dev/demo/adventureworks-dw/#t=FactInternetSales"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/hero.png" alt="The AdventureWorks DW star schema as a qdbd diagram, with the FactInternetSales table selected" width="760"></a>
 </p>
 <p align="center">
-  <em>AdventureWorks (68 tables) with its column descriptions, built by qdbd. <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader">Try it live →</a></em>
+  <em>AdventureWorks DW (28 tables), a star schema in five regions, built by qdbd. <a href="https://qdbd.dev/demo/adventureworks-dw/#t=FactInternetSales">Try it live →</a></em>
 </p>
 
 ## What is qdbd?
@@ -169,7 +169,7 @@ In VS Code (or Cursor), the [extension](https://qdbd.dev/vscode/) does the same
 ```sh
 qdbd build schema.txt -o schema.html      # one self-contained page
 qdbd export schema.txt -o schema.png      # or .svg, .drawio
-qdbd share schema.txt                     # a link to the page, via a GitHub gist
+QDBD_ALLOW_SHARE=1 qdbd share schema.txt  # a link via a GitHub gist: off by default, see the disclaimer
 ```
 
 ## Run in CI
@@ -186,7 +186,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.3.5
+      - uses: MarkPhamm/quickdbd-cli@v0.4.0
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -257,7 +257,7 @@ No. qdbd only borrows the text syntax.
 No. It reads `.txt` / `.dbml` schema files or a dbt `manifest.json`. Nothing connects to a warehouse.
 
 **Does my schema leave my machine?**
-Only if you run `qdbd share`, which uploads the page to a GitHub gist in your account (secret by default), or connect an AI agent through `qdbd mcp`, whose answers go to your AI provider. `qdbd serve` loads its code editor from a CDN; the built pages load nothing.
+Only if you turn sharing on (`QDBD_ALLOW_SHARE=1`, or `quickdbd.allowSharing` in VS Code) and run `qdbd share`, which uploads the page to a GitHub gist in your account (secret by default), publish it yourself (a tunnel, GitHub Pages), or connect an AI agent through `qdbd mcp`, whose answers go to your AI provider. `qdbd serve` loads its code editor from a CDN; the built pages load nothing.
 
 **How big can a diagram get?**
 The demos go up to 200 tables. Search, selectors, regions and collapsed views keep large diagrams workable; `--select` builds a page with just the part you need.

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/README.md

@@ -27,10 +27,10 @@
 </p>
 
 <p align="center">
-  <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/hero.png" alt="The AdventureWorks sample database as a qdbd diagram, with the SalesOrderHeader table selected" width="760"></a>
+  <a href="https://qdbd.dev/demo/adventureworks-dw/#t=FactInternetSales"><img src="https://raw.githubusercontent.com/MarkPhamm/quickdbd-cli/main/docs/assets/img/hero.png" alt="The AdventureWorks DW star schema as a qdbd diagram, with the FactInternetSales table selected" width="760"></a>
 </p>
 <p align="center">
-  <em>AdventureWorks (68 tables) with its column descriptions, built by qdbd. <a href="https://qdbd.dev/demo/adventureworks/#t=SalesOrderHeader">Try it live →</a></em>
+  <em>AdventureWorks DW (28 tables), a star schema in five regions, built by qdbd. <a href="https://qdbd.dev/demo/adventureworks-dw/#t=FactInternetSales">Try it live →</a></em>
 </p>
 
 ## What is qdbd?
@@ -131,7 +131,7 @@ In VS Code (or Cursor), the [extension](https://qdbd.dev/vscode/) does the same
 ```sh
 qdbd build schema.txt -o schema.html      # one self-contained page
 qdbd export schema.txt -o schema.png      # or .svg, .drawio
-qdbd share schema.txt                     # a link to the page, via a GitHub gist
+QDBD_ALLOW_SHARE=1 qdbd share schema.txt  # a link via a GitHub gist: off by default, see the disclaimer
 ```
 
 ## Run in CI
@@ -148,7 +148,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.3.5
+      - uses: MarkPhamm/quickdbd-cli@v0.4.0
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -219,7 +219,7 @@ No. qdbd only borrows the text syntax.
 No. It reads `.txt` / `.dbml` schema files or a dbt `manifest.json`. Nothing connects to a warehouse.
 
 **Does my schema leave my machine?**
-Only if you run `qdbd share`, which uploads the page to a GitHub gist in your account (secret by default), or connect an AI agent through `qdbd mcp`, whose answers go to your AI provider. `qdbd serve` loads its code editor from a CDN; the built pages load nothing.
+Only if you turn sharing on (`QDBD_ALLOW_SHARE=1`, or `quickdbd.allowSharing` in VS Code) and run `qdbd share`, which uploads the page to a GitHub gist in your account (secret by default), publish it yourself (a tunnel, GitHub Pages), or connect an AI agent through `qdbd mcp`, whose answers go to your AI provider. `qdbd serve` loads its code editor from a CDN; the built pages load nothing.
 
 **How big can a diagram get?**
 The demos go up to 200 tables. Search, selectors, regions and collapsed views keep large diagrams workable; `--select` builds a page with just the part you need.

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.3.5"
+version = "0.4.0"
 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.3.5 → quickdbd_cli-0.4.0}/scripts/gen_thumbnails.py

@@ -30,25 +30,32 @@ PATH_SHOT = ("sakila", "t=payment&p=country")
 # Hidden in the screenshot: the table list, toolbar, minimap and hint. The details panel and diff bar stay.
 CLEAN = ".explorer, .bar, .minimap, .hint { display: none !important; }"
 
-CARD = """<!doctype html><html><head><meta charset="utf-8"><style>{font}
+CARD = """<!doctype html><html><head><meta charset="utf-8">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@500;600&family=Geist+Mono&display=swap">
+<style>{font}
 * {{ box-sizing: border-box; margin: 0; }}
-body {{ width: {w}px; height: {h}px; overflow: hidden; font-family: Inter, sans-serif; color: #0f1b2d;
-  background: #eef3fb; background-image: linear-gradient(#dfe7f3 1px, transparent 1px),
-  linear-gradient(90deg, #dfe7f3 1px, transparent 1px); background-size: 28px 28px; position: relative; }}
-.text {{ position: absolute; left: 56px; top: 64px; width: 360px; }}
-.brand {{ display: flex; align-items: center; gap: 10px; font-weight: 700; font-size: 26px; margin-bottom: 44px; }}
-.brand svg {{ color: #2563eb; }}
-h1 {{ display: inline; font-size: 46px; line-height: 1.32; font-weight: 700; color: #fff; background: #2563eb;
-  padding: 2px 10px; -webkit-box-decoration-break: clone; box-decoration-break: clone; }}
-p {{ margin-top: 26px; font-size: 21px; line-height: 1.5; color: #42526b; }}
-.shot {{ position: absolute; left: 460px; top: 56px; width: {sw}px; border-radius: 14px; overflow: hidden;
-  border: 1px solid #cfd8e6; box-shadow: 0 18px 50px rgba(15, 27, 45, .18); background: #fff; }}
+body {{ width: {w}px; height: {h}px; overflow: hidden; font-family: Geist, Inter, sans-serif; color: #15181e;
+  position: relative; --a: rgba(21, 24, 30, .07); --b: rgba(21, 24, 30, .04); background: #f2f2ee;
+  background-image: linear-gradient(var(--a) 1px, #0000 1px), linear-gradient(90deg, var(--a) 1px, #0000 1px),
+    linear-gradient(var(--b) 1px, #0000 1px), linear-gradient(90deg, var(--b) 1px, #0000 1px);
+  background-size: 120px 120px, 120px 120px, 24px 24px, 24px 24px; background-position: -1px -1px; }}
+.text {{ position: absolute; left: 56px; top: 60px; width: 360px; }}
+.brand {{ display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 26px; letter-spacing: -.02em;
+  margin-bottom: 40px; }}
+.brand svg {{ color: #2f5bea; }}
+.brand span {{ font: 16px "Geist Mono", monospace; color: #646a75; border: 1px solid rgba(21, 24, 30, .24);
+  border-radius: 6px; padding: 3px 8px; margin-left: 4px; letter-spacing: 0; }}
+h1 {{ font-size: 48px; line-height: 1.04; font-weight: 600; letter-spacing: -.04em; }}
+p {{ margin-top: 22px; font-size: 21px; line-height: 1.5; color: #4a505b; }}
+.shot {{ position: absolute; left: 460px; top: 56px; width: {sw}px; border-radius: 12px; overflow: hidden;
+  border: 1px solid rgba(21, 24, 30, .24); box-shadow: 0 18px 40px -18px rgba(21, 24, 30, .28); background: #fff; }}
 .shot img {{ display: block; width: 100%; }}
 </style></head><body>
 <div class="text">
   <div class="brand"><svg width="30" height="30" viewBox="0 0 24 24"><rect x="2" y="2.5" width="10" height="8" rx="2"
     fill="currentColor"/><rect x="12" y="13.5" width="10" height="8" rx="2" fill="currentColor" opacity=".55"/><path
-    d="M7 10.5v3.5a3.5 3.5 0 0 0 3.5 3.5H12" stroke="currentColor" stroke-width="2" fill="none"/></svg>qdbd</div>
+    d="M7 10.5v3.5a3.5 3.5 0 0 0 3.5 3.5H12" stroke="currentColor" stroke-width="2" fill="none"/></svg>qdbd
+    <span>demo</span></div>
   <h1>{title}</h1>
   <p>{description}</p>
 </div>
@@ -88,7 +95,7 @@ def main(argv: list[str]) -> int:
                     img=img,
                 )
             )
-            card.wait_for_timeout(100)
+            card.evaluate("document.fonts.ready.then(() => true)")  # Geist comes from Google Fonts
             dst = THUMBS / f"{d.id}.png"
             card.screenshot(path=str(dst))
             print(f"Wrote {dst.relative_to(THUMBS.parents[3])}")

quickdbd_cli-0.4.0/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/src/quickdbd_cli/cli.py

@@ -158,10 +158,28 @@ def cmd_build(args) -> int:
 def cmd_share(args) -> int:
     from . import share
 
+    if not share.allowed():
+        print(
+            "error: sharing is off. qdbd share uploads the diagram (every table and column name) to a GitHub gist"
+            f" that anyone with the link can open. If your data policy allows that, set {share.ALLOW_ENV}=1"
+            " (doing so accepts https://qdbd.dev/sharing/#disclaimer).",
+            file=sys.stderr,
+        )
+        return 2
     res = _built_page(args)
     if isinstance(res, int):
         return res
     page, model = res
+    print(share.DISCLAIMER, file=sys.stderr)
+    if not args.yes:
+        if not sys.stdin.isatty():
+            print("error: no terminal to confirm in: add --yes to accept the disclaimer and share", file=sys.stderr)
+            return 2
+        kind = "public" if args.public else "secret"
+        print(f"Share {len(model['tables'])} tables as a {kind} gist? [y/N] ", end="", file=sys.stderr, flush=True)
+        if sys.stdin.readline().strip().lower() not in ("y", "yes"):
+            print("Not shared.", file=sys.stderr)
+            return 2
     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)
@@ -571,7 +589,10 @@ 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)")
+    sp = sub.add_parser(
+        "share",
+        help="publish the diagram as a GitHub gist and print a link (off unless QDBD_ALLOW_SHARE=1; needs the gh CLI)",
+    )
     paths(sp)
     selectors(sp)
     sp.add_argument(
@@ -582,6 +603,7 @@ def build_parser() -> argparse.ArgumentParser:
     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.add_argument("-y", "--yes", action="store_true", help="accept the disclaimer without asking (for scripts)")
     sp.set_defaults(func=cmd_share)
 
     sp = sub.add_parser("export", help="write a PNG, SVG or draw.io file")
@@ -665,7 +687,7 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument(
         "--read-only",
         action="store_true",
-        help="live view only: no editor, nothing saved; safe to share through a tunnel",
+        help="live view only: no editor, nothing saved; viewers can't change anything",
     )
     sp.add_argument(
         "--embed",

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/src/quickdbd_cli/share.py

@@ -4,6 +4,10 @@ Uses the GitHub CLI (``gh api``), so it inherits the user's login. Gists are sec
 ``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. The VS Code extension does the same
 without gh (vscode/src/gist.ts) and shares the cache: keep the two in step.
+
+Off unless ``QDBD_ALLOW_SHARE`` is set: a gist puts the schema outside the organisation's control, which a
+client's data agreements may not allow. The extension's own switch is the ``quickdbd.allowSharing`` setting.
+Even then, every share shows ``DISCLAIMER`` and asks first; the extension's dialog (export.ts) says the same.
 """
 
 from __future__ import annotations
@@ -15,11 +19,23 @@ import subprocess
 from dataclasses import dataclass
 from pathlib import Path
 
+ALLOW_ENV = "QDBD_ALLOW_SHARE"
+DISCLAIMER = """\
+Before you share: this uploads the diagram (every table and column name, type, key, relationship
+and comment) to a GitHub gist. Anyone with the link can open it, and copies can outlive the gist.
+By sharing, you confirm that you have the right to publish this schema, that your organisation's
+policies and any client agreements allow it, and that qdbd's authors are not liable for any
+disclosure. Full disclaimer: https://qdbd.dev/sharing/#disclaimer"""
+
 
 class ShareError(Exception):
     pass
 
 
+def allowed() -> bool:
+    return os.environ.get(ALLOW_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+
+
 @dataclass
 class Shared:
     link: str  # gistpreview: renders the gist's HTML, keeps the #view part of the URL

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/tests/test_gallery.py

@@ -96,6 +96,7 @@ def test_sample_databases_and_dbt_projects(built):
         assert len(m["tables"]) == n and m["rels"], d
     dw = _model(built / "adventureworks-dw" / "index.html")
     assert {"dim", "fact"} <= {t["name"] for t in dw["tags"]}  # coloured by the Dim/Fact name prefixes
+    assert dw["regions"] and len({t["group"] for t in dw["tables"]}) == 5  # one region per business process
     aw = _model(built / "adventureworks" / "index.html")
     assert aw["regions"] and any(t.get("doc") for t in aw["tables"])  # MS_Description -> tooltips
 

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/tests/test_home_hook.py

@@ -49,4 +49,7 @@ def test_build_tour(tmp_path):
     assert page.exists()
     text = page.read_text(encoding="utf-8")
     model = json.loads(re.search(r'id="qdbd-data">(.*?)</script>', text, re.S).group(1))["model"]
-    assert len(model["tables"]) == 68
+    assert len(model["tables"]) == 28 and model["regions"]
+    # the tables docs/javascripts/home-tour.js types, clicks and paths between
+    driven = {"FactInternetSales", "DimCustomer", "FactResellerSales", "DimProductCategory"}
+    assert driven <= {t["id"] for t in model["tables"]}

{quickdbd_cli-0.3.5 → quickdbd_cli-0.4.0}/tests/test_share.py

@@ -1,5 +1,6 @@
 """`qdbd share`, with `gh api` faked (no network)."""
 
+import io
 import json
 import subprocess
 
@@ -42,6 +43,7 @@ def gh(monkeypatch, tmp_path):
     fake = FakeGh()
     monkeypatch.setattr(share.subprocess, "run", fake)
     monkeypatch.setenv("QDBD_CACHE_DIR", str(tmp_path / "cache"))
+    monkeypatch.setenv("QDBD_ALLOW_SHARE", "1")
     return fake
 
 
@@ -53,8 +55,9 @@ def schema(tmp_path):
 
 
 def test_share_creates_a_secret_gist_and_prints_links(gh, schema, capsys):
-    assert main(["share", str(schema)]) == 0
-    out = capsys.readouterr().out
+    assert main(["share", "--yes", str(schema)]) == 0
+    out, err = capsys.readouterr()
+    assert "Before you share" in err and "https://qdbd.dev/sharing/#disclaimer" in err
     method, endpoint, payload = gh.calls[0]
     assert (method, endpoint, payload["public"]) == ("POST", "/gists", False)
     assert list(payload["files"]) == ["shop.html"]
@@ -64,10 +67,43 @@ def test_share_creates_a_secret_gist_and_prints_links(gh, schema, capsys):
     assert "https://gist.githack.com/me/g1/raw/shop.html" in out
 
 
+@pytest.mark.parametrize("value", [None, "", "0", "false"])
+def test_sharing_is_off_unless_allowed(gh, schema, capsys, monkeypatch, value):
+    if value is None:
+        monkeypatch.delenv("QDBD_ALLOW_SHARE")
+    else:
+        monkeypatch.setenv("QDBD_ALLOW_SHARE", value)
+    assert main(["share", "--yes", str(schema)]) == 2  # --yes accepts the disclaimer, not the switch
+    assert gh.calls == []
+    assert "set QDBD_ALLOW_SHARE=1" in capsys.readouterr().err
+
+
+class Tty(io.StringIO):
+    def isatty(self):
+        return True
+
+
+@pytest.mark.parametrize(("answer", "code", "uploads"), [("y\n", 0, 1), ("yes\n", 0, 1), ("n\n", 2, 0), ("\n", 2, 0)])
+def test_asks_before_sharing(gh, schema, capsys, monkeypatch, answer, code, uploads):
+    monkeypatch.setattr("sys.stdin", Tty(answer))
+    assert main(["share", str(schema)]) == code
+    assert len(gh.calls) == uploads
+    err = capsys.readouterr().err
+    assert "Before you share" in err
+    assert "Share 2 tables as a secret gist? [y/N]" in err
+
+
+def test_no_terminal_needs_yes(gh, schema, capsys, monkeypatch):
+    monkeypatch.setattr("sys.stdin", io.StringIO("y\n"))  # piped input doesn't count as consent
+    assert main(["share", str(schema)]) == 2
+    assert gh.calls == []
+    assert "add --yes" in capsys.readouterr().err
+
+
 def test_sharing_again_updates_the_same_gist(gh, schema, capsys):
-    main(["share", str(schema)])
+    main(["share", "--yes", str(schema)])
     schema.write_text(SCHEMA + "\nProduct\n-\nId PK int\n")
-    assert main(["share", str(schema)]) == 0
+    assert main(["share", "--yes", 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"]
@@ -75,37 +111,37 @@ def test_sharing_again_updates_the_same_gist(gh, schema, capsys):
 
 
 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+"])
+    main(["share", "--yes", str(schema)])
+    main(["share", "--yes", str(schema), "--new"])
+    main(["share", "--yes", str(schema), "-s", "Order+"])
     assert [c[0] for c in gh.calls] == ["POST", "POST", "POST"]
-    main(["share", str(schema), "-s", "Order+"])
+    main(["share", "--yes", str(schema), "-s", "Order+"])
     assert gh.calls[-1][:2] == ("PATCH", "/gists/g3")
 
 
 def test_deleted_gist_is_recreated(gh, schema):
-    main(["share", str(schema)])
+    main(["share", "--yes", str(schema)])
     gh.gists.clear()
-    assert main(["share", str(schema)]) == 0
+    assert main(["share", "--yes", 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"])
+    main(["share", "--yes", 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 main(["share", "--yes", 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 main(["share", "--yes", str(schema)]) == 2
     assert "needs the GitHub CLI" in capsys.readouterr().err
 
 

quickdbd_cli-0.3.5/src/quickdbd_cli/__init__.py

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