@aifabrix/builder 2.55.2 → 2.57.0

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

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * @fileoverview Generation, normalization and projection of the committed, non-secret
+ * `environment-infra.json` installation manifest. Every operational value is explicit in the
+ * file with its source and description; secrets appear only as `valueFromEnv` references.
+ */
+
+const crypto = require('crypto');
+const {
+  PARAMETER_CATALOG, OUTPUT_CATALOG, DEFAULT_LICENSE_EDITION, DEFAULT_ONBOARDING_MODE
+} = require('./infra-catalog');
+
+const INFRA_SCHEMA_VERSION = '2.0.0';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function entry(value, source, description, extra = {}) {
+  return { value, source, description, ...extra };
+}
+
+function templateDefault(template, name) {
+  const value = template.parameters[name].defaultValue;
+  if (typeof value === 'string' && value.startsWith('[')) return '';
+  return value === undefined ? '' : value;
+}
+
+function parameterEntry(name, template) {
+  const spec = PARAMETER_CATALOG[name];
+  switch (spec.kind) {
+  case 'secretEnv':
+    return { valueFromEnv: spec.env, source: 'secretEnv', required: spec.required, description: spec.description };
+  case 'acrLookup':
+    return entry(null, 'azureAcrLookup', spec.description);
+  case 'fixed':
+    return entry(spec.value, spec.source, spec.description);
+  case 'deferred':
+    return entry(null, 'deferred', spec.description, { requiredAt: 'tenantActivation' });
+  case 'allowMyIp':
+    return entry(name === 'allowedIPs' ? [] : false, spec.source, spec.description);
+  case 'license':
+    return entry(DEFAULT_LICENSE_EDITION, spec.source, spec.description);
+  case 'onboarding':
+    return entry(DEFAULT_ONBOARDING_MODE, spec.source, spec.description);
+  default:
+    return entry(templateDefault(template, name), spec.source, spec.description, spec.required ? { required: true } : {});
+  }
+}
+
+function buildParameters(template, existing = {}) {
+  const parameters = {};
+  for (const name of Object.keys(PARAMETER_CATALOG)) {
+    const fresh = parameterEntry(name, template);
+    const workflowOwned = ['fixed', 'deferred', 'secretEnv'].includes(PARAMETER_CATALOG[name].kind);
+    parameters[name] = existing[name] && !workflowOwned ? { ...fresh, value: existing[name].value } : fresh;
+  }
+  return parameters;
+}
+
+function buildOutputs(existing = {}) {
+  return Object.fromEntries(Object.entries(OUTPUT_CATALOG).map(([name, description]) =>
+    [name, { value: existing[name]?.value ?? null, description }]));
+}
+
+function azureSections(template, existing) {
+  return {
+    acrName: existing.acrName || entry('', 'user', 'Required private ACR name. Builder resolves and persists its login server and resource ID using the authenticated Azure account.', { required: true }),
+    allowMyIp: existing.allowMyIp || entry(false, 'cliOrFile', 'Default-off internal test access. When enabled, Builder resolves and audits one public IPv4 /32.', { resolvedCidr: null, resolvedAt: null, resolver: null }),
+    preset: existing.preset || entry('s', 'cliOrFile', 'Shared infrastructure sizing preset.'),
+    parameters: buildParameters(template, existing.parameters),
+    outputs: buildOutputs(existing.outputs),
+    controllerUrl: existing.controllerUrl || entry(null, 'infraOutput', 'Activated Miso Controller URL derived from the Miso web application output.'),
+    tenantActivation: existing.tenantActivation || {
+      status: entry('pending', 'controller', 'Server-reported tenant activation state; Builder never marks activation complete.'),
+      url: entry(null, 'infraOutput', 'URL the user opens to sign in and complete tenant activation.')
+    },
+    deployment: existing.deployment || {
+      status: entry('not-deployed', 'azureDeployment', 'Latest shared infrastructure deployment status.'),
+      name: null, id: null, inputHash: null, completedAt: null
+    }
+  };
+}
+
+function dockerSections(template, existing) {
+  const moriDefault = templateDefault(template, 'moriBaseUrl');
+  return {
+    moriBaseUrl: existing.moriBaseUrl || entry(moriDefault, 'templateDefault', 'Mori service base URL used for registration.', { required: true }),
+    marketplaceSubscriptionId: existing.marketplaceSubscriptionId || entry('', 'workspace', 'Marketplace subscription ID; empty selects Mori Community.'),
+    registration: existing.registration || {
+      status: entry('not-registered', 'mori', 'Mori registration status; the one-time key is stored only in local user secrets.'),
+      evidence: null
+    }
+  };
+}
+
+function identitySections(vendor, resourceGroup, existing) {
+  const docker = vendor === 'DOCKER';
+  const idEntry = (description) => docker
+    ? entry(crypto.randomUUID(), 'generated', description)
+    : entry('', 'user', description, { required: true });
+  return {
+    schemaVersion: INFRA_SCHEMA_VERSION,
+    vendor: existing.vendor || entry(vendor, 'cli', 'Installation vendor; immutable once recorded.'),
+    resourceGroup: existing.resourceGroup || entry(resourceGroup, 'command', 'Workspace and Azure resource-group key.'),
+    installId: existing.installId || entry(resourceGroup, 'command', 'Installation identifier and deployment journal key.'),
+    subscriptionId: existing.subscriptionId || idEntry(docker
+      ? 'Stable Docker installation UUID sent to Mori.'
+      : 'Approved installation subscription recorded by this workspace; active Azure account must match.'),
+    tenantId: existing.tenantId || idEntry(docker
+      ? 'Stable Docker owner UUID sent to Mori.'
+      : 'Approved installation directory tenant recorded by this workspace; not an Entra provider setting.')
+  };
+}
+
+/**
+ * Creates or normalizes the infra manifest for a vendor, preserving user-owned values.
+ * @param {Object} params - Inputs
+ * @param {string} params.vendor - AZURE or DOCKER
+ * @param {string} params.resourceGroup - Resource-group key
+ * @param {Object} params.template - Parsed shipped Marketplace template
+ * @param {Object|null} params.existing - Existing manifest
+ * @returns {Object} Manifest document
+ */
+function buildInfraDocument({ vendor, resourceGroup, template, existing }) {
+  const current = existing || {};
+  if (existing && existing.schemaVersion !== INFRA_SCHEMA_VERSION) {
+    throw new Error(`environment-infra.json schemaVersion ${existing.schemaVersion} is not supported; expected ${INFRA_SCHEMA_VERSION}`);
+  }
+  const sections = vendor === 'DOCKER' ? dockerSections(template, current) : azureSections(template, current);
+  return {
+    ...identitySections(vendor, resourceGroup, current),
+    ...sections,
+    variables: current.variables || {},
+    generated: current.generated || {}
+  };
+}
+
+/**
+ * Lists user-owned required fields that are still empty or invalid.
+ * @param {Object} doc - Manifest
+ * @returns {string[]} JSON paths inside environment-infra.json
+ */
+function missingRequiredFields(doc) {
+  const missing = [];
+  for (const key of ['subscriptionId', 'tenantId']) {
+    if (!UUID.test(String(doc[key].value || ''))) missing.push(`${key}.value (UUID)`);
+  }
+  if (doc.vendor.value === 'DOCKER') {
+    if (!/^https:\/\//.test(String(doc.moriBaseUrl.value || ''))) missing.push('moriBaseUrl.value (https URL)');
+    return missing;
+  }
+  if (!/^[a-zA-Z0-9]{5,50}$/.test(String(doc.acrName.value || ''))) missing.push('acrName.value');
+  if (!/^[a-z0-9]+$/.test(String(doc.parameters.location.value || ''))) missing.push('parameters.location.value');
+  if (!/^https:\/\//.test(String(doc.parameters.moriBaseUrl.value || ''))) missing.push('parameters.moriBaseUrl.value (https URL)');
+  return missing;
+}
+
+module.exports = {
+  INFRA_SCHEMA_VERSION,
+  buildInfraDocument,
+  missingRequiredFields
+};

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

@@ -0,0 +1,86 @@
+'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.
+ */
+
+const { PARAMETER_CATALOG } = require('./infra-catalog');
+const { sha256 } = require('./workspace-files');
+
+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':
+    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 {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 };
+    // Secrets never enter the hash.
+    if (PARAMETER_CATALOG[name].kind !== 'secretEnv') nonSecret[name] = value;
+  }
+  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/stage-input.js

@@ -0,0 +1,169 @@
+'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 } = 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) return;
+  if (stage !== 'infra') {
+    throw new Error('--license-edition is supported only with --stage infra for AZURE installations');
+  }
+  normalizeLicenseEdition(options.licenseEdition);
+}
+
+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,
+ *   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,
+    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 };