feat(mcpedia): Phase 3 — async indexing (BullMQ), git-sync webhook, revisions, MCP Resources

- packages/queue: ioredis singleton + BullMQ Queue/Worker (prefix mcpedia:
  on shared imrnes Redis :6379); apps/worker runs startWorker()
- @mcpedia/core: indexContentFile/runFullIndex (single indexing entry point
  shared by script/worker/hook) + revision.service (list/get/restore)
- document_revisions table (migration 0002) — snapshots only on body change
- apps/api: POST /hooks/reindex + /hooks/index webhooks; tRPC revisions,
  getRevision, restoreRevision, jobStatus, queueStatus
- apps/mcp: register MCP Resources mcpedia://docs{/,+slug/chunks/revisions}
  ({+slug} RFC6570 reserved expansion for slugs containing /)
- apps/mcp zod pinned to ^4 to match MCP SDK 1.30 compiled types
  (resolves registerTool TS2589/ShapeOutput skew)
- scripts/enqueue.ts one-shot job enqueue helper; indexer refactored to runFullIndex
- PHASES.md/README/.env.example/docs updated

apps/api/src/index.ts

@@ -4,12 +4,31 @@ import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 import { db } from "@mcpedia/db";
 import { appRouter } from "./router";
 import type { Context } from "./trpc";
+import { enqueueIndexDoc, enqueueFullIndex } from "@mcpedia/queue";
 
 const app = new Hono();
 
 // Health check.
 app.get("/health", (c) => c.json({ ok: true }));
 
+// --- Phase 3: Git synchronization hook ---
+// POST /hooks/reindex        -> enqueue a full-corpus reindex (git push webhook)
+// POST /hooks/index?slug=... -> enqueue a single document reindex
+// Returns the created job id(s). The worker processes them asynchronously.
+app.post("/hooks/reindex", async (c) => {
+  const job = await enqueueFullIndex("git-push");
+  return c.json({ ok: true, jobId: job.id, kind: "full" });
+});
+
+app.post("/hooks/index", async (c) => {
+  const slug = c.req.query("slug");
+  if (!slug) return c.json({ ok: false, error: "slug query param required" }, 400);
+  // slug is the relative path without extension, e.g. docs/websocket/contract
+  const relPath = slug.endsWith(".md") || slug.endsWith(".mdx") ? slug : `${slug}.md`;
+  const job = await enqueueIndexDoc(relPath, "git-push");
+  return c.json({ ok: true, jobId: job.id, kind: "doc", relPath });
+});
+
 // Mount tRPC at /trpc/*. The fetch adapter is the canonical Bun/Hono adapter.
 app.all("/trpc/*", (c) =>
   fetchRequestHandler({

apps/api/src/router.ts

@@ -7,7 +7,12 @@ import {
   keywordSearch,
   listDocuments,
   semanticSearch,
+  listRevisions,
+  getRevision,
+  restoreRevision,
 } from "@mcpedia/core";
+import { getQueue, INDEX_QUEUE } from "@mcpedia/queue";
+import { getConnection, BULLMQ_PREFIX } from "@mcpedia/queue/client";
 
 export const appRouter = router({
   search: publicProcedure
@@ -33,6 +38,58 @@ export const appRouter = router({
   related: publicProcedure
     .input(z.object({ slug: z.string(), limit: z.number().int().min(1).max(20).default(5) }))
     .query(async ({ input }) => getRelated(input.slug, input.limit)),
+
+  // --- Phase 3: revisions ---
+  revisions: publicProcedure
+    .input(z.object({ slug: z.string(), limit: z.number().int().min(1).max(50).default(20) }))
+    .query(async ({ input }) => listRevisions(input.slug, input.limit)),
+
+  getRevision: publicProcedure
+    .input(z.object({ id: z.string() }))
+    .query(async ({ input }) => getRevision(input.id)),
+
+  restoreRevision: publicProcedure
+    .input(z.object({ id: z.string() }))
+    .mutation(async ({ input }) => restoreRevision(input.id)),
+
+  // --- Phase 3: async job status ---
+  jobStatus: publicProcedure
+    .input(z.object({ id: z.string() }))
+    .query(async ({ input }) => {
+      const queue = getQueue();
+      const job = await queue.getJob(input.id);
+      if (!job) return { exists: false };
+      const state = await job.getState();
+      const failedReason = job.failedReason;
+      const returnvalue = job.returnvalue;
+      const progress = job.progress;
+      return {
+        exists: true,
+        id: job.id,
+        name: job.name,
+        state,
+        progress,
+        failedReason,
+        returnvalue,
+        attemptsMade: job.attemptsMade,
+      };
+    }),
+
+  queueStatus: publicProcedure.query(async () => {
+    const queue = getQueue();
+    const [waiting, active, completed, failed, delayed] = await Promise.all([
+      queue.getWaitingCount(),
+      queue.getActiveCount(),
+      queue.getCompletedCount(),
+      queue.getFailedCount(),
+      queue.getDelayedCount(),
+    ]);
+    return {
+      queue: INDEX_QUEUE,
+      prefix: BULLMQ_PREFIX,
+      counts: { waiting, active, completed, failed, delayed },
+    };
+  }),
 });
 
 export type AppRouter = typeof appRouter;