@booklib/core 2.0.0

package/lib/registry/skills.js

@@ -0,0 +1,102 @@
+/**
+ * The BookLib Curated Registry.
+ *
+ * Each entry describes a skill — where it lives, what triggers it,
+ * and which languages it applies to. The `source` field tells the
+ * skill fetcher how to retrieve the skill content.
+ *
+ * source.type values:
+ *   "npm"    — bundled in this package, available at source.path
+ *   "github" — raw content fetched from source.url
+ */
+export const SKILL_REGISTRY = [
+  {
+    name: 'clean-code-reviewer',
+    description: 'Principles for readable, maintainable, and expressive code.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/clean-code-reviewer' },
+    triggers: { extensions: ['.js', '.ts', '.py', '.java', '.kt', '.rb'], keywords: ['naming', 'functions', 'refactor', 'smells', 'clean code'] },
+    languages: ['all'],
+    version: '1.10.0',
+  },
+  {
+    name: 'effective-kotlin',
+    description: 'Best practices for safety, readability, and efficiency in Kotlin.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/effective-kotlin' },
+    triggers: { extensions: ['.kt', '.kts'], keywords: ['kotlin', 'null safety', 'mutability', 'coroutines'] },
+    languages: ['kotlin'],
+    version: '1.10.0',
+  },
+  {
+    name: 'effective-typescript',
+    description: 'Type-safe patterns from the 62 items of Effective TypeScript.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/effective-typescript' },
+    triggers: { extensions: ['.ts', '.tsx'], keywords: ['typescript', 'type safety', 'any', 'generics', 'inference'] },
+    languages: ['typescript'],
+    version: '1.10.0',
+  },
+  {
+    name: 'effective-python',
+    description: 'Pythonic patterns from Effective Python 3rd edition.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/effective-python' },
+    triggers: { extensions: ['.py'], keywords: ['python', 'pythonic', 'comprehensions', 'generators', 'async'] },
+    languages: ['python'],
+    version: '1.10.0',
+  },
+  {
+    name: 'effective-java',
+    description: 'Best practices from Effective Java 3rd edition.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/effective-java' },
+    triggers: { extensions: ['.java'], keywords: ['java', 'generics', 'concurrency', 'immutability', 'builder'] },
+    languages: ['java'],
+    version: '1.10.0',
+  },
+  {
+    name: 'domain-driven-design',
+    description: 'DDD patterns: aggregates, value objects, bounded contexts.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/domain-driven-design' },
+    triggers: { extensions: ['.ts', '.java', '.kt', '.py'], keywords: ['domain', 'aggregate', 'entity', 'value object', 'bounded context', 'ddd'] },
+    languages: ['all'],
+    version: '1.10.0',
+  },
+  {
+    name: 'microservices-patterns',
+    description: 'Patterns for building reliable microservices.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/microservices-patterns' },
+    triggers: { extensions: ['.ts', '.java', '.py', '.go'], keywords: ['microservices', 'saga', 'event', 'api gateway', 'service mesh'] },
+    languages: ['all'],
+    version: '1.10.0',
+  },
+  {
+    name: 'system-design-interview',
+    description: 'High-level patterns for scalability, estimation, and distributed systems.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/system-design-interview' },
+    triggers: { extensions: ['.md', '.ts', '.java'], keywords: ['scalability', 'load balancer', 'caching', 'replication', 'sharding'] },
+    languages: ['all'],
+    version: '1.10.0',
+  },
+  {
+    name: 'data-intensive-patterns',
+    description: 'Patterns for data systems: storage, replication, consistency.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/data-intensive-patterns' },
+    triggers: { extensions: ['.py', '.java', '.scala', '.ts'], keywords: ['data', 'replication', 'consistency', 'stream', 'batch', 'kafka'] },
+    languages: ['all'],
+    version: '1.10.0',
+  },
+  {
+    name: 'refactoring-ui',
+    description: 'Visual design principles for developers building UI.',
+    source: { type: 'npm', package: '@booklib/skills', path: 'skills/refactoring-ui' },
+    triggers: { extensions: ['.tsx', '.jsx', '.css', '.html', '.svelte', '.vue'], keywords: ['ui', 'design', 'spacing', 'typography', 'color', 'tailwind'] },
+    languages: ['typescript', 'javascript', 'css'],
+    version: '1.10.0',
+  },
+  // External / community skills (fetched from GitHub on demand)
+  {
+    name: 'superpowers-debug',
+    description: 'Systematic debugging workflow.',
+    source: { type: 'github', url: 'https://raw.githubusercontent.com/obra/superpowers/main/skills/debugging.md' },
+    triggers: { extensions: [], keywords: ['debugging', 'troubleshooting', 'systematic', 'bug'] },
+    languages: ['all'],
+    version: null,
+  },
+];

