@mseep/core 3.0.0

package/lib/engine/source-manager.js

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Manages documentation source registration, listing, and removal.
+ * Sources are persisted in .booklib/sources.json.
+ */
+export class SourceManager {
+  constructor(booklibDir) {
+    this.booklibDir = booklibDir;
+    this.registryPath = path.join(booklibDir, 'sources.json');
+  }
+
+  /** Load registry from disk, returning empty structure if file missing or corrupt. */
+  _loadRegistry() {
+    if (!fs.existsSync(this.registryPath)) {
+      return { sources: [] };
+    }
+    try {
+      const raw = fs.readFileSync(this.registryPath, 'utf8');
+      return JSON.parse(raw);
+    } catch {
+      return { sources: [] };
+    }
+  }
+
+  /** Persist registry to disk, creating the directory if needed. */
+  _saveRegistry(registry) {
+    fs.mkdirSync(this.booklibDir, { recursive: true });
+    fs.writeFileSync(this.registryPath, JSON.stringify(registry, null, 2), 'utf8');
+  }
+
+  /**
+   * Register a new documentation source.
+   * @param {object} opts
+   * @param {string} [opts.name] - Display name (derived from path basename if omitted).
+   * @param {string} opts.sourcePath - Absolute path to the documentation directory.
+   * @param {string} opts.type - Source type (e.g. 'local', 'git', 'url').
+   * @param {string} [opts.url] - Optional remote URL.
+   * @returns {object} The registered source entry.
+   */
+  registerSource({ name, sourcePath, type, url }) {
+    const registry = this._loadRegistry();
+    const resolvedName = name ?? path.basename(sourcePath);
+
+    if (!/^[a-zA-Z0-9._-]+$/.test(resolvedName)) {
+      throw new Error(
+        `Invalid source name: "${resolvedName}". Names may only contain letters, digits, dots, hyphens, and underscores.`
+      );
+    }
+
+    const existing = registry.sources.find(s => s.name === resolvedName);
+    if (existing) {
+      throw new Error(`Source already exists: "${resolvedName}". Use a different --name.`);
+    }
+
+    const entry = {
+      name: resolvedName,
+      sourcePath,
+      type,
+      ...(url ? { url } : {}),
+      created_at: new Date().toISOString(),
+      indexed_at: null,
+      chunk_count: 0,
+    };
+
+    registry.sources.push(entry);
+    this._saveRegistry(registry);
+    return entry;
+  }
+
+  /** Return all registered sources. */
+  listSources() {
+    return this._loadRegistry().sources;
+  }
+
+  /**
+   * Return a single source by name, or null if not found.
+   * @param {string} name
+   * @returns {object|null}
+   */
+  getSource(name) {
+    const registry = this._loadRegistry();
+    return registry.sources.find(s => s.name === name) ?? null;
+  }
+
+  /**
+   * Remove a source from the registry by name.
+   * Does not delete indexed chunks -- caller handles that separately.
+   * @param {string} name
+   */
+  removeSource(name) {
+    const registry = this._loadRegistry();
+    const idx = registry.sources.findIndex(s => s.name === name);
+    if (idx === -1) {
+      throw new Error(`Source not found: "${name}". Run 'booklib sources' to see registered sources.`);
+    }
+    registry.sources.splice(idx, 1);
+    this._saveRegistry(registry);
+  }
+
+  /**
+   * Update the indexed_at timestamp and chunk count after indexing completes.
+   * @param {string} name
+   * @param {number} chunkCount
+   */
+  markIndexed(name, chunkCount) {
+    const registry = this._loadRegistry();
+    const source = registry.sources.find(s => s.name === name);
+    if (!source) {
+      throw new Error(`Source not found: "${name}". Register it first with 'booklib connect'.`);
+    }
+    source.indexed_at = new Date().toISOString();
+    source.chunk_count = chunkCount;
+    this._saveRegistry(registry);
+  }
+
+  /**
+   * Store file modification times for incremental re-indexing.
+   * @param {string} name - Source name.
+   * @param {Object} mtimes - { [relativePath]: mtimeMs }
+   */
+  updateMtimes(name, mtimes) {
+    const registry = this._loadRegistry();
+    const source = registry.sources.find(s => s.name === name);
+    if (!source) {
+      throw new Error(`Source not found: "${name}".`);
+    }
+    source.file_mtimes = mtimes;
+    this._saveRegistry(registry);
+  }
+
+  /**
+   * Retrieve stored file modification times for a source.
+   * @param {string} name - Source name.
+   * @returns {Object} { [relativePath]: mtimeMs } or empty object.
+   */
+  getMtimes(name) {
+    const source = this.getSource(name);
+    return source?.file_mtimes ?? {};
+  }
+}

