@cleocode/core 2026.3.76 → 2026.4.0

package/src/code/search.ts

@@ -0,0 +1,173 @@
+/**
+ * smart_search — cross-codebase symbol search via tree-sitter.
+ *
+ * Walks a directory tree, batch-parses code files by language, and
+ * matches symbols against a query string with relevance scoring.
+ *
+ * @task T152
+ */
+
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type { CodeSymbol } from '@cleocode/contracts';
+import { detectLanguage, type TreeSitterLanguage } from '../lib/tree-sitter-languages.js';
+import { batchParse } from './parser.js';
+
+/** A search result with relevance score. */
+export interface SmartSearchResult {
+  /** The matched symbol. */
+  symbol: CodeSymbol;
+  /** Relevance score (higher = better match). */
+  score: number;
+  /** How the query matched (exact, substring, fuzzy, path). */
+  matchType: 'exact' | 'substring' | 'fuzzy' | 'path';
+}
+
+/** Options for smart_search. */
+export interface SmartSearchOptions {
+  /** Maximum results to return (default: 20). */
+  maxResults?: number;
+  /** Glob-like file pattern filter (e.g. "*.ts", "src/**"). */
+  filePattern?: string;
+  /** Restrict to specific language. */
+  language?: TreeSitterLanguage;
+  /** Root directory to search (default: cwd). */
+  rootDir?: string;
+}
+
+/**
+ * Walk a directory tree and collect source files.
+ *
+ * Respects common ignore patterns (node_modules, dist, .git, etc.)
+ * and optionally filters by file pattern and language.
+ */
+function collectSourceFiles(dir: string, options: SmartSearchOptions): string[] {
+  const IGNORE_DIRS = new Set([
+    'node_modules',
+    'dist',
+    '.git',
+    '.cleo',
+    'target',
+    '__pycache__',
+    '.next',
+    '.nuxt',
+    'build',
+    'coverage',
+    '.turbo',
+    '.cache',
+  ]);
+
+  const files: string[] = [];
+
+  function walk(currentDir: string): void {
+    let entries: { isDirectory(): boolean; isFile(): boolean; name: string }[];
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true, encoding: 'utf-8' }) as {
+        isDirectory(): boolean;
+        isFile(): boolean;
+        name: string;
+      }[];
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!IGNORE_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          walk(join(currentDir, entry.name));
+        }
+      } else if (entry.isFile()) {
+        const fullPath = join(currentDir, entry.name);
+        const lang = detectLanguage(entry.name);
+        if (!lang) continue;
+
+        // Language filter
+        if (options.language && lang !== options.language) continue;
+
+        // File pattern filter (simple glob: *.ext or dir/**)
+        if (options.filePattern) {
+          const relPath = relative(dir, fullPath);
+          if (options.filePattern.startsWith('*.')) {
+            const ext = options.filePattern.slice(1);
+            if (!entry.name.endsWith(ext)) continue;
+          } else if (!relPath.includes(options.filePattern.replace('/**', ''))) {
+            continue;
+          }
+        }
+
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Score a symbol against a query string.
+ *
+ * Scoring: exact name match (10) > substring in name (5) >
+ * path match (3) > fuzzy (1).
+ */
+function scoreSymbol(
+  symbol: CodeSymbol,
+  query: string,
+): { score: number; matchType: SmartSearchResult['matchType'] } {
+  const q = query.toLowerCase();
+  const name = symbol.name.toLowerCase();
+  const path = symbol.filePath.toLowerCase();
+
+  // Exact name match
+  if (name === q) return { score: 10, matchType: 'exact' };
+
+  // Substring in name
+  if (name.includes(q)) return { score: 5, matchType: 'substring' };
+
+  // Path match
+  if (path.includes(q)) return { score: 3, matchType: 'path' };
+
+  // Fuzzy: all query chars appear in order in the name
+  let qi = 0;
+  for (let ni = 0; ni < name.length && qi < q.length; ni++) {
+    if (name[ni] === q[qi]) qi++;
+  }
+  if (qi === q.length) return { score: 1, matchType: 'fuzzy' };
+
+  return { score: 0, matchType: 'fuzzy' };
+}
+
+/**
+ * Search for symbols across a codebase.
+ *
+ * Walks the directory tree, batch-parses source files, and returns
+ * symbols matching the query ranked by relevance score.
+ *
+ * @param query - Search string to match against symbol names and paths
+ * @param options - Search options (maxResults, filePattern, language, rootDir)
+ * @returns Ranked array of search results
+ */
+export function smartSearch(query: string, options: SmartSearchOptions = {}): SmartSearchResult[] {
+  const rootDir = options.rootDir ?? process.cwd();
+  const maxResults = options.maxResults ?? 20;
+
+  // Collect and parse source files
+  const files = collectSourceFiles(rootDir, options);
+  const parsed = batchParse(files, rootDir);
+
+  // Score all symbols
+  const results: SmartSearchResult[] = [];
+  for (const fileResult of parsed.results) {
+    for (const symbol of fileResult.symbols) {
+      const { score, matchType } = scoreSymbol(symbol, query);
+      if (score > 0) {
+        results.push({ symbol, score, matchType });
+      }
+    }
+  }
+
+  // Sort by score descending, then by name
+  results.sort((a, b) => b.score - a.score || a.symbol.name.localeCompare(b.symbol.name));
+
+  return results.slice(0, maxResults);
+}

package/src/code/unfold.ts

@@ -0,0 +1,204 @@
+/**
+ * smart_unfold — single symbol extraction from source files.
+ *
+ * Takes a file path + symbol name, parses the file via tree-sitter,
+ * finds the matching symbol node, and extracts complete source including
+ * JSDoc/docstring, decorators, and full body. AST node boundaries
+ * guarantee no truncation.
+ *
+ * @task T153
+ */
+
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import type { CodeSymbol } from '@cleocode/contracts';
+import { detectLanguage } from '../lib/tree-sitter-languages.js';
+import { parseFile } from './parser.js';
+
+/** Result of unfolding a single symbol. */
+export interface SmartUnfoldResult {
+  /** Whether the symbol was found. */
+  found: boolean;
+  /** The matched symbol metadata. */
+  symbol?: CodeSymbol;
+  /** Complete source text including JSDoc, decorators, and body. */
+  source: string;
+  /** Start line (1-based, inclusive of leading doc comment). */
+  startLine: number;
+  /** End line (1-based). */
+  endLine: number;
+  /** Estimated token count for this extraction. */
+  estimatedTokens: number;
+  /** File path (relative). */
+  filePath: string;
+  /** Errors encountered. */
+  errors: string[];
+}
+
+/**
+ * Find leading documentation comment (JSDoc, docstring, Rust doc) above a symbol.
+ *
+ * Scans backwards from the symbol's start line to find attached doc comments.
+ */
+function findLeadingDocStart(lines: string[], symbolStartLine: number, language: string): number {
+  const idx = symbolStartLine - 1; // 1-based to 0-based
+  if (idx <= 0) return symbolStartLine;
+
+  let docStart = idx;
+
+  if (language === 'python') {
+    // Python: look for decorator lines above
+    let i = idx - 1;
+    while (i >= 0 && lines[i]!.trimStart().startsWith('@')) {
+      docStart = i + 1; // back to 1-based
+      i--;
+    }
+    return docStart;
+  }
+
+  // C-family / Rust / JS/TS: look for block comments (/** ... */) or /// lines
+  let i = idx - 1;
+
+  // Skip blank lines immediately above
+  while (i >= 0 && lines[i]!.trim() === '') i--;
+
+  if (i < 0) return symbolStartLine;
+
+  const line = lines[i]!.trimStart();
+
+  // Block comment ending: */
+  if (line.endsWith('*/')) {
+    // Walk backwards to find opening /**
+    while (i >= 0) {
+      if (lines[i]!.trimStart().startsWith('/**') || lines[i]!.trimStart().startsWith('/*')) {
+        docStart = i + 1; // 1-based
+        break;
+      }
+      i--;
+    }
+  }
+  // Line comments: /// (Rust) or // (TS/JS decorators less common)
+  else if (line.startsWith('///') || line.startsWith('//!')) {
+    while (
+      i >= 0 &&
+      (lines[i]!.trimStart().startsWith('///') || lines[i]!.trimStart().startsWith('//!'))
+    ) {
+      docStart = i + 1;
+      i--;
+    }
+  }
+
+  // Also capture decorators (TS/Java) above the doc comment
+  i = docStart - 2; // 0-based, line above current docStart
+  while (i >= 0 && lines[i]!.trimStart().startsWith('@')) {
+    docStart = i + 1;
+    i--;
+  }
+
+  return docStart;
+}
+
+/**
+ * Extract a symbol's complete source from a file.
+ *
+ * Finds the symbol by name (supports "Class.method" dot notation),
+ * determines its full range including leading documentation, and
+ * returns the exact source text.
+ *
+ * @param filePath - Absolute path to source file
+ * @param symbolName - Symbol to extract (e.g. "parseFile" or "HttpTransport.connect")
+ * @param projectRoot - Project root for relative path computation
+ * @returns Unfold result with complete source text
+ */
+export function smartUnfold(
+  filePath: string,
+  symbolName: string,
+  projectRoot?: string,
+): SmartUnfoldResult {
+  const root = projectRoot ?? process.cwd();
+  const relPath = relative(root, filePath);
+  const language = detectLanguage(filePath);
+
+  const empty: SmartUnfoldResult = {
+    found: false,
+    source: '',
+    startLine: 0,
+    endLine: 0,
+    estimatedTokens: 0,
+    filePath: relPath,
+    errors: [],
+  };
+
+  if (!language) {
+    return { ...empty, errors: ['Unsupported language'] };
+  }
+
+  // Parse the file
+  const parseResult = parseFile(filePath, root);
+  if (parseResult.symbols.length === 0) {
+    return {
+      ...empty,
+      errors: parseResult.errors.length > 0 ? parseResult.errors : ['No symbols found'],
+    };
+  }
+
+  // Find the matching symbol
+  const parts = symbolName.split('.');
+  let match: CodeSymbol | undefined;
+
+  if (parts.length === 2) {
+    // Nested: "Class.method" — find method with matching parent range
+    const [parentName, childName] = parts;
+    const parent = parseResult.symbols.find(
+      (s) =>
+        s.name === parentName && (s.kind === 'class' || s.kind === 'struct' || s.kind === 'impl'),
+    );
+    if (parent) {
+      match = parseResult.symbols.find(
+        (s) =>
+          s.name === childName && s.startLine >= parent.startLine && s.endLine <= parent.endLine,
+      );
+    }
+  } else {
+    // Top-level: exact name match, prefer non-method over method
+    match = parseResult.symbols.find((s) => s.name === symbolName && s.kind !== 'method');
+    if (!match) {
+      match = parseResult.symbols.find((s) => s.name === symbolName);
+    }
+  }
+
+  if (!match) {
+    return { ...empty, errors: [`Symbol "${symbolName}" not found in ${relPath}`] };
+  }
+
+  // Read source lines
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, 'utf-8').split('\n');
+  } catch (err) {
+    return {
+      ...empty,
+      errors: [`Failed to read file: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+
+  // Determine full range including doc comment
+  const docStart = findLeadingDocStart(lines, match.startLine, language);
+  const startLine = Math.min(docStart, match.startLine);
+  const endLine = match.endLine;
+
+  // Extract source text
+  const source = lines.slice(startLine - 1, endLine).join('\n');
+  const estimatedTokens = Math.ceil(source.length / 4);
+
+  return {
+    found: true,
+    symbol: match,
+    source,
+    startLine,
+    endLine,
+    estimatedTokens,
+    filePath: relPath,
+    errors: [],
+  };
+}

package/src/conduit/__tests__/dual-api-e2e.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Dual-API E2E test — verify messaging across both SignalDock endpoints.
+ *
+ * Tests that agents can exchange messages on:
+ * 1. api.signaldock.io (canonical)
+ * 2. api.clawmsgr.com (legacy)
+ * 3. Local signaldock.db (offline)
+ *
+ * These tests hit real APIs and require valid credentials.
+ * Set SKIP_E2E=1 to skip when running in CI without network.
+ *
+ * @task T226
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { HttpTransport } from '../http-transport.js';
+
+// ============================================================================
+// Config helpers
+// ============================================================================
+
+const CLEO_DIR = join(process.cwd(), '.cleo');
+const SKIP_E2E = process.env['SKIP_E2E'] === '1';
+
+/** Load a ClawMsgr/SignalDock config file. */
+function loadConfig(
+  filename: string,
+): { agentId: string; apiKey: string; apiBaseUrl: string } | null {
+  const path = join(CLEO_DIR, filename);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as {
+      agentId: string;
+      apiKey: string;
+      apiBaseUrl: string;
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Send a test message and verify it arrives. */
+async function testMessageExchange(
+  apiBaseUrl: string,
+  senderConfig: { agentId: string; apiKey: string },
+  receiverAgentId: string,
+): Promise<{ sent: boolean; messageId: string | null; error: string | null }> {
+  const transport = new HttpTransport();
+  try {
+    await transport.connect({
+      agentId: senderConfig.agentId,
+      apiKey: senderConfig.apiKey,
+      apiBaseUrl,
+    });
+
+    const testContent = `/info @${receiverAgentId} #e2e-test T226 verification at ${new Date().toISOString()}`;
+    const result = await transport.push(receiverAgentId, testContent);
+
+    await transport.disconnect();
+    return { sent: true, messageId: result.messageId, error: null };
+  } catch (err) {
+    await transport.disconnect();
+    return { sent: false, messageId: null, error: String(err) };
+  }
+}
+
+// ============================================================================
+// Test suite
+// ============================================================================
+
+describe('Dual-API E2E', () => {
+  // --------------------------------------------------------------------------
+  // Config verification
+  // --------------------------------------------------------------------------
+
+  describe('config files exist', () => {
+    it('has clawmsgr configs (legacy)', () => {
+      const config = loadConfig('clawmsgr-cleo-rust-lead.json');
+      if (!config) {
+        console.log('SKIP: clawmsgr config not found');
+        return;
+      }
+      expect(config.agentId).toBe('cleo-rust-lead');
+      expect(config.apiBaseUrl).toContain('clawmsgr.com');
+    });
+
+    it('has signaldock configs (canonical)', () => {
+      const config = loadConfig('signaldock-cleo-rust-lead.json');
+      if (!config) {
+        console.log('SKIP: signaldock config not found');
+        return;
+      }
+      expect(config.agentId).toBe('cleo-rust-lead');
+      expect(config.apiBaseUrl).toContain('signaldock.io');
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // API health checks
+  // --------------------------------------------------------------------------
+
+  describe('API health', () => {
+    it('api.signaldock.io is healthy', async () => {
+      if (SKIP_E2E) return;
+      const response = await fetch('https://api.signaldock.io/health', {
+        signal: AbortSignal.timeout(10_000),
+      });
+      expect(response.ok).toBe(true);
+      const data = (await response.json()) as { data?: { status?: string } };
+      expect(data.data?.status).toBe('ok');
+    });
+
+    it('api.clawmsgr.com is healthy', async () => {
+      if (SKIP_E2E) return;
+      const response = await fetch('https://api.clawmsgr.com/health', {
+        signal: AbortSignal.timeout(10_000),
+      });
+      expect(response.ok).toBe(true);
+      const data = (await response.json()) as { data?: { status?: string } };
+      expect(data.data?.status).toBe('ok');
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Message exchange on api.signaldock.io
+  // --------------------------------------------------------------------------
+
+  describe('api.signaldock.io messaging', () => {
+    it('can send a message via signaldock.io', async () => {
+      if (SKIP_E2E) return;
+      const config = loadConfig('signaldock-cleo-rust-lead.json');
+      if (!config) {
+        console.log('SKIP: no signaldock config');
+        return;
+      }
+      const result = await testMessageExchange(
+        'https://api.signaldock.io',
+        { agentId: config.agentId, apiKey: config.apiKey },
+        'cleo-dev',
+      );
+      expect(result.sent).toBe(true);
+      expect(result.messageId).toBeDefined();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Message exchange on api.clawmsgr.com
+  // --------------------------------------------------------------------------
+
+  describe('api.clawmsgr.com messaging', () => {
+    it('can send a message via clawmsgr.com', async () => {
+      if (SKIP_E2E) return;
+      const config = loadConfig('clawmsgr-cleo-rust-lead.json');
+      if (!config) {
+        console.log('SKIP: no clawmsgr config');
+        return;
+      }
+      const result = await testMessageExchange(
+        'https://api.clawmsgr.com',
+        { agentId: config.agentId, apiKey: config.apiKey },
+        'cleo-dev',
+      );
+      expect(result.sent).toBe(true);
+      expect(result.messageId).toBeDefined();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Cross-API metadata consistency
+  // --------------------------------------------------------------------------
+
+  describe('cross-API consistency', () => {
+    it('agent profile exists on both APIs', async () => {
+      if (SKIP_E2E) return;
+      const clawConfig = loadConfig('clawmsgr-cleo-rust-lead.json');
+      const sdConfig = loadConfig('signaldock-cleo-rust-lead.json');
+      if (!clawConfig || !sdConfig) {
+        console.log('SKIP: missing configs');
+        return;
+      }
+
+      // Check agent exists on clawmsgr
+      const clawResp = await fetch('https://api.clawmsgr.com/agents/cleo-rust-lead', {
+        headers: {
+          Authorization: `Bearer ${clawConfig.apiKey}`,
+          'X-Agent-Id': 'cleo-rust-lead',
+        },
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      // Check agent exists on signaldock
+      const sdResp = await fetch('https://api.signaldock.io/agents/cleo-rust-lead', {
+        headers: {
+          Authorization: `Bearer ${sdConfig.apiKey}`,
+          'X-Agent-Id': 'cleo-rust-lead',
+        },
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      expect(clawResp.ok).toBe(true);
+      expect(sdResp.ok).toBe(true);
+
+      const clawData = (await clawResp.json()) as { data?: { agent?: { agentId?: string } } };
+      const sdData = (await sdResp.json()) as { data?: { agent?: { agentId?: string } } };
+
+      expect(clawData.data?.agent?.agentId).toBe('cleo-rust-lead');
+      expect(sdData.data?.agent?.agentId).toBe('cleo-rust-lead');
+    });
+  });
+});