smartnuf-agent-tools 0.1.2__tar.gz

smartnuf_agent_tools-0.1.2/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto
+*.sh text eol=lf
+*.ps1 text eol=crlf
+*.cmd text eol=crlf

smartnuf_agent_tools-0.1.2/.github/actions/install-native/action.yml

@@ -0,0 +1,59 @@
+name: Install native runtime prerequisites
+description: Install and verify Poppler and Ghostscript on supported GitHub runners
+
+runs:
+  using: composite
+  steps:
+    - name: Install native tools (Ubuntu)
+      if: runner.os == 'Linux'
+      shell: bash
+      run: |
+        echo "[$(date --iso-8601=seconds)] Installing Poppler and Ghostscript with apt."
+        sudo apt-get update
+        sudo apt-get install -y poppler-utils ghostscript
+
+    - name: Install native tools (macOS)
+      if: runner.os == 'macOS'
+      shell: bash
+      run: |
+        echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Installing Poppler and Ghostscript with Homebrew."
+        brew install poppler ghostscript
+
+    - name: Install native tools (Windows provider path)
+      id: windows_native_tools
+      if: runner.os == 'Windows'
+      shell: pwsh
+      run: |
+        Write-Host "[$(Get-Date -Format o)] Installing Poppler with WinGet."
+        winget install --id oschwartz10612.Poppler -e --accept-package-agreements --accept-source-agreements
+        if ($LASTEXITCODE -ne 0) { throw "WinGet Poppler installation failed with exit code $LASTEXITCODE." }
+        Write-Host "[$(Get-Date -Format o)] Installing Ghostscript with Chocolatey."
+        choco install ghostscript -y --no-progress
+        if ($LASTEXITCODE -ne 0) { throw "Chocolatey Ghostscript installation failed with exit code $LASTEXITCODE." }
+        $searchRoots = "$env:LOCALAPPDATA\Microsoft\WinGet\Packages", 'C:\Program Files\gs'
+        $required = 'pdfinfo.exe', 'pdftotext.exe', 'pdftoppm.exe', 'gswin64c.exe'
+        $toolDirectories = foreach ($name in $required) {
+          $tool = Get-ChildItem $searchRoots -Filter $name -File -Recurse -ErrorAction SilentlyContinue | Select-Object -First 1
+          if (-not $tool) { throw "The provider path completed but $name was not found." }
+          $tool.DirectoryName
+        }
+        $machineDirectories = [Environment]::GetEnvironmentVariable('Path', 'Machine') -split ';' | Where-Object { $_ }
+        foreach ($directory in @($toolDirectories) + @($machineDirectories) | Select-Object -Unique) {
+          $directory | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+        }
+
+    - name: Report Windows external-provider failure
+      if: failure() && runner.os == 'Windows' && steps.windows_native_tools.outcome == 'failure'
+      shell: pwsh
+      run: |
+        Write-Host "[$(Get-Date -Format o)] External Windows native provider path did not complete."
+        Get-Process -ErrorAction SilentlyContinue |
+          Where-Object { $_.ProcessName -match '^(AppInstallerCLI|choco|gs|msiexec|winget)' } |
+          Select-Object ProcessName, Id, StartTime
+        $chocolateyLog = 'C:\ProgramData\chocolatey\logs\chocolatey.log'
+        if (Test-Path -LiteralPath $chocolateyLog) {
+          Write-Host 'Last 200 lines of the Chocolatey log:'
+          Get-Content -LiteralPath $chocolateyLog -Tail 200
+        } else {
+          Write-Warning "Chocolatey log not found at $chocolateyLog."
+        }

