feat: update-readme GitHub Action (#28, 2/2)

[adrianbrowning]

Closes #28. Stacked on #57 (check-sync); review and merge that first.

Summary

The second action #28 asks for: treat source files as authoritative and open, or refresh, one pull request that holds only the Markdown changes.

+.github/actions/update-readme/
+  action.yml          composite: setup-node (pinned SHA) → node update-readme.mjs
+  update-readme.mjs
+    worktree at the fetched tip of base-branch       (caller's checkout never touched)
+      mdcode update --apply --json <documents>       (Markdown only; nothing if any block fails)
+      commit → refuse unless it changes exactly the documents update wrote
+      force-push `branch` only if its tree or base differs   (idempotent reruns)
+      gh pr create, or gh pr edit the open one
+    already in sync → close its open PR with a comment, keep the branch
+.github/actions/shared/mdcode.mjs   helpers moved out of check-sync, used by both

Decisions (agreed before starting):

• PR step bundled, using only git and gh, both preinstalled on GitHub runners. No third-party actions.
• Idempotent. One fixed branch (mdcode/update-docs). A rerun with nothing new pushes nothing and edits the existing PR instead of opening another.
• Already in sync → close the open PR. You confirmed this: merging that PR would put the docs out of sync again. Closing is reversible, and the branch is kept.

Safety:

• Never pushes to the base branch. branch equal to base-branch is an error, exit 2.
• Never commits a source file. The commit must change exactly the documents update wrote, or the action refuses to push.
• Always on the base tip. The update is computed in a worktree at the tip of base-branch. Staged or unrelated changes in the caller's checkout can't leak in, and a checkout that is behind still produces a PR on the tip.
• Token. It is passed to git as a one-off auth header that replaces the credentials actions/checkout stored. It is never written to git config.
• Permissions. The docs list contents: write and pull-requests: write, and explain that PRs opened with GITHUB_TOKEN don't start workflows (pass an App token or a fine-grained PAT). They also say never to run the action on pull_request_target or on a fork's code.

Evidence

update-readme-action.test.ts (8 tests) runs the script against a local bare repository, which stands in for GitHub, and a stand-in gh that records its calls:

• It opens a PR whose commit changes only README.md and my docs/guide.md, with paths containing spaces. src/greet.ts is untouched, the commit's parent is main's tip, and main itself is never pushed. The caller's checkout keeps its staged notes.txt and its HEAD. The PR body lists each block and its source.
• A rerun says Already up to date: #1 and doesn't push or open a second PR.
• When the sources change again, it says Refreshed #1, with the new commit on main's new tip.
• When the checkout is behind main, the PR is still based on main's tip.
• With everything already in sync, it does nothing (changed=false) and only calls gh pr list.
• After the update is merged by hand, it says Closed #1.
• When a file= can't be read, it exits 1 with ::error file=README.md,line=5,title=mdcode read_failed::…. The message names the caller's checkout, not the worktree. Nothing is pushed and gh is never called.
• branch: main exits 2.

check-sync-action.test.ts (8 tests) still passes with check-sync's helpers moved to the shared module. pnpm check passes. intent maintainer check --base origin/feat/28-github-actions shows 0 pending.

Not verified: a live run against github.com. gh was stubbed.

Merge Danger

Door: two-way

Blast Radius: consumer repos

This is a new action, and only consumers who add it run it. When it does run, it can force-push one branch it owns and open, edit or close one PR. It doesn't change the CLI.

[github-actions]

The changes in this PR will be included in the next version bump.

Minor releases

• mdcode-ts 0.0.4 → 0.1.0

Bump files in this PR

• update-readme-action.md (view diff) (edit)

Click here if you want to add another bump file to this PR

---

This comment is maintained by bumpy.