seam-code 0.3.0__tar.gz → 0.5.0__tar.gz

seam_code-0.5.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owner for everything in the repo.
+# Required reviewer on every PR unless a more specific rule below matches.
+*       @Catafal

seam_code-0.5.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Something isn't working as expected
+labels: bug
+---
+
+**Seam version** (`pip show seam-code` or `uv run seam --version`):
+
+**Python version** (`python --version`):
+
+**OS / platform**:
+
+---
+
+### What happened
+
+<!-- Describe the unexpected behaviour. -->
+
+### What you expected
+
+<!-- Describe what you expected to happen. -->
+
+### Steps to reproduce
+
+```bash
+# Minimal sequence that triggers the bug
+uv run seam init
+uv run seam ...
+```
+
+### Relevant output
+
+<!-- Paste error messages, stack traces, or `--json` output here. -->
+
+```
+```
+
+### Additional context
+
+<!-- Any other details that might help (repo size, language mix, config knobs set). -->

seam_code-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / discussion
+    url: https://github.com/Catafal/seam/discussions
+    about: Ask questions and discuss ideas in GitHub Discussions rather than opening an issue.
+  - name: Security vulnerability
+    url: https://github.com/Catafal/seam/security/advisories/new
+    about: Report security issues privately via GitHub's vulnerability reporting (not a public issue).

seam_code-0.5.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+### Summary
+
+<!-- One-sentence description of the feature. -->
+
+### Problem it solves
+
+<!-- What's missing or painful today? -->
+
+### Proposed solution
+
+<!-- How should it work? A CLI flag, a new MCP tool, a new language, etc. -->
+
+### Alternatives you've considered
+
+<!-- Other approaches you thought of and why you're proposing this one. -->
+
+### Additional context
+
+<!-- Relevant usage patterns, links to prior discussions, example commands. -->

