@cortexmemory/cli 0.1.1 → 0.22.0

package/dist/utils/shell.js

@@ -0,0 +1,188 @@
+/**
+ * Shell Execution Utilities
+ *
+ * Shared utilities for executing shell commands safely.
+ * Used by init wizard and other CLI commands.
+ */
+import { spawn } from "child_process";
+import { existsSync, readdirSync } from "fs";
+import path from "path";
+import { createRequire } from "module";
+// Create require function for ES modules
+const require = createRequire(import.meta.url);
+/**
+ * Allowlist of safe commands that can be executed
+ */
+const ALLOWED_COMMANDS = [
+    "npx",
+    "convex",
+    "npm",
+    "pnpm",
+    "yarn",
+    "bun",
+    "git",
+    "node",
+    "docker",
+    // Process inspection commands (for kill menu)
+    "lsof",
+    "pgrep",
+    "ps",
+];
+/**
+ * Check if a command exists in the system
+ */
+export async function commandExists(command) {
+    return new Promise((resolve) => {
+        // Use platform-specific command (which for Unix, where for Windows)
+        const cmd = process.platform === "win32" ? "where" : "which";
+        const child = spawn(cmd, [command]);
+        child.on("close", (code) => resolve(code === 0));
+    });
+}
+/**
+ * Execute a shell command and return the output
+ *
+ * SECURITY: This function only executes commands from an allowlist.
+ * User input is NEVER passed as the command parameter.
+ */
+export async function execCommand(command, args, options = {}) {
+    // Validate command is from allowlist (defense in depth)
+    if (!ALLOWED_COMMANDS.includes(command)) {
+        throw new Error(`Invalid command: ${command}. Only allowed: ${ALLOWED_COMMANDS.join(", ")}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (data) => {
+            const str = data.toString();
+            stdout += str;
+            if (!options.quiet) {
+                process.stdout.write(str);
+            }
+        });
+        child.stderr?.on("data", (data) => {
+            const str = data.toString();
+            stderr += str;
+            if (!options.quiet) {
+                process.stderr.write(str);
+            }
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+        child.on("close", (code) => {
+            resolve({ stdout, stderr, code: code ?? 1 });
+        });
+    });
+}
+/**
+ * Execute a command with live output (stdio: inherit)
+ *
+ * SECURITY: This function only executes commands from an allowlist.
+ * User input is NEVER passed as the command parameter.
+ */
+export async function execCommandLive(command, args, options = {}) {
+    // Validate command is from allowlist (defense in depth)
+    if (!ALLOWED_COMMANDS.includes(command)) {
+        throw new Error(`Invalid command: ${command}. Only allowed: ${ALLOWED_COMMANDS.join(", ")}`);
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            stdio: "inherit",
+            env: { ...process.env, ...options.env },
+        });
+        child.on("error", (error) => {
+            reject(error);
+        });
+        child.on("close", (code) => {
+            resolve(code ?? 1);
+        });
+    });
+}
+/**
+ * Validate project name
+ */
+export function isValidProjectName(name) {
+    return /^[a-z0-9-_]+$/.test(name);
+}
+/**
+ * Check if directory is empty
+ */
+export function isDirectoryEmpty(dirPath) {
+    if (!existsSync(dirPath)) {
+        return true;
+    }
+    const files = readdirSync(dirPath);
+    return files.length === 0 || (files.length === 1 && files[0] === ".git");
+}
+/**
+ * Get the path to the installed SDK package
+ * @param projectPath - Optional project path to look in (defaults to current directory)
+ */
+export function getSDKPath(projectPath) {
+    try {
+        // If projectPath provided, look in that project's node_modules
+        if (projectPath) {
+            const sdkPath = path.join(projectPath, "node_modules", "@cortexmemory", "sdk");
+            if (existsSync(sdkPath)) {
+                return sdkPath;
+            }
+        }
+        // Fallback: use require.resolve from current location
+        const sdkPackageJson = require.resolve("@cortexmemory/sdk/package.json");
+        return path.dirname(sdkPackageJson);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse Convex URL to determine if it's local or cloud
+ */
+export function isLocalConvexUrl(url) {
+    return url.includes("localhost") || url.includes("127.0.0.1");
+}
+/**
+ * Fetch the latest SDK package.json from npm registry
+ */
+export async function fetchLatestSDKMetadata() {
+    try {
+        const result = await execCommand("npm", [
+            "view",
+            "@cortexmemory/sdk",
+            "peerDependencies.convex",
+            "version",
+            "--json",
+        ], { quiet: true });
+        if (result.code !== 0) {
+            throw new Error(`npm view failed: ${result.stderr}`);
+        }
+        const data = JSON.parse(result.stdout);
+        let convexVersion;
+        let sdkVersion;
+        if (typeof data === "string") {
+            throw new Error("Unexpected npm view response format");
+        }
+        else {
+            convexVersion = data["peerDependencies.convex"] || "^1.29.3";
+            sdkVersion = data["version"] || "latest";
+        }
+        return {
+            convexVersion,
+            sdkVersion,
+        };
+    }
+    catch {
+        // Fallback to safe defaults
+        return {
+            convexVersion: "^1.29.3",
+            sdkVersion: "latest",
+        };
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/utils/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/utils/shell.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAC7C,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,yCAAyC;AACzC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,gBAAgB,GAAG;IACvB,KAAK;IACL,QAAQ;IACR,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,KAAK;IACL,MAAM;IACN,QAAQ;IACR,8CAA8C;IAC9C,MAAM;IACN,OAAO;IACP,IAAI;CACL,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,oEAAoE;QACpE,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACpC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,IAAc,EACd,UAAuF,EAAE;IAEzF,wDAAwD;IACxD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,mBAAmB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACjC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;SACxC,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,CAAC;YACd,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,CAAC;YACd,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,IAAc,EACd,UAAsE,EAAE;IAExE,wDAAwD;IACxD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,mBAAmB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACjC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;SACxC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC;AAC3E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,WAAoB;IAC7C,IAAI,CAAC;QACH,+DAA+D;QAC/D,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CACvB,WAAW,EACX,cAAc,EACd,eAAe,EACf,KAAK,CACN,CAAC;YACF,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxB,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAED,sDAAsD;QACtD,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;QACzE,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAI1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAC9B,KAAK,EACL;YACE,MAAM;YACN,mBAAmB;YACnB,yBAAyB;YACzB,SAAS;YACT,QAAQ;SACT,EACD,EAAE,KAAK,EAAE,IAAI,EAAE,CAChB,CAAC;QAEF,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAEvC,IAAI,aAAqB,CAAC;QAC1B,IAAI,UAAkB,CAAC;QAEvB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACzD,CAAC;aAAM,CAAC;YACN,aAAa,GAAG,IAAI,CAAC,yBAAyB,CAAC,IAAI,SAAS,CAAC;YAC7D,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC;QAC3C,CAAC;QAED,OAAO;YACL,aAAa;YACb,UAAU;SACX,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,4BAA4B;QAC5B,OAAO;YACL,aAAa,EAAE,SAAS;YACxB,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@cortexmemory/cli",
-  "version": "0.1.1",
+  "version": "0.22.0",
   "description": "CLI tool for managing Cortex Memory deployments, performing administrative tasks, and streamlining development workflows",
   "type": "module",
   "bin": {
-    "cortex": "./dist/index.js"
+    "cortex": "dist/index.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,8 +20,11 @@
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
     "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js src/utils/__tests__",
-    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js tests/",
+    "test:unit": "node --experimental-vm-modules node_modules/jest/bin/jest.js --selectProjects unit",
+    "test:commands": "node --experimental-vm-modules node_modules/jest/bin/jest.js --selectProjects commands",
+    "test:e2e": "node --experimental-vm-modules node_modules/jest/bin/jest.js --selectProjects e2e",
+    "test:integration": "node --experimental-vm-modules node_modules/jest/bin/jest.js --selectProjects e2e",
+    "test:fast": "node --experimental-vm-modules node_modules/jest/bin/jest.js --selectProjects unit commands",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run lint && npm run build && npm run test:unit"
   },
@@ -39,7 +42,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/SaintNick1214/Project-Cortex.git",
+    "url": "git+https://github.com/SaintNick1214/Project-Cortex.git",
     "directory": "packages/cortex-cli"
   },
   "publishConfig": {
@@ -51,28 +54,30 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@cortexmemory/sdk": "^0.16.0",
-    "commander": "^14.0.2",
-    "prompts": "^2.4.2",
-    "picocolors": "^1.1.1",
-    "ora": "^9.0.0",
+    "@cortexmemory/sdk": "file:../../cortexmemory-sdk-0.21.0.tgz",
     "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "convex": "^1.31.2",
     "cosmiconfig": "^9.0.0",
-    "convex": "^1.30.0",
     "dotenv": "^17.2.3",
-    "neo4j-driver": "^6.0.1"
+    "fs-extra": "^11.3.3",
+    "neo4j-driver": "^6.0.1",
+    "ora": "^9.0.0",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
     "@types/prompts": "^2.4.9",
-    "@types/node": "^24.10.1",
-    "typescript": "^5.9.3",
-    "eslint": "^9.39.1",
-    "@eslint/js": "^9.39.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "eslint": "^9.39.2",
     "globals": "^16.5.0",
     "jest": "^30.2.0",
-    "@types/jest": "^30.0.0",
-    "ts-jest": "^29.4.6"
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
   }
 }

package/templates/basic/README.md

@@ -0,0 +1,105 @@
+# {{PROJECT_NAME}}
+
+AI agent with persistent memory powered by [Cortex Memory SDK](https://github.com/SaintNick1214/Project-Cortex).
+
+## Getting Started
+
+Your Convex backend functions are deployed and configured!
+
+### For Local Development
+
+**Terminal 1** - Start Convex:
+
+```bash
+npm run dev
+```
+
+Leave this running. It watches for changes and keeps Convex server active.
+
+**Terminal 2** - Run your agent:
+
+```bash
+npm start
+```
+
+### For Cloud Deployments
+
+Your Convex is already running in the cloud, so just:
+
+```bash
+npm start
+```
+
+## Project Structure
+
+```
+.
+├── src/
+│   └── index.ts          # Your AI agent code
+├── convex/               # Cortex backend functions (deployed to Convex)
+│   ├── schema.ts         # Database schema
+│   ├── conversations.ts  # Conversation management
+│   ├── memories.ts       # Memory storage and search
+│   └── ...              # Other Cortex functions
+├── .env.local           # Environment configuration (not committed)
+└── package.json
+```
+
+## What You Get
+
+- **Persistent Memory** - Your agent remembers conversations indefinitely
+- **Semantic Search** - Find relevant memories using natural language
+- **ACID Storage** - Reliable, consistent data storage
+- **Vector Search** - Optional embedding-based search (cloud only)
+- **User Profiles** - Manage user data and preferences
+- **Multi-Agent Support** - Coordinate between multiple agents
+
+## Next Steps
+
+### Add Vector Embeddings
+
+For semantic search, add an embedding provider:
+
+```typescript
+import OpenAI from "openai";
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+await cortex.memory.remember({
+  memorySpaceId: "my-agent",
+  conversationId: "conv-1",
+  userMessage: "message",
+  agentResponse: "response",
+  userId: "user-1",
+  userName: "User",
+  generateEmbedding: async (text) => {
+    const result = await openai.embeddings.create({
+      model: "text-embedding-3-small",
+      input: text,
+    });
+    return result.data[0].embedding;
+  },
+});
+```
+
+### Enable Graph Database
+
+For advanced relationship queries, set up a graph database:
+
+1. Start Neo4j: `docker-compose -f docker-compose.graph.yml up -d`
+2. See `src/graph-init.example.ts` for setup code
+
+### Learn More
+
+- [Documentation](https://github.com/SaintNick1214/Project-Cortex/tree/main/Documentation)
+- [API Reference](https://github.com/SaintNick1214/Project-Cortex/tree/main/Documentation/03-api-reference)
+- [Examples](https://github.com/SaintNick1214/Project-Cortex/tree/main/Examples)
+
+## Support
+
+- [GitHub Issues](https://github.com/SaintNick1214/Project-Cortex/issues)
+- [GitHub Discussions](https://github.com/SaintNick1214/Project-Cortex/discussions)
+
+## License
+
+Apache-2.0

package/templates/basic/dev-runner.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/* eslint-disable no-undef */
+/**
+ * Development runner for Cortex projects
+ * Starts Convex in watch mode
+ */
+
+import { spawn } from "child_process";
+import { config } from "dotenv";
+import { existsSync } from "fs";
+
+// Load environment variables
+config({ path: ".env.local" });
+
+const CONVEX_URL = process.env.CONVEX_URL || "";
+const isLocal =
+  CONVEX_URL.includes("localhost") || CONVEX_URL.includes("127.0.0.1");
+const hasGraphConfig = process.env.NEO4J_URI || process.env.NEO4J_USERNAME;
+const hasDockerCompose = existsSync("./docker-compose.graph.yml");
+
+console.log("🚀 Starting Cortex development environment...\n");
+
+// Start graph database if configured
+if (hasGraphConfig && hasDockerCompose) {
+  console.log("🕸️  Starting graph database...");
+
+  // First check if Docker daemon is running
+  const dockerCheck = spawn("docker", ["info"], { stdio: "pipe" });
+
+  const dockerRunning = await new Promise((resolve) => {
+    let stderr = "";
+    dockerCheck.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    dockerCheck.on("close", (code) => {
+      if (
+        code !== 0 &&
+        stderr.includes("Cannot connect to the Docker daemon")
+      ) {
+        console.log("   ❌ Docker is not running");
+        console.log("   💡 Start Docker Desktop and run npm run dev again");
+        console.log("");
+        resolve(false);
+      } else {
+        resolve(true);
+      }
+    });
+
+    dockerCheck.on("error", () => {
+      console.log("   ⚠️  Docker not installed");
+      console.log("   💡 Install: https://docker.com/products/docker-desktop");
+      console.log("");
+      resolve(false);
+    });
+  });
+
+  if (!dockerRunning) {
+    // Skip graph database startup
+  } else {
+    // Docker is running, start/restart containers
+    // Use 'up -d' which will start existing stopped containers or create new ones
+    const dockerUp = spawn(
+      "docker-compose",
+      ["-f", "docker-compose.graph.yml", "up", "-d", "--remove-orphans"],
+      {
+        stdio: "pipe",
+      },
+    );
+
+    await new Promise((resolve) => {
+      let stdout = "";
+      let stderr = "";
+
+      dockerUp.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      dockerUp.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      dockerUp.on("close", (code) => {
+        if (code === 0) {
+          // Check if containers started or were already running
+          if (stdout.includes("Running") || stdout.includes("Started")) {
+            if (stdout.includes("Running")) {
+              console.log("   ✓ Graph database already running");
+            } else {
+              console.log("   ✓ Graph database started");
+            }
+
+            if (
+              process.env.NEO4J_URI?.includes("neo4j") ||
+              stdout.includes("neo4j")
+            ) {
+              console.log("   Browser: http://localhost:7474");
+            } else {
+              console.log("   Lab: http://localhost:3000");
+            }
+          } else {
+            console.log("   ✓ Graph database ready");
+          }
+        } else {
+          console.log("   ⚠️  Failed to start graph database");
+
+          // Check common issues
+          if (stderr.includes("Cannot connect to the Docker daemon")) {
+            console.log("   ❌ Docker is not running");
+            console.log("   💡 Start Docker Desktop and try again");
+          } else if (
+            stderr.includes("already in use") ||
+            stderr.includes("Conflict")
+          ) {
+            console.log(
+              "   ⚠️  Container name conflict (old stopped container)",
+            );
+            console.log("   💡 Fix: docker rm cortex-neo4j cortex-memgraph");
+            console.log("   Then run: npm run dev");
+          } else if (stderr.includes("already running")) {
+            console.log("   ✓ Container already running (that's fine!)");
+          } else if (stderr) {
+            console.log(
+              "   Error:",
+              stderr.split("\n").find((l) => l.trim()) || stderr.split("\n")[0],
+            );
+          }
+        }
+        resolve();
+      });
+
+      dockerUp.on("error", () => {
+        console.log("   ⚠️  docker-compose command not found");
+        console.log(
+          "   💡 Install Docker Desktop: https://docker.com/products/docker-desktop",
+        );
+        resolve();
+      });
+    });
+    console.log("");
+  }
+}
+
+if (isLocal) {
+  console.log("📝 Mode: LOCAL");
+  console.log("🌐 Convex: http://127.0.0.1:3210");
+} else {
+  console.log("📝 Mode: CLOUD");
+  console.log("🌐 Convex:", CONVEX_URL);
+}
+
+console.log("\n🔄 Watching for changes...");
+console.log("   Press Ctrl+C to stop\n");
+
+// Start Convex dev in watch mode
+const args = ["convex", "dev"];
+
+if (isLocal) {
+  args.push("--url", "http://127.0.0.1:3210");
+}
+
+const child = spawn("npx", args, {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("error", (err) => {
+  console.error("❌ Failed to start Convex:", err);
+  process.exit(1);
+});
+
+child.on("close", (code) => {
+  if (code !== 0 && !stopping) {
+    // Only show error if we're not intentionally stopping
+    console.error(`\n❌ Convex exited unexpectedly with code ${code}`);
+    process.exit(code);
+  }
+});
+
+// Handle Ctrl+C
+let stopping = false;
+process.on("SIGINT", () => {
+  if (stopping) return; // Prevent double execution
+  stopping = true;
+
+  console.log("\n\n👋 Stopping development environment...");
+
+  // Kill Convex gracefully
+  child.kill("SIGTERM");
+
+  // Stop graph database if it was started
+  if (hasGraphConfig && hasDockerCompose) {
+    console.log("🕸️  Stopping graph database...");
+    const dockerDown = spawn(
+      "docker-compose",
+      ["-f", "docker-compose.graph.yml", "stop"],
+      {
+        stdio: "pipe",
+      },
+    );
+
+    dockerDown.on("close", () => {
+      console.log("   ✓ Graph database stopped");
+      process.exit(0);
+    });
+
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      console.log("   ⏱️  Timeout - forcing exit");
+      process.exit(0);
+    }, 5000);
+  } else {
+    process.exit(0);
+  }
+});