@aprimediet/codewalker 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aprimediet/codewalker",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Queryable, token-economical project & code index for the pi coding agent.",
   "keywords": ["pi-package"],

package/src/db.test.ts

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import Database from 'better-sqlite3';
-import { openDb, bootstrapDb, upsertSymbol, searchSymbols, getMeta, setMeta, deleteFileSymbols } from './db.ts';
+import { openDb, bootstrapDb, upsertSymbol, searchSymbols, getMeta, setMeta, deleteFileSymbols, upsertLibrary, upsertLibSymbol, deleteLibrary, searchLibSymbols } from './db.ts';
 
 describe('db.ts', () => {
   let tmpDir: string;
@@ -51,7 +51,41 @@ describe('db.ts', () => {
       const db = new Database(dbPath);
       bootstrapDb(db);
       const version = db.pragma('user_version', { simple: true }) as number;
-      expect(version).toBe(1);
+      expect(version).toBe(2);
+      db.close();
+    });
+
+    it('creates libraries, lib_symbols, and lib_symbols_fts tables', () => {
+      const db = openDb(dbPath);
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      const tableNames = tables.map(t => t.name);
+      expect(tableNames).toContain('libraries');
+      expect(tableNames).toContain('lib_symbols');
+
+      const ftsTables = db.prepare("SELECT name FROM sqlite_master WHERE name='lib_symbols_fts'").all() as { name: string }[];
+      expect(ftsTables.length).toBe(1);
+      db.close();
+    });
+
+    it('does not destroy existing symbols tables (additive upgrade)', () => {
+      // Bootstrap v1 DB first, then re-bootstrap (simulate upgrade)
+      const db = new Database(dbPath);
+      bootstrapDb(db);
+      upsertSymbol(db, {
+        name: 'keep', kind: 'function', file_path: 'src/a.ts',
+        line_start: 1, line_end: 1, signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      // Call bootstrapDb again (simulates upgrade to v2 adds lib tables)
+      bootstrapDb(db);
+
+      // Symbol still there
+      const symbols = searchSymbols(db, 'keep', undefined, 10);
+      expect(symbols).toHaveLength(1);
+
+      // Lib tables exist
+      const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+      expect(tables.map(t => t.name)).toContain('lib_symbols');
       db.close();
     });
   });
@@ -173,6 +207,118 @@ describe('db.ts', () => {
     });
   });
 
