CyberAi Advanced Build System Documentation

This document provides comprehensive information about the advanced build system integrated into the CyberAi repository.

🏗️ Overview

CyberAi now includes a sophisticated build system with multiple build tools and configurations to support various development and deployment scenarios.

🔧 Build Tools

1. Makefile

Cross-platform build automation with comprehensive targets for development and production.

Key Features:

Color-coded output for better readability
Parallel execution support
Comprehensive help system
Quality gates and verification

Usage:

make help           # Display all available targets
make install        # Install dependencies
make build          # Build the project
make test           # Run tests
make quality        # Run all quality checks

2. TypeScript Compiler (tsc)

Primary build tool for TypeScript compilation.

Configuration: tsconfig.json

Usage:

npm run build              # Standard build
npm run build:watch        # Watch mode
npm run typecheck          # Type check only

3. esbuild

Advanced bundling with optimization and tree-shaking.

Configuration: esbuild.config.js

Features:

Fast compilation
Code splitting
Tree shaking
Minification
Source maps

Usage:

npm run build:esbuild        # Build with esbuild
npm run build:esbuild:watch  # Watch mode

4. Turbo

Monorepo build orchestration with intelligent caching.

Configuration: turbo.json

Features:

Parallel execution
Incremental builds
Remote caching
Task dependencies

Usage:

turbo run build      # Run build with turbo
turbo run test       # Run tests with caching

5. Advanced Build Script

Comprehensive build orchestration script.

Location: scripts/advanced-build.sh

Features:

Multi-stage builds
Environment configuration
Quality checks integration
Build verification
Detailed logging

Usage:

npm run build:advanced     # Production build
npm run build:dev          # Development build

# With environment variables
SKIP_TESTS=true npm run build:advanced
VERBOSE=true npm run build:advanced

🚀 Quick Start

Basic Build

# Clone and setup
git clone https://github.com/SolanaRemix/CyberAi.git
cd CyberAi

# Using Makefile (recommended)
make install
make build
make test

# Using npm scripts
npm ci
npm run build
npm test

Production Build

# Using Makefile
make build-prod

# Using advanced script
npm run build:advanced

# Using Make with full pipeline
make ci

Development Workflow

# Start in watch mode
make build-watch

# Or using npm
npm run build:watch

# With test watcher
make test-watch

📦 Build Commands

NPM Scripts

Command	Description
`npm run build`	Standard TypeScript build
`npm run build:advanced`	Production build with advanced script (requires bash)
`npm run build:dev`	Development build (requires bash)
`npm run build:watch`	Watch mode for incremental builds
`npm run build:esbuild`	Build with esbuild bundler
`npm run build:esbuild:watch`	esbuild watch mode
`npm run clean`	Clean build artifacts (cross-platform via rimraf)
`npm run clean:all`	Deep clean including node_modules (cross-platform)

Makefile Targets

Target	Description
`make help`	Display help
`make install`	Install dependencies
`make build`	Build project
`make build-prod`	Production build
`make build-watch`	Watch mode
`make test`	Run tests
`make lint`	Run linter
`make typecheck`	Type checking
`make quality`	All quality checks
`make clean`	Clean artifacts
`make ci`	Full CI pipeline

⚙️ Configuration Files

`tsconfig.json`

TypeScript compiler configuration.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "outDir": "./dist"
  }
}

`esbuild.config.js`

esbuild bundler configuration with multiple entry points.

Key Features:

Multiple bundles (main, agents, contracts, security, utils)
Production minification
Source maps
Tree shaking
Watch mode support

`turbo.json`

Turbo monorepo configuration.

Pipeline Configuration:

Build dependencies
Caching strategies
Output directories
Environment variables

`Makefile`

Cross-platform build automation.

Variables:

NODE_VERSION: Target Node.js version
BUILD_DIR: Build output directory
LOGS_DIR: Logs directory

🐳 Docker Support

Dockerfile

Multi-stage Docker build with optimization.

Stages:

base: Base image with system dependencies
deps: Production dependencies
dev-deps: Development dependencies
builder: Build stage
production: Final production image
development: Development image

Usage:

# Build production image
docker build -t cyberai:latest .

# Build development image
docker build --target development -t cyberai:dev .

# Run container
docker run -p 3000:3000 cyberai:latest

docker-compose.yml

Multi-service orchestration.

Services:

app: Main application (production)
dev: Development service
site: Astro site
redis: Cache layer (optional)
nginx: Reverse proxy (optional)

