@aifabrix/builder 2.0.0

package/lib/validator.js

@@ -0,0 +1,377 @@
+/**
+ * AI Fabrix Builder Schema Validation
+ *
+ * This module provides schema validation with developer-friendly error messages.
+ * Validates variables.yaml, rbac.yaml, and env.template files.
+ *
+ * @fileoverview Schema validation with friendly error messages for AI Fabrix Builder
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const Ajv = require('ajv');
+const applicationSchema = require('./schema/application-schema.json');
+
+/**
+ * Validates variables.yaml file against application schema
+ * Provides detailed error messages for configuration issues
+ *
+ * @async
+ * @function validateVariables
+ * @param {string} appName - Name of the application
+ * @returns {Promise<Object>} Validation result with errors and warnings
+ * @throws {Error} If file cannot be read or parsed
+ *
+ * @example
+ * const result = await validateVariables('myapp');
+ * // Returns: { valid: true, errors: [], warnings: [] }
+ */
+async function validateVariables(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const variablesPath = path.join(process.cwd(), 'builder', appName, 'variables.yaml');
+
+  if (!fs.existsSync(variablesPath)) {
+    throw new Error(`variables.yaml not found: ${variablesPath}`);
+  }
+
+  const content = fs.readFileSync(variablesPath, 'utf8');
+  let variables;
+
+  try {
+    variables = yaml.load(content);
+  } catch (error) {
+    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
+  }
+
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  const validate = ajv.compile(applicationSchema);
+  const valid = validate(variables);
+
+  return {
+    valid,
+    errors: valid ? [] : formatValidationErrors(validate.errors),
+    warnings: []
+  };
+}
+
+/**
+ * Validates rbac.yaml file structure and content
+ * Ensures roles and permissions are properly defined
+ *
+ * @async
+ * @function validateRbac
+ * @param {string} appName - Name of the application
+ * @returns {Promise<Object>} Validation result with errors and warnings
+ * @throws {Error} If file cannot be read or parsed
+ *
+ * @example
+ * const result = await validateRbac('myapp');
+ * // Returns: { valid: true, errors: [], warnings: [] }
+ */
+function validateRoles(roles) {
+  const errors = [];
+  if (!roles || !Array.isArray(roles)) {
+    errors.push('rbac.yaml must contain a "roles" array');
+    return errors;
+  }
+
+  const roleNames = new Set();
+  roles.forEach((role, index) => {
+    if (!role.name || !role.value || !role.description) {
+      errors.push(`Role at index ${index} is missing required fields (name, value, description)`);
+    } else if (roleNames.has(role.value)) {
+      errors.push(`Duplicate role value: ${role.value}`);
+    } else {
+      roleNames.add(role.value);
+    }
+  });
+  return errors;
+}
+
+function validatePermissions(permissions) {
+  const errors = [];
+  if (!permissions || !Array.isArray(permissions)) {
+    errors.push('rbac.yaml must contain a "permissions" array');
+    return errors;
+  }
+
+  const permissionNames = new Set();
+  permissions.forEach((permission, index) => {
+    if (!permission.name || !permission.roles || !permission.description) {
+      errors.push(`Permission at index ${index} is missing required fields (name, roles, description)`);
+    } else if (permissionNames.has(permission.name)) {
+      errors.push(`Duplicate permission name: ${permission.name}`);
+    } else {
+      permissionNames.add(permission.name);
+    }
+  });
+  return errors;
+}
+
+async function validateRbac(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const rbacPath = path.join(process.cwd(), 'builder', appName, 'rbac.yaml');
+
+  if (!fs.existsSync(rbacPath)) {
+    return { valid: true, errors: [], warnings: ['rbac.yaml not found - authentication disabled'] };
+  }
+
+  const content = fs.readFileSync(rbacPath, 'utf8');
+  let rbac;
+
+  try {
+    rbac = yaml.load(content);
+  } catch (error) {
+    throw new Error(`Invalid YAML syntax in rbac.yaml: ${error.message}`);
+  }
+
+  const errors = [
+    ...validateRoles(rbac.roles),
+    ...validatePermissions(rbac.permissions)
+  ];
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings: []
+  };
+}
+
+/**
+ * Validates env.template file for proper kv:// references
+ * Checks for syntax errors and missing secret references
+ *
+ * @async
+ * @function validateEnvTemplate
+ * @param {string} appName - Name of the application
+ * @returns {Promise<Object>} Validation result with errors and warnings
+ * @throws {Error} If file cannot be read
+ *
+ * @example
+ * const result = await validateEnvTemplate('myapp');
+ * // Returns: { valid: true, errors: [], warnings: [] }
+ */
+async function validateEnvTemplate(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const templatePath = path.join(process.cwd(), 'builder', appName, 'env.template');
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`env.template not found: ${templatePath}`);
+  }
+
+  const content = fs.readFileSync(templatePath, 'utf8');
+  const errors = [];
+  const warnings = [];
+
+  // Check for valid environment variable syntax
+  const lines = content.split('\n');
+  lines.forEach((line, index) => {
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('#')) {
+      if (!trimmed.includes('=')) {
+        errors.push(`Line ${index + 1}: Invalid environment variable format (missing =)`);
+      } else {
+        const [key, value] = trimmed.split('=', 2);
+        if (!key || !value) {
+          errors.push(`Line ${index + 1}: Invalid environment variable format`);
+        }
+      }
+    }
+  });
+
+  // Check for kv:// reference format
+  const kvPattern = /kv:\/\/([a-zA-Z0-9-_]+)/g;
+  let match;
+  while ((match = kvPattern.exec(content)) !== null) {
+    const secretKey = match[1];
+    if (!secretKey) {
+      errors.push('Invalid kv:// reference format');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+
+/**
+ * Checks the development environment for common issues
+ * Validates Docker, ports, secrets, and other requirements
+ *
+ * @async
+ * @function checkEnvironment
+ * @returns {Promise<Object>} Environment check result
+ * @throws {Error} If critical issues are found
+ *
+ * @example
+ * const result = await checkEnvironment();
+ * // Returns: { docker: 'ok', ports: 'ok', secrets: 'missing', recommendations: [...] }
+ */
+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');
+  }
+
+  return result;
+}
+
+/**
+ * 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 errorMessages[error.keyword] || `${field}: ${error.message}`;
+}
+
+function formatValidationErrors(errors) {
+  if (!Array.isArray(errors)) {
+    return ['Unknown validation error'];
+  }
+
+  return errors.map(formatSingleError);
+}
+
+/**
+ * Validates all application configuration files
+ * Runs complete validation suite for an application
+ *
+ * @async
+ * @function validateApplication
+ * @param {string} appName - Name of the application
+ * @returns {Promise<Object>} Complete validation result
+ * @throws {Error} If validation fails
+ *
+ * @example
+ * const result = await validateApplication('myapp');
+ * // Returns: { valid: true, variables: {...}, rbac: {...}, env: {...} }
+ */
+async function validateApplication(appName) {
+  if (!appName || typeof appName !== 'string') {
+    throw new Error('App name is required and must be a string');
+  }
+
+  const variables = await validateVariables(appName);
+  const rbac = await validateRbac(appName);
+  const env = await validateEnvTemplate(appName);
+
+  const valid = variables.valid && rbac.valid && env.valid;
+
+  return {
+    valid,
+    variables,
+    rbac,
+    env,
+    summary: {
+      totalErrors: variables.errors.length + rbac.errors.length + env.errors.length,
+      totalWarnings: variables.warnings.length + rbac.warnings.length + env.warnings.length
+    }
+  };
+}
+
+module.exports = {
+  validateVariables,
+  validateRbac,
+  validateEnvTemplate,
+  checkEnvironment,
+  formatValidationErrors,
+  validateApplication
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@aifabrix/builder",
+  "version": "2.0.0",
+  "description": "AI Fabrix Local Fabric & Deployment SDK",
+  "main": "lib/index.js",
+  "bin": {
+    "aifabrix": "bin/aifabrix.js"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "test:ci": "jest --ci --coverage --watchAll=false",
+    "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:ci",
+    "validate": "npm run build",
+    "prepublishOnly": "npm run validate",
+    "precommit": "npm run lint:fix && npm run test",
+    "posttest": "npm run lint"
+  },
+  "keywords": [
+    "aifabrix",
+    "docker",
+    "deployment",
+    "cli",
+    "azure",
+    "container"
+  ],
+  "author": "eSystems Nordic Ltd",
+  "license": "UNLICENSED",
+  "engines": {
+    "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"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "eslint": "^8.55.0",
+    "@types/node": "^20.10.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esystemsdev/aifabrix-builder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/esystemsdev/aifabrix-builder/issues"
+  },
+  "homepage": "https://github.com/esystemsdev/aifabrix-builder#readme"
+}

