@meshxdata/fops 0.1.49 → 0.1.51

package/src/plugins/bundled/fops-plugin-azure/lib/azure-ops-config.js

@@ -0,0 +1,754 @@
+/**
+ * azure-ops-config.js
+ * Config and version management operations for Azure VMs.
+ * Extracted from azure-ops.js for maintainability.
+ */
+
+import chalk from "chalk";
+import { listVms, requireVmState } from "./azure-state.js";
+import {
+  DEFAULTS, DIM, OK, WARN, ERR,
+  banner, hint, kvLine, nameArg,
+  lazyExeca,
+  sshCmd, knockForVm,
+  resolveCliSrc,
+} from "./azure-helpers.js";
+import { closeKnock } from "./port-knock.js";
+
+// ── GHCR: resolve latest tag via gh CLI ──────────────────────────────────────
+
+const GHCR_ORG = "meshxdata";
+
+/**
+ * Pick a short error-like line from command output (git, etc.) for inclusion in reason.
+ */
+function pickErrorLine(output) {
+  const lines = (output || "").trim().split("\n").map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 0) return "";
+  const errorLike = /error|failed|denied|fatal|refused|cannot|unable|invalid|conflict|Permission/i;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (errorLike.test(lines[i]) && lines[i].length < 120) return lines[i];
+  }
+  return lines[lines.length - 1].length < 120 ? lines[lines.length - 1] : "";
+}
+
+/**
+ * Pick the most useful line from make download / docker pull output for a failure message.
+ * Prefers a line that mentions both an image and an error; then any error line; then last non-noise.
+ */
+function pickPullErrorLine(output) {
+  const lines = (output || "").trim().split("\n").map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 0) return "";
+  const errorLike = /error|failed|denied|unauthorized|not found|manifest|invalid|refused|required/i;
+  const imageRef = /ghcr\.io\/[\w.-]+\/[\w.-]+/;
+  const noise = /^(?:[\da-f]{12}\s+)?(?:Download complete|Pull complete|Pulled|Extracting|Waiting)$/i;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (imageRef.test(line) && errorLike.test(line)) return line;
+  }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (errorLike.test(line)) return line;
+  }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (imageRef.test(lines[i])) return lines[i];
+  }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!noise.test(lines[i])) return lines[i];
+  }
+  return lines[lines.length - 1];
+}
+
+/**
+ * Parse make download / docker output for image:tag that failed (not found).
+ * Returns [{ image: "ghcr.io/org/name", tag: "0.3.65" }, ...].
+ */
+function parseNotFoundImages(output) {
+  if (!output?.trim()) return [];
+  const seen = new Set();
+  const out = [];
+  // "Image ghcr.io/meshxdata/foundation-backend:0.3.65 failed to resolve reference"
+  // "failed to resolve reference \"...\": ... not found" (image:tag appears before "not found")
+  const re = /(ghcr\.io\/[^/]+\/[^:]+):([^\s"']+).*?(?:failed|not found)/gi;
+  let m;
+  while ((m = re.exec(output)) !== null) {
+    const key = `${m[1]}:${m[2]}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push({ image: m[1], tag: m[2] });
+    }
+  }
+  return out;
+}
+
+/**
+ * Get latest available tag for a GHCR image via gh api (org packages container versions).
+ * Returns tag string or null if not ghcr.io/org/... or gh api fails.
+ * Prefers semver-like tag, then "compose", then first tag.
+ */
+async function getLatestTagForGhcrImage(execa, imageFull) {
+  const match = imageFull.match(/^ghcr\.io\/([^/]+)\/(.+)$/);
+  if (!match) return null;
+  const [, org, pkg] = match;
+  try {
+    const { stdout, exitCode } = await execa("gh", [
+      "api",
+      `orgs/${org}/packages/container/${pkg}/versions`,
+      "--jq", "if length == 0 then null else (.[0].metadata.container.tags // []) end",
+    ], { timeout: 15000, reject: false });
+    if (exitCode !== 0 || !stdout?.trim() || stdout === "null") return null;
+    let tags = [];
+    try {
+      tags = JSON.parse(stdout);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(tags) || tags.length === 0) return null;
+    const semver = tags.find(t => /^\d+\.\d+\.\d+(-.+)?$/.test(t));
+    if (semver) return semver;
+    if (tags.includes("compose")) return "compose";
+    if (tags.includes("latest")) return "latest";
+    return tags[0];
+  } catch {
+    return null;
+  }
+}
+
+// ── config versions (remote component image tags) ────────────────────────────
+
+export const FOUNDATION_COMPONENTS = {
+  backend:   { label: "Backend",        image: "ghcr.io/meshxdata/foundation-backend",        envKey: "BACKEND" },
+  frontend:  { label: "Frontend",       image: "ghcr.io/meshxdata/foundation-frontend",       envKey: "FRONTEND" },
+  processor: { label: "Processor",      image: "ghcr.io/meshxdata/foundation-processor",      envKey: "PROCESSOR" },
+  watcher:   { label: "Watcher",        image: "ghcr.io/meshxdata/foundation-watcher",       envKey: "WATCHER" },
+  scheduler: { label: "Scheduler",      image: "ghcr.io/meshxdata/foundation-scheduler",      envKey: "SCHEDULER" },
+  storage:   { label: "Storage",        image: "ghcr.io/meshxdata/foundation-storage-engine",  envKey: "STORAGE" },
+  hive:      { label: "Hive Metastore", image: "ghcr.io/meshxdata/foundation-hive-metastore", envKey: "HIVE" },
+  data:      { label: "Data",           image: "ghcr.io/meshxdata/foundation-data",           envKey: "DATA" },
+  dataBase:  { label: "Data Base",      image: "ghcr.io/meshxdata/foundation-data-base",      envKey: "DATA_BASE" },
+};
+
+function trimEnvValue(val) {
+  if (val == null) return null;
+  return val.trim().replace(/\s*#.*$/, "").trim().replace(/^["']|["']$/g, "") || null;
+}
+
+function parseImageTagFromEnv(envContent) {
+  if (!envContent?.trim()) return null;
+  const line = envContent.match(/^\s*IMAGE_TAG\s*=\s*(.+)/m)?.[1];
+  if (line == null) return null;
+  return trimEnvValue(line);
+}
+
+function parsePerComponentTagsFromEnv(envContent) {
+  const out = {};
+  if (!envContent?.trim()) return out;
+  for (const key of Object.keys(FOUNDATION_COMPONENTS)) {
+    const envKey = FOUNDATION_COMPONENTS[key].envKey;
+    const varName = `IMAGE_TAG_${envKey}`;
+    const re = new RegExp(`^\\s*${varName}\\s*=[ \\t]*([^\\n\\r]*)`, "m");
+    const m = envContent.match(re);
+    if (m) {
+      const v = trimEnvValue(m[1]);
+      if (v) out[varName] = v;
+    }
+  }
+  return out;
+}
+
+export function parseComponentVersions(composeContent, envContent) {
+  const envTag = parseImageTagFromEnv(envContent);
+  const perComponent = parsePerComponentTagsFromEnv(envContent);
+
+  const versions = {};
+  for (const [key, comp] of Object.entries(FOUNDATION_COMPONENTS)) {
+    const escapedImage = comp.image.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`image:\\s*${escapedImage}:\\s*(.+)`, "m");
+    const m = composeContent.match(re);
+    if (m) {
+      const rawTag = m[1].trim();
+      const isEnvRef = rawTag.includes("${IMAGE_TAG");
+      const componentVar = `IMAGE_TAG_${comp.envKey}`;
+      const effectiveTag = isEnvRef
+        ? (perComponent[componentVar] ?? envTag ?? "compose")
+        : rawTag;
+      versions[key] = { ...comp, rawTag, effectiveTag, isEnvRef };
+    }
+  }
+  return { versions, globalTag: envTag || null };
+}
+
+export function applyVersionChanges(composeContent, changes) {
+  let result = composeContent;
+  for (const { image, oldPattern, newTag } of changes) {
+    const escapedImage = image.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escapedOld = oldPattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`(image:\\s*${escapedImage}:)\\s*${escapedOld}`, "g");
+    result = result.replace(re, `$1${newTag}`);
+  }
+  return result;
+}
+
+// ── azureConfig (feature flags) ──────────────────────────────────────────────
+
+export async function azureConfig(opts = {}) {
+  const execa = await lazyExeca();
+  const state = requireVmState(opts.vmName);
+  const ip = state.publicIp;
+  const adminUser = DEFAULTS.adminUser;
+
+  if (!ip) { console.error(chalk.red("\n  No IP. Is the VM running? Try: fops azure start\n")); process.exit(1); }
+
+  await knockForVm(state);
+
+  const ssh = (cmd) => sshCmd(execa, ip, adminUser, cmd, 30000);
+
+  hint("Reading feature flags from VM…");
+  const { stdout: composeContent, exitCode } = await ssh("cat /opt/foundation-compose/docker-compose.yaml");
+  if (exitCode !== 0 || !composeContent?.trim()) {
+    console.error(chalk.red("\n  Could not read docker-compose.yaml from VM.\n"));
+    process.exit(1);
+  }
+
+  const { KNOWN_FLAGS, parseComposeFlagsFromContent, applyComposeFlagChanges } =
+    await import(resolveCliSrc("feature-flags.js"));
+
+  const composeFlags = parseComposeFlagsFromContent(composeContent);
+
+  const allFlags = {};
+  for (const [name, info] of Object.entries(composeFlags)) {
+    allFlags[name] = { ...info, inCompose: true };
+  }
+  for (const name of Object.keys(KNOWN_FLAGS)) {
+    if (!allFlags[name]) {
+      allFlags[name] = { value: false, services: new Set(), lines: [], inCompose: false };
+    }
+  }
+
+  const flagNames = Object.keys(allFlags).sort();
+
+  console.log(chalk.bold.cyan("\n  Feature Flags") + chalk.dim(` — ${state.vmName} (${ip})\n`));
+
+  for (const name of flagNames) {
+    const flag = allFlags[name];
+    const label = KNOWN_FLAGS[name] || name;
+    const services = flag.services.size > 0 ? chalk.dim(` (${[...flag.services].join(", ")})`) : "";
+    if (flag.value) {
+      console.log(chalk.green(`  ✓ ${label}`) + services);
+    } else {
+      console.log(chalk.dim(`  · ${label}`) + services);
+    }
+  }
+  console.log("");
+
+  const { getInquirer } = await import(resolveCliSrc("lazy.js"));
+  const choices = flagNames.map((name) => ({
+    name: KNOWN_FLAGS[name] || name,
+    value: name,
+    checked: allFlags[name].value,
+  }));
+
+  const { enabled } = await (await getInquirer()).prompt([{
+    type: "checkbox",
+    name: "enabled",
+    message: "Toggle feature flags:",
+    choices,
+  }]);
+
+  const changes = [];
+  const affectedServices = new Set();
+
+  for (const name of flagNames) {
+    const flag = allFlags[name];
+    const newValue = enabled.includes(name);
+
+    if (newValue !== flag.value) {
+      if (flag.inCompose) {
+        for (const line of flag.lines) {
+          changes.push({ lineNum: line.lineNum, newValue: String(newValue) });
+        }
+        for (const svc of flag.services) affectedServices.add(svc);
+      } else if (newValue) {
+        console.log(chalk.yellow(`  ⚠ ${KNOWN_FLAGS[name] || name} not in docker-compose.yaml — add it to service environments to take effect`));
+      }
+    }
+  }
+
+  if (changes.length === 0) {
+    console.log(chalk.dim("\n  No changes.\n"));
+    if (state.knockSequence?.length) {
+      await closeKnock(ssh, { quiet: true });
+    }
+    return;
+  }
+
+  const updatedContent = applyComposeFlagChanges(composeContent, changes);
+
+  hint("Applying changes to VM…");
+  const b64 = Buffer.from(updatedContent).toString("base64");
+  const { exitCode: writeCode } = await sshCmd(execa, ip, adminUser,
+    `echo '${b64}' | base64 -d > /opt/foundation-compose/docker-compose.yaml`,
+    30000,
+  );
+  if (writeCode !== 0) {
+    console.error(chalk.red("\n  Failed to write docker-compose.yaml on VM.\n"));
+    if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+    process.exit(1);
+  }
+  console.log(chalk.green(`\n  ✓ Updated ${changes.length} flag value(s) on VM`));
+
+  if (affectedServices.size === 0) {
+    if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+    console.log("");
+    return;
+  }
+
+  const serviceList = [...affectedServices];
+  console.log(chalk.dim(`  Affected: ${serviceList.join(", ")}`));
+
+  const { restart } = await (await getInquirer()).prompt([{
+    type: "confirm",
+    name: "restart",
+    message: `Restart ${serviceList.length} service(s) on VM?`,
+    default: true,
+  }]);
+
+  if (restart) {
+    const svcArgs = serviceList.join(" ");
+    console.log(chalk.cyan(`\n  ▶ docker compose up -d --remove-orphans ${svcArgs}\n`));
+    await sshCmd(execa, ip, adminUser,
+      `cd /opt/foundation-compose && docker compose up -d --remove-orphans ${svcArgs}`,
+      120000,
+    );
+    console.log(chalk.green("\n  ✓ Services restarted on VM.\n"));
+  } else {
+    console.log(chalk.dim("\n  Changes saved. Restart manually: fops azure deploy\n"));
+  }
+
+  if (state.knockSequence?.length) {
+    await closeKnock(ssh, { quiet: true });
+  }
+}
+
+// ── azureConfigVersions (component versions) ─────────────────────────────────
+
+export async function azureConfigVersions(opts = {}) {
+  const execa = await lazyExeca();
+  const state = requireVmState(opts.vmName);
+  const ip = state.publicIp;
+  const adminUser = DEFAULTS.adminUser;
+
+  if (!ip) { console.error(chalk.red("\n  No IP. Is the VM running? Try: fops azure start\n")); process.exit(1); }
+
+  await knockForVm(state);
+
+  const ssh = (cmd) => sshCmd(execa, ip, adminUser, cmd, 30000);
+
+  hint("Reading component versions from VM…");
+  const { stdout: composeContent, exitCode } = await ssh("cat /opt/foundation-compose/docker-compose.yaml");
+  if (exitCode !== 0 || !composeContent?.trim()) {
+    console.error(chalk.red("\n  Could not read docker-compose.yaml from VM.\n"));
+    process.exit(1);
+  }
+
+  const { stdout: envContent } = await ssh("cat /opt/foundation-compose/.env 2>/dev/null || echo ''");
+
+  const { versions, globalTag } = parseComponentVersions(composeContent, envContent);
+
+  const n = nameArg(state.vmName);
+  console.log(chalk.bold.cyan("\n  Component Versions") + chalk.dim(` — ${state.vmName} (${ip})\n`));
+
+  if (globalTag) {
+    console.log(chalk.dim(`  IMAGE_TAG=${globalTag}  (from .env)\n`));
+  }
+
+  const maxLabel = Math.max(...Object.values(versions).map(v => v.label.length));
+  for (const [key, v] of Object.entries(versions)) {
+    const tagDisplay = v.isEnvRef
+      ? `${chalk.white(v.effectiveTag)}  ${chalk.dim("(via IMAGE_TAG)")}`
+      : `${chalk.white(v.effectiveTag)}  ${chalk.yellow("(hardcoded in compose)")}`;
+    console.log(`  ${chalk.cyan(v.label.padEnd(maxLabel + 2))} ${tagDisplay}`);
+  }
+  console.log("");
+
+  const { getInquirer } = await import(resolveCliSrc("lazy.js"));
+  const inquirer = await getInquirer();
+
+  // Ask: set all at once, or pick individual components
+  const { mode } = await inquirer.prompt([{
+    type: "list",
+    name: "mode",
+    message: "How do you want to set versions?",
+    choices: [
+      { name: "Set all components to one tag (IMAGE_TAG)", value: "global" },
+      { name: "Set individual component tags", value: "individual" },
+      { name: "Cancel", value: "cancel" },
+    ],
+  }]);
+
+  if (mode === "cancel") {
+    console.log(chalk.dim("\n  Cancelled.\n"));
+    if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+    return;
+  }
+
+  const envPerComponent = {};
+  const composeChanges = [];
+  let envChanges = null;
+  const affectedComponents = [];
+
+  if (mode === "global") {
+    const { tag } = await inquirer.prompt([{
+      type: "input",
+      name: "tag",
+      message: "Tag for all components:",
+      default: globalTag || "compose",
+    }]);
+
+    const trimmed = tag.trim();
+    if (!trimmed) {
+      console.log(chalk.dim("\n  No tag entered.\n"));
+      if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+      return;
+    }
+
+    envChanges = trimmed;
+    for (const [key, v] of Object.entries(versions)) {
+      if (v.effectiveTag !== trimmed) affectedComponents.push(key);
+    }
+  } else {
+    // Individual mode — pick components; write IMAGE_TAG_* to .env only (no compose edit)
+    const componentKeys = Object.keys(versions);
+    const selected = [];
+
+    while (true) {
+      const remaining = componentKeys.filter(k => !selected.includes(k));
+      const choices = [
+        ...remaining.map(key => ({
+          name: `${versions[key].label}  (${versions[key].effectiveTag})`,
+          value: key,
+        })),
+        { name: chalk.dim(selected.length ? "── Done" : "── Cancel"), value: "_done" },
+      ];
+
+      const { pick } = await inquirer.prompt([{
+        type: "list",
+        name: "pick",
+        message: selected.length
+          ? `Selected: ${selected.map(k => versions[k].label).join(", ")}. Add more?`
+          : "Pick a component:",
+        choices,
+      }]);
+
+      if (pick === "_done") break;
+
+      const v = versions[pick];
+      const { tag } = await inquirer.prompt([{
+        type: "input",
+        name: "tag",
+        message: `Tag for ${v.label}:`,
+        default: v.effectiveTag,
+      }]);
+
+      const trimmed = tag.trim();
+      if (!trimmed || trimmed === v.effectiveTag) continue;
+
+      selected.push(pick);
+      envPerComponent[`IMAGE_TAG_${v.envKey}`] = trimmed;
+      affectedComponents.push(pick);
+
+      if (remaining.length <= 1) break;
+    }
+
+    if (!selected.length) {
+      console.log(chalk.dim("\n  No components selected.\n"));
+      if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+      return;
+    }
+  }
+
+  if (Object.keys(envPerComponent).length === 0 && composeChanges.length === 0 && !envChanges) {
+    console.log(chalk.dim("\n  No changes.\n"));
+    if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+    return;
+  }
+
+  let envAfterGlobal = envContent || "";
+  // Apply IMAGE_TAG to .env (global mode)
+  if (envChanges) {
+    hint(`Setting IMAGE_TAG=${envChanges} in .env…`);
+    if (/^\s*IMAGE_TAG\s*=/m.test(envAfterGlobal)) {
+      envAfterGlobal = envAfterGlobal.replace(/^\s*IMAGE_TAG\s*=.*/m, `IMAGE_TAG=${envChanges}`);
+    } else {
+      envAfterGlobal = envAfterGlobal.trimEnd() + (envAfterGlobal.trim() ? "\n" : "") + `IMAGE_TAG=${envChanges}\n`;
+    }
+    const envB64 = Buffer.from(envAfterGlobal).toString("base64");
+    const { exitCode: envWriteCode } = await sshCmd(execa, ip, adminUser,
+      `echo '${envB64}' | base64 -d > /opt/foundation-compose/.env`,
+      30000,
+    );
+    if (envWriteCode !== 0) {
+      console.error(chalk.red("\n  Failed to write .env on VM.\n"));
+      if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+      process.exit(1);
+    }
+    console.log(chalk.green(`  ✓ IMAGE_TAG=${envChanges}`));
+  }
+
+  // Apply per-component tags to .env only (no compose edit)
+  if (Object.keys(envPerComponent).length > 0) {
+    hint("Setting per-component tags in .env…");
+    let currentEnv = envAfterGlobal;
+    for (const [varName, tag] of Object.entries(envPerComponent)) {
+      const re = new RegExp(`^\\s*${varName}\\s*=.*`, "m");
+      if (re.test(currentEnv)) {
+        currentEnv = currentEnv.replace(re, `${varName}=${tag}`);
+      } else {
+        currentEnv = currentEnv.trimEnd() + (currentEnv.trim() ? "\n" : "") + `${varName}=${tag}\n`;
+      }
+      const comp = Object.values(FOUNDATION_COMPONENTS).find(c => `IMAGE_TAG_${c.envKey}` === varName);
+      console.log(chalk.green(`  ✓ ${comp?.label || varName}: ${tag}`));
+    }
+    const envB64 = Buffer.from(currentEnv).toString("base64");
+    const { exitCode: envWriteCode } = await sshCmd(execa, ip, adminUser,
+      `echo '${envB64}' | base64 -d > /opt/foundation-compose/.env`,
+      30000,
+    );
+    if (envWriteCode !== 0) {
+      console.error(chalk.red("\n  Failed to write .env on VM.\n"));
+      if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+      process.exit(1);
+    }
+  }
+
+  // Compose edits only for legacy hardcoded-tag fixes (e.g. make download fallback)
+  if (composeChanges.length > 0) {
+    hint("Updating docker-compose.yaml…");
+    const updatedContent = applyVersionChanges(composeContent, composeChanges);
+    const composeB64 = Buffer.from(updatedContent).toString("base64");
+    const { exitCode: composeWriteCode } = await sshCmd(execa, ip, adminUser,
+      `echo '${composeB64}' | base64 -d > /opt/foundation-compose/docker-compose.yaml`,
+      30000,
+    );
+    if (composeWriteCode !== 0) {
+      console.error(chalk.red("\n  Failed to write docker-compose.yaml on VM.\n"));
+      if (state.knockSequence?.length) await closeKnock(ssh, { quiet: true });
+      process.exit(1);
+    }
+    for (const c of composeChanges) {
+      const comp = Object.values(FOUNDATION_COMPONENTS).find(v => v.image === c.image);
+      console.log(chalk.green(`  ✓ ${comp?.label || c.image}: ${c.newTag}`));
+    }
+  }
+
+  console.log(chalk.green(`\n  ✓ ${affectedComponents.length} component(s) updated`));
+
+  // Offer to pull + restart
+  if (affectedComponents.length > 0) {
+    const { action } = await inquirer.prompt([{
+      type: "list",
+      name: "action",
+      message: "Pull images and restart?",
+      choices: [
+        { name: "Pull + restart affected services", value: "pull-restart" },
+        { name: "Pull only (no restart)", value: "pull" },
+        { name: "Skip (apply on next deploy)", value: "skip" },
+      ],
+    }]);
+
+    if (action === "pull-restart" || action === "pull") {
+      hint("Pulling images…");
+      await sshCmd(execa, ip, adminUser,
+        "cd /opt/foundation-compose && sudo docker compose pull --ignore-pull-failures 2>/dev/null; true",
+        300000,
+      );
+      console.log(chalk.green("  ✓ Images pulled"));
+
+      if (action === "pull-restart") {
+        hint("Restarting services…");
+        await sshCmd(execa, ip, adminUser,
+          "cd /opt/foundation-compose && sudo docker compose up -d --remove-orphans",
+          120000,
+        );
+        console.log(chalk.green("  ✓ Services restarted"));
+      }
+    } else {
+      hint(`Apply on next deploy: fops azure deploy${n}`);
+    }
+  }
+
+  if (state.knockSequence?.length) {
+    await closeKnock(ssh, { quiet: true });
+  }
+  console.log("");
+}
+
+// ── azureDeployVersion (non-interactive, CI-friendly) ────────────────────────
+
+export async function azureDeployVersion(opts = {}) {
+  const execa = await lazyExeca();
+  const component = opts.component;
+  const tag = opts.tag;
+
+  if (!component || !tag) {
+    console.error(chalk.red("\n  Usage: fops azure deploy version <component> <tag>"));
+    console.error(chalk.dim("  Components: " + Object.keys(FOUNDATION_COMPONENTS).join(", ")));
+    console.error(chalk.dim("  Example:    fops azure deploy version backend v0.3.80\n"));
+    process.exit(1);
+  }
+
+  const compDef = FOUNDATION_COMPONENTS[component];
+  if (!compDef) {
+    console.error(chalk.red(`\n  Unknown component: "${component}"`));
+    console.error(chalk.dim("  Available: " + Object.keys(FOUNDATION_COMPONENTS).join(", ") + "\n"));
+    process.exit(1);
+  }
+
+  const { activeVm, vms } = listVms();
+  const vmNames = Object.keys(vms);
+
+  // Determine targets: specific VM, all VMs, or AKS
+  const targets = [];
+  if (opts.vmName) {
+    if (!vms[opts.vmName]) {
+      console.error(chalk.red(`\n  VM "${opts.vmName}" not tracked. Run: fops azure list\n`));
+      process.exit(1);
+    }
+    targets.push(opts.vmName);
+  } else if (opts.all) {
+    targets.push(...vmNames);
+  } else if (vmNames.length === 1) {
+    targets.push(vmNames[0]);
+  } else if (activeVm && vms[activeVm]) {
+    targets.push(activeVm);
+  } else if (vmNames.length > 0) {
+    targets.push(...vmNames);
+  }
+
+  banner(`Deploy ${compDef.label} → ${tag}`);
+
+  // Deploy to VMs
+  if (targets.length > 0) {
+    kvLine("VMs", DIM(targets.join(", ")));
+    kvLine("Image", DIM(`${compDef.image}:${tag}`));
+    console.log("");
+
+    const results = await Promise.allSettled(targets.map(async (name) => {
+      const vm = vms[name];
+      if (!vm?.publicIp) return { name, ok: false, reason: "no public IP" };
+
+      try {
+        await knockForVm(vm);
+        const ip = vm.publicIp;
+        const adminUser = DEFAULTS.adminUser;
+        const ssh = (cmd) => sshCmd(execa, ip, adminUser, cmd, 30000);
+
+        // Read current compose + env
+        const { stdout: composeContent } = await ssh("cat /opt/foundation-compose/docker-compose.yaml");
+        const { stdout: envContent } = await ssh("cat /opt/foundation-compose/.env 2>/dev/null || echo ''");
+        if (!composeContent?.trim()) throw new Error("Cannot read docker-compose.yaml");
+
+        const { versions } = parseComponentVersions(composeContent, envContent);
+        const v = versions[component];
+        if (!v) {
+          console.log(chalk.dim(`  ${name}: ${compDef.label} not found in compose — skipping`));
+          return { name, ok: true, skipped: true };
+        }
+
+        if (v.effectiveTag === tag) {
+          console.log(OK(`  ${name}: ${compDef.label} already at ${tag}`));
+          return { name, ok: true, unchanged: true };
+        }
+
+        // Apply version change: per-component env var in .env only (no compose edit for env refs)
+        if (v.isEnvRef) {
+          const varName = `IMAGE_TAG_${v.envKey}`;
+          const currentEnv = envContent || "";
+          let newEnv;
+          const re = new RegExp(`^\\s*${varName}\\s*=.*`, "m");
+          if (re.test(currentEnv)) {
+            newEnv = currentEnv.replace(re, `${varName}=${tag}`);
+          } else {
+            newEnv = currentEnv.trimEnd() + (currentEnv.trim() ? "\n" : "") + `${varName}=${tag}\n`;
+          }
+          const envB64 = Buffer.from(newEnv).toString("base64");
+          await sshCmd(execa, ip, adminUser,
+            `echo '${envB64}' | base64 -d > /opt/foundation-compose/.env`, 30000);
+        } else {
+          const updated = applyVersionChanges(composeContent, [
+            { image: v.image, oldPattern: v.rawTag, newTag: tag },
+          ]);
+          const composeB64 = Buffer.from(updated).toString("base64");
+          await sshCmd(execa, ip, adminUser,
+            `echo '${composeB64}' | base64 -d > /opt/foundation-compose/docker-compose.yaml`, 30000);
+        }
+
+        // Pull the specific image and restart the service
+        const serviceName = `foundation-${component}`;
+        hint(`  ${name}: pulling ${compDef.image}:${tag}…`);
+        await sshCmd(execa, ip, adminUser,
+          `cd /opt/foundation-compose && sudo docker compose pull ${serviceName} 2>/dev/null; true`,
+          300000);
+
+        if (!opts.noPull) {
+          hint(`  ${name}: restarting ${serviceName}…`);
+          await sshCmd(execa, ip, adminUser,
+            `cd /opt/foundation-compose && sudo docker compose up -d --remove-orphans ${serviceName}`,
+            120000);
+        }
+
+        console.log(OK(`  ${name}: ${compDef.label} → ${tag} ✓`));
+        if (vm.knockSequence?.length) {
+          const sshFn = (cmd) => sshCmd(execa, ip, adminUser, cmd, 30000);
+          await closeKnock(sshFn, { quiet: true });
+        }
+        return { name, ok: true };
+      } catch (err) {
+        console.log(chalk.red(`  ${name}: failed — ${err.message}`));
+        return { name, ok: false, reason: err.message };
+      }
+    }));
+
+    const succeeded = results.filter(r => r.status === "fulfilled" && r.value?.ok).length;
+    const failed = targets.length - succeeded;
+    console.log(`\n  ${chalk.green(succeeded + " ok")}${failed ? chalk.red(", " + failed + " failed") : ""}`);
+  } else {
+    hint("No VMs tracked.");
+  }
+
+  // Deploy to AKS clusters if --aks or --all
+  if (opts.aks || opts.aksCluster) {
+    const aksTarget = opts.aksCluster || "";
+    hint(`\nUpdating AKS image tag…`);
+
+    try {
+      const { readAksClusters } = await import(resolveCliSrc("plugins/bundled/fops-plugin-azure/lib/azure-aks.js"));
+      const { clusters } = readAksClusters?.() || {};
+      const clusterNames = aksTarget ? [aksTarget] : Object.keys(clusters || {});
+
+      for (const cn of clusterNames) {
+        const fullImage = `${compDef.image}:${tag}`;
+        const namespace = "foundation";
+        const deployName = `foundation-${component}`;
+
+        const { exitCode, stderr } = await execa("kubectl", [
+          "--context", cn,
+          "set", "image",
+          `deployment/${deployName}`,
+          `${component}=${fullImage}`,
+          "-n", namespace,
+        ], { reject: false, timeout: 30000 });
+
+        if (exitCode === 0) {
+          console.log(OK(`  ${cn}: ${deployName} → ${tag}`));
+        } else {
+          console.log(WARN(`  ${cn}: ${(stderr || "").split("\n")[0]}`));
+        }
+      }
+    } catch (err) {
+      console.log(WARN(`  AKS deploy failed: ${err.message}`));
+    }
+  }
+
+  console.log("");
+}