@mseep/core 3.0.0

package/lib/conflict-resolver.js

@@ -0,0 +1,148 @@
+/**
+ * Resolves conflicts between skill suggestions or indexed chunks.
+ *
+ * Resolution rules (applied per topic group):
+ *   specificity delta >= 2  OR  score delta >= 0.2  →  auto-resolve (higher wins, rationale attached)
+ *   otherwise                                        →  escalate (add to conflicts list)
+ *
+ * Usage:
+ *   const resolver = new ConflictResolver(registryArray);
+ *   const { winners, suppressed, conflicts } = resolver.resolveSkills(suggestions);
+ *   const { winners, suppressed, conflicts } = resolver.resolveChunks(searchResults);
+ */
+export class ConflictResolver {
+  /**
+   * @param {Array<{name: string, specificity?: number, topic?: string, stars?: number}>} registry
+   */
+  constructor(registry = []) {
+    this._byName = new Map(registry.map(s => [s.name, s]));
+  }
+
+  /**
+   * Resolves conflicts between registry-level skill suggestions.
+   * @param {object[]} skills  — each must have .name
+   */
+  resolveSkills(skills) {
+    return this._resolve(
+      skills,
+      s => s.name,
+      s => this._meta(s.name, s)
+    );
+  }
+
+  /**
+   * Resolves conflicts between semantic-search chunks.
+   * @param {Array<{score: number, text: string, metadata: object}>} chunks
+   */
+  resolveChunks(chunks) {
+    // Deduplicate by skill name — keep highest-scored chunk per skill
+    const bySkill = new Map();
+    for (const c of chunks) {
+      const raw = c.metadata?.name ?? c.metadata?.filePath ?? 'unknown';
+      // Normalise to skill name: take first path segment (handles reference file paths like
+      // "clean-code-reviewer/references/review-checklist.md" → "clean-code-reviewer")
+      const skillName = raw.includes('/') ? raw.split('/')[0] : raw;
+      const existing = bySkill.get(skillName);
+      if (!existing || (c.score ?? 0) > (existing.score ?? 0)) {
+        bySkill.set(skillName, c);
+      }
+    }
+    const deduped = [...bySkill.values()];
+    return this._resolve(
+      deduped,
+      c => c.metadata?.name ?? c.metadata?.filePath ?? 'unknown',
+      c => this._meta(c.metadata?.name, c)
+    );
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  /** Look up registry metadata, falling back to inline values or defaults. */
+  _meta(name, item = {}) {
+    const reg = this._byName.get(name);
+    return {
+      specificity: reg?.specificity ?? item?.specificity ?? 5,
+      topic: reg?.topic ?? item?.topic ?? name ?? 'unknown',
+      stars: reg?.stars ?? item?.stars ?? 0,
+    };
+  }
+
+  _resolve(items, getName, getMeta) {
+    // Group by topic
+    const byTopic = new Map();
+    for (const item of items) {
+      const { topic } = getMeta(item);
+      if (!byTopic.has(topic)) byTopic.set(topic, []);
+      byTopic.get(topic).push(item);
+    }
+
+    const winners = [];
+    const suppressed = [];
+    const conflicts = [];
+
+    for (const [, candidates] of byTopic) {
+      if (candidates.length === 1) {
+        winners.push({ ...candidates[0], _decision: 'auto', _rationale: null });
+        continue;
+      }
+
+      // Sort: specificity desc → score desc → stars desc
+      const sorted = [...candidates].sort((a, b) => {
+        const ma = getMeta(a), mb = getMeta(b);
+        if (mb.specificity !== ma.specificity) return mb.specificity - ma.specificity;
+        if ((b.score ?? 0) !== (a.score ?? 0)) return (b.score ?? 0) - (a.score ?? 0);
+        return (mb.stars ?? 0) - (ma.stars ?? 0);
+      });
+
+      const best = sorted[0];
+      const bestMeta = getMeta(best);
+      let bestAdded = false;
+
+      for (const runner of sorted.slice(1)) {
+        const runnerMeta = getMeta(runner);
+        const dSpec = bestMeta.specificity - runnerMeta.specificity;
+        const dScore = (best.score ?? 0) - (runner.score ?? 0);
+
+        if (dSpec >= 2 || dScore >= 0.2) {
+          // Clear winner — auto-resolve silently
+          const reason = dSpec >= 2
+            ? `more specific (${bestMeta.specificity} vs ${runnerMeta.specificity})`
+            : `higher relevance (${(best.score ?? 0).toFixed(2)} vs ${(runner.score ?? 0).toFixed(2)})`;
+
+          if (!bestAdded) {
+            winners.push({
+              ...best,
+              _decision: 'auto',
+              _rationale: `chosen over \`${getName(runner)}\` — ${reason}`,
+            });
+            bestAdded = true;
+          }
+          suppressed.push({ ...runner, _decision: 'suppressed', _rationale: `\`${getName(best)}\` preferred — ${reason}` });
+        } else {
+          // Genuine conflict — escalate to human
+          if (!conflicts.find(c => c.options.some(o => o.name === getName(best)))) {
+            conflicts.push({
+              topic: bestMeta.topic,
+              options: sorted.map(s => ({
+                name: getName(s),
+                specificity: getMeta(s).specificity,
+                score: s.score ?? null,
+              })),
+              message:
+                `\`${getName(best)}\` vs \`${getName(runner)}\` — both equally applicable` +
+                ` (specificity ${bestMeta.specificity} vs ${runnerMeta.specificity}).` +
+                ` Which should guide this decision?`,
+            });
+          }
+        }
+      }
+
+      // Add best as winner if no conflict was raised for it
+      if (!bestAdded && !conflicts.some(c => c.options.some(o => o.name === getName(best)))) {
+        winners.push({ ...best, _decision: 'auto', _rationale: null });
+      }
+    }
+
+    return { winners, suppressed, conflicts };
+  }
+}

package/lib/connectors/context7.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CONTEXT7_API = 'https://context7.com/api';
+const TIMEOUT_MS = 10000;
+
+export class Context7Connector {
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey ?? process.env.CONTEXT7_API_KEY;
+  }
+
+  /**
+   * Context7 works without an API key (rate-limited).
+   * With a key, higher rate limits apply.
+   * @returns {{ ok: boolean }}
+   */
+  checkAuth() {
+    return { ok: true };
+  }
+
+  /**
+   * Search for a library by name.
+   * @param {string} libraryName - e.g., "next", "react", "stripe"
+   * @param {string} [query] - optional query for relevance ranking
+   * @returns {Promise<Array<{ id: string, name: string, description: string, versions?: string[] }> | null>}
+   */
+  async searchLibrary(libraryName, query) {
+    const params = new URLSearchParams({
+      libraryName,
+      query: query ?? libraryName,
+    });
+    const data = await this._apiGet(`/v2/libs/search?${params}`);
+    if (!data?.results) return null;
+    return data.results.map(r => ({
+      id: r.id ?? r.libraryId,
+      name: r.name ?? r.title ?? libraryName,
+      description: r.description ?? '',
+      versions: r.versions ?? [],
+      totalSnippets: r.totalSnippets ?? r.snippetCount ?? 0,
+    }));
+  }
+
+  /**
+   * Fetch documentation for a library and save as markdown files.
+   * @param {string} libraryId - Context7 library ID (e.g., "/vercel/next.js")
+   * @param {string} query - what to search for in the docs
+   * @param {string} outputDir - where to save markdown
+   * @returns {Promise<{ pageCount: number }>}
+   */
+  async fetchDocs(libraryId, query, outputDir) {
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    // Request text format — returns rich markdown with code examples.
+    // JSON format returns a thin parsed version with less content.
+    const params = new URLSearchParams({ libraryId, query });
+    const text = await this._apiGetText(`/v2/context?${params}`);
+
+    if (!text || text.trim().length < 50) return { pageCount: 0 };
+
+    // Split by Context7's section separator into individual docs
+    const sections = text.split(/^-{20,}$/m).filter(s => s.trim());
+
+    if (sections.length === 0) {
+      // Single doc — save as-is
+      fs.writeFileSync(path.join(outputDir, 'docs.md'), text.trim() + '\n');
+      return { pageCount: 1 };
+    }
+
+    try {
+      let count = 0;
+      for (const section of sections) {
+        const trimmed = section.trim();
+        if (!trimmed) continue;
+        // Extract title from first heading or first line
+        const titleMatch = trimmed.match(/^###?\s+(.+)/m);
+        const title = titleMatch ? titleMatch[1].slice(0, 80) : `section-${count}`;
+        const filename = this._sanitize(title) + '.md';
+        fs.writeFileSync(path.join(outputDir, filename), trimmed + '\n');
+        count++;
+      }
+      return { pageCount: count };
+    } catch (err) {
+      fs.rmSync(outputDir, { recursive: true, force: true });
+      throw err;
+    }
+  }
+
+  /**
+   * Resolve a package name to a Context7 library and fetch its docs.
+   * Convenience method combining searchLibrary + fetchDocs.
+   * @param {string} packageName - e.g., "next", "react"
+   * @param {string} outputDir
+   * @param {string} [query] - what aspect to fetch docs for
+   * @returns {Promise<{ resolved: boolean, libraryId?: string, pageCount: number }>}
+   */
+  async resolveAndFetch(packageName, outputDir, query) {
+    const libraries = await this.searchLibrary(
+      packageName,
+      query ?? `${packageName} API documentation`,
+    );
+    if (!libraries || libraries.length === 0) {
+      return { resolved: false, pageCount: 0 };
+    }
+
+    const best = libraries[0];
+    const result = await this.fetchDocs(
+      best.id,
+      query ?? `${packageName} usage guide API`,
+      outputDir,
+    );
+
+    return { resolved: true, libraryId: best.id, pageCount: result.pageCount };
+  }
+
+  /** GET request to Context7 API. */
+  async _apiGet(endpoint) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const res = await fetch(`${CONTEXT7_API}${endpoint}`, {
+        signal: controller.signal,
+        headers: {
+          ...(this.apiKey ? { 'Authorization': `Bearer ${this.apiKey}` } : {}),
+          'X-Context7-Source': 'booklib',
+          'User-Agent': 'BookLib/1.0',
+        },
+      });
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /** GET request returning raw text (for /v2/context text format). */
+  async _apiGetText(endpoint) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const res = await fetch(`${CONTEXT7_API}${endpoint}`, {
+        signal: controller.signal,
+        headers: {
+          ...(this.apiKey ? { 'Authorization': `Bearer ${this.apiKey}` } : {}),
+          'X-Context7-Source': 'booklib',
+          'User-Agent': 'BookLib/3.0',
+        },
+      });
+      if (!res.ok) return null;
+      return await res.text();
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /** Sanitize a string for use as a filename. */
+  _sanitize(str) {
+    return str
+      .replace(/[/\\:*?"<>|]/g, '_')
+      .replace(/\s+/g, '-')
+      .slice(0, 80)
+      .toLowerCase();
+  }
+}

package/lib/connectors/github.js

@@ -0,0 +1,223 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const RATE_MS = 1000;
+
+export class GitHubConnector {
+  constructor(opts = {}) {
+    this.rateMs = opts.rateMs ?? RATE_MS;
+  }
+
+  /**
+   * Check if gh CLI is installed and authenticated.
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  checkAuth() {
+    try {
+      execFileSync('gh', ['auth', 'status'], { stdio: 'pipe' });
+      return { ok: true };
+    } catch {
+      return {
+        ok: false,
+        error: 'gh CLI not authenticated. Install: https://cli.github.com then run: gh auth login',
+      };
+    }
+  }
+
+  /**
+   * Fetch releases from a GitHub repo and save as markdown.
+   * @param {string} repo - owner/repo format
+   * @param {string} outputDir - where to save markdown files
+   * @param {object} [opts]
+   * @param {number} [opts.limit=30] - max releases to fetch
+   * @param {string} [opts.since] - ISO date, only fetch releases after this
+   * @returns {Promise<{ pageCount: number, releases: string[] }>}
+   */
+  async fetchReleases(repo, outputDir, opts = {}) {
+    const { limit = 30, since } = opts;
+    this._validateRepo(repo);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    const data = this._ghApi(`/repos/${repo}/releases?per_page=${Math.min(limit, 100)}`);
+    let releases;
+    try {
+      releases = JSON.parse(data);
+    } catch {
+      return { pageCount: 0, releases: [] };
+    }
+
+    if (!Array.isArray(releases)) return { pageCount: 0, releases: [] };
+
+    const saved = [];
+    for (const release of releases) {
+      if (since && new Date(release.published_at) <= new Date(since)) continue;
+
+      const tag = release.tag_name.replace(/[/\\:*?"<>|]/g, '_');
+      const filename = `release-${tag}.md`;
+      const content = this._formatRelease(release);
+      fs.writeFileSync(path.join(outputDir, filename), content);
+      saved.push(filename);
+    }
+
+    return { pageCount: saved.length, releases: saved };
+  }
+
+  /**
+   * Fetch wiki pages by cloning the wiki git repo.
+   * GitHub wikis live at <repo>.wiki.git — no REST API endpoint exists.
+   * @param {string} repo - owner/repo format
+   * @param {string} outputDir
+   * @returns {Promise<{ pageCount: number }>}
+   */
+  async fetchWiki(repo, outputDir) {
+    this._validateRepo(repo);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    const wikiUrl = `https://github.com/${repo}.wiki.git`;
+    try {
+      // Array form prevents shell injection via outputDir
+      execFileSync('git', ['clone', '--depth', '1', wikiUrl, outputDir], {
+        stdio: 'pipe',
+        timeout: 30000,
+      });
+    } catch (err) {
+      const msg = err.stderr?.toString() ?? '';
+      if (msg.includes('not found') || msg.includes('not exist')) {
+        return { pageCount: 0 };
+      }
+      throw new Error(`Wiki clone failed: ${msg.slice(0, 200)}`);
+    }
+
+    // Remove .git directory — we only want the content files
+    const gitDir = path.join(outputDir, '.git');
+    if (fs.existsSync(gitDir)) {
+      fs.rmSync(gitDir, { recursive: true, force: true });
+    }
+
+    const files = fs.readdirSync(outputDir).filter(f => f.endsWith('.md'));
+    return { pageCount: files.length };
+  }
+
+  /**
+   * Fetch discussion threads via GraphQL API.
+   * @param {string} repo - owner/repo format
+   * @param {string} outputDir
+   * @param {object} [opts]
+   * @param {number} [opts.limit=20] - max discussions
+   * @param {string} [opts.category] - filter by category name
+   * @returns {Promise<{ pageCount: number }>}
+   */
+  async fetchDiscussions(repo, outputDir, opts = {}) {
+    const { limit = 20, category } = opts;
+    this._validateRepo(repo);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    const [owner, name] = repo.split('/');
+    const count = Math.min(limit, 100);
+
+    // Parameterized GraphQL query — variables passed via -f to prevent injection
+    const query = `query($owner: String!, $name: String!, $count: Int!) {
+      repository(owner: $owner, name: $name) {
+        discussions(first: $count, orderBy: {field: UPDATED_AT, direction: DESC}) {
+          nodes {
+            number title body createdAt updatedAt
+            category { name }
+            answer { body author { login } }
+            comments(first: 10) { nodes { body author { login } } }
+          }
+        }
+      }
+    }`;
+
+    let data;
+    try {
+      const raw = execFileSync('gh', [
+        'api', 'graphql',
+        '-f', `query=${query}`,
+        '-f', `owner=${owner}`,
+        '-f', `name=${name}`,
+        '-F', `count=${count}`,
+      ], { stdio: 'pipe', timeout: 30000 });
+      data = JSON.parse(raw.toString());
+    } catch (err) {
+      const msg = err.stderr?.toString().slice(0, 200) ?? err.message;
+      console.error(`GitHub discussions fetch failed: ${msg}`);
+      return { pageCount: 0 };
+    }
+
+    const discussions = data?.data?.repository?.discussions?.nodes ?? [];
+    let saved = 0;
+
+    for (const disc of discussions) {
+      if (category && disc.category?.name !== category) continue;
+
+      const filename = `discussion-${disc.number}.md`;
+      const content = this._formatDiscussion(disc);
+      fs.writeFileSync(path.join(outputDir, filename), content);
+      saved++;
+    }
+
+    return { pageCount: saved };
+  }
+
+  /** Format a release object as markdown. */
+  _formatRelease(release) {
+    const lines = [
+      `# ${release.name || release.tag_name}`,
+      '',
+      `**Tag:** ${release.tag_name}`,
+      `**Published:** ${release.published_at?.split('T')[0] ?? 'unknown'}`,
+      release.prerelease ? '**Pre-release**' : '',
+      '',
+      release.body ?? '_No release notes._',
+    ];
+    return lines.filter(l => l !== '').join('\n') + '\n';
+  }
+
+  /** Format a discussion as markdown with comments. */
+  _formatDiscussion(disc) {
+    const lines = [
+      `# ${disc.title}`,
+      '',
+      `**Discussion #${disc.number}** — ${disc.category?.name ?? 'General'}`,
+      `**Created:** ${disc.createdAt?.split('T')[0] ?? 'unknown'}`,
+      '',
+      disc.body ?? '',
+    ];
+
+    if (disc.answer) {
+      lines.push('', '---', `## Accepted Answer (by ${disc.answer.author?.login ?? 'unknown'})`, '', disc.answer.body);
+    }
+
+    const comments = disc.comments?.nodes ?? [];
+    if (comments.length > 0) {
+      lines.push('', '---', '## Comments', '');
+      for (const c of comments) {
+        lines.push(`**${c.author?.login ?? 'unknown'}:**`, c.body, '');
+      }
+    }
+
+    return lines.join('\n') + '\n';
+  }
+
+  /** Validate repo format is owner/name. */
+  _validateRepo(repo) {
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      throw new Error(`Invalid repo format: "${repo}". Use owner/repo (e.g., facebook/react)`);
+    }
+  }
+
+  /** Call gh api and return stdout — array form prevents shell injection. */
+  _ghApi(endpoint) {
+    try {
+      return execFileSync('gh', ['api', endpoint], {
+        stdio: 'pipe',
+        timeout: 15000,
+        maxBuffer: 10 * 1024 * 1024,
+      }).toString();
+    } catch (err) {
+      throw new Error(`GitHub API error: ${err.stderr?.toString().slice(0, 200) ?? err.message}`);
+    }
+  }
+}

package/lib/connectors/local.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Local filesystem connector for BookLib.
+ * Walks directories, applies include/exclude filters, tracks mtimes for
+ * incremental re-indexing, and optionally watches for changes.
+ */
+export class LocalConnector {
+  constructor(opts = {}) {
+    this.include = opts.include ?? ['*.md', '*.mdx', '*.txt', '*.rst', '*.adoc'];
+    this.exclude = opts.exclude ?? ['node_modules', '.git', '.booklib'];
+  }
+
+  /**
+   * List files matching include/exclude filters.
+   * @param {string} dirPath - Absolute directory path to walk.
+   * @returns {string[]} Sorted absolute file paths.
+   */
+  listFiles(dirPath) {
+    const results = [];
+    this._walk(dirPath, dirPath, results);
+    return results.sort();
+  }
+
+  /**
+   * Get mtimes for all matching files, keyed by relative path.
+   * @param {string} dirPath
+   * @returns {Object} { [relativePath]: mtimeMs }
+   */
+  getFileMtimes(dirPath) {
+    const files = this.listFiles(dirPath);
+    const mtimes = {};
+    for (const f of files) {
+      mtimes[path.relative(dirPath, f)] = fs.statSync(f).mtimeMs;
+    }
+    return mtimes;
+  }
+
+  /**
+   * Find files that changed since last index.
+   * @param {string} dirPath
+   * @param {Object} previousMtimes - { [relativePath]: mtimeMs } from last index.
+   * @returns {{ changed: string[], removed: string[], currentMtimes: Object }}
+   */
+  findChanges(dirPath, previousMtimes = {}) {
+    const currentMtimes = this.getFileMtimes(dirPath);
+    const changed = [];
+    const removed = [];
+
+    for (const [rel, mtime] of Object.entries(currentMtimes)) {
+      if (!previousMtimes[rel] || previousMtimes[rel] < mtime) {
+        changed.push(path.join(dirPath, rel));
+      }
+    }
+
+    for (const rel of Object.keys(previousMtimes)) {
+      if (!currentMtimes[rel]) {
+        removed.push(rel);
+      }
+    }
+
+    return { changed, removed, currentMtimes };
+  }
+
+  /**
+   * Watch directory for changes, calling callback on each matching file event.
+   * @param {string} dirPath
+   * @param {function} onChange - Called with (eventType, filename).
+   * @returns {fs.FSWatcher}
+   */
+  watch(dirPath, onChange) {
+    console.log(`Watching ${dirPath} for changes (Ctrl+C to stop)...`);
+    let debounceTimer = null;
+    const pending = new Set();
+
+    const watcher = fs.watch(dirPath, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+      if (!this._matchesFilters(filename)) return;
+      pending.add(filename);
+
+      // Debounce: wait 500ms after last event before calling onChange
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        const files = [...pending];
+        pending.clear();
+        onChange(eventType, files);
+      }, 500);
+    });
+    return watcher;
+  }
+
+  /**
+   * Check if a filename matches include patterns and does not match exclude.
+   * @param {string} filename
+   * @returns {boolean}
+   */
+  _matchesFilters(filename) {
+    for (const excl of this.exclude) {
+      if (filename.includes(excl)) return false;
+    }
+    const ext = path.extname(filename).toLowerCase();
+    const includeExts = this.include.map(p => p.startsWith('*.') ? p.slice(1) : p);
+    return includeExts.some(e => ext === e);
+  }
+
+  /** Recursively walk a directory, collecting matching files. */
+  _walk(currentDir, rootDir, results) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (this.exclude.some(excl => entry.name === excl)) continue;
+        this._walk(fullPath, rootDir, results);
+      } else if (entry.isFile() && this._matchesFilters(entry.name)) {
+        results.push(fullPath);
+      }
+    }
+  }
+}