package/lib/registry-searcher.js

@@ -0,0 +1,99 @@
+import { SKILL_REGISTRY } from './registry/skills.js';
+import { BookLibSearcher } from './engine/searcher.js';
+import { resolveBookLibPaths } from './paths.js';
+import { loadConfig } from './config-loader.js';
+import { DiscoveryEngine } from './discovery-engine.js';
+import { ConflictResolver } from './conflict-resolver.js';
+
+/**
+ * Orchestrates the 'Suggested Retrieval' flow.
+ * Combines local semantic search with registry-level keyword suggestions.
+ */
+export class BookLibRegistrySearcher {
+  constructor(options = {}) {
+    this.projectCwd = options.projectCwd;
+    const paths = resolveBookLibPaths(options.projectCwd);
+    this.searcher = new BookLibSearcher(paths.indexPath);
+    this.config = loadConfig(options.projectCwd);
+    this.threshold = this.config.search.registryFallbackThreshold;
+    this.minScore = this.config.search.minScore;
+  }
+
+  async searchHybrid(query, options = {}) {
+    const { useGraph = false } = options;
+    // 1. Perform local semantic search
+    let localResults = [];
+    try {
+      localResults = await this.searcher.search(query, 5, this.minScore, { useGraph });
+    } catch {
+      // Local index might not exist yet
+    }
+
+    // 2. Fall back to keyword matching across bundled registry + community manifest
+    const bestLocalScore = localResults[0]?.score ?? 0;
+    const useFallback = bestLocalScore < this.threshold;
+
+    let suggestions = [];
+    if (useFallback) {
+      const queryLower = query.toLowerCase();
+      const queryWords = queryLower.split(/\s+/).filter(w => w.length > 2);
+
+      const matchesQuery = (skill) => {
+        if (!skill.triggers?.keywords) return false;
+        const keywordMatch = skill.triggers.keywords.some(k => {
+          const kLower = k.toLowerCase();
+          return queryLower.includes(kLower) ||
+            kLower.split(/\s+/).some(kw => queryWords.includes(kw));
+        });
+        return keywordMatch ||
+          skill.name.toLowerCase().includes(queryLower) ||
+          queryWords.some(w => (skill.description ?? '').toLowerCase().includes(w));
+      };
+
+      const alreadyLocal = (skill) =>
+        localResults.some(r => r.metadata?.name === (skill.name ?? skill.id));
+
+      // Bundled registry suggestions
+      const bundledSuggestions = SKILL_REGISTRY.filter(s => matchesQuery(s) && !alreadyLocal(s));
+
+      // Community manifest suggestions (cached — no network call)
+      let communitySuggestions = [];
+      try {
+        const engine = new DiscoveryEngine({ projectCwd: this.projectCwd });
+        const discovered = await engine.discover();
+        communitySuggestions = discovered.filter(s => matchesQuery(s) && !alreadyLocal(s));
+      } catch { /* non-fatal */ }
+
+      suggestions = [...bundledSuggestions, ...communitySuggestions];
+    }
+
+    // Run conflict resolution on suggestions using community registry metadata
+    let resolved = { winners: suggestions, suppressed: [], conflicts: [] };
+    if (suggestions.length > 1) {
+      try {
+        const engine = new DiscoveryEngine({ projectCwd: this.projectCwd });
+        const allSkills = await engine.discover();
+        const resolver = new ConflictResolver(allSkills);
+        resolved = resolver.resolveSkills(suggestions);
+      } catch { /* non-fatal — fall back to unresolved list */ }
+    }
+
+    // Run conflict resolution on local chunks using registry metadata
+    let resolvedLocal = { winners: localResults, suppressed: [], conflicts: [] };
+    if (localResults.length > 1) {
+      try {
+        const engine = new DiscoveryEngine({ projectCwd: this.projectCwd });
+        const allSkills = await engine.discover();
+        const resolver = new ConflictResolver(allSkills);
+        resolvedLocal = resolver.resolveChunks(localResults);
+      } catch { /* non-fatal */ }
+    }
+
+    return {
+      local: resolvedLocal.winners,
+      suggested: resolved.winners,
+      suppressed: [...(resolvedLocal.suppressed ?? []), ...(resolved.suppressed ?? [])],
+      conflicts: [...(resolvedLocal.conflicts ?? []), ...(resolved.conflicts ?? [])],
+    };
+  }
+}

