@aifabrix/builder 2.61.2 → 2.62.0

package/lib/api/applications.api.js

@@ -202,6 +202,26 @@ async function getApplicationStatus(controllerUrl, envKey, appKey, authConfig) {
   );
 }
 
+/**
+ * Update the authenticated application's own runtime status and URLs.
+ * POST /api/v1/environments/{envKey}/applications/self/status
+ * @requiresPermission {Controller} Application client token
+ * @async
+ * @function updateApplicationSelfStatus
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} envKey - Environment key
+ * @param {Object} authConfig - Client-token authentication configuration
+ * @param {Object} statusData - Runtime status payload
+ * @returns {Promise<Object>} Updated application response
+ * @throws {Error} If request fails
+ */
+async function updateApplicationSelfStatus(controllerUrl, envKey, authConfig, statusData) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/environments/${envKey}/applications/self/status`, {
+    body: statusData
+  });
+}
+
 module.exports = {
   listApplications,
   createApplication,
@@ -211,6 +231,6 @@ module.exports = {
   registerApplication,
   bootstrapApplication,
   rotateApplicationSecret,
-  getApplicationStatus
+  getApplicationStatus,
+  updateApplicationSelfStatus
 };
-

package/lib/api/bootstrap-snapshot.api.js

@@ -0,0 +1,115 @@
+/**
+ * `POST /api/v1/auth/bootstrap` — an application's resolved configuration (Miso 257.0).
+ *
+ * This is what removes the drift. Miso generates an environment's variables through the same
+ * catalog and reconciliation it uses for Azure, holds them in whichever store the deployment
+ * calls for — Key Vault, or encrypted in `Environment.configuration` for a local install —
+ * and hands back the resolved set. Builder stops generating values and stops deriving secret
+ * names, so there is one generator, one naming rule and one record.
+ *
+ * **The caller is the application, not the operator.** A client id and secret are provisioned
+ * with the application itself, so there is no chicken-and-egg: they exchange for a client
+ * token at `/api/v1/auth/token`, which needs no prior authentication. The token carries the
+ * application and environment, which means the snapshot is server-assigned — an application
+ * cannot ask for another application's configuration, because it cannot mint a token naming
+ * one. Builder passes credentials it already holds and is told what that application gets.
+ *
+ * **`success === true` is load-bearing.** Miso writes this envelope out explicitly rather than
+ * through the helper every neighbouring route uses, because that helper omits `success` and a
+ * consumer treats its absence as a protocol error. Checking it here keeps Builder honest with
+ * the same contract the SDK enforces.
+ *
+ * @fileoverview Fetch an application's bootstrap configuration snapshot from Miso
+ */
+
+'use strict';
+
+/** The only protocol version the endpoint accepts. */
+const BOOTSTRAP_PROTOCOL_VERSION = 1;
+
+/**
+ * @param {string} controllerUrl - Controller base URL
+ * @returns {string} Without a trailing slash
+ */
+function normalizeControllerUrl(controllerUrl) {
+  return String(controllerUrl || '').trim().replace(/\/+$/, '');
+}
+
+/**
+ * Exchange an application's client credentials for a client token.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller base URL
+ * @param {{ clientId: string, clientSecret: string }} credentials - Application credentials
+ * @param {Function} [makeApiCall] - Injected transport
+ * @returns {Promise<string>} The client token
+ * @throws {Error} When the exchange fails or returns no token
+ */
+async function exchangeClientToken(controllerUrl, credentials, makeApiCall) {
+  const call = makeApiCall || require('../utils/api').makeApiCall;
+  const response = await call(`${normalizeControllerUrl(controllerUrl)}/api/v1/auth/token`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-client-id': credentials.clientId,
+      'x-client-secret': credentials.clientSecret
+    }
+  });
+  if (!response || response.success !== true) {
+    throw new Error(
+      `Could not authenticate as ${credentials.clientId}: ${(response && response.error) || 'request failed'}`
+    );
+  }
+  const data = response.data || {};
+  const token = data.token || data.data?.token || data.accessToken;
+  if (!token) {
+    // Names the client, never the secret, because this message reaches the terminal.
+    throw new Error(`Authentication for ${credentials.clientId} returned no token`);
+  }
+  return token;
+}
+
+/**
+ * Fetch an application's resolved configuration for its environment.
+ *
+ * @async
+ * @param {string} controllerUrl - Controller base URL
+ * @param {{ clientId: string, clientSecret: string }} credentials - Application credentials
+ * @param {Object} [deps] - Injected collaborators
+ * @returns {Promise<{ configuration: Object, context: Object, issuedAt: string }>} The snapshot
+ * @throws {Error} When authentication fails, or the snapshot is refused or malformed
+ */
+async function fetchBootstrapSnapshot(controllerUrl, credentials, deps = {}) {
+  if (!credentials || !credentials.clientId || !credentials.clientSecret) {
+    throw new Error('Client id and secret are required to fetch a bootstrap snapshot');
+  }
+  const call = deps.makeApiCall || require('../utils/api').makeApiCall;
+  const token = await exchangeClientToken(controllerUrl, credentials, call);
+  const response = await call(`${normalizeControllerUrl(controllerUrl)}/api/v1/auth/bootstrap`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify({ protocolVersion: BOOTSTRAP_PROTOCOL_VERSION })
+  });
+  if (!response || response.success !== true) {
+    throw new Error(
+      `Miso refused a configuration snapshot for ${credentials.clientId}: ` +
+        `${(response && response.error) || 'request failed'}`
+    );
+  }
+  const snapshot = response.data && response.data.data ? response.data.data : response.data;
+  if (!snapshot || typeof snapshot.configuration !== 'object' || snapshot.configuration === null) {
+    throw new Error(
+      `Miso returned a snapshot with no configuration for ${credentials.clientId}`
+    );
+  }
+  return snapshot;
+}
+
+module.exports = {
+  BOOTSTRAP_PROTOCOL_VERSION,
+  exchangeClientToken,
+  fetchBootstrapSnapshot
+};

package/lib/app/deploy.js

@@ -191,12 +191,21 @@ async function handleDeploymentError(error, appName, controllerUrl, usedExternal
  * @throws {Error} If image is missing or has no registry
  */
 function validateImageIsPullable(imageRef, appName) {
-  if (!imageRef || !imageRef.includes('/')) {
-    const hint = `Set image.registry and image.tag in builder/${appName}/application.yaml, or pass a full image ref (e.g. --image <registry>/${appName}:<tag>) when deploying`;
-    throw new Error(
-      `Deployed image must be pullable (include a registry). Current image: "${imageRef || 'none'}". ${hint}`
-    );
+  if (imageRef && imageRef.includes('/')) {
+    return;
+  }
+  // No registry configured means the installation deploys the application.yaml image as it
+  // stands, from the local Docker daemon. Demanding a registry component here would make a
+  // local install impossible for the one case it is meant to serve. A configured registry
+  // still has to appear in the reference, because then the image is expected to be pullable.
+  const { readInstallationRegistrySync } = require('../utils/config-registry-preference');
+  if (!readInstallationRegistrySync()) {
+    return;
   }
+  const hint = `Set image.registry and image.tag in builder/${appName}/application.yaml, or pass a full image ref (e.g. --image <registry>/${appName}:<tag>) when deploying`;
+  throw new Error(
+    `Deployed image must be pullable (include a registry). Current image: "${imageRef || 'none'}". ${hint}`
+  );
 }
 
 /**

package/lib/app/run-env-compose.js

@@ -13,6 +13,7 @@ const path = require('path');
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const pathsUtil = require('../utils/paths');
+const { isScopeActiveForOptions } = require('../utils/environment-scoped-resources');
 const adminSecrets = require('../core/admin-secrets');
 const config = require('../core/config');
 const secretsEnsure = require('../core/secrets-ensure');
@@ -25,8 +26,8 @@ const { applyAdminSecretsPlatformOverlay } = require('../core/admin-secrets-env-
  * @param {Object.<string, string>} merged
  * @param {Object.<string, string>} adminObj
  */
-function mergeRunEnvWithAdminOverlay(merged, adminObj) {
-  applyAdminSecretsPlatformOverlay(merged, adminObj);
+function mergeRunEnvWithAdminOverlay(merged, adminObj, appName) {
+  applyAdminSecretsPlatformOverlay(merged, adminObj, appName);
 }
 
 async function applyOnboardingPlatformModeIfNeeded(appName, merged) {
@@ -108,9 +109,7 @@ function injectDatabaseNamesAndUsers(env, appConfig, scopeOpts = null) {
   if (!Array.isArray(databases) || databases.length === 0) return;
   const prefix =
     scopeOpts &&
-    scopeOpts.effectiveEnvironmentScopedResources &&
-    scopeOpts.runEnvKey &&
-    (scopeOpts.runEnvKey === 'dev' || scopeOpts.runEnvKey === 'tst')
+    isScopeActiveForOptions(scopeOpts)
       ? `${String(scopeOpts.runEnvKey).toLowerCase()}-`
       : '';
   for (let i = 0; i < databases.length; i++) {
@@ -298,7 +297,7 @@ async function buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId
     runEnvKey
   });
   const merged = { ...adminObj, ...appObj };
-  mergeRunEnvWithAdminOverlay(merged, adminObj);
+  mergeRunEnvWithAdminOverlay(merged, adminObj, appName);
   await applyOnboardingPlatformModeIfNeeded(appName, merged);
   await applyPostgresPasswordFromPgpass(merged, developerId);
   injectDatabaseNamesAndUsers(merged, appConfig, scopeOpts);

package/lib/app/run.js

@@ -258,10 +258,12 @@ function applyTraefikFlagToRunOptions(runOptions, userCfg) {
 
 /**
  * @param {string} envKey
- * @throws {Error} If env is not dev, tst, or pro
+ * @param {string} appName
+ * @throws {Error} If env is not a supported workload environment or a miso-only platform app
  */
-function assertValidRunEnvKey(envKey) {
-  if (envKey !== 'dev' && envKey !== 'tst' && envKey !== 'pro') {
+function assertValidRunEnvKey(envKey, appName) {
+  const misoOnlyPlatformApp = appName === 'builder-api' || appName === 'integration-server';
+  if (envKey !== 'dev' && envKey !== 'tst' && envKey !== 'pro' && !(envKey === 'miso' && misoOnlyPlatformApp)) {
     throw new Error('--env must be dev, tst, or pro');
   }
 }
@@ -345,7 +347,7 @@ function emitRunManifestMetadataIfRequested(appName, options) {
  */
 async function prepareAppRun(appName, options, debug) {
   const envKey = (options.env || 'dev').toLowerCase();
-  assertValidRunEnvKey(envKey);
+  assertValidRunEnvKey(envKey, appName);
   const shouldContinue = await validateAppForRun(appName, debug);
   if (!shouldContinue) {
     return null;

package/lib/build/standard-docker-build.js

@@ -104,6 +104,10 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
  * @returns {Promise<string>} Built image ref e.g. name:tag
  */
 async function runStandardDockerBuild(appName, options) {
+  // Before the tag plan, the promote shortcut and any Docker call: every build path reaches
+  // here, and a build into tst or pro must not get as far as producing an artifact.
+  const { assertBuildEnvironmentForOptions } = require('../core/environment-mode-policy');
+  await assertBuildEnvironmentForOptions(options);
   const { resolveBuildTagPlan, readAppVersion } = require('../utils/image-tags');
   const { buildConfig, config: appConfig } = await buildHelpers.loadAndValidateConfig(appName);
   // Resolve and validate every tag before any Docker build, tag, login or promote.

package/lib/channels/channel-artifact-generator.js

@@ -92,7 +92,7 @@ function renderTemplateFile(templatePath, context) {
  * @param {boolean} dryRun
  * @returns {{ installPath: string, content: string }|null}
  */
-function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dryRun) {
+function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dryRun, durableDir) {
   const installTemplate = path.join(templatesDir, 'install.template.md.hbs');
   if (!fs.existsSync(installTemplate)) {
     return null;
@@ -100,11 +100,19 @@ function renderInstallGuideIfPresent(templatesDir, runtimeValues, outputDir, dry
   const content = renderTemplateFile(installTemplate, runtimeValues);
   assertNoSecretsInArtifact(content);
   const installPath = path.join(outputDir, 'INSTALL.md');
+  // `outputDir` is under gitignored dist/, so a copy there alone is lost on any clean and the
+  // API that serves this document 404s afterwards. Write the durable copy too when the caller
+  // knows where the channel's committed files live.
+  const durablePath = durableDir ? path.join(durableDir, 'INSTALL.md') : '';
   if (!dryRun) {
     fs.mkdirSync(outputDir, { recursive: true });
     fs.writeFileSync(installPath, content, 'utf8');
+    if (durablePath) {
+      fs.mkdirSync(durableDir, { recursive: true });
+      fs.writeFileSync(durablePath, content, 'utf8');
+    }
   }
-  return { installPath, content };
+  return { installPath, content, durablePath: durablePath || undefined };
 }
 
 /**
@@ -130,6 +138,7 @@ function generateCopilotChannelArtifact(params, templatesDir, outputPath) {
  * @param {string} params.channelTarget
  * @param {Object} params.runtimeValues
  * @param {boolean} [params.dryRun]
+ * @param {string} [params.durableDir] - Committed channel directory for the persisted INSTALL.md
  * @returns {{ outputPath: string, artifactHash: string, content: string, installPath?: string }}
  */
 function generateChannelArtifact(params) {
@@ -158,7 +167,8 @@ function generateChannelArtifact(params) {
     templatesDir,
     runtimeValues,
     outputDir,
-    params.dryRun === true
+    params.dryRun === true,
+    params.durableDir
   );
 
   const installReady = runtimeValues?.installReady === true;

package/lib/cli/infra-guided-footers.js

@@ -46,11 +46,12 @@ async function resolvePlatformControllerUrlForDisplay() {
   return resolvePlatformControllerUrl();
 }
 
-async function logPlatformReadyFooter() {
-  const [controllerUrl, dataplaneUrl, keycloakUrl] = await Promise.all([
+async function logPlatformReadyFooter(options = {}) {
+  const [controllerUrl, dataplaneUrl, keycloakUrl, integrationServerUrl] = await Promise.all([
     resolvePlatformControllerUrlForDisplay(),
     computeAppBaseUrl('dataplane'),
-    computeAppBaseUrl('keycloak')
+    computeAppBaseUrl('keycloak'),
+    options.integrationServer === true ? computeAppBaseUrl('integration-server') : null
   ]);
   const cfg = await config.getConfig();
   const env = cfg && cfg.environment ? cfg.environment : 'dev';
@@ -60,7 +61,7 @@ async function logPlatformReadyFooter() {
   logSection('Miso Controller', controllerUrl);
   logSection('Dataplane (DEV)', dataplaneUrl);
   logSection('Keycloak', keycloakUrl);
-  logSection('API Documentation', `${dataplaneUrl}/api/docs`);
+  if (integrationServerUrl) logSection('Integration Server', `${integrationServerUrl}/download`);
   logSection('Knowledge Base', 'https://docs.aifabrix.ai');
   logSection('Getting Started', 'https://docs.aifabrix.ai/get-started');
   logFooterEnd();
@@ -91,20 +92,21 @@ async function logDataplaneReadyFooter() {
 /**
  * @param {'platform'|'dataplane'} [scope]
  */
-function logPlatformSetupDurationHint(scope = 'platform') {
+function logPlatformSetupDurationHint(scope = 'platform', options = {}) {
+  const optionalApp = options.integrationServer === true ? ', Builder API, and Integration Server' : ', and Builder API';
   const line =
     scope === 'dataplane'
       ? 'Installation may take a few minutes. Authenticating and starting Dataplane — please wait.'
-      : 'Installation may take a few minutes. Keycloak, Miso Controller, Dataplane, and Builder API are starting — please wait.';
+      : `Installation may take a few minutes. Keycloak, Miso Controller, Dataplane${optionalApp} are starting — please wait.`;
   logger.log(chalk.yellow(`⚠ ${line}`));
 }
 
-function logGuidedPlatformSetupHeader() {
+function logGuidedPlatformSetupHeader(options = {}) {
   logger.log('');
   logger.log(title('AI Fabrix Platform Setup'));
   logger.log(SEPARATOR);
   logger.log('');
-  logPlatformSetupDurationHint('platform');
+  logPlatformSetupDurationHint('platform', options);
   logger.log('');
 }
 

package/lib/cli/infra-guided.js

@@ -14,6 +14,10 @@ const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getLogLevel, passesLevelFilter } = require('../commands/app-logs');
 const { handleLogin } = require('../commands/login');
 const { handleUpBuilderApi } = require('../commands/up-builder-api');
+const {
+  handleUpIntegrationServer,
+  isIntegrationServerSelected
+} = require('../commands/up-integration-server');
 const {
   resolveGuidedAuthControllerUrl,
   runGuidedAuthStep,
@@ -295,8 +299,25 @@ async function runGuidedDataplaneInstallPhase(options, handleUpDataplane, handle
   await refreshDataplaneVersionAfterPlatformInstall();
 }
 
+async function runGuidedIntegrationServerPhase(options, selected) {
+  if (!selected) return;
+  const spin = startSpinner('Starting Integration Server...');
+  await withMutedLogger(() => handleUpIntegrationServer({ ...options, platformInstall: true }));
+  stopSpinnerSuccess(spin, 'Integration Server ready');
+}
+
+async function runGuidedKeycloakRealmPhase(options) {
+  if (!options || options.requireKeycloakRealm !== true) return;
+  const { waitForKeycloakRealmReady } = require('../utils/keycloak-realm-ready');
+  const spin = startSpinner('Waiting for Keycloak realm (aifabrix)...');
+  await waitForKeycloakRealmReady({ timeoutSeconds: 180 });
+  stopSpinnerSuccess(spin, 'Keycloak realm ready');
+  logger.log('');
+}
+
 async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, handleLogin, forceCleanSummary = null) {
-  logGuidedPlatformSetupHeader();
+  const integrationServerSelected = await isIntegrationServerSelected();
+  logGuidedPlatformSetupHeader({ integrationServer: integrationServerSelected });
   if (forceCleanSummary && forceCleanSummary.forceSummary) {
     logUpPlatformForceCleanSummary(forceCleanSummary.forceSummary, forceCleanSummary.cleanedApps);
   }
@@ -308,21 +329,20 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
 
   await withMutedLogger(() => prepareUrlsLocalRegistryForUpPlatform());
   await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
-  if (options && options.requireKeycloakRealm === true) {
-    const { waitForKeycloakRealmReady } = require('../utils/keycloak-realm-ready');
-    const realmSpin = startSpinner('Waiting for Keycloak realm (aifabrix)...');
-    await waitForKeycloakRealmReady({ timeoutSeconds: 180 });
-    stopSpinnerSuccess(realmSpin, 'Keycloak realm ready');
-    logger.log('');
-  }
+  await runGuidedKeycloakRealmPhase(options);
   await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
   const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
   await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
   const baSpin = startSpinner('Starting Builder API...');
   await withMutedLogger(() => handleUpBuilderApi({ ...options, platformInstall: true }));
   stopSpinnerSuccess(baSpin, 'Builder API ready');
-  await validateAppErrorLogs(['miso-controller', 'dataplane', 'builder-api']);
-  await logPlatformReadyFooter();
+  await runGuidedIntegrationServerPhase(options, integrationServerSelected);
+  const appNames = [
+    'miso-controller', 'dataplane', 'builder-api',
+    ...(integrationServerSelected ? ['integration-server'] : [])
+  ];
+  await validateAppErrorLogs(appNames);
+  await logPlatformReadyFooter({ integrationServer: integrationServerSelected });
 }
 
 async function runGuidedDownInfra(appName, options, infraMod, appLib) {

package/lib/cli/setup-infra-up-platform-action.js

@@ -17,6 +17,10 @@ const { handleLogin } = require('../commands/login');
 const { handleUpMiso } = require('../commands/up-miso');
 const { handleUpDataplane } = require('../commands/up-dataplane');
 const { handleUpBuilderApi } = require('../commands/up-builder-api');
+const {
+  handleUpIntegrationServer,
+  isIntegrationServerSelected
+} = require('../commands/up-integration-server');
 const {
   applyUpPlatformForceConfig,
   cleanBuilderAppDirs,
@@ -26,7 +30,13 @@ const {
 const { runGuidedUpPlatform } = require('./infra-guided');
 const { recordInfraInstallationCommand } = require('./installation-log-command');
 
-const PLATFORM_APPS = ['keycloak', 'miso-controller', 'dataplane', 'builder-api'];
+const PLATFORM_APPS = [
+  'keycloak',
+  'miso-controller',
+  'dataplane',
+  'builder-api',
+  'integration-server'
+];
 
 /**
  * @param {Object} options
@@ -59,6 +69,9 @@ async function runUpPlatformWork(options) {
     await handleUpMiso(options);
     await handleUpDataplane(options);
     await handleUpBuilderApi({ ...options, platformInstall: true });
+    if (await isIntegrationServerSelected()) {
+      await handleUpIntegrationServer({ ...options, platformInstall: true });
+    }
   }
   return cleanedAppKeys;
 }

package/lib/cli/setup-platform.js

@@ -61,6 +61,8 @@ function registerSetup(program) {
     .option('--pro-password-mode <mode>', 'Pro profile only: autogen or manual')
     .option('--admin-email <email>', 'Admin email (non-interactive fresh install)')
     .option('--admin-password <password>', 'Admin password for dev or pro manual-single (non-interactive)')
+    .option('--integration-server', 'Install the integration server (runs once in the miso environment)')
+    .option('--no-integration-server', 'Do not install the integration server (default)')
     .option('--mode <mode>', 'Non-interactive mode: fresh (no infra) or update-images (infra running)')
     .option('-y, --yes', 'Skip destructive confirmation prompts (re-install, wipe data, teardown)')
     .addHelpText('after', SETUP_HELP_AFTER)

package/lib/commands/auth-config.js

@@ -23,6 +23,7 @@ const {
   checkUserLoggedIn
 } = require('../utils/auth-config-validator');
 const { hasStoredDeviceTokenForController } = require('../utils/controller-url');
+const { assertEnvironmentAllowedForCurrentMode } = require('../core/environment-mode-policy');
 const logger = require('../utils/logger');
 
 /**
@@ -166,6 +167,7 @@ async function handleSetEnvironment(environment) {
   try {
     // Validate environment format
     validateEnvironment(environment);
+    await assertEnvironmentAllowedForCurrentMode(environment);
 
     // Get current controller from config
     const controllerUrl = await getControllerUrl();

package/lib/commands/login.js

@@ -121,6 +121,10 @@ async function normalizeControllerUrl(options) {
 async function handleEnvironmentConfig(options) {
   if (options.environment) {
     const environment = options.environment.trim();
+    // `login -e tst` sets the environment without going through `auth set-environment`,
+    // so the mode rule has to be applied here too or it is trivially bypassed.
+    const { assertEnvironmentAllowedForCurrentMode } = require('../core/environment-mode-policy');
+    await assertEnvironmentAllowedForCurrentMode(environment);
     await setCurrentEnvironment(environment);
     if (!options.compact) {
       logger.log(chalk.gray(`Environment: ${environment}`));

package/lib/commands/repair-datasource-apply.js

@@ -8,6 +8,7 @@
 
 'use strict';
 
+const { repairLegacyDatasource } = require('./repair-datasource-legacy');
 const { repairKeyedDocument } = require('./repair-datasource-keyed-document');
 const { repairOpenapiSection } = require('./repair-datasource-openapi');
 const { repairSyncOperationsFromCapabilities } = require('./repair-datasource-sync-operations');
@@ -122,7 +123,8 @@ function applyOpenapiDatasourceRepairs(parsed, changes) {
  */
 function runRepairDatasourceFile(parsed, options, changes, helpers) {
   const out = Array.isArray(changes) ? changes : [];
-  let updated = helpers.stripDeprecatedServiceCategory(parsed, out);
+  let updated = repairLegacyDatasource(parsed, out);
+  updated = helpers.stripDeprecatedServiceCategory(parsed, out) || updated;
 
   if (shouldApplyServiceContractRepair(parsed, options)) {
     updated = repairNoneLlmToServiceContract(parsed, out) || updated;

package/lib/commands/repair-datasource-legacy.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Migrate legacy datasource storage and mapping shapes.
+ * @author AI Fabrix Team
+ */
+'use strict';
+
+const ENTITY_TYPES = {
+  'record-storage': 'recordStorage',
+  'document-storage': 'documentStorage',
+  'vector-store': 'vectorStore',
+  'message-service': 'messageService'
+};
+
+/**
+ * Preserve legacy attribute types in metadataSchema and qualify raw input paths.
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function repairLegacyAttributes(parsed, changes) {
+  let updated = false;
+  for (const [key, attr] of Object.entries(parsed.fieldMappings?.attributes || {})) {
+    if (!attr || typeof attr !== 'object') continue;
+    if (typeof attr.expression === 'string' && /^\{\{\s*metadata\.[\w.[\]]+\s*\}\}$/.test(attr.expression)) {
+      attr.expression = attr.expression.replace(/\{\{\s*(metadata\.[\w.[\]]+)\s*\}\}/, '{{raw.$1}}');
+      changes.push(`Qualified legacy attribute '${key}' with raw input root`);
+      updated = true;
+    }
+    if (['string', 'number', 'integer', 'boolean', 'object', 'array', 'null'].includes(attr.type)) {
+      parsed.metadataSchema ||= { type: 'object', additionalProperties: true };
+      parsed.metadataSchema.properties ||= {};
+      parsed.metadataSchema.properties[key] ||= { type: attr.type };
+      delete attr.type;
+      changes.push(`Moved legacy attribute '${key}' type to metadataSchema`);
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * Move only unambiguous local bindings; preserve unsupported/conflicting input.
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function repairLegacyDimensions(parsed, changes) {
+  const legacy = parsed.fieldMappings?.dimensions;
+  if (!legacy || typeof legacy !== 'object' || Array.isArray(legacy)) return false;
+  let updated = false;
+  for (const [key, value] of Object.entries(legacy)) {
+    const match = typeof value === 'string' && /^metadata\.([a-z][a-zA-Z0-9]*)$/.exec(value);
+    if (!match || !Object.hasOwn(parsed.fieldMappings.attributes || {}, match[1])) continue;
+    const binding = { type: 'local', field: match[1] };
+    const existing = parsed.dimensions?.[key];
+    if (existing && (existing.type !== 'local' || existing.field !== match[1])) continue;
+    parsed.dimensions ||= {};
+    parsed.dimensions[key] ||= binding;
+    delete legacy[key];
+    changes.push(`Moved legacy dimension '${key}' to root dimensions`);
+    updated = true;
+  }
+  if (Object.keys(legacy).length === 0) {
+    delete parsed.fieldMappings.dimensions;
+    updated = true;
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function repairLegacyDatasource(parsed, changes = []) {
+  if (!parsed || typeof parsed !== 'object') return false;
+  let updated = false;
+  if (Object.hasOwn(ENTITY_TYPES, parsed.entityType)) {
+    parsed.entityType = ENTITY_TYPES[parsed.entityType];
+    changes.push(`Normalized legacy entityType to ${parsed.entityType}`);
+    updated = true;
+  }
+  if (['recordStorage', 'documentStorage'].includes(parsed.entityType) && !parsed.labelKey
+      && parsed.primaryKey?.length === 1
+      && Object.hasOwn(parsed.fieldMappings?.attributes || {}, parsed.primaryKey[0])) {
+    parsed.labelKey = [...parsed.primaryKey];
+    changes.push('Defaulted missing labelKey to the sole primary key attribute');
+    updated = true;
+  }
+  updated = repairLegacyAttributes(parsed, changes) || updated;
+  return repairLegacyDimensions(parsed, changes) || updated;
+}
+
+module.exports = { repairLegacyDatasource };

package/lib/commands/setup-image-refresh.js

@@ -105,6 +105,26 @@ function readPlatformDeployImageRef(appName) {
  * @param {{ quiet?: boolean }} [opts]
  * @returns {Promise<boolean>} True when a pull was attempted
  */
+/**
+ * True when Docker already holds the image.
+ *
+ * An installation with no registry configured deploys the `application.yaml` image as it
+ * stands, which is built locally and never pushed. Authenticating first would prompt for
+ * credentials the install does not need, and pulling would fail against a registry that
+ * has never seen the tag, so the local image is the answer when it is already there.
+ *
+ * @param {string} imageRef - Image reference
+ * @returns {Promise<boolean>}
+ */
+async function imageExistsLocally(imageRef) {
+  try {
+    await dockerExec.execWithDockerEnv(`docker image inspect ${imageRef}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function pullPlatformAppImage(appName, opts = {}) {
   const quiet = Boolean(opts.quiet);
   const imageRef = readPlatformDeployImageRef(appName);
@@ -114,6 +134,12 @@ async function pullPlatformAppImage(appName, opts = {}) {
     }
     return false;
   }
+  if (await imageExistsLocally(imageRef)) {
+    if (!quiet) {
+      logger.log(formatDatasourceListRow('ok', appName, 'image already local'));
+    }
+    return true;
+  }
   // A partial stored credential pair fails closed here instead of degrading to a warning.
   await ensureLoginForImageRefs([imageRef]);
   try {