@aifabrix/builder 2.57.0 → 2.59.0

package/lib/utils/image-tags.js

@@ -0,0 +1,88 @@
+/**
+ * Image tag lists for build and push: comma-separated tags, exact `{version}` expansion from the
+ * application's `app.version`, Docker tag validation, and order-preserving de-duplication.
+ * All validation happens before any Docker call.
+ *
+ * @fileoverview Shared image tag resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { assertSafeTag } = require('./resolve-docker-image-ref');
+
+const DEFAULT_TAG = 'latest';
+const VERSION_PLACEHOLDER = '{version}';
+/** Tags that are floating aliases themselves (a single explicit one gets no extra `latest`). */
+const FLOATING_TAGS = Object.freeze(['latest', 'main']);
+
+/**
+ * @param {Object} [appConfig] - Application manifest (possibly wrapped in `variables`)
+ * @returns {string} Trimmed `app.version` or ''
+ */
+function readAppVersion(appConfig) {
+  const cfg = appConfig?.variables?.app ? appConfig.variables : appConfig;
+  const raw = cfg?.app?.version;
+  return raw === undefined || raw === null ? '' : String(raw).trim();
+}
+
+function expandTag(entry, version) {
+  if (entry === VERSION_PLACEHOLDER) {
+    if (!version) {
+      throw new Error('Tag {version} requires a non-empty app.version in the application manifest');
+    }
+    return version;
+  }
+  if (entry.includes('{') || entry.includes('}')) {
+    throw new Error(`Unsupported tag placeholder "${entry}"; only the exact token {version} is supported`);
+  }
+  return entry;
+}
+
+/**
+ * Resolves a tag option into a validated, de-duplicated list (first occurrence wins).
+ * @param {string|undefined} tagInput - `--tag` value (omitted means `latest`)
+ * @param {string} appVersion - Application `app.version`
+ * @returns {string[]}
+ * @throws {Error} On blank entries, unsupported placeholders, missing version or invalid tags
+ */
+function resolveImageTags(tagInput, appVersion) {
+  if (tagInput === undefined || tagInput === null || String(tagInput).trim() === '') {
+    return [DEFAULT_TAG];
+  }
+  const entries = String(tagInput).split(',').map((entry) => entry.trim());
+  if (entries.some((entry) => entry === '')) {
+    throw new Error(`Invalid tag list "${tagInput}": remove empty entries between commas`);
+  }
+  const resolved = [];
+  for (const entry of entries) {
+    const tag = assertSafeTag(expandTag(entry, String(appVersion || '').trim()));
+    if (!resolved.includes(tag)) resolved.push(tag);
+  }
+  return resolved;
+}
+
+/**
+ * Build plan: the first tag is the Docker build target; the rest are aliases of the same image.
+ * A single explicit non-floating tag keeps its compatibility `latest` alias.
+ * @param {string|undefined} tagInput - `--tag` value
+ * @param {string} appVersion - Application `app.version`
+ * @returns {{ primary: string, aliases: string[], tags: string[] }}
+ */
+function resolveBuildTagPlan(tagInput, appVersion) {
+  const tags = resolveImageTags(tagInput, appVersion);
+  const explicitSingle = tags.length === 1 && tagInput !== undefined && tagInput !== null && String(tagInput).trim() !== '';
+  if (explicitSingle && !FLOATING_TAGS.includes(tags[0])) {
+    tags.push(DEFAULT_TAG);
+  }
+  return { primary: tags[0], aliases: tags.slice(1), tags };
+}
+
+module.exports = {
+  DEFAULT_TAG,
+  VERSION_PLACEHOLDER,
+  readAppVersion,
+  resolveImageTags,
+  resolveBuildTagPlan
+};

package/lib/utils/promote-dev-docker-image.js

