bluebeam-set-manager 0.1.0__tar.gz

bluebeam_set_manager-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Ruff lint
+        run: uvx ruff check --output-format=github .
+
+      - name: Ruff format check
+        run: uvx ruff format --check .
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history + tags so hatch-vcs can resolve a version.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

bluebeam_set_manager-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,105 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed (e.g. `v1.2.3`).
+# The version is derived from the tag by hatch-vcs, so the tag is the single
+# source of truth — no version bump commit is needed.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Ruff lint
+        run: uvx ruff check --output-format=github .
+
+      - name: Ruff format check
+        run: uvx ruff format --check .
+
+  build:
+    name: Build distribution
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history + tags so hatch-vcs resolves the version from the tag.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify the built version matches the tag
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          built=$(ls dist/*.whl | sed -E 's/.*bluebeam_set_manager-([^-]+)-.*/\1/')
+          echo "tag=$tag built=$built"
+          if [ "$tag" != "$built" ]; then
+            echo "::error::Built version '$built' does not match tag '$tag'." \
+                 "Is the tag on a clean commit?"
+            exit 1
+          fi
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the trusted publisher configured on PyPI.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bluebeam-set-manager
+    permissions:
+      # Required for Trusted Publishing (OIDC) — no API token needed.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

bluebeam_set_manager-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+
+# Backups written next to the original .bex on Save
+*.bak-*
+
+# Snapshots
+*.svg
+
+# Stray uv binary if copied into the project root
+uv.exe
+
+# Example Files
+examples/

bluebeam_set_manager-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: bluebeam-set-manager
+Version: 0.1.0
+Summary: TUI manager for Bluebeam Revu page-set (.bex) files
+Requires-Python: >=3.12
+Requires-Dist: textual>=0.80

bluebeam_set_manager-0.1.0/docs/superpowers/specs/2026-05-29-bluebeam-set-manager-design.md

@@ -0,0 +1,188 @@
+# Bluebeam Set Manager — Design Spec
+
+**Date:** 2026-05-29
+**Status:** Approved for implementation
+
+## Purpose
+
+A Python TUI for managing Bluebeam Revu page-set files (`.bex`, XML). It presents
+every sheet in the set as a tree (Category → Sheet Number → Revision), lets the user
+view and edit a selected page's tags/metadata in a properties pane, and supports
+batch sheet renumbering via an Excel-pasteable two-column table. All edits are
+buffered (auto-saved to an in-memory buffer) and only written to disk on an explicit
+Save / Save-As command.
+
+## File format (observed from `examples/DP-P WBMS - STR Markups.bex`)
+
+- UTF-8 **with BOM**, **CRLF** line endings, root `<BluebeamRevuPageSet Version="1">`.
+- Top-level set settings: `PageSort`, `PageShowSetting`, `PageSortType`, `AddendumKey`
+  (CDATA), `WildcardFilter`, `CategoryType`, `CategorizeBy`, etc. (display-only).
+- A sequence of `<File>` elements. Each `<File>`:
+  - Contains the source-PDF path as **raw CDATA text** (`SP:` SharePoint URL),
+    written **both before and after** the page list — interleaved with child elements.
+  - `<Category>` (e.g. "Structural").
+  - One or more `<Page>` elements, each with:
+    - `<Label>` (page label within source PDF)
+    - `<Tags>` containing `<Tag ID="SheetName">`, `<Tag ID="SheetNumber">`,
+      `<Tag ID="RevisionNumber">`, and named tags like
+      `<Tag Name="Plot Date" Type="Date" DateFormat="M/d/yyyy">3/12/2025</Tag>`
+    - `<Width>`, `<Height>`, `<Index>`
+- A "sheet instance" = one `<Page>`. The same SheetNumber can recur across pages/files
+  with different revision numbers.
+
+**Quirk:** Bluebeam writes the CDATA path interleaved with child elements inside
+`<File>`. Standard XML libraries will not round-trip this byte-for-byte, so saving uses
+surgical byte-span edits (see below) rather than tree re-serialization.
+
+## Architecture
+
+```
+bluebeam_set_manager/
+├── model/
+│   ├── document.py      # SetDocument: in-memory model of the .bex
+│   ├── page.py          # Page, Tag, FileEntry dataclasses
+│   └── source.py        # SourceText: original bytes + BOM/line-ending + Span
+├── io/
+│   ├── parser.py        # bytes -> SetDocument, recording byte spans per editable tag
+│   └── writer.py        # SetDocument + buffer -> bytes via surgical span splicing
+├── ops/
+│   ├── buffer.py        # EditBuffer: pending changes, dirty flag, apply/revert
+│   └── renumber.py      # renumber planning, validation, diff generation (headless)
+└── tui/
+    ├── app.py           # Textual App, key bindings, save/save-as/quit
+    ├── tree_pane.py     # Category > SheetNumber > Revision tree
+    ├── props_pane.py    # properties editor for the selected page
+    └── renumber_screen.py  # modal: existing/new table + preview diff
+```
+
+**Data flow:** load → `parser` builds `SetDocument` + span map → tree/props render
+*effective* values (buffer overlaid on model) → edits recorded in `EditBuffer` (model
+not mutated) → on Save, `writer` splices buffered changes into original bytes via the
+span map → timestamped `.bak` written, then original overwritten.
+
+## Data model
+
+```python
+Span = tuple[int, int]  # (start, end) byte offsets into original file
+
+@dataclass
+class Tag:
+    key: str                  # "SheetName" | "SheetNumber" | "RevisionNumber" | named e.g. "Plot Date"
+    value: str
+    kind: Literal["id", "named"]
+    attrs: dict[str, str]     # named-tag attrs: Type, DateFormat, ...
+    value_span: Span | None   # byte span of value text; None for buffer-new tags
+
+@dataclass
+class Page:
+    label: str                # read-only
+    tags: list[Tag]
+    width: int; height: int; index: int   # read-only
+    file_ref: FileEntry
+    page_id: str              # synthetic stable id: f"{file_idx}:{page_idx}"
+    tags_insert_offset: int   # byte offset just before </Tags>, for new-tag insertion
+    # accessors: sheet_number, sheet_name, revision
+
+@dataclass
+class FileEntry:
+    category: str             # read-only (v1)
+    path: str                 # SP: path, read-only
+    pages: list[Page]
+
+@dataclass
+class SetDocument:
+    settings: dict[str, str]  # display-only
+    files: list[FileEntry]
+    source: SourceText
+    def pages(self) -> Iterator[Page]: ...
+```
+
+**Tree projection** from `document.pages()`:
+- L1 Category (distinct, sorted)
+- L2 SheetNumber (distinct within category, natural-sorted: S-100 < S-110 < S-301)
+- L3 one node per distinct RevisionNumber sharing that number; payload = the Page.
+
+Selecting an L3 node loads that Page into the properties pane.
+
+## Editable vs read-only
+
+- **Editable:** core sheet tags (SheetNumber, SheetName, RevisionNumber) and named/custom
+  tags (value + attrs; add/remove custom tags).
+- **Read-only (displayed):** Category, Label, Width, Height, Index, source path,
+  set-level settings.
+
+## Edit buffer & save semantics
+
+```python
+@dataclass
+class TagEdit:
+    page_id: str
+    tag_key: str
+    new_value: str | None     # None => delete tag
+    new_attrs: dict | None
+
+class EditBuffer:
+    edits: dict[tuple[str, str], TagEdit]   # keyed (page_id, tag_key); last-write-wins
+    def set_tag(page_id, key, value): ...
+    def add_tag(page_id, key, value, attrs): ...
+    def remove_tag(page_id, key): ...
+    def is_dirty() -> bool
+    def effective_value(page, key): ...
+    def revert_all(): ...
+```
+
+- **Auto-save to buffer:** props-pane field edits commit on blur/Enter via `set_tag`.
+  Tree and props render effective values; a `●` dirty marker shows in the title bar.
+- **Save (`Ctrl+S`):** writer resolves edits to spans/insertions, splices into original
+  bytes **back-to-front** (offsets stay valid), writes
+  `filename.bex.bak-YYYYMMDD-HHMMSS`, overwrites `filename.bex`, clears buffer.
+- **Save-As (`Ctrl+Shift+S`):** same splice to a new path (no backup; original untouched);
+  active file switches to the new path.
+- **Quit dirty:** modal confirm (Save / Discard / Cancel).
+- Renumbering writes through the **same buffer** (batch `set_tag` on SheetNumber), so it
+  is buffered and revertable until explicit Save.
+
+## Batch renumbering
+
+Modal (`R`) with an editable two-column `DataTable`: **Existing** | **New**.
+
+- **Input:** type into cells, or **paste** a two-column block from Excel (split on
+  tab/newline; rows auto-added). Empty rows ignored; whitespace trimmed.
+- **Plan & validate (Preview):**
+  1. Build `{existing → new}`. Reject duplicate `existing` keys and duplicate `new`
+     values inline.
+  2. Match **all pages** whose SheetNumber == existing, across all files/revisions.
+  3. **Warn on no-match:** existing value matching zero pages.
+  4. **Warn on collision:** new value already present in the set and not itself being
+     renumbered away.
+  5. **Preview diff:** one row per affected page —
+     `Category · old# · rev · SheetName → new#`; warnings banner above.
+- **Apply:** push changes into `EditBuffer` as SheetNumber edits (**SheetNumber only**;
+  Name/Label untouched). Tree rebuilds, dirty marker on. File untouched until Save.
+- Engine `ops/renumber.py` is **headless/pure**: `(SetDocument, mapping) -> (plan, warnings)`.
+
+## Error handling
+
+- **Parse:** non-`BluebeamRevuPageSet` files fail with a clear message. Pages with
+  missing expected tags are still listed; missing fields show `(none)`.
+- **Save:** writer **round-trip self-check** — spliced output must re-parse to the same
+  logical model before overwrite; on mismatch, abort and keep original. Backup-write
+  failure aborts the save.
+- **Encoding:** preserve detected BOM + CRLF; XML-escape edited values (`&`, `<`, `>`)
+  — the example contains `B&P`.
+
+## Testing
+
+pytest. Coverage:
+- Parser span accuracy (spans map to correct value text).
+- Writer round-trip: load → save with no edits → byte-identical output.
+- Single-tag edit splice correctness.
+- Renumber planning: match / no-match / collision / duplicate-key.
+- Buffer revert.
+Fixtures: bundled `examples/*.bex` plus small synthetic snippets.
+
+## Stack & tooling
+
+- Python ≥ 3.12, **uv** for venv + dependency management (`pyproject.toml`).
+- Runtime dep: `textual`. Dev dep: `pytest`.
+- Entry point: `bsm` console script and `python -m bluebeam_set_manager <file.bex>`.

bluebeam_set_manager-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "bluebeam-set-manager"
+description = "TUI manager for Bluebeam Revu page-set (.bex) files"
+readme = "README.md"
+requires-python = ">=3.12"
+version = "0.1.0"
+dependencies = [
+    "textual>=0.80",
+]
+
+[project.scripts]
+bsm = "bluebeam_set_manager.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bluebeam_set_manager"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

bluebeam_set_manager-0.1.0/src/bluebeam_set_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Bluebeam Revu page-set (.bex) manager — TUI."""
+
+__version__ = "0.1.0"

bluebeam_set_manager-0.1.0/src/bluebeam_set_manager/__main__.py

@@ -0,0 +1,21 @@
+"""CLI entry point: bsm [path-to-file.bex]"""
+
+from __future__ import annotations
+
+import argparse
+
+from .tui import run
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="bsm",
+        description="TUI manager for Bluebeam Revu page-set (.bex) files.",
+    )
+    ap.add_argument("file", nargs="?", help="Path to a .bex page-set file to open.")
+    args = ap.parse_args()
+    run(args.file)
+
+
+if __name__ == "__main__":
+    main()

bluebeam_set_manager-0.1.0/src/bluebeam_set_manager/io/__init__.py

@@ -0,0 +1,15 @@
+"""Parsing and writing of .bex files."""
+
+from .parser import parse, parse_bytes, ParseError
+from .writer import render, save, save_as, BackupError, RoundTripError
+
+__all__ = [
+    "parse",
+    "parse_bytes",
+    "ParseError",
+    "render",
+    "save",
+    "save_as",
+    "BackupError",
+    "RoundTripError",
+]

bluebeam_set_manager-0.1.0/src/bluebeam_set_manager/io/parser.py

@@ -0,0 +1,146 @@
+"""Parse a Bluebeam .bex page set into a SetDocument, recording char spans.
+
+The parser is deliberately regex/offset based rather than DOM based: Bluebeam writes
+the source-PDF path as raw CDATA interleaved with child elements inside ``<File>``,
+which a standard XML library will not round-trip. We only need a navigable model plus
+the precise character spans of editable tag values, so a tolerant scan is the right
+tool — and it lets the writer leave every untouched character exactly as it was.
+"""
+
+from __future__ import annotations
+
+import re
+from xml.sax.saxutils import unescape
+
+from ..model import FileEntry, Page, SetDocument, SourceText, Tag
+
+_ROOT_RE = re.compile(r"<BluebeamRevuPageSet\b([^>]*)>")
+_FILE_RE = re.compile(r"<File>(.*?)</File>", re.DOTALL)
+_CATEGORY_RE = re.compile(r"<Category>(.*?)</Category>", re.DOTALL)
+_CDATA_RE = re.compile(r"<!\[CDATA\[(.*?)\]\]>", re.DOTALL)
+_PAGE_RE = re.compile(r"<Page>(.*?)</Page>", re.DOTALL)
+_LABEL_RE = re.compile(r"<Label>(.*?)</Label>", re.DOTALL)
+_WIDTH_RE = re.compile(r"<Width>(\d+)</Width>")
+_HEIGHT_RE = re.compile(r"<Height>(\d+)</Height>")
+_INDEX_RE = re.compile(r"<Index>(\d+)</Index>")
+_TAGS_RE = re.compile(r"<Tags>(.*?)</Tags>", re.DOTALL)
+_TAG_RE = re.compile(r"<Tag\b([^>]*)>(.*?)</Tag>", re.DOTALL)
+_ATTR_RE = re.compile(r'(\w+)\s*=\s*"([^"]*)"')
+# Simple set-level settings: <Name>value</Name> or <Name><![CDATA[..]]></Name>.
+_SETTING_RE = re.compile(r"<(\w+)>(?:<!\[CDATA\[(.*?)\]\]>|([^<]*))</\1>", re.DOTALL)
+
+
+class ParseError(Exception):
+    """Raised when the input is not a recognizable Bluebeam page set."""
+
+
+def parse_bytes(raw: bytes, path: str | None = None) -> SetDocument:
+    return parse(SourceText.from_bytes(raw), path=path)
+
+
+def parse(source: SourceText, path: str | None = None) -> SetDocument:
+    text = source.text
+    root = _ROOT_RE.search(text)
+    if root is None:
+        raise ParseError("Not a BluebeamRevuPageSet file (missing root element).")
+
+    root_attrs = dict(_ATTR_RE.findall(root.group(1)))
+    body_start = root.end()
+    first_file = _FILE_RE.search(text)
+    settings_region_end = first_file.start() if first_file else len(text)
+    settings = _parse_settings(text, body_start, settings_region_end)
+
+    files: list[FileEntry] = []
+    for file_idx, fmatch in enumerate(_FILE_RE.finditer(text)):
+        inner_base = fmatch.start(1)
+        inner = fmatch.group(1)
+        cat_m = _CATEGORY_RE.search(inner)
+        category = unescape(cat_m.group(1).strip()) if cat_m else ""
+        path_m = _CDATA_RE.search(inner)
+        src_path = path_m.group(1) if path_m else ""
+
+        entry = FileEntry(category=category, path=src_path, pages=[])
+        for page_idx, pmatch in enumerate(_PAGE_RE.finditer(inner)):
+            page = _parse_page(
+                inner_base + pmatch.start(1), pmatch.group(1), f"{file_idx}:{page_idx}"
+            )
+            page.file_ref = entry
+            entry.pages.append(page)
+        files.append(entry)
+
+    return SetDocument(
+        settings=settings,
+        files=files,
+        source=source,
+        path=path,
+        root_attrs=root_attrs,
+    )
+
+
+def _parse_settings(text: str, start: int, end: int) -> dict[str, str]:
+    region = text[start:end]
+    settings: dict[str, str] = {}
+    for m in _SETTING_RE.finditer(region):
+        name = m.group(1)
+        if name in ("File", "Page", "Tags", "Tag"):
+            continue
+        value = m.group(2) if m.group(2) is not None else (m.group(3) or "")
+        settings[name] = value
+    return settings
+
+
+def _parse_page(page_base: int, inner: str, page_id: str) -> Page:
+    """`page_base` is the absolute offset (in full text) of `inner`'s first char."""
+    label_m = _LABEL_RE.search(inner)
+    label = unescape(label_m.group(1)) if label_m else ""
+    w_m = _WIDTH_RE.search(inner)
+    h_m = _HEIGHT_RE.search(inner)
+    i_m = _INDEX_RE.search(inner)
+    width = int(w_m.group(1)) if w_m else 0
+    height = int(h_m.group(1)) if h_m else 0
+    index = int(i_m.group(1)) if i_m else 0
+
+    tags: list[Tag] = []
+    tags_insert_offset = page_base + len(inner)  # fallback: end of page
+    tags_m = _TAGS_RE.search(inner)
+    if tags_m:
+        tags_inner_base = page_base + tags_m.start(1)
+        tags_insert_offset = page_base + tags_m.end(1)  # start of "</Tags>"
+        for tm in _TAG_RE.finditer(tags_m.group(1)):
+            tags.append(_parse_tag(tags_inner_base, tm))
+
+    return Page(
+        label=label,
+        tags=tags,
+        width=width,
+        height=height,
+        index=index,
+        page_id=page_id,
+        tags_insert_offset=tags_insert_offset,
+    )
+
+
+def _parse_tag(tags_inner_base: int, tm: "re.Match") -> Tag:
+    attrs = dict(_ATTR_RE.findall(tm.group(1)))
+    value = unescape(tm.group(2))
+    full_span = (tags_inner_base + tm.start(), tags_inner_base + tm.end())
+    value_span = (tags_inner_base + tm.start(2), tags_inner_base + tm.end(2))
+
+    if "ID" in attrs:
+        return Tag(
+            key=attrs["ID"],
+            value=value,
+            kind="id",
+            attrs={},
+            value_span=value_span,
+            full_span=full_span,
+        )
+    name = attrs.pop("Name", "")
+    return Tag(
+        key=name,
+        value=value,
+        kind="named",
+        attrs=attrs,
+        value_span=value_span,
+        full_span=full_span,
+    )