record-screenshots

name	record-screenshots
description	Push branch to GitHub, run the record-snapshots workflow, fetch the screenshot commit it creates, and fold it into the appropriate commit via fixup + autosquash.
allowed-tools	Bash, Read, Grep, Glob

Record updated Paparazzi snapshots for the current branch and fold the resulting CI commit into the right local commit.

Steps

1. Capture branch state

git branch --show-current
git log --oneline develop..HEAD

Note the current branch name and list of commits since develop.

2. Push to origin

git push origin HEAD

If this fails (rejected), explain why and stop — do not force-push without user confirmation.

3. Trigger the workflow

Before triggering, check whether a run is already in progress for this branch:

gh run list --workflow=record-snapshots.yml --branch=<branch> --limit=1 --json databaseId,status,conclusion

If a run is already in_progress or queued, inform the user and ask whether to wait for that run or trigger a new one. Otherwise, trigger:

gh workflow run record-snapshots.yml --ref <branch>

Wait a few seconds for GitHub to register the run, then get its ID:

sleep 5
gh run list --workflow=record-snapshots.yml --branch=<branch> --limit=1 --json databaseId,status,conclusion

4. Wait for completion

gh run watch <run-id> --interval 30

If the conclusion is not success, fetch and display the run log and stop:

gh run view <run-id> --log-failed

5. Fetch the screenshot commit

git fetch origin <branch>

Check how many new commits the remote has:

git log --oneline HEAD..origin/<branch>

• 0 commits ahead: no snapshots changed (CI skipped the commit) — inform the user and stop.
• 1 commit ahead: proceed.
• More than 1 commit ahead: warn the user and stop — the situation is unexpected and needs manual handling.

6. Find the target commit

Look for the most recent commit on the branch (i.e. in develop..HEAD) that touched Paparazzi test sources or related composables. Check in this order:

a. Commits that modified *Paparazzi*.kt files:

git log --oneline develop..HEAD -- '*Paparazzi*.kt'

b. If none found, commits that modified Composable UI source files (files in main source sets containing @Composable):

git log --oneline develop..HEAD -- $(grep -rl "@Composable" --include="*.kt" . | grep "/src/main/")

c. If still none found, commits that modified any test source file:

git log --oneline develop..HEAD -- '*/src/test/**' '*/src/androidTest/**'

If there are multiple candidates at any step, show them and ask the user which commit the screenshots belong to before proceeding.

7. Apply the snapshot changes locally

The CI commit may add new snapshots, delete old ones (e.g. when a package was renamed), or both. Handle all cases:

# Get the full diff between local HEAD and the remote screenshot commit
git diff --name-only HEAD origin/<branch>
git diff --name-status HEAD origin/<branch>

For files marked A (added) or M (modified) — stage them at the remote version:

git checkout origin/<branch> -- <file> [<file> ...]

For files marked D (deleted) — remove them:

git rm <file> [<file> ...]

Do not use a single git checkout origin/<branch> -- $(git diff --name-only ...) shortcut, as it cannot handle deletions (checking out a deleted file would re-create it instead of removing it).

8. Create a fixup commit

git commit --fixup=<target-sha>

9. Rebase with autosquash

Calculate how many commits back to rebase (number of commits in develop..HEAD plus the new fixup commit):

N=$(git rev-list --count develop..HEAD)
GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash HEAD~$((N + 1))

If the rebase fails (conflict), explain the conflict and stop — do not attempt to auto-resolve.

10. Confirm and force-push

Show the user the resulting log:

git log --oneline develop..HEAD

Ask for explicit confirmation before force-pushing. Then, with confirmation:

git push --force-with-lease origin <branch>

Use --force-with-lease (not --force) to guard against unexpected remote changes.