@aifabrix/builder 2.49.2 → 2.50.0

package/lib/schema/type/credential-field-registry.json

@@ -394,7 +394,7 @@
       ]
     },
     "oidc": {
-      "active": false,
+      "active": true,
       "display": {
         "label": "OIDC",
         "order": 5
@@ -485,7 +485,7 @@
       ]
     },
     "hmac": {
-      "active": false,
+      "active": true,
       "display": {
         "label": "HMAC",
         "order": 6

package/lib/schema/type/document-storage.json

@@ -279,6 +279,15 @@
             }
           },
           "additionalProperties": false
+        },
+        "fieldHints": {
+          "type": "object",
+          "description": "Optional per-field extraction hints for governed FK review (plan 441.1).",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          }
         }
       },
       "additionalProperties": false

package/lib/utils/agent-trust-run-display.js

@@ -90,7 +90,7 @@ function logTrustWarningsAndFindings(run, opts) {
 function logTrustFooter(run, opts) {
   logger.log('');
   logger.log(metaGray('  ── Integration reality (informative) ──'));
-  logger.log(metaGray(`  Local manifest:  ${opts.noSync ? 'not uploaded (--no-sync)' : 'uploaded before run'}`));
+  logger.log(metaGray(`  Local manifest:  ${opts.noPublish ? 'not uploaded (--no-publish)' : 'uploaded before run'}`));
   logger.log(metaGray(`  Publish gate:    ${publishGateLine(run.trustDecision, opts.strict === true)}`));
   logger.log(SEP);
 }

package/lib/utils/app-path-resolve.js

@@ -0,0 +1,168 @@
+/**
+ * Resolve Connected Systems vs Enterprise Knowledge authoring trees (456.5).
+ *
+ * @fileoverview Workspace resolution from systemKind and CLI --workspace
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const {
+  WORKSPACE_ENTERPRISE_KNOWLEDGE,
+  SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  getEnterpriseKnowledgePath
+} = require('./enterprise-knowledge-paths');
+
+const WORKSPACE_INTEGRATION = 'integration';
+
+/**
+ * Reads systemKind from <app>-system.json when present.
+ * @param {string} appPath - Anchor directory
+ * @param {string} appName - Anchor key
+ * @returns {string|null}
+ */
+function readSystemKindFromAppDir(appPath, appName) {
+  if (!appPath || !appName) {
+    return null;
+  }
+  const systemFile = path.join(appPath, `${appName}-system.json`);
+  if (!fs.existsSync(systemFile)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(fs.readFileSync(systemFile, 'utf8'));
+    const kind = raw && (raw.systemKind || raw.systemKindKey);
+    return typeof kind === 'string' && kind.trim() ? kind.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} dirPath
+ * @returns {boolean}
+ */
+function isExistingDirectory(dirPath) {
+  try {
+    return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string|undefined|null} raw
+ * @returns {string|null}
+ */
+function normalizeWorkspaceOverride(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return null;
+  }
+  const v = String(raw).trim().toLowerCase();
+  if (v === WORKSPACE_INTEGRATION || v === WORKSPACE_ENTERPRISE_KNOWLEDGE) {
+    return v;
+  }
+  throw new Error(`Unknown workspace "${raw}". Use integration or enterprise-knowledge.`);
+}
+
+function workspacePair(appPath, baseDir) {
+  return { appPath, baseDir };
+}
+
+function resolveFromWorkspaceOverride(workspaceOverride, appName, getIntegrationPath) {
+  if (workspaceOverride === WORKSPACE_ENTERPRISE_KNOWLEDGE) {
+    return workspacePair(getEnterpriseKnowledgePath(appName), WORKSPACE_ENTERPRISE_KNOWLEDGE);
+  }
+  if (workspaceOverride === WORKSPACE_INTEGRATION) {
+    return workspacePair(getIntegrationPath(appName), WORKSPACE_INTEGRATION);
+  }
+  return null;
+}
+
+function resolveAmbiguousWorkspace(ekPath, intPath, explicitKind, appName) {
+  const kind =
+    explicitKind ||
+    readSystemKindFromAppDir(ekPath, appName) ||
+    readSystemKindFromAppDir(intPath, appName);
+  if (kind === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE) {
+    return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
+  }
+  return workspacePair(intPath, WORKSPACE_INTEGRATION);
+}
+
+function resolveFromExistingPaths(ekPath, intPath, ekExists, intExists, explicitKind, appName) {
+  if (ekExists && !intExists) {
+    return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
+  }
+  if (intExists && !ekExists) {
+    return workspacePair(intPath, WORKSPACE_INTEGRATION);
+  }
+  if (ekExists && intExists) {
+    return resolveAmbiguousWorkspace(ekPath, intPath, explicitKind, appName);
+  }
+  const kind = explicitKind || readSystemKindFromAppDir(intPath, appName);
+  if (kind === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE) {
+    return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
+  }
+  return workspacePair(intPath, WORKSPACE_INTEGRATION);
+}
+
+/**
+ * Resolves authoring tree for an external system or Enterprise Knowledge anchor.
+ * @param {string} appName - App or anchor key
+ * @param {Object} [options]
+ * @param {string} [options.workspace] - integration | enterprise-knowledge
+ * @param {string} [options.systemKind] - Explicit systemKind override
+ * @returns {{ appPath: string, baseDir: 'integration' | 'enterprise-knowledge' }}
+ */
+function resolveAppWorkspace(appName, options = {}) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+  const { getIntegrationPath } = require('./paths');
+  const workspaceOverride = normalizeWorkspaceOverride(options.workspace);
+  const explicitKind = typeof options.systemKind === 'string' ? options.systemKind.trim() : '';
+
+  const fromOverride = resolveFromWorkspaceOverride(
+    workspaceOverride,
+    appName,
+    getIntegrationPath
+  );
+  if (fromOverride) {
+    return fromOverride;
+  }
+
+  const ekPath = getEnterpriseKnowledgePath(appName);
+  const intPath = getIntegrationPath(appName);
+  return resolveFromExistingPaths(
+    ekPath,
+    intPath,
+    isExistingDirectory(ekPath),
+    isExistingDirectory(intPath),
+    explicitKind,
+    appName
+  );
+}
+
+/**
+ * Absolute path for external / Enterprise Knowledge anchor files.
+ * @param {string} appName
+ * @param {Object} [options]
+ * @returns {string}
+ */
+function resolveExternalSystemPath(appName, options = {}) {
+  return resolveAppWorkspace(appName, options).appPath;
+}
+
+module.exports = {
+  WORKSPACE_INTEGRATION,
+  WORKSPACE_ENTERPRISE_KNOWLEDGE,
+  SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  readSystemKindFromAppDir,
+  normalizeWorkspaceOverride,
+  resolveAppWorkspace,
+  resolveExternalSystemPath
+};

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

@@ -0,0 +1,222 @@
+/**
+ * Multi-slot authentications[] helpers for env.template repair (454.11).
+ *
+ * @fileoverview KV env names and paths per authentication usage slot
+ */
+
+'use strict';
+
+const { getAuthCredentialTemplate } = require('./authentication-shape');
+const { isPlatformCatalogKvRef, isLegacyKvValue } = require('./platform-kv-ref');
+const {
+  kvEnvKeyToPath,
+  securityKeyToVar,
+  systemKeyToKvPrefix
+} = require('./credential-secrets-env');
+const { getKvPathSegmentForSecurityKey } = require('./credential-secrets-env-kv');
+
+/**
+ * @param {string} slotKey
+ * @returns {string}
+ */
+function slotKeyToEnvSegment(slotKey) {
+  if (!slotKey || slotKey === 'default') {
+    return '';
+  }
+  return `_${String(slotKey).replace(/-/g, '_').toUpperCase()}`;
+}
+
+/**
+ * @param {string} prefix
+ * @param {string} slotKey
+ * @param {string} securityKey
+ * @returns {string}
+ */
+function buildSlotEnvName(prefix, slotKey, securityKey) {
+  return `KV_${prefix}${slotKeyToEnvSegment(slotKey)}_${securityKeyToVar(securityKey)}`;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string} slotKey
+ * @param {string} securityKey
+ * @returns {string|null}
+ */
+function buildSlotKvPath(systemKey, slotKey, securityKey) {
+  const segment = getKvPathSegmentForSecurityKey(securityKey);
+  if (!segment) {
+    return null;
+  }
+  if (slotKey && slotKey !== 'default') {
+    return `kv://${systemKey}/${slotKey}/${segment}`;
+  }
+  return `kv://${systemKey}/${segment}`;
+}
+
+/**
+ * @param {Array} effective
+ * @param {Set<string>} seenNames
+ * @param {string} systemKey
+ * @param {string} prefix
+ * @param {object} authBlock
+ * @param {string} slotKey
+ */
+function addSecurityKeysFromAuthBlock(
+  effective,
+  seenNames,
+  systemKey,
+  prefix,
+  authBlock,
+  slotKey
+) {
+  const credential = getAuthCredentialTemplate(authBlock);
+  const security = credential?.security ?? authBlock?.security;
+  if (!security || typeof security !== 'object') {
+    return;
+  }
+  for (const key of Object.keys(security)) {
+    const securityVal = security[key];
+    if (typeof securityVal === 'string' && isPlatformCatalogKvRef(securityVal)) {
+      continue;
+    }
+    const envName = buildSlotEnvName(prefix, slotKey, key);
+    if (seenNames.has(envName)) {
+      continue;
+    }
+    const pathVal =
+      kvEnvKeyToPath(envName, systemKey) || buildSlotKvPath(systemKey, slotKey, key);
+    if (!pathVal) {
+      continue;
+    }
+    effective.push({
+      name: envName,
+      value: pathVal.replace(/^kv:\/\//, ''),
+      location: 'keyvault'
+    });
+    seenNames.add(envName);
+  }
+}
+
+/**
+ * @param {Array} effective
+ * @param {object} systemParsed
+ * @param {string} prefix
+ * @param {Set<string>} seenNames
+ * @param {string} systemKey
+ */
+function addFromAuthenticationsArray(effective, systemParsed, prefix, seenNames, systemKey) {
+  const rows = systemParsed.authentications;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return;
+  }
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const slotKey = typeof row.key === 'string' && row.key.trim() ? row.key.trim() : 'default';
+    addSecurityKeysFromAuthBlock(effective, seenNames, systemKey, prefix, row, slotKey);
+  }
+}
+
+/**
+ * @param {object} system
+ * @returns {Array<{name: string, value: string, usage?: string}>}
+ */
+function buildAuthSecureVarsFromAllSlots(system) {
+  const systemKey = system?.key || 'external-system';
+  const prefix = systemKeyToKvPrefix(systemKey);
+  if (!prefix) {
+    return [];
+  }
+  const effective = [];
+  const seenNames = new Set();
+  addFromAuthenticationsArray(effective, system, prefix, seenNames, systemKey);
+  if (effective.length > 0) {
+    const rows = Array.isArray(system.authentications) ? system.authentications : [];
+    return effective.map((entry) => {
+      const suffix = entry.name.slice(`KV_${prefix}`.length);
+      const slot = rows.find((row) => {
+        const seg = slotKeyToEnvSegment(row?.key || 'default');
+        return seg && suffix.startsWith(`${seg}_`);
+      });
+      let value = entry.value;
+      if (entry.location === 'keyvault' && value && !String(value).startsWith('kv://')) {
+        value = `kv://${value}`;
+      }
+      return {
+        ...entry,
+        value,
+        usage: slot?.usage || 'api'
+      };
+    });
+  }
+  return [];
+}
+
+/**
+ * @param {object} security
+ * @param {string} prefix
+ * @param {string} systemKey
+ * @param {string} slotKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function normalizeAuthSlotSecurity(security, prefix, systemKey, slotKey, changes) {
+  let updated = false;
+  for (const key of Object.keys(security)) {
+    const val = security[key];
+    if (typeof val !== 'string' || !isLegacyKvValue(val)) {
+      continue;
+    }
+    const envName = buildSlotEnvName(prefix, slotKey, key);
+    const pathVal = kvEnvKeyToPath(envName, systemKey) || buildSlotKvPath(systemKey, slotKey, key);
+    if (pathVal) {
+      security[key] = pathVal;
+      changes.push(
+        `authentications[${slotKey}].security.${key}: normalized to path-style ${pathVal}`
+      );
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * @param {object} systemParsed
+ * @param {string} systemKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function normalizeAuthenticationsSecurity(systemParsed, systemKey, changes) {
+  const prefix = systemKeyToKvPrefix(systemKey);
+  if (!prefix) {
+    return false;
+  }
+  const rows = systemParsed.authentications;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    return false;
+  }
+  let updated = false;
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') {
+      continue;
+    }
+    const slotKey = typeof row.key === 'string' && row.key.trim() ? row.key.trim() : 'default';
+    const credential = getAuthCredentialTemplate(row);
+    const security = credential?.security ?? row.security;
+    if (security && typeof security === 'object') {
+      updated =
+        normalizeAuthSlotSecurity(security, prefix, systemKey, slotKey, changes) || updated;
+    }
+  }
+  return updated;
+}
+
+module.exports = {
+  addFromAuthenticationsArray,
+  buildAuthSecureVarsFromAllSlots,
+  buildSlotEnvName,
+  buildSlotKvPath,
+  normalizeAuthenticationsSecurity,
+  slotKeyToEnvSegment
+};

package/lib/utils/cli-sync-options.js

@@ -1,33 +1,29 @@
 /**
- * @fileoverview Detect skip-sync from Commander options and raw argv (--no-sync → sync: false).
+ * @fileoverview Detect skip-manifest-publish from Commander options (--no-publish).
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 2.0.0
  */
 
 'use strict';
 
 /**
- * True when the user passed `--no-sync` or Commander set `sync: false` / `noSync: true`.
- * Do not use for `protection upload --no-sync` (post-upload datasource sync only).
+ * True when the user passed `--no-publish` or set `noPublish: true` (programmatic).
  *
  * @param {Object|null|undefined} options - Commander-parsed options
  * @param {import('commander').Command} [cmd] - Commander command (for rawArgs fallback)
  * @returns {boolean}
  */
