tool-compass 2.5.2__tar.gz → 2.5.4__tar.gz

{tool_compass-2.5.2 → tool_compass-2.5.4}/.github/workflows/ci.yml

@@ -34,23 +34,15 @@ on:
       - 'npm/**'
       - 'site/**'
       - '.github/workflows/**'
+      - 'atlas/**'
+      # Codecov reads its status and comment settings from this file.
+      - 'codecov.yml'
+  # No paths filter on pull requests, deliberately: this workflow emits the
+  # required status check, and a PR that matched no path (a docs-only change)
+  # would never report it and could never merge. Pushes to main stay
+  # paths-gated.
   pull_request:
     branches: [main]
-    paths:
-      - '*.py'
-      - 'tests/**'
-      - 'scripts/**'
-      - 'requirements*.txt'
-      - 'pyproject.toml'
-      - 'Dockerfile'
-      - 'docker-compose.yml'
-      - 'Makefile'
-      - 'fly.toml'
-      - '.pre-commit-config.yaml'
-      - '.dockerignore'
-      - 'npm/**'
-      - 'site/**'
-      - '.github/workflows/**'
   # TST-FT-002: nightly-fuzz job runs Hypothesis in `nightly` profile
   # Mon/Wed/Fri at 09:00 UTC. Kept in this file to preserve the
   # two-workflow-per-repo limit.
@@ -185,6 +177,10 @@ jobs:
         # Reinstating 3.11 is a deliberate decision with its own test strategy
         # (a self-hosted runner, or a source build of hnswlib/numpy).
         python-version: ['3.12']
+    env:
+      # 'true' on the one leg whose coverage and test results go to Codecov,
+      # on a pull request or a push to the default branch.
+      COVERAGE_LEG: ${{ matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && (github.event_name == 'pull_request' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) }}
 
     steps:
       - name: Checkout repository
@@ -197,6 +193,19 @@ jobs:
           cache: 'pip'
           cache-dependency-path: 'requirements*.txt'
 
+      # The committed Atlas map (atlas/) must match the tree. Atlas needs
+      # Node 22 or later, and the map is the same on every cell, so it is
+      # checked on the Linux cell only.
+      - name: Set up Node for Atlas
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22'
+
+      - name: Atlas check
+        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
+        run: npx --yes @dogfood-lab/atlas@1.24.0 check
+
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -220,16 +229,36 @@ jobs:
           retention-days: 14
 
       - name: Run tests with coverage
+        id: tests
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
         run: |
