@meshxdata/fops 0.1.36 → 0.1.38

package/src/plugins/bundled/fops-plugin-azure/lib/commands/vm-cmds.js

@@ -0,0 +1,893 @@
+/**
+ * VM lifecycle, SSH/knock, deploy/config, bootstrap, and misc commands.
+ * All operations target a single Azure VM.
+ */
+import { pathToFileURL } from "node:url";
+import chalk from "chalk";
+import { resolveFoundationCreds, resolveAuth0Config } from "../azure-auth.js";
+
+export function registerVmCommands(azure, api, registry) {
+  // ── doctor ──────────────────────────────────────────────────────────────
+  azure
+    .command("doctor [name]")
+    .description("Run doctor locally, or on VM if name given (e.g. fops azure doctor my-vm)")
+    .option("--fix", "Apply suggested fixes where possible", false)
+    .action(async (name, opts) => {
+      if (name) {
+        const {
+          lazyExeca, ensureAzCli, ensureAzAuth,
+          requireVmState, knockForVm, DEFAULTS, resolvePublicIp, sshCmd,
+        } = await import("../azure.js");
+        const { closeKnock } = await import("../port-knock.js");
+        const vmName = opts.vmName || name;
+        const execa = await lazyExeca();
+        await ensureAzCli(execa);
+        await ensureAzAuth(execa);
+        const state = requireVmState(vmName);
+        const ip = await resolvePublicIp(execa, state.resourceGroup, state.vmName, state.publicIp);
+        const user = DEFAULTS.adminUser;
+        if (!ip) {
+          console.error(chalk.red("\n  No IP address. Is the VM running? Try: fops azure start\n"));
+          process.exit(1);
+        }
+        await knockForVm(state);
+        const ssh = (cmd, timeout) => sshCmd(execa, ip, user, cmd, timeout);
+        const fixFlag = opts.fix ? " --fix" : "";
+        console.log(chalk.cyan(`\n  Running fops doctor on "${state.vmName}" (${ip})…\n`));
+        const { MUX_OPTS } = await import("../azure.js");
+        const { exitCode } = await execa("ssh", [
+          ...MUX_OPTS(ip, user),
+          `${user}@${ip}`,
+          `cd /opt/foundation-compose && fops doctor${fixFlag}`,
+        ], { timeout: 120000, reject: false, stdio: "inherit" });
+        await closeKnock(ssh, { quiet: true });
+        if (exitCode !== 0) process.exitCode = 1;
+        return;
+      }
+      const doctorPath = api.getCliPath?.("src", "doctor.js");
+      const mod = doctorPath
+        ? await import(pathToFileURL(doctorPath).href)
+        : await import("../../../../../doctor.js");
+      await mod.runDoctor({ fix: opts.fix }, registry ?? null);
+    });
+
+  // ── packer ───────────────────────────────────────────────────────────────
+  azure
+    .command("packer")
+    .description("Build the Foundation platform image with Packer")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--github-token <token>", "GitHub PAT for cloning private repos (default: $GITHUB_TOKEN)")
+    .option("--branch <branch>", "Git branch to bake into the image (default: main)")
+    .option("--fops-version <version>", "fops npm version to install (default: latest)")
+    .option("--location <region>", "Azure region for the build VM (default: from pkrvars)")
+    .option("--vm-size <size>", "Build VM size (default: from pkrvars)")
+    .option("--image-name <name>", "Output image name (default: foundation-platform)")
+    .option("--force", "Replace existing image if it already exists")
+    .action(async (opts) => {
+      const { azureBuild } = await import("../azure.js");
+      await azureBuild({
+        githubToken: opts.githubToken, branch: opts.branch, fopsVersion: opts.fopsVersion,
+        location: opts.location, vmSize: opts.vmSize, imageName: opts.imageName, force: opts.force,
+      });
+    });
+
+  // ── marketplace ──────────────────────────────────────────────────────────
+  const marketplace = azure
+    .command("marketplace")
+    .description("Prepare Azure VM image artifacts for Marketplace publishing");
+
+  marketplace
+    .command("image <vmName>")
+    .description("Create a Marketplace-ready managed image from a safe clone of a source VM (source VM unchanged)")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--source-rg <name>", "Resource group containing the source VM")
+    .option("--resource-group <name>", "Working RG for snapshot/clone/image (default: source RG)")
+    .option("--clone-vm-name <name>", "Temporary clone VM name")
+    .option("--clone-vm-size <size>", "Temporary clone VM size (default: source VM size)")
+    .option("--admin-user <name>", "Admin username for temporary clone VM (default: azureuser)")
+    .option("--snapshot-name <name>", "Snapshot name override")
+    .option("--disk-name <name>", "Managed disk name override")
+    .option("--image-name <name>", "Output managed image artifact name")
+    .option("--keep-staging", "Keep temporary clone resources (VM/disk/snapshot)")
+    .option("--gallery-name <name>", "Optional: publish to Azure Compute Gallery")
+    .option("--image-definition <name>", "Gallery image definition name (default: <offer>-<sku>)")
+    .option("--publisher <name>", "Required with --gallery-name")
+    .option("--offer <name>", "Required with --gallery-name")
+    .option("--sku <name>", "Required with --gallery-name")
+    .option("--version <version>", "Required with --gallery-name (e.g. 1.0.0)")
+    .option("--target-region <region>", "Target region for gallery image version (default: source VM region)")
+    .action(async (vmName, opts) => {
+      const { marketplaceImageFromVm } = await import("../azure.js");
+      await marketplaceImageFromVm({
+        vmName, profile: opts.profile, sourceRg: opts.sourceRg, resourceGroup: opts.resourceGroup,
+        cloneVmName: opts.cloneVmName, cloneVmSize: opts.cloneVmSize, adminUser: opts.adminUser,
+        snapshotName: opts.snapshotName, diskName: opts.diskName, imageName: opts.imageName,
+        keepStaging: opts.keepStaging, galleryName: opts.galleryName, imageDefinition: opts.imageDefinition,
+        publisher: opts.publisher, offer: opts.offer, sku: opts.sku, version: opts.version,
+        targetRegion: opts.targetRegion,
+      });
+    });
+
+  // ── up ───────────────────────────────────────────────────────────────────
+  azure
+    .command("up [names...]")
+    .description("Provision / reconcile Azure VMs, or run 'fops up <component> <branch>' on remote (e.g. fops azure up backend FOU-2072)")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "VM name (default: foundation-test-vm) or target VM for remote up")
+    .option("--vm-size <size>", "VM size (default: Standard_D8s_v3)")
+    .option("--location <region>", "Azure region (default: uaenorth)")
+    .option("--image <urn>", "Custom image URN or managed image ID (default: Ubuntu 24.04 LTS)")
+    .option("--branch <branch>", "Git branch to clone (default: main)")
+    .option("--fops-version <version>", "fops npm version to install (default: latest)")
+    .option("--url <url>", "Public URL override (default: https://<name>.meshx.app)")
+    .option("--github-token <token>", "GitHub PAT for .netrc + GHCR auth (default: $GITHUB_TOKEN)")
+    .option("--cf-token <token>", "Cloudflare API token for DNS (default: $CLOUDFLARE_API_TOKEN)")
+    .option("--wait-mode <mode>", "URL readiness mode: http-any (default) or http-2xx", "http-any")
+    .option("--no-knock", "Skip port-knock setup — SSH stays open to all")
+    .option("--k3s", "Include k3s Kubernetes services")
+    .option("--traefik", "Include traefik reverse proxy (auto-enabled for DNS URLs)")
+    .option("--dai", "Also start DAI services (implies --k3s)")
+    .option("--resource-group <name>", "Resource group for the VM (default: FOUNDATION-VM-RG or AZURE_RESOURCE_GROUP)")
+    .option("--update", "Run fops update (git pull, npm install, image pull) before starting services")
+    .action(async (names, opts) => {
+      if (opts.dai) opts.k3s = true;
+      const looksLikeBranch = (s) => /[/]/.test(s) || /^[A-Z]{2,}-\d+$/.test(s);
+      if (names.length === 2 && looksLikeBranch(names[1])) {
+        const { azureRunUp } = await import("../azure.js");
+        await azureRunUp({
+          vmName: opts.vmName, component: names[0], branch: names[1],
+          url: opts.url, k3s: opts.k3s, traefik: opts.traefik, dai: opts.dai, update: opts.update,
+        });
+        return;
+      }
+      const sharedOpts = {
+        vmSize: opts.vmSize, location: opts.location, image: opts.image, branch: opts.branch,
+        fopsVersion: opts.fopsVersion, url: opts.url, githubToken: opts.githubToken,
+        cfToken: opts.cfToken, profile: opts.profile, knock: opts.knock,
+        k3s: opts.k3s, traefik: opts.traefik, dai: opts.dai,
+        resourceGroup: opts.resourceGroup, waitMode: opts.waitMode,
+      };
+      const vmNames = names.length ? names : (opts.vmName ? [opts.vmName] : []);
+      if (vmNames.length > 0) {
+        const { azureUp } = await import("../azure.js");
+        for (const vmName of vmNames) await azureUp({ ...sharedOpts, vmName });
+      } else {
+        const { azureUpAll } = await import("../azure.js");
+        await azureUpAll(sharedOpts);
+      }
+    });
+
+  // ── list ─────────────────────────────────────────────────────────────────
+  azure
+    .command("list")
+    .description("List all tracked Azure VMs and AKS clusters (cached)")
+    .option("--live", "Force live probe (skip cache)")
+    .option("--verbose", "Show sync progress")
+    .option("--cost", "Show estimated cost per resource (queries Azure Cost Management)")
+    .option("--days <days>", "Days to look back for cost (default: 30)", "30")
+    .option("--versions", "Show service image version matrix")
+    .action(async (opts) => {
+      const { azureList } = await import("../azure.js");
+      await azureList({ live: opts.live, verbose: opts.verbose, cost: opts.cost, days: parseInt(opts.days), versions: opts.versions });
+    });
+
+  // ── select ───────────────────────────────────────────────────────────────
+  azure
+    .command("select [name]")
+    .description("Set the active VM (interactive picker when no name given)")
+    .action(async (name) => {
+      const { listVms, readState, saveState, migrateAzureState } = await import("../azure-state.js");
+      const { activeVm, vms } = listVms();
+      const vmNames = Object.keys(vms);
+      if (vmNames.length === 0) {
+        console.error(chalk.red("\n  No tracked VMs. Provision one first: fops azure up --vm-name <name>\n"));
+        process.exit(1);
+      }
+      let selected = name;
+      if (!selected) {
+        if (vmNames.length === 1) {
+          selected = vmNames[0];
+        } else {
+          const { default: inquirer } = await import("inquirer");
+          const answer = await inquirer.prompt([{
+            type: "list", name: "vm", message: "Select active VM:",
+            choices: vmNames.map(n => ({ name: n === activeVm ? `${n} ${chalk.dim("(current)")}` : n, value: n })),
+            default: activeVm,
+          }]);
+          selected = answer.vm;
+        }
+      }
+      if (!vms[selected]) {
+        console.error(chalk.red(`\n  VM "${selected}" not found. Tracked VMs: ${vmNames.join(", ")}\n`));
+        process.exit(1);
+      }
+      if (selected === activeVm) {
+        console.log(chalk.dim(`\n  "${selected}" is already the active VM.\n`));
+        return;
+      }
+      const state = readState();
+      const az = migrateAzureState(state.azure);
+      az.activeVm = selected;
+      state.azure = az;
+      saveState(state);
+      const vm = vms[selected];
+      const url = vm.publicIp ? `https://${vm.domain || selected + ".meshx.app"}` : "";
+      console.log(chalk.green(`\n  ✓ Active VM → ${chalk.bold(selected)}`));
+      if (url) console.log(chalk.dim(`    ${url}`));
+      console.log();
+    });
+
+  // ── down ─────────────────────────────────────────────────────────────────
+  azure
+    .command("down [name]")
+    .description("Destroy the Azure VM and all associated resources")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--cf-token <token>", "Cloudflare API token for DNS cleanup (default: $CLOUDFLARE_API_TOKEN)")
+    .action(async (name, opts) => {
+      const { azureDown } = await import("../azure.js");
+      await azureDown({ vmName: opts.vmName || name, profile: opts.profile, cfToken: opts.cfToken });
+    });
+
+  // ── stop ─────────────────────────────────────────────────────────────────
+  azure
+    .command("stop [name]")
+    .description("Stop (deallocate) the VM — no compute charges, disk preserved")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureStop } = await import("../azure.js");
+      await azureStop({ vmName: opts.vmName || name, profile: opts.profile });
+    });
+
+  // ── resize ───────────────────────────────────────────────────────────────
+  azure
+    .command("resize [name]")
+    .description("Scale the VM up (or down) to the next size in its family")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--size <size>", "Explicit target size (e.g. Standard_D8s_v3) — skips auto-detection")
+    .option("--down", "Scale down instead of up")
+    .option("--github-token <token>", "GitHub PAT for .netrc + GHCR auth (default: $GITHUB_TOKEN)")
+    .option("--k3s", "Include k3s Kubernetes services")
+    .option("--traefik", "Include traefik reverse proxy (auto-enabled for DNS URLs)")
+    .option("--dai", "Also start DAI services (implies --k3s)")
+    .action(async (name, opts) => {
+      if (opts.dai) opts.k3s = true;
+      const { azureResize } = await import("../azure.js");
+      await azureResize({ vmName: opts.vmName || name, size: opts.size, down: opts.down, githubToken: opts.githubToken, profile: opts.profile, k3s: opts.k3s, traefik: opts.traefik, dai: opts.dai });
+    });
+
+  // ── start ────────────────────────────────────────────────────────────────
+  azure
+    .command("start [name]")
+    .description("Start a stopped VM and reconfigure Foundation URL")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--url <url>", "Public URL override")
+    .option("--github-token <token>", "GitHub PAT for .netrc + GHCR auth (default: $GITHUB_TOKEN)")
+    .option("--cf-token <token>", "Cloudflare API token for DNS (default: $CLOUDFLARE_API_TOKEN)")
+    .option("--k3s", "Include k3s Kubernetes services")
+    .option("--traefik", "Include traefik reverse proxy (auto-enabled for DNS URLs)")
+    .option("--dai", "Also start DAI services (implies --k3s)")
+    .action(async (name, opts) => {
+      if (opts.dai) opts.k3s = true;
+      const { azureStart } = await import("../azure.js");
+      await azureStart({ vmName: opts.vmName || name, url: opts.url, githubToken: opts.githubToken, cfToken: opts.cfToken, profile: opts.profile, k3s: opts.k3s, traefik: opts.traefik, dai: opts.dai });
+    });
+
+  // ── status ───────────────────────────────────────────────────────────────
+  azure
+    .command("status [name]")
+    .description("Show VM state and Foundation service health")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureStatus } = await import("../azure.js");
+      await azureStatus({ vmName: opts.vmName || name, profile: opts.profile });
+    });
+
+  // ── trino-status ─────────────────────────────────────────────────────────
+  azure
+    .command("trino-status [name]")
+    .description("Check Trino container and engine status on the VM (for bootstrap debugging)")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureTrinoStatus } = await import("../azure.js");
+      await azureTrinoStatus({ vmName: opts.vmName || name, profile: opts.profile });
+    });
+
+  // ── terraform ────────────────────────────────────────────────────────────
+  azure
+    .command("terraform [name]")
+    .description("Generate Terraform HCL for the VM and its resources (VNet, NSG, IP, disk encryption)")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--output <file>", "Write HCL to a file instead of stdout")
+    .action(async (name, opts) => {
+      const { vmTerraform } = await import("../azure.js");
+      await vmTerraform({ vmName: opts.vmName || name, profile: opts.profile, output: opts.output });
+    });
+
+  // ── ssh ──────────────────────────────────────────────────────────────────
+  const ssh = azure
+    .command("ssh")
+    .description("SSH access and admin key management");
+
+  ssh
+    .command("connect [name]", { isDefault: true })
+    .description("Open an interactive SSH session to the VM")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureSsh } = await import("../azure.js");
+      await azureSsh({ vmName: opts.vmName || name });
+    });
+
+  const sshAdmin = ssh.command("admin").description("Manage admin SSH keys across all VMs");
+  sshAdmin
+    .command("add <pubKey>")
+    .description("Add a public SSH key to all tracked VMs")
+    .action(async (pubKey) => {
+      const { azureSshAdminAdd } = await import("../azure.js");
+      await azureSshAdminAdd({ pubKey });
+    });
+
+  ssh
+    .command("whitelist-me [names...]")
+    .description("Add your current public IP to the SSH (port 22) NSG rule (one or more VMs)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--profile <sub>", "Azure subscription profile")
+    .action(async (names, opts) => {
+      const { azureSshWhitelistMe } = await import("../azure.js");
+      const targets = names?.length ? names : [opts.vmName || undefined];
+      for (const vmName of targets) await azureSshWhitelistMe({ vmName, profile: opts.profile });
+    });
+
+  // ── port ─────────────────────────────────────────────────────────────────
+  azure
+    .command("port <remotePort>")
+    .description("Forward a remote VM port to localhost (SSH tunnel)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--local-port <port>", "Local port (default: same as remote port)")
+    .action(async (remotePort, opts) => {
+      const { azurePortForward } = await import("../azure.js");
+      await azurePortForward({ vmName: opts.vmName, remotePort: Number(remotePort), localPort: opts.localPort ? Number(opts.localPort) : undefined });
+    });
+
+  // ── foundation graphql ───────────────────────────────────────────────────
+  const azureFoundation = azure
+    .command("foundation")
+    .description("Foundation platform tools targeting a remote Azure VM");
+
+  azureFoundation
+    .command("graphql [name]")
+    .description("Start a local GraphiQL explorer tunnelled to a remote VM's Foundation API")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--port <port>", "Local port for GraphiQL (default: random)", "0")
+    .option("--api-port <port>", "Foundation API port on the VM (default: 9001)", "9001")
+    .action(async (name, opts) => {
+      const { knockForVm, closeMux, ensureKnockSequence, DEFAULTS, lazyExeca } = await import("../azure.js");
+      const { readVmState } = await import("../azure-state.js");
+      const rawName = opts.vmName || name;
+      // Sync IP + knock sequence from Azure before using them
+      const freshState = await ensureKnockSequence(readVmState(rawName));
+      const vmName = rawName || freshState?.vmName;
+      const ip = freshState?.publicIp;
+      if (!ip) {
+        console.error(chalk.red("\n  No IP. Is the VM running? Try: fops azure start\n"));
+        process.exit(1);
+      }
+
+      const execa = await lazyExeca();
+      await closeMux(execa, ip, DEFAULTS.adminUser);
+      await knockForVm(freshState);
+
+      const net = await import("node:net");
+      const tunnelPort = await new Promise((resolve) => {
+        const s = net.createServer();
+        s.listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => resolve(p)); });
+      });
+
+      const { exec } = await import("node:child_process");
+      console.log(chalk.cyan(`\n  Tunnelling ${ip}:${opts.apiPort} → localhost:${tunnelPort}…`));
+
+      const tunnel = execa("ssh", [
+        "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null",
+        "-o", "ExitOnForwardFailure=yes", "-o", "ConnectTimeout=20",
+        "-o", "ServerAliveInterval=30", "-N",
+        "-L", `${tunnelPort}:localhost:${opts.apiPort}`,
+        `${DEFAULTS.adminUser}@${ip}`,
+      ], { reject: false, stderr: "inherit" });
+
+      const deadline = Date.now() + 30000;
+      await new Promise((resolve, reject) => {
+        tunnel.then((result) => {
+          if (result.exitCode !== 0) reject(new Error(`SSH exited with code ${result.exitCode}`));
+        }).catch(() => {});
+        const check = () => {
+          const sock = net.createConnection({ host: "127.0.0.1", port: tunnelPort });
+          sock.on("connect", () => { sock.destroy(); resolve(); });
+          sock.on("error", () => {
+            sock.destroy();
+            if (Date.now() > deadline) return reject(new Error("SSH tunnel did not establish within 30s"));
+            setTimeout(check, 500);
+          });
+        };
+        setTimeout(check, 800);
+      });
+
+      try {
+        const { FoundationClient } = await import("../../../fops-plugin-foundation/lib/client.js");
+        const client = new FoundationClient({ apiUrl: `http://127.0.0.1:${tunnelPort}/api` });
+        const { GraphQLFacade } = await import("../../../fops-plugin-foundation-graphql/lib/graphql/facade.js");
+        const facade = new GraphQLFacade(client);
+        const { createGraphQLRoute } = await import("../../../fops-plugin-foundation-graphql/lib/graphql/hono-route.js");
+        const { serve } = await import("@hono/node-server");
+
+        const route = createGraphQLRoute(facade);
+        const gqlPort = parseInt(opts.port, 10) || 0;
+        const server = serve({ fetch: route.fetch, port: gqlPort }, (info) => {
+          const url = `http://127.0.0.1:${info.port}`;
+          console.log(chalk.cyan(`  ── Foundation GraphQL — ${vmName} (${ip}) ${"─".repeat(8)}`));
+          console.log(`  ${chalk.green("✓")} GraphiQL at ${chalk.bold(url)}`);
+          console.log(chalk.dim("  Press Ctrl+C to stop\n"));
+          const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+          exec(`${opener} ${url}`);
+        });
+
+        await new Promise((resolve) => {
+          const stop = () => { server.close(); tunnel.kill(); resolve(); };
+          process.on("SIGINT", stop);
+          process.on("SIGTERM", stop);
+        });
+      } catch (err) {
+        tunnel.kill();
+        console.error(chalk.red(`  ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  // ── agent ────────────────────────────────────────────────────────────────
+  azure
+    .command("agent [vmName]")
+    .description("Run fops agent TUI on the remote VM via SSH (vmName = VM name; use --agent for agent name)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--agent <name>", "Agent to run (default: foundation)", "foundation")
+    .option("-m, --message <text>", "Single-turn message instead of TUI")
+    .option("--classic", "Use classic terminal REPL instead of TUI")
+    .option("--model <id>", "Model override (e.g. claude-sonnet-4-20250514)")
+    .action(async (vmName, opts) => {
+      const { azureAgent } = await import("../azure.js");
+      await azureAgent({ vmName: opts.vmName || vmName, agent: opts.agent, message: opts.message, classic: opts.classic, model: opts.model });
+    });
+
+  // ── knock ─────────────────────────────────────────────────────────────────
+  const knock = azure
+    .command("knock")
+    .description("Perform port-knock sequence to temporarily open SSH");
+
+  knock
+    .command("open [names...]", { isDefault: true })
+    .description("Send the knock sequence — opens SSH for ~5 min")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (names, opts) => {
+      const { azureKnock } = await import("../azure.js");
+      const targets = opts.vmName ? [opts.vmName] : (names.length ? names : [undefined]);
+      for (const vmName of targets) await azureKnock({ vmName });
+    });
+
+  knock
+    .command("close [name]")
+    .description("Re-lock ports — revoke current knock, require a fresh one")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureKnockClose } = await import("../azure.js");
+      await azureKnockClose({ vmName: opts.vmName || name });
+    });
+
+  knock
+    .command("disable [name]")
+    .description("Remove port knocking — restore open SSH access")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureKnockDisable } = await import("../azure.js");
+      await azureKnockDisable({ vmName: opts.vmName || name });
+    });
+
+  knock
+    .command("verify [name]")
+    .description("Diagnose port-knock setup: check knockd, iptables rules, sequence match")
+    .option("--vm-name <name>", "Target VM (default: all VMs)")
+    .action(async (name, opts) => {
+      const { azureKnockVerify } = await import("../azure.js");
+      await azureKnockVerify({ vmName: opts.vmName || name });
+    });
+
+  knock
+    .command("fix [name]")
+    .description("Re-setup port knocking with correct iptables rules on all (or one) VM")
+    .option("--vm-name <name>", "Target VM (default: all VMs)")
+    .action(async (name, opts) => {
+      const { azureKnockFix } = await import("../azure.js");
+      await azureKnockFix({ vmName: opts.vmName || name });
+    });
+
+  // ── deploy ────────────────────────────────────────────────────────────────
+  const deploy = azure
+    .command("deploy")
+    .description("Deploy code, images, or specific component versions");
+
+  deploy
+    .command("stack [names...]", { isDefault: true })
+    .description("Pull latest code, images, and restart Foundation on the VM")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--branch <branch>", "Git branch to deploy (default: main)")
+    .option("--url <url>", "Public URL override")
+    .option("--github-token <token>", "GitHub PAT for .netrc + GHCR auth (default: $GITHUB_TOKEN)")
+    .option("--k3s", "Include k3s Kubernetes services")
+    .option("--traefik", "Include traefik reverse proxy (auto-enabled for DNS URLs)")
+    .option("--dai", "Also start DAI services (implies --k3s)")
+    .action(async (names, opts) => {
+      if (opts.dai) opts.k3s = true;
+      const { azureDeploy } = await import("../azure.js");
+      const targets = names?.length ? names : [opts.vmName || undefined];
+      for (const vmName of targets)
+        await azureDeploy({ vmName, branch: opts.branch, url: opts.url, githubToken: opts.githubToken, k3s: opts.k3s, traefik: opts.traefik, dai: opts.dai });
+    });
+
+  deploy
+    .command("version <component> <tag>")
+    .description("Set a component to a specific image tag, pull, and restart")
+    .option("--vm-name <name>", "Target a specific VM")
+    .option("--all", "Deploy to all tracked VMs")
+    .option("--aks", "Also deploy to AKS clusters")
+    .option("--aks-cluster <name>", "Target a specific AKS cluster")
+    .option("--no-restart", "Pull image but don't restart the service")
+    .action(async (component, tag, opts) => {
+      const { azureDeployVersion } = await import("../azure.js");
+      await azureDeployVersion({ component, tag, vmName: opts.vmName, all: opts.all, aks: opts.aks, aksCluster: opts.aksCluster, noPull: !opts.restart });
+    });
+
+  // ── config ────────────────────────────────────────────────────────────────
+  const config = azure
+    .command("config")
+    .description("Manage feature flags and component versions on the remote VM");
+
+  config
+    .command("flags [name]", { isDefault: true })
+    .description("Toggle MX_FF_* feature flags")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureConfig } = await import("../azure.js");
+      await azureConfig({ vmName: opts.vmName || name });
+    });
+
+  config
+    .command("versions [name]")
+    .description("Set image tags per Foundation component (backend, frontend, watcher, scheduler, storage)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureConfigVersions } = await import("../azure.js");
+      await azureConfigVersions({ vmName: opts.vmName || name });
+    });
+
+  // ── update ────────────────────────────────────────────────────────────────
+  azure
+    .command("update [names...]")
+    .description("Run fops update on tracked VMs in parallel (no args = all VMs, or list VM names)")
+    .option("--vm-name <name>", "Target a specific VM (alternative to positional names)")
+    .option("--github-token <token>", "GitHub PAT for git pull on VM when repo is private (default: $GITHUB_TOKEN)")
+    .option("--up", "After update, run fops up to restart services")
+    .action(async (names, opts) => {
+      const { azureUpdate } = await import("../azure.js");
+      const list = Array.isArray(names) ? names.filter(Boolean) : (names ? [names] : []);
+      await azureUpdate({ vmName: opts.vmName, vmNames: list.length ? list : undefined, githubToken: opts.githubToken, up: opts.up });
+    });
+
+  // ── apply ─────────────────────────────────────────────────────────────────
+  azure
+    .command("apply <file>")
+    .description("Apply a landscape file (FCL/HCL/YAML) to the remote VM's Foundation")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--dry-run", "Preview changes without creating entities")
+    .action(async (file, opts) => {
+      const { azureApply } = await import("../azure.js");
+      await azureApply(file, { vmName: opts.vmName, dryRun: opts.dryRun });
+    });
+
+  // ── download ──────────────────────────────────────────────────────────────
+  azure
+    .command("download [name]")
+    .description("Pull all container images on a VM (docker compose pull)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { lazyExeca, requireVmState, sshCmd, knockForVm } = await import("../azure.js");
+      const execa = await lazyExeca();
+      const state = requireVmState(opts.vmName || name);
+      const ip = state.ip || state.publicIp;
+      const user = state.adminUser || "azureuser";
+      if (!ip) {
+        console.log(chalk.red(`  ✗ No IP found for VM "${state.vmName}". Run: fops azure audit ${state.vmName}`));
+        return;
+      }
+      await knockForVm(state);
+      console.log(chalk.cyan(`  Pulling images on ${state.vmName || name} (${ip})…`));
+      const { stdout, stderr, exitCode } = await sshCmd(execa, ip, user, "cd /opt/foundation-compose && make download", 600000);
+      if (stdout) console.log(stdout);
+      if (exitCode !== 0) {
+        console.log(chalk.yellow(`  ⚠ download exited with code ${exitCode}`));
+        if (stderr) console.log(chalk.dim(stderr.split("\n").slice(-5).join("\n")));
+      } else {
+        console.log(chalk.green(`  ✓ Images pulled on ${state.vmName || name}`));
+      }
+    });
+
+  // ── pull ──────────────────────────────────────────────────────────────────
+  azure
+    .command("pull [name]")
+    .description("Pull latest git code on a VM (no restart)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--branch <branch>", "Git branch to pull (default: current branch)")
+    .option("--github-token <token>", "GitHub PAT for private repos (default: $GITHUB_TOKEN)")
+    .action(async (name, opts) => {
+      const { azurePull } = await import("../azure.js");
+      await azurePull({ vmName: opts.vmName || name, branch: opts.branch, githubToken: opts.githubToken });
+    });
+
+  // ── vm check ──────────────────────────────────────────────────────────────
+  azure
+    .command("vm check [name]")
+    .description("Diagnose VM: show config versions and run make download with full output (for image-pull failures)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, opts) => {
+      const { azureVmCheck } = await import("../azure.js");
+      await azureVmCheck({ vmName: opts.vmName || name });
+    });
+
+  // ── bootstrap ─────────────────────────────────────────────────────────────
+  azure
+    .command("bootstrap [name]")
+    .description("Run `fops bootstrap` on a VM (create demo data mesh)")
+    .option("--vm-name <name>", "Target VM (default: active)")
+    .action(async (name, opts) => {
+      const vmName = opts.vmName || name;
+      const {
+        lazyExeca, ensureAzCli, ensureAzAuth,
+        requireVmState, sshCmd, knockForVm, DEFAULTS,
+      } = await import("../azure.js");
+      const { closeKnock } = await import("../port-knock.js");
+      const fs = await import("node:fs");
+      const os = await import("node:os");
+      const pathMod = await import("node:path");
+      const execa = await lazyExeca();
+      await ensureAzCli(execa);
+      await ensureAzAuth(execa);
+      const state = requireVmState(vmName);
+      const ip = state.publicIp;
+      const user = DEFAULTS.adminUser;
+
+      if (!ip) {
+        console.error(chalk.red("\n  No IP address. Is the VM running? Try: fops azure start\n"));
+        process.exit(1);
+      }
+
+      // Load project root .env so credentials are available
+      let projectRoot = null;
+      try {
+        const fopsPath = pathMod.join(os.homedir(), ".fops.json");
+        const raw = JSON.parse(fs.readFileSync(fopsPath, "utf8"));
+        if (raw?.projectRoot && fs.existsSync(pathMod.join(raw.projectRoot, ".env"))) projectRoot = raw.projectRoot;
+      } catch {}
+      if (!projectRoot) {
+        let dir = pathMod.resolve(process.cwd());
+        for (;;) {
+          if (fs.existsSync(pathMod.join(dir, "docker-compose.yaml")) && fs.existsSync(pathMod.join(dir, "Makefile"))) {
+            projectRoot = dir; break;
+          }
+          const parent = pathMod.dirname(dir);
+          if (parent === dir) break;
+          dir = parent;
+        }
+      }
+      if (projectRoot) {
+        const { loadEnvFromFile } = await import("../azure-helpers.js");
+        const loaded = loadEnvFromFile(pathMod.join(projectRoot, ".env"));
+        for (const [k, v] of Object.entries(loaded)) {
+          if (process.env[k] === undefined) process.env[k] = v;
+        }
+      }
+
+      // Resolve credentials using shared helper
+      const creds = resolveFoundationCreds();
+      let bearerToken = creds?.bearerToken || "";
+      let qaUser = creds?.user || "";
+      let qaPass = creds?.password || "";
+
+      if (!bearerToken && !qaUser) {
+        console.error(chalk.red("\n  No Foundation credentials found locally."));
+        console.error(chalk.dim("  Set BEARER_TOKEN or QA_USERNAME/QA_PASSWORD in env, .env, or ~/.fops.json\n"));
+        process.exit(1);
+      }
+
+      // Pre-authenticate against the VM's API to get a bearer token
+      const vmUrl = state.publicUrl || `https://${ip}`;
+      let credsRejected = false;
+      if (!bearerToken && qaUser) {
+        console.log(chalk.dim(`  Pre-authenticating against ${vmUrl}…`));
+        const hasDomain = state.publicUrl && !state.publicUrl.match(/^https?:\/\/\d+\.\d+\.\d+\.\d+/);
+        const apiUrls = hasDomain
+          ? [`${vmUrl}/api`]
+          : [`${vmUrl}/api`, `https://${ip}:3002/api`, `http://${ip}:9001/api`];
+
+        for (const apiBase of apiUrls) {
+          try {
+            const resp = await fetch(`${apiBase}/iam/login`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ username: qaUser, password: qaPass }),
+              signal: AbortSignal.timeout(10000),
+            });
+            if (resp.ok) {
+              const data = await resp.json();
+              bearerToken = data.access_token || data.token || "";
+              if (bearerToken) {
+                console.log(chalk.green(`  ✓ Authenticated as ${qaUser} via ${apiBase}`));
+                break;
+              }
+            } else {
+              console.log(chalk.dim(`  ${apiBase}: HTTP ${resp.status}`));
+              if (resp.status === 401) credsRejected = true;
+            }
+          } catch (e) {
+            console.log(chalk.dim(`  ${apiBase}: ${e.cause?.code || e.message || "unreachable"}`));
+          }
+        }
+
+        if (!bearerToken) {
+          const auth0Cfg = resolveAuth0Config();
+          if (auth0Cfg) {
+            try {
+              console.log(chalk.dim(`  Trying Auth0 ROPC fallback (${auth0Cfg.domain})…`));
+              const body = {
+                grant_type: "password", client_id: auth0Cfg.clientId,
+                username: qaUser, password: qaPass, scope: "openid",
+              };
+              if (auth0Cfg.clientSecret) body.client_secret = auth0Cfg.clientSecret;
+              if (auth0Cfg.audience) body.audience = auth0Cfg.audience;
+              const resp = await fetch(`https://${auth0Cfg.domain}/oauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(10000),
+              });
+              if (resp.ok) {
+                const data = await resp.json();
+                bearerToken = data.access_token || "";
+                if (bearerToken) { credsRejected = false; console.log(chalk.green(`  ✓ Authenticated as ${qaUser} via Auth0`)); }
+              } else {
+                console.log(chalk.dim(`  Auth0: HTTP ${resp.status}`));
+              }
+            } catch (e) {
+              console.log(chalk.dim(`  Auth0 fallback: ${e.message || "failed"}`));
+            }
+          }
+        }
+      }
+
+      if (credsRejected && !bearerToken) {
+        console.error(chalk.red("\n  Credentials rejected by the remote API (HTTP 401)."));
+        console.error(chalk.dim("  The password for " + qaUser + " does not match this environment's Keycloak."));
+        console.error(chalk.dim("  Fix: set the correct password in ~/.fops.json or pass BEARER_TOKEN directly.\n"));
+        console.error(chalk.dim("  Hint: ssh into the VM and check the Keycloak password:"));
+        console.error(chalk.dim("    fops azure ssh " + (state.vmName || "") + "\n"));
+        process.exit(1);
+      }
+
+      const cred = {};
+      if (bearerToken) cred.BEARER_TOKEN = bearerToken;
+      else if (qaUser) { cred.QA_USERNAME = qaUser; cred.QA_PASSWORD = qaPass; }
+
+      if (!cred.BEARER_TOKEN && !cred.QA_USERNAME) {
+        console.error(chalk.red("\n  Could not authenticate against the VM's API."));
+        console.error(chalk.dim("  Check that the VM is running (fops azure status) and credentials are valid.\n"));
+        process.exit(1);
+      }
+
+      const vmEnv = { ...cred };
+      if (process.env.AUTH0_EMAIL?.trim()) vmEnv.AUTH0_EMAIL = process.env.AUTH0_EMAIL.trim();
+
+      await knockForVm(state);
+      const sshFn = (cmd, timeout, sshEnv) => sshCmd(execa, ip, user, cmd, timeout, { env: sshEnv });
+
+      const sedParts = ["sed -i '/^BEARER_TOKEN=/d;/^QA_USERNAME=/d;/^QA_PASSWORD=/d;/^AUTH0_EMAIL=/d' .env 2>/dev/null || true"];
+      for (const [k, v] of Object.entries(vmEnv)) {
+        const escaped = String(v).replace(/'/g, "'\\''");
+        sedParts.push(`echo '${k}=${escaped}' >> .env`);
+      }
+      await sshFn(`cd /opt/foundation-compose && ${sedParts.join(" && ")}`, 15000, vmEnv);
+
+      console.log(chalk.cyan(`\n  Running fops bootstrap on "${state.vmName}"…\n`));
+      const { MUX_OPTS } = await import("../azure.js");
+      const bootstrapEnv = vmEnv ? { ...process.env, ...vmEnv } : undefined;
+      const remoteCmd = "cd /opt/foundation-compose && (fops bootstrap --yes || /usr/local/bin/fops bootstrap --yes || /usr/bin/fops bootstrap --yes)";
+      const { exitCode } = await execa("ssh", [
+        ...MUX_OPTS(ip, user), `${user}@${ip}`, remoteCmd,
+      ], { timeout: 600000, reject: false, stdout: ["inherit"], stderr: ["inherit"], env: bootstrapEnv });
+
+      if (state.knockSequence?.length) await closeKnock(sshFn, { quiet: true });
+
+      if (exitCode === 0) {
+        console.log(chalk.green("\n  ✓ Bootstrap complete on VM\n"));
+      } else {
+        const normalized = exitCode === 255 || exitCode === -1 ? 1 : exitCode;
+        console.error(chalk.red(`\n  Bootstrap failed (exit ${normalized}).\n`));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── logs ──────────────────────────────────────────────────────────────────
+  azure
+    .command("logs [name] [service]")
+    .description("Tail Foundation logs from the VM (service 'up' = tail /tmp/fops-up.log)")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .action(async (name, service, opts) => {
+      const { azureLogs } = await import("../azure.js");
+      await azureLogs(service, { vmName: opts.vmName || name });
+    });
+
+  // ── context ───────────────────────────────────────────────────────────────
+  azure
+    .command("context [name]")
+    .description("Set local Docker CLI to talk to the remote VM via SSH")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--reset", "Switch back to the default Docker context")
+    .action(async (name, opts) => {
+      const { azureContext } = await import("../azure.js");
+      await azureContext({ vmName: opts.vmName || name, reset: opts.reset });
+    });
+
+  // ── kubectl ───────────────────────────────────────────────────────────────
+  azure
+    .command("kubectl <name>")
+    .description("Generate / merge kubeconfig for an AKS cluster")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--admin", "Get admin credentials (cluster-admin role)")
+    .action(async (name, opts) => {
+      const { aksKubeconfig } = await import("../azure-aks.js");
+      await aksKubeconfig({ clusterName: name, profile: opts.profile, admin: opts.admin });
+    });
+
+  // ── grant ─────────────────────────────────────────────────────────────────
+  const grant = azure.command("grant").description("Grant roles to users on the VM");
+  grant
+    .command("admin [name]")
+    .description("Grant Foundation Admin role to users on the VM")
+    .option("--vm-name <name>", "Target VM (default: active VM)")
+    .option("--username <email>", "Grant to a specific user by email")
+    .option("--auth0-sub <sub>", "Grant to a specific Auth0 subject")
+    .action(async (name, opts) => {
+      const { azureGrantAdmin } = await import("../azure.js");
+      await azureGrantAdmin({ vmName: opts.vmName || name, username: opts.username, auth0Sub: opts.auth0Sub });
+    });
+
+  // ── cost ──────────────────────────────────────────────────────────────────
+  azure
+    .command("cost")
+    .description("Show current Azure costs by service")
+    .option("--profile <subscription>", "Azure subscription name or ID")
+    .option("--days <days>", "Days to look back (default: 30)", "30")
+    .action(async (opts) => {
+      const { azureCost } = await import("../azure.js");
+      await azureCost({ profile: opts.profile, days: opts.days });
+    });
+
+  // ── subscriptions ─────────────────────────────────────────────────────────
+  azure
+    .command("subscriptions")
+    .description("List available Azure subscriptions")
+    .action(async () => {
+      const { azureSubscriptions } = await import("../azure.js");
+      await azureSubscriptions();
+    });
+}