quickdbd-cli 0.1.7__tar.gz → 0.1.9__tar.gz

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quickdbd-cli
-Version: 0.1.7
+Version: 0.1.9
 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
 
@@ -202,7 +202,32 @@ Where the layout file goes:
 
 `qdbd build` never writes the layout file, so CI builds leave your working tree clean. More: [Table Positions](https://markphamm.github.io/quickdbd-cli/layout/).
 
-### 3.4 Differences from QuickDBD
+### 3.4 Tags and colours
+
+Give tables a role and a header colour. Tags are comments, so the file still pastes into QuickDBD.
+
+```text
+# @color gold #b8860b      # optional: pick a tag's colour
+
+# @tag: gold, pii
+customers
+-
+customer_id PK int
+
+dim_date                   # tagged "dim" automatically from its name
+-
+date_key PK int
+```
+
+A table's tags come from the first source that has any:
+
+1. an explicit `# @tag:` comment;
+2. its name: `dim_*` → dim, `fct_*` / `fact_*` → fact, `stg_*` → staging, `int_*` → intermediate, `raw_*` / `src_*` → raw;
+3. dbt tags, written as `# @dbt-tags:` by `qdbd import dbt`.
+
+The header takes the colour of the first tag. In the page, a chip per tag under the filter box shows only that tag, and the selector `tag:fact` works everywhere. More: [Tags and Colours](https://markphamm.github.io/quickdbd-cli/tags/).
+
+### 3.5 Differences from QuickDBD
 
 `qdbd` accepts a few things QuickDBD rejects, and prints a warning for each:
 
@@ -243,6 +268,7 @@ The explorer's filter box takes dbt-style selectors that follow **relationships*
 | `+orders+1` | one hop in both directions |
 | `group:marts`, `file:core.txt` | a folder or a file |
 | `col:customer_id` | tables with a matching column |
+| `tag:fact` | tables with a matching tag ([3.4](#34-tags-and-colours)) |
 | `a b` / `a,b` / `!a` | union / intersection / exclude |
 
 ```bash
@@ -264,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
@@ -288,6 +333,7 @@ See it on a real project: the [jaffle_shop demo](https://markphamm.github.io/qui
 | Relationships | `relationships` tests (incl. dbt_utils `relationships_where`) and `foreign_key` constraints |
 | Column types | `catalog.json` |
 | Tooltips | model and column descriptions |
+| Header colours | dbt `tags` (unless the name or an explicit `# @tag` says otherwise) |
 
 Useful options: `--select 'marts.*'` (repeatable), `--no-sources`, `--package all`, `-o schema.txt` for a single file.
 
@@ -341,7 +387,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.9
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -364,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.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.9
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -379,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.7
+    rev: v0.1.9
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$
@@ -404,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.7 → quickdbd_cli-0.1.9}/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
 
@@ -174,7 +174,32 @@ Where the layout file goes:
 
 `qdbd build` never writes the layout file, so CI builds leave your working tree clean. More: [Table Positions](https://markphamm.github.io/quickdbd-cli/layout/).
 
-### 3.4 Differences from QuickDBD
+### 3.4 Tags and colours
+
+Give tables a role and a header colour. Tags are comments, so the file still pastes into QuickDBD.
+
+```text
+# @color gold #b8860b      # optional: pick a tag's colour
+
+# @tag: gold, pii
+customers
+-
+customer_id PK int
+
+dim_date                   # tagged "dim" automatically from its name
+-
+date_key PK int
+```
+
+A table's tags come from the first source that has any:
+
+1. an explicit `# @tag:` comment;
+2. its name: `dim_*` → dim, `fct_*` / `fact_*` → fact, `stg_*` → staging, `int_*` → intermediate, `raw_*` / `src_*` → raw;
+3. dbt tags, written as `# @dbt-tags:` by `qdbd import dbt`.
+
+The header takes the colour of the first tag. In the page, a chip per tag under the filter box shows only that tag, and the selector `tag:fact` works everywhere. More: [Tags and Colours](https://markphamm.github.io/quickdbd-cli/tags/).
+
+### 3.5 Differences from QuickDBD
 
 `qdbd` accepts a few things QuickDBD rejects, and prints a warning for each:
 
@@ -215,6 +240,7 @@ The explorer's filter box takes dbt-style selectors that follow **relationships*
 | `+orders+1` | one hop in both directions |
 | `group:marts`, `file:core.txt` | a folder or a file |
 | `col:customer_id` | tables with a matching column |
+| `tag:fact` | tables with a matching tag ([3.4](#34-tags-and-colours)) |
 | `a b` / `a,b` / `!a` | union / intersection / exclude |
 
 ```bash
@@ -236,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
@@ -260,6 +305,7 @@ See it on a real project: the [jaffle_shop demo](https://markphamm.github.io/qui
 | Relationships | `relationships` tests (incl. dbt_utils `relationships_where`) and `foreign_key` constraints |
 | Column types | `catalog.json` |
 | Tooltips | model and column descriptions |
+| Header colours | dbt `tags` (unless the name or an explicit `# @tag` says otherwise) |
 
 Useful options: `--select 'marts.*'` (repeatable), `--no-sources`, `--package all`, `-o schema.txt` for a single file.
 
@@ -313,7 +359,7 @@ jobs:
     permissions: { contents: read, pull-requests: write }
     steps:
       - uses: actions/checkout@v4
-      - uses: MarkPhamm/quickdbd-cli@v0.1.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.9
         with:
           path: erd/                  # schema file(s) or folder(s)
           output: site/index.html
@@ -336,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.7
+      - uses: MarkPhamm/quickdbd-cli@v0.1.9
         with:
           dbt-manifest: target/
           dbt-args: --infer-fks
@@ -351,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.7
+    rev: v0.1.9
     hooks:
       - id: qdbd-check
         files: ^erd/.*\.txt$
@@ -376,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.7 → quickdbd_cli-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quickdbd-cli"
-version = "0.1.7"
+version = "0.1.9"
 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.9/src/quickdbd_cli/__init__.py

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

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/assets/render.js

@@ -78,7 +78,7 @@
     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 + '"/>');
-    var state = t.diff && t.diff.state, hcol = state === "added" ? C.added : state === "changed" ? C.changed : C.header;
+    var state = t.diff && t.diff.state, hcol = state === "added" ? C.added : state === "changed" ? C.changed : t.color || C.header;
     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="' + hcol + '"/>');
     if (state) {
       out.push('<text x="' + (w - st.padX) + '" y="' + n(st.headerH / 2 + 4) + '" text-anchor="end" fill="#fff" font-family="' + FONT +
@@ -310,7 +310,7 @@
       cells.push(cell({
         id: tid, value: t.name, vertex: "1", parent: "1",
         style: "shape=table;startSize=" + HEADH + ";container=1;collapsible=1;childLayout=tableLayout;fixedRows=1;rowLines=0;" +
-          "fontStyle=1;align=left;spacingLeft=10;resizeLast=1;html=0;whiteSpace=wrap;fillColor=#2b5797;fontColor=#ffffff;" +
+          "fontStyle=1;align=left;spacingLeft=10;resizeLast=1;html=0;whiteSpace=wrap;fillColor=" + (t.color || C.header) + ";fontColor=#ffffff;" +
           "strokeColor=#dfe3e8;swimlaneFillColor=#ffffff;fontSize=14;",
       }, g(p[0] - b[0] + 40, p[1] - b[1] + 40, w, HEADH + Math.max(tg.cols.length, 0) * ROWH)));
       tg.cols.forEach(function (c, i) {
@@ -350,7 +350,7 @@
   /* ------------------------------------------------------------------ selectors (dbt-style, over relationships)
    * Space-separated atoms are unioned; a comma inside an atom intersects (a,b); a leading ! excludes.
    * Atom: [N]+  method:pattern  +[N]
-   *   method: name (default; also matches aliases), group, file, col
+   *   method: name (default; also matches aliases), group, file, col, tag
    *   pattern: glob with * and ?
    *   +x   x plus the tables it references (parents), any depth; 2+x limits to 2 hops
    *   x+   x plus the tables referencing it (children); x+1 limits to 1 hop
@@ -391,11 +391,12 @@
       else if (method === "group") ok = re.test(t.group || "") || (t.group || "").toLowerCase().indexOf(pat.toLowerCase() + "/") === 0;
       else if (method === "file") ok = re.test(t.file || "") || re.test((t.file || "").split("/").pop());
       else if (method === "col" || method === "column") ok = t.cols.some(function (c) { return re.test(c.name); });
+      else if (method === "tag") ok = (t.tags || []).some(function (x) { return re.test(x); });
       else if (method === "diff" || method === "state") {
         var ds = t.diff && t.diff.state, want = pat.toLowerCase();
         ok = !!ds && (want === "modified" || want === "*" || want === ds || (want === "new" && ds === "added"));
       }
-      else throw new Error("unknown selector method '" + method + "' (use name, group, file, col, diff)");
+      else throw new Error("unknown selector method '" + method + "' (use name, group, file, col, tag, diff)");
       if (ok) { out[t.id] = true; base.push(t.id); }
     });
     function hops(op, before) {

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/assets/style.css

@@ -56,6 +56,17 @@ html, body { margin: 0; height: 100%; background: var(--bg); color: var(--ink);
 .fstat { font-size: 11px; color: var(--muted); padding: 3px 2px 0; min-height: 14px; }
 .fstat.bad { color: #c0392b; }
 .fstat a { color: var(--blue); cursor: pointer; margin-left: 6px; }
+.tagbar { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px 0 2px; }
+.tchip { display: inline-flex; align-items: center; gap: 4px; font: 11px/1.6 inherit; padding: 0 7px 0 5px; border: 1px solid var(--line);
+  border-radius: 10px; background: #fff; color: var(--text, #333); cursor: pointer; }
+.tchip i { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
+.tchip small { color: var(--muted); }
+.tchip:hover { border-color: #b8c2d0; }
+.tchip.on { border-color: var(--blue); background: #eef3fa; }
+.tdot { display: inline-block; width: 7px; height: 7px; border-radius: 50%; margin: 0 6px 1px -13px; vertical-align: middle; }
+.tree.flat .tdot { margin-left: 0; }
+.details .ttags { margin: -4px 0 10px; display: flex; gap: 4px; flex-wrap: wrap; }
+.details .ttag { color: #fff; font-size: 11px; padding: 1px 8px; border-radius: 10px; cursor: pointer; text-decoration: none; }
 .tree { overflow: auto; padding: 4px 0 8px; }
 .explorer.collapsed .tree { display: none; }
 .gh { padding: 6px 12px 4px; font-size: 11px; font-weight: bold; color: var(--muted); text-transform: uppercase;

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/assets/viewer.js

@@ -331,7 +331,8 @@
       var open = q || !shut[g];
       var rows = items.map(function (t) {
         if (open) visible.push(t.id);
-        return '<div class="ti" data-id="' + Q.esc(t.id) + '">' + Q.esc(t.name) +
+        return '<div class="ti" data-id="' + Q.esc(t.id) + '">' +
+          (t.color ? '<i class="tdot" style="background:' + Q.esc(t.color) + '" title="' + Q.esc(t.tags.join(", ")) + '"></i>' : "") + Q.esc(t.name) +
           (t.aliases.length ? "<small>as " + Q.esc(t.aliases.join(", ")) + "</small>" : "") + "</div>";
       }).join("");
       if (flat) return rows;
@@ -408,7 +409,25 @@
     if (err) fstat.textContent = err;
     else if (ids) fstat.innerHTML = "Showing " + ids.length + " of " + S.model.tables.length + ' tables<a id="fclear">clear</a>';
     else fstat.textContent = "";
+    drawTags();
+  }
+  /* Tag legend: one chip per tag (header colour + count); a click filters to tag:NAME, a second click clears. */
+  var tagbar = document.getElementById("tagbar");
+  function drawTags() {
+    var tags = S.model.tags || [];
+    tagbar.style.display = tags.length ? "" : "none";
+    tagbar.innerHTML = tags.map(function (g) {
+      var on = S.filter.toLowerCase() === "tag:" + g.name;
+      return '<button class="tchip' + (on ? " on" : "") + '" data-tag="' + Q.esc(g.name) + '" title="Show only tag:' + Q.esc(g.name) +
+        '"><i style="background:' + Q.esc(g.color) + '"></i>' + Q.esc(g.name) + "<small>" + g.count + "</small></button>";
+    }).join("");
   }
+  tagbar.addEventListener("click", function (ev) {
+    var b = ev.target.closest(".tchip");
+    if (!b) return;
+    var expr = "tag:" + b.getAttribute("data-tag");
+    applyFilter(S.filter.toLowerCase() === expr ? "" : expr);
+  });
   function applyFilter(expr, keepView) {
     S.filter = (expr || "").trim();
     if (finput.value.trim() !== S.filter) finput.value = S.filter;
@@ -476,6 +495,12 @@
     if (t.aliases.length) meta.push("as " + Q.esc(t.aliases.join(", ")));
     if (t.file) meta.push(Q.esc(t.file) + ":" + t.line);
     if (meta.length) out.push('<div class="meta">' + meta.join(" &middot; ") + "</div>");
+    if (t.tags) {
+      out.push('<div class="ttags">' + t.tags.map(function (g) {
+        var c = (S.model.tags || []).filter(function (x) { return x.name === g; })[0];
+        return '<a class="ttag" data-tag="' + Q.esc(g) + '" style="background:' + Q.esc(c ? c.color : "#2b5797") + '">' + Q.esc(g) + "</a>";
+      }).join("") + "</div>");
+    }
     if (t.doc) out.push('<div class="doc">' + Q.esc(t.doc) + "</div>");
     out.push('<div class="pathbox"><input id="pathto" list="pathlist" placeholder="Path to another table…" autocomplete="off" value="' +
       (S.path && byId[S.path.to] ? Q.esc(byId[S.path.to].name) : "") + '"></div><datalist id="pathlist">' +
@@ -558,6 +583,8 @@
   dbody.addEventListener("click", function (ev) {
     var a = ev.target.closest("a[data-go]");
     if (a) select(a.getAttribute("data-go"), { center: true });
+    var tg = ev.target.closest("a.ttag");
+    if (tg) applyFilter("tag:" + tg.getAttribute("data-tag"));
   });
   document.getElementById("dclose").onclick = function () { select(null); };
 
@@ -570,7 +597,7 @@
     var geo = Q.geometry(S.vm, S.mode), parts = [];
     S.vm.tables.forEach(function (t) {
       var p = S.pos[t.id];
-      if (p) parts.push('<rect x="' + p[0] + '" y="' + p[1] + '" width="' + geo[t.id].w + '" height="' + geo[t.id].h + '" fill="#2b5797" opacity=".55"/>');
+      if (p) parts.push('<rect x="' + p[0] + '" y="' + p[1] + '" width="' + geo[t.id].w + '" height="' + geo[t.id].h + '" fill="' + (t.color || "#2b5797") + '" opacity=".55"/>');
     });
     parts.push('<rect class="vpr" id="vpr"/>');
     mini.innerHTML = parts.join("");

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/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,7 @@ def cmd_serve(args) -> int:
     from .serve import serve
 
     project = _open(args)
-    return serve(project, port=args.port, open_browser=not args.no_open)
+    return serve(project, port=args.port, open_browser=not args.no_open, read_only=args.read_only)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -328,6 +357,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")
@@ -398,6 +440,11 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--port", type=int, default=8765)
     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.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/dbt.py

@@ -113,6 +113,7 @@ class Tbl:
     group: str
     description: str = ""
     cols: dict[str, Col] = field(default_factory=dict)
+    tags: list[str] = field(default_factory=list)
 
     def col(self, name: str) -> Col:
         key = name.lower()
@@ -173,6 +174,17 @@ def _comment_lines(text: str) -> list[str]:
     return out
 
 
+def _node_tags(n: dict) -> list[str]:
+    """dbt tags (node-level and config), lowercased, in order, usable as qdbd tag names."""
+    out: list[str] = []
+    raw = list(n.get("tags") or []) + list((n.get("config") or {}).get("tags") or [])
+    for tag in raw:
+        tag = re.sub(r"[^a-z0-9_.-]+", "-", str(tag).lower()).strip("-.")
+        if tag and tag not in out:
+            out.append(tag)
+    return out
+
+
 class _Importer:
     def __init__(
         self,
@@ -231,7 +243,7 @@ class _Importer:
             name = self._base_name(n)
             if names[name] > 1:  # same name in two packages
                 name = f"{n.get('package_name')}.{name}"
-            t = Tbl(n["unique_id"], name, self._group(n), n.get("description") or "")
+            t = Tbl(n["unique_id"], name, self._group(n), n.get("description") or "", tags=_node_tags(n))
             self._columns(t, n)
             self.tables[t.uid] = t
             self.by_name.setdefault(n.get("name", "").lower(), []).append(t.uid)
@@ -435,6 +447,8 @@ class _Importer:
     # -- output -------------------------------------------------------------
     def render_table(self, t: Tbl) -> list[str]:
         lines = _comment_lines(t.description)
+        if t.tags:
+            lines.append(f"# @dbt-tags: {', '.join(t.tags)}")
         lines += [quote(t.name), "-"]
         for c in sorted(t.cols.values(), key=lambda c: (c.order, c.name.lower())):
             lines += _comment_lines(c.description)

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/html.py

@@ -37,6 +37,7 @@ BODY = """
         <input id="filter" type="text" placeholder="Filter: orders+1  group:marts  !stg_*" autocomplete="off"
           spellcheck="false" title="{filter_help}">
         <div class="fstat" id="fstat"></div>
+        <div class="tagbar" id="tagbar"></div>
       </div>
       <div id="tree" class="tree"></div>
     </div>
@@ -87,17 +88,31 @@ SIDE = """
 
 FILTER_HELP = (
     "dbt-style selectors. +x: x and what it references. x+: x and what references it. "
-    "N+x+N: hops. group:/file:/col: methods. a,b: both. !x: exclude."
+    "N+x+N: hops. group:/file:/col:/tag: methods. a,b: both. !x: exclude."
 )
 
 
-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 = ""
@@ -108,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.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/measure.py

@@ -11,6 +11,7 @@ from functools import cache
 from importlib import resources
 from pathlib import PurePosixPath
 
+from . import tags
 from .model import Column, Schema, Table
 
 STYLE = {
@@ -127,12 +128,17 @@ def model_json(schema: Schema) -> dict:
                 "b": {"t": r.b.table, "c": r.b.column, "card": r.b.card},
             }
         )
-    return {
+    tables = [
+        {**table_json(t), "group": groups[t.path], "file": t.path, "line": t.line} for t in schema.tables.values()
+    ]
+    legend = tags.annotate(schema, tables)
+    out = {
         "style": STYLE,
-        "tables": [
-            {**table_json(t), "group": groups[t.path], "file": t.path, "line": t.line} for t in schema.tables.values()
-        ],
+        "tables": tables,
         "rels": rels,
         "zoom": schema.zoom,
         "position": list(schema.position) if schema.position else None,
     }
+    if legend:
+        out["tags"] = legend
+    return out

{quickdbd_cli-0.1.7 → quickdbd_cli-0.1.9}/src/quickdbd_cli/model.py

@@ -58,6 +58,8 @@ class Table:
     aliases: list[str] = field(default_factory=list)
     columns: dict[str, Column] = field(default_factory=dict)
     comments: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)  # `# @tag: ...` comments
+    dbt_tags: list[str] = field(default_factory=list)  # `# @dbt-tags: ...`, written by `qdbd import dbt`
 
 
 @dataclass
@@ -84,6 +86,7 @@ class Schema:
     layout: dict[str, tuple[float, float]] = field(default_factory=dict)
     diagnostics: list[Diagnostic] = field(default_factory=list)
     general_comments: list[str] = field(default_factory=list)
+    tag_colors: dict[str, str] = field(default_factory=dict)  # `# @color TAG #hex`
 
     @property
     def errors(self) -> list[Diagnostic]: