@aifabrix/builder 2.44.6 → 2.45.0

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

@@ -1,8 +1,14 @@
 /**
- * Primary `urls.local.yaml` under {@link module:lib/utils/paths.getAifabrixHome} (same as
- * `secrets.local.yaml`). When that file is missing, falls back to the config directory for migration.
+ * 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
  */
@@ -14,17 +20,18 @@ 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; under resolved AI Fabrix home)
+ * @returns {string} Absolute path to urls.local.yaml (beside config.yaml)
  */
 function getUrlsLocalYamlPath() {
-  return path.join(pathsUtil.getAifabrixHome(), 'urls.local.yaml');
+  return path.join(pathsUtil.getConfigDirForPaths(), 'urls.local.yaml');
 }
 
-/** @returns {string} Path beside config.yaml (migration / older layouts) */
-function getConfigDirUrlsLocalYamlPath() {
-  return path.join(pathsUtil.getConfigDirForPaths(), 'urls.local.yaml');
+/** @returns {string} Legacy primary path from older CLI (under resolved AI Fabrix home) */
+function getLegacyUrlsLocalYamlPathAtAifabrixHome() {
+  return path.join(pathsUtil.getAifabrixHome(), 'urls.local.yaml');
 }
 
 function loadRegistryYamlFile(filePath) {
@@ -44,9 +51,9 @@ function readUrlsLocalRegistrySync() {
   if (fsRealSync.existsSync(primary)) {
     return loadRegistryYamlFile(primary);
   }
-  const atConfig = getConfigDirUrlsLocalYamlPath();
-  if (path.resolve(atConfig) !== path.resolve(primary) && fsRealSync.existsSync(atConfig)) {
-    return loadRegistryYamlFile(atConfig);
+  const legacy = getLegacyUrlsLocalYamlPathAtAifabrixHome();
+  if (path.resolve(legacy) !== path.resolve(primary) && fsRealSync.existsSync(legacy)) {
+    return loadRegistryYamlFile(legacy);
   }
   return {};
 }
@@ -90,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}
@@ -152,114 +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
+  }
+  try {
+    const pr = pathsUtil.getProjectRoot();
+    if (pr) {
+      out.push(path.join(pr, 'packages'));
+    }
+  } catch {
+    // 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);
+  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;
   }
-  let builderDirs = getOrderedBuilderDirsForRegistryScan(root, effectiveBuilderDir);
-  try {
-    const sysRoot = pathsUtil.getSystemBuilderRoot();
-    const resolvedSys = path.resolve(sysRoot);
-    if (fsRealSync.existsSync(sysRoot)) {
-      const resolvedList = builderDirs.map((d) => path.resolve(d));
-      if (!resolvedList.includes(resolvedSys)) {
-        builderDirs = [sysRoot, ...builderDirs];
-      }
-    }
-  } catch {
-    // ignore
-  }
-  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
@@ -293,5 +363,6 @@ module.exports = {
   writeUrlsLocalRegistrySync,
   refreshUrlsLocalRegistryFromBuilder,
   normalizePatternForUrl,
-  getRegistryEntryForApp
+  getRegistryEntryForApp,
+  readRegistryInternalDockerUseOriginOnly
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.44.6",
+  "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

@@ -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/miso-controller/application.yaml

@@ -23,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}
 

package/templates/applications/miso-controller/env.template

@@ -57,7 +57,6 @@ NODE_ENV=dev
 PORT=${PORT}
 AUTO_CREATE_TABLES=true
 FAST_STARTUP=false
-ALLOWED_ORIGINS=http://localhost:*,url://host-public,url://host-private,url://dataplane-host-public,url://dataplane-host-private
 ENABLE_API_DOCS=true
 
 # Rate Limiting Configuration (for local development)
@@ -141,6 +140,33 @@ KEYCLOAK_EVENTS_SECRET=kv://keycloak-events-secretKeyVault
 WAIT_FOR_KEYCLOAK=true
 # KEYCLOAK_WAIT_TIMEOUT=60
 
+# =============================================================================
+# MISO CONTROLLER CONFIGURATION
+# =============================================================================
+# Web Server URL (for OpenAPI documentation server URLs and Keycloak callbacks)
+# This is the PUBLIC-FACING URL that browsers/users access (e.g., http://localhost:3100)
+# Used to generate correct server URLs in OpenAPI spec and Keycloak callback URLs
+# For Docker: use localhost with mapped port (e.g., localhost:3100)
+# For production: use public domain (e.g., https://miso.example.com)
+# url://public includes front-door path from application.yaml (e.g. /controller).
+MISO_WEB_SERVER_URL=url://public
+MISO_CONTROLLER_URL=url://internal
+MISO_RELATIVE_PATH=url://vdir-public
+ALLOWED_ORIGINS=http://localhost:*,url://host-public,url://host-private,url://dataplane-host-public,url://dataplane-host-private
+
+# MISO Environment Configuration (miso, dev, tst, pro)
+MISO_ENVIRONMENT=miso
+
+# MISO Application Client Credentials (per application)
+MISO_CLIENTID=kv://miso-controller-client-idKeyVault
+MISO_CLIENTSECRET=kv://miso-controller-client-secretKeyVault
+
+# Evaluation mode (optional .env override of DB controller.configuration.evaluation):
+# When true (default if DB omits flag), infra deploy may coerce :envKey to `miso` — e2e poll on `dev` can 404.
+# Set false locally to force path envKey to match deploy + GET .../deployments/:id.
+# Unset = use DB only.
+CONTROLLER_EVALUATION=
+
 # =============================================================================
 # TENANT ACTIVATION (TA-3) — EXISTING LLM CATALOG
 # =============================================================================
@@ -301,34 +327,6 @@ JWT_SECRET=kv://miso-controller-jwt-secretKeyVault
 # When API_KEY is set, a matching Bearer token bypasses OAuth2 validation
 API_KEY=kv://miso-controller-secrets-apiKeyVault
 
-# NPM token for private package (npmjs.org)
-NPM_TOKEN=kv://BASH_NPM_TOKEN
-
-# =============================================================================
-# MISO CONTROLLER CONFIGURATION
-# =============================================================================
-# Web Server URL (for OpenAPI documentation server URLs and Keycloak callbacks)
-# This is the PUBLIC-FACING URL that browsers/users access (e.g., http://localhost:3100)
-# Used to generate correct server URLs in OpenAPI spec and Keycloak callback URLs
-# For Docker: use localhost with mapped port (e.g., localhost:3100)
-# For production: use public domain (e.g., https://miso.example.com)
-# url://public includes front-door path from application.yaml (e.g. /controller).
-MISO_WEB_SERVER_URL=url://public
-MISO_CONTROLLER_URL=url://internal
-MISO_RELATIVE_PATH=url://vdir-public
-# MISO Environment Configuration (miso, dev, tst, pro)
-MISO_ENVIRONMENT=miso
-
-# MISO Application Client Credentials (per application)
-MISO_CLIENTID=kv://miso-controller-client-idKeyVault
-MISO_CLIENTSECRET=kv://miso-controller-client-secretKeyVault
-
-# Evaluation mode (optional .env override of DB controller.configuration.evaluation):
-# When true (default if DB omits flag), infra deploy may coerce :envKey to `miso` — e2e poll on `dev` can 404.
-# Set false locally to force path envKey to match deploy + GET .../deployments/:id.
-# Unset = use DB only.
-CONTROLLER_EVALUATION=
-
 # =============================================================================
 # LICENSE CONFIGURATION
 # =============================================================================

package/.npmrc.token

@@ -1 +0,0 @@
-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