tool-compass 2.3.0__tar.gz → 2.4.0__tar.gz

{tool_compass-2.3.0 → tool_compass-2.4.0}/.env.example

@@ -55,8 +55,10 @@ GRADIO_SERVER_PORT=7860
 # Analytics (optional)
 # =============================================================================
 
-# Disable analytics tracking
+# Disable analytics tracking (truthy: 1/true/yes/on). Overrides the
+# analytics_enabled config-file key when set.
 # TOOL_COMPASS_ANALYTICS_DISABLED=true
 
-# Hot cache size (number of frequently used tools to pre-load)
+# Hot cache size (number of frequently used tools to pre-load). Overrides the
+# hot_cache_size config-file key; clamped to a safe minimum like any config value.
 # TOOL_COMPASS_HOT_CACHE_SIZE=10

{tool_compass-2.3.0 → tool_compass-2.4.0}/.github/workflows/ci.yml

@@ -86,12 +86,11 @@ jobs:
         continue-on-error: true
         uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
 
-      # CDS-FT-001: SCORECARD drift guard. Soft-fail for now — shipcheck
-      # markdown output is still settling. Flip continue-on-error to false
-      # once the format stabilizes.
-      # TODO(swarm): enforce once shipcheck JSON format stabilizes
+      # CDS-FT-001: SCORECARD drift guard — now BLOCKING. The dogfood-swarm v3
+      # pass fixed CIDOCS-01 (regenerate-scorecard.sh forces NO_COLOR + strips
+      # ANSI), so `--check` diff-cleans deterministically in non-TTY CI. The
+      # committed SCORECARD was verified in sync at flip time.
       - name: Verify SCORECARD is in sync
-        continue-on-error: true
         run: |
           if [ -f Makefile ] && grep -q "^verify-scorecard:" Makefile; then
             make verify-scorecard
@@ -202,12 +201,13 @@ jobs:
           # retention and is plenty of window for incident response.
           retention-days: 14
 
+      # Now BLOCKING. The dogfood-swarm v3 pass reviewed the CVE baseline:
+      # `pip-audit -r requirements.txt` reports no known vulnerabilities. The
+      # report-only artifact step above still runs for the full JSON snapshot.
       - name: Audit dependencies for vulnerabilities
         if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
         run: |
           pip-audit -r requirements.txt
-        # TODO(swarm): enforce after CVE baseline reviewed — issue #TBD
-        continue-on-error: true  # Warn-only until clean baseline established
 
   # TST-FT-002: nightly Hypothesis fuzzing. Runs on schedule (Mon/Wed/Fri 09:00
   # UTC) or manually via workflow_dispatch. Never runs on push/PR — nightly-only.
@@ -249,7 +249,7 @@ jobs:
         # SHA-pinned per SLSA L3 supply-chain hygiene (CT-B-001). nightly-fuzz
         # carries issues:write, so a compromised v7 mutable tag would inherit
         # issue-creation capability. Bump via dependabot's github-actions sweep.
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const title = `[nightly-fuzz] Hypothesis failures on ${context.sha}`;

{tool_compass-2.3.0 → tool_compass-2.4.0}/.github/workflows/publish.yml

@@ -3,14 +3,32 @@
 
 name: Publish
 
+# Triggers — the load-bearing one for the auto-chain is `workflow_run`:
+#  * `release: published` does NOT fire when the Release was created by
+#    release.yml using secrets.GITHUB_TOKEN (GitHub's recursion guard). Without
+#    the workflow_run trigger below, a tag-push release would publish to npm
+#    (via release.yml) but silently SKIP PyPI + GHCR here. The `workflow_run`
+#    trigger gated on Release.conclusion == 'success' closes the chain.
+#  * `release: published` retained for manual hand-cut Releases (gh release
+#    create from a maintainer's terminal — attributed to a user, fires normally).
+#  * `workflow_dispatch` retained for re-run-from-UI on transient failure.
 on:
   release:
     types: [published]
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
   workflow_dispatch:
 
+# Publish workflows must serialize, not cancel. Cancelling a mid-flight twine
+# upload leaves PyPI in a state where the next retry fails with E409 ('File
+# already exists') and needs manual --skip-existing recovery. Group per release
+# tag — resolved across all trigger types (under workflow_run github.ref is the
+# default branch, not the tag) — so distinct tags run independently while
+# same-tag re-fires queue safely.
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref }}
+  cancel-in-progress: false
 
 env:
   REGISTRY: ghcr.io