Usage:

# Start all services
docker-compose up -d

# Start specific profile
docker-compose --profile dev up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

NPM Scripts:

npm run docker:build    # Build Docker image
npm run docker:run      # Run container
npm run docker:up       # Docker Compose up
npm run docker:down     # Docker Compose down

🔄 CI/CD Integration

GitHub Actions Workflow

Location: .github/workflows/advanced-build.yml

Jobs:

build-matrix: Multi-platform builds (Ubuntu, macOS, Windows)
optimized-build: Production-optimized build
docker-build: Docker image build test
verify-build: Build output verification
benchmark: Performance benchmarks

Features:

Multi-OS testing
Multiple Node.js versions
Build artifacts upload
Size analysis
Performance metrics

Trigger:

# Automatically on push/PR to main/develop
# Manual trigger via workflow_dispatch

🎯 Advanced Features

1. Parallel Builds

# Using Make parallel execution
make -j4 build test lint

# Using Turbo
turbo run build test --parallel

2. Incremental Builds

# TypeScript incremental
npm run build:watch

# esbuild watch
npm run build:esbuild:watch

3. Build Caching

TypeScript: .tsbuildinfo
Turbo: .turbo/cache
Docker: BuildKit cache

4. Build Information

Generated file: dist/build-info.json

Contains:

Version
Build mode
Timestamp
Node version
Git commit/branch
Platform info

5. Quality Gates

# Run all quality checks
make quality

# Individual checks
make lint
make typecheck
make test

6. Build Verification

Automatic verification of:

Build output existence
Required files
Build info generation

🛠️ Troubleshooting

Common Issues

Build Fails with "Out of Memory"

# Increase Node memory
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Permission Denied on Scripts

chmod +x scripts/advanced-build.sh

Docker Build Slow

# Use BuildKit
DOCKER_BUILDKIT=1 docker build .

# Check .dockerignore
cat .dockerignore

Makefile Not Found

Ensure you're in the project root:

cd /home/runner/work/CyberAi/CyberAi
make help

Clean Build

# Clean and rebuild
make clean-all
make install
make build

Verbose Output

# With advanced script
VERBOSE=true npm run build:advanced

# With make
make build V=1

📊 Build Metrics

Build Times (Approximate)

Standard build: ~5-10s
Advanced build: ~20-30s
Docker build: ~2-3 min
Full CI pipeline: ~5-10 min

Output Sizes

TypeScript output: ~500KB - 2MB
esbuild bundle: ~300KB - 1MB (minified)
Docker image: ~200-400MB

🔐 Security

Best Practices

Use multi-stage Docker builds
Run as non-root user in containers
Scan dependencies regularly
Use specific versions in CI
Implement build verification

Security Features

Non-root Docker user
Minimal base images
Dependency scanning
Secret exclusion (.dockerignore)

📚 Additional Resources

🤝 Contributing

When adding new build features:

Update this documentation
Add tests for new build targets
Update CI/CD workflows
Ensure cross-platform compatibility
Add examples and troubleshooting

📝 License

This build system is part of the CyberAi project and follows the same license (MIT).

Uh oh!

FilesExpand file tree

BUILD.md

Latest commit

History

BUILD.md

File metadata and controls

CyberAi Advanced Build System Documentation

🏗️ Overview

📋 Table of Contents

🔧 Build Tools

1. Makefile

2. TypeScript Compiler (tsc)

3. esbuild

4. Turbo

5. Advanced Build Script

🚀 Quick Start

Basic Build

Production Build

Development Workflow

📦 Build Commands

NPM Scripts

Makefile Targets

⚙️ Configuration Files

tsconfig.json

esbuild.config.js

turbo.json

Makefile

🐳 Docker Support

Dockerfile

docker-compose.yml

🔄 CI/CD Integration

GitHub Actions Workflow

🎯 Advanced Features

1. Parallel Builds

2. Incremental Builds

3. Build Caching

4. Build Information

5. Quality Gates

6. Build Verification

🛠️ Troubleshooting

Common Issues

Build Fails with "Out of Memory"

Permission Denied on Scripts

Docker Build Slow

Makefile Not Found

Clean Build

Verbose Output

📊 Build Metrics

Build Times (Approximate)

Output Sizes

🔐 Security

Best Practices

Security Features

📚 Additional Resources

🤝 Contributing

📝 License

`tsconfig.json`

`esbuild.config.js`

`turbo.json`

`Makefile`