@zosmaai/pi-llm-wiki 0.10.7 → 0.11.0

package/mcp/index.ts

@@ -4,84 +4,34 @@
  * LLM Wiki MCP Server
  *
  * Exposes wiki tools over the Model Context Protocol (MCP).
- * Run: node mcp/index.js
- * Or via package.json: pi install npm:@zosmaai/pi-llm-wiki && node mcp/index.js
+ * Run: node dist/mcp/index.js
  *
  * Environment:
  *   WIKI_ROOT — path to wiki vault (default: auto-detect from cwd)
- *   WIKI_MARKITDOWN_TIMEOUT_MS — PDF extraction timeout (default: 180000)
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { McpServer, StdioServerTransport } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
-
-// ─── Wiki Vault Detection ──────────────────────────────
-
-interface VaultPaths {
-  root: string;
-  raw: string;
-  rawSources: string;
-  wiki: string;
-  meta: string;
-  dotWiki: string;
-  outputs: string;
-  discoveries: string;
-}
-
-/** Detect vault format at a directory. */
-function detectFormat(dir: string): "new" | "legacy" | "none" {
-  if (existsSync(join(dir, ".llm-wiki", "config.json"))) return "new";
-  if (existsSync(join(dir, ".wiki", "config.json"))) return "legacy";
-  return "none";
-}
-
-function resolveVaultRoot(cwd: string): string | null {
-  // Check cwd first
-  if (detectFormat(cwd) !== "none") return cwd;
-
-  // Walk up
-  const parts = cwd.split("/");
-  for (let i = parts.length - 1; i >= 0; i--) {
-    const dir = parts.slice(0, i + 1).join("/") || "/";
-    if (detectFormat(dir) !== "none") return dir;
-  }
-  return null;
-}
-
-function getPaths(): VaultPaths {
-  const detectedRoot = resolveVaultRoot(process.cwd());
-  const root = process.env.WIKI_ROOT || detectedRoot || process.cwd();
-  const format = process.env.WIKI_ROOT
-    ? detectFormat(root) // Use format detection even with explicit WIKI_ROOT
-    : detectedRoot
-      ? detectFormat(root)
-      : "none";
-
-  if (format === "legacy") {
-    return {
-      root,
-      raw: join(root, "raw"),
-      rawSources: join(root, "raw", "sources"),
-      wiki: join(root, "wiki"),
-      meta: join(root, "meta"),
-      dotWiki: join(root, ".wiki"),
-      outputs: join(root, "outputs"),
-      discoveries: join(root, ".discoveries"),
-    };
-  }
-
-  return {
-    root,
-    raw: join(root, ".llm-wiki", "raw"),
-    rawSources: join(root, ".llm-wiki", "raw", "sources"),
-    wiki: join(root, ".llm-wiki", "wiki"),
-    meta: join(root, ".llm-wiki", "meta"),
-    dotWiki: join(root, ".llm-wiki"),
-    outputs: join(root, ".llm-wiki", "outputs"),
-    discoveries: join(root, ".llm-wiki", ".discoveries"),
-  };
+import { resolveVaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import { createExecApi } from "./exec.js";
+import {
+  captureSourceOperation,
+  recallOperation,
+  retroOperation,
+  searchOperation,
+  statusOperation,
+} from "./operations.js";
+
+const execApi = createExecApi();
+
+// ─── Vault Detection ────────────────────────────────────
+
+/** Resolve vault paths, same as Pi extension. */
+function getPaths(): ReturnType<typeof resolveVaultPaths> {
+  const root = process.env.WIKI_ROOT || process.cwd();
+  return resolveVaultPaths(root);
 }
 
 function hasVault(): boolean {
@@ -89,17 +39,6 @@ function hasVault(): boolean {
   return existsSync(join(paths.dotWiki, "config.json"));
 }
 
-// ─── Helpers ────────────────────────────────────────────
-
-function readJson<T>(path: string, defaultVal: T): T {
-  try {
-    if (!existsSync(path)) return defaultVal;
-    return JSON.parse(readFileSync(path, "utf-8")) as T;
-  } catch {
-    return defaultVal;
-  }
-}
-
 // ─── MCP Server ─────────────────────────────────────────
 
 const server = new McpServer({
@@ -133,72 +72,16 @@ server.registerTool(
     }
 
     const paths = getPaths();
-    const registry = readJson<{
-      pages: Record<string, { type: string; title: string; [key: string]: unknown }>;
-    }>(join(paths.meta, "registry.json"), { pages: {} });
-
-    const terms = query
-      .toLowerCase()
-      .split(/\s+/)
-      .filter((t) => t.length > 2)
-      .slice(0, 10);
-
-    if (terms.length === 0) {
-      return {
-        content: [{ type: "text" as const, text: "Query too short." }],
-      };
-    }
-
-    type Scored = { id: string; score: number };
-    const scored: Scored[] = [];
-
-    for (const [id, entry] of Object.entries(registry.pages)) {
-      let score = 0;
-      const title = String(entry.title || "").toLowerCase();
-      const type = String(entry.type || "").toLowerCase();
-
-      for (const term of terms) {
-        if (id.toLowerCase().includes(term)) score += 3;
-        if (title.includes(term)) score += 4;
-        if (type.includes(term)) score += 1;
-      }
-
-      const tags = String(entry.tags || entry.category || entry.domain || "").toLowerCase();
-      for (const term of terms) {
-        if (tags.includes(term)) score += 2;
-      }
-
-      if (score > 0) scored.push({ id, score });
-    }
+    const result = await recallOperation(paths, query, Math.min(max_results ?? 5, 10));
 
-    scored.sort((a, b) => b.score - a.score);
-    const top = scored.slice(0, Math.min(max_results ?? 5, 10));
-
-    const results = top.map(({ id }) => {
-      const entry = registry.pages[id];
-      let preview = "";
-      const pagePath = join(paths.wiki, `${id}.md`);
-      if (existsSync(pagePath)) {
-        const content = readFileSync(pagePath, "utf-8");
-        preview = content
-          .replace(/^---[\s\S]*?---\n/, "")
-          .trim()
-          .slice(0, 200)
-          .replace(/\n/g, " ");
-      }
-      return {
-        id,
-        title: String(entry?.title || id),
-        type: String(entry?.type || "page"),
-        preview,
-      };
-    });
+    const detailLines = result.diagnostics.map((d) => `⚠️ ${d.code}: ${d.message}`);
+    const detailText = detailLines.length > 0 ? `\n\n${detailLines.join("\n")}` : "";
 
     return {
       content: [
         {
           type: "text" as const,
-          text: JSON.stringify(results, null, 2),
+          text: JSON.stringify(result.results, null, 2) + detailText,
         },
       ],
     };
@@ -233,32 +116,19 @@ server.registerTool(
     }
 
     const paths = getPaths();
-    const registry = readJson<{
-      pages: Record<string, { type: string; title: string; [key: string]: unknown }>;
-    }>(join(paths.meta, "registry.json"), { pages: {} });
-
-    const q = query.toLowerCase();
-    const matches = Object.entries(registry.pages)
-      .filter(([id, entry]) => {
-        const matchesQuery =
-          id.toLowerCase().includes(q) ||
-          String(entry.title).toLowerCase().includes(q) ||
-          String(entry.type).toLowerCase().includes(q);
-        const matchesType = !type || String(entry.type).toLowerCase() === type.toLowerCase();
-        return matchesQuery && matchesType;
-      })
-      .map(([id, entry]) => ({
-        id,
-        title: entry.title,
-        type: entry.type,
-      }));
+    const result = await searchOperation(paths, query, type);
+
+    if (result.matches.length === 0) {
+      return {
+        content: [{ type: "text" as const, text: `No pages found for "${query}"` }],
+      };
+    }
 
     return {
       content: [
         {
           type: "text" as const,
-          text:
-            matches.length > 0 ? JSON.stringify(matches, null, 2) : `No pages found for "${query}"`,
+          text: JSON.stringify(result.matches, null, 2),
         },
       ],
     };
@@ -287,38 +157,13 @@ server.registerTool(
     }
 
     const paths = getPaths();
-    const registry = readJson<{
-      version: string;
-      last_updated: string;
-      pages: Record<string, { type: string; title: string; [key: string]: unknown }>;
-    }>(join(paths.meta, "registry.json"), {
-      version: "1.0",
-      last_updated: "",
-      pages: {},
-    });
-
-    const config = readJson<Record<string, unknown>>(join(paths.dotWiki, "config.json"), {});
-
-    const byType: Record<string, number> = {};
-    for (const entry of Object.values(registry.pages)) {
-      byType[entry.type] = (byType[entry.type] || 0) + 1;
-    }
+    const status = await statusOperation(paths);
 
     return {
       content: [
         {
           type: "text" as const,
-          text: JSON.stringify(
-            {
-              topic: config.topic || "Unknown",
-              mode: config.mode || "personal",
-              totalPages: Object.keys(registry.pages).length,
-              byType,
-              lastUpdated: registry.last_updated || "Never",
-            },
-            null,
-            2,
-          ),
+          text: JSON.stringify(status, null, 2),
         },
       ],
     };
@@ -331,15 +176,11 @@ server.registerTool(
   "wiki_retro",
   {
     description:
-      "Save an atomic insight from a completed task into the wiki. Creates a source packet and source page.",
+      "Save an atomic insight from a completed task into the wiki. Creates a source page.",
     inputSchema: z.object({
       slug: z.string().describe("Unique kebab-case identifier (e.g. 'jwt-revocation-pattern')"),
       title: z.string().describe("Short descriptive title (60 chars max)"),
-      body: z
-        .string()
-        .describe(
-          "Markdown body explaining what was learned. Include [[wikilinks]] to related pages.",
-        ),
+      body: z.string().describe("Markdown body explaining what was learned."),
       category: z
         .string()
         .optional()
@@ -359,24 +200,26 @@ server.registerTool(
       };
     }
 
-    const { saveInsight } = (await import("../extensions/llm-wiki/lib/retro.js")) as {
-      saveInsight: (
-        paths: Record<string, string>,
-        slug: string,
-        title: string,
-        body: string,
-        category?: string,
-      ) => { sourceId: string; packetPath: string; sourcePagePath: string };
-    };
+    const paths = getPaths();
+    const result = await retroOperation(paths, slug, title, body, category);
 
-    const vaultPaths = getPaths();
-    const result = saveInsight(vaultPaths, slug, title, body, category);
+    if (!result.ok) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Vault error: ${result.diagnostics[0].message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
 
     return {
       content: [
         {
           type: "text" as const,
-          text: `Insight saved: ${result.sourceId} — ${title}`,
+          text: `Insight saved: ${result.slug} — ${title}`,
         },
       ],
     };
@@ -396,7 +239,7 @@ server.registerTool(
       title: z.string().optional().describe("Title for the captured source"),
     }),
   },
-  async ({ text, url: urlParam, file_path, title }) => {
+  async ({ text, url, file_path, title }) => {
     if (!hasVault()) {
       return {
         content: [
@@ -409,52 +252,19 @@ server.registerTool(
       };
     }
 
-    const vaultPaths = getPaths();
-    let result: { sourceId: string };
-
-    if (urlParam) {
-      const { captureUrl } = (await import("../extensions/llm-wiki/lib/source-packet.js")) as {
-        captureUrl: (
-          pi: never,
-          paths: Record<string, string>,
-          url: string,
-          signal?: AbortSignal,
-        ) => Promise<{ sourceId: string }>;
-      };
-      result = await captureUrl(
-        { exec: async () => ({ stdout: "", stderr: "", code: 0 }) } as never,
-        vaultPaths,
-        urlParam,
-      );
-    } else if (file_path) {
-      const { captureFile } = (await import("../extensions/llm-wiki/lib/source-packet.js")) as {
-        captureFile: (
-          pi: never,
-          paths: Record<string, string>,
-          filePath: string,
-          signal?: AbortSignal,
-        ) => Promise<{ sourceId: string }>;
-      };
-      result = await captureFile(
-        { exec: async () => ({ stdout: "", stderr: "", code: 0 }) } as never,
-        vaultPaths,
-        file_path,
-      );
-    } else if (text) {
-      const { captureText } = (await import("../extensions/llm-wiki/lib/source-packet.js")) as {
-        captureText: (
-          paths: Record<string, string>,
-          text: string,
-          title?: string,
-        ) => { sourceId: string };
-      };
-      result = captureText(vaultPaths, text, title);
-    } else {
+    const paths = getPaths();
+    const result = await captureSourceOperation(
+      paths,
+      { text, url, filePath: file_path, title },
+      execApi,
+    );
+
+    if (!result.ok) {
       return {
         content: [
           {
             type: "text" as const,
-            text: "Provide one of: text, url, or file_path",
+            text: result.diagnostics[0].message,
           },
         ],
         isError: true,

package/mcp/operations.ts

@@ -0,0 +1,176 @@
+/**
+ * MCP operation adapters over shared wiki services.
+ *
+ * Each operation is a thin, testable wrapper around the same services
+ * used by Pi tools. No operation parses YAML, scans files, scores
+ * registry entries, or builds page strings itself.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type ProjectionResult, rebuildMetadata } from "../extensions/llm-wiki/lib/metadata.js";
+import { searchWiki } from "../extensions/llm-wiki/lib/recall.js";
+import { saveInsight } from "../extensions/llm-wiki/lib/retro.js";
+import { captureFile, captureText, captureUrl } from "../extensions/llm-wiki/lib/source-packet.js";
+import type { VaultPaths } from "../extensions/llm-wiki/lib/utils.js";
+import {
+  VaultWriteError,
+  inspectVaultFormat,
+  inspectWritableVault,
+} from "../extensions/llm-wiki/lib/vault-format.js";
+import { getWikiStatus, searchRegistry } from "../extensions/llm-wiki/lib/wiki-service.js";
+
+function projectionOutcome(
+  projection: ProjectionResult,
+): { ok: true } | { ok: false; diagnostics: Array<{ code: string; message: string }> } {
+  return projection.ok
+    ? { ok: true }
+    : {
+        ok: false,
+        diagnostics: projection.diagnostics.map(({ code, message }) => ({ code, message })),
+      };
+}
+
+/** Shared recall operation: calls searchWiki and appends vault diagnostics. */
+export async function recallOperation(
+  paths: VaultPaths,
+  query: string,
+  maxResults = 5,
+): Promise<{
+  results: Array<{ id: string; title: string; type: string; preview?: string }>;
+  diagnostics: Array<{ code: string; message: string }>;
+}> {
+  const results = searchWiki(paths, query, maxResults);
+  const vaultState = inspectVaultFormat(paths);
+  return {
+    results,
+    diagnostics: vaultState.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+  };
+}
+
+/** Shared search operation: delegates directly to wiki-service. */
+export async function searchOperation(
+  paths: VaultPaths,
+  query: string,
+  type?: string,
+): Promise<{
+  matches: Array<{ id: string; title: string; type: string }>;
+  diagnostics: Array<{ code: string; message: string }>;
+}> {
+  const result = searchRegistry(paths, query, type);
+  return {
+    matches: result.matches,
+    diagnostics: result.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+  };
+}
+
+/** Shared status operation: delegates directly to wiki-service. */
+export async function statusOperation(paths: VaultPaths): Promise<{
+  knowledgeFormat: string;
+  totalPages: number;
+  byType: Record<string, number>;
+  blockingDiagnostics: Array<{ code: string; message: string }>;
+  lastUpdated: string;
+}> {
+  const status = getWikiStatus(paths);
+  return {
+    knowledgeFormat: status.knowledgeFormat,
+    totalPages: status.totalPages,
+    byType: status.byType,
+    blockingDiagnostics: status.blockingDiagnostics.map((d) => ({
+      code: d.code,
+      message: d.message,
+    })),
+    lastUpdated: status.lastUpdated,
+  };
+}
+
+/** Shared retro operation: validates vault then delegates to saveInsight. */
+export async function retroOperation(
+  paths: VaultPaths,
+  slug: string,
+  title: string,
+  body: string,
+  category?: string,
+): Promise<
+  | { ok: true; slug: string; sourcePagePath: string }
+  | { ok: false; diagnostics: Array<{ code: string; message: string }> }
+> {
+  const vaultCheck = inspectWritableVault(paths);
+  if (!vaultCheck.ok) {
+    return {
+      ok: false,
+      diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+    };
+  }
+  try {
+    const result = saveInsight(paths, slug, title, body, category, { rebuild: false });
+    const projection = projectionOutcome(rebuildMetadata(paths));
+    if (!projection.ok) return projection;
+    return { ok: true, slug: result.slug, sourcePagePath: result.sourcePagePath };
+  } catch (error: unknown) {
+    if (error instanceof VaultWriteError) {
+      return {
+        ok: false,
+        diagnostics: error.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+      };
+    }
+    if ((error as Error).message.startsWith("Invalid insight slug:")) {
+      return {
+        ok: false,
+        diagnostics: [{ code: "invalid_insight_slug", message: (error as Error).message }],
+      };
+    }
+    throw error;
+  }
+}
+
+/** Shared capture operation: validates vault then delegates to capture functions. */
+export async function captureSourceOperation(
+  paths: VaultPaths,
+  input: { text?: string; url?: string; filePath?: string; title?: string },
+  execApi: Pick<ExtensionAPI, "exec">,
+): Promise<
+  | { ok: true; sourceId: string }
+  | { ok: false; diagnostics: Array<{ code: string; message: string }> }
+> {
+  const vaultCheck = inspectWritableVault(paths);
+  if (!vaultCheck.ok) {
+    return {
+      ok: false,
+      diagnostics: vaultCheck.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+    };
+  }
+
+  try {
+    let sourceId: string;
+    if (input.url) {
+      sourceId = (await captureUrl(execApi, paths, input.url)).sourceId;
+    } else if (input.filePath) {
+      sourceId = (await captureFile(execApi, paths, input.filePath)).sourceId;
+    } else if (input.text) {
+      sourceId = captureText(paths, input.text, input.title).sourceId;
+    } else {
+      return {
+        ok: false,
+        diagnostics: [
+          {
+            code: "event_missing_kind" as const,
+            message: "Provide one of: text, url, or filePath",
+          },
+        ],
+      };
+    }
+
+    const projection = projectionOutcome(rebuildMetadata(paths));
+    if (!projection.ok) return projection;
+    return { ok: true, sourceId };
+  } catch (error: unknown) {
+    if (error instanceof VaultWriteError) {
+      return {
+        ok: false,
+        diagnostics: error.diagnostics.map((d) => ({ code: d.code, message: d.message })),
+      };
+    }
+    throw error;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.10.7",
+  "version": "0.11.0",
   "description": "Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.",
   "keywords": [
     "pi",
@@ -37,7 +37,9 @@
     "extensions",
     "skills",
     "prompts",
+    "scripts/migrate-llm-wiki.js",
     "mcp",
+    "dist",
     "docs",
     "assets",
     "README.md",
@@ -59,7 +61,7 @@
     ],
     "image": "https://raw.githubusercontent.com/zosmaai/pi-llm-wiki/main/assets/screenshot.png",
     "mcpservers": {
-      "llm-wiki": "node ./mcp/index.ts"
+      "llm-wiki": "node ./dist/mcp/index.js"
     }
   },
   "peerDependencies": {
@@ -72,7 +74,9 @@
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "mdast-util-from-markdown": "^2.0.3",
     "node-html-markdown": "^2.0.0",
+    "yaml": "^2.9.0",
     "zod": "^4.0"
   },
   "devDependencies": {
@@ -81,6 +85,7 @@
     "@mariozechner/pi-ai": "^0.70.2",
     "@mariozechner/pi-coding-agent": "^0.70.2",
     "@mermaid-js/mermaid-cli": "^11.12.0",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22",
     "@vitest/coverage-v8": "^3.2.4",
     "typebox": "^1.1.34",
@@ -91,6 +96,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "build:mcp": "node scripts/build-mcp.js",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --apply .",