@@ -20,6 +38,11 @@ jobs:
   build:
     name: Build package
     runs-on: ubuntu-latest
+    # When triggered by workflow_run, only proceed if the upstream Release
+    # workflow succeeded. release: published / workflow_dispatch invocations set
+    # workflow_run to null, which evaluates this expression to truthy (we only
+    # want to short-circuit FAILED workflow_run events).
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
     # CT-B-011: fail-fast budgets per SRE 'fail fast' (Google SRE Book ch.21).
     # Default GitHub timeout is 360 min; a wedged dependency install or twine
     # check is well outside the legitimate envelope at 10 min.
@@ -28,6 +51,11 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Under workflow_run, github.ref is the default branch (main), NOT the
+          # tag — build the tagged commit, not main's HEAD. Resolve the tag from
+          # the single canonical expression used throughout this workflow.
+          ref: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
@@ -107,6 +135,11 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Under workflow_run, github.ref is main, NOT the tag — build the
+          # tagged commit, not main's HEAD. Same resolved-tag expression used
+          # throughout this workflow.
+          ref: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}
 
       - name: Log in to GHCR
         uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
@@ -115,14 +148,36 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # Resolve the release version explicitly. Under workflow_run github.ref
+      # points at the default branch (main), NOT the tag — so
+      # docker/metadata-action's type=semver rules (which only fire on a
+      # refs/tags/... ref) emit NOTHING and the image never gets a :X.Y.Z / :X.Y
+      # tag (only :latest + :sha-...). The tag that started the upstream Release
+      # run is carried on github.event.workflow_run.head_branch (= the tag ref).
+      # Feed the resolved version into metadata-action via type=raw below.
+      - name: Resolve release version
+        id: ver
+        shell: bash
+        run: |
+          set -euo pipefail
+          REF="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}"
+          V="${REF#v}"
+          echo "version=${V}" >> "$GITHUB_OUTPUT"
+          echo "major_minor=$(echo "$V" | cut -d. -f1-2)" >> "$GITHUB_OUTPUT"
+          echo "resolved=${V} (event=${{ github.event_name }} ref=${REF})"
+
       - name: Extract metadata
         id: meta
         uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          # type=raw from the explicitly-resolved version (see Resolve step) —
+          # NOT type=semver, which silently emits nothing under workflow_run
+          # because github.ref is main, not the tag. Each enable=... gates its
+          # raw tag so an empty/missing version never pushes a bogus tag.
           tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=${{ steps.ver.outputs.version }},enable=${{ steps.ver.outputs.version != '' }}
+            type=raw,value=${{ steps.ver.outputs.major_minor }},enable=${{ steps.ver.outputs.major_minor != '' }}
             type=sha
             type=raw,value=latest,enable={{is_default_branch}}
 
@@ -131,7 +186,7 @@ jobs:
         # SHA-pinned per SLSA L3 supply-chain hygiene (CT-B-002). publish job
         # carries packages:write — a compromised mutable v3 tag would inherit
         # GHCR write capability during a release window. Bump via dependabot.
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
@@ -169,7 +224,10 @@ jobs:
         id: ver
         run: |
           set -euo pipefail
-          TAG="${{ github.event.release.tag_name }}"
+          # Resolve the tag across all trigger types. Under workflow_run
+          # github.event.release.tag_name is null and github.ref is main —
+          # workflow_run.head_branch carries the tag ref (e.g. v2.4.0).
+          TAG="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref_name }}"
           echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
           echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
 

tool_compass-2.4.0/.github/workflows/release-binaries.yml

