@cleocode/core 2026.3.74 → 2026.4.0

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

package/src/conduit/__tests__/local-credential-flow.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Local credential flow — end-to-end validation.
+ *
+ * Tests the full lifecycle: signaldock.db creation → agent register →
+ * credential encryption/decryption → LocalTransport connect →
+ * push/poll/ack messaging.
+ *
+ * @task T227
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ensureSignaldockDb, getSignaldockDbPath } from '../../store/signaldock-sqlite.js';
+import { LocalTransport } from '../local-transport.js';
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+let testDir: string;
+let originalCwd: string;
+
+async function setupTestEnvironment(): Promise<string> {
+  const dir = join(
+    tmpdir(),
+    `credential-flow-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(join(dir, '.cleo'), { recursive: true });
+  // Create a minimal .cleo/project-context.json so paths resolve
+  writeFileSync(
+    join(dir, '.cleo', 'project-context.json'),
+    JSON.stringify({ schemaVersion: '1.0.0', projectTypes: ['node'], primaryType: 'node' }),
+  );
+  return dir;
+}
+
+// ============================================================================
+// Test suite
+// ============================================================================
+
+describe('Local Credential Flow E2E', () => {
+  beforeEach(async () => {
+    originalCwd = process.cwd();
+    testDir = await setupTestEnvironment();
+    process.chdir(testDir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    if (testDir && existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  // --------------------------------------------------------------------------
+  // Step 1: cleo init creates signaldock.db
+  // --------------------------------------------------------------------------
+
+  describe('Step 1: signaldock.db creation', () => {
+    it('ensureSignaldockDb creates the database file', async () => {
+      const result = await ensureSignaldockDb(testDir);
+      expect(result.action).toBe('created');
+      expect(existsSync(result.path)).toBe(true);
+    });
+
+    it('ensureSignaldockDb is idempotent', async () => {
+      const first = await ensureSignaldockDb(testDir);
+      const second = await ensureSignaldockDb(testDir);
+      expect(first.action).toBe('created');
+      expect(second.action).toBe('exists');
+      expect(first.path).toBe(second.path);
+    });
+
+    it('signaldock.db has the messages table', async () => {
+      await ensureSignaldockDb(testDir);
+      const dbPath = getSignaldockDbPath(testDir);
+      expect(existsSync(dbPath)).toBe(true);
+
+      // Verify by connecting LocalTransport (which checks for messages table)
+      const transport = new LocalTransport();
+      await transport.connect({
+        agentId: 'test',
+        apiKey: 'sk_test',
+        apiBaseUrl: 'http://localhost',
+      });
+      await transport.disconnect();
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Step 2: LocalTransport availability
+  // --------------------------------------------------------------------------
+
+  describe('Step 2: LocalTransport availability', () => {
+    it('isAvailable returns false before init', () => {
+      const emptyDir = join(tmpdir(), `no-init-${Date.now()}`);
+      mkdirSync(join(emptyDir, '.cleo'), { recursive: true });
+      expect(LocalTransport.isAvailable(emptyDir)).toBe(false);
+      rmSync(emptyDir, { recursive: true, force: true });
+    });
+
+    it('isAvailable returns true after init', async () => {
+      await ensureSignaldockDb(testDir);
+      expect(LocalTransport.isAvailable(testDir)).toBe(true);
+    });
+  });
+
+  // --------------------------------------------------------------------------
+  // Step 3: Full messaging lifecycle
+  // --------------------------------------------------------------------------
+
+  describe('Step 3: messaging lifecycle', () => {
+    it('complete flow: init → connect → push → poll → ack', async () => {
+      // 1. Init signaldock.db
+      await ensureSignaldockDb(testDir);
+
+      // 2. Connect two agents
+      const agent1 = new LocalTransport();
+      const agent2 = new LocalTransport();
+
+      await agent1.connect({
+        agentId: 'cleo-rust-lead',
+        apiKey: 'sk_live_fake1',
+        apiBaseUrl: 'http://localhost',
+      });
+      await agent2.connect({
+        agentId: 'cleo-dev',
+        apiKey: 'sk_live_fake2',
+        apiBaseUrl: 'http://localhost',
+      });
+
+      // 3. Agent 1 sends a message to Agent 2
+      const sendResult = await agent1.push(
+        'cleo-dev',
+        '/action @cleo-dev #test Hello from rust-lead',
+      );
+      expect(sendResult.messageId).toBeDefined();
+
+      // 4. Agent 2 polls and receives the message
+      const messages = await agent2.poll();
+      expect(messages).toHaveLength(1);
+      expect(messages[0].from).toBe('cleo-rust-lead');
+      expect(messages[0].content).toContain('Hello from rust-lead');
+
+      // 5. Agent 2 acknowledges the message
+      await agent2.ack([messages[0].id]);
+
+      // 6. Subsequent poll returns empty (message was acked)
+      const afterAck = await agent2.poll();
+      expect(afterAck).toHaveLength(0);
+
+      // 7. Agent 2 replies
+      const replyResult = await agent2.push('cleo-rust-lead', '/ack Received.');
+      expect(replyResult.messageId).toBeDefined();
+
+      // 8. Agent 1 receives the reply
+      const replies = await agent1.poll();
+      expect(replies).toHaveLength(1);
+      expect(replies[0].from).toBe('cleo-dev');
+      expect(replies[0].content).toBe('/ack Received.');
+
+      // Cleanup
+      await agent1.disconnect();
+      await agent2.disconnect();
+    });
+
+    it('messages persist across transport reconnections', async () => {
+      await ensureSignaldockDb(testDir);
+
+      // Send a message
+      const sender = new LocalTransport();
+      await sender.connect({
+        agentId: 'sender',
+        apiKey: 'sk_test',
+        apiBaseUrl: 'http://localhost',
+      });
+      await sender.push('receiver', 'persistent message');
+      await sender.disconnect();
+
+      // New transport instance reads the same DB
+      const receiver = new LocalTransport();
+      await receiver.connect({
+        agentId: 'receiver',
+        apiKey: 'sk_test',
+        apiBaseUrl: 'http://localhost',
+      });
+      const messages = await receiver.poll();
+      expect(messages).toHaveLength(1);
+      expect(messages[0].content).toBe('persistent message');
+
+      await receiver.disconnect();
+    });
+
+    it('multiple agents can communicate in the same conversation', async () => {
+      await ensureSignaldockDb(testDir);
+
+      const prime = new LocalTransport();
+      const rustLead = new LocalTransport();
+      const dbLead = new LocalTransport();
+
+      await prime.connect({ agentId: 'prime', apiKey: 'sk1', apiBaseUrl: 'http://localhost' });
+      await rustLead.connect({
+        agentId: 'rust-lead',
+        apiKey: 'sk2',
+        apiBaseUrl: 'http://localhost',
+      });
+      await dbLead.connect({ agentId: 'db-lead', apiKey: 'sk3', apiBaseUrl: 'http://localhost' });
+
+      // Prime sends to rust-lead
+      await prime.push('rust-lead', 'Fix cant-lsp');
+      // Prime sends to db-lead
+      await prime.push('db-lead', 'Review schemas');
+
+      // Each agent only sees their own messages
+      const rustMessages = await rustLead.poll();
+      const dbMessages = await dbLead.poll();
+
+      expect(rustMessages).toHaveLength(1);
+      expect(rustMessages[0].content).toBe('Fix cant-lsp');
+      expect(dbMessages).toHaveLength(1);
+      expect(dbMessages[0].content).toBe('Review schemas');
+
+      await prime.disconnect();
+      await rustLead.disconnect();
+      await dbLead.disconnect();
+    });
+  });
+});