@askexenow/exe-os 0.9.286 → 0.9.287

package/dist/chunk-ASL5PHCT.js

@@ -0,0 +1,1934 @@
+import {
+  loadLicense
+} from "./chunk-YMKUXZIG.js";
+
+// 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 path from "path";
+import { fileURLToPath } from "url";
+function serviceSelectionPath(envFile) {
+  return path.join(path.dirname(envFile), ".stack-services.json");
+}
+function loadServiceSelection(envFile) {
+  const selPath = serviceSelectionPath(envFile);
+  if (!existsSync(selPath)) return void 0;
+  try {
+    return JSON.parse(readFileSync(selPath, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function saveServiceSelection(envFile, selectedServices) {
+  const selPath = serviceSelectionPath(envFile);
+  mkdirSync(path.dirname(selPath), { recursive: true });
+  const data = {
+    selectedServices,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync(selPath, JSON.stringify(data, null, 2) + "\n", { mode: 384 });
+}
+function filterServicesBySelection(release, selection) {
+  if (!selection) return release;
+  const selected = new Set(selection.selectedServices);
+  const filteredServices = {};
+  for (const [name, service] of Object.entries(release.services)) {
+    if (service.required) {
+      filteredServices[name] = service;
+      continue;
+    }
+    if (selected.has(name) || selected.has(service.composeService ?? name)) {
+      filteredServices[name] = service;
+    }
+  }
+  return { ...release, services: filteredServices };
+}
+function buildDefaultServiceSelection(release) {
+  return Object.keys(release.services);
+}
+var ProgressReporter = class {
+  totalServices;
+  completedServices;
+  currentPhase;
+  phaseStart;
+  overallStart;
+  constructor(serviceNames) {
+    this.totalServices = serviceNames.length;
+    this.completedServices = 0;
+    this.currentPhase = "";
+    this.phaseStart = Date.now();
+    this.overallStart = Date.now();
+  }
+  /** Log the start of a named phase (pull, stop, start, verify, etc.) */
+  startPhase(phase) {
+    this.currentPhase = phase;
+    this.phaseStart = Date.now();
+    console.log(`[stack-update] ${(/* @__PURE__ */ new Date()).toISOString()} \u25B6 Phase: ${phase}`);
+  }
+  /** Log the end of the current phase with elapsed time */
+  endPhase() {
+    const elapsed = ((Date.now() - this.phaseStart) / 1e3).toFixed(1);
+    console.log(`[stack-update] ${(/* @__PURE__ */ new Date()).toISOString()} \u2713 Phase: ${this.currentPhase} completed in ${elapsed}s`);
+  }
+  /** Log service-level progress with N/M counter and percentage */
+  logServiceProgress(serviceName, action) {
+    this.completedServices++;
+    const pct = Math.round(this.completedServices / this.totalServices * 100);
+    console.log(
+      `[stack-update] [${this.completedServices}/${this.totalServices}] (${pct}%) ${action} service: ${serviceName}`
+    );
+  }
+  /** Log a service-level step without incrementing the counter */
+  logServiceStep(index, serviceName, action) {
+    const pct = Math.round(index / this.totalServices * 100);
+    console.log(
+      `[stack-update] [${index}/${this.totalServices}] (${pct}%) ${action}: ${serviceName}`
+    );
+  }
+  /** Log a clean, actionable error when a service fails */
+  logServiceFailure(serviceName, error, composeFile) {
+    const border = "\u2500".repeat(60);
+    console.error(`
+${border}`);
+    console.error(`  SERVICE FAILURE: ${serviceName}`);
+    console.error(`${border}`);
+    console.error(`  Error: ${error}`);
+    console.error("");
+    console.error("  Suggested actions:");
+    console.error(`    1. Check logs:  docker compose logs ${serviceName}`);
+    console.error(`    2. Inspect:     docker inspect ${serviceName}`);
+    if (composeFile) {
+      console.error(`    3. Restart:     docker compose --file ${composeFile} up -d ${serviceName}`);
+    }
+    console.error(`    4. Resume:      exe-os stack-update --resume --yes`);
+    console.error(`${border}
+`);
+  }
+  /** Print the overall elapsed time */
+  logOverallSummary() {
+    const elapsed = ((Date.now() - this.overallStart) / 1e3).toFixed(1);
+    console.log(`[stack-update] Total update time: ${elapsed}s for ${this.totalServices} services`);
+  }
+  /** Reset counter for a new phase (e.g., going from pull to restart) */
+  resetCounter(newTotal) {
+    this.completedServices = 0;
+    if (newTotal !== void 0) this.totalServices = newTotal;
+  }
+};
+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 lockFilePath = options.lockFile ?? path.join(path.dirname(options.envFile), ".exe-stack-lock.json");
+  const lockData = readStackUpdateLock(lockFilePath);
+  const backupEnvFile = lockData?.backupEnvFile;
+  const rollbackEnv = backupEnvFile && existsSync(backupEnvFile) ? backupEnvFile : findLatestBackupEnvFile(options.envFile);
+  if (!rollbackEnv) throw new Error(`No stack backup env found beside ${options.envFile}`);
+  console.error(`[stack-update] ROLLBACK: restoring ${options.envFile} from ${rollbackEnv}`);
+  console.log("[stack-update] Starting rollback\u2026");
+  const preRollbackBackup = options.envFile + `.pre-rollback-${Date.now()}`;
+  try {
+    if (existsSync(options.envFile)) copyFileSync(options.envFile, preRollbackBackup);
+  } catch {
+  }
+  const scopedServiceNames = options.serviceName ? Object.entries(lockData?.services ?? {}).filter(([name, service]) => name === options.serviceName || (service.composeService ?? name) === options.serviceName).map(([name]) => name) : [];
+  const rollbackEnvRaw = readFileSync(rollbackEnv, "utf8");
+  if (scopedServiceNames.length > 0 && lockData?.services) {
+    const rollbackEnvMap = parseEnv(rollbackEnvRaw);
+    const scopedUpdates = Object.fromEntries(scopedServiceNames.map((serviceName) => {
+      const key = lockData.services[serviceName].env;
+      return [key, rollbackEnvMap.get(key) ?? ""];
+    }));
+    console.log(`[stack-update] Restoring env keys for service ${scopedServiceNames.join(", ")} from ${rollbackEnv}`);
+    writeFileSync(options.envFile, patchEnv(readFileSync(options.envFile, "utf8"), scopedUpdates), { mode: 384 });
+  } else {
+    console.log(`[stack-update] Restoring env from ${rollbackEnv}`);
+    writeFileSync(options.envFile, rollbackEnvRaw, { mode: 384 });
+  }
+  const composeArgs = ["compose", "--file", options.composeFile, "--env-file", options.envFile];
+  if (lockData?.services) {
+    for (const [serviceName, service] of Object.entries(lockData.services)) {
+      if (scopedServiceNames.length > 0 && !scopedServiceNames.includes(serviceName)) continue;
+      if (!service.migrations?.rollback) continue;
+      const composeServiceName = service.composeService ?? serviceName;
+      console.log(`[stack-update] Running rollback migration for ${composeServiceName}: ${service.migrations.rollback}`);
+      try {
+        const migrationArgs = service.migrations.rollback.split(/\s+/);
+        exec("docker", [
+          ...composeArgs,
+          "run",
+          "--rm",
+          "--no-deps",
+          composeServiceName,
+          ...migrationArgs
+        ]);
+        console.log(`[stack-update] \u2713 Rollback migration for ${composeServiceName} completed`);
+      } catch (migErr) {
+        const reason = migErr instanceof Error ? migErr.message : String(migErr);
+        console.warn(`[stack-update] \u26A0 Rollback migration failed for ${composeServiceName}: ${reason} \u2014 continuing rollback`);
+      }
+    }
+  }
+  console.log("[stack-update] Restarting services with previous images\u2026");
+  if (scopedServiceNames.length > 0 && lockData?.services) {
+    for (const serviceName of scopedServiceNames) {
+      const composeServiceName = lockData.services[serviceName]?.composeService ?? serviceName;
+      exec("docker", [...composeArgs, "up", "-d", "--remove-orphans", "--no-deps", composeServiceName]);
+    }
+  } else {
+    exec("docker", [...composeArgs, "up", "-d", "--remove-orphans"]);
+  }
+  console.log("[stack-update] Rollback complete.");
+  return { status: "rolled_back", targetVersion: "previous", changes: [], backupEnvFile: rollbackEnv, lockFile: lockFilePath, serviceStatus: lockData?.serviceStatus };
+}
+function manifestImagesForPull(release) {
+  return Array.from(new Set(
+    Object.values(release.services).map((service) => service.image.trim()).filter(Boolean)
+  ));
+}
+function cloneReleaseWithServices(release, serviceNames) {
+  const wanted = new Set(serviceNames);
+  const services = {};
+  for (const [name, service] of Object.entries(release.services)) {
+    if (wanted.has(name) || wanted.has(service.composeService ?? name)) {
+      services[name] = service;
+    }
+  }
+  const missing = serviceNames.filter((name) => !Object.entries(release.services).some(([svcName, svc]) => svcName === name || (svc.composeService ?? svcName) === name));
+  if (missing.length > 0) throw new Error(`Stack service not found in manifest: ${missing.join(", ")}`);
+  return { ...release, services };
+}
+function readStackUpdateLock(lockFile) {
+  if (!existsSync(lockFile)) return void 0;
+  try {
+    return JSON.parse(readFileSync(lockFile, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function writeStackUpdateLock(lockFile, data) {
+  writeFileSync(lockFile, JSON.stringify(data, null, 2) + "\n");
+}
+function buildInitialServiceStatus(plan, envRaw, now, activeServices) {
+  const env = parseEnv(envRaw);
+  const at = now().toISOString();
+  return Object.fromEntries(Object.entries(plan.release.services).map(([serviceName, service]) => [
+    serviceName,
+    {
+      service: serviceName,
+      image: service.image,
+      env: service.env,
+      before: env.get(service.env),
+      after: service.image,
+      status: activeServices && !activeServices.has(serviceName) ? "skipped" : "pending",
+      error: activeServices && !activeServices.has(serviceName) ? "not selected for this service-scoped update" : void 0,
+      updatedAt: at
+    }
+  ]));
+}
+function updateServiceStatus(lockFile, serviceName, status, now, error) {
+  const lock = readStackUpdateLock(lockFile);
+  if (!lock?.serviceStatus?.[serviceName]) return lock?.serviceStatus;
+  lock.serviceStatus[serviceName] = {
+    ...lock.serviceStatus[serviceName],
+    status,
+    error,
+    updatedAt: now().toISOString()
+  };
+  lock.updatedAt = now().toISOString();
+  writeStackUpdateLock(lockFile, lock);
+  return lock.serviceStatus;
+}
+function incompleteServicesFromLock(lockFile) {
+  const lock = readStackUpdateLock(lockFile);
+  const serviceStatus = lock?.serviceStatus ?? {};
+  return Object.entries(serviceStatus).filter(([, status]) => status.status !== "completed" && status.status !== "skipped").map(([service]) => service);
+}
+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, serviceNames, selection) {
+  const version = targetVersion ?? manifest.latest;
+  const manifestRelease = manifest.stacks[version];
+  if (!manifestRelease) throw new Error(`Stack version ${version} not found in manifest`);
+  const selectedRelease = filterServicesBySelection(manifestRelease, selection);
+  const release = serviceNames && serviceNames.length > 0 ? cloneReleaseWithServices(selectedRelease, serviceNames) : selectedRelease;
+  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 ?? [],
+    scopedServices: serviceNames && serviceNames.length > 0 ? Object.keys(release.services) : void 0
+  };
+}
+var ASKEXE_GHCR_IMAGE = /^(?:ghcr\.io\/askexe|update\.askexe\.com\/askexe)\/[a-z0-9._/-]+(?:(?::[^:@$/{]+)(?:@sha256:[a-f0-9]{64})?|@sha256:[a-f0-9]{64})$/i;
+var OFFICIAL_COMPOSE_IMAGE = /^(?:postgres|pgvector\/pgvector|clickhouse\/clickhouse-server|redis|nginx|postgrest\/postgrest|supabase\/gotrue|cloudflare\/cloudflared|otel\/opentelemetry-collector-contrib)(?:(?::[^:@$/{]+)(?:@sha256:[a-f0-9]{64})?|@sha256:[a-f0-9]{64})$/i;
+function validatePinnedGhcrImage(image, label, requireDigest = false) {
+  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("update.askexe.com/askexe/")) return `${label} must use ghcr.io/askexe/* or update.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 update.askexe.com/askexe, got ${trimmed}`;
+  if (requireDigest && !/@sha256:[a-f0-9]{64}/.test(trimmed)) return `${label} must include @sha256: digest for supply-chain integrity, 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("update.askexe.com/askexe/")) return validatePinnedGhcrImage(trimmed, label);
+  if (OFFICIAL_COMPOSE_IMAGE.test(trimmed)) return null;
+  return `${label} uses unsupported non-AskExe image ${trimmed}; customer app images must come from pinned update.askexe.com/askexe or ghcr.io/askexe images`;
+}
+function resolveComposeImageExpression(image, env) {
+  let resolved = image.trim().replace(/^['"]|['"]$/g, "");
+  for (let i = 0; i < 12 && resolved.includes("${"); i++) {
+    const next = resolved.replace(/\$\{([^${}]+)\}/g, (_match, body) => {
+      const fallbackIdx = body.indexOf(":-");
+      const key = (fallbackIdx >= 0 ? body.slice(0, fallbackIdx) : body).trim();
+      const fallback = fallbackIdx >= 0 ? body.slice(fallbackIdx + 2) : "";
+      const envValue = env.get(key);
+      return envValue && envValue.trim() ? envValue.trim() : fallback;
+    });
+    if (next === resolved) break;
+    resolved = next.trim().replace(/^['"]|['"]$/g, "");
+  }
+  if (resolved.includes("${")) return null;
+  return resolved || null;
+}
+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 resolved = resolveComposeImageExpression(image, env);
+        if (resolved) {
+          const composeIssue = validateComposeImageLiteral(resolved, `compose image resolved value 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 collectImageAvailabilityIssues(plan) {
+  const issues = [];
+  const checked = /* @__PURE__ */ new Set();
+  for (const [serviceName, service] of Object.entries(plan.release.services)) {
+    const image = service.image;
+    if (checked.has(image)) continue;
+    checked.add(image);
+    try {
+      const result = spawnSync("docker", ["manifest", "inspect", image, "--verbose"], {
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 3e4
+      });
+      if (result.status !== 0) {
+        const stderr = result.stderr?.toString().trim() ?? "";
+        issues.push({
+          kind: "image-not-pullable",
+          message: `${serviceName} image ${image} not found on registry. ${stderr.slice(0, 200)}`
+        });
+        continue;
+      }
+      const output = result.stdout?.toString() ?? "";
+      try {
+        const parsed = JSON.parse(output);
+        const manifests = Array.isArray(parsed) ? parsed : [parsed];
+        const hasAmd64 = manifests.some((m) => {
+          const platform = m.platform;
+          return platform?.architecture === "amd64" && platform?.os === "linux";
+        });
+        if (!hasAmd64 && manifests.length > 0 && manifests[0]?.platform) {
+          const platforms = manifests.map((m) => {
+            const p = m.platform;
+            return `${p?.os ?? "?"}/${p?.architecture ?? "?"}`;
+          }).join(", ");
+          issues.push({
+            kind: "platform-mismatch",
+            message: `${serviceName} image ${image} has no linux/amd64 manifest (available: ${platforms}). Rebuild with: docker buildx build --platform linux/amd64 --push`
+          });
+        }
+      } catch {
+      }
+    } catch {
+    }
+  }
+  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 && !options.breakGlassReason?.trim()) {
+    const hasPrivateImages = Object.values(plan.release.services).some(
+      (s) => s.image.startsWith("update.askexe.com")
+    );
+    if (!hasPrivateImages) {
+      try {
+        const availabilityIssues = collectImageAvailabilityIssues(plan);
+        issues.push(...availabilityIssues);
+      } catch {
+      }
+    }
+  }
+  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 update.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: exe-os stack-update --target ${plan.targetVersion} --allow-breaking ${missing.map((c) => c.id).join(",")} --yes`
+    );
+  }
+}
+function registryFromImage(image) {
+  const first = image.split("/")[0] ?? "";
+  return first.includes(".") || first.includes(":") ? first : "docker.io";
+}
+function parseManualRegistryCredentials(raw, sampleImage) {
+  if (!raw) return void 0;
+  const [username, ...rest] = raw.split(":");
+  const password = rest.join(":");
+  if (!username || !password) return void 0;
+  return { registry: registryFromImage(sampleImage ?? ""), username, password };
+}
+async function verifyManifestImagesAvailable(plan, options) {
+  const exec = options.exec ?? defaultExec;
+  const images = manifestImagesForPull(plan.release);
+  const sampleImage = images[0];
+  let registryForLogout;
+  const creds = await fetchImageCredentials(options) ?? parseManualRegistryCredentials(options.registryCredentials || process.env.EXE_REGISTRY_CREDENTIALS, sampleImage);
+  if (creds) {
+    (options.dockerLogin ?? defaultDockerLogin)(creds);
+    registryForLogout = creds.registry;
+  }
+  try {
+    return images.map((image) => {
+      try {
+        exec("docker", ["manifest", "inspect", image]);
+        return { image, ok: true };
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { image, ok: false, error: reason };
+      }
+    });
+  } finally {
+    if (registryForLogout) {
+      try {
+        (options.dockerLogout ?? defaultDockerLogout)(registryForLogout);
+      } catch {
+      }
+    }
+  }
+}
+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 copyTemplate(srcRel, dest, created, options = {}) {
+  const existed = existsSync(dest);
+  if (existed && !options.overwrite) 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);
+  if (!existed) created.push(dest);
+}
+function copyTemplateIfMissing(srcRel, dest, created) {
+  copyTemplate(srcRel, dest, created);
+}
+function refreshPackagedInitSql(dest, created = []) {
+  copyTemplate("deploy/compose/init-db.sql", dest, created, { overwrite: true });
+}
+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 === "CLOUDFLARE_TUNNEL_TOKEN") 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);
+  refreshPackagedInitSql(path.join(path.dirname(options.composeFile), "init-db.sql"), createdFiles);
+  copyTemplateIfMissing(
+    "deploy/compose/clickhouse-config.xml",
+    path.join(path.dirname(options.envFile), "clickhouse-config.xml"),
+    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: "Exe", productName: "Exe OS" }, null, 2) + "\n", { mode: 384 });
+  copyTemplateIfMissing(
+    "deploy/compose/cloudflared/config.yml.example",
+    path.join(path.dirname(options.composeFile), "cloudflared", "config.yml.example"),
+    createdFiles
+  );
+  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|MONITOR_HUB_ADMIN|CLOUDFLARE_TUNNEL_TOKEN/.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 hardenHost(exec) {
+  const run = exec ?? defaultExec;
+  const result = {
+    skipped: false,
+    ufw: { changed: false, actions: [] },
+    ssh: { changed: false, actions: [] }
+  };
+  if (process.platform !== "linux") {
+    result.skipped = true;
+    result.reason = "Host hardening only runs on Linux (skipped on " + process.platform + ")";
+    console.log(`[stack-update] ${result.reason}`);
+    return result;
+  }
+  hardenUfw(run, result);
+  hardenSsh(run, result);
+  return result;
+}
+function hardenUfw(exec, result) {
+  const whichUfw = spawnSync("which", ["ufw"], { stdio: ["pipe", "pipe", "pipe"], timeout: 5e3 });
+  const ufwInstalled = whichUfw.status === 0;
+  if (!ufwInstalled) {
+    if (!existsSync("/etc/os-release")) {
+      result.ufw.actions.push("ufw_not_installed_unknown_distro");
+      console.warn("[stack-update] UFW not installed and OS not detected \u2014 skipping firewall hardening");
+      return;
+    }
+    const osRelease = readFileSync("/etc/os-release", "utf8");
+    if (!/ID=(ubuntu|debian)|ID_LIKE=.*debian/.test(osRelease)) {
+      result.ufw.actions.push("ufw_not_installed_unsupported_distro");
+      console.warn("[stack-update] UFW not installed on non-Debian OS \u2014 skipping firewall hardening");
+      return;
+    }
+    console.log("[stack-update] Installing UFW...");
+    try {
+      exec("apt-get", ["install", "-y", "ufw"]);
+      result.ufw.actions.push("installed_ufw");
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.warn(`[stack-update] Failed to install UFW: ${reason}`);
+      result.ufw.actions.push("install_failed");
+      return;
+    }
+  }
+  const statusResult = spawnSync("ufw", ["status", "verbose"], {
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: 1e4
+  });
+  const statusOutput = statusResult.stdout ?? "";
+  const isActive = /Status:\s*active/i.test(statusOutput);
+  const has22 = /22\/tcp\s+ALLOW/i.test(statusOutput);
+  const has80 = /80\/tcp\s+ALLOW/i.test(statusOutput);
+  const has443 = /443\/tcp\s+ALLOW/i.test(statusOutput);
+  const defaultDeny = /Default:\s*deny\s*\(incoming\)/i.test(statusOutput);
+  if (isActive && has22 && has80 && has443 && defaultDeny) {
+    result.ufw.actions.push("already_hardened");
+    console.log("[stack-update] UFW already active with correct rules \u2014 skipping");
+    return;
+  }
+  console.log("[stack-update] Configuring UFW firewall...");
+  try {
+    if (!defaultDeny) {
+      exec("ufw", ["default", "deny", "incoming"]);
+      result.ufw.actions.push("set_default_deny_incoming");
+    }
+    exec("ufw", ["default", "allow", "outgoing"]);
+    result.ufw.actions.push("set_default_allow_outgoing");
+    if (!has22) {
+      exec("ufw", ["allow", "22/tcp"]);
+      result.ufw.actions.push("allow_22_tcp");
+    }
+    if (!has80) {
+      exec("ufw", ["allow", "80/tcp"]);
+      result.ufw.actions.push("allow_80_tcp");
+    }
+    if (!has443) {
+      exec("ufw", ["allow", "443/tcp"]);
+      result.ufw.actions.push("allow_443_tcp");
+    }
+    if (!isActive) {
+      exec("ufw", ["--force", "enable"]);
+      result.ufw.actions.push("enabled_ufw");
+    }
+    result.ufw.changed = true;
+    console.log("[stack-update] \u2713 UFW firewall configured: deny incoming, allow 22/80/443");
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[stack-update] UFW configuration failed (non-fatal): ${reason}`);
+    result.ufw.actions.push("configuration_failed");
+  }
+}
+function hardenSsh(exec, result) {
+  const sshdConfig = "/etc/ssh/sshd_config";
+  if (!existsSync(sshdConfig)) {
+    result.ssh.actions.push("sshd_config_not_found");
+    console.warn("[stack-update] /etc/ssh/sshd_config not found \u2014 skipping SSH hardening");
+    return;
+  }
+  let configRaw;
+  try {
+    configRaw = readFileSync(sshdConfig, "utf8");
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    result.ssh.actions.push("sshd_config_unreadable");
+    console.warn(`[stack-update] Cannot read sshd_config: ${reason}`);
+    return;
+  }
+  let modified = configRaw;
+  let needsReload = false;
+  const passwordAuthMatch = modified.match(/^\s*PasswordAuthentication\s+(yes|no)\s*$/m);
+  const passwordAuthCurrently = passwordAuthMatch?.[1]?.toLowerCase();
+  if (passwordAuthCurrently === "yes") {
+    modified = modified.replace(
+      /^\s*PasswordAuthentication\s+yes\s*$/m,
+      "PasswordAuthentication no"
+    );
+    result.ssh.actions.push("set_password_auth_no");
+    needsReload = true;
+  } else if (!passwordAuthMatch) {
+    if (/^#\s*PasswordAuthentication\s/m.test(modified)) {
+      modified = modified.replace(
+        /^#\s*PasswordAuthentication\s.*$/m,
+        "PasswordAuthentication no"
+      );
+    } else {
+      modified += "\nPasswordAuthentication no\n";
+    }
+    result.ssh.actions.push("set_password_auth_no");
+    needsReload = true;
+  } else {
+    result.ssh.actions.push("password_auth_already_no");
+  }
+  const rootLoginMatch = modified.match(/^\s*PermitRootLogin\s+(\S+)\s*$/m);
+  const rootLoginCurrently = rootLoginMatch?.[1]?.toLowerCase();
+  if (rootLoginCurrently === "yes") {
+    modified = modified.replace(
+      /^\s*PermitRootLogin\s+yes\s*$/m,
+      "PermitRootLogin prohibit-password"
+    );
+    result.ssh.actions.push("set_root_login_prohibit_password");
+    needsReload = true;
+  } else if (!rootLoginMatch) {
+    if (/^#\s*PermitRootLogin\s/m.test(modified)) {
+      modified = modified.replace(
+        /^#\s*PermitRootLogin\s.*$/m,
+        "PermitRootLogin prohibit-password"
+      );
+    } else {
+      modified += "\nPermitRootLogin prohibit-password\n";
+    }
+    result.ssh.actions.push("set_root_login_prohibit_password");
+    needsReload = true;
+  } else if (rootLoginCurrently === "prohibit-password" || rootLoginCurrently === "without-password" || rootLoginCurrently === "no") {
+    result.ssh.actions.push("root_login_already_restricted");
+  } else {
+    modified = modified.replace(
+      /^\s*PermitRootLogin\s+\S+\s*$/m,
+      "PermitRootLogin prohibit-password"
+    );
+    result.ssh.actions.push("set_root_login_prohibit_password");
+    needsReload = true;
+  }
+  if (!needsReload) {
+    console.log("[stack-update] SSH already hardened \u2014 skipping");
+    return;
+  }
+  try {
+    writeFileSync(sshdConfig, modified, { mode: 384 });
+    result.ssh.changed = true;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[stack-update] Failed to write sshd_config: ${reason}`);
+    result.ssh.actions.push("write_failed");
+    return;
+  }
+  try {
+    exec("systemctl", ["reload", "ssh"]);
+    result.ssh.actions.push("reloaded_ssh");
+  } catch {
+    try {
+      exec("systemctl", ["reload", "sshd"]);
+      result.ssh.actions.push("reloaded_sshd");
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      console.warn(`[stack-update] SSH reload failed (changes will apply on next restart): ${reason}`);
+      result.ssh.actions.push("reload_failed");
+    }
+  }
+  const sshSummary = result.ssh.actions.filter((a) => a.startsWith("set_")).map((a) => a.replace("set_", "").replaceAll("_", " ")).join(", ");
+  if (sshSummary) {
+    console.log(`[stack-update] \u2713 SSH hardened: ${sshSummary}`);
+  }
+}
+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" },
+  { file: "clickhouse-config.xml", description: "ClickHouse memory/log guardrails" }
+];
+var CRITICAL_VOLUMES = [
+  "postgres_data",
+  "gateway_data",
+  "gateway_whatsapp_auth",
+  "wiki_data",
+  "exe_os_data",
+  "crm_data",
+  "monitor_hub_data",
+  "monitor_agent_data",
+  "redis_data",
+  "clickhouse_data",
+  "erp_sites"
+];
+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.");
+  }
+}
+function warnLegacyDaemonVolume() {
+  const legacy = spawnSync("docker", ["volume", "inspect", "exe-os_exed_data"], {
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: 5e3
+  });
+  const current = spawnSync("docker", ["volume", "inspect", "exe-os_exe_os_data"], {
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: 5e3
+  });
+  if (legacy.status === 0 && current.status === 0) {
+    console.warn("[stack-update] \u26A0 Legacy volume exe-os_exed_data exists alongside exe-os_exe_os_data.");
+    console.warn("[stack-update] Keeping both volumes intact; after verifying exe_os_data has current daemon state, remove exed_data manually if desired.");
+  }
+}
+function applyPostgresInitSql(composeArgs, envFile, composeFile, exec) {
+  const initSql = path.join(path.dirname(composeFile), "init-db.sql");
+  refreshPackagedInitSql(initSql);
+  if (!existsSync(initSql)) return;
+  const env = parseEnv(readFileSync(envFile, "utf8"));
+  const postgresUser = env.get("POSTGRES_USER") || "exe";
+  const postgresDb = env.get("POSTGRES_DB") || "exedb";
+  console.log("[stack-update] Applying idempotent Postgres init SQL for existing volumes...");
+  exec("docker", [
+    ...composeArgs,
+    "exec",
+    "-T",
+    "exe-db",
+    "psql",
+    "-v",
+    "ON_ERROR_STOP=1",
+    "-U",
+    postgresUser,
+    "-d",
+    postgresDb,
+    "-f",
+    "/docker-entrypoint-initdb.d/01-init.sql"
+  ]);
+  console.log("[stack-update] \u2713 Postgres init SQL applied");
+}
+async function runStackUpdate(options) {
+  const exec = options.exec ?? defaultExec;
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const phaseDurations = [];
+  const startPhase = (name) => {
+    const started = Date.now();
+    console.log(`[stack-update] ${now().toISOString()} \u25B6 ${name} started`);
+    return () => {
+      const durationMs = Date.now() - started;
+      phaseDurations.push({ name, durationMs });
+      console.log(`[stack-update] ${now().toISOString()} \u2713 ${name} completed in ${(durationMs / 1e3).toFixed(1)}s`);
+    };
+  };
+  const printPhaseSummary = () => {
+    if (phaseDurations.length === 0) return;
+    console.log("[stack-update] Phase duration summary:");
+    for (const phase of phaseDurations) {
+      console.log(`  - ${phase.name}: ${(phase.durationMs / 1e3).toFixed(1)}s`);
+    }
+  };
+  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));
+  warnLegacyDaemonVolume();
+  if (!options.dryRun) {
+    try {
+      const endPhase = startPhase("preflight");
+      if (!options.preflight) {
+        throw new Error("preflight hook not provided");
+      }
+      const preflightReport = options.preflight({
+        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");
+      endPhase();
+    } 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);
+  if (options.addService || options.removeService) {
+    const effectiveVersion = options.targetVersion ?? manifest.latest;
+    const manifestRelease = manifest.stacks[effectiveVersion];
+    if (!manifestRelease) throw new Error(`Stack version ${effectiveVersion} not found in manifest`);
+    const currentSelection = loadServiceSelection(options.envFile);
+    const currentServices = new Set(currentSelection?.selectedServices ?? buildDefaultServiceSelection(manifestRelease));
+    if (options.addService) {
+      if (!manifestRelease.services[options.addService]) {
+        throw new Error(`Service "${options.addService}" not found in manifest ${effectiveVersion}. Available: ${Object.keys(manifestRelease.services).join(", ")}`);
+      }
+      currentServices.add(options.addService);
+      console.log(`[stack-update] Added service: ${options.addService}`);
+    }
+    if (options.removeService) {
+      const svc = manifestRelease.services[options.removeService];
+      if (svc?.required) throw new Error(`Cannot remove required service: ${options.removeService}`);
+      currentServices.delete(options.removeService);
+      console.log(`[stack-update] Removed service: ${options.removeService}`);
+    }
+    saveServiceSelection(options.envFile, [...currentServices]);
+    console.log(`[stack-update] Saved service selection: ${[...currentServices].join(", ")}`);
+  }
+  if (options.services && options.services.length > 0) {
+    saveServiceSelection(options.envFile, options.services);
+    console.log(`[stack-update] Service selection overridden via --services: ${options.services.join(", ")}`);
+  }
+  const serviceSelection = loadServiceSelection(options.envFile);
+  const envRaw = readFileSync(options.envFile, "utf8");
+  const lockFile = options.lockFile ?? path.join(path.dirname(options.envFile), ".exe-stack-lock.json");
+  const resumeLock = options.resume ? readStackUpdateLock(lockFile) : void 0;
+  if (options.resume && !resumeLock) throw new Error(`Cannot resume stack update: lock file not found or unreadable at ${lockFile}`);
+  const resumeServices = options.resume ? incompleteServicesFromLock(lockFile) : [];
+  if (options.resume && resumeServices.length === 0) throw new Error("Cannot resume stack update: no incomplete services found in lock file");
+  const scopedServiceNames = options.serviceName ? [options.serviceName] : resumeServices;
+  const effectiveTargetVersion = options.targetVersion ?? resumeLock?.stackVersion;
+  const plan = createStackUpdatePlan(manifest, envRaw, effectiveTargetVersion, scopedServiceNames, serviceSelection);
+  const fullTargetPlan = scopedServiceNames.length > 0 ? createStackUpdatePlan(manifest, envRaw, effectiveTargetVersion, void 0, serviceSelection) : plan;
+  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 previousVersion = readCurrentStackVersion(lockFile);
+  if (options.verifyImages) {
+    const endPhase = startPhase("verify images");
+    const results = await verifyManifestImagesAvailable(plan, options);
+    endPhase();
+    const failed = results.filter((r) => !r.ok);
+    for (const result of results) {
+      console.log(`[stack-update] ${result.ok ? "\u2713" : "\u2717"} image ${result.image}${result.error ? ` \u2014 ${result.error}` : ""}`);
+    }
+    printPhaseSummary();
+    if (failed.length > 0) {
+      throw new Error(`Image verification failed for ${failed.length} image(s).`);
+    }
+    return { status: "planned", targetVersion: plan.targetVersion, changes: plan.changes, lockFile };
+  }
+  const containersRunning = plan.changes.length === 0 ? areStackContainersRunning(options.composeFile, options.envFile) : true;
+  if (options.dryRun || !options.resume && plan.changes.length === 0 && containersRunning) {
+    return { status: "planned", targetVersion: plan.targetVersion, changes: plan.changes, lockFile };
+  }
+  await postDeployAudit(options, "started", plan.targetVersion, previousVersion);
+  try {
+    if (!options.preDeployBackup) {
+      throw new Error("preDeployBackup hook not provided");
+    }
+    options.preDeployBackup(plan.targetVersion);
+  } catch {
+  }
+  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", "clickhouse-config.xml"];
+  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 initialServiceStatus = options.resume && resumeLock?.serviceStatus ? resumeLock.serviceStatus : buildInitialServiceStatus(fullTargetPlan, envRaw, now, new Set(Object.keys(plan.release.services)));
+  writeStackUpdateLock(lockFile, {
+    stackVersion: plan.targetVersion,
+    previousVersion,
+    updatedAt: now().toISOString(),
+    backupEnvFile: resumeLock?.backupEnvFile ?? backupEnvFile,
+    services: { ...fullTargetPlan.release.services, ...resumeLock?.services ?? {}, ...plan.release.services },
+    serviceStatus: initialServiceStatus
+  });
+  try {
+    const { spawnSync: sp } = await import("child_process");
+    const backupSh = path.join(stackDir, "backup.sh");
+    if (existsSync(backupSh)) {
+      console.log("[stack-update] Uploading pre-update snapshot to R2...");
+      const r2Result = sp("bash", [backupSh, "--upload-r2"], {
+        encoding: "utf8",
+        timeout: 3e5,
+        // 5 min max
+        cwd: stackDir,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      if (r2Result.status === 0) {
+        console.log("[stack-update] \u2713 Pre-update snapshot uploaded to R2");
+      } else {
+        console.warn("[stack-update] R2 upload failed (non-blocking) \u2014 local backup preserved");
+      }
+    }
+  } catch {
+  }
+  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);
+  for (const serviceName of Object.keys(plan.release.services)) {
+    updateServiceStatus(lockFile, serviceName, "env_patched", now);
+  }
+  const composeArgs = ["compose", "--file", options.composeFile, "--env-file", options.envFile];
+  let registryForLogout;
+  try {
+    let creds = await fetchImageCredentials(options);
+    if (!creds) {
+      const manual = options.registryCredentials || process.env.EXE_REGISTRY_CREDENTIALS;
+      if (manual) {
+        const [username, ...rest] = manual.split(":");
+        const password = rest.join(":");
+        if (username && password) {
+          const sampleImage = Object.values(plan.release.services)[0]?.image ?? "";
+          const registry = sampleImage.startsWith("update.askexe.com") ? "update.askexe.com" : "ghcr.io";
+          creds = { registry, username, password };
+          console.log(`[stack-update] Using manual registry credentials for ${registry}.`);
+        }
+      }
+    }
+    if (!creds) {
+      const sampleImage = Object.values(plan.release.services)[0]?.image ?? "";
+      if (sampleImage.startsWith("update.askexe.com")) {
+        const stackEnvPullTokensRaw = process.env.EXE_REGISTRY_PROXY_PULL_TOKENS || (existsSync(options.envFile) ? (() => {
+          const envMap = parseEnv(readFileSync(options.envFile, "utf8"));
+          return envMap.get("EXE_REGISTRY_PROXY_PULL_TOKENS") ?? "";
+        })() : "");
+        const firstPullToken = stackEnvPullTokensRaw.split(/[\n,]/).map((s) => s.trim()).find(Boolean);
+        if (firstPullToken) {
+          creds = { registry: "update.askexe.com", username: "token", password: firstPullToken };
+          console.log("[stack-update] Using EXE_REGISTRY_PROXY_PULL_TOKENS for update.askexe.com registry auth.");
+        }
+      }
+    }
+    if (!creds) {
+      const sampleImage = Object.values(plan.release.services)[0]?.image ?? "";
+      if (sampleImage.startsWith("update.askexe.com")) {
+        const licenseKey = options.manifestAuthToken || options.licenseKey || process.env.EXE_LICENSE_KEY;
+        if (licenseKey) {
+          creds = { registry: "update.askexe.com", username: "license", password: licenseKey };
+          console.log("[stack-update] Using license key for update.askexe.com registry auth.");
+        }
+      }
+    }
+    if (creds) {
+      (options.dockerLogin ?? defaultDockerLogin)(creds);
+      registryForLogout = creds.registry;
+    }
+    const imagesToPull = manifestImagesForPull(plan.release);
+    const allServiceNames = Object.keys(plan.release.services);
+    const progress = new ProgressReporter(allServiceNames);
+    progress.resetCounter(imagesToPull.length);
+    progress.startPhase("pull");
+    for (let imgIdx = 0; imgIdx < imagesToPull.length; imgIdx++) {
+      const image = imagesToPull[imgIdx];
+      const endPull = startPhase(`pull ${image}`);
+      progress.logServiceStep(imgIdx + 1, image, "Pulling image");
+      exec("docker", ["pull", image]);
+      for (const [serviceName, service] of Object.entries(plan.release.services)) {
+        if (service.image === image) updateServiceStatus(lockFile, serviceName, "pulled", now);
+      }
+      endPull();
+    }
+    const endComposePull = startPhase("docker compose pull");
+    exec("docker", [...composeArgs, "pull"]);
+    endComposePull();
+    progress.endPhase();
+    const serviceEntries = Object.entries(plan.release.services);
+    progress.resetCounter(serviceEntries.length);
+    progress.startPhase("verify");
+    for (let svcIdx = 0; svcIdx < serviceEntries.length; svcIdx++) {
+      const [serviceName, service] = serviceEntries[svcIdx];
+      const endVerify = startPhase(`verify ${serviceName} image`);
+      const image = service.image;
+      progress.logServiceStep(svcIdx + 1, serviceName, "Verifying image");
+      try {
+        exec("docker", ["image", "inspect", image, "--format", "{{.Id}}"]);
+      } catch {
+        progress.logServiceFailure(
+          serviceName,
+          `Image ${image} was not pulled successfully. Check registry authentication \u2014 if the image is on update.askexe.com, ensure EXE_LICENSE_KEY or EXE_REGISTRY_PROXY_PULL_TOKENS is set.`,
+          options.composeFile
+        );
+        throw new Error(
+          `Image ${image} for service ${serviceName} was not pulled successfully. Check registry authentication \u2014 if the image is on update.askexe.com, ensure EXE_LICENSE_KEY or EXE_REGISTRY_PROXY_PULL_TOKENS is set.`
+        );
+      }
+      updateServiceStatus(lockFile, serviceName, "verified", now);
+      endVerify();
+    }
+    progress.endPhase();
+    const migratable = Object.entries(plan.release.services).filter(([, s]) => s.migrations?.command);
+    if (migratable.length > 0) {
+      progress.resetCounter(migratable.length);
+      progress.startPhase("migrate");
+    }
+    for (const [serviceName, service] of Object.entries(plan.release.services)) {
+      if (!service.migrations?.command) continue;
+      const composeServiceName = service.composeService ?? serviceName;
+      const endMigration = startPhase(`migrate ${composeServiceName}`);
+      progress.logServiceProgress(composeServiceName, "Migrating");
+      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`);
+        updateServiceStatus(lockFile, serviceName, "migrated", now);
+        endMigration();
+      } catch (migErr) {
+        const reason = migErr instanceof Error ? migErr.message : String(migErr);
+        progress.logServiceFailure(composeServiceName, `Migration failed: ${reason}`, options.composeFile);
+        updateServiceStatus(lockFile, serviceName, "failed", now, reason);
+        throw new Error(`Migration failed for ${composeServiceName} \u2014 aborting update. Fix the migration and retry. Error: ${reason}`);
+      }
+    }
+    if (migratable.length > 0) {
+      progress.endPhase();
+    }
+    const RESTART_ORDER = [
+      "exe-db",
+      // data layer — must be healthy before apps
+      "gotrue",
+      // auth — depends on idempotent init-db.sql applied after exe-db
+      "clickhouse",
+      "redis",
+      "exe-os",
+      // daemon — has its own health endpoint
+      "exe-crm",
+      // CRM app
+      "exe-crm-worker",
+      // CRM background worker
+      "exe-gateway",
+      // gateway — WhatsApp connections
+      "exe-wiki",
+      // wiki
+      "exe-erp",
+      // ERP — depends on exe-db + redis (dbs 3/4/5)
+      "exe-erp-websocket",
+      // ERP WebSocket (Socket.io)
+      "exe-erp-queue",
+      // ERP background workers (RQ)
+      "exe-erp-scheduler",
+      // ERP scheduled tasks
+      "cloudflared"
+      // tunnel — restarted last so services are healthy before it connects
+    ];
+    const scopedComposeServices = Object.entries(plan.release.services).map(([serviceName, service]) => service.composeService ?? serviceName);
+    const restartOrder = [
+      ...RESTART_ORDER.filter((service) => scopedComposeServices.includes(service)),
+      ...scopedComposeServices.filter((service) => !RESTART_ORDER.includes(service))
+    ];
+    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`);
+    let restartedAnyService = false;
+    progress.resetCounter(restartOrder.length);
+    progress.startPhase("restart");
+    let restartIndex = 0;
+    for (const service of restartOrder) {
+      restartIndex++;
+      const endRestart = startPhase(`restart ${service}`);
+      const manifestServiceName = Object.entries(plan.release.services).find(([name, svc]) => (svc.composeService ?? name) === service)?.[0] ?? service;
+      const psResult = spawnSync("docker", [...composeArgs, "ps", "--quiet", service], {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 1e4
+      });
+      if (psResult.status !== 0) continue;
+      progress.logServiceStep(restartIndex, service, "Restarting");
+      exec("docker", [...composeArgs, "up", "-d", "--remove-orphans", "--no-deps", service]);
+      restartedAnyService = true;
+      updateServiceStatus(lockFile, manifestServiceName, "restarted", now);
+      const maxWait = options.healthTimeoutSecs ?? 180;
+      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) {
+        const failMsg = `Service ${service} failed health check after ${maxWait}s`;
+        progress.logServiceFailure(service, failMsg, options.composeFile);
+        updateServiceStatus(lockFile, manifestServiceName, "failed", now, failMsg);
+        throw new Error(`${failMsg} \u2014 aborting update`);
+      }
+      if (service === "exe-db") {
+        applyPostgresInitSql(composeArgs, options.envFile, options.composeFile, exec);
+      }
+      progress.logServiceProgress(service, "Restarted");
+      updateServiceStatus(lockFile, manifestServiceName, "healthy", now);
+      endRestart();
+    }
+    progress.endPhase();
+    if (!restartedAnyService) {
+      exec("docker", [...composeArgs, "up", "-d", "--remove-orphans"]);
+    }
+    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);
+    for (const serviceName of Object.keys(plan.release.services)) {
+      updateServiceStatus(lockFile, serviceName, "completed", now);
+    }
+    try {
+      if (!options.healthGate) {
+        throw new Error("healthGate hook not provided");
+      }
+      const gateResult = await options.healthGate();
+      options.logHealthGateResult?.(gateResult);
+      if (!gateResult.passed) {
+        const failed = gateResult.results.filter((r) => r.status === "fail").map((r) => r.check);
+        throw new Error(`Health gate failed: ${failed.join(", ")}`);
+      }
+      console.log("[stack-update] \u2713 Health gate passed");
+    } catch (gateErr) {
+      if (gateErr instanceof Error && gateErr.message.startsWith("Health gate failed")) {
+        throw gateErr;
+      }
+      console.warn("[stack-update] Health gate check skipped (module not available)");
+    }
+    assertVolumesIntact();
+    try {
+      if (!options.verifyStack) {
+        throw new Error("verifyStack hook not provided");
+      }
+      const verifyReport = await options.verifyStack({ composeFile: options.composeFile, envFile: options.envFile });
+      const securityFailures = [];
+      for (const r of verifyReport.results) {
+        if (r.status === "fail") {
+          console.warn(`[verify-stack] FAIL: ${r.check}: ${r.message}`);
+          if (/security|auth|signup|password|ssl|tls|bind|exposed/i.test(r.check)) {
+            securityFailures.push(`${r.check}: ${r.message}`);
+          }
+        }
+      }
+      if (securityFailures.length > 0) {
+        throw new Error(`Security verification failed:
+  - ${securityFailures.join("\n  - ")}
+Fix these before the stack is safe to operate.`);
+      }
+    } catch (verifyErr) {
+      if (verifyErr instanceof Error && verifyErr.message.startsWith("Security verification failed")) {
+        throw verifyErr;
+      }
+      console.warn("[stack-update] Post-deploy verification skipped (module not available)");
+    }
+    if (!options.skipHardening) {
+      try {
+        const hardenResult = hardenHost(exec);
+        if (!hardenResult.skipped) {
+          const actions = [...hardenResult.ufw.actions, ...hardenResult.ssh.actions].filter(Boolean);
+          if (actions.length > 0) {
+            console.log(`[stack-update] Host hardening: ${actions.join(", ")}`);
+          }
+        }
+      } catch (hardenErr) {
+        const reason = hardenErr instanceof Error ? hardenErr.message : String(hardenErr);
+        console.warn(`[stack-update] Host hardening failed (non-fatal): ${reason}`);
+      }
+    } else {
+      console.log("[stack-update] Host hardening skipped (--skip-hardening)");
+    }
+    progress.logOverallSummary();
+    printPhaseSummary();
+    const finalLock = readStackUpdateLock(lockFile) ?? {};
+    writeStackUpdateLock(lockFile, { ...finalLock, stackVersion: plan.targetVersion, previousVersion, updatedAt: now().toISOString(), backupEnvFile: finalLock.backupEnvFile ?? backupEnvFile, services: { ...fullTargetPlan.release.services, ...finalLock.services ?? {}, ...plan.release.services } });
+    await postDeployAudit(options, "success", plan.targetVersion, previousVersion, void 0, { changes: plan.changes.length });
+    return { status: "updated", targetVersion: plan.targetVersion, changes: plan.changes, backupEnvFile, lockFile, serviceStatus: readStackUpdateLock(lockFile)?.serviceStatus };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    for (const serviceName of Object.keys(plan.release.services)) {
+      const currentStatus = readStackUpdateLock(lockFile)?.serviceStatus?.[serviceName]?.status;
+      if (currentStatus !== "completed") updateServiceStatus(lockFile, serviceName, "failed", now, reason);
+    }
+    console.error(`[stack-update] ROLLBACK starting for ${plan.targetVersion}: ${reason}`);
+    if (plan.release.services && Object.values(plan.release.services).some((s) => s.migrations?.command)) {
+      console.error(
+        "[stack-update] ROLLBACK warning: pre-swap migrations may not be reversible. Running configured rollback migrations where available; verify schema compatibility before re-running old images."
+      );
+    }
+    console.log("[stack-update] Attempting automatic rollback\u2026");
+    try {
+      await rollbackStackUpdate({
+        ...options,
+        lockFile,
+        serviceName: scopedServiceNames.length === 1 ? scopedServiceNames[0] : options.serviceName
+      });
+      console.log("[stack-update] Automatic rollback completed.");
+    } catch (rollbackErr) {
+      const rbReason = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+      console.error(`[stack-update] Rollback via rollbackStackUpdate failed: ${rbReason}`);
+      console.log("[stack-update] Falling back to basic env restore\u2026");
+      writeFileSync(options.envFile, envRaw, { mode: 384 });
+      try {
+        exec("docker", [...composeArgs, "up", "-d", "--remove-orphans"]);
+      } catch {
+      }
+    }
+    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;
+  try {
+    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 }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!res.ok) {
+      let body = "";
+      try {
+        body = (await res.text()).slice(0, 200);
+      } catch {
+      }
+      const suffix = body ? `: ${body}` : "";
+      if (res.status === 401 || res.status === 403) {
+        console.warn(
+          `[stack-update] Image credentials denied (HTTP ${res.status}${suffix}). AskExe must provision registry entitlement for this license/device, or provide EXE_REGISTRY_CREDENTIALS=user:token. Docker pull will use existing auth.`
+        );
+      } else {
+        console.warn(`[stack-update] Image credentials unavailable (HTTP ${res.status}${suffix}). Docker pull will use existing auth.`);
+      }
+      return null;
+    }
+    return await res.json();
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[stack-update] Image credentials fetch failed: ${reason}. Docker pull will use existing auth.`);
+    return null;
+  }
+}
+function readCurrentStackVersion(lockFile) {
+  if (!existsSync(lockFile)) return void 0;
+  try {
+    const parsed = JSON.parse(readFileSync(lockFile, "utf8"));
+    return parsed.stackVersion;
+  } catch {
+    return void 0;
+  }
+}
+function listAvailableVersions(manifest, currentVersion) {
+  const versions = Object.keys(manifest.stacks).sort((a, b) => compareVersions(a, b));
+  return versions.map((v) => ({
+    version: v,
+    releasedAt: manifest.stacks[v]?.releasedAt,
+    notes: manifest.stacks[v]?.notes,
+    isCurrent: v === currentVersion,
+    isLatest: v === manifest.latest
+  }));
+}
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 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://update.askexe.com/v1/stack-manifest.json");
+  const licenseKey = process.env.EXE_LICENSE_KEY || loadLicense() || process.env.EXE_STACK_UPDATE_TOKEN || void 0;
+  const isRemoteManifest = /^https?:\/\//.test(manifestRef);
+  const hasLicenseForRemote = !!licenseKey;
+  const apiBaseUrl = process.env.EXE_STACK_API_URL || process.env.EXE_CLOUD_ENDPOINT || "https://api.askexe.com";
+  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,
+    auditUrl: process.env.EXE_STACK_AUDIT_URL || (isRemoteManifest || hasLicenseForRemote ? `${apiBaseUrl}/v1/deploy-audits` : void 0),
+    imageCredentialsUrl: process.env.EXE_STACK_IMAGE_CREDENTIALS_URL || (isRemoteManifest || hasLicenseForRemote ? `${apiBaseUrl}/v1/image-credentials` : void 0),
+    // License key IS the auth token for update.askexe.com — no separate update token needed.
+    // EXE_STACK_UPDATE_TOKEN kept as legacy fallback during migration.
+    manifestAuthToken: licenseKey,
+    manifestPublicKey: loadDefaultPublicKey()
+  };
+}
+function detectDanglingVolumes() {
+  const result = spawnSync(
+    "docker",
+    ["volume", "ls", "--filter", "dangling=true", "--format", "{{.Name}}	{{.Driver}}"],
+    { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 3e4 }
+  );
+  if (result.status !== 0 || !result.stdout?.trim()) return [];
+  const volumes = [];
+  for (const line of result.stdout.trim().split("\n")) {
+    if (!line.trim()) continue;
+    const [name, driver] = line.split("	");
+    if (!name) continue;
+    const size = getVolumeSize(name);
+    volumes.push({ name, driver: driver ?? "local", size });
+  }
+  return volumes;
+}
+function getVolumeSize(volumeName) {
+  try {
+    const inspectResult = spawnSync(
+      "docker",
+      ["volume", "inspect", volumeName, "--format", "{{.Mountpoint}}"],
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 1e4 }
+    );
+    const mountpoint = inspectResult.stdout?.trim();
+    if (!mountpoint || inspectResult.status !== 0) return "unknown";
+    const duResult = spawnSync(
+      "du",
+      ["-sh", mountpoint],
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 1e4 }
+    );
+    if (duResult.status === 0 && duResult.stdout?.trim()) {
+      return duResult.stdout.trim().split(/\s+/)[0] ?? "unknown";
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function removeDanglingVolumes(volumes) {
+  const result = {
+    detected: volumes,
+    removed: [],
+    failed: [],
+    skipped: []
+  };
+  for (const vol of volumes) {
+    const checkResult = spawnSync(
+      "docker",
+      ["volume", "ls", "--filter", "dangling=true", "--filter", `name=^${vol.name}$`, "--format", "{{.Name}}"],
+      { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"], timeout: 1e4 }
+    );
+    const stillDangling = checkResult.stdout?.trim().split("\n").some((n) => n.trim() === vol.name);
+    if (!stillDangling) {
+      result.skipped.push(vol);
+      console.log(`[stack-update] Skipping ${vol.name} \u2014 no longer dangling`);
+      continue;
+    }
+    try {
+      execFileSync("docker", ["volume", "rm", vol.name], {
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 3e4
+      });
+      result.removed.push(vol);
+      console.log(`[stack-update] Removed volume: ${vol.name} (${vol.size})`);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      result.failed.push({ volume: vol, error: reason });
+      console.warn(`[stack-update] Failed to remove volume ${vol.name}: ${reason}`);
+    }
+  }
+  return result;
+}
+function printDanglingVolumes(volumes) {
+  if (volumes.length === 0) {
+    console.log("[stack-update] No orphaned volumes detected.");
+    return;
+  }
+  console.log(`
+[stack-update] Detected ${volumes.length} orphaned volume(s):`);
+  for (const vol of volumes) {
+    console.log(`  - ${vol.name}  (${vol.size}, driver: ${vol.driver})`);
+  }
+  console.log("");
+}
+function printVolumeCleanupResult(result) {
+  const { removed, failed, skipped } = result;
+  console.log(`
+[stack-update] Volume cleanup summary:`);
+  console.log(`  Removed: ${removed.length}`);
+  if (skipped.length > 0) console.log(`  Skipped (no longer dangling): ${skipped.length}`);
+  if (failed.length > 0) {
+    console.log(`  Failed:  ${failed.length}`);
+    for (const f of failed) {
+      console.log(`    - ${f.volume.name}: ${f.error}`);
+    }
+  }
+}
+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;
+}
+
+export {
+  serviceSelectionPath,
+  loadServiceSelection,
+  saveServiceSelection,
+  filterServicesBySelection,
+  buildDefaultServiceSelection,
+  ProgressReporter,
+  canonicalizeStackManifest,
+  verifyStackManifestSignature,
+  findLatestBackupEnvFile,
+  rollbackStackUpdate,
+  parseStackManifest,
+  loadStackManifest,
+  parseEnv,
+  patchEnv,
+  createStackUpdatePlan,
+  collectProductionDeployGateIssues,
+  collectImageAvailabilityIssues,
+  assertDeploymentScopeAllowed,
+  assertProductionDeployGate,
+  assertBreakingChangesAllowed,
+  verifyManifestImagesAvailable,
+  pairMonitorAgent,
+  bootstrapStackHost,
+  assertHostReadyForApply,
+  hardenHost,
+  runStackUpdate,
+  readCurrentStackVersion,
+  listAvailableVersions,
+  verifyReleaseHealth,
+  defaultStackPaths,
+  detectDanglingVolumes,
+  removeDanglingVolumes,
+  printDanglingVolumes,
+  printVolumeCleanupResult
+};