@aifabrix/builder 2.44.5 → 2.45.0

package/lib/utils/urls-local-registry.js

@@ -1,9 +1,14 @@
 /**
- * urls.local.yaml beside effective config.yaml (same directory as secrets.local.yaml).
- * When AIFABRIX_HOME is POSIX $HOME but config lives in $HOME/.aifabrix/, the registry
- * is $HOME/.aifabrix/urls.local.yaml (not $HOME/urls.local.yaml).
+ * Primary `urls.local.yaml` beside `config.yaml` (same directory as {@link module:lib/utils/paths.getConfigDirForPaths}),
+ * aligned with `secrets.local.yaml`. When missing, {@link readUrlsLocalRegistrySync} may read a legacy
+ * file under {@link module:lib/utils/paths.getAifabrixHome} (older releases when `aifabrix-home` was `$HOME`).
  *
- * @fileoverview Read/write registry; scan each builder app folder for application.yaml
+ * Per-app keys (see {@link mergeDocIntoRegistry}): `appKey-port`, `appKey-pattern`, `appKey-containerPort`,
+ * optional `appKey-internalDockerUseOriginOnly` (boolean) — overrides `frontDoorRouting.internalDockerUseOriginOnly`
+ * for declarative `url://` resolution when set (e.g. Keycloak internal URL without `/auth` when true).
+ *
+ * @fileoverview Read/write registry; scan builder/package dirs in canonical order (plan 141 P3).
+ *   Duplicate `app.key`: last scan directory wins — no cross-root mtime merge or `AIFABRIX_BUILDER_DIR` ordering.
  * @author AI Fabrix Team
  * @version 1.0.0
  */
@@ -15,16 +20,17 @@ const path = require('path');
 const yaml = require('js-yaml');
 const { DECLARATIVE_URL_INFRA_DEFAULTS } = require('./infra-env-defaults');
 const pathsUtil = require('./paths');
+const { collectLatestApplicationYamlEntriesPerApp } = require('./urls-local-registry-scan');
 
 /**
- * @returns {string} Absolute path to urls.local.yaml (primary; beside config.yaml)
+ * @returns {string} Absolute path to urls.local.yaml (beside config.yaml)
  */
 function getUrlsLocalYamlPath() {
   return path.join(pathsUtil.getConfigDirForPaths(), 'urls.local.yaml');
 }
 
