@aifabrix/builder 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 eSystems Nordic Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# 🧱 @aifabrix/builder
+
+Local development infrastructure + Azure deployment tool.
+
+## Install
+
+```bash
+npm install -g @aifabrix/builder
+```
+
+## Quick Start
+
+```bash
+aifabrix up              # Start Postgres + Redis
+aifabrix create myapp    # Create your app
+aifabrix build myapp     # Build Docker image
+aifabrix run myapp       # Run locally
+```
+
+→ [Full Guide](docs/QUICK-START.md) | [CLI Commands](docs/CLI-REFERENCE.md)
+
+## What You Get
+
+- **Local Postgres + Redis infrastructure** - Runs in Docker
+- **Auto-generated Dockerfiles** - TypeScript and Python templates
+- **Environment variable management** - Secret resolution with kv:// references
+- **Azure deployment pipeline** - Push to ACR and deploy via controller
+
+## Optional Platform Apps
+
+Want authentication or deployment controller?
+
+```bash
+# Keycloak for authentication
+aifabrix create keycloak --port 8082 --database --template platform
+aifabrix build keycloak
+aifabrix run keycloak
+
+# Miso Controller for Azure deployments
+aifabrix create miso-controller --port 3000 --database --redis --template platform
+aifabrix build miso-controller
+aifabrix run miso-controller
+```
+
+→ [Infrastructure Guide](docs/INFRASTRUCTURE.md)
+
+## Documentation
+
+- [Quick Start](docs/QUICK-START.md) - Get running in 5 minutes
+- [Infrastructure](docs/INFRASTRUCTURE.md) - What runs and why
+- [Configuration](docs/CONFIGURATION.md) - Config file reference
+- [Building](docs/BUILDING.md) - Build process explained
+- [Running](docs/RUNNING.md) - Run apps locally
+- [Deploying](docs/DEPLOYING.md) - Deploy to Azure
+- [CLI Reference](docs/CLI-REFERENCE.md) - All commands
+
+## How It Works
+
+1. **Infrastructure** - Minimal baseline (Postgres + Redis)
+2. **Create** - Generate config files for your app
+3. **Build** - Auto-detect runtime and build Docker image
+4. **Run** - Start locally, connected to infrastructure
+5. **Deploy** - Push to ACR and deploy via controller
+
+## Requirements
+
+- **Docker Desktop** - For running containers
+- **Node.js 18+** - For running the CLI
+- **Azure CLI** - For deploying to Azure (optional)
+
+## License
+
+© eSystems Nordic Ltd 2025 - All Rights Reserved
+
+`@aifabrix/builder` is part of the AI Fabrix platform.

