action.yml

name: 'CodeBoarding Action'
description: 'Visual system-design review on PRs: a Mermaid diagram of added, modified, and deleted components on every pull request.'
author: 'CodeBoarding'

branding:
  icon: 'git-pull-request'
  color: 'blue'

inputs:
  llm_api_key:
    description: 'Your LLM provider API key (see llm_provider). Required.'
    required: true
  llm_provider:
    description: 'Provider for llm_api_key. The key is handed to the engine as that provider''s env var (anthropic -> ANTHROPIC_API_KEY, openai -> OPENAI_API_KEY, ...; aws_bedrock -> AWS_BEARER_TOKEN_BEDROCK, ollama -> OLLAMA_BASE_URL) and the engine auto-selects it. Default openrouter.'
    required: false
    default: 'openrouter'
  github_token:
    description: 'GITHUB_TOKEN used to post the PR comment. Defaults to the workflow token.'
    required: false
    default: ${{ github.token }}
  push_token:
    description: 'Token used to push the generated .codeboarding/analysis.json to the PR branch (for the webview link). 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.'
    required: false
    default: 'v0.12.0'
  depth_level:
    description: 'Diagram depth (1-3). Higher is slower and more detailed.'
    required: false
    default: '1'
  agent_model:
    description: 'Analysis model (AGENT_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3-flash-preview on OpenRouter; for other providers, empty uses the engine''s per-provider default.'
    required: false
    default: ''
  parsing_model:
    description: 'Parsing model (PARSING_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3.1-flash-lite-preview on OpenRouter; for other providers, empty uses the engine''s per-provider default.'
    required: false
    default: ''
  comment_header:
    description: 'Header line used inside the sticky PR comment.'
    required: false
    default: 'Architecture review'
  diagram_direction:
    description: 'Mermaid layout direction: LR, TD, TB, RL, or BT.'
    required: false
    default: 'LR'
  changed_only:
    description: 'Render only changed components and their incident edges (also auto-applied when the full graph exceeds GitHub''s Mermaid limit).'
    required: false
    default: 'false'
  render_depth:
    description: 'Component levels to DRAW in the PR Mermaid (independent of depth_level): 1 = top-level flat (default), 2 = +one nesting level as subgraphs, etc. Lets you analyze deep (depth_level=2) but display a clean level-1 diagram.'
    required: false
    default: '1'
  cta_base_url:
    description: 'Base URL of the click proxy (e.g. https://go.codeboarding.org). When set, the editor link deep-links into VS Code/Cursor via the proxy and a "get the extension" link is added (owner/repo/pr tracked). Empty (default) links to the extension listing instead, since GitHub strips vscode:/cursor: schemes from comment links.'
    required: false
    default: ''
  webview_base_url:
    description: 'Base URL of the hosted webview (default https://app.codeboarding.org). The PR comment adds an "explore in browser" link deep-linking to this PR''s head-vs-base architecture diff. Requires the head analysis.json to be committed to the PR branch (commit_head_analysis), so it is omitted on fork PRs. Set empty to disable the webview link.'
    required: false
    default: 'https://app.codeboarding.org'
  commit_head_analysis:
    description: 'Commit the generated head .codeboarding/analysis.json (+ health report) back to the PR branch so the webview can fetch it at the head SHA. Same-repo PRs only (the token is read-only on forks). Required for the webview "explore in browser" link.'
    required: false
    default: 'true'
  trigger_command:
    description: 'Slash-command that triggers the action from a PR comment (issue_comment event). A comment whose first word is this runs the diagram on-demand.'
    required: false
    default: '/codeboarding'

outputs:
  diagram_md:
    description: 'Path to the rendered ```mermaid block (in the runner workspace).'
    value: ${{ steps.diagram.outputs.diagram_md }}
  n_changed:
    description: 'Number of components added/modified/deleted, counted recursively.'
    value: ${{ steps.diagram.outputs.n_changed }}
  truncated:
    description: 'True if the diagram was reduced to changed-only to fit GitHub''s Mermaid limit.'
    value: ${{ steps.diagram.outputs.truncated }}

