@aifabrix/builder 2.59.0 → 2.60.0

package/lib/agent-kit/git-identity.js

@@ -0,0 +1,180 @@
+/**
+ * Git commit identity for onboarding and Agent Kit GitHub work.
+ *
+ * Resolution order:
+ *   1. Existing `git config` — never rewritten, because it is the user's own setting.
+ *   2. The AI Fabrix login token's claims, offered as editable defaults.
+ *   3. The prompt answer, written to git config.
+ *
+ * The GitHub token is deliberately not used for the address: `gh api user` returns null whenever
+ * the account keeps its email private, and reading `user/emails` would demand the broader `user`
+ * scope for a value the login token already holds.
+ *
+ * @fileoverview Resolve and persist git user.name / user.email
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const logger = require('../utils/logger');
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * @param {Function} exec - execFileSync
+ * @param {string} key - Config key
+ * @param {boolean} global - Read the global scope only
+ * @returns {string} Trimmed value or ''
+ */
+function readConfig(exec, key, global) {
+  try {
+    const args = global ? ['config', '--global', '--get', key] : ['config', '--get', key];
+    return String(exec('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Current identity, preferring any effective value (local or global) over none.
+ * @param {Object} [options] - `execFileSync`
+ * @returns {{ name: string, email: string, complete: boolean }}
+ */
+function readGitIdentity(options = {}) {
+  const exec = options.execFileSync || execFileSync;
+  const name = readConfig(exec, 'user.name', false);
+  const email = readConfig(exec, 'user.email', false);
+  return { name, email, complete: Boolean(name && email) };
+}
+
+function decodeJwtClaims(token) {
+  const raw = String(token || '');
+  const parts = raw.split('.');
+  if (parts.length < 2) return null;
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Name and email from the AI Fabrix login token, used as prompt defaults.
+ * @param {Object} [options] - `config` and `controller` overrides for tests
+ * @returns {Promise<{ name: string, email: string }>} Empty strings when unavailable
+ */
+async function identityFromLoginToken(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const controller = options.controller || (await config.getControllerUrl());
+    if (!controller) return { name: '', email: '' };
+    const entry = await config.getDeviceToken(controller);
+    const claims = decodeJwtClaims(entry && (entry.token || entry.accessToken));
+    if (!claims) return { name: '', email: '' };
+    return {
+      name: String(claims.name || '').trim(),
+      email: String(claims.email || claims.preferred_username || '').trim()
+    };
+  } catch {
+    return { name: '', email: '' };
+  }
+}
+
+/**
+ * @param {Object} [options] - `config`
+ * @returns {Promise<string>} adminEmail from config.yaml, or ''
+ */
+async function emailFromConfig(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const cfg = await config.getConfig();
+    return String((cfg && cfg.adminEmail) || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} value - Candidate address
+ * @returns {boolean|string} true, or the reason it is rejected
+ */
+function validateEmail(value) {
+  return EMAIL_RE.test(String(value || '').trim()) || 'Enter an email address, for example name@example.com';
+}
+
+function validateName(value) {
+  return String(value || '').trim().length > 0 || 'Enter the name to record on commits';
+}
+
+async function promptIdentity(defaults, deps) {
+  const inquirer = deps.inquirer || require('inquirer');
+  return inquirer.prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Name for git commits',
+      default: defaults.name || undefined,
+      validate: validateName
+    },
+    {
+      type: 'input',
+      name: 'email',
+      message: 'Email for git commits',
+      default: defaults.email || undefined,
+      validate: validateEmail
+    }
+  ]);
+}
+
+function writeGitIdentity(identity, options) {
+  const exec = options.execFileSync || execFileSync;
+  exec('git', ['config', '--global', 'user.name', identity.name], { stdio: 'ignore' });
+  exec('git', ['config', '--global', 'user.email', identity.email], { stdio: 'ignore' });
+}
+
+function missingIdentityError(defaults) {
+  const name = defaults.name || 'Your Name';
+  const email = defaults.email || 'you@example.com';
+  return new Error(
+    'Git commit identity is not configured. Run:\n' +
+    `  git config --global user.name ${JSON.stringify(name)}\n` +
+    `  git config --global user.email ${email}`
+  );
+}
+
+/**
+ * Ensures git has a commit identity, asking only when one is missing.
+ * @param {Object} [options] - `interactive`, `execFileSync`, `inquirer`, `config`
+ * @returns {Promise<{ name: string, email: string, source: 'git'|'prompt' }>}
+ */
+async function ensureGitIdentity(options = {}) {
+  const current = readGitIdentity(options);
+  if (current.complete) {
+    return { name: current.name, email: current.email, source: 'git' };
+  }
+  const token = await identityFromLoginToken(options);
+  const defaults = {
+    name: current.name || token.name,
+    email: current.email || token.email || (await emailFromConfig(options))
+  };
+  if (!options.interactive) {
+    throw missingIdentityError(defaults);
+  }
+  logger.log('Git commit identity is not set. Defaults come from your AI Fabrix login; edit if needed.');
+  const answers = await promptIdentity(defaults, options);
+  const identity = { name: String(answers.name).trim(), email: String(answers.email).trim() };
+  writeGitIdentity(identity, options);
+  logger.log(`Git identity set to ${identity.name} <${identity.email}>`);
+  return { ...identity, source: 'prompt' };
+}
+
+module.exports = {
+  readGitIdentity,
+  identityFromLoginToken,
+  emailFromConfig,
+  ensureGitIdentity,
+  validateEmail,
+  validateName
+};

package/lib/agent-kit/setup.js

@@ -8,6 +8,7 @@ const { auditLog } = require('../core/audit-logger');
 const { normalizeSetup, preflight, resolveWork } = require('./setup-context');
 const { acquireWorkspace } = require('./setup-state');
 const { ensureController, ensureGithubLogin, ensureProvider } = require('./setup-auth');
+const { ensureGitIdentity } = require('./git-identity');
 const { prepareWorkspace, validateExisting } = require('./setup-workspace');
 const { prepareSession, attachSession } = require('./setup-session');
 const { managedSetupOptions } = require('./setup-managed');
@@ -19,6 +20,8 @@ async function authenticate(context, options, setPhase) {
   if (context.fullName) {
     setPhase('github-login');
     ensureGithubLogin(options);
+    // Commits need an author. The login token supplies the default; the user can change it.
+    await ensureGitIdentity({ ...options, interactive: options.interactive !== false });
   }
   if (context.code === 'cursor') return null;
   setPhase('agent-login');

package/lib/agent-kit/start.js

@@ -116,6 +116,27 @@ function claudeInnerArgs(p) {
   ]);
 }
 
+/**
+ * POSIX single-quote escaping for a value sent to a shell via tmux send-keys.
+ * @param {string} value - Raw value
+ * @returns {string} Quoted value
+ */
+function shellQuote(value) {
+  const escaped = String(value).split('\'').join('\'\\\'\'');
+  return `'${escaped}'`;
+}
+
+/**
+ * Codex authenticates inside the session, not in the window that launched it. Running it as the
+ * tmux session command makes the session end with the sign-in process, so the shell owns the
+ * window and codex is started inside it with send-keys.
+ * @param {object} p - Start parameters
+ * @returns {string} Shell command to run inside the session
+ */
+function codexStartCommand(p) {
+  return p.binary ? `exec ${shellQuote(p.binary)}` : 'exec codex';
+}
+
 /**
  * @param {object} p
  * @returns {object}
@@ -127,12 +148,17 @@ function buildTmuxSpec(p) {
     ? ['new-session', '-d', '-s', p.session, '-c', p.cwd]
     : ['new-session', '-s', p.session, '-c', p.cwd];
   const remote = p.app === 'claude' && p.remoteControl;
+  // codex: shell owns the window, codex starts inside it (see codexStartCommand).
+  const launchArgs = p.app === 'codex'
+    ? [...mode]
+    : [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra];
   return {
     bin: 'tmux',
-    args: [...mode, ...(p.binary ? ['env', p.binary] : [spec.bin]), ...extra],
+    args: launchArgs,
     session: p.session,
     appBin: spec.bin,
     needTmux: true,
+    innerCommand: p.app === 'codex' ? codexStartCommand(p) : undefined,
     remoteControlName: remote ? p.remoteControlName : undefined,
     remoteControlPrefix: remote ? p.remoteControlPrefix : undefined
   };
@@ -333,6 +359,22 @@ function executeStart(options, context, execute) {
     startCodexRemote(options, context.remoteSpec);
   }
   spawnLaunch(options, context.spec);
+  sendInnerCommand(options, context.spec);
+}
+
+/**
+ * Starts the agent inside an existing session window. Only codex uses this; the session must exist
+ * first, which is why it runs after the launch.
+ * @param {object} options - Start options
+ * @param {object} spec - Launch spec
+ * @returns {void}
+ */
+function sendInnerCommand(options, spec) {
+  if (!spec.innerCommand) {
+    return;
+  }
+  const exec = options.execFileSync || execFileSync;
+  exec('tmux', ['send-keys', '-t', `=${spec.session}`, spec.innerCommand, 'Enter'], { stdio: 'inherit' });
 }
 
 /**
@@ -363,6 +405,8 @@ function runStart(options) {
 
 module.exports = {
   START_APPS,
+  codexStartCommand,
+  sendInnerCommand,
   normalizeStartApp,
   sanitizeSessionName,
   resolveSessionName,

package/lib/api/role-assistant-test-job.api.js

@@ -0,0 +1,60 @@
+/**
+ * Dataplane asynchronous Role Assistant test job API.
+ *
+ * @fileoverview Enqueue and poll published Role Assistant cases
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { throwIfApiFailed } = require('./api-response-errors');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+function jobPath(systemIdOrKey, suffix = '') {
+  const key = encodeURIComponent(String(systemIdOrKey || '').trim());
+  return `/api/v1/external/systems/${key}/role-assistant-tests/jobs${suffix}`;
+}
+
+function unwrapJob(res) {
+  const value = unwrapApiData(res);
+  if (value && typeof value === 'object' && !Array.isArray(value) && value.data) {
+    return value.data;
+  }
+  return value;
+}
+
+async function enqueueRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  body
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey);
+  const res = await client.post(path, { body, timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+async function getRoleAssistantTestJob(
+  dataplaneUrl,
+  authConfig,
+  systemIdOrKey,
+  jobId
+) {
+  const suffix = `/${encodeURIComponent(String(jobId || '').trim())}`;
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const path = jobPath(systemIdOrKey, suffix);
+  const res = await client.get(path, { timeoutMs: 60000 });
+  throwIfApiFailed(res, {
+    endpointUrl: `${String(dataplaneUrl || '').replace(/\/$/, '')}${path}`
+  });
+  return unwrapJob(res);
+}
+
+module.exports = {
+  enqueueRoleAssistantTestJob,
+  getRoleAssistantTestJob
+};

package/lib/api/work-search.api.js

@@ -121,16 +121,23 @@ async function getWorkRoles(dataplaneUrl, authConfig) {
 
 /**
  * GET-equivalent work.skills for one roleRef.
- * Requests detail=full so search.resourceTypes (executable grammar) is present.
- * Compact summary omits that slice and cannot evaluate named viewpoint ops.
+ * Defaults to detail=full so search.resourceTypes (executable grammar) is present.
+ * A caller may request progressive resource/operation detail for skills-only checks.
  * @requiresPermission {Dataplane} Authenticated (oauth2: [])
  * @async
  */
-async function getWorkSkills(dataplaneUrl, authConfig, roleRef) {
-  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, {
+async function getWorkSkills(dataplaneUrl, authConfig, roleRef, options = {}) {
+  const args = {
     roleRef: String(roleRef || '').trim(),
-    detail: 'full'
-  });
+    detail: String(options.detail || 'full').trim()
+  };
+  if (typeof options.resourceType === 'string' && options.resourceType.trim()) {
+    args.resourceType = options.resourceType.trim();
+  }
+  if (typeof options.operation === 'string' && options.operation.trim()) {
+    args.operation = options.operation.trim();
+  }
+  return executeLayerBTool(dataplaneUrl, authConfig, LAYER_B_TOOLS.skills, args);
 }
 
 /**

package/lib/app/deploy.js

@@ -268,7 +268,14 @@ async function executeStandardDeployment(appName, options) {
   const controllerUrl = config.controllerUrl || 'unknown';
   const appExists = await checkApplicationExists(appName, controllerUrl, config.envKey, config.auth);
 
-  const { manifest, manifestPath } = await generateAndValidateManifest(appName, options);
+  // A controller deployment ships tokens plus the platforms/environments sections, so the
+  // Controller resolves them per installation and can promote dev -> tst without regenerating.
+  // Local runs and an explicit --resource-group resolve here instead.
+  const resolveHere = Boolean(options.local || options.resourceGroup);
+  const { manifest, manifestPath } = await generateAndValidateManifest(appName, {
+    ...options,
+    ...(resolveHere ? { target: { environment: config.envKey, resourceGroup: options.resourceGroup } } : {})
+  });
   applyManifestOverrides(manifest, options);
   validateImageIsPullable(manifest.image, appName);
   displayDeploymentInfo(manifest, manifestPath);

package/lib/app/show-display.js

@@ -234,6 +234,7 @@ function logExternalSystemMain(ext) {
   logger.log(`  Version:       ${ext.version ?? '—'}`);
   logger.log(`  Credential:    ${formatCredentialShowLine(ext)}`);
   logger.log(`  Status:        ${formatDataplaneStatusDisplay(ext.status)}`);
+  logger.log(`  System link:   ${ext.systemUrl ?? '—'}`);
   logger.log(`  API docs:      ${ext.openApiDocsPageUrl ?? ext.apiDocumentUrl ?? '—'}`);
   logger.log(`  MCP server:    ${ext.mcpServerUrl ?? '—'}`);
   logger.log(`  OpenAPI spec:  ${ext.apiDocumentUrl ?? '—'}`);

package/lib/app/show-online.js

@@ -89,6 +89,7 @@ function buildOnlineSummaryFromDataplane(appKey, controllerUrl, dataplaneUrl, ex
 
 async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCert, authBundle) {
   await enrichExternalShowSummary(summary, appKey, verifyCert, authBundle);
+  attachSystemUrl(summary);
   attachRunDefaultsFromUserConfig(summary, appKey, await getConfig());
   await attachDeclarativeUrlsToShowApplication(summary, appKey);
   if (json) {
@@ -100,6 +101,20 @@ async function finishOnlineShow(summary, appKey, json, permissionsOnly, verifyCe
   displayShow(summary, { permissionsOnly: !!permissionsOnly });
 }
 
+/**
+ * Expose the Dataplane system browser route for humans and agents.
+ * Preserve the deployment base path (for example /data).
+ * @param {Object} summary - Online application summary
+ */
+function attachSystemUrl(summary) {
+  const ext = summary.externalSystem;
+  if (!summary.isExternal || !ext || ext.error || !ext.dataplaneUrl) return;
+  const baseUrl = ext.dataplaneUrl.replace(/\/+$/, '');
+  const systemKey = ext.systemKey || summary.appKey;
+  const section = /^(ra-|ek-)/.test(systemKey) ? 'enterprise-knowledge' : 'connected-systems';
+  ext.systemUrl = `${baseUrl}/${section}/${encodeURIComponent(systemKey)}`;
+}
+
 async function runOnlineFromDataplane(appKey, json, permissionsOnly, verifyCert, authConfig, authResult) {
   const environment = await resolveEnvironment();
   const dataplaneUrl = await resolveDataplaneUrl(authResult.actualControllerUrl, environment, authConfig);

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

@@ -81,13 +81,16 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
   await ensureRunSecretsForApp(appName);
   const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
   const { primary, aliases, tags } = options.tagPlan;
+  // `build.target` selects a stage of a multi-stage Dockerfile, so one source tree can
+  // produce more than one image. Absent, Docker builds the last stage as before.
+  const target = buildConfig && buildConfig.target;
   await dockerBuild.executeDockerBuildWithTag(
     effectiveImageName,
     imageName,
     dockerfilePath,
     contextPath,
     primary,
-    { ...options, buildArgs, tagAliases: aliases }
+    { ...options, buildArgs, tagAliases: aliases, target }
   );
   await postBuildTasks(appName, buildConfig);
   logger.log(formatSuccessParagraph('Build completed successfully!'));

package/lib/cli/setup-app.js

@@ -362,7 +362,7 @@ function setupDockerfileGenerateCommand(program) {
 }
 
 function setupDeployCommand(program) {
-  program.command('deploy <appKey|systemKey>')
+  addDeployTargetOptions(program.command('deploy <appKey|systemKey>'))
     .description('Deploy builder app or external system via Miso Controller (Azure or --local)')
     .addHelpText('after', DEPLOY_HELP_AFTER)
     .option('--local', 'Send manifest to controller then run app locally (app: same as aifabrix run <app>; external: restart dataplane)')
@@ -410,6 +410,19 @@ function setupDeployCommand(program) {
     });
 }
 
+/**
+ * Deployment-target options. A controller deployment normally ships {NAME} tokens plus the
+ * platforms/environments sections; these flags force local resolution instead.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
+ */
+function addDeployTargetOptions(command) {
+  return command.option(
+    '-g, --resource-group <name>',
+    'Target Azure resource group; resolves platforms values in the generated manifest instead of shipping tokens'
+  );
+}
+
 function setupPushDeployDockerfileCommands(program) {
   program.command('push <appKey>')
     .description('Push builder appKey image to Azure Container Registry')

package/lib/cli/setup-utility.js

@@ -65,6 +65,23 @@ async function handleSplitJsonCommand(appName, options) {
   return generator.splitDeployJson(deployJsonPath, outputDir);
 }
 
+/**
+ * Deployment target for manifest generation. A resource group resolves platform values; the
+ * environment key resolves the environments layer. Without either, {NAME} tokens are preserved.
+ * @param {Object} options - Command options
+ * @returns {Promise<{ resourceGroup: string|undefined, environment: string }>}
+ */
+async function buildGenerationTarget(options = {}) {
+  // Only an explicit target resolves. The default artifact keeps {NAME} tokens and carries the
+  // platforms/environments sections, so the Controller resolves them per installation.
+  if (!options.resourceGroup && !options.env) return undefined;
+  const { resolveEnvironment } = require('../core/config');
+  const environment = options.env
+    ? String(options.env).trim().toLowerCase()
+    : await resolveEnvironment();
+  return { resourceGroup: options.resourceGroup, environment };
+}
+
 /**
  * Logs split-json results
  * @param {Object} result - Generated file paths
@@ -93,6 +110,11 @@ function logSplitJsonResult(result) {
 function setupJsonCommand(program) {
   program.command('json <appKey|systemKey>')
     .description('Write deployment JSON to disk for version control')
+    .option(
+      '-g, --resource-group <name>',
+      'Target Azure resource group; resolves platforms/environments values instead of leaving {NAME} tokens'
+    )
+    .option('-e, --env <env>', 'Deployment environment key for environments resolution (default: current environment)')
     .addHelpText('after', JSON_HELP_AFTER)
     .action(async(appName, options) => {
       try {
@@ -105,7 +127,8 @@ function setupJsonCommand(program) {
           json: false
         });
         const result = await generator.generateDeployJsonWithValidation(appName, {
-          ...options
+          ...options,
+          target: await buildGenerationTarget(options)
         });
         if (result.success) {
           const fileName = result.path.includes('application-schema.json') ? 'application-schema.json' : 'deployment JSON';

package/lib/commands/role-assistant.js

@@ -41,6 +41,10 @@ const {
   patchCaseStatusAfterRun
 } = require('../role-assistant/test-pack-sync');
 const { collectString } = require('./governance');
+const {
+  hasRoleAssistantTestSubject,
+  runPublishedCaseAsSubject
+} = require('../role-assistant/test-job-runner');
 const {
   sectionTitle,
   headerKeyValue,
@@ -338,6 +342,9 @@ async function resolveExecutableCaseResult(roleKey, roleCase, opts, result, verd
     run: false,
     noPublish: true
   });
+  if (hasRoleAssistantTestSubject(opts)) {
+    return runPublishedCaseAsSubject(roleKey, roleCase, opts, authContext);
+  }
   const evidencePreflight = await assertRoleAssistantEvidencePreflight(roleCase, authContext);
   const executionResult = await runRoleAssistantCaseLifecycle(roleKey, roleCase, authContext, opts);
   const executionVerdict = lifecycleVerdictFromCaseExecution(executionResult, verdict);

package/lib/core/env-platform-expand.js

@@ -0,0 +1,93 @@
+/**
+ * `{NAME}` expansion in env content (plan 200.0).
+ *
+ * Values resolved from the manifest `platforms` / `environments` sections are substituted into
+ * `env.template` values. Runs after `kv://` and before `url://`, so a resolved value may itself
+ * carry a declarative URL.
+ *
+ * Only the value side of `KEY=value` is touched, and only `{UPPER_SNAKE}` tokens that are not
+ * preceded by `$`. That leaves Builder's existing `${VAR}` expansion and `{lowercase}` text in
+ * comments alone — both appear in shipped templates.
+ *
+ * @fileoverview Platform/environment name expansion for env.template
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { resolveConfiguration } = require('../utils/platform-resolution');
+
+/** `{NAME}` not preceded by `$`; uppercase only, matching the configuration name pattern. */
+const NAME_TOKEN = /(?<!\$)\{([A-Z_][A-Z0-9_]*)\}/g;
+
+/**
+ * @param {Object} [manifest] - Application manifest
+ * @returns {boolean} True when the manifest declares either section
+ */
+function declaresPlatformSections(manifest) {
+  if (!manifest || typeof manifest !== 'object') return false;
+  return Array.isArray(manifest.platforms) || Array.isArray(manifest.environments);
+}
+
+function expandValue(value, values, key, strict, context = {}) {
+  return value.replace(NAME_TOKEN, (match, name) => {
+    if (Object.prototype.hasOwnProperty.call(values, name)) return values[name];
+    if (!strict) return match;
+    // Without a resource group no platform matched, so only environments and built-ins resolved.
+    // Saying so turns "why is this missing" into "declare it here".
+    const where = context.resourceGroup
+      ? `resource group "${context.resourceGroup}" and environment "${context.environment || ''}"`
+      : `environment "${context.environment || ''}" (no resource group, so platform values are unavailable)`;
+    throw new Error(
+      `${key} references {${name}}, which no platform or environment configuration resolves for ` +
+      `${where}. Declare it under environments, or run against a resource group that supplies it.`
+    );
+  });
+}
+
+/**
+ * Expands `{NAME}` on the value side of every assignment line.
+ * @param {string} content - Env content
+ * @param {Object} values - Resolved names
+ * @param {Object} [opts] - `strict` (default true) errors on an unresolved name; false leaves the
+ *   token in place for a later resolver (the deploy manifest, resolved by Miso per installation)
+ * @returns {string}
+ * @throws {Error} When strict and a referenced name is not resolved
+ */
+function expandNamesInEnvContent(content, values, opts = {}) {
+  const strict = opts.strict !== false;
+  const context = { environment: opts.environment, resourceGroup: opts.resourceGroup };
+  const lines = String(content || '').split('\n');
+  const out = lines.map(line => {
+    const trimmed = line.trimStart();
+    if (!trimmed || trimmed.startsWith('#')) return line;
+    const separator = line.indexOf('=');
+    if (separator < 0) return line;
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    return `${key}=${expandValue(value, values, key.trim(), strict, context)}`;
+  });
+  return out.join('\n');
+}
+
+/**
+ * Resolves the manifest sections and expands `{NAME}` when either section is declared.
+ * A manifest without them is returned untouched, so existing applications are unaffected.
+ * @param {string} content - Env content after kv:// resolution
+ * @param {Object} params - `manifest`, `environment` (deployment env key), `resourceGroup`, `strict`
+ * @returns {string}
+ */
+function expandPlatformNamesIfPresent(content, params = {}) {
+  const { manifest, environment, resourceGroup, strict } = params;
+  if (!declaresPlatformSections(manifest)) return content;
+  const { values } = resolveConfiguration(manifest, { environment, resourceGroup });
+  return expandNamesInEnvContent(content, values, { strict, environment, resourceGroup });
+}
+
+module.exports = {
+  NAME_TOKEN,
+  declaresPlatformSections,
+  expandNamesInEnvContent,
+  expandPlatformNamesIfPresent
+};