-function cliOptsSkipSync(options, cmd) {
+function cliOptsSkipPublish(options, cmd) {
   if (!options || typeof options !== 'object') {
     return false;
   }
-  if (options.noSync === true) {
-    return true;
-  }
-  if (options.sync === false) {
+  if (options.noPublish === true) {
     return true;
   }
   const raw = cmd && Array.isArray(cmd.rawArgs) ? cmd.rawArgs : [];
-  return raw.includes('--no-sync');
+  return raw.includes('--no-publish');
 }
 
 module.exports = {
-  cliOptsSkipSync
+  cliOptsSkipPublish
 };

package/lib/utils/cli-utils.js

@@ -336,6 +336,10 @@ function tryFormatErrorWithFormatters(errorMsg) {
 }
 
 function formatError(error) {
+  if (error && error.gateFailure === true) {
+    return [`   ${error.message || 'Deploy gate failed'}`];
+  }
+
   // If error has formatted message (from API error handler), use it directly
   if (error.formatted) {
     return formatFormattedError(error.formatted);

package/lib/utils/cli-workspace-options.js

@@ -0,0 +1,29 @@
+/**
+ * CLI workspace helpers (456.5) — auto-detect only; `--workspace` flag removed in 155.0.
+ *
+ * @fileoverview Path options for external / Enterprise Knowledge anchors
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} [_cliOptions]
+ * @returns {{}}
+ */
+function workspaceDetectionOptions(_cliOptions = {}) {
+  return {};
+}
+
+/**
+ * @returns {null}
+ */
+function workspaceOptionDefinition() {
+  return null;
+}
+
+module.exports = {
+  workspaceDetectionOptions,
+  workspaceOptionDefinition
+};

package/lib/utils/compose-generate-docker-compose.js

@@ -12,6 +12,11 @@ const fsSync = require('fs');
 const path = require('path');
 const buildCopy = require('./build-copy');
 const paths = require('./paths');
+const { isSystemBuilderAppName } = require('./paths-system-builder-keys');
+const {
+  isValidReloadSourceRoot,
+  resolveSystemAppReloadSourceRoot
+} = require('./paths-reload-source');
 const { getInfraDirName } = require('../infrastructure/helpers');
 const { resolveMisoEnvironment } = require('./compose-miso-env');
 const { buildCeleryWorkerComposeContext } = require('./compose-celery-worker');
@@ -131,11 +136,106 @@ function resolveInfraPgpassPath(devId, pathsUtil, existsSyncFn = fsSync.existsSy
       : sysPgpass;
 }
 
+/**
+ * Builder manifest paths to try when resolving storage mount source (CI-safe order).
+ *
+ * @param {string} appName
+ * @returns {string[]}
+ */
+function collectComposeBuilderPathCandidates(appName) {
+  const candidates = [];
+  const seen = new Set();
+  const push = (candidate) => {
+    if (candidate && typeof candidate === 'string' && !seen.has(candidate)) {
+      seen.add(candidate);
+      candidates.push(candidate);
+    }
+  };
+  push(paths.getCwdBuilderAppPath(appName));
+  const projectRoot = paths.getProjectRoot();
+  if (projectRoot) {
+    push(path.join(projectRoot, 'builder', appName));
+  }
+  try {
+    push(paths.getBuilderPath(appName));
+  } catch {
+    // materialized builder path unavailable in this environment
+  }
+  return candidates;
+}
+
+/**
+ * @param {string} appName
+ * @param {string} buildContext
+ * @returns {string|null}
+ */
+function resolveStorageMountSourceRoot(appName, buildContext) {
+  for (const builderPath of collectComposeBuilderPathCandidates(appName)) {
+    const sourceRoot = resolveSystemAppReloadSourceRoot(appName, builderPath, buildContext);
+    if (!isSystemBuilderAppName(appName) || isValidReloadSourceRoot(appName, sourceRoot)) {
+      return sourceRoot;
+    }
+  }
+  const projectRoot = paths.getProjectRoot();
+  if (
+    projectRoot &&
+    (!isSystemBuilderAppName(appName) || isValidReloadSourceRoot(appName, projectRoot))
+  ) {
+    return projectRoot;
+  }
+  return null;
+}
+
+/**
+ * Host `mount/` directory bind-mounted to `/mnt/data` when storage is required.
+ *
+ * @param {object} ctx - Compose template context (`devMountPath`, `appName`, `appConfig`, `serviceConfig`)
+ * @returns {string|null}
+ */
+function resolveLocalDataMountPathForCompose(ctx) {
+  if (ctx.devMountPath && typeof ctx.devMountPath === 'string') {
+    return path.join(ctx.devMountPath, 'mount').replace(/\\/g, '/');
+  }
+  const requiresStorage =
+    ctx.serviceConfig?.requiresStorage ||
+    ctx.appConfig?.requires?.storage ||
+    ctx.appConfig?.services?.storage ||
+    false;
+  if (!requiresStorage || !ctx.appName) {
+    return null;
+  }
+  try {
+    const sourceRoot = resolveStorageMountSourceRoot(
+      ctx.appName,
+      ctx.appConfig?.build?.context || '../..'
+    );
+    if (!sourceRoot) {
+      return null;
+    }
+    return path.join(sourceRoot, 'mount').replace(/\\/g, '/');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {object} ctx - Template context fields
  * @returns {object} Spread-ready payload for Handlebars template
  */
 function buildComposeTemplateContext(ctx) {
+  const localDataMountPath = resolveLocalDataMountPathForCompose(ctx);
+  const requiresStorage =
+    ctx.serviceConfig?.requiresStorage ||
+    ctx.appConfig?.requires?.storage ||
+    ctx.appConfig?.services?.storage ||
+    false;
+  if (localDataMountPath && requiresStorage && !fsSync.existsSync(localDataMountPath)) {
+    try {
+      fsSync.mkdirSync(localDataMountPath, { recursive: true });
+    } catch {
+      // Non-fatal: tests may use non-writable devMountPath; host must create mount/ before run.
+    }
+  }
   return {
     ...ctx.serviceConfig,
     ...ctx.volumesConfig,
@@ -150,6 +250,7 @@ function buildComposeTemplateContext(ctx) {
     containerName: ctx.containerName,
     misoEnvironment: resolveMisoEnvironment(ctx.options),
     devMountPath: ctx.devMountPath,
+    localDataMountPath,
     reloadStartCommand: ctx.reloadStartCommand,
     infraPgpassPath: ctx.useInfraPgpass ? ctx.infraPgpassPath : null,
     useInfraPgpass: !!ctx.useInfraPgpass,
@@ -339,6 +440,7 @@ function createGenerateDockerCompose(deps) {
 module.exports = {
   createGenerateDockerCompose,
   resolveInfraPgpassPath,
+  resolveLocalDataMountPathForCompose,
   derivePythonImageStartFromReload,
   buildReloadStartCommandForCompose,
   normalizePythonReloadForComposeMounted