@aifabrix/builder 2.60.0 → 2.61.2

package/lib/app/run-parameter-sync.js

@@ -0,0 +1,142 @@
+/**
+ * Hydrate missing application-owned parameters before a local governed run.
+ *
+ * Local/database controllers deliberately leave database generators to Builder. In
+ * client-credentials mode the application cannot start until those values are in its
+ * bootstrap snapshot, so Builder fills only unresolved declared rows through the
+ * application's own client token. Existing Controller values are never overwritten.
+ *
+ * @fileoverview Local run parameter hydration for governed bootstrap
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+const { ApiClient } = require('../api');
+const { getToken } = require('../api/auth.api');
+const { getControllerDeploymentType } = require('../api/controller-health.api');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getBuilderPath } = require('../utils/paths');
+const { mapEnvToCatalogKeys, parseEnvAssignments } = require('../utils/system-secret-mapping');
+const { getInfraParameterCatalog } = require('../parameters/infra-parameter-catalog');
+
+const LOCAL_DEPLOYMENTS = new Set(['local', 'database']);
+const IDENTITY_NAMES = new Set([
+  'MISO_CLIENTID',
+  'MISO_CLIENT_ID',
+  'MISO_CLIENTSECRET',
+  'MISO_CLIENT_SECRET'
+]);
+
+function statusOf(response) {
+  const value = response && (response.status || response.statusCode || response.response?.status);
+  return Number.isInteger(value) ? value : 0;
+}
+
+function failed(response) {
+  return Boolean(response && (response.success === false || statusOf(response) >= 400));
+}
+
+function tokenFrom(response) {
+  const body = response && response.data !== undefined ? response.data : response;
+  const payload = body && body.data !== undefined ? body.data : body;
+  const token = payload && payload.token;
+  if (!token || typeof token !== 'string') {
+    throw new Error('Controller client-token response is invalid');
+  }
+  return token;
+}
+
+function credentialPair(env) {
+  const clientId = env.get('MISO_CLIENTID') || env.get('MISO_CLIENT_ID');
+  const clientSecret = env.get('MISO_CLIENTSECRET') || env.get('MISO_CLIENT_SECRET');
+  if (!clientId || !clientSecret) {
+    throw new Error('MISO client credentials are required for governed local configuration');
+  }
+  return { clientId, clientSecret };
+}
+
+function uniqueRows(mapping, catalog = getInfraParameterCatalog()) {
+  const rows = new Map();
+  for (const row of mapping.pushable) {
+    if (IDENTITY_NAMES.has(row.name)) continue;
+    const generatorType = catalog.findEntryForKey(row.catalogKey)?.generator?.type;
+    if (generatorType !== 'databaseUrl' && generatorType !== 'databasePassword') continue;
+    const prior = rows.get(row.catalogKey);
+    if (prior && prior.value !== row.value) {
+      throw new Error(`Conflicting local values resolve to parameter '${row.catalogKey}'`);
+    }
+    rows.set(row.catalogKey, row);
+  }
+  return [...rows.values()];
+}
+
+async function isMissing(client, key) {
+  const response = await client.get(`/api/v1/parameters/${encodeURIComponent(key)}`);
+  if (!failed(response)) return false;
+  if (statusOf(response) === 404) return true;
+  throw new Error(`Unable to inspect governed parameter '${key}'`);
+}
+
+async function writeMissing(client, row) {
+  const response = await client.put(`/api/v1/parameters/${encodeURIComponent(row.catalogKey)}`, {
+    body: { value: row.value }
+  });
+  if (failed(response)) {
+    throw new Error(`Unable to initialize governed parameter '${row.catalogKey}'`);
+  }
+}
+
+async function resolveSyncContext(appName, runEnvPath, deps) {
+  const readFile = deps.readFile || fs.readFile;
+  const envContent = await readFile(runEnvPath, 'utf8');
+  const env = parseEnvAssignments(envContent);
+  if (env.get('MISO_AUTH_MODE') !== 'client-credentials') return null;
+  const controllerUrl = await (deps.resolveControllerUrl || resolveControllerUrl)();
+  if (!controllerUrl) throw new Error('Controller URL is required for governed local configuration');
+  const deploymentType = await (deps.getControllerDeploymentType || getControllerDeploymentType)(controllerUrl);
+  if (!LOCAL_DEPLOYMENTS.has(String(deploymentType || '').toLowerCase())) return null;
+  const templatePath = path.join((deps.getBuilderPath || getBuilderPath)(appName), 'env.template');
+  const templateContent = await readFile(templatePath, 'utf8');
+  const catalog = (deps.getInfraParameterCatalog || getInfraParameterCatalog)();
+  return {
+    controllerUrl,
+    credentials: credentialPair(env),
+    rows: uniqueRows(mapEnvToCatalogKeys(envContent, templateContent), catalog)
+  };
+}
+
+/**
+ * Initialize unresolved local parameter rows needed by a client-credentials snapshot.
+ * @param {string} appName Application key
+ * @param {string} runEnvPath Resolved app-only run env
+ * @param {Object} [deps] Test dependencies
+ * @returns {Promise<number>} Number of rows initialized
+ */
+async function hydrateMissingLocalParameters(appName, runEnvPath, deps = {}) {
+  const context = await resolveSyncContext(appName, runEnvPath, deps);
+  if (!context || context.rows.length === 0) return 0;
+  const response = await (deps.getToken || getToken)(
+    context.credentials.clientId,
+    context.credentials.clientSecret,
+    context.controllerUrl
+  );
+  const client = deps.client || new ApiClient(context.controllerUrl, {
+    type: 'client-token', token: tokenFrom(response)
+  });
+  let initialized = 0;
+  for (const row of context.rows) {
+    if (!(await isMissing(client, row.catalogKey))) continue;
+    await writeMissing(client, row);
+    initialized += 1;
+  }
+  return initialized;
+}
+
+module.exports = {
+  credentialPair,
+  hydrateMissingLocalParameters,
+  tokenFrom,
+  uniqueRows
+};

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

