demolab-cli 2.1.0__tar.gz → 2.2.0__tar.gz

demolab_cli-2.2.0/.gitattributes

@@ -0,0 +1 @@
+*.pdf binary

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/.github/workflows/publish.yml

@@ -45,8 +45,8 @@ jobs:
         env:
           TAG: v${{ steps.version.outputs.version }}
         run: |
-          if git rev-parse "$TAG" >/dev/null 2>&1; then
-            echo "$TAG already exists — skipping tag."
+          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
+            echo "$TAG already exists on origin — skipping tag."
           else
             git tag "$TAG"
             git push origin "$TAG"

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: demolab-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Lab notebook for computational science: Python tools produce per-run artifacts; Typst publishes them as a web bundle, per-entry PDFs, and a book.
 Project-URL: Homepage, https://github.com/eoinmurray/demolab
 Project-URL: Changelog, https://github.com/eoinmurray/demolab/blob/main/demolab_cli/CHANGELOG.md

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/AGENT.md

@@ -71,7 +71,8 @@ guide covers it, ground your answer in it — cite it or offer to start it.
 `demolab` lists them all. The loop: `uv run python experiments/expNNN.py` (run an experiment
 end-to-end — run the runner directly, there's no `demolab run` wrapper) · `demolab dev`
 (live-preview server — have the *user* run it in their own terminal) · `demolab build`
-(site + PDFs) · `demolab test`. Reference data ships in the package:
+(complete site + PDFs) · `demolab build <id>` (one entry PDF) · `demolab test`. Preview
+PDFs stay in the ignored site tree; run the complete build before publishing. Reference data ships in the package:
 `demolab docs STARTERS` (canonical first experiments — model file shapes on them, never copy
 blindly; `monte-carlo-pi` is the default) and `demolab docs DEMO` (the published docs site's
 source).

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/CHANGELOG.md

@@ -13,6 +13,33 @@ the runbook shows the entries between your version and the latest.
 
 ## [Unreleased]
 
+## [2.2.0] — 2026-08-07
+
+### Added
+- **Build one entry PDF with `demolab build <id>`.** The targeted build uses the same page
+  surface, branding, root, and artifact paths as the complete publication, while deliberately
+  leaving the website and combined book untouched.
+
+### Fixed
+- **PDF builds are reproducible instead of changing metadata on every run.** Every Typst compile
+  now uses a documented `2000-01-01T00:00:00Z` creation timestamp by default and respects an
+  explicit `SOURCE_DATE_EPOCH` override. PDFs are marked binary in new labs and this source repo.
+- **`demolab dev` no longer dirties committed publication PDFs.** Live preview still builds the
+  complete ignored website, including its PDF links, but no longer mirrors those preview PDFs into
+  `artifacts/pdfs/`; an explicit `demolab build` remains the publication step.
+
+## [2.1.1] — 2026-07-18
+
+### Fixed
+- **UPDATE now verifies the project environment after upgrading `demolab-cli`.** The runbook
+  explains that uv's package upgrade already refreshes targeted cache metadata, compares the
+  active `uv run demolab` version with the lock, and uses a targeted package reinstall when they
+  disagree. It explicitly avoids global cache deletion and `uvx` verification, which operate at
+  the wrong scope for an existing lab.
+- **Release tagging is idempotent against remote tags.** The publish workflow checks the remote
+  before pushing its release tag, avoiding a false-red release when the documented manual tag was
+  already pushed.
+
 ## [2.1.0] — 2026-07-18
 
 ### Added

demolab_cli-2.2.0/demolab_cli/VERSION

@@ -0,0 +1 @@
+2.2.0

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/build.py

@@ -42,6 +42,7 @@ ROOT = Path(os.environ.get("DEMOLAB_ROOT") or _paths.find_lab_root() or Path.cwd
 WRITINGS = ROOT / "writings"
 BUILD = ROOT / "temp" / "bundle"           # scratch: staged main.typ + manifest + deck PDFs
 MAIN = BUILD / "main.typ"                  # staged copy of the packaged typ/main.typ
+ENTRY_MAIN = BUILD / "entry.typ"           # staged single-entry PDF wrapper
 MANIFEST = BUILD / "index.json"            # scratch: id/asset lists main.typ reads
 DECKS = BUILD / "decks"                    # scratch: compiled deck PDFs, embedded as assets
 SITE = ROOT / "artifacts" / "site"         # bundle output (HTML + mp4 + pdfs/), gitignored
@@ -60,6 +61,13 @@ def _find_typst() -> str:
 
 
 TYPST = _find_typst()
+DEFAULT_CREATION_TIMESTAMP = "946684800"  # 2000-01-01T00:00:00Z
+
+
+def typst_compile(*args: str) -> list[str]:
+    """A reproducible Typst compile command shared by every PDF-producing path."""
+    timestamp = os.environ.get("SOURCE_DATE_EPOCH", DEFAULT_CREATION_TIMESTAMP)
+    return [TYPST, "compile", "--creation-timestamp", timestamp, *args]
 
 
 def stage() -> None:
@@ -69,6 +77,7 @@ def stage() -> None:
     _paths.stage(ROOT)
     BUILD.mkdir(parents=True, exist_ok=True)
     shutil.copy2(_paths.TYP / "main.typ", MAIN)
+    shutil.copy2(_paths.TYP / "entry.typ", ENTRY_MAIN)
 
 
 def discover():
@@ -141,8 +150,8 @@ def compile_decks(deck_ids: list[str]) -> list[str]:
     good = []
     for d in deck_ids:
         proc = subprocess.run(
-            [TYPST, "compile", "--root", str(ROOT),
-             str(WRITINGS / f"{d}.slide.typ"), str(DECKS / f"{d}.pdf")],
+            typst_compile("--root", str(ROOT),
+                          str(WRITINGS / f"{d}.slide.typ"), str(DECKS / f"{d}.pdf")),
             capture_output=True, text=True,
         )
         if proc.returncode == 0:
@@ -179,8 +188,8 @@ def compile_bundle(ids: list[str], deck_ids: list[str]) -> dict:
     while True:
         write_manifest(ids, deck_ids, broken=broken)
         proc = subprocess.run(
-            [TYPST, "compile", "--format", "bundle", "--features", "bundle,html",
-             "--root", str(ROOT), str(MAIN), str(SITE) + "/"],
+            typst_compile("--format", "bundle", "--features", "bundle,html",
+                          "--root", str(ROOT), str(MAIN), str(SITE) + "/"),
             capture_output=True, text=True,
         )
         if proc.returncode == 0:
@@ -230,6 +239,26 @@ def _warn_if_content_misplaced(ids: list[str]) -> None:
           file=sys.stderr)
 
 
+def compile_entry(entry_id: str, ids: list[str]) -> None:
+    """Compile one ordinary writing directly to its committed standalone PDF."""
+    if entry_id not in ids:
+        slide = WRITINGS / f"{entry_id}.slide.typ"
+        detail = " (it is a slide deck; use `demolab slides`)" if slide.exists() else ""
+        raise SystemExit(f"error: no buildable entry named {entry_id!r}{detail}")
+    PDFS.mkdir(parents=True, exist_ok=True)
+    proc = subprocess.run(
+        typst_compile("--root", str(ROOT), "--input", f"entry={entry_id}",
+                      "--input", f"has-brand={str((ROOT / 'demolab.yaml').exists()).lower()}",
+                      str(ENTRY_MAIN), str(PDFS / f"{entry_id}.pdf")),
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        sys.stderr.write(proc.stdout + proc.stderr)
+        raise subprocess.CalledProcessError(proc.returncode, proc.args, proc.stdout, proc.stderr)
+    print(f"built {entry_id} -> {PDFS.relative_to(ROOT)}/{entry_id}.pdf"
+          " (site and book not updated)", flush=True)
+
+
 def main() -> None:
     # --generate-only writes the manifest + deck PDFs without compiling the bundle: a hand
     # tool for inspecting what the compiler will see. (Dev serving is devserver.py, which runs
@@ -240,9 +269,16 @@ def main() -> None:
     # prose/CSS/lib edit doesn't pay for deck compilation it can't have affected. Safe only when
     # those PDFs exist (a full build ran first); a bare `demolab build` never skips.
     skip_decks = "--skip-decks" in sys.argv
+    no_mirror = "--no-mirror" in sys.argv
+    entry_args = [arg for arg in sys.argv[1:] if not arg.startswith("--")]
+    if len(entry_args) > 1:
+        raise SystemExit("error: build accepts at most one entry id")
     stage()
     ids = discover()
     _warn_if_content_misplaced(ids)
+    if entry_args:
+        compile_entry(entry_args[0], ids)
+        return
     deck_ids = discover_decks()
     # Zero writings is a valid state (a freshly `demolab scaffold`-ed repo): main.typ renders
     # a friendly empty-state homepage, so we build rather than error.
@@ -263,9 +299,10 @@ def main() -> None:
     broken = compile_bundle(ids, good_decks)
     good = [i for i in ids if i not in broken]
     # mirror the compiled PDFs (entries, book, and decks) to the committed artifacts/pdfs/
-    PDFS.mkdir(parents=True, exist_ok=True)
-    for pdf in sorted((SITE / "pdfs").glob("*.pdf")):
-        shutil.copy(pdf, PDFS / pdf.name)
+    if not no_mirror:
+        PDFS.mkdir(parents=True, exist_ok=True)
+        for pdf in sorted((SITE / "pdfs").glob("*.pdf")):
+            shutil.copy(pdf, PDFS / pdf.name)
     # The verbose detail (which ids built / stubbed, where the PDFs mirror) goes on its own line;
     # the CONCISE summary is printed LAST, because the dev-server watch loop echoes only build.py's
     # final stdout line on each rebuild. So a `demolab dev` session shows a terse one-liner, while a
@@ -273,7 +310,8 @@ def main() -> None:
     print(f"  entries: {', '.join(good)}"
           + (f"  ·  decks: {', '.join(good_decks)}" if good_decks else "")
           + (f"  ·  ⚠ stubbed: {', '.join(sorted(broken))}" if broken else "")
-          + f"  ·  pdfs -> {PDFS.relative_to(ROOT)}/")
+          + (f"  ·  pdfs -> {PDFS.relative_to(ROOT)}/" if not no_mirror
+             else "  ·  preview PDFs left untracked"))
     summary = f"built {len(good)} entries" + (f" + {len(good_decks)} decks" if good_decks else "")
     if broken:
         summary += f", {len(broken)} stubbed"

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/cli.py

@@ -303,7 +303,8 @@ def cmd_dev(args: argparse.Namespace) -> int:
 
 
 def cmd_build(args: argparse.Namespace) -> int:
-    return _mod("build", cwd=_paths.require_lab_root())
+    entry_args = [args.entry] if args.entry else []
+    return _mod("build", *entry_args, cwd=_paths.require_lab_root())
 
 
 def cmd_slides(args: argparse.Namespace) -> int:
@@ -379,6 +380,9 @@ def _build_parser() -> argparse.ArgumentParser:
             sp.add_argument("--demo", action="store_true", help="serve the shipped demo instead of your lab")
             sp.add_argument("--landing", action="store_true",
                             help="with --demo: preview the upstream landing page too")
+        elif name == "build":
+            sp.add_argument("entry", nargs="?",
+                            help="build only this entry PDF; omit for the complete publication")
     return p
 
 

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/devserver.py

@@ -172,6 +172,7 @@ def build(skip_decks: bool = False) -> tuple[bool, str]:
     DEMOLAB_ROOT pins the child to this server's ROOT (which may itself be an override —
     `demolab dev --demo` serves a materialised scratch lab)."""
     cmd = [sys.executable, "-m", "demolab_cli.build"]
+    cmd.append("--no-mirror")
     if skip_decks:
         cmd.append("--skip-decks")
     try:

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/guides/RULES.md

@@ -13,7 +13,7 @@ defined in [`GLOSSARY.md`](GLOSSARY.md).
 
 **1.1 — Python via `uv`.** Never call `python` / `python3` directly. Deps are pinned in the root `pyproject.toml` / `uv.lock`; run scripts with `uv run python <script>` (e.g. `uv run python tools/neuron/tool.py lif`); `uv sync` after pulling.
 
-**1.2 — Publishing via `typst`.** Use the `typst` CLI (an installed prerequisite, alongside `uv`). It compiles the site + PDFs (`demolab build` / `demolab dev`); the bundle build passes `--features bundle,html` (experimental, deliberately used here). No Node/`bun` — demolab publishes entirely with Typst.
+**1.2 — Publishing via `typst`.** Use the `typst` CLI (an installed prerequisite, alongside `uv`). It compiles the site + PDFs (`demolab build` / `demolab dev`); the bundle build passes `--features bundle,html` (experimental, deliberately used here). Typst receives a deterministic creation timestamp (`SOURCE_DATE_EPOCH` overrides the engine default), so unchanged PDFs stay byte-identical within a stable toolchain. No Node/`bun` — demolab publishes entirely with Typst.
 
 **1.3 — Prefer `demolab`.** Common commands are exposed through the `demolab` CLI — prefer `demolab <name>` (run `demolab` to list them). To check the toolchain *and* that the repo obeys these conventions, run the *Doctor the repo* runbook (*"doctor the repo"*).
 
@@ -77,6 +77,11 @@ The concrete annotated file tree is in [`STRUCTURE.md`](STRUCTURE.md); this sect
 - **Per-entry PDFs** — `artifacts/site/pdfs/<id>.pdf`.
 - **Book** — `artifacts/site/pdfs/book.pdf`: every entry, with a table of contents.
 
+For a PDF-only editing loop, `demolab build <id>` updates just
+`artifacts/pdfs/<id>.pdf`; it deliberately leaves the site and `book.pdf` untouched.
+`demolab dev` refreshes the complete ignored preview site without mirroring preview PDFs into
+the tracked publication directory. Run bare `demolab build` before publishing.
+
 **5.3 — What's committed.** PDFs are mirrored to the committed, shareable `artifacts/pdfs/`. `artifacts/site/` is a gitignored build output (CI regenerates + deploys it to Pages). CI does **not** run the experiments, so `artifacts/data/` **must** be committed — that record, not the ephemeral `temp/`, is what reaches the site.
 
 **5.4 — Numbers can't drift.** Each `writings/<id>.typ` reads its own bundle natively — `json("/artifacts/data/<id>/numbers.json")`, `#image("/artifacts/data/<id>/fig.png")` (compiled with `--root` at the repo root) — so the numbers and figures come straight from the run.

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/guides/STRUCTURE.md

@@ -67,7 +67,7 @@ lives in the installed `demolab-cli` package (site-packages), reached via `demol
 
 **S5 — The package vs your stuff.** The engine is the installed `demolab-cli` package — you never hand-edit it, and updating it is a dependency bump (§3.1). The gitignored `.demolab/` staging dir is the CLI's, not yours (§3.2). Everything else in the tree is yours: `tools/`, `experiments/`, `writings/`, `artifacts/`, `demolab.yaml`, and the root stubs `demolab init` laid down (§3.3).
 
-**S6 — Where the build goes.** `demolab build` globs `writings/*.typ` into `temp/bundle/index.json`, stages the engine's `main.typ` beside it, and compiles it to three targets in one pass: the web site → `artifacts/site/`, per-entry PDFs + `book.pdf` → `artifacts/site/pdfs/` (mirrored to `artifacts/pdfs/`). On an empty (freshly-initialised) tree the build still succeeds — it emits a single `index.html` with a friendly empty state, and skips `all.html`/collection pages/`book.pdf`. CI deploys `artifacts/site/` to GitHub Pages (§5.2, §5.3).
+**S6 — Where the build goes.** `demolab build` globs `writings/*.typ` into `temp/bundle/index.json`, stages the engine's `main.typ` beside it, and compiles it to three targets in one pass: the web site → `artifacts/site/`, per-entry PDFs + `book.pdf` → `artifacts/site/pdfs/` (mirrored to `artifacts/pdfs/`). `demolab build <id>` instead updates only `artifacts/pdfs/<id>.pdf`; `demolab dev` keeps preview PDFs in the ignored site tree and never mirrors them. On an empty (freshly-initialised) tree the complete build still succeeds — it emits a single `index.html` with a friendly empty state, and skips `all.html`/collection pages/`book.pdf`. CI deploys `artifacts/site/` to GitHub Pages (§5.2, §5.3).
 
 ## Scaffolding
 

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/runbooks/UPDATE.md

@@ -36,6 +36,26 @@ updating the engine can't touch the user's identity — that's the point.
    uv lock --upgrade-package demolab-cli && uv sync
    ```
 
+   `--upgrade-package demolab-cli` already implies uv's targeted
+   `--refresh-package demolab-cli`; do not clear uv's whole cache. After syncing, verify that the
+   project environment, not a globally cached or `uvx`-managed copy, is active:
+
+   ```sh
+   uv run demolab version
+   uv tree --locked | rg 'demolab-cli'
+   ```
+
+   The versions must agree. If they do not, repair only this package and verify again:
+
+   ```sh
+   uv sync --reinstall-package demolab-cli
+   uv run demolab version
+   ```
+
+   Stop and report the mismatch if it persists; never paper over it with `uv cache clean`, and do
+   not use `uvx demolab-cli` to verify an existing lab because that is a separate ephemeral
+   environment.
+
 4. **Rebuild.** `demolab build` — the CLI notices the version change, refreshes `.demolab/`,
    and prints a one-line notice pointing at the changelog. `demolab test` for good measure.
 

demolab_cli-2.2.0/demolab_cli/scaffold/skeleton/.gitattributes

@@ -0,0 +1 @@
+*.pdf binary

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/test_cli.py

@@ -38,6 +38,12 @@ def test_dev_arguments():
     assert bare_dev.port is None and bare_dev.demo is False and bare_dev.landing is False
 
 
+def test_build_accepts_optional_entry():
+    parser = cli._build_parser()
+    assert parser.parse_args(["build"]).entry is None
+    assert parser.parse_args(["build", "exp007"]).entry == "exp007"
+
+
 def test_demo_landing_passes_live_source_to_devserver(tmp_path, monkeypatch):
     scaffold = tmp_path / "package-scaffold"
     (scaffold / "skeleton").mkdir(parents=True)

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/test_devserver.py

@@ -7,6 +7,7 @@ HTTP request, no build) that an IPv4-only server gets wrong on Windows.
 """
 import socket
 import threading
