chore: merge upstream jocmp/capyreader main

.github/CODEX_LOOP.md

@@ -0,0 +1,52 @@
+# Codex ↔ Claude review loop
+
+Mirrors the (now-disabled) Copilot ↔ Claude loop documented in `COPILOT_LOOP.md`, but driven by the ChatGPT Codex Connector instead of GitHub Copilot.
+
+## Files involved
+
+- `.github/workflows/claude.yml` — generic `@claude` mention responder (shared across loops).
+- `.github/workflows/claude-fix-codex-review.yml` — fires when Codex submits a review; Claude addresses the feedback and pushes back to the PR branch.
+
+There is no `setup-codex-loop.yml` analog: Codex auto-review-on-push is configured in the Codex web UI, not via a GitHub ruleset.
+
+## One-time setup per repo
+
+1. **Create two secrets** in *Settings → Secrets and variables → Actions*:
+   - `CLAUDE_CODE_OAUTH_TOKEN` — from `claude setup-token` (or the Claude Code install flow).
+   - `CODEX_LOOP_PAT` — a fine-grained Personal Access Token scoped to just this repo with:
+     - Contents: **Read and write**
+     - Pull requests: **Read and write**
+
+   This PAT can be the same value as `COPILOT_LOOP_PAT` if that already exists — the permissions are identical. Two distinct secret names just keep the two loops independently configurable.
+
+2. **Enable Codex auto-review on push** in the Codex web UI for this repo. Without that setting, the loop terminates after one round because nothing re-triggers Codex on Claude's push.
+
+3. Open a PR; once Codex has reviewed it once, every subsequent push triggers the next Codex round automatically (until Codex has no feedback left, or the iteration cap is hit).
+
+## Why a PAT?
+
+Defensive design. The Copilot version uses a PAT because GitHub's `copilot_code_review` ruleset silently ignores `github-actions[bot]` pushes (verified empirically — bot pushes produce no `review_requested` event). It's not yet confirmed whether Codex's auto-review setting has the same restriction. If observation across the first few PRs shows Codex re-fires on bot pushes, the PAT can be dropped and the workflow simplified to use the default `GITHUB_TOKEN`.
+
+## Iteration cap
+
+`claude-fix-codex-review.yml` has `MAX_CODEX_ITERATIONS: 7`. After that many Codex reviews on a single PR, Claude posts a comment and stops auto-fixing so humans can take over. Bump the env var if you want more rounds.
+
+## Project-specific check commands
+
+The prompt in `claude-fix-codex-review.yml` mentions Capy-specific check commands (`make` and `make check` for `.js`/`.liquid` changes; skip `./gradlew` because no Android SDK is installed on the runner). When copying to another repo, edit that paragraph to point at the destination repo's lightweight check commands.
+
+## Coexistence with the Copilot loop
+
+`claude-fix-copilot-review.yml` is still on disk but its `on:` trigger has been neutered to `workflow_dispatch:` only — it will not fire on PR events. To re-enable Copilot, restore the original `pull_request_review:` trigger.
+
+The GitHub-side `copilot_code_review` ruleset created by `setup-copilot-loop.yml` still exists and may still cause Copilot to post reviews on every push. Disabling the Claude-fix workflow stops Claude from acting on those reviews, but does not stop Copilot from posting them. To fully retire Copilot:
+
+```bash
+# List rulesets to find the id
+gh api "repos/<owner>/<repo>/rulesets"
+
+# Delete the copilot_code_review ruleset (use the id from above)
+gh api --method DELETE "repos/<owner>/<repo>/rulesets/<ruleset-id>"
+```
+
+Or disable it via the GitHub UI (Settings → Rules → Rulesets → "Copilot auto review for all branches" → Disable).

.github/COPILOT_LOOP.md

