---

Core Engine

The Core Engine is the foundational component of the Provisioning project, providing the unified CLI interface, core Nushell libraries, and essential utility scripts. Built on Nushell and Nickel, it serves as the primary entry point for all infrastructure operations.

Overview

The Core Engine provides:

• Unified CLI Interface - Single command-line tool for all infrastructure operations
• Core Libraries - Reusable Nushell modules for configuration, validation, and utilities
• Provider Abstraction - Cloud-agnostic interface supporting UpCloud, AWS, and local providers
• Workflow Integration - Commands for submitting and managing workflows (executed by the orchestrator)
• Configuration System - Hierarchical, config-driven architecture with 476+ configuration accessors

Project Structure

provisioning/core/
├── cli/                    # Command-line interface
│   └── provisioning        # Main CLI entry point (211 lines, 84% reduction)
├── nulib/                  # Core Nushell libraries
│   ├── lib_provisioning/   # Core provisioning libraries
│   │   ├── config/         # Configuration loading and management
│   │   ├── utils/          # Utility functions (SSH, validation, logging)
│   │   ├── providers/      # Provider abstraction layer
│   │   ├── secrets/        # Secrets management (SOPS integration)
│   │   ├── workspace/      # Workspace management
│   │   └── infra_validator/ # Infrastructure validation engine
│   ├── main_provisioning/  # CLI command handlers
│   │   ├── flags.nu        # Centralized flag handling
│   │   ├── dispatcher.nu   # Command routing (80+ shortcuts)
│   │   ├── help_system.nu  # Categorized help system
│   │   └── commands/       # Domain-focused command modules
│   ├── servers/            # Server management modules
│   ├── taskservs/          # Task service modules
│   ├── clusters/           # Cluster management modules
│   └── workflows/          # Workflow orchestration modules
├── scripts/                # Utility scripts
│   └── test/               # Test automation
└── resources/              # Images and logos
```plaintext

## Installation

### Prerequisites

- **Nushell 0.109.0+** - Primary shell and scripting environment
- **Nickel 1.15.1+** - Configuration language for infrastructure definitions
- **SOPS 3.10.2+** - Secrets management (optional but recommended)
- **Age 1.2.1+** - Encryption tool for secrets (optional)

### Adding to PATH

To use the CLI globally, add it to your PATH:

```bash
# Create symbolic link
ln -sf "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning

# Or add to PATH in your shell config (~/.bashrc, ~/.zshrc, etc.)
export PATH="$PATH:/path/to/project-provisioning/provisioning/core/cli"
```plaintext

Verify installation:

```bash
provisioning version
provisioning help
```plaintext

## Quick Start

### Basic Commands

```bash
# Show help and available commands
provisioning help

# Show environment and configuration
provisioning env
provisioning allenv

# Validate configuration
provisioning validate config

# List available providers
provisioning providers

# Show system information
provisioning nuinfo
```plaintext

### Infrastructure Operations

```bash
# Create new infrastructure workspace
provisioning workspace init my-project

# Create servers
provisioning server create --check

# Install task services (infrastructure components)
provisioning taskserv create kubernetes

# Create complete cluster
provisioning cluster create my-cluster

# SSH into server
provisioning server ssh hostname-01
```plaintext

### Quick Reference

For fastest command reference:

```bash
provisioning sc
```plaintext

For complete guides:

```bash
provisioning guide from-scratch    # Complete deployment guide
provisioning guide quickstart      # Command shortcuts reference
provisioning guide customize       # Customization patterns
```plaintext

## Core Libraries

### Configuration System (`lib_provisioning/config/`)

Hierarchical configuration loading with 476+ config accessors:

- **Defaults** → **User** → **Project** → **Infrastructure** → **Environment** → **Runtime**
- Replaced 200+ ENV variables with config-driven architecture
- Variable interpolation: `{{paths.base}}`, `{{env.HOME}}`, `{{now.date}}`

```nushell
use lib_provisioning/config

# Get configuration value
let value = config get "servers.default_plan"

# Load workspace config
let ws_config = config load-workspace "my-project"
```plaintext

### Provider Abstraction (`lib_provisioning/providers/`)

Unified interface for cloud providers:

```nushell
use lib_provisioning/providers

# Get provider interface
let provider = providers get "upcloud"

# Create server using provider
$provider | invoke "create_server" $server_config
```plaintext

### Utilities (`lib_provisioning/utils/`)

Common utility functions:

- **SSH Operations** - `utils/ssh.nu`
- **Validation** - `utils/validation.nu`
- **Logging** - `utils/logging.nu`
- **Error Handling** - `utils/error.nu`
- **File Operations** - `utils/files.nu`
- **Version Management** - `utils/version_manager.nu`

### Workflow Orchestration (`workflows/`)

Batch operations with dependency resolution:

```bash
# Submit batch workflow
provisioning batch submit workflows/example.ncl

# Monitor workflow progress
provisioning batch monitor <workflow-id>

# List all workflows
provisioning workflow list

