@aifabrix/builder 2.56.0 → 2.58.0

package/lib/deployment/installation/infra-projection.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * @fileoverview Projects `environment-infra.json` plus resolved workspace secrets into standard
+ * ARM deploymentParameters, and applies the default-off current-IP access option.
+ * Deferred tenant-activation parameters are never projected. ACR admin credentials (password mode)
+ * are injected only into the temporary parameters file and never enter the input hash.
+ */
+
+const { PARAMETER_CATALOG } = require('./infra-catalog');
+const { sha256 } = require('./workspace-files');
+
+const ARM_CREDENTIAL_PARAMS = Object.freeze(new Set(['acrAdminUsername', 'acrAdminPassword']));
+
+function projectParameter(name, doc, context) {
+  const spec = PARAMETER_CATALOG[name];
+  switch (spec.kind) {
+  case 'deferred':
+    return undefined;
+  case 'secretEnv': {
+    const value = context.env[spec.env];
+    if (spec.required && (typeof value !== 'string' || value === '')) {
+      throw new Error(`Workspace .env is missing required ${spec.env}; rerun after the secret resolves`);
+    }
+    return value;
+  }
+  case 'acrLookup':
+    if (!context.acr || !context.acr[spec.field]) {
+      throw new Error(`ACR ${spec.field} was not resolved from acrName`);
+    }
+    return context.acr[spec.field];
+  case 'fixed':
+    if (name === 'acrAdminUsername' && context.registryCredentials) {
+      return context.registryCredentials.username;
+    }
+    if (name === 'acrAdminPassword' && context.registryCredentials) {
+      return context.registryCredentials.password;
+    }
+    return spec.value;
+  default:
+    return doc.parameters[name].value;
+  }
+}
+
+/**
+ * Builds the owner-only ARM parameters document and the non-secret input hash.
+ * @param {Object} doc - Infra manifest
+ * @param {Object} context - Resolution context
+ * @param {Object.<string,string>} context.env - Resolved workspace .env values
+ * @param {{ id: string, loginServer: string }} context.acr - Resolved registry
+ * @param {{ username: string, password: string }|null|undefined} context.registryCredentials - Credential-mode pull creds (never hashed)
+ * @param {string} context.templateHash - SHA-256 of the deployed template
+ * @returns {{ document: Object, inputHash: string }}
+ */
+function buildArmParameters(doc, context) {
+  const parameters = {};
+  const nonSecret = {};
+  for (const name of Object.keys(PARAMETER_CATALOG)) {
+    const value = projectParameter(name, doc, context);
+    if (value === undefined) continue;
+    parameters[name] = { value };
+    const catalog = PARAMETER_CATALOG[name];
+    if (catalog.kind !== 'secretEnv' && !ARM_CREDENTIAL_PARAMS.has(name)) nonSecret[name] = value;
+  }
+  nonSecret.acrAuth = doc.acrAuth?.effective || doc.acrAuth?.value || 'auto';
+  return {
+    document: {
+      $schema: 'https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#',
+      contentVersion: '1.0.0.0',
+      parameters
+    },
+    inputHash: sha256(JSON.stringify({ templateHash: context.templateHash, parameters: nonSecret }))
+  };
+}
+
+/**
+ * Applies or revokes the generated caller `/32` rule. User-entered rules are preserved.
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {{ enabled: boolean, cidr?: string, resolvedAt?: string, resolver?: string }} access
+ */
+function applyAllowMyIp(doc, access) {
+  const previous = doc.allowMyIp.resolvedCidr;
+  const current = Array.isArray(doc.parameters.allowedIPs.value) ? doc.parameters.allowedIPs.value : [];
+  const userRules = current.filter(rule => rule !== previous);
+  doc.allowMyIp.value = access.enabled;
+  if (access.enabled) {
+    doc.parameters.allowedIPs.value = [...new Set([...userRules, access.cidr])];
+    doc.parameters.enablePostgresPublicAccess.value = true;
+    Object.assign(doc.allowMyIp, { resolvedCidr: access.cidr, resolvedAt: access.resolvedAt, resolver: access.resolver });
+    return;
+  }
+  doc.parameters.allowedIPs.value = userRules;
+  doc.parameters.enablePostgresPublicAccess.value = false;
+  Object.assign(doc.allowMyIp, { resolvedCidr: null, resolvedAt: null, resolver: null });
+}
+
+module.exports = { buildArmParameters, applyAllowMyIp };

