@djolex999/vir-cli 0.1.0

package/src/pipeline/summarizer.ts

@@ -0,0 +1,204 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Config } from "../config.js";
+import type { DistilledRow, StateDb } from "../state/db.js";
+import {
+  buildAnthropicClient,
+  callLLM,
+  normalizeModelName,
+  withRateLimitRetry,
+} from "./distiller.js";
+import type { Category } from "./types.js";
+import { kebab } from "./writer.js";
+
+const EXCERPT_LEN = 200;
+const CHANGELOG_HEADER = "## Changelog";
+
+export interface ProjectGroup {
+  slug: string;
+  displayName: string;
+  rows: DistilledRow[];
+}
+
+export interface ProjectCounts {
+  patterns: number;
+  gotchas: number;
+  decisions: number;
+  tools: number;
+  total: number;
+}
+
+export function groupByProject(rows: DistilledRow[]): Map<string, ProjectGroup> {
+  const out = new Map<string, ProjectGroup>();
+  for (const r of rows) {
+    const slug = kebab(r.project);
+    if (slug.length === 0) continue;
+    let g = out.get(slug);
+    if (!g) {
+      g = { slug, displayName: r.project, rows: [] };
+      out.set(slug, g);
+    }
+    g.rows.push(r);
+  }
+  return out;
+}
+
+export function countByCategory(rows: DistilledRow[]): ProjectCounts {
+  let patterns = 0,
+    gotchas = 0,
+    decisions = 0,
+    tools = 0;
+  for (const r of rows) {
+    if (r.category === "pattern") patterns += 1;
+    else if (r.category === "gotcha") gotchas += 1;
+    else if (r.category === "decision") decisions += 1;
+    else if (r.category === "tool") tools += 1;
+  }
+  return { patterns, gotchas, decisions, tools, total: rows.length };
+}
+
+export async function summarizeProject(
+  cfg: Config,
+  projectSlug: string,
+  db: StateDb,
+): Promise<{ slug: string; path: string; counts: ProjectCounts } | null> {
+  const allRows = db.listDistilled();
+  const grouped = groupByProject(allRows);
+  const group = grouped.get(projectSlug);
+  if (!group || group.rows.length === 0) return null;
+
+  const counts = countByCategory(group.rows);
+  const prompt = buildPrompt(group, counts);
+
+  const client = buildAnthropicClient(cfg);
+  const model = normalizeModelName(cfg.models.distill, cfg.provider);
+  const body = await withRateLimitRetry(() =>
+    callLLM(cfg, client, { prompt, model, maxTokens: 1500 }),
+  );
+
+  const outPath = writeSummaryFile(cfg, projectSlug, body.trim(), counts);
+  return { slug: projectSlug, path: outPath, counts };
+}
+
+export async function summarizeAll(
+  cfg: Config,
+  db: StateDb,
+): Promise<Array<{ slug: string; path: string; counts: ProjectCounts }>> {
+  const grouped = groupByProject(db.listDistilled());
+  const results: Array<{ slug: string; path: string; counts: ProjectCounts }> =
+    [];
+  for (const slug of grouped.keys()) {
+    const res = await summarizeProject(cfg, slug, db);
+    if (res) results.push(res);
+  }
+  return results;
+}
+
+function buildPrompt(group: ProjectGroup, counts: ProjectCounts): string {
+  const byCat: Record<Category, DistilledRow[]> = {
+    pattern: [],
+    gotcha: [],
+    decision: [],
+    tool: [],
+  };
+  for (const r of group.rows) byCat[r.category].push(r);
+
+  const renderList = (rows: DistilledRow[]): string => {
+    if (rows.length === 0) return "(none)";
+    return rows
+      .map((r) => {
+        const excerpt = r.content
+          .replace(/\s+/g, " ")
+          .trim()
+          .slice(0, EXCERPT_LEN);
+        return `- ${r.topic}: ${excerpt}`;
+      })
+      .join("\n");
+  };
+
+  return `You are synthesizing a project knowledge summary from distilled Claude Code session notes.
+
+Project: ${group.slug}
+Total sessions: ${counts.total}
+
+Patterns (${counts.patterns}):
+${renderList(byCat.pattern)}
+
+Gotchas (${counts.gotchas}):
+${renderList(byCat.gotcha)}
+
+Decisions (${counts.decisions}):
+${renderList(byCat.decision)}
+
+Tools (${counts.tools}):
+${renderList(byCat.tool)}
+
+Write a project summary with these exact sections:
+## Overview
+2-3 sentences: what this project is, what stack/approach dominates
+
+## Key Patterns
+Bullet list of the most reusable patterns, 1 sentence each
+
+## Watch Out For
+Bullet list of the most important gotchas, 1 sentence each
+
+## Architecture Decisions
+Bullet list of significant decisions made, 1 sentence each
+
+## Knowledge Gaps
+1-2 sentences: what topics appear underrepresented or missing
+
+Be specific and direct. Use the actual topic names.`;
+}
+
+function writeSummaryFile(
+  cfg: Config,
+  projectSlug: string,
+  body: string,
+  counts: ProjectCounts,
+): string {
+  const dir = join(cfg.vaultPath, cfg.outputDir, "projects");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const filePath = join(dir, `${projectSlug}.md`);
+
+  const generated = new Date().toISOString();
+  const date = generated.slice(0, 10);
+  const newEntry = `- ${date}: ${counts.total} sessions, ${counts.patterns} patterns, ${counts.gotchas} gotchas, ${counts.decisions} decisions, ${counts.tools} tools`;
+
+  const existingChangelog = readExistingChangelog(filePath);
+  const changelog = [CHANGELOG_HEADER, newEntry, ...existingChangelog].join("\n");
+
+  const frontmatter = [
+    "---",
+    `project: ${projectSlug}`,
+    `generated: ${generated}`,
+    `sessions: ${counts.total}`,
+    "---",
+    "",
+    `Project: [[${projectSlug}]]`,
+    "",
+  ].join("\n");
+
+  const content = `${frontmatter}${body}\n\n---\n${changelog}\n`;
+  writeFileSync(filePath, content);
+  return filePath;
+}
+
+// Returns the existing changelog entries (the lines after `## Changelog`),
+// excluding the header itself. Empty array if file is missing or has no
+// changelog section yet.
+function readExistingChangelog(filePath: string): string[] {
+  if (!existsSync(filePath)) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch {
+    return [];
+  }
+  const idx = raw.indexOf(CHANGELOG_HEADER);
+  if (idx === -1) return [];
+  const rest = raw.slice(idx + CHANGELOG_HEADER.length).trim();
+  if (rest.length === 0) return [];
+  return rest.split("\n").filter((l) => l.trim().length > 0);
+}

