@mseep/core 3.0.0

package/hooks/hooks.json

@@ -0,0 +1,52 @@
+{
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"$HOME/.claude/booklib-suggest.js\""
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${BOOKLIB_ROOT}/hooks/pretooluse-inject.mjs\""
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "WebFetch|WebSearch",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${BOOKLIB_ROOT}/hooks/posttooluse-capture.mjs\""
+        }
+      ]
+    },
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${BOOKLIB_ROOT}/hooks/posttooluse-contradict.mjs\""
+        }
+      ]
+    },
+    {
+      "matcher": "Edit|Write",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node \"${BOOKLIB_ROOT}/hooks/posttooluse-imports.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/posttooluse-contradict.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// PostToolUse hook — checks written code against context map constraints
+// after Edit/Write tool use. Outputs a hint when contradictions are found.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ContextMapMatcher } from '../lib/engine/context-map.js';
+
+/**
+ * Format contradictions into a warning hint.
+ * @param {Array<{id: string, constraint: string, example: string|null, source: string|null}>} contradictions
+ * @returns {string}
+ */
+export function formatContradiction(contradictions) {
+  if (!contradictions?.length) return '';
+
+  const lines = ['[BookLib] Contradiction detected:'];
+
+  for (const v of contradictions) {
+    lines.push(`  ${v.constraint}`);
+    if (v.example) {
+      lines.push(`    Fix: ${v.example}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Only run stdin reading when executed as a script, not when imported for testing
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+  process.exitCode = 0;
+
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const parsed = JSON.parse(input);
+      const toolName = parsed.tool_name ?? parsed.toolName ?? '';
+      const toolInput = parsed.tool_input ?? parsed.toolInput ?? {};
+
+      const writeTools = ['Write', 'Edit', 'write', 'edit'];
+      if (!writeTools.includes(toolName)) process.exit(0);
+
+      const filePath = toolInput.file_path ?? toolInput.filePath ?? '';
+      if (!filePath) process.exit(0);
+
+      const mapPath = join(process.cwd(), '.booklib', 'context-map.json');
+      const raw = readFileSync(mapPath, 'utf8');
+      const map = JSON.parse(raw);
+      if (!map?.items?.length) process.exit(0);
+
+      const newCode = toolInput.new_string ?? toolInput.content ?? '';
+      if (!newCode) process.exit(0);
+
+      const importRe = /from\s+['"]([^'"]+)['"]/g;
+      const imports = [];
+      let match;
+      while ((match = importRe.exec(newCode)) !== null) {
+        imports.push(match[1]);
+      }
+
+      const matcher = new ContextMapMatcher(map.items);
+      const matched = matcher.match(filePath, newCode, imports);
+      const contradictions = matcher.checkContradictions(newCode, matched);
+
+      if (contradictions.length > 0) {
+        process.stdout.write(formatContradiction(contradictions));
+      }
+    } catch {
+      // Best effort — don't break the hook chain
+    }
+
+    process.exit(0);
+  });
+}

package/hooks/posttooluse-imports.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// PostToolUse hook — checks imports after Write/Edit tool use.
+// Reads tool info from stdin (JSON), runs ImportChecker on written files,
+// outputs a hint when unknown imports are found.
+
+import path from 'node:path';
+import { detectLanguage } from '../lib/engine/import-parser.js';
+
+process.exitCode = 0;
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', async () => {
+  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 writeTools = ['Write', 'Edit', 'write', 'edit'];
+  if (!writeTools.includes(toolName)) process.exit(0);
+
+  const filePath = toolInput.file_path ?? toolInput.filePath ?? '';
+  if (!filePath) process.exit(0);
+
+  // Use the parser's language detection instead of duplicating extension list
+  if (!detectLanguage(filePath)) process.exit(0);
+
+  try {
+    const { ImportChecker } = await import('../lib/engine/import-checker.js');
+    const checker = new ImportChecker();
+    const result = await checker.checkFile(filePath);
+
+    if (result.unknown.length === 0) process.exit(0);
+
+    const lines = [
+      '',
+      `[booklib] ${result.unknown.length} unknown import(s) in ${path.basename(filePath)}:`,
+    ];
+
+    for (const imp of result.unknown.slice(0, 3)) {
+      lines.push(`  ${imp.module} — not in BookLib index`);
+    }
+    if (result.unknown.length > 3) {
+      lines.push(`  ... and ${result.unknown.length - 3} more`);
+    }
+
+    lines.push(`  Run: booklib check-imports ${filePath}`);
+    lines.push('');
+    process.stdout.write(lines.join('\n'));
+  } catch {
+    // Best effort — don't break the hook chain
+  }
+
+  // Future integration point: decision contradiction checking.
+  // DecisionChecker requires a BookLibSearcher with the embedding model loaded,
+  // which is too heavy for a PostToolUse hook. Will activate when hooks can
+  // access a persistent searcher instance (e.g., via MCP or shared process).
+
+  process.exit(0);
+});

package/hooks/pretooluse-inject.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// PreToolUse hook — injects relevant context from the BookLib context map
+// before Edit/Write tool use. Reads tool info from stdin (JSON), matches
+// file + code against context map, outputs injection hints.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ContextMapMatcher } from '../lib/engine/context-map.js';
+
+/**
+ * Format matched context map items into an injection hint.
+ * @param {Array<{injection: {correction: string|null, constraint: string|null, example: string|null}, source?: string|null}>} items
+ * @returns {string}
+ */
+export function formatInjection(items) {
+  if (!items?.length) return '';
+
+  const lines = ['[BookLib] Context for this edit:'];
+
+  for (const item of items) {
+    const { correction, constraint, example } = item.injection ?? {};
+
+    if (correction) {
+      lines.push(`  ${correction}`);
+    } else if (constraint) {
+      const team = item.source ? `${item.source}: ` : '';
+      lines.push(`  ${team}${constraint}`);
+    }
+
+    if (example) {
+      lines.push(`    ${example}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Only run stdin reading when executed as a script, not when imported for testing
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'))) {
+  process.exitCode = 0;
+
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', async () => {
+    try {
+      const parsed = JSON.parse(input);
+      const toolName = parsed.tool_name ?? parsed.toolName ?? '';
+      const toolInput = parsed.tool_input ?? parsed.toolInput ?? {};
+
+      const writeTools = ['Write', 'Edit', 'write', 'edit'];
+      if (!writeTools.includes(toolName)) process.exit(0);
+
+      const filePath = toolInput.file_path ?? toolInput.filePath ?? '';
+      if (!filePath) process.exit(0);
+
+      const mapPath = join(process.cwd(), '.booklib', 'context-map.json');
+      const raw = readFileSync(mapPath, 'utf8');
+      const map = JSON.parse(raw);
+      if (!map?.items?.length) process.exit(0);
+
+      const fileContent = toolInput.old_string ?? toolInput.content ?? '';
+      const importRe = /from\s+['"]([^'"]+)['"]/g;
+      const imports = [];
+      let match;
+      while ((match = importRe.exec(fileContent)) !== null) {
+        imports.push(match[1]);
+      }
+
+      const matcher = new ContextMapMatcher(map.items);
+      const matched = matcher.match(filePath, fileContent, imports);
+
+      if (matched.length > 0) {
+        process.stdout.write(formatInjection(matched));
+      }
+    } catch {
+      // Best effort — don't break the hook chain
+    }
+
+    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-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      ?? {}) },
+  };
+}