@bluefly/bfcli v0.2.2

bfcli - AI Platform Command Line Interface

Overview

Enterprise command line interface for AI Platform orchestration. Production-ready with OpenAPI 3.1 compliance, comprehensive service management, and automated platform operations. Implements plugin-based architecture with dependency injection, distributed tracing, and enterprise-grade security.

Features

Core Capabilities

• Platform Management: Service deployment and orchestration
• Drupal Integration: Drupal 11 + Recipe automation
• Cloud Operations: Multi-cloud deployment (AWS, Azure, GCP)
• Plugin System: Hot-swappable plugins with DI
• GitLab CI/CD: Pipeline automation and management
• Security: JWT authentication and audit logging
• API Gateway: OpenAPI 3.1 compliant interfaces

Advanced Features

• Service Mesh: Distributed service management
• Metrics Engine: Real-time performance monitoring
• Distributed Tracing: OpenTelemetry integration
• Database Operations: Migration and replication
• Secret Management: Vault integration
• Auto-scaling: Dynamic resource management

Architecture

Core Components

• Command Engine: TypeScript command framework
• Plugin Manager: Dynamic plugin loading
• Service Layer: Business logic orchestration
• Config System: Multi-source configuration
• API Client: OpenAPI 3.1 client generation
• Security: Authentication and authorization

Platform Integration

graph TB
    subgraph "CLI Core"
        A[Command Engine] --> H[Plugin Manager]
        B[Service Layer] --> H
        C[Config System] --> H
        D[Security] --> H
    end
    
    subgraph "Platform Services"
        H --> I[bfapi]
        H --> J[bfmcp]
        H --> K[Drupal Control]
        H --> L[Cloud Providers]
    end
    
    subgraph "Monitoring"
        H --> M[OpenTelemetry]
        H --> N[Prometheus]
        H --> O[Grafana]
    end

Infrastructure

• Containerization: Docker and Kubernetes
• Orchestration: Service mesh integration
• CI/CD: GitLab CI templates
• Testing: 95% test coverage with TDD
• Security: Automated vulnerability scanning
• Performance: Real-time metrics collection

Command Catalog

Platform Commands

Drupal Commands

GitLab Commands

Maintenance Commands

Prerequisites

Core Requirements

• Node.js 20.x or later
• TypeScript 5.x or later
• GitLab access token
• Cloud provider credentials
• Drupal 11.x
• OpenAPI 3.1 specifications

Optional Requirements

• Docker and Kubernetes
• Prometheus and Grafana
• OpenTelemetry collector
• HashiCorp Vault

Installation

Quick Start

# Install CLI tool globally
npm install -g @bluefly/bfcli

# Verify installation
bfcli --version

Development Setup

# Clone the repository
git clone https://github.com/blueflyio/bfcli.git
cd bfcli

# Install dependencies
npm install

# Build the project
npm run build

# Create a symbolic link for local development
npm link

Usage

Basic Platform Management

# Initialize platform
bfcli platform:init --env=production

# Deploy services
bfcli platform:deploy --stack=enterprise

# Check status
bfcli platform:status --detailed

# Health check
bfcli platform:doctor --comprehensive

Drupal Operations

# Check Drupal status
bfcli drush:status --detailed

# Manage modules
bfcli drush:modules --list
bfcli drush:modules --enable=my_module

# Cache operations
bfcli drush:cache --rebuild
bfcli drush:cache --clear=all

# Recipe management
bfcli drush:recipe --apply=my_recipe
bfcli drush:recipe --validate

Code Cleanup Command (v0.2.2)

The code-cleanup command reorganizes your CLI project structure following best practices:

# Reorganize CLI code structure
bfcli code-cleanup

# Preview changes without making them
bfcli code-cleanup --dry-run

# Skip updating import paths
bfcli code-cleanup --skip-imports

# Skip creating backup
bfcli code-cleanup --no-backup

# Show detailed output
bfcli code-cleanup --verbose

What the Code Cleanup Command Does

1. Creates a Backup: Makes a complete backup of your project before making changes
2. Creates Directory Structure: Sets up a standardized directory structure
3. Migrates Files: Moves files to their appropriate locations
4. Updates Import Paths: Updates import paths to reflect the new structure
5. Generates Reports: Creates a detailed report of all changes

Directory Structure Created

bfcli/
  ├── bin/               # CLI entry points
  ├── config/            # Configuration files
  ├── dist/              # Compiled output
  ├── docs/              # Documentation
  │   ├── commands/      # Command documentation
  │   ├── guides/        # User guides
  │   └── development/   # Developer documentation
  ├── scripts/           # Development and build scripts
  │   ├── build/         # Build scripts
  │   ├── docs/          # Documentation scripts
  │   └── utils/         # Utility scripts
  ├── src/               # Source code
  │   ├── commands/      # CLI commands
  │   │   ├── core/      # Core command infrastructure
  │   │   ├── drupal/    # Drupal-related commands
  │   │   ├── git/       # Git-related commands
  │   │   ├── llm/       # LLM-related commands
  │   │   ├── system/    # System commands
  │   │   └── utils/     # Utility commands
  │   ├── compatibility/ # Backward compatibility
  │   ├── models/        # Data models
  │   ├── services/      # Services
  │   └── utils/         # Utilities
  └── tests/             # Tests
      ├── unit/          # Unit tests
      ├── integration/   # Integration tests
      └── fixtures/      # Test fixtures

