code-graph-context 2.2.0 → 2.4.0

package/README.md

@@ -30,6 +30,7 @@ A Model Context Protocol (MCP) server that builds rich code graphs to provide de
 - **Impact Analysis**: Assess refactoring risk with dependency analysis (LOW/MEDIUM/HIGH/CRITICAL scoring)
 - **Dead Code Detection**: Find unreferenced exports, uncalled private methods, unused interfaces with confidence scoring
 - **Duplicate Code Detection**: Identify structural duplicates (identical AST) and semantic duplicates (similar logic via embeddings)
+- **Swarm Coordination**: Multi-agent stigmergic coordination through pheromone markers with exponential decay
 - **High Performance**: Optimized Neo4j storage with vector indexing for fast retrieval
 - **MCP Integration**: Seamless integration with Claude Code and other MCP-compatible tools
 
@@ -64,100 +65,90 @@ The system uses a dual-schema approach:
 
 Choose the installation method that works best for you:
 
-#### Option 1: Development Install (From Source)
+#### Option 1: NPM Install (Recommended)
 
-Best for: Contributing to the project or customizing the code
-
-1. **Clone the repository:**
 ```bash
-git clone https://github.com/drewdrewH/code-graph-context.git
-cd code-graph-context
-```
+# Install globally
+npm install -g code-graph-context
 
-2. **Install dependencies:**
-```bash
-npm install
+# Set up Neo4j (requires Docker)
+code-graph-context init
+
+# Add to Claude Code
+claude mcp add code-graph-context code-graph-context
 ```
 
