pi-para 0.5.2

package/src/index.ts

@@ -0,0 +1,384 @@
+/**
+ * pi-para — PARA Knowledge Base Extension for pi
+ *
+ * Main extension entry point. Wires together wiki filesystem, qmd store,
+ * scope detection, context injection, tools, and commands.
+ *
+ * Session capture is handled by a separate daemon (pi-para-daemon).
+ * This extension registers completed sessions for the daemon to process.
+ */
+
+import { readFile, writeFile, mkdir, appendFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir, networkInterfaces } from "node:os";
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { QMDStore } from "qmd-engine";
+
+import type { ProjectScope } from "./scope.js";
+import { detectScope } from "./scope.js";
+import { initWiki } from "./wiki.js";
+import { openStore, closeStore } from "./store.js";
+import { registerTools } from "./tools.js";
+import { setupContextInjection, markContextDirty } from "./context.js";
+import type { ContextConfig } from "./context.js";
+import { registerCommands } from "./commands.js";
+import { createServer } from "node:http";
+
+// Re-export public types for consumers
+export type { ParaCategory, WikiPage, PageFrontmatter, PageRef, LogEntry } from "./wiki.js";
+export type { WikiSearchOptions, WikiSearchResult } from "./store.js";
+export type { ProjectScope, ScopeConfig } from "./scope.js";
+export type { IngestOptions, IngestReport, IngestResult } from "./ingest.js";
+export type { QueryOptions, QueryResult } from "./query.js";
+export type { LintOptions, LintReport, LintIssue, WikiStats } from "./lint.js";
+export type { ContextOptions } from "./context.js";
+export type { RawSource, SessionDigest } from "./raw.js";
+export type { SummarizeOptions } from "./summarize.js";
+
+// -- Config ------------------------------------------------------------------
+
+interface ParaConfig {
+  wikiDir: string;
+  contextMaxTokens: number;
+  contextIncludeSchema: boolean;
+  contextIncludeIndex: boolean;
+  lintAutoFix: boolean;
+  lintStaleDays: number;
+  searchLimit: number;
+  searchIncludeArchives: boolean;
+  searchGraphBoost: boolean;
+  /** Daemon LLM: "provider/model-id" (e.g. "anthropic/claude-sonnet-4").
+   *  If not set, daemon auto-detects from pi env keys or qmd config. */
+  daemonModel: string | null;
+  /** Web wiki UI settings */
+  webWiki: {
+    enabled: boolean;
+    host: string;
+    port: number;
+  };
+  /** GEPA prompt optimizer settings */
+  gepa: {
+    /** When true, load optimized prompts from ~/.pi/wiki/gepa/optimized/ at runtime. */
+    useOptimized: boolean;
+    /** Student model — runs the proxy (generates wiki output). Fast + cheap.
+     *  Default: anthropic/claude-sonnet-4-20250514 */
+    studentModel: string | null;
+    /** Teacher/reflection model — proposes instruction mutations. Smart + creative.
+     *  Default: anthropic/claude-opus-4-6 */
+    teacherModel: string | null;
+    /** Judge model — scores candidate outputs (LLM-as-judge). Fast + cheap.
+     *  Default: same as studentModel */
+    judgeModel: string | null;
+    /** Budget preset: light (~460 calls), medium (~1500), heavy (~5000) */
+    auto: "light" | "medium" | "heavy";
+    /** Parallel eval threads */
+    threads: number;
+    /** Random seed for reproducibility */
+    seed: number;
+  };
+}
+
+function getDefaultConfig(): ParaConfig {
+  return {
+    wikiDir: join(homedir(), ".pi", "wiki"),
+    contextMaxTokens: 4000,
+    contextIncludeSchema: true,
+    contextIncludeIndex: true,
+    lintAutoFix: true,
+    lintStaleDays: 90,
+    searchLimit: 10,
+    searchIncludeArchives: false,
+    searchGraphBoost: true,
+    daemonModel: null,
+    webWiki: {
+      enabled: false,
+      host: "0.0.0.0",
+      port: 10973,
+    },
+    gepa: {
+      useOptimized: true,
+      studentModel: null,
+      teacherModel: null,
+      judgeModel: null,
+      auto: "light",
+      threads: 2,
+      seed: 42,
+    },
+  };
+}
+
+async function loadConfig(): Promise<ParaConfig> {
+  const defaults = getDefaultConfig();
+  const configPath = join(defaults.wikiDir, "config.json");
+  try {
+    const raw = await readFile(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<ParaConfig>;
+    const wikiDir = parsed.wikiDir
+      ? parsed.wikiDir.replace(/^~\//, `${homedir()}/`)
+      : defaults.wikiDir;
+    return { ...defaults, ...parsed, wikiDir };
+  } catch {
+    try {
+      await mkdir(dirname(configPath), { recursive: true });
+      await writeFile(configPath, JSON.stringify(defaults, null, 2), "utf-8");
+    } catch {
+      // Non-fatal
+    }
+    return { ...defaults };
+  }
+}
+
+// -- LAN IP detection --------------------------------------------------------
+
+/** Check if the daemon's web server is alive on the given port. */
+function checkWebServerAlive(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = createServer().listen(port, "127.0.0.1");
+    req.on("error", (err: NodeJS.ErrnoException) => {
+      req.close();
+      // EADDRINUSE means something is already listening — daemon is running
+      resolve(err.code === "EADDRINUSE");
+    });
+    req.on("listening", () => {
+      // Port is free — no daemon web server
+      req.close();
+      resolve(false);
+    });
+  });
+}
+
+function getLanIp(): string | null {
+  const interfaces = networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    const addrs = interfaces[name];
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal) {
+        return addr.address;
+      }
+    }
+  }
+  return null;
+}
+
+// -- Session state -----------------------------------------------------------
+
+interface ParaSessionState {
+  lastScope: ProjectScope;
+  sessionFile: string | null;
+}
+
+const ENTRY_TYPE = "pi-para-state";
+
+function reconstructState(ctx: ExtensionContext): ParaSessionState | null {
+  let latest: ParaSessionState | null = null;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "custom" && entry.customType === ENTRY_TYPE) {
+      latest = entry.data as ParaSessionState;
+    }
+  }
+  return latest;
+}
+
+// -- Extension entry point ---------------------------------------------------
+
+export default async function piPara(pi: ExtensionAPI): Promise<void> {
+  const config = await loadConfig();
+  const wikiDir = config.wikiDir;
+
+  let store: QMDStore | null = null;
+  let currentScope: ProjectScope | null = null;
+  let storeDisabled = false;
+
+
+  const getScope = (): ProjectScope => {
+    if (!currentScope) {
+      return { name: "unknown", include: ["unknown"], exclude: [], source: "dirname" };
+    }
+    return currentScope;
+  };
+
+  const setScope = (scope: ProjectScope): void => {
+    currentScope = scope;
+    markContextDirty();
+    pi.appendEntry(ENTRY_TYPE, {
+      lastScope: scope,
+      sessionFile: null,
+    } satisfies ParaSessionState);
+  };
+
+  const getConfig = (): ContextConfig => ({
+    contextMaxTokens: config.contextMaxTokens,
+    contextIncludeSchema: config.contextIncludeSchema,
+    contextIncludeIndex: config.contextIncludeIndex,
+  });
+
+  // Lazy retry: if the store failed at startup, try reopening on first tool use.
+  // This handles cases where the db was temporarily locked or had transient errors.
+  let storeRetrying = false;
+  async function retryStoreOpen(): Promise<boolean> {
+    if (storeRetrying) return false;
+    storeRetrying = true;
+    try {
+      store = await openStore(wikiDir);
+      storeDisabled = false;
+      markContextDirty(); // rebuild context now that store works
+      return true;
+    } catch {
+      return false;
+    } finally {
+      storeRetrying = false;
+    }
+  }
+
+  // Store proxy — delegates to real store once opened, with lazy retry on failure
+  const storeProxy = new Proxy({} as QMDStore, {
+    get(_target, prop) {
+      if (!store) {
+        if (storeDisabled) {
+          // Return an async function that retries opening the store first
+          return async (...args: unknown[]) => {
+            const reopened = await retryStoreOpen();
+            if (reopened && store) {
+              const method = (store as unknown as Record<string, unknown>)[prop as string];
+              if (typeof method === "function") {
+                return (method as Function).apply(store, args);
+              }
+              return method;
+            }
+            throw new Error("Wiki search is disabled: qmd store failed to open.");
+          };
+        }
+        return (..._args: unknown[]) => {
+          throw new Error("Wiki store not initialized yet.");
+        };
+      }
+      return (store as unknown as Record<string, unknown>)[prop as string];
+    },
+  });
+
+  // Register tools, context injection, commands
+  registerTools(pi, wikiDir, storeProxy, getScope, markContextDirty, () => config.searchGraphBoost);
+  setupContextInjection(pi, wikiDir, storeProxy, () => currentScope, getConfig);
+  registerCommands(pi, wikiDir, storeProxy, getScope, setScope);
+
+  // -- session_start ---------------------------------------------------------
+
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.setStatus("pi-para", "wiki: loading...");
+
+    try {
+      await initWiki(wikiDir);
+    } catch (err) {
+      ctx.ui.notify(
+        `Wiki init failed: ${err instanceof Error ? err.message : String(err)}`,
+        "error",
+      );
+    }
+
+    ctx.ui.setStatus("pi-para", "wiki: indexing...");
+    storeDisabled = false;
+    try {
+      store = await openStore(wikiDir);
+    } catch (err) {
+      store = null;
+      storeDisabled = true;
+      ctx.ui.notify(
+        `Wiki search disabled: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
+
+    currentScope = await detectScope(ctx.cwd);
+
+    const savedState = reconstructState(ctx);
+    if (savedState?.lastScope.source === "config") {
+      currentScope = savedState.lastScope;
+    }
+
+    pi.appendEntry(ENTRY_TYPE, {
+      lastScope: currentScope,
+      sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+    } satisfies ParaSessionState);
+
+    // Check if daemon's web wiki server is running (don't start our own)
+    if (config.webWiki.enabled) {
+      const port = config.webWiki.port;
+      try {
+        const alive = await checkWebServerAlive(port);
+        if (alive) {
+          const lanIp = getLanIp();
+          const url = lanIp ? `http://${lanIp}:${port}` : `http://localhost:${port}`;
+          ctx.ui.setStatus("pi-para", `wiki: ${url}`);
+        } else {
+          ctx.ui.setStatus("pi-para", "wiki: ready (start daemon for web UI)");
+          setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 5000);
+        }
+      } catch {
+        ctx.ui.setStatus("pi-para", "wiki: ready");
+        setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 3000);
+      }
+    } else {
+      ctx.ui.setStatus("pi-para", "wiki: ready");
+      setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 3000);
+    }
+  });
+
+  // -- session_tree ----------------------------------------------------------
+
+  pi.on("session_tree", async (_event, ctx) => {
+    const savedState = reconstructState(ctx);
+    if (savedState?.lastScope.source === "config") {
+      currentScope = savedState.lastScope;
+    } else {
+      currentScope = await detectScope(ctx.cwd);
+    }
+    markContextDirty();
+  });
+
+  // -- session_compact: register session for daemon capture on compaction ----
+
+  pi.on("session_compact", async (_event, ctx) => {
+    // Compaction means the session has accumulated enough content that details
+    // are about to be compressed/lost. Perfect time to capture knowledge.
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    if (sessionFile) {
+      try {
+        const registry = join(wikiDir, ".completed-sessions");
+        const entry = `${new Date().toISOString()}|${sessionFile}\n`;
+        await appendFile(registry, entry);
+        ctx.ui.setStatus("pi-para", "wiki: capture queued (compaction)");
+        setTimeout(() => ctx.ui.setStatus("pi-para", undefined), 5000);
+      } catch {
+        // Non-fatal
+      }
+    }
+  });
+
+  // -- session_shutdown: register session for daemon, close store ------------
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    // 1. Register session as completed (for daemon to process later)
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    if (sessionFile) {
+      try {
+        const registry = join(wikiDir, ".completed-sessions");
+        const entry = `${new Date().toISOString()}|${sessionFile}\n`;
+        await appendFile(registry, entry);
+      } catch {
+        // Non-fatal — daemon can also discover sessions via filesystem scan
+      }
+    }
+
+    // 2. Close the store (instant)
+    if (store) {
+      try {
+        await closeStore(store);
+      } catch {
+        // Non-fatal
+      }
+      store = null;
+    }
+  });
+}

