@booklib/core 2.0.0

package/tests/engine/graph-augmented-search.test.js

@@ -0,0 +1,107 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { BookLibIndexer } from '../../lib/engine/indexer.js';
+import { BookLibSearcher } from '../../lib/engine/searcher.js';
+
+async function buildTestIndex(tmpDir) {
+  const indexDir = path.join(tmpDir, 'index');
+  const skillsDir = path.join(tmpDir, 'skills');
+
+  const skills = [
+    { name: 'effective-kotlin', text: 'Kotlin null safety val immutable data class sealed class' },
+    { name: 'design-patterns', text: 'Design patterns singleton factory observer decorator strategy' },
+    { name: 'clean-code-reviewer', text: 'clean code naming functions variables single responsibility' },
+  ];
+
+  for (const skill of skills) {
+    const dir = path.join(skillsDir, skill.name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), `---
+name: ${skill.name}
+description: Test skill
+version: "1.0"
+tags: [test]
+license: MIT
+---
+${skill.text}
+`);
+  }
+
+  const indexer = new BookLibIndexer(indexDir);
+  await indexer.indexDirectory(skillsDir, true, { quiet: true });
+  return indexDir;
+}
+
+function writeEdge(bookLibDir, edge) {
+  const graphDir = path.join(bookLibDir, 'knowledge');
+  fs.mkdirSync(graphDir, { recursive: true });
+  fs.appendFileSync(path.join(graphDir, 'graph.jsonl'), JSON.stringify(edge) + '\n', 'utf8');
+}
+
+describe('graph-augmented search', () => {
+  test('useGraph: false returns no graph-linked results', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-graph-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    writeEdge(path.dirname(indexDir), {
+      from: 'insight_abc', to: 'design-patterns', type: 'applies-to', weight: 1.0, created: '2026-03-31',
+    });
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin immutable', 5, 0, { useGraph: false });
+    assert.ok(results.every(r => r.metadata?.source !== 'graph'), 'no graph-linked results expected');
+  });
+
+  test('useGraph: true appends linked skill when edge exists', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-graph-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const bookLibDir = path.dirname(indexDir);
+    // Point to a skill that is not indexed, so it cannot appear in top-k on its own
+    writeEdge(bookLibDir, {
+      from: 'effective-kotlin', to: 'not-indexed-skill', type: 'applies-to', weight: 1.0, created: '2026-03-31',
+    });
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin immutable', 5, 0, { useGraph: true });
+    const graphResults = results.filter(r => r.metadata?.source === 'graph');
+    assert.ok(graphResults.length > 0, 'should have at least one graph-linked result');
+    assert.strictEqual(graphResults[0].metadata.name, 'not-indexed-skill');
+    assert.strictEqual(graphResults[0].metadata.edgeType, 'applies-to');
+  });
+
+  test('useGraph: true does not duplicate results already in top-k', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-graph-dedup-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const bookLibDir = path.dirname(indexDir);
+    writeEdge(bookLibDir, {
+      from: 'effective-kotlin', to: 'effective-kotlin', type: 'see-also', weight: 1.0, created: '2026-03-31',
+    });
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin immutable', 5, 0, { useGraph: true });
+    const names = results.map(r => r.metadata?.name).filter(Boolean);
+    const unique = new Set(names);
+    assert.strictEqual(unique.size, names.length, 'no duplicate skill names in results');
+  });
+
+  test('useGraph: true ignores non-discovery edge types (contradicts)', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-graph-edgetype-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const bookLibDir = path.dirname(indexDir);
+    writeEdge(bookLibDir, {
+      from: 'effective-kotlin', to: 'design-patterns', type: 'contradicts', weight: 1.0, created: '2026-03-31',
+    });
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin immutable', 5, 0, { useGraph: true });
+    const graphResults = results.filter(r => r.metadata?.source === 'graph');
+    assert.strictEqual(graphResults.length, 0, 'contradicts edge should not produce graph-linked results');
+  });
+
+  test('useGraph: true returns normal results when graph.jsonl is absent', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-graph-nofile-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin immutable', 5, 0, { useGraph: true });
+    assert.ok(results.length > 0, 'should return normal results');
+    assert.ok(results.every(r => r.metadata?.source !== 'graph'), 'no graph results when file absent');
+  });
+});

