bigfix-root-mcp 0.1.4__tar.gz

bigfix_root_mcp-0.1.4/.editorconfig

@@ -0,0 +1,23 @@
+# EditorConfig is awesome: https://EditorConfig.org
+# Requires plugin for VSCode:
+# - https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.py]
+# the following is required for compatibility with black:
+indent_style = space
+indent_size = 4
+
+[*.bes]
+indent_style = tab
+# should tabs be 2, 3, or 4 spaces?
+# indent_size = 4
+# actionscript within the XML of BES files MUST have windows line endings:
+end_of_line = crlf

bigfix_root_mcp-0.1.4/.github/dependabot.yml

@@ -0,0 +1,42 @@
+---
+# Dependency-update alerts and PRs.
+#
+# The 7-day cooldown is the point, not a courtesy: a release published minutes
+# ago is the likeliest to be a compromised one. It matches `exclude-newer` in
+# pyproject.toml and is zizmor's minimum.
+version: 2
+updates:
+  # "uv", not "pip": uv.lock is what CI installs from (uv sync --locked), and
+  # "pip" would read pyproject.toml without updating the lock.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+
+  # Scans .pre-commit-config.yaml and updates each hook's `rev:` (SHA-pinned
+  # revs get their version comment updated too, same as the github-actions
+  # entries above). No `cooldown` here: as of 2026-03, GitHub does not support
+  # the cooldown option for this ecosystem, so these PRs land without the
+  # 7-day delay the other two ecosystems get - review before merging.
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"

bigfix_root_mcp-0.1.4/.github/workflows/pre-commit.yaml

