@zosmaai/pi-llm-wiki 0.1.6 → 0.2.1

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

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Vault utility functions for the LLM Wiki extension.
+ */
+
+export interface VaultPaths {
+  root: string;
+  raw: string;
+  rawSources: string;
+  wiki: string;
+  meta: string;
+  dotWiki: string;
+  outputs: string;
+  discoveries: string;
+}
+
+/** Resolve vault root from cwd or find nearest wiki root. */
+export function resolveVaultRoot(cwd: string): string {
+  // If cwd has .wiki/config.json, it's the root
+  if (existsSync(join(cwd, ".wiki", "config.json"))) return cwd;
+
+  // Walk up looking for .wiki/config.json
+  let dir = cwd;
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, ".wiki", "config.json"))) return dir;
+    dir = dirname(dir);
+  }
+
+  // Fallback: cwd itself
+  return cwd;
+}
+
+/** Get all vault paths. */
+export function getVaultPaths(root: string): VaultPaths {
+  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"),
+  };
+}
+
+/** Ensure all vault directories exist. */
+export function ensureVaultStructure(paths: VaultPaths): void {
+  const dirs = [
+    paths.rawSources,
+    join(paths.raw, "assets"),
+    join(paths.wiki, "sources"),
+    join(paths.wiki, "entities"),
+    join(paths.wiki, "concepts"),
+    join(paths.wiki, "syntheses"),
+    join(paths.wiki, "analyses"),
+    paths.meta,
+    paths.dotWiki,
+    paths.outputs,
+    paths.discoveries,
+    join(paths.dotWiki, "templates"),
+    join(paths.dotWiki, "templates", "pages"),
+  ];
+  for (const d of dirs) mkdirSync(d, { recursive: true });
+}
+
+/** Read JSON file or return default. */
+export function readJson<T>(path: string, defaultValue: T): T {
+  try {
+    if (!existsSync(path)) return defaultValue;
+    return JSON.parse(readFileSync(path, "utf-8")) as T;
+  } catch {
+    return defaultValue;
+  }
+}
+
+/** Write JSON file atomically. */
+export function writeJson(path: string, data: unknown): void {
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+}
+
+/** Read text file or return empty string. */
+export function readText(path: string): string {
+  try {
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/** Generate the next source ID. */
+export function nextSourceId(paths: VaultPaths): string {
+  const today = new Date().toISOString().split("T")[0];
+  const prefix = `SRC-${today}`;
+
+  if (!existsSync(paths.rawSources)) return `${prefix}-001`;
+
+  const dirs = readdirSync(paths.rawSources)
+    .filter((d) => d.startsWith(prefix))
+    .sort();
+
+  if (dirs.length === 0) return `${prefix}-001`;
+
+  const last = dirs[dirs.length - 1];
+  const num = Number.parseInt(last.slice(-3), 10);
+  return `${prefix}-${String(num + 1).padStart(3, "0")}`;
+}
+
+/** Extract frontmatter from markdown. */
+export function parseFrontmatter(content: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const frontmatter: Record<string, unknown> = {};
+  const lines = match[1].split("\n");
+  for (const line of lines) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      const key = line.slice(0, idx).trim();
+      const val = line.slice(idx + 1).trim();
+      frontmatter[key] = val;
+    }
+  }
+  return { frontmatter, body: match[2] };
+}
+
+/** Find all wiki pages recursively. */
+export function findWikiPages(
+  wikiDir: string,
+): Array<{ path: string; relative: string; content: string }> {
+  const results: Array<{ path: string; relative: string; content: string }> = [];
+
+  function walk(dir: string, rel: string) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) {
+        walk(full, rel ? `${rel}/${entry}` : entry);
+      } else if (entry.endsWith(".md")) {
+        results.push({
+          path: full,
+          relative: rel ? `${rel}/${entry.slice(0, -3)}` : entry.slice(0, -3),
+          content: readFileSync(full, "utf-8"),
+        });
+      }
+    }
+  }
+
+  walk(wikiDir, "");
+  return results;
+}
+
+/** Extract all [[wikilinks]] from content. */
+export function extractWikilinks(content: string): string[] {
+  const links: string[] = [];
+  const regex = /\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g;
+  let m: RegExpExecArray | null = regex.exec(content);
+  while (m !== null) {
+    links.push(m[1]);
+    m = regex.exec(content);
+  }
+  return links;
+}
+
+/** Slugify a title. */
+export function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .slice(0, 80);
+}
+
+/** Format date as YYYY-MM-DD. */
+export function fmtDate(d = new Date()): string {
+  return d.toISOString().split("T")[0];
+}
+
+/** Run a shell command via pi.exec. */
+export async function exec(
+  pi: ExtensionAPI,
+  command: string,
+  args: string[],
+  options?: { signal?: AbortSignal; timeout?: number; cwd?: string },
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  const result = await pi.exec(command, args, options ?? {});
+  return result;
+}
+
+/** Check if a path is inside a protected directory. */
+export function isProtectedPath(
+  absPath: string,
+  root: string,
+): { protected: boolean; reason?: string } {
+  const rawPath = resolve(root, "raw");
+  const metaPath = resolve(root, "meta");
+  const norm = resolve(absPath);
+
+  if (norm.startsWith(`${rawPath}/`) || norm === rawPath) {
+    return {
+      protected: true,
+      reason: "Raw sources are immutable. Use wiki_capture_source to add sources.",
+    };
+  }
+  if (norm.startsWith(`${metaPath}/`) || norm === metaPath) {
+    return {
+      protected: true,
+      reason: "Metadata is auto-generated. Use wiki_rebuild_meta or wiki_log_event instead.",
+    };
+  }
+
+  return { protected: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zosmaai/pi-llm-wiki",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "LLM Wiki for Pi — self-maintaining knowledge base following Karpathy's pattern. Obsidian-friendly, auto-updating, personal & company wiki.",
   "keywords": [
     "pi-package",
@@ -27,10 +27,14 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --apply .",
-    "prepare": "node -e \"try { require('husky').install() } catch {}\""
+    "release:patch": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
+    "release:push": "git push origin main --tags"
   },
   "pi": {
     "extensions": ["./extensions"],
@@ -49,6 +53,7 @@
     "@biomejs/biome": "^1.9.4",
     "@mariozechner/pi-coding-agent": "^0.70.2",
     "@mermaid-js/mermaid-cli": "^11.12.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "typebox": "^1.1.34",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"

package/prompts/wiki-digest.md

@@ -1,6 +1,6 @@
 ---
 description: Generate a daily or weekly digest of wiki changes — new sources, pages, insights, and gaps.
-args: [--period daily|weekly]
+argument-hint: "[--period daily|weekly]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Generate a digest of recent wiki activity.
 
+## User Arguments
+
+$ARGUMENTS
+
 ## Steps
 
 1. Read `wiki/LOG.md` — filter entries since last digest

package/prompts/wiki-discover.md

@@ -1,6 +1,6 @@
 ---
 description: Auto-discover new sources from the web. Searches based on config topics and known knowledge gaps.
-args: [--topic <topic>]
+argument-hint: "[--topic <topic>]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Find new source material for the wiki by searching the web.
 
+## User Arguments
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first. Also read `config.yaml` for topics and feeds.
 
 ## Steps

package/prompts/wiki-ingest.md

@@ -1,6 +1,6 @@
 ---
 description: Process new source files in raw/ and update the wiki. Creates summaries, entities, concepts, and cross-references.
-args: [path]
+argument-hint: "[path]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Process new files in `raw/` and integrate them into the wiki.
 
+## User Arguments
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema, page formats, and conventions.
 
 ## Steps

package/prompts/wiki-init.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize a new LLM Wiki in the current directory. Creates the full directory structure, config, and template files.
-args: <topic> [--mode personal|company]
+argument-hint: "<topic> [--mode personal|company]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Initialize a new LLM Wiki in the current directory.
 
+## User Arguments
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` (or wherever the skill is installed) first to understand the full schema and conventions.
 
 ## Steps

package/prompts/wiki-lint.md

@@ -1,6 +1,6 @@
 ---
 description: Health check the wiki. Detects contradictions, orphans, missing pages, stale claims, and knowledge gaps.
-args: [--fix]
+argument-hint: "[--fix]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Run a comprehensive health check on the wiki.
 
+## User Arguments
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema and conventions.
 
 ## Steps

package/prompts/wiki-query.md

@@ -1,6 +1,6 @@
 ---
 description: Ask questions against the wiki. Synthesizes answers from wiki pages with cross-reference citations.
-args: <question>
+argument-hint: "<question>"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Ask a question and get an answer synthesized from wiki content.
 
+## User Question
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first to understand the full schema and conventions.
 
 ## Steps

package/prompts/wiki-run.md

@@ -1,6 +1,6 @@
 ---
 description: Run the full wiki cycle: discover → ingest → lint. Optionally schedule for auto-updates.
-args: [--schedule daily|weekly]
+argument-hint: "[--schedule daily|weekly]"
 section: LLM Wiki
 topLevelCli: true
 ---
@@ -9,6 +9,10 @@ topLevelCli: true
 
 Run the complete wiki maintenance cycle: discover new sources, ingest them, and lint for health.
 
+## User Arguments
+
+$ARGUMENTS
+
 Read the LLM Wiki skill at `.pi/skills/llm-wiki/SKILL.md` first.
 
 ## Steps

package/prompts/wiki-status.md

@@ -1,6 +1,6 @@
 ---
 description: Show wiki health overview — source count, page stats, orphan count, last activity dates.
-args: []
+argument-hint: ""
 section: LLM Wiki
 topLevelCli: true
 ---

package/scripts/release.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Semantic version release script.
+ * Usage: node scripts/release.js [patch|minor|major]
+ */
+
+const { execSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const bump = process.argv[2];
+if (!["patch", "minor", "major"].includes(bump)) {
+  console.error("Usage: node scripts/release.js [patch|minor|major]");
+  process.exit(1);
+}
+
+// Verify clean tree
+const status = execSync("git status --porcelain", { encoding: "utf-8" }).trim();
+if (status) {
+  console.error("Error: working tree is not clean");
+  process.exit(1);
+}
+
+// Verify main branch
+const branch = execSync("git branch --show-current", { encoding: "utf-8" }).trim();
+if (branch !== "main") {
+  console.error("Error: not on main branch");
+  process.exit(1);
+}
+
+// Run checks
+execSync("npm run typecheck", { stdio: "inherit" });
+execSync("npm run lint", { stdio: "inherit" });
+execSync("npm test", { stdio: "inherit" });
+
+// Read current version
+const pkgPath = path.join(__dirname, "..", "package.json");
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+const current = pkg.version;
+const [major, minor, patch] = current.split(".").map(Number);
+
+let next;
+if (bump === "major") next = `${major + 1}.0.0`;
+else if (bump === "minor") next = `${major}.${minor + 1}.0`;
+else next = `${major}.${minor}.${patch + 1}`;
+
+// Update package.json
+pkg.version = next;
+fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf-8");
+
+// Update CHANGELOG
+const changelogPath = path.join(__dirname, "..", "CHANGELOG.md");
+let changelog = "";
+if (fs.existsSync(changelogPath)) {
+  changelog = fs.readFileSync(changelogPath, "utf-8");
+}
+const today = new Date().toISOString().split("T")[0];
+const newSection = `## [${next}] - ${today}\n\n### Added\n- Release ${next}\n`;
+if (changelog.includes("## [Unreleased]")) {
+  changelog = changelog.replace("## [Unreleased]", `## [Unreleased]\n\n${newSection}`);
+} else {
+  changelog = `# Changelog\n\n## [Unreleased]\n\n${newSection}\n${changelog.replace("# Changelog\n\n", "")}`;
+}
+fs.writeFileSync(changelogPath, changelog, "utf-8");
+
+// Commit and tag
+execSync("git add package.json CHANGELOG.md", { stdio: "inherit" });
+execSync(`git commit -m "chore(release): v${next}"`, { stdio: "inherit" });
+execSync(`git tag v${next}`, { stdio: "inherit" });
+
+console.log(`\n✅ Released v${next}`);
+console.log(`Run "npm run release:push" to publish.`);