package/tests/engine/graph-injector.test.js

@@ -0,0 +1,44 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { findOwningComponents, scoreAndRankNodes } from '../../lib/engine/graph-injector.js';
+
+test('findOwningComponents matches file path against component glob', () => {
+  const components = [
+    { id: 'comp_auth', paths: ['src/auth/**'], title: 'Auth' },
+    { id: 'comp_pay',  paths: ['src/payments/**'], title: 'Payments' },
+  ];
+  const result = findOwningComponents('src/auth/middleware.js', components);
+  assert.equal(result.length, 1);
+  assert.equal(result[0].id, 'comp_auth');
+});
+
+test('findOwningComponents returns empty array when no match', () => {
+  const components = [
+    { id: 'comp_auth', paths: ['src/auth/**'], title: 'Auth' },
+  ];
+  const result = findOwningComponents('src/payments/stripe.js', components);
+  assert.equal(result.length, 0);
+});
+
+test('findOwningComponents matches multiple components', () => {
+  const components = [
+    { id: 'comp_auth', paths: ['src/auth/**', '**/middleware*'], title: 'Auth' },
+    { id: 'comp_core', paths: ['src/**'], title: 'Core' },
+  ];
+  const result = findOwningComponents('src/auth/util.js', components);
+  const ids = result.map(c => c.id);
+  assert.ok(ids.includes('comp_auth'));
+  assert.ok(ids.includes('comp_core'));
+});
+
+test('scoreAndRankNodes deduplicates by id keeping highest score', () => {
+  const nodes = [
+    { id: 'a', score: 0.9, text: 'foo', hop: 0 },
+    { id: 'a', score: 0.8, text: 'foo', hop: 1 },
+    { id: 'b', score: 0.7, text: 'bar', hop: 0 },
+  ];
+  const ranked = scoreAndRankNodes(nodes);
+  assert.equal(ranked.filter(n => n.id === 'a').length, 1);
+  assert.equal(ranked[0].id, 'a');
+  assert.equal(ranked[0].score, 0.9);
+});

package/tests/engine/graph.test.js

