feat: version history browser (CE3)

CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes to git-cms are documented in this file.
 
 ### Added
 
+- **Version History Browser (CE3):** Browse prior versions of an article, preview old content, and restore a selected version as a new draft commit
+  - `CmsService.getArticleHistory()` — walk parent chain to list version summaries (SHA, title, status, author, date)
+  - `CmsService.readVersion()` — read full content of a specific commit by SHA
+  - `CmsService.restoreVersion()` — restore historical content as a new draft with ancestry validation and provenance trailers (`restoredFromSha`, `restoredAt`)
+  - `GET /api/cms/history`, `GET /api/cms/show-version`, `POST /api/cms/restore` server endpoints
+  - Admin UI: collapsible history panel with lazy-fetch, version preview, and restore button
+
 - **Content Identity Policy (M1.1):** Canonical slug validation with NFKC normalization, reserved word rejection, and `CmsValidationError` contract (`ContentIdentityPolicy.js`)
 - **State Machine (M1.2):** Explicit draft/published/unpublished/reverted states with enforced transition rules (`ContentStatePolicy.js`)
 - **Admin UI overhaul:** Split/edit/preview markdown editor (via `marked`), autosave, toast notifications, skeleton loading, drag-and-drop file uploads, metadata trailer editor, keyboard shortcuts (`Cmd+S`, `Esc`), dark mode token system

public/index.html

@@ -359,6 +359,50 @@
       margin-top: var(--size-2);
     }
 
+    /* ── History Section ── */
+    #historySection .history-list {
+      max-height: 240px;
+      overflow-y: auto;
+      margin-top: var(--size-2);
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+    }
+    .history-item {
+      display: flex;
+      align-items: center;
+      gap: var(--size-3);
+      padding: var(--size-2) var(--size-3);
+      border-radius: var(--radius-2);
+      cursor: pointer;
+      transition: background 0.15s;
+      font-size: var(--font-size-0);
+    }
+    .history-item:hover { background: var(--surface-3); }
+    .history-item.active { background: var(--brand); color: white; }
+    .history-item .hist-sha { font-family: var(--font-mono); font-size: var(--font-size-00); opacity: 0.7; }
+    .history-item .hist-title { flex: 1; font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .history-item .hist-date { font-size: var(--font-size-00); opacity: 0.7; white-space: nowrap; }
+    .history-item .hist-status { font-size: var(--font-size-00); opacity: 0.7; }
+
+    #historyPreview {
+      margin-top: var(--size-3);
+      border: 1px solid var(--surface-3);
+      border-radius: var(--radius-2);
+      padding: var(--size-3);
+      display: none;
+    }
+    #historyPreview .preview-content {
+      max-height: 300px;
+      overflow-y: auto;
+      line-height: 1.7;
+    }
+    #historyPreview .preview-actions {
+      margin-top: var(--size-3);
+      display: flex;
+      gap: var(--size-2);
+    }
+
     /* ── Status Bar ── */
     .status-bar {
       font-size: var(--font-size-0);
@@ -457,6 +501,17 @@ <h1>Git CMS</h1>
       <button class="btn add-trailer-btn" onclick="UI.addTrailerRow()">+ Add Field</button>
     </details>
 
+    <details id="historySection">
+      <summary>Version History</summary>
+      <div id="historyList" class="history-list"></div>
+      <div id="historyPreview">
+        <div id="historyPreviewContent" class="preview-content"></div>
+        <div class="preview-actions">
+          <button class="btn btn-primary" id="restoreBtn" onclick="UI.restoreVersion()" disabled>Restore This Version</button>
+        </div>
+      </div>
+    </details>
+
     <div class="asset-section" id="dropZone">
       Drop files here or
       <label class="btn" style="margin-left:var(--size-2)">
@@ -490,6 +545,8 @@ <h1>Git CMS</h1>
       autosaveTimer: null,
       editorMode: 'split',
       trailers: {},
+      historyVersions: [],
+      selectedVersion: null,
     };
 
     /* ── API Layer ── */
@@ -537,6 +594,29 @@ <h1>Git CMS</h1>
         if (!res.ok) throw new Error(`Upload failed: ${res.status}`);
         return res.json();
       },
