@askexenow/exe-os 0.9.166 → 0.9.167

package/dist/bin/stack-update.js

@@ -1,7 +1,18 @@
 #!/usr/bin/env node
 import {
-  loadLicense
-} from "../chunk-MVMMULOJ.js";
+  assertDeploymentScopeAllowed,
+  assertHostReadyForApply,
+  assertProductionDeployGate,
+  bootstrapStackHost,
+  createStackUpdatePlan,
+  defaultStackPaths,
+  listAvailableVersions,
+  loadStackManifest,
+  patchEnv,
+  readCurrentStackVersion,
+  runStackUpdate
+} from "../chunk-WCYT54XP.js";
+import "../chunk-MVMMULOJ.js";
 import "../chunk-4GXRETYL.js";
 import "../chunk-LYH5HE24.js";
 import {
@@ -10,849 +21,9 @@ import {
 import "../chunk-MLKGABMK.js";
 
 // src/bin/stack-update.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { spawnSync as spawnSync2 } from "child_process";
-import path2 from "path";
-
-// src/lib/stack-update.ts
-import { execFileSync, spawnSync } from "child_process";
-import { createVerify, randomBytes, verify as verifySignature } from "crypto";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "fs";
-import http from "http";
-import https from "https";
+import { readFileSync } from "fs";
+import { spawnSync } from "child_process";
 import path from "path";
-import { fileURLToPath } from "url";
-function isSignedEnvelope(value) {
-  return !!value && typeof value === "object" && "manifest" in value && "signature" in value;
-}
-function canonicalizeStackManifest(manifest) {
-  const clone = JSON.parse(JSON.stringify(manifest));
-  delete clone.signature;
-  return stableJson(clone);
-}
-function verifyStackManifestSignature(manifest, publicKeyPem) {
-  const signature = manifest.signature;
-  if (!signature) throw new Error("Stack manifest signature required but missing");
-  const payload = Buffer.from(canonicalizeStackManifest(manifest));
-  const sig = Buffer.from(signature.signature, "base64");
-  let ok = false;
-  if (signature.alg === "ed25519") {
-    ok = verifySignature(null, payload, publicKeyPem, sig);
-  } else if (signature.alg === "rsa-sha256") {
-    const verifier = createVerify("RSA-SHA256");
-    verifier.update(payload);
-    verifier.end();
-    ok = verifier.verify(publicKeyPem, sig);
-  } else {
-    throw new Error(`Unsupported stack manifest signature alg: ${signature.alg}`);
-  }
-  if (!ok) throw new Error("Stack manifest signature verification failed");
-}
-function stableJson(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
-  const obj = value;
-  return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableJson(obj[key])}`).join(",")}}`;
-}
-function findLatestBackupEnvFile(envFile) {
-  const backupDir = path.join(path.dirname(envFile), ".exe-stack-backups");
-  if (!existsSync(backupDir)) return null;
-  const backups = readdirSync(backupDir).filter((name) => name.startsWith("env-") && name.endsWith(".bak")).sort();
-  const latest = backups.at(-1);
-  return latest ? path.join(backupDir, latest) : null;
-}
-async function rollbackStackUpdate(options) {
-  const exec = options.exec ?? defaultExec;
-  const backupEnvFile = options.lockFile && existsSync(options.lockFile) ? JSON.parse(readFileSync(options.lockFile, "utf8")).backupEnvFile : void 0;
-  const rollbackEnv = backupEnvFile && existsSync(backupEnvFile) ? backupEnvFile : findLatestBackupEnvFile(options.envFile);
-  if (!rollbackEnv) throw new Error(`No stack backup env found beside ${options.envFile}`);
-  const preRollbackBackup = options.envFile + `.pre-rollback-${Date.now()}`;
-  try {
-    if (existsSync(options.envFile)) copyFileSync(options.envFile, preRollbackBackup);
-  } catch {
-  }
-  writeFileSync(options.envFile, readFileSync(rollbackEnv), { mode: 384 });
-  const composeArgs = ["compose", "--file", options.composeFile, "--env-file", options.envFile];
-  exec("docker", [...composeArgs, "up", "-d"]);
-  return { status: "rolled_back", targetVersion: "previous", changes: [], backupEnvFile: rollbackEnv, lockFile: options.lockFile ?? path.join(path.dirname(options.envFile), ".exe-stack-lock.json") };
-}
-function parseStackManifest(raw, publicKey) {
-  const parsedRaw = JSON.parse(raw);
-  const parsed = isSignedEnvelope(parsedRaw) ? { ...parsedRaw.manifest, signature: parsedRaw.signature } : parsedRaw;
-  if (publicKey) verifyStackManifestSignature(parsed, publicKey);
-  if (parsed.schemaVersion !== 1) throw new Error("Unsupported stack manifest schemaVersion");
-  if (!parsed.latest || !parsed.stacks || typeof parsed.stacks !== "object") {
-    throw new Error("Invalid stack manifest: latest and stacks are required");
-  }
-  for (const [version, release] of Object.entries(parsed.stacks)) {
-    if (!release.version) release.version = version;
-    if (!release.services || typeof release.services !== "object") {
-      throw new Error(`Invalid stack manifest: release ${version} has no services`);
-    }
-    for (const [serviceName, service] of Object.entries(release.services)) {
-      if (!service.image || !service.env) {
-        throw new Error(`Invalid stack manifest: ${version}.${serviceName} requires image and env`);
-      }
-    }
-  }
-  return parsed;
-}
-async function loadStackManifest(ref, fetchText = defaultFetchText, publicKey, authToken) {
-  if (/^https?:\/\//.test(ref)) return parseStackManifest(await fetchTextWithAuth(ref, fetchText, authToken), publicKey);
-  return parseStackManifest(readFileSync(ref, "utf8"), publicKey);
-}
-async function fetchTextWithAuth(ref, fetchText, authToken) {
-  if (!authToken || fetchText !== defaultFetchText) return fetchText(ref);
-  return defaultFetchText(ref, authToken);
-}
-function parseEnv(raw) {
-  const env = /* @__PURE__ */ new Map();
-  for (const line of raw.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const idx = line.indexOf("=");
-    if (idx <= 0) continue;
-    env.set(line.slice(0, idx).trim(), line.slice(idx + 1));
-  }
-  return env;
-}
-function patchEnv(raw, updates) {
-  const seen = /* @__PURE__ */ new Set();
-  const lines = raw.replace(/\n$/, "").split(/\r?\n/);
-  const patched = lines.map((line) => {
-    const idx = line.indexOf("=");
-    if (idx <= 0 || line.trim().startsWith("#")) return line;
-    const key = line.slice(0, idx).trim();
-    if (!(key in updates)) return line;
-    seen.add(key);
-    return `${key}=${updates[key]}`;
-  });
-  for (const [key, value] of Object.entries(updates)) {
-    if (!seen.has(key)) patched.push(`${key}=${value}`);
-  }
-  return patched.join("\n").replace(/\n*$/, "\n");
-}
-function createStackUpdatePlan(manifest, envRaw, targetVersion) {
-  const version = targetVersion ?? manifest.latest;
-  const release = manifest.stacks[version];
-  if (!release) throw new Error(`Stack version ${version} not found in manifest`);
-  const env = parseEnv(envRaw);
-  const changes = [];
-  for (const [serviceName, service] of Object.entries(release.services)) {
-    const before = env.get(service.env);
-    if (before !== service.image) {
-      changes.push({ key: service.env, before, after: service.image, service: serviceName });
-    }
-  }
-  return {
-    manifest,
-    release,
-    targetVersion: version,
-    changes,
-    breakingChanges: release.breakingChanges ?? []
-  };
-}
-var ASKEXE_GHCR_IMAGE = /^(?:ghcr\.io\/askexe|registry\.askexe\.com\/askexe)\/[a-z0-9._/-]+(?::[^:@$/{]+|@sha256:[a-f0-9]{64})$/i;
-function validatePinnedGhcrImage(image, label) {
-  const trimmed = image.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) return `${label} is empty`;
-  if (trimmed.includes("${")) return null;
-  if (!trimmed.startsWith("ghcr.io/askexe/") && !trimmed.startsWith("registry.askexe.com/askexe/")) return `${label} must use ghcr.io/askexe/* or registry.askexe.com/askexe/*, got ${trimmed}`;
-  if (/:latest(?:$|[\s#])/.test(trimmed)) return `${label} must not use :latest (${trimmed})`;
-  if (!ASKEXE_GHCR_IMAGE.test(trimmed)) return `${label} must be pinned with an explicit tag or sha256 digest from ghcr.io/askexe or registry.askexe.com/askexe, got ${trimmed}`;
-  return null;
-}
-function validateComposeImageLiteral(image, label) {
-  const trimmed = image.trim().replace(/^['"]|['"]$/g, "");
-  if (!trimmed) return `${label} is empty`;
-  if (trimmed.startsWith("ghcr.io/askexe/") || trimmed.startsWith("registry.askexe.com/askexe/")) return validatePinnedGhcrImage(trimmed, label);
-  if (/^(postgres|pgvector\/pgvector|clickhouse\/clickhouse-server|redis|nginx|postgrest\/postgrest|supabase\/gotrue):[^:]+$/i.test(trimmed)) return null;
-  return `${label} uses unsupported non-AskExe image ${trimmed}; customer app images must come from pinned ghcr.io/askexe images`;
-}
-function collectProductionDeployGateIssues(plan, envRaw, composeRaw) {
-  const issues = [];
-  const env = parseEnv(envRaw);
-  for (const [serviceName, service] of Object.entries(plan.release.services)) {
-    const manifestIssue = validatePinnedGhcrImage(service.image, `manifest ${plan.targetVersion}.${serviceName}.image`);
-    if (manifestIssue) issues.push({ kind: "manifest-image", message: manifestIssue });
-    const envImage = env.get(service.env);
-    if (envImage) {
-      const envIssue = validatePinnedGhcrImage(envImage, `env ${service.env}`);
-      if (envIssue) issues.push({ kind: "env-image", message: envIssue });
-    }
-  }
-  const lines = composeRaw.split(/\r?\n/);
-  lines.forEach((line, index) => {
-    if (/^\s*build\s*:/.test(line)) {
-      issues.push({ kind: "compose-build", message: `compose line ${index + 1} contains build:, production deploys must pull images` });
-    }
-    const imageMatch = line.match(/^\s*image\s*:\s*(.+?)\s*(?:#.*)?$/);
-    if (imageMatch) {
-      const image = imageMatch[1].trim();
-      if (image.includes("${")) {
-        const fallback = image.match(/:-([^}]+)}/)?.[1];
-        if (fallback) {
-          const composeIssue = validateComposeImageLiteral(fallback, `compose image fallback on line ${index + 1}`);
-          if (composeIssue) issues.push({ kind: "compose-image", message: composeIssue });
-        }
-      } else {
-        const composeIssue = validateComposeImageLiteral(image, `compose image on line ${index + 1}`);
-        if (composeIssue) issues.push({ kind: "compose-image", message: composeIssue });
-      }
-    }
-  });
-  return issues;
-}
-function assertDeploymentScopeAllowed(plan, persona = "customer") {
-  if (persona === "askexe-control-plane") return;
-  const blocked = Object.entries(plan.release.services).filter(([, service]) => service.deploymentScope === "askexe-control-plane").map(([name]) => name);
-  if (blocked.length > 0) {
-    throw new Error(
-      `Customer deployment manifest includes AskExe control-plane service(s): ${blocked.join(", ")}. Customer VPSs may deploy customer services and optional agents only.`
-    );
-  }
-}
-function assertProductionDeployGate(plan, envRaw, composeRaw, options = {}) {
-  const issues = collectProductionDeployGateIssues(plan, envRaw, composeRaw);
-  if (issues.length === 0) return;
-  if (options.breakGlassReason?.trim()) {
-    writeBreakGlassAudit(plan, issues, options);
-    return;
-  }
-  const details = issues.map((issue) => `- [${issue.kind}] ${issue.message}`).join("\n");
-  throw new Error(
-    `Production deploy gate failed. Exe OS deploys must use pinned ghcr.io/askexe or registry.askexe.com/askexe images and must not build from source on the VPS.
-${details}
-Emergency override requires --break-glass <reason> and writes an audit file.`
-  );
-}
-function writeBreakGlassAudit(plan, issues, options) {
-  const now = options.now ?? (() => /* @__PURE__ */ new Date());
-  const stamp = now().toISOString().replace(/[:.]/g, "-");
-  const defaultDir = existsSync("exe/output") ? "exe/output" : path.dirname(options.envFile ?? ".");
-  const auditFile = options.breakGlassAuditFile ?? path.join(defaultDir, `stack-update-break-glass-${stamp}.md`);
-  mkdirSync(path.dirname(auditFile), { recursive: true });
-  const body = [
-    `# Stack Update Break-Glass Audit \u2014 ${now().toISOString()}`,
-    "",
-    `Target version: ${plan.targetVersion}`,
-    `Reason: ${options.breakGlassReason?.trim()}`,
-    "",
-    "## Gate failures overridden",
-    ...issues.map((issue) => `- [${issue.kind}] ${issue.message}`),
-    "",
-    "## Required follow-up",
-    "Return this deployment to the standard pinned GHCR image path immediately after the emergency is resolved.",
-    ""
-  ].join("\n");
-  writeFileSync(auditFile, body, { mode: 384 });
-  console.warn(`[stack-update] BREAK-GLASS deploy override recorded: ${auditFile}`);
-}
-function assertBreakingChangesAllowed(plan, allowedIds) {
-  const required = plan.breakingChanges.filter((c) => c.requiresConfirmation !== false);
-  const missing = required.filter((c) => !allowedIds.includes(c.id));
-  if (missing.length > 0) {
-    const details = missing.map((c) => `- ${c.id}: ${c.title}
-  ${c.description}
-  Action: ${c.requiredAction ?? "Review release notes."}`).join("\n");
-    throw new Error(
-      `Stack ${plan.targetVersion} has breaking changes that require confirmation:
-${details}
-Re-run with --allow-breaking ${missing.map((c) => c.id).join(",")}`
-    );
-  }
-}
-function commandSucceeds(cmd, args = []) {
-  const res = spawnSync(cmd, args, { stdio: "ignore" });
-  return res.status === 0;
-}
-function shellSucceeds(command) {
-  const res = spawnSync("sh", ["-lc", command], { stdio: "ignore" });
-  return res.status === 0;
-}
-function resolvePackageRoot() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  const candidates = [
-    path.resolve(here, "..", ".."),
-    path.resolve(here, ".."),
-    process.cwd()
-  ];
-  for (const c of candidates) {
-    if (existsSync(path.join(c, "package.json")) && existsSync(path.join(c, "deploy", "compose", "docker-compose.yml"))) return c;
-  }
-  return process.cwd();
-}
-function copyTemplateIfMissing(srcRel, dest, created) {
-  if (existsSync(dest)) return;
-  const src = path.join(resolvePackageRoot(), srcRel);
-  if (!existsSync(src)) throw new Error(`Missing packaged stack template: ${srcRel}. Reinstall/update exe-os and retry.`);
-  try {
-    mkdirSync(path.dirname(dest), { recursive: true });
-  } catch (err) {
-    if (err.code === "EACCES") {
-      const dir = path.dirname(dest);
-      throw new Error(
-        `Permission denied creating ${dir}. Run this first:
-
-  sudo mkdir -p ${dir} && sudo chown $(whoami) ${dir}
-
-Then re-run stack-update.`
-      );
-    }
-    throw err;
-  }
-  copyFileSync(src, dest);
-  created.push(dest);
-}
-function installDockerUbuntu(exec) {
-  if (process.platform !== "linux") throw new Error("Docker auto-install is only supported on Linux. Install Docker manually, then retry.");
-  if (!existsSync("/etc/os-release")) throw new Error("Cannot detect Linux distro; install Docker manually, then retry.");
-  const osRelease = readFileSync("/etc/os-release", "utf8");
-  if (!/ID=(ubuntu|debian)|ID_LIKE=.*debian/.test(osRelease)) {
-    throw new Error("Docker auto-install currently supports Ubuntu/Debian only. Install Docker manually, then retry.");
-  }
-  const script = [
-    "set -e",
-    "sudo apt-get update",
-    "sudo apt-get install -y ca-certificates curl gnupg",
-    "sudo install -m 0755 -d /etc/apt/keyrings",
-    "if [ ! -f /etc/apt/keyrings/docker.gpg ]; then curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg; sudo chmod a+r /etc/apt/keyrings/docker.gpg; fi",
-    ". /etc/os-release",
-    'CODENAME="${VERSION_CODENAME:-bookworm}"',
-    'if [ "${ID:-}" = "debian" ]; then DOCKER_DISTRO=debian; else DOCKER_DISTRO=ubuntu; fi',
-    `printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/%s %s stable\\n' "$(dpkg --print-architecture)" "$DOCKER_DISTRO" "$CODENAME" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null`,
-    "sudo apt-get update",
-    "sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin",
-    "sudo systemctl enable --now docker",
-    "sudo docker version >/dev/null",
-    "sudo docker compose version >/dev/null"
-  ].join("\n");
-  exec("sh", ["-lc", script]);
-}
-function randomSecret(bytes = 32) {
-  return randomBytes(bytes).toString("base64url");
-}
-function randomHexSecret(bytes = 24) {
-  return randomBytes(bytes).toString("hex");
-}
-function hydrateEnv(raw, opts) {
-  let next = raw;
-  const license = opts.licenseKey || process.env.EXE_LICENSE_KEY || loadLicense() || "";
-  const domain = opts.domain || process.env.EXE_STACK_DOMAIN || process.env.CUSTOMER_DOMAIN || "";
-  const replacements = {};
-  const env = parseEnv(raw);
-  for (const [key, value] of env.entries()) {
-    if (!/CHANGEME/.test(value)) continue;
-    if (key === "EXE_LICENSE_KEY" && license) replacements[key] = license;
-    else if (key === "MONITOR_AGENT_TOKEN" || key === "MONITOR_AGENT_KEY") continue;
-    else if (key === "EXE_GATEWAY_WS_RELAY_AUTH_TOKEN") replacements[key] = randomHexSecret(24);
-    else if (key.endsWith("_PASSWORD")) replacements[key] = randomSecret(24);
-    else if (key.endsWith("_TOKEN")) replacements[key] = randomHexSecret(32);
-    else if (key.endsWith("_SECRET") || key.endsWith("_SALT")) replacements[key] = randomSecret(32);
-    else if (key.endsWith("_KEY") && key !== "EXE_LICENSE_KEY") continue;
-  }
-  if (domain) next = next.replaceAll("CHANGEME_DOMAIN", domain);
-  next = patchEnv(next, replacements);
-  const remaining = [...parseEnv(next).entries()].filter(([, value]) => /CHANGEME/.test(value)).map(([key, value]) => `${key}=${value}`);
-  return { raw: next, hadPlaceholders: /CHANGEME/.test(raw), remaining: [...new Set(remaining)] };
-}
-async function pairMonitorAgent(hubUrl, licenseKey, domain, envFile) {
-  if (!hubUrl || !licenseKey || !domain) {
-    return { paired: false, error: "Missing hubUrl, licenseKey, or domain for monitor pairing" };
-  }
-  const registrationUrl = `${hubUrl.replace(/\/+$/, "")}/api/register-agent`;
-  try {
-    const res = await fetch(registrationUrl, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        authorization: `Bearer ${licenseKey}`
-      },
-      body: JSON.stringify({ name: domain, host: domain, port: 45876 }),
-      signal: AbortSignal.timeout(15e3)
-    });
-    if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      return { paired: false, error: `Monitor hub returned HTTP ${res.status}: ${body}` };
-    }
-    const data = await res.json();
-    if (!data.token || !data.key) {
-      return { paired: false, error: "Monitor hub response missing token or key" };
-    }
-    if (existsSync(envFile)) {
-      const envRaw = readFileSync(envFile, "utf8");
-      const patched = patchEnv(envRaw, {
-        MONITOR_AGENT_TOKEN: data.token,
-        MONITOR_AGENT_KEY: data.key
-      });
-      if (patched !== envRaw) {
-        writeFileSync(envFile, patched, { mode: 384 });
-      }
-    }
-    return { paired: true, systemName: data.name ?? domain };
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    return { paired: false, error: `Monitor hub unreachable: ${reason}` };
-  }
-}
-function bootstrapStackHost(options) {
-  const exec = options.exec ?? defaultExec;
-  const createdFiles = [];
-  const actions = [];
-  let dockerInstalled = commandSucceeds("docker", ["version"]);
-  let dockerComposeInstalled = shellSucceeds("docker compose version");
-  if ((!dockerInstalled || !dockerComposeInstalled) && options.installDocker) {
-    actions.push("install_docker");
-    installDockerUbuntu(exec);
-    dockerInstalled = commandSucceeds("docker", ["version"]);
-    dockerComposeInstalled = shellSucceeds("docker compose version");
-  }
-  copyTemplateIfMissing("deploy/compose/docker-compose.yml", options.composeFile, createdFiles);
-  copyTemplateIfMissing("deploy/compose/.env.customer.example", options.envFile, createdFiles);
-  const brandingDest = path.join(path.dirname(options.envFile), "branding.json");
-  copyTemplateIfMissing("deploy/compose/gateway.json", path.join(path.dirname(options.envFile), "gateway.json"), createdFiles);
-  if (!existsSync(brandingDest)) writeFileSync(brandingDest, JSON.stringify({ brandName: "Hygo", productName: "Hygo OS" }, null, 2) + "\n", { mode: 384 });
-  let envHadPlaceholders = false;
-  let envRemainingPlaceholders = [];
-  if (existsSync(options.envFile)) {
-    const envRaw = readFileSync(options.envFile, "utf8");
-    const hydrated = hydrateEnv(envRaw, options);
-    envHadPlaceholders = hydrated.hadPlaceholders;
-    envRemainingPlaceholders = hydrated.remaining;
-    if (hydrated.raw !== envRaw) {
-      const backupPath = options.envFile + `.bak-${Date.now()}`;
-      try {
-        copyFileSync(options.envFile, backupPath);
-      } catch {
-      }
-      writeFileSync(options.envFile, hydrated.raw, { mode: 384 });
-      actions.push("hydrate_env_secrets");
-    }
-  }
-  return {
-    dockerInstalled,
-    dockerComposeInstalled,
-    composeFileExists: existsSync(options.composeFile),
-    envFileExists: existsSync(options.envFile),
-    envHadPlaceholders,
-    envRemainingPlaceholders,
-    licensePresent: !!(options.licenseKey || process.env.EXE_LICENSE_KEY || loadLicense()),
-    createdFiles,
-    actions
-  };
-}
-function assertHostReadyForApply(report) {
-  const blockers = [];
-  if (!report.dockerInstalled) blockers.push("Docker is not installed/running. Re-run with --yes to auto-install on Ubuntu/Debian, or install Docker manually.");
-  if (!report.dockerComposeInstalled) blockers.push("Docker Compose plugin is missing. Re-run with --yes to auto-install on Ubuntu/Debian, or install docker-compose-plugin manually.");
-  if (!report.composeFileExists) blockers.push("docker-compose.yml is missing and could not be created.");
-  if (!report.envFileExists) blockers.push(".env is missing and could not be created.");
-  if (!report.licensePresent) blockers.push("Exe OS license key is missing. Run `exe-os setup`, `exe-os --activate <key>`, or pass --license-key.");
-  const hardPlaceholders = report.envRemainingPlaceholders.filter((p) => !/WHATSAPP|API_ROUTER|MONITOR_AGENT/.test(p));
-  if (hardPlaceholders.length > 0) blockers.push(`Required .env placeholders remain: ${hardPlaceholders.join(", ")}`);
-  if (blockers.length > 0) throw new Error(`Stack host is not ready:
-- ${blockers.join("\n- ")}`);
-}
-function areStackContainersRunning(composeFile, envFile) {
-  try {
-    const result = spawnSync("docker", ["compose", "--file", composeFile, "--env-file", envFile, "ps", "-q"], {
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15e3
-    });
-    return result.status === 0 && (result.stdout?.toString().trim().length ?? 0) > 0;
-  } catch {
-    return false;
-  }
-}
-var CRITICAL_BIND_MOUNTS = [
-  { file: ".env", description: "secrets and image tags" },
-  { file: "gateway.json", description: "gateway connector config" }
-];
-var CRITICAL_VOLUMES = [
-  "postgres_data",
-  "gateway_data",
-  "wiki_data",
-  "exe_os_data"
-];
-function assertBindMountsExist(stackDir) {
-  const missing = [];
-  for (const mount of CRITICAL_BIND_MOUNTS) {
-    const fullPath = path.join(stackDir, mount.file);
-    if (!existsSync(fullPath)) {
-      missing.push(`${mount.file} (${mount.description})`);
-    }
-  }
-  if (missing.length > 0) {
-    console.warn(`[stack-update] \u26A0 Missing critical bind mounts:
-  - ${missing.join("\n  - ")}`);
-    console.warn("[stack-update] These files contain customer config that will be lost if not present.");
-  }
-}
-function assertVolumesIntact() {
-  const missing = [];
-  for (const vol of CRITICAL_VOLUMES) {
-    const result = spawnSync("docker", ["volume", "inspect", `exe-os_${vol}`], {
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 5e3
-    });
-    if (result.status !== 0) {
-      missing.push(vol);
-    }
-  }
-  if (missing.length > 0) {
-    console.warn(`[stack-update] \u26A0 Critical volumes missing after update: ${missing.join(", ")}`);
-    console.warn("[stack-update] Data may have been lost. Check if 'docker compose down -v' was used.");
-  }
-}
-async function runStackUpdate(options) {
-  const exec = options.exec ?? defaultExec;
-  const now = options.now ?? (() => /* @__PURE__ */ new Date());
-  if (options.rollback) return rollbackStackUpdate(options);
-  if (options.bootstrap !== false) {
-    const report = bootstrapStackHost({ ...options, installDocker: options.installDocker ?? !!options.yes });
-    if (!options.dryRun) assertHostReadyForApply(report);
-  }
-  assertBindMountsExist(path.dirname(options.envFile));
-  if (!options.dryRun) {
-    try {
-      const { runPreflight } = await import("../preflight-3KY5JETE.js");
-      const preflightReport = runPreflight({
-        composeFile: options.composeFile,
-        envFile: options.envFile
-      });
-      if (!preflightReport.passed) {
-        const failures = preflightReport.results.filter((r) => r.status === "fail").map((r) => `${r.check}: ${r.message}`);
-        throw new Error(`Preflight blocked deploy:
-- ${failures.join("\n- ")}`);
-      }
-      console.log("[stack-update] \u2713 Preflight passed");
-    } catch (preflightErr) {
-      if (preflightErr instanceof Error && preflightErr.message.startsWith("Preflight blocked")) {
-        throw preflightErr;
-      }
-      console.warn("[stack-update] Preflight check skipped (module not available)");
-    }
-  }
-  const hubUrl = options.monitorHubUrl || parseEnv(readFileSync(options.envFile, "utf8")).get("MONITOR_HUB_URL") || "";
-  const pairLicense = options.licenseKey || process.env.EXE_LICENSE_KEY || loadLicense() || "";
-  const pairDomain = options.domain || process.env.EXE_STACK_DOMAIN || process.env.CUSTOMER_DOMAIN || "";
-  if (hubUrl && pairLicense && pairDomain) {
-    const envBefore = readFileSync(options.envFile, "utf8");
-    const hasPlaceholder = /CHANGEME/.test(parseEnv(envBefore).get("MONITOR_AGENT_TOKEN") ?? "");
-    if (hasPlaceholder) {
-      const pair = options.pairMonitor ? options.pairMonitor(hubUrl, pairLicense, pairDomain, options.envFile) : pairMonitorAgent(hubUrl, pairLicense, pairDomain, options.envFile);
-      const result = await pair;
-      if (result.paired) {
-        console.log(`[stack-update] Monitor agent paired: ${result.systemName}`);
-      } else {
-        console.warn(`[stack-update] Monitor pairing skipped: ${result.error}`);
-      }
-    }
-  }
-  const manifest = await loadStackManifest(options.manifestRef, options.fetchText, options.manifestPublicKey, options.manifestAuthToken);
-  const envRaw = readFileSync(options.envFile, "utf8");
-  const plan = createStackUpdatePlan(manifest, envRaw, options.targetVersion);
-  assertBreakingChangesAllowed(plan, options.allowedBreakingChangeIds ?? []);
-  assertDeploymentScopeAllowed(plan, options.deploymentPersona ?? "customer");
-  const plannedEnvRaw = patchEnv(envRaw, Object.fromEntries(plan.changes.map((c) => [c.key, c.after])));
-  const composeRaw = readFileSync(options.composeFile, "utf8");
-  assertProductionDeployGate(plan, plannedEnvRaw, composeRaw, {
-    breakGlassReason: options.breakGlassReason,
-    breakGlassAuditFile: options.breakGlassAuditFile,
-    now,
-    envFile: options.envFile
-  });
-  const lockFile = options.lockFile ?? path.join(path.dirname(options.envFile), ".exe-stack-lock.json");
-  const previousVersion = readCurrentStackVersion(lockFile);
-  const containersRunning = plan.changes.length === 0 ? areStackContainersRunning(options.composeFile, options.envFile) : true;
-  if (options.dryRun || plan.changes.length === 0 && containersRunning) {
-    return { status: "planned", targetVersion: plan.targetVersion, changes: plan.changes, lockFile };
-  }
-  await postDeployAudit(options, "started", plan.targetVersion, previousVersion);
-  const stackDir = path.dirname(options.envFile);
-  const backupDir = path.join(stackDir, ".exe-stack-backups");
-  mkdirSync(backupDir, { recursive: true });
-  const stamp = now().toISOString().replace(/[:.]/g, "-");
-  const updateBackupDir = path.join(backupDir, `pre-update-${stamp}`);
-  mkdirSync(updateBackupDir, { recursive: true });
-  const backupEnvFile = path.join(updateBackupDir, "env.bak");
-  writeFileSync(backupEnvFile, envRaw, { mode: 384 });
-  const protectedFiles = ["gateway.json", "branding.json"];
-  for (const f of protectedFiles) {
-    const src = path.join(stackDir, f);
-    try {
-      if (existsSync(src)) {
-        copyFileSync(src, path.join(updateBackupDir, f));
-      }
-    } catch {
-    }
-  }
-  const cfDir = path.join(stackDir, "cloudflared");
-  try {
-    if (existsSync(cfDir)) {
-      const cfBackup = path.join(updateBackupDir, "cloudflared");
-      mkdirSync(cfBackup, { recursive: true });
-      for (const f of readdirSync(cfDir)) {
-        copyFileSync(path.join(cfDir, f), path.join(cfBackup, f));
-      }
-    }
-  } catch {
-  }
-  console.log(`[stack-update] Config backed up to ${updateBackupDir}`);
-  const updates = Object.fromEntries(plan.changes.map((c) => [c.key, c.after]));
-  const patched = patchEnv(envRaw, updates);
-  const tmp = `${options.envFile}.tmp-${process.pid}`;
-  writeFileSync(tmp, patched, { mode: 384 });
-  renameSync(tmp, options.envFile);
-  const composeArgs = ["compose", "--file", options.composeFile, "--env-file", options.envFile];
-  let registryForLogout;
-  try {
-    const creds = await fetchImageCredentials(options);
-    if (creds) {
-      (options.dockerLogin ?? defaultDockerLogin)(creds);
-      registryForLogout = creds.registry;
-    }
-    exec("docker", [...composeArgs, "pull"]);
-    for (const [serviceName, service] of Object.entries(plan.release.services)) {
-      if (!service.migrations?.command) continue;
-      const composeServiceName = service.composeService ?? serviceName;
-      console.log(`[stack-update] Running migrations for ${composeServiceName}: ${service.migrations.command}`);
-      try {
-        const migrationArgs = service.migrations.command.split(/\s+/);
-        exec("docker", [
-          ...composeArgs,
-          "run",
-          "--rm",
-          "--no-deps",
-          composeServiceName,
-          ...migrationArgs
-        ]);
-        console.log(`[stack-update] \u2713 Migrations for ${composeServiceName} completed`);
-      } catch (migErr) {
-        const reason = migErr instanceof Error ? migErr.message : String(migErr);
-        console.error(`[stack-update] \u2717 Migration failed for ${composeServiceName}: ${reason}`);
-        throw new Error(`Migration failed for ${composeServiceName} \u2014 aborting update. Fix the migration and retry. Error: ${reason}`);
-      }
-    }
-    const RESTART_ORDER = [
-      "exe-db",
-      // data layer — must be healthy before apps
-      "clickhouse",
-      "redis",
-      "exed",
-      // daemon — has its own health endpoint
-      "exe-crm",
-      // CRM app
-      "exe-crm-worker",
-      // CRM background worker
-      "exe-gateway",
-      // gateway — WhatsApp connections
-      "exe-wiki"
-      // wiki
-    ];
-    const preSnapshot = spawnSync("docker", ["ps", "--format", "json"], { encoding: "utf8", timeout: 1e4 });
-    const preContainerCount = preSnapshot.stdout?.split("\n").filter(Boolean).length ?? 0;
-    console.log(`[stack-update] Pre-update snapshot: ${preContainerCount} containers`);
-    for (const service of RESTART_ORDER) {
-      const psResult = spawnSync("docker", [...composeArgs, "ps", "--quiet", service], {
-        encoding: "utf8",
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 1e4
-      });
-      if (psResult.status !== 0) continue;
-      exec("docker", [...composeArgs, "up", "-d", "--no-deps", service]);
-      const maxWait = 60;
-      let healthy = false;
-      for (let i = 0; i < maxWait; i++) {
-        const inspectResult = spawnSync(
-          "docker",
-          ["inspect", "--format", "{{.State.Health.Status}}", service],
-          { encoding: "utf8", timeout: 5e3 }
-        );
-        const status = inspectResult.stdout?.trim();
-        if (status === "healthy") {
-          healthy = true;
-          break;
-        }
-        if (status === "" || inspectResult.status !== 0) {
-          healthy = true;
-          break;
-        }
-        await new Promise((r) => setTimeout(r, 1e3));
-      }
-      if (!healthy) {
-        throw new Error(`Service ${service} failed health check after ${maxWait}s \u2014 aborting update`);
-      }
-      console.log(`[stack-update] \u2713 ${service} restarted and healthy`);
-    }
-    const postSnapshot = spawnSync("docker", ["ps", "--format", "json"], { encoding: "utf8", timeout: 1e4 });
-    const postContainerCount = postSnapshot.stdout?.split("\n").filter(Boolean).length ?? 0;
-    console.log(`[stack-update] Post-update snapshot: ${postContainerCount} containers (was ${preContainerCount})`);
-    if (postContainerCount < preContainerCount) {
-      console.warn(`[stack-update] \u26A0 Container count dropped from ${preContainerCount} to ${postContainerCount}`);
-    }
-    await verifyReleaseHealth(plan.release, options.healthRetries ?? 12, options.healthDelayMs ?? 5e3);
-    assertVolumesIntact();
-    try {
-      const { runVerifyStack } = await import("./verify-stack.js");
-      const verifyReport = await runVerifyStack({ composeFile: options.composeFile, envFile: options.envFile });
-      for (const r of verifyReport.results) {
-        if (r.status === "fail") console.warn(`[verify-stack] FAIL: ${r.check}: ${r.message}`);
-      }
-    } catch {
-    }
-    writeFileSync(lockFile, JSON.stringify({ stackVersion: plan.targetVersion, updatedAt: now().toISOString(), backupEnvFile, services: plan.release.services }, null, 2) + "\n");
-    await postDeployAudit(options, "success", plan.targetVersion, previousVersion, void 0, { changes: plan.changes.length });
-    return { status: "updated", targetVersion: plan.targetVersion, changes: plan.changes, backupEnvFile, lockFile };
-  } catch (err) {
-    writeFileSync(options.envFile, envRaw, { mode: 384 });
-    try {
-      exec("docker", [...composeArgs, "up", "-d"]);
-    } catch {
-    }
-    const reason = err instanceof Error ? err.message : String(err);
-    await postDeployAudit(options, "failed", plan.targetVersion, previousVersion, reason, { rollbackAttempted: true });
-    throw new Error(`Stack update failed and rollback was attempted: ${reason}`);
-  } finally {
-    if (registryForLogout) {
-      try {
-        (options.dockerLogout ?? defaultDockerLogout)(registryForLogout);
-      } catch {
-      }
-    }
-  }
-}
-async function fetchImageCredentials(options) {
-  if (!options.imageCredentialsUrl) return null;
-  const res = await fetch(options.imageCredentialsUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      ...options.manifestAuthToken ? { authorization: `Bearer ${options.manifestAuthToken}` } : {}
-    },
-    body: JSON.stringify({ deviceId: options.deviceId, licenseKey: options.licenseKey })
-  });
-  if (!res.ok) throw new Error(`Failed to fetch image credentials: HTTP ${res.status}`);
-  return await res.json();
-}
-function readCurrentStackVersion(lockFile) {
-  if (!existsSync(lockFile)) return void 0;
-  try {
-    const parsed = JSON.parse(readFileSync(lockFile, "utf8"));
-    return parsed.stackVersion;
-  } catch {
-    return void 0;
-  }
-}
-async function postDeployAudit(options, status, stackVersion, previousVersion, error, metadata) {
-  if (!options.auditUrl) return;
-  const postJson = options.postJson ?? defaultPostJson;
-  try {
-    await postJson(options.auditUrl, {
-      stackVersion,
-      previousVersion,
-      status,
-      error,
-      metadata,
-      deviceId: options.deviceId,
-      licenseKey: options.licenseKey
-    }, options.manifestAuthToken);
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(`[stack-update] deploy audit failed: ${reason}`);
-  }
-}
-async function verifyReleaseHealth(release, retries, delayMs) {
-  for (const [serviceName, service] of Object.entries(release.services)) {
-    if (!service.healthUrl) continue;
-    await waitForHttpOk(service.healthUrl, retries, delayMs, serviceName);
-  }
-}
-async function waitForHttpOk(url, retries, delayMs, label) {
-  let last = "";
-  for (let i = 0; i < retries; i++) {
-    try {
-      const status = await httpStatus(url);
-      if (status >= 200 && status < 300) return;
-      last = `HTTP ${status}`;
-    } catch (err) {
-      last = err instanceof Error ? err.message : String(err);
-    }
-    if (i < retries - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
-  }
-  throw new Error(`Health check failed for ${label} (${url}): ${last}`);
-}
-function httpStatus(urlString) {
-  return new Promise((resolve, reject) => {
-    const url = new URL(urlString);
-    const mod = url.protocol === "https:" ? https : http;
-    const req = mod.request(url, { method: "GET", timeout: 5e3 }, (res) => {
-      res.resume();
-      resolve(res.statusCode ?? 0);
-    });
-    req.on("timeout", () => req.destroy(new Error("timeout")));
-    req.on("error", reject);
-    req.end();
-  });
-}
-function defaultExec(cmd, args, opts) {
-  execFileSync(cmd, args, { stdio: "inherit", cwd: opts?.cwd });
-}
-function defaultDockerLogin(creds) {
-  execFileSync("docker", ["login", creds.registry, "-u", creds.username, "--password-stdin"], {
-    input: creds.password,
-    stdio: ["pipe", "inherit", "inherit"]
-  });
-}
-function defaultDockerLogout(registry) {
-  execFileSync("docker", ["logout", registry], { stdio: "ignore" });
-}
-async function defaultFetchText(ref, authToken) {
-  const res = await fetch(ref, {
-    headers: authToken ? { authorization: `Bearer ${authToken}` } : void 0
-  });
-  if (!res.ok) throw new Error(`Failed to fetch ${ref}: HTTP ${res.status}`);
-  return res.text();
-}
-async function defaultPostJson(url, body, authToken) {
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      ...authToken ? { authorization: `Bearer ${authToken}` } : {}
-    },
-    body: JSON.stringify(body)
-  });
-  if (!res.ok) throw new Error(`Failed to POST ${url}: HTTP ${res.status}`);
-}
-function defaultStackPaths() {
-  const cwdCompose = path.resolve("docker-compose.yml");
-  const cwdEnv = path.resolve(".env");
-  const packagedManifest = path.join(resolvePackageRoot(), "deploy", "stack-manifests", "v0.9.json");
-  const manifestRef = process.env.EXE_STACK_MANIFEST || (existsSync(packagedManifest) ? packagedManifest : "https://api.askexe.com/stack-manifest.json");
-  return {
-    composeFile: process.env.EXE_STACK_COMPOSE_FILE || (existsSync(cwdCompose) ? cwdCompose : "/opt/exe-stack/docker-compose.yml"),
-    envFile: process.env.EXE_STACK_ENV_FILE || (existsSync(cwdEnv) ? cwdEnv : "/opt/exe-stack/.env"),
-    manifestRef,
-    // Only call api.askexe.com if explicitly configured or if a remote manifest was requested.
-    // Packaged manifests keep cold-start installs unblocked even before update-service entitlements are provisioned.
-    auditUrl: process.env.EXE_STACK_AUDIT_URL || (/^https?:\/\//.test(manifestRef) ? "https://api.askexe.com/v1/deploy-audits" : void 0),
-    imageCredentialsUrl: process.env.EXE_STACK_IMAGE_CREDENTIALS_URL || (/^https?:\/\//.test(manifestRef) ? "https://api.askexe.com/v1/image-credentials" : void 0),
-    // License key IS the auth token for api.askexe.com — no separate update token needed.
-    // EXE_STACK_UPDATE_TOKEN kept as legacy fallback during migration.
-    manifestAuthToken: process.env.EXE_LICENSE_KEY || loadLicense() || process.env.EXE_STACK_UPDATE_TOKEN || void 0,
-    manifestPublicKey: loadDefaultPublicKey()
-  };
-}
-function loadDefaultPublicKey() {
-  if (process.env.EXE_STACK_PUBLIC_KEY) return process.env.EXE_STACK_PUBLIC_KEY;
-  if (process.env.EXE_STACK_PUBLIC_KEY_FILE && existsSync(process.env.EXE_STACK_PUBLIC_KEY_FILE)) {
-    return readFileSync(process.env.EXE_STACK_PUBLIC_KEY_FILE, "utf8");
-  }
-  return void 0;
-}
-
-// src/bin/stack-update.ts
 function parseArgs(args) {
   const defaults = defaultStackPaths();
   const opts = {
@@ -885,8 +56,8 @@ function parseArgs(args) {
     else if (arg === "--env-file" || arg === "--stack-env-file") opts.envFile = next();
     else if (arg.startsWith("--env-file=") || arg.startsWith("--stack-env-file=")) opts.envFile = arg.split("=").slice(1).join("=");
     else if (arg === "--lock-file") opts.lockFile = next();
-    else if (arg === "--public-key") opts.manifestPublicKey = readFileSync2(next(), "utf8");
-    else if (arg.startsWith("--public-key=")) opts.manifestPublicKey = readFileSync2(arg.split("=").slice(1).join("="), "utf8");
+    else if (arg === "--public-key") opts.manifestPublicKey = readFileSync(next(), "utf8");
+    else if (arg.startsWith("--public-key=")) opts.manifestPublicKey = readFileSync(arg.split("=").slice(1).join("="), "utf8");
     else if (arg === "--auth-token") opts.manifestAuthToken = next();
     else if (arg.startsWith("--auth-token=")) opts.manifestAuthToken = arg.split("=").slice(1).join("=");
     else if (arg === "--auth-token-env") opts.manifestAuthToken = process.env[next()] ?? "";
@@ -933,11 +104,12 @@ function printHelp() {
   console.log(`exe-os stack-update \u2014 update a self-hosted Exe OS stack from a pinned manifest
 
 Usage:
-  exe-os stack-update [--manifest <path-or-url>] [--target <version>] [--yes]
+  exe-os stack-update --check                     Show installed vs available versions
+  exe-os stack-update --target <version> --yes     Update to a specific version
 
 Options:
   --manifest <ref>           Stack manifest JSON path or URL (default: update.askexe.com)
-  --target <version>         Stack version to install (default: manifest.latest)
+  --target <version>         Stack version to install (required for updates; fresh installs default to latest)
   --compose-file <path>      docker-compose.yml path (default: ./docker-compose.yml or /opt/exe-stack/docker-compose.yml)
   --stack-env-file <path>    .env path (default: ./.env or /opt/exe-stack/.env)
   --env-file <path>          Alias; prefer --stack-env-file because Node 22 reserves --env-file
@@ -999,7 +171,7 @@ function printChanges(changes, composeFile, envFile) {
 }
 function areCliContainersRunning(composeFile, envFile) {
   try {
-    const result = spawnSync2("docker", ["compose", "--file", composeFile, "--env-file", envFile, "ps", "-q"], {
+    const result = spawnSync("docker", ["compose", "--file", composeFile, "--env-file", envFile, "ps", "-q"], {
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 15e3
     });
@@ -1010,7 +182,7 @@ function areCliContainersRunning(composeFile, envFile) {
 }
 function getContainerHealth(composeFile, envFile) {
   try {
-    const result = spawnSync2(
+    const result = spawnSync(
       "docker",
       ["compose", "--file", composeFile, "--env-file", envFile, "ps", "--format", "json"],
       { stdio: ["pipe", "pipe", "pipe"], timeout: 15e3 }
@@ -1077,9 +249,9 @@ async function main(args = process.argv.slice(2)) {
   const opts = parseArgs(args);
   let usingPackagedCheckTemplates = false;
   if (opts.check && !opts.noBootstrap && !existsForCli(opts.composeFile) && !existsForCli(opts.envFile)) {
-    const packageRoot = path2.resolve(new URL("../..", import.meta.url).pathname);
-    opts.composeFile = path2.join(packageRoot, "deploy", "compose", "docker-compose.yml");
-    opts.envFile = path2.join(packageRoot, "deploy", "compose", ".env.customer.example");
+    const packageRoot = path.resolve(new URL("../..", import.meta.url).pathname);
+    opts.composeFile = path.join(packageRoot, "deploy", "compose", "docker-compose.yml");
+    opts.envFile = path.join(packageRoot, "deploy", "compose", ".env.customer.example");
     opts.noBootstrap = true;
     usingPackagedCheckTemplates = true;
   }
@@ -1099,20 +271,47 @@ async function main(args = process.argv.slice(2)) {
     if (!opts.check && !opts.dryRun) assertHostReadyForApply(hostReport);
   }
   const manifest = await loadStackManifest(opts.manifestRef, void 0, opts.manifestPublicKey, opts.manifestAuthToken);
-  const envRaw = readFileSync2(opts.envFile, "utf8");
-  const plan = createStackUpdatePlan(manifest, envRaw, opts.targetVersion);
+  const envRaw = readFileSync(opts.envFile, "utf8");
+  const lockFilePath = opts.lockFile ?? path.join(path.dirname(opts.envFile), ".exe-stack-lock.json");
+  const installedVersion = readCurrentStackVersion(lockFilePath);
+  const effectiveTarget = opts.targetVersion ?? (installedVersion ?? manifest.latest);
+  const plan = createStackUpdatePlan(manifest, envRaw, effectiveTarget);
   assertDeploymentScopeAllowed(plan, opts.deploymentPersona);
   const plannedEnvRaw = patchEnv(envRaw, Object.fromEntries(plan.changes.map((c) => [c.key, c.after])));
-  assertProductionDeployGate(plan, plannedEnvRaw, readFileSync2(opts.composeFile, "utf8"), {
+  assertProductionDeployGate(plan, plannedEnvRaw, readFileSync(opts.composeFile, "utf8"), {
     breakGlassReason: opts.breakGlassReason,
     breakGlassAuditFile: opts.breakGlassAuditFile,
     envFile: opts.envFile
   });
   console.log(`Exe OS stack target: ${plan.targetVersion}`);
+  if (installedVersion) {
+    console.log(`Installed version:   ${installedVersion}`);
+  }
+  console.log(`Latest available:    ${manifest.latest}`);
   console.log(`Manifest: ${opts.manifestRef}`);
   console.log(`Compose:  ${opts.composeFile}`);
   console.log(`Env:      ${opts.envFile}
 `);
+  if (opts.check) {
+    const versions = listAvailableVersions(manifest, installedVersion);
+    if (versions.length > 0) {
+      console.log("Available stack versions:");
+      for (const v of versions) {
+        const markers = [];
+        if (v.isCurrent) markers.push("installed");
+        if (v.isLatest) markers.push("latest");
+        const markerStr = markers.length > 0 ? ` \u2190 ${markers.join(", ")}` : "";
+        console.log(`  ${v.version}${markerStr}${v.releasedAt ? `  (${v.releasedAt.slice(0, 10)})` : ""}`);
+      }
+      console.log("");
+      if (installedVersion && installedVersion !== manifest.latest) {
+        console.log(`To update: exe-os stack-update --target ${manifest.latest} --yes`);
+      } else if (installedVersion === manifest.latest) {
+        console.log("Stack is up to date.");
+      }
+      console.log("");
+    }
+  }
   const unhealthyCount = printChanges(plan.changes, opts.composeFile, opts.envFile);
   printBreaking(plan.breakingChanges);
   if (opts.check || opts.dryRun) {
@@ -1121,6 +320,11 @@ async function main(args = process.argv.slice(2)) {
     } else if (unhealthyCount > 0) process.exitCode = 1;
     return;
   }
+  if (!opts.targetVersion && installedVersion && plan.changes.length === 0) {
+    console.log(`Stack is pinned at v${installedVersion}. To update, specify --target <version>.`);
+    console.log(`Available: exe-os stack-update --check`);
+    return;
+  }
   if (!opts.yes) {
     console.error("\nRefusing to update without --yes. Re-run with --yes after reviewing the plan.");
     process.exit(2);
@@ -1133,7 +337,7 @@ async function main(args = process.argv.slice(2)) {
 }
 function existsForCli(filePath) {
   try {
-    readFileSync2(filePath);
+    readFileSync(filePath);
     return true;
   } catch {
     return false;