@aifabrix/builder 2.40.0 → 2.41.0

package/lib/api/types/dev.types.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Builder Server (dev) API type definitions – issue-cert, settings, users, SSH keys, secrets
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Issue certificate request (POST /api/dev/issue-cert). Public; no client cert.
+ * @typedef {Object} IssueCertDto
+ * @property {string} developerId - Developer ID (must match user for whom PIN was created)
+ * @property {string} pin - One-time PIN from POST /api/dev/users/:id/pin
+ * @property {string} csr - PEM-encoded Certificate Signing Request
+ */
+
+/**
+ * Issue certificate response (POST /api/dev/issue-cert)
+ * @typedef {Object} IssueCertResponseDto
+ * @property {string} certificate - PEM-encoded X.509 certificate
+ * @property {number} validDays - Validity in days
+ * @property {string} validNotAfter - ISO 8601 validity end (UTC)
+ * @property {string} [caCertificate] - Optional PEM-encoded CA certificate (for remote Docker TLS; saved as ca.pem)
+ * @property {string} [ca] - Optional alias for caCertificate
+ */
+
+/**
+ * Developer settings (GET /api/dev/settings). Cert-authenticated.
+ * @typedef {Object} SettingsResponseDto
+ * @property {string} user-mutagen-folder - Server path to workspace root (no app segment)
+ * @property {string} secrets-encryption - Encryption key (hex)
+ * @property {string} aifabrix-secrets - Path or URL for secrets
+ * @property {string} aifabrix-env-config - Env config path
+ * @property {string} remote-server - Builder-server base URL
+ * @property {string} docker-endpoint - Docker API endpoint
+ * @property {string} sync-ssh-user - SSH user for Mutagen
+ * @property {string} sync-ssh-host - SSH host for Mutagen
+ */
+
+/**
+ * User list item (GET /api/dev/users)
+ * @typedef {Object} UserResponseDto
+ * @property {string} id - Developer ID
+ * @property {string} name - Display name
+ * @property {string} email - Email
+ * @property {string} createdAt - ISO 8601
+ * @property {boolean} certificateIssued - Whether cert was issued
+ * @property {string} [certificateValidNotAfter] - Cert validity end (optional)
+ * @property {string[]} groups - Access groups (admin, secret-manager, developer)
+ */
+
+/**
+ * Create user request (POST /api/dev/users)
+ * @typedef {Object} CreateUserDto
+ * @property {string} developerId - Unique developer ID (numeric string)
+ * @property {string} name - Display name
+ * @property {string} email - Email
+ * @property {string[]} [groups] - Default [developer]
+ */
+
+/**
+ * Update user request (PATCH /api/dev/users/:id). At least one field.
+ * @typedef {Object} UpdateUserDto
+ * @property {string} [name] - Display name
+ * @property {string} [email] - Email
+ * @property {string[]} [groups] - Access groups
+ */
+
+/**
+ * Create PIN response (POST /api/dev/users/:id/pin)
+ * @typedef {Object} CreatePinResponseDto
+ * @property {string} pin - One-time PIN
+ * @property {string} expiresAt - ISO 8601
+ */
+
+/**
+ * Add SSH key request (POST /api/dev/users/:id/ssh-keys)
+ * @typedef {Object} AddSshKeyDto
+ * @property {string} publicKey - SSH public key line
+ * @property {string} [label] - Optional label
+ */
+
+/**
+ * SSH key item (list/add response)
+ * @typedef {Object} SshKeyItemDto
+ * @property {string} fingerprint - Key fingerprint
+ * @property {string} [label] - Optional label
+ * @property {string} [createdAt] - ISO 8601
+ */
+
+/**
+ * Deleted response (DELETE endpoints)
+ * @typedef {Object} DeletedResponseDto
+ * @property {string} deleted - ID or key of deleted resource
+ */
+
+/**
+ * Secret item (GET /api/dev/secrets)
+ * @typedef {Object} SecretItemDto
+ * @property {string} name - Secret key
+ * @property {string} value - Decrypted value
+ */
+
+/**
+ * Add secret request (POST /api/dev/secrets)
+ * @typedef {Object} AddSecretDto
+ * @property {string} key - Secret key
+ * @property {string} value - Secret value
+ */
+
+/**
+ * Add secret response
+ * @typedef {Object} AddSecretResponseDto
+ * @property {string} key - Key that was added/updated
+ */
+
+/**
+ * Delete secret response
+ * @typedef {Object} DeleteSecretResponseDto
+ * @property {string} deleted - Key that was removed
+ */
+
+/**
+ * Health response (GET /health)
+ * @typedef {Object} HealthResponseDto
+ * @property {string} status - Overall status, e.g. "ok"
+ * @property {Object} checks - Per-component health checks
+ * @property {string} checks.dataDir - Data directory check ("ok" or error)
+ * @property {string} checks.encryptionKey - Encryption key check ("ok" or error)
+ * @property {string} checks.ca - CA certificate check ("ok" or error)
+ * @property {string} checks.users - Users store check ("ok" or error)
+ * @property {string} checks.tokens - Tokens store check ("ok" or error)
+ */
+
+/**
+ * Error response (all error responses)
+ * @typedef {Object} ErrorResponseDto
+ * @property {number} statusCode - HTTP status
+ * @property {string} error - Short error type
+ * @property {string} message - Human-readable message
+ * @property {string} [code] - Optional machine-readable code
+ */