package/lib/deployment/installation/public-ip.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * @fileoverview Resolves the caller's single public IPv4 for default-off, invocation-specific
+ * infrastructure test access. Sends no credentials or cookies, follows no redirects and never
+ * retries against another host.
+ */
+
+const net = require('net');
+const { makeApiCall } = require('../../utils/api');
+
+const PUBLIC_IP_RESOLVER = 'https://api.ipify.org?format=json';
+const TIMEOUT_MS = 5000;
+
+const NON_PUBLIC_IPV4 = [
+  ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16],
+  ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16],
+  ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4]
+];
+
+function ipv4ToInt(ip) {
+  return ip.split('.').reduce((acc, octet) => ((acc << 8) + Number(octet)) >>> 0, 0);
+}
+
+/**
+ * True for one strictly formatted, globally routable IPv4 address.
+ * @param {string} ip - Candidate address
+ * @returns {boolean}
+ */
+function isPublicIpv4(ip) {
+  if (typeof ip !== 'string' || net.isIPv4(ip) !== true || !/^(\d{1,3})(\.\d{1,3}){3}$/.test(ip)) return false;
+  if (ip.split('.').some(octet => octet.length > 1 && octet.startsWith('0'))) return false;
+  const value = ipv4ToInt(ip);
+  return !NON_PUBLIC_IPV4.some(([base, bits]) => {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return ((value & mask) >>> 0) === ((ipv4ToInt(base) & mask) >>> 0);
+  });
+}
+
+/**
+ * Resolves the caller's public IPv4 as a `/32` rule.
+ * @param {Function} [call] - HTTP call (defaults to the shared API utility)
+ * @param {Function} [now] - Clock
+ * @returns {Promise<{ cidr: string, resolvedAt: string, resolver: string }>}
+ */
+async function resolvePublicIpv4(call = makeApiCall, now = () => new Date()) {
+  const response = await call(PUBLIC_IP_RESOLVER, {
+    method: 'GET',
+    headers: { Accept: 'application/json' },
+    redirect: 'error',
+    credentials: 'omit',
+    timeoutMs: TIMEOUT_MS
+  });
+  if (!response || !response.success) {
+    throw new Error('Could not resolve the caller public IPv4 for --allow-my-ip (resolver unavailable, redirected or timed out)');
+  }
+  const data = response.data;
+  const ip = data && typeof data === 'object' && !Array.isArray(data) ? data.ip : undefined;
+  if (!isPublicIpv4(ip)) {
+    throw new Error('Public IP resolver did not return exactly one public IPv4 address; --allow-my-ip was not applied');
+  }
+  return { cidr: `${ip}/32`, resolvedAt: now().toISOString(), resolver: PUBLIC_IP_RESOLVER };
+}
+
+module.exports = { PUBLIC_IP_RESOLVER, isPublicIpv4, resolvePublicIpv4 };

