# Milestone 4a: forks and pull requests (contract between workers)

Reviews with line comments come in M4b, not here. The global rules from `docs/m1-interfaces.md` and `docs/m3-interfaces.md` apply:
- The git CLI only gets **full hex OIDs** and validated ref names, placed after `--end-of-options` where git supports it.
- No shell, no unwrap in non-test code. Clippy `-D warnings` and fmt must pass.
- No inline styles and no JS.
- Every page goes through `load_repo` and `authorize`, and times use `viewer_tz`.
- **Never put cargo target dirs or big files in /tmp**, and tests use `tempfile::TempDir`.

## Concepts
- A PR is an `issues` row with `kind = 'pull'`, so it shares the per-repo numbering with issues. That gives it comments, labels, assignees, milestones, events and edit history for free. Issue pages already filter `kind = 'issue'`; PR pages filter `kind = 'pull'`. `#N` links go to `/issues/N`, and the issue page redirects (303) to `/pulls/N` when N is a PR.
- The **head** is `(head_repo_id, head_branch)`, either the same repo or a fork of the base. The **base** is `(base repo = issue.repo_id, base_branch)`.
- The base repo keeps `refs/pull/<N>/head` pointing at the head commit. It's updated whenever the head branch moves, so the base repo always has the objects. For a fork, that means a local `git fetch` from the fork's path.

## Forks
- `repos` gains `fork_of TEXT NULL REFERENCES repos(id)` (migration 0007).
- Creating a fork: `POST /{o}/{r}/fork` (signed in, Read on the source, CSRF). The new repo is named like the source (a `-1`, `-2` suffix on conflict), owned by the viewer. Its visibility matches the source; a private source forks to private.
- **On disk:** `git clone --bare --local --no-checkout <src_path> <new_path>` via GitCommand. `--local` hardlinks objects, which is cheap and safe because objects are immutable. Copy only branches and tags (`refs/heads/*`, `refs/tags/*`), not `refs/pull/*`. Then apply the managed config the same way `init_bare` does (hooks path and so on). Use alternates? **No**: deleting or trashing the parent would break the fork.
- The fork page header shows "forked from owner/name", linked to the source if the viewer can see it.
- Deleting a parent repo leaves forks working, with `fork_of` set to NULL in the delete transaction.

## Schema (migration `0007_pulls.sql`)
```sql
ALTER TABLE repos ADD COLUMN fork_of TEXT REFERENCES repos(id);
CREATE TABLE pull_requests (
    issue_id       TEXT PRIMARY KEY REFERENCES issues(id) ON DELETE CASCADE,
    base_branch    TEXT NOT NULL,
    head_repo_id   TEXT REFERENCES repos(id),     -- NULL if the head repo was deleted
    head_branch    TEXT NOT NULL,
    head_oid       TEXT NOT NULL,                 -- last known head commit (also refs/pull/N/head)
    base_oid       TEXT NOT NULL,                 -- base branch tip when mergeability was last computed
    merge_base     TEXT,
    mergeable      TEXT NOT NULL DEFAULT 'unknown', -- 'unknown' | 'clean' | 'conflict' | 'merged' | 'up_to_date'
    conflict_files TEXT NOT NULL DEFAULT '[]',    -- JSON array of paths
    merged_at      TEXT, merged_by TEXT REFERENCES users(id), merge_commit TEXT,
    allow_maintainer_edits INTEGER NOT NULL DEFAULT 1);
CREATE INDEX pull_requests_head ON pull_requests(head_repo_id, head_branch);
```
`Store::delete_repo` (base) must delete pull_requests rows of the repo's issues. Deleting a **head** repo sets `head_repo_id = NULL`; such a PR can't be merged any more, but its stored refs and diff still show.