package/lib/app/config.js

@@ -31,6 +31,26 @@ async function fileExists(filePath) {
   }
 }
 
+/**
+ * Renames legacy variables.yaml to application.yaml if only variables.yaml exists.
+ * Ensures create always results in application.yaml.
+ * @async
+ * @param {string} appPath - Path to application directory
+ */
+async function normalizeLegacyVariablesYaml(appPath) {
+  const applicationYaml = path.join(appPath, 'application.yaml');
+  const applicationYml = path.join(appPath, 'application.yml');
+  const applicationJson = path.join(appPath, 'application.json');
+  const variablesYaml = path.join(appPath, 'variables.yaml');
+  const hasAppYaml = await fileExists(applicationYaml);
+  const hasAppYml = await fileExists(applicationYml);
+  const hasAppJson = await fileExists(applicationJson);
+  const hasVariables = await fileExists(variablesYaml);
+  if (hasVariables && !hasAppYaml && !hasAppYml && !hasAppJson) {
+    await fs.rename(variablesYaml, applicationYaml);
+  }
+}
+
 /**
  * Generates application.yaml file if no application config exists
  * @async
@@ -39,6 +59,7 @@ async function fileExists(filePath) {
  * @param {Object} config - Application configuration
  */
 async function generateVariablesYamlFile(appPath, appName, config) {
+  await normalizeLegacyVariablesYaml(appPath);
   const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
   try {
     resolveApplicationConfigPath(appPath);

package/lib/app/down.js

@@ -118,6 +118,7 @@ async function downApp(appName, options = {}) {
 }
 
 module.exports = {
-  downApp
+  downApp,
+  getAppVolumeName
 };
 

package/lib/app/index.js

@@ -31,6 +31,8 @@ const {
   processTemplateFiles,
   setupAppFiles
 } = require('./helpers');
+const path = require('path');
+const secretsEnsure = require('../core/secrets-ensure');
 
 /**
  * Creates new application with scaffolded configuration files
@@ -130,6 +132,13 @@ async function generateApplicationFiles(finalAppPath, appName, config, options)
 
   await generateConfigFiles(finalAppPath, appName, config, existingEnv);
 
+  const envTemplatePath = path.join(finalAppPath, 'env.template');
+  try {
+    await secretsEnsure.ensureSecretsFromEnvTemplate(envTemplatePath, {});
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
   // Generate external system files if type is external
   if (config.type === 'external') {
     const externalGenerator = require('../external-system/generator');

package/lib/app/push.js

@@ -40,21 +40,38 @@ function validateAppName(appName) {
 }
 
 /**
- * Extracts image name from configuration using the same logic as build command
- * @param {Object} config - Configuration object from application.yaml
- * @param {string} appName - Application name (fallback)
- * @returns {string} Image name
+ * Returns effective config (unwrap variables wrapper if present so image/app are at top level).
+ * application.yaml may have top-level image/app or a variables: { image, app } wrapper.
+ * @param {Object} config - Raw config from loadConfigFile
+ * @returns {Object} Config with image and app at top level
+ */
+function getEffectiveConfig(config) {
+  if (!config || typeof config !== 'object') return config || {};
+  if (config.variables && typeof config.variables === 'object' && (config.variables.image !== undefined || config.variables.app !== undefined)) {
+    return config.variables;
+  }
+  return config;
+}
+
+/**
+ * Extracts image name from configuration using the same logic as build command.
+ * Uses image.name (e.g. aifabrix/dataplane) so ACR repository matches application.yaml.
+ * @param {Object} config - Configuration object from application.yaml (or effective config)
+ * @param {string} appName - Application name (fallback when image not set)
+ * @returns {string} Image name (e.g. aifabrix/dataplane, not just dataplane)
  */
 function extractImageName(config, appName) {
-  if (typeof config.image === 'string') {
-    return config.image.split(':')[0];
-  } else if (config.image?.name) {
-    return config.image.name;
-  } else if (config.app?.key) {
-    return config.app.key;
+  const c = getEffectiveConfig(config);
+  if (typeof c.image === 'string') {
+    return c.image.split(':')[0];
+  }
+  if (c.image?.name) {
+    return c.image.name;
+  }
+  if (c.app?.key) {
+    return c.app.key;
   }
   return appName;
-
 }
 
 /**
@@ -72,7 +89,8 @@ async function loadPushConfig(appName, options) {
   try {
     const configPath = resolveApplicationConfigPath(appPath);
     const config = loadConfigFile(configPath);
-    const registry = options.registry || config.image?.registry;
+    const effective = getEffectiveConfig(config);
+    const registry = options.registry || effective.image?.registry;
     if (!registry) {
       throw new Error('Registry URL is required. Provide via --registry flag or configure in application config under image.registry');
     }
@@ -110,6 +128,12 @@ async function validatePushConfig(registry, imageName, appName) {
   if (!await pushUtils.checkAzureCLIInstalled()) {
     throw new Error('Azure CLI is not installed. Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
   }
+
+  if (!await pushUtils.checkAzureLogin()) {
+    throw new Error(
+      'Not logged in to Azure. Run "az login" first, then run push again.'
+    );
+  }
 }
 
 /**

package/lib/app/readme.js

@@ -120,9 +120,7 @@ function buildExternalDatasourcePlaceholders(systemKey, datasourceCount) {
 function buildReadmeContext(appName, config) {
   const displayName = config.displayName || formatAppDisplayName(appName);
   const port = config.port ?? 3000;
-  const localPort = (typeof config.build?.localPort === 'number' && config.build.localPort > 0)
-    ? config.build.localPort
-    : port;
+  const localPort = port;
   const imageName = config.image?.name || `aifabrix/${appName}`;
   // Extract registry from nested structure (config.image.registry) or flattened (config.registry)
   const registry = config.image?.registry || config.registry || 'myacr.azurecr.io';

package/lib/app/run-env-compose.js

@@ -0,0 +1,201 @@
+/**
+ * Helpers for application run: clean applications dir, build merged .env, compose safeguard.
+ * Keeps run-helpers.js under line limit.
+ *
+ * @fileoverview Run env and compose helpers
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const pathsUtil = require('../utils/paths');
+const adminSecrets = require('../core/admin-secrets');
+const secretsEnvWrite = require('../core/secrets-env-write');
+const { getContainerPort } = require('../utils/port-resolver');
+
+/**
+ * Clean applications directory: remove generated docker-compose.yaml and .env.* files.
+ * @param {string|number} developerId - Developer ID
+ */
+function cleanApplicationsDir(developerId) {
+  const baseDir = pathsUtil.getApplicationsBaseDir(developerId);
+  if (!fsSync.existsSync(baseDir)) return;
+  const toRemove = [path.join(baseDir, 'docker-compose.yaml')];
+  try {
+    const entries = fsSync.readdirSync(baseDir);
+    for (const name of entries) {
+      if (name.startsWith('.env.')) toRemove.push(path.join(baseDir, name));
+    }
+  } catch {
+    // Ignore readdir errors
+  }
+  for (const filePath of toRemove) {
+    try {
+      if (fsSync.existsSync(filePath)) fsSync.unlinkSync(filePath);
+    } catch {
+      // Ignore unlink errors
+    }
+  }
+}
+
+/**
+ * Derive PostgreSQL user from database name (same as compose-handlebars-helpers pgUserName).
+ * @param {string} dbName - Database name (e.g. keycloak)
+ * @returns {string} User name (e.g. keycloak_user)
+ */
+function pgUserName(dbName) {
+  if (!dbName) return '';
+  return `${String(dbName).replace(/-/g, '_')}_user`;
+}
+
+/**
+ * Inject DB_N_NAME and DB_N_USER from application.yaml databases into env so .env has everything.
+ * @param {Object} env - Merged env object (mutated)
+ * @param {Object} appConfig - Application config (requires.databases or databases array)
+ */
+function injectDatabaseNamesAndUsers(env, appConfig) {
+  const databases = appConfig?.requires?.databases || appConfig?.databases;
+  if (!Array.isArray(databases) || databases.length === 0) return;
+  for (let i = 0; i < databases.length; i++) {
+    const db = databases[i];
+    const name = db?.name || (appConfig?.app?.key || 'app');
+    env[`DB_${i}_NAME`] = name;
+    env[`DB_${i}_USER`] = pgUserName(name);
+  }
+}
+
+/**
+ * Get the env var name used for PORT in env.template (e.g. PORT=${MISO_PORT} -> MISO_PORT).
+ * @param {string} appName - Application name
+ * @returns {string|null} Variable name or null if not found
+ */
+function getPortVarFromEnvTemplate(appName) {
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const templatePath = path.join(builderPath, 'env.template');
+  if (!fsSync.existsSync(templatePath)) return null;
+  try {
+    const content = fsSync.readFileSync(templatePath, 'utf8');
+    const m = content.match(/^PORT\s*=\s*\$\{([A-Za-z0-9_]+)\}/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Override PORT and the template's port variable (e.g. MISO_PORT) with container port from application.yaml.
+ * Run .env only: when running in Docker, the app listens on the container port (port or build.containerPort), not localPort.
+ * For envOutputPath .env (local, not reload) we use localPort instead - see adjustLocalEnvPortsInContent in secrets-helpers.
+ * @param {Object} env - Merged env object (mutated)
+ * @param {Object} appConfig - Application configuration (port, build.containerPort)
+ * @param {string} appName - Application name (to resolve env.template port var)
+ */
+function injectContainerPortForRun(env, appConfig, appName) {
+  const containerPort = getContainerPort(appConfig, 3000);
+  env.PORT = String(containerPort);
+  const portVar = getPortVarFromEnvTemplate(appName);
+  if (portVar) {
+    env[portVar] = String(containerPort);
+  }
+}
+
+/** Keys that must never be passed to the app container (admin/start-only). */
+const ADMIN_ONLY_KEYS = [
+  'POSTGRES_PASSWORD',
+  'PGADMIN_DEFAULT_EMAIL',
+  'PGADMIN_DEFAULT_PASSWORD',
+  'REDIS_HOST',
+  'REDIS_COMMANDER_USER',
+  'REDIS_COMMANDER_PASSWORD'
+];
+
+/**
+ * Build app-only env (merged minus admin secrets). App container must not receive admin passwords.
+ * @param {Object} merged - Full merged env
+ * @returns {Object} Env object safe for app container
+ */
+function buildAppOnlyEnv(merged) {
+  const appOnly = {};
+  for (const [k, v] of Object.entries(merged)) {
+    if (ADMIN_ONLY_KEYS.includes(k)) continue;
+    appOnly[k] = v;
+  }
+  return appOnly;
+}
+
+/**
+ * Build env for db-init only: POSTGRES_PASSWORD + DB_N_PASSWORD, DB_N_NAME, DB_N_USER. Used only for start, not in app container.
+ * @param {Object} merged - Full merged env
+ * @returns {Object} Env object for db-init service only
+ */
+function buildDbInitOnlyEnv(merged) {
+  const dbInit = {};
+  if (merged.POSTGRES_PASSWORD !== undefined) {
+    dbInit.POSTGRES_PASSWORD = merged.POSTGRES_PASSWORD;
+  }
+  for (const [k, v] of Object.entries(merged)) {
+    if (k.startsWith('DB_') && (k.endsWith('_PASSWORD') || k.endsWith('_NAME') || k.endsWith('_USER'))) {
+      dbInit[k] = v;
+    }
+  }
+  return dbInit;
+}
+
+/**
+ * Build two run env files: .env.run (app-only, no admin secrets) and .env.run.admin (start-only, for db-init).
+ * Admin password is never set in the app container; .env.run.admin is used only for start and then deleted.
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {string} devDir - Applications directory path
+ * @returns {Promise<{ runEnvPath: string, runEnvAdminPath: string }>} Paths to .env.run and .env.run.admin
+ */
+async function buildMergedRunEnvAndWrite(appName, appConfig, devDir) {
+  const infra = require('../infrastructure');
+  const ensureAdminSecretsFn = typeof infra.ensureAdminSecrets === 'function'
+    ? infra.ensureAdminSecrets
+    : require('../infrastructure/helpers').ensureAdminSecrets;
+  await ensureAdminSecretsFn();
+  const adminObj = await adminSecrets.readAndDecryptAdminSecrets();
+  const appObj = await secretsEnvWrite.resolveAndGetEnvMap(appName, {
+    environment: 'docker',
+    secretsPath: null,
+    force: false
+  });
+  const merged = { ...adminObj, ...appObj };
+  injectDatabaseNamesAndUsers(merged, appConfig);
+  injectContainerPortForRun(merged, appConfig, appName);
+
+  const runEnvPath = path.join(devDir, '.env.run');
+  const runEnvAdminPath = path.join(devDir, '.env.run.admin');
+
+  const appOnly = buildAppOnlyEnv(merged);
+  const dbInitOnly = buildDbInitOnlyEnv(merged);
+
+  await fs.writeFile(runEnvPath, adminSecrets.envObjectToContent(appOnly), { mode: 0o600 });
+  await fs.writeFile(runEnvAdminPath, adminSecrets.envObjectToContent(dbInitOnly), { mode: 0o600 });
+
+  return { runEnvPath, runEnvAdminPath };
+}
+
+/**
+ * Assert generated compose does not contain password literals in environment (ISO 27K).
+ * @param {string} composeContent - Generated docker-compose content
+ * @throws {Error} If password keys appear in environment-like assignment
+ */
+function assertNoPasswordLiteralsInCompose(composeContent) {
+  const badPattern = /\n\s+(-?\s*)(POSTGRES_PASSWORD|DB_\d+_PASSWORD)\s*[:=]/;
+  if (badPattern.test(composeContent)) {
+    throw new Error('Generated compose must not contain password literals (POSTGRES_PASSWORD, DB_*_PASSWORD). Use env_file only.');
+  }
+}
+
+module.exports = {
+  cleanApplicationsDir,
+  buildMergedRunEnvAndWrite,
+  assertNoPasswordLiteralsInCompose
+};