seam_code-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+## Summary
+
+<!-- What does this PR do? One paragraph is enough. Link the relevant issue if there is one. -->
+
+Closes #
+
+## Changes
+
+<!-- Bullet list of what changed and why. -->
+
+-
+
+## Checklist
+
+- [ ] `make gate` passes locally (`make lint && make typecheck && make test`)
+- [ ] Tests added or updated for changed behaviour
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`
+- [ ] No new `os.getenv()` calls outside `seam/config.py`
+- [ ] No new runtime network calls or external service dependencies
+- [ ] Functions stay under 200 lines; files stay under 1000 lines
+
+## Notes for reviewers
+
+<!-- Anything that needs special attention, known trade-offs, or follow-up work. -->

seam_code-0.5.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+  # Python dependencies (uv / pyproject.toml).
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+
+  # GitHub Actions used in CI + release workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"

seam_code-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+# Mirror of `make gate` (lint + typecheck + test) so local and CI verification can never drift.
+# Runs on every push to main and every pull request.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref to save CI minutes.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    name: gate (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # pyproject requires-python = ">=3.12"; test the supported range.
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies (dev group)
+        run: uv sync --dev --python ${{ matrix.python-version }}
+
+      # The three gate steps are split so a failure points at the exact stage.
+      - name: Lint (ruff)
+        run: uv run ruff check seam/ tests/
+
+      - name: Typecheck (mypy)
+        run: uv run mypy seam/ --ignore-missing-imports
+
+      - name: Test (pytest)
+        run: uv run pytest tests/ --tb=short -q

seam_code-0.5.0/.github/workflows/explorer-visual.yml

@@ -0,0 +1,66 @@
+name: Explorer Visual QA
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "web/**"
+      - "seam/server/**"
+      - "seam/query/layout.py"
+      - "seam/cli/serve.py"
+      - ".github/workflows/explorer-visual.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: explorer-visual-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  topology:
+    name: topology browser invariant
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install Python dependencies
+        run: uv sync --extra web --dev --python 3.12
+
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        run: npm ci
+        working-directory: web
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+        working-directory: web
+
+      - name: Run topology visual QA
+        run: npm run test:visual
+        working-directory: web
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: explorer-visual-report
+          path: |
+            web/playwright-report/
+            web/test-results/topology-visual/

seam_code-0.5.0/.github/workflows/no-egress.yml

@@ -0,0 +1,147 @@
+name: No-Egress Proof
+
+# WHY this workflow exists:
+#   Seam's contract is "zero outbound network connections" on its read path.
+#   This workflow proves it at the syscall level by running each Seam command
+#   (CLI + MCP server) under ``strace -f -e trace=connect``, then feeding the
+#   trace to ``tests/support/egress_audit.py``.  Any AF_INET/AF_INET6 connect()
+#   to a non-loopback address fails the job immediately.
+#
+# WHY strace only (not eBPF / seccomp):
+#   strace is available on ubuntu-latest without extra setup; it intercepts
+#   connect() at the kernel boundary regardless of language/runtime/TLS wrapping.
+#   False-positive local connects (SQLite WAL, Unix sockets) are already
+#   classified as 'local' by egress_audit.py.
+#
+# WHY NOT the semantic extra:
+#   ``seam init --semantic`` downloads a ~67 MB model on first run — that IS
+#   a legitimate network call (model bootstrap, not a read-path egress).
+#   The no-egress contract applies to the READ path: init (graph only), search,
+#   context, impact, and the MCP server after a warm index.
+#
+# WHY NOT ``seam fetch``:
+#   ``seam fetch`` downloads a pre-built index artifact from a CI-published URL —
+#   another intentional SETUP-TIME network path, explicitly excluded from this proof.
+#   It is the team-shared-index provisioning download (WS4 S3), analogous to the
+#   model download above.  Once the fetched index is on disk, every subsequent
+#   read command is offline.  ``seam fetch`` is deliberately absent from the strace
+#   probes below; its egress is accepted and documented, not an oversight.
+#
+# WHY the ANN tier (WS2b ``sqlite-vec`` / SEAM_VEC_ANN) needs NO exclusion here:
+#   The sqlite-vec extension is an IN-PROCESS SQLite extension (a shared library
+#   loaded via conn.enable_load_extension).  It makes ZERO network calls at any
+#   point — index build time, query time, or extension-load time.  The ANN read
+#   path is: load extension → issue SQL KNN MATCH → return rows from the local DB.
+#   All I/O is to the local .seam/seam.db file; nothing touches the network.
+#   ANN activation therefore does NOT need to be excluded from the strace probes
+#   below — it is provably in-process and offline, unlike ``seam init --semantic``
+#   (model download) or ``seam fetch`` (artifact download).
+#
+# WHY ``set -euo pipefail``:
+#   Each strace command propagates the child's exit code.  A crashed seam command
+#   would produce an empty trace, which egress_audit would pass — giving a false
+#   green.  Under ``set -e`` the job fails on non-zero exit from the traced
+#   command before egress_audit even runs.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Cancel superseded runs on the same ref to save CI minutes (mirrors ci.yml).
+concurrency:
+  group: no-egress-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  no-egress:
+    name: no-egress syscall audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies (server extra + dev group)
+        # server extra → mcp package needed for the MCP smoke driver.
+        # dev group    → pytest, ruff, etc. (also ensures egress_audit is on PYTHONPATH).
+        # NO semantic extra — model downloads are legitimate network calls, not read-path egress.
+        run: uv sync --extra server --dev --python 3.12
+
+      - name: Install strace
+        run: sudo apt-get update -qq && sudo apt-get install -y strace
+
+      # Index a small fixture directory so every subsequent read command has data.
+      # tests/fixtures/ contains 11 sample source files (~129 symbols) — fast to index
+      # and guaranteed to exist in the repo.
+      - name: Index fixtures directory
+        run: |
+          set -euo pipefail
+          uv run seam init tests/fixtures/
+          echo "Index complete. Verifying index status:"
+          cd tests/fixtures && uv run seam status
+
+      # ── strace probes ────────────────────────────────────────────────────────
+      # Each step: run the command under strace, write a tracefile, then audit it.
+      # ``strace -f`` follows forked children so multi-process commands are covered.
+      # ``-e trace=connect`` captures ONLY connect() syscalls — the minimal filter.
+      # The tracefile name matches the step for easy identification in failure output.
+
+      - name: Probe — seam init (graph only, no --semantic)
+        run: |
+          set -euo pipefail
+          # Re-run init on the fixtures dir (idempotent). The first indexed run above
+          # already proved the path; this run is traced for the egress proof.
+          strace -f -e trace=connect -o /tmp/init.trace \
+            uv run seam init tests/fixtures/
+          uv run python -m tests.support.egress_audit /tmp/init.trace
+
+      - name: Probe — seam search
+        run: |
+          set -euo pipefail
+          cd tests/fixtures
+          strace -f -e trace=connect -o /tmp/search.trace \
+            uv run seam search "add"
+          uv run python -m tests.support.egress_audit /tmp/search.trace
+
+      - name: Probe — seam context
+        run: |
+          set -euo pipefail
+          cd tests/fixtures
+          strace -f -e trace=connect -o /tmp/context.trace \
+            uv run seam context add
+          uv run python -m tests.support.egress_audit /tmp/context.trace
+
+      - name: Probe — seam impact
+        run: |
+          set -euo pipefail
+          cd tests/fixtures
+          strace -f -e trace=connect -o /tmp/impact.trace \
+            uv run seam impact add
+          uv run python -m tests.support.egress_audit /tmp/impact.trace
+
+      - name: Probe — MCP stdio server (via mcp_smoke driver)
+        # The smoke driver spawns ``seam start tests/fixtures/`` as a stdio child,
+        # performs a full MCP handshake (initialize + list_tools), prints the tool
+        # count, and exits 0.  strace -f follows the spawned server child so its
+        # connect() calls are captured in the same tracefile.
+        run: |
+          set -euo pipefail
+          strace -f -e trace=connect -o /tmp/start.trace \
+            uv run --extra server python -m tests.support.mcp_smoke tests/fixtures/
+          uv run python -m tests.support.egress_audit /tmp/start.trace
+
+      - name: All probes passed — no external connections detected
+        run: echo "No-egress proof complete. All connect() calls were local."

seam_code-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,197 @@
+name: Release
+
+# Build and publish `seam-code` to PyPI when a version tag is pushed.
+# Auth uses PyPI Trusted Publishing (OIDC) — no API token anywhere.
+# Tag a release with:  git tag v0.3.1 && git push origin v0.3.1
+on:
+  push:
+    tags:
+      - "v*"
+
+# Least-privilege default for all jobs.  Individual jobs override only what
+# they specifically need (id-token:write for OIDC, contents:write for Release).
+permissions:
+  contents: read
+
+jobs:
+  # ── Gate ────────────────────────────────────────────────────────────────────
+  # Mirror of `make gate` (ruff + mypy + pytest) on the minimum supported
+  # Python version.  Every downstream job depends on this — a red build can
+  # never reach PyPI or the GitHub Release.
+  #
+  # WHY single Python (3.12): the smoke job already exercises 3.12 and 3.13
+  # against the built artifact; duplicating the matrix here doubles tag-push
+  # CI time for no additional signal.
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies (dev group)
+        run: uv sync --dev --python 3.12
+
+      # Three gate steps split so a failure points at the exact stage.
+      - name: Lint (ruff)
+        run: uv run ruff check seam/ tests/
+
+      - name: Typecheck (mypy)
+        run: uv run mypy seam/ --ignore-missing-imports
+
+      - name: Test (pytest)
+        run: uv run pytest tests/ -q
+
+  # ── Build ────────────────────────────────────────────────────────────────────
+  # Build the sdist + wheel; generate SHA-256 checksums OUTSIDE dist/ so the
+  # pypi-publish action only sees the wheel + sdist in its packages-dir.
+  # Two artifacts are uploaded:
+  #   dist       — wheel + sdist (consumed by smoke + publish)
+  #   checksums  — checksums.txt only (consumed by github-release)
+  build:
+    name: build distribution
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: true
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      # Write checksums to the repo root, NOT inside dist/.
+      # The pypi-publish action uploads everything under dist/ — a stray
+      # checksums.txt there would cause a publish error.
+      - name: Generate SHA-256 checksums (outside dist/)
+        run: cd dist && sha256sum *.whl *.tar.gz > ../checksums.txt
+
+      - name: Upload dist artifacts (wheel + sdist)
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload checksums artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: checksums
+          path: checksums.txt
+
+  # ── Smoke ────────────────────────────────────────────────────────────────────
+  # Install the built wheel into a CLEAN virtual environment on each supported
+  # Python version and verify `seam --help` exits 0.
+  #
+  # WHY /tmp/smoke-env: outside the workspace, so no accidental source-tree
+  # reads.  uv manages the exact CPython version requested.
+  smoke:
+    name: smoke (py${{ matrix.python-version }})
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+        with:
+          enable-cache: false  # clean environment — no cached state
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create clean virtual environment
+        run: uv venv /tmp/smoke-env --python ${{ matrix.python-version }}
+
+      - name: Install built wheel into clean environment
+        run: uv pip install --python /tmp/smoke-env/bin/python dist/*.whl
+
+      # `seam --version` reads the installed package metadata — this proves the
+      # binary is installed, importable from the wheel, AND reports the version
+      # that was just built (a stronger post-install assertion than --help).
+      - name: Verify seam binary is installed and reports its version
+        run: /tmp/smoke-env/bin/seam --version
+
+  # ── GitHub Release ───────────────────────────────────────────────────────────
+  # Create a GitHub Release for the pushed tag and attach the distributions
+  # plus checksums.txt.  Uses the pre-installed `gh` CLI — no third-party
+  # action is needed, so the S1 SHA-pin audit gate is not widened.
+  #
+  # WHY contents:write scoped here only: the spec requires least-privilege on
+  # all other jobs.  This is the only job that writes to the repo (releases).
+  github-release:
+    name: GitHub Release
+    needs: [gate, smoke]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # required to create and upload assets to a GitHub Release
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Download checksums
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: checksums
+          path: ./  # land checksums.txt in the working directory
+
+      - name: Create GitHub Release and attach artifacts
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Strip the leading 'v' from the tag for the PyPI URL (v0.3.1 → 0.3.1).
+          VERSION="${GITHUB_REF_NAME#v}"
+          gh release create "$GITHUB_REF_NAME" \
+            dist/* \
+            checksums.txt \
+            --title "seam-code $GITHUB_REF_NAME" \
+            --notes "PyPI: https://pypi.org/project/seam-code/${VERSION}/" \
+            --repo "$GITHUB_REPOSITORY"
+
+  # ── Publish ──────────────────────────────────────────────────────────────────
+  # Publish to PyPI via Trusted Publishing (OIDC — no API token anywhere).
+  # Runs only after the gate AND the smoke matrix both pass.
+  # PEP 740 attestations are enabled so consumers can verify provenance.
+  publish:
+    name: publish to PyPI
+    needs: [gate, smoke]
+    runs-on: ubuntu-latest
+    # The OIDC environment PyPI Trusted Publishing is configured against.
+    environment:
+      name: pypi
+      url: https://pypi.org/project/seam-code/
+    permissions:
+      # Required for Trusted Publishing — mints the short-lived OIDC token.
+      id-token: write
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (Trusted Publishing + PEP 740 attestations)
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
+        with:
+          attestations: true