@cortexmemory/cli 0.27.3 → 0.28.0

package/templates/basic/src/server.ts

@@ -0,0 +1,280 @@
+/**
+ * Cortex Memory - HTTP Server Mode
+ *
+ * REST API server for demonstrating Cortex Memory SDK.
+ * Useful for testing with tools like curl, Postman, or integrating with other apps.
+ *
+ * Usage:
+ *   npm run server
+ *
+ * Endpoints:
+ *   POST /chat          Chat and store memory
+ *   GET  /recall        Search memories
+ *   GET  /facts         List stored facts
+ *   GET  /history/:id   Get conversation history
+ *   GET  /health        Health check
+ */
+
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import { closeCortex, CONFIG } from "./cortex.js";
+import {
+  chat,
+  recallMemories,
+  listFacts,
+  generateConversationId,
+} from "./chat.js";
+import { printWelcome, printInfo, printError } from "./display.js";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Setup
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const app = new Hono();
+
+// Middleware
+app.use("*", cors());
+app.use("*", logger());
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Routes
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Health check
+ */
+app.get("/health", (c) => {
+  return c.json({
+    status: "ok",
+    memorySpaceId: CONFIG.memorySpaceId,
+    agentId: CONFIG.agentId,
+    features: {
+      factExtraction: CONFIG.enableFactExtraction,
+      graphSync: CONFIG.enableGraphMemory,
+      llm: !!process.env.OPENAI_API_KEY,
+    },
+  });
+});
+
+/**
+ * Chat endpoint
+ *
+ * POST /chat
+ * Body: { message: string, conversationId?: string }
+ */
+app.post("/chat", async (c) => {
+  try {
+    const body = await c.req.json();
+    const { message, conversationId } = body;
+
+    if (!message || typeof message !== "string") {
+      return c.json({ error: "message is required" }, 400);
+    }
+
+    const convId = conversationId || generateConversationId();
+
+    console.log(`\n[Chat] User: ${message.slice(0, 50)}${message.length > 50 ? "..." : ""}`);
+
+    const result = await chat(message, convId);
+
+    console.log(`[Chat] Response sent (${result.memoriesRecalled} memories, ${result.factsRecalled} facts recalled)\n`);
+
+    return c.json({
+      response: result.response,
+      conversationId: result.conversationId,
+      memoriesRecalled: result.memoriesRecalled,
+      factsRecalled: result.factsRecalled,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    printError("Chat failed", error instanceof Error ? error : undefined);
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Recall endpoint
+ *
+ * GET /recall?query=<query>
+ */
+app.get("/recall", async (c) => {
+  try {
+    const query = c.req.query("query");
+
+    if (!query) {
+      return c.json({ error: "query parameter is required" }, 400);
+    }
+
+    console.log(`\n[Recall] Query: ${query}`);
+
+    // Use the internal recall function but capture results
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const result = await cortex.memory.recall({
+      memorySpaceId: CONFIG.memorySpaceId,
+      query,
+      limit: 10,
+      sources: {
+        vector: true,
+        facts: true,
+        graph: CONFIG.enableGraphMemory,
+      },
+    });
+
+    console.log(`[Recall] Found ${result.memories?.length || 0} memories, ${result.facts?.length || 0} facts\n`);
+
+    return c.json({
+      memories: result.memories || [],
+      facts: result.facts || [],
+      query,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Facts endpoint
+ *
+ * GET /facts
+ */
+app.get("/facts", async (c) => {
+  try {
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const result = await cortex.facts.list({
+      memorySpaceId: CONFIG.memorySpaceId,
+      limit: 50,
+    });
+
+    const facts = result.facts || result || [];
+
+    return c.json({ facts, count: facts.length });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Conversation history endpoint
+ *
+ * GET /history/:conversationId
+ */
+app.get("/history/:conversationId", async (c) => {
+  try {
+    const conversationId = c.req.param("conversationId");
+
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const conversation = await cortex.conversations.get(conversationId);
+
+    if (!conversation) {
+      return c.json({ error: "Conversation not found" }, 404);
+    }
+
+    return c.json({
+      conversationId,
+      messages: conversation.messages || [],
+      messageCount: conversation.messages?.length || 0,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Root endpoint - API docs
+ */
+app.get("/", (c) => {
+  return c.json({
+    name: "Cortex Memory - Basic Demo API",
+    version: "1.0.0",
+    endpoints: {
+      "POST /chat": {
+        description: "Chat and store memory",
+        body: { message: "string", conversationId: "string (optional)" },
+      },
+      "GET /recall": {
+        description: "Search memories",
+        query: { query: "string" },
+      },
+      "GET /facts": {
+        description: "List all stored facts",
+      },
+      "GET /history/:id": {
+        description: "Get conversation history",
+      },
+      "GET /health": {
+        description: "Health check",
+      },
+    },
+  });
+});
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Start
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const PORT = parseInt(process.env.PORT || "3001", 10);
+
+async function main(): Promise<void> {
+  // Check for required environment
+  if (!process.env.CONVEX_URL) {
+    printError(
+      "CONVEX_URL is required. Set it in .env.local or run: cortex init",
+    );
+    process.exit(1);
+  }
+
+  // Print welcome
+  printWelcome("server");
+
+  // Start server
+  console.log(`🚀 Server starting on http://localhost:${PORT}`);
+  console.log("");
+  console.log("Endpoints:");
+  console.log(`   POST http://localhost:${PORT}/chat`);
+  console.log(`   GET  http://localhost:${PORT}/recall?query=...`);
+  console.log(`   GET  http://localhost:${PORT}/facts`);
+  console.log(`   GET  http://localhost:${PORT}/history/:id`);
+  console.log(`   GET  http://localhost:${PORT}/health`);
+  console.log("");
+  console.log("Example:");
+  console.log(`   curl -X POST http://localhost:${PORT}/chat \\`);
+  console.log('     -H "Content-Type: application/json" \\');
+  console.log('     -d \'{"message": "My name is Alex"}\'');
+  console.log("");
+
+  serve({
+    fetch: app.fetch,
+    port: PORT,
+  });
+
+  printInfo(`Server running on port ${PORT}`);
+}
+
+// Handle cleanup
+process.on("SIGINT", () => {
+  console.log("\n\nShutting down...");
+  closeCortex();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  closeCortex();
+  process.exit(0);
+});
+
+// Run
+main().catch((error) => {
+  printError("Fatal error", error instanceof Error ? error : undefined);
+  process.exit(1);
+});

package/templates/basic/vitest.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: [
+      "src/**/*.test.ts",
+      "src/__tests__/**/*.test.ts",
+    ],
+    // Unit tests run fast
+    testTimeout: 10000,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/__tests__/**",
+        "src/index.ts", // Entry point, tested via integration
+        "src/server.ts", // Entry point, tested via integration
+      ],
+    },
+    clearMocks: true,
+    restoreMocks: true,
+    // Separate pools for different test types
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});

package/templates/basic/vitest.e2e.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Configuration for E2E tests.
+ * These tests require real Convex backend and optionally OpenAI API key.
+ *
+ * Run with:
+ *   CONVEX_URL=<url> npm run test:e2e
+ *   CONVEX_URL=<url> OPENAI_API_KEY=<key> npm run test:e2e
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/__tests__/e2e/**/*.test.ts"],
+    testTimeout: 180000, // 3 minutes for E2E tests (fact extraction takes time)
+    hookTimeout: 60000, // 1 minute for setup/teardown
+    clearMocks: true,
+    restoreMocks: true,
+    // Run E2E tests sequentially to avoid rate limits
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});

package/templates/basic/vitest.integration.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Configuration for integration tests.
+ * These tests use mocked SDK but test real component interactions.
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/__tests__/integration/**/*.test.ts"],
+    testTimeout: 30000, // 30 seconds for integration tests
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/__tests__/**",
+      ],
+    },
+    clearMocks: true,
+    restoreMocks: true,
+  },
+});

package/templates/vercel-ai-quickstart/app/api/auth/check/route.ts

@@ -24,7 +24,7 @@ export async function GET() {
 
     return Response.json(
       { error: "Failed to check admin setup status" },
-      { status: 500 }
+      { status: 500 },
     );
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/login/route.ts

@@ -7,25 +7,69 @@
 import { getCortex } from "@/lib/cortex";
 import { verifyPassword, generateSessionToken } from "@/lib/password";
 
+/**
+ * Validates login request body structure.
+ * Returns validated credentials or null if invalid.
+ */
+function validateLoginBody(
+  body: unknown,
+): { username: string; password: string } | null {
+  if (typeof body !== "object" || body === null) {
+    return null;
+  }
+
+  const record = body as Record<string, unknown>;
+
+  // Validate username field exists and is a non-empty string
+  const hasValidUsername =
+    "username" in record &&
+    typeof record.username === "string" &&
+    record.username.length > 0 &&
+    record.username.length <= 256;
+
+  // Validate password field exists and is a non-empty string
+  const hasValidPassword =
+    "password" in record &&
+    typeof record.password === "string" &&
+    record.password.length > 0 &&
+    record.password.length <= 1024;
+
+  if (!hasValidUsername || !hasValidPassword) {
+    return null;
+  }
+
+  return {
+    username: record.username as string,
+    password: record.password as string,
+  };
+}
+
+/**
+ * Safely extracts an error message for logging without exposing user data.
+ */
+function getSafeErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    // Only include error name and a sanitized message
+    // Avoid logging full stack traces which may contain user data
+    return `${error.name}: ${error.message.slice(0, 200)}`;
+  }
+  return "Unknown error";
+}
+
 export async function POST(req: Request) {
   try {
     const body = await req.json();
-    const { username, password } = body;
 
-    // Validate input
-    if (!username || typeof username !== "string") {
+    // Validate input structure before extracting values
+    const credentials = validateLoginBody(body);
+    if (!credentials) {
       return Response.json(
-        { error: "Username is required" },
-        { status: 400 }
+        { error: "Username and password are required" },
+        { status: 400 },
       );
     }
 
-    if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
-    }
+    const { username, password } = credentials;
 
     const cortex = getCortex();
     const sanitizedUsername = username.toLowerCase();
@@ -35,7 +79,7 @@ export async function POST(req: Request) {
     if (!user) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -44,7 +88,7 @@ export async function POST(req: Request) {
     if (!storedHash) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -52,7 +96,7 @@ export async function POST(req: Request) {
     if (!isValid) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -73,11 +117,9 @@ export async function POST(req: Request) {
       sessionToken,
     });
   } catch (error) {
-    console.error("[Login Error]", error);
+    // Log sanitized error to prevent log injection
+    console.error("[Login Error]", getSafeErrorMessage(error));
 
-    return Response.json(
-      { error: "Failed to authenticate" },
-      { status: 500 }
-    );
+    return Response.json({ error: "Failed to authenticate" }, { status: 500 });
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/register/route.ts

@@ -14,39 +14,38 @@ export async function POST(req: Request) {
 
     // Validate input
     if (!username || typeof username !== "string") {
-      return Response.json(
-        { error: "Username is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Username is required" }, { status: 400 });
     }
 
     if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Password is required" }, { status: 400 });
     }
 
     if (username.length < 2) {
       return Response.json(
         { error: "Username must be at least 2 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
     if (password.length < 4) {
       return Response.json(
         { error: "Password must be at least 4 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
     // Sanitize username (alphanumeric, underscore, hyphen only)
-    const sanitizedUsername = username.toLowerCase().replace(/[^a-z0-9_-]/g, "");
+    const sanitizedUsername = username
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, "");
     if (sanitizedUsername !== username.toLowerCase()) {
       return Response.json(
-        { error: "Username can only contain letters, numbers, underscores, and hyphens" },
-        { status: 400 }
+        {
+          error:
+            "Username can only contain letters, numbers, underscores, and hyphens",
+        },
+        { status: 400 },
       );
     }
 
@@ -57,7 +56,7 @@ export async function POST(req: Request) {
     if (existingUser) {
       return Response.json(
         { error: "Username already taken" },
-        { status: 409 }
+        { status: 409 },
       );
     }
 
@@ -86,9 +85,6 @@ export async function POST(req: Request) {
   } catch (error) {
     console.error("[Register Error]", error);
 
-    return Response.json(
-      { error: "Failed to register user" },
-      { status: 500 }
-    );
+    return Response.json({ error: "Failed to register user" }, { status: 500 });
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/setup/route.ts

@@ -16,16 +16,13 @@ export async function POST(req: Request) {
     const { password } = body;
 
     if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Password is required" }, { status: 400 });
     }
 
     if (password.length < 4) {
       return Response.json(
         { error: "Password must be at least 4 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
@@ -36,7 +33,7 @@ export async function POST(req: Request) {
     if (existingHash !== null) {
       return Response.json(
         { error: "Admin already configured" },
-        { status: 409 }
+        { status: 409 },
       );
     }
 
@@ -53,7 +50,7 @@ export async function POST(req: Request) {
 
     return Response.json(
       { error: "Failed to configure admin password" },
-      { status: 500 }
+      { status: 500 },
     );
   }
 }