@@ -0,0 +1,216 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path, { join } from 'node:path';
+import {
+  resolveKnowledgePaths,
+  generateNodeId,
+  serializeNode,
+  saveNode,
+  loadNode,
+  parseNodeFrontmatter,
+  listNodes,
+  appendEdge,
+  loadEdges,
+  traverseEdges,
+  resolveNodeRef,
+} from '../../lib/engine/graph.js';
+
+function tmpDir() {
+  return mkdtempSync(join(tmpdir(), 'booklib-graph-test-'));
+}
+
+test('generateNodeId returns prefixed hex string', () => {
+  const id = generateNodeId('node');
+  assert.match(id, /^node_[a-f0-9]{8}$/);
+});
+
+test('generateNodeId with component prefix', () => {
+  const id = generateNodeId('comp');
+  assert.match(id, /^comp_[a-f0-9]{8}$/);
+});
+
+test('serializeNode produces valid frontmatter markdown', () => {
+  const md = serializeNode({
+    id: 'node_abc',
+    type: 'research',
+    title: 'JWT patterns',
+    content: 'Some findings.',
+    tags: ['auth', 'jwt'],
+    sources: ['https://example.com'],
+    confidence: 'high',
+  });
+  assert.ok(md.startsWith('---\n'));
+  assert.ok(md.includes('node_abc'));
+  assert.ok(md.includes('research'));
+  assert.ok(md.includes('JWT patterns'));
+  assert.ok(md.includes('Some findings.'));
+});
+
+test('saveNode writes file and loadNode reads it back', () => {
+  const dir = tmpDir();
+  const nodesDir = join(dir, 'nodes');
+  const id = 'node_test01';
+  const content = serializeNode({ id, type: 'note', title: 'Test', content: 'hello' });
+  const filePath = saveNode(content, id, { nodesDir });
+  assert.ok(existsSync(filePath));
+  const loaded = loadNode(id, { nodesDir });
+  assert.equal(loaded, content);
+  rmSync(dir, { recursive: true });
+});
+
+test('loadNode returns null for missing node', () => {
+  const dir = tmpDir();
+  const result = loadNode('nonexistent', { nodesDir: join(dir, 'nodes') });
+  assert.equal(result, null);
+  rmSync(dir, { recursive: true });
+});
+
+test('parseNodeFrontmatter extracts fields and body', () => {
+  const md = `---\nid: node_x\ntype: research\ntitle: JWT\ntags:\n  - auth\n---\n\nContent here.`;
+  const parsed = parseNodeFrontmatter(md);
+  assert.equal(parsed.id, 'node_x');
+  assert.equal(parsed.type, 'research');
+  assert.equal(parsed.title, 'JWT');
+  assert.deepEqual(parsed.tags, ['auth']);
+  assert.equal(parsed.body, 'Content here.');
+});
+
+test('listNodes returns all node IDs', () => {
+  const dir = tmpDir();
+  const nodesDir = join(dir, 'nodes');
+  saveNode(serializeNode({ id: 'node_a1b2c3d4', type: 'note', title: 'A', content: '' }), 'node_a1b2c3d4', { nodesDir });
+  saveNode(serializeNode({ id: 'node_b2c3d4e5', type: 'note', title: 'B', content: '' }), 'node_b2c3d4e5', { nodesDir });
+  const ids = listNodes({ nodesDir });
+  assert.ok(ids.includes('node_a1b2c3d4'));
+  assert.ok(ids.includes('node_b2c3d4e5'));
+  rmSync(dir, { recursive: true });
+});
+
+test('appendEdge writes edge to graph.jsonl', () => {
+  const dir = tmpDir();
+  const graphFile = join(dir, 'graph.jsonl');
+  const edge = { from: 'node_a', to: 'node_b', type: 'implements', weight: 1.0 };
+  appendEdge(edge, { graphFile });
+  const lines = readFileSync(graphFile, 'utf8').trim().split('\n');
+  assert.equal(lines.length, 1);
+  assert.deepEqual(JSON.parse(lines[0]), edge);
+  rmSync(dir, { recursive: true });
+});
+
+test('loadEdges returns all edges from graph.jsonl', () => {
+  const dir = tmpDir();
+  const graphFile = join(dir, 'graph.jsonl');
+  appendEdge({ from: 'a', to: 'b', type: 'see-also', weight: 1.0 }, { graphFile });
+  appendEdge({ from: 'b', to: 'c', type: 'extends', weight: 0.8 }, { graphFile });
+  const edges = loadEdges({ graphFile });
+  assert.equal(edges.length, 2);
+  assert.equal(edges[0].from, 'a');
+  assert.equal(edges[1].from, 'b');
+  rmSync(dir, { recursive: true });
+});
+
+test('loadEdges returns empty array when file missing', () => {
+  const dir = tmpDir();
+  const edges = loadEdges({ graphFile: join(dir, 'missing.jsonl') });
+  assert.deepEqual(edges, []);
+  rmSync(dir, { recursive: true });
+});
+
+test('traverseEdges finds 1-hop neighbours', () => {
+  const edges = [
+    { from: 'a', to: 'b', type: 'implements', weight: 1.0 },
+    { from: 'a', to: 'c', type: 'see-also', weight: 0.9 },
+    { from: 'd', to: 'e', type: 'extends', weight: 0.8 },
+  ];
+  const result = traverseEdges('a', edges, 1);
+  const ids = result.map(r => r.id);
+  assert.ok(ids.includes('b'));
+  assert.ok(ids.includes('c'));
+  assert.ok(!ids.includes('d'));
+});
+
+test('traverseEdges does not revisit nodes (no infinite cycles)', () => {
+  const edges = [
+    { from: 'a', to: 'b', type: 'see-also', weight: 1.0 },
+    { from: 'b', to: 'a', type: 'see-also', weight: 1.0 },
+  ];
+  const result = traverseEdges('a', edges, 3);
+  const ids = result.map(r => r.id);
+  assert.ok(!ids.includes('a'));
+});
+
+test('traverseEdges follows edges in both directions', () => {
+  const edges = [
+    { from: 'x', to: 'target', type: 'applies-to', weight: 1.0 },
+  ];
+  const result = traverseEdges('target', edges, 1);
+  const ids = result.map(r => r.id);
+  assert.ok(ids.includes('x'));
+});
+
+test('serializeNode preserves body content passed via stdin path', async (t) => {
+  const result = serializeNode({ id: 'node_test01', type: 'note', title: 'My note', content: 'body text here' });
+  assert.ok(result.includes('body text here'), 'body text is in the serialized node');
+  assert.ok(result.includes('title: My note'), 'title is in frontmatter');
+});
+
+test('resolveNodeRef — returns exact ID unchanged', (t) => {
+  const tmpNodeDir = mkdtempSync(path.join(tmpdir(), 'ref-test-'));
+  const opts = { nodesDir: tmpNodeDir };
+  const id = 'node_aaaabbbb';
+  saveNode(serializeNode({ id, type: 'note', title: 'Auth decisions' }), id, opts);
+  const result = resolveNodeRef(id, opts);
+  assert.strictEqual(result, id);
+  rmSync(tmpNodeDir, { recursive: true });
+});
+
+test('resolveNodeRef — finds node by partial title', (t) => {
+  const tmpNodeDir = mkdtempSync(path.join(tmpdir(), 'ref-test2-'));
+  const opts = { nodesDir: tmpNodeDir };
+  const id = 'node_ccccdddd';
+  saveNode(serializeNode({ id, type: 'note', title: 'JWT refresh patterns' }), id, opts);
+  const result = resolveNodeRef('jwt refresh', opts);
+  assert.strictEqual(result, id);
+  rmSync(tmpNodeDir, { recursive: true });
+});
+
+test('resolveNodeRef — throws when no match found', async (t) => {
+  const { resolveNodeRef } = await import('../../lib/engine/graph.js');
+  const tmpNodeDir = mkdtempSync(path.join(tmpdir(), 'ref-err-test-'));
+  assert.throws(
+    () => resolveNodeRef('nonexistent query', { nodesDir: tmpNodeDir }),
+    /No node found/
+  );
+  rmSync(tmpNodeDir, { recursive: true });
+});
+
+test('resolveNodeRef — throws with match list when ambiguous', async (t) => {
+  const { resolveNodeRef, saveNode, serializeNode } = await import('../../lib/engine/graph.js');
+  const tmpNodeDir = mkdtempSync(path.join(tmpdir(), 'ref-ambig-test-'));
+  const opts = { nodesDir: tmpNodeDir };
+  saveNode(serializeNode({ id: 'node_auth01', type: 'note', title: 'Auth session handling' }), 'node_auth01', opts);
+  saveNode(serializeNode({ id: 'node_auth02', type: 'note', title: 'Auth token refresh' }), 'node_auth02', opts);
+  assert.throws(
+    () => resolveNodeRef('auth', opts),
+    /Multiple nodes match/
+  );
+  rmSync(tmpNodeDir, { recursive: true });
+});
+
+test('research success message does not tell user to manually re-run index', async (t) => {
+  const { readFileSync } = await import('node:fs');
+  const src = readFileSync(new URL('../../bin/booklib.js', import.meta.url), 'utf8');
+  const staleMessage = 'run booklib index to update the search index';
+  assert.ok(!src.includes(staleMessage), 'stale re-index message removed from research case');
+});
+
+test('bin/booklib.js contains component hint for --file with no graph context', async (t) => {
+  const { readFileSync } = await import('node:fs');
+  const src = readFileSync(new URL('../../bin/booklib.js', import.meta.url), 'utf8');
+  assert.ok(
+    src.includes('booklib component add'),
+    'bin/booklib.js contains component hint for --file with no graph context'
+  );
+});

