@zosmaai/pi-llm-wiki 0.10.9 → 0.11.1

package/extensions/llm-wiki/index.ts

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { bootstrapVault } from "./lib/bootstrap.js";
 import { installGuardrails } from "./lib/guardrails.js";
 import { buildAgentStartInjection, normalizeSystemPrompt } from "./lib/inject.js";
 import { registerWikiModelCommand } from "./lib/model-command.js";
@@ -39,14 +40,8 @@ import {
   registerWikiDistillSkills,
   registerWikiRecallSkill,
 } from "./lib/trajectory.js";
-import {
-  ensureVaultStructure,
-  fmtDate,
-  getVaultPaths,
-  migrateDoubledPersonalVault,
-  resolveVaultPaths,
-  writeJson,
-} from "./lib/utils.js";
+import { migrateDoubledPersonalVault, resolveVaultPaths } from "./lib/utils.js";
+import { inspectWritableVault } from "./lib/vault-format.js";
 import { applySessionStartStatus } from "./lib/visible-status.js";
 
 /**
@@ -144,33 +139,18 @@ export default function (pi: ExtensionAPI) {
 
     const paths = resolveVaultPaths(process.cwd());
     if (!existsSync(join(paths.dotWiki, "config.json"))) {
-      // Silently create the wiki vault — no UI prompts
-      // Topic/mode will be inferred from user's first prompt via before_agent_start
-      const root = paths.root;
-      const vaultPaths = getVaultPaths(root);
-      ensureVaultStructure(vaultPaths);
-
-      writeJson(join(vaultPaths.dotWiki, "config.json"), {
-        name: "pending",
-        mode: "personal",
-        topic: "pending",
-        created: fmtDate(),
-        version: "1.0",
-      });
-
-      const schema = [
-        "# LLM Wiki Schema",
-        "",
-        "## Ownership Rules",
-        "",
-        "| Path | Owner | Rule |",
-        "|------|-------|------|",
-        "| raw/** | extension | immutable after capture |",
-        "| wiki/** | model + user | editable knowledge pages |",
-        "| meta/* | extension | auto-generated |",
-        "| . | human + explicit request | operating rules |",
-      ].join("\n");
-      writeFileSync(join(vaultPaths.dotWiki, "WIKI_SCHEMA.md"), schema, "utf-8");
+      // Silently create the wiki vault — no UI prompts. Topic/mode will be
+      // inferred from the user's first prompt via before_agent_start.
+      const result = bootstrapVault(paths, { topic: "pending", mode: "personal" });
+      if (!result.ok || !result.projection.ok) {
+        ctx.ui.setStatus(
+          "llm-wiki",
+          `🧠 Wiki setup blocked: ${
+            result.ok ? result.projection.diagnostics[0].message : result.diagnostics[0].message
+          }`,
+        );
+        return;
+      }
 
       needsTopicInference = true;
       // INTENTIONALLY NOT gated by `noticesEnabled` (issues #77, #84): one-shot
@@ -180,6 +160,12 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
+    const writable = inspectWritableVault(paths);
+    if (!writable.ok) {
+      ctx.ui.setStatus("llm-wiki", `🧠 Wiki setup blocked: ${writable.diagnostics[0].message}`);
+      return;
+    }
+
     // Surface the "wiki active" badge and the active background task model
     // (issue #69), both gated by `llm-wiki.notices` (issue #77, regression
     // fixed in #83, helper extracted in #84). `ensureConfig` MUST run first so

package/extensions/llm-wiki/lib/bootstrap.ts

@@ -0,0 +1,87 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { KnowledgeDiagnostic } from "./knowledge-document.js";
+import { type ProjectionResult, appendEvent, rebuildMetadata } from "./metadata.js";
+import { type VaultPaths, ensureVaultStructure, fmtDate, writeJson } from "./utils.js";
+import { inspectWritableVault, readVaultConfig } from "./vault-format.js";
+
+export const WIKI_SCHEMA = [
+  "# LLM Wiki Schema",
+  "",
+  "## Ownership Rules",
+  "",
+  "| Path | Owner | Rule |",
+  "|------|-------|------|",
+  "| raw/** | extension | immutable after capture |",
+  "| wiki/** | model + user | editable knowledge pages |",
+  "| meta/events.jsonl | extension tools | append-only authoritative state |",
+  "| meta/* except events.jsonl | extension | generated projections |",
+  "| . | human + explicit request | operating rules |",
+  "",
+  "Back up `meta/events.jsonl` to preserve activity history. Generated logs cannot reconstruct it.",
+  "",
+  "## Source Packet Format",
+  "",
+  "```",
+  "raw/sources/SRC-YYYY-MM-DD-NNN/",
+  "  manifest.json",
+  "  original/",
+  "  extracted.md",
+  "  attachments/",
+  "```",
+  "",
+  "## Page Types",
+  "",
+  "- **source** — what this specific source says",
+  "- **entity** — people, orgs, tools, products",
+  "- **concept** — ideas, patterns, frameworks",
+  "- **synthesis** — cross-source theses and tensions",
+  "- **analysis** — durable filed answers from queries",
+  "- **requirement** — atomic requirements with status, priority, and traceability",
+  "",
+  "## Linking Style",
+  "",
+  "- New internal links: [label](/folder/page.md)",
+  "- Legacy readable links: [[folder/page]]",
+  "- Source citation: [source](/sources/SRC-YYYY-MM-DD-NNN.md)",
+  "",
+].join("\n");
+
+export interface BootstrapInput {
+  topic: string;
+  mode: string;
+}
+
+export type BootstrapResult =
+  | { ok: true; created: boolean; projection: ProjectionResult }
+  | { ok: false; created: false; diagnostics: KnowledgeDiagnostic[] };
+
+export function bootstrapVault(paths: VaultPaths, input: BootstrapInput): BootstrapResult {
+  const configPath = join(paths.dotWiki, "config.json");
+  const created = !existsSync(paths.dotWiki);
+  let existing: Record<string, unknown> = {};
+
+  if (!created) {
+    const writable = inspectWritableVault(paths);
+    if (!writable.ok) return { ok: false, created: false, diagnostics: writable.diagnostics };
+    const config = readVaultConfig(paths);
+    if (!config.ok) return { ok: false, created: false, diagnostics: [config.diagnostic] };
+    existing = config.config;
+  }
+
+  const config: Record<string, unknown> = {
+    ...existing,
+    name: input.topic,
+    mode: input.mode,
+    topic: input.topic,
+    created: existing.created ?? fmtDate(),
+    version: existing.version ?? "1.0",
+    ...(created ? { knowledge_format: "okf-0.2" } : {}),
+  };
+
+  ensureVaultStructure(paths);
+  writeJson(configPath, config);
+  writeFileSync(join(paths.dotWiki, "WIKI_SCHEMA.md"), WIKI_SCHEMA, "utf8");
+  appendEvent(paths, { kind: "bootstrap", topic: input.topic, mode: input.mode });
+  return { ok: true, created, projection: rebuildMetadata(paths) };
+}

package/extensions/llm-wiki/lib/embeddings.ts

@@ -3,10 +3,12 @@ import { existsSync, readFileSync } from "node:fs";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
 import { join } from "node:path";
+import { parseKnowledgeDocument } from "./knowledge-document.js";
 import type { Registry } from "./metadata.js";
 import type { LaunchCtx, Runtime } from "./runtime.js";
 import type { TaskConfig } from "./task-config.js";
-import { type VaultPaths, parseFrontmatter, readJson, writeJson } from "./utils.js";
+import { type VaultPaths, readJson, writeJson } from "./utils.js";
+import { assertWritableVault } from "./vault-format.js";
 
 /**
  * Background semantic embeddings, computed at write time (issue #66, epic #63).
@@ -166,6 +168,7 @@ export function readEmbeddingStore(paths: VaultPaths): EmbeddingStore {
 }
 
 export function writeEmbeddingStore(paths: VaultPaths, store: EmbeddingStore): void {
+  assertWritableVault(paths);
   writeJson(embeddingStorePath(paths), store);
 }
 
@@ -189,8 +192,9 @@ function readPageText(paths: VaultPaths, id: string): PageText | undefined {
   const pagePath = join(paths.wiki, `${id}.md`);
   if (!existsSync(pagePath)) return undefined;
   const raw = readFileSync(pagePath, "utf-8");
-  const { frontmatter, body } = parseFrontmatter(raw);
-  const text = buildEmbeddingText(id, frontmatter, body);
+  const result = parseKnowledgeDocument(raw, `${id}.md`);
+  if (!result.ok) return undefined;
+  const text = buildEmbeddingText(id, result.document.frontmatter, result.document.body);
   return { id, text, hash: contentHash(text) };
 }
 
@@ -205,6 +209,7 @@ export async function embedPages(
   embedder: Embedder,
   opts: { force?: boolean } = {},
 ): Promise<EmbedStats> {
+  assertWritableVault(paths);
   const store = readEmbeddingStore(paths);
   const targets: PageText[] = [];
   let skipped = 0;
@@ -251,6 +256,7 @@ export async function reindexEmbeddings(
   embedder: Embedder,
   opts: { force?: boolean } = {},
 ): Promise<ReindexStats> {
+  assertWritableVault(paths);
   const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
     version: "1.0",
     last_updated: "",

package/extensions/llm-wiki/lib/guardrails.ts

@@ -1,10 +1,11 @@
-import { resolve, sep } from "node:path";
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { scheduleReindex } from "./indexing.js";
 import { rebuildMetadataLight } from "./metadata.js";
 import type { Runtime } from "./runtime.js";
-import { isProtectedPath, resolveVaultPaths } from "./utils.js";
+import { isPathWithin, isProtectedPath, resolveVaultPaths } from "./utils.js";
+import type { VaultPaths } from "./utils.js";
+import { inspectVaultFormat, isGeneratedOkfPath } from "./vault-format.js";
 
 /**
  * Guardrails and auto-rebuild hooks for the LLM Wiki extension.
@@ -172,26 +173,35 @@ export function extractMutationPaths(input: unknown): string[] {
 
 /** True when a write or patch-shaped edit targets a page in the wiki directory. */
 export function hasWikiMutation(input: unknown, wikiPath: string): boolean {
-  const resolvedWikiPath = resolve(wikiPath);
-  return extractMutationPaths(input).some((path) => {
-    const resolvedPath = resolve(path);
-    return (
-      resolvedPath === resolvedWikiPath || resolvedPath.startsWith(`${resolvedWikiPath}${sep}`)
-    );
-  });
+  return extractMutationPaths(input).some((path) => isPathWithin(wikiPath, path));
+}
+
+export function mutationBlockReason(path: string, paths: VaultPaths): string | undefined {
+  const protectedPath = isProtectedPath(path, paths);
+  if (protectedPath.protected) return protectedPath.reason;
+
+  if (isPathWithin(paths.dotWiki, path)) {
+    const state = inspectVaultFormat(paths);
+    if (state.blocking) {
+      return `Wiki vault configuration is invalid: ${state.diagnostics[0].message}`;
+    }
+  }
+
+  if (isGeneratedOkfPath(path, paths)) {
+    return "Generated OKF indexes and log are read-only. Use wiki_rebuild_meta or the page-producing tool that owns the source mutation.";
+  }
+  return undefined;
 }
 
 /** Install guardrails on the extension API. */
 export function installGuardrails(pi: ExtensionAPI, runtime?: Runtime): void {
-  // Block direct edits to raw/ and meta/
+  // Block direct edits to raw/ and meta/, plus OKF generated projections
   pi.on("tool_call", async (event) => {
     if (isToolCallEventType("write", event)) {
       const path = event.input.path as string;
       const paths = resolveVaultPaths(process.cwd());
-      const check = isProtectedPath(path, paths);
-      if (check.protected) {
-        return { block: true, reason: check.reason };
-      }
+      const reason = mutationBlockReason(path, paths);
+      if (reason) return { block: true, reason };
     }
 
     if (isToolCallEventType("edit", event)) {
@@ -203,10 +213,8 @@ export function installGuardrails(pi: ExtensionAPI, runtime?: Runtime): void {
 
       const paths = resolveVaultPaths(process.cwd());
       for (const path of targetPaths) {
-        const check = isProtectedPath(path, paths);
-        if (check.protected) {
-          return { block: true, reason: check.reason };
-        }
+        const reason = mutationBlockReason(path, paths);
+        if (reason) return { block: true, reason };
       }
     }
   });

package/extensions/llm-wiki/lib/indexing.ts

@@ -64,7 +64,8 @@ export function scheduleReindex(
       // that land during embedding are not lost.
       while (dirty.has(root)) {
         dirty.delete(root);
-        rebuildMetadataLight(paths);
+        const projection = rebuildMetadataLight(paths);
+        if (!projection.ok) continue;
 
         // Refresh embeddings only after metadata is consistent. Stale-aware and
         // a no-op unless an embedder is configured.