fix: install CodeBoarding engine from PyPI

Amp-Thread-ID: https://ampcode.com/threads/T-019edcb0-130a-713d-8e97-997ec5e29b33
Co-authored-by: Amp <amp@ampcode.com>

Author: ivanmilevtues

README.md

@@ -262,7 +262,7 @@ Review mode does not need `contents: write`: PR-specific generated files are sto
 | `mode` | both | `review` | `review` posts the PR architecture-diff comment; `sync` analyzes on push and commits the architecture (`analysis.json` + rendered docs) to `target_branch`, keeping it versioned and current. |
 | `github_token` | both | `${{ github.token }}` | Token for GitHub API calls; in review mode it posts or updates the PR comment. |
 | `push_token` | sync | `${{ github.token }}` | Token used for sync-mode pushes to `target_branch`. The workflow token can push when the workflow grants `permissions: contents: write`. Separate from `github_token` so commenting can use a GitHub App token while the push uses the workflow token. |
-| `engine_ref` | both | `v0.12.1` | CodeBoarding engine ref. Pin for reproducibility. |
+| `codeboarding_version` | both | `0.12.2` | CodeBoarding PyPI package version used as the analysis engine. Pin for reproducibility. |
 | `depth_level` | both | empty (`2` for cold starts) | Analysis depth, 1 to 3, used for first analysis and `force_full` rebuilds. Once `.codeboarding/analysis.json` exists, its `metadata.depth_level` is the source of truth for incremental analysis and fallback-full recovery. |
 | `render_depth` | review | `1` | Display depth for the PR diagram. Keep `1` for a clean top-level view. |
 | `diagram_direction` | review | `LR` | Mermaid direction: `LR`, `TD`, `TB`, `RL`, or `BT`. |
@@ -296,7 +296,7 @@ Outputs of the mode that did not run are empty strings.
 
 ## Notes
 
-- No checkout step is required in your workflow. This action checks out the target (the PR in review mode, the pushed commit in sync mode) and the CodeBoarding engine internally.
+- No checkout step is required in your workflow. This action checks out the target (the PR in review mode, the pushed commit in sync mode) and installs the CodeBoarding engine from PyPI internally.
 - GitHub withholds secrets from fork PRs on `pull_request`, so fork runs fail early if an LLM key is unavailable.
 - Do not use `pull_request_target` for this action. It can expose secrets to PR-head code.
 - GitHub renders Mermaid in strict mode, so node click-through links are not supported in the PR diagram.
@@ -313,8 +313,9 @@ Full local pipeline:
 
 ```bash
 export OPENROUTER_API_KEY=sk-or-...
-scripts/run_local.sh --repo /path/to/repo --base <base-ref> --head <head-ref> \
-  --engine /path/to/CodeBoarding
+python -m pip install codeboarding==0.12.2
+codeboarding-setup --auto-install-npm
+scripts/run_local.sh --repo /path/to/repo --base <base-ref> --head <head-ref>
 ```
 
 Useful flags:

action.yml

@@ -31,10 +31,10 @@ inputs:
     description: 'Token used for sync-mode git pushes to target_branch. Defaults to the workflow github.token, which can push when the calling workflow grants "permissions: contents: write". Kept separate from github_token so commenting can use a GitHub App token while the push uses the workflow token (whose write access the consumer controls).'
     required: false
     default: ${{ github.token }}
-  engine_ref:
-    description: 'Git ref (tag/branch/SHA) of CodeBoarding/CodeBoarding used as the analysis engine. Pinned to a release for reproducibility; override to track a newer ref.'
+  codeboarding_version:
+    description: 'CodeBoarding PyPI package version used as the analysis engine. Pin for reproducibility; set to a newer released version to opt into newer engine releases.'
     required: false
-    default: 'v0.12.1'
+    default: '0.12.2'
   depth_level:
     description: 'Analysis depth (1-3) for cold-start or force_full rebuilds. Once .codeboarding/analysis.json exists, its metadata.depth_level is the source of truth for incremental analysis and fallback-full recovery. Empty (default): 2 for cold starts.'
     required: false
@@ -142,7 +142,7 @@ runs:
   # interleave only because they share the LLM-key lifecycle, NOT because they
   # are unrelated:
   #   1. GUARD            — resolve mode + event eligibility + SHAs (one source of truth)
