@bcmyguest/openmem 0.0.0-stage → 0.6.3

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");
+}

package/wizard/lib/pm-config.mjs

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import path from "node:path";
+import TOML from "@iarna/toml";
+import { DEFAULT_PROVIDER_ID } from "./providers/registry.mjs";
+
+/** @param {string} home */
+export function userConfigPath(home) {
+  return path.join(home, ".config/personal-memory/config.toml");
+}
+
+/** @param {string} repoRoot */
+export function projectConfigPaths(repoRoot) {
+  return [
+    path.join(repoRoot, "openmem.toml"),
+    path.join(repoRoot, "config/openmem.toml"),
+    // Pre-rebrand filenames still load if present.
+    path.join(repoRoot, "personal-memory.toml"),
+    path.join(repoRoot, "config/personal-memory.toml"),
+  ];
+}
+
+/**
+ * @param {string} file
+ * @returns {Record<string, unknown>}
+ */
+function readTomlFile(file) {
+  if (!fs.existsSync(file)) return {};
+  try {
+    return TOML.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`${file}: ${/** @type {Error} */ (e).message}`);
+  }
+}
+
+/** @param {Record<string, unknown>} base @param {Record<string, unknown>} over */
+function deepMerge(base, over) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    if (v && typeof v === "object" && !Array.isArray(v) && typeof out[k] === "object") {
+      out[k] = deepMerge(/** @type {Record<string, unknown>} */ (out[k]), /** @type {Record<string, unknown>} */ (v));
+    } else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * @param {string} home
+ * @param {string} repoRoot
+ * @returns {{ merged: Record<string, unknown>, userPath: string, wroteFrom: string[] }}
+ */
+export function loadPmConfig(home, repoRoot) {
+  let merged = {};
+  const wroteFrom = [];
+  for (const p of projectConfigPaths(repoRoot)) {
+    if (fs.existsSync(p)) {
+      merged = deepMerge(merged, readTomlFile(p));
+      wroteFrom.push(p);
+    }
+  }
+  const userPath = userConfigPath(home);
+  if (fs.existsSync(userPath)) {
+    merged = deepMerge(merged, readTomlFile(userPath));
+    wroteFrom.push(userPath);
+  }
+  return { merged, userPath, wroteFrom };
+}
+
+/**
+ * Flat defaults for the wizard (--yes / Clack initialValue). Provider-specific tables
+ * ([model], provider ports) are read by the provider's own hooks from `cfg`.
+ * @param {Record<string, unknown>} cfg
+ */
+export function defaultsFromPmConfig(cfg) {
+  const memory = /** @type {Record<string, unknown>} */ (cfg.memory || {});
+  const stack = /** @type {Record<string, unknown>} */ (cfg.stack || {});
+  const wizard = /** @type {Record<string, unknown>} */ (cfg.wizard || {});
+
+  return {
+    memoryProvider: String(memory.provider || ""),
+    stackProject: String(stack.project || ""),
+    wizardAction: String(wizard.action || ""),
+  };
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {Record<string, Record<string, unknown>>} [sections] provider-owned tables:
+ *   `stack` keys are merged into [stack]; `memory` sub-tables (for example `memory.mem0`) are
+ *   merged into [memory], and `provider` there is always the active provider id; every other
+ *   key becomes its own top-level table
+ * @returns {string}
+ */
+export function buildPmConfigToml(ctx, sections = {}) {
+  const { stack: stackExtra = {}, memory: memoryExtra = {}, ...rest } = sections;
+  const doc = {
+    memory: { ...memoryExtra, provider: ctx.memoryProvider?.id || DEFAULT_PROVIDER_ID },
+    stack: { project: ctx.project, ...stackExtra },
+    wizard: { action: ctx.action || "configure" },
+    ...rest,
+    tasks: {
+      configure: { description: "Secrets, index sources, build images, compose up" },
+      up: { description: "Start stack using existing config" },
+      down: { description: "docker compose down for this project" },
+      doctor: { description: "Validate memory setup on this machine" },
+    },
+  };
+  return `# Written by ./setup — mise-like config for openmem.\n# Docs: docs/openmem-config.md\n${TOML.stringify(doc)}`;
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {Record<string, Record<string, unknown>>} [sections] see buildPmConfigToml
+ */
+export function syncPmConfig(ctx, sections = {}) {
+  if (ctx.dry) return;
+  const dir = path.dirname(userConfigPath(ctx.home));
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = userConfigPath(ctx.home);
+  fs.writeFileSync(file, buildPmConfigToml(ctx, sections), { mode: 0o600 });
+}
+
+/**
+ * Minimal in-place update of `memory.provider` in the user config.toml when the file
+ * already exists. Does not create the file (unlike syncPmConfig).
+ *
+ * @param {string} home
+ * @param {string} providerId
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {"updated"|"skipped"|"dry-run"}
+ */
+export function updatePmConfigProvider(home, providerId, opts = {}) {
+  const file = userConfigPath(home);
+  if (!fs.existsSync(file)) return "skipped";
+  if (opts.dry) return "dry-run";
+  const doc = readTomlFile(file);
+  const memory = {
+    ...(doc.memory && typeof doc.memory === "object" && !Array.isArray(doc.memory)
+      ? /** @type {Record<string, unknown>} */ (doc.memory)
+      : {}),
+    provider: providerId,
+  };
+  doc.memory = memory;
+  const header =
+    "# Written by openmem — mise-like config.\n# Docs: docs/openmem-config.md\n";
+  fs.writeFileSync(file, `${header}${TOML.stringify(doc)}`, { mode: 0o600 });
+  return "updated";
+}
+
+/**
+ * Apply config defaults into process.env when env/CLI did not set them. Only the
+ * provider-neutral keys live here; a provider maps its own tables in its `init` hook.
+ * @param {Record<string, unknown>} cfg
+ */
+export function applyPmConfigEnv(cfg) {
+  const d = defaultsFromPmConfig(cfg);
+  if (d.memoryProvider && !process.env.MEMORY_PROVIDER) {
+    process.env.MEMORY_PROVIDER = d.memoryProvider;
+  }
+  if (d.stackProject && !process.env.PM_PROJECT) process.env.PM_PROJECT = d.stackProject;
+  if (d.wizardAction && !process.env.PM_WIZARD_ACTION) {
+    process.env.PM_WIZARD_ACTION = d.wizardAction;
+  }
+}

package/wizard/lib/ports.mjs

@@ -0,0 +1,94 @@
+import net from "node:net";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { envValue } from "./paths.mjs";
+import { ok, warn, die } from "./log.mjs";
+import { confirm } from "./prompts.mjs";
+
+/**
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+export function portFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", () => resolve(false));
+    server.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Keep a host port when it is free (or held by this compose project); otherwise offer
+ * the next free one.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} label
+ * @param {number} port
+ * @param {{ envVars?: string[] }} [opts] env var names that override the ports, for messages
+ * @returns {Promise<number>}
+ */
+export async function choosePort(ctx, label, port, opts = {}) {
+  const envVars = opts.envVars || [];
+  if (await portFree(port)) {
+    ok(`${label} port ${port} is free`);
+    return port;
+  }
+  let owner = "";
+  const ps = spawnSync(
+    "docker",
+    ["ps", "--filter", `publish=${port}`, "--format", "{{.Label \"com.docker.compose.project\"}}"],
+    { encoding: "utf8" },
+  );
+  if (ps.status === 0 && ps.stdout) {
+    owner = ps.stdout.split("\n").find((l) => l.trim())?.trim() || "";
+  }
+  if (owner === ctx.project) {
+    ok(`${label} port ${port} is held by this project (${ctx.project})`);
+    return port;
+  }
+  if (owner) warn(`${label} port ${port} is held by compose project '${owner}'`);
+  else warn(`${label} port ${port} is held by another process`);
+
+  let alt = 0;
+  for (let i = 1; i <= 50; i++) {
+    if (await portFree(port + i)) {
+      alt = port + i;
+      break;
+    }
+  }
+  if (!alt) {
+    die(
+      `no free port near ${port}${envVars.length ? `; set ${envVars.join(" or ")} and` : ";"} rerun`,
+    );
+  }
+  if (await confirm(ctx, `Use port ${alt} for the ${label} instead (saved to ${path.join(ctx.repoRoot, ".env")})?`, "y")) {
+    return alt;
+  }
+  die(`free port ${port}${envVars.length ? ` (or set ${envVars.join(" / ")})` : ""} and rerun ./setup`);
+}
+
+/**
+ * Resolve one host port from the active provider's manifest (`compose.hostPortEnv`,
+ * `compose.defaultHostPort`): process env, then the stack .env, then the default.
+ * Exports the chosen port in process.env under the manifest's variable name.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} [label]
+ * @returns {Promise<number>}
+ */
+export async function resolveHostPort(ctx, label) {
+  const compose = ctx.memoryProvider?.compose || {};
+  const envName = compose.hostPortEnv;
+  if (!envName) die(`provider ${ctx.memoryProvider?.id} declares no compose.hostPortEnv`);
+  const wanted =
+    process.env[envName] ||
+    envValue(path.join(ctx.repoRoot, ".env"), envName) ||
+    String(compose.defaultHostPort ?? 8888);
+  if (!/^\d+$/.test(wanted)) die(`${envName} must be a port number`);
+  const port = await choosePort(ctx, label || `${ctx.memoryProvider.label} API`, Number(wanted), {
+    envVars: [envName],
+  });
+  process.env[envName] = String(port);
+  return port;
+}

package/wizard/lib/prompts.mjs

@@ -0,0 +1,57 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} prompt
+ * @param {string} defaultValue
+ */
+export async function ask(ctx, prompt, defaultValue) {
+  if (ctx.yes) return defaultValue;
+  if (!process.stdin.isTTY) return defaultValue;
+  try {
+    const clack = await import("@clack/prompts");
+    const v = await clack.text({
+      message: prompt,
+      placeholder: defaultValue,
+      defaultValue,
+    });
+    if (clack.isCancel(v)) process.exit(0);
+    const s = String(v ?? "").trim();
+    return s || defaultValue;
+  } catch {
+    const rl = readline.createInterface({ input, output });
+    const line = await rl.question(`  ${prompt} [${defaultValue}]: `);
+    rl.close();
+    const s = line.trim();
+    return s || defaultValue;
+  }
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} prompt
+ * @param {"y"|"n"} defaultYN
+ */
+export async function confirm(ctx, prompt, defaultYN) {
+  if (ctx.yes) return defaultYN === "y";
+  if (!process.stdin.isTTY) return defaultYN === "y";
+  try {
+    const clack = await import("@clack/prompts");
+    const v = await clack.confirm({
+      message: prompt,
+      active: "yes",
+      inactive: "no",
+      initialValue: defaultYN === "y",
+    });
+    if (clack.isCancel(v)) process.exit(0);
+    return Boolean(v);
+  } catch {
+    const hint = defaultYN === "y" ? "Y/n" : "y/N";
+    const rl = readline.createInterface({ input, output });
+    const line = await rl.question(`  ${prompt} [${hint}]: `);
+    rl.close();
+    const reply = (line.trim() || defaultYN).toLowerCase();
+    return reply === "y" || reply === "yes";
+  }
+}