pi-para 0.5.2 → 0.5.5

package/src/wiki-tool-guidance.ts

@@ -0,0 +1,84 @@
+export type WikiToolName =
+  | "wiki_ingest"
+  | "wiki_query"
+  | "wiki_edit"
+  | "wiki_write"
+  | "wiki_read"
+  | "wiki_move"
+  | "wiki_lint"
+  | "wiki_migrate"
+  | "wiki_summarize";
+
+export const WIKI_TOOL_DESCRIPTIONS: Record<WikiToolName, string> = {
+  wiki_ingest: "Ingest a URL, file path, or raw text into the PARA wiki and save a raw source copy.",
+  wiki_query: "Search the PARA wiki with scope/category filters and freshness metadata.",
+  wiki_edit: "Atomically edit an existing wiki page with exact oldText→newText replacements.",
+  wiki_write: "Create new pages, append sections, or intentionally replace complete wiki pages.",
+  wiki_read: "Read index.md or a wiki page by path/title, including frontmatter and freshness metadata.",
+  wiki_move: "Move a wiki page between PARA categories and update frontmatter.",
+  wiki_lint: "Run wiki health checks and optionally auto-fix safe issues.",
+  wiki_migrate: "Batch-migrate all wiki pages to the current schema version.",
+  wiki_summarize: "Collect page/category/wiki content for an LLM-written summary.",
+};
+
+export const WIKI_TOOL_SNIPPETS: Record<WikiToolName, string> = {
+  wiki_ingest: "Ingest a source into the PARA wiki.",
+  wiki_query: "Search the PARA wiki for relevant knowledge.",
+  wiki_edit: "Surgically edit an existing wiki page; every oldText must match exactly once.",
+  wiki_write: "Create/append/replace PARA wiki pages; prefer wiki_edit for surgical updates.",
+  wiki_read: "Read index.md or a wiki page and check freshness for page results.",
+  wiki_move: "Move a wiki page between PARA categories.",
+  wiki_lint: "Run wiki health checks and safe autofixes.",
+  wiki_migrate: "Batch-migrate wiki pages to the current schema.",
+  wiki_summarize: "Summarize wiki pages, categories, or the entire wiki.",
+};
+
+const TOOL_SPECIFIC_GUIDELINES: Record<WikiToolName, readonly string[]> = {
+  wiki_ingest: [
+    "Use wiki_ingest when the user provides a URL, file path, or text to add to the knowledge base.",
+    "After ingesting, synthesize durable knowledge with wiki_write/wiki_edit when the source contains reusable facts.",
+  ],
+  wiki_query: [
+    "Use wiki_query before answering questions that may depend on past architecture decisions, debugging history, conventions, or domain knowledge.",
+    "Use global=true only when the answer should search across project scopes.",
+  ],
+  wiki_edit: [
+    "Use wiki_edit after wiki_read when fixing stale, incorrect, or incomplete content.",
+    "Keep oldText as small as possible while still unique in the page body.",
+  ],
+  wiki_write: [
+    "Use wiki_write for new pages, appending new sections, or intentional whole-page replacement.",
+    "mode=create is safe: if a page exists it is skipped, not overwritten.",
+    "Use mode=replace only when deliberately rewriting the entire page.",
+  ],
+  wiki_read: [
+    "When wiki_read returns AGING/STALE/VERY STALE, verify code/config/API claims against source before trusting them.",
+  ],
+  wiki_move: [
+    "Use wiki_move when a page's PARA lifecycle changes, such as archiving a completed project.",
+  ],
+  wiki_lint: [
+    "Use wiki_lint to check orphan pages, broken links, stale pages, scope drift, frontmatter, index drift, and duplicate slugs.",
+  ],
+  wiki_migrate: [
+    "Use wiki_migrate when schemaVersion changes or doctor/lint reports stale page schema.",
+  ],
+  wiki_summarize: [
+    "Use wiki_summarize to gather source material for a synthesized summary; write a durable page only if the summary is worth preserving.",
+  ],
+};
+
+export function getWikiToolGuidelines(name: WikiToolName): string[] {
+  return [...TOOL_SPECIFIC_GUIDELINES[name]];
+}
+
+export function buildWikiToolGuidanceSection(): string {
+  return [
+    "## pi-para Wiki Tool Guidance",
+    "",
+    "- Search with wiki_query when past architecture, debugging, conventions, domain facts, or prior discussion may matter.",
+    "- Treat AGING/STALE/VERY STALE code/config/API claims as untrusted until verified against source; fix wrong pages with wiki_edit.",
+    "- Persist major decisions/debugging/conventions without being asked. Use wiki_edit for surgical fixes; wiki_write create/append for new/additive knowledge; replace only for deliberate full rewrites.",
+    "- Prefer resources/, kebab-case scope/tags, [[wikilinks]], and no secrets.",
+  ].join("\n");
+}

package/src/wiki.ts