package/tests/engine/hybrid-searcher.test.js

@@ -0,0 +1,74 @@
+// tests/engine/hybrid-searcher.test.js
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { BookLibIndexer } from '../../lib/engine/indexer.js';
+import { BookLibSearcher } from '../../lib/engine/searcher.js';
+
+async function buildTestIndex(tmpDir) {
+  const indexDir = path.join(tmpDir, 'index');
+  const skillsDir = path.join(tmpDir, 'skills');
+
+  const skills = [
+    { name: 'effective-kotlin', text: 'Kotlin null safety val immutable data class sealed class' },
+    { name: 'effective-typescript', text: 'TypeScript strict null checks undefined type narrowing' },
+    { name: 'clean-code-reviewer', text: 'clean code naming functions variables single responsibility' },
+    { name: 'effective-java', text: 'Java generics builder pattern equals hashCode immutable' },
+  ];
+
+  for (const skill of skills) {
+    const dir = path.join(skillsDir, skill.name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'SKILL.md'), `---
+name: ${skill.name}
+description: Test skill
+version: "1.0"
+tags: [test]
+license: MIT
+---
+${skill.text}
+`);
+  }
+
+  const indexer = new BookLibIndexer(indexDir);
+  await indexer.indexDirectory(skillsDir, true, { quiet: true });
+  return indexDir;
+}
+
+describe('BookLibSearcher hybrid pipeline', () => {
+  it('returns results for a query with bm25.json present', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-hybrid-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const searcher = new BookLibSearcher(indexDir);
+
+    const results = await searcher.search('kotlin null safety', 3, 0);
+    assert.ok(results.length > 0, 'should return results');
+    assert.ok(results[0].score !== undefined);
+    assert.ok(results[0].text !== undefined);
+    assert.ok(results[0].metadata !== undefined);
+  });
+
+  it('falls back to vector search when bm25.json is missing', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-noBm25-'));
+    const indexDir = await buildTestIndex(tmpDir);
+
+    const bm25Path = path.join(path.dirname(indexDir), 'bm25.json');
+    if (fs.existsSync(bm25Path)) fs.unlinkSync(bm25Path);
+
+    const searcher = new BookLibSearcher(indexDir);
+    const results = await searcher.search('kotlin null safety', 3, 0);
+    assert.ok(results.length > 0, 'should fall back to vector search');
+  });
+
+  it('top result is relevant to query', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-relevance-'));
+    const indexDir = await buildTestIndex(tmpDir);
+    const searcher = new BookLibSearcher(indexDir);
+
+    const results = await searcher.search('kotlin immutable data', 5, 0);
+    assert.ok(results.length > 0);
+    assert.strictEqual(results[0].metadata.name, 'effective-kotlin');
+  });
+});

