@booklib/core 2.0.0

package/lib/engine/ai-features.js

@@ -0,0 +1,253 @@
+import fs from 'fs';
+import path from 'path';
+
+export class BookLibAIFeatures {
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this.sessionsDir = path.join(projectRoot, '.booklib/sessions');
+  }
+
+  async generateSessionSummary(sessionName, modelProvider = 'claude') {
+    const sessionPath = path.join(this.sessionsDir, `${sessionName}.md`);
+    if (!fs.existsSync(sessionPath)) {
+      return { error: 'Session not found' };
+    }
+
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    const data = this._parseSession(content);
+
+    const summary = this._generateMockSummary(data);
+
+    return {
+      session: sessionName,
+      summary,
+      tokens_estimated: 100,
+      model: modelProvider
+    };
+  }
+
+  recommendSkills(goal, availableSkills = []) {
+    const skillKeywords = {
+      'effective-typescript': ['typescript', 'type', 'interface', 'generic', 'null safety'],
+      'clean-code-reviewer': ['code quality', 'refactor', 'clean', 'maintainability'],
+      'microservices-patterns': ['service', 'distributed', 'saga', 'cqrs', 'message queue'],
+      'effective-python': ['python', 'async', 'decorator', 'context manager'],
+      'design-patterns': ['pattern', 'factory', 'observer', 'singleton', 'decorator'],
+      'domain-driven-design': ['domain', 'entity', 'aggregate', 'ubiquitous language'],
+      'system-design-interview': ['scale', 'load balance', 'cache', 'database sharding'],
+      'refactoring-ui': ['ui', 'design', 'layout', 'typography', 'color palette'],
+      'data-pipelines': ['data', 'etl', 'pipeline', 'orchestration', 'warehouse'],
+      'animation-at-work': ['animation', 'transition', 'motion', 'keyframe']
+    };
+
+    const lowerGoal = goal.toLowerCase();
+    const recommendations = {};
+
+    for (const [skill, keywords] of Object.entries(skillKeywords)) {
+      const matchCount = keywords.filter(kw => lowerGoal.includes(kw)).length;
+      if (matchCount > 0) {
+        recommendations[skill] = matchCount;
+      }
+    }
+
+    const sorted = Object.entries(recommendations)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([skill, score]) => ({
+        skill,
+        confidence: Math.min(100, score * 20),
+        reason: this._getSkillReason(skill, goal)
+      }));
+
+    return { recommendations: sorted };
+  }
+
+  getExtensionData() {
+    const sessions = this._loadAllSessions();
+    
+    return {
+      version: '1.0.0',
+      sessions: sessions.map(s => ({
+        id: s.session_id,
+        name: s.session_id,
+        goal: s.goal,
+        branch: s.branch,
+        timestamp: s.timestamp
+      })),
+      status_bar_data: sessions[0] ? {
+        current_session: sessions[0].session_id,
+        branch: sessions[0].branch,
+        pending_tasks: (sessions[0].pending_tasks || '').split('\n').length
+      } : null,
+      quick_actions: [
+        { command: 'booklib.saveSession', title: 'Save Session', icon: 'save' },
+        { command: 'booklib.recoverSession', title: 'Recover Session', icon: 'refresh' },
+        { command: 'booklib.viewTasks', title: 'View Tasks', icon: 'list' },
+        { command: 'booklib.switchSession', title: 'Switch Session', icon: 'branch' }
+      ]
+    };
+  }
+
+  getGitHubIntegrationData(sessionName) {
+    const sessionPath = path.join(this.sessionsDir, `${sessionName}.md`);
+    if (!fs.existsSync(sessionPath)) {
+      return { error: 'Session not found' };
+    }
+
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    const data = this._parseSession(content);
+
+    return {
+      wiki_page: {
+        title: `Session: ${data.session_id}`,
+        content: this._generateWikiMarkdown(data),
+        slug: `session-${data.session_id}`
+      },
+      issues_to_create: (data.pending_tasks || '')
+        .split('\n')
+        .filter(t => t.trim())
+        .map((task, i) => ({
+          title: task.trim(),
+          body: `From session: ${data.session_id}\n\nContext: ${data.goal}`,
+          labels: ['from-session', ...data.skills],
+          priority: i === 0 ? 'high' : 'medium'
+        })),
+      pr_context: {
+        session: data.session_id,
+        goal: data.goal,
+        branch: data.branch,
+        summary: `Working on: ${data.goal}`
+      }
+    };
+  }
+
+  getSlackIntegrationData(sessionName) {
+    const sessionPath = path.join(this.sessionsDir, `${sessionName}.md`);
+    if (!fs.existsSync(sessionPath)) {
+      return { error: 'Session not found' };
+    }
+
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    const data = this._parseSession(content);
+
+    return {
+      webhook_enabled: !!process.env.SLACK_WEBHOOK,
+      message: {
+        text: `📝 Session Update: ${data.session_id}`,
+        blocks: [
+          {
+            type: 'header',
+            text: {
+              type: 'plain_text',
+              text: `📝 ${data.session_id}`
+            }
+          },
+          {
+            type: 'section',
+            fields: [
+              {
+                type: 'mrkdwn',
+                text: `*Goal:*\n${data.goal}`
+              },
+              {
+                type: 'mrkdwn',
+                text: `*Progress:*\n${data.progress.substring(0, 100)}...`
+              }
+            ]
+          },
+          {
+            type: 'section',
+            text: {
+              type: 'mrkdwn',
+              text: `*Skills:* ${data.skills.join(', ')}`
+            }
+          }
+        ]
+      },
+      notification_types: {
+        on_save: true,
+        on_complete: true,
+        team_mention: data.pending_tasks ? '@team' : null,
+        branch_mention: `#${data.branch}`
+      }
+    };
+  }
+
+  _parseSession(content) {
+    const extract = (tag) => {
+      const regex = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`);
+      const match = content.match(regex);
+      return match ? match[1].trim() : '';
+    };
+
+    const skillRegex = /<skill id="([^"]+)"/g;
+    const skills = [];
+    let match;
+    while ((match = skillRegex.exec(content)) !== null) {
+      skills.push(match[1]);
+    }
+
+    return {
+      session_id: extract('session_id'),
+      timestamp: extract('timestamp'),
+      goal: extract('goal'),
+      progress: extract('progress'),
+      pending_tasks: extract('pending_tasks'),
+      branch: extract('branch'),
+      skills
+    };
+  }
+
+  _generateMockSummary(data) {
+    const parts = [
+      `Building: ${data.goal.split(' ').slice(0, 3).join(' ')}`,
+      `Progress: ${data.progress.split('\n')[0]}`,
+      data.pending_tasks ? `Next: ${data.pending_tasks.split('\n')[0]}` : 'Ready for review'
+    ];
+    return parts.join('. ');
+  }
+
+  _getSkillReason(skill, goal) {
+    const reasons = {
+      'effective-typescript': 'Goal mentions TypeScript or type safety concerns',
+      'clean-code-reviewer': 'Goal includes code quality or refactoring',
+      'microservices-patterns': 'Goal mentions distributed systems or services',
+      'system-design-interview': 'Goal includes scaling or architecture',
+      'design-patterns': 'Goal mentions patterns or architecture',
+      'refactoring-ui': 'Goal includes UI/design work'
+    };
+    return reasons[skill] || 'Relevant to development goals';
+  }
+
+  _generateWikiMarkdown(data) {
+    return `# Session: ${data.session_id}
+
+## Goal
+${data.goal}
+
+## Progress
+${data.progress}
+
+## Next Tasks
+${data.pending_tasks || 'No tasks defined'}
+
+## Skills
+- ${data.skills.join('\n- ')}
+
+## Metadata
+- **Branch:** ${data.branch}
+- **Created:** ${new Date(data.timestamp).toLocaleString()}
+`;
+  }
+
+  _loadAllSessions() {
+    if (!fs.existsSync(this.sessionsDir)) return [];
+    
+    return fs.readdirSync(this.sessionsDir)
+      .filter(f => f.endsWith('.md') && !f.startsWith('_'))
+      .map(file => {
+        const content = fs.readFileSync(path.join(this.sessionsDir, file), 'utf8');
+        return this._parseSession(content);
+      });
+  }
+}

package/lib/engine/auditor.js

@@ -0,0 +1,103 @@
+import fs from 'fs';
+import path from 'path';
+import { parseSkillFile } from './parser.js';
+
+/**
+ * Handles systematic audits of content against BookLib skills.
+ */
+export class BookLibAuditor {
+  constructor() {}
+
+  /**
+   * Performs an audit of a file against a specific skill.
+   */
+  async audit(skillPath, targetFilePath) {
+    if (!fs.existsSync(skillPath)) {
+      throw new Error(`Skill not found at ${skillPath}`);
+    }
+
+    if (!fs.existsSync(targetFilePath)) {
+      throw new Error(`Target file not found at ${targetFilePath}`);
+    }
+
+    const skillMdPath = fs.statSync(skillPath).isDirectory() 
+      ? path.join(skillPath, 'SKILL.md') 
+      : skillPath;
+    
+    const skillContent = fs.readFileSync(skillMdPath, 'utf8');
+    const chunks = parseSkillFile(skillContent, skillMdPath);
+    
+    const targetContent = fs.readFileSync(targetFilePath, 'utf8');
+    const targetLines = targetContent.split('\n');
+    
+    // Support both legacy and universal tags
+    const principles = chunks.find(c => c.metadata.type === 'framework' || c.metadata.type === 'core_principles')?.text || 'See metadata';
+    const pitfalls = chunks.find(c => c.metadata.type === 'pitfalls' || c.metadata.type === 'anti_patterns')?.text || 'See metadata';
+
+    // 1. Static Analysis (Domain-specific low-hanging fruit)
+    const auditJsonPath = path.join(path.dirname(skillMdPath), 'audit.json');
+    let staticFindings = '';
+    if (fs.existsSync(auditJsonPath)) {
+      const { rules } = JSON.parse(fs.readFileSync(auditJsonPath, 'utf8'));
+      const findings = [];
+
+      for (const rule of rules) {
+        const regex = new RegExp(rule.pattern, 'g');
+        targetLines.forEach((line, index) => {
+          if (regex.test(line)) {
+            findings.push(`- ${rule.severity} **${rule.id}**: ${rule.message} (Line ${index + 1}: \`${line.trim()}\`)`);
+          }
+        });
+      }
+      
+      if (findings.length > 0) {
+        staticFindings = `### 🤖 Automated Detections\n${findings.join('\n')}\n`;
+      } else {
+        staticFindings = `### 🤖 Automated Detections\n*No common pitfalls detected automatically.*\n`;
+      }
+    }
+
+    return `
+# BookLib Active Audit: ${path.basename(skillPath)}
+**Target Content**: \`${targetFilePath}\`
+
+## 🛠 Instructions for the Agent
+You are tasked with a systematic audit of the provided content against expert frameworks. 
+Follow these steps:
+1. **Analyze**: Read the target content carefully.
+2. **Evaluate**: Compare the work against the "Expert Framework" and "Pitfalls to Avoid".
+3. **Report**: Document where the content aligns or violates these expert standards.
+
+---
+
+## 📜 Expert Framework
+${principles}
+
+## 🚫 Pitfalls to Avoid
+${pitfalls}
+
+---
+
+## 🔍 Audit Findings
+
+${staticFindings}
+
+### 🔴 Critical Misalignments (Manual)
+*   (List major deviations from the expert framework)
+
+### 🟡 Opportunities for Improvement
+*   (List areas where the content can be sharpened)
+
+### 🟢 Strengths
+*   (Acknowledge where the content perfectly embodies the principles)
+
+### 🚀 Recommended Refinement
+\`\`\`
+// Provide a surgical improvement or rewritten section here
+\`\`\`
+
+> **Note**: This audit was generated by the BookLib Universal Engine. 
+> Always cite the specific expert items in your findings.
+`;
+  }
+}