package/bin/aifabrix.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+/**
+ * AI Fabrix Builder CLI Entry Point
+ *
+ * This is the main entry point for the @aifabrix/builder CLI tool.
+ * It initializes Commander.js and delegates command handling to lib/cli.js
+ *
+ * Usage: aifabrix <command> [options]
+ *
+ * @fileoverview CLI entry point for AI Fabrix Builder SDK
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { Command } = require('commander');
+const cli = require('../lib/cli');
+
+/**
+ * Initialize and configure the CLI
+ * Sets up command parsing, help text, and version information
+ */
+function initializeCLI() {
+  const program = new Command();
+
+  program.name('aifabrix')
+    .version('2.0.0')
+    .description('AI Fabrix Local Fabric & Deployment SDK');
+
+  // Delegate command setup to lib/cli.js
+  cli.setupCommands(program);
+
+  // Parse command line arguments
+  program.parse();
+}
+
+// TODO: Add error handling for CLI initialization
+// TODO: Add graceful shutdown handling
+// TODO: Add telemetry/analytics hooks (opt-in)
+
+// Initialize CLI when this file is executed directly
+if (require.main === module) {
+  try {
+    initializeCLI();
+  } catch (error) {
+    console.error('❌ Failed to initialize CLI:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { initializeCLI };

package/lib/app-deploy.js

@@ -0,0 +1,209 @@
+/**
+ * AI Fabrix Builder Application Deployment Module
+ *
+ * Handles deployment to Miso Controller with manifest generation
+ * and orchestration. Includes push to Azure Container Registry.
+ *
+ * @fileoverview Application deployment for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+const chalk = require('chalk');
+const pushUtils = require('./push');
+
+/**
+ * Validate application name format
+ * @param {string} appName - Application name to validate
+ * @throws {Error} If app name is invalid
+ */
+function validateAppName(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('Application name is required');
+  }
+
+  // App name should be lowercase, alphanumeric with dashes, 3-40 characters
+  const nameRegex = /^[a-z0-9-]{3,40}$/;
+  if (!nameRegex.test(appName)) {
+    throw new Error('Application name must be 3-40 characters, lowercase letters, numbers, and dashes only');
+  }
+
+  // Cannot start or end with dash
+  if (appName.startsWith('-') || appName.endsWith('-')) {
+    throw new Error('Application name cannot start or end with a dash');
+  }
+
+  // Cannot have consecutive dashes
+  if (appName.includes('--')) {
+    throw new Error('Application name cannot have consecutive dashes');
+  }
+}
+
+/**
+ * Pushes application image to Azure Container Registry
+ * @async
+ * @function pushApp
+ * @param {string} appName - Name of the application
+ * @param {Object} options - Push options (registry, tag)
+ * @returns {Promise<void>} Resolves when push is complete
+ */
+async function pushApp(appName, options = {}) {
+  try {
+    // Validate app name
+    validateAppName(appName);
+
+    const configPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+    let config;
+    try {
+      config = yaml.load(await fs.readFile(configPath, 'utf8'));
+    } catch (error) {
+      throw new Error(`Failed to load configuration: ${configPath}\nRun 'aifabrix create ${appName}' first`);
+    }
+
+    const registry = options.registry || config.image?.registry;
+    if (!registry) {
+      throw new Error('Registry URL is required. Provide via --registry flag or configure in variables.yaml under image.registry');
+    }
+
+    if (!pushUtils.validateRegistryURL(registry)) {
+      throw new Error(`Invalid registry URL format: ${registry}. Expected format: *.azurecr.io`);
+    }
+
+    const tags = options.tag ? options.tag.split(',').map(t => t.trim()) : ['latest'];
+
+    if (!await pushUtils.checkLocalImageExists(appName, 'latest')) {
+      throw new Error(`Docker image ${appName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
+    }
+
+    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.checkACRAuthentication(registry)) {
+      console.log(chalk.green(`✓ Already authenticated with ${registry}`));
+    } else {
+      await pushUtils.authenticateACR(registry);
+    }
+
+    await Promise.all(tags.map(async(tag) => {
+      await pushUtils.tagImage(`${appName}:latest`, `${registry}/${appName}:${tag}`);
+      await pushUtils.pushImage(`${registry}/${appName}:${tag}`);
+    }));
+
+    console.log(chalk.green(`\n✓ Successfully pushed ${tags.length} tag(s) to ${registry}`));
+    console.log(chalk.gray(`Image: ${registry}/${appName}:*`));
+    console.log(chalk.gray(`Tags: ${tags.join(', ')}`));
+
+  } catch (error) {
+    throw new Error(`Failed to push application: ${error.message}`);
+  }
+}
+
+/**
+ * Deploys application to Miso Controller
+ * Orchestrates manifest generation, key creation, and deployment
+ *
+ * @async
+ * @function deployApp
+ * @param {string} appName - Name of the application to deploy
+ * @param {Object} options - Deployment options
+ * @param {string} options.controller - Controller URL (required)
+ * @param {string} [options.environment] - Target environment (dev/tst/pro)
+ * @param {boolean} [options.poll] - Poll for deployment status
+ * @param {number} [options.pollInterval] - Polling interval in milliseconds
+ * @returns {Promise<Object>} Deployment result
+ * @throws {Error} If deployment fails
+ *
+ * @example
+ * await deployApp('myapp', { controller: 'https://controller.aifabrix.ai', environment: 'dev' });
+ */
+async function deployApp(appName, options = {}) {
+  try {
+    // 1. Input validation
+    if (!appName || typeof appName !== 'string') {
+      throw new Error('App name is required');
+    }
+
+    validateAppName(appName);
+
+    if (!options.controller) {
+      throw new Error('Controller URL is required (--controller flag required)');
+    }
+
+    // 2. Load application configuration
+    const builderPath = path.join(process.cwd(), 'builder', appName);
+    try {
+      await fs.access(builderPath);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`Application '${appName}' not found in builder/. Run 'aifabrix create ${appName}' first`);
+      }
+      throw error;
+    }
+
+    // 3. Generate deployment manifest
+    console.log(chalk.blue(`\n📋 Generating deployment manifest for ${appName}...`));
+    const generator = require('./generator');
+    const manifestPath = await generator.generateDeployJson(appName);
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+
+    // 4. Validate manifest
+    const validation = generator.validateDeploymentJson(manifest);
+    if (!validation.valid) {
+      console.log(chalk.red('\n❌ Validation failed:'));
+      validation.errors.forEach(error => console.log(chalk.red(`   • ${error}`)));
+      throw new Error('Deployment manifest validation failed');
+    }
+
+    if (validation.warnings.length > 0) {
+      console.log(chalk.yellow('\n⚠️  Warnings:'));
+      validation.warnings.forEach(warning => console.log(chalk.yellow(`   • ${warning}`)));
+    }
+
+    // 5. Display deployment info
+    console.log(chalk.green(`✓ Manifest generated: ${manifestPath}`));
+    console.log(chalk.blue(`   Key: ${manifest.key}`));
+    console.log(chalk.blue(`   Display Name: ${manifest.displayName}`));
+    console.log(chalk.blue(`   Image: ${manifest.image}`));
+    console.log(chalk.blue(`   Port: ${manifest.port}`));
+
+    // 6. Deploy to controller
+    console.log(chalk.blue(`\n🚀 Deploying to ${options.controller}...`));
+    const deployer = require('./deployer');
+    const result = await deployer.deployToController(manifest, options.controller, {
+      environment: options.environment,
+      poll: options.poll !== false, // Poll by default
+      pollInterval: options.pollInterval || 5000,
+      pollMaxAttempts: options.pollMaxAttempts || 60
+    });
+
+    // 7. Display results
+    console.log(chalk.green('\n✅ Deployment initiated successfully'));
+    if (result.deploymentUrl) {
+      console.log(chalk.blue(`   URL: ${result.deploymentUrl}`));
+    }
+    if (result.deploymentId) {
+      console.log(chalk.blue(`   Deployment ID: ${result.deploymentId}`));
+    }
+    if (result.status) {
+      const statusIcon = result.status.status === 'completed' ? '✅' :
+        result.status.status === 'failed' ? '❌' : '⏳';
+      console.log(chalk.blue(`   Status: ${statusIcon} ${result.status.status}`));
+    }
+
+    return result;
+
+  } catch (error) {
+    throw new Error(`Failed to deploy application: ${error.message}`);
+  }
+}
+
+module.exports = {
+  pushApp,
+  deployApp,
+  validateAppName
+};
+

package/lib/app-run.js

@@ -0,0 +1,291 @@
+/**
+ * AI Fabrix Builder Application Run Management
+ *
+ * This module handles application running with Docker containers.
+ * Includes Docker orchestration, health checking, and port management.
+ *
+ * @fileoverview Application run management for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const path = require('path');
+const net = require('net');
+const chalk = require('chalk');
+const yaml = require('js-yaml');
+const handlebars = require('handlebars');
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const validator = require('./validator');
+const infra = require('./infra');
+const secrets = require('./secrets');
+
+const execAsync = promisify(exec);
+
+/**
+ * Checks if Docker image exists for the application
+ * @param {string} appName - Application name
+ * @returns {Promise<boolean>} True if image exists
+ */
+async function checkImageExists(appName) {
+  try {
+    const { stdout } = await execAsync(`docker images --format "{{.Repository}}:{{.Tag}}" | grep "^${appName}:latest$"`);
+    return stdout.trim() === `${appName}:latest`;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Checks if container is already running
+ * @param {string} appName - Application name
+ * @returns {Promise<boolean>} True if container is running
+ */
+async function checkContainerRunning(appName) {
+  try {
+    const { stdout } = await execAsync(`docker ps --filter "name=aifabrix-${appName}" --format "{{.Names}}"`);
+    return stdout.trim() === `aifabrix-${appName}`;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Stops and removes existing container
+ * @param {string} appName - Application name
+ */
+async function stopAndRemoveContainer(appName) {
+  try {
+    console.log(chalk.yellow(`Stopping existing container aifabrix-${appName}...`));
+    await execAsync(`docker stop aifabrix-${appName}`);
+    await execAsync(`docker rm aifabrix-${appName}`);
+    console.log(chalk.green(`✓ Container aifabrix-${appName} stopped and removed`));
+  } catch (error) {
+    // Container might not exist, which is fine
+    console.log(chalk.gray(`Container aifabrix-${appName} was not running`));
+  }
+}
+
+/**
+ * Checks if port is available
+ * @param {number} port - Port number to check
+ * @returns {Promise<boolean>} True if port is available
+ */
+async function checkPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+    server.on('error', () => resolve(false));
+  });
+}
+
+/**
+ * Generates Docker Compose configuration from template
+ * @param {string} appName - Application name
+ * @param {Object} config - Application configuration
+ * @param {Object} options - Run options
+ * @returns {Promise<string>} Generated compose content
+ */
+async function generateDockerCompose(appName, config, options) {
+  const language = config.build?.language || config.language || 'typescript';
+  const templatePath = path.join(__dirname, '..', 'templates', language, 'docker-compose.hbs');
+  if (!fsSync.existsSync(templatePath)) {
+    throw new Error(`Docker Compose template not found for language: ${language}`);
+  }
+
+  const templateContent = fsSync.readFileSync(templatePath, 'utf8');
+  const template = handlebars.compile(templateContent);
+
+  const port = options.port || config.build?.localPort || config.port || 3000;
+
+  const templateData = {
+    app: {
+      key: appName,
+      name: config.displayName || appName
+    },
+    image: {
+      name: appName,
+      tag: 'latest'
+    },
+    port: config.port || 3000,
+    build: {
+      localPort: port
+    },
+    healthCheck: {
+      path: config.healthCheck?.path || '/health',
+      interval: config.healthCheck?.interval || 30
+    },
+    requiresDatabase: config.services?.database || false,
+    requiresStorage: config.services?.storage || false,
+    requiresRedis: config.services?.redis || false,
+    mountVolume: path.join(process.cwd(), 'data', appName),
+    databases: config.databases || []
+  };
+
+  return template(templateData);
+}
+
+/**
+ * Waits for container health check to pass
+ * @param {string} appName - Application name
+ * @param {number} timeout - Timeout in seconds
+ */
+async function waitForHealthCheck(appName, timeout = 60) {
+  const maxAttempts = timeout / 2; // Check every 2 seconds
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    try {
+      const { stdout } = await execAsync(`docker inspect --format='{{.State.Health.Status}}' aifabrix-${appName}`);
+      const status = stdout.trim();
+
+      if (status === 'healthy') {
+        return;
+      } else if (status === 'unhealthy') {
+        throw new Error(`Container aifabrix-${appName} is unhealthy`);
+      }
+
+      attempts++;
+      if (attempts < maxAttempts) {
+        console.log(chalk.yellow(`Waiting for health check... (${attempts}/${maxAttempts})`));
+        await new Promise(resolve => setTimeout(resolve, 2000));
+      }
+    } catch (error) {
+      attempts++;
+      if (attempts < maxAttempts) {
+        await new Promise(resolve => setTimeout(resolve, 2000));
+      }
+    }
+  }
+
+  throw new Error(`Health check timeout after ${timeout} seconds`);
+}
+
+/**
+ * Runs the application locally using Docker
+ * Starts container with proper port mapping and environment
+ *
+ * @async
+ * @function runApp
+ * @param {string} appName - Name of the application to run
+ * @param {Object} options - Run options
+ * @param {number} [options.port] - Override local port
+ * @returns {Promise<void>} Resolves when app is running
+ * @throws {Error} If run fails or app is not built
+ *
+ * @example
+ * await runApp('myapp', { port: 3001 });
+ * // Application is now running on localhost:3001
+ */
+async function runApp(appName, options = {}) {
+  try {
+    // Validate app name
+    if (!appName || typeof appName !== 'string') {
+      throw new Error('Application name is required');
+    }
+
+    // Load and validate app configuration
+    const configPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+    if (!fsSync.existsSync(configPath)) {
+      throw new Error(`Application configuration not found: ${configPath}\nRun 'aifabrix create ${appName}' first`);
+    }
+
+    const configContent = fsSync.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+
+    // Validate configuration
+    const validation = await validator.validateApplication(appName);
+    if (!validation.valid) {
+      throw new Error(`Configuration validation failed:\n${validation.variables.errors.join('\n')}`);
+    }
+
+    // Check if Docker image exists
+    console.log(chalk.blue(`Checking if image ${appName}:latest exists...`));
+    const imageExists = await checkImageExists(appName);
+    if (!imageExists) {
+      throw new Error(`Docker image ${appName}:latest not found\nRun 'aifabrix build ${appName}' first`);
+    }
+    console.log(chalk.green(`✓ Image ${appName}:latest found`));
+
+    // Check infrastructure health
+    console.log(chalk.blue('Checking infrastructure health...'));
+    const infraHealth = await infra.checkInfraHealth();
+    const unhealthyServices = Object.entries(infraHealth)
+      .filter(([_, status]) => status !== 'healthy')
+      .map(([service, _]) => service);
+
+    if (unhealthyServices.length > 0) {
+      throw new Error(`Infrastructure services not healthy: ${unhealthyServices.join(', ')}\nRun 'aifabrix up' first`);
+    }
+    console.log(chalk.green('✓ Infrastructure is running'));
+
+    // Check if container is already running
+    const containerRunning = await checkContainerRunning(appName);
+    if (containerRunning) {
+      console.log(chalk.yellow(`Container aifabrix-${appName} is already running`));
+      await stopAndRemoveContainer(appName);
+    }
+
+    // Check port availability
+    const port = options.port || config.build?.localPort || config.port || 3000;
+    const portAvailable = await checkPortAvailable(port);
+    if (!portAvailable) {
+      throw new Error(`Port ${port} is already in use. Try --port <alternative>`);
+    }
+
+    // Ensure .env file exists
+    const envPath = path.join(process.cwd(), 'builder', appName, '.env');
+    if (!fsSync.existsSync(envPath)) {
+      console.log(chalk.yellow('Generating .env file from template...'));
+      await secrets.generateEnvFile(appName);
+    }
+
+    // Generate Docker Compose configuration
+    console.log(chalk.blue('Generating Docker Compose configuration...'));
+    const composeContent = await generateDockerCompose(appName, config, options);
+    // Write compose file to temporary location
+    const tempComposePath = path.join(process.cwd(), 'builder', appName, 'docker-compose.yaml');
+    await fs.writeFile(tempComposePath, composeContent);
+
+    try {
+      // Start container
+      console.log(chalk.blue(`Starting ${appName}...`));
+      await execAsync(`docker-compose -f "${tempComposePath}" up -d`);
+      console.log(chalk.green(`✓ Container aifabrix-${appName} started`));
+
+      // Wait for health check
+      console.log(chalk.blue('Waiting for application to be healthy...'));
+      await waitForHealthCheck(appName);
+
+      // Display success message
+      console.log(chalk.green(`\n✓ App running at http://localhost:${port}`));
+      console.log(chalk.gray(`Container: aifabrix-${appName}`));
+      console.log(chalk.gray('Health check: /health'));
+
+    } finally {
+      // Clean up temporary compose file
+      try {
+        await fs.unlink(tempComposePath);
+      } catch (error) {
+        // Ignore cleanup errors
+      }
+    }
+
+  } catch (error) {
+    throw new Error(`Failed to run application: ${error.message}`);
+  }
+}
+
+module.exports = {
+  runApp,
+  checkImageExists,
+  checkContainerRunning,
+  stopAndRemoveContainer,
+  checkPortAvailable,
+  generateDockerCompose,
+  waitForHealthCheck
+};