@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/wizard/lib/pm-config.mjs

@@ -0,0 +1,371 @@
+import fs from "node:fs";
+import path from "node:path";
+import TOML from "@iarna/toml";
+import { writeFileAtomic } from "../../cli/coding-agent/file-io.mjs";
+import { DEFAULT_PROVIDER_ID } from "./providers/registry.mjs";
+
+/** Tables owned by install-coding-agent; the wizard carries them over when it rewrites the file. */
+const INSTALLER_TABLES = ["agents", "context_proxy", "compaction", "context_store"];
+const AGENT_INTEGRATIONS = ["openmem", "provider"];
+const DEFAULT_CONTEXT_PROXY_PORT = 4100;
+/** `[context_proxy.agents]` keys. opencode2 trims in its plugin; the others route through the proxy service. */
+export const CONTEXT_AGENT_KEYS = ["claude-code", "opencode1", "codex", "opencode2"];
+export const CONTEXT_PROXY_AGENT_KEYS = ["claude-code", "opencode1", "codex"];
+// Same defaults as proxy/openmem_context/settings.py and cli/coding-agent/context-trim.mjs.
+const DEFAULT_TRIM_AT_TOKENS = 120000;
+const DEFAULT_COMPRESS_OVER_TOKENS = 4000;
+const DEFAULT_COMPACTION_MAX_CHARS = 12000;
+/** Config keys that reach the proxy container (stack .env) and the OpenCode 2 plugin as env. */
+const CONTEXT_TRIM_ENV_KEYS = [
+  ["context_proxy", "trim_at_tokens", "CONTEXT_TRIM_AT_TOKENS"],
+  ["context_proxy", "compress_over_tokens", "CONTEXT_COMPRESS_OVER_TOKENS"],
+  ["compaction", "max_chars", "CONTEXT_COMPACTION_MAX_CHARS"],
+  ["context_store", "ttl_days", "CONTEXT_STORE_TTL_DAYS"],
+  ["context_store", "embedding_max_chars", "CONTEXT_EMBEDDING_MAX_CHARS"],
+];
+/** String keys of `[context_store]` and their env names (session database vectors, docs/context-store.md). */
+const CONTEXT_STORE_STRING_KEYS = [
+  ["embedding_model", "CONTEXT_EMBEDDING_MODEL"],
+  ["embedding_url", "CONTEXT_EMBEDDING_URL"],
+];
+const CONFIG_MODE = 0o600;
+const CONFIG_HEADER = "# Written by openmem — mise-like config.\n# Docs: docs/openmem-config.md\n";
+
+/** @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}`);
+  }
+}
+
+/** Atomic rewrite; a new file is created mode 600, an existing one keeps its mode. */
+function writeConfigFile(file, text) {
+  writeFileAtomic(file, text, fs.existsSync(file) ? {} : { mode: CONFIG_MODE });
+}
+
+/** @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);
+  let previous = {};
+  try {
+    previous = readTomlFile(file);
+  } catch {
+    // A malformed file is replaced, as before; nothing to carry over.
+  }
+  const kept = Object.fromEntries(
+    INSTALLER_TABLES.filter((t) => previous[t] && !(t in sections)).map((t) => [t, previous[t]]),
+  );
+  writeConfigFile(file, buildPmConfigToml(ctx, { ...sections, ...kept }));
+}
+
+/**
+ * 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;
+  writeConfigFile(file, `${CONFIG_HEADER}${TOML.stringify(doc)}`);
+  return "updated";
+}
+
+/**
+ * Merge `values` into one top-level table of the user config.toml, creating the file
+ * (mode 600, directory 700) when it is missing. Other tables are kept.
+ *
+ * @param {string} home
+ * @param {string} table
+ * @param {Record<string, unknown>} values
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {"updated"|"dry-run"}
+ */
+export function updatePmConfigTable(home, table, values, opts = {}) {
+  if (opts.dry) return "dry-run";
+  const file = userConfigPath(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const doc = readTomlFile(file);
+  const current = doc[table] && typeof doc[table] === "object" && !Array.isArray(doc[table])
+    ? /** @type {Record<string, unknown>} */ (doc[table])
+    : {};
+  doc[table] = { ...current, ...values };
+  writeConfigFile(file, `${CONFIG_HEADER}${TOML.stringify(doc)}`);
+  return "updated";
+}
+
+/**
+ * Write per-agent context management values into `[context_proxy.agents]` (merged with saved keys) and set
+ * `[context_proxy] enabled` to whether any agent resolves on. Other `[context_proxy]` keys are kept.
+ * @param {string} home
+ * @param {Record<string, boolean>} values keys from CONTEXT_AGENT_KEYS
+ * @param {{ dry?: boolean }} [opts]
+ * @returns {{ result: "updated"|"dry-run", agents: Record<string, boolean>, enabled: boolean }}
+ */
+export function updatePmConfigContextAgents(home, values, opts = {}) {
+  const file = userConfigPath(home);
+  const doc = fs.existsSync(file) ? readTomlFile(file) : {};
+  const current = contextAgentsFromPmConfig(doc).agents;
+  const agents = { ...current, ...values };
+  const enabled = CONTEXT_AGENT_KEYS.some((k) => agents[k]);
+  const result = updatePmConfigTable(home, "context_proxy", { enabled, agents }, opts);
+  return { result, agents, enabled };
+}
+
+/**
+ * `[agents] integration`: "openmem" (OpenMem hooks) or "provider" (the provider's own plugin).
+ * @param {Record<string, unknown>} cfg
+ */
+export function agentIntegrationFromPmConfig(cfg) {
+  const value = String(/** @type {Record<string, unknown>} */ (cfg.agents || {}).integration || "");
+  return AGENT_INTEGRATIONS.includes(value) ? value : "openmem";
+}
+
+/** @param {Record<string, unknown>} cfg @param {string} name */
+function tableOf(cfg, name) {
+  const t = cfg?.[name];
+  return t && typeof t === "object" && !Array.isArray(t) ? /** @type {Record<string, unknown>} */ (t) : {};
+}
+
+/** A non-negative integer config value, or undefined when unset or invalid. */
+function countValue(value) {
+  if (value === null || value === undefined || typeof value === "boolean" || typeof value === "string") return undefined;
+  const n = Number(value);
+  return Number.isSafeInteger(n) && n >= 0 ? n : undefined;
+}
+
+/**
+ * `[context_proxy]` wiring with defaults: disabled, port 4100.
+ * @param {Record<string, unknown>} cfg
+ */
+export function contextProxyFromPmConfig(cfg) {
+  const table = tableOf(cfg, "context_proxy");
+  const port = Number(table.port);
+  return {
+    enabled: table.enabled === true,
+    port: Number.isInteger(port) && port > 0 && port < 65536 ? port : DEFAULT_CONTEXT_PROXY_PORT,
+  };
+}
+
+/**
+ * Per-agent context management: `[context_proxy.agents] <key> = true|false`, a missing key following
+ * `[context_proxy] enabled`; with neither set, opencode2 is on (it needs no service) and the proxy-routed
+ * agents are off. Keys: CONTEXT_AGENT_KEYS. `saved` lists the keys that config.toml sets.
+ * @param {Record<string, unknown>} cfg
+ * @returns {{ agents: Record<string, boolean>, saved: string[], enabledSaved: boolean }}
+ */
+export function contextAgentsFromPmConfig(cfg) {
+  const table = tableOf(cfg, "context_proxy");
+  const overrides = tableOf(table, "agents");
+  const enabledSaved = typeof table.enabled === "boolean";
+  const agents = {};
+  const saved = [];
+  for (const key of CONTEXT_AGENT_KEYS) {
+    if (typeof overrides[key] === "boolean") {
+      agents[key] = overrides[key];
+      saved.push(key);
+    } else agents[key] = enabledSaved ? table.enabled : key === "opencode2";
+  }
+  return { agents, saved, enabledSaved };
+}
+
+/**
+ * Trim settings with defaults: `[context_proxy] trim_at_tokens` (120000; unset, the proxy and plugin trim Haiku at 95000), `compress_over_tokens`
+ * (4000), `standing_instruction` (true), `[compaction] max_chars` (12000), `native` (true). Env overrides are applied by
+ * `contextTrimEnvFromPmConfig` + `trimSettings()`, not here.
+ * @param {Record<string, unknown>} cfg
+ */
+export function contextTrimFromPmConfig(cfg) {
+  const proxy = tableOf(cfg, "context_proxy");
+  const compaction = tableOf(cfg, "compaction");
+  return {
+    trimAtTokens: countValue(proxy.trim_at_tokens) ?? DEFAULT_TRIM_AT_TOKENS,
+    compressOverTokens: countValue(proxy.compress_over_tokens) ?? DEFAULT_COMPRESS_OVER_TOKENS,
+    compactionMaxChars: countValue(compaction.max_chars) ?? DEFAULT_COMPACTION_MAX_CHARS,
+    compactionNative: compaction.native !== false,
+    standingInstruction: proxy.standing_instruction !== false,
+  };
+}
+
+/**
+ * Context-trim settings that config.toml sets, as the environment variables the proxy and
+ * `trimSettings()` read: `[context_proxy] trim_at_tokens` → CONTEXT_TRIM_AT_TOKENS,
+ * `compress_over_tokens` → CONTEXT_COMPRESS_OVER_TOKENS, `[compaction] max_chars` →
+ * CONTEXT_COMPACTION_MAX_CHARS, `[context_proxy] standing_instruction` (boolean) →
+ * CONTEXT_STANDING_INSTRUCTION ("1" / "0"), `[compaction] recall` (boolean) → CONTEXT_COMPACTION_RECALL
+ * ("1" / "0"), `[context_proxy] chars_per_token` (positive number) →
+ * CONTEXT_CHARS_PER_TOKEN, `trim_to_fraction` (0 < x < 1) → CONTEXT_TRIM_TO_FRACTION, `[context_store] ttl_days` → CONTEXT_STORE_TTL_DAYS, `embedding_model` →
+ * CONTEXT_EMBEDDING_MODEL, `embedding_url` → CONTEXT_EMBEDDING_URL, `embedding_timeout_s` (positive number) →
+ * CONTEXT_EMBEDDING_TIMEOUT_S, `embedding_max_chars` → CONTEXT_EMBEDDING_MAX_CHARS. Unset or invalid keys are left out, so the reader's defaults
+ * apply. Real env vars override: `trimSettings({ ...contextTrimEnvFromPmConfig(cfg), ...process.env })`.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, string>}
+ */
+export function contextTrimEnvFromPmConfig(cfg) {
+  const out = {};
+  for (const [table, key, envName] of CONTEXT_TRIM_ENV_KEYS) {
+    const value = countValue(tableOf(cfg, table)[key]);
+    if (value !== undefined) out[envName] = String(value);
+  }
+  const standing = tableOf(cfg, "context_proxy").standing_instruction;
+  if (typeof standing === "boolean") out.CONTEXT_STANDING_INSTRUCTION = standing ? "1" : "0";
+  const recall = tableOf(cfg, "compaction").recall;
+  if (typeof recall === "boolean") out.CONTEXT_COMPACTION_RECALL = recall ? "1" : "0";
+  const fraction = tableOf(cfg, "context_proxy").trim_to_fraction;
+  if (typeof fraction === "number" && Number.isFinite(fraction) && fraction > 0 && fraction < 1) {
+    out.CONTEXT_TRIM_TO_FRACTION = String(fraction);
+  }
+  const ratio = tableOf(cfg, "context_proxy").chars_per_token;
+  if (typeof ratio === "number" && Number.isFinite(ratio) && ratio > 0) out.CONTEXT_CHARS_PER_TOKEN = String(ratio);
+  const store = tableOf(cfg, "context_store");
+  const timeout = store.embedding_timeout_s;
+  if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) out.CONTEXT_EMBEDDING_TIMEOUT_S = String(timeout);
+  for (const [key, envName] of CONTEXT_STORE_STRING_KEYS) {
+    if (typeof store[key] === "string") out[envName] = store[key].trim();
+  }
+  return out;
+}
+
+/**
+ * Stack .env entries for the context-proxy compose service: the trim env above plus
+ * CONTEXT_PROXY_PORT when `[context_proxy] port` is set, so the container binds the port
+ * Claude Code is pointed at.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, string>}
+ */
+export function contextProxyStackEnvFromPmConfig(cfg) {
+  const out = contextTrimEnvFromPmConfig(cfg);
+  if (tableOf(cfg, "context_proxy").port !== undefined) out.CONTEXT_PROXY_PORT = String(contextProxyFromPmConfig(cfg).port);
+  return out;
+}
+
+/**
+ * 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,85 @@
+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;
+  }
+}
+
+/**
+ * Pick any of `options`; `--yes` and non-TTY runs return `initial`.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} prompt
+ * @param {{ value: string, label: string }[]} options
+ * @param {string[]} initial
+ * @returns {Promise<string[]>}
+ */
+export async function multiselect(ctx, prompt, options, initial) {
+  if (ctx.yes) return initial;
+  if (!process.stdin.isTTY) return initial;
+  try {
+    const clack = await import("@clack/prompts");
+    const v = await clack.multiselect({ message: prompt, options, initialValues: initial, required: false });
+    if (clack.isCancel(v)) process.exit(0);
+    return /** @type {string[]} */ (v);
+  } catch {
+    const rl = readline.createInterface({ input, output });
+    const names = options.map((o) => o.value).join(", ");
+    const line = await rl.question(`  ${prompt} (comma-separated: ${names}; "none" for none) [${initial.join(",") || "none"}]: `);
+    rl.close();
+    const s = line.trim();
+    if (!s) return initial;
+    if (s === "none") return [];
+    return s.split(",").map((x) => x.trim()).filter((x) => options.some((o) => o.value === x));
+  }
+}
+
+/**
+ * @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";
+  }
+}

package/wizard/lib/provider-wizard/helpers.mjs

@@ -0,0 +1,98 @@
+import { step, info, ok, warn, die, problem } from "../log.mjs";
+import { ask, confirm } from "../prompts.mjs";
+import { act, actWithEnv, commandExists } from "../exec.mjs";
+import { curlGet, curlJson, curlRequest } from "../curl.mjs";
+import { loadMachineEnv } from "../load-machine-env.mjs";
+import { envValue, expandHome, ensureHsDir } from "../paths.mjs";
+import { portFree, choosePort, resolveHostPort } from "../ports.mjs";
+import { composeArgs } from "../compose.mjs";
+import { writeWizardConf } from "../wizard-conf.mjs";
+import { providerApiBase } from "../providers/registry.mjs";
+
+/** Bump when a helper is removed or changes meaning; adding helpers does not bump it. */
+export const HELPERS_API_VERSION = 2;
+
+/**
+ * API passed as the second argument of every hook in providers/<id>/wizard.mjs.
+ * Providers must not import run-wizard.mjs (it imports them); everything the meta wizard
+ * owns reaches them through this object. Check `apiVersion` before relying on a helper.
+ *
+ * Every function that takes `ctx` receives the WizardContext the hook was called with
+ * (`ctx.repoRoot` = mutable stack root, `ctx.packageRoot` = read-only code root).
+ *
+ * @typedef {object} ProviderWizardHelpers
+ * @property {2} apiVersion
+ * @property {(title: string) => void} step print a numbered step heading
+ * @property {(msg: string) => void} info
+ * @property {(msg: string) => void} ok
+ * @property {(msg: string) => void} warn
+ * @property {(msg: string) => never} die print an error and exit 1
+ * @property {(ctx: object, msg: string) => void} problem die, or warn in a dry run
+ * @property {(ctx: object, prompt: string, defaultValue: string) => Promise<string>} ask
+ * @property {(ctx: object, prompt: string, defaultYN: "y"|"n") => Promise<boolean>} confirm
+ * @property {(ctx: object, description: string, cmd: string, args: string[], opts?: { env?: Record<string, string>, cwd?: string }) => Promise<void>} act
+ *   run a command (printed, not run, in a dry run); exits the wizard on failure
+ * @property {(ctx: object, description: string, cmd: string, args: string[], extraEnv: Record<string, string>) => Promise<void>} actWithEnv
+ * @property {(name: string) => boolean} commandExists
+ * @property {(repoRoot: string) => Record<string, string>} loadMachineEnv deprecated; always {}
+ * @property {(file: string, key: string) => string} envValue read one KEY=value from an env file
+ * @property {(p: string, home?: string) => string} expandHome
+ * @property {(ctx: object) => void} ensureConfigDir create the per-machine config dir (no-op in a dry run)
+ * @property {(url: string, timeoutSec?: number) => string} curlGet
+ * @property {(url: string) => object|null} curlJson
+ * @property {(method: string, url: string, jsonBody?: string, timeoutSec?: number) => string} curlRequest
+ * @property {(port: number) => Promise<boolean>} portFree
+ * @property {(ctx: object, label: string, port: number, opts?: { envVars?: string[] }) => Promise<number>} choosePort
+ * @property {(ctx: object, label?: string) => Promise<number>} resolveHostPort
+ *   pick the manifest's host port (compose.hostPortEnv / defaultHostPort) and export it in process.env
+ * @property {(ctx: object, ...rest: string[]) => string[]} composeArgs
+ *   `docker` args for a compose subcommand, with the manifest's profile and files applied
+ * @property {(ctx: object, extra?: Record<string, string>, opts?: { pmSections?: Record<string, Record<string, unknown>> }) => void} saveWizardConf
+ *   write wizard.conf (MEMORY_PROVIDER + extra keys) and config.toml; no-op in a dry run
+ * @property {(ctx: object, opts?: { description?: string, args?: string[], env?: Record<string, string> }) => Promise<void>} runStackSetup
+ *   run scripts/setup.mjs (writes the stack .env and compose.override.yaml, then the provider's
+ *   `prepareStackEnv`); `description` and `env` default to what the `stackEnv` hook returns
+ * @property {(ctx: object) => Promise<string>|string} apiBase the provider's API base URL (apiBase hook, else manifest)
+ */
+
+/**
+ * Build the helper object. With no argument it is fully functional from leaf modules;
+ * the meta wizard overrides the few helpers that need its own state.
+ * @param {Partial<ProviderWizardHelpers>} [impl]
+ * @returns {ProviderWizardHelpers}
+ */
+export function createHelpers(impl = {}) {
+  return Object.freeze(
+    /** @type {ProviderWizardHelpers} */ ({
+      apiVersion: HELPERS_API_VERSION,
+      step,
+      info,
+      ok,
+      warn,
+      die,
+      problem,
+      ask,
+      confirm,
+      act,
+      actWithEnv,
+      commandExists,
+      loadMachineEnv,
+      envValue,
+      expandHome,
+      ensureConfigDir: ensureHsDir,
+      curlGet,
+      curlJson,
+      curlRequest,
+      portFree,
+      choosePort,
+      resolveHostPort,
+      composeArgs,
+      saveWizardConf: writeWizardConf,
+      runStackSetup: async () => {
+        throw new Error("runStackSetup is only available inside the meta wizard");
+      },
+      apiBase: (ctx) => providerApiBase(ctx, ctx.memoryProvider),
+      ...impl,
+    }),
+  );
+}