@meshxdata/fops 0.1.44 → 0.1.46

package/src/plugins/bundled/fops-plugin-azure/lib/azure-aks-flux.js

@@ -0,0 +1,1180 @@
+/**
+ * azure-aks-flux.js - Flux provisioning, bootstrap, and commands
+ *
+ * Depends on: azure-aks-naming.js, azure-aks-state.js
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  OK, WARN, ERR, DIM, LABEL,
+  banner, hint, kvLine, subArgs,
+  lazyExeca, ensureAzCli, ensureAzAuth,
+  resolveGithubToken, readState,
+} from "./azure.js";
+import { AKS_DEFAULTS } from "./azure-aks-naming.js";
+import {
+  readClusterState, writeClusterState, resolveFluxConfig, requireCluster,
+} from "./azure-aks-state.js";
+
+// ── Template defaults ─────────────────────────────────────────────────────────
+
+export const TEMPLATE_DEFAULTS = {
+  templateOwner: "meshxdata",
+  templateRepo: "platform-flux-template",
+  templateBranch: "main",
+  templatePath: "clusters/_template",
+};
+
+// Kustomizations that fops manages directly — suspend them so Flux doesn't revert patches.
+export const FOPS_MANAGED_KUSTOMIZATIONS = [
+  "foundation-backend",
+  "foundation-processor",
+  "foundation-scheduler",
+  "foundation-watcher",
+  "foundation-storage-engine",
+  "istio-controlplane",
+];
+
+export const DAI_KUSTOMIZATIONS = [
+  "dai-backend",
+  "dai-trino",
+];
+
+// ── CLI helpers ───────────────────────────────────────────────────────────────
+
+export async function ensureFluxCli(execa) {
+  try {
+    await execa("flux", ["--version"], { timeout: 10000 });
+  } catch {
+    console.error(ERR("\n  Flux CLI is not installed."));
+    hint("Install:  brew install fluxcd/tap/flux");
+    hint("Or:       curl -s https://fluxcd.io/install.sh | sudo bash\n");
+    process.exit(1);
+  }
+}
+
+// ── Template submodule resolver ───────────────────────────────────────────────
+
+function resolveTemplateSubmodule() {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const fromSource = path.resolve(thisDir, "../../../../../../platform-flux-template");
+  if (fs.existsSync(path.join(fromSource, "clusters/_template"))) {
+    return fromSource;
+  }
+  return null;
+}
+
+// ── Clone or update repo ──────────────────────────────────────────────────────
+
+export async function cloneOrUpdateRepo(execa, { repo, owner, branch, githubToken, cacheKey }) {
+  const cacheDir = path.join(os.homedir(), ".fops", "repos", cacheKey);
+  const repoUrl = githubToken
+    ? `https://x-access-token:${githubToken}@github.com/${owner}/${repo}.git`
+    : `https://github.com/${owner}/${repo}.git`;
+
+  if (fs.existsSync(path.join(cacheDir, ".git"))) {
+    hint(`Updating cached ${owner}/${repo}…`);
+    await execa("git", ["fetch", "origin", branch || "main"], { cwd: cacheDir, timeout: 60000 });
+    await execa("git", ["reset", "--hard", `origin/${branch || "main"}`], { cwd: cacheDir, timeout: 30000 });
+  } else {
+    hint(`Cloning ${owner}/${repo}…`);
+    fs.mkdirSync(cacheDir, { recursive: true });
+    await execa("git", ["clone", "--depth", "1", "--branch", branch || "main", repoUrl, cacheDir], { timeout: 120000 });
+  }
+  return cacheDir;
+}
+
+// ── Template rendering ────────────────────────────────────────────────────────
+
+export function renderTemplate(templateDir, outputDir, vars) {
+  const varMap = {
+    "{{CLUSTER_NAME}}": vars.clusterName,
+    "{{OVERLAY}}": vars.overlay || `${vars.clusterName}-azure`,
+    "{{ENVIRONMENT}}": vars.environment || "demo",
+    "{{CLOUD}}": "azure",
+    "{{REGION}}": vars.region || "uaenorth",
+    "{{AZURE_KEYVAULT_URL}}": vars.keyvaultUrl || "",
+    "{{AZURE_IDENTITY_ID}}": vars.azureIdentityId || "",
+    "{{AZURE_TENANT_ID}}": vars.azureTenantId || "",
+    "{{ACR_USERNAME}}": vars.acrUsername || "",
+    "{{ACR_PASSWORD}}": vars.acrPassword || "",
+    "{{TAILSCALE_CLIENT_ID}}": vars.tailscaleClientId || "",
+    "{{TAILSCALE_CLIENT_SECRET}}": vars.tailscaleClientSecret || "",
+    "{{TAILSCALE_HOSTNAME}}": vars.tailscaleHostname || vars.clusterName,
+    "{{VNET_CIDR}}": vars.vnetCidr || "10.50.0.0/16",
+    "{{PROMETHEUS_REMOTE_WRITE_URL}}": vars.prometheusRemoteWriteUrl || "",
+    "{{DOMAIN}}": vars.domain || "",
+    "{{NAMESPACE}}": vars.namespace || "foundation",
+    "{{POSTGRES_HOST}}": vars.postgresHost || "",
+    "{{FLUX_PATH}}": vars.fluxPath || `clusters/${vars.clusterName}`,
+    "{{AUTH0_DOMAIN}}": vars.auth0Domain || "meshx.eu.auth0.com",
+  };
+
+  function applyVars(content) {
+    let out = content;
+    for (const [k, v] of Object.entries(varMap)) {
+      out = out.replaceAll(k, v);
+    }
+    return out;
+  }
+
+  function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        const content = fs.readFileSync(srcPath, "utf8");
+        fs.writeFileSync(destPath, applyVars(content));
+      }
+    }
+  }
+
+  copyDir(templateDir, outputDir);
+  return varMap;
+}
+
+// ── Recursive copy with variable substitution ─────────────────────────────────
+
+export function copyAndRenderTemplateDir(srcDir, destDir, vars) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyAndRenderTemplateDir(srcPath, destPath, vars);
+    } else if (entry.isFile()) {
+      let content = fs.readFileSync(srcPath, "utf8");
+      for (const [key, val] of Object.entries(vars)) {
+        content = content.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), val || "");
+      }
+      fs.writeFileSync(destPath, content);
+    }
+  }
+}
+
+// ── Commit cluster to Flux repo ───────────────────────────────────────────────
+
+export async function commitClusterToFlux(execa, { fluxDir, clusterName, clusterDir, overlayName, dryRun }) {
+  const targetDir = path.join(fluxDir, "clusters", clusterName);
+
+  if (fs.existsSync(targetDir)) {
+    hint(`Cluster directory exists in flux repo — updating…`);
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+
+  fs.cpSync(clusterDir, targetDir, { recursive: true });
+
+  await execa("git", ["add", `clusters/${clusterName}`], { cwd: fluxDir, timeout: 30000 });
+
+  if (overlayName) {
+    const appsDir = path.join(fluxDir, "apps");
+    if (fs.existsSync(appsDir)) {
+      await execa("git", ["add", "apps/"], { cwd: fluxDir, timeout: 30000 });
+    }
+  }
+
+  const { stdout: status } = await execa("git", ["status", "--porcelain"], { cwd: fluxDir, timeout: 10000 });
+  if (!status.trim()) {
+    hint("No changes to commit (manifests already up to date)");
+    return false;
+  }
+
+  if (dryRun) {
+    console.log(OK(`  ✓ Would commit cluster manifests (dry-run)`));
+    return false;
+  }
+
+  await execa("git", ["commit", "-m", `Add cluster ${clusterName}\n\nAuto-generated by fops azure aks up`], { cwd: fluxDir, timeout: 30000 });
+  console.log(OK(`  ✓ Committed cluster manifests`));
+
+  hint("Pushing to flux repo…");
+  await execa("git", ["push", "origin", "main"], { cwd: fluxDir, timeout: 60000 });
+  console.log(OK(`  ✓ Pushed to flux repo`));
+  return true;
+}
+
+// ── Full template-based Flux provisioning ─────────────────────────────────────
+
+export async function provisionFluxFromTemplate(execa, opts) {
+  const {
+    clusterName,
+    region,
+    domain,
+    keyvaultUrl,
+    environment,
+    azureIdentityId,
+    azureTenantId,
+    acrUsername,
+    acrPassword,
+    tailscaleClientId,
+    tailscaleClientSecret,
+    vnetCidr,
+    prometheusRemoteWriteUrl,
+    auth0Domain,
+    githubToken,
+    fluxRepo,
+    fluxOwner,
+    fluxBranch,
+    templateRepo = TEMPLATE_DEFAULTS.templateRepo,
+    templateOwner = TEMPLATE_DEFAULTS.templateOwner,
+    templateBranch = TEMPLATE_DEFAULTS.templateBranch,
+    templatePath = TEMPLATE_DEFAULTS.templatePath,
+    dryRun = false,
+    noCommit = false,
+  } = opts;
+
+  banner("Flux Template Provisioning");
+  kvLine("Cluster",  clusterName);
+  kvLine("Target",   DIM(`${fluxOwner}/${fluxRepo}`));
+
+  let templateDir;
+  const submodulePath = resolveTemplateSubmodule();
+  if (submodulePath) {
+    templateDir = submodulePath;
+    kvLine("Template", DIM(`submodule (${path.basename(submodulePath)})`));
+  } else {
+    kvLine("Template", DIM(`${templateOwner}/${templateRepo}`));
+    templateDir = await cloneOrUpdateRepo(execa, {
+      repo: templateRepo,
+      owner: templateOwner,
+      branch: templateBranch,
+      githubToken,
+      cacheKey: `${templateOwner}-${templateRepo}`,
+    });
+  }
+
+  const templateSourceDir = path.join(templateDir, templatePath);
+  if (!fs.existsSync(templateSourceDir)) {
+    console.log(WARN(`\n  ⚠ Template directory not found: ${templatePath}`));
+    hint("Falling back to legacy Flux bootstrap (no template rendering)");
+    return false;
+  }
+
+  const renderedDir = path.join(os.tmpdir(), `flux-${clusterName}-${Date.now()}`);
+  hint("Rendering template…");
+  const varsUsed = renderTemplate(templateSourceDir, renderedDir, {
+    clusterName,
+    overlay: `${clusterName}-azure`,
+    region,
+    domain,
+    keyvaultUrl,
+    environment,
+    azureIdentityId,
+    azureTenantId,
+    acrUsername,
+    acrPassword,
+    tailscaleClientId,
+    tailscaleClientSecret,
+    tailscaleHostname: clusterName,
+    vnetCidr,
+    prometheusRemoteWriteUrl,
+    auth0Domain,
+    fluxPath: `clusters/${clusterName}`,
+  });
+  console.log(OK(`  ✓ Template rendered to ${renderedDir}`));
+
+  if (noCommit) {
+    console.log(OK(`\n  ✓ Template rendered (--no-commit). Output: ${renderedDir}`));
+    return { renderedDir, varsUsed, committed: false };
+  }
+
+  const fluxDir = await cloneOrUpdateRepo(execa, {
+    repo: fluxRepo,
+    owner: fluxOwner,
+    branch: fluxBranch,
+    githubToken,
+    cacheKey: `${fluxOwner}-${fluxRepo}`,
+  });
+
+  const overlayName = `${clusterName}-azure`;
+  const overlayVars = {
+    CLUSTER_NAME: clusterName,
+    CLUSTER_DOMAIN: `${clusterName}.meshx.app`,
+    POSTGRES_HOST: `fops-${clusterName}-psql.postgres.database.azure.com`,
+    STORAGE_ACCOUNT: `fops${clusterName.replace(/-/g, "")}`,
+    NATS_PREFIX: `meshx-${clusterName}`,
+    OVERLAY_NAME: overlayName,
+    HELM_REPO_NAMESPACE: "flux-system",
+    AUTH0_DOMAIN: auth0Domain || "meshx.eu.auth0.com",
+  };
+
+  const appsDir = path.join(fluxDir, "apps", "foundation");
+  if (fs.existsSync(appsDir)) {
+    let createdCount = 0;
+    for (const app of fs.readdirSync(appsDir)) {
+      const appDir = path.join(appsDir, app);
+      if (!fs.statSync(appDir).isDirectory()) continue;
+      const templateOverlay = path.join(appDir, "overlays", "_template");
+      const clusterOverlay = path.join(appDir, "overlays", overlayName);
+
+      if (fs.existsSync(templateOverlay)) {
+        if (fs.existsSync(clusterOverlay)) {
+          fs.rmSync(clusterOverlay, { recursive: true, force: true });
+        }
+        copyAndRenderTemplateDir(templateOverlay, clusterOverlay, overlayVars);
+        createdCount++;
+      }
+    }
+    if (createdCount > 0) {
+      hint(`  Created ${createdCount} overlays: ${overlayName}`);
+    }
+  }
+
+  const committed = await commitClusterToFlux(execa, {
+    fluxDir,
+    clusterName,
+    clusterDir: renderedDir,
+    overlayName,
+    dryRun,
+  });
+
+  try { fs.rmSync(renderedDir, { recursive: true, force: true }); } catch {}
+
+  return { renderedDir, varsUsed, committed, fluxDir };
+}
+
+// ── Bootstrap Flux (Azure GitOps extension) ───────────────────────────────────
+
+export async function bootstrapFlux(execa, { clusterName, rg, sub, githubToken, repo, owner, path: fluxPath, branch }) {
+  repo = repo || AKS_DEFAULTS.fluxRepo;
+  owner = owner || AKS_DEFAULTS.fluxOwner;
+  branch = branch || AKS_DEFAULTS.fluxBranch;
+
+  if (!githubToken) {
+    console.error(ERR("\n  GitHub token required for Flux bootstrap."));
+    hint("Authenticate:  gh auth login   (writes to ~/.netrc)");
+    hint("Or:            export GITHUB_TOKEN=<token>");
+    hint("Or:            --github-token <token>\n");
+    process.exit(1);
+  }
+
+  const repoUrl = `https://github.com/${owner}/${repo}`;
+  const configName = "flux-system";
+
+  banner("Flux Bootstrap (Azure GitOps)");
+  kvLine("Repo",   DIM(`${owner}/${repo}`));
+  kvLine("Path",   DIM(fluxPath));
+  kvLine("Branch", DIM(branch));
+  kvLine("Mode",   DIM("Azure-managed extension (read-only)"));
+  hint("This takes 2–5 minutes…\n");
+
+  hint("Installing Flux extension…");
+  try {
+    await execa("az", [
+      "k8s-extension", "create",
+      "--resource-group", rg,
+      "--cluster-name", clusterName,
+      "--cluster-type", "managedClusters",
+      "--name", "flux",
+      "--extension-type", "microsoft.flux",
+      "--scope", "cluster",
+      "--output", "none",
+      ...subArgs(sub),
+    ], { timeout: 600000 });
+    console.log(OK("  ✓ Flux extension installed"));
+  } catch (err) {
+    const msg = (err.stderr || err.message || "").toString();
+    if (/rpds|No module named|ModuleNotFoundError/.test(msg)) {
+      console.error(ERR("\n  Azure k8s-extension failed (broken vendored rpds — known Azure CLI bug)."));
+      hint("Workaround (macOS Homebrew): install rpds-py into Azure CLI's Python, then remove the extension's vendored rpds:");
+      hint("  $(brew --prefix azure-cli)/libexec/bin/pip install rpds-py");
+      hint("  rm -rf ~/.azure/cliextensions/k8s-extension/rpds");
+      hint("Then re-run. See: https://github.com/Azure/azure-cli/issues/32709\n");
+      throw err;
+    }
+    throw err;
+  }
+
+  hint("Creating GitOps configuration…");
+  await execa("az", [
+    "k8s-configuration", "flux", "create",
+    "--resource-group", rg,
+    "--cluster-name", clusterName,
+    "--cluster-type", "managedClusters",
+    "--name", configName,
+    "--namespace", "flux-system",
+    "--scope", "cluster",
+    "--url", repoUrl,
+    "--branch", branch,
+    "--https-user", "x-access-token",
+    "--https-key", githubToken,
+    "--kustomization", `name=${configName}`, `path=./${fluxPath}`, "prune=true",
+    "--output", "none",
+    ...subArgs(sub),
+  ], { timeout: 300000 });
+  console.log(OK("  ✓ GitOps configuration created (read-only — no push to repo)"));
+}
+
+// ── Reconcile Flux (idempotent install/update) ────────────────────────────────
+
+export async function reconcileFlux(execa, { clusterName, rg, sub, githubToken, repo, owner, path: fluxPath, branch }) {
+  repo = repo || AKS_DEFAULTS.fluxRepo;
+  owner = owner || AKS_DEFAULTS.fluxOwner;
+  branch = branch || AKS_DEFAULTS.fluxBranch;
+  const repoUrl = `https://github.com/${owner}/${repo}`;
+  const configName = "flux-system";
+
+  const { exitCode: extExists } = await execa("az", [
+    "k8s-extension", "show",
+    "--resource-group", rg,
+    "--cluster-name", clusterName,
+    "--cluster-type", "managedClusters",
+    "--name", "flux",
+    "--output", "none",
+    ...subArgs(sub),
+  ], { reject: false, timeout: 30000 });
+
+  if (extExists !== 0) {
+    hint("Installing Flux extension…");
+    try {
+      await execa("az", [
+        "k8s-extension", "create",
+        "--resource-group", rg,
+        "--cluster-name", clusterName,
+        "--cluster-type", "managedClusters",
+        "--name", "flux",
+        "--extension-type", "microsoft.flux",
+        "--scope", "cluster",
+        "--output", "none",
+        ...subArgs(sub),
+      ], { timeout: 600000 });
+      console.log(OK("  ✓ Flux extension installed"));
+    } catch (err) {
+      const msg = (err.stderr || err.message || "").toString();
+      if (/rpds|No module named|ModuleNotFoundError/.test(msg)) {
+        console.error(ERR("\n  Azure k8s-extension failed (broken vendored rpds — known Azure CLI bug)."));
+        hint("Workaround (macOS Homebrew): install rpds-py into Azure CLI's Python, then remove the extension's vendored rpds:");
+        hint("  $(brew --prefix azure-cli)/libexec/bin/pip install rpds-py");
+        hint("  rm -rf ~/.azure/cliextensions/k8s-extension/rpds");
+        hint("Then re-run. See: https://github.com/Azure/azure-cli/issues/32709\n");
+        throw err;
+      }
+      throw err;
+    }
+  } else {
+    console.log(OK("  ✓ Flux extension already installed"));
+  }
+
+  const { exitCode: cfgExists } = await execa("az", [
+    "k8s-configuration", "flux", "show",
+    "--resource-group", rg,
+    "--cluster-name", clusterName,
+    "--cluster-type", "managedClusters",
+    "--name", configName,
+    "--output", "none",
+    ...subArgs(sub),
+  ], { reject: false, timeout: 30000 });
+
+  if (cfgExists !== 0) {
+    hint("Creating GitOps configuration…");
+    try {
+      await execa("az", [
+        "k8s-configuration", "flux", "create",
+        "--resource-group", rg,
+        "--cluster-name", clusterName,
+        "--cluster-type", "managedClusters",
+        "--name", configName,
+        "--namespace", "flux-system",
+        "--scope", "cluster",
+        "--url", repoUrl,
+        "--branch", branch,
+        "--https-user", "x-access-token",
+        "--https-key", githubToken,
+        "--kustomization", `name=${configName}`, `path=./${fluxPath}`, "prune=true",
+        "--output", "none",
+        ...subArgs(sub),
+      ], { timeout: 300000 });
+      console.log(OK("  ✓ GitOps configuration created"));
+    } catch (err) {
+      const azErr = (err.stderr || err.message || "").replace(/^.*ERROR:\s*/m, "").split("\n")[0];
+      console.log(WARN(`  ⚠ GitOps configuration failed: ${azErr}`));
+      hint("Create manually: az k8s-configuration flux create -g " + rg + " -c " + clusterName + " -t managedClusters -n " + configName + " ...");
+    }
+  } else {
+    const { stdout: cfgJson } = await execa("az", [
+      "k8s-configuration", "flux", "show",
+      "--resource-group", rg,
+      "--cluster-name", clusterName,
+      "--cluster-type", "managedClusters",
+      "--name", configName,
+      "--output", "json",
+      ...subArgs(sub),
+    ], { reject: false, timeout: 30000 });
+    let currentUrl = "";
+    let currentPath = "";
+    if (cfgJson) {
+      try {
+        const cfg = JSON.parse(cfgJson);
+        currentUrl = (cfg.gitRepository && cfg.gitRepository.url) || "";
+        const ks = cfg.kustomizations && cfg.kustomizations[configName];
+        currentPath = (ks && ks.path) || "";
+      } catch { /* ignore */ }
+    }
+    const desiredPath = fluxPath.startsWith("./") ? fluxPath : `./${fluxPath}`;
+    const urlMismatch = currentUrl && currentUrl !== repoUrl;
+    const pathMismatch = currentPath && currentPath !== desiredPath;
+    if (urlMismatch || pathMismatch) {
+      hint(`Flux path mismatch: ${currentPath} → ${desiredPath}. Recreating…`);
+      try {
+        await execa("az", [
+          "k8s-configuration", "flux", "delete",
+          "--resource-group", rg,
+          "--cluster-name", clusterName,
+          "--cluster-type", "managedClusters",
+          "--name", configName,
+          "--yes",
+          "--output", "none",
+          ...subArgs(sub),
+        ], { timeout: 300000 });
+        hint("  Deleted old configuration…");
+        await execa("az", [
+          "k8s-configuration", "flux", "create",
+          "--resource-group", rg,
+          "--cluster-name", clusterName,
+          "--cluster-type", "managedClusters",
+          "--name", configName,
+          "--namespace", "flux-system",
+          "--scope", "cluster",
+          "--url", repoUrl,
+          "--branch", branch,
+          "--https-user", "x-access-token",
+          "--https-key", githubToken,
+          "--kustomization", `name=${configName}`, `path=${desiredPath}`, "prune=true",
+          "--output", "none",
+          ...subArgs(sub),
+        ], { timeout: 300000 });
+        console.log(OK(`  ✓ GitOps configuration recreated with path ${desiredPath}`));
+      } catch (err) {
+        const azErr = (err.stderr || err.message || "").replace(/^.*ERROR:\s*/m, "").split("\n")[0];
+        console.log(WARN(`  ⚠ Flux recreate failed: ${azErr}`));
+      }
+    } else {
+      console.log(OK("  ✓ GitOps configuration already exists"));
+    }
+  }
+}
+
+// ── Reconcile Flux step (for reconciler array) ────────────────────────────────
+
+export async function reconcileFluxStep(ctx) {
+  const { execa, clusterName, rg, sub, opts } = ctx;
+  if (opts.noFlux) return;
+
+  const githubToken = resolveGithubToken(opts);
+  if (!githubToken) {
+    console.log(WARN("  ⚠ Skipping Flux — no GitHub token found."));
+    hint("Authenticate with:  gh auth login");
+    return;
+  }
+
+  const { fluxRepo, fluxOwner, fluxPath, fluxBranch } = resolveFluxConfig(clusterName, opts);
+
+  await reconcileFlux(execa, {
+    clusterName, rg, sub, githubToken,
+    repo: fluxRepo, owner: fluxOwner,
+    path: fluxPath, branch: fluxBranch,
+  });
+
+  writeClusterState(clusterName, {
+    flux: { repo: fluxRepo, owner: fluxOwner, path: fluxPath, branch: fluxBranch },
+  });
+}
+
+// ── Suspend managed Kustomizations ────────────────────────────────────────────
+
+export async function suspendManagedKustomizations(ctx) {
+  const { execa, clusterName, opts } = ctx;
+  const kubectl = (args, o = {}) =>
+    execa("kubectl", ["--context", clusterName, ...args], { timeout: 15000, reject: false, ...o });
+
+  const targets = opts?.dai
+    ? FOPS_MANAGED_KUSTOMIZATIONS
+    : [...FOPS_MANAGED_KUSTOMIZATIONS, ...DAI_KUSTOMIZATIONS];
+
+  let suspended = 0;
+  for (const name of targets) {
+    const { exitCode } = await kubectl([
+      "get", "kustomization", name, "-n", "flux-system",
+    ]);
+    if (exitCode !== 0) continue;
+
+    const { stdout: isSuspended } = await kubectl([
+      "get", "kustomization", name, "-n", "flux-system",
+      "-o", "jsonpath={.spec.suspend}",
+    ]);
+    if (isSuspended === "true") continue;
+
+    await kubectl([
+      "patch", "kustomization", name, "-n", "flux-system",
+      "--type", "merge", "-p", '{"spec":{"suspend":true}}',
+    ]);
+    suspended++;
+  }
+  if (suspended > 0) {
+    console.log(OK(`  ✓ Suspended ${suspended} Flux Kustomization(s) to prevent revert`));
+  } else {
+    console.log(OK("  ✓ Managed Kustomizations already suspended"));
+  }
+}
+
+// ── Flux prerequisites reconciler ─────────────────────────────────────────────
+
+export async function reconcileFluxPrereqs(ctx) {
+  const { execa, clusterName } = ctx;
+  const tracked = readClusterState(clusterName);
+  if (!tracked?.flux) return;
+
+  banner("Flux Prerequisites");
+
+  const kubectl = (args, opts = {}) =>
+    execa("kubectl", ["--context", clusterName, ...args], { reject: false, timeout: 60000, ...opts });
+
+  // 1. Clean up legacy acr-cache-system if present
+  try {
+    const { exitCode } = await kubectl(["get", "namespace", "acr-cache-system"]);
+    if (exitCode === 0) {
+      hint("Cleaning up legacy acr-cache-system namespace…");
+      for (const wh of ["acr-pod-webhook", "acr-helm-webhook"]) {
+        await kubectl(["delete", "mutatingwebhookconfiguration", wh, "--ignore-not-found"]);
+      }
+      await kubectl(["delete", "namespace", "acr-cache-system", "--ignore-not-found"]);
+      console.log(OK("  ✓ Legacy acr-cache-system removed"));
+    }
+  } catch { /* not present */ }
+
+  // 2. Pre-install CRDs that Flux manifests reference before their operators deploy
+  const crdBundles = [
+    {
+      name: "external-secrets",
+      check: "externalsecrets.external-secrets.io",
+      url: "https://raw.githubusercontent.com/external-secrets/external-secrets/main/deploy/crds/bundle.yaml",
+      serverSide: true,
+    },
+    {
+      name: "Istio",
+      check: "virtualservices.networking.istio.io",
+      helm: { repo: "https://istio-release.storage.googleapis.com/charts", chart: "base", release: "istio-base", namespace: "istio-system" },
+    },
+  ];
+
+  for (const bundle of crdBundles) {
+    const { exitCode } = await kubectl(["get", "crd", bundle.check], { timeout: 10000 });
+    if (exitCode === 0) {
+      console.log(OK(`  ✓ ${bundle.name} CRDs present`));
+      continue;
+    }
+
+    hint(`Installing ${bundle.name} CRDs…`);
+    try {
+      if (bundle.helm) {
+        await execa("helm", ["repo", "add", bundle.name, bundle.helm.repo, "--force-update"], { reject: false, timeout: 30000 });
+        await execa("helm", [
+          "--kube-context", clusterName,
+          "install", bundle.helm.release, `${bundle.name}/${bundle.helm.chart}`,
+          "-n", bundle.helm.namespace, "--create-namespace",
+          "--wait", "--timeout", "90s",
+        ], { timeout: 120000 });
+      } else {
+        const applyArgs = ["apply", "-f", bundle.url];
+        if (bundle.serverSide) applyArgs.push("--server-side");
+        await kubectl(applyArgs, { timeout: 120000 });
+      }
+      console.log(OK(`  ✓ ${bundle.name} CRDs installed`));
+    } catch (err) {
+      console.log(WARN(`  ⚠ ${bundle.name} CRDs failed: ${(err.message || "").split("\n")[0]}`));
+    }
+  }
+
+  // 3. Enable v1beta1 on ExternalSecret CRD if the operator disabled it
+  try {
+    const { stdout: crdJson } = await kubectl([
+      "get", "crd", "externalsecrets.external-secrets.io",
+      "-o", "jsonpath={.spec.versions[?(@.name==\"v1beta1\")].served}",
+    ], { timeout: 10000 });
+    if (crdJson === "false") {
+      hint("Enabling v1beta1 on ExternalSecret CRD…");
+      const { stdout: fullCrd } = await kubectl([
+        "get", "crd", "externalsecrets.external-secrets.io", "-o", "json",
+      ], { timeout: 10000 });
+      const crd = JSON.parse(fullCrd);
+      for (const v of crd.spec.versions) {
+        if (v.name === "v1beta1") v.served = true;
+      }
+      await execa("kubectl", [
+        "--context", clusterName, "apply", "--server-side", "-f", "-",
+      ], { input: JSON.stringify(crd), timeout: 30000, reject: false });
+
+      const { stdout: ssCrd } = await kubectl([
+        "get", "crd", "secretstores.external-secrets.io", "-o", "json",
+      ], { timeout: 10000 });
+      const ss = JSON.parse(ssCrd);
+      for (const v of ss.spec.versions) {
+        if (v.name === "v1beta1") v.served = true;
+      }
+      await execa("kubectl", [
+        "--context", clusterName, "apply", "--server-side", "-f", "-",
+      ], { input: JSON.stringify(ss), timeout: 30000, reject: false });
+
+      console.log(OK("  ✓ v1beta1 enabled on ExternalSecret CRDs"));
+    }
+  } catch { /* CRD not installed yet */ }
+
+  // 4. Trigger a full Flux reconciliation
+  try {
+    hint("Triggering Flux reconciliation…");
+    const { stdout: ksList } = await kubectl([
+      "get", "kustomization", "-n", "flux-system", "--no-headers",
+      "-o", "custom-columns=NAME:.metadata.name",
+    ]);
+    const names = ksList.trim().split("\n").map(n => n.trim()).filter(Boolean);
+    const ts = String(Date.now());
+    for (const ks of names) {
+      await kubectl([
+        "annotate", "kustomization", ks, "-n", "flux-system",
+        `reconcile.fluxcd.io/requestedAt=${ts}-${ks}`, "--overwrite",
+      ], { timeout: 10000 });
+    }
+    console.log(OK(`  ✓ Reconciliation triggered for ${names.length} kustomizations`));
+  } catch {
+    hint("Could not trigger reconciliation — Flux may not be ready yet");
+  }
+}
+
+// ── CLI module resolver helper ────────────────────────────────────────────────
+
+function resolveCliSrc(relPath) {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const fromSource = path.resolve(thisDir, "../../../..", relPath);
+  if (fs.existsSync(fromSource)) return new URL(`file://${fromSource}`).href;
+  const fopsBin = process.argv[1];
+  if (fopsBin) {
+    try {
+      const cliRoot = path.dirname(fs.realpathSync(fopsBin));
+      const fromCli = path.resolve(cliRoot, "src", relPath);
+      if (fs.existsSync(fromCli)) return new URL(`file://${fromCli}`).href;
+    } catch { /* fall through */ }
+  }
+  return "../../../../" + relPath;
+}
+
+// ── aks flux init ─────────────────────────────────────────────────────────────
+
+export async function aksFluxInit(opts = {}) {
+  const clusterName = opts.clusterName;
+  if (!clusterName) {
+    console.error(ERR("\n  Cluster name is required."));
+    hint("Usage: fops azure aks flux init <name> --flux-repo <path>\n");
+    process.exit(1);
+  }
+
+  const overlay = opts.overlay || "demo-azure";
+  const namespace = opts.namespace || "foundation";
+  const fluxRepoPath = opts.fluxRepo;
+
+  if (!fluxRepoPath) {
+    console.error(ERR("\n  --flux-repo <path> is required (path to your local flux repo clone)."));
+    hint("Example: fops azure aks flux init alessio --flux-repo ../flux\n");
+    process.exit(1);
+  }
+
+  const fluxRepo = path.resolve(fluxRepoPath);
+  if (!fs.existsSync(path.join(fluxRepo, "clusters"))) {
+    console.error(ERR(`\n  "${fluxRepo}" does not look like a flux repo (no clusters/ dir).`));
+    process.exit(1);
+  }
+
+  const clusterDir = path.join(fluxRepo, "clusters", clusterName);
+  if (fs.existsSync(clusterDir)) {
+    console.error(ERR(`\n  Cluster directory already exists: ${clusterDir}`));
+    hint("Remove it first or use a different name.\n");
+    process.exit(1);
+  }
+
+  const state = readState();
+  const projectRoot = state.azure?.projectRoot || state.projectRoot;
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  let templateRoot = projectRoot && fs.existsSync(path.join(projectRoot, "flux-templates", "cluster"))
+    ? path.join(projectRoot, "flux-templates", "cluster")
+    : path.resolve(thisDir, "../../../../foundation-flux/cluster");
+  if (!fs.existsSync(templateRoot)) {
+    console.error(ERR("\n  Template directory not found."));
+    hint(`Expected at: ${templateRoot}`);
+    hint("Create flux-templates/cluster/ in your project or install foundation-flux.\n");
+    process.exit(1);
+  }
+
+  const vars = {
+    "{{CLUSTER_NAME}}": clusterName,
+    "{{OVERLAY}}": overlay,
+    "{{NAMESPACE}}": namespace,
+    "{{FLUX_PATH}}": opts.fluxPath || `clusters/${clusterName}`,
+    "{{POSTGRES_HOST}}": opts.postgresHost || `{{POSTGRES_HOST}}`,
+    "{{ACCESS_KEY_ID}}": opts.accessKeyId || `{{ACCESS_KEY_ID}}`,
+    "{{AZURE_SP_CLIENT_ID_B64}}": opts.azureSpClientId || `{{AZURE_SP_CLIENT_ID_B64}}`,
+    "{{AZURE_SP_CLIENT_SECRET_B64}}": opts.azureSpClientSecret || `{{AZURE_SP_CLIENT_SECRET_B64}}`,
+    "{{AZURE_IDENTITY_ID}}": opts.azureIdentityId || `{{AZURE_IDENTITY_ID}}`,
+    "{{AZURE_TENANT_ID}}": opts.azureTenantId || `{{AZURE_TENANT_ID}}`,
+    "{{AZURE_KEYVAULT_URL}}": opts.azureKeyvaultUrl || `{{AZURE_KEYVAULT_URL}}`,
+  };
+
+  function applyVars(content) {
+    let out = content;
+    for (const [k, v] of Object.entries(vars)) {
+      out = out.replaceAll(k, v);
+    }
+    return out;
+  }
+
+  function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        const content = fs.readFileSync(srcPath, "utf8");
+        fs.writeFileSync(destPath, applyVars(content));
+      }
+    }
+  }
+
+  banner(`Flux Init: ${clusterName}`);
+  kvLine("Cluster",   clusterName);
+  kvLine("Overlay",   overlay);
+  kvLine("Namespace", namespace);
+  kvLine("Output",    DIM(clusterDir));
+  console.log("");
+
+  hint("Scaffolding cluster manifests…");
+  copyDir(templateRoot, clusterDir);
+  console.log(OK("  ✓ Cluster directory created"));
+
+  const remaining = Object.entries(vars)
+    .filter(([, v]) => v.startsWith("{{"))
+    .map(([k]) => k);
+
+  if (remaining.length) {
+    console.log(`\n  ${WARN("Placeholders to fill in:")}`);
+    for (const p of remaining) {
+      hint(`  ${p}`);
+    }
+  }
+
+  const sampleOverlay = path.join(fluxRepo, "apps/foundation/backend/overlays/meshx", overlay);
+  if (!fs.existsSync(sampleOverlay)) {
+    console.log(WARN(`\n  ⚠ Overlay "${overlay}" not found in apps/ — app Kustomizations will fail until it exists.`));
+    hint(`Create overlays or use an existing one: --overlay demo-azure`);
+  }
+
+  console.log("");
+  hint("Next steps:");
+  hint(`  1. Fill in remaining {{…}} placeholders in clusters/${clusterName}/`);
+  hint(`  2. Commit and push to the flux repo`);
+  hint(`  3. Bootstrap Flux: fops azure aks flux bootstrap ${clusterName}`);
+  console.log("");
+}
+
+// ── aks flux bootstrap ────────────────────────────────────────────────────────
+
+export async function aksFluxBootstrap(opts = {}) {
+  const execa = await lazyExeca();
+  const sub = opts.profile;
+  await ensureAzCli(execa);
+  await ensureAzAuth(execa, { subscription: sub });
+  const cl = requireCluster(opts.clusterName);
+
+  const { getCredentials } = await import("./azure-aks-core.js");
+  await getCredentials(execa, {
+    clusterName: cl.clusterName,
+    rg: cl.resourceGroup,
+    sub,
+  });
+
+  const githubToken = resolveGithubToken(opts);
+  if (!githubToken) {
+    console.error(ERR("\n  GitHub token required for Flux bootstrap."));
+    hint("Authenticate:  gh auth login   or set GITHUB_TOKEN\n");
+    process.exit(1);
+  }
+
+  const fluxOpts = {
+    fluxRepo: opts.repo,
+    fluxOwner: opts.owner,
+    fluxPath: opts.path,
+    fluxBranch: opts.branch,
+  };
+  const { fluxRepo, fluxOwner, fluxPath, fluxBranch } = resolveFluxConfig(cl.clusterName, fluxOpts);
+
+  const { ensureGhcrPullSecret } = await import("./azure-aks-core.js");
+  await ensureGhcrPullSecret(execa, { clusterName: cl.clusterName, githubToken });
+
+  await reconcileFlux(execa, {
+    clusterName: cl.clusterName,
+    rg: cl.resourceGroup,
+    sub,
+    githubToken,
+    repo: fluxRepo,
+    owner: fluxOwner,
+    path: fluxPath,
+    branch: fluxBranch,
+  });
+
+  writeClusterState(cl.clusterName, {
+    flux: { repo: fluxRepo, owner: fluxOwner, path: fluxPath, branch: fluxBranch },
+  });
+  console.log(OK(`  ✓ Flux now using ${fluxOwner}/${fluxRepo}\n`));
+}
+
+// ── aks flux status ───────────────────────────────────────────────────────────
+
+export async function aksFluxStatus(opts = {}) {
+  const execa = await lazyExeca();
+  await ensureFluxCli(execa);
+  const cl = requireCluster(opts.clusterName);
+
+  banner(`Flux Status: ${cl.clusterName}`);
+
+  const commands = [
+    { label: "Sources",         args: ["get", "sources", "all"] },
+    { label: "Kustomizations",  args: ["get", "kustomizations"] },
+    { label: "Helm Releases",   args: ["get", "helmreleases", "--all-namespaces"] },
+  ];
+
+  for (const { label, args } of commands) {
+    console.log(`\n  ${LABEL(label)}`);
+    const { stdout } = await execa("flux", [
+      ...args, "--context", cl.clusterName,
+    ], { timeout: 30000, reject: false });
+    if (stdout?.trim()) {
+      for (const line of stdout.trim().split("\n")) {
+        console.log(`    ${DIM(line)}`);
+      }
+    } else {
+      hint(`  No ${label.toLowerCase()} found.`);
+    }
+  }
+
+  console.log("");
+}
+
+// ── aks flux reconcile ────────────────────────────────────────────────────────
+
+export async function aksFluxReconcile(opts = {}) {
+  const execa = await lazyExeca();
+  await ensureFluxCli(execa);
+  const cl = requireCluster(opts.clusterName);
+
+  banner(`Flux Reconcile: ${cl.clusterName}`);
+
+  const source = opts.source || "flux-system";
+  hint(`Triggering reconcile for source "${source}"…\n`);
+
+  await execa("flux", [
+    "reconcile", "source", "git", source,
+    "--context", cl.clusterName,
+  ], { timeout: 60000, stdio: "inherit" });
+
+  const ksNames = ["flux-system-flux-system", "flux-system"];
+  let reconciled = false;
+  for (const ks of ksNames) {
+    const { exitCode } = await execa("flux", [
+      "reconcile", "kustomization", ks,
+      "--context", cl.clusterName,
+    ], { timeout: 60000, stdio: "inherit", reject: false });
+    if (exitCode === 0) { reconciled = true; break; }
+  }
+
+  if (reconciled) {
+    console.log(OK("\n  ✓ Reconciliation triggered.\n"));
+  } else {
+    console.error(ERR("\n  ✗ Could not reconcile kustomization. Check: kubectl --context " + cl.clusterName + " get kustomizations -n flux-system\n"));
+  }
+}
+
+// ── aks data bootstrap ────────────────────────────────────────────────────────
+
+function findBootstrapRepoRoot() {
+  const scriptPath = "scripts/bootstrap_foundation.py";
+  const envRoot = process.env.FOUNDATION_ROOT;
+  if (envRoot && fs.existsSync(path.join(envRoot, scriptPath))) return path.resolve(envRoot);
+  try {
+    const fopsPath = path.join(os.homedir(), ".fops.json");
+    const raw = JSON.parse(fs.readFileSync(fopsPath, "utf8"));
+    const root = raw?.projectRoot;
+    if (root && fs.existsSync(path.join(root, scriptPath))) return path.resolve(root);
+  } catch {}
+  let dir = path.resolve(process.cwd());
+  for (;;) {
+    if (fs.existsSync(path.join(dir, scriptPath))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+async function discoverFoundationApiUrlFromCluster(execa, clusterName) {
+  try {
+    const { stdout } = await execa("kubectl", [
+      "get", "ingress", "-A",
+      "-o", "jsonpath={.items[*].spec.rules[*].host}",
+      "--context", clusterName,
+    ], { timeout: 15000 });
+    const first = (stdout || "").trim().split(/\s+/).filter(Boolean)[0];
+    if (first) return `https://${first}/api`;
+  } catch {}
+  return null;
+}
+
+export async function aksDataBootstrap(opts = {}) {
+  const execa = await lazyExeca();
+  await ensureAzCli(execa);
+  await ensureAzAuth(execa, { subscription: opts.profile });
+  const cl = requireCluster(opts.clusterName);
+
+  const { getCredentials } = await import("./azure-aks-core.js");
+  await getCredentials(execa, {
+    clusterName: cl.clusterName,
+    rg: cl.resourceGroup,
+    sub: opts.profile,
+  });
+
+  let apiUrl = opts.apiUrl?.trim() || cl.foundationApiUrl?.trim();
+  if (!apiUrl) {
+    apiUrl = await discoverFoundationApiUrlFromCluster(execa, cl.clusterName);
+    if (apiUrl) {
+      hint(`Using API URL from cluster ingress: ${apiUrl}`);
+      writeClusterState(cl.clusterName, { foundationApiUrl: apiUrl });
+    }
+  }
+  if (!apiUrl) {
+    console.error(ERR("\n  Foundation backend API URL is required."));
+    hint("Pass the backend API base URL (e.g. https://foundation.example.com/api):");
+    hint("  fops azure aks bootstrap " + cl.clusterName + " --api-url https://your-foundation-host/api\n");
+    process.exit(1);
+  }
+  const normalized = apiUrl.replace(/\/+$/, "");
+  if (!normalized.endsWith("/api")) {
+    console.log(WARN("  API URL should usually end with /api (e.g. https://host/api). Using as-is."));
+  }
+
+  const root = findBootstrapRepoRoot();
+  if (!root) {
+    console.error(ERR("\n  Could not find foundation-compose root (scripts/bootstrap_foundation.py)."));
+    hint("Run from the foundation-compose directory, or set FOUNDATION_ROOT.\n");
+    process.exit(1);
+  }
+
+  const { loadEnvFromFile } = await import("./azure-helpers.js");
+  const projectEnv = loadEnvFromFile(path.join(root, ".env"));
+  let bootstrapEnv = {
+    ...process.env,
+    ...projectEnv,
+    PYTHONUNBUFFERED: "1",
+    API_URL: normalized,
+  };
+
+  // CLI --bearer-token takes precedence
+  if (opts.bearerToken?.trim()) {
+    bootstrapEnv.BEARER_TOKEN = opts.bearerToken.trim();
+  }
+
+  let hasCreds = !!(bootstrapEnv.BEARER_TOKEN?.trim()
+    || (bootstrapEnv.QA_USERNAME?.trim() && bootstrapEnv.QA_PASSWORD != null));
+  if (!hasCreds) {
+    try {
+      const fopsPath = path.join(os.homedir(), ".fops.json");
+      const raw = JSON.parse(fs.readFileSync(fopsPath, "utf8"));
+      const cfg = raw?.plugins?.entries?.["fops-plugin-foundation"]?.config || {};
+      if (cfg.bearerToken?.trim()) {
+        bootstrapEnv.BEARER_TOKEN = cfg.bearerToken.trim();
+        hasCreds = true;
+      } else if (cfg.user?.trim() && cfg.password) {
+        bootstrapEnv.QA_USERNAME = cfg.user.trim();
+        bootstrapEnv.QA_PASSWORD = cfg.password;
+        hasCreds = true;
+      }
+    } catch {}
+  }
+  if (!hasCreds && !opts.yes) {
+    console.log(WARN("  No Foundation credentials in env or ~/.fops.json."));
+    const { getInquirer } = await import(resolveCliSrc("lazy.js"));
+    const inquirer = await getInquirer();
+    const { authMethod } = await inquirer.prompt([{
+      type: "list",
+      name: "authMethod",
+      message: "Authentication method:",
+      choices: [
+        { name: "Username / password", value: "password" },
+        { name: "Bearer token (JWT)", value: "jwt" },
+      ],
+    }]);
+    if (authMethod === "jwt") {
+      const { token } = await inquirer.prompt([{ type: "input", name: "token", message: "Bearer token:", validate: (v) => v?.trim() ? true : "Token required" }]);
+      bootstrapEnv.BEARER_TOKEN = token.trim();
+    } else {
+      const { user } = await inquirer.prompt([{ type: "input", name: "user", message: "Username (email):", validate: (v) => v?.trim() ? true : "Username required" }]);
+      const { password } = await inquirer.prompt([{ type: "password", name: "password", message: "Password:", mask: "*", validate: (v) => v ? true : "Password required" }]);
+      bootstrapEnv.QA_USERNAME = user.trim();
+      bootstrapEnv.QA_PASSWORD = password;
+    }
+    hasCreds = true;
+  }
+  if (!hasCreds) {
+    console.error(ERR("  Set BEARER_TOKEN or QA_USERNAME+QA_PASSWORD (env or ~/.fops.json), or run without --yes.\n"));
+    process.exit(1);
+  }
+
+  banner("Bootstrap demo data (AKS)");
+  kvLine("Cluster", cl.clusterName);
+  kvLine("API URL", normalized);
+  hint("Same as fops bootstrap — creates demo data mesh via backend API.\n");
+
+  const scriptsDir = path.join(root, "scripts");
+  const venvPython = path.join(scriptsDir, ".venv", "bin", "python");
+  const scriptPath = path.join(scriptsDir, "bootstrap_foundation.py");
+  if (!fs.existsSync(venvPython)) {
+    hint("Creating scripts/.venv…");
+    await execa("python3", ["-m", "venv", path.join(scriptsDir, ".venv")], { cwd: root, timeout: 30000 });
+    const pip = path.join(scriptsDir, ".venv", "bin", "pip");
+    if (!fs.existsSync(pip)) {
+      hint("Installing pip into venv…");
+      await execa("sh", ["-c", `curl -sS https://bootstrap.pypa.io/get-pip.py | ${venvPython}`], { cwd: root, timeout: 60000 });
+    }
+    const reqPath = path.join(scriptsDir, "requirements.txt");
+    if (fs.existsSync(reqPath)) {
+      await execa(venvPython, ["-m", "pip", "install", "--quiet", "-r", reqPath], { cwd: root, timeout: 120000 });
+    }
+  }
+
+  let captured = "";
+  const proc = execa(venvPython, ["-u", scriptPath], {
+    cwd: root,
+    timeout: 600_000,
+    env: bootstrapEnv,
+    reject: false,
+  });
+  proc.stdout?.on("data", (chunk) => { const s = chunk.toString(); captured += s; process.stdout.write(s); });
+  proc.stderr?.on("data", (chunk) => { const s = chunk.toString(); captured += s; process.stderr.write(s); });
+  const result = await proc;
+
+  if (result.exitCode === 0) {
+    console.log(OK("\n  ✓ Bootstrap complete! Demo data mesh created on the cluster backend."));
+    writeClusterState(cl.clusterName, { foundationApiUrl: normalized });
+    return;
+  }
+  if ((captured || "").includes("401") || (captured || "").includes("Insufficient permissions")) {
+    hint("\n  If the user needs Foundation Admin, grant it in the UI or via your IdP, then retry.");
+  }
+  const code = result.exitCode === 255 || result.exitCode === -1 ? 1 : result.exitCode;
+  console.error(ERR(`\n  Bootstrap failed (exit code ${code}).`));
+  hint("Ensure the AKS backend is up and reachable at " + normalized);
+  process.exit(1);
+}