Modernization phase 1.4 (#110)

* add feature branch audit file

* Phase 1.4: Migrate build backend from setuptools to hatchling (#109)

- Replace setuptools with hatchling as build backend
- Hatchling is git-aware: sdist now includes all tracked files by default

Note: This work was completed with AI assistance (Claude Code).

* Update dependencies: autobahn>=25.12.1, zlmdb>=25.12.1

Align with the latest WAMP ecosystem releases using hatchling.

Note: This work was completed with AI assistance (Claude Code).

* Add Crossbar.io logo to documentation with scour optimization

- Add crossbar.svg to docs/_graphics/ (source)
- Add _build-images just recipe to optimize SVGs using scour
- Update docs recipe to call _build-images before sphinx-build
- Add html_logo to conf.py pointing to optimized logo
- Add scour>=0.38 to dev dependencies
- Add docs/_static/img/ to .gitignore (generated files)

Note: This work was completed with AI assistance (Claude Code).

* Add install-dev-latest and install-dev-local recipes

- Add dev-latest optional dependency for GitHub master branches
- Add [tool.hatch.metadata] allow-direct-references = true
- Add install-dev-latest just recipe for GitHub dependencies
- Add install-dev-local just recipe for local sibling repos

This enables development when upstream WAMP packages (txaio,
autobahn-python, zlmdb) have unreleased versions not yet on PyPI.

Note: This work was completed with AI assistance (Claude Code).

* docs: standardize Sphinx configuration across WAMP projects

- Modernize conf.py with Furo theme and Noto fonts from Google Fonts
- Add Crossbar.io logo (crossbar_icon.svg)
- Standardize extensions, project metadata, and spelling configuration
- Add spelling_wordlist.txt and docs-spelling just recipe

Note: This work was completed with AI assistance (Claude Code).

* docs: add install-docs just recipe

Add missing install-docs recipe required by docs-spelling and
_build-images recipes.

Note: This work was completed with AI assistance (Claude Code).

* build: add docs optional dependency for Sphinx documentation

- Add [docs] optional dependency group to pyproject.toml
- Add autoapi_dirs configuration to docs/conf.py

Note: This work was completed with AI assistance (Claude Code).

* docs: update trademark holder to typedef int GmbH

Note: This work was completed with AI assistance (Claude Code).

* Add docs/ai/index.rst for AI policy documentation

- Create docs/ai/index.rst to collect AI-related docs in toctree
- Add Contents section with toctree to README.rst (which is symlinked
  as docs/index.rst)

This organizes AI policy documentation under a dedicated section.

Note: This work was completed with AI assistance (Claude Code).

* Add OVERVIEW.md from wamp-ai submodule for project docs

- Update .ai submodule to include OVERVIEW.md with wamp-xbr section
- Add OVERVIEW.md symlink to project root (via just setup-repo)
- Add docs/OVERVIEW.md symlink for Sphinx documentation
- Add OVERVIEW.md to README.rst toctree

OVERVIEW.md provides context about the WAMP project ecosystem.

Note: This work was completed with AI assistance (Claude Code).

* Modernize Sphinx docs: Furo theme, branding, favicon

- Add sync-images recipe to copy logo/favicon from crossbar
- Update conf.py with Crossbar.io Bright Yellow (#ffff00) brand colors
- Add html_favicon setting for browser tab icon
- Add pygments_dark_style for dark mode code highlighting
- Update docs recipe to depend on sync-images

Part of docs consistency effort across WAMP Python projects.

Note: This work was completed with AI assistance (Claude Code).

* add after sync-images and gitignore partial update

* Standardize docs: .gitignore and AutoAPI configuration

- Add docs/autoapi/ to .gitignore
- Standardize AutoAPI config to match txaio pattern:
  - autoapi_add_toctree_entry = True
  - autoapi_keep_files = False
  - autoapi_generate_api_docs = True
  - autoapi_member_order = "alphabetical"
  - Consistent autoapi_options and autoapi_ignore patterns

Note: This work was completed with AI assistance (Claude Code).

* Standardize docs: autoapi options, standalone index.rst, master_doc

- Add private-members and special-members to autoapi_options
- Change master_doc from "contents" to "index"
- Remove contents.rst, create standalone index.rst (was symlink to README.rst)
- Update page title to "Crossbar.io Database Library"

Note: This work was completed with AI assistance (Claude Code).

* Convert README.rst to README.md, add AI_ACKNOWLEDGEMENT.md

- Convert README.rst to README.md using pandoc
- Reference AI_ACKNOWLEDGEMENT.md in docs/ai/index.rst toctree

Note: This work was completed with AI assistance (Claude Code).

* Standardize docs structure per STD-TOC.md

- Add overview.rst, installation.rst, getting-started.rst
- Add releases.rst, changelog.rst, contributing.rst
- Add programming-guide/index.rst consolidating database sections
- Update index.rst with standardized ToC order

Note: This work was completed with AI assistance (Claude Code).

* Standardize LICENSE with SPDX header and add docs copyright footer

- Add YAML-formatted SPDX license metadata header to LICENSE
- Add copyright/trademark footer to docs/index.rst
- MIT license year based on first git commit (2020)

Note: This work was completed with AI assistance (Claude Code).

* Add CONTRIBUTING.md, update RTD config, and update docs

- Add root-level CONTRIBUTING.md with contribution guidelines
- Update .readthedocs.yaml for consistent RTD builds with docs dependency
- Update docs/contributing.rst to include CONTRIBUTING.md via MyST parser

Note: This work was completed with AI assistance (Claude Code).

* docs: Rename Overview to Introduction, Releases to Release Notes

Standardize documentation page titles across the WAMP project group:
- Rename 'Overview' page to 'Introduction'
- Rename 'Releases' page to 'Release Notes'

Note: This work was completed with AI assistance (Claude Code).

* docs: Add sphinx_auto_section_anchors + release workflow recipes

- Update .cicd submodule to include sphinx_auto_section_anchors extension
- Add extension to docs/conf.py with path to .cicd/scripts
- Add version links (GitHub/PyPI/RTD) to releases.rst
- Add Release Workflow documentation section for maintainers
- Add prepare-changelog, draft-release, prepare-release justfile recipes

Note: This work was completed with AI assistance (Claude Code).

* docs: Enable auto_section_anchor_force for stable HTML anchors

This ensures the sphinx_auto_section_anchors extension overwrites
auto-generated ids (id1, id2, etc.) with slug-based anchors like
#25-12-1 instead of #id3.

Note: This work was completed with AI assistance (Claude Code).

* docs: Add git hooks steps to release workflow

- Add Step 4: Disable Git Hooks (if needed)
- Add Step 6: Enable Git Hooks (if previously disabled)
- Renumber remaining steps accordingly

Note: This work was completed with AI assistance (Claude Code).

* Standardize project badges

- Add 6 core badges: PyPI, Python, CI, Docs (RTD), License, Downloads
- Apply consistent badge format to both README.md and docs/index.rst
- Use RTD native badge for documentation status

Note: This work was completed with AI assistance (Claude Code).

* Update .cicd submodule: fix linting error

Pull in wamp-cicd commit 08c9305 which removes unused variable
in sphinx_auto_section_anchors.py (F841 linting error).

Note: This work was completed with AI assistance (Claude Code).

* Fix RST badge rendering: disable override_image_directive

Set override_image_directive=False in sphinxcontrib-images config
to preserve standard RST image directive :target: option support.

This fixes badge substitutions in docs/index.rst that require the
:target: option for clickable badge links.

Note: This work was completed with AI assistance (Claude Code).

* Add conf.py comment and require Sphinx>=8.2.3

- Add explanatory comment for override_image_directive=False setting
  explaining it's required for RST badge :target: option support
- Update sphinx>=8.2.3 in docs optional dependency (highest version
  compatible with furo's sphinx<9.0 constraint)

Note: This work was completed with AI assistance (Claude Code).

* Add submodules config to .readthedocs.yaml, fix release.yml tag_name

- Add submodules config for .cicd submodule (sphinx_auto_section_anchors.py)
- Add explicit tag_name to release-production GitHub Release step
  (fixes "GitHub Releases requires a tag" error in workflow_run context)

Note: This work was completed with AI assistance (Claude Code).

* Fix RTD submodules configuration (remove invalid depth key)

Use explicit submodule list instead of 'include: all':
- .ai for AI/audit docs
- .cicd for sphinx_auto_section_anchors extension

Note: This work was completed with AI assistance (Claude Code).

* Remove dev-latest dependency and update .cicd submodule

- Remove dev-latest optional dependency (PyPI rejects direct URLs)
- Remove allow-direct-references from hatch.metadata
- Remove install-dev-latest just recipe
- Update .cicd submodule to latest (2691c4b)

Note: This work was completed with AI assistance (Claude Code).

* Fix readme path: README.rst -> README.md

The README was converted to Markdown but pyproject.toml still
referenced the old .rst file.

Note: This work was completed with AI assistance (Claude Code).

* Use zlmdb's vendored flatbuffers instead of separate package

- Hand-written code: change `import flatbuffers` to `from zlmdb import flatbuffers`
- Generated code (cfxdb/gen/): register vendored flatbuffers in sys.modules
- Monkey-patch zlmdb to add `zlmdb.flatbuffers` and `zlmdb.setup_flatbuffers_import`
  (TEMPORARY: until zlmdb >= 25.12.2 with native support)

This removes the implicit dependency on a separate flatbuffers package.
cfxdb now uses flatbuffers exclusively through zlmdb.

Note: This work was completed with AI assistance (Claude Code).

* Fix CI: Ruff formatting and docs dependencies

- Apply Ruff formatting to __init__.py files (single to double quotes)
- Add install-docs step to Documentation workflow job

Note: This work was completed with AI assistance (Claude Code).

* Fix ruff linting: import sorting and exclude generated code

- Exclude src/cfxdb/gen from ruff linting (auto-generated flatbuffers code)
- Fix import sorting (I001) in all source files via ruff --fix
- Combine zlmdb imports: `from zlmdb import flatbuffers` merged with
  other zlmdb imports where applicable

Note: This work was completed with AI assistance (Claude Code).

* Modernize CI/CD workflows with chain-of-custody verification

main.yml changes:
- Add tags trigger ('v*') so tag pushes trigger the workflow
- Add workflow_dispatch for manual triggering
- Add permissions block (contents: read, pull-requests: read)
- Add new "Build Distribution" job that:
  - Builds sdist and wheel after check/test pass
  - Uploads artifacts using upload-artifact-verified action
  - Ensures chain-of-custody: same artifacts that pass tests get released

release.yml changes:
- Use download-artifact-verified to download verified artifacts from main
- Use check-release-fileset action for validation (replaces inline scripts)
- Use validate-audit-file action for production releases
- Add actions: read permission for artifact download
- Dynamic artifact name discovery (with checksum suffix)
- Cleaner job structure with clear section comments

This brings cfxdb workflows in line with autobahn-python patterns:
- Chain of custody: artifacts built once, verified throughout
- Reusable actions from wamp-proto/wamp-cicd
- Proper release workflow triggering via workflow_run

Note: This work was completed with AI assistance (Claude Code).

* Add release notes and changelog for v25.12.1

- Add 25.12.1 entry to docs/releases.rst with links to GitHub, PyPI, RTD
- Add 25.12.1 changelog entry to docs/changelog.rst with:
  - New: build system modernization, just recipes, uv, ruff, ty, Sphinx/MyST
  - Fix: flatbuffers import, import sorting, exclude gen/ from linting
  - Other: dependency updates, Python version support changes

Note: This work was completed with AI assistance (Claude Code).

Author: oberstet

.ai

@@ -0,0 +1,8 @@
+- [ ] I did **not** use any AI-assistance tools to help create this pull request.
+- [x] I **did** use AI-assistance tools to *help* create this pull request.
+- [x] I have read, understood and followed the project's AI_POLICY.md when creating code, documentation etc. for this pull request.
+
+Submitted by: @oberstet
+Date: 2025-12-05
+Related issue(s): #109
+Branch: oberstet:modernization-phase-1.4

.audit/oberstet_modernization-phase-14.md

@@ -4,9 +4,16 @@ on:
   push:
     branches:
       - master
+    tags:
+      - 'v*'
   pull_request:
     branches:
       - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
 
 jobs:
   identifiers:
@@ -125,6 +132,58 @@ jobs:
         run: |
           just create cpy311
           just install-dev cpy311
+          just install-docs cpy311
 
       - name: Build documentation
         run: just docs cpy311
+
+  # Build distribution packages (sdist + wheel)
+  # Artifacts are uploaded with checksums for chain-of-custody verification
+  build:
+    name: Build Distribution
+    needs: [identifiers, check, test]
+    runs-on: ubuntu-24.04
+
+    env:
+      BASE_REPO: ${{ needs.identifiers.outputs.base_repo }}
+      BASE_BRANCH: ${{ needs.identifiers.outputs.base_branch }}
+      PR_NUMBER: ${{ needs.identifiers.outputs.pr_number }}
+      PR_REPO: ${{ needs.identifiers.outputs.pr_repo }}
+      PR_BRANCH: ${{ needs.identifiers.outputs.pr_branch }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Create venv and install build tools
+        run: |
+          just create cpy311
+          just install-build-tools cpy311
+
+      - name: Build distribution packages
+        run: just dist cpy311
+
+      - name: Verify packages
+        run: just verify-dist cpy311
+
+      - name: List built packages
+        run: |
+          echo "Built packages:"
+          ls -lh dist/
+
+      - name: Upload distribution artifacts (verified)
+        uses: wamp-proto/wamp-cicd/actions/upload-artifact-verified@main
+        with:
+          name: dist-packages
+          path: dist/
+          retention-days: 14