v8x 0.1.2__tar.gz

v8x-0.1.2/.github/copilot-instructions.md

@@ -0,0 +1,79 @@
+# GitHub Copilot Instructions for v8x
+
+## Python Command Execution
+
+**ALWAYS use `uv run` for Python commands in this project.**
+
+This project uses `uv` for dependency management and virtual environment handling. All Python commands must be prefixed with `uv run`.
+
+### Examples:
+
+✅ **CORRECT:**
+- `uv run python script.py`
+
+
+❌ **INCORRECT:**
+- `python script.py`
+- `pytest tests/`
+- `python -m v8x.main`
+- `v8x --help`
+- `coverage run`
+- `mypy .`
+- `black .`
+- `ruff check`
+
+### Just Commands (Primary Development Workflow):
+
+**Testing:**
+- `just unit` - Run unit tests with coverage (80% threshold)
+- `just integration` - Run integration tests  
+- `just coverage-all` - Run full test suite with combined coverage
+
+**Code Quality:**
+- `just typecheck` - Run static type checker (pyright)
+- `just lint` - Check code against style standards (codespell + ruff)
+- `just fmt` - Apply coding style standards (ruff format + fix)
+
+**Documentation:**
+- `just docs-dev` - Start Docusaurus development server
+- `just docs-dev-port [port]` - Start dev server on specific port
+- `just docs-build` - Build documentation for production
+- `just docs-serve` - Serve built documentation
+- `just docs-clean` - Clean documentation build artifacts
+- `just docs-help` - Show documentation commands
+
+**Development:**
+- `just lock` - Regenerate uv.lock file
+
+### Direct UV Commands (When Needed):
+- Run CLI: `uv run v8x [command]`
+- Specific test: `uv run pytest tests/unit/test_example.py::test_function`
+- Add dependency: `uv add package-name`
+- Add dev dependency: `uv add --dev package-name`
+
+### Installation Commands:
+- Install dependencies: `uv sync`
+- Add new dependency: `uv add package-name`
+- Add dev dependency: `uv add --dev package-name`
+- Regenerate lock: `just lock`
+
+## Project Structure
+
+This is a Python CLI application using:
+- `uv` for dependency management
+- `typer` for CLI framework
+- `rich` for terminal output
+- `pytest` for testing
+- `RenderStepOutput` for progress rendering with JSON bypass support
+
+## Test Patterns
+
+When working with tests, ensure:
+1. MockConsole includes all necessary Rich console methods
+2. Use `RenderStepOutput.json_bypass()` for JSON output tests
+3. All async functions are properly awaited in tests
+4. Function signatures match current implementation
+
+## Never Forget
+
+**EVERY Python command MUST start with `uv run`** - this is critical for proper dependency resolution and virtual environment isolation in this project.

v8x-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+# Copyright 2025 Vantage Compute Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: v8x Code Quality Checks
+on:
+  workflow_call:
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - name: Install commitlint
+        run: npm install -D @commitlint/cli @commitlint/config-conventional
+      - name: Validate PR commits with commitlint
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
+
+  ci-tests:
+    name: CI-Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install `just`
+        run: sudo snap install just --classic
+      - name: Install `uv`
+        run: sudo snap install astral-uv --classic
+      - name: Run lint checks
+        run: just lint
+      - name: Run type checks
+        run: just typecheck
+      - name: Run unit tests
+        run: just unit
+      - name: Run integration tests
+        run: just integration

