feat: /codeboarding comment command to trigger on-demand (issue_comment)

Guard now resolves the PR from either a pull_request event or an issue_comment
'/codeboarding' command (comment body read from env, never interpolated -> no
injection; SHAs fetched via gh api). Reacts 👀 to acknowledge. Configurable via
trigger_command. Sticky comment + base_ref now use the resolved PR explicitly.

Author: brovatten

README.md

@@ -25,14 +25,21 @@ name: Architecture diff
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
+  issue_comment:               # enables the /codeboarding command on PRs
+    types: [created]
 
 permissions:
-  pull-requests: write       # the only permission needed — nothing is pushed
+  pull-requests: write         # the only permission needed — nothing is pushed
 
 jobs:
   diagram:
     runs-on: ubuntu-latest
-    if: github.event.pull_request.draft == false
+    # Run on (non-draft) PR events, OR when someone comments "/codeboarding" on a PR.
+    # The if-gate is important: without it a runner spins up for every comment.
+    if: >
+      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request != null &&
+       startsWith(github.event.comment.body, '/codeboarding'))
     timeout-minutes: 60
     steps:
       - uses: codeboarding/codeboarding-action@v1
@@ -42,6 +49,12 @@ jobs:
 
 You need **one secret**: an LLM API key. OpenRouter is the default; pass your own model via the `agent_model` / `parsing_model` inputs if you prefer.
 
+### On-demand: the `/codeboarding` command
+
+Comment **`/codeboarding`** on any pull request to (re)run the diagram on demand — handy after the engine/baseline changes, or on draft PRs you don't auto-review. The action reacts with 👀 to acknowledge. Change the word via the `trigger_command` input.
+
+> **Note:** GitHub runs `issue_comment` workflows from the **default branch's** copy of the workflow file. So the command only works once this workflow is merged to your default branch — a workflow that exists only on a feature branch won't respond to comments.
+
 ## Inputs
 
 | Input | Default | Description |
@@ -57,6 +70,7 @@ You need **one secret**: an LLM API key. OpenRouter is the default; pass your ow
 | `changed_only` | `false` | Draw only changed components and their incident edges. |
 | `render_depth` | `1` | Component levels to **draw** in the PR diagram, independent of `depth_level`: `1` = top-level flat, `2` = +one nesting level as subgraphs. Analyze deep, display shallow. |
 | `cta_base_url` | `''` | Base URL of a click proxy. When set, the comment adds "explore in browser" / "open in VS Code or Cursor" / "get the extension" links (with `owner`/`repo`/`pr` appended). Empty disables the CTA. |
+| `trigger_command` | `/codeboarding` | PR-comment slash-command that triggers an on-demand run (requires the `issue_comment` trigger in your workflow). |
 
 ## Outputs
 

action.yml

@@ -50,6 +50,10 @@ inputs:
     description: 'Base URL of the click proxy (e.g. https://go.codeboarding.org). When set, the comment adds "open in workspace" / "get the extension" links with owner/repo/pr appended. Empty disables the CTA.'
     required: false
     default: ''
+  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:
@@ -65,20 +69,59 @@ outputs:
 runs:
   using: 'composite'
   steps:
-    - name: Guard — PR event only
+    - 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 }}
+        TRIGGER: ${{ inputs.trigger_command }}
+        EVENT: ${{ github.event_name }}
       run: |
-        if [ -z "${{ github.event.pull_request.number }}" ]; then
-          echo "::warning::CodeBoarding Architecture Diff only runs on pull_request events. Skipping."
-          echo "skip=true" >> $GITHUB_OUTPUT
+        skip() { echo "::notice::$1 Skipping."; echo "skip=true" >> $GITHUB_OUTPUT; exit 0; }
+
+        if [ "$EVENT" = "pull_request" ] || [ "$EVENT" = "pull_request_target" ]; then
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+          BASE_REF="${{ github.event.pull_request.base.ref }}"
+        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 "${{ github.event.issue.pull_request.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'."
+          PR_NUMBER="${{ github.event.issue.number }}"
+          PR_JSON="$(gh api "repos/${{ github.repository }}/pulls/${PR_NUMBER}")"
+          BASE_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["sha"])')"
+          HEAD_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["sha"])')"
+          BASE_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["ref"])')"
         else
-          echo "skip=false" >> $GITHUB_OUTPUT
-          echo "base_sha=${{ github.event.pull_request.base.sha }}" >> $GITHUB_OUTPUT
-          echo "head_sha=${{ github.event.pull_request.head.sha }}" >> $GITHUB_OUTPUT
-          echo "pr_number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+          skip "Unsupported event '$EVENT' (use pull_request or issue_comment)."
         fi
 
+        [ -n "$PR_NUMBER" ] || skip "No pull request in context."
+        {
+          echo "skip=false"
+          echo "pr_number=$PR_NUMBER"
+          echo "base_sha=$BASE_SHA"
+          echo "head_sha=$HEAD_SHA"
+          echo "base_ref=$BASE_REF"
+        } >> $GITHUB_OUTPUT
+        echo "Resolved PR #$PR_NUMBER (base=$BASE_SHA head=$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 }}
+      run: |
+        # 👀 react to the triggering comment so the user knows it was picked up.
+        gh api -X POST "repos/${{ github.repository }}/issues/comments/${{ github.event.comment.id }}/reactions" \
+          -f content=eyes >/dev/null 2>&1 || true
+
     - name: Checkout CodeBoarding engine
       if: steps.guard.outputs.skip != 'true'
       uses: actions/checkout@v4
@@ -379,7 +422,7 @@ runs:
       shell: bash
       run: |
         HEADER="${{ inputs.comment_header }}"
-        BASE_REF="${{ github.event.pull_request.base.ref }}"
+        BASE_REF="${{ steps.guard.outputs.base_ref }}"
         N="${{ steps.diagram.outputs.n_changed }}"
         RENDERED="${{ steps.diagram.outputs.rendered }}"
         TRUNC="${{ steps.diagram.outputs.truncated }}"
@@ -440,5 +483,6 @@ runs:
       uses: marocchino/sticky-pull-request-comment@v2
       with:
         header: codeboarding-architecture-diff
+        number: ${{ steps.guard.outputs.pr_number }}
         path: ${{ steps.body.outputs.body_file }}
         GITHUB_TOKEN: ${{ inputs.github_token }}