smartnuf_agent_tools-0.1.2/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## Scope
+
+- Acceptance criterion or issue:
+- In scope:
+- Non-goals:
+- Base commit:
+- Merge owner:
+
+## Evidence
+
+- [ ] Focused commits form one coherent review wave.
+- [ ] Repository-defined local validation passed, including `git diff --check`.
+- [ ] CI and automated review completed for the exact current head.
+- [ ] Findings have evidence-backed dispositions and no actionable thread remains unresolved.
+- [ ] [Adaptation review](https://github.com/smartnuf/agent-tools/blob/main/docs/development-workflow.md#9-review-adaptations) was not triggered, or applicable impact, recovery, reusable lessons, evidence, and durable follow-ups are recorded.
+- [ ] Roadmap/evidence was reconciled when this change advances readiness.
+- [ ] Unrelated dirty state, stashes, branches, worktrees, and user configuration were preserved.
+
+## Integration
+
+- Current head:
+- Current `origin/main`:
+- [ ] The base has not moved, or latest `origin/main` was incorporated and the new head was revalidated and rereviewed.
+- [ ] This stream owns merging. If not, stop merge-ready and await ownership.
+- [ ] `--match-head-commit` will guard the verified head and strict required status checks still guard base freshness.

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

@@ -0,0 +1,171 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  package-artifacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - name: Validate GitHub workflow syntax and expressions
+        shell: bash
+        run: |
+          archive="$RUNNER_TEMP/actionlint.tar.gz"
+          curl --fail --silent --show-error --location \
+            --output "$archive" \
+            "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz"
+          echo "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8  $archive" | sha256sum --check --strict
+          tar --extract --gzip --file "$archive" --directory "$RUNNER_TEMP" actionlint
+          "$RUNNER_TEMP/actionlint"
+      - name: Build wheel and source distribution
+        run: uv build --out-dir "${{ runner.temp }}/dist"
+      - name: Validate artifact metadata and contents
+        run: python tests/check_distribution.py "${{ runner.temp }}/dist"
+      - name: Validate release version and checksums
+        shell: bash
+        run: |
+          python scripts/release.py verify-tag v0.1.2
+          python scripts/release.py checksums "${{ runner.temp }}/dist/SHA256SUMS" "${{ runner.temp }}"/dist/*.whl "${{ runner.temp }}"/dist/*.tar.gz
+      - name: Install wheel and declared dependencies
+        run: |
+          uv venv "${{ runner.temp }}/installed" --python 3.11
+          uv pip install --python "${{ runner.temp }}/installed/bin/python" "${{ runner.temp }}"/dist/*.whl
+      - name: Test installed CLI and declared Python dependencies without native tools
+        run: python tests/check_installed_cli.py "${{ runner.temp }}/installed/bin/agent-tools" "${{ runner.temp }}/dist"
+      - name: Verify build and tests leave the checkout unchanged
+        run: |
+          git diff --exit-code
+          test -z "$(git status --porcelain=v1 --untracked-files=all)"
+      - name: Upload validated release bundle
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dist
+          path: ${{ runner.temp }}/dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  install-and-test:
+    needs: package-artifacts
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - name: Download shared release bundle
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dist
+          path: ${{ runner.temp }}/release-dist
+
+      - name: Install and test shared release wheel (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}\release-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}\release-bin
+        run: |
+          python scripts/release.py verify-checksums "$env:RUNNER_TEMP\release-dist\SHA256SUMS"
+          $wheel = Get-ChildItem "$env:RUNNER_TEMP\release-dist" -Filter '*.whl' | Select-Object -ExpandProperty FullName -First 1
+          uv tool install --python 3.13 $wheel
+          python tests/check_installed_cli.py "$(uv tool dir --bin)\agent-tools.exe" "$env:RUNNER_TEMP\release-dist"
+
+      - name: Install and test shared release wheel (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}/release-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}/release-bin
+        run: |
+          python scripts/release.py verify-checksums "$RUNNER_TEMP/release-dist/SHA256SUMS"
+          uv tool install --python 3.13 "$RUNNER_TEMP"/release-dist/*.whl
+          python tests/check_installed_cli.py "$(uv tool dir --bin)/agent-tools" "$RUNNER_TEMP/release-dist"
+
+      - name: Bootstrap twice (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          ./scripts/bootstrap.ps1
+          uv pip install --python .venv -e tests/fixtures/extraneous
+          ./scripts/bootstrap.ps1
+          .venv\Scripts\python.exe -c "import importlib.util; assert importlib.util.find_spec('agent_tools_extraneous') is None"
+          ./scripts/path.ps1
+
+      - name: Bootstrap twice (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          sh scripts/bootstrap.sh
+          uv pip install --python .venv -e tests/fixtures/extraneous
+          sh scripts/bootstrap.sh
+          .venv/bin/python -c "import importlib.util; assert importlib.util.find_spec('agent_tools_extraneous') is None"
+          sh scripts/path.sh
+
+      - name: Exercise checkout doctor (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $output = & .\bin\agent-tools.cmd doctor 2>&1 | Out-String
+          $exitCode = $LASTEXITCODE
+          $output
+          if ($exitCode -notin 0, 1) { throw "checkout doctor failed with exit code $exitCode" }
+          if ($output -match 'Traceback') { throw 'checkout doctor emitted a traceback' }
+          exit 0
+
+      - name: Exercise checkout doctor (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          set +e
+          output=$(./bin/agent-tools doctor 2>&1)
+          status=$?
+          set -e
+          printf '%s\n' "$output"
+          test "$status" -eq 0 || test "$status" -eq 1
+          case "$output" in *Traceback*) exit 1;; esac
+
+      - name: Run unit tests (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: .venv\Scripts\python.exe -m unittest discover -s tests
+
+      - name: Test PATH backup and restoration (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: ./tests/test_path.ps1
+
+      - name: Test Windows native-tool discovery
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: ./tests/test_windows_tools.ps1
+
+      - name: Run unit tests (Unix)
+        if: runner.os != 'Windows'
+        run: .venv/bin/python -m unittest discover -s tests
+
+      - name: Test PATH profile handling (Unix)
+        if: runner.os != 'Windows'
+        run: sh tests/test_path.sh
+
+      - name: Test privileged native installation routing (Unix)
+        if: runner.os != 'Windows'
+        run: sh tests/test_install_native.sh

smartnuf_agent_tools-0.1.2/.github/workflows/native-integration.yml

@@ -0,0 +1,96 @@
+name: Native integration
+
+on:
+  pull_request:
+  schedule:
+    - cron: "23 5 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  select-native-integration:
+    runs-on: ubuntu-latest
+    outputs:
+      run-native: ${{ steps.select.outputs.run-native }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Select native integration
+        id: select
+        shell: bash
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          if test "$EVENT_NAME" = pull_request; then
+            selected="$(python scripts/select_native_integration.py --base "$BASE_SHA" --head "$HEAD_SHA")"
+          else
+            selected=true
+          fi
+          echo "run-native=$selected" | tee -a "$GITHUB_OUTPUT"
+          echo "Native integration selected: $selected"
+
+  build-native-test-artifact:
+    needs: select-native-integration
+    if: needs.select-native-integration.outputs.run-native == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - run: uv build --out-dir "${{ runner.temp }}/dist"
+      - run: python tests/check_distribution.py "${{ runner.temp }}/dist"
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: native-test-dist
+          path: ${{ runner.temp }}/dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  native-install-and-test:
+    needs: build-native-test-artifact
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: native-test-dist
+          path: ${{ runner.temp }}/native-test-dist
+      - name: Install native tools through external providers
+        timeout-minutes: 10
+        uses: ./.github/actions/install-native
+      - name: Install and test wheel (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}\native-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}\native-bin
+        run: |
+          $wheel = Get-ChildItem "$env:RUNNER_TEMP\native-test-dist" -Filter '*.whl' | Select-Object -ExpandProperty FullName -First 1
+          uv tool install --python 3.13 $wheel
+          python tests/check_installed_cli.py "$(uv tool dir --bin)\agent-tools.exe" "$env:RUNNER_TEMP\native-test-dist" --native-tools require
+      - name: Install and test wheel (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}/native-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}/native-bin
+        run: |
+          uv tool install --python 3.13 "$RUNNER_TEMP"/native-test-dist/*.whl
+          python tests/check_installed_cli.py "$(uv tool dir --bin)/agent-tools" "$RUNNER_TEMP/native-test-dist" --native-tools require

smartnuf_agent_tools-0.1.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,83 @@
+name: Publish stable release to PyPI
+
+on:
+  release:
+    types: [published, released]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing stable GitHub release tag to publish or recover
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: github.event_name == 'workflow_dispatch' || (github.event.release.prerelease == false && github.event.release.draft == false)
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/smartnuf-agent-tools
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.event.release.tag_name }}
+      DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - name: Verify reviewed stable release tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          test "$(gh api "repos/$GITHUB_REPOSITORY/releases/tags/$RELEASE_TAG" --jq '.draft or .prerelease')" = false
+          git fetch --force origin "refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"
+          git fetch --no-tags origin "$DEFAULT_BRANCH:refs/remotes/origin/$DEFAULT_BRANCH"
+          tag_commit="$(git rev-list -n 1 "$RELEASE_TAG")"
+          git merge-base --is-ancestor "$tag_commit" "origin/$DEFAULT_BRANCH"
+          tag_version="$(git show "$RELEASE_TAG:src/agent_tools/__init__.py" | sed -n 's/^__version__ = "\([^"]*\)"$/\1/p')"
+          test "$tag_version" = "${RELEASE_TAG#v}"
+      - name: Download and verify GitHub release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          mkdir dist publish
+          gh release download "$RELEASE_TAG" \
+            --pattern '*.whl' \
+            --pattern '*.tar.gz' \
+            --pattern SHA256SUMS \
+            --dir dist
+          version="${RELEASE_TAG#v}"
+          tag_commit="$(git rev-list -n 1 "$RELEASE_TAG")"
+          wheel="smartnuf_agent_tools-$version-py3-none-any.whl"
+          sdist="smartnuf_agent_tools-$version.tar.gz"
+          test -f "dist/$wheel"
+          test -f "dist/$sdist"
+          printf '%s\n' "$wheel" "$sdist" | sort > expected-files
+          awk 'NF {print $2}' dist/SHA256SUMS | sort > manifest-files
+          diff -u expected-files manifest-files
+          (cd dist && sha256sum --check SHA256SUMS)
+          gh attestation verify "dist/$wheel" \
+            --repo "$GITHUB_REPOSITORY" \
+            --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \
+            --source-ref "refs/tags/$RELEASE_TAG" \
+            --source-digest "$tag_commit"
+          gh attestation verify "dist/$sdist" \
+            --repo "$GITHUB_REPOSITORY" \
+            --signer-workflow "$GITHUB_REPOSITORY/.github/workflows/release.yml" \
+            --source-ref "refs/tags/$RELEASE_TAG" \
+            --source-digest "$tag_commit"
+          cp dist/*.whl dist/*.tar.gz publish/
+          test "$(find publish -maxdepth 1 -type f -name '*.whl' | wc -l)" -eq 1
+          test "$(find publish -maxdepth 1 -type f -name '*.tar.gz' | wc -l)" -eq 1
+      - name: Publish distributions with GitHub OIDC
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+        with:
+          packages-dir: publish

smartnuf_agent_tools-0.1.2/.github/workflows/release.yml

@@ -0,0 +1,127 @@
+name: GitHub prerelease
+
+on:
+  push:
+    tags:
+      - "v[0-9]*"
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing GitHub release tag to smoke-test
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      attestations: write
+      contents: write
+      id-token: write
+    env:
+      RELEASE_TAG: ${{ github.ref_name }}
+      DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - name: Verify reviewed tag and package version
+        shell: bash
+        run: |
+          python scripts/release.py verify-tag "$RELEASE_TAG"
+          test -f "docs/releases/$RELEASE_TAG.md"
+          git fetch --no-tags origin "$DEFAULT_BRANCH:refs/remotes/origin/$DEFAULT_BRANCH"
+          tag_commit="$(git rev-list -n 1 "$RELEASE_TAG")"
+          git merge-base --is-ancestor "$tag_commit" "origin/$DEFAULT_BRANCH"
+      - name: Build and validate artifacts
+        shell: bash
+        run: |
+          uv build --out-dir dist
+          python tests/check_distribution.py dist
+          python scripts/release.py checksums dist/SHA256SUMS dist/*.whl dist/*.tar.gz
+      - name: Attest distributions built from the release tag
+        uses: actions/attest@a1948c3f048ba23858d222213b7c278aabede763 # v4.1.1
+        with:
+          subject-path: |
+            dist/*.whl
+            dist/*.tar.gz
+      - name: Create GitHub prerelease
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          gh release create "$RELEASE_TAG" \
+            dist/*.whl dist/*.tar.gz dist/SHA256SUMS \
+            --verify-tag \
+            --prerelease \
+            --notes-file "docs/releases/$RELEASE_TAG.md" \
+            --title "agent-tools $RELEASE_TAG"
+
+  smoke-release:
+    needs: release
+    if: always() && (github.event_name == 'workflow_dispatch' || needs.release.result == 'success')
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    env:
+      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.release_tag || github.ref_name }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.12.7"
+      - name: Qualify fresh native installation through external providers
+        timeout-minutes: 10
+        uses: ./.github/actions/install-native
+      - name: Install, pin, and uninstall published wheel (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}\release-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}\release-bin
+        run: |
+          $version = $env:RELEASE_TAG.TrimStart('v')
+          $wheel = "smartnuf_agent_tools-$version-py3-none-any.whl"
+          $url = "https://github.com/$env:GITHUB_REPOSITORY/releases/download/$env:RELEASE_TAG/$wheel"
+          uv tool install --python 3.13 $url
+          if ($LASTEXITCODE -ne 0) { throw "initial tool install failed with exit code $LASTEXITCODE" }
+          $executable = "$(uv tool dir --bin)\agent-tools.exe"
+          if ($LASTEXITCODE -ne 0) { throw "tool bin lookup failed with exit code $LASTEXITCODE" }
+          $reportedVersion = & $executable --version
+          if ($LASTEXITCODE -ne 0) { throw "version command failed with exit code $LASTEXITCODE" }
+          if ($reportedVersion -ne "agent-tools $version") { throw "unexpected version output: $reportedVersion" }
+          & $executable doctor
+          if ($LASTEXITCODE -ne 0) { throw "complete native doctor failed with exit code $LASTEXITCODE" }
+          uv tool install --python 3.13 --reinstall $url
+          if ($LASTEXITCODE -ne 0) { throw "pinned tool reinstall failed with exit code $LASTEXITCODE" }
+          uv tool uninstall smartnuf-agent-tools
+          if ($LASTEXITCODE -ne 0) { throw "tool uninstall failed with exit code $LASTEXITCODE" }
+          if (Test-Path $executable) { throw 'agent-tools executable remains after uninstall' }
+      - name: Install, pin, and uninstall published wheel (Unix)
+        if: runner.os != 'Windows'
+        shell: bash
+        env:
+          UV_TOOL_DIR: ${{ runner.temp }}/release-tools
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}/release-bin
+        run: |
+          version="${RELEASE_TAG#v}"
+          wheel="smartnuf_agent_tools-$version-py3-none-any.whl"
+          url="https://github.com/$GITHUB_REPOSITORY/releases/download/$RELEASE_TAG/$wheel"
+          uv tool install --python 3.13 "$url"
+          tool_bin="$(uv tool dir --bin)"
+          test "$("$tool_bin/agent-tools" --version)" = "agent-tools $version"
+          "$tool_bin/agent-tools" doctor
+          uv tool install --python 3.13 --reinstall "$url"
+          uv tool uninstall smartnuf-agent-tools
+          test ! -e "$tool_bin/agent-tools"

smartnuf_agent_tools-0.1.2/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.tools/
+.cache/
+.backups/
+tmp/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+*.log
+.DS_Store
+Thumbs.db

smartnuf_agent_tools-0.1.2/AGENTS.md

@@ -0,0 +1,20 @@
+# Repository instructions
+
+This repository contains reusable, user-level tools for coding agents and humans.
+
+- Keep scripts cross-platform, idempotent, and safe to rerun.
+- Never commit credentials, tokens, private source material, `.venv/`, caches, or downloaded binaries.
+- Prefer official platform package managers for native programs and `uv` for Python environments.
+- Do not silently alter a user's shell profile, user `PATH`, or system packages. Require an explicit flag and report every change.
+- Pin or constrain dependencies deliberately; review upgrades before changing them.
+- Put portable Python code in `src/agent_tools/`, launchers in `bin/`, platform automation in `scripts/`, and configuration in `config/`.
+- Preserve compatibility with Windows PowerShell 7+, Linux, and macOS. Where behavior differs, document and test the difference.
+- Downloads outside package managers must use official HTTPS sources and verify a published checksum or signature.
+- Prefer additive, reviewable changes. Do not overwrite user configuration without a backup and explicit authorization.
+- Run `python -m unittest discover -s tests`, the platform script syntax checks, and `agent-tools doctor` when relevant.
+- Bound Windows CI steps that invoke native-tool installers with explicit timeouts. After inspecting a failure, retry the same head at most once; never push an empty or unrelated commit merely to retrigger CI.
+- Read `docs/plan/00-index.md` before planning roadmap work. Keep its status, effort forecast, and evidence links current in the same change that advances a milestone.
+- For non-trivial work, identify the milestone and acceptance criterion, write a task plan with estimated effort before implementation, and report completed work, validation, changed estimates, and the recommended next task afterward.
+- Mark roadmap criteria complete only with durable evidence such as a merged change, passing test, published artifact, or release. Do not infer completion from prose or issue counts.
+- Follow [`docs/development-workflow.md`](docs/development-workflow.md) for branch, pull-request, review, and merge work. Merge evidence must apply to the exact current head, concurrent autonomous streams must serialize integration through one merge owner, and pre-existing repository or user state must be preserved.
+- Respect any more-specific `AGENTS.md` in subdirectories.

smartnuf_agent_tools-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smartnuf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.