package/templates/README.md

@@ -0,0 +1,51 @@
+# 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.
+
+## Template Files
+
+- `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
+- `infra/compose.yaml` - Infrastructure services docker-compose template
+
+## Template Variables
+
+### Application Configuration
+- `{{app.key}}` - Application key/identifier
+- `{{image.name}}` - Container image name
+- `{{image.tag}}` - Container image tag (defaults to "latest")
+- `{{port}}` - Application port from schema
+- `{{startupCommand}}` - Custom startup command (optional)
+
+### Health Check Configuration
+- `{{healthCheck.path}}` - Health check endpoint path (e.g., "/health")
+- `{{healthCheck.interval}}` - Health check interval in seconds
+
+### Service Requirements
+- `{{requiresDatabase}}` - Database requirement flag (conditional db-init service)
+- `{{requiresStorage}}` - Storage requirement flag (conditional volume mounting)
+- `{{databases}}` - Array of database configurations
+
+### Build Configuration
+- `{{build.localPort}}` - Local development port (different from Docker port)
+- `{{mountVolume}}` - Volume mount path for local development
+
+## 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.
+
+## VS Code Configuration
+
+The `.vscode/settings.json` file is configured to:
+- Treat `.hbs` files as Handlebars templates (not Dockerfiles)
+- Ignore template files from Docker linting
+- Prevent false linting errors on template variables
+
+## Generated Output
+
+After processing, these templates generate:
+- Valid Dockerfiles with proper syntax
+- Docker-compose files with conditional services
+- Infrastructure configurations with shared services only

package/templates/github/ci.yaml.hbs

@@ -0,0 +1,15 @@
+name: CI/CD Pipeline
+on:
+  push:
+    branches: [{{mainBranch}}]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Run tests
+        run: npm test

package/templates/github/pr-checks.yaml.hbs

@@ -0,0 +1,35 @@
+name: Pull Request Checks
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  pr-validation:
+    name: PR Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Check file sizes
+        run: |
+          find {{sourceDir}} -name "*.{{fileExtension}}" -exec sh -c 'lines=$(wc -l < "$1"); if [ $lines -gt 500 ]; then echo "File $1 exceeds 500 lines ($lines)"; exit 1; fi' _ {} \;
+      
+      - name: Check for TODOs in modified files
+        run: |
+          git diff origin/${{ github.base_ref }} --name-only | grep "\.{{fileExtension}}$" | xargs grep -n "TODO" || true
+      
+      - name: Validate commit messages
+        run: |
+          git log origin/${{ github.base_ref }}..HEAD --format=%s | grep -E "^(feat|fix|docs|style|refactor|test|chore|perf)(\(.+\))?: .+" || echo "Warning: Some commits don't follow conventional commits"

package/templates/github/release.yaml.hbs

@@ -0,0 +1,79 @@
+name: Release and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  validate:
+    name: Validate Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run all checks
+        run: npm run validate
+      
+      - name: Verify version matches tag
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+
+{{#if publishToNpm}}
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build package
+        run: npm run build
+      
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+{{/if}}
+
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: {{#if publishToNpm}}publish-npm{{else}}validate{{/if}}
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Create Release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body: Release {{appName}} ${{ github.ref }}
+          draft: false
+          prerelease: false

package/templates/github/test.hbs

@@ -0,0 +1,11 @@
+name: Test Workflow
+on:
+  push:
+    branches: [{{mainBranch}}]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Test {{appName}}
+        run: echo "Testing {{appName}}"

package/templates/github/test.yaml.hbs

@@ -0,0 +1,11 @@
+name: Test Workflow
+on:
+  push:
+    branches: [{{mainBranch}}]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Test {{appName}}
+        run: echo "Testing {{appName}}"