package/lib/rules/rules-manager.js

@@ -0,0 +1,169 @@
+// lib/rules/rules-manager.js
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const RULES_DIR = path.join(PACKAGE_ROOT, 'rules');
+
+function markerStart(lang) { return `<!-- booklib-rules-${lang}-start -->`; }
+function markerEnd(lang)   { return `<!-- booklib-rules-${lang}-end -->`; }
+function escapeRegex(s)    { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+function _ensureAlwaysApply(content) {
+  if (!content.trimStart().startsWith('---')) {
+    // No frontmatter — add complete block
+    return `---\nalwaysApply: false\n---\n\n${content}`;
+  }
+  // Has frontmatter — check if alwaysApply is already set
+  if (content.includes('alwaysApply:')) return content;
+  // Inject alwaysApply before the closing ---
+  // Frontmatter ends at the first \n---\n (or \n--- at EOF) after the opening ---
+  const fmEnd = content.indexOf('\n---', 3); // skip the opening ---
+  if (fmEnd === -1) return content; // malformed, leave as-is
+  return content.slice(0, fmEnd) + '\nalwaysApply: false' + content.slice(fmEnd);
+}
+
+/**
+ * Lists all bundled language rule sets with project/global install status.
+ */
+export function listAvailable(cwd = process.cwd(), home = os.homedir()) {
+  if (!fs.existsSync(RULES_DIR)) return [];
+
+  const claudeMdPath = path.join(home, '.claude', 'CLAUDE.md');
+  const claudeMdContent = fs.existsSync(claudeMdPath)
+    ? fs.readFileSync(claudeMdPath, 'utf8')
+    : '';
+
+  const langDirs = fs.readdirSync(RULES_DIR, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+
+  return langDirs.map(lang => {
+    const files = fs.readdirSync(path.join(RULES_DIR, lang))
+      .filter(f => f.endsWith('.md'));
+
+    const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
+    const installedProject = fs.existsSync(cursorRulesDir) &&
+      fs.readdirSync(cursorRulesDir).some(f => f.startsWith(`${lang}-`) && f.endsWith('.mdc'));
+
+    const installedGlobal = claudeMdContent.includes(markerStart(lang));
+
+    return { lang, files, installedProject, installedGlobal };
+  });
+}
+
+/**
+ * Installs a language rule set to the project (.cursor/rules/) or globally (~/.claude/CLAUDE.md).
+ *
+ * @param {string} lang
+ * @param {{ cwd?, home?, global?, dryRun? }} opts
+ * @returns {string[]} written file paths
+ */
+export function installRule(lang, {
+  cwd = process.cwd(),
+  home = os.homedir(),
+  global: isGlobal = false,
+  dryRun = false,
+} = {}) {
+  const langDir = path.join(RULES_DIR, lang);
+  if (!fs.existsSync(langDir)) {
+    const available = fs.readdirSync(RULES_DIR, { withFileTypes: true })
+      .filter(e => e.isDirectory()).map(e => e.name);
+    throw new Error(`Unknown language: '${lang}'. Available: ${available.join(', ')}`);
+  }
+
+  const mdFiles = fs.readdirSync(langDir).filter(f => f.endsWith('.md'));
+  if (mdFiles.length === 0) return [];
+
+  return isGlobal
+    ? _installGlobal(lang, langDir, mdFiles, home, dryRun)
+    : _installProject(lang, langDir, mdFiles, cwd, dryRun);
+}
+
+function _installProject(lang, langDir, mdFiles, cwd, dryRun) {
+  const destDir = path.join(cwd, '.cursor', 'rules');
+  const written = [];
+
+  if (!dryRun) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  for (const file of mdFiles) {
+    const content = _ensureAlwaysApply(fs.readFileSync(path.join(langDir, file), 'utf8'));
+    const destPath = path.join(destDir, `${lang}-${file.replace(/\.md$/, '.mdc')}`);
+    if (!dryRun) {
+      fs.writeFileSync(destPath, content);
+    }
+    written.push(destPath);
+  }
+  return written;
+}
+
+function _installGlobal(lang, langDir, mdFiles, home, dryRun) {
+  const claudeDir    = path.join(home, '.claude');
+  const claudeMdPath = path.join(claudeDir, 'CLAUDE.md');
+
+  const body = mdFiles
+    .map(f => fs.readFileSync(path.join(langDir, f), 'utf8'))
+    .join('\n\n');
+
+  const section = [
+    markerStart(lang),
+    `## ${lang.charAt(0).toUpperCase() + lang.slice(1)} Standards (BookLib)`,
+    '',
+    body,
+    markerEnd(lang),
+  ].join('\n');
+
+  if (!dryRun) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+    let existing = '';
+    try { existing = fs.readFileSync(claudeMdPath, 'utf8'); } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    const re = new RegExp(
+      `${escapeRegex(markerStart(lang))}[\\s\\S]*?${escapeRegex(markerEnd(lang))}`,
+    );
+    const updated = existing.includes(markerStart(lang))
+      ? existing.replace(re, section)
+      : (existing ? `${existing}\n\n${section}\n` : `${section}\n`);
+
+    fs.writeFileSync(claudeMdPath, updated);
+  }
+  return [claudeMdPath];
+}
+
+/**
+ * Returns sizes of all installed rules in the current project and globally.
+ */
+export function status(cwd = process.cwd(), home = os.homedir()) {
+  const cursorRulesDir = path.join(cwd, '.cursor', 'rules');
+  const claudeMdPath   = path.join(home, '.claude', 'CLAUDE.md');
+
+  const cursor = [];
+  if (fs.existsSync(cursorRulesDir)) {
+    for (const file of fs.readdirSync(cursorRulesDir)) {
+      if (!file.endsWith('.mdc')) continue;
+      const p = path.join(cursorRulesDir, file);
+      cursor.push({ path: p, sizeBytes: fs.statSync(p).size });
+    }
+  }
+
+  const globalEntries = [];
+  if (fs.existsSync(claudeMdPath)) {
+    const content = fs.readFileSync(claudeMdPath, 'utf8');
+    const re = /<!-- booklib-rules-(\w+)-start -->([\s\S]*?)<!-- booklib-rules-\1-end -->/g;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+      globalEntries.push({ lang: match[1], sizeBytes: Buffer.byteLength(match[0], 'utf8') });
+    }
+  }
+
+  const totalBytes = cursor.reduce((s, c) => s + c.sizeBytes, 0) +
+    globalEntries.reduce((s, g) => s + g.sizeBytes, 0);
+
+  return { cursor, global: globalEntries, totalBytes };
+}