@@ -0,0 +1,130 @@
+---
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+  # so a future release workflow can gate on this exact job rather than
+  # polling for other checks to go green
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pre-commit-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    # no-commit-to-branch guards a developer's local `git commit`; it has nothing
+    # to check on a runner. On a push to main, actions/checkout leaves HEAD on
+    # the main branch, so the hook fails the whole run on a merged PR. (On a
+    # pull_request event HEAD is detached at the merge ref, where it passes -
+    # which is why this only shows up after the merge.) SKIP is read by
+    # pre-commit itself, so it applies to both steps below. It is set even
+    # though that hook is currently commented out in .pre-commit-config.yaml,
+    # so uncommenting it there does not silently break CI.
+    #
+    # GH_TOKEN puts zizmor in online mode (offline is the default without it):
+    # it can then fetch the referenced actions themselves for the audits that
+    # need that - see the comment above the zizmor hook in
+    # .pre-commit-config.yaml. The runner's own GITHUB_TOKEN is enough for a
+    # public repo; this is read-only per the `permissions:` block above and
+    # never touches git credentials (actions/checkout below already sets
+    # persist-credentials: false).
+    env:
+      SKIP: no-commit-to-branch
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # required to grab the history of the PR for pre-commit
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+
+      # single source of truth for the uv version: the `rev` of the
+      # astral-sh/uv-pre-commit repo in .pre-commit-config.yaml, which
+      # `pre-commit autoupdate` already keeps current. Read with awk rather
+      # than a yaml parser so it needs nothing installed first. `rev` is
+      # SHA-pinned (Dependabot's pre-commit ecosystem keeps the trailing
+      # `# X.Y.Z` comment in sync when it bumps the SHA - same convention as
+      # the actions/* pins above), so the version comes from that comment;
+      # fall back to the bare `rev` value for a tag-pinned rev with no
+      # comment.
+      - name: read uv version from .pre-commit-config.yaml
+        run: |
+          UV_VERSION="$(awk '
+            /^[[:space:]]*-[[:space:]]*repo:.*astral-sh\/uv-pre-commit[[:space:]]*$/ { found = 1; next }
+            found && $1 == "rev:" {
+              if (match($0, /#[ \t]*(frozen:[ \t]*)?[vV]?[0-9]+(\.[0-9]+)*/)) {
+                ver = substr($0, RSTART, RLENGTH)
+                sub(/^#[ \t]*(frozen:[ \t]*)?[vV]?/, "", ver)
+              } else {
+                ver = $2
+                gsub(/["'\'']/, "", ver)
+                sub(/^[vV]/, "", ver)
+              }
+              print ver
+              exit
+            }
+          ' .pre-commit-config.yaml)"
+          if [ -z "$UV_VERSION" ]; then
+            echo "::error::could not read the astral-sh/uv-pre-commit version from .pre-commit-config.yaml"
+            exit 1
+          fi
+          echo "UV_VERSION=$UV_VERSION" >> "$GITHUB_ENV"
+          echo "uv version: $UV_VERSION"
+
+      # the local uv-lock-check / uv-build-wheel / pytest / mypy hooks are
+      # language: system and shell out to `uv`, which is not on a runner by
+      # default - without this they all fail
+      - name: install uv (needed by the local pre-commit hooks)
+        run: python -m pip install "uv==${UV_VERSION}"
+
+      # the local hooks run `uv run --frozen`, which needs the project's
+      # environment to already exist
+      - name: uv sync --locked
+        run: uv sync --locked
+
+      - name: pre-commit local action test
+        if: github.event_name == 'pull_request' || github.event_name == 'push'
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd  # v3.0.1
+        with:
+          extra_args: >-
+            --color=always
+            --from-ref ${{ github.event.pull_request.base.sha || github.event.before }}
+            --to-ref ${{ github.event.pull_request.head.sha || github.sha }}
+            --hook-stage manual
+
+      # manual dispatch, and a workflow_call: run every hook (including the
+      # manual-stage ones - validate-pyproject, pyroma, the pytest and mypy
+      # wrappers, the check-useless-excludes/check-hooks-apply meta hooks)
+      # against the full tree, not just the diff range a PR/push would use.
+      # workflow_call has no pull_request/before ref to diff against anyway -
+      # github.event there is the caller's payload, not a diff range.
+      - name: pre-commit local action test (manual dispatch)
+        if: github.event_name == 'workflow_dispatch' || github.event_name == 'workflow_call'
+        uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd  # v3.0.1
+        with:
+          extra_args: --color=always --all-files --hook-stage manual
+
+      # `restore-keys` in the shared action means a config change restores the
+      # previous cache and then saves it back under the new key - so every hook
+      # rev bump would otherwise leave its old environment in the cache forever.
+      # gc deletes exactly the environments no live config references. Last step
+      # in the job on purpose: actions/cache saves in its post step, which runs
+      # after this, so what gets uploaded is the pruned store. No `if:` - the
+      # default success() matches the cache action's own `post-if: success()`,
+      # so this runs in precisely the cases where a save follows. `pre-commit`
+      # is on PATH from the shared action's `python -m pip install pre-commit`.
+      - name: prune unused hook environments before the cache is saved
+        run: pre-commit gc

bigfix_root_mcp-0.1.4/.github/workflows/tag_and_release.yaml

@@ -0,0 +1,234 @@
+---
+# Tags and releases on a version bump. Nothing here bumps the version: the flow
+# is to change `[project] version` in pyproject.toml in a PR, merge it to main,
+# and this workflow does the rest (tag, build, checksums, GitHub Release, and -
+# once deliberately enabled, see the publish step - PyPI).
+name: Tag and Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "pyproject.toml"
+      - "uv.lock"
+      - "src/**"
+      - ".github/workflows/tag_and_release.yaml"
+      - ".github/workflows/test.yaml"
+      - ".github/workflows/pre-commit.yaml"
+  # a re-run path for when a release run failed after the version was already
+  # merged; the tag check below still makes it a no-op if the tag exists
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # deliberately no cancel-in-progress: never kill a release mid-flight
+  group: release-${{ github.ref }}
+
+jobs:
+  # Decides whether there is anything to do, so the expensive jobs below can be
+  # skipped outright. A push that touches src/** without bumping the version
+  # gets a green, near-instant run and no release.
+  version:
+    name: Check for an untagged version
+    runs-on: ubuntu-latest
+    # fork guard: a fork that pushes to its own main should not try to release
+    if: github.repository == 'jgstew/bigfix-root-mcp'
+    outputs:
+      version: ${{ steps.getversion.outputs.version }}
+      release_needed: ${{ steps.tagged.outputs.release_needed }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          # full history + tags: the tag check below needs every existing tag
+          fetch-depth: 0
+          fetch-tags: true
+          persist-credentials: false
+
+      # `[project] version` in pyproject.toml is the single source of truth -
+      # src/bigfix_root_mcp/__init__.py reads __version__ back out of the
+      # installed package metadata, so there is no second place to bump.
+      # tomllib is stdlib on the 3.11+ this package requires, and the runner's
+      # preinstalled python is new enough, so no setup-python step is needed.
+      - name: Read version from pyproject.toml
+        id: getversion
+        run: |
+          version="$(python3 -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if ! printf '%s' "$version" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([.-]?[0-9A-Za-z.]+)?$'; then
+            echo "::error::unexpected version string in pyproject.toml: '$version'"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "version: $version"
+
+      # Release only if this version has no tag yet. This is what makes the
+      # workflow idempotent and safe to re-run.
+      - name: Check whether v<version> is already tagged
+        id: tagged
+        env:
+          VERSION: ${{ steps.getversion.outputs.version }}
+        run: |
+          if git show-ref --tags --verify --quiet -- "refs/tags/v${VERSION}"; then
+            echo "release_needed=false" >> "$GITHUB_OUTPUT"
+            echo "v${VERSION} is already tagged - nothing to release"
+          else
+            echo "release_needed=true" >> "$GITHUB_OUTPUT"
+            echo "v${VERSION} has no tag yet - will release"
+          fi
+
+  # The gates. Reusing the test and pre-commit workflows means the release is
+  # blocked by the exact same jobs that guard PRs, with no third-party
+  # wait-for-checks action and no polling. Both run in parallel off `version`
+  # so a release is no slower than the slower of the two.
+  test:
+    name: Test
+    needs: version
+    if: needs.version.outputs.release_needed == 'true'
+    uses: ./.github/workflows/test.yaml
+
+  pre-commit:
+    name: pre-commit
+    needs: version
+    if: needs.version.outputs.release_needed == 'true'
+    uses: ./.github/workflows/pre-commit.yaml
+
+  release:
+    name: Tag and Release
+    needs: [version, test, pre-commit]
+    runs-on: ubuntu-latest
+    # Deliberately gates the whole release - tag, GitHub release, and PyPI
+    # upload - not just the publish step, so an environment protection rule
+    # (required reviewer, wait timer, branch restriction) stops a release
+    # before the tag is cut rather than after. The name must match the
+    # `Environment name` field of the PyPI trusted publisher exactly: PyPI
+    # checks the `environment` claim in the OIDC token, and a mismatch fails
+    # the publish. Create it under Settings > Environments; an environment
+    # with no protection rules is valid and simply records the deployment.
+    environment: pypi
+    permissions:
+      # contents: write - create the tag and the release, and upload assets.
+      # id-token: write - OIDC for the PyPI trusted-publishing step at the end
+      # of this job. Both live here rather than in a separate publish job so
+      # the built dist/ does not have to be handed between jobs through
+      # upload-artifact/download-artifact.
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      # same awk-from-.pre-commit-config.yaml source of truth as
+      # .github/workflows/test.yaml and pre-commit.yaml
+      - name: read uv version from .pre-commit-config.yaml
+        run: |
+          UV_VERSION="$(awk '
+            /^[[:space:]]*-[[:space:]]*repo:.*astral-sh\/uv-pre-commit[[:space:]]*$/ { found = 1; next }
+            found && $1 == "rev:" {
+              if (match($0, /#[ \t]*(frozen:[ \t]*)?[vV]?[0-9]+(\.[0-9]+)*/)) {
+                ver = substr($0, RSTART, RLENGTH)
+                sub(/^#[ \t]*(frozen:[ \t]*)?[vV]?/, "", ver)
+              } else {
+                ver = $2
+                gsub(/["'\'']/, "", ver)
+                sub(/^[vV]/, "", ver)
+              }
+              print ver
+              exit
+            }
+          ' .pre-commit-config.yaml)"
+          if [ -z "$UV_VERSION" ]; then
+            echo "::error::could not read the astral-sh/uv-pre-commit version from .pre-commit-config.yaml"
+            exit 1
+          fi
+          echo "UV_VERSION=$UV_VERSION" >> "$GITHUB_ENV"
+          echo "uv version: $UV_VERSION"
+
+      - name: install uv
+        run: python -m pip install "uv==${UV_VERSION}"
+
+      - name: uv build (wheel + sdist)
+        run: uv build
+
+      # `sha256sum -c SHA256SUMS.txt`-verifiable, and with no dist/ prefix in
+      # it, so it checks out wherever the assets are downloaded to. Globs are
+      # listed explicitly rather than `./*` so the output file can never end up
+      # listing itself.
+      - name: Compute SHA-256 checksums
+        working-directory: dist
+        run: |
+          sha256sum ./*.whl ./*.tar.gz > SHA256SUMS.txt
+          cat SHA256SUMS.txt
+
+      # Release notes: GitHub's own generated notes (same content the Releases
+      # UI would produce) with the checksums appended, so the hashes are
+      # readable in the release body as well as downloadable as an asset. The
+      # notes are built here instead of passing --generate-notes to `gh release
+      # create` so the appended block is not at the mercy of how that flag
+      # combines with --notes.
+      - name: Build release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.version.outputs.version }}
+        run: |
+          notes_file="${RUNNER_TEMP}/release-notes.md"
+          if ! gh api "repos/${GITHUB_REPOSITORY}/releases/generate-notes" \
+                --method POST \
+                -f "tag_name=v${VERSION}" \
+                -f "target_commitish=${GITHUB_SHA}" \
+                --jq '.body' > "$notes_file"; then
+            echo "::warning::could not generate release notes; falling back to a plain body"
+            printf 'Release v%s\n' "${VERSION}" > "$notes_file"
+          fi
+          {
+            printf '\n## SHA-256\n\n'
+            printf 'Verify with `sha256sum -c SHA256SUMS.txt`:\n\n'
+            printf '```\n'
+            cat dist/SHA256SUMS.txt
+            printf '```\n'
+          } >> "$notes_file"
+          echo "NOTES_FILE=$notes_file" >> "$GITHUB_ENV"
+          cat "$notes_file"
+
+      # `gh release create --target` creates the tag itself, so this needs no
+      # git push and the checkout above can stay credential-less. Using the gh
+      # CLI (preinstalled on the runner) also means one less third-party action
+      # to pin and keep updated.
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.version.outputs.version }}
+        run: |
+          gh release create "v${VERSION}" \
+            --target "${GITHUB_SHA}" \
+            --title "v${VERSION}" \
+            --notes-file "${NOTES_FILE}" \
+            dist/*.whl dist/*.tar.gz dist/SHA256SUMS.txt
+
+      # Inert until all of these are true, so nothing can publish by accident:
+      #   1. a PyPI trusted publisher exists for this repo with workflow name
+      #      `tag_and_release.yaml` and environment name `pypi`, matching the
+      #      `environment:` above (https://docs.pypi.org/trusted-publishers/)
+      #   2. the repository variable PYPI_PUBLISH is set to `true`
+      #      (Settings > Secrets and variables > Actions > Variables)
+      #   3. whatever protection rules the `pypi` environment carries have been
+      #      satisfied - those gate this entire job, tagging included
+      # `uv publish` speaks OIDC natively given the id-token: write permission
+      # above, so there is no long-lived API token to store and no
+      # pypa/gh-action-pypi-publish pin to maintain. The release is already
+      # created at this point: a failure here leaves the GitHub release intact
+      # and is re-run by hand, not by re-running the whole workflow.
+      #
+      # NOTE: bigfix-root-mcp is not on PyPI yet, so the very first publish also
+      # needs the project name to exist there or a pending publisher configured.
+      - name: Publish to PyPI (trusted publishing)
+        if: vars.PYPI_PUBLISH == 'true'
+        # the explicit globs keep SHA256SUMS.txt (which lives in dist/ too) out
+        # of the upload; uv publish would otherwise take everything in dist/
+        run: uv publish --trusted-publishing always dist/*.whl dist/*.tar.gz

bigfix_root_mcp-0.1.4/.github/workflows/test.yaml

@@ -0,0 +1,111 @@
+---
+name: test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+  # so a future release workflow can gate on this exact job rather than
+  # polling for other checks to go green
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      # Single bump point for the version this package is tested against; keep
+      # it in step with the `classifiers` list in pyproject.toml. Pinned rather
+      # than "3" so a new CPython release does not silently change what CI runs.
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.13"
+
+      # single source of truth for the uv version: the `rev` of the
+      # astral-sh/uv-pre-commit repo in .pre-commit-config.yaml, which
+      # `pre-commit autoupdate` already keeps current. Read with awk rather
+      # than a yaml parser so it needs nothing installed first. `rev` is
+      # SHA-pinned (Dependabot's pre-commit ecosystem keeps the trailing
+      # `# X.Y.Z` comment in sync when it bumps the SHA - same convention as
+      # the actions/* pins above), so the version comes from that comment;
+      # fall back to the bare `rev` value for a tag-pinned rev with no
+      # comment. Same step as in .github/workflows/pre-commit.yaml.
+      - name: read uv version from .pre-commit-config.yaml
+        run: |
+          UV_VERSION="$(awk '
+            /^[[:space:]]*-[[:space:]]*repo:.*astral-sh\/uv-pre-commit[[:space:]]*$/ { found = 1; next }
+            found && $1 == "rev:" {
+              if (match($0, /#[ \t]*(frozen:[ \t]*)?[vV]?[0-9]+(\.[0-9]+)*/)) {
+                ver = substr($0, RSTART, RLENGTH)
+                sub(/^#[ \t]*(frozen:[ \t]*)?[vV]?/, "", ver)
+              } else {
+                ver = $2
+                gsub(/["'\'']/, "", ver)
+                sub(/^[vV]/, "", ver)
+              }
+              print ver
+              exit
+            }
+          ' .pre-commit-config.yaml)"
+          if [ -z "$UV_VERSION" ]; then
+            echo "::error::could not read the astral-sh/uv-pre-commit version from .pre-commit-config.yaml"
+            exit 1
+          fi
+          echo "UV_VERSION=$UV_VERSION" >> "$GITHUB_ENV"
+          echo "uv version: $UV_VERSION"
+
+      - name: install uv
+        run: python -m pip install "uv==${UV_VERSION}"
+
+      # no --all-extras: this package declares no optional extras, and the dev
+      # tooling lives in [dependency-groups] dev, which uv syncs by default
+      - name: uv sync --locked
+        run: uv sync --locked
+
+      # flags live in [tool.pytest.ini_options] in pyproject.toml, not here
+      - name: pytest
+        run: uv run --frozen pytest
+
+      - name: uv build (wheel + sdist)
+        run: uv build
+
+      # Exercise the artifact a release would actually ship, not just the
+      # source tree: install the wheel into a throwaway venv and import it.
+      # The resource read is the point - the MCP resources are markdown files
+      # loaded at runtime via importlib.resources, so a packaging change that
+      # drops them breaks the server without breaking a source-tree test run.
+      # There is no --help smoke check because the one console script
+      # (bigfix-root-mcp -> server:main) takes no arguments and goes straight
+      # to serving MCP over stdio.
+      - name: install the built wheel and smoke-import it
+        run: |
+          uv venv "${RUNNER_TEMP}/wheeltest"
+          VIRTUAL_ENV="${RUNNER_TEMP}/wheeltest" uv pip install dist/*.whl
+          "${RUNNER_TEMP}/wheeltest/bin/python" - <<'PY'
+          import importlib.resources as r
+
+          import bigfix_root_mcp
+          from bigfix_root_mcp import server  # noqa: F401  (import side effects register the tools)
+
+          print("version:", bigfix_root_mcp.__version__)
+          for name in ("tool-guide.md", "session-cookbook.md", "client-cookbook.md"):
+              text = (r.files("bigfix_root_mcp") / "resources" / name).read_text()
+              assert len(text) > 500, name
+              print(name, len(text), "bytes")
+          PY
+
+      # cheap, and makes a test run's hashes comparable to any released ones
+      - name: sha256 of the built artifacts
+        run: sha256sum dist/*