package/src/ingest.ts

@@ -0,0 +1,177 @@
+/**
+ * Ingest pipeline — processes sources and integrates knowledge into the wiki.
+ *
+ * Resolves source content (URL, file, text), saves raw copy to the vault,
+ * and returns structured data for the caller (tool or standalone agent)
+ * to pass to the LLM for synthesis into wiki pages.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { QMDStore } from "qmd-engine";
+import type { ParaCategory, PageRef, LogEntry } from "./wiki.js";
+import { readSchema, readIndex } from "./wiki.js";
+import { saveRawSource } from "./raw.js";
+import type { ProjectScope } from "./scope.js";
+
+// -- Types ------------------------------------------------------------------
+
+export interface IngestOptions {
+  source: string; // URL, file path, or raw text
+  sourceType?: "url" | "file" | "text"; // auto-detected if omitted
+  scope?: string[]; // override auto-detected scope
+  category?: ParaCategory; // hint for PARA classification
+}
+
+export interface IngestReport {
+  pagesCreated: PageRef[];
+  pagesUpdated: PageRef[];
+  logEntry: LogEntry;
+}
+
+/** Structure returned by LLM during ingest. */
+export interface IngestResult {
+  newPages: Array<{
+    category: ParaCategory;
+    slug: string;
+    title: string;
+    scope: string[];
+    tags: string[];
+    body: string;
+  }>;
+  updatedPages: Array<{
+    category: ParaCategory;
+    slug: string;
+    appendOrReplace: "append" | "replace";
+    body: string;
+  }>;
+  indexUpdate: string;
+  logSummary: string;
+}
+
+/** Resolved source data from the ingest pipeline. */
+export interface ResolvedSource {
+  /** Original source string (URL, path, or text) */
+  source: string;
+  /** Detected or explicit source type */
+  sourceType: "url" | "file" | "text";
+  /** Fetched/read source content */
+  content: string;
+  /** Path in raw/ vault (undefined for inline text) */
+  rawPath: string | undefined;
+  /** Schema.md content for LLM context */
+  schema: string;
+  /** Index.md content for LLM context */
+  index: string;
+  /** Scope tags to assign */
+  scopeTags: string[];
+  /** Scope name */
+  scopeName: string;
+  /** Category hint (if provided) */
+  categoryHint: ParaCategory | undefined;
+}
+
+// -- Source resolution -------------------------------------------------------
+
+/** Detect source type from the source string. */
+export function detectSourceType(source: string): "url" | "file" | "text" {
+  if (/^https?:\/\//i.test(source)) return "url";
+  if (/^\/|^\.\/|^~\/|^[a-zA-Z]:\\/.test(source)) return "file";
+  // Heuristic: if it contains newlines or is very long, treat as text
+  if (source.includes("\n") || source.length > 500) return "text";
+  // Check for file-like paths (has extension)
+  if (/\.\w{1,10}$/.test(source) && !source.includes(" ")) return "file";
+  return "text";
+}
+
+/** Fetch content from a URL. */
+export async function fetchUrl(url: string): Promise<string> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  return response.text();
+}
+
+/** Read content from a file path. */
+export async function readFileSource(filePath: string): Promise<string> {
+  const resolved = filePath.replace(/^~\//, `${process.env.HOME ?? ""}/`);
+  return readFile(resolved, "utf-8");
+}
+
+// -- Main pipeline -----------------------------------------------------------
+
+/**
+ * Resolve a source and prepare it for LLM synthesis.
+ *
+ * This is the reusable library function. It:
+ * 1. Detects or uses the explicit source type
+ * 2. Fetches URL / reads file / uses text directly
+ * 3. Saves a raw copy to the vault (for non-text sources)
+ * 4. Reads schema.md and index.md for LLM context
+ * 5. Returns everything the caller needs to build an LLM prompt
+ *
+ * The caller (tool or standalone agent) assembles the prompt and
+ * passes it to the LLM, which calls wiki_write to create pages.
+ */
+export async function resolveSource(
+  wikiDir: string,
+  options: IngestOptions,
+  scope: ProjectScope,
+): Promise<ResolvedSource> {
+  const sourceType = options.sourceType ?? detectSourceType(options.source);
+
+  // Resolve source content
+  let content: string;
+  switch (sourceType) {
+    case "url":
+      content = await fetchUrl(options.source);
+      break;
+    case "file":
+      content = await readFileSource(options.source);
+      break;
+    case "text":
+      content = options.source;
+      break;
+  }
+
+  // Save raw source (skip for inline text — it's ephemeral)
+  let rawPath: string | undefined;
+  if (sourceType !== "text") {
+    rawPath = await saveRawSource(wikiDir, {
+      type: sourceType,
+      content,
+      originalPath: options.source,
+    });
+  }
+
+  // Read schema and index for LLM context
+  const schema = await readSchema(wikiDir);
+  const index = await readIndex(wikiDir);
+
+  // Build scope info
+  const scopeTags = options.scope ?? scope.include;
+
+  return {
+    source: options.source,
+    sourceType,
+    content,
+    rawPath,
+    schema,
+    index,
+    scopeTags,
+    scopeName: scope.name,
+    categoryHint: options.category,
+  };
+}
+
+/** Maximum source content length before truncation. */
+export const MAX_SOURCE_LENGTH = 50_000;
+
+/**
+ * Truncate source content if it exceeds the limit.
+ * Returns the truncated content with a marker.
+ */
+export function truncateSource(content: string, maxLength: number = MAX_SOURCE_LENGTH): string {
+  if (content.length <= maxLength) return content;
+  return content.slice(0, maxLength) + "\n\n[... truncated]";
+}