@@ -53,7 +53,7 @@ export interface PageRef {
 
 export interface LogEntry {
   date: string;
-  operation: "ingest" | "query" | "lint" | "capture" | "move" | "archive";
+  operation: "ingest" | "query" | "lint" | "capture" | "move" | "archive" | "edit";
   summary: string;
   pages: string[];
 }
@@ -176,6 +176,17 @@ const DEFAULT_LOG = "# Activity Log\n";
 
 const DEFAULT_SESSIONS = "# Session Digests\n";
 
+const DEFAULT_GITIGNORE = `# pi-para generated state (do not version)
+.qmd.sqlite*
+.daemon.sqlite*
+.pi-para.sqlite*
+gepa/input/
+gepa/output/
+
+# local caches/logs
+*.tmp
+`;
+
 // -- Helpers -----------------------------------------------------------------
 
 async function fileExists(path: string): Promise<boolean> {
@@ -216,6 +227,7 @@ export async function initWiki(wikiDir: string): Promise<void> {
   await seedFile(join(wikiDir, "index.md"), DEFAULT_INDEX);
   await seedFile(join(wikiDir, "log.md"), DEFAULT_LOG);
   await seedFile(join(wikiDir, "sessions.md"), DEFAULT_SESSIONS);
+  await seedFile(join(wikiDir, ".gitignore"), DEFAULT_GITIGNORE);
 }
 
 /**
@@ -339,19 +351,22 @@ export async function listPages(
       continue; // directory doesn't exist yet
     }
 
-    for (const entry of entries) {
-      if (!entry.endsWith(".md")) continue;
-      const slug = entry.slice(0, -3);
-      const filePath = join(dirPath, entry);
-      const content = await readFile(filePath, "utf-8");
-      const { frontmatter } = parseFrontmatter(content);
-      refs.push({
-        category: cat,
-        slug,
-        title: frontmatter.title,
-        path: `${cat}/${entry}`,
-      });
-    }
+    const catRefs = await Promise.all(
+      entries
+        .filter((entry) => entry.endsWith(".md"))
+        .map(async (entry): Promise<PageRef> => {
+          const slug = entry.slice(0, -3);
+          const content = await readFile(join(dirPath, entry), "utf-8");
+          const { frontmatter } = parseFrontmatter(content);
+          return {
+            category: cat,
+            slug,
+            title: frontmatter.title,
+            path: `${cat}/${entry}`,
+          };
+        }),
+    );
+    refs.push(...catRefs);
   }
 
   // Sort by category order, then slug alphabetically
@@ -366,6 +381,26 @@ export async function listPages(
   return refs;
 }
 
+/**
+ * List page slugs across all PARA categories without reading file contents.
+ * Much cheaper than listPages() when only slugs are needed (e.g. auto-linking).
+ */
+export async function listPageSlugs(wikiDir: string): Promise<Set<string>> {
+  const slugs = new Set<string>();
+  for (const cat of PARA_CATEGORIES) {
+    let entries: string[];
+    try {
+      entries = await readdir(join(wikiDir, cat));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith(".md")) slugs.add(entry.slice(0, -3));
+    }
+  }
+  return slugs;
+}
+
 /**
  * Read the wiki index (index.md).
  */
@@ -427,8 +462,6 @@ function git(wikiDir: string, args: string[]): Promise<string | null> {
  * each category, and writes a standardized index.md with one-line summaries.
  */
 export async function rebuildIndex(wikiDir: string): Promise<void> {
-  const allRefs = await listPages(wikiDir);
-
   const sections: Record<ParaCategory, string[]> = {
     projects: [],
     areas: [],
@@ -436,14 +469,36 @@ export async function rebuildIndex(wikiDir: string): Promise<void> {
     archives: [],
   };
 
-  for (const ref of allRefs) {
-    const page = await readPage(wikiDir, ref.category, ref.slug);
-    const title = page?.frontmatter.title ?? ref.title;
-    const summary = page ? extractFirstParagraphFromBody(page.body) : "";
-    const desc = summary && summary !== "(no summary)"
-      ? ": " + (summary.length > 120 ? summary.slice(0, 117) + "..." : summary)
-      : "";
-    sections[ref.category].push(`- [[${ref.slug}]] \u2014 ${title}${desc}`);
+  // Single pass: read each page file exactly once, in parallel per category.
+  // (Previously this called listPages() and then readPage() per page, reading
+  // every file twice sequentially — the dominant cost of wiki_write at scale.)
+  for (const cat of PARA_CATEGORIES) {
+    const dirPath = join(wikiDir, cat);
+    let entries: string[];
+    try {
+      entries = await readdir(dirPath);
+    } catch {
+      continue; // directory doesn't exist yet
+    }
+
+    const lines = await Promise.all(
+      entries
+        .filter((entry) => entry.endsWith(".md"))
+        .map((entry) => entry.slice(0, -3))
+        .sort((a, b) => a.localeCompare(b))
+        .map(async (slug) => {
+          const entry = `${slug}.md`;
+          const content = await readFile(join(dirPath, entry), "utf-8");
+          const { frontmatter, body } = parseFrontmatter(content);
+          const title = frontmatter.title;
+          const summary = extractFirstParagraphFromBody(body);
+          const desc = summary && summary !== "(no summary)"
+            ? ": " + (summary.length > 120 ? summary.slice(0, 117) + "..." : summary)
+            : "";
+          return `- [[${slug}]] \u2014 ${title}${desc}`;
+        }),
+    );
+    sections[cat].push(...lines);
   }
 
   const categoryLabels: Record<ParaCategory, string> = {
@@ -534,8 +589,25 @@ export async function gitCommit(
       if (!initResult) return false;
     }
 
-    // Stage all changes
-    await git(wikiDir, ["add", "-A"]);
+    // Stage durable wiki content only. Generated SQLite/search state can be large
+    // and made wiki edits slow when `git add -A` tried to version it.
+    const stageCandidates = [
+      ".gitignore",
+      "schema.md",
+      "index.md",
+      "log.md",
+      "sessions.md",
+      "config.json",
+      ".completed-sessions",
+      ...PARA_CATEGORIES,
+    ];
+    const stagePaths: string[] = [];
+    for (const p of stageCandidates) {
+      if (await fileExists(join(wikiDir, p))) stagePaths.push(p);
+    }
+    if (stagePaths.length > 0) {
+      await git(wikiDir, ["add", "--", ...stagePaths]);
+    }
 
     // Check if there's anything to commit
     const status = await git(wikiDir, ["status", "--porcelain"]);