`5ac31a3`

Document in-app file editing

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 3 days ago

SHA: 5ac31a3a8439c4b69e304efe69d0ba537542f550
Parents: 0056ee6
Tree: b08d8ce

4 changed files

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          |
 . 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`.
 . 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
 -  enqueue a `push:process` job carrying the new event id.
 +* For each `<old> <new> <ref>` line: INSERT a `push_events` row with
 +  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