package/src/pipeline/types.ts

@@ -0,0 +1,41 @@
+export interface TranscriptLine {
+  type?: string;
+  role?: string;
+  content?: unknown;
+  timestamp?: string;
+  message?: {
+    role?: string;
+    content?: unknown;
+  };
+  toolUseResult?: unknown;
+  [key: string]: unknown;
+}
+
+export interface ParsedSession {
+  path: string;
+  hash: string;
+  sessionId: string;
+  projectSlug: string;
+  startedAt: string | null;
+  endedAt: string | null;
+  lineCount: number;
+  toolCallCount: number;
+  filesTouched: string[];
+  assistantText: string;
+  userText: string;
+  rawSummary: string;
+}
+
+export type Category = "pattern" | "gotcha" | "decision" | "tool";
+
+export interface Classification {
+  category: Category;
+  topic: string;
+  project: string;
+  confidence: number;
+}
+
+export interface DistilledNote {
+  classification: Classification;
+  markdown: string;
+}

package/src/pipeline/writer.ts

@@ -0,0 +1,242 @@
+import chalk from "chalk";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { Config } from "../config.js";
+import {
+  embeddingForNote,
+  isOllamaAvailableCached,
+} from "../search/embedder.js";
+import type { StateDb } from "../state/db.js";
+import type { Category, DistilledNote, ParsedSession } from "./types.js";
+
+const CATEGORY_DIR: Record<Category, string> = {
+  pattern: "patterns",
+  gotcha: "gotchas",
+  decision: "decisions",
+  tool: "tools",
+};
+
+export class VaultWriter {
+  private root: string;
+  private db: StateDb | null;
+
+  constructor(cfg: Config, db: StateDb | null = null) {
+    this.root = join(cfg.vaultPath, cfg.outputDir);
+    this.db = db;
+    for (const sub of Object.values(CATEGORY_DIR)) {
+      const p = join(this.root, sub);
+      if (!existsSync(p)) mkdirSync(p, { recursive: true });
+    }
+    this.ensureIndex();
+    this.ensureLog();
+  }
+
+  async write(session: ParsedSession, note: DistilledNote): Promise<string[]> {
+    const { classification, markdown } = note;
+    const slug = makeSlug(classification.topic, session.sessionId);
+    const subDir = CATEGORY_DIR[classification.category];
+    const relPath = join(subDir, `${slug}.md`);
+    const fullPath = join(this.root, relPath);
+
+    const frontmatter = [
+      "---",
+      `topic: "${classification.topic.replace(/"/g, '\\"')}"`,
+      `category: ${classification.category}`,
+      `project: "${classification.project.replace(/"/g, '\\"')}"`,
+      `session_id: ${session.sessionId}`,
+      `date: ${session.startedAt ?? new Date().toISOString()}`,
+      `confidence: ${classification.confidence}`,
+      "---",
+      "",
+    ].join("\n");
+
+    const projectSlug = kebab(classification.project);
+    const categorySlug = classification.category;
+    const wikilinkHeader =
+      `Project: [[${projectSlug}]]\n` +
+      `Category: [[${categorySlug}]]\n\n`;
+
+    const body = wikilinkRelated(markdown);
+
+    const finalContent = frontmatter + wikilinkHeader + body + "\n";
+    writeFileSync(fullPath, finalContent);
+    await this.maybeEmbed(session, note, finalContent);
+    this.appendIndex({
+      date: (session.startedAt ?? new Date().toISOString()).slice(0, 10),
+      topic: classification.topic,
+      category: classification.category,
+      project: classification.project,
+      relPath,
+    });
+    this.appendLog({
+      ts: new Date().toISOString().slice(0, 16).replace("T", " "),
+      category: classification.category,
+      topic: classification.topic,
+      project: classification.project,
+    });
+    return [fullPath];
+  }
+
+  // Best-effort: embed the freshly-written note via Ollama and store the
+  // vector. Any failure (Ollama down, timeout, model missing) is swallowed —
+  // an embedding miss must never fail a write.
+  private async maybeEmbed(
+    session: ParsedSession,
+    note: DistilledNote,
+    fileContent: string,
+  ): Promise<void> {
+    if (!this.db) return;
+    try {
+      const available = await isOllamaAvailableCached();
+      if (!available) return;
+      const vec = await embeddingForNote(fileContent);
+      if (!vec) return;
+      this.db.storeEmbedding(session.sessionId, vec);
+      console.log(
+        chalk.dim(
+          `  embedded ${note.classification.topic} (${vec.length}d)`,
+        ),
+      );
+    } catch {
+      // never crash the writer on embedding failure
+    }
+  }
+
+  private ensureIndex(): void {
+    const p = join(this.root, "index.md");
+    if (!existsSync(p)) {
+      writeFileSync(
+        p,
+        "# vir — Distilled Knowledge\n\n| Date | Topic | Category | Project | Link |\n|------|-------|----------|---------|------|\n",
+      );
+    }
+  }
+
+  private ensureLog(): void {
+    const p = join(this.root, "log.md");
+    if (!existsSync(p)) {
+      writeFileSync(p, "# vir — Run Log\n\n");
+    }
+  }
+
+  private appendIndex(row: {
+    date: string;
+    topic: string;
+    category: Category;
+    project: string;
+    relPath: string;
+  }): void {
+    const p = join(this.root, "index.md");
+    const link = `[[${row.relPath.replace(/\.md$/, "")}|${row.topic}]]`;
+    const line = `| ${row.date} | ${row.topic} | ${row.category} | ${row.project} | ${link} |\n`;
+    const current = readFileSync(p, "utf8");
+    // Insert after the table header (first occurrence of '|------')
+    const headerIdx = current.indexOf("|------");
+    if (headerIdx === -1) {
+      appendFileSync(p, line);
+      return;
+    }
+    const newlineAfter = current.indexOf("\n", headerIdx);
+    const updated =
+      current.slice(0, newlineAfter + 1) + line + current.slice(newlineAfter + 1);
+    writeFileSync(p, updated);
+  }
+
+  private appendLog(entry: {
+    ts: string;
+    category: Category;
+    topic: string;
+    project: string;
+  }): void {
+    const p = join(this.root, "log.md");
+    appendFileSync(
+      p,
+      `## [${entry.ts}] ${entry.category} | ${entry.topic} | ${entry.project}\n\n`,
+    );
+  }
+
+  noteCount(): number {
+    let n = 0;
+    for (const sub of Object.values(CATEGORY_DIR)) {
+      const dir = join(this.root, sub);
+      if (!existsSync(dir)) continue;
+      try {
+        n += readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+      } catch {
+        // ignore
+      }
+    }
+    return n;
+  }
+}
+
+function makeSlug(topic: string, sessionId: string): string {
+  const base = kebab(topic).slice(0, 50);
+  const suffix = sessionId.slice(0, 8);
+  return base.length > 0 ? `${base}-${suffix}` : `note-${suffix}`;
+}
+
+export function kebab(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Rewrites the bullet list under a `## Related` heading so each item
+// becomes an Obsidian wikilink to a kebab-cased slug of the item's text.
+// Stops at the next heading or end of document.
+export function wikilinkRelated(markdown: string): string {
+  const lines = markdown.split("\n");
+  const out: string[] = [];
+  let inRelated = false;
+
+  for (const line of lines) {
+    if (/^##\s+related\b/i.test(line)) {
+      inRelated = true;
+      out.push(line);
+      continue;
+    }
+    if (inRelated && /^#{1,6}\s+/.test(line)) {
+      inRelated = false;
+      out.push(line);
+      continue;
+    }
+    if (inRelated) {
+      const bullet = line.match(/^(\s*[-*]\s+)(.*)$/);
+      if (bullet) {
+        const prefix = bullet[1] ?? "- ";
+        const text = (bullet[2] ?? "").trim();
+        if (text.length === 0) {
+          out.push(line);
+        } else if (/^\[\[.+\]\]$/.test(text)) {
+          // already a wikilink — leave it
+          out.push(line);
+        } else {
+          const slug = kebab(stripWikilink(text));
+          out.push(`${prefix}[[${slug}]]`);
+        }
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+function stripWikilink(s: string): string {
+  // If the model already partially wrapped it like "[[Something]]" or
+  // "[Something](url)", reduce to the inner text before kebab-casing.
+  const wiki = s.match(/^\[\[(.+?)\]\]$/);
+  if (wiki) return wiki[1] ?? s;
+  const md = s.match(/^\[(.+?)\]\(.+\)$/);
+  if (md) return md[1] ?? s;
+  return s;
+}

package/src/search/embedder.ts

@@ -0,0 +1,88 @@
+const OLLAMA_BASE = "http://localhost:11434";
+export const EMBED_MODEL = "nomic-embed-text";
+const EMBED_TIMEOUT_MS = 10_000;
+const PING_TIMEOUT_MS = 3_000;
+
+export class EmbedderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EmbedderError";
+  }
+}
+
+export async function embed(text: string): Promise<number[]> {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), EMBED_TIMEOUT_MS);
+  try {
+    const resp = await fetch(`${OLLAMA_BASE}/api/embeddings`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ model: EMBED_MODEL, prompt: text }),
+      signal: ac.signal,
+    });
+    if (!resp.ok) {
+      throw new EmbedderError(`Ollama ${resp.status}: ${await resp.text().catch(() => "")}`);
+    }
+    const data = (await resp.json()) as { embedding?: unknown; error?: string };
+    if (data.error) throw new EmbedderError(`Ollama error: ${data.error}`);
+    if (!Array.isArray(data.embedding) || data.embedding.length === 0) {
+      throw new EmbedderError("Ollama returned no embedding");
+    }
+    return (data.embedding as unknown[]).map((n) => Number(n));
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length === 0 || b.length === 0 || a.length !== b.length) return 0;
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    dot += x * y;
+    magA += x * x;
+    magB += y * y;
+  }
+  if (magA === 0 || magB === 0) return 0;
+  const sim = dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  // Clamp to [0, 1] — embeddings are typically positively correlated; negative
+  // values would otherwise distort the topK ordering downstream.
+  if (!Number.isFinite(sim)) return 0;
+  if (sim < 0) return 0;
+  if (sim > 1) return 1;
+  return sim;
+}
+
+export async function isOllamaAvailable(): Promise<boolean> {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), PING_TIMEOUT_MS);
+  try {
+    const resp = await fetch(`${OLLAMA_BASE}/api/tags`, { signal: ac.signal });
+    return resp.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// Module-level memo so a long-running daemon doesn't hammer /api/tags on every
+// session. Invalidated only by process restart, which is fine for our cadence.
+let _availabilityCache: Promise<boolean> | null = null;
+export function isOllamaAvailableCached(): Promise<boolean> {
+  if (_availabilityCache === null) {
+    _availabilityCache = isOllamaAvailable();
+  }
+  return _availabilityCache;
+}
+
+export async function embeddingForNote(text: string): Promise<number[] | null> {
+  try {
+    return await embed(text);
+  } catch {
+    return null;
+  }
+}