package/lib/deployment/installation/registry-auth-mode.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * @fileoverview Image-pull authentication for CLI-managed AZURE infra. The requested mode
+ * (`auto|mi|credentials`, deprecated `admin` = credentials) resolves to an effective `mi` or
+ * `credentials` mode. Credential values come from the primary user's `dev set-registry` pair for the
+ * resolved ACR login server, or (explicit credentials only) from an authorized ACR admin lookup.
+ * They live only in memory and in the temporary ARM parameters file.
+ */
+
+const { normalizeAcrAuth } = require('./infra-catalog');
+const { ACR_AUTH_DESCRIPTION } = require('./infra-manifest');
+
+const FORCED_ROLE_SOURCES = Object.freeze(['acrAuthCredentials', 'acrAuthAdmin']);
+
+/**
+ * Normalizes and records the requested mode (CLI wins over the workspace value).
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {Object} input - Stage input (`acrAuth` from CLI)
+ * @returns {string} Requested mode
+ */
+function applyRequestedAcrAuth(doc, input) {
+  const fromCli = input.acrAuth !== undefined;
+  const mode = normalizeAcrAuth(fromCli ? input.acrAuth : (doc.acrAuth?.value || 'auto'));
+  doc.acrAuth = {
+    ...(doc.acrAuth || {}),
+    value: mode,
+    source: fromCli ? 'cli' : (doc.acrAuth?.source || 'cliOrFile'),
+    description: ACR_AUTH_DESCRIPTION
+  };
+  return mode;
+}
+
+function localSetupHint(host) {
+  return `Run "aifabrix dev set-registry ${host} --username <username> --password-stdin", or use --acr-auth mi`;
+}
+
+async function resolveAzureFallback(doc, acr, az, fetchAdmin) {
+  try {
+    return fetchAdmin(doc, acr, az);
+  } catch (error) {
+    throw new Error(`No registry credentials are available for ${acr.loginServer}: ${error.message}. ${localSetupHint(acr.loginServer)}`);
+  }
+}
+
+/**
+ * Resolves the effective pull mode and ephemeral credentials. A partial local pair always fails.
+ * @param {Object} doc - Infra manifest with a normalized `acrAuth`
+ * @param {{ loginServer: string, adminUserEnabled?: boolean }} acr - Resolved registry
+ * @param {Function} az - Azure CLI runner
+ * @param {Object} deps - `loadRegistryCredentials(host)` and `resolveAcrAdminCredentials(doc, acr, az)`
+ * @returns {Promise<{ mode: 'mi'|'credentials', credentials: ({username: string, password: string}|null), source: string }>}
+ */
+async function resolveRegistryAuth(doc, acr, az, deps) {
+  const requested = normalizeAcrAuth(doc.acrAuth?.value || 'auto');
+  if (requested === 'mi') return { mode: 'mi', credentials: null, source: 'managedIdentity' };
+  const local = await deps.loadRegistryCredentials(acr.loginServer);
+  if (local) return { mode: 'credentials', credentials: local, source: 'localRegistryCredentials' };
+  if (requested === 'auto') return { mode: 'mi', credentials: null, source: 'managedIdentity' };
+  const azure = await resolveAzureFallback(doc, acr, az, deps.resolveAcrAdminCredentials);
+  return { mode: 'credentials', credentials: azure, source: 'acrAdminLookup' };
+}
+
+/**
+ * Records the effective mode and keeps role assignments consistent with it. Credential mode turns
+ * ARM role assignments off; returning to managed identity restores the value it replaced.
+ * @param {Object} doc - Infra manifest (mutated)
+ * @param {'mi'|'credentials'} mode - Effective mode
+ */
+function applyEffectiveAcrAuth(doc, mode) {
+  doc.acrAuth = { ...doc.acrAuth, effective: mode };
+  const roles = doc.parameters.deployRoleAssignments;
+  const forced = FORCED_ROLE_SOURCES.includes(roles.source);
+  if (mode === 'credentials') {
+    if (forced) return;
+    doc.parameters.deployRoleAssignments = {
+      ...roles, value: false, source: 'acrAuthCredentials', restoreValue: roles.value, restoreSource: roles.source
+    };
+    return;
+  }
+  if (!forced) return;
+  const { restoreValue, restoreSource, ...rest } = roles;
+  doc.parameters.deployRoleAssignments = {
+    ...rest,
+    value: restoreValue === undefined ? true : restoreValue,
+    source: restoreSource || 'templateDefault'
+  };
+}
+
+/**
+ * @param {Object} doc - Infra manifest
+ * @returns {boolean} True when the last resolved pull mode uses registry credentials
+ */
+function usesRegistryCredentials(doc) {
+  return doc.acrAuth?.effective === 'credentials';
+}
+
+module.exports = { applyRequestedAcrAuth, resolveRegistryAuth, applyEffectiveAcrAuth, usesRegistryCredentials };

