@bcmyguest/openmem 0.0.0-stage → 0.8.0

package/wizard/bin/pm.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Mise-like task runner for openmem (reads ~/.config/personal-memory/config.toml).
+ *   ./pm configure | up | down | doctor
+ * Packaged installs reach it through `openmem <task>`.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { ensureWizardDeps, resolveWizardRoots } from "../../cli/roots.mjs";
+
+const { pkgRoot, repo: REPO, packaged } = resolveWizardRoots(import.meta.url);
+// setup.mjs is code, so it always comes from the package root, never the stack root.
+const SETUP = path.join(pkgRoot, "wizard/bin/setup.mjs");
+
+const TASKS = {
+  configure: { args: ["--yes"], help: "Full setup and start" },
+  up: { args: ["--up", "--yes"], help: "Start stack" },
+  down: { args: ["--down", "--yes"], help: "Stop stack" },
+  doctor: { args: ["--yes", "--no-smoke"], help: "Validate config (no smoke)" },
+  "install-mcp": {
+    script: "cli/install-memory-mcp.mjs",
+    help: "Install memory MCP servers into ~/.cursor/mcp.json",
+  },
+  "install-coding-agent": {
+    script: "cli/install-coding-agent.mjs",
+    help: "Wire session memory for Claude Code, Codex, OpenCode, Cursor CLI",
+  },
+  "feed-sync": {
+    script: "cli/feed-sync.mjs",
+    help: "Fetch RSS/OpenAlex feeds into index.yml feeds.out_dir",
+  },
+  switch: {
+    script: "cli/switch-memory-provider.mjs",
+    help: "Switch MEMORY_PROVIDER (wizard.conf + optional stack/MCP)",
+  },
+};
+
+const task = process.argv[2];
+if (!task || task === "-h" || task === "--help") {
+  ensureWizardDeps(pkgRoot, packaged);
+  const { loadPmConfig } = await import("../lib/pm-config.mjs");
+  const home = process.env.HOME || "";
+  const { merged } = loadPmConfig(home, REPO);
+  const tasks = /** @type {Record<string, {description?: string}>} */ (
+    merged.tasks || {}
+  );
+  console.log("Usage: pm <task>\n");
+  console.log("Tasks:");
+  for (const name of Object.keys(TASKS)) {
+    const desc = tasks[name]?.description || TASKS[name].help;
+    console.log(`  ${name.padEnd(12)} ${desc}`);
+  }
+  process.exit(task ? 0 : 1);
+}
+
+const spec = TASKS[task];
+if (!spec) {
+  console.error(`unknown task: ${task} (try: ${Object.keys(TASKS).join(", ")})`);
+  process.exit(1);
+}
+
+const extra = process.argv.slice(3);
+
+if (spec.script) {
+  const script = path.join(pkgRoot, spec.script);
+  if (!fs.existsSync(script)) {
+    console.error(`${spec.script} not found; run from a openmem checkout or install`);
+    process.exit(1);
+  }
+  const r = spawnSync(process.execPath, [script, ...extra], {
+    cwd: REPO,
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(r.status ?? 1);
+}
+
+if (!fs.existsSync(SETUP)) {
+  console.error("setup.mjs not found; run from a openmem checkout or install");
+  process.exit(1);
+}
+
+const r = spawnSync(process.execPath, [SETUP, ...spec.args, ...extra], {
+  cwd: REPO,
+  stdio: "inherit",
+  env: process.env,
+});
+if (task === "doctor" && (r.status ?? 1) === 0) {
+  const wiring = spawnSync(process.execPath, [path.join(pkgRoot, "cli/wiring-report.mjs")], {
+    cwd: REPO,
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(wiring.status ?? 0);
+}
+process.exit(r.status ?? 1);

package/wizard/bin/setup.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Setup wizard entry (./setup in a checkout; `openmem setup` when packaged).
+ *
+ * REPO is the mutable stack root (PM_STACK_ROOT, default: the checkout): compose project
+ * dir, .env, generated files and docker build context. PM_PACKAGE_ROOT is the read-only
+ * code root (providers/, scripts/setup.mjs, wizard/lib).
+ */
+import { ensureWizardDeps, resolveWizardRoots } from "../../cli/roots.mjs";
+
+const { pkgRoot, repo: REPO, packaged } = resolveWizardRoots(import.meta.url);
+ensureWizardDeps(pkgRoot, packaged);
+
+const { runWizard } = await import("../lib/run-wizard.mjs");
+
+const argv = process.argv.slice(2);
+const wantsClack =
+  !argv.includes("--yes") &&
+  !argv.includes("-y") &&
+  !argv.includes("--dry-run") &&
+  process.stdin.isTTY;
+
+/** @type {Record<string, string>} */
+let handoff = {};
+if (wantsClack) {
+  const { runClackSetup } = await import("../lib/run-clack.mjs");
+  handoff = await runClackSetup(REPO);
+  for (const [k, v] of Object.entries(handoff)) {
+    process.env[k] = v;
+  }
+}
+
+await runWizard(REPO, argv);

package/wizard/lib/compose-version.mjs

@@ -0,0 +1,32 @@
+/**
+ * Docker Compose version gate for the wizard preflight.
+ *
+ * Provider compose fragments use `env_file: [{path, required: false}]`, which needs Compose 2.24;
+ * the Hindsight base file already needs 2.20 for `depends_on.required`. The wizard requires the
+ * higher bar everywhere so a stack never fails halfway through `docker compose up`.
+ */
+
+export const MIN_COMPOSE = { major: 2, minor: 24 };
+
+/**
+ * Parse `docker compose version --short` ("2.29.0", "v2.29.0") or the long form
+ * ("Docker Compose version v2.29.0"). Returns null when no version is found.
+ * @param {string} text
+ * @returns {{major:number, minor:number}|null}
+ */
+export function parseComposeVersion(text) {
+  const m = String(text || "").match(/v?(\d+)\.(\d+)/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]) } : null;
+}
+
+/**
+ * @param {{major:number, minor:number}|null} version
+ * @returns {boolean} true when the version meets MIN_COMPOSE
+ */
+export function composeVersionOk(version) {
+  if (!version) return false;
+  if (version.major !== MIN_COMPOSE.major) return version.major > MIN_COMPOSE.major;
+  return version.minor >= MIN_COMPOSE.minor;
+}
+
+export const COMPOSE_TOO_OLD_HINT = `Docker Compose ${MIN_COMPOSE.major}.${MIN_COMPOSE.minor} or newer is required (docker compose version --short); provider compose files use env_file required: false. Update the compose plugin`;

package/wizard/lib/compose.mjs

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Compose profiles for the active provider + optional extras (Ollama, NotebookLM).
+ *
+ * @param {{ memoryProvider?: { compose?: { profile?: string } }, extraComposeProfiles?: string[] }} ctx
+ * @returns {string[]}
+ */
+export function composeProfiles(ctx) {
+  const compose = ctx.memoryProvider?.compose || {};
+  const profiles = [];
+  if (compose.profile) profiles.push(compose.profile);
+  for (const p of ctx.extraComposeProfiles || []) {
+    if (typeof p === "string" && p && !profiles.includes(p)) profiles.push(p);
+  }
+  return profiles;
+}
+
+/**
+ * Arguments for `docker` that run a compose subcommand for the active provider.
+ *
+ * Every compose call in the wizard goes through here so the manifest's
+ * `compose.profile` and `compose.files` apply uniformly (up, build, run, down, ps).
+ * With no `compose.files`, no -f flag is added and compose auto-loads compose.yaml
+ * and compose.override.yaml from the stack root. With `compose.files`, the list is
+ * compose.yaml, compose.override.yaml (when present), then the extra files.
+ *
+ * Extra profiles (compose Ollama, NotebookLM) come from `ctx.extraComposeProfiles`.
+ * Docker Compose unions CLI `--profile` with `COMPOSE_PROFILES` from `.env`, so
+ * `composeSpawnOptions` overrides that env var to the same list — otherwise `.env`
+ * can start NotebookLM while the wizard intentionally omitted it (e.g. during smoke).
+ *
+ * @param {{ project: string, repoRoot: string, memoryProvider?: { compose?: { profile?: string, files?: string[] } }, extraComposeProfiles?: string[] }} ctx
+ * @param {...string} rest the compose subcommand and its arguments
+ * @returns {string[]}
+ */
+export function composeArgs(ctx, ...rest) {
+  const compose = ctx.memoryProvider?.compose || {};
+  const args = ["compose", "-p", ctx.project];
+  const extra = Array.isArray(compose.files) ? compose.files : [];
+  if (extra.length) {
+    args.push("-f", "compose.yaml");
+    if (fs.existsSync(path.join(ctx.repoRoot, "compose.override.yaml"))) {
+      args.push("-f", "compose.override.yaml");
+    }
+    for (const f of extra) args.push("-f", f);
+  }
+  for (const p of composeProfiles(ctx)) args.push("--profile", p);
+  return [...args, ...rest];
+}
+
+/** `docker ...` as the wizard prints it in descriptions. */
+export function composeCommandText(ctx, ...rest) {
+  return `docker ${composeArgs(ctx, ...rest).join(" ")}`;
+}
+
+/**
+ * Spawn options for compose calls: cwd is the stack root; COMPOSE_PROFILES matches
+ * the `--profile` flags so `.env` cannot enable extra profiles behind the wizard's back.
+ */
+export function composeSpawnOptions(ctx) {
+  return {
+    cwd: ctx.repoRoot,
+    env: {
+      ...process.env,
+      COMPOSE_PROFILES: composeProfiles(ctx).join(","),
+    },
+  };
+}

package/wizard/lib/context-step.mjs

@@ -0,0 +1,140 @@
+import { spawnSync } from "node:child_process";
+import {
+  CONTEXT_PROXY_SERVICE,
+  contextProxyRunning,
+  prepareContextProxyFiles,
+  proxyServiceNeeded,
+} from "../../cli/context-management.mjs";
+import { agentsPointedAtContextProxy } from "../../cli/coding-agent/install-context-proxy.mjs";
+import { act } from "./exec.mjs";
+import { composeArgs, composeSpawnOptions } from "./compose.mjs";
+import { info, ok, step, warn } from "./log.mjs";
+import { multiselect } from "./prompts.mjs";
+import { CONTEXT_AGENT_KEYS, contextAgentsFromPmConfig, updatePmConfigContextAgents } from "./pm-config.mjs";
+
+/**
+ * Wizard step "Context management (smart compaction)": pick the installed agents to trim, save
+ * `[context_proxy.agents]` and `[context_proxy] enabled` (syncPmConfig keeps the table when it rewrites
+ * config.toml), and start or stop the compose `context-proxy` service. install-coding-agent reads the
+ * saved values when the next step wires agents.
+ */
+
+export const CONTEXT_STEP_TITLE = "Context management (smart compaction)";
+/** Agents the step offers. */
+const SELECTABLE = ["claude-code", "opencode1", "codex", "opencode2"];
+const LABELS = {
+  "claude-code": "Claude Code (context-proxy service)",
+  opencode1: "OpenCode 1 (context-proxy service)",
+  codex: "Codex (context-proxy service, ChatGPT login)",
+  opencode2: "OpenCode 2 (native plugin, no service)",
+};
+
+/**
+ * Config keys for detected harnesses (`claude-code`, `codex`, `opencode`, `cursor-cli`).
+ * @param {string[]} harnesses
+ * @param {number} opencodeMajor
+ */
+export function contextAgentKeys(harnesses, opencodeMajor) {
+  const keys = [];
+  if (harnesses.includes("claude-code")) keys.push("claude-code");
+  if (harnesses.includes("codex")) keys.push("codex");
+  if (harnesses.includes("opencode")) keys.push(opencodeMajor >= 2 ? "opencode2" : "opencode1");
+  return keys;
+}
+
+/**
+ * Defaults: a saved per-agent key, else a saved `enabled`, else OpenCode 2 on and the proxy-routed agents off.
+ * @param {Record<string, unknown>} cfg
+ * @returns {Record<string, boolean>}
+ */
+export function contextAgentDefaults(cfg) {
+  return contextAgentsFromPmConfig(cfg).agents;
+}
+
+/** Whether the proxy service is needed: the step's choice, else the saved config. */
+export function contextServiceWanted(ctx) {
+  return proxyServiceNeeded(ctx.contextAgents || contextAgentsFromPmConfig(ctx.pmMerged || {}).agents);
+}
+
+/** Context with the context-proxy profile added, for compose calls on that service. */
+function withProxyProfile(ctx) {
+  return { ...ctx, extraComposeProfiles: [...(ctx.extraComposeProfiles || []), CONTEXT_PROXY_SERVICE] };
+}
+
+/**
+ * Multi-select the installed agents (defaults: contextAgentDefaults) and save the values when they differ
+ * from config. Agents that are not installed keep their saved value, else their default.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} number step number shown in the title
+ * @param {string[]} installed config keys of the installed agents (contextAgentKeys)
+ * @returns {Promise<Record<string, boolean>>}
+ */
+export async function chooseContextManagement(ctx, number, installed) {
+  step(`${number}. ${CONTEXT_STEP_TITLE}`);
+  info("Stores every session message in a local SQLite store and trims long sessions; agents query the trimmed turns with smart_compact_search and smart_compact_sql.");
+  info("Claude Code, OpenCode 1 and Codex go through the local context-proxy compose service; OpenCode 2 uses its native plugin.");
+  const cfg = ctx.pmMerged || {};
+  const { agents: current, saved } = contextAgentsFromPmConfig(cfg);
+  const defaults = contextAgentDefaults(cfg);
+  const offered = SELECTABLE.filter((k) => installed.includes(k));
+  let values;
+  if (!offered.length) {
+    info("no agent that supports context management is installed; saved values kept");
+    values = current;
+  } else {
+    const picked = await multiselect(
+      ctx,
+      "Trim long sessions for which agents?",
+      offered.map((k) => ({ value: k, label: LABELS[k] })),
+      offered.filter((k) => defaults[k]),
+    );
+    values = Object.fromEntries(CONTEXT_AGENT_KEYS.map((k) => [k, offered.includes(k) ? picked.includes(k) : (saved.includes(k) ? current[k] : defaults[k])]));
+    const changed = CONTEXT_AGENT_KEYS.some((k) => !saved.includes(k) || current[k] !== values[k]);
+    if (changed) {
+      const r = updatePmConfigContextAgents(ctx.home, values, { dry: ctx.dry });
+      const summary = CONTEXT_AGENT_KEYS.map((k) => `${k} = ${values[k]}`).join(", ");
+      info(`${r.result === "dry-run" ? "[dry-run] would save" : "saved"} [context_proxy.agents] ${summary}`);
+      if (r.result !== "dry-run") {
+        const table = { ...(cfg.context_proxy || {}), enabled: r.enabled, agents: r.agents };
+        ctx.pmMerged = { ...cfg, context_proxy: table };
+      }
+    }
+  }
+  ctx.contextAgents = values;
+  ok(`context management: ${CONTEXT_AGENT_KEYS.map((k) => `${k} ${values[k] ? "on" : "off"}`).join(", ")}`);
+  return values;
+}
+
+/**
+ * Start the service when a proxy-routed agent is on (before agents are pointed at it). Writes the key file
+ * and store directories compose needs first.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ */
+export async function startContextProxy(ctx) {
+  if (!contextServiceWanted(ctx)) return;
+  if (!ctx.dry) prepareContextProxyFiles(ctx.home);
+  const c = withProxyProfile(ctx);
+  const up = composeArgs(c, "up", "-d", "--no-build", CONTEXT_PROXY_SERVICE);
+  await act(ctx, `docker ${up.join(" ")}`, "docker", up, composeSpawnOptions(c));
+  if (!ctx.dry) ok("context-proxy started");
+}
+
+/**
+ * Stop the service when no proxy-routed agent is on and it runs, unless an agent still points at it
+ * (stopping would break that agent's every request).
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {typeof spawnSync} [spawn]
+ */
+export async function stopContextProxy(ctx, spawn = spawnSync) {
+  if (contextServiceWanted(ctx)) return;
+  const c = withProxyProfile(ctx);
+  if (!contextProxyRunning(composeArgs(c), composeSpawnOptions(c), spawn)) return;
+  const pointed = ctx.dry ? [] : agentsPointedAtContextProxy(ctx.home);
+  if (pointed.length) {
+    warn(`context-proxy left running: ${pointed.join(", ")} still point at it. Run: npx @bcmyguest/openmem install-coding-agent --yes`);
+    return;
+  }
+  const stop = composeArgs(c, "stop", CONTEXT_PROXY_SERVICE);
+  await act(ctx, `docker ${stop.join(" ")}`, "docker", stop, composeSpawnOptions(c));
+  if (!ctx.dry) ok("context-proxy stopped");
+}

package/wizard/lib/curl.mjs

@@ -0,0 +1,103 @@
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * @param {string} url
+ * @param {number} [timeoutSec]
+ * @returns {string}
+ */
+export function curlGet(url, timeoutSec = 5) {
+  const r = spawnSync("curl", ["-fsS", "-m", String(timeoutSec), url], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return "";
+  return r.stdout || "";
+}
+
+/**
+ * @param {string} url
+ * @returns {object|null}
+ */
+export function curlJson(url) {
+  const body = curlGet(url);
+  if (!body) return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} [timeoutSec]
+ * @returns {string}
+ */
+export function curlRequest(method, url, jsonBody, timeoutSec = 60) {
+  const args = curlArgs(method, url, jsonBody, timeoutSec);
+  const r = spawnSync("curl", args, { encoding: "utf8" });
+  if (r.status !== 0) return "";
+  return r.stdout || "";
+}
+
+/**
+ * Build curl argv for a JSON (or empty-body) request.
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} timeoutSec
+ * @returns {string[]}
+ */
+export function curlArgs(method, url, jsonBody, timeoutSec) {
+  const args = ["-fsS", "-m", String(timeoutSec), "-X", method, url];
+  if (jsonBody !== undefined) {
+    args.push("-H", "Content-Type: application/json", "-d", jsonBody);
+  }
+  return args;
+}
+
+/**
+ * Like curlRequest, but async with an optional heartbeat so long retains do not look hung.
+ *
+ * @param {string} method
+ * @param {string} url
+ * @param {string} [jsonBody]
+ * @param {number} [timeoutSec]
+ * @param {{ tickSec?: number, onTick?: (info: { elapsed: number, timeoutSec: number }) => void }} [opts]
+ * @returns {Promise<string>} response body, or "" on failure / timeout
+ */
+export function curlRequestProgress(method, url, jsonBody, timeoutSec = 60, opts = {}) {
+  const tickSec = opts.tickSec ?? 15;
+  const onTick = opts.onTick;
+  const args = curlArgs(method, url, jsonBody, timeoutSec);
+  return new Promise((resolve) => {
+    const child = spawn("curl", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let settled = false;
+    const started = Date.now();
+    const timer =
+      typeof onTick === "function"
+        ? setInterval(() => {
+            onTick({
+              elapsed: Math.round((Date.now() - started) / 1000),
+              timeoutSec,
+            });
+          }, tickSec * 1000)
+        : null;
+
+    const finish = (body) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearInterval(timer);
+      resolve(body);
+    };
+
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.on("error", () => finish(""));
+    child.on("close", (code) => finish(code === 0 ? stdout : ""));
+  });
+}

package/wizard/lib/docker-build.mjs

@@ -0,0 +1,148 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { ok, die } from "./log.mjs";
+import { act } from "./exec.mjs";
+import { composeArgs, composeSpawnOptions } from "./compose.mjs";
+
+function buildDockerfile(svc) {
+  if (svc === "indexer") return "indexer/Dockerfile";
+  if (svc === "notebooklm") return "sync/Dockerfile";
+  die(`the wizard does not build service ${svc}`);
+}
+
+function copySourcesFromDockerfile(repoRoot, dfRel) {
+  const dfPath = path.join(repoRoot, dfRel);
+  const text = fs.readFileSync(dfPath, "utf8");
+  const srcs = [];
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("COPY")) continue;
+    const parts = line.trim().split(/\s+/).slice(1);
+    const filtered = parts.filter((p) => !p.startsWith("--"));
+    for (let i = 0; i < filtered.length - 1; i++) srcs.push(filtered[i]);
+  }
+  return srcs;
+}
+
+function expandInputs(repoRoot, rel) {
+  const abs = path.join(repoRoot, rel);
+  const out = [];
+  if (!fs.existsSync(abs)) {
+    out.push(rel);
+    return out;
+  }
+  if (fs.statSync(abs).isDirectory()) {
+    const walk = (dir, prefix) => {
+      for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (ent.name === "__pycache__" || ent.name.endsWith(".pyc")) continue;
+        const p = path.join(dir, ent.name);
+        const relP = prefix ? `${prefix}/${ent.name}` : ent.name;
+        if (ent.isDirectory()) walk(p, relP);
+        else out.push(relP);
+      }
+    };
+    walk(abs, rel);
+  } else out.push(rel);
+  return out;
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ */
+export function buildHash(ctx, svc) {
+  const df = buildDockerfile(svc);
+  const files = new Set([df, "compose.yaml"]);
+  for (const f of ctx.memoryProvider?.compose?.files || []) files.add(f);
+  for (const src of copySourcesFromDockerfile(ctx.repoRoot, df)) {
+    for (const f of expandInputs(ctx.repoRoot, src)) files.add(f);
+  }
+  const sorted = [...files].sort();
+  const hash = crypto.createHash("sha256");
+  for (const f of sorted) {
+    const p = path.join(ctx.repoRoot, f);
+    if (!fs.existsSync(p)) die(`missing build input ${f}`);
+    hash.update(fs.readFileSync(p));
+  }
+  return hash.digest("hex");
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ * @param {string} hash
+ */
+function recordBuildHash(ctx, svc, hash) {
+  let lines = [];
+  if (fs.existsSync(ctx.buildHashFile)) {
+    lines = fs
+      .readFileSync(ctx.buildHashFile, "utf8")
+      .split("\n")
+      .filter((l) => l && !l.startsWith(`${svc} `));
+  }
+  lines.push(`${svc} ${hash}`);
+  fs.writeFileSync(ctx.buildHashFile, `${lines.join("\n")}\n`);
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} svc
+ * @param {string} image
+ */
+export async function buildService(ctx, svc, image) {
+  const hash = buildHash(ctx, svc);
+  let stored = "";
+  if (fs.existsSync(ctx.buildHashFile)) {
+    for (const line of fs.readFileSync(ctx.buildHashFile, "utf8").split("\n")) {
+      if (line.startsWith(`${svc} `)) stored = line.split(/\s+/)[1] || "";
+    }
+  }
+  const inspect = spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" });
+  const imageOk = inspect.status === 0;
+  if (!ctx.rebuild && stored === hash && imageOk) {
+    ok(`${svc} image unchanged; build skipped`);
+    return;
+  }
+  await act(
+    ctx,
+    `build the ${svc} image (compose project ${ctx.project})`,
+    "docker",
+    composeArgs(ctx, "build", svc),
+    composeSpawnOptions(ctx),
+  );
+  if (ctx.dry) return;
+  recordBuildHash(ctx, svc, hash);
+}
+
+/**
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @returns {Promise<string[]>}
+ */
+export async function snapshot(ctx) {
+  const lines = [];
+  const globHs = fs.existsSync(ctx.hsDir) ? fs.readdirSync(ctx.hsDir) : [];
+  for (const name of globHs) {
+    const f = path.join(ctx.hsDir, name);
+    if (fs.statSync(f).isFile()) {
+      const h = crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+      lines.push(`${f} ${h}`);
+    }
+  }
+  for (const f of [path.join(ctx.repoRoot, ".env"), path.join(ctx.repoRoot, "compose.override.yaml")]) {
+    if (fs.existsSync(f)) {
+      const h = crypto.createHash("sha256").update(fs.readFileSync(f)).digest("hex");
+      lines.push(`${f} ${h}`);
+    }
+  }
+  const ps = spawnSync("docker", composeArgs(ctx, "ps", "-q"), {
+    encoding: "utf8",
+    ...composeSpawnOptions(ctx),
+  });
+  if (ps.status === 0 && ps.stdout) {
+    for (const id of ps.stdout.split("\n").filter(Boolean)) {
+      lines.push(`container ${id.trim()}`);
+    }
+  }
+  return lines.sort();
+}

package/wizard/lib/exec.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { info } from "./log.mjs";
+
+/**
+ * Run a command, or print it when the context is a dry run. Exits the process on failure.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} description
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ env?: Record<string, string>, cwd?: string }} [opts] extra environment, working directory
+ */
+export async function act(ctx, description, cmd, args, opts = {}) {
+  if (ctx.dry) {
+    info(`[dry-run] ${description}`);
+    return;
+  }
+  info(description);
+  const r = spawnSync(cmd, args, {
+    stdio: "inherit",
+    env: { ...process.env, ...(opts.env || {}) },
+    ...(opts.cwd ? { cwd: opts.cwd } : {}),
+  });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+/**
+ * Like act(), with extra environment variables for the child.
+ * @param {import("./run-wizard.mjs").WizardContext} ctx
+ * @param {string} description
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {Record<string, string>} extraEnv
+ */
+export async function actWithEnv(ctx, description, cmd, args, extraEnv) {
+  await act(ctx, description, cmd, args, { env: extraEnv });
+}
+
+export function commandExists(name) {
+  const r = spawnSync("command", ["-v", name], { shell: true, stdio: "ignore" });
+  return r.status === 0;
+}

package/wizard/lib/indexer.mjs

@@ -0,0 +1,6 @@
+/**
+ * The shared indexer's container entry point. The wizard runs it with --list to preview
+ * which sources an index.yml selects. PM_INDEXER_BIN overrides the name if the entry
+ * point is renamed.
+ */
+export const INDEXER_BIN = process.env.PM_INDEXER_BIN || "hindsight-project-index";