package/lib/engine/structured-response.js

@@ -0,0 +1,47 @@
+import { extractFromResults } from './principle-extractor.js';
+
+/**
+ * Transforms raw search results into structured MCP response format.
+ * Returns actionable principles or "no relevant knowledge found."
+ *
+ * @param {string} query - the original query
+ * @param {Array} results - raw search results from BookLibSearcher.search()
+ * @param {object} [opts]
+ * @param {number} [opts.maxPrinciples=3] - max principles to return
+ * @param {string} [opts.file] - optional file path for context
+ * @returns {object} structured response
+ */
+export function buildStructuredResponse(query, results, opts = {}) {
+  const { maxPrinciples = 3, file } = opts;
+
+  if (!results || results.length === 0) {
+    return {
+      query,
+      file: file ?? null,
+      results: [],
+      note: 'No relevant knowledge found.',
+    };
+  }
+
+  const principles = extractFromResults(results, maxPrinciples);
+
+  if (principles.length === 0) {
+    return {
+      query,
+      file: file ?? null,
+      results: [],
+      note: 'Search returned results but no extractable principles found.',
+    };
+  }
+
+  // Count unique sources
+  const sources = new Set(principles.map(p => p.source));
+  const note = `${principles.length} result${principles.length > 1 ? 's' : ''} from ${sources.size} source${sources.size > 1 ? 's' : ''}.`;
+
+  return {
+    query,
+    file: file ?? null,
+    results: principles,
+    note,
+  };
+}

package/lib/engine/synthesis-templates.js

