@booklib/core 2.0.0

package/hooks/hooks.json

@@ -0,0 +1,23 @@
+{
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"$HOME/.claude/booklib-suggest.js\""
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "WebFetch|WebSearch",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${BOOKLIB_ROOT}/hooks/posttooluse-capture.mjs\""
+        }
+      ]
+    }
+  ]
+}

package/hooks/posttooluse-capture.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// PostToolUse hook — suggests saving knowledge after WebFetch or WebSearch.
+// Reads tool info from stdin (JSON), writes a hint to stdout when relevant.
+
+"use strict";
+
+process.exitCode = 0;
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  let toolName = '';
+  let toolInput = {};
+
+  try {
+    const parsed = JSON.parse(input);
+    toolName = parsed.tool_name ?? parsed.toolName ?? '';
+    toolInput = parsed.tool_input ?? parsed.toolInput ?? {};
+  } catch {
+    process.exit(0);
+  }
+
+  const captureTools = ['WebFetch', 'WebSearch', 'web_fetch', 'web_search'];
+  if (!captureTools.includes(toolName)) process.exit(0);
+
+  const isSearch = ['WebSearch', 'web_search'].includes(toolName);
+  const url = toolInput.url ?? '';
+  const query = toolInput.query ?? toolInput.input ?? '';
+
+  let suggestedTitle;
+  let sourceDesc;
+
+  if (isSearch && query) {
+    suggestedTitle = query.slice(0, 60);
+    sourceDesc = `search: "${query}"`;
+  } else if (url) {
+    try {
+      const u = new URL(url);
+      const lastSegment = u.pathname.split('/').filter(Boolean).pop() ?? '';
+      const readable = lastSegment.replace(/[-_]/g, ' ').replace(/\.\w+$/, '').trim();
+      suggestedTitle = (readable ? `${readable} (${u.hostname})` : u.hostname).slice(0, 60);
+    } catch {
+      suggestedTitle = url.slice(0, 60);
+    }
+    sourceDesc = url;
+  } else {
+    process.stdout.write('\n[booklib] To save what you found: booklib note "<title>"\n');
+    process.exit(0);
+  }
+
+  // Strip shell metacharacters so the displayed command is always safe to copy-paste
+  const safeTitle = suggestedTitle.replace(/["$`\\]/g, '');
+
+  const hint = [
+    '',
+    `[booklib] Knowledge capture — ${sourceDesc}`,
+    `  Save what you found:`,
+    `    echo "paste key findings here" | booklib note "${safeTitle}"`,
+    `  Or create a research template:`,
+    `    booklib research "${safeTitle}"`,
+    '',
+  ].join('\n');
+
+  process.stdout.write(hint);
+  process.exit(0);
+});