+
+      async history(slug, limit = 50) {
+        const res = await fetch(`${API_BASE}/history?slug=${encodeURIComponent(slug)}&limit=${limit}`);
+        if (!res.ok) throw new Error(`History failed: ${res.status}`);
+        return res.json();
+      },
+
+      async showVersion(slug, sha) {
+        const res = await fetch(`${API_BASE}/show-version?slug=${encodeURIComponent(slug)}&sha=${encodeURIComponent(sha)}`);
+        if (!res.ok) throw new Error(`Show version failed: ${res.status}`);
+        return res.json();
+      },
+
+      async restore({ slug, sha }) {
+        const res = await fetch(`${API_BASE}/restore`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ slug, sha }),
+        });
+        const data = await res.json();
+        if (!res.ok) throw Object.assign(new Error(data.error || `Restore failed: ${res.status}`), { code: data.code });
+        return data;
+      },
     };
 
     /* ── Toast ── */
@@ -903,6 +983,94 @@ <h1>Git CMS</h1>
         this.hideEditor();
       },
 
+      /* Version History */
+      async fetchHistory() {
+        if (!state.currentSlug) return;
+        const listEl = document.getElementById('historyList');
+        listEl.innerHTML = '<div class="skeleton" style="height:1.8em"></div>';
+        document.getElementById('historyPreview').style.display = 'none';
+        state.selectedVersion = null;
+
+        try {
+          const versions = await api.history(state.currentSlug);
+          state.historyVersions = versions;
+          listEl.innerHTML = '';
+
+          versions.forEach((v, idx) => {
+            const div = document.createElement('div');
+            div.className = 'history-item';
+            div.dataset.idx = idx;
+
+            const shaSpan = document.createElement('span');
+            shaSpan.className = 'hist-sha';
+            shaSpan.textContent = v.sha.slice(0, 7);
+
+            const titleSpan = document.createElement('span');
+            titleSpan.className = 'hist-title';
+            titleSpan.textContent = v.title;
+
+            const statusSpan = document.createElement('span');
+            statusSpan.className = 'hist-status';
+            statusSpan.textContent = v.status;
+
+            const dateSpan = document.createElement('span');
+            dateSpan.className = 'hist-date';
+            dateSpan.textContent = relTime(v.date);
+
+            div.append(shaSpan, titleSpan, statusSpan, dateSpan);
+            div.onclick = () => this.selectVersion(v.sha, idx);
+            listEl.appendChild(div);
+          });
+        } catch (err) {
+          toast('Failed to load history', 'error');
+          listEl.innerHTML = '';
+        }
+      },
+
+      async selectVersion(sha, idx) {
+        state.selectedVersion = { sha, idx };
+        document.querySelectorAll('.history-item').forEach((el, i) => {
+          el.classList.toggle('active', i === idx);
+        });
+
+        const previewEl = document.getElementById('historyPreview');
+        const contentEl = document.getElementById('historyPreviewContent');
+        const restoreBtn = document.getElementById('restoreBtn');
+
+        previewEl.style.display = 'block';
+        contentEl.innerHTML = '<div class="skeleton" style="height:4em"></div>';
+
+        try {
+          const data = await api.showVersion(state.currentSlug, sha);
+          contentEl.innerHTML = DOMPurify.sanitize(marked.parse(data.body || ''));
+          // Disable restore for current version (idx 0)
+          restoreBtn.disabled = idx === 0;
+        } catch (err) {
+          contentEl.textContent = 'Failed to load version content';
+          restoreBtn.disabled = true;
+        }
+      },
+
+      async restoreVersion() {
+        if (!state.selectedVersion || !state.currentSlug) return;
+        const { sha } = state.selectedVersion;
+        if (!confirm(`Restore version ${sha.slice(0, 7)}? This creates a new draft with the old content.`)) return;
+
+        try {
+          await api.restore({ slug: state.currentSlug, sha });
+          toast('Version restored', 'success');
+          // Close history section and reload article
+          document.getElementById('historySection').open = false;
+          await this.loadArticle(state.currentSlug);
+        } catch (err) {
+          if (err.code === 'invalid_state_transition') {
+            toast('Cannot restore: unpublish the article first', 'error');
+          } else {
+            toast('Restore failed: ' + err.message, 'error');
+          }
+        }
+      },
+
       escAttr(s) {
         return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/'/g, '&#39;');
       },
@@ -967,6 +1135,11 @@ <h1>Git CMS</h1>
       this.value = '';
     });
 
+    // History section toggle — lazy-fetch on expand
+    document.getElementById('historySection').addEventListener('toggle', (e) => {
+      if (e.target.open) UI.fetchHistory();
+    });
+
     /* ── Init ── */
     UI.fetchList();
   </script>

src/lib/CmsService.js

@@ -317,6 +317,131 @@ export default class CmsService {
     return { ref: draftRef, sha: newSha, prev: draftSha };
   }
 