## forge-core (`src/pulls.rs` model plus `store/pulls.rs`, an `impl Store` block)
```rust
pub enum Mergeable { Unknown, Clean, Conflict, Merged, UpToDate }   // as_str/parse
pub struct PullRequest { pub issue: Issue, pub base_branch: String, pub head_repo_id: Option<Id>,
    pub head_branch: String, pub head_oid: String, pub base_oid: String, pub merge_base: Option<String>,
    pub mergeable: Mergeable, pub conflict_files: Vec<String>, pub merged_at: Option<String>,
    pub merged_by: Option<Id>, pub merge_commit: Option<String> }
pub enum MergeStyle { Merge, Squash, FastForward }                  // "merge" | "squash" | "ff"

// store/pulls.rs
pub async fn create_pull(&self, repo_id: &str, author_id: &str, title: &str, body: &str,
    base_branch: &str, head_repo_id: &str, head_branch: &str, head_oid: &str, base_oid: &str) -> Result<PullRequest>; // allocates a number like create_issue (shared counter), kind='pull'
pub async fn pull_by_number(&self, repo_id: &str, number: i64) -> Result<Option<PullRequest>>;
pub async fn list_pulls(&self, repo_id: &str, f: &IssueFilter) -> Result<(Vec<IssueListItem>, u64)>; // same filters as issues; state 'open'|'closed' (merged PRs are closed)
pub async fn pull_counts(&self, repo_id: &str) -> Result<(u64, u64)>;
pub async fn open_pulls_for_head(&self, head_repo_id: &str, head_branch: &str) -> Result<Vec<(Id /*base repo*/, i64 /*number*/, Id /*issue id*/)>>;
pub async fn open_pulls_for_base(&self, repo_id: &str, base_branch: &str) -> Result<Vec<(i64, Id)>>;
pub async fn update_pull_head(&self, issue_id: &str, head_oid: &str) -> Result<()>;          // resets mergeable to 'unknown'
pub async fn set_mergeability(&self, issue_id: &str, base_oid: &str, merge_base: Option<&str>, m: Mergeable, conflicts: &[String]) -> Result<()>;
pub async fn mark_merged(&self, issue_id: &str, actor_id: &str, merge_commit: &str) -> Result<()>; // closes the issue (state_reason completed) + 'merged' event {"commit"}
pub async fn find_open_pull(&self, base_repo: &str, base_branch: &str, head_repo: &str, head_branch: &str) -> Result<Option<i64>>; // prevents duplicates
// forks
pub async fn create_fork(&self, source: &Repo, owner_id: &str, name: &str) -> Result<Repo>;  // sets fork_of
pub async fn list_forks(&self, repo_id: &str) -> Result<Vec<Repo>>;
```
`add_event` must accept the new kinds: `merged`, `head_updated` (data `{"from","to"}`), `base_changed`, and `head_deleted`.

## forge-git (`src/pulls.rs`)
```rust
pub async fn fetch_into_pull_ref(env: &GitEnv, base_repo: &Path, head_repo: &Path, head_oid: &str, number: i64) -> Result<()>;
    // same repo: `update-ref refs/pull/N/head <oid>`; fork: `git fetch --no-tags <head_repo_path> <oid>` then update-ref (uploadpack.allowAnySHA1InWant isn't needed for a local path fetch of a full oid; if it is, fetch the branch ref and verify the oid)
pub async fn merge_base(env, repo, a: &str, b: &str) -> Result<Option<String>>;
pub enum MergeCheck { Clean { tree: String }, Conflict { files: Vec<String> }, UpToDate }
pub async fn check_merge(env, repo, base_oid: &str, head_oid: &str) -> Result<MergeCheck>;
    // `git merge-tree --write-tree --name-only --no-messages <base> <head>`; exit 1 = conflict (parse the file list); UpToDate if head is an ancestor of base
pub async fn commit_tree(env, repo, tree: &str, parents: &[&str], message: &str, author: &Signature, committer: &Signature) -> Result<String>;
    // `git commit-tree`, with GIT_AUTHOR_*/GIT_COMMITTER_* env set from the signatures; the message goes in via stdin (never argv)
pub async fn update_ref_cas(env, repo, refname: &str, new: &str, old: &str) -> Result<()>;      // `update-ref <ref> <new> <old>`, an atomic compare-and-swap
pub async fn range_diff_files(env, repo, base_oid: &str, head_oid: &str, limits: DiffLimits) -> Result<CommitDiff>; // three-dot: merge-base..head, same parsing as commit_diff
pub async fn range_log(env, repo, base_oid: &str, head_oid: &str, max: usize) -> Result<Vec<CommitInfo>>;          // `log <head> ^<base>`, oldest first
pub struct Signature { pub name: String, pub email: String, pub time_unix: i64 }
```
**Merging (forge-web, `pulls_merge.rs`):** load the PR; require Write on the base repo, not archived, the PR open, and the head present. Recompute `check_merge` against the CURRENT base tip.
- **Merge:** `commit_tree(tree, [base, head], "Merge pull request #N from owner/branch\n\n<title>")`.
- **Squash:** `commit_tree(tree, [base], "<title> (#N)\n\n<body or commit list>")`, with the PR author as author.
- **FastForward:** only if base is an ancestor of head; new = head.
- Then `update_ref_cas(refs/heads/<base>, new, base)`. On a CAS failure, show "base moved, try again".
- **Branch protection:** a merge is never a force push. It runs as Write, so allowed.
- After the merge, call `mark_merged`, then run the same post-push side effects the hook would: closing keywords from the merged commits, the maintenance trigger, and recomputing mergeability of other PRs on that base. Factor the post-receive logic in `internal.rs` into a reusable `fn after_ref_update(state, repo, actor, refname, old, new)`, then call it from both places.

