openaca 0.1.0__tar.gz

openaca-0.1.0/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/INDEX.md ]; then printf '=== ARCHITECTURE DECISIONS (docs/adrs/) ===\\n\\nRead a full ADR before changing logic in the area it covers.\\n\\n'; cat docs/adrs/INDEX.md; fi"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE COMPACTION ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE SESSION END ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

openaca-0.1.0/.github/ISSUE_TEMPLATE/beta-feedback.md

@@ -0,0 +1,68 @@
+---
+name: Beta feedback
+about: Report scanner ergonomics, coverage gaps, or workflow fit during the 0.1.0bN beta.
+title: '[beta] '
+labels: ['beta']
+---
+
+<!-- Thanks for testing OpenACA. Fields marked (required) are the ones I look at first. -->
+
+### Feedback type (required)
+
+<!-- Pick the closest fit — helps me triage. -->
+
+- [ ] Scanner ergonomics — install / first scan / output legibility / CLI friction
+- [ ] Coverage gap — something the scanner inventoried or missed that surprised me
+- [ ] Workflow fit — where OpenACA does or doesn't fit in my security tooling
+
+### Command run (required)
+
+```bash
+# Paste the full command you ran, e.g.:
+# openaca scan repo --target ./my-mcp-server --include-posture
+```
+
+### OpenACA version (required)
+
+```
+# Output of `openaca --version`
+```
+
+### Expected vs actual (required)
+
+**Expected:**
+
+**Actual:**
+
+### Output (redacted as needed)
+
+<!--
+Paste scanner output. If it contains internal names, paths, or component IDs
+you don't want public, redact freely — replace with <redacted> or generic
+placeholders. The shape of the output is more useful than the literal
+contents. SARIF is sometimes easier to redact than text.
+-->
+
+```
+```
+
+### Missing or incorrect inventory
+
+<!--
+If the scanner missed something it should have inventoried, or inventoried
+something incorrectly, describe what + where. Format hint:
+- Manifest: path/to/file
+- Should have shown: <name@version>
+- Actually showed: <empty | wrong name | wrong version>
+Leave blank if this isn't an inventory issue.
+-->
+
+### Environment
+
+- OS:
+- Python version (`python --version`):
+- Install path (`pip install ...` / `uv sync` / other):
+
+### Anything else?
+
+<!-- Workflow context, what you wish it did, why you tried it, etc. -->

openaca-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security disclosure
+    url: https://github.com/open-agent-security/openaca/security/advisories/new
+    about: Private security advisories for OpenACA-the-scanner bugs. See SECURITY.md.
+  - name: Beta tester guide
+    url: https://github.com/open-agent-security/openaca-demo/blob/main/BETA-TESTER-GUIDE.md
+    about: Beta-tester guide (hosted in the public openaca-demo repo since openaca is private during the closed beta).

openaca-0.1.0/.github/workflows/autofix.yml

