chore: Prevent PRs from touching dist folder

[brunoborges]

The dist/ folder contains compiled TypeScript output that should be generated by automation, not edited by hand in PRs. We should:

• Block or flag PRs that modify dist/ directly.
• Define a clear policy for when and how the build is triggered (e.g., on release, via CI, or a bot commit).

[brunoborges]

Policy options for triggering the dist/ build — pro/con

Note: the repo already has check-dist.yml, which validates that the committed dist/ matches a fresh build of the source. The options below are about when/how the build is produced.

Option A — Status quo: contributor builds & commits dist/, CI validates

Pros

• Already implemented — zero migration cost.
• main is always immediately runnable as an action (Actions consumes the committed dist/, not source).
• Tamper-evident: reviewer + CI can diff dist/ against source; supply-chain integrity is verifiable in the PR.
• No bot write permissions needed.

Cons

• Noisy minified diffs clutter review and blame.
• Frequent merge conflicts in dist/ across concurrent PRs.
• Friction for contributors who forget to rebuild → red CI and back-and-forth.
• Detects drift but doesn't prevent hand-edits to dist/.

Option B — CI auto-builds and commits dist/ back to the PR branch (bot commit)

Pros

• Contributors never touch dist/ — directly satisfies the "prevent PRs from touching dist" goal.
• main stays immediately runnable.
• Eliminates "you forgot to rebuild" churn.

Cons

• Security: requires write-back to PR branches. pull_request_target / pushing to forks is a known privilege-escalation vector; building untrusted PR code with elevated tokens is risky.
• Pushing to forks from upstream needs a PAT/app token; permissions are awkward.
• Bot commits can race with contributor pushes and trigger re-run loops.
• Still large diffs, just authored by a bot — and harder to attribute for supply-chain trust.

Option C — Build only at release time (remove dist/ from main)

Pros

• Cleanest main: no generated artifacts, no diff noise, no conflicts.
• Fully prevents PRs from touching dist/ (it isn't there).
• Build provenance centralized in one trusted, audited release workflow.

Cons

• Breaks @main/SHA pinning: users who pin to a branch or commit would get a non-runnable action. Major compatibility risk for a popular action.
• e2e/branch tests that reference the action by ref need a build step everywhere.
• More complex release tooling; release becomes a single point of failure.
• Requires reworking the release npm script and release-new-action-version.yml.

Option D — Build on merge to main (post-merge bot commit)

Pros

• Clean PRs (no dist/) while main still ships a runnable dist/.
• @main and tags keep working.
• Build runs on trusted main code, not untrusted PR code → safer than Option B.

Cons

• Interleaves bot "rebuild" commits into main history.
• Brief window where merged main is stale until the bot commit lands (can break a SHA pinned to the merge commit).
• Needs bot push access to protected main (app token / branch-protection exception).
• Two-step merge; a failed post-merge build leaves main inconsistent.

---

Recommendation

For a high-traffic action where users pin to branches/SHAs, keeping dist/ on main rules out Option C. Strongest combination:

• Keep Option A's check-dist validation (integrity guarantee), plus
• Add a CODEOWNERS / branch-protection rule or a labeler to flag PRs touching dist/ (satisfies the "prevent hand-edits" goal), and optionally
• Layer Option D (post-merge rebuild) later if PR diff-noise becomes the dominant pain.

Avoid Option B unless the build can be isolated with a hardened, least-privilege token — the pull_request_target write-back risk outweighs the convenience.