## Post-receive integration (forge-web `internal.rs`)
For every updated `refs/heads/<b>` of repo R (both paths, via `after_ref_update`):
- For each open PR whose head is (R, b): `fetch_into_pull_ref`, `update_pull_head`, a `head_updated` event, then recompute mergeability in the background. If the branch was deleted: a `head_deleted` event, and keep the last head.
- For each open PR whose base is (R, b): recompute mergeability in the background.
- If a push to the base branch makes a PR's head an ancestor of base (someone merged manually on the CLI), call `mark_merged` with the merge commit unknown. Use the base tip, and record the `merged` event.

## Web routes
- `GET /{o}/{r}/pulls`: list, same filters as issues; state open/closed, where closed also shows merged with a purple badge. `pulls_list.rs`.
- `GET /{o}/{r}/compare/{base}...{head}`, where head is `branch` or `owner:branch` for forks; also `GET /{o}/{r}/compare` with a base/head picker form (plain GET form). `compare.rs`.
  - Shows the commits, the diff stat and the file diffs (reuse the commit page's diff rendering: extract it into a shared component in `views/diff.rs`).
  - Shows an "Open pull request" form (title prefilled from the first commit summary, body) if the viewer can Read the base and there are commits.
  - `POST /{o}/{r}/pulls` creates the PR (CSRF; a duplicate open PR for the same head and base redirects to the existing one).
- `GET /{o}/{r}/pulls/{n}` (Conversation tab), `/pulls/{n}/commits`, `/pulls/{n}/files`. `pull_view.rs`.
  - Header: title, state badge (Open / Merged / Closed), "author wants to merge N commits into base from head".
  - The Conversation tab reuses the issue timeline, sidebar and comment form. Factor the shared parts of `issue_view.rs` into reusable components; the issue page must keep working and its tests must keep passing.
  - **Merge box:** mergeability status ("This branch has conflicts that must be resolved", listing the files; "Ready to merge"; "Checking…" when unknown), a style radio (merge, squash, ff when possible) and a Merge button for Write holders. `POST /{o}/{r}/pulls/{n}/merge`.
  - Close and reopen work like issues.
- Repo tabs gain **Pull requests (N)** after Issues.
- Repo pages for a forkable repo show a **Fork** button in the header (`POST /fork`). The fork header shows "forked from".
- A banner on the repo home after a recent push to a non-default branch ("feature/x had recent pushes — Compare & pull request"): optional, skip if complex.

## Tests (each worker covers its part; the e2e test file `tests/pulls_e2e.rs` uses real git)
- Same-repo PR: push `feature`, open the PR via compare, see its commits and files, merge-commit merge, then main contains the feature commit, the PR is merged, and a "Fixes #1" in the PR commits closes issue 1.
- Fork PR: bob forks, pushes to his fork, opens a PR to alice's repo. Alice merges with squash, giving a single new commit on main with bob as author.
- A conflict is detected and lists the file; the Merge button is disabled and the POST is rejected.
- Pushing to the head branch updates the PR (a new commit shows, a `head_updated` event).
- A base that moved concurrently gives the CAS failure message (simulate by updating the base between check and update; a unit test in forge-git is fine).
- FF-only when possible; otherwise the FF option is hidden or rejected.
- Permissions: a Read user can open a PR from their fork but can't merge (403). Private base: anonymous gets 404.
- `#N` on the issue page redirects to the PR.