@aifabrix/builder 2.0.0 → 2.0.2

package/lib/utils/variable-transformer.js

@@ -0,0 +1,271 @@
+/**
+ * Variable Transformation Utilities
+ *
+ * Transforms nested variables.yaml structure to flat schema format
+ * Converts app.*, image.*, requires.* to schema-compatible structure
+ *
+ * @fileoverview Variable transformation utilities for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Sanitizes authentication type - map keycloak to azure (schema allows: azure, local, none)
+ * @function sanitizeAuthType
+ * @param {string} authType - Authentication type
+ * @returns {string} Sanitized authentication type
+ */
+function sanitizeAuthType(authType) {
+  if (authType === 'keycloak') {
+    return 'azure';
+  }
+  if (authType && !['azure', 'local', 'none'].includes(authType)) {
+    return 'azure'; // Default to azure if invalid type
+  }
+  return authType;
+}
+
+/**
+ * Transforms flat structure to schema-compatible format
+ * @function transformFlatStructure
+ * @param {Object} variables - Raw variables from YAML
+ * @param {string} appName - Application name (fallback)
+ * @returns {Object} Transformed variables matching schema
+ */
+function transformFlatStructure(variables, appName) {
+  const result = {
+    key: variables.key || appName,
+    displayName: variables.displayName || appName,
+    description: variables.description || '',
+    type: variables.type || 'webapp',
+    image: variables.image,
+    registryMode: variables.registryMode || 'external',
+    port: variables.port || 3000,
+    requiresDatabase: variables.requiresDatabase || false,
+    requiresRedis: variables.requiresRedis || false,
+    requiresStorage: variables.requiresStorage || false,
+    databases: variables.databases || [],
+    ...variables
+  };
+
+  // Sanitize authentication if present
+  if (result.authentication && result.authentication.type) {
+    result.authentication = {
+      ...result.authentication,
+      type: sanitizeAuthType(result.authentication.type)
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Builds image reference string from variables
+ * @function buildImageReference
+ * @param {Object} variables - Variables configuration
+ * @param {string} appName - Application name (fallback)
+ * @returns {string} Image reference string
+ */
+function buildImageReference(variables, appName) {
+  const imageName = variables.image?.name || variables.app?.key || appName;
+  const registry = variables.image?.registry;
+  const tag = variables.image?.tag || 'latest';
+  return registry ? `${registry}/${imageName}:${tag}` : `${imageName}:${tag}`;
+}
+
+/**
+ * Validates repository URL format
+ * @function validateRepositoryUrl
+ * @param {string} url - Repository URL
+ * @returns {boolean} True if valid
+ */
+function validateRepositoryUrl(url) {
+  if (!url || url.trim() === '') {
+    return false;
+  }
+  const repoPattern = /^(https:\/\/github\.com\/[^/]+\/[^/]+|https:\/\/gitlab\.com\/[^/]+\/[^/]+|https:\/\/dev\.azure\.com\/[^/]+\/[^/]+\/[^/]+)$/;
+  return repoPattern.test(url);
+}
+
+/**
+ * Validates and transforms repository configuration
+ * @function validateRepositoryConfig
+ * @param {Object} repository - Repository configuration
+ * @returns {Object|null} Validated repository config or null
+ */
+function validateRepositoryConfig(repository) {
+  if (!repository) {
+    return null;
+  }
+
+  const repo = { enabled: repository.enabled || false };
+  if (validateRepositoryUrl(repository.repositoryUrl)) {
+    repo.repositoryUrl = repository.repositoryUrl;
+  }
+
+  if (repo.enabled || repo.repositoryUrl) {
+    return repo;
+  }
+
+  return null;
+}
+
+/**
+ * Validates and transforms build configuration
+ * @function validateBuildConfig
+ * @param {Object} build - Build configuration
+ * @returns {Object|null} Validated build config or null
+ */
+function validateBuildConfig(build) {
+  if (!build) {
+    return null;
+  }
+
+  const buildConfig = {};
+  if (build.envOutputPath) {
+    buildConfig.envOutputPath = build.envOutputPath;
+  }
+  if (build.secrets !== null && build.secrets !== undefined && build.secrets !== '') {
+    buildConfig.secrets = build.secrets;
+  }
+  if (build.localPort) {
+    buildConfig.localPort = build.localPort;
+  }
+  if (build.language) {
+    buildConfig.language = build.language;
+  }
+  if (build.context) {
+    buildConfig.context = build.context;
+  }
+  if (build.dockerfile && build.dockerfile.trim() !== '') {
+    buildConfig.dockerfile = build.dockerfile;
+  }
+
+  return Object.keys(buildConfig).length > 0 ? buildConfig : null;
+}
+
+/**
+ * Validates and transforms deployment configuration
+ * @function validateDeploymentConfig
+ * @param {Object} deployment - Deployment configuration
+ * @returns {Object|null} Validated deployment config or null
+ */
+function validateDeploymentConfig(deployment) {
+  if (!deployment) {
+    return null;
+  }
+
+  const deploymentConfig = {};
+  if (deployment.controllerUrl && deployment.controllerUrl.trim() !== '' && /^https:\/\/.*$/.test(deployment.controllerUrl)) {
+    deploymentConfig.controllerUrl = deployment.controllerUrl;
+  }
+  if (deployment.clientId && deployment.clientId.trim() !== '' && /^[a-z0-9-]+$/.test(deployment.clientId)) {
+    deploymentConfig.clientId = deployment.clientId;
+  }
+  if (deployment.clientSecret && deployment.clientSecret.trim() !== '' && /^(kv:\/\/.*|.+)$/.test(deployment.clientSecret)) {
+    deploymentConfig.clientSecret = deployment.clientSecret;
+  }
+
+  return Object.keys(deploymentConfig).length > 0 ? deploymentConfig : null;
+}
+
+/**
+ * Transforms optional fields from variables
+ * @function transformOptionalFields
+ * @param {Object} variables - Raw variables from YAML
+ * @param {Object} transformed - Base transformed object
+ * @returns {Object} Transformed object with optional fields added
+ */
+function transformOptionalFields(variables, transformed) {
+  if (variables.healthCheck) {
+    transformed.healthCheck = variables.healthCheck;
+  }
+
+  if (variables.authentication) {
+    transformed.authentication = {
+      ...variables.authentication,
+      type: sanitizeAuthType(variables.authentication.type)
+    };
+  }
+
+  const repository = validateRepositoryConfig(variables.repository);
+  if (repository) {
+    transformed.repository = repository;
+  }
+
+  const build = validateBuildConfig(variables.build);
+  if (build) {
+    transformed.build = build;
+  }
+
+  const deployment = validateDeploymentConfig(variables.deployment);
+  if (deployment) {
+    transformed.deployment = deployment;
+  }
+
+  if (variables.startupCommand) {
+    transformed.startupCommand = variables.startupCommand;
+  }
+  if (variables.runtimeVersion) {
+    transformed.runtimeVersion = variables.runtimeVersion;
+  }
+  if (variables.scaling) {
+    transformed.scaling = variables.scaling;
+  }
+  if (variables.frontDoorRouting) {
+    transformed.frontDoorRouting = variables.frontDoorRouting;
+  }
+  if (variables.roles) {
+    transformed.roles = variables.roles;
+  }
+  if (variables.permissions) {
+    transformed.permissions = variables.permissions;
+  }
+
+  return transformed;
+}
+
+/**
+ * Transforms nested variables.yaml structure to flat schema format
+ * Converts app.*, image.*, requires.* to schema-compatible structure
+ * Handles both flat and nested structures
+ *
+ * @function transformVariablesForValidation
+ * @param {Object} variables - Raw variables from YAML
+ * @param {string} appName - Application name (fallback)
+ * @returns {Object} Transformed variables matching schema
+ */
+function transformVariablesForValidation(variables, appName) {
+  // Check if structure is already flat (has key, displayName, image as string)
+  const isFlat = variables.key && variables.image && typeof variables.image === 'string';
+
+  if (isFlat) {
+    return transformFlatStructure(variables, appName);
+  }
+
+  // Nested structure - transform it
+  const requires = variables.requires || {};
+  const imageRef = buildImageReference(variables, appName);
+
+  // Transform to flat schema structure
+  const transformed = {
+    key: variables.app?.key || appName,
+    displayName: variables.app?.displayName || appName,
+    description: variables.app?.description || '',
+    type: variables.app?.type || 'webapp',
+    image: imageRef,
+    registryMode: variables.image?.registryMode || 'external',
+    port: variables.port || 3000,
+    requiresDatabase: requires.database || false,
+    requiresRedis: requires.redis || false,
+    requiresStorage: requires.storage || false,
+    databases: requires.databases || (requires.database ? [{ name: variables.app?.key || appName }] : [])
+  };
+
+  return transformOptionalFields(variables, transformed);
+}
+
+module.exports = {
+  transformVariablesForValidation
+};
+

package/lib/validator.js

@@ -14,6 +14,9 @@ const path = require('path');
 const yaml = require('js-yaml');
 const Ajv = require('ajv');
 const applicationSchema = require('./schema/application-schema.json');
+const { transformVariablesForValidation } = require('./utils/variable-transformer');
+const { checkEnvironment } = require('./utils/environment-checker');
+const { formatValidationErrors } = require('./utils/error-formatter');
 
 /**
  * Validates variables.yaml file against application schema
@@ -49,9 +52,12 @@ async function validateVariables(appName) {
     throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
   }
 
+  // Transform nested structure to flat schema format
+  const transformed = transformVariablesForValidation(variables, appName);
+
   const ajv = new Ajv({ allErrors: true, strict: false });
   const validate = ajv.compile(applicationSchema);
-  const valid = validate(variables);
+  const valid = validate(transformed);
 
   return {
     valid,
@@ -209,125 +215,33 @@ async function validateEnvTemplate(appName) {
 }
 
 /**
- * Checks the development environment for common issues
- * Validates Docker, ports, secrets, and other requirements
+ * Validates deployment JSON against application schema
+ * Ensures generated aifabrix-deploy.json matches the schema structure
  *
- * @async
- * @function checkEnvironment
- * @returns {Promise<Object>} Environment check result
- * @throws {Error} If critical issues are found
+ * @function validateDeploymentJson
+ * @param {Object} deployment - Deployment JSON object to validate
+ * @returns {Object} Validation result with errors
  *
  * @example
- * const result = await checkEnvironment();
- * // Returns: { docker: 'ok', ports: 'ok', secrets: 'missing', recommendations: [...] }
+ * const result = validateDeploymentJson(deployment);
+ * // Returns: { valid: true, errors: [] }
  */
-async function checkDocker() {
-  try {
-    const { exec } = require('child_process');
-    const { promisify } = require('util');
-    const execAsync = promisify(exec);
-
-    await execAsync('docker --version');
-    await execAsync('docker-compose --version');
-    return 'ok';
-  } catch (error) {
-    return 'error';
-  }
-}
-
-async function checkPorts() {
-  const requiredPorts = [5432, 6379, 5050, 8081];
-  const netstat = require('net');
-  let portIssues = 0;
-
-  for (const port of requiredPorts) {
-    try {
-      await new Promise((resolve, reject) => {
-        const server = netstat.createServer();
-        server.listen(port, () => {
-          server.close(resolve);
-        });
-        server.on('error', reject);
-      });
-    } catch (error) {
-      portIssues++;
-    }
-  }
-
-  return portIssues === 0 ? 'ok' : 'warning';
-}
-
-function checkSecrets() {
-  const os = require('os');
-  const secretsPath = path.join(os.homedir(), '.aifabrix', 'secrets.yaml');
-  return fs.existsSync(secretsPath) ? 'ok' : 'missing';
-}
-
-async function checkEnvironment() {
-  const result = {
-    docker: 'unknown',
-    ports: 'unknown',
-    secrets: 'unknown',
-    recommendations: []
-  };
-
-  // Check Docker
-  result.docker = await checkDocker();
-  if (result.docker === 'error') {
-    result.recommendations.push('Install Docker and Docker Compose');
-  }
-
-  // Check ports
-  result.ports = await checkPorts();
-  if (result.ports === 'warning') {
-    result.recommendations.push('Some required ports (5432, 6379, 5050, 8081) are in use');
-  }
-
-  // Check secrets
-  result.secrets = checkSecrets();
-  if (result.secrets === 'missing') {
-    result.recommendations.push('Create secrets file: ~/.aifabrix/secrets.yaml');
+function validateDeploymentJson(deployment) {
+  if (!deployment || typeof deployment !== 'object') {
+    return {
+      valid: false,
+      errors: ['Deployment must be an object']
+    };
   }
 
-  return result;
-}
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(applicationSchema);
+  const valid = validate(deployment);
 
-/**
- * Formats validation errors into developer-friendly messages
- * Converts technical schema errors into actionable advice
- *
- * @function formatValidationErrors
- * @param {Array} errors - Raw validation errors from Ajv
- * @returns {Array} Formatted error messages
- *
- * @example
- * const messages = formatValidationErrors(ajvErrors);
- * // Returns: ['Port must be between 1 and 65535', 'Missing required field: displayName']
- */
-function formatSingleError(error) {
-  const path = error.instancePath ? error.instancePath.slice(1) : 'root';
-  const field = path ? `Field "${path}"` : 'Configuration';
-
-  const errorMessages = {
-    required: `${field}: Missing required property "${error.params.missingProperty}"`,
-    type: `${field}: Expected ${error.params.type}, got ${typeof error.data}`,
-    minimum: `${field}: Value must be at least ${error.params.limit}`,
-    maximum: `${field}: Value must be at most ${error.params.limit}`,
-    minLength: `${field}: Must be at least ${error.params.limit} characters`,
-    maxLength: `${field}: Must be at most ${error.params.limit} characters`,
-    pattern: `${field}: Invalid format`,
-    enum: `${field}: Must be one of: ${error.params.allowedValues?.join(', ') || 'unknown'}`
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validate.errors)
   };
-
-  return errorMessages[error.keyword] || `${field}: ${error.message}`;
-}
-
-function formatValidationErrors(errors) {
-  if (!Array.isArray(errors)) {
-    return ['Unknown validation error'];
-  }
-
-  return errors.map(formatSingleError);
 }
 
 /**
@@ -371,6 +285,7 @@ module.exports = {
   validateVariables,
   validateRbac,
   validateEnvTemplate,
+  validateDeploymentJson,
   checkEnvironment,
   formatValidationErrors,
   validateApplication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
@@ -10,6 +10,9 @@
     "test": "jest --coverage",
     "test:watch": "jest --watch",
     "test:ci": "jest --ci --coverage --watchAll=false",
+    "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",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
     "lint:ci": "eslint . --ext .js --format json --output-file eslint-report.json",
@@ -17,8 +20,7 @@
     "build": "npm run lint && npm run test:ci",
     "validate": "npm run build",
     "prepublishOnly": "npm run validate",
-    "precommit": "npm run lint:fix && npm run test",
-    "posttest": "npm run lint"
+    "precommit": "npm run lint:fix && npm run test"
   },
   "keywords": [
     "aifabrix",
@@ -34,19 +36,20 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "commander": "^11.1.0",
-    "js-yaml": "^4.1.0",
     "ajv": "^8.12.0",
-    "handlebars": "^4.7.8",
     "axios": "^1.6.0",
     "chalk": "^4.1.2",
-    "ora": "^5.4.1",
-    "inquirer": "^8.2.5"
+    "commander": "^11.1.0",
+    "handlebars": "^4.7.8",
+    "inquirer": "^8.2.5",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
+    "@types/node": "^20.10.0",
+    "cross-env": "^10.1.0",
     "eslint": "^8.55.0",
-    "@types/node": "^20.10.0"
+    "jest": "^29.7.0"
   },
   "repository": {
     "type": "git",

package/templates/README.md

@@ -1,15 +1,56 @@
 # AI Fabrix Builder Templates
 
-These are Handlebars (.hbs) template files that generate Docker files for AI Fabrix applications. They should NOT be linted as Dockerfiles since they contain template variables that will be replaced during generation.
+These are Handlebars (.hbs) template files that generate Docker files and application configurations for AI Fabrix applications. They should NOT be linted as Dockerfiles since they contain template variables that will be replaced during generation.
 
-## Template Files
+## Template Structure
+
+The templates directory is organized as follows:
+
+### Application Templates (for `--template` flag)
+
+Application templates are folder-based and located under `templates/applications/`. When you use `--template <name>`, the tool looks for `templates/applications/<name>/` and copies all files from that folder to `builder/<app>/`.
+
+**Example:**
+- `templates/applications/miso-controller/` - Miso Controller application template
+- `templates/applications/keycloak/` - Keycloak application template
+
+**Template Validation:**
+- Template folder must exist in `templates/applications/<name>/`
+- Template folder must contain at least one file
+- Hidden files (starting with `.`) are skipped
+- If a template includes a `Dockerfile`, it will be copied to `builder/<app>/Dockerfile` along with other files
+
+### Language Templates
 
 - `python/Dockerfile.hbs` - Python application Dockerfile template
 - `python/docker-compose.hbs` - Python application docker-compose template
 - `typescript/Dockerfile.hbs` - TypeScript/Node.js application Dockerfile template
 - `typescript/docker-compose.hbs` - TypeScript/Node.js application docker-compose template
+
+### Infrastructure Templates
+
 - `infra/compose.yaml` - Infrastructure services docker-compose template
 
+### GitHub Workflow Templates
+
+- `github/ci.yaml.hbs` - Continuous Integration workflow
+- `github/pr-checks.yaml.hbs` - Pull Request checks workflow
+- `github/release.yaml.hbs` - Release and publish workflow
+- `github/test.yaml.hbs` - Test workflow
+
+### GitHub Workflow Step Templates (for `--github-steps` flag)
+
+Extra workflow steps are located in `templates/github/steps/`. When you use `--github-steps <steps>`, the tool loads step templates from `templates/github/steps/{step}.hbs` and includes them in the generated workflows.
+
+**Example:**
+- `github/steps/npm.hbs` - NPM publishing step
+- `github/steps/test.hbs` - Custom test step
+
+**Step Templates:**
+- Step templates are Handlebars templates that generate workflow job definitions
+- They receive the same context as the main workflow templates
+- Step templates are rendered and included in workflow files based on the `githubSteps` array
+
 ## Template Variables
 
 ### Application Configuration
@@ -34,7 +75,38 @@ These are Handlebars (.hbs) template files that generate Docker files for AI Fab
 
 ## Usage
 
-These templates are processed by the AI Fabrix Builder SDK based on the application schema defined in `variables.yaml`. The generated files will be valid Docker files after template processing.
+### Application Templates
+
+Use `--template <name>` when creating an application:
+
+```bash
+aifabrix create myapp --template miso-controller --port 3000
+```
+
+This validates that `templates/applications/miso-controller/` exists and copies all files (including Dockerfile if present) from it to `builder/myapp/`.
+
+### GitHub Workflow Steps
+
+Use `--github-steps <steps>` when creating an application with GitHub workflows:
+
+```bash
+aifabrix create myapp --github --github-steps npm
+```
+
+This loads step templates from:
+- `templates/github/steps/npm.hbs`
+
+And includes them in the generated workflow files (e.g., `release.yaml`).
+
+**Currently available step templates:**
+- `npm.hbs` - Adds NPM publishing job to release workflow
+
+**Creating custom step templates:**
+Create your own step templates in `templates/github/steps/{your-step}.hbs` and reference them in `--github-steps`.
+
+### Language and Infrastructure Templates
+
+These templates are processed automatically by the AI Fabrix Builder SDK based on the application schema defined in `variables.yaml`. The generated files will be valid Docker files after template processing.
 
 ## VS Code Configuration
 

package/templates/applications/keycloak/Dockerfile

@@ -0,0 +1,36 @@
+# Keycloak Identity and Access Management with Custom Themes
+# This Dockerfile extends Keycloak 24.0 with custom themes
+
+FROM quay.io/keycloak/keycloak:24.0
+
+# Set working directory
+WORKDIR /opt/keycloak
+
+# Copy custom themes from share directory (only if themes/ folder exists)
+USER root
+# Use a shell script approach: copy themes if it exists, otherwise skip
+# First, copy everything from build context to a staging area
+COPY . /tmp/build-context/
+# Then conditionally copy themes if the directory exists
+RUN if [ -d "/tmp/build-context/themes" ] && [ "$(ls -A /tmp/build-context/themes)" ]; then \
+      cp -r /tmp/build-context/themes/* /opt/keycloak/themes/ && \
+      chown -R keycloak:keycloak /opt/keycloak/themes/ && \
+      echo "Themes copied successfully"; \
+    else \
+      echo "No themes directory found, skipping theme copy"; \
+    fi && \
+    rm -rf /tmp/build-context
+
+# Build Keycloak with health checks enabled
+# This enables the /health, /health/live, /health/ready, and /health/started endpoints
+RUN /opt/keycloak/bin/kc.sh build --health-enabled=true
+
+# Switch back to keycloak user
+USER keycloak
+
+# Keycloak runs on port 8080 internally, exposed as 8082
+EXPOSE 8080
+
+# Default Keycloak command (can be overridden in docker-compose.yaml)
+# Health checks are enabled via the build step above
+CMD ["start-dev"]

package/templates/applications/keycloak/env.template

@@ -0,0 +1,32 @@
+# Environment Variables Template
+# Use kv:// references for secrets (resolved from .aifabrix/secrets.yaml)
+# Use ${VAR} for environment-specific values
+
+# =============================================================================
+# APPLICATION ENVIRONMENT
+# =============================================================================
+
+KEYCLOAK_ADMIN=admin
+KEYCLOAK_ADMIN_PASSWORD=kv://keycloak-admin-passwordKeyVault
+KC_HOSTNAME_STRICT=false
+KC_HTTP_ENABLED=true
+
+# =============================================================================
+# HEALTH CHECK CONFIGURATION
+# =============================================================================
+# Enable health check endpoints: /health, /health/live, /health/ready, /health/started
+
+KC_HEALTH_ENABLED=true
+
+# =============================================================================
+# DATABASE CONFIGURATION
+# =============================================================================
+# Connects to postgres service in Docker network (postgres) or localhost (local)
+
+KC_DB=postgres
+KC_DB_URL_HOST=${DB_HOST}
+KC_DB_URL_PORT=5432
+KC_DB_URL_DATABASE=keycloak
+KC_DB_USERNAME=keycloak_user
+KC_DB_PASSWORD=kv://databases-keycloak-0-passwordKeyVault
+