+  describe('library CRUD', () => {
+    it('upsertLibrary inserts or updates a library record', () => {
+      const db = openDb(dbPath);
+      upsertLibrary(db, { name: 'hono', version: '4.6.3', source: 'node_modules', dts_path: '/a.d.ts', readme: 'Hono web framework' });
+
+      const row = db.prepare("SELECT * FROM libraries WHERE name = ?").get('hono') as any;
+      expect(row).not.toBeUndefined();
+      expect(row.version).toBe('4.6.3');
+      expect(row.source).toBe('node_modules');
+      db.close();
+    });
+
+    it('upsertLibSymbol inserts a lib symbol and it is FTS-searchable', () => {
+      const db = openDb(dbPath);
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'export declare function createMiddleware(...)',
+        doc: 'Define a typed middleware handler.', summary: 'Define a typed middleware handler.',
+        card_path: '/cards/hono/createMiddleware.md',
+      });
+
+      const results = searchLibSymbols(db, 'createMiddleware', undefined, 10);
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('createMiddleware');
+      expect(results[0]!.lib).toBe('hono');
+      expect(results[0]!.version).toBe('4.6.3');
+      expect(results[0]!.source).toBe('lib');
+
+      db.close();
+    });
+
+    it('searchLibSymbols empty query returns all symbols ordered by name', () => {
+      const db = openDb(dbPath);
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'zMiddleware',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'aRouter',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      const results = searchLibSymbols(db, '', undefined, 10);
+      expect(results).toHaveLength(2);
+      expect(results[0]!.name).toBe('aRouter');
+      expect(results[1]!.name).toBe('zMiddleware');
+      db.close();
+    });
+
+    it('deleteLibrary removes symbols and FTS rows for all versions of a lib', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.5.0', name: 'oldFunc',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      deleteLibrary(db, 'hono');
+
+      const results = searchLibSymbols(db, '', undefined, 10);
+      expect(results).toHaveLength(0);
+
+      const libRow = db.prepare("SELECT * FROM libraries WHERE name = ?").get('hono') as any;
+      expect(libRow).toBeUndefined();
+
+      db.close();
+    });
+
+    it('re-inserting same (lib, name) does not create duplicates', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'v1', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'createMiddleware',
+        kind: 'function', signature: 'v2', doc: '', summary: '', card_path: '',
+      });
+
+      const results = searchLibSymbols(db, 'createMiddleware', undefined, 10);
+      expect(results).toHaveLength(1);
+      // Latest signature
+      expect(results[0]!.signature).toBe('v2');
+
+      db.close();
+    });
+
+    it('kind filter narrows lib symbol results', () => {
+      const db = openDb(dbPath);
+
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'myFunc',
+        kind: 'function', signature: '', doc: '', summary: '', card_path: '',
+      });
+      upsertLibSymbol(db, {
+        lib: 'hono', version: '4.6.3', name: 'MyType',
+        kind: 'type', signature: '', doc: '', summary: '', card_path: '',
+      });
+
+      const funcs = searchLibSymbols(db, '', 'function', 10);
+      expect(funcs).toHaveLength(1);
+      expect(funcs[0]!.name).toBe('myFunc');
+
+      db.close();
+    });
+  });
+
   describe('meta', () => {
     it('setMeta and getMeta round-trip values', () => {
       const db = openDb(dbPath);

package/src/db.ts

@@ -12,6 +12,7 @@
  */
 
 import Database, { type Database as DatabaseType } from "better-sqlite3";
+import type { LibSymbol } from "./types.ts";
 
 export { Database };
 export type { DatabaseType };
@@ -27,7 +28,7 @@ export function openDb(dbPath: string): DatabaseType {
 /** Bootstrap DDL — idempotent (all CREATE use IF NOT EXISTS). */
 export function bootstrapDb(db: DatabaseType): void {
   db.exec(`
-    PRAGMA user_version = 1;
+    PRAGMA user_version = 2;
 
     CREATE TABLE IF NOT EXISTS files (
       path        TEXT PRIMARY KEY,
@@ -55,7 +56,70 @@ export function bootstrapDb(db: DatabaseType): void {
       tokenize='unicode61 remove_diacritics 2'
     );
 
+    CREATE TABLE IF NOT EXISTS libraries (
+      name        TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      source      TEXT,
+      dts_path    TEXT,
+      readme      TEXT,
+      indexed_at  TEXT,
+      PRIMARY KEY (name, version)
+    );
+
+    CREATE TABLE IF NOT EXISTS lib_symbols (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      lib         TEXT NOT NULL,
+      version     TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      kind        TEXT,
+      signature   TEXT,
+      doc         TEXT,
+      summary     TEXT,
+      card_path   TEXT
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS lib_symbols_fts USING fts5(
+      name, signature, doc, summary,
+      content='lib_symbols', content_rowid='id',
+      tokenize='unicode61 remove_diacritics 2'
+    );
+
     CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+
+    -- Keep the external-content FTS indexes in sync via triggers (the SQLite-documented
+    -- pattern). Code must do plain INSERT/UPDATE/DELETE on the base tables and NEVER touch
+    -- the *_fts tables directly: the 'delete' command needs the ORIGINAL column values, which
+    -- only the triggers (via old.*) have. Hand-rolled FTS maintenance with empty/placeholder
+    -- values corrupts the index ("database disk image is malformed").
+    CREATE TRIGGER IF NOT EXISTS symbols_ai AFTER INSERT ON symbols BEGIN
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_ad AFTER DELETE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS symbols_au AFTER UPDATE ON symbols BEGIN
+      INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ai AFTER INSERT ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_ad AFTER DELETE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+    END;
+    CREATE TRIGGER IF NOT EXISTS lib_symbols_au AFTER UPDATE ON lib_symbols BEGIN
+      INSERT INTO lib_symbols_fts(lib_symbols_fts, rowid, name, signature, doc, summary)
+      VALUES ('delete', old.id, old.name, old.signature, old.doc, old.summary);
+      INSERT INTO lib_symbols_fts(rowid, name, signature, doc, summary)
+      VALUES (new.id, new.name, new.signature, new.doc, new.summary);
+    END;
   `);
 }
 
@@ -93,42 +157,19 @@ export function upsertSymbol(
     card_path: string;
   },
 ): void {
-  // Delete existing FTS row for this row first (content=sync requires manual FTS management)
-  // We use a replace-or-insert approach: delete old, insert new
-  const existing = db.prepare(
-    "SELECT id FROM symbols WHERE name = ? AND file_path = ?",
-  ).get(symbol.name, symbol.file_path) as { id: number } | undefined;
-
-  if (existing) {
-    // FTS external content: must delete old content row
-    db.prepare("INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary) VALUES ('delete', ?, '', '', '', '')").run(existing.id);
-  }
-
-  const result = db.prepare(
+  // Plain INSERT — the symbols_ai trigger keeps symbols_fts in sync. Callers (scan/sync) always
+  // delete a file's symbols before re-inserting, so re-indexing is idempotent without an update path.
+  db.prepare(
     `INSERT INTO symbols (name, kind, file_path, line_start, line_end, signature, doc, summary, card_path)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO UPDATE SET
-       kind=excluded.kind, line_start=excluded.line_start, line_end=excluded.line_end,
-       signature=excluded.signature, doc=excluded.doc, summary=excluded.summary, card_path=excluded.card_path`,
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
   ).run(
     symbol.name, symbol.kind, symbol.file_path, symbol.line_start, symbol.line_end,
     symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
   );
-
-  // Insert into FTS
-  const rowId = existing?.id ?? (result.lastInsertRowid as number);
-  db.prepare(
-    `INSERT INTO symbols_fts(rowid, name, signature, doc, summary)
-     VALUES (?, ?, ?, ?, ?)`,
-  ).run(rowId, symbol.name, symbol.signature, symbol.doc, symbol.summary);
 }
 
-/** Delete all symbols for a given file. */
+/** Delete all symbols for a given file. The symbols_ad trigger removes their FTS rows. */
 export function deleteFileSymbols(db: DatabaseType, filePath: string): void {
-  const rows = db.prepare("SELECT id FROM symbols WHERE file_path = ?").all(filePath) as { id: number }[];
-  for (const row of rows) {
-    db.prepare("INSERT INTO symbols_fts(symbols_fts, rowid, name, signature, doc, summary) VALUES ('delete', ?, '', '', '', '')").run(row.id);
-  }
   db.prepare("DELETE FROM symbols WHERE file_path = ?").run(filePath);
 }
 
@@ -182,6 +223,132 @@ export function searchSymbols(
   return db.prepare(sql).all(...params) as typeof results;
 }
 
+/** Upsert a library record. */
+export function upsertLibrary(
+  db: DatabaseType,
+  pkg: { name: string; version: string; source?: string; dts_path?: string | null; readme?: string | null },
+): void {
+  db.prepare(
+    `INSERT INTO libraries (name, version, source, dts_path, readme, indexed_at)
+     VALUES (?, ?, ?, ?, ?, datetime('now'))
+     ON CONFLICT(name, version) DO UPDATE SET
+       source=excluded.source, dts_path=excluded.dts_path, readme=excluded.readme, indexed_at=excluded.indexed_at`,
+  ).run(pkg.name, pkg.version, pkg.source ?? null, pkg.dts_path ?? null, pkg.readme ?? null);
+}
+
+/** Upsert a lib symbol. Replaces on (lib, name) duplicate. */
+export function upsertLibSymbol(
+  db: DatabaseType,
+  symbol: {
+    lib: string;
+    version: string;
+    name: string;
+    kind: string;
+    signature: string;
+    doc: string;
+    summary: string;
+    card_path: string;
+  },
+): void {
+  // The lib_symbols_ai / _au triggers keep lib_symbols_fts in sync — never touch the FTS table here.
+  const existing = db.prepare(
+    "SELECT id FROM lib_symbols WHERE lib = ? AND name = ?",
+  ).get(symbol.lib, symbol.name) as { id: number } | undefined;
+
+  if (existing) {
+    db.prepare(
+      `UPDATE lib_symbols SET version=?, kind=?, signature=?, doc=?, summary=?, card_path=?
+       WHERE id = ?`,
+    ).run(
+      symbol.version, symbol.kind, symbol.signature,
+      symbol.doc, symbol.summary, symbol.card_path,
+      existing.id,
+    );
+  } else {
+    db.prepare(
+      `INSERT INTO lib_symbols (lib, version, name, kind, signature, doc, summary, card_path)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      symbol.lib, symbol.version, symbol.name, symbol.kind,
+      symbol.signature, symbol.doc, symbol.summary, symbol.card_path,
+    );
+  }
+}
+
+/** Delete all lib_symbols (all versions) for a library, then the libraries rows.
+ *  The lib_symbols_ad trigger removes the FTS rows. */
+export function deleteLibrary(db: DatabaseType, libName: string): void {
+  db.prepare("DELETE FROM lib_symbols WHERE lib = ?").run(libName);
+  db.prepare("DELETE FROM libraries WHERE name = ?").run(libName);
+}
+
+/**
+ * Search lib symbols via FTS5 MATCH, ranked by bm25.
+ * Empty query returns all symbols ordered by name.
+ */
+export function searchLibSymbols(
+  db: DatabaseType,
+  query: string,
+  kindFilter?: string,
+  limit = 10,
+): Array<{
+  id: number;
+  name: string;
+  kind: string;
+  lib: string;
+  version: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  signature: string;
+  summary: string;
+  score: number;
+  source: "lib";
+}> {
+  if (!query.trim()) {
+    let sql = "SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary, 0.0 as score FROM lib_symbols s";
+    const params: unknown[] = [];
+    if (kindFilter) {
+      sql += " WHERE s.kind = ?";
+      params.push(kindFilter);
+    }
+    sql += " ORDER BY s.name LIMIT ?";
+    params.push(limit);
+    return db.prepare(sql).all(...params).map((r: any) => ({
+      ...r,
+      file_path: "",
+      line_start: 0,
+      line_end: 0,
+      source: "lib" as const,
+    }));
+  }
+
+  let sql = `
+    SELECT s.id, s.name, s.kind, s.lib, s.version, s.signature, s.summary,
+           bm25(lib_symbols_fts, 10.0, 5.0, 1.0, 8.0) as score
+    FROM lib_symbols_fts
+    JOIN lib_symbols s ON s.id = lib_symbols_fts.rowid
+    WHERE lib_symbols_fts MATCH ?
+  `;
+  const params: unknown[] = [query];
+
+  if (kindFilter) {
+    sql += " AND s.kind = ?";
+    params.push(kindFilter);
+  }
+
+  sql += " ORDER BY score LIMIT ?";
+  params.push(limit);
+
+  return db.prepare(sql).all(...params).map((r: any) => ({
+    ...r,
+    file_path: "",
+    line_start: 0,
+    line_end: 0,
+    source: "lib" as const,
+  }));
+}
+
 /** Get a meta value. */
 export function getMeta(db: DatabaseType, key: string): string | null {
   const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as { value: string } | undefined;

package/src/format.test.ts

@@ -2,6 +2,24 @@ import { describe, it, expect } from 'vitest';
 import { formatCompact, formatCardBody } from './format.ts';
 import type { QueryResultRow, StalenessInfo } from './types.ts';
 
+function makeLibRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
+  return {
+    id: 100,
+    name: 'createMiddleware',
+    kind: 'function',
+    file_path: 'hono/dist/helper.d.ts',
+    line_start: 0,
+    line_end: 0,
+    signature: 'export declare function createMiddleware<E>(...): MiddlewareHandler',
+    summary: 'Define a typed middleware handler.',
+    score: 0.3,
+    source: 'lib',
+    lib: 'hono',
+    version: '4.6.3',
+    ...overrides,
+  };
+}
+
 function makeRow(overrides: Partial<QueryResultRow> = {}): QueryResultRow {
   return {
     id: 1,
@@ -63,6 +81,40 @@ describe('formatCompact', () => {
   });
 });
 
+describe('formatCompact with lib rows', () => {
+  it('renders a lib row with [lib@version] origin tag', () => {
+    const rows = [makeLibRow()];
+    const result = formatCompact(rows, null);
+    expect(result).toContain('createMiddleware');
+    expect(result).toContain('function');
+    expect(result).toContain('[hono@4.6.3]');
+    expect(result).toContain('Define a typed middleware handler.');
+  });
+
+  it('renders mixed code and lib rows', () => {
+    const libRow = makeLibRow();
+    const codeRow: QueryResultRow = {
+      id: 1, name: 'myFunc', kind: 'function',
+      file_path: 'src/util/helper.ts', line_start: 10, line_end: 20,
+      signature: '(x: number) => string', summary: 'Does something', score: 0.5,
+    };
+    const result = formatCompact([codeRow, libRow], null);
+    expect(result).toContain('helper.ts:10-20');
+    expect(result).toContain('[hono@4.6.3]');
+    // Two lines
+    expect(result.split('\n')).toHaveLength(2);
+  });
+
+  it('bounded output for lib rows (one line per hit)', () => {
+    const rows = Array.from({ length: 5 }, (_, i) =>
+      makeLibRow({ name: `fn${i}`, lib: 'test-pkg', version: '1.0.0' })
+    );
+    const result = formatCompact(rows, null);
+    expect(result.split('\n')).toHaveLength(5);
+    expect(result).toContain('[test-pkg@1.0.0]');
+  });
+});
+
 describe('formatCardBody', () => {
   it('returns the card body text', () => {
     const body = '# myFunc\n\nDoes something.\n';

package/src/format.ts

@@ -27,6 +27,12 @@ export function formatCompact(
   }
 
   const lines = rows.map((row) => {
+    if (row.source === "lib" && row.lib && row.version) {
+      const origin = `[${row.lib}@${row.version}]`;
+      const summary = truncate(row.summary || "", SUMMARY_MAX);
+      const loc = row.file_path ? `${basename(row.file_path)}:${row.line_start}-${row.line_end}` : `lib`;
+      return `${row.name} · ${row.kind} · ${origin} · ${loc} · ${summary}`;
+    }
     const loc = `${basename(row.file_path)}:${row.line_start}-${row.line_end}`;
     const summary = truncate(row.summary || "", SUMMARY_MAX);
     return `${row.name} · ${row.kind} · ${loc} · ${summary}`;

package/src/index.contract.test.ts

@@ -58,10 +58,15 @@ describe('index.ts contract', () => {
     expect(queryTool).toBeDefined();
     expect(queryTool!.description).toContain('code index');
 
+    // Check tool has a source parameter
+    const toolParams = (queryTool!.parameters as any);
+    expect(toolParams.properties).toHaveProperty('source');
+
     // Check command registered
     const cmd = stub.commands.find(c => c.name === 'codewalker');
     expect(cmd).toBeDefined();
-    expect(cmd!.description).toBeDefined();
+    expect(cmd!.description).toContain('libs');
+    expect(cmd!.description).toContain('lib');
   });
 
   it('tool.execute returns { content, details } with compact text content', async () => {
@@ -97,4 +102,44 @@ describe('index.ts contract', () => {
 
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
+
+  it('tool.execute with source="libs" returns valid result even with no lib data', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-contract-libs-'));
+    const piDir = path.join(tmpDir, '.pi');
+    fs.mkdirSync(piDir, { recursive: true });
+    const markerId = 'test-project-libs-' + Math.random().toString(36).slice(2, 8);
+    fs.writeFileSync(path.join(piDir, markerId + '.md'), `---\npi-project: true\nid: ${markerId}\n---\n`);
+
+    const homePi = path.join(os.homedir(), '.pi', 'projects', markerId, 'codewalker');
+    fs.mkdirSync(homePi, { recursive: true });
+
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const tool = stub.tools.find(t => t.name === 'codewalker_query')!;
+    const result = await tool.execute(
+      'test-id',
+      { query: 'test', source: 'libs' },
+      new AbortController().signal,
+      () => {},
+      { cwd: tmpDir },
+    );
+
+    expect(result).toHaveProperty('content');
+    expect(result.content[0]!.text).toContain('No matches');
+    expect(result.details.rows).toEqual([]);
+
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('command description mentions libs and lib subcommands', async () => {
+    const mod = await import('./index.ts');
+    const stub = createPiStub();
+    mod.default(stub.api as any);
+
+    const cmd = stub.commands.find(c => c.name === 'codewalker')!;
+    expect(cmd.description).toContain('libs [--dev]');
+    expect(cmd.description).toContain('lib <pkg>');
+  });
 });