package/hooks/suggest.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * booklib-suggest.js
+ * Claude Code UserPromptSubmit hook — suggests a relevant booklib skill
+ * when the prompt contains a review intent AND a language/domain signal.
+ *
+ * Install: copy (or symlink) this file to ~/.claude/booklib-suggest.js
+ * Hook config (hooks.json):
+ *   { "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node \"$HOME/.claude/booklib-suggest.js\"" }] }] }
+ */
+
+"use strict";
+
+process.exitCode = 0;
+
+const REVIEW_KEYWORDS = [
+  "review", "check", "improve", "refactor", "fix", "audit",
+  "analyse", "analyze", "critique", "lint",
+];
+
+const LANGUAGE_SIGNALS = {
+  python_async: [".py", "asyncio", "async def", "await "],
+  python_scraping: [".py", "python", "beautifulsoup", "scrapy", "requests.get", "web scraping"],
+  python: [".py", "python", "def ", "async def", "import ", "asyncio", "beautifulsoup", "scrapy"],
+  typescript: [".ts", ".tsx", ".js", "typescript", "interface ", "type ", "const ", "function "],
+  java: [".java", "java", "class ", "@override", "public static"],
+  kotlin: [".kt", "kotlin", "fun ", "val ", "var ", "data class"],
+  rust: [".rs", "rust", "fn ", "impl ", "struct ", "enum ", "let mut"],
+  ui_animation: [".css", ".scss", "animation", "transition", "@keyframes", "styled", "tailwind"],
+  ui: [".css", ".scss", "animation", "transition", "@keyframes", "styled", "tailwind"],
+  data: ["pipeline", "etl", "dataframe", "schema", "migration", "replication"],
+  architecture: ["microservice", "aggregate", "bounded context", "saga", "event sourcing"],
+};
+
+const SKILL_MAP = {
+  python_async: { skill: "/using-asyncio-python", reason: "Async patterns and asyncio best practices in Python" },
+  python_scraping: { skill: "/web-scraping-python", reason: "Web scraping techniques and patterns with Python" },
+  python: { skill: "/effective-python", reason: "Pythonic idioms and best practices" },
+  typescript: { skill: "/effective-typescript", reason: "TypeScript type safety and idiomatic patterns" },
+  java: { skill: "/effective-java", reason: "Effective Java patterns and API design" },
+  kotlin: { skill: "/effective-kotlin", reason: "Idiomatic Kotlin and best practices" },
+  rust: { skill: "/programming-with-rust", reason: "Rust ownership, safety, and idiomatic patterns" },
+  ui_animation: { skill: "/animation-at-work", reason: "Web animation principles and best practices" },
+  ui: { skill: "/refactoring-ui", reason: "UI design principles and visual hierarchy" },
+  data: { skill: "/data-pipelines", reason: "Data pipeline design and ETL best practices" },
+  architecture: { skill: "/skill-router", reason: "Routes to the right skill for architecture concerns" },
+};
+
+function extractPrompt(raw) {
+  if (!raw || raw.trim() === "") return "";
+  try {
+    const parsed = JSON.parse(raw);
+    // Claude Code may send { prompt: "..." } or { message: "..." }
+    if (parsed && typeof parsed === "object") {
+      return String(parsed.prompt || parsed.message || parsed.text || "");
+    }
+  } catch (_) {
+    // Not JSON — treat as raw prompt text
+  }
+  return raw;
+}
+
+function hasReviewIntent(text) {
+  const lower = text.toLowerCase();
+  return REVIEW_KEYWORDS.some((kw) => lower.includes(kw));
+}
+
+/**
+ * Returns the most specific language key that matches, or null.
+ * Order matters: more specific keys (python_async, python_scraping) are checked first.
+ */
+function detectLanguage(text) {
+  const lower = text.toLowerCase();
+
+  const orderedKeys = [
+    "python_async",
+    "python_scraping",
+    "python",
+    "typescript",
+    "java",
+    "kotlin",
+    "rust",
+    "ui_animation",
+    "ui",
+    "data",
+    "architecture",
+  ];
+
+  for (const key of orderedKeys) {
+    const signals = LANGUAGE_SIGNALS[key];
+    // For compound keys, require at least 2 signals to avoid false positives
+    // (e.g. python_async needs both a python marker AND an async marker)
+    if (key === "python_async") {
+      const hasPython = [".py", "python", "def ", "import "].some((s) => lower.includes(s));
+      const hasAsync = ["asyncio", "async def", "await "].some((s) => lower.includes(s));
+      if (hasPython && hasAsync) return key;
+      continue;
+    }
+    if (key === "python_scraping") {
+      const hasPython = [".py", "python", "def ", "import "].some((s) => lower.includes(s));
+      const hasScraping = ["beautifulsoup", "scrapy", "web scraping", "requests.get"].some((s) => lower.includes(s));
+      if (hasPython && hasScraping) return key;
+      continue;
+    }
+    if (signals.some((s) => lower.includes(s.toLowerCase()))) {
+      return key;
+    }
+  }
+
+  return null;
+}
+
+function main() {
+  let raw = "";
+  try {
+    // Read all of stdin synchronously
+    const fd = require("fs").openSync("/dev/stdin", "r");
+    const chunks = [];
+    const buf = Buffer.alloc(4096);
+    let bytesRead;
+    while ((bytesRead = require("fs").readSync(fd, buf, 0, buf.length, null)) > 0) {
+      chunks.push(buf.slice(0, bytesRead));
+    }
+    require("fs").closeSync(fd);
+    raw = Buffer.concat(chunks).toString("utf8");
+  } catch (_) {
+    // stdin unavailable or empty — exit silently
+    process.exit(0);
+  }
+
+  const prompt = extractPrompt(raw);
+  if (!prompt) process.exit(0);
+
+  if (!hasReviewIntent(prompt)) process.exit(0);
+
+  const langKey = detectLanguage(prompt);
+
+  if (!langKey) {
+    // Review intent but no specific language — suggest clean-code-reviewer
+    process.stdout.write(
+      "💡 booklib: try /clean-code-reviewer — General clean code review principles\n"
+    );
+    process.exit(0);
+  }
+
+  const match = SKILL_MAP[langKey];
+  if (!match) process.exit(0);
+
+  process.stdout.write(`💡 booklib: try ${match.skill} — ${match.reason}\n`);
+  process.exit(0);
+}
+
+main();

package/lib/agent-behaviors.js