package/lib/deployment/installation/stage-input.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * @fileoverview Workspace-mode `env deploy <resource-group> --stage <stage>` input validation:
+ * resource-group key, stage, vendor matrix and stage-scoped option checks. Runs before any
+ * filesystem, network or cloud mutation.
+ */
+
+const path = require('path');
+const { normalizeLicenseEdition, normalizeAcrAuth, normalizeAzureLocation } = require('./infra-catalog');
+
+const WORKSPACE_STAGES = Object.freeze(['register', 'infra', 'dev', 'tst', 'pro']);
+const ENVIRONMENT_STAGES = Object.freeze(['dev', 'tst', 'pro']);
+const VENDORS = Object.freeze(['AZURE', 'DOCKER']);
+const DEFAULT_VENDOR = 'AZURE';
+const RESOURCE_GROUP_KEY = /^[a-z][a-z0-9-]{2,39}$/;
+const ENV_VAR_NAME = /^[A-Z_][A-Z0-9_]*$/;
+const LEGACY_MARKETPLACE_FLAGS = Object.freeze([
+  'marketplaceJson', 'parameters', 'subscription', 'resourceGroup', 'installId'
+]);
+const DOCKER_SETUP_GUIDANCE = 'DOCKER installations deploy through "aifabrix setup"; only --stage register is supported for DOCKER.';
+
+/**
+ * True when options select the deprecated explicit Marketplace/journal mode.
+ * @param {Object} options - Commander options
+ * @returns {boolean}
+ */
+function isLegacyMarketplaceMode(options) {
+  if (LEGACY_MARKETPLACE_FLAGS.some(flag => options[flag] !== undefined && options[flag] !== null)) {
+    return true;
+  }
+  return !options.stage && Boolean(options.controllerUrl);
+}
+
+/**
+ * True when options select the resource-group installation workspace mode.
+ * @param {Object} options - Commander options
+ * @returns {boolean}
+ */
+function isWorkspaceMode(options) {
+  return Boolean(options.stage) && !isLegacyMarketplaceMode(options);
+}
+
+/**
+ * Validates the positional resource-group key before it is used as a path segment.
+ * @param {string} value - Positional value
+ * @returns {string} The validated key
+ * @throws {Error} On absolute paths, separators, traversal, normalization changes or bad format
+ */
+function validateResourceGroupKey(value) {
+  const raw = typeof value === 'string' ? value : '';
+  if (!raw || path.isAbsolute(raw) || /[\\/]/.test(raw) || raw.includes('..') ||
+      path.normalize(raw) !== raw || raw.normalize('NFC') !== raw || raw.trim() !== raw) {
+    throw new Error('Resource group must be a plain workspace key without paths, separators or traversal');
+  }
+  if (!RESOURCE_GROUP_KEY.test(raw)) {
+    throw new Error('Resource group must be a lowercase Azure-safe name (3-40 characters: a-z, 0-9, -; starts with a letter)');
+  }
+  return raw;
+}
+
+/**
+ * Normalizes a vendor value case-insensitively.
+ * @param {string|undefined} value - Raw vendor value
+ * @returns {string|undefined} Canonical vendor or undefined when absent
+ */
+function normalizeVendor(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const vendor = String(value).trim().toUpperCase();
+  if (!VENDORS.includes(vendor)) {
+    throw new Error(`Unsupported vendor "${value}". Use one of: ${VENDORS.join(', ')}`);
+  }
+  return vendor;
+}
+
+function validateStage(stage) {
+  const value = String(stage || '').trim().toLowerCase();
+  if (!WORKSPACE_STAGES.includes(value)) {
+    throw new Error(`Unsupported stage "${stage}". Use one of: ${WORKSPACE_STAGES.join(', ')}`);
+  }
+  return value;
+}
+
+function resolveVendor(stage, requested, persisted) {
+  if (requested && persisted && requested !== persisted) {
+    throw new Error(`Workspace vendor is ${persisted}; --vendor ${requested} conflicts with the existing installation`);
+  }
+  if (stage === 'register') {
+    if (requested !== 'DOCKER') {
+      throw new Error('--stage register requires explicit --vendor DOCKER; AZURE installations register with Mori during tenant activation in Miso');
+    }
+    return requested;
+  }
+  const vendor = requested || persisted || DEFAULT_VENDOR;
+  if (vendor === 'DOCKER') {
+    throw new Error(`--stage ${stage} is not supported for DOCKER. ${DOCKER_SETUP_GUIDANCE}`);
+  }
+  return vendor;
+}
+
+function assertInfraOnlyOptions(stage, options) {
+  if (options.allowMyIp && stage !== 'infra') {
+    throw new Error('--allow-my-ip is supported only with --stage infra for AZURE installations');
+  }
+  if (options.licenseEdition !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--license-edition is supported only with --stage infra for AZURE installations');
+    }
+    normalizeLicenseEdition(options.licenseEdition);
+  }
+  if (options.acrAuth !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--acr-auth is supported only with --stage infra for AZURE installations');
+    }
+    normalizeAcrAuth(options.acrAuth);
+  }
+  if (options.location !== undefined) {
+    if (stage !== 'infra') {
+      throw new Error('--location is supported only with --stage infra (later environments inherit the saved region)');
+    }
+    normalizeAzureLocation(options.location);
+  }
+}
+
+function assertStageScopedOptions(stage, options) {
+  assertInfraOnlyOptions(stage, options);
+  const envOnly = [['controllerUrl', '--controller-url'], ['misoApiKeyEnv', '--miso-api-key-env']];
+  for (const [key, flag] of envOnly) {
+    if (options[key] !== undefined && !ENVIRONMENT_STAGES.includes(stage)) {
+      throw new Error(`${flag} is supported only with --stage dev, tst or pro`);
+    }
+  }
+  if (options.config !== undefined) {
+    throw new Error('--config is not supported with --stage; environment settings live in the workspace environment files');
+  }
+  if (options.preset !== undefined && stage === 'register') {
+    throw new Error('--preset is not supported with --stage register');
+  }
+  if (options.misoApiKeyEnv !== undefined && !ENV_VAR_NAME.test(String(options.misoApiKeyEnv))) {
+    throw new Error('--miso-api-key-env must be an environment-variable name (for example MISO_API_KEY), never a key value');
+  }
+  if (options.controllerUrl !== undefined && !/^https:\/\/[^/\s]+(\/[^\s]*)?$/.test(String(options.controllerUrl))) {
+    throw new Error('--controller-url must be an https:// URL');
+  }
+}
+
+/**
+ * Resolves validated workspace-mode input.
+ * @param {string} resourceGroupKey - Positional resource-group key
+ * @param {Object} options - Commander options
+ * @param {string|undefined} persistedVendor - Vendor recorded in an existing workspace
+ * @returns {{ resourceGroup: string, stage: string, vendor: string, allowMyIp: boolean, licenseEdition: string|undefined,
+ *   acrAuth: string|undefined, location: string|undefined, preset: string|undefined, controllerUrl: string|undefined, misoApiKeyEnv: string|undefined }}
+ */
+function resolveStageInput(resourceGroupKey, options, persistedVendor) {
+  const resourceGroup = validateResourceGroupKey(resourceGroupKey);
+  const stage = validateStage(options.stage);
+  assertStageScopedOptions(stage, options);
+  const vendor = resolveVendor(stage, normalizeVendor(options.vendor), normalizeVendor(persistedVendor));
+  return {
+    resourceGroup,
+    stage,
+    vendor,
+    allowMyIp: options.allowMyIp === true,
+    licenseEdition: options.licenseEdition,
+    acrAuth: options.acrAuth,
+    location: options.location,
+    preset: options.preset,
+    controllerUrl: options.controllerUrl,
+    misoApiKeyEnv: options.misoApiKeyEnv
+  };
+}
+
+module.exports = {
+  WORKSPACE_STAGES,
+  ENVIRONMENT_STAGES,
+  VENDORS,
+  DEFAULT_VENDOR,
+  isLegacyMarketplaceMode,
+  isWorkspaceMode,
+  validateResourceGroupKey,
+  normalizeVendor,
+  resolveStageInput
+};

