@cleocode/core 2026.4.30 → 2026.4.35

package/src/nexus/nexus-bridge.ts

@@ -0,0 +1,444 @@
+/**
+ * Nexus Bridge Generator
+ *
+ * Generates .cleo/nexus-bridge.md from nexus.db content. This file is
+ * the code intelligence equivalent of memory-bridge.md — it summarizes
+ * the codebase graph for agent consumption.
+ *
+ * Content assembly:
+ *   - Index status (file count, node count, relation count, last indexed)
+ *   - Symbol counts by kind (functions, classes, methods, etc.)
+ *   - Relation counts by type (calls, imports, extends, etc.)
+ *   - Top entry points (most outgoing CALLS edges, exported)
+ *   - Functional clusters (communities by symbol count)
+ *   - Code intelligence command reference
+ *
+ * Regeneration triggers:
+ *   - cleo nexus analyze (called after pipeline flush)
+ *   - Manual: cleo nexus refresh-bridge
+ *
+ * @task T551
+ * @epic T549
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { DatabaseSync } from 'node:sqlite';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Raw row for node kind counts. */
+interface NodeKindCountRow {
+  kind: string;
+  count: number;
+}
+
+/** Raw row for relation type counts. */
+interface RelationTypeCountRow {
+  type: string;
+  count: number;
+}
+
+/** Raw row for top entry points. */
+interface EntryPointRow {
+  name: string | null;
+  file_path: string | null;
+  callees: number;
+  is_exported: number;
+}
+
+/** Raw row for community/cluster nodes. */
+interface CommunityRow {
+  id: string;
+  label: string;
+  meta_json: string | null;
+  indexed_at: string;
+}
+
+/** Raw row for index metadata. */
+interface IndexMetaRow {
+  total_nodes: number;
+  total_relations: number;
+  file_count: number;
+  last_indexed_at: string | null;
+}
+
+// ============================================================================
+// DB helpers
+// ============================================================================
+
+/** Type-safe wrapper for DatabaseSync.prepare().all(). */
+function typedAll<T>(db: DatabaseSync, sql: string, ...params: (string | number | null)[]): T[] {
+  return db.prepare(sql).all(...params) as T[];
+}
+
+/** Type-safe wrapper for DatabaseSync.prepare().get(). */
+function typedGet<T>(
+  db: DatabaseSync,
+  sql: string,
+  ...params: (string | number | null)[]
+): T | undefined {
+  return db.prepare(sql).get(...params) as T | undefined;
+}
+
+// ============================================================================
+// Query helpers
+// ============================================================================
+
+/** Query total node/relation counts and last indexed timestamp. */
+function queryIndexMeta(db: DatabaseSync, projectId: string): IndexMetaRow {
+  try {
+    const nodeMeta = typedGet<{
+      total_nodes: number;
+      file_count: number;
+      last_indexed_at: string | null;
+    }>(
+      db,
+      `SELECT COUNT(*) as total_nodes,
+              COUNT(CASE WHEN kind = 'file' THEN 1 END) as file_count,
+              MAX(indexed_at) as last_indexed_at
+       FROM nexus_nodes
+       WHERE project_id = ?`,
+      projectId,
+    );
+
+    const relMeta = typedGet<{ total_relations: number }>(
+      db,
+      `SELECT COUNT(*) as total_relations
+       FROM nexus_relations
+       WHERE project_id = ?`,
+      projectId,
+    );
+
+    return {
+      total_nodes: nodeMeta?.total_nodes ?? 0,
+      total_relations: relMeta?.total_relations ?? 0,
+      file_count: nodeMeta?.file_count ?? 0,
+      last_indexed_at: nodeMeta?.last_indexed_at ?? null,
+    };
+  } catch {
+    return {
+      total_nodes: 0,
+      total_relations: 0,
+      file_count: 0,
+      last_indexed_at: null,
+    };
+  }
+}
+
+/** Query node counts grouped by kind. */
+function queryNodeKindCounts(db: DatabaseSync, projectId: string): NodeKindCountRow[] {
+  try {
+    return typedAll<NodeKindCountRow>(
+      db,
+      `SELECT kind, COUNT(*) as count
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind NOT IN ('file', 'folder', 'community', 'process')
+       GROUP BY kind
+       ORDER BY count DESC
+       LIMIT 10`,
+      projectId,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query relation counts grouped by type. */
+function queryRelationTypeCounts(db: DatabaseSync, projectId: string): RelationTypeCountRow[] {
+  try {
+    return typedAll<RelationTypeCountRow>(
+      db,
+      `SELECT type, COUNT(*) as count
+       FROM nexus_relations
+       WHERE project_id = ?
+         AND type NOT IN ('member_of', 'step_in_process', 'entry_point_of')
+       GROUP BY type
+       ORDER BY count DESC
+       LIMIT 8`,
+      projectId,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query top entry points by outgoing CALLS edge count. */
+function queryTopEntryPoints(db: DatabaseSync, projectId: string, limit = 5): EntryPointRow[] {
+  try {
+    return typedAll<EntryPointRow>(
+      db,
+      `SELECT n.name, n.file_path, COUNT(*) as callees, n.is_exported
+       FROM nexus_relations r
+       JOIN nexus_nodes n ON r.source_id = n.id
+       WHERE r.type = 'calls'
+         AND r.project_id = ?
+         AND n.kind IN ('function', 'method', 'constructor')
+       GROUP BY r.source_id
+       ORDER BY callees DESC
+       LIMIT ?`,
+      projectId,
+      limit,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query community nodes ordered by member count. */
+function queryCommunities(db: DatabaseSync, projectId: string, limit = 6): CommunityRow[] {
+  try {
+    return typedAll<CommunityRow>(
+      db,
+      `SELECT id, label, meta_json, indexed_at
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind = 'community'
+       ORDER BY indexed_at DESC
+       LIMIT ?`,
+      projectId,
+      limit,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** Query count of execution flow (process) nodes. */
+function queryProcessCount(db: DatabaseSync, projectId: string): number {
+  try {
+    const row = typedGet<{ count: number }>(
+      db,
+      `SELECT COUNT(*) as count
+       FROM nexus_nodes
+       WHERE project_id = ?
+         AND kind = 'process'`,
+      projectId,
+    );
+    return row?.count ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+// ============================================================================
+// Content generation
+// ============================================================================
+
+/**
+ * Generate nexus bridge markdown content from nexus.db.
+ * Returns the full markdown string (does not write to disk).
+ *
+ * @param projectId - Project registry ID used to scope nexus.db queries
+ * @param repoPath - Absolute path to the repository root (used for display)
+ * @returns Markdown string summarizing the code intelligence index
+ */
+export async function generateNexusBridgeContent(
+  projectId: string,
+  repoPath: string,
+): Promise<string> {
+  const { getNexusDb, getNexusNativeDb } = await import('../store/nexus-sqlite.js');
+
+  // Ensure DB is initialized
+  await getNexusDb();
+  const nativeDb = getNexusNativeDb();
+
+  if (!nativeDb) {
+    return buildEmptyBridge(repoPath);
+  }
+
+  // Check whether this project has been indexed at all
+  const meta = queryIndexMeta(nativeDb, projectId);
+  if (meta.total_nodes === 0) {
+    return buildEmptyBridge(repoPath);
+  }
+
+  const lines: string[] = [
+    '# CLEO Nexus Bridge — Code Intelligence',
+    '',
+    `> Auto-generated from nexus index. Regenerate with \`cleo nexus analyze\`.`,
+    `> Project: ${repoPath}`,
+    '',
+  ];
+
+  // --- Index Status ---
+  const kindCounts = queryNodeKindCounts(nativeDb, projectId);
+  const relCounts = queryRelationTypeCounts(nativeDb, projectId);
+  const processCount = queryProcessCount(nativeDb, projectId);
+  const communities = queryCommunities(nativeDb, projectId);
+
+  const symbolBreakdown = kindCounts.map((r) => `${r.kind}s: ${r.count}`).join(', ');
+
+  const callsCount = relCounts.find((r) => r.type === 'calls')?.count ?? 0;
+  const importsCount = relCounts.find((r) => r.type === 'imports')?.count ?? 0;
+  const extendsCount = relCounts.find((r) => r.type === 'extends')?.count ?? 0;
+
+  const freshnessLabel = meta.last_indexed_at ? meta.last_indexed_at.slice(0, 10) : 'unknown';
+
+  lines.push('## Index Status');
+  lines.push('');
+  lines.push(`- **Files**: ${meta.file_count.toLocaleString()} indexed`);
+  lines.push(
+    `- **Symbols**: ${meta.total_nodes.toLocaleString()} total${symbolBreakdown ? ` (${symbolBreakdown})` : ''}`,
+  );
+  lines.push(
+    `- **Relations**: ${meta.total_relations.toLocaleString()} total (calls: ${callsCount.toLocaleString()}, imports: ${importsCount.toLocaleString()}, extends: ${extendsCount.toLocaleString()})`,
+  );
+  lines.push(`- **Communities**: ${communities.length} functional clusters`);
+  lines.push(`- **Execution Flows**: ${processCount} traced processes`);
+  lines.push(`- **Last Indexed**: ${meta.last_indexed_at ?? 'never'}`);
+  lines.push(`- **Date**: ${freshnessLabel}`);
+  lines.push('');
+
+  // --- Top Entry Points ---
+  const entryPoints = queryTopEntryPoints(nativeDb, projectId);
+  if (entryPoints.length > 0) {
+    lines.push('## Top Entry Points');
+    lines.push('');
+    entryPoints.forEach((ep, i) => {
+      const name = ep.name ?? '(unknown)';
+      const filePath = ep.file_path ?? '';
+      const displayPath = filePath.length > 60 ? `...${filePath.slice(-57)}` : filePath;
+      lines.push(`${i + 1}. \`${name}\` — ${displayPath} (${ep.callees} callees)`);
+    });
+    lines.push('');
+  }
+
+  // --- Functional Clusters ---
+  if (communities.length > 0) {
+    lines.push('## Functional Clusters');
+    lines.push('');
+    communities.forEach((c, i) => {
+      let symbolCount = 0;
+      let topFolder = '';
+      try {
+        if (c.meta_json) {
+          const meta = JSON.parse(c.meta_json) as Record<string, unknown>;
+          symbolCount = typeof meta['symbolCount'] === 'number' ? meta['symbolCount'] : 0;
+          const folders = meta['topFolders'];
+          if (Array.isArray(folders) && folders.length > 0) {
+            topFolder = String(folders[0]);
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+      const symbolsLabel = symbolCount > 0 ? ` (${symbolCount} symbols)` : '';
+      const folderLabel = topFolder ? ` — ${topFolder}` : '';
+      lines.push(`${i + 1}. **${c.label}**${symbolsLabel}${folderLabel}`);
+    });
+    lines.push('');
+  }
+
+  // --- Code Intelligence Commands ---
+  lines.push('## Code Intelligence Commands');
+  lines.push('');
+  lines.push('| Need | Command |');
+  lines.push('|------|---------|');
+  lines.push('| What calls this function? | `cleo nexus context <symbol>` |');
+  lines.push('| What breaks if I change this? | `cleo nexus impact <symbol>` |');
+  lines.push('| What functional areas exist? | `cleo nexus clusters` |');
+  lines.push('| What execution flows exist? | `cleo nexus flows` |');
+  lines.push('| Re-index after code changes | `cleo nexus analyze` |');
+  lines.push('| Index freshness check | `cleo nexus status` |');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Write nexus bridge content to .cleo/nexus-bridge.md.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param projectId - Project registry ID (used to scope nexus.db queries)
+ * @returns Result with path and whether the file was written
+ */
+export async function writeNexusBridge(
+  projectRoot: string,
+  projectId?: string,
+): Promise<{ path: string; written: boolean }> {
+  const cleoDir = join(projectRoot, '.cleo');
+  const bridgePath = join(cleoDir, 'nexus-bridge.md');
+
+  // Derive project ID from path if not provided (matches nexus analyze convention)
+  const resolvedProjectId =
+    projectId ?? Buffer.from(projectRoot).toString('base64url').slice(0, 32);
+
+  try {
+    const content = await generateNexusBridgeContent(resolvedProjectId, projectRoot);
+
+    if (!existsSync(cleoDir)) {
+      mkdirSync(cleoDir, { recursive: true });
+    }
+
+    // Only write if content changed (avoid unnecessary git noise)
+    if (existsSync(bridgePath)) {
+      const existing = readFileSync(bridgePath, 'utf-8');
+      // Compare without the date line since it changes daily
+      const stripDate = (s: string) => s.replace(/^> Date: .*/m, '');
+      if (stripDate(existing) === stripDate(content)) {
+        return { path: bridgePath, written: false };
+      }
+    }
+
+    writeFileSync(bridgePath, content, 'utf-8');
+    return { path: bridgePath, written: true };
+  } catch (err) {
+    console.error(
+      '[CLEO] Failed to write nexus bridge:',
+      err instanceof Error ? err.message : String(err),
+    );
+    return { path: bridgePath, written: false };
+  }
+}
+
+/**
+ * Best-effort nexus bridge refresh. Never throws.
+ * Called after cleo nexus analyze completes.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param projectId - Project registry ID (used to scope nexus.db queries)
+ */
+export async function refreshNexusBridge(projectRoot: string, projectId?: string): Promise<void> {
+  try {
+    await writeNexusBridge(projectRoot, projectId);
+  } catch (err) {
+    console.error(
+      '[CLEO] Nexus bridge refresh failed:',
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/** Build placeholder content when no index data exists. */
+function buildEmptyBridge(repoPath: string): string {
+  return [
+    '# CLEO Nexus Bridge — Code Intelligence',
+    '',
+    `> Auto-generated from nexus index. Regenerate with \`cleo nexus analyze\`.`,
+    `> Project: ${repoPath}`,
+    '',
+    '## Index Status',
+    '',
+    'Not indexed. Run `cleo nexus analyze` to build the code intelligence index.',
+    '',
+    '## Code Intelligence Commands',
+    '',
+    '| Need | Command |',
+    '|------|---------|',
+    '| Build the index | `cleo nexus analyze` |',
+    '| Check index status | `cleo nexus status` |',
+    '| What calls this function? | `cleo nexus context <symbol>` |',
+    '| What breaks if I change this? | `cleo nexus impact <symbol>` |',
+    '| What functional areas exist? | `cleo nexus clusters` |',
+    '| What execution flows exist? | `cleo nexus flows` |',
+    '',
+  ].join('\n');
+}

package/src/scaffold.ts

@@ -1348,6 +1348,48 @@ export function checkMemoryBridge(projectRoot: string): CheckResult {
   };
 }
 
+/**
+ * Verify .cleo/nexus-bridge.md exists.
+ * Warning level if missing (not failure) — it is auto-generated after `cleo nexus analyze`.
+ *
+ * @param projectRoot - Absolute path to the project root directory
+ * @returns Check result indicating presence of the nexus bridge file
+ *
+ * @remarks
+ * Read-only diagnostic. The nexus bridge is auto-generated from nexus.db
+ * content after `cleo nexus analyze` runs, so its absence is only a warning.
+ *
+ * @example
+ * ```typescript
+ * const check = checkNexusBridge('/my/project');
+ * if (check.status === 'warning') console.log('Run: cleo nexus analyze');
+ * ```
+ */
+export function checkNexusBridge(projectRoot: string): CheckResult {
+  const cleoDir = getCleoDirAbsolute(projectRoot);
+  const bridgePath = join(cleoDir, 'nexus-bridge.md');
+
+  if (!existsSync(bridgePath)) {
+    return {
+      id: 'nexus_bridge',
+      category: 'scaffold',
+      status: 'warning',
+      message: 'nexus-bridge.md not found',
+      details: { path: bridgePath, exists: false },
+      fix: 'cleo nexus analyze',
+    };
+  }
+
+  return {
+    id: 'nexus_bridge',
+    category: 'scaffold',
+    status: 'passed',
+    message: 'nexus-bridge.md exists',
+    details: { path: bridgePath, exists: true },
+    fix: null,
+  };
+}
+
 // ── Global (~/.cleo) scaffold functions ──────────────────────────────
 
 /**

package/src/sessions/__tests__/session-memory-bridge.test.ts

@@ -1,61 +1,39 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-const mocks = vi.hoisted(() => ({
-  observeBrain: vi.fn(),
-}));
-
-vi.mock('../../memory/brain-retrieval.js', () => ({
-  observeBrain: mocks.observeBrain,
-}));
+import { describe, expect, it } from 'vitest';
 
 import { bridgeSessionToMemory } from '../session-memory-bridge.js';
 
+/**
+ * T527: bridgeSessionToMemory is now a no-op. Session data already lives in
+ * the sessions table; the duplicate observeBrain write and extractSessionEndMemory
+ * call were removed to reduce brain.db noise.
+ *
+ * These tests verify the function remains safe to call from sessions/index.ts
+ * without throwing.
+ */
 describe('bridgeSessionToMemory', () => {
-  beforeEach(() => {
-    mocks.observeBrain.mockReset();
-  });
-
-  it('records a session summary observation on success', async () => {
-    mocks.observeBrain.mockResolvedValue(undefined);
-
-    await bridgeSessionToMemory('/tmp/project', {
-      sessionId: 'session-100',
-      scope: 'epic:T5417',
-      tasksCompleted: ['T5464', 'T5466'],
-      duration: 125,
-    });
-
-    expect(mocks.observeBrain).toHaveBeenCalledTimes(1);
-    expect(mocks.observeBrain).toHaveBeenCalledWith('/tmp/project', {
-      text: 'Session session-100 ended. Scope: epic:T5417. Duration: 2 min. Tasks completed: T5464, T5466.',
-      title: 'Session summary: session-100',
-      type: 'change',
-      sourceSessionId: 'session-100',
-      sourceType: 'agent',
-    });
+  it('resolves without throwing for a normal session', async () => {
+    await expect(
+      bridgeSessionToMemory('/tmp/project', {
+        sessionId: 'session-100',
+        scope: 'epic:T5417',
+        tasksCompleted: ['T5464', 'T5466'],
+        duration: 125,
+      }),
+    ).resolves.toBeUndefined();
   });
 
-  it('uses "none" for empty task completion lists', async () => {
-    mocks.observeBrain.mockResolvedValue(undefined);
-
-    await bridgeSessionToMemory('/tmp/project', {
-      sessionId: 'session-101',
-      scope: 'global',
-      tasksCompleted: [],
-      duration: 59,
-    });
-
-    expect(mocks.observeBrain).toHaveBeenCalledWith(
-      '/tmp/project',
-      expect.objectContaining({
-        text: 'Session session-101 ended. Scope: global. Duration: 1 min. Tasks completed: none.',
+  it('resolves without throwing for empty task completion list', async () => {
+    await expect(
+      bridgeSessionToMemory('/tmp/project', {
+        sessionId: 'session-101',
+        scope: 'global',
+        tasksCompleted: [],
+        duration: 59,
       }),
-    );
+    ).resolves.toBeUndefined();
   });
 
-  it('swallows persistence errors to preserve session-end flow', async () => {
-    mocks.observeBrain.mockRejectedValue(new Error('database is locked'));
-
+  it('resolves without throwing even when called with minimal data', async () => {
     await expect(
       bridgeSessionToMemory('/tmp/project', {
         sessionId: 'session-102',

package/src/sessions/session-memory-bridge.ts

@@ -1,16 +1,19 @@
 /**
- * Memory-session bridge — records session summaries as brain observations.
+ * Memory-session bridge — no-op placeholder retained for call-site compatibility.
  *
- * Hooks into the session end flow to persist a summary of the session's
- * work (tasks completed, scope, duration) into brain.db as an observation.
- * This is best-effort: failures do not affect the session end operation.
+ * Previously this function wrote a session summary observation to brain.db and
+ * triggered auto-extraction of structured memory. Both were removed in T527
+ * because session data already lives in the sessions table; duplicating it to
+ * brain_observations was pure noise.
+ *
+ * The function is kept (as a no-op) so callers in sessions/index.ts do not need
+ * to be updated in this task.
  *
  * @task T5392
  * @epic T5149
+ * @see T527 — removal of duplicate session observation writes
  */
 
-import { observeBrain } from '../memory/brain-retrieval.js';
-
 /** Session data needed to create a memory bridge observation. */
 export interface SessionBridgeData {
   sessionId: string;
@@ -20,50 +23,19 @@ export interface SessionBridgeData {
 }
 
 /**
- * Bridge session end data to brain.db as an observation.
+ * Bridge session end data — currently a no-op.
  *
- * Builds a summary text from the session metadata and saves it
- * as a 'change' observation with source_type 'agent'.
+ * Retained for call-site compatibility. Previously wrote a duplicate summary
+ * observation to brain.db and triggered extractSessionEndMemory; both were
+ * removed in T527 to reduce brain.db noise.
  *
- * @param projectRoot - Project root directory for brain.db resolution
- * @param sessionData - Session metadata to record
+ * @param _projectRoot - Project root directory (unused)
+ * @param _sessionData - Session metadata (unused)
  */
 export async function bridgeSessionToMemory(
-  projectRoot: string,
-  sessionData: SessionBridgeData,
+  _projectRoot: string,
+  _sessionData: SessionBridgeData,
 ): Promise<void> {
-  try {
-    const taskList =
-      sessionData.tasksCompleted.length > 0 ? sessionData.tasksCompleted.join(', ') : 'none';
-
-    const durationMinutes = Math.round(sessionData.duration / 60);
-
-    const summary = [
-      `Session ${sessionData.sessionId} ended.`,
-      `Scope: ${sessionData.scope}.`,
-      `Duration: ${durationMinutes} min.`,
-      `Tasks completed: ${taskList}.`,
-    ].join(' ');
-
-    await observeBrain(projectRoot, {
-      text: summary,
-      title: `Session summary: ${sessionData.sessionId}`,
-      type: 'change',
-      sourceSessionId: sessionData.sessionId,
-      sourceType: 'agent',
-    });
-
-    // Auto-extract structured memory from session end (best-effort)
-    try {
-      const { extractSessionEndMemory, resolveTaskDetails } = await import(
-        '../memory/auto-extract.js'
-      );
-      const taskDetails = await resolveTaskDetails(projectRoot, sessionData.tasksCompleted);
-      await extractSessionEndMemory(projectRoot, sessionData, taskDetails);
-    } catch {
-      /* Session memory extraction is best-effort */
-    }
-  } catch {
-    // Best-effort: session bridge must never fail the session end flow
-  }
+  // T527: Intentional no-op. Session data is already in the sessions table.
+  // Removed: observeBrain duplicate write and extractSessionEndMemory call.
 }