+  /**
+   * Returns version history for an article by walking the parent chain.
+   * @param {{ slug: string, limit?: number }} options
+   * @returns {Promise<Array<{ sha: string, title: string, status: string, author: string, date: string }>>}
+   */
+  async getArticleHistory({ slug, limit = 50 }) {
+    const canonicalSlug = canonicalizeSlug(slug);
+    const draftRef = this._refFor(canonicalSlug, 'articles');
+    const sha = await this.graph.readRef(draftRef);
+
+    if (!sha) {
+      throw new CmsValidationError(
+        `Article not found: "${canonicalSlug}"`,
+        { code: 'article_not_found', field: 'slug' }
+      );
+    }
+
+    const versions = [];
+    let current = sha;
+
+    while (current && versions.length < limit) {
+      const info = await this.graph.getNodeInfo(current);
+      const message = await this.graph.showNode(current);
+      const decoded = this.codec.decode(message);
+
+      versions.push({
+        sha: current,
+        title: decoded.title,
+        status: decoded.trailers?.status || 'draft',
+        author: info.author,
+        date: info.date,
+      });
+
+      current = info.parents?.[0] || null;
+    }
+
+    return versions;
+  }
+
+  /**
+   * Reads full content of a specific commit by SHA.
+   * @param {{ slug: string, sha: string }} options
+   * @returns {Promise<{ sha: string, title: string, body: string, trailers: object }>}
+   */
+  async readVersion({ slug, sha }) {
+    const canonicalSlug = canonicalizeSlug(slug);
+    const draftRef = this._refFor(canonicalSlug, 'articles');
+    const draftSha = await this.graph.readRef(draftRef);
+
+    if (!draftSha) {
+      throw new CmsValidationError(
+        `Article not found: "${canonicalSlug}"`,
+        { code: 'article_not_found', field: 'slug' }
+      );
+    }
+
+    const message = await this.graph.showNode(sha);
+    const decoded = this.codec.decode(message);
+    return { sha, title: decoded.title, body: decoded.body, trailers: decoded.trailers };
+  }
+
+  /**
+   * Restores content from a historical SHA as a new draft commit.
+   * @param {{ slug: string, sha: string }} options
+   * @returns {Promise<{ ref: string, sha: string, prev: string }>}
+   */
+  async restoreVersion({ slug, sha }) {
+    const canonicalSlug = canonicalizeSlug(slug);
+    const draftRef = this._refFor(canonicalSlug, 'articles');
+
+    const { effectiveState, draftSha } = await this._resolveArticleState(canonicalSlug);
+    validateTransition(effectiveState, STATES.DRAFT);
+
+    if (!draftSha) {
+      throw new CmsValidationError(
+        `Cannot restore "${canonicalSlug}": no draft ref exists`,
+        { code: 'no_draft', field: 'slug' }
+      );
+    }
+
+    // Ancestry validation: walk parent chain to verify target SHA belongs to this article
+    let found = false;
+    let walk = draftSha;
+    let steps = 0;
+    const walkLimit = 200;
+    while (walk && steps < walkLimit) {
+      if (walk === sha) { found = true; break; }
+      const info = await this.graph.getNodeInfo(walk);
+      walk = info.parents?.[0] || null;
+      steps++;
+    }
+    if (!found) {
+      throw new CmsValidationError(
+        `SHA "${sha}" is not in the history of article "${canonicalSlug}"`,
+        { code: 'invalid_version_for_article', field: 'sha' }
+      );
+    }
+
+    // Read target SHA content
+    const targetMessage = await this.graph.showNode(sha);
+    const decoded = this.codec.decode(targetMessage);
+    const { updatedat: _, restoredfromsha: _r, restoredat: _ra, ...restTrailers } = decoded.trailers;
+
+    const newMessage = this.codec.encode({
+      title: decoded.title,
+      body: decoded.body,
+      trailers: {
+        ...restTrailers,
+        status: STATES.DRAFT,
+        updatedAt: new Date().toISOString(),
+        restoredFromSha: sha,
+        restoredAt: new Date().toISOString(),
+      },
+    });
+
+    const newSha = await this.graph.commitNode({
+      message: newMessage,
+      parents: [draftSha],
+      sign: process.env.CMS_SIGN === '1',
+    });
+
+    await this._updateRef({ ref: draftRef, newSha, oldSha: draftSha });
+    return { ref: draftRef, sha: newSha, prev: draftSha };
+  }
+
   /**
    * Uploads an asset and returns its manifest and CAS info.
    */