feat(mcpedia): Phase 4 — operability + correctness hardening

Reinterpreted from the plan's YAGNI 'Scale-out' (OpenSearch/object-storage
/multi-tenant deferred at KB scale). Phase 4 = make the Phase 3 async +
revision system correct, secure, observable, deployable.

- T1 (correctness bug): restoreRevision now rebuilds semantic chunks via new
  @mcpedia/core reindexChunks(slug) so semantic/hybrid search stay consistent
  after a restore (previously document_chunks held the NEW body while
  documents.body held the restored OLD body -> stale search).
- T2 (security): /hooks/* git-sync webhooks now require x-webhook-secret header
  matching WEBHOOK_SECRET (401 otherwise); API fails fast at startup if unset.
  Added WEBHOOK_SECRET to @mcpedia/config + .env.example; set real secret in .env.
- T3 (UX): web doc page shows a History panel (revision no/reason/date/length)
  with per-revision Restore; app/api/revisions/restore/route.ts calls
  restoreRevision + revalidatePath (server-component only, no client JS).
- T4: listRevisions gains offset paging; summary never includes body.
- T5 (ops): deploy/mcpedia-api.service + deploy/mcpedia-worker.service systemd
  units (Restart=on-failure, EnvironmentFile=.env). Not auto-enabled on host.

Verified against live imrnes Redis + Postgres: turbo typecheck+build green;
restore-rebuilds-chunks (marker present -> gone after restore); webhook 401/200;
web restore route redirects to doc + reverts body; revisions API returns summary
(no body); systemd-analyze verify passes.

packages/config/src/index.ts

@@ -46,6 +46,10 @@ export const REDIS_PASSWORD = process.env.REDIS_PASSWORD ?? "";
 // BullMQ key prefix to namespace jobs on the shared Redis instance.
 export const QUEUE_PREFIX = process.env.QUEUE_PREFIX ?? "mcpedia";
 
+// Phase 4: git-sync webhook shared secret. The API /hooks/* endpoints require
+// this header (x-webhook-secret) to match, so an open port can't trigger reindex.
+export const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET ?? "";
+
 if (!DATABASE_URL) {
   // Fail fast with an explicit message instead of a cryptic driver error.
   throw new Error(

packages/core/src/index.service.ts

@@ -131,6 +131,28 @@ async function snapshotRevision(
   return true;
 }
 
+/**
+ * Rebuild the semantic chunks + embeddings for a slug from its CURRENT live
+ * `documents.body`. Used after `restoreRevision` so semantic/hybrid search
+ * stay consistent with the restored body (otherwise chunks would be stale).
+ * Embed failures are logged, not thrown — FTS remains the source of truth.
+ */
+export async function reindexChunks(slug: string): Promise<number> {
+  const [doc] = await db
+    .select({ body: documents.body })
+    .from(documents)
+    .where(eq(documents.slug, slug));
+  if (!doc) return 0;
+  try {
+    return await indexChunks(slug, doc.body);
+  } catch (err) {
+    console.error(
+      `    reindexChunks embed FAILED for ${slug}: ${err instanceof Error ? err.message : err}`,
+    );
+    return 0;
+  }
+}
+
 /**
  * Walk the entire content tree and index every file. Returns aggregate counts.
  */

packages/core/src/revision.service.ts

@@ -1,5 +1,6 @@
 import { db } from "@mcpedia/db";
 import { documents, documentRevisions, documentChunks } from "@mcpedia/db/schema";
+import { reindexChunks } from "./index.service";
 import { eq, desc, and, sql } from "drizzle-orm";
 import { toMeta } from "./row-map";
 import type { DocumentMeta } from "@mcpedia/types";
@@ -14,10 +15,11 @@ export interface RevisionSummary {
   bodyLength: number;
 }
 
-/** List revisions for a slug, newest first. */
+/** List revisions for a slug, newest first. `offset` enables paging. */
 export async function listRevisions(
   slug: string,
   limit = 20,
+  offset = 0,
 ): Promise<RevisionSummary[]> {
   const [doc] = await db
     .select({ id: documents.id })
@@ -38,7 +40,8 @@ export async function listRevisions(
     .from(documentRevisions)
     .where(eq(documentRevisions.documentId, doc.id))
     .orderBy(desc(documentRevisions.revisionNo))
-    .limit(limit);
+    .limit(limit)
+    .offset(offset);
 
   return rows.map((r) => ({
     id: r.id,
@@ -112,5 +115,10 @@ export async function restoreRevision(
     })
     .where(eq(documents.id, rev.documentId));
 
+  // Rebuild semantic chunks + embeddings from the restored body so semantic
+  // and hybrid search stay consistent (otherwise document_chunks would hold
+  // the NEW body's chunks while documents.body holds the OLD/restore body).
+  await reindexChunks(rev.slug);
+
   return { slug: rev.slug, documentId: rev.documentId };
 }