@@ -0,0 +1,34 @@
+# Copilot ↔ Claude review loop
+
+> **Status (2026-04-23):** This loop is **disabled** in this repo — the active review-fix loop is now `CODEX_LOOP.md`. The workflow file `claude-fix-copilot-review.yml` has had its `on:` trigger neutered to `workflow_dispatch:` only. To re-enable, restore the original `pull_request_review` trigger.
+
+Copy these three workflows into another repo and the loop works after a one-time secret + setup-workflow step. No GitHub web-UI settings, no per-repo file edits.
+
+## Files to copy
+
+- `.github/workflows/claude.yml` — responds to `@claude` mentions in issues / PR comments.
+- `.github/workflows/claude-fix-copilot-review.yml` — fires when Copilot submits a review; Claude fixes the feedback and pushes back to the PR branch.
+- `.github/workflows/setup-copilot-loop.yml` — one-shot, creates the `copilot_code_review` ruleset so pushes by the PAT owner auto-trigger the next Copilot review.
+
+## One-time setup per repo
+
+1. **Create two secrets** in *Settings → Secrets and variables → Actions*:
+   - `CLAUDE_CODE_OAUTH_TOKEN` — from `claude setup-token` (or the Claude Code install flow).
+   - `COPILOT_LOOP_PAT` — a fine-grained Personal Access Token scoped to just this repo with:
+     - Contents: **Read and write**
+     - Pull requests: **Read and write**
+     - Administration: **Read and write** — this is the permission that covers creating/updating rulesets. Only needed while running `setup-copilot-loop`; you can remove it afterward and regenerate the PAT with just Contents + Pull requests.
+2. **Run the setup workflow once.** Actions tab → *Setup Copilot ↔ Claude loop* → *Run workflow*. It creates/updates the ruleset via the REST API.
+3. Open a PR and request a Copilot review on it once — from then on, every Claude push triggers the next Copilot round until Copilot has no feedback left (or the iteration cap is hit).
+
+## Why the PAT is unavoidable
+
+GitHub's `copilot_code_review` ruleset silently ignores pushes authenticated as `github-actions[bot]` (verified empirically on PR #21, 2026-04-20 — bot pushes produced no `review_requested` event, user pushes did). The REST endpoint `POST /pulls/{n}/requested_reviewers` with `copilot-pull-request-reviewer` is not a reliable fallback either. So the loop depends on Claude's push being attributed to a real user; the PAT provides that identity. Everything *else* (the ruleset, the git author config) is automated by the workflows.
+
+## Iteration cap
+
+`claude-fix-copilot-review.yml` has `MAX_COPILOT_ITERATIONS: 5`. After that many Copilot reviews on a single PR, Claude posts a comment and stops auto-fixing so humans can take over. Bump the env var if you want more rounds.
+
+## Project-specific check commands
+
+The prompt in `claude-fix-copilot-review.yml` mentions `ego_sdk/flutter/bin/flutter analyze` / `flutter test` as the checks Claude should run before committing. When copying to another repo, edit that single `run the project checks` paragraph to point at the destination repo's build/test commands. Nothing else in the workflow is repo-specific.

.github/workflows/build-release.yml

