@aifabrix/builder 2.36.1 → 2.37.0

package/lib/commands/auth-status.js

@@ -197,15 +197,15 @@ function displayTokenInfo(tokenInfo) {
   const statusIcon = tokenInfo.authenticated ? chalk.green('✓') : chalk.red('✗');
   const statusText = tokenInfo.authenticated ? 'Authenticated' : 'Not authenticated';
 
-  logger.log(`Status: ${statusIcon} ${statusText}`);
-  logger.log(`Token Type: ${chalk.cyan(tokenInfo.type)}`);
+  logger.log(`  Status: ${statusIcon} ${statusText}`);
+  logger.log(`  Token Type: ${chalk.cyan(tokenInfo.type)}`);
 
   if (tokenInfo.appName) {
-    logger.log(`Application: ${chalk.cyan(tokenInfo.appName)}`);
+    logger.log(`  Application: ${chalk.cyan(tokenInfo.appName)}`);
   }
 
   if (tokenInfo.expiresAt) {
-    logger.log(`Expires: ${chalk.gray(formatExpiration(tokenInfo.expiresAt))}`);
+    logger.log(`  Expires: ${chalk.gray(formatExpiration(tokenInfo.expiresAt))}`);
   }
 
   if (tokenInfo.error) {
@@ -241,14 +241,43 @@ async function resolveDataplaneUrlSilent(controllerUrl, environment, authConfig)
  * @param {boolean} dataplaneConnected - Whether dataplane health check passed
  */
 function displayDataplaneSection(dataplaneUrl, dataplaneConnected) {
+  logger.log('');
   if (dataplaneUrl) {
     logger.log(`Dataplane: ${chalk.cyan(dataplaneUrl)}`);
     const statusIcon = dataplaneConnected ? chalk.green('✓') : chalk.red('✗');
     const statusText = dataplaneConnected ? 'Connected' : 'Not reachable';
-    logger.log(`Status: ${statusIcon} ${statusText}`);
+    displayOpenApiDocs(null, dataplaneUrl);
+    logger.log('');
+    logger.log(`  Status: ${statusIcon} ${statusText}`);
   } else {
     logger.log(`Dataplane: ${chalk.gray('—')}`);
-    logger.log(`Status: ${chalk.gray('Not discovered')}`);
+    logger.log('');
+    logger.log(`  Status: ${chalk.gray('Not discovered')}`);
+  }
+}
+
+/**
+ * Normalize base URL (no trailing slash) for docs path
+ * @param {string} url - Base URL
+ * @returns {string} URL without trailing slash
+ */
+function normalizeBaseUrl(url) {
+  return (url || '').replace(/\/$/, '');
+}
+
+/**
+ * Display Open API documentation links (Controller and Dataplane)
+ * @param {string} controllerUrl - Controller URL
+ * @param {string|null} dataplaneUrl - Dataplane URL or null
+ */
+function displayOpenApiDocs(controllerUrl, dataplaneUrl) {
+  const controllerBase = normalizeBaseUrl(controllerUrl);
+  if (controllerBase) {
+    logger.log(`  Open API docs: ${chalk.cyan(controllerBase + '/api/docs')}`);
+  }
+  if (dataplaneUrl) {
+    const dataplaneBase = normalizeBaseUrl(dataplaneUrl);
+    logger.log(`  Open API docs: ${chalk.cyan(dataplaneBase + '/api/docs')}`);
   }
 }
 
@@ -264,11 +293,12 @@ function displayDataplaneSection(dataplaneUrl, dataplaneConnected) {
 function displayStatus(controllerUrl, environment, tokenInfo, dataplaneInfo) {
   logger.log(chalk.bold('\n🔐 Authentication Status\n'));
   logger.log(`Controller: ${chalk.cyan(controllerUrl)}`);
-  logger.log(`Environment: ${chalk.cyan(environment || 'Not specified')}\n`);
+  displayOpenApiDocs(controllerUrl, null);
+  logger.log(`  Environment: ${chalk.cyan(environment || 'Not specified')}\n`);
 
   if (!tokenInfo) {
-    logger.log(`Status: ${chalk.red('✗ Not authenticated')}`);
-    logger.log(`Token Type: ${chalk.gray('None')}\n`);
+    logger.log(`  Status: ${chalk.red('✗ Not authenticated')}`);
+    logger.log(`  Token Type: ${chalk.gray('None')}\n`);
     logger.log(chalk.yellow('💡 Run "aifabrix login" to authenticate\n'));
     return;
   }

package/lib/commands/up-miso.js

@@ -126,7 +126,7 @@ async function handleUpMiso(options = {}) {
   const health = await infra.checkInfraHealth(undefined, { strict: true });
   const allHealthy = Object.values(health).every(status => status === 'healthy');
   if (!allHealthy) {
-    throw new Error('Infrastructure is not up. Run \'aifabrix up\' first.');
+    throw new Error('Infrastructure is not up. Run \'aifabrix up-infra\' first.');
   }
   logger.log(chalk.green('✓ Infrastructure is up'));
   await ensureAppFromTemplate('keycloak');

package/lib/core/config.js

@@ -396,6 +396,15 @@ async function setSecretsEncryptionKey(key) {
   await saveConfig(config);
 }
 
+/**
+ * Ensure secrets encryption key exists (empty install). Delegates to ensure-encryption-key module.
+ * @returns {Promise<void>}
+ */
+async function ensureSecretsEncryptionKey() {
+  const { ensureSecretsEncryptionKey: run } = require('./ensure-encryption-key');
+  await run({ getSecretsEncryptionKey, setSecretsEncryptionKey, getSecretsPath });
+}
+
 async function getSecretsPath() {
   const config = await getConfig();
   return config['aifabrix-secrets'] || config['secrets-path'] || null;
@@ -427,6 +436,7 @@ const exportsObj = {
   decryptTokenValue,
   getSecretsEncryptionKey,
   setSecretsEncryptionKey,
+  ensureSecretsEncryptionKey,
   getSecretsPath,
   setSecretsPath,
   normalizeControllerUrl,

package/lib/core/ensure-encryption-key.js

@@ -0,0 +1,56 @@
+/**
+ * Ensure secrets encryption key exists on empty install.
+ * If missing from config and from user/project secrets, generates and saves one. Never logs the key.
+ *
+ * @fileoverview Encryption key bootstrap for empty installation
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const path = require('path');
+const fs = require('fs');
+const yaml = require('js-yaml');
+const crypto = require('crypto');
+const pathsUtil = require('../utils/paths');
+const { saveLocalSecret } = require('../utils/local-secrets');
+
+const ENCRYPTION_KEY = 'secrets-encryptionKeyVault';
+
+function readKeyFromFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const data = yaml.load(content);
+    if (data && typeof data[ENCRYPTION_KEY] === 'string') return data[ENCRYPTION_KEY];
+  } catch {
+    // Ignore
+  }
+  return null;
+}
+
+/**
+ * Ensure secrets encryption key exists. If config already has it, do nothing.
+ * If key exists in user or project secrets file, set config. Otherwise generate, write to user secrets, set config.
+ * @param {Object} config - Config module (getSecretsEncryptionKey, setSecretsEncryptionKey, getSecretsPath)
+ * @returns {Promise<void>}
+ */
+async function ensureSecretsEncryptionKey(config) {
+  const existing = await config.getSecretsEncryptionKey();
+  if (existing) return;
+
+  const userSecretsPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
+  const projectSecretsPath = await config.getSecretsPath();
+
+  let key = readKeyFromFile(userSecretsPath);
+  if (!key && projectSecretsPath) key = readKeyFromFile(path.resolve(projectSecretsPath));
+  if (key) {
+    await config.setSecretsEncryptionKey(key);
+    return;
+  }
+
+  const newKey = crypto.randomBytes(32).toString('hex');
+  await saveLocalSecret(ENCRYPTION_KEY, newKey);
+  await config.setSecretsEncryptionKey(newKey);
+}
+
+module.exports = { ensureSecretsEncryptionKey };

package/lib/generator/wizard.js

@@ -360,54 +360,39 @@ async function generateEnvTemplate(appPath, systemConfig) {
 }
 
 /**
- * Generate deployment scripts (deploy.sh and deploy.ps1) from templates
+ * Generate deployment scripts (deploy.sh, deploy.ps1, deploy.js) from templates
  * @async
  * @function generateDeployScripts
  * @param {string} appPath - Application directory path
  * @param {string} systemKey - System key
  * @param {string} systemFileName - System file name
  * @param {string[]} datasourceFileNames - Array of datasource file names
- * @returns {Promise<Object>} Object with script file paths
+ * @returns {Promise<Object>} Object with deployShPath, deployPs1Path, deployJsPath
  * @throws {Error} If generation fails
  */
+const templatesExternalDir = path.join(__dirname, '..', '..', 'templates', 'external-system');
+
+async function writeDeployScriptFromTemplate(templateName, outputPath, context, executable) {
+  const templatePath = path.join(templatesExternalDir, templateName);
+  const content = Handlebars.compile(await fs.readFile(templatePath, 'utf8'))(context);
+  await fs.writeFile(outputPath, content, 'utf8');
+  if (executable) await fs.chmod(outputPath, 0o755);
+  logger.log(chalk.green(`✓ Generated ${path.basename(outputPath)}`));
+}
+
 async function generateDeployScripts(appPath, systemKey, systemFileName, datasourceFileNames) {
   try {
     const allJsonFiles = [systemFileName, ...datasourceFileNames];
+    const context = { systemKey, allJsonFiles, datasourceFileNames };
 
-    // Load and compile deploy.sh template
-    const deployShTemplatePath = path.join(__dirname, '..', '..', 'templates', 'external-system', 'deploy.sh.hbs');
-    const deployShTemplateContent = await fs.readFile(deployShTemplatePath, 'utf8');
-    const deployShTemplate = Handlebars.compile(deployShTemplateContent);
-
-    // Generate deploy.sh
-    const deployShPath = path.join(appPath, 'deploy.sh');
-    const deployShContent = deployShTemplate({
-      systemKey,
-      allJsonFiles,
-      datasourceFileNames
-    });
-    await fs.writeFile(deployShPath, deployShContent, 'utf8');
-    await fs.chmod(deployShPath, 0o755); // Make executable
-    logger.log(chalk.green('✓ Generated deploy.sh'));
-
-    // Load and compile deploy.ps1 template
-    const deployPs1TemplatePath = path.join(__dirname, '..', '..', 'templates', 'external-system', 'deploy.ps1.hbs');
-    const deployPs1TemplateContent = await fs.readFile(deployPs1TemplatePath, 'utf8');
-    const deployPs1Template = Handlebars.compile(deployPs1TemplateContent);
-
-    // Generate deploy.ps1
-    const deployPs1Path = path.join(appPath, 'deploy.ps1');
-    const deployPs1Content = deployPs1Template({
-      systemKey,
-      allJsonFiles,
-      datasourceFileNames
-    });
-    await fs.writeFile(deployPs1Path, deployPs1Content, 'utf8');
-    logger.log(chalk.green('✓ Generated deploy.ps1'));
+    await writeDeployScriptFromTemplate('deploy.sh.hbs', path.join(appPath, 'deploy.sh'), context, true);
+    await writeDeployScriptFromTemplate('deploy.ps1.hbs', path.join(appPath, 'deploy.ps1'), context, false);
+    await writeDeployScriptFromTemplate('deploy.js.hbs', path.join(appPath, 'deploy.js'), context, false);
 
     return {
-      deployShPath,
-      deployPs1Path
+      deployShPath: path.join(appPath, 'deploy.sh'),
+      deployPs1Path: path.join(appPath, 'deploy.ps1'),
+      deployJsPath: path.join(appPath, 'deploy.js')
     };
   } catch (error) {
     throw new Error(`Failed to generate deployment scripts: ${error.message}`);

package/lib/infrastructure/helpers.js

@@ -119,7 +119,7 @@ function extractPasswordFromUrlOrValue(urlOrPassword) {
  * Ensures Postgres init script exists for miso-controller app (database miso, user miso_user).
  * Uses password from secrets (databases-miso-controller-0-passwordKeyVault) or default miso_pass123.
  * Init scripts run only when the Postgres data volume is first created. If infra was already
- * started before this script existed, run `aifabrix down -v` then `aifabrix up` to re-init, or
+ * started before this script existed, run `aifabrix down-infra -v` then `aifabrix up-infra` to re-init, or
  * create the database and user manually (e.g. via pgAdmin or psql).
  *
  * @async

package/lib/schema/external-system.schema.json

@@ -7,7 +7,7 @@
     "key": "external-system-schema",
     "name": "External System Configuration Schema",
     "description": "JSON schema for validating ExternalSystem configuration files",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "type": "schema",
     "category": "integration",
     "author": "AI Fabrix Team",
@@ -27,6 +27,15 @@
     ],
     "dependencies": [],
     "changelog": [
+      {
+        "version": "1.2.0",
+        "date": "2025-02-01T00:00:00Z",
+        "changes": [
+          "Added generateMcpContract (boolean, default true): config-only control for MCP contract generation on publish",
+          "Added generateOpenApiContract (boolean, default true): reserved for future use"
+        ],
+        "breaking": false
+      },
       {
         "version": "1.1.0",
         "date": "2025-12-01T00:00:00Z",
@@ -407,6 +416,20 @@
       "type": "boolean",
       "description": "Master switch for all endpoints in this system. If false, no endpoints are registered regardless of individual endpoint active flags.",
       "default": true
+    },
+    "credentialIdOrKey": {
+      "type": "string",
+      "description": "Credential identifier (ID or key) to use for authenticating with this external system."
+    },
+    "generateMcpContract": {
+      "type": "boolean",
+      "description": "Whether to generate MCP contract on publish. Config only (no query parameter); default true when absent.",
+      "default": true
+    },
+    "generateOpenApiContract": {
+      "type": "boolean",
+      "description": "Reserved: whether to generate or expose OpenAPI contract on publish. Not yet implemented.",
+      "default": true
     }
   },
   "additionalProperties": false

package/lib/utils/help-builder.js

@@ -20,8 +20,11 @@ const CATEGORIES = [
   {
     name: 'Infrastructure (Local Development)',
     commands: [
-      { name: 'up' },
-      { name: 'down', term: 'down [app]' },
+      { name: 'up-infra' },
+      { name: 'up-platform' },
+      { name: 'up-miso' },
+      { name: 'up-dataplane' },
+      { name: 'down-infra', term: 'down-infra [app]' },
       { name: 'doctor' },
       { name: 'status' },
       { name: 'restart', term: 'restart <service>' }

package/lib/utils/token-manager.js

@@ -251,9 +251,8 @@ async function tryClientTokenAuth(environment, appName, controllerUrl) {
         controller: clientToken.controller
       };
     }
-  } catch (error) {
-    // Client token unavailable, continue to credentials
-    logger.warn(`Client token unavailable: ${error.message}`);
+  } catch {
+    // Client token unavailable; getDeploymentAuth will try client credentials next (no warning here to avoid misleading output when env credentials succeed)
   }
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.36.1",
+  "version": "2.37.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/README.md.hbs

@@ -47,8 +47,8 @@ docker logs aifabrix-{{appName}} -f
 
 **Stop:**
 ```bash
-aifabrix down {{appName}}
-# aifabrix down {{appName}} --volumes   # also remove data volume
+aifabrix down-infra {{appName}}
+# aifabrix down-infra {{appName}} --volumes   # also remove data volume
 ```
 
 ### 4. Deploy to Azure
@@ -87,7 +87,7 @@ aifabrix app rotate-secret {{appName}}
 # Development
 aifabrix build {{appName}}                        # Build app
 aifabrix run {{appName}}                          # Run locally
-aifabrix down {{appName}} [--volumes]             # Stop app (optionally remove volume)
+aifabrix down-infra {{appName}} [--volumes]             # Stop app (optionally remove volume)
 aifabrix dockerfile {{appName}} --force           # Generate Dockerfile
 aifabrix resolve {{appName}}                      # Generate .env file
 

package/templates/applications/dataplane/variables.yaml

@@ -43,8 +43,6 @@ authentication:
   type: azure
   enableSSO: true
   requiredRoles: ["aifabrix-user"]
-  endpoints:
-    local: "https://dataplane.aifabrix.ai/auth/callback"
 
 # Build Configuration
 build:

package/templates/applications/miso-controller/variables.yaml

@@ -38,8 +38,6 @@ authentication:
   enableSSO: true
   requiredRoles:
     - aifabrix-user
-  endpoints:
-    local: http://localhost:3000/auth/callback
 
 # Build Configuration
 build:

package/templates/external-system/deploy.js.hbs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Deploy {{systemKey}} external system and datasources using aifabrix CLI.
+ * Run: node deploy.js
+ * Flow: check auth → login if needed → deploy → run integration tests.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const scriptDir = __dirname;
+const appKey = '{{systemKey}}';
+const env = process.env.ENVIRONMENT || 'dev';
+// Controller URL: from config (aifabrix auth config) or set CONTROLLER env before running
+
+function run(cmd, options = {}) {
+  const opts = { cwd: scriptDir, stdio: 'inherit', ...options };
+  try {
+    execSync(cmd, opts);
+    return true;
+  } catch (err) {
+    if (options.ignoreExit) return false;
+    process.exit(err.status ?? 1);
+  }
+}
+
+function isLoggedIn() {
+  try {
+    execSync('aifabrix auth status', { cwd: scriptDir, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+console.log('🔍 Checking authentication...');
+if (!isLoggedIn()) {
+  console.log('⚠️  Not logged in. Run login (e.g. aifabrix login --controller <url> --method device --environment ' + env + ').');
+  run('aifabrix login --environment ' + env);
+}
+
+console.log('🔍 Validating configuration...');
+{{#each allJsonFiles}}
+run('aifabrix validate "' + path.join(scriptDir, '{{this}}') + '"');
+{{/each}}
+console.log('✅ Validation passed');
+
+console.log('🚀 Deploying ' + appKey + '...');
+run('aifabrix deploy ' + appKey);
+console.log('✅ Deployment complete');
+
+if (process.env.RUN_TESTS !== 'false') {
+  console.log('🧪 Running integration tests...');
+  run('aifabrix test-integration ' + appKey);
+  console.log('✅ Tests passed');
+}
+
+console.log('✅ Done.');