@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/wizard/lib/litellm-env.mjs

@@ -0,0 +1,55 @@
+/**
+ * The stack LiteLLM's secrets file (litellm.env, mode 600): LITELLM_MASTER_KEY and the
+ * provider keys its routes reference as os.environ/<NAME>. Shared by every provider that
+ * enables the `litellm` compose service (Hindsight, mem0).
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Create litellm.env (mode 600) with a fresh LITELLM_MASTER_KEY when it does not exist.
+ * @param {string} litellmEnv
+ * @returns {boolean} true when the file was created
+ */
+export function ensureLitellmEnv(litellmEnv) {
+  if (fs.existsSync(litellmEnv)) return false;
+  const key = crypto.randomBytes(24).toString("hex");
+  const body =
+    "# LiteLLM proxy secrets. Read by the litellm compose service. Do not commit.\n" +
+    `LITELLM_MASTER_KEY=sk-${key}\n` +
+    "# lemond ignores the key; any non-empty value works.\n" +
+    "LEMOND_API_KEY=placeholder\n" +
+    "# Hosted models: add the provider key here, e.g. ANTHROPIC_API_KEY=..., and reference it as os.environ/ANTHROPIC_API_KEY.\n";
+  fs.mkdirSync(path.dirname(litellmEnv), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(litellmEnv, body, { mode: 0o600 });
+  return true;
+}
+
+/**
+ * Set NAME=value in litellm.env (mode 600), creating the file with a master key first when
+ * it does not exist. Never prints the value.
+ * @param {string} litellmEnv
+ * @param {string} name
+ * @param {string} value
+ * @returns {"unchanged"|"updated"|"added"}
+ */
+export function setLitellmEnvValue(litellmEnv, name, value) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`invalid variable name: ${name}`);
+  if (/[\r\n]/.test(value)) throw new Error(`${name} must be one line`);
+  ensureLitellmEnv(litellmEnv);
+  const lines = fs.readFileSync(litellmEnv, "utf8").replace(/\n$/, "").split("\n");
+  const line = `${name}=${value}`;
+  const at = lines.findIndex((l) => l.startsWith(`${name}=`));
+  if (at >= 0 && lines[at] === line) {
+    fs.chmodSync(litellmEnv, 0o600);
+    return "unchanged";
+  }
+  if (at >= 0) lines[at] = line;
+  else lines.push(line);
+  const tmp = path.join(path.dirname(litellmEnv), `.litellm.env.${process.pid}`);
+  fs.writeFileSync(tmp, `${lines.join("\n")}\n`, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, litellmEnv);
+  return at >= 0 ? "updated" : "added";
+}

package/wizard/lib/load-machine-env.mjs

@@ -0,0 +1,4 @@
+/** @deprecated Use ~/.config/personal-memory/config.toml. Kept for provider hook compatibility. */
+export function loadMachineEnv(_repoRoot) {
+  return {};
+}

package/wizard/lib/log.mjs

@@ -0,0 +1,32 @@
+const tty = Boolean(process.stdout.isTTY);
+const BOLD = tty ? "\x1b[1m" : "";
+const GREEN = tty ? "\x1b[32m" : "";
+const YELLOW = tty ? "\x1b[33m" : "";
+const RED = tty ? "\x1b[31m" : "";
+const RESET = tty ? "\x1b[0m" : "";
+
+export function step(title) {
+  console.log(`\n${BOLD}== ${title} ==${RESET}`);
+}
+
+export function info(msg) {
+  console.log(`  ${msg}`);
+}
+
+export function ok(msg) {
+  console.log(`  ${GREEN}ok${RESET} ${msg}`);
+}
+
+export function warn(msg) {
+  console.error(`  ${YELLOW}warn${RESET} ${msg}`);
+}
+
+export function die(msg) {
+  console.error(`  ${RED}error${RESET} ${msg}`);
+  process.exit(1);
+}
+
+export function problem(ctx, msg) {
+  if (ctx.dry) warn(`${msg} (dry run: continuing)`);
+  else die(msg);
+}

package/wizard/lib/notebooklm-agent-access.mjs