v8x-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,204 @@
+# Copyright (c) 2025 Vantage Compute Corporation.
+name: Build and Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-alpha.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+-beta.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+a[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+b[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+
+permissions:
+  contents: write  # Required for creating releases
+  id-token: write  # Required for PyPI trusted publishing
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Fetch full history for proper version detection
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y build-essential
+        sudo snap install astral-uv --classic
+
+    
+    - name: Install git-cliff
+      run: |
+        curl -L https://github.com/orhun/git-cliff/releases/download/v2.10.0/git-cliff-2.10.0-x86_64-unknown-linux-gnu.tar.gz | tar xz
+        sudo mv git-cliff-*/git-cliff /usr/local/bin/
+        git-cliff --version
+    
+    - name: Build Python package
+      run: |
+        uv build
+    
+    - name: Check build artifacts
+      run: |
+        ls -la dist/
+        # Basic validation - ensure files exist
+        test -n "$(find dist -name '*.whl')" || (echo "No wheel files found" && exit 1)
+        test -n "$(find dist -name '*.tar.gz')" || (echo "No source distribution found" && exit 1)
+
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: distribution-files
+        path: dist/
+        retention-days: 7
+
+  test-install:
+    name: Test Installation
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    
+    steps:
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: distribution-files
+        path: dist/
+    
+    - name: Test wheel installation
+      run: |
+        sudo snap install astral-uv --classic
+        uv venv
+        uv pip install dist/*.whl
+        uv run python3 -c "import v8x; print('Package imported successfully')"
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, test-install]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/v8x
+
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: distribution-files
+        path: dist/
+    
+    - name: Publish to PyPI
+      run: |
+        sudo snap install astral-uv --classic
+        uv publish
+
+  create-release:
+    name: Create GitHub Release
+    needs: [build, test-install]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: distribution-files
+        path: dist/
+
+    - name: Extract version from tag
+      id: get_version
+      run: |
+        VERSION=${GITHUB_REF#refs/tags/}
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+    
+    - name: Generate release notes
+      id: release_notes
+      run: |
+        # Extract release notes from CHANGELOG.md if it exists
+        if [ -f "CHANGELOG.md" ]; then
+          # Try to extract notes for this version using git-cliff for consistency
+          VERSION="${{ steps.get_version.outputs.version }}"
+          
+          # Use git-cliff to generate notes for this specific version
+          git-cliff --latest --strip header --strip footer > release_notes.txt || true
+          
+          # If that fails, fall back to grep method
+          if [ ! -s release_notes.txt ]; then
+            grep -A 1000 "^## .*${VERSION}" CHANGELOG.md | grep -B 1000 -m 2 "^## " | head -n -1 | tail -n +2 > release_notes.txt || true
+          fi
+          
+          # If no specific version notes found, create generic notes
+          if [ ! -s release_notes.txt ]; then
+            echo "Release ${{ steps.get_version.outputs.tag }}" > release_notes.txt
+            echo "" >> release_notes.txt
+            echo "### Changes" >> release_notes.txt
+            echo "- See CHANGELOG.md for detailed changes" >> release_notes.txt
+          fi
+        else
+          echo "Release ${{ steps.get_version.outputs.tag }}" > release_notes.txt
+          echo "" >> release_notes.txt
+          echo "### Files" >> release_notes.txt
+          echo "- Source distribution (tar.gz)" >> release_notes.txt
+          echo "- Wheel distribution (.whl)" >> release_notes.txt
+        fi
+        
+        echo "Release notes:"
+        cat release_notes.txt
+    
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        name: Release ${{ steps.get_version.outputs.tag }}
+        body_path: release_notes.txt
+        files: |
+          dist/*.tar.gz
+          dist/*.whl
+        draft: false
+        prerelease: ${{ contains(steps.get_version.outputs.version, 'rc') || contains(steps.get_version.outputs.version, 'beta') || contains(steps.get_version.outputs.version, 'alpha') }}
+        generate_release_notes: true
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  notify-success:
+    name: Notify Success
+    needs: [publish-pypi, create-release]
+    runs-on: ubuntu-latest
+    if: success() && startsWith(github.ref, 'refs/tags/')
+    
+    steps:
+    - name: Extract version from tag
+      id: get_version
+      run: |
+        VERSION=${GITHUB_REF#refs/tags/}
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+    
+    - name: Success notification
+      run: |
+        echo "🎉 Successfully released v8x ${{ steps.get_version.outputs.tag }}"
+        echo "📦 Published to PyPI: https://pypi.org/project/v8x/${{ steps.get_version.outputs.version }}/"
+        echo "🚀 GitHub Release: ${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ steps.get_version.outputs.tag }}"

v8x-0.1.2/.github/workflows/update-docs.yml

@@ -0,0 +1,265 @@
+# Copyright 2025 Vantage Compute Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Update Documentation
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - 'v8x/**'
+      - 'scripts/generate_complete_docs.py'
+      - 'scripts/update_docs_version.py'
+      - 'pyproject.toml'
+      - 'docusaurus/**'
+  workflow_dispatch:
+
+concurrency:
+  group: "update-docs"
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+  pages: write
+
+env:
+  BASE_BRANCH: main
+
+jobs:
+  update-docs:
+    name: Update Documentation
+    runs-on: ubuntu-24.04
+    environment: github-pages
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          # GITHUB_TOKEN is provided automatically; no need to pass from secrets
+          token: ${{ github.token }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+          cache-dependency-path: docusaurus/yarn.lock
+
+      - name: Install just
+        run: sudo snap install just --classic
+
+      - name: Install UV
+        run: sudo snap install astral-uv --classic
+
+      - name: Ensure GitHub CLI auth
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh --version
+          gh auth status -h github.com
+
+      - name: Create docs update branch & commit
+        id: commit_changes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          BRANCH_NAME="docs/auto-update-$(date +%Y%m%d-%H%M%S)"
+
+          # Make sure base exists locally and is up to date
+          git fetch origin --prune
+          if ! git ls-remote --exit-code --heads origin "${BASE_BRANCH}" >/dev/null 2>&1; then
+            echo "Base branch '${BASE_BRANCH}' not found on origin." >&2
+            exit 1
+          fi
+          git checkout -B "${BASE_BRANCH}" "origin/${BASE_BRANCH}"
+
+          # Create/update working branch from base
+          git switch -C "${BRANCH_NAME}"
+
+          python3 scripts/generate_complete_docs.py
+          python3 scripts/update_docs_version.py
+          just docs-build
+
+          # Stage only intended paths
+          git add docusaurus/ || true
+
+          # Check if anything changed
+          if git diff --cached --quiet; then
+            echo "changes=false" >> "$GITHUB_OUTPUT"
+            echo "No changes detected; skipping PR."
+           exit 0
+          fi
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git commit -m "docs: auto-update generated documentation
+
+          - Updated CLI command documentation
+          - Regenerated Docusaurus build files
+          - Updated version information
+
+          Auto-generated by GitHub Actions"
+
+          git push -u origin "${BRANCH_NAME}"
+
+          echo "branch=${BRANCH_NAME}" >> "$GITHUB_OUTPUT"
+          echo "changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Open PR
+        if: steps.commit_changes.outputs.changes == 'true'
+        id: open_pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          BRANCH_NAME="${{ steps.commit_changes.outputs.branch }}"
+
+          # Create PR targeting main (change if you use a different base)
+          if ! PR_URL=$(
+            gh pr create \
+              --base "${BASE_BRANCH}" \
+              --label "deploy-docs" \
+              --label "auto-merge" \
+              --title "docs: auto-update generated documentation" \
+              --body $'🤖 **Automated Documentation Update**\n\n- ✅ Updated CLI command documentation\n- ✅ Regenerated Docusaurus build files\n- ✅ Updated version information\n\n> Created by GitHub Actions.'
+          ); then
+            echo "PR create failed—attempting to fetch existing PR…"
+            PR_URL="$(gh pr view "${BRANCH_NAME}" --json url -q .url || true)"
+          fi
+
+          if [ -z "${PR_URL}" ]; then
+            echo "Could not create or find the PR." >&2
+            exit 1
+          fi
+
+          echo "url=${PR_URL}" >> "$GITHUB_OUTPUT"
+          echo "PR_URL=${PR_URL}" >> "$GITHUB_ENV"
+          echo "Opened PR: ${PR_URL}"
+
+      - name: Merge or enable auto-merge
+        if: steps.commit_changes.outputs.changes == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_URL: ${{ steps.open_pr.outputs.url }}
+        run: |
+          set -euo pipefail
+      
+          # Fetch PR status
+          ms=$(gh pr view "$PR_URL" --json mergeStateStatus -q .mergeStateStatus)
+          rd=$(gh pr view "$PR_URL" --json reviewDecision -q .reviewDecision)
+          draft=$(gh pr view "$PR_URL" --json isDraft -q .isDraft)
+      
+          echo "mergeStateStatus=${ms}"
+          echo "reviewDecision=${rd}"
+          echo "isDraft=${draft}"
+      
+          case "$ms" in
+            CLEAN)
+              echo "PR is clean/mergeable now. Merging immediately…"
+              gh pr merge "$PR_URL" --squash --delete-branch
+              ;;
+      
+            BLOCKED|BEHIND|UNSTABLE|DIRTY)
+              echo "PR is not immediately mergeable (status: $ms). Attempting to enable auto-merge…"
+              # Will succeed only if repo has Auto-merge enabled and required conditions will pass later.
+              if gh pr merge "$PR_URL" --squash --auto; then
+                echo "Auto-merge enabled."
+              else
+                echo "Could not enable auto-merge. Likely reasons:"
+                echo " - Repo hasn’t enabled Auto-merge (Settings → Pull requests → Enable auto-merge)"
+                echo " - Required reviews/checks not satisfied (reviewDecision=$rd, draft=$draft)"
+                echo " - Branch is behind or needs an update (status=$ms)"
+                exit 1
+              fi
+              ;;
+      
+            *)
+              echo "Unexpected mergeStateStatus: $ms"
+              gh pr view "$PR_URL" --json url,mergeable,mergeStateStatus,reviewDecision,isDraft,requiredStatusCheckContexts
+              exit 1
+              ;;
+          esac
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload build directory
+          path: './docusaurus/build'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Gather context
+        id: ctx
+        run: |
+          echo "sha=$(git rev-parse --short HEAD || echo $GITHUB_SHA)" >> $GITHUB_OUTPUT
+          echo "ref=$GITHUB_REF" >> $GITHUB_OUTPUT
+          echo "repo=${GITHUB_REPOSITORY}" >> $GITHUB_OUTPUT
+          echo "actor=${GITHUB_ACTOR}" >> $GITHUB_OUTPUT
+
+      - name: Send repository_dispatch to vantage-docs
+        env:
+          TOKEN: ${{ secrets.PLATFORM_REPO_TOKEN }}
+          TARGET_REPO: vantagecompute/vantage-docs
+          EVENT_TYPE: cli-docs-updated
+          SHA: ${{ steps.ctx.outputs.sha }}
+          REF: ${{ steps.ctx.outputs.ref }}
+          REPO: ${{ steps.ctx.outputs.repo }}
+          ACTOR: ${{ steps.ctx.outputs.actor }}
+        run: |
+          set -euo pipefail
+          
+          # Build the JSON payload using cat instead of read
+          PAYLOAD=$(cat <<EOF
+          {
+            "event_type": "${EVENT_TYPE}",
+            "client_payload": {
+              "source_repo": "${REPO}",
+              "source_ref": "${REF}",
+              "source_sha": "${SHA}",
+              "actor": "${ACTOR}"
+            }
+          }
+          EOF
+          )
+
+          # Validate payload is not empty
+          if [ -z "${PAYLOAD}" ]; then
+            echo "Error: Payload is empty" >&2
+            exit 1
+          fi
+
+          echo "Sending dispatch with payload:"
+          echo "${PAYLOAD}"
+
+          # Fire the dispatch
+          curl -sS -X POST \
+            -H "Authorization: token ${TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            -H "Content-Type: application/json" \
+            https://api.github.com/repos/${TARGET_REPO}/dispatches \
+            -d "${PAYLOAD}"
+
+    # Optional: prevent overlapping dispatches
+    concurrency:
+      group: notify-platform-${{ github.ref }}
+      cancel-in-progress: false

v8x-0.1.2/.gitignore

@@ -0,0 +1,68 @@
+__pycache__/
+**/__pycache__/
+**/**/__pycache__/
+
+# Docusaurus
+docs/node_modules
+docs/yarn-global
+docs/yarn-cache
+docs/.docusaurus
+docs/build
+docs/.yarn
+docs/yarn-error.log
+docs/npm-debug.log*
+docs/yarn-debug.log*
+
+
+# Python virtual environments
+.venv
+venv/
+env/
+.env
+**/.env
+
+# Coverage reports
+.coverage
+cover_unit
+cover_integration
+cover_combined
+.coverage.*
+coverage
+cover/
+htmlcov/
+
+# Testing and linting
+.tox/
+.nox/
+.pytest_cache/
+.pytest_cache/**
+.pytest_cache/**/*
+.pytest_cache/**/*
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+.dmypy.json/**
+.pyre/
+.pyre/**
+.pyre/**/*
+
+# Jupyter
+.ipynb_checkpoints
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*.tar.gz
+*.tgz