# Get workflow status
provisioning workflow status <id>
```plaintext

## CLI Architecture

### Modular Design

The CLI uses a domain-driven architecture:

- **Infrastructure** - Servers, task services, clusters
- **Orchestration** - Workflows, batch operations, orchestrator management
- **Development** - Modules, layers, versioning, packaging
- **Workspace** - Workspace management, templates
- **Configuration** - Settings, environment, validation
- **Utilities** - SSH, SOPS, cache, plugins

### Command Shortcuts

80+ shortcuts for improved productivity:

| Full Command | Shortcuts | Description |
|--------------|-----------|-------------|
| `server` | `s` | Server operations |
| `taskserv` | `t`, `task` | Task service operations |
| `cluster` | `cl` | Cluster operations |
| `workspace` | `ws` | Workspace management |
| `workflow` | `wf`, `flow` | Workflow operations |
| `batch` | `bat` | Batch operations |
| `module` | `mod` | Module management |
| `generate` | `g`, `gen` | Code generation |
| `validate` | `val` | Validation operations |

See complete reference: `provisioning sc` or `provisioning guide quickstart`

### Bi-directional Help

Help works in both directions:

```bash
provisioning help workspace  # ✅
provisioning workspace help  # ✅ Same result
provisioning ws help         # ✅ Shortcut also works
```plaintext

## Configuration

### Configuration Files

With the new structure (2025-09-26):

- **System Defaults**: `provisioning/config/config.defaults.toml`
- **User Config**: `workspace/config/local-overrides.toml`
- **Environment Configs**: `workspace/config/{dev,test,prod}-defaults.toml`
- **Infrastructure Configs**: `workspace/infra/{name}/config.toml`

### Environment Variables

Legacy ENV variables still supported during transition:

```bash
# Show current environment
provisioning env

# Show all configuration and environment
provisioning allenv

# Use specific environment
PROVISIONING_ENV=prod provisioning server list
```plaintext

### Debug Flags

```bash
# Enable debug mode
provisioning --debug <command>

# Check mode (dry-run, no changes)
provisioning --check server create

# Auto-confirm operations
provisioning --yes cluster delete

# Specify infrastructure
provisioning --infra my-project server list
```plaintext

## Design Principles

### Modularity

Clean separation between libraries, CLI, and extensions:

- **Core Engine** (`core/`) - CLI, libraries, scripts
- **Extensions** (`extensions/`) - Providers, task services, clusters
- **Platform Services** (`platform/`) - Orchestrator, control center, API gateway

### Extensibility

Plugin architecture for extending functionality:

- Provider plugins for cloud integrations
- Task service definitions for infrastructure components
- Cluster templates for complete deployments
- Workflow templates for automation

### Consistency

Unified API patterns across all components:

- Standardized command structure
- Common flag handling
- Consistent error messages
- Predictable output formats

### Performance

Optimized for large-scale infrastructure operations:

- Token-optimized agents (85-90% efficiency)
- Batch operations with parallel execution
- Checkpoint-based recovery
- Incremental state management

## Migration Strategy

The project follows a three-phase migration:

1. **Phase 1** (Complete) - Created symbolic links to existing implementations
2. **Phase 2** (In Progress) - Gradual migration of components to new structure
3. **Phase 3** (Planned) - Consolidate and optimize unified core engine

## Dependencies

### Required

- **Nushell 0.109.0+** - Shell and scripting language
- **Nickel 1.15.1+** - Configuration language

### Recommended

- **SOPS 3.10.2+** - Secrets management
- **Age 1.2.1+** - Encryption for secrets
- **K9s 0.50.6+** - Kubernetes management interface

### Optional

- **nu_plugin_tera** - Template rendering
- **Nickel Language** - Native Nickel support via CLI (no plugin required)

## Documentation

### User Guides

- **Quick Start**: `provisioning guide from-scratch`
- **Command Reference**: `provisioning sc`
- **Update Guide**: `provisioning guide update`
- **Customization**: `provisioning guide customize`

### Architecture Documentation

- **CLI Architecture**: `../docs/src/architecture/adr/ADR-006-provisioning-cli-refactoring.md`
- **Configuration System**: `../docs/src/infrastructure/configuration-system.md`
- **Batch Workflows**: `../docs/src/infrastructure/batch-workflow-system.md`
- **Orchestrator**: `../docs/src/operations/orchestrator-system.md`

### API Documentation

- **REST API**: See `../docs/src/api-reference/` (when orchestrator is running)
- **Nushell Modules**: See inline documentation in `nulib/` modules

## Testing

### Run Tests

```bash
# Run all tests
nu provisioning/core/scripts/test/test_all.nu

# Run specific test group
nu provisioning/core/scripts/test/test_config.nu
nu provisioning/core/scripts/test/test_cli.nu
```plaintext

### Test Coverage

The core engine includes comprehensive test coverage:

- Configuration loading and validation
- Provider interface contracts
- CLI command routing
- Workflow orchestration
- Error handling

## Contributing

When contributing to the Core Engine:

1. **Follow Nushell Patterns** - See `.claude/best_nushell_code.md`
2. **Use Modular Design** - Domain-focused modules in appropriate directories
3. **Add Tests** - Include tests for new functionality
4. **Update Documentation** - Keep README and inline docs current
5. **Follow PAP** - Project Architecture Principles (see `CLAUDE.md`)

## Troubleshooting

### Common Issues

**Missing environment variables:**

```bash
provisioning env          # Check current configuration
provisioning validate config  # Validate configuration files
```plaintext

**Nickel schema errors:**

```bash
nickel fmt <file>.ncl          # Format Nickel file
nickel eval <file>.ncl         # Evaluate Nickel schema
nickel typecheck <file>.ncl    # Type check schema
```plaintext

**Provider authentication:**

```bash
provisioning providers    # List available providers
provisioning show settings # View provider configuration
```plaintext

### Debug Mode

Enable verbose logging:

```bash
provisioning --debug <command>
```plaintext

### Getting Help

```bash
provisioning help              # Show main help
provisioning help <category>   # Category-specific help
provisioning <command> help    # Command-specific help
provisioning guide list        # List all guides
```plaintext

## Version Information

Check system versions:

```bash
provisioning version           # Show all versions
provisioning nuinfo            # Nushell information
```plaintext

## License

See project root LICENSE file.

---

**Maintained By**: Core Team
**Last Updated**: 2026-01-08