@@ -0,0 +1,106 @@
+name: Build and Publish Release APK
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: "Release tag (e.g. v2026.04.1). Leave blank to derive one from the date + run number."
+        required: false
+        type: string
+      prerelease:
+        description: "Mark as prerelease"
+        required: false
+        type: boolean
+        default: false
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: build-release-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build free release APK
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: "zulu"
+          java-version: "21"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Resolve tag name
+        id: tag
+        run: |
+          if [ -n "${{ github.event.inputs.tag_name }}" ]; then
+            TAG="${{ github.event.inputs.tag_name }}"
+          elif [ "${{ github.ref_type }}" = "tag" ]; then
+            TAG="${{ github.ref_name }}"
+          else
+            TAG="v$(date -u +'%Y.%m.%d')-build.${{ github.run_number }}"
+          fi
+          echo "name=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "Resolved tag: ${TAG}"
+
+      - name: Configure signing
+        env:
+          ENCODED_RELEASE_KEYSTORE: ${{ secrets.ENCODED_RELEASE_KEYSTORE }}
+          ENCODED_SECRETS_PROPERTIES: ${{ secrets.ENCODED_SECRETS_PROPERTIES }}
+        run: |
+          if [ -n "${ENCODED_RELEASE_KEYSTORE}" ] && [ -n "${ENCODED_SECRETS_PROPERTIES}" ]; then
+            echo "Using release keystore from repository secrets"
+            printf '%s' "${ENCODED_RELEASE_KEYSTORE}" | base64 --decode > ./release.keystore
+            printf '%s' "${ENCODED_SECRETS_PROPERTIES}" | base64 --decode > ./secrets.properties
+          else
+            echo "No release secrets found — falling back to committed debug.keystore"
+            cp debug.keystore release.keystore
+            printf '%s\n' 'store_password=android' 'key_alias=androiddebugkey' 'key_password=android' > secrets.properties
+          fi
+
+      - name: Build free release APK
+        run: ./gradlew :app:assembleFreeRelease --no-daemon --stacktrace
+
+      - name: Stage APK artifact
+        id: artifact
+        run: |
+          SRC="$(ls app/build/outputs/apk/free/release/app-free-release*.apk | head -n 1)"
+          if [ -z "${SRC}" ] || [ ! -f "${SRC}" ]; then
+            echo "APK not found in app/build/outputs/apk/free/release/" >&2
+            ls -R app/build/outputs/apk || true
+            exit 1
+          fi
+          mkdir -p release-artifacts
+          DEST="release-artifacts/capyreader-${{ steps.tag.outputs.name }}.apk"
+          cp "${SRC}" "${DEST}"
+          echo "path=${DEST}" >> "$GITHUB_OUTPUT"
+
+      - name: Upload APK workflow artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: capyreader-${{ steps.tag.outputs.name }}
+          path: ${{ steps.artifact.outputs.path }}
+          if-no-files-found: error
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.tag.outputs.name }}
+          name: ${{ steps.tag.outputs.name }}
+          draft: false
+          prerelease: ${{ github.event.inputs.prerelease == 'true' }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: ${{ steps.artifact.outputs.path }}

.github/workflows/claude-fix-codex-review.yml

@@ -0,0 +1,153 @@
+name: Claude Fix Codex Review
+
+# The fix half of the Codex ↔ Claude review loop. Fires whenever the ChatGPT
+# Codex Connector submits a review, lets Claude address the feedback, and
+# pushes the fixes back to the PR branch. The push is attributed to the
+# CODEX_LOOP_PAT owner so that Codex's "auto-review on push" UI setting
+# re-fires the next round of review (it's not yet known whether Codex
+# auto-review fires on github-actions[bot] pushes — using the PAT is the
+# safe default; can be simplified later if observation confirms bot-push
+# auto-review works).
+#
+# Portability: no repo-specific values here other than the project-specific
+# pre-commit checks paragraph in the prompt. See .github/CODEX_LOOP.md for
+# setup instructions.
+
+on:
+  pull_request_review:
+    types: [submitted]
+
+env:
+  # Hard cap on Codex review iterations per PR. Once Codex has submitted
+  # this many reviews, Claude stops auto-fixing and asks for manual review.
+  MAX_CODEX_ITERATIONS: 7
+
+jobs:
+  fix-codex-review:
+    # Only run when the ChatGPT Codex Connector is the reviewer, and skip
+    # fork PRs — we need write access to the PR branch to push fixes.
+    if: |
+      github.event.review.user.login == 'chatgpt-codex-connector[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: read
+      id-token: write
+      actions: read
+    steps:
+      - name: Verify CODEX_LOOP_PAT secret is configured
+        env:
+          CODEX_LOOP_PAT: ${{ secrets.CODEX_LOOP_PAT }}
+        run: |
+          if [ -z "${CODEX_LOOP_PAT:-}" ]; then
+            echo "::error::CODEX_LOOP_PAT secret is missing. Add it — see .github/CODEX_LOOP.md." >&2
+            exit 1
+          fi
+
+      - name: Check Codex iteration cap
+        id: cap
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          count=$(gh api --paginate \
+            "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews" \
+            --jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]")] | length' \
+            | awk '{s+=$1} END {print s+0}')
+          echo "Codex reviews so far: $count (cap: $MAX_CODEX_ITERATIONS)"
+          if [ "$count" -ge "$MAX_CODEX_ITERATIONS" ]; then
+            gh pr comment ${{ github.event.pull_request.number }} --body \
+              "Claude auto-fix stopped after $count Codex review iterations (cap: $MAX_CODEX_ITERATIONS). Remaining feedback needs manual attention."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout PR head branch
+        if: steps.cap.outputs.skip != 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+          # Push as the PAT owner (not github-actions[bot]) so that Codex's
+          # auto-review-on-push setting fires reliably on the next push.
+          token: ${{ secrets.CODEX_LOOP_PAT }}
+
+      - name: Derive git identity from PAT owner
+        if: steps.cap.outputs.skip != 'true'
+        # Attribute commits to the PAT owner via their GitHub noreply email so
+        # they show up as regular user-authored commits on the PR timeline.
+        # Derived at runtime so this file is portable across repos/owners.
+        env:
+          GH_TOKEN: ${{ secrets.CODEX_LOOP_PAT }}
+        run: |
+          set -euo pipefail
+          owner_json=$(gh api /user)
+          login=$(jq -r '.login' <<<"$owner_json")
+          id=$(jq -r '.id' <<<"$owner_json")
+          name=$(jq -r '.name // .login' <<<"$owner_json")
+          git config user.name "$name"
+          git config user.email "${id}+${login}@users.noreply.github.com"
+
+      # We intentionally use the sub-path `base-action` instead of the
+      # top-level `anthropics/claude-code-action@v1`. The top-level action's
+      # `checkHumanActor` unconditionally calls `GET /users/<actor>` before
+      # consulting `allowed_bots`, and that crashes for some bot logins. The
+      # base-action skips all actor/permission checks and just runs Claude
+      # Code with our prompt — the job-level `if:` already restricts execution
+      # to Codex reviews on same-repo PRs.
+      - name: Run Claude Code to address Codex review
+        if: steps.cap.outputs.skip != 'true'
+        uses: anthropics/claude-code-action/base-action@v1
+        timeout-minutes: 30
+        env:
+          # Use the PAT so Claude's `gh api` calls (inline review replies,
+          # PR comments, etc.) are attributed to the PAT owner instead of
+          # github-actions[bot]. Matches the git push identity set above.
+          GH_TOKEN: ${{ secrets.CODEX_LOOP_PAT }}
+          GITHUB_TOKEN: ${{ secrets.CODEX_LOOP_PAT }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            The ChatGPT Codex Connector just submitted a review on PR #${{ github.event.pull_request.number }}
+            (review id ${{ github.event.review.id }}). Address its feedback so that the Codex ↔ Claude
+            review-fix loop can continue until Codex has no more issues.
+
+            1. Fetch the review body and all inline comments attached to it:
+                 gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews/${{ github.event.review.id }}
+                 gh api --paginate repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments
+               Only act on inline comments whose `pull_request_review_id` equals ${{ github.event.review.id }}.
+
+            2. For each comment, decide whether the suggestion is valid:
+               - If it is a legitimate bug, code smell, or style issue, fix it by editing the code on the PR branch.
+               - If it is a false positive, leave the code alone and reply to that specific comment explaining why.
+
+            3. Before committing, run ONLY the cheap checks that can realistically finish in this
+               runner (no Android SDK is installed and no Gradle cache is warmed, so a cold
+               `./gradlew assembleFreeDebug` will hang for tens of minutes downloading SDK
+               components and typically fail on license acceptance — do NOT run it here).
+               - Kotlin/Android changes: rely on the repo's existing `test.yml` CI workflow to
+                 validate the build after you push. Do not invoke `./gradlew` from this job.
+                 Limit yourself to static reasoning (read the code, check types by inspection)
+                 and, at most, `./gradlew help` or `./gradlew :<module>:tasks --offline` as a
+                 sanity check — and even those only if you can confirm the Gradle daemon starts
+                 within a minute. If in doubt, skip the check entirely and push; CI will catch it.
+               - `.js` / `.liquid` asset changes: run `make` to recompile assets, then `make check`
+                 to typecheck. These do not need the Android SDK and are safe to run here.
+               If you are running this workflow on a different repo, substitute the project's own
+               lightweight check commands — never a full Android build.
+
+            4. Commit each logical group of fixes with a message like
+               `fix: address Codex review feedback on <topic>` and push to the PR branch.
+               Do not force-push, do not amend existing commits, and do not resolve review conversations.
+
+            5. Do NOT manually request a Codex re-review. Codex's "auto-review on push" UI
+               setting handles re-triggering when the next push lands. If you pushed nothing
+               (all comments were false positives or the review was purely approving), the loop
+               terminates naturally — do not post an empty review or comment.
+
+            A workflow-level cap (MAX_CODEX_ITERATIONS = ${{ env.MAX_CODEX_ITERATIONS }}) will stop
+            this job from running after too many Codex review rounds, so you do not need to track that yourself.
+          claude_args: '--allowed-tools Bash(gh:*),Bash(git:*),Bash(make:*),Edit,Write,Read,Grep,Glob'