-          pytest --cov=. --cov-report=xml --cov-report=term -m "not integration"
-
-      - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v5
+          pytest --cov=. --cov-report=xml --cov-report=term -m "not integration" --junitxml=junit.xml
+
+      # The codecov job below uploads what these two steps save; this job
+      # never holds an OIDC token. Coverage is saved when the tests passed,
+      # and test results whenever they ran, failures included, because a
+      # failing test is what that report exists to show. A save step with no
+      # file to save fails the job. overwrite lets a re-run of this job
+      # replace the artifact its earlier attempt saved.
+      - name: Save coverage for Codecov
+        if: ${{ env.COVERAGE_LEG == 'true' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: codecov-coverage
+          path: coverage.xml
+          if-no-files-found: error
+          retention-days: 3
+          overwrite: true
+
+      - name: Save test results for Codecov
+        if: ${{ !cancelled() && env.COVERAGE_LEG == 'true' && steps.tests.outcome != 'skipped' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          file: coverage.xml
-          fail_ci_if_error: false
+          name: codecov-test-results
+          path: junit.xml
+          if-no-files-found: error
+          retention-days: 3
+          overwrite: true
 
       - name: Run pip-audit (report only)
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
@@ -256,6 +285,68 @@ jobs:
         run: |
           pip-audit -r requirements.txt
 
+  codecov:
+    # Uploads what the test job saved, from a job of its own, so the OIDC
+    # token that signs in to Codecov never exists beside the install and the
+    # tests. The checkout, which keeps no token, is there only so Codecov can
+    # match report paths to files: the job installs nothing and runs none of
+    # the repository's code. It runs whenever the test job ran, failures
+    # included, so failing tests still reach Codecov, and only on the events
+    # that collect coverage. A run the concurrency group cancels uploads
+    # nothing, and each run reads only its own artifacts.
+    needs: test
+    if: ${{ !cancelled() && needs.test.result != 'cancelled' && needs.test.result != 'skipped' && (github.event_name == 'pull_request' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch)) }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      # Each artifact unpacks where the test job wrote its files. A pattern
+      # that matches nothing, unlike a name, does not fail: a failing test
+      # run saves test results and no coverage.
+      - name: Download coverage
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: codecov-coverage
+          path: .
+
+      - name: Download test results
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          pattern: codecov-test-results
+          path: .
+
+      # After a passing test job both artifacts exist, so each upload runs,
+      # and fails the job if its files are missing; after a failing one each
+      # runs when its files arrived. Both sign in with OIDC, fail the job when
+      # Codecov refuses the report, and run the Codecov CLI at a fixed version
+      # rather than whichever is newest.
+      - name: Upload coverage to Codecov
+        if: ${{ needs.test.result == 'success' || hashFiles('coverage.xml') != '' }}
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          version: v11.3.1
+          use_oidc: true
+          fail_ci_if_error: true
+          disable_search: true
+          files: ./coverage.xml
+
+      - name: Upload test results to Codecov
+        if: ${{ needs.test.result == 'success' || hashFiles('junit.xml') != '' }}
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          version: v11.3.1
+          use_oidc: true
+          fail_ci_if_error: true
+          report_type: test_results
+          disable_search: true
+          files: ./junit.xml
+
   npm-wrapper:
     name: npm wrapper tests
     runs-on: ubuntu-latest
@@ -285,7 +376,9 @@ jobs:
   # On failure, opens a tracking issue via actions/github-script.
   nightly-fuzz:
     name: Nightly Hypothesis fuzz
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    # A required check, so it also runs on pull requests, with the `ci` profile
+    # (200 examples); the schedule and manual runs keep the slow `nightly` one.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     # CT-B-011: Hypothesis nightly profile is deliberately slow — 45 min cap
     # is wider than the test job because fuzz examples are unbounded.
@@ -313,10 +406,10 @@ jobs:
       - name: Run Hypothesis (nightly profile)
         id: fuzz
         run: |
-          HYPOTHESIS_PROFILE=nightly pytest -m "not integration"
+          HYPOTHESIS_PROFILE=${{ github.event_name == 'pull_request' && 'ci' || 'nightly' }} pytest -m "not integration"
 
       - name: Open tracking issue on failure
-        if: failure() && steps.fuzz.conclusion == 'failure'
+        if: failure() && steps.fuzz.conclusion == 'failure' && github.event_name != 'pull_request'
         # 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.
@@ -485,7 +578,9 @@ jobs:
   # ===========================================================================
   pages-build:
     name: Build site
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    # A required check, so the site also builds on pull requests; only a push to
+    # main configures Pages and uploads the artifact that pages-deploy publishes.
+    if: github.event_name == 'pull_request' || (github.ref == 'refs/heads/main' && github.event_name == 'push')
     runs-on: ubuntu-latest
     # CT-B-011: Starlight npm ci + Astro build; 10 min is generous.
     timeout-minutes: 10
@@ -502,6 +597,7 @@ jobs:
       # silently dependent on Settings → Pages UI state. configure-pages
       # is idempotent and exposes the base path to downstream steps.
       - name: Configure Pages
+        if: github.event_name == 'push'
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
 
       - name: Install site dependencies
@@ -513,6 +609,7 @@ jobs:
         run: npm run build
 
       - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        if: github.event_name == 'push'
         with:
           path: site/dist
 

{tool_compass-2.5.2 → tool_compass-2.5.4}/.github/workflows/publish.yml

@@ -34,6 +34,9 @@ env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: Build package

{tool_compass-2.5.2 → tool_compass-2.5.4}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.4] - 2026-10-14
+
+### Security
+
+- **Workflow jobs run with a read-only token by default.** `publish.yml` had jobs with no `permissions` block, so they inherited the repository default token. A top-level `permissions: contents: read` now applies to every job that does not set its own (the jobs that publish or write keep theirs). Closes the `actions/missing-workflow-permissions` code-scanning alerts.
+
+## [2.5.3] - 2026-10-14
+
+- Build fake credentials at runtime in config and HTTP backend tests so secret scanners do not flag test fixtures.
+
 ## [2.5.2] - 2026-09-09
 
 ### Added

{tool_compass-2.5.2 → tool_compass-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tool-compass
-Version: 2.5.2
+Version: 2.5.4
 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

tool_compass-2.5.4/atlas/README.md

@@ -0,0 +1,101 @@
+# tool-compass: how it works
+
+Mapped at 2026-10-14 from commit a7e6492 by Atlas 1.24.0.
+
+## What this is
+
+8 parts, mostly Python (46 files), JavaScript (4), shell (4), CSS (2), TypeScript (2) and Astro (1). Work enters through 7 doors; the busiest is CI, which reaches 5 parts. It publishes to PyPI, @mcptoolshop/tool-compass to npm, and a container image. It deploys a site to GitHub Pages. People run tool-compass and tool-compass-ui.
+
+## What changed since 2026-10-01 (e6e5806)
+
+Nothing structural changed since 2026-10-01; 9 files changed content.
+
+## What comes in
+
+1. **CI.** On a pull request to main; on a push to main touching 16 paths; on a schedule (`0 9 * * 1,3,5`); or by hand. Runs docker-entrypoint.sh, gateway.py, scripts/check-org-urls.sh and 35 more; checks requirements.txt; packs LICENSE, README.md, _version.py and 15 more into an image. Except on a schedule or when run by hand, it also runs site/astro.config.mjs and site/src/.
+2. **Publish.** When a release is published; when the workflow Release completes; or by hand. Runs cli.py, docker-entrypoint.sh and gateway.py; packs LICENSE, README.md, _version.py and 15 more into an image.
+3. **Release.** When a tag matching `v*` is pushed; or by hand. Runs ui.py.
+4. **Release Binaries.** When a release is published; on a `workflow_call` event; or by hand. Runs ui.py; builds cli.py.
+5. **tool-compass** (a command people run, from npm/package.json). Runs npm/bin/tool-compass.js.
+6. **tool-compass** (a command people run, from pyproject.toml). Runs cli.py.
+7. **tool-compass-ui** (a command people run). Runs ui.py.
+
+## What happens through CI
+
+1. The workflow runs npm/test/ in npm, docker-entrypoint.sh and gateway.py in the repository root, scripts/check-org-urls.sh, scripts/regenerate-scorecard.sh and scripts/verify-metrics.sh in scripts, and tests/ in tests; it checks requirements.txt in the repository root; it packs 18 files in the repository root into an image.
+   1. Inside gateway.py, `main` does, in order: `config.py` (6 steps), `backend_client_simple.py` (3 steps), `ToolDefinition`, `Embedder`, `indexer.py` (3 steps), `disconnect_all` (SimpleBackendManager) and `indexer.py` (3 steps).
+   2. Or, when `isinstance(explicit, str) and explicit.strip()`, `main` does `redact_url_credentials` instead.
+   3. Or, when `_is_ollama_embedding_provider(cfg)`, `main` does `redact_url_credentials` instead.
+   4. Or, when `not tools`, `main` does `disconnect_all` (SimpleBackendManager) instead.
+   5. `main` returns early 1 more way.
+2. Except on a schedule or when run by hand, it also runs site/astro.config.mjs and site/src/.
+3. It uploads coverage to Codecov.
+4. It runs the pre-commit hooks.
+5. It deploys the site on a push to main.
+
+## Who reads the results
+
+CI writes nothing this map can see.
+
+## The other doors
+
+**Publish** runs cli.py, docker-entrypoint.sh and gateway.py, packs LICENSE, README.md, _version.py and 15 more into an image, and publishes to PyPI and a container image.
+
+**Release** runs ui.py, publishes @mcptoolshop/tool-compass to npm, creates a GitHub release, and uploads artifacts/* to the release.
+
+**Release Binaries** runs ui.py, creates a GitHub release, and builds cli.py into binaries for darwin-arm64, linux-x64 and win-x64 and uploads them to the release.
+
+**tool-compass** (a command people run, from npm/package.json) runs npm/bin/tool-compass.js.
+
+**tool-compass** (a command people run, from pyproject.toml) runs cli.py.
+
+**tool-compass-ui** (a command people run) runs ui.py.
+
+## What breaks what
+
+- **the repository root** is imported only from tests, by 1 part (tests), and sits on the path of 6 doors.
+- **npm** is imported by no other part and sits on the path of 2 doors.
+
+## What tends to change together
+
+No two source files changed together often enough to name.
+
+Window: 180 days; a pair counts from 3 shared commits, since 0 source files reach 10 revisions; the floor rises to 10 when 25 do.
+
+## What no test touches
+
+- **scripts** is imported by no test.
+
+npm is tested only by its package's own test script, which a workflow runs.
+
+## Written but never read
+
+Every written place has a reader.
+
+## Helpers that look duplicated
+
+No two parts export a helper that looks alike.
+
+## Generated, never hand-edited
+
+- **npm/bin/tool-compass.js** has a block written by scripts/sync-version.mjs.
+- **npm/package.json** has a block written by scripts/sync-version.mjs.
+
+## Hand-authored
+
+People write .github/, assets/, docs/ and site/; 11 writes with paths built at run time may land here.
+
+## Where to start
+
+.github/workflows/ci.yml → gateway.py → config.py → backend_client_simple.py → tool_manifest.py → embedder.py → indexer.py
+
+Read those in order to follow one pull request end to end.
+
+## What this map cannot see
+
+- 11 writes and 4 reads use paths built at run time and are not named here.
+- 5 writes and 35 reads go to a path their caller passes, not to this repository.
+- There is a docker-compose.yml and a fly.toml that no workflow runs; what deploys from them does so from outside this repository, and is not on this page.
+- Statistics confidence is low: fewer than 25 source files reach 10 revisions in the window.
+
+Regenerate with `npx --yes @dogfood-lab/atlas map`.

tool_compass-2.5.4/atlas/boundaries.yaml

@@ -0,0 +1,34 @@
+summary: ""
+boundaries:
+  - name: .github
+    globs:
+      - .github/**
+    role: config
+  - name: assets
+    globs:
+      - assets/**
+    role: data
+  - name: docs
+    globs:
+      - docs/**
+    role: data
+  - name: npm
+    globs:
+      - npm/**
+    role: code
+  - name: root
+    globs:
+      - "*"
+    role: code
+  - name: scripts
+    globs:
+      - scripts/**
+    role: code
+  - name: site
+    globs:
+      - site/**
+    role: site
+  - name: tests
+    globs:
+      - tests/**
+    role: test