@@ -88,6 +88,12 @@ function resolvePromoteVersionTag(options = {}) {
  * @returns {string[]}
  */
 function resolvePromoteBaseTags(options = {}) {
+  if (options.tagPlan && Array.isArray(options.tagPlan.tags) && options.tagPlan.tags.length > 0) {
+    // Shared build tag plan (comma list / {version}); every tag becomes a base alias.
+    const tags = [...options.tagPlan.tags];
+    if (!tags.includes(PROMOTE_FLOATING_TAG)) tags.push(PROMOTE_FLOATING_TAG);
+    return tags;
+  }
   const versionTag = resolvePromoteVersionTag(options);
   const tags = [versionTag];
   if (versionTag !== PROMOTE_FLOATING_TAG) {

package/lib/utils/registry-credentials.js

@@ -0,0 +1,236 @@
+/**
+ * Host-scoped container registry credentials in the primary user secrets file.
+ *
+ * Keys are exactly `<registry>-username` and `<registry>-password` in the user's
+ * `secrets.local.yaml` (never the shared store). Values are encrypted through the existing
+ * local-secret writer and reach Docker only via `docker login --password-stdin`.
+ *
+ * @fileoverview Registry credential storage, lookup, removal, and per-command Docker login
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+const config = require('../core/config');
+const pathsUtil = require('./paths');
+const { loadExistingSecrets, mergeSecretsIntoFile } = require('./secrets-generator');
+const { saveLocalSecret } = require('./local-secrets');
+const { decryptSecret, isEncrypted } = require('./secrets-encryption');
+const { normalizeRegistryHost } = require('./config-registry-preference');
+
+/** Hosts already authenticated during this CLI process. */
+const authenticatedHosts = new Set();
+
+/**
+ * @param {string} registry - Registry host
+ * @returns {{ host: string, usernameKey: string, passwordKey: string }}
+ */
+function registryCredentialKeys(registry) {
+  const host = normalizeRegistryHost(registry);
+  return { host, usernameKey: `${host}-username`, passwordKey: `${host}-password` };
+}
+
+function hasValue(value) {
+  return typeof value === 'string' ? value.trim() !== '' : value !== undefined && value !== null;
+}
+
+function readRawPair(keys) {
+  const file = pathsUtil.getPrimaryUserSecretsLocalPath();
+  const raw = loadExistingSecrets(file);
+  return { file, username: raw[keys.usernameKey], password: raw[keys.passwordKey] };
+}
+
+function partialPairError(keys) {
+  return new Error(
+    `Registry credentials for ${keys.host} are incomplete: both ${keys.usernameKey} and ${keys.passwordKey} ` +
+    `must be set. Run "aifabrix dev set-registry ${keys.host} --username <username> --password-stdin" ` +
+    `or "aifabrix dev set-registry ${keys.host} --clear-credentials".`
+  );
+}
+
+/**
+ * Credential presence for a registry without decrypting anything.
+ * @param {string} registry - Registry host
+ * @returns {'complete'|'absent'|'partial'}
+ */
+function getRegistryCredentialStatus(registry) {
+  const keys = registryCredentialKeys(registry);
+  const pair = readRawPair(keys);
+  const count = [pair.username, pair.password].filter(hasValue).length;
+  if (count === 2) return 'complete';
+  return count === 0 ? 'absent' : 'partial';
+}
+
+async function decryptStoredValue(value, label) {
+  const text = String(value);
+  if (!isEncrypted(text)) return text;
+  const key = await config.getSecretsEncryptionKey();
+  if (!key) {
+    throw new Error(`Cannot decrypt the stored ${label}: the local secrets encryption key is not configured`);
+  }
+  return decryptSecret(text, key);
+}
+
+/**
+ * Loads a complete credential pair for the registry.
+ * @param {string} registry - Registry host
+ * @returns {Promise<{ username: string, password: string }|null>} null when no pair is stored
+ * @throws {Error} When only one of the two keys is stored
+ */
+async function loadRegistryCredentials(registry) {
+  const keys = registryCredentialKeys(registry);
+  const pair = readRawPair(keys);
+  const present = [pair.username, pair.password].filter(hasValue).length;
+  if (present === 0) return null;
+  if (present === 1) throw partialPairError(keys);
+  return {
+    username: await decryptStoredValue(pair.username, `${keys.host} username`),
+    password: await decryptStoredValue(pair.password, `${keys.host} password`)
+  };
+}
+
+function removeKeysFromFile(file, keyNames) {
+  if (!fs.existsSync(file)) return false;
+  const data = loadExistingSecrets(file);
+  const present = keyNames.filter((key) => Object.prototype.hasOwnProperty.call(data, key));
+  if (present.length === 0) return false;
+  for (const key of present) delete data[key];
+  const { assertWritableSecretsPathForTests } = require('./aifabrix-test-runtime-guard');
+  assertWritableSecretsPathForTests(file);
+  fs.writeFileSync(file, yaml.dump(data, { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false }), { mode: 0o600 });
+  // `mode` applies only on creation; keep an existing file owner-only too.
+  fs.chmodSync(file, 0o600);
+  return true;
+}
+
+function restorePair(keys, snapshot) {
+  const restore = {};
+  const remove = [];
+  for (const [key, value] of [[keys.usernameKey, snapshot.username], [keys.passwordKey, snapshot.password]]) {
+    if (value === undefined) remove.push(key);
+    else restore[key] = value;
+  }
+  removeKeysFromFile(snapshot.file, remove);
+  mergeSecretsIntoFile(snapshot.file, restore);
+}
+
+/**
+ * Saves a complete pair. On any write failure the previous entries are restored.
+ * @param {string} registry - Registry host
+ * @param {string} username - Registry username
+ * @param {string} password - Registry password or token
+ * @returns {Promise<{ host: string, rollback: Function }>} rollback restores the prior entries
+ */
+async function saveRegistryCredentials(registry, username, password) {
+  const keys = registryCredentialKeys(registry);
+  if (!hasValue(username) || !hasValue(password)) {
+    throw new Error('Registry username and password must both be non-empty');
+  }
+  const snapshot = readRawPair(keys);
+  await config.ensureSecretsEncryptionKey();
+  try {
+    await saveLocalSecret(keys.usernameKey, String(username));
+    await saveLocalSecret(keys.passwordKey, String(password));
+  } catch (error) {
+    restorePair(keys, snapshot);
+    throw new Error(`Could not save registry credentials for ${keys.host}; previous values were restored (${error.message})`);
+  }
+  authenticatedHosts.delete(keys.host);
+  return { host: keys.host, rollback: () => restorePair(keys, snapshot) };
+}
+
+/**
+ * Removes both credential keys for the registry (idempotent).
+ * @param {string} registry - Registry host
+ * @returns {boolean} true when at least one key was removed
+ */
+function removeRegistryCredentials(registry) {
+  const keys = registryCredentialKeys(registry);
+  authenticatedHosts.delete(keys.host);
+  return removeKeysFromFile(pathsUtil.getPrimaryUserSecretsLocalPath(), [keys.usernameKey, keys.passwordKey]);
+}
+
+/**
+ * Authenticates Docker to the registry once per process: stored pair first, then the optional
+ * fallback (for example Azure CLI for ACR). The password is sent only on stdin.
+ * @param {string} registry - Registry host
+ * @param {Object} [options] - Options
+ * @param {Function} [options.fallback] - async (host) => void when no pair is stored
+ * @param {Function} [options.login] - async (host, username, password) => void (tests)
+ * @returns {Promise<'cached'|'credentials'|'fallback'|'none'>}
+ */
+async function ensureRegistryLogin(registry, options = {}) {
+  const host = normalizeRegistryHost(registry);
+  if (authenticatedHosts.has(host)) return 'cached';
+  const credentials = await loadRegistryCredentials(host);
+  if (credentials) {
+    const login = options.login || require('../deployment/push').authenticateExternalRegistry;
+    await login(host, credentials.username, credentials.password);
+    authenticatedHosts.add(host);
+    return 'credentials';
+  }
+  if (typeof options.fallback === 'function') {
+    await options.fallback(host);
+    authenticatedHosts.add(host);
+    return 'fallback';
+  }
+  return 'none';
+}
+
+/**
+ * Registry host of an image reference, or '' for Docker Hub style refs.
+ * @param {string} imageRef - Image reference (`host/repo:tag`, `repo:tag`, ...)
+ * @returns {string}
+ */
+function registryHostFromImageRef(imageRef) {
+  const ref = String(imageRef || '').trim();
+  const slash = ref.indexOf('/');
+  if (slash <= 0) return '';
+  const first = ref.slice(0, slash);
+  if (!(first.includes('.') || first.includes(':') || first === 'localhost')) return '';
+  try {
+    return normalizeRegistryHost(first);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Logs in once per distinct registry host of the given image refs when a stored pair exists.
+ * Hosts without stored credentials are pulled anonymously (or with the user's own Docker login).
+ * @param {string[]} imageRefs - Image references
+ * @returns {Promise<string[]>} Hosts logged in with stored credentials
+ */
+async function ensureLoginForImageRefs(imageRefs) {
+  const hosts = [...new Set((imageRefs || []).map(registryHostFromImageRef).filter(Boolean))];
+  const used = [];
+  for (const host of hosts) {
+    const outcome = await ensureRegistryLogin(host);
+    if (outcome === 'credentials') used.push(host);
+  }
+  return used;
+}
+
+/**
+ * Forgets cached logins (used before re-authentication and in tests).
+ * @param {string} [registry] - Host to forget; all when omitted
+ */
+function resetRegistryLoginCache(registry) {
+  if (registry) authenticatedHosts.delete(normalizeRegistryHost(registry));
+  else authenticatedHosts.clear();
+}
+
+module.exports = {
+  registryCredentialKeys,
+  getRegistryCredentialStatus,
+  loadRegistryCredentials,
+  saveRegistryCredentials,
+  removeRegistryCredentials,
+  ensureRegistryLogin,
+  ensureLoginForImageRefs,
+  registryHostFromImageRef,
+  resetRegistryLoginCache
+};

package/lib/utils/resolve-docker-image-ref.js

@@ -1,6 +1,7 @@
 /**
  * Resolve Docker repository path and tag from application config and optional CLI overrides.
- * Precedence: --image (full ref), --registry CLI, image.registry in manifest, else unqualified name.
+ * Precedence: --image (full ref), --registry CLI, installation `registry` in config.yaml,
+ * image.registry in manifest, else unqualified name.
  *
  * For refs like localhost:5000/repo without an explicit tag, prefer --image with :tag (parse ambiguity).
  *
@@ -12,6 +13,7 @@
 'use strict';
 
 const { parseImageOverride } = require('./parse-image-ref');
+const { readInstallationRegistrySync } = require('./config-registry-preference');
 const DOCKER_REPOSITORY_RE = /^[a-z0-9][a-z0-9._/-]*$/i;
 const DOCKER_TAG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 
@@ -92,6 +94,73 @@ function normalizeDockerRegistryPrefix(registry) {
   return t.slice(0, end);
 }
 
+/**
+ * Remove a registry host prefix from a Docker repository path.
+ * The first segment is a host when it contains `.` or `:` or equals `localhost`.
+ * @param {string} repository
+ * @returns {string}
+ */
+function stripRegistryHostFromRepository(repository) {
+  if (!repository || typeof repository !== 'string') {
+    return repository;
+  }
+  const parts = repository.split('/');
+  if (parts.length <= 1) {
+    return repository;
+  }
+  const host = parts[0];
+  if (host.includes('.') || host.includes(':') || host === 'localhost') {
+    return parts.slice(1).join('/');
+  }
+  return repository;
+}
+
+/**
+ * Effective registry for an application image.
+ * Precedence: `options.registry` (CLI) > installation `registry` > manifest `image.registry`.
+ * @param {Object} [appConfig] - Application manifest
+ * @param {Object} [options] - `registry` (CLI) and optional `installationRegistry` (preloaded; '' = none)
+ * @returns {{ registry: string, source: 'cli'|'installation'|'manifest'|'none' }}
+ */
+function resolveEffectiveRegistry(appConfig, options = {}) {
+  const opts = options || {};
+  const cli = normalizeDockerRegistryPrefix(opts.registry);
+  if (cli) return { registry: cli, source: 'cli' };
+  const installation = opts.installationRegistry !== undefined
+    ? normalizeDockerRegistryPrefix(opts.installationRegistry)
+    : readInstallationRegistrySync();
+  if (installation) return { registry: installation, source: 'installation' };
+  const manifest = normalizeDockerRegistryPrefix(appConfig?.image?.registry ?? '');
+  if (manifest) return { registry: manifest, source: 'manifest' };
+  return { registry: '', source: 'none' };
+}
+
+/**
+ * Prefix a repository with a registry exactly once (replacing any existing host).
+ * @param {string} registry - Registry prefix ('' keeps the repository unchanged)
+ * @param {string} repository - Repository path, possibly already qualified
+ * @returns {string}
+ */
+function qualifyRepository(registry, repository) {
+  const prefix = normalizeDockerRegistryPrefix(registry);
+  if (!prefix) return repository;
+  return `${prefix}/${stripRegistryHostFromRepository(repository)}`;
+}
+
+/**
+ * Deployment/registration image reference (`registry/name:tag`) using the shared precedence.
+ * @param {Object} variables - Application manifest
+ * @param {string} fallbackName - Name when the manifest has no image name or app key
+ * @param {Object} [options] - Same options as {@link resolveEffectiveRegistry}
+ * @returns {string}
+ */
+function buildManifestImageReference(variables, fallbackName, options = {}) {
+  const imageName = variables?.image?.name || variables?.app?.key || fallbackName;
+  const tag = variables?.image?.tag || 'latest';
+  const { registry } = resolveEffectiveRegistry(variables, options);
+  return `${qualifyRepository(registry, imageName)}:${tag}`;
+}
+
 /**
  * Effective image repository (may include registry prefix) and tag for Docker.
  * @param {string} appName - Application name
@@ -118,13 +187,8 @@ function resolveDockerImageRef(appName, appConfig, runOptions = {}) {
 
   const baseRepo = assertSafeRepository(getRepositoryPathFromConfig(appConfig, appName));
   const imageTag = assertSafeTag(tagFromOpts || imageTagFromConfig(appConfig));
-  const prefix =
-    normalizeDockerRegistryPrefix(opts.registry) ||
-    normalizeDockerRegistryPrefix(appConfig?.image?.registry ?? '');
-  if (prefix) {
-    return { imageName: assertSafeRepository(`${prefix}/${baseRepo}`), imageTag };
-  }
-  return { imageName: baseRepo, imageTag };
+  const { registry } = resolveEffectiveRegistry(appConfig, opts);
+  return { imageName: assertSafeRepository(qualifyRepository(registry, baseRepo)), imageTag };
 }
 
 /**
@@ -137,7 +201,7 @@ function resolveDockerImageRef(appName, appConfig, runOptions = {}) {
 function resolveComposeImageOverrideString(appName, appConfig, options = {}) {
   if (options.image) return options.image;
   if (options.imageOverride) return options.imageOverride;
-  const runOpts = { registry: options.registry, image: undefined };
+  const runOpts = { registry: options.registry, installationRegistry: options.installationRegistry, image: undefined };
   if (options.tag) {
     const { imageName } = resolveDockerImageRef(appName, appConfig, runOpts);
     return `${imageName}:${options.tag}`;
@@ -154,6 +218,11 @@ function resolveComposeImageOverrideString(appName, appConfig, options = {}) {
 module.exports = {
   resolveDockerImageRef,
   resolveComposeImageOverrideString,
+  resolveEffectiveRegistry,
+  qualifyRepository,
+  buildManifestImageReference,
+  stripRegistryHostFromRepository,
+  assertSafeTag,
   normalizeDockerRegistryPrefix,
   getRepositoryPathFromConfig,
   imageTagFromConfig

package/lib/utils/secrets-helpers.js

@@ -29,7 +29,15 @@ const { collectUniqueKvPathStrings, isCommentOrEmptyLine, activeEnvLineForKvScan
  * @returns {string} Interpolated content
  */
 function interpolateEnvVars(content, envVars) {
-  return content.replace(/\$\{([A-Z_]+)\}/g, (match, envVar) => {
+  const hasOwn = (key) => Object.prototype.hasOwnProperty.call(envVars, key);
+  const interpolated = content.replace(
+    /\$\{DEV_USERNAME\}\.\$\{REMOTE_HOST\}/g,
+    (match) => {
+      if (!hasOwn('DEV_USERNAME') || !hasOwn('REMOTE_HOST')) return match;
+      return [envVars.DEV_USERNAME, envVars.REMOTE_HOST].filter(Boolean).join('.');
+    }
+  );
+  return interpolated.replace(/\$\{([A-Z_]+)\}/g, (match, envVar) => {
     return envVars[envVar] || match;
   });
 }

package/lib/utils/token-manager.js

@@ -11,6 +11,7 @@
 
 const config = require('../core/config');
 const logger = require('./logger');
+const { maskSensitiveData } = require('./log-redaction');
 const {
   refreshClientToken,
   refreshDeviceToken
@@ -99,55 +100,47 @@ async function getOrRefreshClientToken(environment, appName, controllerUrl) {
  * @returns {Promise<{token: string, controller: string}|null>} Token and controller URL, or null if not available
  */
 async function getOrRefreshDeviceToken(controllerUrl) {
-  // Try to get existing token
   const tokenInfo = await getDeviceToken(controllerUrl);
-
-  if (!tokenInfo) {
-    return null;
+  if (!tokenInfo) return null;
+  if (reusableDeviceToken(tokenInfo) && !shouldRefreshToken(tokenInfo.expiresAt)) {
+    return reusableDeviceToken(tokenInfo);
   }
-
-  // Check if token should be refreshed proactively (within 15 minutes of expiry)
-  // This ensures we refresh before Keycloak's SSO Session Idle timeout (30 minutes)
-  const needsRefresh = shouldRefreshToken(tokenInfo.expiresAt);
-
-  if (!needsRefresh) {
-    // Token is valid and doesn't need refresh yet
-    return {
-      token: tokenInfo.token,
-      controller: tokenInfo.controller
-    };
-  }
-
-  // Token needs refresh (expired or within 15 minutes of expiry)
-  // Try to refresh if refresh token exists
   if (!tokenInfo.refreshToken) {
-    const { isSetupPlatformFlow } = require('../commands/setup-run-context');
-    if (!isSetupPlatformFlow()) {
-      logger.warn(
-        'Access token expired and no refresh token available. Please login again using: aifabrix login'
-      );
+    const usable = reusableDeviceToken(tokenInfo);
+    if (!usable) {
+      warnRefreshFailureOnce(controllerUrl, 'No usable access token and no refresh token available. Please login again using: aifabrix login');
     }
-    return null;
+    return usable;
   }
-
   try {
     const refreshed = await refreshDeviceToken(controllerUrl, tokenInfo.refreshToken);
-    return {
-      token: refreshed.token,
-      controller: controllerUrl
-    };
+    return { token: refreshed.token, controller: controllerUrl };
   } catch (error) {
-    // Refresh failed - check if it's a refresh token expiry
-    const errorMessage = error.message || String(error);
-    if (errorMessage.includes('Refresh token has expired')) {
-      warnRefreshTokenExpiredOnce(controllerUrl, errorMessage);
+    let message = error.message || String(error);
+    for (const secret of [tokenInfo.token, tokenInfo.refreshToken]) {
+      if (secret) message = message.split(secret).join('***');
+    }
+    message = maskSensitiveData(message);
+    if (message.includes('Refresh token has expired')) {
+      warnRefreshTokenExpiredOnce(controllerUrl, message);
     } else {
-      warnRefreshFailureOnce(controllerUrl, errorMessage);
+      warnRefreshFailureOnce(controllerUrl, message);
     }
-    return null;
+    return reusableDeviceToken(tokenInfo);
   }
 }
 
+/**
+ * Reuse only a token whose actual expiry is known and still in the future.
+ * @param {Object} tokenInfo - Stored device token
+ * @returns {Object|null} Usable token, without refresh credentials
+ */
+function reusableDeviceToken(tokenInfo) {
+  const expiry = typeof tokenInfo.expiresAt === 'string' ? Date.parse(tokenInfo.expiresAt) : NaN;
+  return tokenInfo.token && Number.isFinite(expiry) && expiry > Date.now()
+    ? { token: tokenInfo.token, controller: tokenInfo.controller } : null;
+}
+
 /**
  * Validates deployment auth parameters
  * @function validateDeploymentAuthParams

package/lib/utils/variable-transformer.js

@@ -126,10 +126,8 @@ function transformFlatStructure(variables, appName) {
  * @returns {string} Image reference string
  */
 function buildImageReference(variables, appName) {
-  const imageName = variables.image?.name || variables.app?.key || appName;
-  const registry = variables.image?.registry;
-  const tag = variables.image?.tag || 'latest';
-  return registry ? `${registry}/${imageName}:${tag}` : `${imageName}:${tag}`;
+  const { buildManifestImageReference } = require('./resolve-docker-image-ref');
+  return buildManifestImageReference(variables, appName);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.57.0",
+  "version": "2.59.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -28,6 +28,7 @@
     "agent-skills:check": "node scripts/pnpm/agent-skills-sync.mjs --check",
     "agent-skills:sync:codex": "node scripts/pnpm/agent-skills-sync.mjs --codex-home",
     "agent-skills:test": "node --test scripts/pnpm/agent-skills-sync.test.mjs",
+    "dev-deploy:test": "node --test scripts/pnpm/dev-deploy.test.mjs",
     "check": "npm run lint && npm run test",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
@@ -130,7 +131,8 @@
     }
   },
   "dependencies": {
-    "@aifabrix/miso-client": "4.22.4",
+    "@aifabrix/miso-client": "4.23.1",
+    "@azure/identity": "4.11.1",
     "adm-zip": "^0.6.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/templates/agent-kit/instructions/AGENTKIT.md

@@ -2,6 +2,35 @@
 
 Builder-owned. `aifabrix agent-kit update` refreshes this file. If workspace `README.md` is missing, install/update creates it. An existing README is never overwritten.
 
+## Onboard
+
+On an organisation-managed SSH workspace with a provisioned `config.yaml`:
+
+```bash
+af onboarding
+af onboarding --coding claude   # or codex or cursor for this run
+```
+
+For Claude, onboarding starts or reuses a detached tmux session and prints
+its attach command. For Codex or Cursor, open the printed workspace in the
+selected coding client over SSH, then say “Hi”. `--coding` selects a platform
+for one run without changing the provisioned default.
+The agent reads this workspace's `AGENTS.md` and `README.md`, checks which
+packages already exist, and guides you to a first delivery task.
+
+On a Linux or macOS terminal with Builder, Git, and tmux:
+
+```bash
+aifabrix agent-kit setup https://controller.example.com
+```
+
+This prepares a local workspace under the configured AI Fabrix work directory and starts
+Codex. Select Claude with `--code claude`. GitHub is optional: add `--repo owner/name`
+to reuse a matching local checkout, clone a remote, or create a private repository.
+The repository name becomes the folder name; unresolved access stops safely.
+Setup preserves existing agent permissions. Change environment afterward with
+`aifabrix auth --set-environment <environment>`.
+
 ## Install
 
 From this git repository (Builder CLI on PATH):
@@ -57,7 +86,12 @@ curl -fsSL https://claude.ai/install.sh | bash
 claude auth login
 ```
 
-**Run in tmux** from this workspace so closing the terminal does not kill Claude. The command enables Remote Control and this workspace's Claude auto-approval by default. Remote Control is the **same** session on this PC, [claude.ai/code](https://claude.ai/code), and the Claude mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude `--tmux` is for worktrees only.
+**Optional terminal session in tmux:** run from this workspace so closing the
+terminal does not kill Claude. The command enables Remote Control and this
+workspace's Claude auto-approval by default. Remote Control is the **same**
+session on this PC, [claude.ai/code](https://claude.ai/code), and the Claude
+mobile app (Code). That is not `claude --cloud` (a separate cloud VM). Claude
+`--tmux` is for worktrees only.
 
 ```bash
 aifabrix agent-kit start claude
@@ -76,7 +110,10 @@ npm install -g @openai/codex
 codex login
 ```
 
-**Run in tmux** from this workspace so the session stays if you close the terminal. The command starts native Codex Remote Control and writes this workspace's Codex auto-approval by default:
+**Optional terminal session in tmux:** run from this workspace so a terminal
+Codex session stays after SSH disconnects. This session is separate from a
+Codex app chat opened over SSH. The command requests native Codex Remote
+Control and writes workspace auto-approval by default:
 
 ```bash
 aifabrix agent-kit start codex