package/tests/engine/indexer-bm25.test.js

@@ -0,0 +1,37 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { BookLibIndexer } from '../../lib/engine/indexer.js';
+import { BM25Index } from '../../lib/engine/bm25-index.js';
+
+describe('BookLibIndexer BM25 co-build', () => {
+  it('creates bm25.json alongside vectra index after indexDirectory', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'booklib-indexer-'));
+    const indexDir = path.join(tmpDir, 'index');
+    const skillsDir = path.join(tmpDir, 'skills');
+    const testSkillDir = path.join(skillsDir, 'test-skill');
+    fs.mkdirSync(testSkillDir, { recursive: true });
+    fs.writeFileSync(path.join(testSkillDir, 'SKILL.md'), `---
+name: test-skill
+description: A test skill about kotlin null safety
+version: "1.0"
+tags: [kotlin]
+license: MIT
+---
+Kotlin null safety prevents null pointer exceptions.
+`);
+
+    const indexer = new BookLibIndexer(indexDir);
+    await indexer.indexDirectory(skillsDir, true, { quiet: true });
+
+    const bm25Path = path.join(path.dirname(indexDir), 'bm25.json');
+    assert.ok(fs.existsSync(bm25Path), 'bm25.json should exist after indexDirectory');
+
+    const idx = BM25Index.load(bm25Path);
+    const results = idx.search('kotlin null', 3);
+    assert.ok(results.length > 0, 'loaded BM25 index should return results');
+    assert.ok(results[0].score > 0);
+  });
+});