@@ -0,0 +1,364 @@
+export const SYNTHESIS_TEMPLATES = {
+  'framework-docs': `You are synthesizing a context injection from framework documentation. The agent needs to use a specific API correctly.
+
+Task: {query}
+{fileContext}
+
+Search results from indexed docs:
+{results}
+
+Structure as:
+
+## API Reference
+- [Exact function/component name with signature and parameters]
+- [Required configuration or setup steps]
+
+## Migration (if applicable)
+- [Old API → New API with specific method names]
+- [What changed and why]
+
+## Code Example
+[Working code example from the search results — not invented]
+
+## Gotchas
+- [Non-obvious behavior, common mistakes, or breaking changes]
+
+Only include what's IN the search results. Don't add knowledge from training data.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'api-reference': `You are synthesizing a context injection from API documentation.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Endpoints
+- [Method + path + description]
+
+## Request Format
+- [Parameters, headers, body schema]
+
+## Response Format
+- [Status codes + response body]
+
+## Error Handling
+- [Error codes and what they mean]
+
+Only include what's IN the search results.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'release-notes': `You are synthesizing a context injection from release notes and changelogs.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## What Changed
+- [Specific API or behavior change with version number]
+
+## Before → After
+- Before: [old pattern] → After: [new pattern]
+
+## Migration Code
+[Code showing the new way to do it]
+
+## Breaking Changes
+- [What will break if old patterns are used]
+
+Only include what's IN the search results. Flag deprecated APIs explicitly.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'spec': `You are synthesizing a context injection from project specifications.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Requirements
+- [Specific requirement with acceptance criteria]
+
+## Constraints
+- [Technical or business constraint that limits implementation]
+
+## Dependencies
+- [Other features or systems this depends on]
+
+Only include what's IN the search results. Don't add assumptions.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'team-decision': `You are synthesizing a context injection from team architecture decisions.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Decision
+- [What was decided and when]
+
+## Context
+- [Why this decision was made — the problem it solves]
+
+## Constraints
+- [What this decision requires or prohibits in the codebase]
+
+## Consequences
+- [Trade-offs accepted with this decision]
+
+Only include what's IN the search results.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'tutorial': `You are synthesizing a context injection from a tutorial or guide.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Steps
+1. [First step with specific command or action]
+2. [Next step]
+3. [Continue...]
+
+## Key Concepts
+- [Important concept the agent needs to understand]
+
+## Common Mistakes
+- [What beginners get wrong]
+
+Only include what's IN the search results.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'sdd-spec': `You are synthesizing a context injection from a spec-driven development artifact (SpecKit, GSD, Kiro, Superpowers, or similar).
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Goal
+- [What the spec is trying to achieve]
+
+## Requirements
+- [Specific deliverables or acceptance criteria]
+
+## Constraints
+- [What is explicitly out of scope or not allowed]
+
+## Architecture / Approach
+- [Technical approach, key files, dependencies]
+
+## Tasks
+- [Implementation steps if defined in the spec]
+
+Only include what's IN the search results.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'api-spec': `You are synthesizing a context injection from a structured API specification (OpenAPI, AsyncAPI, GraphQL, gRPC/Proto).
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Endpoints / Operations
+- [Method + path + description, or query/mutation/subscription name]
+
+## Schema
+- [Request/response types, message definitions, input types]
+
+## Parameters
+- [Path params, query params, headers, field arguments]
+
+## Authentication
+- [Security schemes, required headers/tokens]
+
+## Errors
+- [Error codes, error types, validation rules]
+
+Only include what's IN the search results. Preserve exact type names and field definitions.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'bdd-spec': `You are synthesizing a context injection from BDD/Gherkin specifications.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Features
+- [Feature name and description]
+
+## Scenarios
+- [Scenario name: Given/When/Then steps summarized]
+
+## Business Rules
+- [Rules or constraints implied by the scenarios]
+
+## Test Coverage
+- [What behaviors are specified vs gaps]
+
+Only include what's IN the search results. Preserve exact Given/When/Then language.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'architecture': `You are synthesizing a context injection from architecture documentation (C4 model, Structurizr, arc42, or similar).
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## System Overview
+- [Systems, containers, and their purposes]
+
+## Components
+- [Key components and their responsibilities]
+
+## Relationships
+- [How components interact — protocols, data flow]
+
+## Constraints
+- [Technology choices, deployment requirements, quality attributes]
+
+Only include what's IN the search results. Preserve exact component and system names.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'pkm': `You are synthesizing a context injection from a personal knowledge base (Obsidian, Logseq, Foam, or similar PKM vault).
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Key Insights
+- [Main ideas and conclusions relevant to the task]
+
+## Decisions & Agreements
+- [Any decisions, commitments, or agreements captured in the notes]
+
+## Connected Topics
+- [Related notes, linked concepts, and cross-references mentioned]
+
+## Context & Background
+- [Relevant context, meeting notes, or research findings]
+
+Only include what's IN the search results. Preserve note titles and link references.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'project-docs': `You are synthesizing a context injection from internal project documentation that contains both specifications and code examples.
+
+Task: {query}
+{fileContext}
+
+Search results from project docs:
+{results}
+
+Structure as:
+
+## Requirements & Decisions
+- [Relevant requirements, acceptance criteria, or architectural decisions]
+
+## Implementation Notes
+- [Code patterns, conventions, or technical constraints from the project]
+
+## Code Context
+[Relevant code examples from the project docs -- not from external frameworks]
+
+## Dependencies & Risks
+- [Related components, migration concerns, or known issues]
+
+Only include what's IN the search results. Don't add external knowledge.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+
+  'wiki': `You are synthesizing a context injection from general documentation.
+
+Task: {query}
+{fileContext}
+
+Search results:
+{results}
+
+Structure as:
+
+## Summary
+- [Key points relevant to the task]
+
+## Details
+- [Specific information the agent needs]
+
+## Related
+- [Connected topics or references mentioned]
+
+Only include what's IN the search results.
+If not relevant: NO_RELEVANT_KNOWLEDGE`,
+};
+
+/**
+ * Get the synthesis prompt for a source type.
+ * Falls back to 'wiki' template for unknown types.
+ *
+ * @param {string} sourceType
+ * @param {object} vars - { query, file, results }
+ * @returns {string} filled prompt
+ */
+export function getSynthesisPrompt(sourceType, vars) {
+  const template = SYNTHESIS_TEMPLATES[sourceType] ?? SYNTHESIS_TEMPLATES['wiki'];
+  // Sanitize inputs: length-limit to prevent prompt injection and context overflow
+  const query = String(vars.query ?? '').slice(0, 500);
+  const file = vars.file ? `File: ${String(vars.file).slice(0, 200)}` : '';
+  const results = String(vars.results ?? '').slice(0, 10000);
+  return template
+    .replace('{query}', query)
+    .replace('{fileContext}', file)
+    .replace('{results}', results);
+}
+
+/**
+ * Detect the majority source type from search result metadata.
+ * @param {Array} results - search results with metadata
+ * @returns {string|null} majority source type or null
+ */
+export function detectResultSourceType(results) {
+  const counts = {};
+  for (const r of results) {
+    const st = r.metadata?.sourceType ?? r.metadata?.sourceName;
+    if (st) counts[st] = (counts[st] ?? 0) + 1;
+  }
+  if (Object.keys(counts).length === 0) return null;
+
+  // Return the most frequent
+  return Object.entries(counts).sort((a, b) => b[1] - a[1])[0][0];
+}