@@ -0,0 +1,92 @@
+/**
+ * Opt-in coding-agent NotebookLM MCP access: materialize ~/.hindsight/coding-agent.json
+ * as a real file (never write machine settings into the repo template) and toggle
+ * notebooklmAccess.enabled.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} agentPath ~/.hindsight/coding-agent.json
+ * @param {string} templatePath repo config/coding-agent.json
+ * @returns {{ path: string, action: "created" | "materialized" | "exists", cfg: Record<string, any> }}
+ */
+export function ensureCodingAgentJsonRealFile(agentPath, templatePath) {
+  fs.mkdirSync(path.dirname(agentPath), { recursive: true });
+
+  let stat = null;
+  try {
+    stat = fs.lstatSync(agentPath);
+  } catch {
+    stat = null;
+  }
+
+  if (stat?.isSymbolicLink()) {
+    const raw = fs.readFileSync(agentPath, "utf8");
+    const cfg = JSON.parse(raw);
+    fs.unlinkSync(agentPath);
+    fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    return { path: agentPath, action: "materialized", cfg };
+  }
+
+  if (stat?.isFile()) {
+    const cfg = JSON.parse(fs.readFileSync(agentPath, "utf8"));
+    return { path: agentPath, action: "exists", cfg };
+  }
+
+  let cfg;
+  if (fs.existsSync(templatePath) && fs.statSync(templatePath).isFile()) {
+    cfg = JSON.parse(fs.readFileSync(templatePath, "utf8"));
+  } else {
+    cfg = {
+      serverMode: "self-hosted",
+      apiUrl: "http://127.0.0.1:8888",
+      optInOnly: true,
+      optInPaths: [],
+      mapPathToBank: {},
+      notebooklmAccess: { enabled: false, banks: ["*"] },
+    };
+  }
+  fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { path: agentPath, action: "created", cfg };
+}
+
+/**
+ * Set notebooklmAccess.enabled on a real coding-agent.json. Never writes templatePath.
+ * Materializes a symlink into a regular file first when needed.
+ *
+ * @param {string} agentPath
+ * @param {string} templatePath
+ * @param {boolean} enabled
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {{ dry?: boolean, action?: string, agentPath: string, enabled: boolean, wrote: boolean }}
+ */
+export function setNotebooklmAccessEnabled(agentPath, templatePath, enabled, opts = {}) {
+  const absTemplate = path.resolve(templatePath);
+  if (opts.dry) {
+    return {
+      dry: true,
+      agentPath,
+      enabled,
+      wrote: false,
+      action: fs.existsSync(agentPath)
+        ? fs.lstatSync(agentPath).isSymbolicLink()
+          ? "would-materialize"
+          : "would-update"
+        : "would-create",
+    };
+  }
+
+  const { cfg, action } = ensureCodingAgentJsonRealFile(agentPath, templatePath);
+  // Guard: never write into the shipped template even if agentPath somehow resolves there.
+  if (path.resolve(agentPath) === absTemplate) {
+    throw new Error(`refusing to write notebooklmAccess into shipped template ${templatePath}`);
+  }
+  const access =
+    cfg.notebooklmAccess && typeof cfg.notebooklmAccess === "object" ? { ...cfg.notebooklmAccess } : {};
+  access.enabled = enabled === true;
+  if (!Array.isArray(access.banks) || !access.banks.length) access.banks = ["*"];
+  cfg.notebooklmAccess = access;
+  fs.writeFileSync(agentPath, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { agentPath, enabled: access.enabled, wrote: true, action };
+}

package/wizard/lib/notebooklm.mjs

@@ -0,0 +1,214 @@
+/**
+ * NotebookLM opt-in during setup: install the CLI if needed, run `notebooklm login`
+ * (browser) when there is no valid session, then inject NOTEBOOKLM_HOME so host
+ * commands and wizard.conf agree with the compose bind mount (~/.config/notebooklm).
+ * After sync is enabled, optionally opt in coding-agent MCP access (notebooklm_list_banks /
+ * notebooklm_search).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { step, info, ok, warn } from "./log.mjs";
+import { act, commandExists } from "./exec.mjs";
+import { confirm } from "./prompts.mjs";
+import { upsertWizardConf } from "./wizard-conf.mjs";
+import { setNotebooklmAccessEnabled } from "./notebooklm-agent-access.mjs";
+import { installNotebooklmMcp } from "../../providers/hindsight/lib/notebooklm-mcp-install.mjs";
+
+/** @typedef {import("./run-wizard.mjs").WizardContext} WizardContext */
+
+const MCP_CONFIRM =
+  "Allow coding agents to query NotebookLM banks via MCP (notebooklm_list_banks / notebooklm_search)?";
+
+/** @param {WizardContext} ctx */
+function codingAgentPaths(ctx) {
+  const agentPath = ctx.agentJson || path.join(ctx.home, ".hindsight", "coding-agent.json");
+  const templatePath = path.join(ctx.repoRoot, "config/coding-agent.json");
+  return { agentPath, templatePath };
+}
+
+/**
+ * After NotebookLM sync was enabled this run: opt-in MCP access (default yes).
+ * @param {WizardContext} ctx
+ */
+export async function offerNotebooklmMcpAccess(ctx) {
+  const allow = await confirm(ctx, MCP_CONFIRM, "y");
+  const { agentPath, templatePath } = codingAgentPaths(ctx);
+  const h = { info, ok, warn };
+
+  if (!allow) {
+    if (ctx.dry) {
+      info(`[dry-run] leave notebooklmAccess.enabled false; skip MCP merge (${agentPath})`);
+      return false;
+    }
+    if (fs.existsSync(agentPath)) {
+      try {
+        const st = fs.lstatSync(agentPath);
+        if (st.isFile() || st.isSymbolicLink()) {
+          setNotebooklmAccessEnabled(agentPath, templatePath, false);
+          ok(`notebooklmAccess.enabled=false in ${agentPath}`);
+        }
+      } catch (err) {
+        warn(`could not clear notebooklmAccess.enabled: ${err instanceof Error ? err.message : err}`);
+      }
+    } else {
+      info("notebooklmAccess left disabled (no coding-agent.json yet)");
+    }
+    return false;
+  }
+
+  if (ctx.dry) {
+    const plan = setNotebooklmAccessEnabled(agentPath, templatePath, true, { dry: true });
+    info(
+      `[dry-run] ${plan.action} ${agentPath} with notebooklmAccess.enabled=true; merge notebooklm MCP into ~/.cursor/mcp.json`,
+    );
+    return true;
+  }
+
+  const result = setNotebooklmAccessEnabled(agentPath, templatePath, true);
+  ok(
+    `notebooklmAccess.enabled=true in ${agentPath}` +
+      (result.action === "materialized" ? " (copied from symlink → regular file)" : ""),
+  );
+  await installNotebooklmMcp(
+    { home: ctx.home, repoRoot: ctx.repoRoot, agentJson: agentPath, dry: false },
+    h,
+  );
+  ok("Restart Cursor Agent so it picks up the notebooklm MCP");
+  return true;
+}
+
+/** Host path the compose service bind-mounts as /data/notebooklm. */
+export function notebooklmHome(ctx) {
+  return path.join(ctx.home, ".config/notebooklm");
+}
+
+/** Env for every host `notebooklm` child: NOTEBOOKLM_HOME points at the shared cookie dir. */
+export function notebooklmEnv(ctx) {
+  return { ...process.env, NOTEBOOKLM_HOME: notebooklmHome(ctx) };
+}
+
+/**
+ * Persist NOTEBOOKLM_HOME into the process env and wizard.conf (compose already mounts the path).
+ * @param {WizardContext} ctx
+ */
+export function injectNotebooklmHome(ctx) {
+  const home = notebooklmHome(ctx);
+  process.env.NOTEBOOKLM_HOME = home;
+  upsertWizardConf(ctx, { NOTEBOOKLM_HOME: home });
+  ok(`NOTEBOOKLM_HOME=${home} (process env + wizard.conf)`);
+}
+
+/**
+ * @param {WizardContext} ctx
+ * @returns {boolean}
+ */
+export function notebooklmAuthOk(ctx) {
+  if (!commandExists("notebooklm")) return false;
+  const check = spawnSync("notebooklm", ["auth", "check", "--test", "--json"], {
+    env: notebooklmEnv(ctx),
+    stdio: "ignore",
+  });
+  return check.status === 0;
+}
+
+/**
+ * Install notebooklm-py + Playwright Chromium via uv when the CLI is missing.
+ * @param {WizardContext} ctx
+ * @returns {Promise<boolean>} true when `notebooklm` is on PATH afterwards
+ */
+export async function ensureNotebooklmCli(ctx) {
+  if (commandExists("notebooklm")) return true;
+  if (!commandExists("uv")) {
+    warn("uv is not on PATH; install uv, then rerun setup to enable NotebookLM");
+    return false;
+  }
+  if (ctx.dry) {
+    info(`[dry-run] uv tool install ${ctx.notebooklmPkg} && playwright install chromium`);
+    return false;
+  }
+  info(`installing ${ctx.notebooklmPkg} (includes Playwright Chromium)`);
+  await act(ctx, `uv tool install ${ctx.notebooklmPkg}`, "uv", ["tool", "install", ctx.notebooklmPkg]);
+  await act(
+    ctx,
+    "playwright install chromium for notebooklm-py",
+    "uv",
+    ["tool", "run", "--from", ctx.notebooklmPkg, "python", "-m", "playwright", "install", "chromium"],
+  );
+  if (!commandExists("notebooklm")) {
+    warn("notebooklm still not on PATH after install (check ~/.local/bin)");
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Open the Google sign-in browser via notebooklm-py. Stdio is inherited so the
+ * operator can complete login; no separate "are you done?" prompt.
+ * @param {WizardContext} ctx
+ * @returns {Promise<boolean>}
+ */
+export async function runNotebooklmLogin(ctx) {
+  if (ctx.dry) {
+    info("[dry-run] notebooklm login (opens a browser; NOTEBOOKLM_HOME set)");
+    return false;
+  }
+  if (ctx.yes) {
+    warn("skipping notebooklm login under --yes (needs a browser); log in interactively or rerun without --yes");
+    return false;
+  }
+  if (!process.stdin.isTTY) {
+    warn("skipping notebooklm login (no TTY); run setup interactively once");
+    return false;
+  }
+  fs.mkdirSync(notebooklmHome(ctx), { recursive: true, mode: 0o700 });
+  info("opening Google sign-in for NotebookLM (complete it in the browser window)…");
+  const r = spawnSync("notebooklm", ["login"], {
+    env: notebooklmEnv(ctx),
+    stdio: "inherit",
+  });
+  return r.status === 0;
+}
+
+/**
+ * @param {WizardContext} ctx
+ * @param {(c: WizardContext) => void} enableNotebooklm
+ */
+export async function setupNotebooklm(ctx, enableNotebooklm) {
+  step("6. NotebookLM sync (optional, default no)");
+  if (!(await confirm(ctx, "Enable the NotebookLM sync? It stores a Google session cookie on this machine", "n"))) {
+    info("skipped; the service stays off");
+    return;
+  }
+  if (ctx.dry) {
+    info("[dry-run] install notebooklm-py if needed, login if auth fails, inject NOTEBOOKLM_HOME, enable notebooklm.yml");
+    await offerNotebooklmMcpAccess(ctx);
+    return;
+  }
+
+  fs.mkdirSync(notebooklmHome(ctx), { recursive: true, mode: 0o700 });
+  injectNotebooklmHome(ctx);
+
+  if (!(await ensureNotebooklmCli(ctx))) return;
+
+  if (notebooklmAuthOk(ctx)) {
+    ok("NotebookLM session already valid");
+    enableNotebooklm(ctx);
+    await offerNotebooklmMcpAccess(ctx);
+    return;
+  }
+
+  info("no valid NotebookLM session yet; starting login…");
+  const loggedIn = await runNotebooklmLogin(ctx);
+  if (!loggedIn) {
+    warn(`login did not finish; ${ctx.notebookFile} is unchanged. Rerun setup when ready`);
+    return;
+  }
+  if (!notebooklmAuthOk(ctx)) {
+    warn(`auth check failed after login; ${ctx.notebookFile} is unchanged`);
+    return;
+  }
+  ok("NotebookLM login ok");
+  enableNotebooklm(ctx);
+  await offerNotebooklmMcpAccess(ctx);
+}

package/wizard/lib/parse-args.mjs

@@ -0,0 +1,87 @@
+import os from "node:os";
+import path from "node:path";
+import { die } from "./log.mjs";
+import { parseActionFromArgv } from "./wizard-action.mjs";
+
+const HELP = `Setup wizard: takes a fresh clone to a running memory stack for the selected provider. Symlinked as ./setup at the repo root.
+Re-runnable: shows current values as defaults and asks before it replaces config or secrets.
+
+  ./setup                      interactive (@clack/prompts UI, then the rest)
+  ./setup --yes                accept every default, no prompts
+  ./setup --dry-run [--yes]    print the actions; read-only checks run, nothing is written or started
+  ./setup --yes --no-smoke     skip the smoke retain/recall (for scripted re-runs)
+  ./setup --rebuild            rebuild the images even when their sources are unchanged
+  ./setup --up [--yes]         start the stack using existing wizard.conf
+  ./setup --down [--yes]       stop the stack (docker compose down)
+
+PM_PROJECT sets the compose project name (default: openmem). MEMORY_PROVIDER selects the
+memory plugin (default: hindsight). PM_WIZARD_ACTION=configure|up|down. Each provider documents its
+own environment variables (model backend, ports) in providers/<id>/. PM_STACK_ROOT and PM_PACKAGE_ROOT
+split the mutable stack directory from the read-only code directory. The last line is
+"wizard: changed=N": files and containers this run altered.
+Test against a scratch HOME:
+  HOME=/tmp/wiz-home PM_PROJECT=pm-wizard-test ./setup --yes`;
+
+/**
+ * @param {string} repoRoot
+ * @param {string[]} argv
+ * @returns {import("./run-wizard.mjs").WizardContext}
+ */
+export function parseWizardFlags(repoRoot, argv) {
+  const home = process.env.HOME || os.homedir();
+
+  const ctx = {
+    repoRoot,
+    // Read-only code root (wizard/, providers/, scripts/); the stack root is repoRoot.
+    packageRoot: process.env.PM_PACKAGE_ROOT ? path.resolve(process.env.PM_PACKAGE_ROOT) : repoRoot,
+    home,
+    project: process.env.PM_PROJECT || "openmem",
+    // Shared per-machine config dir: wizard.conf, index.yml, notebooklm.yml. The name predates
+    // provider plugins and stays fixed so existing machines keep their config.
+    hsDir: path.join(home, ".config/hindsight"),
+    indexFile: path.join(home, ".config/hindsight/index.yml"),
+    notebookFile: path.join(home, ".config/hindsight/notebooklm.yml"),
+    wizardConf: path.join(home, ".config/hindsight/wizard.conf"),
+    smokeBank: "wizard-smoke",
+    buildHashFile: path.join(repoRoot, ".build-hash"),
+    notebooklmPkg: "notebooklm-py[browser]==0.8.5",
+    yes: false,
+    dry: false,
+    smoke: true,
+    rebuild: false,
+    // True when the Clack UI already asked the provider's questions (WIZARD_SKIP_BACKEND_STEP=1).
+    skipBackendStep: process.env.WIZARD_SKIP_BACKEND_STEP === "1",
+    action: parseActionFromArgv(argv),
+    providerId: "",
+  };
+
+  for (const arg of argv) {
+    switch (arg) {
+      case "--up":
+      case "--down":
+        break;
+      case "--yes":
+      case "-y":
+        ctx.yes = true;
+        break;
+      case "--dry-run":
+        ctx.dry = true;
+        break;
+      case "--no-smoke":
+        ctx.smoke = false;
+        break;
+      case "--rebuild":
+        ctx.rebuild = true;
+        break;
+      case "-h":
+      case "--help":
+        console.log(HELP);
+        process.exit(0);
+        break;
+      default:
+        die(`unknown option: ${arg} (see --help)`);
+    }
+  }
+
+  return ctx;
+}

package/wizard/lib/paths.mjs

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function expandHome(p, home = process.env.HOME || os.homedir()) {
+  if (p === "~") return home;
+  if (p.startsWith("~/")) return path.join(home, p.slice(2));
+  return p;
+}
+
+export function envValue(filePath, key) {
+  if (!fs.existsSync(filePath)) return "";
+  const prefix = `${key}=`;
+  for (const line of fs.readFileSync(filePath, "utf8").split("\n")) {
+    if (line.startsWith(prefix)) return line.slice(prefix.length);
+  }
+  return "";
+}
+
+export function ensureHsDir(ctx) {
+  if (ctx.dry) return;
+  fs.mkdirSync(ctx.hsDir, { recursive: true, mode: 0o700 });
+}
+
+export function realpathSafe(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * Mount point for the shared indexer's state. The directory name predates provider
+ * plugins and stays fixed so existing state keeps working.
+ */
+export function indexerStateDir(ctx) {
+  return path.join(ctx.home, ".cache", "hindsight-project-index");
+}