package/tests/engine/mcp-tools.test.js

@@ -0,0 +1,73 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+// ── get_context ───────────────────────────────────────────────────────────────
+
+test('ContextBuilder.build returns a non-empty string for a valid task', async (t) => {
+  const { ContextBuilder } = await import('../../lib/context-builder.js');
+  const builder = new ContextBuilder();
+  const result = await builder.build('implement null safety in Kotlin');
+  assert.ok(typeof result === 'string', 'result is a string');
+  assert.ok(result.length > 50, 'result has meaningful content');
+});
+
+test('ContextBuilder.buildWithGraph returns skill context even with no file', async (t) => {
+  const { ContextBuilder } = await import('../../lib/context-builder.js');
+  const builder = new ContextBuilder();
+  const result = await builder.buildWithGraph('implement null safety in Kotlin', null);
+  assert.ok(typeof result === 'string', 'result is a string');
+  assert.ok(result.length > 50, 'result has meaningful content');
+});
+
+// ── create_note ───────────────────────────────────────────────────────────────
+
+test('serializeNode + saveNode creates a readable note node', async (t) => {
+  const { serializeNode, saveNode, loadNode, parseNodeFrontmatter, generateNodeId } = await import('../../lib/engine/graph.js');
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'mcp-note-'));
+  const id = generateNodeId('node');
+  const content = serializeNode({ id, type: 'note', title: 'MCP test note', content: 'body text' });
+  const filePath = saveNode(content, id, { nodesDir: tmpDir });
+  const raw = loadNode(id, { nodesDir: tmpDir });
+  const parsed = parseNodeFrontmatter(raw);
+  assert.strictEqual(parsed.title, 'MCP test note');
+  assert.ok(parsed.body.includes('body text'));
+});
+
+// ── search_knowledge ─────────────────────────────────────────────────────────
+
+test('BookLibSearcher.search returns an array (empty or populated)', async (t) => {
+  const { BookLibSearcher } = await import('../../lib/engine/searcher.js');
+  const searcher = new BookLibSearcher();
+  try {
+    const results = await searcher.search('null safety', 3);
+    assert.ok(Array.isArray(results), 'results is an array');
+  } catch (err) {
+    // Index not built in test env — acceptable
+    assert.ok(err.message.includes('booklib index'), 'informative error message');
+  }
+});
+
+// ── list_nodes + link_nodes ───────────────────────────────────────────────────
+
+test('listNodes returns array of IDs from a temp dir', async (t) => {
+  const { listNodes, saveNode, serializeNode, generateNodeId } = await import('../../lib/engine/graph.js');
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'mcp-list-'));
+  const id = generateNodeId('node');
+  saveNode(serializeNode({ id, type: 'note', title: 'List test' }), id, { nodesDir: tmpDir });
+  const ids = listNodes({ nodesDir: tmpDir });
+  assert.ok(ids.includes(id), 'saved node appears in list');
+});
+
+test('resolveNodeRef resolves partial title to node ID in temp dir', async (t) => {
+  const { saveNode, serializeNode, generateNodeId, resolveNodeRef } = await import('../../lib/engine/graph.js');
+  const tmpDir = mkdtempSync(path.join(tmpdir(), 'mcp-link-'));
+  const idA = generateNodeId('node');
+  const idB = generateNodeId('node');
+  saveNode(serializeNode({ id: idA, type: 'note', title: 'Source note' }), idA, { nodesDir: tmpDir });
+  saveNode(serializeNode({ id: idB, type: 'note', title: 'Auth component' }), idB, { nodesDir: tmpDir });
+  const resolvedA = resolveNodeRef('Source note', { nodesDir: tmpDir });
+  assert.strictEqual(resolvedA, idA);
+});

package/tests/engine/project-initializer-mcp.test.js

