Document in-app file editing

Status	File	+	-
M	`docs/internal/branch-protection.md`	9	3
M	`docs/internal/code-tab.md`	66	0
M	`docs/internal/hooks.md`	12	2
M	`docs/internal/permissions.md`	5	0

docs/internal/branch-protection.mdmodified

  | `pattern`                  | (set)   | `filepath.Match` glob                        |
  | `prevent_force_push`       | `true`  | enforced                                     |
  | `prevent_deletion`         | `true`  | enforced                                     |
--| `require_pr_for_push`      | `false` | placeholder — column exists, no-op           |
++| `require_pr_for_push`      | `false` | enforced for direct git pushes and web edits |
  | `allowed_pusher_user_ids`  | `{}`    | enforced; empty = no restriction              |
  | `require_signed_commits`   | `false` | placeholder — post-MVP                       |
  | `status_checks_required`   | `{}`    | placeholder — S24 wires real checks          |
  3. For each ref update, calls `protection.Enforce`:
     - Skip non-`refs/heads/*` refs (tag protection out of scope).
     - Resolve the longest-matching rule.
--   - Apply the gates in order: deletion → force-push → allowed-pushers.
++   - Apply the gates in order: deletion → require-PR → force-push →
++     allowed-pushers.
     - Return a `Decision` with `Allow`, `Reason`, and `Pattern`.
  4. On any `Allow=false`: write `protection.FriendlyMessage(d)` to
     stderr; exit non-zero.
  (via `repogit.IsAncestor`). When the old SHA is not an ancestor of
  the new SHA, the update is non-fast-forward → reject.
++**Require pull request** rejects direct branch creates and updates when
++`require_pr_for_push` is true on the matching rule. That covers both
++normal git pushes and in-browser file-editor commits because both paths
++call `protection.Enforce` before advancing `refs/heads/*`. Branch
++deletions remain controlled by `prevent_deletion`.
++
  **Failure mode** (DB unavailable from hook): the rule lookup returns
  an error; the hook prints "transient; retry" to stderr and exits
  non-zero. **Fail closed**, per the S20 lean: better to reject a
  ## Deferred to later sprints
--- **`require_pr_for_push` enforcement** → S22 (PR engine) wires it.
  - **`require_signed_commits` enforcement** → post-MVP signing surface.
  - **`status_checks_required`** → S24 ships the check engine.
  - **Required reviewers attached to rules** → S23.

docs/internal/code-tab.mdmodified

  | `GET /{owner}/{repo}/blob/{ref}/{path...}`       | `codeBlob`                       |
  | `GET /{owner}/{repo}/raw/{ref}/{path...}`        | `codeRaw`                        |
  | `GET /{owner}/{repo}/find/{ref}?q=...`           | `codeFinder`                     |
++| `GET /{owner}/{repo}/edit/{ref}/{path...}`       | in-browser file editor           |
++| `POST /{owner}/{repo}/edit/{ref}/{path...}`      | commit file edit / rename        |
++| `GET /{owner}/{repo}/new/{ref}/{path...}`        | in-browser new-file editor       |
++| `POST /{owner}/{repo}/new/{ref}/{path...}`       | commit new file                  |
++| `GET /{owner}/{repo}/delete/{ref}/{path...}`     | delete-file confirmation         |
++| `POST /{owner}/{repo}/delete/{ref}/{path...}`    | commit file deletion             |
++| `GET /{owner}/{repo}/upload/{ref}/{path...}`     | upload-files form                |
++| `POST /{owner}/{repo}/upload/{ref}/{path...}`    | commit uploaded files            |
++| `POST /{owner}/{repo}/markdown-preview`          | editor Markdown preview fragment |
  | `GET /{owner}/{repo}/actions`                    | parked product-tab shell         |
  | `GET /{owner}/{repo}/projects`                   | parked product-tab shell         |
  | `GET /{owner}/{repo}/wiki`                       | parked product-tab shell         |
  private repos hide from anonymous viewers and unrelated users via the
  existence-leak 404 guard from S15.
++The in-browser mutation routes run through `policy.Can(... ActionRepoWrite)`.
++They inherit the same archived-repo, suspended-user, collaborator-role,
++site-admin, and private-repo existence behavior as git push surfaces.
++
  ## Repository product tabs
  The repo header intentionally exposes GitHub's major product-map tabs:
  Chroma uses the `github` style baked at process start; the CSS is
  served from `/static/css/chroma.css` via a tiny in-process generator.
