From 2ac7a5dd130a89608f5dddfaa25a784199721b3a Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Fri, 23 Oct 2026 09:51:28 +0700 Subject: [PATCH] fix(edit): send blob sha in Contents API PUT (Gitea 28 UpdateFile contract) Gitea 28 decides create-vs-update solely by the body 'sha' (blob ID): empty sha -> create (422 'already exists' on an existing file), stale sha -> 422 'does not match'. The client sent last_commit_sha, which Gitea 28 bodies ignore - every save was a CREATE, so nothing ever reached the branch. fetchDoc/putBase64 now carry the file's blob sha, save reads the new sha from FileResponse.content.sha, and save-conflict detection accepts 412 (older Gitea) or 422 with a 'does not match' message; other 422s stay a hard failure with resume. Spec 6.1 amended with dated note; AGENTS.md DraftStore line aligned. --- AGENTS.md | 2 +- docs/design/specs/v4/spec-v4-live-edit.md | 11 +++-- src/i18n/draft.ts | 58 +++++++++++++++-------- 3 files changed, 46 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8a87778..f6ebf4e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,7 +87,7 @@ Content is split once, at authoring time, into language-neutral **structure docu - Entry: any route with `?edit` — `MaybeEditMode` in `App.tsx` lazy-mounts `EditModeShell` (its own chunk; visitors never load edit code). The shell authenticates, fetches the live master documents through the proxy, and re-wraps the tree in an `I18nProvider` override — the seven routes ARE the preview - Target branch (spec D10): `?edit=` reads (`?ref=`) and writes (`branch` in the PUT body) that branch; a bare `?edit` resumes the session's last branch, default `master`. Names are validated against git ref rules in `src/i18n/edit-mode.ts` before any request (illegal → exit like a failed auth); the branch is stored beside the session flag. The target branch must already exist — Contents API updates never create branches. Only `master` deploys, so the EditBar shows a merge hint on other branches - Auth: HTTP Basic at the nginx `/api/content/` proxy is the security boundary; `src/i18n/edit-mode.ts` probes it through a hidden iframe, keeps the session flag `portfolio-edit` in sessionStorage, and strips `?edit` when the probe fails (401 or cancelled prompt → normal visitor site) -- `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + `last_commit_sha`) of the six content documents, copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on 412 conflicts (origin / base / working kept separate), draft persisted to sessionStorage `portfolio-draft`, sequential-PUT save (one commit per touched document, resume from the first unwritten one on failure), and appending new id union members to `src/types/index.ts` after their documents land +- `src/i18n/draft.ts` — `DraftStore`: baselines (`data` + blob `sha`) of the six content documents, copy-on-write draft, leaf-path diff, cross-document validation on every accepted edit, three-way rebase on save conflicts (Gitea 28 reports a blob-sha mismatch as 422 with a "does not match" message; older deployments answered 412 — both are handled; origin / base / working kept separate), draft persisted to sessionStorage `portfolio-draft`, sequential-PUT save (one commit per touched document, resume from the first unwritten one on failure), and appending new id union members to `src/types/index.ts` after their documents land - `src/components/ui/EditableText.tsx` — the site's own element (`as` = the tag or motion component it renders today) becomes the inline editor only in edit mode; commit on blur only (Vietnamese IME-safe), Esc cancels, Enter commits single-line fields, paste is plain-text, empty required values are rejected at commit; without an `EditContext` provider it renders byte-identical markup to the plain element - `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert, conflict resolution (rebase / take-theirs / hand-merge), per-document save status, partial-save resume, exit confirm; `src/components/layout/JsonPanel.tsx` — per-document JSON editor with shape hints, record templates (structure + text stubs created together), orphan-free record delete, read-only `ui.json` tabs - Editable surface is content text only (bio, tagline segments, project titles/summaries/section prose, experience titles/responsibilities, skill-group titles, philosophy titles/descriptions); structure fields (`featured`, `variant`, technologies, links, ids) are edited in the JSON panel; `ui.json` is read-only in v4. **Design agreed 2026-10-23 (`spec-v4-inline-editing.md`), not yet implemented:** the JSON panel will be deleted — pencil-icon-trigger inline editing with field-provenance chips (`document → pointer`), chip-level tag editors, ghost add/delete/move record controls, per-record settings popover, auto-generated ids, handle-only social links with loader-derived URLs diff --git a/docs/design/specs/v4/spec-v4-live-edit.md b/docs/design/specs/v4/spec-v4-live-edit.md index 4e175a6..1f1134d 100644 --- a/docs/design/specs/v4/spec-v4-live-edit.md +++ b/docs/design/specs/v4/spec-v4-live-edit.md @@ -285,7 +285,7 @@ graph LR subgraph edit["Edit time (new)"] V2["edit mode"] --> DR["draft state
= the same JSON documents"] DR -->|"validate before save"| DR - DR -->|"PUT + last_commit_sha"| PX["nginx /api/content/
basic auth + token"] + DR -->|"PUT + blob sha"| PX["nginx /api/content/
basic auth + token"] PX --> GA["Gitea Contents API"] --> COMMIT["commit on master"] --> CI end ``` @@ -329,7 +329,7 @@ Type changes in `src/types/index.ts`: every `*En` optional is deleted from the 6 The site itself gains an edit mode. There is no second preview machinery — the seven routes *are* the preview. - **Entry:** edit mode activates only for the authenticated owner (handshake against the protected proxy endpoint, §6.2; activation stored in `sessionStorage`; a `?edit` query on any route re-enters the mode within a session; the query is stripped from the URL on exit so shared/canonical URLs stay clean). Anonymous visitors never see edit affordances. -- **Draft initialization:** the draft is initialized from **live repository files fetched through the proxy** (`GET` per document + its `last_commit_sha`), not from the bundle — the bundle may be older than master if anyone edited via Gitea web since the last build, and a bundle-seeded draft would silently revert those edits. The static bundle is used only as an offline fallback, with a visible "stale" warning. +- **Draft initialization:** the draft is initialized from **live repository files fetched through the proxy** (`GET` per document + its blob `sha`), not from the bundle — the bundle may be older than master if anyone edited via Gitea web since the last build, and a bundle-seeded draft would silently revert those edits. The static bundle is used only as an offline fallback, with a visible "stale" warning. - **Mechanism:** edit mode wraps `` in ``. All pages, all components, both languages render the draft — text **and** structure. - **Inline text editing:** rendered text nodes bound to a text-document path become editable on focus (`contentEditable`); blur writes `{ path, value }` into the draft. Editing `projects['iot-dws-integration'].title` updates the card on `/projects`, the header on `/projects/:id`, and the featured block on the home page **simultaneously** — one draft, every consumer. - **Editable surface (curated scope):** inline editing covers **text documents only** — profile bio and tagline (each tagline segment is an individually editable span), profile subtitle / career TL;DR / philosophy quote titles+paragraphs (row 18), project titles/summaries/section content/role, experience titles/companies/durations/responsibilities (row 19), skill group titles, philosophy titles/descriptions. `ui.json` is **read-only** in v4 (labels/aria are low-frequency chrome). This bounds the wrapping work to the ~40 content render sites, not the 130+ UI-string sites. Adjacent tagline segments are separate edit targets — the caret does not cross a segment boundary; intended behavior (D9), not a bug. *Superseded 2026-10-23 by `spec-v4-inline-editing.md`: editing is triggered by a per-field pencil icon, never by text focus; tag arrays (`currentInterests`, `roles`, `keywords`, `metrics`, `technologies`, tagline segments + emphasis toggle) become chip-level edit units with add/delete/move.* @@ -356,7 +356,7 @@ stateDiagram-v2 ``` - **Entry:** `?edit` on any route → the app probes the protected endpoint once (hidden-iframe GET to trigger the native Basic prompt, §6.2). 401 or cancel → normal visitor site, zero affordances. Auth OK → session flag in `sessionStorage` + draft initialization (§5.1). Within a session the browser re-attaches Basic credentials to later requests on its own — no repeated prompt. The probe targets the session's branch: `?edit=` selects it, a bare `?edit` resumes the last one or `master` (D10); the branch name is validated before the probe and stored beside the session flag. -- **Durability:** every accepted edit is also copied to `sessionStorage` (the documents are tens of KB). An accidental reload restores the draft: the app re-fetches live files, re-applies the saved draft, and flags any document whose `last_commit_sha` moved → conflict flow (§5.6). SPA navigation never loses the draft; `beforeunload` warns while dirty. +- **Durability:** every accepted edit is also copied to `sessionStorage` (the documents are tens of KB). An accidental reload restores the draft: the app re-fetches live files, re-applies the saved draft, and flags any document whose blob `sha` moved → conflict flow (§5.6). SPA navigation never loses the draft; `beforeunload` warns while dirty. - **Exit:** explicit action in the EditBar — save-or-discard prompt if dirty, clear flag + draft, `history.replaceState` strips `?edit`. ### 5.3 `EditableText` contract (inline editing) @@ -414,8 +414,8 @@ v4 exposes no new layout knobs. `featured` and `variant` already exist and are e Repo: `https://code.vugado.com/dong.nguyen/cv` — self-hosted Gitea (API verified live: `/api/v1/version` → 28.1.0). Contents API paths are fixed to this repo: -- `GET /api/v1/repos/dong.nguyen/cv/contents/{path}` — read the live file + its `last_commit_sha` when a draft session starts (§5.1). -- `PUT /api/v1/repos/dong.nguyen/cv/contents/{path}` — body: base64 content, `message`, `branch`, `last_commit_sha`. A stale sha → 412 → editor refetches and re-applies; lost updates are impossible. +- `GET /api/v1/repos/dong.nguyen/cv/contents/{path}` — read the live file + its blob `sha` when a draft session starts (§5.1). +- `PUT /api/v1/repos/dong.nguyen/cv/contents/{path}` — body: base64 content, `message`, `branch`, `sha` (the file's blob ID). Gitea 28 `UpdateFile` keys create-vs-update on this field: empty `sha` → create (an existing file answers 422 "repository file already exists"); a stale `sha` → 422 with a "does not match" message → editor refetches and re-applies; lost updates are impossible. *(Amended 2026-10-23 after the first real save against 28.1.0 — the text previously described the retired `last_commit_sha`/412 contract; `last_commit_sha` exists only in responses.)* **Save/CI policy (decided):** a save writes its touched documents as **sequential PUTs to `master`** — each is one commit and triggers the existing pipeline. Consequences accepted: a save touching 2–4 documents produces 2–4 sequential CI runs, and between runs the deployed site can transiently mix old/new documents. For a single owner publishing at low frequency this is the boring, correct choice; the final state after the last pipeline is always consistent. (Branch-then-merge for a single pipeline run is noted as a future optimization, not v4.) @@ -598,3 +598,4 @@ Deferred (not v4): | 17 | Target-branch editing (D10): `?edit=`, `?ref=` on GET, `branch` on PUT, branch chip + merge hint | 3 | ✅ Done 2026-10-22 (automated) — tri-state URL parsing with git-ref validation (`edit-mode.ts`), `?ref=` on every document GET and `branch` in every PUT body (`draft.ts`, incl. the 412-refresh and id-union legs), branch persisted beside the session flag, EditBar branch chip + merge hint on non-default branches (`ui.json` `branchLabel`/`mergeHint`). Verified: `pnpm build`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7, throwaway wiring smoke (URL tri-state, ref/branch transport, EditBar render for branch vs master) — deleted after the run. ⬜ Browser + Gitea: edit on a non-master branch → commits land there; merge → deploy | | 18 | Move the three person-content keys out of `ui.json` (§11): `about.subtitle` → `profile.subtitle`, `experience.tldrText` → `profile.tldr`, `philosophy.quotes` → `profile.philosophyQuotes`; extend `ProfileText`, repoint 4 call sites, `EditableText` wrap + `SectionHeading` `subtitle: ReactNode`, JsonPanel hint update; `tsc` is the migration net | post-v4 | ✅ Done 2026-10-22 (automated) — values in both `content.{vi,en}.json`, keys deleted from both `ui` documents, `edit.fields` labels added; verified: `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 7/7, throwaway SSR smoke asserting the subtitle / TL;DR / essay markers on `/about`, home + `/experience`, `/philosophy` in both languages — deleted after the run. ⬜ Browser: inline-edit the three fields in `?edit` | | 19 | Localize the §4 structure-assigned strings (`experience.company` of non-company entries, `duration`, `currentInterests`, `roles`, `keywords`, `projects.role`/`metrics`) or keep them EN-only like `technologies` | post-v4 | ✅ Done 2026-10-22 (automated) — fields moved to the text documents (§4 follow-up); VI document carries localized values (numeric dates + "nay", "Sẵn sàng cho cơ hội mới", "Nghỉ giữa chặng", "Đã triển khai tại 16 sortations", "Xử lý 70.000 ảnh/tháng"), en overrides with the originals, proper nouns and term lists identical (en omits); company/duration/role inline-editable, tag arrays JSON-panel-only; templates in `draft.ts` and JsonPanel hints follow the new shapes; resume generator reads `profile.tldr` from content. Verified: `pnpm build`, `pnpm validate:content`, `pnpm lint` (no new warnings), `pnpm build:resume-all` (both PDFs), SSR smoke marker sets per language incl. localized durations/companies/metrics/roles on home + `/experience` + project detail — deleted after the run. ⬜ Browser: VI pages show the localized timeline; `?edit` company/duration/role | +| 20 | Save pipeline adapted to the live Gitea 28 Contents API | 3 | ✅ Done 2026-10-23 — the first real save answered 422 "repository file already exists [path: src/i18n/locales/vi/content.json]": Gitea 28 decides create-vs-update by the body `sha` (blob ID), which the client never sent. `draft.ts`: `fetchDoc`/`fetchTextFile` keep the blob `sha`; PUT bodies send `sha`; the new blob sha is read from the FileResponse `content.sha`; save conflict detection = 422 with a "does not match" message (412 kept for older deployments); §6.1 amended. Verified: `tsc -b`, `pnpm lint` (no new warnings), `scripts/smoke-draft.ts` 8/8. ⬜ Browser + Gitea: save → commit lands on the target branch; stale blob sha → conflict flow | diff --git a/src/i18n/draft.ts b/src/i18n/draft.ts index 30a4f2c..2d9d1a2 100644 --- a/src/i18n/draft.ts +++ b/src/i18n/draft.ts @@ -1,7 +1,7 @@ // Draft store (spec-v4 §5.1, §5.5, §5.6, §6.1): the live branch documents // fetched through the proxy, a copy-on-write draft over them, changed-path // tracking, cross-document validation on every accepted edit, sessionStorage -// durability, and the sequential-PUT save pipeline with last_commit_sha +// durability, and the sequential-PUT save pipeline with blob-sha // optimistic concurrency. Pure logic — the React glue lives in EditModeShell. import contentEnJson from './locales/en/content.json'; import contentViJson from './locales/vi/content.json'; @@ -161,29 +161,38 @@ function encodeBase64(text: string): string { export async function fetchDoc(file: string, branch: string): Promise { const res = await fetch(proxyUrl(file, branch)); if (!res.ok) throw new Error(`GET ${file}: ${res.status}`); - const json = (await res.json()) as { content?: string; last_commit_sha?: string }; + // The contents response carries both the blob sha (`sha`) and the last + // commit that touched the file (`last_commit_sha`). Gitea 28's UpdateFile + // concurrency field is the blob sha — that is the value the draft keeps. + const json = (await res.json()) as { content?: string; sha?: string }; return { data: JSON.parse(decodeBase64(json.content ?? '')), - sha: String(json.last_commit_sha ?? ''), + sha: String(json.sha ?? ''), }; } export async function fetchTextFile(file: string, branch: string): Promise<{ text: string; sha: string }> { const res = await fetch(proxyUrl(file, branch)); if (!res.ok) throw new Error(`GET ${file}: ${res.status}`); - const json = (await res.json()) as { content?: string; last_commit_sha?: string }; - return { text: decodeBase64(json.content ?? ''), sha: String(json.last_commit_sha ?? '') }; + const json = (await res.json()) as { content?: string; sha?: string }; + return { text: decodeBase64(json.content ?? ''), sha: String(json.sha ?? '') }; } -export type PutResult = { ok: true; sha: string } | { ok: false; status: number }; +export type PutResult = + | { ok: true; sha: string } + | { ok: false; status: number; message: string }; async function putBase64( file: string, encoded: string, message: string, - lastCommitSha: string, + blobSha: string, branch: string, ): Promise { + // Gitea 28 UpdateFileOptions: `sha` is the blob ID of the file to update — + // empty means create (an existing file then answers 422 "repository file + // already exists"), a stale one means a concurrency mismatch. The FileResponse + // returns the new blob sha at `content.sha`. const res = await fetch(proxyUrl(file, branch), { method: 'PUT', headers: { 'content-type': 'application/json' }, @@ -191,12 +200,21 @@ async function putBase64( content: encoded, message, branch, - last_commit_sha: lastCommitSha, + sha: blobSha, }), }); - if (!res.ok) return { ok: false, status: res.status }; - const json = (await res.json()) as { last_commit_sha?: string }; - return { ok: true, sha: String(json.last_commit_sha ?? '') }; + if (!res.ok) { + let detail = ''; + try { + const json = (await res.json()) as { message?: string }; + detail = String(json.message ?? ''); + } catch { + // non-JSON body — the status code alone still drives the caller + } + return { ok: false, status: res.status, message: detail }; + } + const json = (await res.json()) as { content?: { sha?: string } }; + return { ok: true, sha: String(json.content?.sha ?? '') }; } // Serialize exactly as the repository file is formatted (2-space indent, key @@ -333,7 +351,7 @@ export function recordForTitlePath( export class DraftStore { private base = new Map(); // The baseline the draft was taken against. `base` may be refreshed by a - // 412 conflict; `origin` never moves until a document lands, so a rebase + // 422/412 conflict; `origin` never moves until a document lands, so a rebase // can always tell my changes from theirs (§5.6). private origin = new Map(); private working = new Map(); @@ -830,7 +848,7 @@ export class DraftStore { } // Re-apply a persisted draft onto freshly fetched baselines. A document - // whose last_commit_sha moved since the draft was taken is returned as + // whose blob sha moved since the draft was taken is returned as // drifted → the conflict flow (§5.6) owns it from here. applySaved(saved: SavedDraft): DraftDocId[] { this.created = new Set(saved.created ?? []); @@ -902,10 +920,12 @@ export type DocSaveResult = { http?: number; }; -// Sequential PUTs, one commit per touched document (§6.1). A 412 refreshes -// that document's base and reports a conflict without stopping the sequence; -// any other failure stops so a retry resumes from the first unwritten -// document — landed documents are never rewritten (§5.6). +// Sequential PUTs, one commit per touched document (§6.1). A blob-sha +// mismatch — Gitea 28 answers 422 with a "does not match" message, older +// deployments answered 412 — refreshes that document's base and reports a +// conflict without stopping the sequence; any other failure stops so a retry +// resumes from the first unwritten document — landed documents are never +// rewritten (§5.6). export async function saveDraft( store: DraftStore, onResult: (result: DocSaveResult) => void, @@ -924,13 +944,13 @@ export async function saveDraft( onResult(result); continue; } - if (res.status === 412) { + if (res.status === 412 || (res.status === 422 && /does not match/i.test(res.message))) { try { store.resetBase(id, await fetchDoc(meta.file, branch)); } catch { // keep the old base; the conflict UI still offers take-theirs } - const result: DocSaveResult = { id, status: 'conflict', http: 412 }; + const result: DocSaveResult = { id, status: 'conflict', http: res.status }; results.push(result); onResult(result); continue;