[INIT] Initial commit

Author: healkeiser

.auto-changelog

@@ -0,0 +1,7 @@
+{
+    "template": "keepachangelog",
+    "unreleased": true,
+    "commitLimit": false,
+    "ignoreCommitPattern": ".*(CHANGELOG|README).*",
+    "sortCommits": "date"
+}

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: pip install -r requirements.mkdocs.txt
+
+      - name: Configure Git
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+
+      - name: Fetch gh-pages branch
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1; then
+            git fetch origin gh-pages:gh-pages
+            echo "Fetched existing gh-pages branch"
+          else
+            echo "gh-pages branch does not exist yet, mike will create it"
+          fi
+
+      - name: Deploy docs (versioned)
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: |
+          VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "0.1.0")
+          mike deploy --push --update-aliases "$VERSION" latest
+          git fetch origin gh-pages:gh-pages --force
+          mike set-default --push latest
+          echo "Mike versions:"
+          mike list

.github/workflows/release.yml

@@ -0,0 +1,197 @@
+# This workflow handles the complete release process:
+# 1. Generate changelog from conventional commits
+# 2. Create a GitHub release with changelog content
+# 3. Build and publish Python package to PyPI
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      node-version:
+        description: "Node.js version to use for changelog generation"
+        type: string
+        default: "20"
+      python-version:
+        description: "Python version to use for build and documentation"
+        type: string
+        default: "3.11"
+      skip-changelog:
+        description: "Skip changelog generation"
+        type: boolean
+        default: false
+      skip-pypi:
+        description: "Skip PyPI publishing"
+        type: boolean
+        default: false
+    secrets:
+      PIPY_USERNAME:
+        description: "PyPI username for package publishing"
+        required: false
+      PIPY_API_TOKEN:
+        description: "PyPI API token for package publishing"
+        required: false
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  # Step 1: Generate changelog FIRST so it can be included in the release
+  generate-changelog:
+    name: Generate Changelog
+    if: ${{ inputs.skip-changelog != true }}
+    runs-on: ubuntu-latest
+    outputs:
+      changelog-section: ${{ steps.extract-changelog.outputs.section }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Check for package.json
+        id: check-npm
+        run: |
+          if [ -f "package.json" ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "No package.json found, skipping changelog generation"
+          fi
+
+      - name: Setup Node.js
+        if: steps.check-npm.outputs.exists == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version || '20' }}
+
+      - name: Install dependencies
+        if: steps.check-npm.outputs.exists == 'true'
+        run: npm install && npm install -g auto-changelog
+
+      - name: Generate changelog
+        if: steps.check-npm.outputs.exists == 'true'
+        run: npm run changelog
+
+      - name: Extract changelog section for this release
+        id: extract-changelog
+        run: |
+          TAG_NAME="${GITHUB_REF_NAME:-$(git describe --tags --abbrev=0)}"
+          VERSION="${TAG_NAME#v}"
+
+          if [ ! -f "CHANGELOG.md" ]; then
+            echo "section=No changelog available for this release." >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          echo "Looking for version: ${VERSION} (tag: ${TAG_NAME})"
+
+          # Try multiple patterns to find the version section
+          SECTION=$(awk "/^## \[v?${VERSION}\]/{found=1; next} /^## /{if(found) exit} found{print}" CHANGELOG.md)
+          SECTION=$(echo "$SECTION" | sed '/^[[:space:]]*$/d' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+
+          if [ -z "$SECTION" ]; then
+            SECTION=$(awk "/^## \[${TAG_NAME}\]/{found=1; next} /^## /{if(found) exit} found{print}" CHANGELOG.md)
+            SECTION=$(echo "$SECTION" | sed '/^[[:space:]]*$/d' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+          fi
+
+          if [ -z "$SECTION" ]; then
+            SECTION=$(awk "/^## v?${VERSION}/{found=1; next} /^## /{if(found) exit} found{print}" CHANGELOG.md)
+            SECTION=$(echo "$SECTION" | sed '/^[[:space:]]*$/d' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+          fi
+
+          if [ -z "$SECTION" ]; then
+            if grep -q "## \[v\?${VERSION}\]" CHANGELOG.md || grep -q "## v\?${VERSION}" CHANGELOG.md; then
+              SECTION="This release contains minor updates. See commit history for details."
+            else
+              SECTION="No changelog entry found for version ${VERSION}."
+            fi
+          fi
+
+          echo "section<<EOF" >> $GITHUB_OUTPUT
+          echo "$SECTION" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Remove package-lock.json
+        if: steps.check-npm.outputs.exists == 'true'
+        run: rm -f package-lock.json
+
+      - name: Commit and push changelog
+        if: steps.check-npm.outputs.exists == 'true'
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add CHANGELOG.md
+          if [ -n "$(git status --porcelain)" ]; then
+            git commit -m '[DOC] CHANGELOG' -m '[skip ci]'
+            git push origin main
+          else
+            echo "No changes to commit"
+          fi
+
+  # Step 2: Create release WITH changelog content
+  create-release:
+    name: Create GitHub Release
+    needs: generate-changelog
+    if: ${{ always() && !cancelled() }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Create draft release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          name: ${{ github.ref_name }}
+          body: |
+            ## What's Changed
+
+            ${{ needs.generate-changelog.outputs.changelog-section || 'No detailed changelog available for this release.' }}
+
+            ---
+            📄 **[View Full Changelog](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)**
+
+  # Step 3: Build and publish to PyPI
+  publish-pypi:
+    name: Publish to PyPI
+    needs: create-release
+    if: ${{ always() && !cancelled() && inputs.skip-pypi != true && startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+          submodules: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version || '3.11' }}
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel twine build
+
+      - name: Build package
+        run: |
+          python -m build
+
+      - name: Publish package to PyPI
+        env:
+          TWINE_USERNAME: ${{ secrets.PIPY_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PIPY_API_TOKEN }}
+        run: |
+          twine upload dist/*

.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.so
+*.dylib
+
+# Testing
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+
+# Node
+node_modules/
+package-lock.json
+
+# MkDocs
+site/
+
+# OS
+*.log
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/settings.json
+
+# AI tools
+.claude/
+.cursor/
+.aider*
+.copilot/

.scripts/git/Get-CurrentGitTag.ps1

@@ -0,0 +1,5 @@
+# Get the latest tag
+$latestTag = git describe --tags (git rev-list --tags --max-count=1)
+
+# Output the latest tag
+Write-Output "Current version: $latestTag"

.scripts/git/Update-GitTag.ps1

@@ -0,0 +1,73 @@
+param (
+    [string]$incrementType
+)
+
+# Get the latest tag (handle case where no tags exist)
+try {
+    $tagList = git rev-list --tags --max-count=1 2>$null
+    if ($tagList) {
+        $latestTag = git describe --tags $tagList 2>$null
+    }
+    else {
+        $latestTag = $null
+    }
+}
+catch {
+    $latestTag = $null
+}
+
+# If no tags exist, start with v0.1.0
+if (-not $latestTag) {
+    Write-Host "No existing tags found. Creating initial version v0.1.0..."
+    $newVersion = "0.1.0"
+    git tag -a "v$newVersion" -m "Version $newVersion"
+    git push origin "v$newVersion"
+    Write-Host "Tag v$newVersion pushed."
+    Write-Output $newVersion
+    exit 0
+}
+
+# Remove the 'v' prefix if it exists
+if ($latestTag.StartsWith('v')) {
+    $latestTag = $latestTag.Substring(1)
+}
+
+# Split the version into an array
+$versionParts = $latestTag -split '\.'
+
+# Ensure the versionParts array has three elements
+if ($versionParts.Length -ne 3) {
+    Write-Host "Error: The latest tag '$latestTag' is not in the expected format 'vX.Y.Z'."
+    exit 1
+}
+
+switch ($incrementType) {
+    "major" {
+        $versionParts[0] = [int]$versionParts[0] + 1
+        $versionParts[1] = 0
+        $versionParts[2] = 0
+    }
+    "minor" {
+        $versionParts[1] = [int]$versionParts[1] + 1
+        $versionParts[2] = 0
+    }
+    "patch" {
+        $versionParts[2] = [int]$versionParts[2] + 1
+    }
+    default {
+        Write-Host "Usage: .\Update-GitTag.ps1 {major|minor|patch}"
+        exit 1
+    }
+}
+
+# Join the version parts into a new version string
+$newVersion = "$($versionParts[0]).$($versionParts[1]).$($versionParts[2])"
+
+# Create and push the new tag (CI will handle the rest)
+git tag -a "v$newVersion" -m "Version $newVersion"
+git push origin "v$newVersion"
+
+Write-Host "Tag v$newVersion pushed."
+
+# Output the new version
+Write-Output $newVersion