package/lib/engine/bm25-index.js

@@ -0,0 +1,178 @@
+import fs from 'node:fs';
+
+const K1 = 1.5;
+const B = 0.75;
+const MIN_TOKEN_LENGTH = 2;
+
+/**
+ * Tokenizes text into lowercase alphanumeric terms of at least 2 characters.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function tokenize(text) {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(token => token.length >= MIN_TOKEN_LENGTH);
+}
+
+/**
+ * Counts term frequencies in a token array.
+ * @param {string[]} tokens
+ * @returns {Map<string, number>}
+ */
+function countTermFrequencies(tokens) {
+  const freq = new Map();
+  for (const token of tokens) {
+    freq.set(token, (freq.get(token) ?? 0) + 1);
+  }
+  return freq;
+}
+
+/**
+ * Computes BM25 IDF for a term.
+ * Formula: log((N - df + 0.5) / (df + 0.5) + 1)
+ * @param {number} docCount - Total number of documents
+ * @param {number} docFrequency - Number of documents containing the term
+ * @returns {number}
+ */
+function computeIdf(docCount, docFrequency) {
+  return Math.log((docCount - docFrequency + 0.5) / (docFrequency + 0.5) + 1);
+}
+
+/**
+ * Scores a single document against a set of query terms using BM25.
+ * @param {Object} doc - Document with freq map and len
+ * @param {string[]} queryTerms
+ * @param {Map<string, number>} df - Document frequency map
+ * @param {number} docCount
+ * @param {number} avgDocLen
+ * @returns {number}
+ */
+function scoreBm25(doc, queryTerms, df, docCount, avgDocLen) {
+  let score = 0;
+  for (const term of queryTerms) {
+    const termFreq = doc.freq[term] ?? 0;
+    if (termFreq === 0) continue;
+
+    const docFrequency = df[term] ?? 0;
+    const idf = computeIdf(docCount, docFrequency);
+    const normalizedTf =
+      (termFreq * (K1 + 1)) /
+      (termFreq + K1 * (1 - B + B * (doc.len / avgDocLen)));
+
+    score += idf * normalizedTf;
+  }
+  return score;
+}
+
+/**
+ * BM25 full-text search index.
+ *
+ * Supports incremental document addition, JSON persistence, and
+ * Robertson BM25 ranking.
+ */
+export class BM25Index {
+  constructor() {
+    this._docs = [];
+    this._df = {};
+    this._avgLen = 0;
+    this._totalLen = 0;
+  }
+
+  /**
+   * Builds the index from scratch from an array of chunks.
+   * @param {{ text: string, metadata: object }[]} chunks
+   */
+  build(chunks) {
+    this._docs = [];
+    this._df = {};
+    this._avgLen = 0;
+    this._totalLen = 0;
+
+    for (const chunk of chunks) {
+      this._appendDoc(chunk);
+    }
+  }
+
+  /**
+   * Incrementally adds one document to the index, updating avgLen and df.
+   * @param {{ text: string, metadata: object }} chunk
+   */
+  add(chunk) {
+    this._appendDoc(chunk);
+  }
+
+  /**
+   * Searches the index and returns top-K results sorted by score descending.
+   * @param {string} query
+   * @param {number} topK
+   * @returns {{ score: number, text: string, metadata: object }[]}
+   */
+  search(query, topK = 20) {
+    if (this._docs.length === 0) return [];
+
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0) return [];
+
+    const scoredDocs = this._docs.map(doc => ({
+      score: scoreBm25(doc, queryTerms, this._df, this._docs.length, this._avgLen),
+      text: doc.text,
+      metadata: doc.metadata,
+    }));
+
+    const matchingDocs = scoredDocs.filter(r => r.score > 0);
+    return matchingDocs
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK);
+  }
+
+  /**
+   * Persists the index to a JSON file.
+   * @param {string} filePath
+   */
+  save(filePath) {
+    const serialized = JSON.stringify({
+      docs: this._docs,
+      df: this._df,
+      avgLen: this._avgLen,
+    });
+    fs.writeFileSync(filePath, serialized, 'utf8');
+  }
+
+  /**
+   * Restores a BM25Index instance from a JSON file.
+   * @param {string} filePath
+   * @returns {BM25Index}
+   */
+  static load(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const { docs, df, avgLen } = JSON.parse(raw);
+    const idx = new BM25Index();
+    idx._docs = docs;
+    idx._df = df;
+    idx._avgLen = avgLen;
+    idx._totalLen = docs.reduce((sum, d) => sum + d.len, 0);
+    return idx;
+  }
+
+  /**
+   * Internal: adds one document and updates df and avgLen.
+   * @param {{ text: string, metadata: object }} chunk
+   */
+  _appendDoc(chunk) {
+    const tokens = tokenize(chunk.text);
+    const freqMap = countTermFrequencies(tokens);
+    const freqObj = Object.fromEntries(freqMap);
+
+    for (const term of freqMap.keys()) {
+      this._df[term] = (this._df[term] ?? 0) + 1;
+    }
+
+    const len = tokens.length;
+    this._docs.push({ text: chunk.text, metadata: chunk.metadata, freq: freqObj, len });
+
+    this._totalLen += len;
+    this._avgLen = this._totalLen / this._docs.length;
+  }
+}

