@aifabrix/builder 2.59.0 → 2.61.2

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/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/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
+};

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

@@ -0,0 +1,200 @@
+/**
+ * Show compact configuration status without exposing sensitive values.
+ *
+ * @fileoverview aifabrix env secret list
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const logger = require('../utils/logger');
+const { listEnvironmentConfiguration } = require('../api/configuration.api');
+const {
+  colorAggregateGlyph,
+  metadata,
+  sectionTitle
+} = require('../utils/cli-layout-chalk');
+
+const FORBIDDEN_FIELDS = ['data', 'ciphertext', 'reference', 'vaultName', 'secretValue'];
+const WIDTHS = Object.freeze({ status: 6, application: 20, name: 28, type: 8, value: 48 });
+const GLYPHS = Object.freeze({ ok: '✔', warn: '⚠', skipped: '⏭' });
+
+/**
+ * @param {Object} row - Configuration metadata row
+ * @param {string} application - Optional expected owner
+ * @returns {void} Throws when unsafe or contradictory
+ */
+function assertSafeRow(row, application) {
+  if (!row || typeof row !== 'object') {
+    throw new Error('Configuration list returned invalid or unsafe metadata');
+  }
+  const owner = String(row.application || '').trim();
+  const name = String(row.name || row.key || '').trim();
+  const hasValue = Object.prototype.hasOwnProperty.call(row, 'value');
+  const safeValue = [!hasValue, row.sensitive === false && typeof row.value === 'string']
+    .some(Boolean);
+  const forbidden = FORBIDDEN_FIELDS.some(field =>
+    Object.prototype.hasOwnProperty.call(row, field)
+  );
+  const exactOwner = [!application, owner === application].some(Boolean);
+  const booleans = ['sensitive', 'configured', 'required']
+    .every(field => typeof row[field] === 'boolean');
+  const valid = [owner, name, exactOwner, booleans, safeValue, !forbidden].every(Boolean);
+  if (!valid) {
+    throw new Error('Configuration list returned invalid or unsafe metadata');
+  }
+}
+
+/**
+ * @param {Object} row - Configuration metadata row
+ * @param {string} application - Optional expected exact owner
+ * @returns {Object} Safe normalized row
+ */
+function normalizeRow(row, application) {
+  assertSafeRow(row, application);
+  const owner = String(row.application).trim();
+  const name = String(row.name || row.key).trim();
+  const hasValue = Object.prototype.hasOwnProperty.call(row, 'value');
+  const state = row.configured ? 'ok' : (row.required ? 'warn' : 'skipped');
+  const normalized = {
+    application: owner,
+    name,
+    type: row.sensitive ? 'secret' : 'variable',
+    configured: row.configured,
+    required: row.required,
+    state
+  };
+  if (!row.sensitive && hasValue) normalized.value = row.value;
+  return normalized;
+}
+
+/**
+ * @param {unknown} value - Cell value
+ * @returns {string} Safe single-line cell value
+ */
+function cleanCell(value) {
+  const noControls = [...String(value ?? '')]
+    .map(char => char.charCodeAt(0) <= 31 || char.charCodeAt(0) === 127 ? ' ' : char)
+    .join('');
+  return noControls.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * @param {unknown} value - Cell value
+ * @param {number} width - Visible cell width
+ * @returns {string} Single-line padded or truncated cell
+ */
+function formatCell(value, width) {
+  const clean = cleanCell(value);
+  const visible = clean.length > width ? `${clean.slice(0, width - 1)}…` : clean;
+  return visible.padEnd(width);
+}
+
+/**
+ * Keep identifiers complete while retaining compact minimum widths.
+ * @param {Array<Object>} rows - Safe normalized rows
+ * @returns {Object} Widths for this result set
+ */
+function tableWidths(rows) {
+  return {
+    ...WIDTHS,
+    application: Math.max(WIDTHS.application, ...rows.map(row => cleanCell(row.application).length)),
+    name: Math.max(WIDTHS.name, ...rows.map(row => cleanCell(row.name).length))
+  };
+}
+
+/**
+ * @param {Object} row - Safe normalized row
+ * @param {boolean} includeApplication - Include owner column
+ * @returns {string} One compact table row
+ */
+function formatRow(row, includeApplication, widths = WIDTHS) {
+  const glyph = colorAggregateGlyph(row.state, GLYPHS[row.state]);
+  const value = row.type === 'variable'
+    ? (row.value === '' ? '""' : (row.value ?? ''))
+    : '';
+  const cells = [glyph + ' '.repeat(widths.status - 1)];
+  if (includeApplication) cells.push(formatCell(row.application, widths.application));
+  cells.push(formatCell(row.name, widths.name));
+  cells.push(formatCell(row.type, widths.type));
+  cells.push(formatCell(value, widths.value).trimEnd());
+  return `  ${cells.join('  ')}`;
+}
+
+/**
+ * @param {boolean} includeApplication - Include owner column
+ * @returns {string[]} Header and divider
+ */
+function tableHeader(includeApplication, widths = WIDTHS) {
+  const headers = [formatCell('Status', widths.status)];
+  const dividers = ['-'.repeat(widths.status)];
+  if (includeApplication) {
+    headers.push(formatCell('Application', widths.application));
+    dividers.push('-'.repeat(widths.application));
+  }
+  headers.push(formatCell('Name', widths.name), formatCell('Type', widths.type), 'Value');
+  dividers.push('-'.repeat(widths.name), '-'.repeat(widths.type), '-'.repeat(12));
+  return [`  ${headers.join('  ')}`, `  ${dividers.join('  ')}`];
+}
+
+/**
+ * @param {Array<Object>} rows - Safe rows
+ * @returns {string} Compact totals
+ */
+function formatSummary(rows) {
+  const configured = rows.filter(row => row.configured).length;
+  const requiredMissing = rows.filter(row => !row.configured && row.required).length;
+  const optionalUnset = rows.length - configured - requiredMissing;
+  const ok = colorAggregateGlyph('ok', GLYPHS.ok);
+  const warn = colorAggregateGlyph('warn', GLYPHS.warn);
+  const skipped = colorAggregateGlyph('skipped', GLYPHS.skipped);
+  const label = rows.length === 1 ? 'entry' : 'entries';
+  return `${rows.length} ${label} · ${ok} ${configured} configured · ` +
+    `${warn} ${requiredMissing} required missing · ${skipped} ${optionalUnset} optional unset`;
+}
+
+/**
+ * List Parameter declarations for an environment or exact application owner.
+ * @param {Object} ctx - controllerUrl, authConfig, envKey
+ * @param {Object} [options] - `api` for injection, application and key search
+ * @returns {Promise<{ exitCode: number, rows: Array<Object> }>} Safe normalized rows
+ */
+async function runEnvSecretList(ctx, options = {}) {
+  const application = String(options.application || '').trim();
+  const api = options.api || { listEnvironmentConfiguration };
+  const raw = await api.listEnvironmentConfiguration(
+    ctx.controllerUrl, ctx.authConfig, ctx.envKey, application || undefined,
+    options.key ? { search: String(options.key).trim() } : {}
+  );
+  if (!Array.isArray(raw)) throw new Error('Configuration list response is not an array');
+  const rows = raw.map(row => normalizeRow(row, application)).sort((left, right) =>
+    left.application.localeCompare(right.application) || left.name.localeCompare(right.name)
+  );
+  const title = application ? `${application} (${ctx.envKey})` : ctx.envKey;
+  logger.log(sectionTitle(`Configuration: ${title}`));
+  logger.log(metadata(`Controller: ${ctx.controllerUrl}`));
+  logger.log('');
+  if (rows.length === 0) {
+    const suffix = options.key ? ` matching "${options.key}"` : '';
+    logger.log(metadata(`  No configuration entries${suffix}.`));
+    return { exitCode: 0, rows };
+  }
+  const widths = tableWidths(rows);
+  tableHeader(!application, widths).forEach(line => logger.log(line));
+  rows.forEach(row => logger.log(formatRow(row, !application, widths)));
+  logger.log('');
+  logger.log(metadata(formatSummary(rows)));
+  return { exitCode: 0, rows };
+}
+
+module.exports = {
+  normalizeRow,
+  cleanCell,
+  formatCell,
+  tableWidths,
+  formatRow,
+  tableHeader,
+  formatSummary,
+  runEnvSecretList
+};