@@ -52,10 +52,13 @@ function applyMisoControllerUiBuildArgs(buildArgs, envMap) {
  *
  * @param {string} appName
  * @param {string} [contextPath] Docker build context (repo root for miso-controller)
+ * @param {Object} [options] - `runEnvKey`: environment key for manifest {NAME} resolution
+ *   (defaults to the current CLI environment inside generateEnvContent)
  * @returns {Promise<Object.<string, string>>}
  */
-async function resolveDockerBuildArgsForApp(appName, contextPath) {
-  const envMap = await secretsEnvWrite.resolveAndGetEnvMap(appName, { environment: 'docker' });
+async function resolveDockerBuildArgsForApp(appName, contextPath, options = {}) {
+  const runEnvKey = options && options.runEnvKey ? String(options.runEnvKey) : undefined;
+  const envMap = await secretsEnvWrite.resolveAndGetEnvMap(appName, { environment: 'docker', runEnvKey });
   const { getBashPrefixedProcessEnvOverlay } = require('../utils/bash-secret-env');
   const bashOverlay = await getBashPrefixedProcessEnvOverlay(null, appName);
   const buildArgs = {};

package/lib/build/index.js

@@ -191,12 +191,13 @@ async function generateDockerfile(appNameOrPath, language, config, buildConfig =
  * @param {Object} options - Build options
  */
 
-async function postBuildTasks(appName, buildConfig) {
+async function postBuildTasks(appName, buildConfig, options = {}) {
   try {
     // Validate that env.template + secrets resolve cleanly, but never write <appPath>/.env or
     // envOutputPath. Build args still flow through resolveAndGetEnvMap (in-memory). Run
     // `aifabrix resolve <app>` to materialize an on-disk .env.
-    await secrets.generateEnvFile(appName, buildConfig.secrets, 'docker', false, { noWrite: true });
+    const runEnvKey = options && options.env ? String(options.env) : undefined;
+    await secrets.generateEnvFile(appName, buildConfig.secrets, 'docker', false, { noWrite: true, runEnvKey });
     logger.log(formatSuccessLine('Env resolution validated (in-memory only; run "aifabrix resolve ' + appName + '" for on-disk .env)'));
   } catch (error) {
     logger.log(formatWarningLine(`Could not resolve env: ${error.message}`));

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

@@ -79,7 +79,7 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
     buildHelpers
   );
   await ensureRunSecretsForApp(appName);
-  const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
+  const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath, { runEnvKey: options.env });
   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.
@@ -92,7 +92,7 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
     primary,
     { ...options, buildArgs, tagAliases: aliases, target }
   );
-  await postBuildTasks(appName, buildConfig);
+  await postBuildTasks(appName, buildConfig, options);
   logger.log(formatSuccessParagraph('Build completed successfully!'));
   return tags.map((tag) => `${effectiveImageName}:${tag}`).join(', ');
 }

package/lib/cli/setup-app.js

@@ -243,6 +243,10 @@ function registerBuildCommand(program) {
       'Image tag or comma-separated tags (default: latest); {version} expands to app.version, e.g. "latest,{version}"'
     )
     .option('-r, --registry <registry>', 'Registry host for the image name (overrides dev set-registry and application.yaml)')
+    .option(
+      '-e, --env <env>',
+      'Environment key used to resolve manifest {NAME} values (dev|tst|pro); defaults to the current CLI environment'
+    )
     .option(
       '--base',
       'Build/run the manifest base image (no -devN suffix). Default local build uses a developer-scoped repository when developer-id > 0.'
@@ -255,6 +259,7 @@ function registerBuildCommand(program) {
 Examples:
   $ aifabrix build myapp
   $ aifabrix build myapp --tag v1.0.0            # also tags latest
+  $ aifabrix build myapp --env dev               # resolve manifest {NAME} values for dev
   $ aifabrix build myapp --base --from-dev --tag 'latest,{version}'
   $ aifabrix build myapp --registry myregistry.azurecr.io`)
     .action(async(appName, options) => {

package/lib/cli/setup-environment.js

@@ -118,6 +118,79 @@ Typical workflow:
 
 Subcommands:
   deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
+  secret         Installation configuration on the Controller (push, list)
+`;
+
+const SECRET_GROUP_HELP_AFTER = `
+Installation configuration held by the Controller. Push updates declared variables and secrets;
+list reads them for one application or every authorized application.
+
+Scope, compared with the other two stores:
+  aifabrix secret        your own local secrets.local.yaml (and the shared store)
+  aifabrix credential    a Connected System's credentials on the Dataplane
+  aifabrix env secret    this installation's secrets on the Controller
+
+Secret values are write-only: they can be set and never read back. Listing shows values only
+for rows the Controller authoritatively classifies as non-sensitive variables.
+
+The environment is a parameter. Omit it to use the one in config.yaml
+(aifabrix auth set-environment <env>).
+
+Examples:
+  $ aifabrix env secret list --app builder-api
+  $ aifabrix env secret list dev --app mori-controller
+  $ aifabrix env secret push --app mori-controller
+  $ af env secret push miso --app mori-controller --dry-run
+`;
+
+const SECRET_PUSH_HELP_AFTER = `
+Reads values from the application's ignored .env and matches each variable name to the
+Controller's declaration. Non-sensitive variables use configuration PUT; secrets use the
+protected system-secret PUT. Undeclared .env names are skipped.
+
+Secrets: pass paths only. The value is read from the file and never taken from the command
+line, so it cannot reach shell history or a process list. No value is printed or logged on
+any path, including failure.
+
+Environment: omit to use the configured one, or name it explicitly.
+--key is the variable name from .env, not the Controller declaration key.
+Without --key, an interactive terminal asks before pushing all declared values. Automation
+and AI usage must pass --yes explicitly. Dry-run never prompts and never writes.
+
+Examples:
+  Preview one value from mori-controller's default .env, then push it to dev:
+  $ aifabrix env secret push dev --app mori-controller --key NOTIFICATION_EVENT_WEBHOOK_SECRET --dry-run
+  $ aifabrix env secret push dev --app mori-controller --key NOTIFICATION_EVENT_WEBHOOK_SECRET
+
+  Preview every declared configuration value found in the app's default .env:
+  $ aifabrix env secret push dev --app mori-controller --dry-run
+
+  Push every declared value after reviewing the dry run (interactive confirmation):
+  $ aifabrix env secret push dev --app mori-controller
+
+  Push every declared value non-interactively after explicit approval:
+  $ aifabrix env secret push dev --app mori-controller --yes
+
+  Preview values from a different ignored env file:
+  $ af env secret push dev --app mori-controller --file ./path/to/ignored.env --dry-run
+`;
+
+const SECRET_LIST_HELP_AFTER = `
+Shows declared configuration in a compact table. Without --app, the Application column
+lists every authorized owner; with --app, only that exact owner is shown. Non-sensitive
+variable values are shown. Secret values, references, vault names and ciphertext are never shown.
+
+Environment: omit to use the configured one, or name it explicitly.
+--app optionally identifies one exact owner; * means the literal wildcard owner.
+--key searches that owner's secret key and environment-variable names by substring.
+The table has Status, Name, Type and Value headers (plus Application without --app).
+Rows use ✔ for configured, ⚠ for required missing, and ⏭ for optional unset.
+
+Examples:
+  $ aifabrix env secret list dev
+  $ aifabrix env secret list --app mori-controller
+  $ aifabrix env secret list dev --app builder-api
+  $ aifabrix env secret list --app mori-controller --key policy
 `;
 
 function setupEnvironmentCommands(program) {
@@ -136,6 +209,89 @@ function setupEnvironmentCommands(program) {
     .option('--no-poll', 'Do not poll for status'))
     .addHelpText('after', DEPLOY_EXAMPLES)
     .action(deployEnvHandler);
+
+  setupEnvSecretCommands(env);
+}
+
+/**
+ * @param {string|undefined} envKey - Positional environment
+ * @param {Object} options - CLI options
+ * @returns {Promise<void>} Exits non-zero on failure
+ */
+async function envSecretPushHandler(envKey, options) {
+  try {
+    const { resolveEnvSecretContext, resolveAppPaths } = require('../commands/env-secret-context');
+    const { runEnvSecretPush } = require('../commands/env-secret-push-run');
+    const { confirmBulkSecretPush } = require('../commands/env-secret-push-confirm');
+    const base = await resolveEnvSecretContext(envKey, options);
+    const paths = resolveAppPaths(options.app, options);
+    const confirmed = await confirmBulkSecretPush(base, options);
+    if (!confirmed) return;
+    const { exitCode } = await runEnvSecretPush({ ...base, ...paths }, {
+      key: options.key,
+      application: options.app,
+      dryRun: options.dryRun === true
+    });
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  } catch (error) {
+    handleCommandError(error, 'env secret push');
+    process.exit(1);
+  }
+}
+
+/**
+ * @param {string|undefined} envKey - Positional environment
+ * @param {Object} options - CLI options
+ * @returns {Promise<void>} Exits non-zero on failure
+ */
+async function envSecretListHandler(envKey, options) {
+  try {
+    const { resolveEnvSecretContext } = require('../commands/env-secret-context');
+    const { runEnvSecretList } = require('../commands/env-secret-list');
+    const ctx = await resolveEnvSecretContext(envKey, options);
+    const { exitCode } = await runEnvSecretList(ctx, { key: options.key, application: options.app });
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+  } catch (error) {
+    handleCommandError(error, 'env secret list');
+    process.exit(1);
+  }
+}
+
+/**
+ * `aifabrix env secret` — installation secrets on the Controller.
+ * @param {import('commander').Command} env - The env command group
+ * @returns {void}
+ */
+function setupEnvSecretCommands(env) {
+  const secret = env
+    .command('secret')
+    .description('Installation configuration on the Controller (secret values remain write-only)')
+    .addHelpText('after', SECRET_GROUP_HELP_AFTER);
+
+  // The API takes the environment in the path, so both commands accept it; omitted, it falls
+  // back to the one in config.yaml. Push and list have distinct resource contracts.
+  secret
+    .command('push [env]')
+    .description('Push declared configuration from an app env file (values are never arguments)')
+    .option('--app <appKey>', 'Exact application owner of the configuration declarations')
+    .option('--file <path>', 'Env file to read values from (default: the app\'s .env)')
+    .option('--key <variable>', 'Push one .env variable name')
+    .option('--dry-run', 'Show what would be pushed and write nothing')
+    .option('-y, --yes', 'Confirm bulk push without prompting (automation / AI usage)')
+    .addHelpText('after', SECRET_PUSH_HELP_AFTER)
+    .action(envSecretPushHandler);
+
+  secret
+    .command('list [env]')
+    .description('List configuration types, safe values and status by application')
+    .option('--app <appKey>', 'Only this exact application owner (* is the wildcard owner)')
+    .option('--key <text>', 'Search key and environment-variable names')
+    .addHelpText('after', SECRET_LIST_HELP_AFTER)
+    .action(envSecretListHandler);
 }
 
 module.exports = { setupEnvironmentCommands, deployEnvHandler, addMarketplaceOptions };

package/lib/commands/datasource-capability-upsert-cli.js

@@ -0,0 +1,112 @@
+/**
+ * `datasource capability upsert` command registration.
+ *
+ * @fileoverview Explicit upsert candidate authoring CLI
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const {
+  formatBlockingError,
+  headerKeyValue,
+  infoLine,
+  formatWarningLine,
+  formatNextActions
+} = require('../utils/cli-test-layout-chalk');
+const { runCapabilityUpsert } = require('../datasource/capability/run-capability-upsert');
+const { printCapabilitySuccessFooter } = require('./datasource-capability-output');
+
+const HELP = `
+Authors a manifest-declared upsert candidate only when create, update, business
+identity, and an exact vendor lookup are already declared. This is static
+authoring eligibility, not live readiness certification.
+
+  $ aifabrix datasource capability upsert my-datasource --dry-run --json
+  $ aifabrix datasource capability upsert ./datasource.yaml --identity domain
+`;
+
+function printHumanResult(result) {
+  if (result.dryRun) {
+    logger.log(infoLine('Dry run — planned JSON Patch operations:'));
+    logger.log('');
+    logger.log(JSON.stringify(result.patchOperations, null, 2));
+  } else {
+    if (result.backupPath) logger.log(headerKeyValue('Backup:', result.backupPath));
+    printCapabilitySuccessFooter(result.resolvedPath, result.updatedSections);
+  }
+  logger.log(formatWarningLine('Candidate authored — live readiness is not yet verified'));
+  logger.log(formatNextActions(result.nextActions));
+}
+
+function printUpsertIssues(issues) {
+  (issues || []).forEach((issue) => {
+    const code = issue.code ? `[${issue.code}] ` : '';
+    logger.log(formatWarningLine(`${code}${issue.message}`));
+    const details = [
+      ['Consequence', issue.consequence],
+      ['Can AI fix?', issue.aiFixable === true ? 'Yes, with an authorized local manifest change' : 'No automatic fix is safe'],
+      ['Safe action', issue.remediation],
+      ['Prevention', issue.prevention],
+      ['Residual risk', issue.residualRisk]
+    ];
+    details.forEach(([label, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      values.filter(Boolean).forEach((item) => logger.log(`  ${label}: ${item}`));
+    });
+  });
+}
+
+async function runUpsertAction(fileOrKey, options) {
+  const result = await runCapabilityUpsert({
+    fileOrKey,
+    as: options.as,
+    create: options.create,
+    update: options.update,
+    identity: options.identity,
+    test: Boolean(options.test),
+    dryRun: Boolean(options.dryRun),
+    overwrite: Boolean(options.overwrite),
+    noBackup: Boolean(options.noBackup)
+  });
+  if (options.json) {
+    logger.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  printHumanResult(result);
+}
+
+function setupCapabilityUpsertCommand(cap) {
+  cap.command('upsert <file-or-key>')
+    .description('Author an upsert candidate from declared identity and exact OpenAPI coverage')
+    .option('--as <key>', 'Target capability key', 'upsert')
+    .option('--create <key>', 'Existing create-shaped capability', 'create')
+    .option('--update <key>', 'Existing update-shaped capability', 'update')
+    .option('--identity <fields>', 'Comma-separated mapped business identity fields')
+    .option('--test', 'Add proof scaffolding when existing safe fixture facts are sufficient')
+    .option('--dry-run', 'Print JSON Patch operations; do not write')
+    .option('--overwrite', 'Replace only the target upsert slice after full analysis')
+    .option('--no-backup', 'Skip backup copy under integration/<app>/backup/')
+    .option('--json', 'Print a machine-readable result envelope')
+    .addHelpText('after', HELP)
+    .action(async(fileOrKey, options) => {
+      try {
+        await runUpsertAction(fileOrKey, options);
+      } catch (error) {
+        if (options.json) {
+          logger.log(JSON.stringify({ eligible: false, issues: error.analysis?.issues || [], error: error.message }, null, 2));
+        } else {
+          logger.error(formatBlockingError(`capability upsert failed: ${error.message}`));
+          printUpsertIssues(error.analysis?.issues);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  setupCapabilityUpsertCommand,
+  runUpsertAction,
+  printHumanResult,
+  printUpsertIssues
+};

package/lib/commands/datasource-capability.js

@@ -1,5 +1,5 @@
 /**
- * Datasource capability subcommands (copy, remove, create, diff, edit, validate).
+ * Datasource capability subcommands (copy, create, upsert, remove, diff, edit, validate).
  *
  * @fileoverview Nested `aifabrix datasource capability` CLI (copy, relate, …)
  * @author AI Fabrix Team
@@ -26,6 +26,7 @@ const pathMod = require('path');
 const { printCapabilitySuccessFooter } = require('./datasource-capability-output');
 const { setupCapabilityRelateCommand } = require('./datasource-capability-relate-cli');
 const { setupCapabilityDimensionCommand } = require('./datasource-capability-dimension-cli');
+const { setupCapabilityUpsertCommand } = require('./datasource-capability-upsert-cli');
 
 const CAP_COPY_HELP = `
 Examples:
@@ -386,7 +387,7 @@ function setupDatasourceCapabilityCommands(datasource) {
   const cap = datasource
     .command('capability')
     .description(
-      'Copy, remove, relate (FK metadata), diff, edit, or validate per-capability slices in datasource JSON'
+      'Copy, create, upsert, remove, relate, diff, edit, or validate datasource capability slices'
     );
   if (typeof cap.alias === 'function') {
     cap.alias('cap');
@@ -395,6 +396,7 @@ function setupDatasourceCapabilityCommands(datasource) {
   setupCapabilityCopyCommand(cap);
   setupCapabilityRemoveCommand(cap);
   setupCapabilityCreateCommand(cap);
+  setupCapabilityUpsertCommand(cap);
   setupCapabilityRelateCommand(cap);
   setupCapabilityDimensionCommand(cap);
   setupCapabilityDiffCommand(cap);

package/lib/commands/env-secret-context.js

@@ -0,0 +1,113 @@
+/**
+ * Resolve where `aifabrix env secret` reads from and writes to.
+ *
+ * The controller URL is resolved once and printed before any write, because pushing into
+ * the wrong installation is silent and unrecoverable — no value can be read back to show
+ * what was overwritten.
+ *
+ * @fileoverview env secret: controller, environment and file resolution
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveControllerUrl } = require('../utils/controller-url');
+const { getOrRefreshDeviceToken } = require('../utils/token-manager');
+const { normalizeControllerUrl, resolveEnvironment } = require('../core/config');
+const { getAppPath, getIntegrationPath } = require('../utils/paths');
+
+/**
+ * @param {string} controllerUrl - Raw controller URL
+ * @returns {Promise<Object>} Auth config carrying a bearer token
+ * @throws {Error} When no usable token is stored
+ */
+async function resolveAuth(controllerUrl) {
+  const normalized = normalizeControllerUrl(controllerUrl);
+  const deviceToken = await getOrRefreshDeviceToken(normalized);
+  if (deviceToken && deviceToken.token) {
+    return { token: deviceToken.token, controllerUrl: deviceToken.controller || normalized };
+  }
+  throw new Error('Not signed in to the Controller. Run: aifabrix login');
+}
+
+/**
+ * Locate the application directory and env file holding the values.
+ * @param {string} appKey - Application key
+ * @param {Object} options - `file` overrides the env file path
+ * @returns {{ appPath: string, envFilePath: string }} Resolved paths
+ * @throws {Error} When the application cannot be located
+ */
+function resolveAppPaths(appKey, options = {}) {
+  if (!appKey) {
+    throw new Error('--app is required: the catalog keys are read from that application env.template');
+  }
+  // A platform application lives under builder/<appKey>/; an external system under
+  // integration/<systemKey>/. Prefer the candidate holding the default .env, then an existing
+  // application directory. An explicit --file supplies values but does not change ownership.
+  const candidates = [safePath(getAppPath, appKey), safePath(getIntegrationPath, appKey)]
+    .filter(Boolean);
+  const appPath = candidates.find(dir => fs.existsSync(path.join(dir, '.env'))) ||
+    candidates.find(dir => fs.existsSync(dir)) || candidates[0];
+  if (!appPath) {
+    throw new Error(`Application not found: ${appKey}`);
+  }
+  return {
+    appPath,
+    envFilePath: options.file ? path.resolve(options.file) : path.join(appPath, '.env')
+  };
+}
+
+/**
+ * @param {Function} resolver - Path helper
+ * @param {string} appKey - Application key
+ * @returns {string} Resolved path, or '' when the helper cannot resolve it
+ */
+function safePath(resolver, appKey) {
+  try {
+    return resolver(appKey) || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Build the context both subcommands share.
+ *
+ * The environment is the one recorded in config.yaml, not something a command accepts. It is
+ * changed deliberately with `aifabrix auth set-environment`, so a per-command override would
+ * let any string be treated as an environment and fail confusingly against the API.
+ *
+ * @param {Object} [options] - CLI options
+ * @returns {Promise<Object>} controllerUrl, authConfig, envKey
+ */
+async function resolveEnvSecretContext(envKey, options = {}) {
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error('No Controller URL configured. Run: aifabrix auth set-controller <url>');
+  }
+  const auth = await resolveAuth(controllerUrl);
+  // The API takes the environment in the path and accepts `*` for every installed
+  // environment. Omitted, it falls back to the one recorded in config.yaml.
+  const explicit = envKey === undefined || envKey === null ? '' : String(envKey).trim();
+  const resolvedEnv = explicit || await resolveEnvironment(options);
+  if (!resolvedEnv) {
+    throw new Error(
+      'No environment given and none configured. Pass one, use * for all, ' +
+      'or set a default with: aifabrix auth set-environment <env>'
+    );
+  }
+  return {
+    controllerUrl: auth.controllerUrl || controllerUrl,
+    authConfig: { token: auth.token },
+    envKey: resolvedEnv
+  };
+}
+
+module.exports = {
+  resolveAuth,
+  resolveAppPaths,
+  resolveEnvSecretContext
+};