@@ -0,0 +1,324 @@
+name: Autofix
+
+# Two-direction comment-bounce that closes the Codex/Claude review loop
+# without human intervention:
+#
+#   1. Codex bot reviews a PR  ->  this workflow posts `@claude please
+#      address...`  ->  claude.yml fires, claude reads the review, fixes
+#      it, pushes commits, posts a "Claude finished" summary comment.
+#
+#   2. Any new commits land on a PR head (`pull_request: synchronize`) ->
+#      this workflow posts `@codex review` -> Codex re-reviews HEAD. ONE
+#      job covers every source of new commits — the claude bot's fixes, a
+#      human / local-agent push, AND the auto-rebase force-push below —
+#      because `synchronize` fires regardless of who pushed. (Codex
+#      auto-reviews on PR open / draft->ready natively, but NOT on
+#      subsequent pushes; without this, later commits land unreviewed.)
+#
+# The two bounces together produce: codex-flag -> claude-fix ->
+# codex-rereview -> ... bounded by the claude-side iteration cap in
+# bounce 1 (the cap counts claude runs, so push-driven re-reviews add
+# entry points, not an unbounded cycle). Codex is silent when clean
+# (thumbs reaction), so an unnecessary @codex review on a no-op SHA costs
+# one cheap call with no PR noise.
+#
+# Authentication: comments are posted (and PR branches are rebased)
+# using AUTOFIX_TRIGGER_PAT, NOT secrets.GITHUB_TOKEN. GitHub explicitly
+# suppresses workflow runs triggered by events created with
+# GITHUB_TOKEN (recursion guard) — so a comment posted under
+# github-actions[bot] would be silently dropped before claude.yml ever
+# fired, and a rebase pushed under GITHUB_TOKEN would not re-trigger
+# CI / Codex on the rebased branch. The PAT is fine-grained, owned by
+# a repo OWNER/MEMBER, with BOTH:
+#   - `Pull requests: Read and write` — for `gh pr comment` (bounces 1
+#     and 2) and `gh pr list` (bounce 0).
+#   - `Contents: Read and write` — for `actions/checkout` to fetch and
+#     `git push` from the rebase-stale-prs job. WITHOUT this, the job
+#     fails at the `Checkout` step with `403: Write access to
+#     repository not granted` — actions/checkout asks GitHub to verify
+#     write permission upfront because the same token will push later.
+# The resulting comments/pushes are authored by that user, which DOES
+# trigger downstream workflows AND naturally passes claude.yml's
+# OWNER/MEMBER/COLLABORATOR trust gate. The same PAT serves all three
+# bounces — Codex's webhook listener watches @-mentions in PR comments
+# regardless of author.
+#
+# If AUTOFIX_TRIGGER_PAT is unset, both `gh pr comment` paths fail
+# with an auth error and the chain breaks; rebase-stale-prs detects
+# the missing secret and skips with a workflow warning. Manual
+# @claude triggers are unaffected.
+#
+# Workflow-injection safety: every user/bot-controlled input (PR number,
+# comment body, review id) is read via env: and referenced as a shell
+# variable. Comment bodies posted to the PR are hardcoded literals — no
+# interpolation of untrusted input into shell.
+
+on:
+  pull_request_review:
+    types: [submitted]
+  pull_request:
+    # Bounce 2: new commits on a PR head -> request a Codex re-review.
+    # `synchronize` fires for pushes from ANY author — claude bot fixes,
+    # human / local-agent pushes, AND the auto-rebase force-push from
+    # rebase-stale-prs. App-authored pushes (claude[bot]) are NOT the
+    # workflow's GITHUB_TOKEN, so they are not recursion-suppressed and DO
+    # fire this event (verified: CI runs on claude's pushed commits).
+    types: [synchronize]
+  push:
+    # Bounce 0: main moved -> rebase open PRs that are now stale. Catches
+    # both PR merges AND direct pushes to main (manual hotfixes, manual
+    # main pushes). pull_request:closed+merged would miss the latter.
+    branches: [main]
+
+jobs:
+  trigger-claude-via-comment:
+    # Bounce 1: Codex review submitted -> @claude addresses it.
+    if: github.event_name == 'pull_request_review' && github.event.review.user.login == 'chatgpt-codex-connector[bot]' && github.event.review.state == 'commented'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.pull_request.number }}
+      REVIEW_ID: ${{ github.event.review.id }}
+      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    steps:
+      # Cap the auto-address loop at 7 claude runs per PR. If claude has
+      # already run 7+ times and Codex is still finding issues, the loop
+      # isn't converging — force human attention rather than burn cycles.
+      #
+      # Default was 3 originally; bumped to 7 because legitimate Codex
+      # reviews on substantive PRs routinely surface 5-6 rounds of real
+      # findings (defensive type guards across sibling files, CLI-flag
+      # table extensions, OSV event-window edge cases). 3 was capping
+      # real review work, not just runaway loops; 7 keeps the safety
+      # net while accommodating multi-round legitimate review. Adjust
+      # MAX below if your project's review patterns differ.
+      #
+      # Count claude-code-action runs by counting top-level PR comments
+      # authored by the bot (the action posts ONE in-progress comment
+      # per run and edits it in place to the "Claude finished..." summary
+      # — 1 comment == 1 run). More accurate than counting bot commits:
+      # a run that lands 0 commits (no-op fix or pre-push failure) and a
+      # run that lands N commits both equal one iteration of the loop.
+      #
+      # Login string is "claude" — NOT "claude[bot]" — because
+      # `gh pr view --json comments` uses GraphQL, and GraphQL's
+      # `author.login` returns the bare bot name without the `[bot]`
+      # suffix. The `[bot]` suffix only appears in REST surfaces (e.g.
+      # `github.event.comment.user.login` at bounce-2 below). Same bot,
+      # two string representations depending on which API you read.
+      - name: Cap auto-address iterations (max 7)
+        run: |
+          MAX=7
+          CLAUDE_RUNS=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq '[.comments[] | select(.author.login == "claude")] | length')
+          if [ "$CLAUDE_RUNS" -ge "$MAX" ]; then
+            gh pr comment "$PR_NUM" -R "$REPO" --body "🛑 Auto-address loop limit hit — claude has already run $CLAUDE_RUNS times on this PR (max $MAX). Codex review id $REVIEW_ID was NOT auto-addressed. Manual review needed; re-tag claude explicitly after addressing the underlying issue if you want to continue. ([workflow run]($RUN_URL))"
+            echo "::error::Auto-address loop limit hit ($CLAUDE_RUNS/$MAX) — see PR comment."
+            exit 1
+          fi
+          echo "Auto-address iteration $((CLAUDE_RUNS + 1)) of $MAX"
+
+      # Post the @claude trigger. The body intentionally references "the
+      # Codex review above" — claude-code-action's default prompt
+      # construction will include the full review thread so the bot has
+      # the actual findings + line context to act on.
+      #
+      # No HEAD-SHA marker is needed here: bounce 2 is now driven by
+      # `pull_request: synchronize` (a real push), so "claude finished
+      # without pushing" simply produces no synchronize and no re-review —
+      # the old comment-driven no-push detection it required is gone.
+      - name: Post @claude trigger comment
+        run: |
+          gh pr comment "$PR_NUM" -R "$REPO" --body "@claude please address the Codex review feedback above. CRITICAL: before applying any fix that depends on infrastructure or invariants you have not verified (DLQ, schema, contracts, ADRs in docs/adrs/), grep the repo for the prerequisite. If it is not present, push back via a PR comment explaining the missing context rather than implementing on a false premise."
+
+  request-codex-rereview-on-push:
+    # Bounce 2: new commits pushed to a PR head -> @codex re-reviews HEAD.
+    # `pull_request: synchronize` fires on EVERY push to the PR head
+    # regardless of author — the claude bot's fixes, a human / local-agent
+    # push, AND the auto-rebase force-push from rebase-stale-prs — so this
+    # single job covers all of them. Replaces the old issue_comment /
+    # "Claude finished" trigger: claude-code-action commits via the Claude
+    # GitHub App (author claude[bot]), and App-authored pushes fire
+    # pull_request events (they are not the workflow's GITHUB_TOKEN, so not
+    # recursion-suppressed). "Claude finished without pushing" needs no
+    # special case now — no commits means no synchronize means no review.
+    #
+    # Same-repo only: GitHub withholds secrets from pull_request runs on
+    # fork PRs, so AUTOFIX_TRIGGER_PAT would be empty and `gh pr comment`
+    # would fail. Excluding forks here keeps fork PRs from producing red
+    # runs (and claude.yml refuses fork PRs downstream anyway).
+    if: >
+      github.event_name == 'pull_request'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    concurrency:
+      # Coalesce rapid pushes to one review of the final SHA. Without this,
+      # 5 quick commits = 5 separate @codex reviews (each distinct SHA
+      # dodges the per-SHA marker). cancel-in-progress keeps only the
+      # latest push's job, which then reads the current HEAD.
+      group: codex-rereview-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.pull_request.number }}
+    steps:
+      # Per-SHA idempotency: skip if we already requested review for the
+      # current HEAD. Guards a double-synchronize on the same SHA and any
+      # overlap with a manual @codex review. Read live HEAD (not the event
+      # SHA) so a coalesced burst reviews the latest commit.
+      - name: Post @codex re-review trigger (idempotent per SHA)
+        run: |
+          HEAD_SHA=$(gh pr view "$PR_NUM" -R "$REPO" --json headRefOid --jq '.headRefOid')
+          MARKER="<!-- autofix-rereview-sha:$HEAD_SHA -->"
+          ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+          if [ "$ALREADY" -gt 0 ]; then
+            echo "Already requested @codex review for $HEAD_SHA — skipping."
+            exit 0
+          fi
+          gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+          @codex review the latest commits pushed to this PR."
+
+  rebase-stale-prs:
+    # Bounce 0: main moved -> for each open PR (same-repo only, fork PRs
+    # excluded), check mergeStateStatus and either rebase cleanly or ask
+    # @claude to resolve conflicts. Catches both PR-merge pushes and
+    # direct pushes to main.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    concurrency:
+      # Coalesce: if main moves twice while we're still working on the
+      # first push, cancel and re-run with the latest SHA. Avoids racing
+      # two rebase runs against the same PR.
+      group: rebase-stale-prs
+      cancel-in-progress: true
+    env:
+      # Use the PAT for both gh API calls AND the git push. Pushing to a
+      # PR branch under GITHUB_TOKEN works but invalidates downstream
+      # workflow triggers (recursion guard) — the PAT keeps the @claude
+      # comment path working if this rebase later races with a Codex
+      # review on the same PR.
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      MAIN_SHA: ${{ github.sha }}
+    steps:
+      # Graceful skip when the PAT secret isn't configured yet (initial
+      # repo setup). Without this guard, actions/checkout fails with
+      # "Input required and not supplied: token" on every push to main,
+      # turning every merge into a red workflow run during the window
+      # between "workflows scaffolded" and "secrets configured."
+      - id: have_pat
+        name: Check AUTOFIX_TRIGGER_PAT presence
+        env:
+          PAT: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+        run: |
+          if [ -z "$PAT" ]; then
+            echo "::warning::AUTOFIX_TRIGGER_PAT not set; skipping rebase. Add the secret per setup-autofix instructions to enable."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout (full history for rebase)
+        if: steps.have_pat.outputs.skip != 'true'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+
+      - name: Configure git author
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          git config user.email "actions@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Rebase BEHIND PRs / flag DIRTY ones
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+
+          # mergeStateStatus values that matter:
+          #   CLEAN     - up to date with main (or ahead). skip.
+          #   BEHIND    - mergeable, base moved. clean rebase needed.
+          #   DIRTY     - conflicts. ask @claude.
+          #   BLOCKED   - branch protection or required checks failing. skip.
+          #   UNSTABLE  - mergeable but failing checks. skip — pre-existing.
+          #   UNKNOWN   - GitHub still computing. skip; next push retries.
+          #
+          # We exclude fork PRs: pushing to a fork branch from this workflow
+          # 403s, and posting @claude on a fork is blocked downstream by
+          # claude.yml's fork-refusal step anyway.
+          PRS_JSON=$(gh pr list --state open -R "$REPO" \
+            --json number,headRefName,mergeStateStatus,baseRefName,headRepository \
+            --jq "[.[] | select(.baseRefName == \"main\") | select(.headRepository.nameWithOwner == \"$REPO\")]")
+
+          echo "Open same-repo PRs targeting main:"
+          echo "$PRS_JSON" | jq -r '.[] | "  #\(.number) [\(.mergeStateStatus)] \(.headRefName)"'
+
+          # Process each PR. Loop over JSON array via index so we can read
+          # only env-style fields and never interpolate untrusted data.
+          COUNT=$(echo "$PRS_JSON" | jq 'length')
+          for i in $(seq 0 $((COUNT - 1))); do
+            PR_NUM=$(echo "$PRS_JSON" | jq -r ".[$i].number")
+            BRANCH=$(echo "$PRS_JSON" | jq -r ".[$i].headRefName")
+            STATUS=$(echo "$PRS_JSON" | jq -r ".[$i].mergeStateStatus")
+
+            # Defensive: branch names are user-controlled. Refuse anything
+            # that isn't a sane ref. (`refs/heads/<name>` syntax: letters,
+            # digits, slashes, dashes, underscores, dots.)
+            if ! printf '%s' "$BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then
+              echo "::warning::PR #$PR_NUM has unsafe branch name; skipping"
+              continue
+            fi
+
+            case "$STATUS" in
+              BEHIND)
+                echo "PR #$PR_NUM ($BRANCH): clean rebase needed"
+                git fetch origin "$BRANCH":"refs/remotes/origin/$BRANCH" --force
+                git checkout -B "$BRANCH" "origin/$BRANCH"
+                if git rebase origin/main; then
+                  if git push --force-with-lease origin "$BRANCH"; then
+                    gh pr comment "$PR_NUM" -R "$REPO" \
+                      --body "🔁 Auto-rebased on \`main\` (no conflicts) after $MAIN_SHA."
+                  else
+                    echo "::warning::Force-push of #$PR_NUM failed (lease lost?). Will retry on next push."
+                  fi
+                else
+                  # Race: GitHub said BEHIND but the rebase produced
+                  # conflicts. The next push will see DIRTY and route to
+                  # the @claude path.
+                  git rebase --abort
+                  echo "::warning::Rebase of #$PR_NUM failed despite BEHIND status (likely race with another push)"
+                fi
+                git checkout main
+                ;;
+              DIRTY)
+                echo "PR #$PR_NUM ($BRANCH): conflicts — asking @claude to rebase"
+                # Idempotency: don't re-ask claude for the same main SHA.
+                MARKER="<!-- autofix-rebase-claude:$MAIN_SHA -->"
+                ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+                  --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+                if [ "$ALREADY" -gt 0 ]; then
+                  echo "  already asked @claude for $MAIN_SHA — skipping"
+                  continue
+                fi
+                gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+                @claude main has moved and this PR has merge conflicts. Please rebase \`$BRANCH\` on \`origin/main\` and resolve any conflicts. Run the local pre-push gate before force-pushing. If the conflicts indicate the underlying approach is invalidated by the new main, push back via a comment instead of force-fitting a resolution."
+                ;;
+              CLEAN)
+                echo "PR #$PR_NUM ($BRANCH): already current — skipping"
+                ;;
+              *)
+                echo "PR #$PR_NUM ($BRANCH): status $STATUS — leaving alone"
+                ;;
+            esac
+          done

openaca-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,135 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Skip the gates on chore/setup PRs that don't have Python sources yet.
+      # Without this, `uv sync --frozen` fails on a clean repo because there's
+      # no pyproject.toml/uv.lock to install from. Once the first pyproject.toml
+      # lands, the rest of the workflow runs.
+      - id: project_check
+        name: Detect Python project files
+        run: |
+          if [ -f pyproject.toml ] && [ -f uv.lock ]; then
+            echo "have_project=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "have_project=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No pyproject.toml + uv.lock yet — skipping lint/test gates."
+          fi
+
+      - name: Install uv
+        if: steps.project_check.outputs.have_project == 'true'
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          # Match pyproject.toml `requires-python`. Pinning here in CI catches
+          # any newer-syntax regressions that would break the lower bound.
+          # `python-version` here both installs that interpreter AND sets
+          # UV_PYTHON so every subsequent `uv sync`/`uv run` uses it.
+          python-version: "3.11"
+
+      - name: Sync deps
+        if: steps.project_check.outputs.have_project == 'true'
+        # `--frozen` forbids re-resolution: CI installs exactly what's in the
+        # committed uv.lock instead of silently picking up newer transitive
+        # versions. If uv.lock is missing or stale vs. pyproject.toml, this
+        # fails fast — exactly what we want in CI.
+        run: uv sync --frozen
+
+      - name: Ruff check
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run ruff format --check .
+
+      - name: Pyright
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run pyright
+
+      - name: Pytest
+        if: steps.project_check.outputs.have_project == 'true'
+        run: uv run pytest --cov=tools --cov-report=term-missing
+
+      - name: Lint overlay corpus
+        if: steps.project_check.outputs.have_project == 'true'
+        run: |
+          if [ -d overlays ] && [ "$(find overlays -name '*.yaml' -print -quit)" ]; then
+            uv run openaca lint overlays/
+          else
+            echo "::notice::no overlays present yet; skipping openaca lint"
+          fi
+
+  # lint-and-test installs from the committed uv.lock (--frozen) — the *dev*
+  # env. End users run `uv tool install` from PyPI, which ignores uv.lock and
+  # re-resolves deps from this package's metadata (pyproject constraints). That
+  # path once shipped a dep pre-release that broke the CLI at runtime. This job
+  # exercises it: build the wheel, install with deps resolved fresh (mirroring
+  # scripts/install.sh's --prerelease=explicit), then run the user-facing
+  # commands — so a too-loose constraint fails CI here, not a user's shell.
+  # No network calls: the scan fixture has no OSV-queryable components, and
+  # the remote sync targets an unreachable port (per linter discipline,
+  # external APIs must not gate PRs).
+  smoke-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+      - name: Build wheel
+        run: uv build --wheel
+      - name: Install the wheel with deps resolved fresh (no lock)
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke/bin/python --prerelease=explicit dist/*.whl
+      - name: Smoke — user-facing commands against freshly-resolved deps
+        run: |
+          set -eu
+          openaca=/tmp/smoke/bin/openaca
+
+          "$openaca" --version
+
+          # scan repo: parsers + matcher + renderer wiring. The remote-MCP
+          # fixture yields a real component but no OSV-queryable PURL.
+          mkdir -p /tmp/smoke-target
+          cat > /tmp/smoke-target/mcp.json <<'FIXTURE'
+          {"mcpServers": {"remote": {"type": "http", "url": "https://api.example.test/mcp"}}}
+          FIXTURE
+          "$openaca" scan repo --target /tmp/smoke-target --include-posture --fail-on none
+
+          # bom repo: BOM build + serialization wiring.
+          "$openaca" bom repo --target /tmp/smoke-target --output /tmp/smoke-bom.json
+          test -s /tmp/smoke-bom.json
+
+          # remote configure + sync: config, endpoint collection, and the
+          # HTTP client stack. The API is an unreachable port, so a healthy
+          # CLI exits 2 with its network-failure message; a dependency
+          # breakage surfaces as a crash (exit 1 / traceback) and fails here.
+          export HOME=/tmp/smoke-home
+          mkdir -p "$HOME"
+          OPENACA_REMOTE_TOKEN=ot_SMOKE "$openaca" remote configure --api-url http://127.0.0.1:9
+          set +e
+          out=$("$openaca" remote sync endpoint 2>&1)
+          code=$?
+          set -e
+          printf '%s\n' "$out"
+          if [ "$code" -ne 2 ]; then
+            echo "expected exit 2 (clean network failure), got $code" >&2
+            exit 1
+          fi
+          if printf '%s' "$out" | grep -q "Traceback"; then
+            echo "remote sync crashed instead of failing cleanly" >&2
+            exit 1
+          fi
+          echo "smoke ok: CLI surfaces work against freshly-resolved deps"