-/** @returns {string} Legacy path when registry was stored under getAifabrixHome() only */
-function getLegacyUrlsLocalYamlPath() {
+/** @returns {string} Legacy primary path from older CLI (under resolved AI Fabrix home) */
+function getLegacyUrlsLocalYamlPathAtAifabrixHome() {
   return path.join(pathsUtil.getAifabrixHome(), 'urls.local.yaml');
 }
 
@@ -45,8 +51,8 @@ function readUrlsLocalRegistrySync() {
   if (fsRealSync.existsSync(primary)) {
     return loadRegistryYamlFile(primary);
   }
-  const legacy = getLegacyUrlsLocalYamlPath();
-  if (legacy !== primary && fsRealSync.existsSync(legacy)) {
+  const legacy = getLegacyUrlsLocalYamlPathAtAifabrixHome();
+  if (path.resolve(legacy) !== path.resolve(primary) && fsRealSync.existsSync(legacy)) {
     return loadRegistryYamlFile(legacy);
   }
   return {};
@@ -91,22 +97,6 @@ function writeMergedRegistry(merged) {
   return merged;
 }
 
-/**
- * @param {string} cfgPath
- * @returns {object|null}
- */
-function tryLoadApplicationYaml(cfgPath) {
-  if (!fsRealSync.existsSync(cfgPath)) {
-    return null;
-  }
-  try {
-    const doc = yaml.load(fsRealSync.readFileSync(cfgPath, 'utf8'));
-    return doc && typeof doc === 'object' ? doc : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * @param {object} doc
  * @returns {number|null}
@@ -153,102 +143,193 @@ function mergeDocIntoRegistry(merged, doc, folderName) {
   } else {
     delete merged[ckey];
   }
+
+  mergeInternalDockerOriginOnlyRegistryKeyFromDoc(merged, appKey, doc);
 }
 
 /**
+ * When `application.yaml` explicitly sets `frontDoorRouting.internalDockerUseOriginOnly`, mirror it into
+ * `urls.local.yaml` on refresh. If the property is absent, leave any existing registry value unchanged
+ * (supports hand-edited `appKey-internalDockerUseOriginOnly` without a YAML field).
+ *
  * @param {Object} merged
- * @param {string} builderDir
+ * @param {string} appKey
+ * @param {object} doc
  */
-function mergeBuilderDirIntoRegistry(merged, builderDir) {
-  if (!builderDir || !fsRealSync.existsSync(builderDir) || !fsRealSync.statSync(builderDir).isDirectory()) {
+function mergeInternalDockerOriginOnlyRegistryKeyFromDoc(merged, appKey, doc) {
+  const key = `${appKey}-internalDockerUseOriginOnly`;
+  const fd = doc && doc.frontDoorRouting;
+  if (!fd || typeof fd !== 'object') {
     return;
   }
-  for (const ent of fsRealSync.readdirSync(builderDir, { withFileTypes: true })) {
-    if (!ent.isDirectory()) {
-      continue;
-    }
-    const doc = tryLoadApplicationYaml(path.join(builderDir, ent.name, 'application.yaml'));
-    if (!doc) {
-      continue;
-    }
-    mergeDocIntoRegistry(merged, doc, ent.name);
+  if (!Object.prototype.hasOwnProperty.call(fd, 'internalDockerUseOriginOnly')) {
+    return;
+  }
+  const v = fd.internalDockerUseOriginOnly;
+  if (v === true) {
+    merged[key] = true;
+  } else if (v === false) {
+    merged[key] = false;
+  } else {
+    delete merged[key];
   }
 }
 
 /**
- * True when getBuilderRoot() resolves to the same path as AIFABRIX_BUILDER_DIR (authoritative override).
- * @param {string|null} resolvedEffective
- * @param {string|null} envResolved
- * @returns {boolean}
+ * Append a directory to the scan list when it exists, is a directory, and is not already included (resolved).
+ * Later entries win duplicate `app.key` merges (see {@link collectLatestApplicationYamlEntriesPerApp}).
+ *
+ * @param {string[]} scanDirs
+ * @param {string|null|undefined} dirPath
+ * @returns {void}
  */
-function effectiveBuilderMatchesEnvVar(resolvedEffective, envResolved) {
-  return Boolean(envResolved && resolvedEffective && resolvedEffective === envResolved);
+function pushUniqueScanDir(scanDirs, dirPath) {
+  if (!dirPath || typeof dirPath !== 'string') {
+    return;
+  }
+  let resolved;
+  try {
+    resolved = path.resolve(dirPath);
+  } catch {
+    return;
+  }
+  try {
+    if (!fsRealSync.existsSync(resolved) || !fsRealSync.statSync(resolved).isDirectory()) {
+      return;
+    }
+  } catch {
+    return;
+  }
+  for (const existing of scanDirs) {
+    try {
+      if (path.resolve(existing) === resolved) {
+        return;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  scanDirs.push(resolved);
 }
 
 /**
- * Builder dirs to scan in order; later merges overwrite registry keys from earlier dirs.
- * When `AIFABRIX_BUILDER_DIR` is set and differs from projectRoot/builder, env builder root is merged last.
- * Otherwise projectRoot/builder is merged last so explicit refresh roots override getBuilderRoot().
- *
- * @param {string} root - Resolved project root passed to refresh
- * @param {string|null} effectiveBuilderDir - pathsUtil.getBuilderRoot()
  * @returns {string[]}
  */
-function getOrderedBuilderDirsForRegistryScan(root, effectiveBuilderDir) {
-  const legacyBuilderDir = path.join(root, 'builder');
-  let resolvedLegacy;
-  let resolvedEffective;
+function getPackageBuilderLikeDirsForRegistryScan() {
+  const out = [];
   try {
-    resolvedLegacy = path.resolve(legacyBuilderDir);
-    resolvedEffective = effectiveBuilderDir ? path.resolve(effectiveBuilderDir) : null;
+    out.push(path.join(pathsUtil.getIntegrationBuilderBaseDir(), 'packages'));
   } catch {
-    return [legacyBuilderDir];
+    // ignore
   }
-  const envRaw = process.env.AIFABRIX_BUILDER_DIR && String(process.env.AIFABRIX_BUILDER_DIR).trim();
-  const envResolved = envRaw ? path.resolve(envRaw) : null;
-  // Only treat env as authoritative when getBuilderRoot() is actually that path. Otherwise a stray
-  // AIFABRIX_BUILDER_DIR on CI (or Jest mocking getBuilderRoot to a temp dir) must not force
-  // [legacy, effective] — that order lets the real checkout builder overwrite the mocked root last.
-  const effectiveMatchesEnvVar = effectiveBuilderMatchesEnvVar(resolvedEffective, envResolved);
+  try {
+    const pr = pathsUtil.getProjectRoot();
+    if (pr) {
+      out.push(path.join(pr, 'packages'));
+    }
+  } catch {
+    // ignore
+  }
+  return out;
+}
 
-  if (effectiveBuilderDir && resolvedEffective && resolvedEffective === resolvedLegacy) {
-    return [legacyBuilderDir];
+/**
+ * Canonical builder/package scan roots (low → high priority). Plan 141 P3: fixed order replaces
+ * mtime merge and `AIFABRIX_BUILDER_DIR` scan ordering; `findProjectRootFromCwd` builder is last when enabled.
+ *
+ * @param {string|null} root
+ * @param {string|null} effectiveBuilderDir
+ * @param {{ excludeCwdBuilderScan?: boolean }} opts
+ * @returns {string[]}
+ */
+function buildCanonicalRegistryScanDirs(root, effectiveBuilderDir, opts = {}) {
+  const scanDirs = [];
+  pushUniqueScanDir(scanDirs, pathsUtil.getSystemBuilderRoot());
+  pushUniqueScanDir(scanDirs, effectiveBuilderDir);
+  if (root) {
+    pushUniqueScanDir(scanDirs, path.join(root, 'builder'));
   }
-  if (effectiveMatchesEnvVar && effectiveBuilderDir && resolvedEffective && resolvedEffective !== resolvedLegacy) {
-    return [legacyBuilderDir, effectiveBuilderDir];
+  for (const pkg of getPackageBuilderLikeDirsForRegistryScan()) {
+    pushUniqueScanDir(scanDirs, pkg);
   }
-  if (effectiveBuilderDir && resolvedEffective && resolvedEffective !== resolvedLegacy) {
-    return [effectiveBuilderDir, legacyBuilderDir];
+  if (!opts.excludeCwdBuilderScan) {
+    let cwdRoot = null;
+    try {
+      cwdRoot = pathsUtil.findProjectRootFromCwd();
+    } catch {
+      cwdRoot = null;
+    }
+    if (cwdRoot && typeof cwdRoot === 'string') {
+      pushUniqueScanDir(scanDirs, path.join(cwdRoot, 'builder'));
+    }
   }
-  return [legacyBuilderDir];
+  return scanDirs;
 }
 
 /**
  * Merge scan results into registry (does not remove stale keys).
  * @param {string|null} projectRoot - getProjectRoot() or null (same semantics as projectRoot || getProjectRoot())
+ * @param {{ excludeCwdBuilderScan?: boolean }} [opts] - When `excludeCwdBuilderScan` is true, omit cwd
+ *   checkout `builder/` (tests / `ctx.projectRoot` isolation — avoids merging ambient repo `builder/`).
  * @returns {Object} Updated registry
  */
-function refreshUrlsLocalRegistryFromBuilder(projectRoot) {
+function refreshUrlsLocalRegistryFromBuilder(projectRoot, opts) {
+  const o = opts && typeof opts === 'object' ? opts : {};
   const root = projectRoot || pathsUtil.getProjectRoot();
   const merged = { ...readUrlsLocalRegistrySync() };
   if (!root) {
     return writeMergedRegistry(merged);
   }
-  // Published npm tarball omits builder/ under the package root (.npmignore). Global installs must
-  // still refresh from the real builder tree (AIFABRIX_BUILDER_DIR or integration base + builder).
+  // Published npm tarball omits builder/ under the package root (.npmignore). Global installs still
+  // resolve materialized apps via getBuilderRoot() (same parent as getSystemBuilderRoot when aligned).
   let effectiveBuilderDir = null;
   try {
     effectiveBuilderDir = pathsUtil.getBuilderRoot();
   } catch {
     effectiveBuilderDir = null;
   }
-  const builderDirs = getOrderedBuilderDirsForRegistryScan(root, effectiveBuilderDir);
-  for (const builderDir of builderDirs) {
-    mergeBuilderDirIntoRegistry(merged, builderDir);
+  const scanDirs = buildCanonicalRegistryScanDirs(root, effectiveBuilderDir, o);
+  const entries = collectLatestApplicationYamlEntriesPerApp(scanDirs);
+  for (const { folderName, doc } of entries) {
+    mergeDocIntoRegistry(merged, doc, folderName);
   }
   return writeMergedRegistry(merged);
 }
 
+const REGISTRY_BOOL_TRUE = new Set([true, 'true', 'yes', 'on', 1, '1']);
+const REGISTRY_BOOL_FALSE = new Set([false, 'false', 'no', 'off', 0, '0']);
+
+/**
+ * @param {unknown} raw
+ * @returns {boolean|undefined}
+ */
+function coerceRegistryBool(raw) {
+  if (REGISTRY_BOOL_TRUE.has(raw)) {
+    return true;
+  }
+  if (REGISTRY_BOOL_FALSE.has(raw)) {
+    return false;
+  }
+  return undefined;
+}
+
+/**
+ * Optional `appKey-internalDockerUseOriginOnly` in `urls.local.yaml` (boolean or common string coercions).
+ * When set, declarative URL resolution uses this value instead of (or in addition to) `application.yaml`.
+ *
+ * @param {string} appKey
+ * @param {Object|null|undefined} registry
+ * @returns {boolean|undefined} undefined when the key is absent or not coercible to boolean
+ */
+function readRegistryInternalDockerUseOriginOnly(appKey, registry) {
+  const r = registry && typeof registry === 'object' ? registry : {};
+  const key = `${appKey}-internalDockerUseOriginOnly`;
+  if (!Object.prototype.hasOwnProperty.call(r, key)) {
+    return undefined;
+  }
+  return coerceRegistryBool(r[key]);
+}
+
 /**
  * @param {string} appKey
  * @param {Object} registry
@@ -282,5 +363,6 @@ module.exports = {
   writeUrlsLocalRegistrySync,
   refreshUrlsLocalRegistryFromBuilder,
   normalizePatternForUrl,
-  getRegistryEntryForApp
+  getRegistryEntryForApp,
+  readRegistryInternalDockerUseOriginOnly
 };

package/lib/utils/validation-poll-ui.js

@@ -0,0 +1,81 @@
+/**
+ * TTY ora spinner + throttled non-TTY lines for unified validation run polling (aligned with deploy-poll-ui).
+ *
+ * @fileoverview Validation run poll presentation helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+function shouldUseValidationPollSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * Single-line ora text / log line for validation polling.
+ *
+ * @param {Object|null|undefined} envelope - Latest GET envelope (optional before first poll tick)
+ * @param {number} attemptIndex - Zero-based poll index after initial POST
+ * @param {number} deadlineMs - Wall-clock deadline (Date.now() + remaining budget)
+ * @returns {string}
+ */
+function buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs) {
+  const remainingSec = Math.max(0, Math.ceil((deadlineMs - Date.now()) / 1000));
+  if (!envelope || typeof envelope !== 'object') {
+    return `Waiting for validation run… starting (budget ~${remainingSec}s)`;
+  }
+  const c =
+    envelope.reportCompleteness !== undefined && envelope.reportCompleteness !== null
+      ? String(envelope.reportCompleteness)
+      : '?';
+  const st =
+    envelope.status !== undefined && envelope.status !== null ? String(envelope.status) : '?';
+  return `Waiting for validation run… completeness=${c} status=${st} (poll ${attemptIndex + 1} · ~${remainingSec}s left)`;
+}
+
+const NON_TTY_THROTTLE_MS = 5000;
+
+/**
+ * @param {number} deadlineMs - Absolute deadline for poll budget display
+ * @returns {{ usesSpinner: boolean, onPollProgress: Function, finish: () => void }}
+ */
+function createValidationPollHandlers(deadlineMs) {
+  if (shouldUseValidationPollSpinner()) {
+    const ora = require('ora');
+    const spinner = ora({
+      text: buildValidationPollSpinnerText(null, 0, deadlineMs),
+      spinner: 'dots'
+    }).start();
+    return {
+      usesSpinner: true,
+      onPollProgress: (envelope, attemptIndex, _meta) => {
+        spinner.text = buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs);
+      },
+      finish: () => {
+        spinner.stop();
+      }
+    };
+  }
+
+  let lastNonTtyLogAt = 0;
+  return {
+    usesSpinner: false,
+    onPollProgress: (envelope, attemptIndex, _meta) => {
+      const now = Date.now();
+      if (now - lastNonTtyLogAt < NON_TTY_THROTTLE_MS) return;
+      lastNonTtyLogAt = now;
+      logger.log(chalk.gray(buildValidationPollSpinnerText(envelope, attemptIndex, deadlineMs)));
+    },
+    finish: () => {}
+  };
+}
+
+module.exports = {
+  createValidationPollHandlers,
+  shouldUseValidationPollSpinner,
+  buildValidationPollSpinnerText
+};

package/lib/utils/validation-run-poll.js

@@ -34,8 +34,8 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-function maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef) {
-  if (!verbosePoll || !envelope || typeof envelope !== 'object') return;
+function maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef, skipBecauseUi) {
+  if (skipBecauseUi || !verbosePoll || !envelope || typeof envelope !== 'object') return;
   const now = Date.now();
   if (now - lastProgressLogAtRef[0] < 5000) return;
   lastProgressLogAtRef[0] = now;
@@ -57,6 +57,21 @@ function isTerminalReportCompleteness(envelope) {
   return envelope.reportCompleteness === 'full';
 }
 
+function emitPollProgressLine(
+  envelope,
+  verbosePoll,
+  lastProgressLogAtRef,
+  onPollProgress,
+  attempt,
+  deadline
+) {
+  const hasPollUi = typeof onPollProgress === 'function';
+  maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef, hasPollUi);
+  if (hasPollUi) {
+    onPollProgress(envelope, attempt, { deadlineMs: deadline });
+  }
+}
+
 /**
  * Poll until reportCompleteness === 'full' or budget exhausted.
  * @async
@@ -66,7 +81,8 @@ function isTerminalReportCompleteness(envelope) {
  * @param {string} opts.testRunId
  * @param {number} opts.budgetMs - Remaining wall-clock budget for polls only (POST excluded)
  * @param {typeof getValidationRunWithTransportRetry} [opts.fetchRun] - Inject for tests (default: GET with transport retry)
- * @param {boolean} [opts.verbosePoll] - Log throttled progress (plan §3.13)
+ * @param {boolean} [opts.verbosePoll] - Log throttled progress (plan §3.13); skipped when `onPollProgress` is set
+ * @param {Function|null} [opts.onPollProgress] - `(envelope, attemptIndex, { deadlineMs })` each non-terminal poll
  * @param {number} [opts.pollRequestTimeoutMs] - Per-GET HTTP timeout (match validation aggregate budget)
  * @returns {Promise<{ envelope: Object|null, timedOut: boolean, lastApiResult: Object|null }>}
  */
@@ -78,7 +94,8 @@ async function pollValidationRunUntilComplete(opts) {
     budgetMs,
     fetchRun = getValidationRunWithTransportRetry,
     verbosePoll = false,
-    pollRequestTimeoutMs
+    pollRequestTimeoutMs,
+    onPollProgress = null
   } = opts;
   const pollTransportOpts =
     Number.isFinite(pollRequestTimeoutMs) && pollRequestTimeoutMs > 0
@@ -100,7 +117,14 @@ async function pollValidationRunUntilComplete(opts) {
       return { envelope, timedOut: false, lastApiResult };
     }
 
-    maybeLogPollProgress(envelope, verbosePoll, lastProgressLogAtRef);
+    emitPollProgressLine(
+      envelope,
+      verbosePoll,
+      lastProgressLogAtRef,
+      onPollProgress,
+      attempt,
+      deadline
+    );
 
     const delay = Math.min(nextPollDelayMs(attempt), Math.max(0, deadline - Date.now()));
     attempt += 1;

package/lib/utils/with-muted-logger.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Temporarily mute logger.log output for guided UX flows.
+ *
+ * Used by guided installer-style commands (e.g. up-platform default mode) to avoid
+ * streaming orchestration mechanics while preserving errors and warnings.
+ */
+
+'use strict';
+
+const logger = require('./logger');
+
+/**
+ * Run a function while muting logger.log/info.
+ *
+ * - logger.error and logger.warn are preserved.
+ * - An optional allowlist can let specific messages through (rare).
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {{ allow?: ((...args: any[]) => boolean) }} [opts]
+ * @returns {Promise<T>}
+ */
+async function withMutedLogger(fn, opts = {}) {
+  const original = {
+    log: logger.log,
+    info: logger.info
+  };
+
+  const allow = typeof opts.allow === 'function' ? opts.allow : null;
+
+  const muted = (...args) => {
+    try {
+      if (allow && allow(...args)) {
+        return original.log(...args);
+      }
+    } catch {
+      // ignore allow errors; treat as muted
+    }
+    return undefined;
+  };
+
+  logger.log = muted;
+  logger.info = muted;
+  try {
+    return await fn();
+  } finally {
+    logger.log = original.log;
+    logger.info = original.info;
+  }
+}
+
+module.exports = { withMutedLogger };
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.44.5",
+  "version": "2.45.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
@@ -36,6 +36,8 @@
     "precommit": "npm run lint:fix && npm run test",
     "install:local": "node scripts/install-local.js && which aifabrix && which af",
     "uninstall:local": "node scripts/install-local.js uninstall && which aifabrix && which af",
+    "install:global": "npm install -g . --force && which aifabrix && which af && aifabrix --version",
+    "uninstall:global": "npm uninstall -g @aifabrix/builder",
     "diagnose:cli": "node scripts/diagnose-cli.js",
     "check:schema-sync": "node scripts/check-datasource-test-run-schema-sync.js",
     "check:flags": "jest tests/lib/schema/flag-map-validation-run.test.js --runInBand --config jest.config.default.js"

package/templates/applications/dataplane/application.yaml

@@ -8,7 +8,7 @@ app:
   version: 1.9.5
 
 # Image Configuration
-# Set tag to match your build (e.g. aifabrix build dataplane -t v1.0.0 then tag: v1.0.0)
+# Set tag to match your build (e.g. aifabrix build dataplane -t 1.0.0 then tag: 1.0.0)
 # Registry is required so the controller can pull the image (avoids "docker: not found" on the controller host).
 image:
   name: aifabrix/dataplane
@@ -26,6 +26,8 @@ environmentScopedResources: true
 frontDoorRouting:
   pattern: /data/*
   enabled: true
+  # Docker url://internal full URLs: http://dataplane:PORT only (ingress /data is not on in-container routes).
+  internalDockerUseOriginOnly: false
   host: ${DEV_USERNAME}.${REMOTE_HOST}
   tls: ${TLS_ENABLED}
 
@@ -63,6 +65,8 @@ build:
   envOutputPath: ../../.env       # Copy to repo root for local dev
   language: python                # Runtime language for template selection (typescript or python)
   reloadStart: uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-3001} --reload  # PORT set from port above at run time; default 3001 must match port
+  # Pulled-image local compose (no bind-mount): drives `command` in generated docker-compose. Override for non-standard images (e.g. stub ACR tags).
+  imageRun: exec python -m uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-3001}
 
 # =============================================================================
 # Portal Input Configuration (Deployment Wizard)

package/templates/applications/dataplane/rbac.yaml

@@ -232,19 +232,19 @@ permissions:
     roles: ["aifabrix-platform-admin", "aifabrix-security-admin", "aifabrix-compliance-admin", "aifabrix-observer"]
     description: "Read group information"
   
-  # OpenAPI file management
-  - name: "openapi-file:read"
+  # OpenAPI / MCP spec bundle (mounted specs under /api/v1/specs)
+  - name: "spec:read"
     roles: ["aifabrix-platform-admin", "aifabrix-security-admin", "aifabrix-deployment-admin", "aifabrix-compliance-admin", "aifabrix-developer", "aifabrix-observer"]
-    description: "Read OpenAPI files"
-  
-  - name: "openapi-file:update"
+    description: "Read OpenAPI/MCP spec bundles"
+
+  - name: "spec:update"
     roles: ["aifabrix-platform-admin", "aifabrix-developer"]
-    description: "Update OpenAPI files"
-  
-  - name: "openapi-file:delete"
+    description: "Update OpenAPI/MCP spec bundles (uploaded or user-owned)"
+
+  - name: "spec:delete"
     roles: ["aifabrix-platform-admin", "aifabrix-developer"]
-    description: "Delete OpenAPI files"
-  
+    description: "Delete OpenAPI/MCP spec bundles (user-owned only; internal specs are not deletable via API)"
+
   # External data source write operations
   - name: "external-data-source:write"
     roles: ["aifabrix-platform-admin", "aifabrix-developer"]

package/templates/applications/keycloak/env.template

@@ -23,15 +23,17 @@ KC_HTTP_RELATIVE_PATH=url://vdir-public
 # must use the PUBLIC URL as issuer in all tokens so they match what the
 # controller expects (KEYCLOAK_SERVER_URL).
 # - Users log in via http://localhost:${KEYCLOAK_PUBLIC_PORT} (browser/CLI)
-# - Server calls Keycloak at http://keycloak:8080 for token exchange and refresh
+# - Server calls Keycloak at url://keycloak-internal for token exchange and refresh
 # - Controller sends Host: localhost:${KEYCLOAK_PUBLIC_PORT} so Keycloak validates issuer
 #   against public URL (requires KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true)
 # When KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true, hostname must be a full URL.
-# Use host-only origin (no /auth); KC_HTTP_RELATIVE_PATH carries the front-door path (url://vdir-public).
-# Hostname v2: port belongs in KC_HOSTNAME (url://host-public expands to e.g. http://localhost:8182 or
-# https://devNN.example.com). Do not set KC_HOSTNAME_PORT (deprecated v1; triggers Quarkus warnings).
-# KEYCLOAK_PUBLIC_PORT = application.yaml `port` (host-published) + dev×100; used by other apps / docs.
-KC_HOSTNAME=url://host-public
+# KC_HTTP_RELATIVE_PATH carries the runtime base path (url://vdir-public), and application.yaml
+# frontDoorRouting exposes the same path for internal server-to-server URLs when enabled.
+# Hostname v2: use a full public URL so Keycloak generates redirects that preserve the /auth base path.
+# `url://public` expands to the full front-door URL (including /auth when Traefik + frontDoorRouting.enabled are on).
+# NOTE: Prefer KC_HOSTNAME (not KC_HOSTNAME_URL). hostname-url triggers legacy hostname v1 warnings and, depending on
+# runtime, may not be treated as an active hostname for hostname-backchannel-dynamic.
+KC_HOSTNAME=url://public
 # nginx / Traefik send X-Forwarded-*; required when using an edge proxy (Keycloak 26+).
 KC_PROXY_HEADERS=xforwarded
 # Required for Host header to work: Keycloak resolves backchannel URL from request headers

package/templates/applications/miso-controller/application.yaml

@@ -7,6 +7,8 @@ app:
   version: '1.9.5'
 
 # Image Configuration
+# Set tag to match your build (e.g. aifabrix build miso-controller -t 1.0.0 then tag: 1.0.0)
+# Registry is required so the controller can pull the image (avoids "docker: not found" on the controller host).
 image:
   name: aifabrix/miso-controller
   tag: latest
@@ -21,6 +23,8 @@ port: 3000
 frontDoorRouting:
   pattern: /miso/*
   enabled: true
+  # Docker url://internal full URLs: http://miso-controller:PORT only (ingress /miso is not on in-container routes).
+  internalDockerUseOriginOnly: false
   host: ${DEV_USERNAME}.${REMOTE_HOST}
   tls: ${TLS_ENABLED}
 
@@ -57,6 +61,11 @@ build:
   language: typescript # Runtime language for template selection (typescript or python)
   reloadStart: pnpm run start:reload # When running with --reload
 
+# Repository Configuration (pipeline validate: REPOSITORY_URL_MISMATCH)
+repository:
+  enabled: true
+  repositoryUrl: https://github.com/aifabrix/aifabrix-miso
+
 # =============================================================================
 # Portal Input Configuration (Deployment Wizard)
 # =============================================================================