-3. **Set up Neo4j using Docker:**
-```bash
-docker-compose up -d
+Then configure your OpenAI API key in `~/.config/claude/config.json`:
+```json
+{
+  "mcpServers": {
+    "code-graph-context": {
+      "command": "code-graph-context",
+      "env": {
+        "OPENAI_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
 ```
 
-This will start Neo4j with:
-- Web interface: http://localhost:7474
-- Bolt connection: bolt://localhost:7687
-- Username: `neo4j`, Password: `PASSWORD`
+#### Option 2: From Source
 
-4. **Configure environment variables:**
 ```bash
-cp .env.example .env
-# Edit .env with your configuration
+# Clone and build
+git clone https://github.com/drewdrewH/code-graph-context.git
+cd code-graph-context
+npm install
+npm run build
+
+# Set up Neo4j
+code-graph-context init
+
+# Add to Claude Code (use absolute path)
+claude mcp add code-graph-context node /absolute/path/to/code-graph-context/dist/cli/cli.js
 ```
 
-5. **Build the project:**
+### CLI Commands
+
+The package includes a CLI for managing Neo4j:
+
 ```bash
-npm run build
+code-graph-context init [options]   # Set up Neo4j container
+code-graph-context status           # Check Docker/Neo4j status
+code-graph-context stop             # Stop Neo4j container
 ```
 
-6. **Add to Claude Code:**
-```bash
-claude mcp add code-graph-context node /absolute/path/to/code-graph-context/dist/mcp/mcp.server.js
+**Init options:**
+```
+-p, --port <port>       Bolt port (default: 7687)
+--http-port <port>      Browser port (default: 7474)
+--password <password>   Neo4j password (default: PASSWORD)
+-m, --memory <size>     Heap memory (default: 2G)
+-f, --force             Recreate container
 ```
 
-#### Option 2: NPM Install (Global Package)
+### Alternative Neo4j Setup
 
-Best for: Easy setup and automatic updates
+If you prefer not to use the CLI, you can set up Neo4j manually:
 
-1. **Install the package globally:**
+**Docker Compose:**
 ```bash
-npm install -g code-graph-context
+docker-compose up -d
 ```
 
-2. **Set up Neo4j** (choose one):
-
-**Option A: Docker (Recommended)**
+**Docker Run:**
 ```bash
 docker run -d \
   --name code-graph-neo4j \
   -p 7474:7474 -p 7687:7687 \
   -e NEO4J_AUTH=neo4j/PASSWORD \
-  -e NEO4J_PLUGINS='["apoc"]' \
+  -e 'NEO4J_PLUGINS=["apoc"]' \
   neo4j:5.23
 ```
 
-**Option B: Neo4j Desktop**
-- Download from [neo4j.com/download](https://neo4j.com/download/)
-- Install APOC plugin
-- Start database
+**Neo4j Desktop:** Download from [neo4j.com/download](https://neo4j.com/download/) and install APOC plugin.
 
-**Option C: Neo4j Aura (Cloud)**
-- Create free account at [neo4j.com/cloud/aura](https://neo4j.com/cloud/platform/aura-graph-database/)
-- Note your connection URI and credentials
-
-3. **Add to Claude Code:**
-```bash
-claude mcp add code-graph-context code-graph-context
-```
-
-Then configure in your MCP config file (`~/.config/claude/config.json`):
-```json
-{
-  "mcpServers": {
-    "code-graph-context": {
-      "command": "code-graph-context",
-      "env": {
-        "OPENAI_API_KEY": "sk-your-key-here",
-        "NEO4J_URI": "bolt://localhost:7687",
-        "NEO4J_USER": "neo4j",
-        "NEO4J_PASSWORD": "PASSWORD"
-      }
-    }
-  }
-}
-```
-
-**Note:** The env vars can be configured for any Neo4j instance - local, Docker, cloud (Aura), or enterprise.
+**Neo4j Aura (Cloud):** Create account at [neo4j.com/cloud/aura](https://neo4j.com/cloud/platform/aura-graph-database/) and configure connection URI in env vars.
 
 ### Verify Installation
 
@@ -255,6 +246,9 @@ npm run build
 | `natural_language_to_cypher` | Convert natural language to Cypher | **Advanced queries** - complex graph queries |
 | `detect_dead_code` | Find unreferenced exports, uncalled methods, unused interfaces | **Code cleanup** - identify potentially removable code |
 | `detect_duplicate_code` | Find structural and semantic code duplicates | **Refactoring** - identify DRY violations |
+| `swarm_pheromone` | Leave pheromone markers on code nodes | **Multi-agent** - stigmergic coordination |
+| `swarm_sense` | Query pheromones in the code graph | **Multi-agent** - sense what other agents are doing |
+| `swarm_cleanup` | Bulk delete pheromones | **Multi-agent** - cleanup after swarm completion |
 | `test_neo4j_connection` | Verify database connectivity | **Health check** - troubleshooting |
 
 > **Note**: All query tools (`search_codebase`, `traverse_from_node`, `impact_analysis`, `natural_language_to_cypher`) require a `projectId` parameter. Use `list_projects` to discover available projects.
@@ -755,6 +749,67 @@ await mcp.call('stop_watch_project', {
 - 1000 pending events per watcher
 - Graceful cleanup on server shutdown
 
+#### 8. Swarm Coordination Tools
+**Purpose**: Enable multiple parallel agents to coordinate work through stigmergic pheromone markers in the code graph—no direct messaging needed.
+
+**Core Concepts:**
+- **Pheromones**: Markers attached to graph nodes that decay over time
+- **swarmId**: Groups related agents for bulk cleanup when done
+- **Workflow States**: `exploring`, `claiming`, `modifying`, `completed`, `blocked` (mutually exclusive per agent+node)
+- **Flags**: `warning`, `proposal`, `needs_review` (can coexist with workflow states)
+
+**Pheromone Types & Decay:**
+| Type | Half-Life | Use |
+|------|-----------|-----|
+| `exploring` | 2 min | Browsing/reading |
+| `modifying` | 10 min | Active work |
+| `claiming` | 1 hour | Ownership |
+| `completed` | 24 hours | Done |
+| `warning` | Never | Danger |
+| `blocked` | 5 min | Stuck |
+| `proposal` | 1 hour | Awaiting approval |
+| `needs_review` | 30 min | Review requested |
+
+```typescript
+// Orchestrator: Generate swarm ID and spawn agents
+const swarmId = `swarm_${Date.now()}`;
+
+// Agent: Check what's claimed before working
+await mcp.call('swarm_sense', {
+  projectId: 'my-backend',
+  swarmId,
+  types: ['claiming', 'modifying']
+});
+
+// Agent: Claim a node before working
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',  // From search_codebase or traverse_from_node
+  type: 'claiming',
+  agentId: 'agent_1',
+  swarmId
+});
+
+// Agent: Mark complete when done
+await mcp.call('swarm_pheromone', {
+  projectId: 'my-backend',
+  nodeId: 'proj_xxx:ClassDeclaration:abc123',
+  type: 'completed',
+  agentId: 'agent_1',
+  swarmId,
+  data: { summary: 'Added soft delete support' }
+});
+
+// Orchestrator: Clean up when swarm is done
+await mcp.call('swarm_cleanup', {
+  projectId: 'my-backend',
+  swarmId,
+  keepTypes: ['warning']  // Preserve warnings
+});
+```
+
+**Important**: Node IDs must come from graph tool responses (`search_codebase`, `traverse_from_node`). Never fabricate node IDs—they are hash-based strings like `proj_xxx:ClassDeclaration:abc123`.
+
 ### Workflow Examples
 
 #### Example 1: Understanding Authentication Flow

package/dist/cli/cli.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+/**
+ * CLI Entry Point for Code Graph Context
+ *
+ * Handles CLI commands (init, status, stop) and delegates to MCP server
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { NEO4J_CONFIG, createContainer, getContainerStatus, getFullStatus, isApocAvailable, isDockerInstalled, isDockerRunning, removeContainer, startContainer, stopContainer, waitForNeo4j, } from './neo4j-docker.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// ANSI colors
+const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+};
+const sym = {
+    ok: `${c.green}✓${c.reset}`,
+    err: `${c.red}✗${c.reset}`,
+    warn: `${c.yellow}⚠${c.reset}`,
+    info: `${c.blue}ℹ${c.reset}`,
+};
+const log = (symbol, msg) => {
+    console.log(`  ${symbol} ${msg}`);
+};
+const header = (text) => {
+    console.log(`\n${c.bold}${text}${c.reset}\n`);
+};
+/**
+ * Spinner for async operations
+ */
+const spinner = (msg) => {
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    let i = 0;
+    const interval = setInterval(() => {
+        process.stdout.write(`\r  ${c.blue}${frames[i]}${c.reset} ${msg}`);
+        i = (i + 1) % frames.length;
+    }, 80);
+    return {
+        stop: (ok, finalMsg) => {
+            clearInterval(interval);
+            process.stdout.write(`\r  ${ok ? sym.ok : sym.err} ${finalMsg || msg}\n`);
+        },
+    };
+};
+/**
+ * Print config instructions
+ */
+const printConfigInstructions = (password, boltPort) => {
+    console.log(`
+${c.bold}Next steps:${c.reset}
+
+  1. Add to Claude Code:
+     ${c.dim}claude mcp add code-graph-context code-graph-context${c.reset}
+
+  2. Configure in ${c.cyan}~/.config/claude/config.json${c.reset}:
+
+     ${c.dim}{
+       "mcpServers": {
+         "code-graph-context": {
+           "command": "code-graph-context",
+           "env": {
+             "OPENAI_API_KEY": "sk-..."${password !== NEO4J_CONFIG.defaultPassword
+        ? `,
+             "NEO4J_PASSWORD": "${password}"`
+        : ''}${boltPort !== NEO4J_CONFIG.boltPort
+        ? `,
+             "NEO4J_URI": "bolt://localhost:${boltPort}"`
+        : ''}
+           }
+         }
+       }
+     }${c.reset}
+
+     ${c.yellow}Get your OpenAI API key:${c.reset} https://platform.openai.com/api-keys
+
+  3. Restart Claude Code
+`);
+};
+/**
+ * Init command - set up Neo4j
+ */
+const runInit = async (options) => {
+    const boltPort = options.port ? parseInt(options.port, 10) : NEO4J_CONFIG.boltPort;
+    const httpPort = options.httpPort ? parseInt(options.httpPort, 10) : NEO4J_CONFIG.httpPort;
+    const password = options.password || NEO4J_CONFIG.defaultPassword;
+    const memory = options.memory || '4G';
+    header('Code Graph Context Setup');
+    // Check Docker
+    if (!isDockerInstalled()) {
+        log(sym.err, 'Docker is not installed');
+        console.log(`\n  Install Docker: ${c.cyan}https://docs.docker.com/get-docker/${c.reset}\n`);
+        process.exit(1);
+    }
+    log(sym.ok, 'Docker installed');
+    if (!isDockerRunning()) {
+        log(sym.err, 'Docker daemon is not running');
+        console.log(`\n  Start Docker Desktop or run: ${c.dim}sudo systemctl start docker${c.reset}\n`);
+        process.exit(1);
+    }
+    log(sym.ok, 'Docker daemon running');
+    // Handle existing container
+    const status = getContainerStatus();
+    if (status === 'running' && !options.force) {
+        log(sym.ok, 'Neo4j container already running');
+        const apocOk = isApocAvailable(NEO4J_CONFIG.containerName, password);
+        log(apocOk ? sym.ok : sym.warn, apocOk ? 'APOC plugin available' : 'APOC plugin not detected');
+        console.log(`\n  ${c.dim}Use --force to recreate the container${c.reset}`);
+        printConfigInstructions(password, boltPort);
+        return;
+    }
+    if (status !== 'not-found' && options.force) {
+        const s = spinner('Removing existing container...');
+        stopContainer();
+        removeContainer();
+        s.stop(true, 'Removed existing container');
+    }
+    if (status === 'stopped' && !options.force) {
+        const s = spinner('Starting existing container...');
+        const started = startContainer();
+        if (!started) {
+            s.stop(false, 'Failed to start container');
+            console.log(`\n  Try: ${c.dim}code-graph-context init --force${c.reset}\n`);
+            process.exit(1);
+        }
+        s.stop(true, 'Container started');
+    }
+    else if (status === 'not-found' || options.force) {
+        const s = spinner('Creating Neo4j container...');
+        const created = createContainer({ httpPort, boltPort, password, memory });
+        if (!created) {
+            s.stop(false, 'Failed to create container');
+            console.log(`
+  Check if ports are in use:
+    ${c.dim}lsof -i :${httpPort}${c.reset}
+    ${c.dim}lsof -i :${boltPort}${c.reset}
+`);
+            process.exit(1);
+        }
+        s.stop(true, 'Container created');
+    }
+    // Wait for Neo4j
+    const healthSpinner = spinner('Waiting for Neo4j to be ready (this may take a minute)...');
+    const ready = await waitForNeo4j(NEO4J_CONFIG.containerName, password);
+    healthSpinner.stop(ready, ready ? 'Neo4j is ready' : 'Neo4j failed to start');
+    if (!ready) {
+        console.log(`\n  Check logs: ${c.dim}docker logs ${NEO4J_CONFIG.containerName}${c.reset}\n`);
+        process.exit(1);
+    }
+    // Check APOC
+    const apocOk = isApocAvailable(NEO4J_CONFIG.containerName, password);
+    log(apocOk ? sym.ok : sym.warn, apocOk ? 'APOC plugin verified' : 'APOC still loading (should be ready shortly)');
+    // Print connection info
+    console.log(`
+${c.bold}Neo4j is ready${c.reset}
+
+  Browser:     ${c.cyan}http://localhost:${httpPort}${c.reset}
+  Bolt URI:    ${c.cyan}bolt://localhost:${boltPort}${c.reset}
+  Credentials: ${c.dim}neo4j / ${password}${c.reset}`);
+    printConfigInstructions(password, boltPort);
+};
+/**
+ * Status command
+ */
+const runStatus = () => {
+    header('Code Graph Context Status');
+    const status = getFullStatus();
+    log(status.dockerInstalled ? sym.ok : sym.err, `Docker installed: ${status.dockerInstalled ? 'yes' : 'no'}`);
+    if (!status.dockerInstalled) {
+        console.log(`\n  Install: ${c.cyan}https://docs.docker.com/get-docker/${c.reset}\n`);
+        return;
+    }
+    log(status.dockerRunning ? sym.ok : sym.err, `Docker running: ${status.dockerRunning ? 'yes' : 'no'}`);
+    if (!status.dockerRunning) {
+        console.log(`\n  Start Docker Desktop or: ${c.dim}sudo systemctl start docker${c.reset}\n`);
+        return;
+    }
+    const containerIcon = status.containerStatus === 'running' ? sym.ok : status.containerStatus === 'stopped' ? sym.warn : sym.err;
+    log(containerIcon, `Container: ${status.containerStatus}`);
+    if (status.containerStatus === 'running') {
+        log(status.neo4jReady ? sym.ok : sym.warn, `Neo4j responding: ${status.neo4jReady ? 'yes' : 'no'}`);
+        log(status.apocAvailable ? sym.ok : sym.warn, `APOC plugin: ${status.apocAvailable ? 'available' : 'not available'}`);
+    }
+    console.log('');
+    if (status.containerStatus !== 'running') {
+        console.log(`  Run ${c.dim}code-graph-context init${c.reset} to start Neo4j\n`);
+    }
+    else if (!status.apocAvailable) {
+        console.log(`  APOC may still be loading. Wait a moment and check again.\n`);
+    }
+};
+/**
+ * Stop command
+ */
+const runStop = () => {
+    const status = getContainerStatus();
+    if (status === 'not-found') {
+        log(sym.info, 'No Neo4j container found');
+        return;
+    }
+    if (status === 'stopped') {
+        log(sym.info, 'Container already stopped');
+        return;
+    }
+    const s = spinner('Stopping Neo4j...');
+    const stopped = stopContainer();
+    s.stop(stopped, stopped ? 'Neo4j stopped' : 'Failed to stop container');
+};
+/**
+ * Start MCP server
+ */
+const startMcpServer = async () => {
+    // The MCP server is in a sibling directory after build
+    // cli/cli.js -> mcp/mcp.server.js
+    const mcpPath = join(__dirname, '..', 'mcp', 'mcp.server.js');
+    await import(mcpPath);
+};
+/**
+ * Get package version
+ */
+const getVersion = () => {
+    try {
+        // Go up from dist/cli to root
+        const pkgPath = join(__dirname, '..', '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version;
+    }
+    catch {
+        return 'unknown';
+    }
+};
+// Build CLI
+const program = new Command();
+program.name('code-graph-context').description('MCP server for code graph analysis with Neo4j').version(getVersion());
+program
+    .command('init')
+    .description('Set up Neo4j container and show configuration steps')
+    .option('-p, --port <port>', 'Neo4j Bolt port', '7687')
+    .option('--http-port <port>', 'Neo4j Browser port', '7474')
+    .option('--password <password>', 'Neo4j password', 'PASSWORD')
+    .option('-m, --memory <size>', 'Max heap memory (e.g., 2G, 4G)', '2G')
+    .option('-f, --force', 'Recreate container even if exists')
+    .action(runInit);
+program.command('status').description('Check Neo4j and Docker status').action(runStatus);
+program.command('stop').description('Stop the Neo4j container').action(runStop);
+// Default action: start MCP server if no command given
+const knownCommands = ['init', 'status', 'stop', 'help'];
+const args = process.argv.slice(2);
+const hasCommand = args.some((arg) => knownCommands.includes(arg) || arg.startsWith('-'));
+if (args.length === 0 || !hasCommand) {
+    startMcpServer().catch((err) => {
+        console.error('Failed to start MCP server:', err);
+        process.exit(1);
+    });
+}
+else {
+    program.parse();
+}

package/dist/cli/neo4j-docker.js

@@ -0,0 +1,159 @@
+/**
+ * Neo4j Docker Management
+ *
+ * Handles Docker container lifecycle for Neo4j
+ */
+import { execSync } from 'child_process';
+// Container configuration
+export const NEO4J_CONFIG = {
+    containerName: 'code-graph-neo4j',
+    image: 'neo4j:5.23',
+    httpPort: 7474,
+    boltPort: 7687,
+    defaultPassword: 'PASSWORD',
+    defaultUser: 'neo4j',
+    healthCheckTimeoutMs: 120000,
+    healthCheckIntervalMs: 2000,
+};
+/**
+ * Execute a command and return stdout, or null if failed
+ */
+const exec = (command) => {
+    try {
+        return execSync(command, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Check if Docker CLI is available
+ */
+export const isDockerInstalled = () => exec('docker --version') !== null;
+/**
+ * Check if Docker daemon is running
+ */
+export const isDockerRunning = () => exec('docker info') !== null;
+/**
+ * Get container status
+ */
+export const getContainerStatus = (containerName = NEO4J_CONFIG.containerName) => {
+    const result = exec(`docker inspect --format='{{.State.Running}}' ${containerName} 2>/dev/null`);
+    if (result === null)
+        return 'not-found';
+    return result === 'true' ? 'running' : 'stopped';
+};
+/**
+ * Start an existing stopped container
+ */
+export const startContainer = (containerName = NEO4J_CONFIG.containerName) => exec(`docker start ${containerName}`) !== null;
+/**
+ * Stop a running container
+ */
+export const stopContainer = (containerName = NEO4J_CONFIG.containerName) => exec(`docker stop ${containerName}`) !== null;
+/**
+ * Remove a container
+ */
+export const removeContainer = (containerName = NEO4J_CONFIG.containerName) => exec(`docker rm ${containerName}`) !== null;
+/**
+ * Create and start a new Neo4j container
+ */
+export const createContainer = (options = {}) => {
+    const { containerName = NEO4J_CONFIG.containerName, httpPort = NEO4J_CONFIG.httpPort, boltPort = NEO4J_CONFIG.boltPort, password = NEO4J_CONFIG.defaultPassword, memory = '2G', } = options;
+    const cmd = [
+        'docker run -d',
+        `--name ${containerName}`,
+        `--restart unless-stopped`,
+        `-p ${httpPort}:7474`,
+        `-p ${boltPort}:7687`,
+        `-e NEO4J_AUTH=neo4j/${password}`,
+        `-e 'NEO4J_PLUGINS=["apoc"]'`,
+        `-e NEO4J_dbms_security_procedures_unrestricted=apoc.*`,
+        `-e NEO4J_server_memory_heap_initial__size=1G`,
+        `-e NEO4J_server_memory_heap_max__size=${memory}`,
+        `-e NEO4J_server_memory_pagecache_size=2G`,
+        NEO4J_CONFIG.image,
+    ].join(' ');
+    return exec(cmd) !== null;
+};
+/**
+ * Check if Neo4j is accepting connections
+ */
+export const isNeo4jReady = (containerName = NEO4J_CONFIG.containerName, password = NEO4J_CONFIG.defaultPassword) => {
+    const result = exec(`docker exec ${containerName} cypher-shell -u neo4j -p ${password} "RETURN 1" 2>/dev/null`);
+    return result !== null;
+};
+/**
+ * Check if APOC plugin is available
+ */
+export const isApocAvailable = (containerName = NEO4J_CONFIG.containerName, password = NEO4J_CONFIG.defaultPassword) => {
+    const result = exec(`docker exec ${containerName} cypher-shell -u neo4j -p ${password} "CALL apoc.help('apoc') YIELD name RETURN count(name)" 2>/dev/null`);
+    return result !== null && !result.includes('error');
+};
+/**
+ * Wait for Neo4j to be ready
+ */
+export const waitForNeo4j = async (containerName = NEO4J_CONFIG.containerName, password = NEO4J_CONFIG.defaultPassword, timeoutMs = NEO4J_CONFIG.healthCheckTimeoutMs) => {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        if (isNeo4jReady(containerName, password)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, NEO4J_CONFIG.healthCheckIntervalMs));
+    }
+    return false;
+};
+/**
+ * Ensure Neo4j is running - start if needed
+ */
+export const ensureNeo4jRunning = async (options = {}) => {
+    const containerName = options.containerName ?? NEO4J_CONFIG.containerName;
+    const status = getContainerStatus(containerName);
+    if (status === 'running') {
+        return { success: true, action: 'already-running' };
+    }
+    if (!isDockerInstalled()) {
+        return { success: false, action: 'failed', error: 'Docker not installed' };
+    }
+    if (!isDockerRunning()) {
+        return { success: false, action: 'failed', error: 'Docker daemon not running' };
+    }
+    // Start existing container
+    if (status === 'stopped') {
+        if (startContainer(containerName)) {
+            const ready = await waitForNeo4j(containerName, options.password);
+            return ready
+                ? { success: true, action: 'started' }
+                : { success: false, action: 'failed', error: 'Container started but Neo4j not responding' };
+        }
+        return { success: false, action: 'failed', error: 'Failed to start existing container' };
+    }
+    // Create new container
+    if (createContainer(options)) {
+        const ready = await waitForNeo4j(containerName, options.password);
+        return ready
+            ? { success: true, action: 'created' }
+            : { success: false, action: 'failed', error: 'Container created but Neo4j not responding' };
+    }
+    return { success: false, action: 'failed', error: 'Failed to create container' };
+};
+/**
+ * Get full status for diagnostics
+ */
+export const getFullStatus = () => {
+    const dockerInstalled = isDockerInstalled();
+    const dockerRunning = dockerInstalled && isDockerRunning();
+    const containerStatus = dockerRunning ? getContainerStatus() : 'not-found';
+    const neo4jReady = containerStatus === 'running' && isNeo4jReady();
+    const apocAvailable = neo4jReady && isApocAvailable();
+    return {
+        dockerInstalled,
+        dockerRunning,
+        containerStatus,
+        neo4jReady,
+        apocAvailable,
+    };
+};