runs:
  using: 'composite'
  steps:
    - name: Guard — resolve the target PR
      id: guard
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github_token }}
        # Read from env, NEVER interpolated into the script — a comment body is
        # untrusted input and must not reach the shell as code (injection).
        COMMENT_BODY: ${{ github.event.comment.body }}
        AUTHOR_ASSOC: ${{ github.event.comment.author_association }}
        TRIGGER: ${{ inputs.trigger_command }}
        EVENT: ${{ github.event_name }}
        REPOSITORY: ${{ github.repository }}
        PR_NUMBER_PULL: ${{ github.event.pull_request.number }}
        PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        PULL_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        PULL_HEAD_REF: ${{ github.event.pull_request.head.ref }}
        PULL_BASE_REF: ${{ github.event.pull_request.base.ref }}
        PULL_BASE_REPO: ${{ github.event.pull_request.base.repo.full_name }}
        PULL_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
        ISSUE_NUMBER: ${{ github.event.issue.number }}
        ISSUE_PR_URL: ${{ github.event.issue.pull_request.url }}
      run: |
        set -uo pipefail
        skip() { echo "::notice::$1 Skipping."; echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0; }

        # Sticky-comment targeting. Written up front so the failure-comment step
        # always has a header even if PR resolution below fails. Automatic
        # pull_request runs reuse one stable header → the comment is updated in
        # place. An on-demand /codeboarding run uses a run-unique header so it
        # posts a NEW comment and never touches comments from earlier runs; its
        # own in-progress→result→failure steps still share it (one comment per
        # invocation). Re-running the same run keeps the same run id, so a re-run
        # updates that invocation's comment rather than spawning another.
        if [ "$EVENT" = "issue_comment" ]; then
          echo "sticky_header=codeboarding-architecture-diff-run-${GITHUB_RUN_ID}" >> "$GITHUB_OUTPUT"
        else
          echo "sticky_header=codeboarding-architecture-diff" >> "$GITHUB_OUTPUT"
        fi

        if [ "$EVENT" = "pull_request" ]; then
          PR_NUMBER="$PR_NUMBER_PULL"
          BASE_SHA="$PULL_BASE_SHA"
          HEAD_SHA="$PULL_HEAD_SHA"
          HEAD_REF="$PULL_HEAD_REF"
          BASE_REF="$PULL_BASE_REF"
          BASE_REPO="$PULL_BASE_REPO"
          HEAD_REPO="$PULL_HEAD_REPO"
        elif [ "$EVENT" = "pull_request_target" ]; then
          skip "pull_request_target is not supported because it can expose secrets to PR-head code; use pull_request or trusted issue_comment."
        elif [ "$EVENT" = "issue_comment" ]; then
          # On-demand "/codeboarding" command. Must be a PR comment whose first
          # word is the trigger; the payload lacks SHAs so we query the API.
          [ -n "$ISSUE_PR_URL" ] || skip "Comment is on a plain issue, not a PR."
          FIRST_WORD="$(printf '%s' "$COMMENT_BODY" | tr -d '\r' | awk 'NR==1{print $1; exit}')"
          [ "$FIRST_WORD" = "$TRIGGER" ] || skip "Comment does not start with '$TRIGGER'."
          # SECURITY (pwn-request guard): issue_comment runs in the base repo WITH
          # secrets for ANY commenter. Only a trusted collaborator may trigger an
          # analysis that checks out + runs over PR-head code with the LLM key present.
          case "$AUTHOR_ASSOC" in
            OWNER|MEMBER|COLLABORATOR) : ;;
            *) skip "Commenter is '$AUTHOR_ASSOC' (not OWNER/MEMBER/COLLABORATOR)." ;;
          esac
          PR_NUMBER="$ISSUE_NUMBER"
          PR_JSON="$(gh api "repos/${REPOSITORY}/pulls/${PR_NUMBER}" 2>/dev/null)" || skip "Could not fetch PR #$PR_NUMBER from the API."
          BASE_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["sha"])' 2>/dev/null)" || skip "Could not parse base SHA from the PR API."
          HEAD_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["sha"])' 2>/dev/null)" || skip "Could not parse head SHA from the PR API."
          HEAD_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["ref"])' 2>/dev/null)" || HEAD_REF=""
          BASE_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["ref"])' 2>/dev/null)" || BASE_REF=""
          BASE_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse base repo from the PR API."
          HEAD_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse head repo from the PR API."
          [ "$HEAD_REPO" = "$REPOSITORY" ] || skip "On-demand runs with secrets are disabled for fork PRs."
        else
          skip "Unsupported event '$EVENT' (use pull_request or issue_comment)."
        fi

        { [ -n "$PR_NUMBER" ] && [ -n "$BASE_SHA" ] && [ -n "$HEAD_SHA" ] && [ -n "$BASE_REPO" ] && [ -n "$HEAD_REPO" ]; } || skip "Could not resolve PR/base/head SHAs/repos."
        {
          echo "skip=false"
          echo "pr_number=$PR_NUMBER"
          echo "base_sha=$BASE_SHA"
          echo "head_sha=$HEAD_SHA"
          echo "head_ref=$HEAD_REF"
          echo "base_ref=$BASE_REF"
          echo "base_repo=$BASE_REPO"
          echo "head_repo=$HEAD_REPO"
          # same_repo gates pushing the head analysis: forks give a read-only token.
          if [ "$HEAD_REPO" = "$REPOSITORY" ]; then echo "same_repo=true"; else echo "same_repo=false"; fi
        } >> "$GITHUB_OUTPUT"
        echo "Resolved PR #$PR_NUMBER (base=$BASE_REPO@$BASE_SHA head=$HEAD_REPO@$HEAD_SHA) via $EVENT"

    - name: Acknowledge command
      if: steps.guard.outputs.skip != 'true' && github.event_name == 'issue_comment'
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github_token }}
        REPOSITORY: ${{ github.repository }}
        COMMENT_ID: ${{ github.event.comment.id }}
      run: |
        # 👀 react to the triggering comment so the user knows it was picked up.
        gh api -X POST "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}/reactions" \
          -f content=eyes >/dev/null 2>&1 || true

    - name: Post in-progress comment
      if: steps.guard.outputs.skip != 'true'
      continue-on-error: true
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        message: |
          ### ${{ inputs.comment_header }} · analyzing…

          ⏳ CodeBoarding is analyzing the architecture changes in this PR. This usually takes a few minutes.

          <sub>codeboarding-action · run ${{ github.run_id }}</sub>
        GITHUB_TOKEN: ${{ inputs.github_token }}

    - 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

    - name: Checkout target repository (PR head)
      if: steps.guard.outputs.skip != 'true'
      uses: actions/checkout@v4
      with:
        repository: ${{ steps.guard.outputs.head_repo }}
        path: target-repo
        fetch-depth: 0
        ref: ${{ steps.guard.outputs.head_sha }}
        persist-credentials: false

    - name: Ensure PR base commit is fetched
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      working-directory: target-repo
      env:
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        BASE_REPO: ${{ steps.guard.outputs.base_repo }}
      run: |
        git fetch origin "$BASE_SHA" --depth=1 || true
        if ! git cat-file -e "$BASE_SHA" 2>/dev/null; then
          git remote add base "https://github.com/${BASE_REPO}.git" 2>/dev/null || git remote set-url base "https://github.com/${BASE_REPO}.git"
          git fetch base "$BASE_SHA" --depth=1 || true
        fi
        git cat-file -e "$BASE_SHA" && echo "Base commit reachable." || \
          (echo "::error::Base commit $BASE_SHA is not reachable." && exit 1)

    - name: Set up Python 3.13
      if: steps.guard.outputs.skip != 'true'
      uses: actions/setup-python@v5
      with:
        python-version: '3.13'

    - name: Set up Node.js 20
      if: steps.guard.outputs.skip != 'true'
      uses: actions/setup-node@v4
      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
        restore-keys: |
          cb-lsp-${{ runner.os }}-

    - name: Install Python dependencies
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      working-directory: codeboarding-engine
      run: |
        test -d .venv || uv venv   # reuse the cached venv instead of wiping it (--clear defeated the cache)
        uv pip install -e .

    - 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

    - name: Prepare & verify LLM key
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      env:
        RAW_KEY: ${{ inputs.llm_api_key }}
        RAW_PROVIDER: ${{ inputs.llm_provider }}
        RAW_AGENT_MODEL: ${{ inputs.agent_model }}
        RAW_PARSING_MODEL: ${{ inputs.parsing_model }}
      run: |
        AUTH_FILE="${RUNNER_TEMP}/openrouter-auth.json"
        trap 'rm -f "$AUTH_FILE"' EXIT
        if [ -z "$RAW_KEY" ]; then
          echo "::error::llm_api_key is empty. On fork PRs, repo secrets are withheld by GitHub."
          exit 1
        fi
        # Resolve the provider -> the env var the engine reads. Convention is
        # <NAME>_API_KEY; two providers don't follow it. The engine is the source
        # of truth: an unknown provider just yields an env var it won't recognize,
        # and the engine errors with the list of valid keys.
        PROVIDER="$(printf '%s' "$RAW_PROVIDER" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_')"
        PROVIDER="${PROVIDER:-openrouter}"
        case "$PROVIDER" in
          aws_bedrock) PROVIDER_ENV="AWS_BEARER_TOKEN_BEDROCK" ;;
          ollama)      PROVIDER_ENV="OLLAMA_BASE_URL" ;;
          *)           PROVIDER_ENV="$(printf '%s' "$PROVIDER" | tr '[:lower:]' '[:upper:]')_API_KEY" ;;
        esac

        # Normalize a pasted key: strip whitespace/quotes and a leading `<ENV>=`.
        _strip() { printf '%s' "$1" | tr -d '[:space:]' | sed -e 's/^"//;s/"$//' -e "s/^'//;s/'\$//"; }
        KEY="$(_strip "$RAW_KEY")"
        case "$KEY" in "${PROVIDER_ENV}="*) KEY="${KEY#${PROVIDER_ENV}=}";; esac
        KEY="$(_strip "$KEY")"
        AGENT_MODEL="$(_strip "$RAW_AGENT_MODEL")"
        PARSING_MODEL="$(_strip "$RAW_PARSING_MODEL")"
        echo "::add-mask::$KEY"
        echo "Provider: $PROVIDER -> $PROVIDER_ENV; key length: ${#KEY}"

        if [ "$PROVIDER" = "openrouter" ]; then
          # Default models on OpenRouter when the user didn't pin one (cheap Gemini).
          # Other providers fall through to the engine's own per-provider default.
          AGENT_MODEL="${AGENT_MODEL:-google/gemini-3-flash-preview}"
          PARSING_MODEL="${PARSING_MODEL:-google/gemini-3.1-flash-lite-preview}"
          # OpenRouter-only checks. The litellm 'openrouter/...' model prefix 400s
          # the engine's native OpenRouter call; other providers use native ids.
          for M in "$AGENT_MODEL" "$PARSING_MODEL"; do
            case "$M" in
              openrouter/*)
                echo "::error::Invalid model '$M': drop the 'openrouter/' prefix and use a bare OpenRouter slug, e.g. anthropic/claude-sonnet-4."
                exit 1 ;;
            esac
          done
          # Cheap preflight; other providers are validated by the engine at run time.
          STATUS=$(curl -sS -o "$AUTH_FILE" -w "%{http_code}" \
            -H "Authorization: Bearer $KEY" --max-time 10 \
            https://openrouter.ai/api/v1/auth/key || echo "curl-fail")
          echo "OpenRouter /auth/key response: HTTP $STATUS"
          if [ "$STATUS" != "200" ]; then
            # Surface the upstream error MESSAGE only — never the whole auth body (avoid leaking).
            MSG="$(AUTH_FILE="$AUTH_FILE" python3 -c 'import json,os;print(json.load(open(os.environ["AUTH_FILE"])).get("error",{}).get("message",""))' 2>/dev/null || true)"
            echo "::error::OpenRouter rejected the API key (HTTP $STATUS). ${MSG:-Verify the OPENROUTER_API_KEY secret.}"
            exit 1
          fi
        fi

        # Store key material in runner-temp files. Later shell steps read these
        # explicitly; third-party post-comment actions do not inherit the LLM key.
        umask 077
        printf '%s' "$KEY" > "${RUNNER_TEMP}/cb-llm-key"
        printf '%s' "$PROVIDER_ENV" > "${RUNNER_TEMP}/cb-provider-env"
        printf '%s' "$AGENT_MODEL" > "${RUNNER_TEMP}/cb-agent-model"
        printf '%s' "$PARSING_MODEL" > "${RUNNER_TEMP}/cb-parsing-model"

    - name: Resolve base analysis (committed baseline)
      if: steps.guard.outputs.skip != 'true'
      id: base
      shell: bash
      working-directory: target-repo
      env:
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        ACTION_PATH: ${{ github.action_path }}
      run: |
        BASE_DIR="${RUNNER_TEMP}/cb-base"
        HEAD_DIR="${RUNNER_TEMP}/cb-head"
        mkdir -p "$BASE_DIR" "$HEAD_DIR"
        echo "base_dir=$BASE_DIR" >> $GITHUB_OUTPUT
        echo "head_dir=$HEAD_DIR" >> $GITHUB_OUTPUT
        if git show "${BASE_SHA}:.codeboarding/analysis.json" > "${BASE_DIR}/analysis.json" 2>/dev/null; then
          if python3 "$ACTION_PATH/scripts/cb_engine.py" validate-base \
              --analysis "${BASE_DIR}/analysis.json" \
              --expected-sha "$BASE_SHA"; then
            echo "committed=true" >> $GITHUB_OUTPUT
            echo "Using committed .codeboarding/analysis.json at ${BASE_SHA}."
          else
            rm -f "${BASE_DIR}/analysis.json"
            echo "committed=false" >> $GITHUB_OUTPUT
            echo "Committed baseline at ${BASE_SHA} is stale; will generate a fresh base analysis."
          fi
        else
          rm -f "${BASE_DIR}/analysis.json"
          echo "committed=false" >> $GITHUB_OUTPUT
          echo "No committed baseline at ${BASE_SHA}; will generate one via a full analysis on the base commit."
        fi

    - name: Restore base artifacts (keyed by base SHA)
      if: steps.guard.outputs.skip != 'true'
      id: basecache
      uses: actions/cache/restore@v4
      with:
        path: ${{ runner.temp }}/cb-base
        key: cb-base-v2-${{ runner.os }}-${{ steps.guard.outputs.base_sha }}-d${{ inputs.depth_level }}-${{ inputs.engine_ref }}-${{ 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
    # with its cluster baseline — which git can't provide (the pkl is never
    # committed, by design). Build it here deterministically: LSP + Leiden
    # clustering, no LLM key read. Fail-open: a failed seed degrades to exactly
    # the previous behavior (the head run falls back to a full analysis).
    - name: Seed base static-analysis cache (committed baseline, no cached pkl)
      if: steps.guard.outputs.skip != 'true' && steps.base.outputs.committed == 'true' && steps.basecache.outputs.cache-hit != 'true'
      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 }}
        TARGET: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
      run: |
        # Clean up any stale registration before re-adding (rm -rf alone leaves a
        # dangling worktree entry that makes a retry's `worktree add` fail).
        BASE_SRC="${RUNNER_TEMP}/base-src"
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        git -C "$TARGET" worktree prune
        rm -rf "$BASE_SRC"
        git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASE_SHA"
        if uv run python "$ACTION_PATH/scripts/cb_engine.py" seed \
             --repo "$BASE_SRC" \
             --out "$BASE_DIR" \
             --source-sha "$BASE_SHA" \
           && [ -f "$BASE_DIR/static_analysis.pkl" ] && [ -f "$BASE_DIR/static_analysis.sha" ]; then
          echo "seed_ok=true" >> "$GITHUB_OUTPUT"
          echo "::notice::Seeded base static-analysis cache for ${BASE_SHA}; head analysis can run incrementally."
        else
          # Never leave a partial pkl/sha pair behind: the save step below would
          # cache it under this base SHA's key and suppress every retry.
          rm -f "$BASE_DIR/static_analysis.pkl" "$BASE_DIR/static_analysis.sha"
          echo "seed_ok=false" >> "$GITHUB_OUTPUT"
          echo "::warning::Base static-analysis seeding failed; head analysis will fall back to a full run."
        fi
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true

    - name: Generate base analysis (no committed baseline)
      if: steps.guard.outputs.skip != 'true' && 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: ${{ inputs.depth_level }}
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_BASE: ${{ github.run_id }}-${{ github.run_attempt }}-base
        DEPTH: ${{ inputs.depth_level }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
      run: |
        # Export the key under the selected provider's env var (only this one),
        # so the engine auto-selects that provider.
        PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
        export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
        # Export the model env only when the user set it; empty -> the engine uses
        # its own valid per-provider default (no stale hardcoded model id to rot).
        AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
        PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
        if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
        if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi

        BASE_SRC="${RUNNER_TEMP}/base-src"
        # Clean up any stale registration before re-adding (rm -rf alone leaves a
        # dangling worktree entry that makes a retry's `worktree add` fail).
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        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/cb_engine.py" base \
          --repo "$BASE_SRC" \
          --out "$BASE_DIR" \
          --name "$REPO_NAME" \
          --run-id "$RUN_ID_BASE" \
          --depth "$DEPTH" \
          --source-sha "$BASE_SHA"
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        if [ ! -f "$BASE_DIR/analysis.json" ]; then
          echo "::error::Base full analysis ran but analysis.json is missing."
          exit 1
        fi

    # Covers both base-artifact producers: the full analysis (no committed
    # baseline) and the seeded pkl (committed baseline). The seed_ok gate is
    # load-bearing — caching a pkl-less dir under this base SHA's key would
    # permanently suppress seeding retries for it.
    - name: Save generated base artifacts
      if: steps.guard.outputs.skip != 'true' && steps.basecache.outputs.cache-hit != 'true' && (steps.base.outputs.committed == 'false' || steps.seedbase.outputs.seed_ok == 'true')
      uses: actions/cache/save@v4
      with:
        path: ${{ runner.temp }}/cb-base
        key: cb-base-v2-${{ runner.os }}-${{ steps.guard.outputs.base_sha }}-d${{ inputs.depth_level }}-${{ inputs.engine_ref }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}

    - name: Analyze PR head (incremental from base)
      if: steps.guard.outputs.skip != 'true'
      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: ${{ inputs.depth_level }}
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        HEAD_DIR: ${{ steps.base.outputs.head_dir }}
        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_HEAD: ${{ github.run_id }}-${{ github.run_attempt }}-head
        DEPTH: ${{ inputs.depth_level }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
      run: |
        # Export the key under the selected provider's env var (only this one),
        # so the engine auto-selects that provider.
        PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
        export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
        # Export the model env only when the user set it; empty -> the engine uses
        # its own valid per-provider default (no stale hardcoded model id to rot).
        AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
        PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
        if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
        if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi

        # Seed the head dir from the base analysis so incremental stitches
        # component ids from the baseline (stable diff). Base dir is left
        # 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/cb_engine.py" head \
          --repo "$TARGET_REPO" \
          --out "$HEAD_DIR" \
          --name "$REPO_NAME" \
          --run-id "$RUN_ID_HEAD" \
          --depth "$DEPTH" \
          --base-ref "$BASE_SHA" \
          --target-ref "$HEAD_SHA" \
          --source-sha "$HEAD_SHA"
        if [ ! -f "$HEAD_DIR/analysis.json" ]; then
          echo "::error::Head analysis ran but analysis.json is missing."
          exit 1
        fi
        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'
      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
        # cb_engine writes the WARNING/CRITICAL count (0 on any failure — best-effort).
        uv run python "$ACTION_PATH/scripts/cb_engine.py" health \
          --artifact-dir "$ARTIFACT_DIR" \
          --repo "$TARGET_REPO" \
          --name "$REPO_NAME" \
          --issues-out /tmp/cb-issues.txt || true
        N=$(cat /tmp/cb-issues.txt 2>/dev/null || echo 0)
        echo "issues=$N" >> $GITHUB_OUTPUT
        echo "Architecture issues: $N"

    - name: Drop LLM key material
      if: always() && steps.guard.outputs.skip != 'true'
      shell: bash
      run: |
        rm -f "${RUNNER_TEMP}/cb-llm-key" \
              "${RUNNER_TEMP}/cb-provider-env" \
              "${RUNNER_TEMP}/cb-agent-model" \
              "${RUNNER_TEMP}/cb-parsing-model"

    # Commit the generated head analysis (+ health report) to the PR branch so the
    # hosted webview can fetch .codeboarding/analysis.json at the head SHA and open
    # this PR's head-vs-base diff. Same-repo PRs only — the token is read-only on
    # forks (the step is skipped there and the webview link is omitted). The push
    # creates a NEW head commit; its SHA (webview_sha) is what the comment links to.
    - name: Commit head analysis to PR branch
      id: commit_head
      if: >-
        steps.guard.outputs.skip != 'true'
        && inputs.commit_head_analysis == 'true'
        && steps.guard.outputs.same_repo == 'true'
        && inputs.webview_base_url != ''
      shell: bash
      working-directory: target-repo
      env:
        # Push with push_token (defaults to the workflow github.token, gated by the
        # consumer's `permissions: contents: write`) — NOT github_token, which may be
        # a GitHub App token used only for commenting and need not have write access.
        GH_TOKEN: ${{ inputs.push_token }}
        HEAD_DIR: ${{ steps.base.outputs.head_dir }}
        HEAD_REF: ${{ steps.guard.outputs.head_ref }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
        REPOSITORY: ${{ github.repository }}
        SERVER_URL: ${{ github.server_url }}
      run: |
        echo "ready=false" >> "$GITHUB_OUTPUT"
        echo "webview_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
        [ -n "$HEAD_REF" ] || { echo "::notice::No head branch ref resolved; skipping head-analysis commit."; exit 0; }
        [ -f "$HEAD_DIR/analysis.json" ] || { echo "::notice::No head analysis.json to commit."; exit 0; }

        mkdir -p .codeboarding/health
        cp "$HEAD_DIR/analysis.json" .codeboarding/analysis.json
        if [ -f "$HEAD_DIR/health/health_report.json" ]; then
          cp "$HEAD_DIR/health/health_report.json" .codeboarding/health/health_report.json
        fi

        git add .codeboarding/analysis.json .codeboarding/health/health_report.json 2>/dev/null || git add .codeboarding/analysis.json
        if git diff --cached --quiet; then
          echo "::notice::Head analysis unchanged; nothing to commit."
          echo "ready=true" >> "$GITHUB_OUTPUT"   # already committed at this SHA → webview can read it
          exit 0
        fi

        git config user.name "codeboarding[bot]"
        git config user.email "codeboarding[bot]@users.noreply.github.com"
        git commit -m "chore(codeboarding): update architecture analysis [skip ci]" >/dev/null

        # Push to the PR head branch. The checkout used persist-credentials:false, so
        # authenticate the push explicitly with the workflow token (same-repo only).
        # Requires `contents: write` on the job's token — a read-only token (the
        # default) is rejected here; the push error below names the cause.
        AUTH_URL="https://x-access-token:${GH_TOKEN}@${SERVER_URL#https://}/${REPOSITORY}.git"
        if git push "$AUTH_URL" "HEAD:refs/heads/${HEAD_REF}"; then
          NEW_SHA="$(git rev-parse HEAD)"
          echo "webview_sha=$NEW_SHA" >> "$GITHUB_OUTPUT"
          echo "ready=true" >> "$GITHUB_OUTPUT"
          echo "Committed head analysis to ${HEAD_REF} as ${NEW_SHA}."
        else
          echo "::warning::Could not push head analysis to ${HEAD_REF}; the webview link will be omitted. Most likely the job's token lacks 'contents: write' (add 'permissions: contents: write' to the calling workflow), or the branch is protected against this pusher."
        fi

    - name: Diff analyses → Mermaid
      if: steps.guard.outputs.skip != 'true'
      id: diagram
      shell: bash
      env:
        ACTION_PATH: ${{ github.action_path }}
        BASE_ANALYSIS: ${{ steps.analyze.outputs.base_analysis }}
        HEAD_ANALYSIS: ${{ steps.analyze.outputs.head_analysis }}
        DIRECTION: ${{ inputs.diagram_direction }}
        RENDER_DEPTH: ${{ inputs.render_depth }}
        CHANGED_ONLY: ${{ inputs.changed_only }}
      run: |
        case "$CHANGED_ONLY" in
          true|false) ;;
          *) echo "::error::changed_only must be 'true' or 'false'."; exit 1 ;;
        esac
        case "$RENDER_DEPTH" in
          ''|*[!0-9]*) echo "::error::render_depth must be a positive integer."; exit 1 ;;
        esac

        args=(
          --base "$BASE_ANALYSIS"
          --head "$HEAD_ANALYSIS"
          --out "${RUNNER_TEMP}/diagram.md"
          --direction "$DIRECTION"
          --render-depth "$RENDER_DEPTH"
        )
        [ "$CHANGED_ONLY" = "true" ] && args+=(--changed-only)
        META=$(python3 "$ACTION_PATH/scripts/diff_to_mermaid.py" "${args[@]}")
        echo "$META" > "${RUNNER_TEMP}/diagram_meta.json"
        echo "diff meta: $META"
        read N CHANGED RENDERED TRUNC < <(python3 -c "import json;d=json.load(open('${RUNNER_TEMP}/diagram_meta.json'));print(d['n_changed'], str(d.get('changed', d['n_changed']>0)).lower(), str(d['rendered']).lower(), str(d['truncated']).lower())")
        echo "n_changed=$N" >> $GITHUB_OUTPUT
        echo "changed=$CHANGED" >> $GITHUB_OUTPUT
        echo "rendered=$RENDERED" >> $GITHUB_OUTPUT
        echo "truncated=$TRUNC" >> $GITHUB_OUTPUT
        echo "diagram_md=${RUNNER_TEMP}/diagram.md" >> $GITHUB_OUTPUT

    - name: Build PR comment body
      if: steps.guard.outputs.skip != 'true'
      id: body
      shell: bash
      env:
        # Pass event/input-derived strings as DATA (not interpolated into the script).
        HEADER: ${{ inputs.comment_header }}
        BASE_REF: ${{ steps.guard.outputs.base_ref }}
        CTA_BASE: ${{ inputs.cta_base_url }}
        OWNER_REPO: ${{ github.repository }}
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        DIAGRAM_MD: ${{ steps.diagram.outputs.diagram_md }}
        BASE_ANALYSIS: ${{ steps.analyze.outputs.base_analysis }}
        HEAD_ANALYSIS: ${{ steps.analyze.outputs.head_analysis }}
        RUN_ID: ${{ github.run_id }}
        N: ${{ steps.diagram.outputs.n_changed }}
        CHANGED: ${{ steps.diagram.outputs.changed }}
        RENDERED: ${{ steps.diagram.outputs.rendered }}
        TRUNC: ${{ steps.diagram.outputs.truncated }}
        PR: ${{ steps.guard.outputs.pr_number }}
        ISSUES: ${{ steps.health.outputs.issues }}
        WEBVIEW_BASE: ${{ inputs.webview_base_url }}
        # SHA the head analysis.json was committed at (post-push), and whether that
        # commit succeeded — gates the webview "explore in browser" link.
        WEBVIEW_SHA: ${{ steps.commit_head.outputs.webview_sha }}
        WEBVIEW_READY: ${{ steps.commit_head.outputs.ready }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
      run: |
        BODY_FILE=$(mktemp)
        OWNER="${OWNER_REPO%%/*}"; REPO="${OWNER_REPO##*/}"

        headline() {
          if [ "$CHANGED" != "true" ]; then echo "no architectural changes";
          elif [ "$N" = "1" ]; then echo "1 component changed";
          elif [ "$N" = "0" ]; then echo "architecture updated";
          else echo "$N components changed"; fi
        }

        # CTA footer: an editor link (proxy deep-link when CTA_BASE is set, else the
        # extension's https listing — GitHub strips vscode:/cursor:), the ⚠️ banner,
        # and — when the head analysis was committed (WEBVIEW_READY) — a webview
        # "explore in browser" link to this PR's head-vs-base diff.
        cta() {
          local extra=()
          if [ "$WEBVIEW_READY" = "true" ]; then
            extra+=(--webview-ready --webview-base "$WEBVIEW_BASE" --head-sha "$WEBVIEW_SHA" --base-sha "$BASE_SHA")
          fi
          python3 "$ACTION_PATH/scripts/build_cta.py" \
            --cta-base "$CTA_BASE" --owner "$OWNER" --repo "$REPO" --pr "$PR" \
            --repo-path "$TARGET_REPO" --issues "${ISSUES:-0}" "${extra[@]}"
        }

        # Per-component changed-file dropdowns: which files made each node change
        # color. The git listing is the PR's own changes (three-dot merge-base..head,
        # the same set as the Files-changed tab; --no-renames so a moved file's old
        # path still appears for the donor component). Node colors compare against
        # the base *tip*, so a node colored only by base-branch churn on a stale PR
        # gets no dropdown. Best-effort: if the git diff fails (e.g. merge-base
        # unreachable on a shallow fork fetch) the script falls back to
        # analysis-derived changes, and if the script fails the section is omitted —
        # the comment always posts.
        FILES_MD="${RUNNER_TEMP}/component_files.md"
        : > "$FILES_MD"
        if [ -n "$BASE_ANALYSIS" ] && [ -n "$HEAD_ANALYSIS" ]; then
          CHANGED_LIST="${RUNNER_TEMP}/changed_files.txt"
          files_args=(--base "$BASE_ANALYSIS" --head "$HEAD_ANALYSIS" --out "$FILES_MD")
          if git -C "$TARGET_REPO" -c core.quotepath=off diff --no-renames --name-only "$BASE_SHA...HEAD" > "$CHANGED_LIST" 2>/dev/null; then
            files_args+=(--changed-files "$CHANGED_LIST")
          fi
          python3 "$ACTION_PATH/scripts/build_component_files.py" "${files_args[@]}" || : > "$FILES_MD"
        fi

        {
          echo "### ${HEADER} · $(headline)"
          echo ""
          if [ "$RENDERED" = "true" ]; then
            cat "$DIAGRAM_MD"
            echo ""
            echo ""
            echo "Colors indicate component changes compared to \`${BASE_REF}\`: 🟩 Added · 🟨 Modified · 🟥 Removed"
            if [ "$TRUNC" = "true" ]; then
              echo ""
              echo "<sub>Showing changed components only — the full graph exceeds GitHub's inline Mermaid limit.</sub>"
            fi
          elif [ "$CHANGED" = "true" ]; then
            echo "Architecture changed versus \`${BASE_REF}\`, but the diagram is too large to render inline (GitHub caps inline Mermaid at ~500 edges)."
          else
            echo "No architectural changes detected versus \`${BASE_REF}\`."
          fi
          if [ -s "$FILES_MD" ]; then
            echo ""
            cat "$FILES_MD"
          fi
          cta
          echo ""
          echo "<sub>codeboarding-action · run ${RUN_ID}</sub>"
        } > "$BODY_FILE"

        echo "body_file=$BODY_FILE" >> "$GITHUB_OUTPUT"

    - name: Post sticky PR comment
      if: steps.guard.outputs.skip != 'true'
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        path: ${{ steps.body.outputs.body_file }}
        GITHUB_TOKEN: ${{ inputs.github_token }}

    # If any analysis step failed, replace the sticky comment with a short failure
    # note (same header) instead of leaving the PR with nothing / a stale diagram.
    - name: Post failure comment
      if: failure() && steps.guard.outputs.skip != 'true'
      continue-on-error: true
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        message: |
          ### ${{ inputs.comment_header }} · failed

          The architecture diff couldn't be generated for this run. See the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.

          <sub>codeboarding-action · run ${{ github.run_id }}</sub>
        GITHUB_TOKEN: ${{ inputs.github_token }}