package/lib/installer.js

@@ -0,0 +1,70 @@
+import fs from 'fs';
+import path from 'path';
+import https from 'https';
+import { SKILL_REGISTRY } from './registry/skills.js';
+import { BookLibIndexer } from './engine/indexer.js';
+import { resolveBookLibPaths } from './paths.js';
+
+/**
+ * Handles adding new skills from the registry or external URLs.
+ */
+export class BookLibInstaller {
+  constructor() {
+    this.indexer = new BookLibIndexer();
+  }
+
+  async add(skillId) {
+    const registryEntry = SKILL_REGISTRY.find(s => s.id === skillId);
+    let url = registryEntry ? registryEntry.url : skillId;
+
+    if (!url.startsWith('http')) {
+      throw new Error(`Invalid skill ID or URL: ${skillId}`);
+    }
+
+    console.log(`Fetching skill from ${url}...`);
+    let content = await this.fetchUrl(url);
+    
+    // Universal Adapter: Ensure the content is wrapped in BookLib tags for retrieval
+    if (!content.includes('<framework>') && !content.includes('<core_principles>')) {
+      console.log('External skill detected. Applying Universal Wrap...');
+      content = `
+---
+name: ${registryEntry ? registryEntry.id : 'external-skill'}
+source: ${url}
+---
+
+# ${registryEntry ? registryEntry.name : 'External Skill'}
+
+<framework>
+${content}
+</framework>
+
+> **Note**: This skill was automatically optimized by the BookLib Universal Engine.
+`;
+    }
+
+    const { cachePath } = resolveBookLibPaths();
+    const targetDir = path.join(cachePath, 'skills', registryEntry ? registryEntry.name : 'external');
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    const targetFile = path.join(targetDir, 'SKILL.md');
+    fs.writeFileSync(targetFile, content);
+    console.log(`Skill saved to ${targetFile}`);
+
+    console.log('Re-indexing to include new skill...');
+    await this.indexer.indexDirectory(targetDir);
+    console.log('Success.');
+  }
+
+  fetchUrl(url) {
+    return new Promise((resolve, reject) => {
+      https.get(url, (res) => {
+        let data = '';
+        res.on('data', (chunk) => data += chunk);
+        res.on('end', () => resolve(data));
+      }).on('error', reject);
+    });
+  }
+}

package/lib/instinct-block.js

@@ -0,0 +1,21 @@
+/**
+ * Returns CLI command instructions for non-MCP tools.
+ * MCP-capable tools return null — they discover BookLib via MCP protocol.
+ *
+ * @param {string} target - Tool target (claude, cursor, junie, etc.)
+ * @returns {string|null} Markdown block for non-MCP tools, null for MCP tools
+ */
+
+const MCP_TOOLS = new Set([
+  'claude', 'cursor', 'copilot', 'gemini', 'codex',
+  'windsurf', 'roo-code', 'goose', 'zed', 'continue',
+]);
+
+export function renderInstinctBlock(target) {
+  if (MCP_TOOLS.has(target)) return null;
+
+  return `## BookLib
+Run \`booklib search "query"\` for relevant principles.
+Run \`booklib capture --title "..." --type decision\` to save knowledge.
+Run \`booklib doctor\` for health check.`;
+}