-  #   2. SHARED SETUP     — checkout engine + target, Python/Node/uv, caches, LLM-key prep
+  #   2. SHARED SETUP     — checkout target, Python/Node/uv, install CodeBoarding, caches, LLM-key prep
   #   3. ANALYSIS (key live) — review: base/seed/head/health ; sync: seed/analyze
   #   4. Drop LLM key, then OUTPUT (no key) — review: diff→artifact→comment ; sync: render→commit
   # The binding between the modes is the committed .codeboarding/analysis.json
@@ -397,15 +397,6 @@ runs:
           9.0.x
           10.0.x
 
-    - name: Checkout CodeBoarding engine
-      if: steps.guard.outputs.skip != 'true'
-      uses: actions/checkout@v4
-      with:
-        repository: CodeBoarding/CodeBoarding
-        ref: ${{ inputs.engine_ref }}
-        path: codeboarding-engine
-        persist-credentials: false
-
     # Review mode: the PR head repo at the head SHA. Sync mode: this repo at the
     # pushed/selected SHA. Always credential-free — sync pushes authenticate
     # explicitly via push_token.
@@ -474,54 +465,36 @@ runs:
       with:
         node-version: '20'
 
-    - name: Install uv
-      if: steps.guard.outputs.skip != 'true'
-      uses: astral-sh/setup-uv@v4
-      with:
-        enable-cache: true   # cache ~/.cache/uv (wheels/builds) for fast cold installs
-
-    - name: Cache uv venv (engine)
-      if: steps.guard.outputs.skip != 'true'
-      uses: actions/cache@v4
-      with:
-        path: codeboarding-engine/.venv
-        # No restore-keys: a lockfile change must force a clean cold venv, not
-        # restore a venv built from a different lock (`uv pip install -e .` won't
-        # downgrade/sync already-installed transitive deps back to this uv.lock).
-        key: cb-uv-${{ runner.os }}-${{ hashFiles('codeboarding-engine/pyproject.toml', 'codeboarding-engine/uv.lock') }}
-
     - name: Cache LSP servers
       if: steps.guard.outputs.skip != 'true'
       uses: actions/cache@v4
       with:
         path: |
-          codeboarding-engine/static_analyzer/servers/node_modules
-          codeboarding-engine/static_analyzer/servers/bin
-        key: cb-lsp-${{ runner.os }}-v1
+          ~/.codeboarding/servers
+        key: cb-lsp-${{ runner.os }}-${{ inputs.codeboarding_version }}-v1
         restore-keys: |
           cb-lsp-${{ runner.os }}-
 
-    - name: Install Python dependencies
+    - name: Install CodeBoarding package
       if: steps.guard.outputs.skip != 'true'
       shell: bash
-      working-directory: codeboarding-engine
+      env:
+        CODEBOARDING_VERSION: ${{ inputs.codeboarding_version }}
       run: |
-        # Reuse the cached venv when it's healthy, but rebuild it if its interpreter
-        # symlink is dead. The cache key is the lockfiles only, NOT the Python patch
-        # version, so when setup-python provisions a newer patch (e.g. 3.13.13 ->
-        # 3.13.14) and GitHub GCs the old toolcache dir, the cached `.venv/bin/python3`
-        # symlink dangles. A bare `test -d .venv` would then reuse it and `uv pip
-        # install -e .` fails with "Broken symlink … was the underlying Python
-        # interpreter removed?". Probing the interpreter recreates the venv instead.
-        .venv/bin/python -c '' 2>/dev/null || uv venv   # rebuild on missing/broken venv
-        uv pip install -e .
+        set -euo pipefail
+        SPEC="$CODEBOARDING_VERSION"
+        case "$SPEC" in
+          '' ) SPEC='' ;;
+          [0-9]* ) SPEC="==$SPEC" ;;
+        esac
+        python -m pip install --upgrade pip
+        python -m pip install "codeboarding${SPEC}"
 
     - name: Install LSP servers
       if: steps.guard.outputs.skip != 'true'
       shell: bash
-      working-directory: codeboarding-engine
       run: |
-        uv run python install.py --auto-install-npm
+        codeboarding-setup --auto-install-npm
 
     - name: Prepare & verify LLM key
       if: steps.guard.outputs.skip != 'true'
@@ -755,7 +728,7 @@ runs:
         # inputs. So a free-tier run (oidc, forced Gemini) and a BYO OpenRouter-key
         # run with no model pinned would share a key yet produce different base
         # analyses; the mode discriminator keeps them from reusing each other's cache.
