@aifabrix/builder 2.40.0 → 2.41.0

package/lib/utils/secrets-path.js

@@ -54,8 +54,8 @@ async function getActualSecretsPath(secretsPath, _appName) {
     };
   }
 
-  // Cascading lookup: user's file first (under configured home)
-  const userSecretsPath = path.join(paths.getAifabrixHome(), 'secrets.local.yaml');
+  // Cascading lookup: user's file first (primary home: AIFABRIX_HOME or ~/.aifabrix)
+  const userSecretsPath = path.join(paths.getConfigDirForPaths(), 'secrets.local.yaml');
 
   // Check config.yaml for canonical secrets path
   let buildSecretsPath = null;

package/lib/utils/secrets-utils.js

@@ -15,6 +15,24 @@ const yaml = require('js-yaml');
 const logger = require('./logger');
 const pathsUtil = require('./paths');
 const { getContainerPort } = require('./port-resolver');
+const { loadYamlTolerantOfDuplicateKeys } = require('./secrets-generator');
+
+/**
+ * Parses secrets YAML content with fallback for duplicate keys.
+ * @param {string} content - Raw file content
+ * @returns {Object} Parsed secrets object
+ */
+function parseSecretsContent(content) {
+  try {
+    return yaml.load(content);
+  } catch (yamlErr) {
+    const msg = yamlErr.message || '';
+    if (msg.includes('duplicate') || msg.includes('duplicated mapping')) {
+      return loadYamlTolerantOfDuplicateKeys(content);
+    }
+    throw yamlErr;
+  }
+}
 
 /**
  * Loads secrets from file with cascading lookup support
@@ -45,6 +63,38 @@ async function loadSecretsFromFile(filePath) {
   }
 }
 
+/**
+ * Loads user secrets from the primary config directory (AIFABRIX_HOME or ~/.aifabrix).
+ * Used as the master source when merging with project/public secrets: user values win,
+ * missing keys are filled from the public (aifabrix-secrets) file.
+ * Does not use config.yaml aifabrix-home so the merge always sees the actual user file.
+ *
+ * @function loadPrimaryUserSecrets
+ * @returns {Object} Loaded secrets object or empty object
+ */
+function loadPrimaryUserSecrets() {
+  const primaryDir = pathsUtil.getConfigDirForPaths();
+  const userSecretsPath = path.join(primaryDir, 'secrets.local.yaml');
+  if (!fs.existsSync(userSecretsPath)) {
+    return {};
+  }
+
+  try {
+    const content = fs.readFileSync(userSecretsPath, 'utf8');
+    const secrets = parseSecretsContent(content);
+    if (!secrets || typeof secrets !== 'object') {
+      throw new Error(`Invalid secrets file format: ${userSecretsPath}`);
+    }
+    return secrets;
+  } catch (error) {
+    if (error.message.includes('Invalid secrets file format')) {
+      throw error;
+    }
+    logger.warn(`Warning: Could not read secrets file ${userSecretsPath}: ${error.message}`);
+    return {};
+  }
+}
+
 /**
  * Loads user secrets from ~/.aifabrix/secrets.local.yaml
  * Uses paths.getAifabrixHome() to respect config.yaml aifabrix-home override
@@ -59,7 +109,7 @@ function loadUserSecrets() {
 
   try {
     const content = fs.readFileSync(userSecretsPath, 'utf8');
-    const secrets = yaml.load(content);
+    const secrets = parseSecretsContent(content);
     if (!secrets || typeof secrets !== 'object') {
       throw new Error(`Invalid secrets file format: ${userSecretsPath}`);
     }
@@ -157,6 +207,7 @@ function resolveUrlPort(protocol, hostname, port, urlPath, hostnameToService) {
 
 module.exports = {
   loadSecretsFromFile,
+  loadPrimaryUserSecrets,
   loadUserSecrets,
   loadDefaultSecrets,
   buildHostnameToServiceMap,

package/lib/utils/secrets-validation.js

@@ -0,0 +1,84 @@
+/**
+ * AI Fabrix Builder – Secrets file validation
+ *
+ * Validates secrets.local.yaml (or given path): valid YAML, flat key-value structure,
+ * and optional naming convention (*KeyVault suffix per keyvault.md).
+ *
+ * @fileoverview Secrets file validation for structure and naming
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Optional naming convention: keys should end with KeyVault or match known patterns.
+ * @param {string} key - Secret key
+ * @returns {boolean} True if key matches convention
+ */
+function keyMatchesNamingConvention(key) {
+  if (!key || typeof key !== 'string') return false;
+  if (key.endsWith('KeyVault')) return true;
+  return /^[a-z0-9-_]+KeyVault$/i.test(key);
+}
+
+/**
+ * Validate that parsed secrets is a flat object (no nested objects for values).
+ * @param {*} parsed - Parsed YAML
+ * @param {boolean} checkNaming - Whether to check key naming
+ * @returns {string[]} Errors
+ */
+function validateParsedSecrets(parsed, checkNaming) {
+  const errors = [];
+  if (parsed === null || parsed === undefined) return errors;
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    errors.push('Secrets file must be a flat key-value object (no nested objects or arrays)');
+    return errors;
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    if (typeof value !== 'string' && typeof value !== 'number' && value !== null && value !== undefined) {
+      if (typeof value === 'object') {
+        errors.push(`Key "${key}": secret values must be strings or scalars (no nested objects)`);
+      }
+    }
+    if (checkNaming && !keyMatchesNamingConvention(key)) {
+      errors.push(`Key "${key}": recommended format is *KeyVault (e.g. postgres-passwordKeyVault)`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * Validate secrets file at path: YAML syntax, flat object, optional naming check.
+ *
+ * @param {string} filePath - Path to secrets file
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.checkNaming=false] - Check key names against *KeyVault convention
+ * @returns {{ valid: boolean, errors: string[], path: string }}
+ */
+function validateSecretsFile(filePath, options = {}) {
+  const checkNaming = Boolean(options.checkNaming);
+  if (!filePath || typeof filePath !== 'string') {
+    return { valid: false, errors: ['Path is required'], path: '' };
+  }
+  const resolvedPath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+  if (!fs.existsSync(resolvedPath)) {
+    return { valid: false, errors: [`File not found: ${resolvedPath}`], path: resolvedPath };
+  }
+  let parsed;
+  try {
+    const content = fs.readFileSync(resolvedPath, 'utf8');
+    parsed = yaml.load(content);
+  } catch (err) {
+    return { valid: false, errors: [`Invalid YAML: ${err.message}`], path: resolvedPath };
+  }
+  const errors = validateParsedSecrets(parsed, checkNaming);
+  return { valid: errors.length === 0, errors, path: resolvedPath };
+}
+
+module.exports = {
+  validateSecretsFile,
+  keyMatchesNamingConvention
+};

package/lib/utils/ssh-key-helper.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview Locate or generate SSH key for Mutagen sync (Windows and Mac). Prefer ed25519.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+/**
+ * Default SSH directory (user's .ssh)
+ * @returns {string} Path to .ssh directory
+ */
+function getDefaultSshDir() {
+  const home = os.homedir();
+  return path.join(home, '.ssh');
+}
+
+/**
+ * Path to default ed25519 public key
+ * @returns {string} Path to id_ed25519.pub
+ */
+function getDefaultEd25519PublicKeyPath() {
+  return path.join(getDefaultSshDir(), 'id_ed25519.pub');
+}
+
+/**
+ * Path to default ed25519 private key
+ * @returns {string} Path to id_ed25519
+ */
+function getDefaultEd25519PrivateKeyPath() {
+  return path.join(getDefaultSshDir(), 'id_ed25519');
+}
+
+/**
+ * Ensure .ssh directory exists
+ * @param {string} [sshDir] - SSH directory (default: user .ssh)
+ * @returns {string} Resolved SSH dir path
+ */
+function ensureSshDir(sshDir) {
+  const dir = sshDir || getDefaultSshDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  return dir;
+}
+
+/**
+ * Generate ed25519 SSH key pair if it does not exist. Idempotent.
+ * @param {string} [privateKeyPath] - Path to private key (default: ~/.ssh/id_ed25519)
+ * @returns {string} Path to public key file
+ * @throws {Error} If ssh-keygen fails
+ */
+function ensureEd25519Key(privateKeyPath) {
+  const privPath = privateKeyPath || getDefaultEd25519PrivateKeyPath();
+  const pubPath = privPath + '.pub';
+  if (fs.existsSync(pubPath) && fs.existsSync(privPath)) {
+    return pubPath;
+  }
+  ensureSshDir(path.dirname(privPath));
+  execSync(`ssh-keygen -t ed25519 -f "${privPath}" -N "" -C "aifabrix"`, {
+    stdio: 'pipe',
+    encoding: 'utf8'
+  });
+  return pubPath;
+}
+
+/**
+ * Read public key content (single line). Prefer ed25519, fallback to id_rsa.pub.
+ * @param {string} [sshDir] - SSH directory
+ * @returns {string} Public key line (e.g. "ssh-ed25519 AAAA... aifabrix")
+ * @throws {Error} If no key found or read fails
+ */
+function readPublicKeyContent(sshDir) {
+  const dir = sshDir || getDefaultSshDir();
+  const ed25519Pub = path.join(dir, 'id_ed25519.pub');
+  const rsaPub = path.join(dir, 'id_rsa.pub');
+  let pathToRead = null;
+  if (fs.existsSync(ed25519Pub)) {
+    pathToRead = ed25519Pub;
+  } else if (fs.existsSync(rsaPub)) {
+    pathToRead = rsaPub;
+  }
+  if (!pathToRead) {
+    throw new Error(
+      'No SSH public key found. Run: ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "aifabrix"'
+    );
+  }
+  const content = fs.readFileSync(pathToRead, 'utf8').trim();
+  const firstLine = content.split('\n')[0];
+  if (!firstLine || !firstLine.startsWith('ssh-')) {
+    throw new Error(`Invalid SSH public key file: ${pathToRead}`);
+  }
+  return firstLine;
+}
+
+/**
+ * Get or create ed25519 key and return its public key content for POST /api/dev/users/:id/ssh-keys.
+ * @returns {string} Single-line public key content
+ */
+function getOrCreatePublicKeyContent() {
+  ensureEd25519Key();
+  return readPublicKeyContent();
+}
+
+module.exports = {
+  getDefaultSshDir,
+  getDefaultEd25519PublicKeyPath,
+  getDefaultEd25519PrivateKeyPath,
+  ensureSshDir,
+  ensureEd25519Key,
+  readPublicKeyContent,
+  getOrCreatePublicKeyContent
+};

package/lib/utils/token-manager-messages.js

@@ -0,0 +1,90 @@
+/**
+ * Token refresh failure message formatting and once-per-URL warning (used by token-manager).
+ * @fileoverview Token manager message helpers
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const config = require('../core/config');
+const logger = require('./logger');
+
+/** Network-style error messages that indicate controller unreachable (not token expiry). */
+const NETWORK_ERROR_PATTERNS = [
+  'fetch failed',
+  'econnrefused',
+  'enotfound',
+  'etimedout',
+  'network',
+  'unreachable',
+  'timed out'
+];
+
+/** Controller URLs we have already logged a refresh-failure warning for this process. */
+const refreshFailureWarnedUrls = new Set();
+
+/** Controller URLs we have already logged a refresh-token-expired warning for this process. */
+const refreshTokenExpiredWarnedUrls = new Set();
+
+/**
+ * Reset warned state (for test isolation only). Not for production use.
+ */
+function resetRefreshWarnedUrlsForTesting() {
+  refreshFailureWarnedUrls.clear();
+  refreshTokenExpiredWarnedUrls.clear();
+}
+
+/**
+ * Log "refresh token expired" once per controller URL per process (avoids duplicate messages when auth is tried multiple times).
+ * @param {string} controllerUrl - Controller URL (for dedupe key)
+ * @param {string} errorMessage - Full error message to log
+ */
+function warnRefreshTokenExpiredOnce(controllerUrl, errorMessage) {
+  const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
+    ? config.normalizeControllerUrl(controllerUrl)
+    : '__no_url__';
+  if (refreshTokenExpiredWarnedUrls.has(key)) {
+    return;
+  }
+  refreshTokenExpiredWarnedUrls.add(key);
+  logger.warn(`Refresh token expired: ${errorMessage}`);
+}
+
+/**
+ * Returns a user-facing message for token refresh failure; adds a hint when the error looks like a connectivity issue.
+ * @param {string} errorMessage - Raw error message
+ * @param {string} [controllerUrl] - Controller URL for the hint
+ * @returns {string} Message to log
+ */
+function formatRefreshFailureMessage(errorMessage, controllerUrl) {
+  const lower = (errorMessage || '').toLowerCase();
+  const isNetwork = NETWORK_ERROR_PATTERNS.some(p => lower.includes(p));
+  const hint = isNetwork
+    ? (controllerUrl
+      ? ` The controller at ${controllerUrl} may be unreachable—ensure it is running and try again, or run 'aifabrix login' once it is available.`
+      : ' The controller may be unreachable—ensure it is running and try again, or run \'aifabrix login\' once it is available.')
+    : '';
+  return `${errorMessage}${hint}`;
+}
+
+/**
+ * Log device token refresh failure once per controller URL per process.
+ * @param {string} controllerUrl - Controller URL (for dedupe key and message)
+ * @param {string} errorMessage - Raw error message
+ */
+function warnRefreshFailureOnce(controllerUrl, errorMessage) {
+  const key = (controllerUrl && typeof controllerUrl === 'string' && controllerUrl.trim())
+    ? config.normalizeControllerUrl(controllerUrl)
+    : '__no_url__';
+  if (refreshFailureWarnedUrls.has(key)) {
+    return;
+  }
+  refreshFailureWarnedUrls.add(key);
+  logger.warn(`Failed to refresh device token: ${formatRefreshFailureMessage(errorMessage, controllerUrl)}`);
+}
+
+module.exports = {
+  formatRefreshFailureMessage,
+  warnRefreshFailureOnce,
+  warnRefreshTokenExpiredOnce,
+  resetRefreshWarnedUrlsForTesting
+};

package/lib/utils/token-manager.js

@@ -19,6 +19,7 @@ const {
   refreshClientToken,
   refreshDeviceToken
 } = require('./token-manager-refresh');
+const { warnRefreshFailureOnce, warnRefreshTokenExpiredOnce } = require('./token-manager-messages');
 
 function getSecretsFilePath() {
   return path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
@@ -185,9 +186,9 @@ async function getOrRefreshDeviceToken(controllerUrl) {
     // Refresh failed - check if it's a refresh token expiry
     const errorMessage = error.message || String(error);
     if (errorMessage.includes('Refresh token has expired')) {
-      logger.warn(`Refresh token expired: ${errorMessage}`);
+      warnRefreshTokenExpiredOnce(controllerUrl, errorMessage);
     } else {
-      logger.warn(`Failed to refresh device token: ${errorMessage}`);
+      warnRefreshFailureOnce(controllerUrl, errorMessage);
     }
     return null;
   }
@@ -398,9 +399,9 @@ async function forceRefreshDeviceToken(controllerUrl) {
   } catch (error) {
     const errorMessage = error.message || String(error);
     if (errorMessage.includes('Refresh token has expired')) {
-      logger.warn(`Refresh token expired: ${errorMessage}`);
+      warnRefreshTokenExpiredOnce(controllerUrl, errorMessage);
     } else {
-      logger.warn(`Failed to refresh device token: ${errorMessage}`);
+      warnRefreshFailureOnce(controllerUrl, errorMessage);
     }
     return null;
   }

package/lib/utils/variable-transformer.js

@@ -181,9 +181,6 @@ function validateBuildConfig(build) {
   if (build.envOutputPath) {
     buildConfig.envOutputPath = build.envOutputPath;
   }
-  if (build.localPort) {
-    buildConfig.localPort = build.localPort;
-  }
   if (build.language) {
     buildConfig.language = build.language;
   }
@@ -193,6 +190,9 @@ function validateBuildConfig(build) {
   if (build.dockerfile && build.dockerfile.trim() !== '') {
     buildConfig.dockerfile = build.dockerfile;
   }
+  if (build.localPort !== undefined && build.localPort !== null) {
+    buildConfig.localPort = build.localPort;
+  }
 
   return Object.keys(buildConfig).length > 0 ? buildConfig : null;
 }

package/lib/validation/validate.js

@@ -452,7 +452,7 @@ async function validateAppOrFile(appOrFile, options = {}) {
   logOfflinePathWhenType(appPath);
 
   if (isExternal) {
-    return await validateExternalSystemComplete(appName);
+    return await validateExternalSystemComplete(appName, options);
   }
 
   const appValidation = await validator.validateApplication(appName, options);

package/lib/validation/validator.js

@@ -365,6 +365,69 @@ function validateDeploymentJson(deployment) {
   };
 }
 
+/** Pattern matching ${VAR} style unresolved variables in strings */
+const UNRESOLVED_VAR_REGEX = /\$\{[^}]+\}/g;
+
+/**
+ * Recursively finds all string values in obj that contain ${...} placeholders.
+ * Used to ensure deployment manifest has no unresolved variables before deploy.
+ *
+ * @function findUnresolvedVariablesInObject
+ * @param {Object} obj - Object to scan (e.g. deployment manifest)
+ * @param {string} [prefix=''] - Path prefix for error reporting
+ * @returns {string[]} List of paths with example placeholder (e.g. "port: ${PORT}")
+ *
+ * @example
+ * findUnresolvedVariablesInObject({ port: '${PORT}' }) // ['port: ${PORT}']
+ */
+function findUnresolvedVariablesInObject(obj, prefix = '') {
+  const found = [];
+  if (obj === null || obj === undefined) {
+    return found;
+  }
+  if (typeof obj === 'string') {
+    const matches = obj.match(UNRESOLVED_VAR_REGEX);
+    if (matches && matches.length > 0) {
+      const pathLabel = prefix || 'value';
+      found.push(`${pathLabel}: ${matches[0]}`);
+    }
+    return found;
+  }
+  if (Array.isArray(obj)) {
+    obj.forEach((item, i) => {
+      found.push(...findUnresolvedVariablesInObject(item, `${prefix}[${i}]`));
+    });
+    return found;
+  }
+  if (typeof obj === 'object') {
+    for (const [key, value] of Object.entries(obj)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      found.push(...findUnresolvedVariablesInObject(value, path));
+    }
+    return found;
+  }
+  return found;
+}
+
+/**
+ * Validates that deployment manifest contains no unresolved ${...} variables.
+ * Throws if any are found, with a message to use secret variables or literal values.
+ *
+ * @function validateNoUnresolvedVariablesInDeployment
+ * @param {Object} deployment - Deployment manifest object
+ * @throws {Error} If any ${...} placeholders are found
+ */
+function validateNoUnresolvedVariablesInDeployment(deployment) {
+  const unresolved = findUnresolvedVariablesInObject(deployment);
+  if (unresolved.length > 0) {
+    const examples = [...new Set(unresolved)].slice(0, 5).join(', ');
+    throw new Error(
+      `Deployment manifest contains unresolved variables (e.g. ${examples}). ` +
+      'Use secret variables (kv://) in env.template for sensitive values, and set the application port as a number in application.yaml.'
+    );
+  }
+}
+
 /**
  * Validates all application configuration files
  * Runs complete validation suite for an application
@@ -411,6 +474,8 @@ module.exports = {
   validateRbac,
   validateEnvTemplate,
   validateDeploymentJson,
+  validateNoUnresolvedVariablesInDeployment,
+  findUnresolvedVariablesInObject,
   validateObjectAgainstApplicationSchema,
   checkEnvironment,
   formatValidationErrors,

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.40.0",
+  "version": "2.41.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
     "aifabrix": "bin/aifabrix.js",
-    "aifx": "bin/aifabrix.js"
+    "af": "bin/aifabrix.js"
   },
   "scripts": {
     "test": "node tests/scripts/test-wrapper.js",
@@ -16,11 +16,13 @@
     "test:integration": "jest --config jest.config.integration.js --runInBand",
     "test:integration:python": "cross-env TEST_LANGUAGE=python jest --config jest.config.integration.js --runInBand",
     "test:integration:typescript": "cross-env TEST_LANGUAGE=typescript jest --config jest.config.integration.js --runInBand",
+    "test:manual": "jest --config jest.config.manual.js --runInBand",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
     "lint:ci": "eslint . --ext .js --format json --output-file eslint-report.json",
     "dev": "node bin/aifabrix.js",
     "build": "npm run lint && npm run test",
+    "build:ci": "npm run lint && npm run test:ci",
     "pack": "npm run build && npm pack",
     "validate": "npm run build",
     "prepublishOnly": "npm run validate",

package/scripts/install-local.js

@@ -97,6 +97,39 @@ function displaySuccessMessage(currentVersion, newVersion) {
   console.log('Run "aifabrix --version" to verify.');
 }
 
+/**
+ * Run pnpm link --global and npm link from project root (handles pnpm global bin not set).
+ * @param {string} projectRoot - Path to project root
+ * @returns {void}
+ * @throws {Error} If linking fails when pnpm global bin is not configured
+ */
+function runPnpmLink(projectRoot) {
+  let pnpmLinked = false;
+  try {
+    execSync('pnpm link --global', { stdio: 'inherit', cwd: projectRoot });
+    pnpmLinked = true;
+  } catch (pnpmErr) {
+    const msg = (pnpmErr.message || String(pnpmErr));
+    if (msg.includes('global bin directory') || msg.includes('ERR_PNPM_NO_GLOBAL_BIN_DIR')) {
+      console.log(
+        '⚠️  pnpm global bin is not set up. Run "pnpm setup" and add PNPM_HOME to PATH, or we will use npm link.\n'
+      );
+    } else {
+      throw pnpmErr;
+    }
+  }
+  try {
+    execSync('npm link', { stdio: 'inherit', cwd: projectRoot });
+  } catch {
+    if (!pnpmLinked) {
+      console.error(
+        '\n💡 To fix: run "pnpm setup" and add the suggested line to your shell config, then run install:local again.'
+      );
+      throw new Error('Linking failed. pnpm global bin not configured and npm link failed.');
+    }
+  }
+}
+
 /**
  * Install local package globally
  * @returns {void}
@@ -107,31 +140,17 @@ function installLocal() {
   const currentVersion = getCurrentVersion();
 
   console.log(`Detected package manager: ${pm}\n`);
-
-  // Show version comparison
   displayVersionInfo(currentVersion, packageVersion);
-
   console.log('Linking @aifabrix/builder globally...\n');
 
   try {
     const projectRoot = path.join(__dirname, '..');
     if (pm === 'pnpm') {
-      // Update pnpm global.
-      execSync('pnpm link --global', { stdio: 'inherit', cwd: projectRoot });
-      // Also run npm link so npm's global bin points here; often PATH has
-      // npm's global bin before pnpm's, so "aifabrix" would otherwise stay old.
-      try {
-        execSync('npm link', { stdio: 'inherit', cwd: projectRoot });
-      } catch {
-        // npm may not be available or may fail; pnpm link already ran
-      }
+      runPnpmLink(projectRoot);
     } else {
       execSync('npm link', { stdio: 'inherit', cwd: projectRoot });
     }
-
-    // Get new version after linking
     const newVersion = getCurrentVersion();
-
     displaySuccessMessage(currentVersion, newVersion);
   } catch (error) {
     console.error('\n❌ Failed to link package:', error.message);

package/templates/README.md

@@ -70,7 +70,6 @@ Extra workflow steps are located in `templates/github/steps/`. When you use `--g
 - `{{databases}}` - Array of database configurations
 
 ### Build Configuration
-- `{{build.localPort}}` - Local development port (different from Docker port)
 - `{{mountVolume}}` - Volume mount path for local development
 
 ## Usage

package/templates/applications/README.md.hbs

@@ -38,7 +38,7 @@ aifabrix resolve {{appName}}
 aifabrix run {{appName}}
 ```
 
-**Access your app:** http://localhost:{{localPort}}
+**Access your app:** http://localhost:{{port}}
 
 **View logs:**
 ```bash
@@ -118,7 +118,7 @@ aifabrix build {{appName}} --language typescript  # Override language detection
 ### Run Options
 
 ```bash
-aifabrix run {{appName}} --port {{localPort}}     # Override local port
+aifabrix run {{appName}} --port {{port}}     # Override port
 aifabrix run {{appName}} --debug                  # Debug output
 ```
 
@@ -166,7 +166,7 @@ Controller URL and environment (for `deploy`, `app register`, etc.) are set via
 
 - **"Docker not running"** → Start Docker Desktop
 - **"Not logged in"** → Run `aifabrix login` first
-- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `build.localPort` in `application.yaml` (default: {{localPort}})
+- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `port` in `application.yaml` (default: {{port}})
 - **"Authentication failed"** → Run `aifabrix login` again
 - **"Build fails"** → Check Docker is running and `aifabrix-secrets` in `config.yaml` is configured correctly
 - **"Can't connect"** → Verify infrastructure is running{{#if hasDatabase}} and PostgreSQL is accessible{{/if}}
@@ -203,4 +203,4 @@ aifabrix json {{appName}}
 
 ---
 
-**Application**: {{appName}} | **Port**: {{localPort}} | **Registry**: {{registry}} | **Image**: {{imageName}}:latest
+**Application**: {{appName}} | **Port**: {{port}} | **Registry**: {{registry}} | **Image**: {{imageName}}:latest