++## In-browser file edits
++
++The Code tab surfaces GitHub-style write affordances for users with
++`repo:write` on a named branch:
++
++- The tree header has an **Add file** dropdown with create and upload
++  actions.
++- Text blob headers show edit and delete icon buttons.
++- The rendered README header shows an edit icon when the README was
++  found in the current directory. SECURITY and CONTRIBUTING documents
++  use the same blob-header controls when opened from the document tabs.
++
++Direct web commits are intentionally limited to `refs/heads/<branch>`.
++Tags and detached 40-hex commit views render read-only controls and
++direct edit URLs return `400`.
++
++`internal/repos/webedit` owns the mutation path. For each edit it:
++
++1. Resolves the branch to its current commit and compares the submitted
++   hidden `base_oid`; a mismatch returns a stale-edit conflict.
++2. Builds a temporary index from the old commit with `git read-tree`.
++3. Stages file changes via canonical git plumbing (`hash-object`,
++   `update-index`, `write-tree`, `commit-tree`).
++4. Runs `protection.Enforce` before moving the branch, so protected
++   branches deny direct web commits just like pushes.
++5. Advances the branch with `git update-ref <ref> <new> <old>` CAS.
++6. Inserts a `push_events` row with `protocol = 'web'`, enqueues
++   `push:process`, and sends the worker NOTIFY. If enqueueing fails
++   after the ref has moved, the commit still succeeds and the failure
++   is logged; the same post-push reconciliation gap exists for hook
++   failures.
++
++Validation rules:
++
++- Text editor actions are capped at 1 MiB and reject NUL-byte binary
++  content. Existing edit sources must be regular blobs, not symlinks,
++  submodules, trees, or oversized blobs.
++- Uploads are capped at 25 MiB per request and 10 MiB per file. Uploads
++  may contain binary data.
++- Repository paths reject empty names, leading/trailing slash, duplicate
++  slash, backslash, `.`/`..` segments, control bytes, exact overwrites,
++  duplicate uploads, and parent-path conflicts.
++- Default commit messages are generated server-side (`Update`, `Create`,
++  `Rename`, `Delete`, or `Upload`) when the form leaves the message
++  blank.
++
++The editor component is still server-rendered Go templates plus a small
++page-local script. No frontend build pipeline or React/Vite layer is
++required for this slice.
++
  ## Raw view
  * Content-Type derived from the extension whitelist
    (TODO — minimal coverage today).
  * **Path traversal**: `validateSubpath` in `code.go` rejects `..`,
    controls, leading slashes.
++* **Web edit path traversal / overwrite**: `webedit.ValidateFilePath`
++  applies the stricter mutation path guard and the service re-checks
++  path existence against the commit being modified.
  * **Hex collision with SHA**: ref-list lookup wins over SHA shortcut
    when the same string is both.
  * **Encoding (GBK / Shift-JIS)**: TODO — text files outside UTF-8 may

docs/internal/hooks.mdmodified

         worker picks it up via LISTEN
  ```
++In-browser file-editor commits do not execute git hooks: they are built
++with plumbing inside the already-bare repository and advance the branch
++with `git update-ref`. To keep downstream behavior identical to pushed
++commits, `internal/repos/webedit` runs the same branch-protection
++enforcer before the ref update, inserts `push_events.protocol = 'web'`
++after a successful CAS, enqueues `push:process`, and sends
++`NOTIFY shithub_jobs`.
++
  ## pre-receive contract
  Implements the **minimum gates** described in S14. The full branch
  ## post-receive contract
  * Reads stdin, ignores empty/malformed lines.
--* For each `<old> <new> <ref>` line: INSERT a `push_events` row, then
++* For each `<old> <new> <ref>` line: INSERT a `push_events` row with
--  enqueue a `push:process` job carrying the new event id.
++  protocol `http` or `ssh`, then enqueue a `push:process` job carrying
++  the new event id. Web-editor commits use the same table with protocol
++  `web`.
  * Issues a single `NOTIFY shithub_jobs` per push (workers wake on the
    next tx commit).
  * Exits 0 even on internal errors. The push has already landed; the

docs/internal/permissions.mdmodified

  Read actions on **public** repos are short-circuited to allow before the
  role check — anyone (anonymous or otherwise) can read a public repo.
++The in-browser file editor uses `repo:write` for every mutation route
++(`edit`, `new`, `delete`, and `upload`). Its buttons are only rendered
++when the same action allows the current web actor on a named branch, and
++the POST handlers re-run the policy check before committing.
++
  ## Decision precedence
  `Can()` evaluates in a fixed order; the first matching rule produces

tenseleyflow/shithub / `5ac31a3`

4 changed files