Configuration

CLI Configuration

// config.ts
import { CLIConfig } from '@bluefly/cli';

export const cliConfig: CLIConfig = {
  platform: {
    environment: 'production',
    region: 'us-west-2',
    services: {
      ai: true,
      llm: true,
      mcp: true
    }
  },
  drupal: {
    root: './web',
    containerTool: 'ddev',
    recipePath: './recipes'
  },
  gitlab: {
    host: 'https://gitlab.bluefly.io',
    token: process.env.GITLAB_TOKEN,
    projectId: 123
  },
  monitoring: {
    enabled: true,
    providers: {
      prometheus: true,
      opentelemetry: true
    },
    sampling: 1.0
  }
};

Plugin Configuration

// plugins.ts
import { PluginConfig } from '@bluefly/cli';

export const pluginConfig: PluginConfig = {
  paths: [
    './custom-plugins',
    './enterprise-plugins'
  ],
  registry: {
    type: 'npm',
    scope: '@bluefly'
  },
  security: {
    validation: true,
    sandbox: true
  },
  telemetry: {
    enabled: true,
    sampling: 1.0,
    exportInterval: 60
  }
};

Development

Setup

# Install development dependencies
npm install --dev

# Setup development environment
npm run setup:dev

# Start development server
npm run dev

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:performance
npm run test:security

# Generate coverage report
npm run test:coverage

# Run TDD workflow
npm run recipe:tdd:gen    # Generate test skeletons
npm run recipe:tdd:verify # Verify tests fail as expected
npm run recipe:tdd:check  # Check implementation meets tests
npm run recipe:tdd:install # Install and validate in environment

Building

# Build for production
npm run build

# Quick safe build (JavaScript only, no TypeScript)
npm run build:safe

# Build and create a symlink in your bin directory
npm run build:link

# Build and run the CLI in one command
npm run build:run -- --help

# Build Docker images
npm run docker:build

# Build documentation
npm run docs:build

# Build OpenAPI spec
npm run openapi:build

Quick Start with Safe Build

If you're experiencing TypeScript build issues, you can use the safe build system which creates a functional CLI without requiring TypeScript compilation:

# Build the CLI with the safe build system
npm run build:safe

# Build and run the CLI
npm run build:run -- --help

# Build and create a symlink in your bin directory
npm run build:link

Enhanced CLI with Detailed Command Descriptions

The CLI includes an enhanced version with detailed command descriptions, better organization, and improved visual formatting:

# Quick way to try out the enhanced CLI
./try-enhanced.sh

# Or install the enhanced CLI with help formatter manually
./update-cli-with-help.sh

Enhanced Help Utilities

There are multiple ways to access the enhanced help system:

1. Interactive Command Explorer - Browse and search commands interactively:

   # Launch interactive explorer
   bfcli command-explorer
   
   # List all commands with descriptions
   bfcli command-explorer list
   
   # Get detailed help for a specific command
   bfcli command-explorer llm

2. Enhanced Help Utility - Reads directly from the CLI script for up-to-date information:

   # View enhanced main help screen
   ./dist/enhanced-help
   
   # View detailed command list
   ./dist/enhanced-help list
   
   # Get detailed help for a specific command
   ./dist/enhanced-help help llm

3. CLI Help Commands - Built into the CLI itself:

   # View CLI help screen
   ./dist/cli.js --help
   
   # View detailed command list
   ./dist/cli.js list
   
   # Get detailed help for a specific command
   ./dist/cli.js help llm

Enhanced Features

• Interactive Explorer: Browse and search commands interactively
• Detailed Descriptions: Comprehensive explanation of each command's functionality
• Command Categories: Logical grouping of related commands
• Visual Formatting: Improved terminal output with color and formatting
• Usage Examples: Clear examples for each command
• Subcommand Support: Detailed information about available subcommands
• Command Organization: Commands organized by related functionality
• Related Commands: Discover related functionality
• Search Capabilities: Find commands by name, description, or category

Customizing Descriptions

You can add or update detailed command descriptions:

# Update detailed descriptions in batch
node scripts/populate-detailed-descriptions.cjs

# Add a specific command description
node scripts/add-command.js <n> <description> <category> <longDescription>

Contributing

See CONTRIBUTING.md for development guidelines.

Security

• Report security issues to security@bluefly.io
• Follow our Security Policy
• Review Security Guidelines

License

MIT License - see LICENSE for details

Support

• Documentation
• Issue Queue
• Community Support
• API Reference

Credits

• Bluefly.io
• Contributors
• Commander.js
• OpenAPI

The bfcli tool provides enterprise-grade platform management with OpenAPI compliance, comprehensive testing, and security validation.

Observability & Monitoring

The CLI implements comprehensive observability:

Metrics Collection

• Command execution times
• Plugin performance
• Service health status
• Resource utilization
• Error rates and types

Distributed Tracing

• Command lifecycle tracking
• Plugin execution flow
• Service interactions
• Resource utilization
• Error propagation

Health Monitoring

• Platform health status
• Service availability
• Plugin integrity
• Resource utilization
• Security status

Alerting

• Command failures
• Service degradation
• Resource exhaustion
• Security incidents
• Performance issues