@aifabrix/builder 2.56.0 → 2.57.0

package/lib/cli/setup-environment.js

@@ -7,39 +7,95 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { isWorkspaceMode, isLegacyMarketplaceMode } = require('../deployment/installation/stage-input');
 
 /**
- * Sets up environment deployment commands
- * @param {Command} program - Commander program instance
+ * Adds installation workspace and deprecated explicit Marketplace options.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
  */
-function setupEnvironmentCommands(program) {
-  const deployEnvHandler = async(envKey, options) => {
-    try {
+function addMarketplaceOptions(command) {
+  return command
+    .option('--stage <stage>', 'Installation workspace stage: register, infra, dev, tst or pro (<env> is then the resource group)')
+    .option('--vendor <vendor>', 'Installation vendor: AZURE (default) or DOCKER (register only)')
+    .option('--allow-my-ip', 'Allow the caller public IPv4 /32 to reach PostgreSQL, Key Vault and Storage (infra only; default off)')
+    .option('--license-edition <edition>', 'License requested at activation: COMMUNITY, STANDARD, ENTERPRISE or a Marketplace subscription ID (infra only; saved in the workspace)')
+    .option('--miso-api-key-env <name>', 'Environment variable holding a temporary Miso API key (dev, tst, pro)')
+    .option('--controller-url <url>', 'Controller URL override for dev, tst or pro (deprecated platform stage also uses it)')
+    .option('--marketplace-json <file>', 'Deprecated explicit mode: ARM Marketplace infrastructure template')
+    .option('--parameters <file>', 'Deprecated explicit mode: secure ARM deploymentParameters JSON file')
+    .option('--subscription <id>', 'Deprecated explicit mode: Azure subscription ID')
+    .option('--resource-group <name>', 'Deprecated explicit mode: new isolated Azure resource group')
+    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key')
+    .option('--location <region>', 'Deprecated explicit mode: Azure region when not set in the parameter file');
+}
+
+async function runLegacyMarketplace(envKey, options) {
+  process.stderr.write(`${formatWarningLine('Explicit Marketplace flags are deprecated; use af env deploy <resource-group> --stage infra')}\n`);
+  const installer = require('../deployment/marketplace-environment');
+  const result = await installer.deployMarketplaceEnvironment(envKey, options);
+  if (result.platformComplete) {
+    process.stdout.write(`Platform ready: ${result.publicControllerUrl}\n`);
+  } else {
+    process.stdout.write(`Infrastructure deployed: ${result.outputs.webAppUrl} (deployment ${result.deploymentId})\n`);
+    process.stdout.write(`Resume after controller login and wizard activation: af env deploy ${envKey} --install-id ${result.installId} --controller-url https://<ready-public-host>/miso --stage platform\n`);
+  }
+}
+
+async function runInstallationStage(resourceGroup, options) {
+  const { deployInstallationStage } = require('../deployment/installation');
+  const { formatStageResult } = require('../deployment/installation/stage-output');
+  const result = await deployInstallationStage(resourceGroup, options);
+  process.stdout.write(formatStageResult(result, resourceGroup));
+}
+
+async function deployEnvHandler(envKey, options) {
+  try {
+    if (isWorkspaceMode(options)) {
+      await runInstallationStage(envKey, options);
+    } else if (isLegacyMarketplaceMode(options)) {
+      await runLegacyMarketplace(envKey, options);
+    } else {
       const environmentDeploy = require('../deployment/environment');
       await environmentDeploy.deployEnvironment(envKey, options);
-    } catch (error) {
-      handleCommandError(error, 'env deploy');
-      process.exit(1);
     }
-  };
+  } catch (error) {
+    handleCommandError(error, 'env deploy');
+    process.exit(1);
+  }
+}
 
-  const deployExamples = `
+const DEPLOY_EXAMPLES = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy tst
   $ aifabrix env deploy pro --preset m
-  $ aifabrix env deploy dev --preset xl
   $ aifabrix env deploy dev --config ./env-config.json
   $ aifabrix env deploy dev --no-poll
 
-Prerequisites: aifabrix login (device token; controller permission controller:deploy).
+Installation workspace (<env> is the resource group; files under infrastructure/<resource-group>/):
+  $ af env deploy <resource-group> --stage infra
+  $ af env deploy <resource-group> --stage infra --allow-my-ip
+  $ af env deploy <resource-group> --stage infra --license-edition ENTERPRISE
+  $ af env deploy <resource-group> --stage dev
+  $ af env deploy <resource-group> --stage pro --preset m
+  $ af env deploy <resource-group> --stage register --vendor DOCKER
+
+Vendor/stage matrix:
+  AZURE   infra, dev, tst, pro   (Mori bootstrap runs inside the Marketplace template)
+  DOCKER  register only          (deploy with aifabrix setup)
+
+Prerequisites: aifabrix login (controller permission controller:deploy); infra also needs az login.
 Environment keys: miso, dev, tst, pro. Default size preset: s (use --preset s|m|l|xl).
+Tenant activation after infra is a manual step in the Miso web application.
 Run this before aifabrix deploy <app> — the environment must exist first.`;
 
-  const ENV_GROUP_HELP_AFTER = `
+const ENV_GROUP_HELP_AFTER = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy dev --preset m
+  $ af env deploy <resource-group> --stage infra
   $ aifabrix env deploy dev --help
 
 Typical workflow:
@@ -51,21 +107,22 @@ Subcommands:
   deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
 `;
 
+function setupEnvironmentCommands(program) {
   const env = program
     .command('env')
     .description('Miso Controller environments (primary: env deploy <env>)')
     .addHelpText('after', ENV_GROUP_HELP_AFTER);
 
-  env
+  addMarketplaceOptions(env
     .command('deploy <env>')
-    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
+    .description('Deploy environment infrastructure in Miso Controller, or an installation workspace stage with --stage')
     .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
-    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
+    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s, or the workspace file value)')
     .option('--skip-validation', 'Skip environment validation')
     .option('--poll', 'Poll for deployment status', true)
-    .option('--no-poll', 'Do not poll for status')
-    .addHelpText('after', deployExamples)
+    .option('--no-poll', 'Do not poll for status'))
+    .addHelpText('after', DEPLOY_EXAMPLES)
     .action(deployEnvHandler);
 }
 
-module.exports = { setupEnvironmentCommands };
+module.exports = { setupEnvironmentCommands, deployEnvHandler, addMarketplaceOptions };

package/lib/commands/agent-kit-help.js

@@ -21,9 +21,10 @@ Examples:
   $ aifabrix agent-kit install --host all --approve-all claude --yes
   $ aifabrix agent-kit update --host all --approve-all --yes
   $ aifabrix agent-kit remote create --org my-org --yes
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start claude
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit kill aifabrix-docs
   $ aifabrix agent-kit status
   $ aifabrix agent-kit validate
 `;
@@ -117,23 +118,37 @@ Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 const START_HELP = `
 Does not install Agent Kit skills. Starts claude or codex in tmux in this git
 workspace so closing the terminal does not kill the session. Detach: Ctrl-b then
-d. --approve-all writes that app's local permission config only. --name is the
-tmux session (default: last folder, e.g. aifabrix-docs). Claude also gets
---name and --remote-control hostname-user-folder, e.g.
-builder01-dev03-aifabrix-docs. Claude --tmux is for worktrees, not this wrapper.
-That is not Claude --cloud (a separate cloud VM). Codex has no phone/web attach.
+d. The defaults enable that app's Remote Control and workspace auto-approval.
+--name is the tmux session (default: last git-root folder, e.g. aifabrix-docs).
+Claude gets --name and hostname-user-folder Remote Control. Codex uses its native
+remote-control daemon. Use --no-remote-control and/or --skip-approve-all to opt
+out. Claude --tmux is for worktrees, not this wrapper.
 
 Examples:
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-miso --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --remote-control --detach
   $ aifabrix agent-kit start claude
-  $ aifabrix agent-kit start claude --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit start claude --name aifabrix-miso
+  $ aifabrix agent-kit start codex --no-remote-control --skip-approve-all
+  $ aifabrix agent-kit start claude --detach
   $ aifabrix agent-kit start claude --dry-run --json
 `;
 
+const LIST_HELP = `
+Lists every active tmux session visible to the current Unix user.
+
+Examples:
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit list --json
+`;
+
+const KILL_HELP = `
+Stops exactly one tmux session. Use agent-kit list to find its name.
+
+Examples:
+  $ aifabrix agent-kit kill aifabrix-miso
+  $ aifabrix agent-kit kill aifabrix-miso --json
+`;
+
 module.exports = {
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP,
@@ -145,5 +160,7 @@ module.exports = {
   INIT_HELP,
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
-  START_HELP
+  START_HELP,
+  LIST_HELP,
+  KILL_HELP
 };

package/lib/commands/agent-kit.js

@@ -1,15 +1,18 @@
-/**
- * `aifabrix agent-kit` command group.
- * @fileoverview Install, init, status, update, validate, remote create, start
- */
+/** `aifabrix agent-kit` command group. */
 
 'use strict';
 
 const logger = require('../utils/logger');
 const { handleCommandError } = require('../utils/cli-utils');
-const { formatSuccessLine, formatBlockingError, formatWarningLine } = require('../utils/cli-layout-chalk');
+const {
+  formatSuccessLine,
+  formatBlockingError,
+  formatWarningLine
+} = require('../utils/cli-layout-chalk');
 const { runInstall, runUpdate } = require('../agent-kit/run');
 const { runStart } = require('../agent-kit/start');
+const { runList, runKill } = require('../agent-kit/tmux-sessions');
+const { formatSessionList, formatMissingKillName } = require('../agent-kit/session-report');
 const path = require('path');
 const { runInit, runRemoteCreate } = require('../agent-kit/init');
 const { enrichInitHostOptions, enrichInitRemoteOptions, enrichRemoteOptions, enrichApproveAllOptions } = require('../agent-kit/remote-prompts');
@@ -30,6 +33,8 @@ const {
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
   START_HELP,
+  LIST_HELP,
+  KILL_HELP,
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP
 } = require('./agent-kit-help');
@@ -110,6 +115,8 @@ function emitStartReport(json, asJson) {
   logger.log(`Session    ${json.session}`);
   if (json.remoteControlName) {
     logger.log(`Remote     ${json.remoteControlName}`);
+  } else if (json.remoteControl) {
+    logger.log('Remote     Codex Remote Control');
   }
   logger.log(`Path       ${json.path}`);
   logger.log(`Launch     ${json.launch.join(' ')}`);
@@ -124,6 +131,32 @@ function emitStartReport(json, asJson) {
   logger.log(formatSuccessLine(json.dryRun ? 'Dry-run complete' : 'Ready'));
 }
 
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitListReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(formatSessionList(json));
+}
+
+/**
+ * @param {object} json
+ * @param {boolean} asJson
+ * @returns {void}
+ */
+function emitKillReport(json, asJson) {
+  if (asJson) {
+    logger.log(JSON.stringify(json, null, 2));
+    return;
+  }
+  logger.log(formatSuccessLine(`Stopped tmux session ${json.session}`));
+}
+
 /**
  * @param {Function} runner
  * @param {object} options
@@ -159,6 +192,8 @@ function setupAgentKitCommands(program) {
   addValidateCommand(group);
   addRemoteCommand(group);
   addStartCommand(group);
+  addListCommand(group);
+  addKillCommand(group);
 }
 
 /**
@@ -387,8 +422,8 @@ async function runValidateLeaf(options) {
 function addStartCommand(group) {
   group
     .command('start <app>')
-    .description('Start Claude Code or Codex in tmux (does not install skills)')
-    .option('--approve-all', 'Write auto-approve config for this app only')
+    .description('Start Claude Code or Codex with Remote Control in named tmux')
+    .option('--approve-all', 'Write auto-approve config (default for start)')
     .option('--skip-approve-all', 'Do not write auto-approve configs')
     .option('--yes', 'Same as --approve-all')
     .option('--detach', 'Create the tmux session in the background (no attach)')
@@ -398,8 +433,10 @@ function addStartCommand(group) {
     )
     .option(
       '--remote-control',
-      'Claude Code only: same session on this PC, claude.ai/code, and the Claude mobile app'
+      'Enable native Remote Control for Claude or Codex (default)',
+      true
     )
+    .option('--no-remote-control', 'Start a local tmux-only session')
     .option('--dry-run', 'Print the launch command without starting it')
     .option('--json', 'Machine-readable output')
     .addHelpText('after', START_HELP)
@@ -414,4 +451,49 @@ function addStartCommand(group) {
     });
 }
 
+/**
+ * @param {import('commander').Command} group
+ */
+function addListCommand(group) {
+  group
+    .command('list')
+    .description('List active tmux sessions for the current user')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', LIST_HELP)
+    .action(async(options) => {
+      try {
+        emitListReport(runList(options), Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit list');
+        process.exitCode = 1;
+      }
+    });
+}
+
+/**
+ * @param {import('commander').Command} group
+ */
+function addKillCommand(group) {
+  group
+    .command('kill [name]')
+    .description('Stop one tmux session by exact name')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', KILL_HELP)
+    .action(async(name, options) => {
+      if (!name) {
+        const report = formatMissingKillName(Boolean(options.json));
+        logger.error(report.stderr);
+        if (report.stdout) logger.log(report.stdout);
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        emitKillReport(runKill({ ...options, name }), Boolean(options.json));
+      } catch (error) {
+        handleCommandError(error, 'agent-kit kill');
+        process.exitCode = 1;
+      }
+    });
+}
+
 module.exports = { setupAgentKitCommands };

package/lib/deployment/installation/azure-infra-stage.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE `--stage infra`: validates the workspace, resolves ACR and secrets, deploys
+ * the workspace Marketplace template snapshot, verifies managed-identity image pull and that both
+ * applications started, and records outputs. Mori registration and tenant activation stay with Miso.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+const os = require('os');
+const path = require('path');
+const marketplace = require('../marketplace-environment');
+const { normalizePreset } = require('../environment-config');
+const { normalizeLicenseEdition, ONBOARDING_MODES } = require('./infra-catalog');
+const { materializeWorkspace, saveInfra } = require('./workspace');
+const { missingRequiredFields } = require('./infra-manifest');
+const { buildArmParameters, applyAllowMyIp } = require('./infra-projection');
+const { materializeWorkspaceSecrets } = require('./workspace-secrets');
+const { mergeWorkspaceEnv } = require('./workspace-env');
+const { resolvePublicIpv4 } = require('./public-ip');
+const preflight = require('./azure-preflight');
+const readiness = require('./azure-readiness');
+
+const INFRA_SECRETS = Object.freeze(['ADMIN_PASSWORD', 'ENCRYPTION_KEY', 'MORI_CALLBACK_API_KEY']);
+
+function missingInputError(file, fields) {
+  const error = new Error(
+    `Installation workspace needs input before infra can run. Set these fields in ${file}, then rerun:\n  - ${fields.join('\n  - ')}`
+  );
+  error.code = 'WORKSPACE_INPUT_REQUIRED';
+  return error;
+}
+
+function applyLicenseOptions(doc, input) {
+  const license = doc.parameters.licenseEdition;
+  if (input.licenseEdition !== undefined) {
+    doc.parameters.licenseEdition = { ...license, value: normalizeLicenseEdition(input.licenseEdition), source: 'cli' };
+  } else {
+    doc.parameters.licenseEdition = { ...license, value: normalizeLicenseEdition(license.value) };
+  }
+  if (!ONBOARDING_MODES.includes(doc.parameters.onboardingMode.value)) {
+    throw new Error(`parameters.onboardingMode.value must be one of ${ONBOARDING_MODES.join(', ')}`);
+  }
+}
+
+async function applyAccessOptions(doc, input, deps) {
+  if (input.preset !== undefined) {
+    doc.preset = { ...doc.preset, value: normalizePreset(input.preset), source: 'cli' };
+  }
+  applyLicenseOptions(doc, input);
+  const enabled = input.allowMyIp || doc.allowMyIp.value === true;
+  if (!enabled) {
+    applyAllowMyIp(doc, { enabled: false });
+    return;
+  }
+  const access = await (deps.resolvePublicIpv4 || resolvePublicIpv4)();
+  applyAllowMyIp(doc, { enabled: true, ...access });
+}
+
+function withTemporaryParameters(document, action) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'aifabrix-arm-'));
+  const file = path.join(dir, 'parameters.json');
+  try {
+    fs.chmodSync(dir, 0o700);
+    fs.writeFileSync(file, JSON.stringify(document), { mode: 0o600 });
+    return action(file);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function recordDeployment(doc, record, now) {
+  doc.deployment = {
+    ...doc.deployment,
+    status: { ...doc.deployment.status, value: 'succeeded' },
+    name: record.deploymentName,
+    id: record.deploymentId,
+    correlationId: record.correlationId || null,
+    inputHash: record.inputHash,
+    completedAt: record.recordedAt || now().toISOString()
+  };
+  for (const name of Object.keys(doc.outputs)) {
+    doc.outputs[name].value = record.outputs[name] ?? null;
+  }
+}
+
+function deployTemplate(workspace, doc, context) {
+  const { document, inputHash } = buildArmParameters(doc, context);
+  return withTemporaryParameters(document, parametersFile => marketplace.deployInfra({
+    installId: doc.installId.value,
+    envKey: null,
+    subscription: doc.subscriptionId.value,
+    resourceGroup: doc.resourceGroup.value,
+    location: doc.parameters.location.value,
+    template: workspace.paths.template,
+    parameters: parametersFile,
+    templateHash: context.templateHash,
+    inputHash
+  }, context.az));
+}
+
+async function verifyAndRecordReadiness(workspace, doc, deps) {
+  readiness.verifyRuntimeImagePull(doc, deps.az);
+  await readiness.waitForApplications(doc, deps.probe || marketplace.probeHttps);
+  const controllerUrl = `${String(doc.outputs.webAppUrl.value).replace(/\/+$/, '')}/miso`;
+  doc.controllerUrl = { ...doc.controllerUrl, value: controllerUrl };
+  doc.tenantActivation.url = { ...doc.tenantActivation.url, value: controllerUrl };
+  saveInfra(workspace, doc);
+  mergeWorkspaceEnv(workspace.paths.env, { CONTROLLER_URL: controllerUrl }, { root: workspace.root, replaceable: ['CONTROLLER_URL'] });
+  return controllerUrl;
+}
+
+async function prepareInfra(workspace, input, deps, az) {
+  const { doc, templateHash } = materializeWorkspace(workspace, input, deps);
+  const missing = missingRequiredFields(doc);
+  if (missing.length > 0) throw missingInputError(workspace.paths.infra, missing);
+  preflight.assertActiveAccount(doc, az);
+  const acr = preflight.resolveAcr(doc, az);
+  preflight.assertDeploymentAuthority(doc, acr, az);
+  doc.parameters.acrLoginServer.value = acr.loginServer;
+  doc.parameters.acrResourceId.value = acr.id;
+  await applyAccessOptions(doc, input, deps);
+  saveInfra(workspace, doc);
+  return { doc, templateHash, acr };
+}
+
+function deployWithStatus(workspace, doc, context) {
+  doc.deployment.status = { ...doc.deployment.status, value: 'running' };
+  saveInfra(workspace, doc);
+  try {
+    return deployTemplate(workspace, doc, context);
+  } catch (error) {
+    doc.deployment.status = { ...doc.deployment.status, value: 'failed' };
+    saveInfra(workspace, doc);
+    throw error;
+  }
+}
+
+/**
+ * Runs the AZURE infra stage.
+ * @param {Object} workspace - Opened workspace
+ * @param {Object} input - Validated stage input
+ * @param {Object} [deps] - Injected dependencies (az, probe, resolvePublicIpv4, secretsApi, now, templatePath)
+ * @returns {Promise<{ doc: Object, controllerUrl: string, activationUrl: string }>}
+ */
+async function runAzureInfraStage(workspace, input, deps = {}) {
+  const context = { az: deps.az || marketplace.runAz, now: deps.now || (() => new Date()), probe: deps.probe };
+  const { doc, templateHash, acr } = await prepareInfra(workspace, input, deps, context.az);
+  const env = await materializeWorkspaceSecrets({
+    vendor: 'AZURE', envPath: workspace.paths.env, root: workspace.root, names: INFRA_SECRETS, secretsApi: deps.secretsApi
+  });
+  const record = deployWithStatus(workspace, doc, { env, acr, templateHash, az: context.az });
+  recordDeployment(doc, record, context.now);
+  saveInfra(workspace, doc);
+  const controllerUrl = await verifyAndRecordReadiness(workspace, doc, context);
+  return { doc, controllerUrl, activationUrl: doc.tenantActivation.url.value };
+}
+
+module.exports = { runAzureInfraStage, INFRA_SECRETS };

package/lib/deployment/installation/azure-preflight.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * @fileoverview AZURE infra preflight before any Azure mutation: active account equals the
+ * workspace subscription/tenant, `acrName` resolves inside that subscription, and the caller can
+ * create deployments, role assignments and the registry AcrPull grant. Uses only the operator's Azure CLI session; no tokens
+ * are stored.
+ */
+
+const ROLE_ASSIGNMENT_WRITE = 'Microsoft.Authorization/roleAssignments/write';
+const DEPLOYMENT_WRITE = 'Microsoft.Resources/deployments/write';
+const PERMISSIONS_API = '2022-04-01';
+
+function parseJson(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    throw new Error(`Azure CLI returned an unreadable ${label} response`);
+  }
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @param {Function} az - Azure CLI runner
+ * @throws {Error} When the active account differs from the workspace target
+ */
+function assertActiveAccount(doc, az) {
+  const account = parseJson(az(['account', 'show', '--output', 'json']), 'account');
+  const expectedSub = String(doc.subscriptionId.value).toLowerCase();
+  const expectedTenant = String(doc.tenantId.value).toLowerCase();
+  if (String(account.id).toLowerCase() !== expectedSub || String(account.tenantId).toLowerCase() !== expectedTenant) {
+    throw new Error(
+      `Active Azure account (subscription ${account.id}, tenant ${account.tenantId}) does not match the workspace ` +
+      `(subscription ${doc.subscriptionId.value}, tenant ${doc.tenantId.value}). ` +
+      `Run "az login --tenant ${doc.tenantId.value}" and "az account set --subscription ${doc.subscriptionId.value}".`
+    );
+  }
+}
+
+/**
+ * Resolves `acrName` to its resource ID and login server within the workspace subscription.
+ * @param {Object} doc - Infra manifest
+ * @param {Function} az - Azure CLI runner
+ * @returns {{ id: string, loginServer: string }}
+ */
+function resolveAcr(doc, az) {
+  const subscription = String(doc.subscriptionId.value);
+  const acr = parseJson(az([
+    'acr', 'show', '--name', doc.acrName.value, '--subscription', subscription, '--output', 'json'
+  ]), 'registry');
+  if (typeof acr.id !== 'string' || typeof acr.loginServer !== 'string' || !acr.loginServer) {
+    throw new Error(`Registry ${doc.acrName.value} did not return a resource ID and login server`);
+  }
+  if (!acr.id.toLowerCase().startsWith(`/subscriptions/${subscription.toLowerCase()}/`)) {
+    throw new Error(`Registry ${doc.acrName.value} is outside the workspace subscription; use a registry in ${subscription}`);
+  }
+  return { id: acr.id, loginServer: acr.loginServer };
+}
+
+function actionMatches(pattern, action) {
+  const expression = new RegExp(`^${String(pattern).split('*').map(part => part.replace(/[.+?^${}()|[\]\\/]/g, '\\$&')).join('.*')}$`, 'i');
+  return expression.test(action);
+}
+
+/**
+ * True when Azure RBAC grants `action` at `scope` to the signed-in caller.
+ * @param {Function} az - Azure CLI runner
+ * @param {string} scope - Resource scope ID
+ * @param {string} action - Control-plane action
+ * @returns {boolean}
+ */
+function hasPermission(az, scope, action) {
+  const result = parseJson(az([
+    'rest', '--method', 'get',
+    '--url', `https://management.azure.com${scope}/providers/Microsoft.Authorization/permissions?api-version=${PERMISSIONS_API}`,
+    '--output', 'json'
+  ]), 'permissions');
+  return (result.value || []).some(permission =>
+    (permission.actions || []).some(pattern => actionMatches(pattern, action)) &&
+    !(permission.notActions || []).some(pattern => actionMatches(pattern, action)));
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @param {{ id: string }} acr - Resolved registry
+ * @param {Function} az - Azure CLI runner
+ * @throws {Error} When deployment, role-assignment or AcrPull grant authority is missing
+ */
+function assertDeploymentAuthority(doc, acr, az) {
+  const subscriptionScope = `/subscriptions/${doc.subscriptionId.value}`;
+  if (!hasPermission(az, subscriptionScope, DEPLOYMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot create deployments in subscription ${doc.subscriptionId.value}`);
+  }
+  if (doc.parameters.deployRoleAssignments.value !== false && !hasPermission(az, subscriptionScope, ROLE_ASSIGNMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot create role assignments in subscription ${doc.subscriptionId.value}; ask for Owner or User Access Administrator, or set parameters.deployRoleAssignments.value to false when roles already exist`);
+  }
+  if (!hasPermission(az, acr.id, ROLE_ASSIGNMENT_WRITE)) {
+    throw new Error(`The signed-in Azure account cannot assign AcrPull on registry ${doc.acrName.value}; ask for Owner or User Access Administrator on that registry`);
+  }
+}
+
+module.exports = { assertActiveAccount, resolveAcr, hasPermission, actionMatches, assertDeploymentAuthority };