package/lib/engine/capture.js

@@ -0,0 +1,120 @@
+// lib/engine/capture.js
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, readFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// ── AI prompt builders (exported for testing) ─────────────────────────────────
+
+/** Returns the prompt used to ask Claude to structure raw dictation into a clean note. */
+export function buildDictatePrompt(rawText) {
+  return `You are a knowledge management assistant. Structure the following raw notes into a clean markdown knowledge note.
+
+Raw input:
+${rawText}
+
+Return ONLY valid YAML frontmatter + markdown. The frontmatter must include:
+- title: (concise, descriptive title extracted or inferred from the content)
+- tags: (2-5 relevant tags as a YAML list)
+- type: note
+
+Fix grammar and typos. Preserve all meaning. Do not add information not present in the input.
+Return nothing except the markdown document starting with ---.`;
+}
+
+/** Returns the prompt used to summarize a conversation transcript into a structured note. */
+export function buildSummarizePrompt(transcript, title = '') {
+  const titleLine = title ? `Title: ${title}\n\n` : '';
+  return `You are a knowledge management assistant. Summarize this AI conversation into a structured knowledge note.
+
+${titleLine}Conversation:
+${transcript}
+
+Return ONLY a markdown document starting with ---. Include this frontmatter:
+- title: (descriptive title${title ? ` — use "${title}" as basis` : ''})
+- tags: (2-5 relevant tags)
+- type: note
+
+And these sections in the body:
+## Key Decisions
+(bullet list of decisions made)
+
+## Findings
+(bullet list of key findings or conclusions)
+
+## Context
+(1-2 sentences of background)
+
+Then append the full transcript inside a details element:
+<details>
+<summary>Full conversation transcript</summary>
+
+${transcript}
+
+</details>`;
+}
+
+// ── AI call (requires ANTHROPIC_API_KEY env var) ──────────────────────────────
+
+/** Calls claude-haiku via the Anthropic Messages API. Requires ANTHROPIC_API_KEY. */
+export async function callAnthropicAPI(prompt) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error('ANTHROPIC_API_KEY not set. Export it or add to .env.local');
+  }
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      model: 'claude-haiku-4-5-20251001',
+      max_tokens: 2048,
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Anthropic API ${response.status}: ${body}`);
+  }
+  const data = await response.json();
+  return data.content[0].text;
+}
+
+// ── Input helpers ─────────────────────────────────────────────────────────────
+
+/** Opens $EDITOR (or vi) with optional initial content. Returns edited content. */
+export function openEditor(initialContent = '') {
+  const tmpFile = join(tmpdir(), `booklib-edit-${Date.now()}.md`);
+  writeFileSync(tmpFile, initialContent, 'utf8');
+  const editor = process.env.EDITOR ?? 'vi';
+  spawnSync(editor, [tmpFile], { stdio: 'inherit' });
+  const content = readFileSync(tmpFile, 'utf8');
+  unlinkSync(tmpFile);
+  return content.trim();
+}
+
+/** Reads all of stdin when piped. Returns empty string when stdin is a TTY. */
+export async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return new Promise(resolve => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+  });
+}
+
+/** Prompts user to type input interactively until Ctrl+D. */
+export async function readInteractive(prompt = 'Type your note (Ctrl+D when done):') {
+  process.stdout.write(prompt + '\n');
+  return new Promise(resolve => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.resume();
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => resolve(data.trim()));
+  });
+}