+from types import SimpleNamespace
 
 from demolab_cli import devserver
 
@@ -84,6 +85,18 @@ def test_deck_affecting_triggers_on_slide_and_data():
     assert not devserver.deck_affecting(set())
 
 
+def test_dev_build_never_mirrors_preview_pdfs(monkeypatch):
+    captured = {}
+
+    def run(cmd, **kwargs):
+        captured["cmd"] = cmd
+        return SimpleNamespace(returncode=0, stdout="built\n", stderr="")
+
+    monkeypatch.setattr(devserver.subprocess, "run", run)
+    assert devserver.build() == (True, "built")
+    assert "--no-mirror" in captured["cmd"]
+
+
 def test_sync_landing_source_copies_updates_and_removal(tmp_path):
     source = tmp_path / "package" / "site" / "landing.typ"
     target = tmp_path / "preview" / "landing.typ"

{demolab_cli-2.1.0 → demolab_cli-2.2.0}/demolab_cli/test_engine_build.py

@@ -9,6 +9,7 @@ empty-state homepage rather than erroring.
 
 Needs the `typst` CLI on PATH (same as `demolab build`); skipped if it's missing.
 """
+import hashlib
 import os
 import re
 import shutil
@@ -18,7 +19,7 @@ from pathlib import Path
 
 import pytest
 
-from demolab_cli import _paths
+from demolab_cli import _paths, build
 
 SCAFFOLD = _paths.SCAFFOLD
 
@@ -40,14 +41,44 @@ def _assemble(root: Path, *, demo: bool) -> None:
                         ignore=shutil.ignore_patterns("landing.typ", "temp", "site"))
 
 
-def _build(root: Path) -> None:
+def _build(root: Path, entry: str | None = None) -> None:
     subprocess.run(
-        [sys.executable, "-m", "demolab_cli.build"],
+        [sys.executable, "-m", "demolab_cli.build", *([entry] if entry else [])],
         env={**os.environ, "DEMOLAB_ROOT": str(root)},
         check=True,
     )
 
 
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def test_complete_build_is_pdf_reproducible(tmp_path: Path) -> None:
+    root = tmp_path / "repo"
+    root.mkdir()
+    _assemble(root, demo=True)
+    _build(root)
+    first = {p.name: _sha256(p) for p in (root / "artifacts" / "pdfs").glob("*.pdf")}
+    _build(root)
+    second = {p.name: _sha256(p) for p in (root / "artifacts" / "pdfs").glob("*.pdf")}
+    assert second == first
+
+
+def test_targeted_build_writes_only_selected_pdf(tmp_path: Path) -> None:
+    root = tmp_path / "repo"
+    root.mkdir()
+    _assemble(root, demo=True)
+    shutil.rmtree(root / "artifacts" / "pdfs", ignore_errors=True)
+    _build(root, "ar018")
+    assert sorted(p.name for p in (root / "artifacts" / "pdfs").glob("*.pdf")) == ["ar018.pdf"]
+    assert not (root / "artifacts" / "site").exists()
+
+
+def test_source_date_epoch_overrides_default(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setenv("SOURCE_DATE_EPOCH", "1234567890")
+    assert build.typst_compile("input.typ")[3] == "1234567890"
+
+
 def test_demo_fixture_builds_full_site(tmp_path: Path) -> None:
     root = tmp_path / "repo"
     root.mkdir()

demolab_cli-2.2.0/demolab_cli/typ/entry.typ

@@ -0,0 +1,11 @@
+// Standalone entry-PDF root used by `demolab build <id>`.
+#import "/.demolab/lib.typ": *
+
+#let entry-id = sys.inputs.entry
+#let has-brand = sys.inputs.at("has-brand", default: "false") == "true"
+#let config = if has-brand { yaml("/demolab.yaml") } else { (:) }
+#let brand = default-brand + config
+#import "/writings/" + entry-id + ".typ" as writing
+
+#set document(title: writing.meta.title)
+#numbered-pages(entry-page(writing.meta, writing.body, id: entry-id, brand: brand))

demolab_cli-2.1.0/demolab_cli/VERSION

@@ -1 +0,0 @@
-2.1.0