@@ -0,0 +1,99 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import fs from 'node:fs';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { ProjectInitializer } from '../../lib/project-initializer.js';
+
+function makeInit(dir) {
+  return new ProjectInitializer({ projectCwd: dir });
+}
+
+// ── Per-tool output ───────────────────────────────────────────────────────────
+
+test('generateMcpConfigs writes .claude/settings.json for claude', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['claude'] });
+  const settings = JSON.parse(fs.readFileSync(path.join(dir, '.claude', 'settings.json'), 'utf8'));
+  assert.deepStrictEqual(settings.mcpServers.booklib, { command: 'booklib-mcp', args: [] });
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs writes .cursor/mcp.json for cursor', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['cursor'] });
+  const mcp = JSON.parse(fs.readFileSync(path.join(dir, '.cursor', 'mcp.json'), 'utf8'));
+  assert.deepStrictEqual(mcp.mcpServers.booklib, { command: 'booklib-mcp', args: [] });
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs writes .gemini/settings.json for gemini', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['gemini'] });
+  const settings = JSON.parse(fs.readFileSync(path.join(dir, '.gemini', 'settings.json'), 'utf8'));
+  assert.deepStrictEqual(settings.mcpServers.booklib, { command: 'booklib-mcp', args: [] });
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs writes .codex/config.toml for codex', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['codex'] });
+  const toml = fs.readFileSync(path.join(dir, '.codex', 'config.toml'), 'utf8');
+  assert.ok(toml.includes('[mcp_servers.booklib]'), 'has section header');
+  assert.ok(toml.includes('command = "booklib-mcp"'), 'has command');
+  assert.ok(toml.includes('args = []'), 'has args');
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs writes .zed/settings.json for zed', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['zed'] });
+  const settings = JSON.parse(fs.readFileSync(path.join(dir, '.zed', 'settings.json'), 'utf8'));
+  assert.deepStrictEqual(
+    settings['context_servers']['booklib-mcp'],
+    { command: { path: 'booklib-mcp', args: [] } }
+  );
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs writes .continue/mcpServers/booklib.yaml for continue', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  await makeInit(dir).generateMcpConfigs({ tools: ['continue'] });
+  const yaml = fs.readFileSync(path.join(dir, '.continue', 'mcpServers', 'booklib.yaml'), 'utf8');
+  assert.ok(yaml.includes('name: booklib'), 'has name');
+  assert.ok(yaml.includes('command: booklib-mcp'), 'has command');
+  assert.ok(yaml.includes('args: []'), 'has args');
+  fs.rmSync(dir, { recursive: true });
+});
+
+// ── Merge behaviour ───────────────────────────────────────────────────────────
+
+test('generateMcpConfigs merges into existing JSON without overwriting other servers', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  const claudeDir = path.join(dir, '.claude');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  const existing = { mcpServers: { 'other-server': { command: 'other', args: [] } } };
+  fs.writeFileSync(path.join(claudeDir, 'settings.json'), JSON.stringify(existing));
+
+  await makeInit(dir).generateMcpConfigs({ tools: ['claude'] });
+
+  const settings = JSON.parse(fs.readFileSync(path.join(claudeDir, 'settings.json'), 'utf8'));
+  assert.deepStrictEqual(settings.mcpServers['other-server'], { command: 'other', args: [] });
+  assert.deepStrictEqual(settings.mcpServers.booklib, { command: 'booklib-mcp', args: [] });
+  fs.rmSync(dir, { recursive: true });
+});
+
+test('generateMcpConfigs appends booklib section into existing TOML without altering other content', async () => {
+  const dir = mkdtempSync(path.join(tmpdir(), 'bl-mcp-'));
+  const codexDir = path.join(dir, '.codex');
+  fs.mkdirSync(codexDir, { recursive: true });
+  fs.writeFileSync(path.join(codexDir, 'config.toml'), '[other_service]\nkey = "value"\n');
+
+  await makeInit(dir).generateMcpConfigs({ tools: ['codex'] });
+
+  const toml = fs.readFileSync(path.join(codexDir, 'config.toml'), 'utf8');
+  assert.ok(toml.includes('[other_service]'), 'preserves existing content');
+  assert.ok(toml.includes('[mcp_servers.booklib]'), 'appends booklib section');
+  fs.rmSync(dir, { recursive: true });
+});