recallmem 0.1.0

package/bin/commands/doctor.js

@@ -0,0 +1,129 @@
+/**
+ * recallmem doctor
+ *
+ * Diagnostic command. Checks every dependency and prints a status report.
+ * Doesn't try to fix anything -- just tells you what's working and what's not.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const {
+  detectNode,
+  detectPostgres,
+  detectPostgresService,
+  detectPgvector,
+  detectOllama,
+  detectOllamaModel,
+  detectDatabase,
+} = require("../lib/detect");
+
+const {
+  color,
+  symbols,
+  printHeader,
+  section,
+  success,
+  fail,
+  warn,
+  info,
+  blank,
+} = require("../lib/output");
+
+const PROJECT_ROOT = process.cwd();
+const ENV_PATH = path.join(PROJECT_ROOT, ".env.local");
+
+function readEnv() {
+  if (!fs.existsSync(ENV_PATH)) return {};
+  const text = fs.readFileSync(ENV_PATH, "utf-8");
+  const env = {};
+  for (const line of text.split("\n")) {
+    const m = line.match(/^([A-Z_]+)=(.*)$/);
+    if (m) env[m[1]] = m[2];
+  }
+  return env;
+}
+
+async function doctorCommand() {
+  printHeader();
+  section("System");
+
+  // Node
+  const node = detectNode();
+  if (node.ok) success(`Node.js ${node.version}`);
+  else fail(`Node.js ${node.version} (need ${node.needed}+)`);
+
+  // Postgres
+  const pg = detectPostgres();
+  if (pg.ok) success(`Postgres ${pg.major} (${pg.psqlPath})`);
+  else if (pg.installed) fail(`Postgres ${pg.major} - too old, need 17+`);
+  else fail("Postgres not installed");
+
+  // Service
+  if (pg.installed) {
+    const svc = detectPostgresService();
+    if (svc.running) success("Postgres service running on localhost:5432");
+    else fail("Postgres installed but not running");
+  }
+
+  // Env file
+  section("Configuration");
+  const envExists = fs.existsSync(ENV_PATH);
+  if (envExists) success(`.env.local found`);
+  else warn(".env.local not found - run `npx recallmem init` to create it");
+
+  const env = readEnv();
+  if (env.DATABASE_URL) {
+    info(`DATABASE_URL=${env.DATABASE_URL.replace(/:[^@]*@/, ":***@")}`);
+  }
+  if (env.OLLAMA_URL) info(`OLLAMA_URL=${env.OLLAMA_URL}`);
+  if (env.OLLAMA_CHAT_MODEL) info(`OLLAMA_CHAT_MODEL=${env.OLLAMA_CHAT_MODEL}`);
+  if (env.OLLAMA_FAST_MODEL) info(`OLLAMA_FAST_MODEL=${env.OLLAMA_FAST_MODEL}`);
+  if (env.OLLAMA_EMBED_MODEL) info(`OLLAMA_EMBED_MODEL=${env.OLLAMA_EMBED_MODEL}`);
+
+  // Database connectivity
+  section("Database");
+  if (env.DATABASE_URL && pg.installed) {
+    const dbCheck = await detectDatabase(env.DATABASE_URL);
+    if (dbCheck.exists) {
+      success("Database reachable");
+      const pgvec = await detectPgvector(env.DATABASE_URL);
+      if (pgvec.available) success("pgvector extension available");
+      else fail("pgvector extension not available");
+    } else {
+      fail(`Cannot connect to database: ${dbCheck.error}`);
+    }
+  } else {
+    info("Skipped (DATABASE_URL not set)");
+  }
+
+  // Ollama
+  section("LLM runtime");
+  const ollama = detectOllama();
+  if (ollama.running) {
+    success(`Ollama running ${ollama.version || ""}`);
+
+    // Required model
+    const embed = await detectOllamaModel("embeddinggemma");
+    if (embed.installed) success("embeddinggemma installed (required)");
+    else fail("embeddinggemma not installed - run: ollama pull embeddinggemma");
+
+    // Optional models
+    const models = ["gemma4:26b", "gemma4:31b", "gemma4:e4b", "gemma4:e2b"];
+    for (const m of models) {
+      const r = await detectOllamaModel(m);
+      if (r.installed) success(`${m} installed`);
+    }
+  } else if (ollama.installed) {
+    warn("Ollama installed but not running");
+    info("Try: brew services start ollama (Mac) or ollama serve");
+  } else {
+    warn("Ollama not installed (optional - cloud providers still work)");
+  }
+
+  blank();
+  console.log(color.dim("Done. Run `npx recallmem init` to fix any issues."));
+  blank();
+}
+
+module.exports = { doctorCommand };

package/bin/commands/setup.js

@@ -0,0 +1,296 @@
+/**
+ * recallmem init / setup
+ *
+ * Idempotent setup pipeline:
+ *   1. Check Node.js version
+ *   2. Check Postgres is installed and running
+ *   3. Check pgvector is available
+ *   4. Create the database if missing
+ *   5. Run migrations
+ *   6. Check Ollama (optional - skip if user wants cloud-only)
+ *   7. Pull embeddinggemma (required, ~600MB)
+ *   8. Offer to pull gemma4:26b (recommended chat model, ~18GB)
+ *   9. Generate .env.local with sensible defaults
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn, spawnSync, execSync } = require("node:child_process");
+
+const {
+  getOS,
+  detectNode,
+  detectPostgres,
+  detectPostgresService,
+  detectPgvector,
+  detectOllama,
+  detectOllamaModel,
+  detectDatabase,
+} = require("../lib/detect");
+
+const {
+  postgresInstallHint,
+  pgvectorInstallHint,
+  ollamaInstallHint,
+  nodeInstallHint,
+} = require("../lib/install-hints");
+
+const {
+  color,
+  step,
+  success,
+  warn,
+  fail,
+  info,
+  section,
+  blank,
+} = require("../lib/output");
+
+const { confirm } = require("../lib/prompt");
+
+const DEFAULT_DB_NAME = "recallmem";
+
+function defaultConnectionString() {
+  const user = process.env.USER || process.env.USERNAME || "postgres";
+  return `postgres://${user}@localhost:5432/${DEFAULT_DB_NAME}`;
+}
+
+function readEnv(envPath) {
+  if (!fs.existsSync(envPath)) return {};
+  const text = fs.readFileSync(envPath, "utf-8");
+  const env = {};
+  for (const line of text.split("\n")) {
+    const m = line.match(/^([A-Z_]+)=(.*)$/);
+    if (m) env[m[1]] = m[2];
+  }
+  return env;
+}
+
+function writeEnv(envPath, env) {
+  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+  fs.writeFileSync(envPath, lines.join("\n") + "\n");
+}
+
+async function setupCommand(opts = {}) {
+  const {
+    silent = false,
+    skipIfDone = false,
+    installPath = process.cwd(),
+    devMode = false,
+  } = opts;
+  const ENV_PATH = path.join(installPath, ".env.local");
+
+  // ─── Step 1: Node.js ───────────────────────────────────────────────────
+  if (!silent) section("Checking dependencies");
+  const node = detectNode();
+  if (!node.ok) {
+    fail(`Node.js ${node.version} is too old (need ${node.needed}+)`);
+    blank();
+    console.log(nodeInstallHint());
+    return { ok: false };
+  }
+  success(`Node.js ${node.version}`);
+
+  // ─── Step 2: Postgres ──────────────────────────────────────────────────
+  const pg = detectPostgres();
+  if (!pg.installed) {
+    fail("Postgres not found");
+    blank();
+    console.log(postgresInstallHint());
+    blank();
+    info("Once installed, re-run: npx recallmem");
+    return { ok: false };
+  }
+  if (!pg.ok) {
+    fail(`Postgres ${pg.major} found, but version 17+ is required`);
+    blank();
+    console.log(postgresInstallHint());
+    return { ok: false };
+  }
+  success(`Postgres ${pg.major}`);
+
+  // ─── Step 3: Postgres service running ──────────────────────────────────
+  const pgService = detectPostgresService();
+  if (!pgService.running) {
+    warn("Postgres is installed but not running");
+    if (getOS() === "mac") {
+      info("Try: brew services start postgresql@17");
+    } else if (getOS() === "linux") {
+      info("Try: sudo systemctl start postgresql");
+    }
+    return { ok: false };
+  }
+  success("Postgres service running on localhost:5432");
+
+  // ─── Step 4: env file (we need DATABASE_URL before checking pgvector) ──
+  const env = readEnv(ENV_PATH);
+  let connectionString = env.DATABASE_URL;
+
+  if (!connectionString) {
+    connectionString = defaultConnectionString();
+    step(`No .env.local found, will create one with default DATABASE_URL`);
+  }
+
+  // ─── Step 5: Database exists ───────────────────────────────────────────
+  // Extract the database name from the connection string for accurate messages
+  const dbNameMatch = connectionString.match(/\/([^/?]+)(\?|$)/);
+  const dbName = dbNameMatch ? dbNameMatch[1] : DEFAULT_DB_NAME;
+
+  const dbCheck = await detectDatabase(connectionString);
+  if (!dbCheck.exists) {
+    step(`Database '${dbName}' not found, creating...`);
+    try {
+      execSync(`${pg.psqlPath.replace(/psql$/, "createdb")} ${dbName}`, {
+        stdio: "pipe",
+      });
+      success(`Created database '${dbName}'`);
+    } catch (err) {
+      fail(`Failed to create database: ${err.message}`);
+      info(`Try manually: createdb ${dbName}`);
+      return { ok: false };
+    }
+  } else {
+    success(`Database '${dbName}' exists`);
+  }
+
+  // ─── Step 6: pgvector extension available ──────────────────────────────
+  const pgvec = await detectPgvector(connectionString);
+  if (!pgvec.available) {
+    fail("pgvector extension is not installed in Postgres");
+    blank();
+    console.log(pgvectorInstallHint());
+    return { ok: false };
+  }
+  success("pgvector extension available");
+
+  // ─── Step 7: Run migrations ────────────────────────────────────────────
+  step("Running migrations...");
+  try {
+    process.env.DATABASE_URL = connectionString;
+    const migrateResult = spawnSync("npx", ["tsx", "scripts/migrate.ts"], {
+      cwd: installPath,
+      stdio: silent ? "pipe" : "inherit",
+      env: { ...process.env, DATABASE_URL: connectionString },
+    });
+    if (migrateResult.status !== 0) {
+      fail("Migration failed");
+      return { ok: false };
+    }
+  } catch (err) {
+    fail(`Migration failed: ${err.message}`);
+    return { ok: false };
+  }
+
+  // ─── Step 8: Ollama (optional) ─────────────────────────────────────────
+  section("Checking LLM runtime");
+  const ollama = detectOllama();
+  let ollamaUrl = env.OLLAMA_URL || "http://localhost:11434";
+
+  if (!ollama.installed) {
+    warn("Ollama not installed (optional - you can use cloud providers instead)");
+    blank();
+    console.log(ollamaInstallHint());
+    blank();
+    info("Continuing without Ollama. You can add Claude/OpenAI as a provider in the app.");
+    blank();
+  } else if (!ollama.running) {
+    warn("Ollama is installed but not running");
+    if (getOS() === "mac") {
+      info("Try: brew services start ollama");
+    } else {
+      info("Try: ollama serve");
+    }
+    blank();
+  } else {
+    success(`Ollama running (${ollama.version || "unknown version"})`);
+
+    // ─── Step 9: Required model: embeddinggemma ──────────────────────────
+    const embedModel = await detectOllamaModel("embeddinggemma");
+    if (!embedModel.installed) {
+      step("Pulling embeddinggemma (~600MB, required for vector search)...");
+      try {
+        execSync("ollama pull embeddinggemma", { stdio: "inherit" });
+        success("Pulled embeddinggemma");
+      } catch (err) {
+        fail(`Failed to pull embeddinggemma: ${err.message}`);
+        return { ok: false };
+      }
+    } else {
+      success("embeddinggemma installed");
+    }
+
+    // ─── Step 10: Recommended model: gemma4:26b ──────────────────────────
+    const chatModel = await detectOllamaModel("gemma4:26b");
+    if (!chatModel.installed && !skipIfDone) {
+      blank();
+      info("Recommended chat model: gemma4:26b (~18GB)");
+      info("Optional - you can use cloud providers (Claude, GPT) instead.");
+      const wantsPull = await confirm("Pull gemma4:26b now?", false);
+      if (wantsPull) {
+        try {
+          execSync("ollama pull gemma4:26b", { stdio: "inherit" });
+          success("Pulled gemma4:26b");
+        } catch (err) {
+          fail(`Failed to pull gemma4:26b: ${err.message}`);
+          info("You can pull it later with: ollama pull gemma4:26b");
+        }
+      } else {
+        info("Skipped. You can pull it later with: ollama pull gemma4:26b");
+      }
+    } else if (chatModel.installed) {
+      success("gemma4:26b installed");
+    }
+  }
+
+  // ─── Step 11: Write .env.local ─────────────────────────────────────────
+  section("Writing config");
+  const finalEnv = {
+    DATABASE_URL: env.DATABASE_URL || connectionString,
+    OLLAMA_URL: env.OLLAMA_URL || ollamaUrl,
+    OLLAMA_CHAT_MODEL: env.OLLAMA_CHAT_MODEL || "gemma4:26b",
+    OLLAMA_FAST_MODEL: env.OLLAMA_FAST_MODEL || "gemma4:e4b",
+    OLLAMA_EMBED_MODEL: env.OLLAMA_EMBED_MODEL || "embeddinggemma",
+  };
+  const existedBefore = fs.existsSync(ENV_PATH);
+  writeEnv(ENV_PATH, finalEnv);
+  success(`.env.local ${existedBefore ? "updated" : "created"}`);
+
+  // ─── Step 12: Production build (skipped in dev mode) ──────────────────
+  // End users get a production build for speed and to avoid dev-mode hot-reload
+  // hydration warnings. Developers in their own checkout (devMode=true) skip the
+  // build so they get hot reload via `next dev`.
+  if (!devMode) {
+    const hasBuild = fs.existsSync(
+      path.join(installPath, ".next", "BUILD_ID")
+    );
+    if (!hasBuild) {
+      section("Building app for production");
+      info("This takes about 30-60 seconds, but only on the first install.");
+      try {
+        const buildResult = spawnSync("npx", ["next", "build"], {
+          cwd: installPath,
+          stdio: silent ? "pipe" : "inherit",
+          env: { ...process.env, ...finalEnv },
+        });
+        if (buildResult.status !== 0) {
+          warn("Production build failed, will fall back to dev mode at runtime");
+        } else {
+          success("Production build complete");
+        }
+      } catch (err) {
+        warn(`Build failed: ${err.message}`);
+        info("Falling back to dev mode at runtime");
+      }
+    } else {
+      success("Production build already exists");
+    }
+  }
+
+  blank();
+  success(color.bold("Setup complete!"));
+  blank();
+
+  return { ok: true };
+}
+
+module.exports = { setupCommand };

package/bin/commands/start.js

@@ -0,0 +1,59 @@
+/**
+ * recallmem start
+ *
+ * Starts the Next.js server. In dev mode (no .next build), runs `next dev`.
+ * In production mode (built), runs `next start`.
+ *
+ * Opens the browser when the server is ready.
+ */
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { spawn } = require("node:child_process");
+const { color, section, success, info } = require("../lib/output");
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin" ? "open" :
+    platform === "win32" ? "start" :
+    "xdg-open";
+  try {
+    spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    // best effort
+  }
+}
+
+async function startCommand(opts = {}) {
+  const { installPath = process.cwd() } = opts;
+  section("Starting RecallMEM");
+
+  const hasBuild = fs.existsSync(path.join(installPath, ".next", "BUILD_ID"));
+  const command = hasBuild ? "start" : "dev";
+
+  info(hasBuild ? "Production build detected, running next start" : "No build found, running next dev");
+  info("Opening http://localhost:3000 in your browser...");
+  console.log("");
+  console.log(color.dim("  (Press Ctrl+C to stop)"));
+  console.log("");
+
+  // Open the browser shortly after starting (give Next a moment to be ready)
+  setTimeout(() => openBrowser("http://localhost:3000"), 2000);
+
+  const child = spawn("npx", ["next", command], {
+    cwd: installPath,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  return new Promise((resolve, reject) => {
+    child.on("exit", (code) => {
+      if (code === 0 || code === null) resolve();
+      else reject(new Error(`Server exited with code ${code}`));
+    });
+    child.on("error", reject);
+  });
+}
+
+module.exports = { startCommand };

package/bin/commands/upgrade.js

@@ -0,0 +1,77 @@
+/**
+ * recallmem upgrade
+ *
+ * Pulls the latest code (git pull), reinstalls dependencies, runs pending
+ * migrations, and rebuilds the production bundle so the next start picks up
+ * the new code. Doesn't restart the server itself -- assumes you're not
+ * running it, or you'll restart manually.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { gitPull, detectInstallMode } = require("../lib/install-mode");
+const { color, section, success, fail, warn, info, blank } = require("../lib/output");
+
+async function upgradeCommand() {
+  const mode = detectInstallMode();
+
+  if (mode.mode === "first-run") {
+    fail("Nothing to upgrade -- no install found.");
+    info("Run `npx recallmem` first to install.");
+    return;
+  }
+
+  section(`Upgrading ${mode.path}`);
+
+  // Pull latest code
+  const pullResult = gitPull(mode.path);
+  if (!pullResult.ok) {
+    fail(`git pull failed: ${pullResult.error}`);
+    process.exit(1);
+  }
+
+  // Run pending migrations
+  section("Running migrations");
+  const migrateResult = spawnSync("npx", ["tsx", "scripts/migrate.ts"], {
+    cwd: mode.path,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (migrateResult.status !== 0) {
+    fail("Migration failed");
+    process.exit(1);
+  }
+
+  // Rebuild the production bundle so the next start picks up new code.
+  // Skip in dev mode since developers run `next dev` (which compiles on demand).
+  if (mode.mode !== "dev") {
+    section("Rebuilding production bundle");
+    info("This takes about 30-60 seconds.");
+
+    // Wipe old build first so we always get fresh output
+    const nextDir = path.join(mode.path, ".next");
+    if (fs.existsSync(nextDir)) {
+      fs.rmSync(nextDir, { recursive: true, force: true });
+    }
+
+    const buildResult = spawnSync("npx", ["next", "build"], {
+      cwd: mode.path,
+      stdio: "inherit",
+      env: process.env,
+    });
+    if (buildResult.status !== 0) {
+      warn("Build failed, will fall back to dev mode at runtime");
+    } else {
+      success("Production build complete");
+    }
+  }
+
+  blank();
+  success("Up to date");
+  info("Restart with: npx recallmem");
+  blank();
+}
+
+module.exports = { upgradeCommand };