@aifabrix/builder 2.56.0 → 2.58.0

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

@@ -0,0 +1,178 @@
+'use strict';
+
+/**
+ * @fileoverview Installation workspace filesystem helpers: `infrastructure/<resource-group>/`
+ * resolution, deterministic atomic JSON writes, hash-guarded generated files and ignore checks.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const WORKSPACE_PARENT = 'infrastructure';
+const FILES = Object.freeze({
+  template: 'azure-main.json',
+  infra: 'environment-infra.json',
+  envTemplate: 'env.template',
+  env: '.env'
+});
+
+/**
+ * @param {string} envKey - dev, tst or pro
+ * @returns {string} Environment file name
+ */
+function environmentFileName(envKey) {
+  return `environment-${envKey}.json`;
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function runGit(args, cwd) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+/**
+ * Builder workspace root: the Git top-level of the current directory, else the current directory.
+ * @param {string} [cwd] - Starting directory
+ * @returns {string} Absolute root path
+ */
+function resolveWorkspaceRoot(cwd = process.cwd()) {
+  const result = runGit(['rev-parse', '--show-toplevel'], cwd);
+  if (!result.error && result.status === 0 && result.stdout.trim()) {
+    return path.resolve(result.stdout.trim());
+  }
+  return path.resolve(cwd);
+}
+
+/**
+ * Resolves `infrastructure/<resource-group>/` and proves it stays inside the workspace root.
+ * @param {string} root - Workspace root
+ * @param {string} resourceGroup - Validated resource-group key
+ * @returns {string} Absolute workspace directory
+ */
+function resolveWorkspaceDir(root, resourceGroup) {
+  const parent = path.join(root, WORKSPACE_PARENT);
+  const dir = path.join(parent, resourceGroup);
+  const relative = path.relative(parent, dir);
+  if (relative !== resourceGroup || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('Resolved installation workspace escapes the infrastructure directory');
+  }
+  for (const candidate of [parent, dir]) {
+    if (fs.existsSync(candidate) && fs.lstatSync(candidate).isSymbolicLink()) {
+      throw new Error(`Installation workspace path must not be a symbolic link: ${candidate}`);
+    }
+  }
+  return dir;
+}
+
+/**
+ * Deterministic JSON text (two-space indentation, trailing newline).
+ * @param {Object} document - JSON document
+ * @returns {string}
+ */
+function toJsonText(document) {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+/**
+ * @param {string} file - JSON file path
+ * @returns {Object|null} Parsed document or null when absent
+ */
+function readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (_) {
+    throw new Error(`Workspace file is not valid JSON: ${file}`);
+  }
+}
+
+/**
+ * Writes content atomically through an owner-only temporary file in the same directory.
+ * The temporary file is removed on every failure path.
+ * @param {string} file - Target path
+ * @param {string} content - Content
+ * @param {number} mode - Final file mode
+ */
+function writeFileAtomic(file, content, mode) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, content, { mode: 0o600, flag: 'wx' });
+    fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, file);
+  } finally {
+    if (fs.existsSync(tmp)) fs.rmSync(tmp, { force: true });
+  }
+}
+
+/**
+ * @param {string} file - Target path
+ * @param {Object} document - JSON document
+ */
+function writeJsonAtomic(file, document) {
+  writeFileAtomic(file, toJsonText(document), 0o644);
+}
+
+/**
+ * Writes a committed generated file only when it is absent, unchanged since generation, or
+ * already identical. Returns the new SHA-256 hash.
+ * @param {string} file - Target path
+ * @param {string} content - Generated content
+ * @param {string|undefined} recordedHash - Hash recorded at the previous generation
+ * @returns {string} Hash of the written content
+ * @throws {Error} When a user-modified generated file would be replaced
+ */
+function writeGeneratedFile(file, content, recordedHash) {
+  const nextHash = sha256(content);
+  if (fs.existsSync(file)) {
+    const currentHash = sha256(fs.readFileSync(file));
+    if (currentHash === nextHash) return nextHash;
+    if (currentHash !== recordedHash) {
+      throw new Error(
+        `Generated workspace file ${path.basename(file)} was modified after generation. ` +
+        `Review it with "git diff -- ${file}", restore it (git checkout -- <file>) or delete it, then rerun.`
+      );
+    }
+  }
+  writeFileAtomic(file, content, 0o644);
+  return nextHash;
+}
+
+/**
+ * Refuses to write a secret file that Git could track.
+ * @param {string} file - Secret file path
+ * @param {string} root - Workspace root
+ * @throws {Error} When the file is inside a Git work tree and not ignored, or already tracked
+ */
+function assertIgnoredSecretFile(file, root) {
+  const inside = runGit(['rev-parse', '--is-inside-work-tree'], root);
+  if (inside.error || inside.status !== 0) return;
+  const relative = path.relative(root, file);
+  if (runGit(['ls-files', '--error-unmatch', '--', relative], root).status === 0) {
+    throw new Error(`${relative} is tracked by Git; remove it from the index (git rm --cached) before continuing`);
+  }
+  if (runGit(['check-ignore', '-q', '--', relative], root).status !== 0) {
+    throw new Error(`${relative} is not ignored by Git; add ".env" to .gitignore before Builder writes secrets there`);
+  }
+}
+
+module.exports = {
+  FILES,
+  WORKSPACE_PARENT,
+  environmentFileName,
+  sha256,
+  resolveWorkspaceRoot,
+  resolveWorkspaceDir,
+  toJsonText,
+  readJsonIfExists,
+  writeFileAtomic,
+  writeJsonAtomic,
+  writeGeneratedFile,
+  assertIgnoredSecretFile
+};

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

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * @fileoverview Validates installation workspace manifests against their Builder-owned schemas
+ * before they are written, so unknown or secret-bearing shapes never reach version control.
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const { formatValidationErrors } = require('../../utils/error-formatter');
+
+let validators = null;
+
+function getValidators() {
+  if (!validators) {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    validators = {
+      infra: ajv.compile(require('../../schema/infrastructure-schema.json')),
+      environment: ajv.compile(require('../../schema/installation-environment.schema.json'))
+    };
+  }
+  return validators;
+}
+
+/**
+ * @param {'infra'|'environment'} kind - Manifest kind
+ * @param {Object} document - Manifest document
+ * @param {string} fileName - File name for messages
+ * @throws {Error} When the document does not match its schema
+ */
+function assertWorkspaceDocument(kind, document, fileName) {
+  const validate = getValidators()[kind];
+  if (!validate(document)) {
+    const messages = formatValidationErrors(validate.errors);
+    throw new Error(`${fileName} does not match its schema:\n  - ${messages.join('\n  - ')}`);
+  }
+}
+
+module.exports = { assertWorkspaceDocument };

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

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * @fileoverview Resolves the workspace `env.template` contract through the configured Builder
+ * secret system and materializes values into the owner-only workspace `.env`.
+ * Automated writes target only the primary user secrets file, never the shared store.
+ */
+
+const { SECRET_BINDINGS, ENV_TEMPLATE_KEYS } = require('./infra-catalog');
+const { mergeWorkspaceEnv } = require('./workspace-env');
+
+function secretSetHint(binding) {
+  return `aifabrix secret set ${binding.kv} <value>`;
+}
+
+function defaultSecretsApi() {
+  const { loadSecrets } = require('../../core/secrets');
+  const { ensureSecretsForKeys } = require('../../core/secrets-ensure');
+  return { loadSecrets, ensureSecretsForKeys };
+}
+
+function asValue(raw) {
+  if (raw === undefined || raw === null) return '';
+  return String(raw);
+}
+
+/**
+ * Resolves and materializes the vendor's secret contract into `.env`.
+ * @param {Object} params - Inputs
+ * @param {string} params.vendor - AZURE or DOCKER
+ * @param {string} params.envPath - Workspace .env path
+ * @param {string} params.root - Workspace root
+ * @param {string[]} [params.names] - Subset of contract names to resolve (defaults to vendor contract)
+ * @param {Object} [params.secretsApi] - Injected secret-system functions (tests)
+ * @returns {Promise<Object.<string,string>>} Resolved values (never logged)
+ * @throws {Error} When a required secret is missing; message names only variable and kv key
+ */
+async function materializeWorkspaceSecrets({ vendor, envPath, root, names, secretsApi }) {
+  const api = secretsApi || defaultSecretsApi();
+  const selected = names || ENV_TEMPLATE_KEYS[vendor];
+  const generated = selected.filter(name => SECRET_BINDINGS[name].generate).map(name => SECRET_BINDINGS[name].kv);
+  if (generated.length > 0) {
+    await api.ensureSecretsForKeys(generated);
+  }
+  const secrets = (await api.loadSecrets()) || {};
+  const resolved = {};
+  const missing = [];
+  for (const name of selected) {
+    const binding = SECRET_BINDINGS[name];
+    const value = asValue(secrets[binding.kv]);
+    if (value.startsWith('kv://')) {
+      missing.push(`${name} (kv://${binding.kv}): unresolved reference; run ${secretSetHint(binding)}`);
+    } else if (value) {
+      resolved[name] = value;
+    } else if (binding.required) {
+      missing.push(`${name} (kv://${binding.kv}): run ${secretSetHint(binding)}`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(`Required installation secrets are not set:\n  - ${missing.join('\n  - ')}`);
+  }
+  mergeWorkspaceEnv(envPath, resolved, { root });
+  return resolved;
+}
+
+module.exports = { materializeWorkspaceSecrets };

package/lib/deployment/installation/workspace.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * @fileoverview Loads and generates the `infrastructure/<resource-group>/` installation workspace:
+ * vendor template snapshot, `environment-infra.json`, per-environment files and `env.template`,
+ * with recorded provenance hashes.
+ */
+
+// Real-sync adapter: installation workspace state must not disappear under Jest fs mocks.
+const fs = require('../../internal/fs-real-sync');
+const path = require('path');
+const files = require('./workspace-files');
+const { buildEnvTemplate, assertTemplateCoverage } = require('./infra-catalog');
+const { buildInfraDocument } = require('./infra-manifest');
+const { buildEnvironmentDocument } = require('./environment-manifest');
+const { ENVIRONMENT_STAGES } = require('./stage-input');
+const { assertWorkspaceDocument } = require('./workspace-schema');
+
+const SHIPPED_TEMPLATE = path.resolve(__dirname, '../../../templates/marketplace/main.json');
+
+function builderVersion() {
+  return require('../../../package.json').version;
+}
+
+/**
+ * Resolves workspace paths and reads the persisted infra manifest (if any).
+ * @param {string} resourceGroup - Validated resource-group key
+ * @param {Object} [context] - Optional overrides
+ * @param {string} [context.root] - Workspace root
+ * @returns {{ root: string, dir: string, paths: Object, infra: Object|null }}
+ */
+function openWorkspace(resourceGroup, context = {}) {
+  const root = context.root || files.resolveWorkspaceRoot();
+  const dir = files.resolveWorkspaceDir(root, resourceGroup);
+  const paths = {
+    template: path.join(dir, files.FILES.template),
+    infra: path.join(dir, files.FILES.infra),
+    envTemplate: path.join(dir, files.FILES.envTemplate),
+    env: path.join(dir, files.FILES.env),
+    environment: envKey => path.join(dir, files.environmentFileName(envKey))
+  };
+  const infra = files.readJsonIfExists(paths.infra);
+  if (infra && infra.resourceGroup?.value !== resourceGroup) {
+    throw new Error(`Workspace identity mismatch: ${paths.infra} records resource group "${infra.resourceGroup?.value}"`);
+  }
+  return { root, dir, paths, infra };
+}
+
+function loadShippedTemplate(templatePath = SHIPPED_TEMPLATE) {
+  const text = fs.readFileSync(templatePath, 'utf8');
+  const template = JSON.parse(text);
+  assertTemplateCoverage(template);
+  return { text, template, hash: files.sha256(text) };
+}
+
+function writeGenerated(workspace, doc, name, content) {
+  const recorded = doc.generated.files?.[name];
+  const hash = files.writeGeneratedFile(path.join(workspace.dir, name), content, recorded);
+  if (hash !== recorded) {
+    doc.generated.files = { ...(doc.generated.files || {}), [name]: hash };
+    return true;
+  }
+  return false;
+}
+
+function ensureEnvironmentFiles(workspace) {
+  for (const envKey of ENVIRONMENT_STAGES) {
+    const file = workspace.paths.environment(envKey);
+    if (!fs.existsSync(file)) saveEnvironment(workspace, envKey, buildEnvironmentDocument({ envKey, existing: null }));
+  }
+}
+
+/**
+ * Creates or refreshes the workspace for a vendor and persists `environment-infra.json`.
+ * @param {Object} workspace - Result of openWorkspace
+ * @param {{ vendor: string, resourceGroup: string }} input - Validated stage input
+ * @param {Object} [context] - Optional overrides
+ * @param {string} [context.templatePath] - Vendor template source (tests)
+ * @param {Function} [context.now] - Clock
+ * @returns {{ doc: Object, template: Object, templateHash: string }}
+ */
+function materializeWorkspace(workspace, input, context = {}) {
+  const shipped = loadShippedTemplate(context.templatePath);
+  const doc = buildInfraDocument({
+    vendor: input.vendor, resourceGroup: input.resourceGroup, template: shipped.template, existing: workspace.infra
+  });
+  let changed = !workspace.infra;
+  if (input.vendor === 'AZURE') {
+    changed = writeGenerated(workspace, doc, files.FILES.template, shipped.text) || changed;
+    ensureEnvironmentFiles(workspace);
+  }
+  changed = writeGenerated(workspace, doc, files.FILES.envTemplate, buildEnvTemplate(input.vendor)) || changed;
+  if (changed) {
+    doc.generated = {
+      ...doc.generated,
+      builderVersion: builderVersion(),
+      templateContentVersion: shipped.template.contentVersion || null,
+      templateSha256: shipped.hash,
+      generatedAt: (context.now ? context.now() : new Date()).toISOString()
+    };
+  }
+  saveInfra(workspace, doc);
+  return { doc, template: shipped.template, templateHash: shipped.hash };
+}
+
+/**
+ * Persists the infra manifest.
+ * @param {Object} workspace - Workspace
+ * @param {Object} doc - Manifest
+ */
+function saveInfra(workspace, doc) {
+  assertWorkspaceDocument('infra', doc, files.FILES.infra);
+  files.writeJsonAtomic(workspace.paths.infra, doc);
+  workspace.infra = doc;
+}
+
+/**
+ * Persists an environment file after schema validation.
+ * @param {Object} workspace - Workspace
+ * @param {string} envKey - dev, tst or pro
+ * @param {Object} doc - Environment document
+ */
+function saveEnvironment(workspace, envKey, doc) {
+  assertWorkspaceDocument('environment', doc, files.environmentFileName(envKey));
+  files.writeJsonAtomic(workspace.paths.environment(envKey), doc);
+}
+
+module.exports = { SHIPPED_TEMPLATE, openWorkspace, materializeWorkspace, saveInfra, saveEnvironment, loadShippedTemplate };