package/lib/deployment/installation/stage-output.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * @fileoverview Terminal summary lines for installation workspace stages (tty-summary profile).
+ */
+
+const {
+  formatSuccessLine,
+  formatNextActions,
+  metadata
+} = require('../../utils/cli-test-layout-chalk');
+
+function registerLines(result, resourceGroup) {
+  return [
+    formatSuccessLine(result.alreadyRegistered
+      ? `DOCKER installation ${resourceGroup} is already registered with Mori`
+      : `DOCKER installation ${resourceGroup} registered with Mori`),
+    formatNextActions(['Install locally with: aifabrix setup'])
+  ];
+}
+
+function infraLines(result, resourceGroup) {
+  return [
+    formatSuccessLine(`Shared infrastructure ready: ${result.controllerUrl}`),
+    formatNextActions([
+      `Tenant activation is pending. Open ${result.activationUrl}, sign in and complete activation.`,
+      `Then deploy environments: af env deploy ${resourceGroup} --stage dev (or tst, pro)`
+    ])
+  ];
+}
+
+function environmentLines(result) {
+  return [
+    formatSuccessLine(`Environment ${result.envKey} ${result.status} (deployment ${result.deploymentId}${result.resumed ? ', resumed' : ''})`),
+    formatNextActions([`Deploy applications with: aifabrix deploy <app> (environment ${result.envKey})`])
+  ];
+}
+
+/**
+ * @param {Object} result - Stage result
+ * @param {string} resourceGroup - Resource-group key
+ * @returns {string} Multi-line summary
+ */
+function formatStageResult(result, resourceGroup) {
+  const header = metadata(`Workspace: ${result.workspaceDir}`);
+  let lines;
+  if (result.stage === 'register') lines = registerLines(result, resourceGroup);
+  else if (result.stage === 'infra') lines = infraLines(result, resourceGroup);
+  else lines = environmentLines(result);
+  return `${[header, ...lines].join('\n')}\n`;
+}
+
+module.exports = { formatStageResult };