@@ -0,0 +1,175 @@
+# Builds platform binaries on release, uploads to the GitHub Release with
+# SHA256 checksums. Consumed by the @mcptoolshop/tool-compass npm wrapper
+# (via @mcptoolshop/npm-launcher) for zero-prerequisite `npx` installs.
+#
+# Asset naming convention (must match npm-launcher expectations):
+#   binary:    tool-compass-<version>-<os>-<arch>[.exe]
+#   checksums: checksums-<version>.txt
+name: Release Binaries
+
+# Triggers — the load-bearing one for the auto-chain is `workflow_run`:
+#  * `release: published` does NOT fire when the Release was created by
+#    release.yml using secrets.GITHUB_TOKEN (GitHub's recursion guard). Without
+#    the workflow_run trigger below, a tag-push release would publish npm + PyPI
+#    but silently SKIP the platform binaries here (and the npm wrapper that
+#    depends on them). The `workflow_run` trigger gated on
+#    Release.conclusion == 'success' closes the chain.
+#  * `release: published` retained for manual hand-cut Releases (gh release
+#    create from a maintainer's terminal — attributed to a user, fires normally).
+#  * `workflow_dispatch` retained for manually (re)building binaries for a tag.
+on:
+  release:
+    types: [published]
+  workflow_run:
+    workflows: [Release]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build binaries for (e.g. v2.3.0)"
+        required: true
+        type: string
+
+# Serialize per-tag — resolved across all trigger types (under workflow_run
+# github.ref is the default branch, not the tag). Never cancel a mid-flight
+# binary build / asset upload.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch || github.event.release.tag_name || github.ref }}
+  cancel-in-progress: false
+
+env:
+  TOOL_NAME: tool-compass
+  ENTRYPOINT: cli.py
+
+jobs:
+  build:
+    name: Build ${{ matrix.target }}
+    # When triggered by workflow_run, only proceed if the upstream Release
+    # workflow succeeded. release: published / workflow_dispatch invocations set
+    # workflow_run to null, which evaluates this expression to truthy (we only
+    # short-circuit FAILED workflow_run events).
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          # Under workflow_run, github.ref is main, NOT the tag — check out the
+          # tagged commit so binaries are built from the released source.
+          ref: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || inputs.tag }}
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+
+      - name: Install package + PyInstaller
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          pip install . "pyinstaller>=6.9.0"
+
+      - name: Resolve version
+        id: version
+        shell: bash
+        run: |
+          # Resolve the tag across all trigger types. Under workflow_run
+          # github.event.release.tag_name is null — workflow_run.head_branch
+          # carries the tag ref. Asset names derive from this, so a stale value
+          # would name binaries tool-compass-main-... instead of -2.4.0-...
+          TAG="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || inputs.tag }}"
+          VERSION="${TAG#v}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Build single-file binary
+        shell: bash
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          # --collect-submodules covers dynamic imports MCP / Gradio / Rich pull in.
+          # --console keeps stdout/stderr behavior identical to `python cli.py`.
+          pyinstaller --onefile \
+            --name "${{ env.TOOL_NAME }}" \
+            --console \
+            --collect-submodules mcp.client \
+            --collect-submodules mcp.server \
+            --collect-submodules mcp.types \
+            --collect-submodules mcp.shared \
+            --exclude-module mcp.cli \
+            --exclude-module typer \
+            --collect-submodules hnswlib \
+            --collect-submodules numpy \
+            --collect-submodules httpx \
+            "${{ env.ENTRYPOINT }}"
+          OUTNAME="${{ env.TOOL_NAME }}-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/${{ env.TOOL_NAME }}${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "Built: dist/${OUTNAME}"
+          ls -la "dist/${OUTNAME}"
+
+      - name: Smoke test binary
+        shell: bash
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          BIN="dist/${{ env.TOOL_NAME }}-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          # --version is wired on the root parser as of v2.2.1 (a942a67).
+          "$BIN" --version
+          "$BIN" --help
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.TOOL_NAME }}-*
+          retention-days: 7
+
+  attach:
+    name: Attach binaries + checksums to release
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - name: Download all binaries
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          # Resolve the tag across all trigger types (see Resolve version notes).
+          # The checksum filename embeds VERSION, so a stale value would emit
+          # checksums-main.txt — which npm-launcher could never find.
+          TAG="${{ github.event.workflow_run.head_branch || github.event.release.tag_name || inputs.tag }}"
+          VERSION="${TAG#v}"
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          echo "--- checksums-${VERSION}.txt ---"
+          cat "checksums-${VERSION}.txt"
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        with:
+          # Resolve the tag across all trigger types — under workflow_run the
+          # release context is null; head_branch carries the tag. A stale value
+          # would try to attach assets to a release named "main".
+          tag_name: ${{ github.event.workflow_run.head_branch || github.event.release.tag_name || inputs.tag }}
+          files: artifacts/*
+          fail_on_unmatched_files: true
+

tool_compass-2.4.0/.github/workflows/release.yml

@@ -0,0 +1,165 @@
+# Tool Compass — npm Trusted Publisher (OIDC) + GitHub Release.
+#
+# This is the canonical npm publish path. The npm Trusted Publisher binding
+# configured on npmjs.com for @mcptoolshop/tool-compass points at THIS file
+# (.github/workflows/release.yml, workflow name "Release") — the filename and
+# the `name:` below are load-bearing and MUST NOT be renamed.
+#
+# The GitHub Release this workflow creates (step "Create GitHub Release") is
+# what fires the downstream chain: publish.yml (PyPI + GHCR + smoke) and
+# release-binaries.yml (platform binaries + npm wrapper). Because that Release
+# is created with secrets.GITHUB_TOKEN, the `release: published` event does NOT
+# fire (GitHub's recursion guard) — the downstream workflows therefore key off
+# a `workflow_run` trigger gated on this workflow's success. See their headers.
+#
+# The npm wrapper lives in the npm/ subdir (npm/package.json,
+# npm/bin/tool-compass.js), so every npm step runs with working-directory: npm.
+# The pyproject.toml version check runs at the repo root.
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+# Serialize per-tag releases; never cancel an in-flight release just because
+# someone re-pushed the same tag or fired workflow_dispatch. Cancelling a
+# mid-flight `npm publish` after the Sigstore-provenance attestation is signed
+# but before the packument-save commits leaves the registry returning E409
+# ('packument-save race') for 5-30 minutes on retry.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write       # for GitHub Release creation
+  id-token: write       # for npm provenance via Sigstore OIDC
+
+jobs:
+  release:
+    name: Publish to npm + GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install npm >=11.5 in sandbox for OIDC trusted-publishing auth
+        run: |
+          # Node 22 ships npm 10.9, which signs Sigstore provenance fine but
+          # cannot negotiate the OIDC auth path for trusted publishing — the
+          # PUT returns a misleading 404 "not in this registry".
+          #
+          # An in-place `npm install -g npm@latest` races on Node 22's bundled
+          # npm 10.9 arborist rebuild and breaks irrecoverably (MODULE_NOT_FOUND:
+          # promise-retry). Sandbox install + PATH shadow avoids the race.
+          SANDBOX="$HOME/.npm-cli-sandbox"
+          mkdir -p "$SANDBOX"
+          pushd "$SANDBOX" >/dev/null
+          echo '{"name":"npm-cli-sandbox","version":"0.0.0","private":true}' > package.json
+          npm install --no-save --no-audit --no-fund --silent npm@latest
+          popd >/dev/null
+          echo "$SANDBOX/node_modules/.bin" >> "$GITHUB_PATH"
+          "$SANDBOX/node_modules/.bin/npm" --version
+
+      - name: Verify tag matches npm/package.json version
+        run: |
+          PKG_VERSION=$(node -p "require('./npm/package.json').version")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          echo "Tag: ${GITHUB_REF_NAME} → ${TAG_VERSION}"
+          echo "npm/package.json: ${PKG_VERSION}"
+          if [ "${PKG_VERSION}" != "${TAG_VERSION}" ]; then
+            echo "::error::Tag ${TAG_VERSION} does not match npm/package.json version ${PKG_VERSION}"
+            exit 1
+          fi
+
+      # ubuntu-latest's default python3 is not pinned to a particular minor
+      # version. tomllib lives in Python 3.11+ stdlib — falling through to a
+      # 3.10 default would ImportError. Pin 3.11 explicitly (same setup-python
+      # SHA as ci.yml + publish.yml) so the version check is reproducible.
+      - name: Setup Python for pyproject version check
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.11'
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          PY_VERSION=$(python3 -c "import tomllib; print(tomllib.loads(open('pyproject.toml').read())['project']['version'])")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          echo "pyproject.toml: ${PY_VERSION}"
+          if [ "${PY_VERSION}" != "${TAG_VERSION}" ]; then
+            echo "::error::Tag ${TAG_VERSION} does not match pyproject.toml version ${PY_VERSION}"
+            exit 1
+          fi
+
+      # The npm wrapper's bin shim hard-codes the release tag (it points
+      # npm-launcher at the GitHub Release binaries for this exact tag). A stale
+      # tag here would make `npx tool-compass` fetch the wrong release's
+      # binaries. Verify the shim was synced before we publish.
+      - name: Verify npm/bin/tool-compass.js references the tag
+        run: |
+          if ! grep -Fq "${GITHUB_REF_NAME}" npm/bin/tool-compass.js; then
+            echo "::error::npm/bin/tool-compass.js does not reference ${GITHUB_REF_NAME} — run scripts/sync-version.mjs before tagging"
+            exit 1
+          fi
+          echo "npm/bin/tool-compass.js references ${GITHUB_REF_NAME} ✓"
+
+      # No package-lock.json is committed (sole runtime dep is
+      # @mcptoolshop/npm-launcher, digest-locked by the registry). `npm install`
+      # is the honest path here.
+      - name: Install npm wrapper dependencies
+        working-directory: npm
+        run: npm install --no-audit --no-fund
+
+      - name: npm pack dry-run (verify shape)
+        working-directory: npm
+        run: npm pack --dry-run
+
+      - name: Publish to npm with provenance (OIDC trusted publisher)
+        working-directory: npm
+        # OIDC trusted publisher — NO token, NO NODE_AUTH_TOKEN. The
+        # id-token: write permission + the npm@latest installed above negotiate
+        # the auth path. --access public is required for the scoped package.
+        run: npm publish --provenance --access public
+
+      - name: Create GitHub Release (idempotent)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Extract the [<version>] section from CHANGELOG.md as the release
+          # notes. Falls back to the tag name if the section is missing/empty.
+          VERSION="${GITHUB_REF_NAME#v}"
+          NOTES_FILE="$(mktemp)"
+          awk -v ver="${VERSION}" '
+            $0 ~ "^## \\[" ver "\\]" {capture=1; next}
+            capture && /^## \[/ {exit}
+            capture {print}
+          ' CHANGELOG.md > "${NOTES_FILE}"
+
+          if [ ! -s "${NOTES_FILE}" ]; then
+            echo "Tool Compass ${GITHUB_REF_NAME}" > "${NOTES_FILE}"
+            echo "" >> "${NOTES_FILE}"
+            echo "See CHANGELOG.md for details." >> "${NOTES_FILE}"
+          fi
+
+          # Create the release only if it doesn't already exist. This Release is
+          # what fires the downstream workflow_run chain (publish.yml +
+          # release-binaries.yml). Skipping when it exists makes the step
+          # idempotent on workflow_dispatch re-runs / second tag pushes (no
+          # HTTP 422 "tag_name already exists").
+          if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
+            echo "Release ${GITHUB_REF_NAME} already exists; skipping create."
+          else
+            gh release create "${GITHUB_REF_NAME}" \
+              --title "Tool Compass ${GITHUB_REF_NAME}" \
+              --notes-file "${NOTES_FILE}" \
+              --verify-tag
+          fi

{tool_compass-2.3.0 → tool_compass-2.4.0}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-06-20
+
+Dogfood swarm v3 — full health pass (bug/security → proactive → humanization
+→ visual) + a user-scoped feature pass. Tests 991 → 1151; ruff errors 31 → 0.
+No breaking changes; the default config path, the Ollama embedding default,
+and all existing tool/CLI behavior are unchanged.
+
+### Added
+- **`tool-compass init`** — scaffolds `compass_config.json` at the resolved
+  config path and prints a ready-to-paste Claude Desktop `mcpServers` snippet.
+  `--force` to overwrite, `--json` for machine output.
+- **Pluggable embedding backend** — `embedding_provider` config selects the
+  embedder: `ollama` (default, unchanged) or `openai`/`openai-compatible`
+  (`/v1/embeddings`; covers OpenAI, LM Studio, and any compatible server),
+  with `embedding_base_url`, `embedding_api_key` (redacted;
+  `TOOL_COMPASS_EMBEDDING_API_KEY` env override), and prefix overrides.
+- MCP-client registration recipes (Claude Desktop, Cursor, Cline) in the handbook.
+- `LOG_LEVEL`, `TOOL_COMPASS_ANALYTICS_DISABLED`, and
+  `TOOL_COMPASS_HOT_CACHE_SIZE` env overrides are now honored (previously
+  advertised in `.env.example` but ignored).
+
+### Fixed
+- **`tool-compass serve` / `serve --http`** crashed with "unrecognized
+  arguments: serve" — the CLI now neutralizes `sys.argv` before delegating to
+  the gateway.
+- Oversize backend lines (>1 MiB) no longer wedge a connection — the read loop
+  caught the wrong exception type (`LimitOverrunError` vs the `ValueError`
+  `readline()` actually raises).
+- `config doctor`/`show_config` no longer leak `${VAR}`-resolved secrets in
+  backend `headers`/`env`/`args` or credentialed `ollama_url`/backend URLs.
+- Cold-start (`get_index()` RuntimeError) now returns the structured
+  service-unavailable envelope on every read tool instead of a raw stack.
+- `tool-compass sync` reports the honest indexed count + warns on backends
+  that failed to connect (was a fabricated "+0 ~0 -0" line); per-backend sync
+  status is now durable (a failing backend stops reporting healthy).
+- `gateway.py --sync` exits non-zero when it indexes nothing (CI-safe).
+- Gradio UI: pinned the dark theme surface (the UI was invisible in light
+  mode); Status tab now probes the configured Ollama; empty index shows a
+  "run sync" card.
+- Cross-event-loop `RuntimeError` in the embedder semaphore + gateway locks
+  (per-loop keying); several unguarded `json.loads`/error paths hardened.
+
+### Changed
+- Lint gate cleaned (31 ruff errors → 0); 4 vacuous/skip-masking tests
+  hardened so `/ready` + `/metrics` now have executing coverage.
+
 ## [2.3.0] - 2026-05-15
 
 Dogfood swarm v2 release — comprehensive Stage A bug/security pass +

{tool_compass-2.3.0 → tool_compass-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tool-compass
-Version: 2.3.0
+Version: 2.4.0
 Summary: Semantic MCP tool discovery gateway - find tools by intent, not memory
 Project-URL: Homepage, https://github.com/mcp-tool-shop-org/tool-compass
 Project-URL: Documentation, https://github.com/mcp-tool-shop-org/tool-compass#readme
@@ -86,14 +86,6 @@ Savings: 95%
 
 Tool Compass uses **semantic search** to find relevant tools from a natural language description. Instead of loading all tools, Claude calls `compass()` with an intent and gets back only the relevant tools.
 
-<!--
-## Demo
-
-<p align="center">
-  <img src="docs/assets/demo.gif" alt="Tool Compass Demo" width="600">
-</p>
--->
-
 ## Quick Start
 
 📖 **Full documentation:** See the [Tool Compass Handbook](https://mcp-tool-shop-org.github.io/tool-compass/handbook/) for installation, configuration, and architecture deep-dives.
@@ -177,20 +169,20 @@ docker-compose --profile with-ollama up
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                     TOOL COMPASS                            │
+│                       TOOL COMPASS                          │
 │                                                             │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
-│  │   Ollama     │    │   hnswlib    │    │   SQLite     │  │
-│  │   Embedder   │───▶│    HNSW      │◀───│   Metadata   │  │
-│  │  (nomic)     │    │   Index      │    │   Store      │  │
-│  └──────────────┘    └──────────────┘    └──────────────┘  │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
+│  │   Ollama     │    │   hnswlib    │    │   SQLite     │   │
+│  │   Embedder   │───▶│    HNSW      │◀───│   Metadata   │   │
+│  │  (nomic)     │    │   Index      │    │   Store      │   │
+│  └──────────────┘    └──────────────┘    └──────────────┘   │
 │                              │                              │
 │                              ▼                              │
-│                    ┌──────────────────┐                    │
-│                    │  Gateway (9 tools)│                   │
-│                    │  compass, describe│                   │
-│                    │  execute, etc.    │                   │
-│                    └──────────────────┘                    │
+│                    ┌───────────────────┐                    │
+│                    │ Gateway (9 tools)  │                   │
+│                    │ compass, describe  │                   │
+│                    │ execute, etc.      │                   │
+│                    └───────────────────┘                    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -341,7 +333,7 @@ ollama pull nomic-embed-text
 ### Index Not Found
 
 ```bash
-python gateway.py --sync
+tool-compass sync
 ```
 
 ## Related Projects