skillroute 0.2.0__tar.gz

skillroute-0.2.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: npm
+    directory: "/mcp"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: npm
+    directory: "/web"
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly

skillroute-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          cache-suffix: python-${{ matrix.python-version }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Verify lockfile is up to date
+        run: uv lock --check
+
+      - name: Run tests with coverage
+        run: uv run --frozen --extra dev pytest --cov=skillroute --cov-report=term-missing --cov-fail-under=80
+
+      - name: Run lint
+        run: uv run --frozen --extra dev ruff check .
+
+      - name: Run type check
+        run: uv run --frozen --extra dev mypy
+
+      - name: Run example golden routes
+        run: uv run --frozen --extra dev skillroute eval run --fresh --index-root examples/skills --cases examples/evals/golden_routes.json
+
+      - name: Audit Python dependencies
+        run: |
+          uv export --frozen --no-emit-project --no-hashes --format requirements-txt -o requirements-audit.txt
+          uvx pip-audit --no-deps -r requirements-audit.txt
+
+  web:
+    name: Web
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Typecheck web
+        working-directory: web
+        run: npm run typecheck
+
+      - name: Lint web
+        working-directory: web
+        run: npm run lint
+
+      - name: Test web
+        working-directory: web
+        run: npm run test
+
+      - name: Build web
+        working-directory: web
+        run: npm run build
+
+      - name: Audit web dependencies
+        working-directory: web
+        run: npm audit --audit-level=high
+
+  mcp:
+    name: MCP
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          cache-suffix: mcp
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: mcp/package-lock.json
+
+      - name: Install MCP dependencies
+        working-directory: mcp
+        run: npm ci
+
+      - name: Build MCP server
+        working-directory: mcp
+        run: npm run build
+
+      - name: Typecheck MCP server
+        working-directory: mcp
+        run: npm run typecheck
+
+      - name: Test MCP server
+        working-directory: mcp
+        run: npm test
+
+      - name: Verify MCP package contents
+        working-directory: mcp
+        run: npm pack --dry-run
+
+      - name: Audit MCP dependencies
+        working-directory: mcp
+        run: npm audit --audit-level=high
+
+      - name: Smoke test MCP tools
+        working-directory: mcp
+        run: npm run smoke
+
+  package:
+    name: Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          cache-suffix: package
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Verify wheel bundles the web UI
+        run: unzip -l dist/*.whl | grep -q "skillroute/_web/index.html"

skillroute-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,144 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      # The tag is the only thing a human types here, and the version published
+      # comes from package metadata, not from the tag. Without this check,
+      # tagging v0.2.0 while pyproject.toml still says 0.1.0 publishes 0.1.0 to
+      # PyPI under a release titled v0.2.0 -- and a PyPI version can never be
+      # reused, so there is no clean recovery.
+      - name: Verify the tag matches both package versions
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          py=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          npm_version=$(node -p "require('./mcp/package.json').version")
+          echo "tag=$tag pyproject=$py package.json=$npm_version"
+          if [ "$tag" != "$py" ] || [ "$tag" != "$npm_version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME disagrees with pyproject.toml ($py) and/or mcp/package.json ($npm_version)."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel (bundles the web UI)
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Verify wheel bundles the web UI
+        run: unzip -l dist/*.whl | grep -q "skillroute/_web/index.html"
+
+      - name: Pack MCP server tarball
+        working-directory: mcp
+        run: |
+          npm ci
+          npm pack --pack-destination ../dist
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: release-artifacts
+          path: dist/*
+
+  github-release:
+    name: Create GitHub release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: release-artifacts
+          path: dist
+
+      - name: Create release with artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes
+
+  pypi:
+    name: Publish to PyPI
+    if: vars.PYPI_PUBLISH == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: release-artifacts
+          path: dist
+
+      - name: Remove non-PyPI artifacts
+        run: rm -f dist/*.tgz
+
+      - name: Publish via trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  npm:
+    name: Publish MCP server to npm
+    if: vars.NPM_PUBLISH == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      # npm trusted publishing is OIDC: this replaces NPM_TOKEN entirely, so
+      # there is no long-lived credential in repo secrets to leak or rotate.
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      # Trusted publishing needs npm >= 11.5.1. Node 22 bundles npm 10.x even at
+      # its latest patch, so it cannot be used here; Node 24 bundles 11.17+,
+      # which clears the floor without installing anything.
+      #
+      # Do not "fix" this by adding `npm install -g npm@latest` on Node 22: that
+      # is what v0.2.0's first release attempt did, and it failed with
+      # EBADENGINE because npm 12 requires Node ^22.22.2 || ^24.15.0 while
+      # setup-node had pinned 22.14.0.
+      - name: Set up Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish
+        working-directory: mcp
+        run: |
+          npm ci
+          npm publish

skillroute-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+.coverage
+.pytest_cache/
+.ruff_cache/
+.skillroute/
+.venv/
+__pycache__/
+*.egg-info/
+*.pyc
+
+.env
+.env.*
+!.env.example
+
+requirements-audit.txt
+
+mcp/build/
+mcp/node_modules/
+web/dist/
+web/node_modules/
+node_modules/
+
+dist/
+.mypy_cache/
+htmlcov/
+coverage.xml

skillroute-0.2.0/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-13
+
+### Added
+
+- **Harness packs.** Every agent tool SkillRoute supports is now one declarative
+  manifest in `harnesses/*.toml` describing detection, per-platform config paths,
+  and which install modes it offers. v0.1 encoded this as a hardcoded if/elif
+  chain plus a per-client detection function, so adding a tool meant editing
+  around seven places across two modules and three docs; adding one that fits an
+  existing config shape is now a data change with no Python. Six of the fourteen
+  shipped harnesses reuse the same shape unchanged. `tests/test_harnesses.py` is
+  parametrized over whatever is in `harnesses/`, so a new manifest is covered
+  automatically.
+- Seven new harnesses: `pi`, `hermes`, `opencode`, `goose`, `gemini-cli`, `zed`,
+  and `amp` — joining the seven from v0.1, all migrated to manifests with
+  byte-identical generated output.
+- Install modes beyond MCP: `acp`, `skills` (native skills-directory discovery
+  and projection), `hook`, `extension`, and `router_skill`. Where a harness lets
+  you register an extra skills directory (Hermes `external_dirs`, Pi's settings),
+  SkillRoute registers rather than copying — no duplication, no sync drift.
+- Cross-platform config paths. Manifests declare `macos`/`linux`/`windows`
+  variants and the most specific match wins; `skillroute harness show --platform`
+  renders for a platform you are not on. v0.1 detection was macOS-only.
+- `skillroute harness list | detect | show | install | doctor`, plus
+  [docs/harnesses.md](docs/harnesses.md) covering how to add a harness.
+- `skillroute harness doctor` verifies a pack still matches reality: the manifest
+  declares a path for the current platform, every mode still renders, and the
+  config on disk names our server. It then runs the exact server command the
+  config points at and confirms it answers an MCP `initialize` handshake — the
+  one check that inspection cannot fake. Config paths for fourteen tools rot
+  silently, because `harness install` keeps reporting success while writing to a
+  file the tool no longer reads. An absent or unconfigured harness warns rather
+  than fails, so a non-zero exit means real breakage and the command works as a
+  CI gate (`--json`, `--no-probe`).
+- `--server-source {local,npx}` on `harness show` and `harness install` chooses
+  whether a generated config starts the MCP server from a built checkout or from
+  the published `@skillroute/mcp-server` via `npx -y`. v0.1 hardcoded the
+  checkout path, which is why nothing outside a git clone could run SkillRoute.
+  The default stays `local` until the package is actually on npm, so this adds
+  the capability without emitting configs that resolve to nothing.
+- Catalog schema v2 with real migration machinery. `skillroute.migrations`
+  defines ordered, named migrations; `Catalog.initialize()` detects the on-disk
+  version, takes a write lock (`BEGIN IMMEDIATE`) so a concurrent index and UI
+  server cannot both migrate, backs the file up before altering it, and refuses
+  a catalog written by a newer SkillRoute instead of corrupting it. Existing v1
+  catalogs upgrade in place; their traces are unpacked into the new columns
+  rather than discarded.
+- Route traces now record who asked and what happened: `harness_id`,
+  `harness_version`, `surface`, `request_text`, `top_confidence`,
+  `second_confidence`, `catalog_fingerprint`, and the routing weights in effect.
+  A new `route_trace_candidates` table denormalizes every ranked candidate and
+  its score breakdown so analytics can use SQL instead of parsing response
+  blobs. `skillroute route --harness <id>` and `SKILLROUTE_HARNESS` set the
+  attribution; an unknown caller stays unknown rather than erroring.
+- `Catalog.record_outcome()` and a `route_outcomes` table, so an agent can
+  report which skill it actually used. The rank it was offered at is resolved
+  from the recorded candidates rather than trusted from the caller.
+- `route_trace_daily` aggregates every route on the day it happens. Raw traces
+  are still capped, but the rollup is not, so route counts, clarification rates,
+  and confidence distributions survive pruning and remain answerable over time.
+- SQLite FTS5 retrieval backend (`--backend fts5`, alias `sqlite-fts5`):
+  local BM25 ranking with term-frequency and document-length normalization on
+  top of the existing token-overlap lexical score. Query input is escaped so
+  FTS5 syntax in requests is treated as literal terms. Available in the CLI,
+  bridge, and MCP server backend choices.
+- Routing weights are now explicit and tunable: `RouteWeights` replaces the
+  hardcoded blend constants, `SKILLROUTE_WEIGHTS` overrides them per process,
+  and `skillroute eval tune` grid-searches weights against golden route cases
+  so changes are backed by eval evidence. Defaults are unchanged.
+
+### Changed
+
+- The npm release job publishes via npm trusted publishing (OIDC) instead of a
+  long-lived `NPM_TOKEN` secret, so there is no static credential in repo
+  secrets to leak or rotate, and provenance attestations are generated
+  automatically. Requires `id-token: write` and npm ≥ 11.5.1, which Node 22 does
+  not bundle — the job upgrades npm explicitly.
+- The release workflow now fails if the pushed tag disagrees with the version in
+  `pyproject.toml` or `mcp/package.json`. The published version comes from
+  package metadata rather than the tag, so tagging `v0.2.0` against a `0.1.0`
+  pyproject would have published `0.1.0` under a release titled `v0.2.0` — and
+  a PyPI version can never be reused, so there is no clean recovery.
+- Skill discovery is derived from the harness manifests instead of a hardcoded
+  three-entry tuple, growing from 3 roots to 10 — including `~/.claude/skills`,
+  which v0.1 never scanned.
+- Raw route-trace retention raised from 1,000 to 20,000, configurable via
+  `SKILLROUTE_MAX_TRACES` (`0` disables pruning). 1,000 rows was a few days of
+  one active harness — too short a horizon for any question about change over
+  time. Pruning is now amortized across inserts rather than run on every one, so
+  the table may sit slightly above the cap between prunes.
+
+### Deprecated
+
+- `skillroute mcp config --client <id>` in favour of `skillroute harness show`
+  and `skillroute harness install`. Output is unchanged and the deprecation
+  notice goes to stderr, so `--json` stdout stays machine-parseable. The
+  `skillroute.client_setup` and `skillroute.mcp_setup` modules are now shims
+  re-exporting `skillroute.harness_setup` and `skillroute.harness_render`. All
+  are removed in 0.3.
+
+### Security
+
+- The Skill Atlas `POST /api/route-preview` endpoint no longer accepts an
+  arbitrary `repo` filesystem path. Any caller who could reach the local UI
+  server could use it to probe the disk: the response reports whether a
+  directory exists, its resolved absolute path, which marker files it holds,
+  and how many files it contains. A `repo` is now honored only when
+  `SKILLROUTE_REPO_ROOT` names a base directory, and only for paths that
+  resolve inside it (CodeQL `py/path-injection`). The bundled UI never sent
+  `repo`, and the CLI's `--repo` is unaffected.
+
+[Unreleased]: https://github.com/erichare/skill-route/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/erichare/skill-route/compare/v0.1.0...v0.2.0
+
+## [0.1.0] - 2026-08-10
+
+First release.
+
+### Added
+
+- SKILL.md bundle indexing into a local SQLite catalog (`skillroute index`)
+- Semantic routing with ranked skills, confidence, evidence snippets, suggested
+  order, and clarification questions (`skillroute route`)
+- Hybrid search over indexed skills (`skillroute search`) and per-skill
+  inspection (`skillroute inspect`)
+- Pluggable retrieval backends: local token backend and Astra Data API backend,
+  plus a LangChain retriever adapter
+- Metadata overlays for curating tags, domains, and languages without editing
+  skill sources
+- Route observability: persisted route traces (`skillroute traces list`)
+- Golden route evals (`skillroute eval run`)
+- Skill Atlas web UI (`skillroute ui`), bundled into the Python wheel
+- MCP stdio server (`@skillroute/mcp-server`) exposing `skillroute.route`,
+  `skillroute.search`, and `skillroute.inspect_skill`, with client setup via
+  `skillroute mcp config --client <client>`
+
+[0.1.0]: https://github.com/erichare/skill-route/releases/tag/v0.1.0

skillroute-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for your interest in SkillRoute! This page covers local development and
+the release process.
+
+## Development setup
+
+Requirements: [uv](https://docs.astral.sh/uv/), Node 20+.
+
+```bash
+# Python package (src/skillroute) + tests
+uv sync --extra dev
+uv run --extra dev pytest --cov=skillroute --cov-fail-under=80
+uv run --extra dev ruff check .
+uv run --extra dev mypy
+
+# Skill Atlas web UI
+npm --prefix web ci
+npm --prefix web run typecheck && npm --prefix web run lint && npm --prefix web run test
+
+# MCP server
+npm --prefix mcp ci
+npm --prefix mcp run build && npm --prefix mcp test && npm --prefix mcp run smoke
+```
+
+CI mirrors these commands plus dependency audits and a packaging check; see
+[.github/workflows/ci.yml](.github/workflows/ci.yml).
+
+## Guidelines
+
+- Conventional commit messages (`feat:`, `fix:`, `chore:`, ...)
+- Add or update tests with behavior changes; overall coverage must stay >= 80%
+- `ruff` and `mypy` must pass
+
+## Releasing
+
+1. Bump the version in `pyproject.toml`, `mcp/package.json` (and
+   `web/package.json` for consistency). Python code and the MCP server read
+   their versions from package metadata — do not hardcode versions elsewhere.
+2. Add a section to `CHANGELOG.md` and update its compare/tag links.
+3. Land those changes on `main`, then tag and push:
+
+   ```bash
+   git tag vX.Y.Z && git push origin vX.Y.Z
+   ```
+
+4. The [release workflow](.github/workflows/release.yml) builds the sdist,
+   wheel, and npm tarball, then creates a GitHub release with the artifacts
+   attached.
+   - PyPI publishing runs only when the `PYPI_PUBLISH` repository variable is
+     `true` and a [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/)
+     is configured for this repository.
+   - npm publishing runs only when the `NPM_PUBLISH` repository variable is
+     `true` and an `NPM_TOKEN` secret with publish rights to the
+     `@skillroute` scope is configured.

skillroute-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Hare
+
+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.