@aifabrix/builder 2.49.2 → 2.50.0

package/lib/utils/enterprise-knowledge-paths.js

@@ -0,0 +1,142 @@
+/**
+ * Enterprise Knowledge workspace path helpers (456.5).
+ *
+ * @fileoverview Paths under enterprise-knowledge/ for Enterprise Knowledge anchors
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { nodeFs } = require('../internal/node-fs');
+
+const WORKSPACE_ENTERPRISE_KNOWLEDGE = 'enterprise-knowledge';
+const SYSTEM_KIND_ENTERPRISE_KNOWLEDGE = 'enterpriseKnowledge';
+
+/**
+ * Materialization parent without importing paths.js (avoids circular deps in tests).
+ * @returns {string}
+ */
+function getMaterializationParent() {
+  const work = process.env.AIFABRIX_WORK;
+  if (work && typeof work === 'string' && work.trim()) {
+    return path.resolve(work.trim());
+  }
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    return path.resolve(process.env.AIFABRIX_HOME.trim());
+  }
+  return path.join(os.homedir(), '.aifabrix');
+}
+
+/**
+ * Absolute enterprise-knowledge/ next to process.cwd when present.
+ * @returns {string|null}
+ */
+function getCwdEnterpriseKnowledgeRoot() {
+  const p = path.join(path.resolve(process.cwd()), WORKSPACE_ENTERPRISE_KNOWLEDGE);
+  try {
+    const disk = nodeFs();
+    if (disk.existsSync(p)) {
+      const st = disk.statSync(p);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Default enterprise-knowledge root under materialization parent.
+ * @returns {string}
+ */
+function getEnterpriseKnowledgeRoot() {
+  const cwdRoot = getCwdEnterpriseKnowledgeRoot();
+  if (cwdRoot) {
+    return cwdRoot;
+  }
+  return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE);
+}
+
+/**
+ * Resolves enterprise-knowledge/<anchorKey> (cwd-first, then materialization parent).
+ * @param {string} anchorKey - Enterprise Knowledge anchor key
+ * @returns {string}
+ */
+function getEnterpriseKnowledgePath(anchorKey) {
+  if (!anchorKey || typeof anchorKey !== 'string') {
+    throw new Error('Anchor key is required and must be a string');
+  }
+  const cwdHit = path.join(path.resolve(process.cwd()), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+  try {
+    const disk = nodeFs();
+    if (disk.existsSync(cwdHit)) {
+      const st = disk.statSync(cwdHit);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return cwdHit;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+}
+
+function isEnterpriseKnowledgeDirectory(disk, fullPath) {
+  try {
+    const child = disk.statSync(fullPath);
+    return Boolean(child && typeof child.isDirectory === 'function' && child.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+function collectAnchorNamesInRoot(disk, root, names) {
+  if (!root || !disk.existsSync(root) || !isEnterpriseKnowledgeDirectory(disk, root)) {
+    return;
+  }
+  let entries;
+  try {
+    entries = disk.readdirSync(root);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const full = path.join(root, name);
+    if (isEnterpriseKnowledgeDirectory(disk, full)) {
+      names.add(name);
+    }
+  }
+}
+
+/**
+ * Lists anchor folder names under enterprise-knowledge/.
+ * @returns {string[]}
+ */
+function listEnterpriseKnowledgeAnchors() {
+  const disk = nodeFs();
+  const names = new Set();
+  const roots = new Set();
+  const cwdRoot = getCwdEnterpriseKnowledgeRoot();
+  if (cwdRoot) {
+    roots.add(path.resolve(cwdRoot));
+  }
+  roots.add(path.resolve(path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE)));
+  for (const root of roots) {
+    collectAnchorNamesInRoot(disk, root, names);
+  }
+  return [...names].sort();
+}
+
+module.exports = {
+  WORKSPACE_ENTERPRISE_KNOWLEDGE,
+  SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  getCwdEnterpriseKnowledgeRoot,
+  getEnterpriseKnowledgeRoot,
+  getEnterpriseKnowledgePath,
+  listEnterpriseKnowledgeAnchors
+};

package/lib/utils/env-copy.js

@@ -123,7 +123,8 @@ async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
   } else {
     baseContent = runContent;
   }
-  const toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
+  let toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
+  toWrite = substituteMntDataForLocal(toWrite, outputPath);
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
   logger.log(
     formatSuccessLine(

package/lib/utils/env-dotenv-format.js

@@ -0,0 +1,103 @@
+/**
+ * Dotenv serialization for values that may contain PEM or other multiline secrets.
+ * Docker Compose env_file and Builder .env.run require single-line KEY=value rows.
+ *
+ * @fileoverview Shared dotenv quoting/escaping for resolve, run, and admin env writers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Whether a dotenv value should be double-quoted (spaces, #, =, commas, or multiline).
+ * @param {string} value
+ * @returns {boolean}
+ */
+function valueNeedsDotenvQuoting(value) {
+  const s = String(value ?? '');
+  return /[\r\n]/.test(s) || /[,\s#=]/.test(s) || s !== s.trim();
+}
+
+/**
+ * Escape a logical string for placement inside double quotes in a .env file.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeDotenvQuotedInner(value) {
+  return String(value ?? '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+}
+
+/**
+ * Format the value portion of KEY=value (includes quotes when needed).
+ * Never emits raw newline characters.
+ *
+ * @param {string} value - Logical value (may contain real newlines)
+ * @returns {string}
+ */
+function formatDotenvValuePart(value) {
+  const logical = String(value ?? '');
+  if (!valueNeedsDotenvQuoting(logical)) {
+    return logical;
+  }
+  return `"${escapeDotenvQuotedInner(logical)}"`;
+}
+
+/**
+ * Format a full KEY=value line without trailing newline.
+ * @param {string} key
+ * @param {string} value
+ * @returns {string}
+ */
+function formatDotenvLine(key, value) {
+  return `${key}=${formatDotenvValuePart(value)}`;
+}
+
+/**
+ * Normalize kv:// substitution values so multiline PEM never splits .env rows.
+ * @param {string} value
+ * @returns {string}
+ */
+function formatDotenvSubstitutionValue(value) {
+  const s = String(value ?? '');
+  if (/[\r\n]/.test(s)) {
+    return formatDotenvValuePart(s);
+  }
+  if (/\\n/.test(s) && /-----BEGIN [A-Z ]+-----/.test(s)) {
+    return formatDotenvValuePart(s.replace(/\\n/g, '\n'));
+  }
+  return s;
+}
+
+/**
+ * Parse a raw value segment from KEY=value (after first '=').
+ * @param {string} raw
+ * @returns {string}
+ */
+function parseDotenvRawValue(raw) {
+  let value = raw ?? '';
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    value = value
+      .slice(1, -1)
+      .replace(/\\n/g, '\n')
+      .replace(/\\"/g, '"')
+      .replace(/\\\\/g, '\\');
+  } else if (value.length >= 2 && value.startsWith('\'') && value.endsWith('\'')) {
+    value = value.slice(1, -1);
+  }
+  return value;
+}
+
+module.exports = {
+  valueNeedsDotenvQuoting,
+  escapeDotenvQuotedInner,
+  formatDotenvValuePart,
+  formatDotenvLine,
+  formatDotenvSubstitutionValue,
+  parseDotenvRawValue
+};

package/lib/utils/external-env-template.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const Handlebars = require('handlebars');
 const { systemKeyToKvPrefix, kvEnvKeyToPath, securityKeyToVar } = require('./credential-secrets-env');
 const { getAuthCredentialTemplate } = require('./authentication-shape');
+const { buildAuthSecureVarsFromAllSlots } = require('./authentication-env-template');
 
 /**
  * Builds hint string from portalInput (options → enum, validation → min-max or pattern).
@@ -154,7 +155,9 @@ function buildExternalEnvTemplateContext(system) {
       'apikey'
     ).toLowerCase();
   }
-  const authSecureVars = buildAuthSecureVarsFromSystem(system);
+  const slotSecureVars = buildAuthSecureVarsFromAllSlots(system);
+  const authSecureVars =
+    slotSecureVars.length > 0 ? slotSecureVars : buildAuthSecureVarsFromSystem(system);
   const authVars =
     (credential?.variables && typeof credential.variables === 'object' ? credential.variables : null) ||
     (authBlock?.variables && typeof authBlock.variables === 'object' ? authBlock.variables : {});

package/lib/utils/external-system-display.js

@@ -273,7 +273,11 @@ function displayServerDatasourceTestRunResults(results, verbose, opts = {}) {
   // Plan §17: system-level overview for multi-datasource results (no full §16 dump per datasource by default).
   // Keep legacy per-datasource full envelope available only via datasource commands.
   if (integrationResultsHaveEnvelope(results)) {
-    displaySystemAggregateDatasourceTestRuns(results, { runType, verbose: Boolean(verbose) });
+    displaySystemAggregateDatasourceTestRuns(results, {
+      runType,
+      verbose: Boolean(verbose),
+      debug: opts.debug
+    });
     return;
   }
 

package/lib/utils/external-system-readiness-compact-blocks.js

@@ -0,0 +1,221 @@
+/**
+ * Compact card section loggers (plan 156.0).
+ *
+ * @fileoverview Internal blocks for upload/deploy compact summaries
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { formatSuccessLine, formatBlockingError } = require('./cli-test-layout-chalk');
+const { summarizeDatasourceTiersA } = require('./external-system-readiness-core');
+const {
+  PILLAR_LABELS,
+  formatAuthenticationSummary,
+  formatDatasourceAggregateLine,
+  formatCredentialPushLine,
+  formatConfigResolveLine,
+  formatGatePillarLine,
+  formatPreflightLine,
+  formatRuntimeDatasourceIssues,
+  buildProbeCompactContext,
+  resolveConnectedSystemStatus,
+  resolveManifestAuthMethod,
+  logCompactHeader,
+  logCompactPortalLinks,
+  logCompactTip
+} = require('./external-system-readiness-compact-display');
+
+/**
+ * @param {Object|null|undefined} credentialPush
+ * @param {Object|null|undefined} configPush
+ */
+function logCompactPushLines(credentialPush, configPush) {
+  const credLine = formatCredentialPushLine(credentialPush || {});
+  if (credLine) logger.log(`  ${credLine}`);
+  const cfgLine = formatConfigResolveLine({
+    count: configPush?.pushed || configPush?.count,
+    names: configPush?.names
+  });
+  if (cfgLine) logger.log(`  ${cfgLine}`);
+}
+
+/**
+ * @param {Object|null|undefined} probeData
+ */
+function logCompactProbeSection(probeData) {
+  const probeCtx = buildProbeCompactContext({ probeData });
+  if (!probeCtx) return;
+  logger.log('');
+  const conn = probeCtx.connectivityPassed ? 'passed' : 'failed';
+  logger.log(`  Runtime: ${probeCtx.runtimeVerdict}            Connectivity: ${conn}`);
+  logger.log(
+    `  Runtime datasources: ${probeCtx.summary.ready} ready · ${probeCtx.summary.partial} partial · ${probeCtx.summary.failed} failed`
+  );
+  const issueLines = formatRuntimeDatasourceIssues({
+    issues: probeCtx.summary.issues.map(i => ({
+      key: i.key,
+      lines: i.lines,
+      tier: probeCtx.summary.rows.find(r => r.key === i.key)?.tier === 'failed' ? 'Failed' : 'Partial'
+    }))
+  });
+  for (const line of issueLines) {
+    logger.log(chalk.yellow(`  ${line}`));
+  }
+}
+
+/**
+ * @param {Object} ctx
+ */
+function logUploadReadinessSummaryCompact(ctx) {
+  const { systemKey, environment, dataplaneUrl, publication, manifest, forcePublish, probeData } = ctx;
+  const genMcp = publication?.generateMcpContract !== false;
+  const tierA = summarizeDatasourceTiersA(publication?.datasources || [], genMcp);
+  const systemCfg = manifest?.system || {};
+  const statusLabel = resolveConnectedSystemStatus({ publication });
+
+  logCompactHeader({ command: 'upload', systemKey, environment, dataplaneUrl });
+  if (forcePublish) {
+    logger.log(
+      chalk.yellow(
+        '  Warning: --force bypasses active-datasource schema replacement guards on publish.'
+      )
+    );
+  }
+  logCompactPushLines(ctx.credentialPush, ctx.configPush);
+  logger.log('');
+  let statusPart = `Status: ${statusLabel}`;
+  statusPart += `          ${formatAuthenticationSummary({ method: resolveManifestAuthMethod(systemCfg) })}`;
+  statusPart += `          ${formatDatasourceAggregateLine({
+    ready: tierA.ready,
+    partial: tierA.partial,
+    failed: tierA.failed,
+    mcp: genMcp
+  })}`;
+  if (forcePublish) statusPart += '          Publish mode: forced';
+  logger.log(`  ${statusPart}`);
+  logCompactProbeSection(probeData);
+  logger.log('');
+  logCompactPortalLinks({ dataplaneUrl, systemKey });
+  logger.log('');
+  logCompactTip({ systemKey, command: 'upload', probed: !!probeData });
+}
+
+/**
+ * @param {Array<Object>|undefined} dsFromCtx
+ * @param {Object} manifest
+ * @returns {Object[]}
+ */
+function resolveDeployCompactDatasources(dsFromCtx, manifest) {
+  if (Array.isArray(dsFromCtx) && dsFromCtx.length > 0) return dsFromCtx;
+  return (manifest.dataSources || []).map(d => ({
+    key: d.key,
+    status: d.status || 'published',
+    isActive: d.isActive !== false,
+    mcpContract: d.mcpContract
+  }));
+}
+
+/**
+ * @param {Object} ctx
+ */
+function logDeployCompactPreflightAndGates(ctx) {
+  logger.log(`  ${formatSuccessLine('Local validation')}`);
+  const preflight = ctx.gateOutcomes?.baseline;
+  if (preflight) {
+    const pf = formatPreflightLine(preflight);
+    if (pf) logger.log(`  ${pf}`);
+  } else {
+    logger.log(`  ${formatSuccessLine('Preflight: unit + integration')}`);
+  }
+  for (const gate of ctx.gateOutcomes?.gates || []) {
+    if (gate.failedDetail) {
+      logger.log(
+        `  ${formatBlockingError(`${PILLAR_LABELS[gate.pillar] || gate.pillar} · FAILED — ${gate.failedDetail}`)}`
+      );
+    } else {
+      logger.log(`  ${formatGatePillarLine(gate)}`);
+    }
+  }
+}
+
+/**
+ * @param {Object} ctx
+ */
+function logDeployCompactDeploymentSteps(ctx) {
+  logCompactPushLines(ctx.credentialPush, ctx.configPush);
+  if (!ctx.fetchError) {
+    logger.log(`  ${formatSuccessLine('Dataplane validation')}`);
+  }
+  if (ctx.deploymentOk) {
+    const draftPart = ctx.draftDeploymentId
+      ? ` · Draft ID: ${String(ctx.draftDeploymentId).slice(0, 12)}…`
+      : '';
+    logger.log(`  ${formatSuccessLine(`Controller deploy · polled · completed${draftPart}`)}`);
+    return;
+  }
+  logger.log(`  ${formatBlockingError('Controller deploy failed')}`);
+  if (ctx.deploymentDetail?.error) {
+    logger.log(chalk.red(`     Error: ${ctx.deploymentDetail.error}`));
+  }
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object} systemCfg
+ * @param {Object} tierA
+ * @param {boolean} genMcp
+ * @param {string} statusLabel
+ */
+function logDeployCompactStatusRow(ctx, systemCfg, tierA, genMcp, statusLabel) {
+  const aggregate = formatDatasourceAggregateLine({
+    ready: tierA.ready,
+    partial: tierA.partial,
+    failed: tierA.failed,
+    mcp: genMcp
+  });
+  const auth = formatAuthenticationSummary({ method: resolveManifestAuthMethod(systemCfg) });
+  const isDraftAfterDeploy =
+    ctx.deploymentOk && String(ctx.systemFromDataplane?.status || '').toLowerCase() === 'draft';
+  if (isDraftAfterDeploy) {
+    logger.log(`  ${formatBlockingError('Status: Draft (expected Published after deploy)')}`);
+    logger.log(`     ${auth}          ${aggregate}`);
+    return;
+  }
+  if (ctx.fetchError) {
+    logger.log(chalk.yellow(`  Unable to fetch system status: ${ctx.fetchError.message}`));
+    return;
+  }
+  logger.log(`  Status: ${statusLabel}          ${auth}          ${aggregate}`);
+}
+
+/**
+ * @param {Object} ctx
+ */
+function logDeployReadinessSummaryCompact(ctx) {
+  const systemKey = ctx.manifest.key;
+  const systemCfg = ctx.manifest.system || {};
+  const genMcp = systemCfg.generateMcpContract !== false;
+  const datasources = resolveDeployCompactDatasources(ctx.datasources, ctx.manifest);
+  const tierA = summarizeDatasourceTiersA(datasources, genMcp);
+  const statusLabel = resolveConnectedSystemStatus({ systemFromDataplane: ctx.systemFromDataplane });
+
+  logCompactHeader({ command: 'deploy', systemKey, environment: ctx.environment, dataplaneUrl: ctx.dataplaneUrl });
+  logDeployCompactPreflightAndGates(ctx);
+  logDeployCompactDeploymentSteps(ctx);
+  logger.log('');
+  logDeployCompactStatusRow(ctx, systemCfg, tierA, genMcp, statusLabel);
+  logCompactProbeSection(ctx.probeData);
+  logger.log('');
+  logCompactPortalLinks({ dataplaneUrl: ctx.dataplaneUrl, systemKey });
+  logger.log('');
+  logCompactTip({ systemKey, command: 'deploy', probed: !!ctx.probeData });
+}
+
+module.exports = {
+  logUploadReadinessSummaryCompact,
+  logDeployReadinessSummaryCompact
+};