syntaxai/tdd.md · commit a7a8d04

Self-hosted editor: replace "edit on GitHub" with proposal queue

The docs-layout edit link no longer points at GitHub's web editor. It
now points at /edit/<section>/<slug> on tdd.md itself. Authentication
still goes through GitHub OAuth (we already had that flow), but every
edit lands as a *proposal* in our SQLite store. Live pages do not
change until the owner downloads the proposed body via /admin/
proposals/<id>/patch and commits it on dev — keeping git as the
single source of truth and the deploy pipeline as the only path to
production. No file mutation in the running container.

  src/c31_site_config.ts (extended)
    ADMIN_USERNAME (gates /admin/*)
    SELF_HOSTED_REPO_BLOB_BASE (the "view source" link target)

  src/c13_database.ts (extended)
    proposals table + index. CRUD: createProposal, getProposal,
    listProposals (optional status filter), setProposalStatus.

  src/c31_proposals.ts (new)
  src/c31_proposals.test.ts (sibling test, 8 cases)
    Validates form-submitted proposal bodies before they reach the DB.
    256 KB body cap, non-empty body and author required. isNoOpProposal
    helper so the handler can skip storing identical resubmissions.

  src/c32_edit_resolve.ts (new)
  src/c32_edit_resolve.test.ts (sibling test, 7 cases)
    Pure resolver: (section, slug) -> { pageUrl, filePath, title }.
    Section must be one of sama/guides/blog. Slug must match an entry
    in the corresponding registry. Rejects path traversal, uppercase,
    leading dashes, etc. — locks edit targets to known doc pages so
    /edit/../../etc/passwd cannot escape the content tree.

  src/c21_handlers_auth.ts
    startGithubOauth(req) accepts an optional ?to=<path> query and
    sets a tdd_oauth_return cookie alongside the state nonce. The
    callback honours it for returning users (new-user welcome flow
    is unchanged). Open-redirect guard via isSafeReturnTo.

  src/c21_handlers_edit.ts (new)
    GET /edit/:section/:slug — login wall when anonymous, edit form
                               when signed in (current body in textarea)
    POST /edit/:section/:slug — validates, no-op-skips, createProposal,
                                redirects to thank-you page

  src/c21_handlers_admin.ts (new)
    GET /admin/proposals             - queue listing
    GET /admin/proposals/:id         - side-by-side current vs proposed
    POST /admin/proposals/:id/approve - mark approved (no fs write)
    POST /admin/proposals/:id/reject  - mark rejected with optional reason
    GET /admin/proposals/:id/patch    - downloadable .md with header
                                        comment for git apply
    All gated by viewer === ADMIN_USERNAME.

  src/c51_render_edit.ts (new)
    renderEditFormPage, renderEditLoginWall, renderEditThanks,
    renderAdminProposalList, renderAdminProposalDetail, renderAdminGate.
    Uses bodyHtml mode (no marked.parse) so <form> elements render
    instead of being escaped.

  src/c51_render_docs_layout.ts
    renderEditLink now emits two anchors: "propose an edit ->" linking
    to the internal /edit route, and "view source on git.tdd.md ->"
    linking to the self-hosted Forgejo mirror. The GitHub web-editor
    link is gone.

  src/c21_app.ts
    /edit/:section/:slug + 5 /admin/proposals/* routes registered as
    one-line delegations. /auth/github/start now passes req through
    so the returnTo query can be read.

  public/style.css
    Editor + admin styling: textarea, login button, status badges,
    side-by-side diff. Mobile collapses the diff to single column.

Verifier dogfood unchanged from before (S, A, Atomic still pass; the
4 c32_* sibling-test gaps stay queued as a separate sliver). c21_app.ts
went 649 -> 665 lines, comfortably under the 700 split threshold.

End-to-end verified: /edit/sama/sorted returns 401 with login wall;
/edit/sama/nonexistent returns 404 from resolveEdit; /admin/proposals
returns 401 for anon and the gate page renders; /sama/sorted now
shows the new "propose an edit" + "view source on git.tdd.md" links
with no GitHub edit-URL anywhere.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

author

syntaxai <[email protected]>

date

2026-05-10 09:37:19 +01:00

parent

8e72c3b

commit

a7a8d04441d1a356b0ac9ce91c9e314fe595bfd3