-        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.engine_ref }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
+        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.codeboarding_version }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
 
     # A committed analysis.json gives the head analysis stable component ids,
     # but the engine's incremental path ALSO needs the base static_analysis.pkl
@@ -768,10 +741,7 @@ runs:
       id: seedbase
       continue-on-error: true
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         CACHING_DOCUMENTATION: 'false'
         ENABLE_MONITORING: 'false'
         ACTION_PATH: ${{ github.action_path }}
@@ -786,7 +756,7 @@ runs:
         git -C "$TARGET" worktree prune
         rm -rf "$BASE_SRC"
         git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASELINE_SHA"
-        if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
+        if python "$ACTION_PATH/scripts/engine_adapter.py" seed \
              --repo "$BASE_SRC" \
              --out "$BASE_DIR" \
              --source-sha "$BASELINE_SHA" \
@@ -805,10 +775,7 @@ runs:
     - name: Generate base analysis (no committed baseline)
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.base.outputs.committed == 'false' && steps.basecache.outputs.cache-hit != 'true'
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
         CACHING_DOCUMENTATION: 'false'
         ENABLE_MONITORING: 'false'
@@ -846,7 +813,7 @@ runs:
         git -C "$TARGET" worktree prune
         rm -rf "$BASE_SRC"
         git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASE_SHA"
-        uv run python "$ACTION_PATH/scripts/engine_adapter.py" base \
+        python "$ACTION_PATH/scripts/engine_adapter.py" base \
           --repo "$BASE_SRC" \
           --out "$BASE_DIR" \
           --name "$REPO_NAME" \
@@ -874,16 +841,13 @@ runs:
         # inputs. So a free-tier run (oidc, forced Gemini) and a BYO OpenRouter-key
         # run with no model pinned would share a key yet produce different base
         # analyses; the mode discriminator keeps them from reusing each other's cache.
-        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.engine_ref }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
+        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.codeboarding_version }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}
 
     - name: Analyze PR head (incremental from base)
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
       id: analyze
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
         CACHING_DOCUMENTATION: 'false'
         ENABLE_MONITORING: 'false'
@@ -921,7 +885,7 @@ runs:
         # untouched as the "before" snapshot for the diff.
         cp -a "$BASE_DIR"/. "$HEAD_DIR"/ 2>/dev/null || true
         rm -rf "$HEAD_DIR/health"
-        uv run python "$ACTION_PATH/scripts/engine_adapter.py" head \
+        python "$ACTION_PATH/scripts/engine_adapter.py" head \
           --repo "$TARGET_REPO" \
           --out "$HEAD_DIR" \
           --name "$REPO_NAME" \
@@ -934,26 +898,23 @@ runs:
           echo "::error::Head analysis ran but analysis.json is missing."
           exit 1
         fi
-        echo "base_analysis=$BASE_DIR/analysis.json" >> $GITHUB_OUTPUT
+        echo "base_analysis=$BASE_DIR/analysis.json" >> "$GITHUB_OUTPUT"
         echo "head_analysis=$HEAD_DIR/analysis.json" >> $GITHUB_OUTPUT
 
     - name: Architecture health check (best-effort)
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
       id: health
       continue-on-error: true
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         ACTION_PATH: ${{ github.action_path }}
         ARTIFACT_DIR: ${{ steps.base.outputs.head_dir }}
         TARGET_REPO: ${{ github.workspace }}/target-repo
         REPO_NAME: ${{ github.event.repository.name }}
       run: |
         rm -f /tmp/cb-issues.txt
         # engine_adapter writes the WARNING/CRITICAL count (0 on any failure — best-effort).
-        uv run python "$ACTION_PATH/scripts/engine_adapter.py" health \
+        python "$ACTION_PATH/scripts/engine_adapter.py" health \
           --artifact-dir "$ARTIFACT_DIR" \
           --repo "$TARGET_REPO" \
           --name "$REPO_NAME" \
@@ -1027,7 +988,7 @@ runs:
         path: |
           ${{ runner.temp }}/cb-sync/static_analysis.pkl
           ${{ runner.temp }}/cb-sync/static_analysis.sha
-        key: cb-sync-${{ runner.os }}-${{ inputs.engine_ref }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.sync_seed.outputs.baseline_sha }}
+        key: cb-sync-${{ runner.os }}-${{ inputs.codeboarding_version }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.sync_seed.outputs.baseline_sha }}
 
     # Same rationale as the review pipeline's seed step: the committed
     # analysis.json supplies component ids, but the incremental path also needs