@@ -0,0 +1,40 @@
+/**
+ * Returns the agent behaviors markdown block for a given tool target.
+ * @param {string} target - Tool target (claude, cursor, copilot, etc.)
+ * @returns {string} Markdown block
+ */
+export function renderBehaviors(target) {
+  const canRunCLI = !['cursor', 'copilot'].includes(target);
+
+  if (canRunCLI) {
+    return `### Code Review
+When reviewing code or suggesting changes, query BookLib for relevant principles:
+\`booklib search "topic relevant to the code"\`
+Cite the skill and principle in your review.
+
+### Knowledge Capture
+When the user discovers a useful pattern or asks to remember something:
+\`booklib capture --title "insight title" --type insight --tags relevant,tags\`
+
+### Search Before Answering
+When asked about best practices, patterns, or "how should I do X":
+First run: \`booklib search "the question"\`
+Use results to ground your answer in the project's active skills.
+
+### Deep Audit
+When asked to thoroughly review a file against a specific skill:
+\`booklib audit <skill-name> <file-path>\`
+
+### Health Check
+When code quality issues accumulate or skills seem irrelevant:
+\`booklib doctor\``;
+  }
+
+  return `### Code Quality Guidance
+When reviewing or generating code, apply the principles from the active skills listed below.
+Focus on the patterns and anti-patterns described in each skill's documentation.
+
+### What These Skills Cover
+Each skill represents distilled knowledge from a specific book or guide.
+When making design decisions, consider which skill's principles are most relevant.`;
+}

package/lib/agent-detector.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+/**
+ * Detects which AI coding agents are present in the project or on $PATH.
+ * Always returns at least ['claude'].
+ */
+export class AgentDetector {
+  /**
+   * @param {object} opts
+   * @param {string}  [opts.cwd]       - project root to check for config dirs/files
+   * @param {boolean} [opts.checkPath] - whether to check $PATH (default true)
+   */
+  constructor({ cwd = process.cwd(), checkPath = true, home } = {}) {
+    this.cwd = cwd;
+    this.checkPath = checkPath;
+    this.home = home ?? os.homedir();
+  }
+
+  detect() {
+    const found = new Set(['claude']); // always present
+
+    const DIR_SIGNALS = {
+      cursor:    ['.cursor'],
+      'roo-code':  ['.roo'],
+      openhands: ['.openhands'],
+      junie:     ['.junie'],
+      goose:     ['.goose'],
+      letta:     ['.letta'],
+      windsurf:  ['.windsurf'],
+      gemini:    ['.gemini'],
+    };
+
+    const FILE_SIGNALS = {
+      opencode: ['opencode.toml'],
+      copilot:  ['.github/copilot-instructions.md'],
+    };
+
+    const EXTENSION_SIGNALS = {
+      copilot: ['github.copilot', 'github.copilot-chat'],
+    };
+
+    const PATH_SIGNALS = {
+      cursor:   'cursor',
+      codex:    'codex',
+      windsurf: 'windsurf',
+      gemini:   'gemini',
+      goose:    'goose',
+      opencode: 'opencode',
+    };
+
+    for (const [agent, dirs] of Object.entries(DIR_SIGNALS)) {
+      if (dirs.some(dir => fs.existsSync(path.join(this.cwd, dir)))) {
+        found.add(agent);
+      }
+    }
+
+    for (const [agent, files] of Object.entries(FILE_SIGNALS)) {
+      if (files.some(file => fs.existsSync(path.join(this.cwd, file)))) {
+        found.add(agent);
+      }
+    }
+
+    // VS Code extension detection
+    const extDir = path.join(this.home, '.vscode', 'extensions');
+    if (fs.existsSync(extDir)) {
+      let entries;
+      try { entries = fs.readdirSync(extDir); } catch { entries = []; }
+      for (const [agent, prefixes] of Object.entries(EXTENSION_SIGNALS)) {
+        if (prefixes.some(p => entries.some(e => e.startsWith(p)))) {
+          found.add(agent);
+        }
+      }
+    }
+
+    if (this.checkPath) {
+      for (const [agent, bin] of Object.entries(PATH_SIGNALS)) {
+        if (this._inPath(bin)) found.add(agent);
+      }
+    }
+
+    return [...found];
+  }
+
+  _inPath(bin) {
+    try {
+      const cmd = process.platform === 'win32' ? `where ${bin}` : `which ${bin}`;
+      execSync(cmd, { stdio: 'ignore' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/lib/config-loader.js

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import { resolveBookLibPaths } from './paths.js';
+
+const DEFAULT_CONFIG = {
+  sources: [
+    { type: 'registry', trusted: true }
+  ],
+  discovery: {
+    ttlHours: 24
+  },
+  search: {
+    minScore: 0.3,
+    registryFallbackThreshold: 0.4
+  }
+};
+
+/**
+ * Loads booklib.config.json from project-local or global user dir.
+ * Returns DEFAULT_CONFIG if no config file is found.
+ * User config is shallow-merged with defaults so missing keys always have values.
+ */
+export function loadConfig(projectCwd) {
+  const { configPath } = resolveBookLibPaths(projectCwd);
+
+  let userConfig = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      userConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch {
+      // malformed config — fall back to defaults silently
+    }
+  }
+
+  return {
+    sources:   userConfig.sources   ?? DEFAULT_CONFIG.sources,
+    discovery: { ...DEFAULT_CONFIG.discovery,   ...(userConfig.discovery   ?? {}) },
+    search:    { ...DEFAULT_CONFIG.search,       ...(userConfig.search      ?? {}) },
+  };
+}

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 };
+  }
+}