@aifabrix/builder 2.51.1 → 2.52.0

package/lib/generator/builders.js

@@ -27,24 +27,18 @@ function sanitizeAuthType(authType) {
 }
 
 /**
- * Filters configuration based on registry mode
- * When registryMode is "external", only DOCKER_REGISTRY_SERVER_* variables are allowed
+ * Historically (incorrectly) stripped all non-DOCKER_REGISTRY_* vars when
+ * registryMode was "external", which wiped platform app env/portal config on
+ * `aifabrix json`. External only means image pull source — keep full configuration.
+ * DOCKER_REGISTRY_SERVER_* may still appear when present in env.template.
+ *
  * @function filterConfigurationByRegistryMode
  * @param {Array} configuration - Environment configuration
- * @param {string} registryMode - Registry mode ('external' or 'internal')
- * @returns {Array} Filtered configuration
+ * @param {string} _registryMode - Registry mode ('external' or 'acr'); unused
+ * @returns {Array} Configuration unchanged
  */
-function filterConfigurationByRegistryMode(configuration, registryMode) {
-  if (registryMode !== 'external') {
-    return configuration;
-  }
-
-  const allowedDockerRegistryVars = [
-    'DOCKER_REGISTRY_SERVER_URL',
-    'DOCKER_REGISTRY_SERVER_USERNAME',
-    'DOCKER_REGISTRY_SERVER_PASSWORD'
-  ];
-  return configuration.filter(config => allowedDockerRegistryVars.includes(config.name));
+function filterConfigurationByRegistryMode(configuration, _registryMode) {
+  return Array.isArray(configuration) ? configuration : [];
 }
 
 function buildImageReference(variables) {

package/lib/role-assistant/knowledge-markdown-frontmatter.js

@@ -0,0 +1,75 @@
+/**
+ * Parse optional YAML frontmatter from Role Assistant knowledge markdown.
+ *
+ * @fileoverview knowledge-markdown-frontmatter
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const yaml = require('js-yaml');
+
+const SEARCH_META_KEYS = [
+  'aspect',
+  'knowledgeType',
+  'knowledgeKey',
+  'title',
+  'resourceType',
+  'roleKey'
+];
+
+/**
+ * Split markdown into optional YAML frontmatter and body.
+ * @param {string} content
+ * @returns {{ frontmatter: Object|null, body: string }}
+ */
+function splitMarkdownFrontmatter(content) {
+  const text = typeof content === 'string' ? content : '';
+  if (!text.startsWith('---')) {
+    return { frontmatter: null, body: text };
+  }
+  const end = text.indexOf('\n---', 3);
+  if (end < 0) {
+    return { frontmatter: null, body: text };
+  }
+  const raw = text.slice(3, end).trim();
+  const body = text.slice(end + 4).replace(/^(?:\r?\n)+/, '');
+  if (!raw) {
+    return { frontmatter: {}, body };
+  }
+  try {
+    const parsed = yaml.load(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { frontmatter: null, body: text };
+    }
+    return { frontmatter: parsed, body };
+  } catch (_error) {
+    return { frontmatter: null, body: text };
+  }
+}
+
+/**
+ * Project searchable metadata fields from frontmatter.
+ * @param {Object|null|undefined} frontmatter
+ * @returns {Object}
+ */
+function knowledgeSearchMetadataFromFrontmatter(frontmatter) {
+  const out = {};
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    return out;
+  }
+  for (const key of SEARCH_META_KEYS) {
+    const value = frontmatter[key];
+    if (typeof value === 'string' && value.trim()) {
+      out[key] = value.trim();
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  SEARCH_META_KEYS,
+  splitMarkdownFrontmatter,
+  knowledgeSearchMetadataFromFrontmatter
+};

package/lib/role-assistant/knowledge-sync.js

@@ -28,6 +28,10 @@ const {
   resolveDocumentStorageKeyFromRoleAssistantSettings,
   resolveRoleAssistantEnvironmentSettings
 } = require('./settings');
+const {
+  knowledgeSearchMetadataFromFrontmatter,
+  splitMarkdownFrontmatter
+} = require('./knowledge-markdown-frontmatter');
 
 function resolveSystemNode(input) {
   if (!input || typeof input !== 'object') {
@@ -108,6 +112,15 @@ async function pushRoleAssistantDocumentStorageSettings(params) {
       documentStorageKey: documentStorageKey || null
     };
   }
+  if (documentStorageKey === '') {
+    // No Knowledge binding in role-assistant.yaml — skip Assistants settings write.
+    // Draft / not-yet-catalogued digital workers would 404 on PATCH otherwise.
+    return {
+      skipped: true,
+      reason: 'no-document-storage-key',
+      documentStorageKey: null
+    };
+  }
   if (!dataplaneUrl || !authConfig) {
     return { skipped: true, reason: 'missing-dataplane-auth' };
   }
@@ -182,20 +195,27 @@ function normalizeDocumentExternalId(knowledgeRoot, filePath) {
 }
 
 function buildDocumentRecord(knowledgeRoot, filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = splitMarkdownFrontmatter(raw);
+  const searchMeta = knowledgeSearchMetadataFromFrontmatter(frontmatter);
   const externalId = normalizeDocumentExternalId(knowledgeRoot, filePath);
-  const title = path.basename(externalId);
+  const title =
+    (typeof searchMeta.title === 'string' && searchMeta.title) || path.basename(externalId);
+  const content = typeof body === 'string' ? body : raw;
   const contentHash = crypto.createHash('sha256').update(content, 'utf8').digest('hex');
   const metadata = {
     externalId,
-    title,
     mimeType: 'text/markdown',
     sourcePath: path.relative(knowledgeRoot, filePath).replace(/\\/g, '/'),
-    sourceType: 'role-assistant-markdown'
+    sourceType: 'role-assistant-markdown',
+    ...searchMeta,
+    title
   };
   return {
     key: externalId,
-    name: title,
+    // Prefer sourcePath (*.md) so binary storage uses a known markdown extension
+    // instead of inventing ".guide" from path-like keys or titles.
+    name: metadata.sourcePath || `${externalId}.md`,
     contentHash,
     metadata,
     binaryBase64: Buffer.from(content, 'utf8').toString('base64'),

package/lib/role-assistant/test-runner-workhub-answers.js

@@ -88,40 +88,58 @@ function fillFieldsFromHints(fields, hints) {
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
-function synthesizeFromCapability(capability, hints) {
+function _synthContactFields(hints) {
+  const out = {};
+  if (hints.email) {
+    out.email = hints.email;
+  }
+  if (hints.name || hints.email) {
+    out.firstname = String(hints.email || 'user').split('@')[0];
+    out.lastname = hints.name || 'Contact';
+  }
+  return out;
+}
+
+function _synthCustomerFields(hints) {
+  const out = {};
+  if (hints.name) {
+    out.name = hints.name;
+  }
+  if (hints.domain) {
+    out.domain = hints.domain;
+  }
+  if (hints.address) {
+    out.address = hints.address;
+  }
+  return out;
+}
+
+function _synthDefaultFields(hints) {
   const out = {};
+  if (hints.name) {
+    out.name = hints.name;
+  }
+  if (hints.email) {
+    out.email = hints.email;
+  }
+  if (hints.domain) {
+    out.domain = hints.domain;
+  }
+  return out;
+}
+
+function synthesizeFromCapability(capability, hints) {
+  let out = {};
   if (capability.includes('contact')) {
-    if (hints.email) {
-      out.email = hints.email;
-    }
-    if (hints.name || hints.email) {
-      out.firstname = String(hints.email || 'user').split('@')[0];
-      out.lastname = hints.name || 'Contact';
-    }
+    out = _synthContactFields(hints);
   } else if (capability.includes('deal')) {
     if (hints.name) {
       out.dealname = hints.name;
     }
   } else if (capability.includes('customer') || capability.includes('compan')) {
-    if (hints.name) {
-      out.name = hints.name;
-    }
-    if (hints.domain) {
-      out.domain = hints.domain;
-    }
-    if (hints.address) {
-      out.address = hints.address;
-    }
+    out = _synthCustomerFields(hints);
   } else {
-    if (hints.name) {
-      out.name = hints.name;
-    }
-    if (hints.email) {
-      out.email = hints.email;
-    }
-    if (hints.domain) {
-      out.domain = hints.domain;
-    }
+    out = _synthDefaultFields(hints);
   }
   return Object.keys(out).length > 0 ? out : undefined;
 }

package/lib/role-assistant/test-runner-workhub.js

@@ -180,23 +180,25 @@ async function createActivateAcceptPlan(dataplaneUrl, authConfig, planBody, assi
   throw lastError || new Error('Work Hub plan create/activate/accept failed.');
 }
 
-async function maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
+function _approveGateDecision(ctx) {
   if (ctx.approveStopped) {
-    return;
+    return 'skip';
   }
   const status = String(ctx.status || '').trim().toLowerCase();
   if (status !== 'pendingapproval' && status !== 'pending_approval') {
-    return;
+    return 'skip';
   }
   const approvalState = String(ctx.taskRow?.approvalState || '').trim().toLowerCase();
   if (approvalState && approvalState !== 'pending') {
-    ctx.approveStopped = true;
-    return;
+    return 'stop';
   }
   if ((Number(ctx.approveAttempts) || 0) >= 8) {
-    ctx.approveStopped = true;
-    return;
+    return 'stop';
   }
+  return 'run';
+}
+
+async function _attemptApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
   try {
     await approveWorkTask(dataplaneUrl, authConfig, taskId, {});
     ctx.interactions.push({ type: 'approve', taskId, attempt: ctx.approveAttempts });
@@ -211,6 +213,18 @@ async function maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
   }
 }
 
+async function maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
+  const gate = _approveGateDecision(ctx);
+  if (gate === 'skip') {
+    return;
+  }
+  if (gate === 'stop') {
+    ctx.approveStopped = true;
+    return;
+  }
+  await _attemptApproveTask(dataplaneUrl, authConfig, taskId, ctx);
+}
+
 async function maybeRespondWaiting(dataplaneUrl, authConfig, taskRow, testCase, interactions) {
   const peId = extractPeFromTask(taskRow);
   if (!peId) {

package/lib/schema/application-schema.json

@@ -7,12 +7,12 @@
     "key": "application-schema",
     "name": "Application Configuration Schema",
     "description": "JSON schema for validating AI Fabrix application configuration files",
-    "version": "1.6.0",
+    "version": "1.6.1",
     "type": "schema",
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-07-28T00:00:00Z",
+    "updatedAt": "2026-08-03T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -30,6 +30,14 @@
       "external-datasource.schema.json"
     ],
     "changelog": [
+      {
+        "version": "1.6.1",
+        "date": "2026-08-03T00:00:00Z",
+        "changes": [
+          "registryMode external no longer restricts configuration item names to DOCKER_REGISTRY_SERVER_*; external is image pull source only and full env/portal configuration remains valid."
+        ],
+        "breaking": false
+      },
       {
         "version": "1.6.0",
         "date": "2026-07-28T00:00:00Z",
@@ -974,32 +982,6 @@
           "databases"
         ]
       }
-    },
-    {
-      "if": {
-        "properties": {
-          "registryMode": {
-            "const": "external"
-          }
-        }
-      },
-      "then": {
-        "properties": {
-          "configuration": {
-            "items": {
-              "properties": {
-                "name": {
-                  "enum": [
-                    "DOCKER_REGISTRY_SERVER_URL",
-                    "DOCKER_REGISTRY_SERVER_USERNAME",
-                    "DOCKER_REGISTRY_SERVER_PASSWORD"
-                  ]
-                }
-              }
-            }
-          }
-        }
-      }
     }
   ]
 }

package/lib/schema/infra.parameter.yaml

@@ -340,26 +340,6 @@ parameters:
       vaultSecretName: dataplane-client-secretKeyVault
       notes: Per-app OAuth client secret for dataplane; generated on first ensure.
 
-  - key: mori-controller-client-idKeyVault
-    scope: app
-    generator:
-      type: literal
-      value: 'miso-controller-dev-mori-controller'
-    ensureOn: [upInfra, resolveApp]
-    azure:
-      notes: >-
-        Per-app OAuth client id from controller registration; literal default matches
-        {controllerId}-{environmentKey}-{applicationKey} (override per environment).
-
-  - key: mori-controller-client-secretKeyVault
-    scope: app
-    generator:
-      type: randomBytes32
-    ensureOn: [upInfra, resolveApp]
-    azure:
-      vaultSecretName: mori-controller-client-secretKeyVault
-      notes: Per-app OAuth client secret for mori-controller; generated on first ensure.
-
   # Mori / telemetry: optional locally (LICENSE_JWT via miso-controller-jwt-licenseKeyVault=DEVELOPMENT skips Mori).
   # MORI_AUTH_METHOD=kv://mori-controller-auth-methodKeyVault — local default apiKey.
   - key: mori-controller-auth-methodKeyVault

package/lib/utils/certify-external-workspace.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Workspace roots allowed for external certify / verify CLI commands.
+ */
+
+'use strict';
+
+const CERTIFY_EXTERNAL_BASE_DIRS = new Set([
+  'integration',
+  'role-assistant',
+  'enterprise-knowledge'
+]);
+
+/**
+ * @param {string|null|undefined} baseDir
+ * @returns {boolean}
+ */
+function isCertifyExternalWorkspace(baseDir) {
+  return CERTIFY_EXTERNAL_BASE_DIRS.has(baseDir);
+}
+
+/**
+ * @param {string|null|undefined} baseDir
+ * @param {string} commandLabel - e.g. verify-operations
+ * @returns {void}
+ * @throws {Error}
+ */
+function assertCertifyExternalWorkspace(baseDir, commandLabel) {
+  if (!isCertifyExternalWorkspace(baseDir)) {
+    throw new Error(
+      `${commandLabel} applies to external authoring folders only ` +
+        '(integration/<systemKey>/, role-assistant/<roleKey>/, or enterprise-knowledge/<key>/).'
+    );
+  }
+}
+
+module.exports = {
+  CERTIFY_EXTERNAL_BASE_DIRS,
+  isCertifyExternalWorkspace,
+  assertCertifyExternalWorkspace
+};

package/lib/utils/docker-run-ephemeral.js

@@ -16,8 +16,12 @@ const { getDockerExecEnv } = require('./remote-docker-env');
  * @param {string} fullImage - Image:tag
  * @param {string} cmd - Shell command (passed to sh -c)
  * @param {string|null} [envFilePath] - Path for docker run --env-file
- * @param {{ network?: string|null, volumeMounts?: Array<{ host: string, container: string }> }} [options]
- * @returns {Promise<number>} Exit code
+ * @param {{
+ *   network?: string|null,
+ *   volumeMounts?: Array<{ host: string, container: string }>,
+ *   quiet?: boolean
+ * }} [options] - quiet=true pipes stdio (installer-friendly; dump on failure)
+ * @returns {Promise<number|{ code: number, output: string }>} Exit code, or code+output when quiet
  */
 async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null, options = {}) {
   const dockerEnv = await getDockerExecEnv();
@@ -26,22 +30,48 @@ async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null, options
       ? options.network.trim()
       : null;
   const volumeMounts = Array.isArray(options?.volumeMounts) ? options.volumeMounts : [];
-  return new Promise((resolve) => {
-    const args = ['run', '--rm'];
-    if (network) {
-      args.push('--network', network);
-    }
-    if (envFilePath) {
-      args.push('--env-file', envFilePath);
-    }
-    for (const mount of volumeMounts) {
-      const host = typeof mount?.host === 'string' ? mount.host.trim() : '';
-      const container = typeof mount?.container === 'string' ? mount.container.trim() : '';
-      if (host && container) {
-        args.push('-v', `${host}:${container}`);
-      }
+  const quiet = options?.quiet === true;
+  const args = _buildDockerRunArgs(fullImage, cmd, envFilePath, network, volumeMounts);
+  if (quiet) {
+    return _spawnDockerQuiet(args, dockerEnv);
+  }
+  return _spawnDockerInherit(args, dockerEnv);
+}
+
+/**
+ * @param {string} fullImage
+ * @param {string} cmd
+ * @param {string|null} envFilePath
+ * @param {string|null} network
+ * @param {Array<{ host: string, container: string }>} volumeMounts
+ * @returns {string[]}
+ */
+function _buildDockerRunArgs(fullImage, cmd, envFilePath, network, volumeMounts) {
+  const args = ['run', '--rm'];
+  if (network) {
+    args.push('--network', network);
+  }
+  if (envFilePath) {
+    args.push('--env-file', envFilePath);
+  }
+  for (const mount of volumeMounts) {
+    const host = typeof mount?.host === 'string' ? mount.host.trim() : '';
+    const container = typeof mount?.container === 'string' ? mount.container.trim() : '';
+    if (host && container) {
+      args.push('-v', `${host}:${container}`);
     }
-    args.push(fullImage, 'sh', '-c', cmd);
+  }
+  args.push(fullImage, 'sh', '-c', cmd);
+  return args;
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} dockerEnv
+ * @returns {Promise<number>}
+ */
+function _spawnDockerInherit(args, dockerEnv) {
+  return new Promise((resolve) => {
     const proc = spawn('docker', args, {
       stdio: 'inherit',
       shell: false,
@@ -52,4 +82,34 @@ async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null, options
   });
 }
 
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} dockerEnv
+ * @returns {Promise<{ code: number, output: string }>}
+ */
+function _spawnDockerQuiet(args, dockerEnv) {
+  return new Promise((resolve) => {
+    const proc = spawn('docker', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false,
+      env: dockerEnv
+    });
+    const chunks = [];
+    const push = (buf) => {
+      if (buf && buf.length) {
+        chunks.push(buf);
+      }
+    };
+    proc.stdout.on('data', push);
+    proc.stderr.on('data', push);
+    proc.on('close', (code) => {
+      resolve({
+        code: code !== null ? code : 1,
+        output: Buffer.concat(chunks).toString('utf8')
+      });
+    });
+    proc.on('error', () => resolve({ code: 1, output: '' }));
+  });
+}
+
 module.exports = { runDockerRunEphemeral };

package/lib/utils/health-check-public-warn.js

@@ -38,32 +38,50 @@ async function filterTraefikUrlByDns(traefikUrl, debug, isHostnameResolvableFn)
  * @param {string} [p.skippedPublicHealthUrl]
  * @param {string[]} [p.urlsToTry]
  * @param {number} p.resolvedIndex
+ * @returns {string|null} Warning message without leading glyph, or null
  */
-function logPublicHealthUrlWarningIfNeeded(p) {
+function buildPublicHealthUrlWarningMessage(p) {
   const { skippedPublicHealthUrl, urlsToTry, resolvedIndex } = p;
-  if (typeof resolvedIndex !== 'number' || resolvedIndex < 0) return;
+  if (typeof resolvedIndex !== 'number' || resolvedIndex < 0) return null;
 
   if (skippedPublicHealthUrl) {
-    logger.log(
-      chalk.yellow(
-        `⚠ Public URL was not verified (DNS): ${skippedPublicHealthUrl}. ` +
-          'The application reported healthy via localhost only. Validate DNS names and Traefik routing for this host.'
-      )
+    return (
+      `Public URL was not verified (DNS): ${skippedPublicHealthUrl}. ` +
+      'The application reported healthy via localhost only. Validate DNS names and Traefik routing for this host.'
     );
-    return;
   }
   if (Array.isArray(urlsToTry) && urlsToTry.length > 1 && resolvedIndex > 0) {
     const pub = urlsToTry[0];
-    logger.log(
-      chalk.yellow(
-        `⚠ Public URL was not verified: ${pub}. ` +
-          'Health checks succeeded via localhost only. Validate Traefik routing, TLS, and DNS.'
-      )
+    return (
+      `Public URL was not verified: ${pub}. ` +
+      'Health checks succeeded via localhost only. Validate Traefik routing, TLS, and DNS.'
     );
   }
+  return null;
+}
+
+/**
+ * @param {Object} p
+ * @param {string} [p.skippedPublicHealthUrl]
+ * @param {string[]} [p.urlsToTry]
+ * @param {number} p.resolvedIndex
+ * @param {boolean} [p.defer]
+ * @param {(message: string) => void} [p.onDeferred]
+ */
+function logPublicHealthUrlWarningIfNeeded(p) {
+  const message = buildPublicHealthUrlWarningMessage(p);
+  if (!message) return;
+  if (p && p.defer === true) {
+    if (typeof p.onDeferred === 'function') {
+      p.onDeferred(message);
+    }
+    return;
+  }
+  logger.log(chalk.yellow(`⚠ ${message}`));
 }
 
 module.exports = {
   filterTraefikUrlByDns,
+  buildPublicHealthUrlWarningMessage,
   logPublicHealthUrlWarningIfNeeded
 };

package/lib/utils/health-check.js

@@ -339,6 +339,14 @@ function resolveHealthCheckPollOptions(runOptions = {}) {
   if (typeof runOptions.onPollText === 'function') {
     pollOptions.onPollText = runOptions.onPollText;
   }
+  const defer =
+    runOptions.deferPublicUrlWarning === true || typeof runOptions.onPollText === 'function';
+  if (defer) {
+    pollOptions.deferPublicUrlWarning = true;
+    if (typeof runOptions.onDeferredPublicUrlWarning === 'function') {
+      pollOptions.onDeferredPublicUrlWarning = runOptions.onDeferredPublicUrlWarning;
+    }
+  }
   return pollOptions;
 }
 
@@ -367,7 +375,9 @@ async function pollUntilHealthCheckPasses({
       logPublicHealthUrlWarningIfNeeded({
         skippedPublicHealthUrl,
         urlsToTry,
-        resolvedIndex: attemptResult.resolvedIndex
+        resolvedIndex: attemptResult.resolvedIndex,
+        defer: pollOptions.deferPublicUrlWarning === true,
+        onDeferred: pollOptions.onDeferredPublicUrlWarning
       });
       return;
     }