@agent-native/core 0.48.4 → 0.49.0

package/dist/cli/pr-visual-recap-workflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"pr-visual-recap-workflow.js","sourceRoot":"","sources":["../../src/cli/pr-visual-recap-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,4BAA4B,GACvC,mutBAAmutB,CAAC","sourcesContent":["/**\n * Bundled copy of .github/workflows/pr-visual-recap.yml so the CLI can write the\n * PR Visual Recap workflow into a user repo via\n * `agent-native skills add visual-plan --with-github-action`.\n *\n * AUTO-GENERATED — keep byte-identical with the source workflow. A sync test in\n * recap.spec.ts fails if these drift. Regenerate from the YAML with the snippet\n * in recap.spec.ts.\n */\n\nexport const PR_VISUAL_RECAP_WORKFLOW_YML =\n  'name: PR Visual Recap\\n\\n# Visual code review: a coding agent runs the repo\\'s visual-recap skill over the\\n# PR diff, publishes a plan, and upserts one sticky comment with a screenshot.\\n# Plain `pull_request` (NOT `pull_request_target`) so fork code never sees secrets.\\n\\non:\\n  pull_request:\\n    types: [opened, synchronize, reopened, ready_for_review]\\n\\npermissions:\\n  contents: read\\n\\nconcurrency:\\n  group: pr-visual-recap-${{ github.event.pull_request.number }}\\n  cancel-in-progress: true\\n\\nenv:\\n  VISUAL_RECAP_AGENT: ${{ vars.VISUAL_RECAP_AGENT || \\'claude\\' }}\\n  VISUAL_RECAP_SKILL_SOURCE: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || \\'auto\\' }}\\n\\njobs:\\n  gate:\\n    name: Gate\\n    runs-on: ubuntu-latest\\n    timeout-minutes: 10\\n    permissions:\\n      contents: read\\n      issues: write\\n      pull-requests: write\\n    outputs:\\n      run: ${{ steps.decide.outputs.run }}\\n      agent: ${{ steps.decide.outputs.agent }}\\n    steps:\\n      - id: decide\\n        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\\n        env:\\n          # Presence-only signals — never expose secret VALUES to the gate.\\n          HAS_PLAN: ${{ secrets.PLAN_RECAP_TOKEN != \\'\\' }}\\n          HAS_ANTHROPIC: ${{ secrets.ANTHROPIC_API_KEY != \\'\\' }}\\n          HAS_OPENAI: ${{ secrets.OPENAI_API_KEY != \\'\\' }}\\n          AGENT: ${{ env.VISUAL_RECAP_AGENT }}\\n          VISUAL_RECAP_MODEL: ${{ vars.VISUAL_RECAP_MODEL }}\\n          HEAD_SHA: ${{ github.event.pull_request.head.sha }}\\n        with:\\n          script: |\\n            const pr = context.payload.pull_request;\\n            const reasons = [];\\n\\n            if (!pr) reasons.push(\\'no pull_request payload\\');\\n            if (pr && pr.draft) reasons.push(\\'draft PR\\');\\n\\n            // Fork PRs run with no secrets, so publishing would fail anyway — skip.\\n            const headRepo = pr && pr.head && pr.head.repo && pr.head.repo.full_name;\\n            if (pr && headRepo && headRepo !== process.env.GITHUB_REPOSITORY) {\\n              reasons.push(`fork PR (${headRepo})`);\\n            }\\n\\n            const login = (pr && pr.user && pr.user.login || \\'\\').toLowerCase();\\n            const botAuthors = [\\'dependabot[bot]\\', \\'dependabot\\', \\'renovate[bot]\\', \\'renovate\\'];\\n            if (botAuthors.includes(login)) reasons.push(`bot author (${login})`);\\n            if (pr && pr.user && pr.user.type === \\'Bot\\') reasons.push(\\'bot author (type=Bot)\\');\\n\\n            if (process.env.HAS_PLAN !== \\'true\\') reasons.push(\\'PLAN_RECAP_TOKEN not configured\\');\\n\\n            // Normalize + validate the agent so a mis-cased value can\\'t pass the\\n            // gate and then match neither agent step below.\\n            const agent = (process.env.AGENT || \\'claude\\').toLowerCase();\\n            if (agent !== \\'claude\\' && agent !== \\'codex\\') {\\n              reasons.push(`unsupported VISUAL_RECAP_AGENT \"${process.env.AGENT}\" (expected \"claude\" or \"codex\")`);\\n            } else if (agent === \\'codex\\') {\\n              if (process.env.HAS_OPENAI !== \\'true\\') reasons.push(\\'OPENAI_API_KEY not configured (codex backend)\\');\\n            } else {\\n              if (process.env.HAS_ANTHROPIC !== \\'true\\') reasons.push(\\'ANTHROPIC_API_KEY not configured (claude backend)\\');\\n            }\\n\\n            // Validate the model before it reaches the agent CLI.\\n            const model = process.env.VISUAL_RECAP_MODEL || \\'\\';\\n            if (model && !/^[a-zA-Z0-9._-]{1,80}$/.test(model)) {\\n              reasons.push(`invalid VISUAL_RECAP_MODEL value (must match [a-zA-Z0-9._-]{1,80})`);\\n            }\\n\\n            // Self-modifying guard, evaluated in the trusted gate (runs NO\\n            // PR-checked-out code): skip the ENTIRE job if the PR touches the\\n            // workflow, skill, local CLI, or any agent config the runner loads,\\n            // so a PR can\\'t rewrite what runs and exfiltrate secrets.\\n            if (pr) {\\n              try {\\n                const files = await github.paginate(github.rest.pulls.listFiles, {\\n                  owner: context.repo.owner,\\n                  repo: context.repo.repo,\\n                  pull_number: pr.number,\\n                  per_page: 100,\\n                });\\n                const isAgentNativeMonorepo = context.repo.owner === \\'BuilderIO\\' && context.repo.repo === \\'agent-native\\';\\n                const isSensitive = (p) =>\\n                  p === \\'.github/workflows/pr-visual-recap.yml\\' ||\\n                  /(^|\\\\/)skills\\\\/visual-(recap|plan|plans)\\\\//.test(p) ||\\n                  /(^|\\\\/)\\\\.claude\\\\//.test(p) ||\\n                  /(^|\\\\/)CLAUDE\\\\.md$/.test(p) ||\\n                  /(^|\\\\/)AGENTS\\\\.md$/.test(p) ||\\n                  /(^|\\\\/)\\\\.mcp\\\\.json$/.test(p) ||\\n                  (isAgentNativeMonorepo && /(^|\\\\/)packages\\\\/core\\\\//.test(p));\\n                const hits = files.map((f) => f.filename).filter(isSensitive);\\n                if (hits.length) {\\n                  reasons.push(`PR modifies recap-control files (${hits.slice(0, 3).join(\\', \\')}${hits.length > 3 ? \\', …\\' : \\'\\'}) — skipping so untrusted PR code never runs with secrets`);\\n                }\\n              } catch (e) {\\n                // Fail closed: if the file list can\\'t be read, skip.\\n                reasons.push(`could not list PR files for the self-modifying guard (${e.message}); skipping to be safe`);\\n              }\\n            }\\n\\n            const run = reasons.length === 0;\\n            core.setOutput(\\'run\\', run ? \\'true\\' : \\'false\\');\\n            core.setOutput(\\'agent\\', agent);\\n            core.info(run ? `Visual recap will run (${agent}).` : `Visual recap skipped: ${reasons.join(\\'; \\')}`);\\n\\n            // When skipping, refresh an EXISTING sticky recap comment with a\\n            // short skip line so it does not silently go stale. Never create a\\n            // new comment (no spam for repos where the recap has never run).\\n            if (!run && pr) {\\n              try {\\n                const MARKER = \\'<!-- pr-visual-recap -->\\';\\n                const { data: comments } = await github.rest.issues.listComments({\\n                  owner: context.repo.owner,\\n                  repo: context.repo.repo,\\n                  issue_number: pr.number,\\n                  per_page: 100,\\n                });\\n                const existing = comments.find(\\n                  (c) => c.user && c.user.type === \\'Bot\\' && c.body && c.body.includes(MARKER)\\n                );\\n                if (existing) {\\n                  const headShort = (process.env.HEAD_SHA || \\'\\').slice(0, 7);\\n                  const shaRef = headShort ? `\\\\`${headShort}\\\\`` : \\'latest push\\';\\n                  const primaryReason = reasons.filter(\\n                    (r) => !r.startsWith(\\'could not list PR files for the self-modifying guard\\')\\n                  )[0] || reasons[0] || \\'skipped\\';\\n                  const skipLine = `_Recap skipped for ${shaRef}: ${primaryReason}._`;\\n                  const withoutPrev = (existing.body || \\'\\')\\n                    .split(\\'\\\\n\\')\\n                    .filter((l) => !/_Recap skipped for .+_$/.test(l.trim()))\\n                    .join(\\'\\\\n\\')\\n                    .trimEnd();\\n                  const updatedBody = `${withoutPrev}\\\\n\\\\n${skipLine}`;\\n                  await github.rest.issues.updateComment({\\n                    owner: context.repo.owner,\\n                    repo: context.repo.repo,\\n                    comment_id: existing.id,\\n                    body: updatedBody,\\n                  });\\n                }\\n              } catch (e) {\\n                core.warning(`Could not update recap skip comment: ${e.message}`);\\n              }\\n            }\\n\\n  recap:\\n    name: Generate visual recap\\n    needs: gate\\n    if: needs.gate.outputs.run == \\'true\\'\\n    runs-on: ubuntu-latest\\n    timeout-minutes: 30\\n    permissions:\\n      checks: write\\n      contents: read\\n      issues: write\\n      pull-requests: write\\n    env:\\n      PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL || \\'https://plan.agent-native.com\\' }}\\n      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}\\n      GH_TOKEN: ${{ github.token }}\\n      PR_NUMBER: ${{ github.event.pull_request.number }}\\n      HEAD_SHA: ${{ github.event.pull_request.head.sha }}\\n      VISUAL_RECAP_MODEL: ${{ vars.VISUAL_RECAP_MODEL }}\\n      VISUAL_RECAP_REASONING: ${{ vars.VISUAL_RECAP_REASONING }}\\n      VISUAL_RECAP_SKILL_SOURCE: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || \\'auto\\' }}\\n    steps:\\n      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3\\n        with:\\n          fetch-depth: 0\\n          # This job runs an agent over untrusted PR diff; don\\'t leave the token\\n          # in .git/config (it uses GH_TOKEN for gh API calls, never git push).\\n          persist-credentials: false\\n\\n      # Dogfood local source inside this monorepo, else the published package.\\n      # The pnpm steps run ONLY on the local path so npm/yarn consumer repos\\n      # (no pnpm-lock.yaml) fall back to `npx @agent-native/core`.\\n      - name: Resolve recap CLI\\n        id: cli\\n        env:\\n          # Optional: pin the consumer CLI version (e.g. \"1.2.3\"). Defaults to\\n          # \"latest\" when unset. Set via repository variable RECAP_CLI_VERSION.\\n          RECAP_CLI_VERSION: ${{ vars.RECAP_CLI_VERSION || \\'latest\\' }}\\n        run: |\\n          if [ -f packages/core/src/cli/index.ts ]; then\\n            echo \"RECAP_CLI=pnpm exec tsx packages/core/src/cli/index.ts\" >> \"$GITHUB_ENV\"\\n            echo \"local=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"RECAP_CLI=npx -y @agent-native/core@${RECAP_CLI_VERSION}\" >> \"$GITHUB_ENV\"\\n            echo \"local=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8\\n        if: steps.cli.outputs.local == \\'true\\'\\n\\n      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0\\n        with:\\n          node-version: \"22\"\\n          cache: ${{ steps.cli.outputs.local == \\'true\\' && \\'pnpm\\' || \\'\\' }}\\n\\n      - name: Install workspace (local source only)\\n        if: steps.cli.outputs.local == \\'true\\'\\n        run: pnpm install --frozen-lockfile --ignore-scripts\\n\\n      - name: Start visual recap check\\n        id: recap_check\\n        continue-on-error: true\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap check start --sha \"$HEAD_SHA\" --workflow-url \"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\"\\n\\n      - name: Collect bounded diff\\n        id: diff\\n        env:\\n          BASE_SHA: ${{ github.event.pull_request.base.sha }}\\n        run: |\\n          set -euo pipefail\\n          $RECAP_CLI recap collect-diff --base \"$BASE_SHA\" --head \"$HEAD_SHA\" --out recap.diff --stat recap.stat\\n\\n      - name: Probe plan-app auth\\n        id: auth_probe\\n        if: steps.diff.outputs.tiny != \\'true\\'\\n        continue-on-error: true\\n        run: |\\n          set -uo pipefail\\n          # Hit the plan app\\'s action surface with the publish token. A 401 means\\n          # the token is expired/revoked; surface it in the sticky comment so the\\n          # repo owner knows to re-mint it instead of seeing a generic failure.\\n          HTTP_STATUS=$(node -e \\'\\n            const https = require(\"https\");\\n            const url = new URL(\"/_agent-native/actions/record-recap-usage\", process.env.PLAN_RECAP_APP_URL || \"https://plan.agent-native.com\");\\n            const req = https.request(url, { method: \"POST\", headers: { \"authorization\": \"Bearer \" + process.env.PLAN_RECAP_TOKEN, \"content-type\": \"application/json\" }, timeout: 8000 }, (res) => { process.stdout.write(String(res.statusCode)); req.destroy(); });\\n            req.on(\"error\", () => process.stdout.write(\"0\"));\\n            req.end(JSON.stringify({ planId: \"__probe__\" }));\\n          \\' 2>/dev/null || echo \"0\")\\n          if [ \"$HTTP_STATUS\" = \"401\" ]; then\\n            echo \"auth_failed=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"auth_failed=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - name: Secret scan\\n        id: scan\\n        if: steps.diff.outputs.tiny != \\'true\\'\\n        run: |\\n          set -uo pipefail\\n          # Fail CLOSED: a scanner error or invalid JSON suppresses the diff so a\\n          # credential-bearing diff is never handed to the agent / plan service.\\n          if ! SCAN_JSON=\"$($RECAP_CLI recap scan --diff recap.diff)\"; then\\n            SCAN_JSON=\\'{\"suppressed\":true,\"reason\":\"secret scan failed to run; failing closed\"}\\'\\n          fi\\n          {\\n            echo \\'json<<__RECAP_SCAN_EOF__\\'\\n            echo \"$SCAN_JSON\"\\n            echo \\'__RECAP_SCAN_EOF__\\'\\n          } >> \"$GITHUB_OUTPUT\"\\n          SUPPRESSED=$(node -e \\'try{process.stdout.write(JSON.parse(process.argv[1]).suppressed?\"true\":\"false\")}catch{process.stdout.write(\"true\")}\\' \"$SCAN_JSON\")\\n          echo \"suppressed=$SUPPRESSED\" >> \"$GITHUB_OUTPUT\"\\n\\n      - name: Read previous plan id\\n        id: prev\\n        continue-on-error: true\\n        run: |\\n          set -euo pipefail\\n          PLAN_ID=\"$($RECAP_CLI recap comment find-plan-id --repo \"$GITHUB_REPOSITORY\" --issue \"$PR_NUMBER\" --token \"$GH_TOKEN\")\"\\n          echo \"plan_id=$PLAN_ID\" >> \"$GITHUB_OUTPUT\"\\n\\n      - name: Build recap prompt\\n        id: prompt\\n        if: steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        env:\\n          # Pass step outputs via env, NOT ${{ }} interpolation into the run body:\\n          # the prev plan id is parsed from a PR comment and could inject shell.\\n          PREV_PLAN_ID: ${{ steps.prev.outputs.plan_id }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n        run: |\\n          set -euo pipefail\\n          ARGS=(--diff recap.diff --stat recap.stat --pr \"$PR_NUMBER\" --repo \"$GITHUB_REPOSITORY\" --head \"$HEAD_SHA\" --app-url \"$PLAN_RECAP_APP_URL\" --skill-source \"$VISUAL_RECAP_SKILL_SOURCE\" --out recap-prompt.md)\\n          if [ \"${DIFF_HUGE:-}\" = \"true\" ]; then ARGS+=(--huge); fi\\n          if [ -n \"${PREV_PLAN_ID:-}\" ]; then ARGS+=(--prev-plan-id \"$PREV_PLAN_ID\"); fi\\n          $RECAP_CLI recap build-prompt \"${ARGS[@]}\"\\n\\n      - name: Run agent (Claude Code)\\n        id: claude\\n        if: needs.gate.outputs.agent == \\'claude\\' && steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        continue-on-error: true\\n        env:\\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\\n        run: |\\n          set -uo pipefail\\n          MCP_CONFIG=\"$RUNNER_TEMP/plan-mcp.json\"\\n          $RECAP_CLI recap mcp-config --agent claude --app-url \"$PLAN_RECAP_APP_URL\" --out \"$MCP_CONFIG\"\\n          CLAUDE_ARGS=(-p \"$(cat recap-prompt.md)\" --mcp-config \"$MCP_CONFIG\" --allowedTools \"Read,Write,Bash(git diff:*),mcp__plan__get-plan-blocks,mcp__plan__create-visual-recap,mcp__plan__set-resource-visibility\" --permission-mode dontAsk --output-format json)\\n          if [ -n \"${VISUAL_RECAP_MODEL:-}\" ]; then CLAUDE_ARGS+=(--model \"$VISUAL_RECAP_MODEL\"); fi\\n          npx -y @anthropic-ai/claude-code@2 \"${CLAUDE_ARGS[@]}\" > claude-result.json || true\\n          rm -f \"$MCP_CONFIG\" || true\\n\\n      - name: Run agent (Codex)\\n        id: codex\\n        if: needs.gate.outputs.agent == \\'codex\\' && steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        continue-on-error: true\\n        env:\\n          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap mcp-config --agent codex --app-url \"$PLAN_RECAP_APP_URL\"\\n          # `codex login` writes ~/.codex/auth.json (the bare env var is dropped on\\n          # the gpt-5.5 wss transport); stdin keeps the key out of process args.\\n          printenv OPENAI_API_KEY | npx -y @openai/codex@0 login --with-api-key || true\\n          # The runner is itself an ephemeral sandbox; bypass Codex\\'s own sandbox\\n          # (bubblewrap can\\'t init here) and approval gate (cancels the MCP write).\\n          CODEX_ARGS=(exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check)\\n          if [ -n \"${VISUAL_RECAP_MODEL:-}\" ]; then CODEX_ARGS+=(--model \"$VISUAL_RECAP_MODEL\"); fi\\n          # Validate reasoning against the enum before embedding it in the TOML override.\\n          case \"${VISUAL_RECAP_REASONING:-}\" in\\n            none|minimal|low|medium|high|xhigh)\\n              CODEX_ARGS+=(-c \"model_reasoning_effort=\\\\\"$VISUAL_RECAP_REASONING\\\\\"\") ;;\\n            \"\") ;;\\n            *) echo \"Ignoring invalid VISUAL_RECAP_REASONING: $VISUAL_RECAP_REASONING\" ;;\\n          esac\\n          npx -y @openai/codex@0 \"${CODEX_ARGS[@]}\" --json \"$(cat recap-prompt.md)\" | tee codex-events.jsonl || true\\n\\n      - name: Read plan URL\\n        id: url\\n        if: steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        run: |\\n          set -uo pipefail\\n          PLAN_URL=\"\"\\n          if [ -f recap-url.txt ]; then PLAN_URL=\"$(tr -d \\'\\\\r\\\\n\\' < recap-url.txt | tr -d \\' \\')\"; fi\\n          # recap-url.txt is agent-written -> untrusted. Rebuild a canonical\\n          # recap URL from the trusted app base and a strictly validated plan id,\\n          # preserving path-prefixed self-hosted mounts.\\n          CANONICAL_URL=$(PLAN_URL=\"$PLAN_URL\" node <<\\'NODE\\'\\n          try {\\n            const raw = process.env.PLAN_URL || \"\";\\n            const trusted = new URL(process.env.PLAN_RECAP_APP_URL || \"https://plan.agent-native.com\");\\n            const parsed = /^https?:\\\\/\\\\//i.test(raw)\\n              ? new URL(raw)\\n              : new URL(raw, trusted);\\n            if (parsed.origin !== trusted.origin) {\\n              process.exit(0);\\n            }\\n\\n            const base = trusted.pathname.replace(/\\\\/$/, \"\");\\n            const paths = [parsed.pathname];\\n            if (base && parsed.pathname.startsWith(`${base}/`)) {\\n              paths.push(parsed.pathname.slice(base.length) || \"/\");\\n            }\\n\\n            for (const path of paths) {\\n              const match = path.match(/^\\\\/(?:plans|recaps)\\\\/([A-Za-z0-9_-]+)\\\\/?$/);\\n              if (match) {\\n                process.stdout.write(`${trusted.origin}${base}/recaps/${match[1]}`);\\n                break;\\n              }\\n            }\\n          } catch {\\n            process.exit(0);\\n          }\\n          NODE\\n          )\\n          if [ -n \"$CANONICAL_URL\" ]; then\\n            echo \"plan_url=$CANONICAL_URL\" >> \"$GITHUB_OUTPUT\"; echo \"ok=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"plan_url=\" >> \"$GITHUB_OUTPUT\"; echo \"ok=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - name: Attach usage\\n        if: steps.url.outputs.ok == \\'true\\'\\n        continue-on-error: true\\n        env:\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          # Use the gate-normalized agent so \"Codex\" still selects the right file.\\n          RECAP_AGENT: ${{ needs.gate.outputs.agent }}\\n        run: |\\n          set -uo pipefail\\n          RESULT=claude-result.json\\n          if [ \"$RECAP_AGENT\" = \"codex\" ]; then RESULT=codex-events.jsonl; fi\\n          if [ -f \"$RESULT\" ]; then $RECAP_CLI recap usage --plan-url \"$PLAN_URL\" --agent \"$RECAP_AGENT\" --result-file \"$RESULT\" --model \"${VISUAL_RECAP_MODEL:-}\" --app-url \"$PLAN_RECAP_APP_URL\" --token \"$PLAN_RECAP_TOKEN\" || true; fi\\n\\n      - name: Cache Playwright browsers\\n        if: steps.url.outputs.ok == \\'true\\'\\n        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3\\n        with:\\n          path: ~/.cache/ms-playwright\\n          key: playwright-1-${{ runner.os }}\\n\\n      - name: Screenshot + upload\\n        id: shot\\n        if: steps.url.outputs.ok == \\'true\\'\\n        continue-on-error: true\\n        env:\\n          # recap-url.txt is untrusted agent output; pass via env, never ${{ }}.\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n        run: |\\n          set -uo pipefail\\n          pnpm exec playwright install --with-deps chromium 2>/dev/null || npx -y playwright@1 install --with-deps chromium || true\\n          SHOT_JSON=\"$($RECAP_CLI recap shot --url \"$PLAN_URL\" --token \"$PLAN_RECAP_TOKEN\" --app-url \"$PLAN_RECAP_APP_URL\" --out recap.png || echo \\'{}\\')\"\\n          IMAGE_URL=$(node -e \\'try{process.stdout.write(JSON.parse(process.argv[1]).imageUrl||\"\")}catch{process.stdout.write(\"\")}\\' \"$SHOT_JSON\")\\n          echo \"image_url=$IMAGE_URL\" >> \"$GITHUB_OUTPUT\"\\n          if [ -f recap.png ]; then echo \"captured=true\" >> \"$GITHUB_OUTPUT\"; else echo \"captured=false\" >> \"$GITHUB_OUTPUT\"; fi\\n\\n      - name: Upload recap screenshot artifact\\n        if: steps.shot.outputs.captured == \\'true\\'\\n        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\\n        with:\\n          name: pr-visual-recap-${{ github.event.pull_request.number }}\\n          path: recap.png\\n          if-no-files-found: ignore\\n          retention-days: 14\\n\\n      - name: Upsert sticky comment\\n        if: always()\\n        continue-on-error: true\\n        env:\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          RECAP_IMAGE_URL: ${{ steps.shot.outputs.image_url }}\\n          SUPPRESSED: ${{ steps.scan.outputs.suppressed }}\\n          SUPPRESSED_JSON: ${{ steps.scan.outputs.json }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n          DIFF_TINY: ${{ steps.diff.outputs.tiny }}\\n          PREV_PLAN_ID: ${{ steps.prev.outputs.plan_id }}\\n          RECAP_AUTH_FAILED: ${{ steps.auth_probe.outputs.auth_failed }}\\n        run: |\\n          set -euo pipefail\\n          ARGS=(recap comment upsert --repo \"$GITHUB_REPOSITORY\" --issue \"$PR_NUMBER\" --token \"$GH_TOKEN\")\\n          # On a tiny diff, only REFRESH an existing comment, never create one.\\n          if [ \"${DIFF_TINY:-}\" = \"true\" ]; then ARGS+=(--update-only); fi\\n          $RECAP_CLI \"${ARGS[@]}\"\\n\\n      - name: Complete visual recap check\\n        if: always() && steps.recap_check.outputs.check_run_id != \\'\\'\\n        continue-on-error: true\\n        env:\\n          # Untrusted/step values via env (NOT ${{ }}-interpolated into the run\\n          # body): the agent-written plan URL and the scan JSON could inject shell.\\n          CHECK_RUN_ID: ${{ steps.recap_check.outputs.check_run_id }}\\n          PLAN_OK: ${{ steps.url.outputs.ok }}\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          SUPPRESSED: ${{ steps.scan.outputs.suppressed }}\\n          SUPPRESSED_JSON: ${{ steps.scan.outputs.json }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n          DIFF_TINY: ${{ steps.diff.outputs.tiny }}\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap check complete \\\\\\n            --check-run-id \"$CHECK_RUN_ID\" \\\\\\n            --plan-ok \"$PLAN_OK\" \\\\\\n            --plan-url \"$PLAN_URL\" \\\\\\n            --suppressed \"$SUPPRESSED\" \\\\\\n            --suppressed-json \"$SUPPRESSED_JSON\" \\\\\\n            --huge \"$DIFF_HUGE\" \\\\\\n            --tiny \"$DIFF_TINY\" \\\\\\n            --workflow-url \"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\"\\n';\n"]}
+{"version":3,"file":"pr-visual-recap-workflow.js","sourceRoot":"","sources":["../../src/cli/pr-visual-recap-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,4BAA4B,GACvC,g+uBAAg+uB,CAAC","sourcesContent":["/**\n * Bundled copy of .github/workflows/pr-visual-recap.yml so the CLI can write the\n * PR Visual Recap workflow into a user repo via\n * `agent-native skills add visual-plan --with-github-action`.\n *\n * AUTO-GENERATED — keep byte-identical with the source workflow. A sync test in\n * recap.spec.ts fails if these drift. Regenerate from the YAML with the snippet\n * in recap.spec.ts.\n */\n\nexport const PR_VISUAL_RECAP_WORKFLOW_YML =\n  'name: PR Visual Recap\\n\\n# Visual code review: a coding agent runs the repo\\'s visual-recap skill over the\\n# PR diff, publishes a plan, and upserts one sticky comment with a screenshot.\\n# Plain `pull_request` (NOT `pull_request_target`) so fork code never sees secrets.\\n\\non:\\n  pull_request:\\n    types: [opened, synchronize, reopened, ready_for_review]\\n\\npermissions:\\n  contents: read\\n\\nconcurrency:\\n  group: pr-visual-recap-${{ github.event.pull_request.number }}\\n  cancel-in-progress: true\\n\\nenv:\\n  VISUAL_RECAP_AGENT: ${{ vars.VISUAL_RECAP_AGENT || \\'claude\\' }}\\n  VISUAL_RECAP_SKILL_SOURCE: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || \\'auto\\' }}\\n\\njobs:\\n  gate:\\n    name: Gate\\n    runs-on: ubuntu-latest\\n    timeout-minutes: 10\\n    permissions:\\n      contents: read\\n      issues: write\\n      pull-requests: write\\n    outputs:\\n      run: ${{ steps.decide.outputs.run }}\\n      agent: ${{ steps.decide.outputs.agent }}\\n    steps:\\n      - id: decide\\n        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0\\n        env:\\n          # Presence-only signals — never expose secret VALUES to the gate.\\n          HAS_PLAN: ${{ secrets.PLAN_RECAP_TOKEN != \\'\\' }}\\n          HAS_ANTHROPIC: ${{ secrets.ANTHROPIC_API_KEY != \\'\\' }}\\n          HAS_OPENAI: ${{ secrets.OPENAI_API_KEY != \\'\\' }}\\n          AGENT: ${{ env.VISUAL_RECAP_AGENT }}\\n          VISUAL_RECAP_MODEL: ${{ vars.VISUAL_RECAP_MODEL }}\\n          HEAD_SHA: ${{ github.event.pull_request.head.sha }}\\n        with:\\n          script: |\\n            const pr = context.payload.pull_request;\\n            const reasons = [];\\n\\n            if (!pr) reasons.push(\\'no pull_request payload\\');\\n            if (pr && pr.draft) reasons.push(\\'draft PR\\');\\n\\n            // Fork PRs run with no secrets, so publishing would fail anyway — skip.\\n            const headRepo = pr && pr.head && pr.head.repo && pr.head.repo.full_name;\\n            if (pr && headRepo && headRepo !== process.env.GITHUB_REPOSITORY) {\\n              reasons.push(`fork PR (${headRepo})`);\\n            }\\n\\n            const login = (pr && pr.user && pr.user.login || \\'\\').toLowerCase();\\n            const botAuthors = [\\'dependabot[bot]\\', \\'dependabot\\', \\'renovate[bot]\\', \\'renovate\\'];\\n            if (botAuthors.includes(login)) reasons.push(`bot author (${login})`);\\n            if (pr && pr.user && pr.user.type === \\'Bot\\') reasons.push(\\'bot author (type=Bot)\\');\\n\\n            if (process.env.HAS_PLAN !== \\'true\\') reasons.push(\\'PLAN_RECAP_TOKEN not configured\\');\\n\\n            // Normalize + validate the agent so a mis-cased value can\\'t pass the\\n            // gate and then match neither agent step below.\\n            const agent = (process.env.AGENT || \\'claude\\').toLowerCase();\\n            if (agent !== \\'claude\\' && agent !== \\'codex\\') {\\n              reasons.push(`unsupported VISUAL_RECAP_AGENT \"${process.env.AGENT}\" (expected \"claude\" or \"codex\")`);\\n            } else if (agent === \\'codex\\') {\\n              if (process.env.HAS_OPENAI !== \\'true\\') reasons.push(\\'OPENAI_API_KEY not configured (codex backend)\\');\\n            } else {\\n              if (process.env.HAS_ANTHROPIC !== \\'true\\') reasons.push(\\'ANTHROPIC_API_KEY not configured (claude backend)\\');\\n            }\\n\\n            // Validate the model before it reaches the agent CLI.\\n            const model = process.env.VISUAL_RECAP_MODEL || \\'\\';\\n            if (model && !/^[a-zA-Z0-9._-]{1,80}$/.test(model)) {\\n              reasons.push(`invalid VISUAL_RECAP_MODEL value (must match [a-zA-Z0-9._-]{1,80})`);\\n            }\\n\\n            // Self-modifying guard, evaluated in the trusted gate (runs NO\\n            // PR-checked-out code): skip the ENTIRE job if the PR touches the\\n            // workflow, skill, local CLI, or any agent config the runner loads,\\n            // so a PR can\\'t rewrite what runs and exfiltrate secrets.\\n            if (pr) {\\n              try {\\n                const files = await github.paginate(github.rest.pulls.listFiles, {\\n                  owner: context.repo.owner,\\n                  repo: context.repo.repo,\\n                  pull_number: pr.number,\\n                  per_page: 100,\\n                });\\n                const isAgentNativeMonorepo = context.repo.owner === \\'BuilderIO\\' && context.repo.repo === \\'agent-native\\';\\n                const isSensitive = (p) =>\\n                  p === \\'.github/workflows/pr-visual-recap.yml\\' ||\\n                  /(^|\\\\/)skills\\\\/visual-(recap|plan|plans)\\\\//.test(p) ||\\n                  /(^|\\\\/)\\\\.claude\\\\//.test(p) ||\\n                  /(^|\\\\/)CLAUDE\\\\.md$/.test(p) ||\\n                  /(^|\\\\/)AGENTS\\\\.md$/.test(p) ||\\n                  /(^|\\\\/)\\\\.mcp\\\\.json$/.test(p) ||\\n                  (isAgentNativeMonorepo && /(^|\\\\/)packages\\\\/core\\\\//.test(p));\\n                const hits = files.map((f) => f.filename).filter(isSensitive);\\n                if (hits.length) {\\n                  reasons.push(`PR modifies recap-control files (${hits.slice(0, 3).join(\\', \\')}${hits.length > 3 ? \\', …\\' : \\'\\'}) — skipping so untrusted PR code never runs with secrets`);\\n                }\\n              } catch (e) {\\n                // Fail closed: if the file list can\\'t be read, skip.\\n                reasons.push(`could not list PR files for the self-modifying guard (${e.message}); skipping to be safe`);\\n              }\\n            }\\n\\n            const run = reasons.length === 0;\\n            core.setOutput(\\'run\\', run ? \\'true\\' : \\'false\\');\\n            core.setOutput(\\'agent\\', agent);\\n            core.info(run ? `Visual recap will run (${agent}).` : `Visual recap skipped: ${reasons.join(\\'; \\')}`);\\n\\n            // When skipping, refresh an EXISTING sticky recap comment with a\\n            // short skip line so it does not silently go stale. Never create a\\n            // new comment (no spam for repos where the recap has never run).\\n            if (!run && pr) {\\n              try {\\n                const MARKER = \\'<!-- pr-visual-recap -->\\';\\n                const { data: comments } = await github.rest.issues.listComments({\\n                  owner: context.repo.owner,\\n                  repo: context.repo.repo,\\n                  issue_number: pr.number,\\n                  per_page: 100,\\n                });\\n                const existing = comments.find(\\n                  (c) => c.user && c.user.type === \\'Bot\\' && c.body && c.body.includes(MARKER)\\n                );\\n                if (existing) {\\n                  const headShort = (process.env.HEAD_SHA || \\'\\').slice(0, 7);\\n                  const shaRef = headShort ? `\\\\`${headShort}\\\\`` : \\'latest push\\';\\n                  const primaryReason = reasons.filter(\\n                    (r) => !r.startsWith(\\'could not list PR files for the self-modifying guard\\')\\n                  )[0] || reasons[0] || \\'skipped\\';\\n                  const skipLine = `_Recap skipped for ${shaRef}: ${primaryReason}._`;\\n                  const withoutPrev = (existing.body || \\'\\')\\n                    .split(\\'\\\\n\\')\\n                    .filter((l) => !/_Recap skipped for .+_$/.test(l.trim()))\\n                    .join(\\'\\\\n\\')\\n                    .trimEnd();\\n                  const updatedBody = `${withoutPrev}\\\\n\\\\n${skipLine}`;\\n                  await github.rest.issues.updateComment({\\n                    owner: context.repo.owner,\\n                    repo: context.repo.repo,\\n                    comment_id: existing.id,\\n                    body: updatedBody,\\n                  });\\n                }\\n              } catch (e) {\\n                core.warning(`Could not update recap skip comment: ${e.message}`);\\n              }\\n            }\\n\\n  recap:\\n    name: Generate visual recap\\n    needs: gate\\n    if: needs.gate.outputs.run == \\'true\\'\\n    runs-on: ubuntu-latest\\n    timeout-minutes: 30\\n    permissions:\\n      checks: write\\n      contents: read\\n      issues: write\\n      pull-requests: write\\n    env:\\n      PLAN_RECAP_APP_URL: ${{ secrets.PLAN_RECAP_APP_URL || \\'https://plan.agent-native.com\\' }}\\n      PLAN_RECAP_TOKEN: ${{ secrets.PLAN_RECAP_TOKEN }}\\n      GH_TOKEN: ${{ github.token }}\\n      PR_NUMBER: ${{ github.event.pull_request.number }}\\n      HEAD_SHA: ${{ github.event.pull_request.head.sha }}\\n      VISUAL_RECAP_MODEL: ${{ vars.VISUAL_RECAP_MODEL }}\\n      VISUAL_RECAP_REASONING: ${{ vars.VISUAL_RECAP_REASONING }}\\n      VISUAL_RECAP_SKILL_SOURCE: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || \\'auto\\' }}\\n    steps:\\n      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3\\n        with:\\n          fetch-depth: 0\\n          # This job runs an agent over untrusted PR diff; don\\'t leave the token\\n          # in .git/config (it uses GH_TOKEN for gh API calls, never git push).\\n          persist-credentials: false\\n\\n      # Dogfood local source inside this monorepo, else the published package.\\n      # The pnpm steps run ONLY on the local path so npm/yarn consumer repos\\n      # (no pnpm-lock.yaml) fall back to `npx @agent-native/core`.\\n      - name: Resolve recap CLI\\n        id: cli\\n        env:\\n          # Optional: pin the consumer CLI version (e.g. \"1.2.3\"). Defaults to\\n          # \"latest\" when unset. Set via repository variable RECAP_CLI_VERSION.\\n          RECAP_CLI_VERSION: ${{ vars.RECAP_CLI_VERSION || \\'latest\\' }}\\n        run: |\\n          if [ -f packages/core/src/cli/index.ts ]; then\\n            echo \"RECAP_CLI=pnpm exec tsx packages/core/src/cli/index.ts\" >> \"$GITHUB_ENV\"\\n            echo \"local=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"RECAP_CLI=npx -y @agent-native/core@${RECAP_CLI_VERSION}\" >> \"$GITHUB_ENV\"\\n            echo \"local=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8\\n        if: steps.cli.outputs.local == \\'true\\'\\n\\n      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0\\n        with:\\n          node-version: \"22\"\\n          cache: ${{ steps.cli.outputs.local == \\'true\\' && \\'pnpm\\' || \\'\\' }}\\n\\n      - name: Install workspace (local source only)\\n        if: steps.cli.outputs.local == \\'true\\'\\n        run: pnpm install --frozen-lockfile --ignore-scripts\\n\\n      - name: Start visual recap check\\n        id: recap_check\\n        continue-on-error: true\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap check start --sha \"$HEAD_SHA\" --workflow-url \"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\"\\n\\n      - name: Collect bounded diff\\n        id: diff\\n        env:\\n          BASE_SHA: ${{ github.event.pull_request.base.sha }}\\n        run: |\\n          set -euo pipefail\\n          $RECAP_CLI recap collect-diff --base \"$BASE_SHA\" --head \"$HEAD_SHA\" --out recap.diff --stat recap.stat\\n\\n      - name: Probe plan-app auth\\n        id: auth_probe\\n        if: steps.diff.outputs.tiny != \\'true\\'\\n        continue-on-error: true\\n        run: |\\n          set -uo pipefail\\n          # Hit the plan app\\'s action surface with the publish token. A 401 means\\n          # the token is expired/revoked; surface it in the sticky comment so the\\n          # repo owner knows to re-mint it instead of seeing a generic failure.\\n          HTTP_STATUS=$(node -e \\'\\n            const https = require(\"https\");\\n            const url = new URL(\"/_agent-native/actions/record-recap-usage\", process.env.PLAN_RECAP_APP_URL || \"https://plan.agent-native.com\");\\n            const req = https.request(url, { method: \"POST\", headers: { \"authorization\": \"Bearer \" + process.env.PLAN_RECAP_TOKEN, \"content-type\": \"application/json\" }, timeout: 8000 }, (res) => { process.stdout.write(String(res.statusCode)); req.destroy(); });\\n            req.on(\"error\", () => process.stdout.write(\"0\"));\\n            req.end(JSON.stringify({ planId: \"__probe__\" }));\\n          \\' 2>/dev/null || echo \"0\")\\n          if [ \"$HTTP_STATUS\" = \"401\" ]; then\\n            echo \"auth_failed=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"auth_failed=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - name: Secret scan\\n        id: scan\\n        if: steps.diff.outputs.tiny != \\'true\\'\\n        run: |\\n          set -uo pipefail\\n          # Fail CLOSED: a scanner error or invalid JSON suppresses the diff so a\\n          # credential-bearing diff is never handed to the agent / plan service.\\n          if ! SCAN_JSON=\"$($RECAP_CLI recap scan --diff recap.diff)\"; then\\n            SCAN_JSON=\\'{\"suppressed\":true,\"reason\":\"secret scan failed to run; failing closed\"}\\'\\n          fi\\n          {\\n            echo \\'json<<__RECAP_SCAN_EOF__\\'\\n            echo \"$SCAN_JSON\"\\n            echo \\'__RECAP_SCAN_EOF__\\'\\n          } >> \"$GITHUB_OUTPUT\"\\n          SUPPRESSED=$(node -e \\'try{process.stdout.write(JSON.parse(process.argv[1]).suppressed?\"true\":\"false\")}catch{process.stdout.write(\"true\")}\\' \"$SCAN_JSON\")\\n          echo \"suppressed=$SUPPRESSED\" >> \"$GITHUB_OUTPUT\"\\n\\n      - name: Read previous plan id\\n        id: prev\\n        continue-on-error: true\\n        run: |\\n          set -euo pipefail\\n          PLAN_ID=\"$($RECAP_CLI recap comment find-plan-id --repo \"$GITHUB_REPOSITORY\" --issue \"$PR_NUMBER\" --token \"$GH_TOKEN\")\"\\n          echo \"plan_id=$PLAN_ID\" >> \"$GITHUB_OUTPUT\"\\n\\n      - name: Build recap prompt\\n        id: prompt\\n        if: steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        env:\\n          # Pass step outputs via env, NOT ${{ }} interpolation into the run body:\\n          # the prev plan id is parsed from a PR comment and could inject shell.\\n          PREV_PLAN_ID: ${{ steps.prev.outputs.plan_id }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n        run: |\\n          set -euo pipefail\\n          ARGS=(--diff recap.diff --stat recap.stat --pr \"$PR_NUMBER\" --repo \"$GITHUB_REPOSITORY\" --head \"$HEAD_SHA\" --app-url \"$PLAN_RECAP_APP_URL\" --skill-source \"$VISUAL_RECAP_SKILL_SOURCE\" --out recap-prompt.md)\\n          if [ \"${DIFF_HUGE:-}\" = \"true\" ]; then ARGS+=(--huge); fi\\n          if [ -n \"${PREV_PLAN_ID:-}\" ]; then ARGS+=(--prev-plan-id \"$PREV_PLAN_ID\"); fi\\n          $RECAP_CLI recap build-prompt \"${ARGS[@]}\"\\n\\n      - name: Run agent (Claude Code)\\n        id: claude\\n        if: needs.gate.outputs.agent == \\'claude\\' && steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        continue-on-error: true\\n        env:\\n          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}\\n        run: |\\n          set -uo pipefail\\n          MCP_CONFIG=\"$RUNNER_TEMP/plan-mcp.json\"\\n          $RECAP_CLI recap mcp-config --agent claude --app-url \"$PLAN_RECAP_APP_URL\" --out \"$MCP_CONFIG\"\\n          CLAUDE_ARGS=(-p \"$(cat recap-prompt.md)\" --mcp-config \"$MCP_CONFIG\" --allowedTools \"Read,Write,Bash(git diff:*),mcp__plan__get-plan-blocks,mcp__plan__create-visual-recap,mcp__plan__set-resource-visibility\" --permission-mode dontAsk --output-format json)\\n          if [ -n \"${VISUAL_RECAP_MODEL:-}\" ]; then CLAUDE_ARGS+=(--model \"$VISUAL_RECAP_MODEL\"); fi\\n          npx -y @anthropic-ai/claude-code@2 \"${CLAUDE_ARGS[@]}\" > claude-result.json || true\\n          rm -f \"$MCP_CONFIG\" || true\\n\\n      - name: Run agent (Codex)\\n        id: codex\\n        if: needs.gate.outputs.agent == \\'codex\\' && steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        continue-on-error: true\\n        env:\\n          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap mcp-config --agent codex --app-url \"$PLAN_RECAP_APP_URL\"\\n          # `codex login` writes ~/.codex/auth.json (the bare env var is dropped on\\n          # the gpt-5.5 wss transport); stdin keeps the key out of process args.\\n          printenv OPENAI_API_KEY | npx -y @openai/codex@0 login --with-api-key || true\\n          # The runner is itself an ephemeral sandbox; bypass Codex\\'s own sandbox\\n          # (bubblewrap can\\'t init here) and approval gate (cancels the MCP write).\\n          CODEX_ARGS=(exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check)\\n          if [ -n \"${VISUAL_RECAP_MODEL:-}\" ]; then CODEX_ARGS+=(--model \"$VISUAL_RECAP_MODEL\"); fi\\n          # Validate reasoning against the enum before embedding it in the TOML override.\\n          case \"${VISUAL_RECAP_REASONING:-}\" in\\n            none|minimal|low|medium|high|xhigh)\\n              CODEX_ARGS+=(-c \"model_reasoning_effort=\\\\\"$VISUAL_RECAP_REASONING\\\\\"\") ;;\\n            \"\") ;;\\n            *) echo \"Ignoring invalid VISUAL_RECAP_REASONING: $VISUAL_RECAP_REASONING\" ;;\\n          esac\\n          npx -y @openai/codex@0 \"${CODEX_ARGS[@]}\" --json \"$(cat recap-prompt.md)\" | tee codex-events.jsonl || true\\n\\n      - name: Read plan URL\\n        id: url\\n        if: steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        run: |\\n          set -uo pipefail\\n          PLAN_URL=\"\"\\n          if [ -f recap-url.txt ]; then PLAN_URL=\"$(tr -d \\'\\\\r\\\\n\\' < recap-url.txt | tr -d \\' \\')\"; fi\\n          # recap-url.txt is agent-written -> untrusted. Rebuild a canonical\\n          # recap URL from the trusted app base and a strictly validated plan id,\\n          # preserving path-prefixed self-hosted mounts.\\n          CANONICAL_URL=$(PLAN_URL=\"$PLAN_URL\" node <<\\'NODE\\'\\n          try {\\n            const raw = process.env.PLAN_URL || \"\";\\n            const trusted = new URL(process.env.PLAN_RECAP_APP_URL || \"https://plan.agent-native.com\");\\n            const parsed = /^https?:\\\\/\\\\//i.test(raw)\\n              ? new URL(raw)\\n              : new URL(raw, trusted);\\n            if (parsed.origin !== trusted.origin) {\\n              process.exit(0);\\n            }\\n\\n            const base = trusted.pathname.replace(/\\\\/$/, \"\");\\n            const paths = [parsed.pathname];\\n            if (base && parsed.pathname.startsWith(`${base}/`)) {\\n              paths.push(parsed.pathname.slice(base.length) || \"/\");\\n            }\\n\\n            for (const path of paths) {\\n              const match = path.match(/^\\\\/(?:plans|recaps)\\\\/([A-Za-z0-9_-]+)\\\\/?$/);\\n              if (match) {\\n                process.stdout.write(`${trusted.origin}${base}/recaps/${match[1]}`);\\n                break;\\n              }\\n            }\\n          } catch {\\n            process.exit(0);\\n          }\\n          NODE\\n          )\\n          if [ -n \"$CANONICAL_URL\" ]; then\\n            echo \"plan_url=$CANONICAL_URL\" >> \"$GITHUB_OUTPUT\"; echo \"ok=true\" >> \"$GITHUB_OUTPUT\"\\n          else\\n            echo \"plan_url=\" >> \"$GITHUB_OUTPUT\"; echo \"ok=false\" >> \"$GITHUB_OUTPUT\"\\n          fi\\n\\n      - name: Summarize agent failure\\n        id: agent_summary\\n        if: steps.url.outputs.ok != \\'true\\' && steps.diff.outputs.tiny != \\'true\\' && steps.scan.outputs.suppressed != \\'true\\'\\n        continue-on-error: true\\n        env:\\n          RECAP_AGENT: ${{ needs.gate.outputs.agent }}\\n        run: |\\n          set -uo pipefail\\n          RESULT=claude-result.json\\n          if [ \"$RECAP_AGENT\" = \"codex\" ]; then RESULT=codex-events.jsonl; fi\\n          $RECAP_CLI recap agent-summary --agent \"$RECAP_AGENT\" --result-file \"$RESULT\" || true\\n\\n      - name: Attach usage\\n        if: steps.url.outputs.ok == \\'true\\'\\n        continue-on-error: true\\n        env:\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          # Use the gate-normalized agent so \"Codex\" still selects the right file.\\n          RECAP_AGENT: ${{ needs.gate.outputs.agent }}\\n        run: |\\n          set -uo pipefail\\n          RESULT=claude-result.json\\n          if [ \"$RECAP_AGENT\" = \"codex\" ]; then RESULT=codex-events.jsonl; fi\\n          if [ -f \"$RESULT\" ]; then $RECAP_CLI recap usage --plan-url \"$PLAN_URL\" --agent \"$RECAP_AGENT\" --result-file \"$RESULT\" --model \"${VISUAL_RECAP_MODEL:-}\" --app-url \"$PLAN_RECAP_APP_URL\" --token \"$PLAN_RECAP_TOKEN\" || true; fi\\n\\n      - name: Cache Playwright browsers\\n        if: steps.url.outputs.ok == \\'true\\'\\n        uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3\\n        with:\\n          path: ~/.cache/ms-playwright\\n          key: playwright-1-${{ runner.os }}\\n\\n      - name: Screenshot + upload\\n        id: shot\\n        if: steps.url.outputs.ok == \\'true\\'\\n        continue-on-error: true\\n        env:\\n          # recap-url.txt is untrusted agent output; pass via env, never ${{ }}.\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n        run: |\\n          set -uo pipefail\\n          pnpm exec playwright install --with-deps chromium 2>/dev/null || npx -y playwright@1 install --with-deps chromium || true\\n          SHOT_JSON=\"$($RECAP_CLI recap shot --url \"$PLAN_URL\" --token \"$PLAN_RECAP_TOKEN\" --app-url \"$PLAN_RECAP_APP_URL\" --out recap.png || echo \\'{}\\')\"\\n          IMAGE_URL=$(node -e \\'try{process.stdout.write(JSON.parse(process.argv[1]).imageUrl||\"\")}catch{process.stdout.write(\"\")}\\' \"$SHOT_JSON\")\\n          echo \"image_url=$IMAGE_URL\" >> \"$GITHUB_OUTPUT\"\\n          if [ -f recap.png ]; then echo \"captured=true\" >> \"$GITHUB_OUTPUT\"; else echo \"captured=false\" >> \"$GITHUB_OUTPUT\"; fi\\n\\n      - name: Upload recap screenshot artifact\\n        if: steps.shot.outputs.captured == \\'true\\'\\n        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1\\n        with:\\n          name: pr-visual-recap-${{ github.event.pull_request.number }}\\n          path: recap.png\\n          if-no-files-found: ignore\\n          retention-days: 14\\n\\n      - name: Upsert sticky comment\\n        if: always()\\n        continue-on-error: true\\n        env:\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          RECAP_IMAGE_URL: ${{ steps.shot.outputs.image_url }}\\n          SUPPRESSED: ${{ steps.scan.outputs.suppressed }}\\n          SUPPRESSED_JSON: ${{ steps.scan.outputs.json }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n          DIFF_TINY: ${{ steps.diff.outputs.tiny }}\\n          PREV_PLAN_ID: ${{ steps.prev.outputs.plan_id }}\\n          RECAP_AUTH_FAILED: ${{ steps.auth_probe.outputs.auth_failed }}\\n          RECAP_AGENT_SUMMARY: ${{ steps.agent_summary.outputs.summary }}\\n        run: |\\n          set -euo pipefail\\n          ARGS=(recap comment upsert --repo \"$GITHUB_REPOSITORY\" --issue \"$PR_NUMBER\" --token \"$GH_TOKEN\")\\n          # On a tiny diff, only REFRESH an existing comment, never create one.\\n          if [ \"${DIFF_TINY:-}\" = \"true\" ]; then ARGS+=(--update-only); fi\\n          $RECAP_CLI \"${ARGS[@]}\"\\n\\n      - name: Complete visual recap check\\n        if: always() && steps.recap_check.outputs.check_run_id != \\'\\'\\n        continue-on-error: true\\n        env:\\n          # Untrusted/step values via env (NOT ${{ }}-interpolated into the run\\n          # body): the agent-written plan URL and the scan JSON could inject shell.\\n          CHECK_RUN_ID: ${{ steps.recap_check.outputs.check_run_id }}\\n          PLAN_OK: ${{ steps.url.outputs.ok }}\\n          PLAN_URL: ${{ steps.url.outputs.plan_url }}\\n          SUPPRESSED: ${{ steps.scan.outputs.suppressed }}\\n          SUPPRESSED_JSON: ${{ steps.scan.outputs.json }}\\n          DIFF_HUGE: ${{ steps.diff.outputs.huge }}\\n          DIFF_TINY: ${{ steps.diff.outputs.tiny }}\\n          RECAP_AGENT_SUMMARY: ${{ steps.agent_summary.outputs.summary }}\\n        run: |\\n          set -uo pipefail\\n          $RECAP_CLI recap check complete \\\\\\n            --check-run-id \"$CHECK_RUN_ID\" \\\\\\n            --plan-ok \"$PLAN_OK\" \\\\\\n            --plan-url \"$PLAN_URL\" \\\\\\n            --suppressed \"$SUPPRESSED\" \\\\\\n            --suppressed-json \"$SUPPRESSED_JSON\" \\\\\\n            --huge \"$DIFF_HUGE\" \\\\\\n            --tiny \"$DIFF_TINY\" \\\\\\n            --failure-summary \"$RECAP_AGENT_SUMMARY\" \\\\\\n            --workflow-url \"$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID\"\\n';\n"]}

package/dist/cli/recap.d.ts

@@ -0,0 +1,453 @@
+/**
+ * `agent-native recap` — the helper surface used by the PR Visual Recap GitHub
+ * Action. Run `agent-native recap help` for the full subcommand list.
+ *
+ * The action no longer generates the recap deterministically. Instead a coding
+ * agent (Claude Code or Codex) RUNS THE REPO'S visual-recap skill against the
+ * diff and publishes the plan via the plan MCP tools. These subcommands are the
+ * thin, deterministic glue around that:
+ *
+ *   gate          The security boundary: decide whether the recap runs at all
+ *                 (skipping drafts, forks, bots, missing secrets, an invalid
+ *                 agent/model, and PRs that touch recap-control files) and which
+ *                 normalized backend agent to use.
+ *   collect-diff  Collect the bounded base...head diff (excluding lockfiles,
+ *                 build output, snapshots), cap it at ~600KB, and classify the
+ *                 huge/tiny flags.
+ *   mcp-config    Write the plan MCP client config for the chosen backend
+ *                 (Claude Code JSON or Codex config.toml).
+ *   scan          Refuse to hand a secret-leaking diff to the agent.
+ *   build-prompt  Assemble the agent prompt = latest visual-recap skill bundle
+ *                 + a task wrapper (or repo-pinned skill with --skill-source).
+ *   shot          Screenshot the published plan and upload it to the plan app's
+ *                 signed public image route (for an inline PR-comment image).
+ *   usage         Parse and emit agent token-usage/cost from stdout.
+ *   comment       Find the previous plan id / upsert the sticky PR comment.
+ *   check         Evaluate the recap result and set a GitHub commit status.
+ *   setup         Install the PR Visual Recap GitHub Action workflow.
+ *   doctor        Diagnose missing secrets / misconfigured workflow.
+ *
+ * Promoting these to the published CLI means an installed repo's workflow calls
+ * `agent-native recap …` instead of copying helper scripts into the repo.
+ *
+ * Node built-ins only (plus an optional dynamic `playwright` import for `shot`).
+ */
+/** GitHub secrets the installed PR Visual Recap workflow needs. */
+export declare const PR_VISUAL_RECAP_SETUP: string[];
+/**
+ * Result of attempting to write the PR Visual Recap workflow.
+ *
+ * - `written` — the file was written (new or forced overwrite).
+ * - `skipped` — the file already exists and is identical; no-op.
+ * - `refused` — the file already exists and differs; nothing was written.
+ *   Caller should re-run with `--force` (or pass `force: true`) to overwrite.
+ */
+export type WriteWorkflowResult = {
+    status: "written";
+    path: string;
+    existed: boolean;
+} | {
+    status: "skipped";
+    path: string;
+} | {
+    status: "refused";
+    path: string;
+    message: string;
+};
+/** Write .github/workflows/pr-visual-recap.yml into a repo. */
+export declare function writePrVisualRecapWorkflow(baseDir: string, options?: {
+    force?: boolean;
+}): WriteWorkflowResult;
+/**
+ * The thin caller workflow that consumers paste into their repo when using the
+ * reusable variant.  It references the canonical reusable workflow in the
+ * BuilderIO/agent-native repo rather than carrying a full copy.
+ *
+ * Callers must trigger on the same `pull_request` event types so that
+ * `github.event.pull_request.*` expressions in the reusable workflow resolve
+ * correctly (workflow_call inherits the caller's event context).
+ *
+ * @param options.cliVersion  Semver or tag to pin (default "main" / latest).
+ * @param options.ref         Git ref to pin the reusable workflow to (default "@main").
+ */
+export declare function buildReusableCallerWorkflow(options?: {
+    ref?: string;
+    agent?: RecapAgentValue;
+    model?: string;
+}): string;
+/** Write the thin caller workflow that references the reusable workflow. */
+export declare function writePrVisualRecapReusableCallerWorkflow(baseDir: string, options?: {
+    force?: boolean;
+    ref?: string;
+    agent?: RecapAgentValue;
+    model?: string;
+}): WriteWorkflowResult;
+type RecapAgentValue = "claude" | "codex";
+export type RecapAgent = "claude" | "codex";
+export declare function normalizeRecapAgent(value: string | undefined): RecapAgent;
+export declare function recapRequiredSecrets(agent: RecapAgent): string[];
+export interface RecapSetupPlan {
+    agent: RecapAgent;
+    appUrl: string;
+    repo?: string;
+    workflowPath: string;
+    workflowExists: boolean;
+    requiredSecrets: string[];
+    variableValues: Record<string, string>;
+    secretValues: Record<string, string | undefined>;
+}
+export declare function buildRecapSetupPlan(input: {
+    baseDir: string;
+    appUrl?: string;
+    agent?: string;
+    repo?: string;
+    env?: NodeJS.ProcessEnv;
+}): RecapSetupPlan;
+export declare function lineLooksSecret(line: string): boolean;
+/**
+ * Parse a `.github/recap-scan-allowlist` file into a list of matchers.
+ * Each non-blank, non-comment line is either:
+ *   - a `/regex/` literal (JS regex syntax) — matched against the full line
+ *   - a plain literal string — checked with String.includes()
+ *
+ * Returns an empty array when the file is absent or empty.
+ */
+export declare function parseRecapScanAllowlist(allowlistPath: string): Array<RegExp | string>;
+/**
+ * Return true when `line` matches ANY entry in the allowlist (i.e., the
+ * finding should be ignored).
+ */
+export declare function lineMatchesAllowlist(line: string, allowlist: Array<RegExp | string>): boolean;
+export declare function diffContainsSecret(diffText: string, allowlist?: Array<RegExp | string>): boolean;
+export declare function sanitizeAgentFailureSummary(value: string, maxChars?: number): string;
+export declare function summarizeAgentResult(agent: string, resultText: string): string;
+/** ~600KB byte cap for the diff handed to the recap agent. */
+export declare const RECAP_DIFF_BYTE_CAP = 614400;
+/** The footer appended when a diff is truncated at the byte cap. */
+export declare const RECAP_DIFF_TRUNCATED_FOOTER = "\n\n[diff truncated at 600KB for the recap agent]\n";
+/**
+ * Classify a bounded diff into the `huge` / `tiny` flags the workflow consumes.
+ *
+ * - huge: BYTES over the ~600KB cap. The agent is told to summarize AND the
+ *   diff file is physically truncated so it can't overflow the prompt budget.
+ * - tiny: <= 1 changed file AND <= 8 changed lines. Uses ORIGINAL line count
+ *   (captured before any truncation) so a large diff is never misclassified as
+ *   tiny after the byte cap drops most of its lines.
+ *
+ * Pure (no I/O) so the classification can be unit-tested without invoking git.
+ */
+export declare function classifyDiff(input: {
+    bytes: number;
+    changed: number;
+    originalLines: number;
+}): {
+    huge: boolean;
+    tiny: boolean;
+};
+/**
+ * Reorder a unified diff's per-file segments so likely-noise paths (paths whose
+ * first component starts with `.`, e.g. `.changeset/`, `.github/`) sort LAST,
+ * and all other paths keep their original git order. This ensures that when
+ * `truncateDiffAtLineBoundary` drops the tail to stay under the byte cap, source
+ * files survive and dotfile dirs are sacrificed instead.
+ *
+ * Pure (string in → string out) for unit testing. The initial preamble (lines
+ * before the first `diff --git` header) is preserved unchanged.
+ */
+export declare function sortDiffSourceFirst(text: string): string;
+/**
+ * Truncate a diff to the ~600KB byte cap at a COMPLETE LINE boundary, then
+ * append the truncated footer. Dropping the last (possibly-partial) line is the
+ * equivalent of the original `head -c 614400 | sed '$d'`: it guarantees the cap
+ * never cuts a multi-byte UTF-8 char or a diff line mid-way and corrupts the
+ * agent's input. Pure (string in, string out) so it can be unit-tested.
+ */
+export declare function truncateDiffAtLineBoundary(text: string): string;
+/**
+ * Count lines that begin with `+` or `-` (added/removed diff lines), excluding
+ * the `+++ b/file` / `--- a/file` unified-diff header lines. Without this
+ * exclusion a single-file change loses ~2 "real" lines from the 8-line tiny
+ * threshold, incorrectly classifying a small-but-meaningful change as tiny.
+ */
+export declare function countDiffLines(diffText: string): number;
+/**
+ * The Claude Code MCP config the recap agent loads: a single HTTP `plan` server
+ * pointing at the app's `/_agent-native/mcp` endpoint, authorized with the
+ * PLAN_RECAP_TOKEN. Pure (returns the JSON string) so it can be unit-tested.
+ */
+export declare function buildRecapClaudeMcpConfig(appUrl: string, token: string | undefined): string;
+/**
+ * The Codex `config.toml` the recap agent loads. JSON.stringify the URL value so
+ * a stray quote/newline in the app URL can't break out of the TOML basic string
+ * (TOML shares JSON's escaping); the key and env-var name stay literal. Pure so
+ * it can be unit-tested.
+ */
+export declare function buildRecapCodexMcpConfig(appUrl: string): string;
+/**
+ * Locate the repo's visual-recap SKILL.md, preferring the host-agent install
+ * locations so a user's `agent-native skills add` copy wins, then falling back
+ * to the framework's own source locations.
+ */
+export declare function readRepoSkillMd(cwd?: string): {
+    text: string;
+    source: string;
+};
+type RecapSkillSourceMode = "auto" | "latest" | "repo";
+export declare function readVisualRecapSkillBundle(cwd?: string, mode?: RecapSkillSourceMode): {
+    text: string;
+    source: string;
+};
+export declare function buildRecapPrompt(input: {
+    skillMd: string;
+    pr: string;
+    repo?: string;
+    head?: string;
+    appUrl: string;
+    diffPath: string;
+    statPath?: string;
+    prevPlanId?: string;
+    huge?: boolean;
+    localFiles?: boolean;
+    localDir?: string;
+    /** Fully-qualified PR URL to store on the plan as the back-link. When
+     *  `repo` is supplied this is auto-derived; pass explicitly to override. */
+    sourceUrl?: string;
+    /**
+     * When true, the diff originates from a fork PR — an external contributor's
+     * branch. Add an explicit prompt-hardening note so the agent treats diff
+     * content as untrusted user data, never as instructions. This does NOT change
+     * what the agent is allowed to do; it is a reminder that the diff text is
+     * attacker-controlled input to an LLM that holds a publish token.
+     */
+    forkPr?: boolean;
+    /**
+     * Byte size of the (possibly truncated) diff file — used to emit a
+     * consumption instruction so the agent knows how large the file is and reads
+     * it in full before authoring. When omitted, no size instruction is emitted.
+     */
+    diffBytes?: number;
+    /**
+     * Line count of the (possibly truncated) diff — same purpose as diffBytes.
+     */
+    diffLines?: number;
+}): string;
+type GitHubComment = {
+    id: number;
+    body?: string | null;
+    html_url?: string;
+    user?: {
+        type?: string | null;
+    } | null;
+};
+export declare function findExistingComment(input: {
+    token: string;
+    owner: string;
+    repo: string;
+    issue: string;
+    /** @internal test seam — defaults to global fetch */
+    fetchFn?: typeof fetch;
+}): Promise<GitHubComment | null>;
+export declare function upsertComment(input: {
+    token: string;
+    owner: string;
+    repo: string;
+    issue: string;
+    body: string;
+    /** When true, refresh an existing comment but never create a new one. */
+    updateOnly?: boolean;
+    /** @internal test seam — defaults to global fetch */
+    fetchFn?: typeof fetch;
+}): Promise<{
+    action: "created" | "updated" | "skipped";
+    id: number;
+    html_url?: string;
+}>;
+/** Build the sticky comment body from the workflow's environment. */
+export declare function buildCommentBody(env?: NodeJS.ProcessEnv): string;
+/**
+ * Confirm GitHub can fetch the uploaded image anonymously before we embed it.
+ *
+ * Default budget: 8 attempts with capped exponential backoff (1s, 2s, 3s, …
+ * capped at 4s) → ~20s total. This is enough to survive a cold-start CDN
+ * propagation delay that would otherwise cause `uploadRecapImage` to return a
+ * URL that the GitHub PR comment can't display.
+ *
+ * The `attempts` and `delayMs` overrides remain for unit tests and for callers
+ * that need a tighter or looser budget.
+ */
+export declare function waitForPublicRecapImage(input: {
+    imageUrl: string;
+    attempts?: number;
+    delayMs?: number;
+    fetchFn?: typeof fetch;
+}): Promise<boolean>;
+/** Upload a PNG to the plan app's signed public image route; returns its URL. */
+export declare function uploadRecapImage(input: {
+    appUrl: string;
+    token: string;
+    pngPath: string;
+    /** @internal test seam — defaults to global fetch */
+    fetchFn?: typeof fetch;
+    /** @internal test seam — defaults to waitForPublicRecapImage */
+    waitFn?: typeof waitForPublicRecapImage;
+}): Promise<string | null>;
+type PlaywrightModule = {
+    chromium: import("playwright").BrowserType;
+};
+export declare function withRecapScreenshotParams(url: string): string;
+export declare function runShot(args: Record<string, string | boolean>, 
+/** @internal test seam — defaults to dynamic playwright import */
+importPlaywright?: () => Promise<PlaywrightModule>): Promise<void>;
+/**
+ * Minimal shape of the `pull_request` object from a GitHub `pull_request` event
+ * payload that the gate inspects. Everything is optional so a malformed/partial
+ * payload degrades to "skip" rather than throwing.
+ */
+export interface RecapGatePullRequest {
+    number?: number;
+    draft?: boolean;
+    head?: {
+        repo?: {
+            full_name?: string | null;
+        } | null;
+    } | null;
+    user?: {
+        login?: string | null;
+        type?: string | null;
+    } | null;
+}
+export interface RecapGateInput {
+    /** The `pull_request` payload object, or null when absent. */
+    pr: RecapGatePullRequest | null;
+    /** GITHUB_REPOSITORY ("owner/name"). */
+    repository: string | undefined;
+    /** PLAN_RECAP_TOKEN present. */
+    hasPlan: boolean;
+    /** ANTHROPIC_API_KEY present. */
+    hasAnthropic: boolean;
+    /** OPENAI_API_KEY present. */
+    hasOpenai: boolean;
+    /** Raw VISUAL_RECAP_AGENT value (may be undefined / mis-cased). */
+    agentRaw: string | undefined;
+    /** Raw VISUAL_RECAP_MODEL value (may be undefined). */
+    model: string | undefined;
+    /** Filenames changed by the PR (for the self-modifying guard). */
+    changedFiles: string[];
+}
+/**
+ * Files that, if a PR touches them, would let that PR rewrite what the trusted
+ * recap job runs (the workflow itself, the skill, the local CLI, or any agent
+ * config the runner loads) — so the whole job is skipped, not just the agent
+ * step, to keep untrusted PR code away from the publish/API secrets.
+ *
+ * The `packages/core/**` rule is scoped to the BuilderIO/agent-native monorepo
+ * (where packages/core IS the recap CLI source) so that consumer repos with an
+ * unrelated `packages/core/` directory are not silently gated. Pass the
+ * `repository` ("owner/name") to apply that scoping; omit it to match the old
+ * unconditional behaviour (safe for the gate's self-test).
+ */
+export declare function isRecapSensitivePath(p: string, repository?: string): boolean;
+/**
+ * The pure gate decision: given the PR payload, secret-presence flags, the
+ * configured backend/model, and the PR's changed files, decide whether the
+ * visual recap should run, which (normalized) agent to use, and — when skipped —
+ * the human-readable reasons. This is the security boundary; it replicates the
+ * inline github-script gate bit-for-bit. No I/O so it can be unit-tested.
+ */
+export declare function evaluateRecapGate(input: RecapGateInput): {
+    run: boolean;
+    agent: string;
+    reasons: string[];
+};
+/**
+ * Build the short skip-line appended to an existing recap comment when the
+ * gate skips. Pure so it can be unit-tested.
+ *
+ * @param reason    - Human-readable skip reason (primary reason, short).
+ * @param headShort - 7-char short SHA, or "" if unavailable.
+ */
+export declare function buildGateSkipLine(reason: string, headShort: string): string;
+/**
+ * Append (or replace the last gate-skip line in) a sticky comment body.
+ * Idempotent: calling it twice with different skip lines replaces the old one.
+ * Pure so it can be unit-tested.
+ */
+export declare function appendGateSkipLine(existingBody: string, skipLine: string): string;
+/**
+ * Canonicalize the agent-written plan URL into a trusted recap URL, or "".
+ *
+ * recap-url.txt is produced by the (LLM) agent, so the raw URL is untrusted.
+ * This rebuilds a canonical `${origin}${base}/recaps/<id>` link from the TRUSTED
+ * app URL plus a strictly-validated plan id, enforcing the app origin and
+ * honoring a path-prefixed mount (e.g. https://host/agent-native). Returns ""
+ * for a wrong origin or an unrecognized path. Pure so it can be unit-tested —
+ * SAME impl as the workflow's previous inline `canonicalRecapUrl`.
+ */
+export declare function canonicalRecapUrl(rawUrl: string, appUrl: string): string;
+/** The signals that decide the completed "Visual Recap" check's conclusion. */
+export interface RecapCheckOutcomeInput {
+    /** steps.url.outputs.ok — the agent published a plan whose origin validated. */
+    planOk: boolean;
+    /** steps.url.outputs.plan_url — the (untrusted) agent-written plan URL. */
+    planUrl: string;
+    /** PLAN_RECAP_APP_URL — the trusted plan app origin/base. */
+    appUrl: string;
+    /** steps.diff.outputs.huge — the diff exceeded the byte cap (summarized). */
+    huge: boolean;
+    /** steps.diff.outputs.tiny — the diff was too small to recap. */
+    tiny: boolean;
+    /** steps.scan.outputs.suppressed — a secret pattern suppressed the recap. */
+    suppressed: boolean;
+    /** steps.scan.outputs.json — the raw scan JSON (carries the suppress reason). */
+    suppressedJson: string;
+    /** Sanitized final agent output when no valid plan URL was produced. */
+    failureSummary?: string;
+    /** The Actions run URL, used as the default details_url. */
+    workflowUrl: string;
+}
+/** The completed-check fields PATCHed to the GitHub check run. */
+export interface RecapCheckOutcome {
+    conclusion: "neutral" | "success" | "skipped";
+    title: string;
+    summary: string;
+    text: string;
+    detailsUrl: string;
+}
+/**
+ * Map the workflow's terminal recap state to the completed check's
+ * conclusion/title/summary/text/details_url. Pure so it can be unit-tested —
+ * reproduces the workflow's previous inline branch logic EXACTLY:
+ *
+ * - default → neutral "Visual recap not generated"
+ * - planOk + valid recapUrl → success "Visual recap ready" (huge → "summarized"
+ *   summary), Open-recap link as text, details_url = recapUrl
+ * - planOk + invalid url → neutral "Visual recap published" (see the comment)
+ * - else tiny → skipped "Visual recap skipped"
+ * - else suppressed → skipped "Visual recap suppressed" (reason from scan JSON)
+ */
+export declare function recapCheckOutcome(input: RecapCheckOutcomeInput): RecapCheckOutcome;
+interface ParsedUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    model?: string;
+    reportedCostUsd?: number;
+}
+/**
+ * Claude Code `-p --output-format json` prints one final result object with a
+ * `usage` block and `total_cost_usd`. Anthropic's `input_tokens` already
+ * EXCLUDES cache tokens, so no normalization is needed here.
+ */
+export declare function parseClaudeUsage(stdout: string): ParsedUsage | null;
+/**
+ * Codex `exec --json` reports `input_tokens` INCLUSIVE of `cached_input_tokens`
+ * (OpenAI counts cached as a subset of prompt tokens) and bills
+ * `reasoning_output_tokens` separately. Normalize to the cache-exclusive shape
+ * `calculateCost` expects: strip cached out of input, fold reasoning into
+ * output. Without this, cached tokens are billed twice and reasoning is dropped.
+ */
+export declare function parseCodexUsage(jsonl: string): ParsedUsage | null;
+export declare function runRecap(argv: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=recap.d.ts.map

package/dist/cli/recap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../../src/cli/recap.ts"],"names":[],"mappings":"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"}