package/lib/deployment/installation/workspace-env.js

@@ -0,0 +1,76 @@
+'use strict';
+
+/**
+ * @fileoverview Owner-only workspace `.env` merge/remove. Never replaces the file as a whole:
+ * preserves unrelated values and comments, enforces mode 0600, and refuses to overwrite a
+ * conflicting user-set value. Error messages name keys only, never values.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../../core/secrets-env-content');
+const { writeFileAtomic, assertIgnoredSecretFile } = require('./workspace-files');
+
+/**
+ * @param {string} envPath - Workspace .env path
+ * @returns {Object.<string, string>} Parsed values (empty when absent)
+ */
+function readWorkspaceEnv(envPath) {
+  if (!fs.existsSync(envPath)) return {};
+  return parseEnvContentToMap(fs.readFileSync(envPath, 'utf8'));
+}
+
+function findConflicts(existing, entries, replaceable) {
+  return Object.keys(entries).filter((key) => {
+    const current = existing[key];
+    return current !== undefined && current !== '' && current !== entries[key] && !replaceable.has(key);
+  });
+}
+
+/**
+ * Atomically merges owned keys into the workspace `.env`.
+ * @param {string} envPath - Workspace .env path
+ * @param {Object.<string, string>} entries - Keys to set
+ * @param {Object} context - Merge context
+ * @param {string} context.root - Workspace root (ignore check)
+ * @param {string[]} [context.replaceable] - Keys Builder may replace when they differ
+ * @throws {Error} When a user-set value conflicts
+ */
+function mergeWorkspaceEnv(envPath, entries, context) {
+  assertIgnoredSecretFile(envPath, context.root);
+  const content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf8') : '';
+  const existing = parseEnvContentToMap(content);
+  const conflicts = findConflicts(existing, entries, new Set(context.replaceable || []));
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Workspace .env already sets a different value for ${conflicts.join(', ')}. ` +
+      'Remove or correct those lines, then rerun.'
+    );
+  }
+  const changed = Object.fromEntries(Object.entries(entries).filter(([key, value]) => existing[key] !== value));
+  if (Object.keys(changed).length === 0 && content) {
+    fs.chmodSync(envPath, 0o600);
+    return;
+  }
+  const merged = mergeEnvMapIntoContent(content, changed);
+  writeFileAtomic(envPath, merged.endsWith('\n') ? merged : `${merged}\n`, 0o600);
+}
+
+/**
+ * Removes one resolved key line from the workspace `.env` (no-op when absent).
+ * @param {string} envPath - Workspace .env path
+ * @param {string} key - Variable name
+ */
+function removeWorkspaceEnvKey(envPath, key) {
+  if (!fs.existsSync(envPath)) return;
+  const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+  const kept = lines.filter((line) => {
+    const trimmed = line.trim();
+    return trimmed.startsWith('#') || trimmed.substring(0, trimmed.indexOf('=')).trim() !== key;
+  });
+  if (kept.length !== lines.length) {
+    writeFileAtomic(envPath, kept.join('\n'), 0o600);
+  }
+}
+
+module.exports = { readWorkspaceEnv, mergeWorkspaceEnv, removeWorkspaceEnvKey };