@@ -1037,10 +998,7 @@ runs:
       id: sync_seedcache
       continue-on-error: true
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         # The seed subcommand defaults to github_action attribution; sync-mode
         # telemetry must report as sync (setdefault never clobbers this).
         CODEBOARDING_SOURCE: 'sync'
@@ -1065,7 +1023,7 @@ runs:
         git -C "$TARGET_REPO" worktree prune
         rm -rf "$BASE_SRC"
         git -C "$TARGET_REPO" worktree add --detach "$BASE_SRC" "$BASELINE_SHA"
-        if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
+        if python "$ACTION_PATH/scripts/engine_adapter.py" seed \
              --repo "$BASE_SRC" \
              --out "$ANALYSIS_DIR" \
              --source-sha "$BASELINE_SHA" \
@@ -1082,10 +1040,7 @@ runs:
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
       id: sync_analyze
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
         CACHING_DOCUMENTATION: 'false'
         ENABLE_MONITORING: 'false'
@@ -1128,7 +1083,7 @@ runs:
         )
         [ "$FORCE_FULL" = "true" ] && args+=(--force-full)
         LOG="${RUNNER_TEMP}/cb-sync-analyze.log"
-        uv run python "$ACTION_PATH/scripts/engine_adapter.py" analyze "${args[@]}" | tee "$LOG"
+        python "$ACTION_PATH/scripts/engine_adapter.py" analyze "${args[@]}" | tee "$LOG"
         MODE="$(sed -n 's/^analysis_mode=//p' "$LOG" | tail -1)"
         MODE="${MODE:-unknown}"
         echo "analysis_mode=$MODE" >> "$GITHUB_OUTPUT"
@@ -1359,9 +1314,7 @@ runs:
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
       id: sync_render
       shell: bash
-      working-directory: codeboarding-engine
       env:
-        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
         ACTION_PATH: ${{ github.action_path }}
         ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
         RENDER_DIR: ${{ steps.sync_seed.outputs.render_dir }}
@@ -1375,14 +1328,14 @@ runs:
       run: |
         set -euo pipefail
         REPO_REF="https://github.com/${REPOSITORY}/blob/${TARGET_BRANCH}/${OUTPUT_DIR}"
-        uv run python "$ACTION_PATH/scripts/engine_adapter.py" render \
+        python "$ACTION_PATH/scripts/engine_adapter.py" render \
           --analysis "$ANALYSIS_DIR/analysis.json" \
           --out "$RENDER_DIR" \
           --repo-name "$REPO_NAME" \
           --repo-ref "$REPO_REF" \
           --format "$OUTPUT_FORMAT"
         if [ "$WRITE_ARCHITECTURE_MD" = "true" ]; then
-          uv run python "$ACTION_PATH/scripts/engine_adapter.py" concat \
+          python "$ACTION_PATH/scripts/engine_adapter.py" concat \
             --docs-dir "$RENDER_DIR" \
             --out "$ARCHITECTURE_FILE"
         fi
@@ -1412,7 +1365,7 @@ runs:
         path: |
           ${{ runner.temp }}/cb-sync/static_analysis.pkl
           ${{ runner.temp }}/cb-sync/static_analysis.sha
-        key: cb-sync-${{ runner.os }}-${{ inputs.engine_ref }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.guard.outputs.target_sha }}
+        key: cb-sync-${{ runner.os }}-${{ inputs.codeboarding_version }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.guard.outputs.target_sha }}
 
     - name: Commit and push synced architecture
       if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'

scripts/engine_adapter.py

@@ -1,11 +1,11 @@
 """CLI adapter between the action and the CodeBoarding analysis ENGINE.
 
-No analysis logic lives here. The engine is the separate ``CodeBoarding/
-CodeBoarding`` repo, checked out at runtime into ``codeboarding-engine/`` and
-imported lazily inside each function (``codeboarding_workflows`` etc.); this
-module just turns the action's shell steps into typed, tested calls into it.
-The lazy imports mean this file imports fine without the engine venv present —
-the tests stub those modules and assert we call the engine with the right args.
+No analysis logic lives here. The engine is the published ``codeboarding`` PyPI
+package installed by the action and imported lazily inside each function
+(``codeboarding_workflows`` etc.); this module just turns the action's shell
+steps into typed, tested calls into it. The lazy imports mean this file imports
+fine without the package present — the tests stub those modules and assert we
+call the engine with the right args.
 
 Subcommands (all paths/refs come in as argv, never interpolated into source):