provisioning/tools/distribution/generate-docs.nu

#!/usr/bin/env nu

# Documentation generation tool - generates distribution documentation
#
# Generates:
# - Installation guides and system requirements
# - User manuals and API documentation
# - Configuration references and examples
# - Troubleshooting guides and FAQ
# - Developer documentation and contributing guides

use std log

def main [
    --source-root: string = ""                  # Source root directory (auto-detected if empty)
    --output-dir: string = "dist/docs"          # Output directory for documentation
    --doc-types: string = "all"                 # Documentation types: user, admin, dev, api, all
    --format: string = "markdown"               # Output format: markdown, html, pdf, all
    --include-examples: bool = true             # Include configuration examples
    --generate-api: bool = true                 # Generate API documentation
    --create-index: bool = true                 # Create documentation index
    --minify-output: bool = false               # Minify output files
    --verbose: bool = false                     # Enable verbose logging
] -> record {

    let repo_root = if $source_root == "" {
        ($env.PWD | path dirname | path dirname | path dirname)
    } else {
        ($source_root | path expand)
    }

    let doc_types_list = if $doc_types == "all" {
        ["user", "admin", "dev", "api"]
    } else {
        ($doc_types | split row "," | each { str trim })
    }

    let format_list = if $format == "all" {
        ["markdown", "html"]
    } else {
        [$format]
    }

    let docs_config = {
        source_root: $repo_root
        output_dir: ($output_dir | path expand)
        doc_types: $doc_types_list
        formats: $format_list
        include_examples: $include_examples
        generate_api: $generate_api
        create_index: $create_index
        minify_output: $minify_output
        verbose: $verbose
    }

    log info $"Starting documentation generation with config: ($docs_config)"

    # Ensure output directory exists
    mkdir ($docs_config.output_dir)

    let generation_results = []

    try {
        # Phase 1: Discover documentation sources
        let discovery_result = discover_documentation_sources $docs_config

        let generation_results = ($generation_results | append { phase: "discovery", result: $discovery_result })

        # Phase 2: Generate user documentation
        let user_docs_result = if "user" in $docs_config.doc_types {
            generate_user_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "user documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "user", result: $user_docs_result })

        # Phase 3: Generate admin documentation
        let admin_docs_result = if "admin" in $docs_config.doc_types {
            generate_admin_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "admin documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "admin", result: $admin_docs_result })

        # Phase 4: Generate developer documentation
        let dev_docs_result = if "dev" in $docs_config.doc_types {
            generate_developer_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "developer documentation not requested" }
        }

        let generation_results = ($generation_results | append { phase: "dev", result: $dev_docs_result })

        # Phase 5: Generate API documentation
        let api_docs_result = if "api" in $docs_config.doc_types and $docs_config.generate_api {
            generate_api_documentation $docs_config $discovery_result
        } else {
            { status: "skipped", reason: "API documentation not requested or disabled" }
        }

        let generation_results = ($generation_results | append { phase: "api", result: $api_docs_result })

        # Phase 6: Create documentation index
        let index_result = if $docs_config.create_index {
            create_documentation_index $docs_config $generation_results
        } else {
            { status: "skipped", reason: "index creation disabled" }
        }

        let generation_results = ($generation_results | append { phase: "index", result: $index_result })

        # Phase 7: Convert to additional formats
        let conversion_result = convert_documentation_formats $docs_config $generation_results

        let generation_results = ($generation_results | append { phase: "conversion", result: $conversion_result })

        let summary = {
            source_root: $docs_config.source_root
            output_directory: $docs_config.output_dir
            doc_types: ($docs_config.doc_types | length)
            formats: ($docs_config.formats | length)
            successful_phases: ($generation_results | where {|r| $r.result.status == "success"} | length)
            total_phases: ($generation_results | length)
            documents_generated: (count_generated_documents $generation_results)
            total_size: (get_directory_size $docs_config.output_dir)
            docs_config: $docs_config
            phases: $generation_results
        }

        log info $"Documentation generation completed - ($summary.documents_generated) documents generated"

        return $summary

    } catch {|err|
        log error $"Documentation generation failed: ($err.msg)"
        exit 1
    }
}

# Discover documentation sources in the project
def discover_documentation_sources [docs_config: record] -> record {
    log info "Discovering documentation sources..."

    let start_time = (date now)

    try {
        # Find existing documentation files
        let existing_docs = find_existing_documentation $docs_config.source_root

        # Analyze project structure for automatic documentation generation
        let project_structure = analyze_project_structure $docs_config.source_root

        # Discover configuration examples
        let config_examples = find_configuration_examples $docs_config.source_root

        # Find API endpoints for documentation
        let api_endpoints = if $docs_config.generate_api {
            discover_api_endpoints $docs_config.source_root
        } else {
            []
        }

        {
            status: "success"
            existing_docs: $existing_docs
            project_structure: $project_structure
            config_examples: $config_examples
            api_endpoints: $api_endpoints
            duration: ((date now) - $start_time)
        }

    } catch {|err|
        {
            status: "failed"
            reason: $err.msg
            duration: ((date now) - $start_time)
        }
    }
}

# Find existing documentation files
def find_existing_documentation [repo_root: string] -> record {
    let doc_patterns = ["README.md", "*.md", "*.rst", "docs/*", "doc/*"]
    let mut found_docs = []

    for pattern in $doc_patterns {
        let matching_files = try {
            find $repo_root -name $pattern -type f | head -50
        } catch {
            []
        }

        $found_docs = ($found_docs | append $matching_files)
    }

    let categorized_docs = $found_docs | each {|doc|
        {
            path: $doc
            name: ($doc | path basename)
            category: (categorize_document $doc)
            size: (ls $doc | get 0.size)
        }
    }

    {
        total_docs: ($found_docs | length)
        readme_files: ($categorized_docs | where category == "readme")
        user_docs: ($categorized_docs | where category == "user")
        dev_docs: ($categorized_docs | where category == "dev")
        api_docs: ($categorized_docs | where category == "api")
        other_docs: ($categorized_docs | where category == "other")
        all_docs: $categorized_docs
    }
}

# Categorize document based on filename and location
def categorize_document [doc_path: string] -> string {
    let name = ($doc_path | path basename | str downcase)
    let path = ($doc_path | str downcase)

    if ($name == "readme.md") or ($name | str starts-with "readme") {
        return "readme"
    }

    if ($name | str contains "install") or ($name | str contains "setup") or ($name | str contains "getting") {
        return "user"
    }

    if ($name | str contains "api") or ($path | str contains "/api/") {
        return "api"
    }

    if ($name | str contains "dev") or ($name | str contains "contrib") or ($path | str contains "/dev/") {
        return "dev"
    }

    if ($name | str contains "config") or ($name | str contains "reference") {
        return "admin"
    }

    return "other"
}

# Analyze project structure for documentation generation
def analyze_project_structure [repo_root: string] -> record {
    # Find major components
    let components = [
        { name: "orchestrator", path: ($repo_root | path join "orchestrator") }
        { name: "control-center", path: ($repo_root | path join "control-center") }
        { name: "provisioning", path: ($repo_root | path join "provisioning") }
        { name: "platform", path: ($repo_root | path join "platform") }
        { name: "core", path: ($repo_root | path join "core") }
    ]

    let existing_components = ($components | where {|comp| ($comp.path | path exists) })

    # Analyze Nushell modules for documentation
    let nu_modules = try {
        find $repo_root -name "*.nu" -type f | head -100
    } catch {
        []
    }

    # Find configuration files
    let config_files = try {
        find $repo_root -name "*.toml" -o -name "*.yaml" -o -name "*.json" | head -50
    } catch {
        []
    }

    {
        components: $existing_components
        nu_modules: ($nu_modules | length)
        config_files: ($config_files | length)
        has_rust_projects: (($repo_root | path join "Cargo.toml") | path exists)
        has_docker: (($repo_root | path join "Dockerfile") | path exists)
    }
}

# Find configuration examples
def find_configuration_examples [repo_root: string] -> list {
    let example_patterns = ["*.example", "*.template", "examples/*", "config/*"]
    let mut examples = []

    for pattern in $example_patterns {
        let matching_files = try {
            find $repo_root -name $pattern -type f | head -20
        } catch {
            []
        }

        $examples = ($examples | append $matching_files)
    }

    return ($examples | each {|ex|
        {
            path: $ex
            name: ($ex | path basename)
            type: (get_config_type $ex)
        }
    })
}

# Get configuration file type
def get_config_type [config_path: string] -> string {
    let ext = ($config_path | path extension)
    match $ext {
        "toml" => "toml"
        "yaml" | "yml" => "yaml"
        "json" => "json"
        "env" => "environment"
        _ => "unknown"
    }
}

# Discover API endpoints for documentation
def discover_api_endpoints [repo_root: string] -> list {
    # This would analyze Rust source files to find API routes
    # For now, we'll return a placeholder structure

    [
        { path: "/health", method: "GET", description: "Health check endpoint" }
        { path: "/version", method: "GET", description: "System version information" }
        { path: "/workflows", method: "GET", description: "List workflows" }
        { path: "/workflows", method: "POST", description: "Create new workflow" }
        { path: "/workflows/{id}", method: "GET", description: "Get workflow details" }
        { path: "/workflows/{id}", method: "DELETE", description: "Delete workflow" }
    ]
}

# Generate user documentation
def generate_user_documentation [
    docs_config: record
    discovery_result: record
] -> record {
    log info "Generating user documentation..."

    let start_time = (date now)

    try {
        let user_docs_dir = ($docs_config.output_dir | path join "user")
        mkdir $user_docs_dir

        let mut generated_docs = []

        # Generate getting started guide
        let getting_started = generate_getting_started_guide $docs_config $discovery_result

        $getting_started | save ($user_docs_dir | path join "getting-started.md")
        $generated_docs = ($generated_docs | append "getting-started.md")

        # Generate installation guide
        let installation_guide = generate_installation_guide $docs_config $discovery_result

        $installation_guide | save ($user_docs_dir | path join "installation.md")
        $generated_docs = ($generated_docs | append "installation.md")

        # Generate CLI reference
        let cli_reference = generate_cli_reference $docs_config $discovery_result

        $cli_reference | save ($user_docs_dir | path join "cli-reference.md")
        $generated_docs = ($generated_docs | append "cli-reference.md")

        # Generate troubleshooting guide
        let troubleshooting = generate_troubleshooting_guide $docs_config $discovery_result

        $troubleshooting | save ($user_docs_dir | path join "troubleshooting.md")
        $generated_docs = ($generated_docs | append "troubleshooting.md")

        # Generate FAQ
        let faq = generate_faq $docs_config $discovery_result

        $faq | save ($user_docs_dir | path join "faq.md")
        $generated_docs = ($generated_docs | append "faq.md")

        {
            status: "success"
            docs_generated: ($generated_docs | length)
            generated_docs: $generated_docs
            user_docs_dir: $user_docs_dir
            duration: ((date now) - $start_time)
        }

    } catch {|err|
        {
            status: "failed"
            reason: $err.msg
            duration: ((date now) - $start_time)
        }
    }
}

# Generate getting started guide
def generate_getting_started_guide [docs_config: record, discovery_result: record] -> string {
    $"# Getting Started with Provisioning System

Welcome to the Provisioning System! This guide will help you get up and running quickly.

## What is the Provisioning System?

The Provisioning System is a cloud-native infrastructure provisioning and management platform that helps you:

- Provision and manage cloud infrastructure across multiple providers
- Deploy and orchestrate containerized applications
- Manage configuration and secrets
- Monitor and observe your infrastructure

## Quick Start

### 1. Installation

Choose your preferred installation method:

#### Using the installer script (Recommended)
```bash
# Linux/macOS
sudo ./install.sh

# Windows (as Administrator)
install.bat
```

#### Manual installation
See the [Installation Guide](installation.md) for detailed instructions.

### 2. Verify Installation

```bash
# Check version
provisioning version

# Check environment
provisioning env

# Get help
provisioning help
```

### 3. Basic Configuration

Create your user configuration:
```bash
cp config/config.user.toml.template config/config.user.toml
# Edit config/config.user.toml with your preferences
```

### 4. Your First Workflow

Create a simple server:
```bash
# List available commands
provisioning help

# Create a server (dry-run first)
provisioning servers create --check

# Actually create the server
provisioning servers create
```

## Key Concepts

### Workflows
Workflows are automated sequences of infrastructure operations. They can be:
- **Server workflows**: Provision and configure servers
- **Application workflows**: Deploy applications and services
- **Maintenance workflows**: Updates, backups, and monitoring

### Providers
The system supports multiple cloud providers:
- **AWS**: Amazon Web Services
- **UpCloud**: European cloud provider
- **Local**: Local development and testing

### Configuration
Configuration is hierarchical and environment-aware:
- **System defaults**: Built-in sensible defaults
- **User config**: Personal preferences and credentials
- **Project config**: Project-specific settings
- **Environment config**: Environment-specific overrides

## Next Steps

1. Read the [CLI Reference](cli-reference.md) for detailed command information
2. See the [Configuration Guide](../admin/configuration.md) for advanced configuration
3. Check out the [Examples](../examples/) directory for sample configurations
4. Join our community for support and discussions

## Getting Help

- **Documentation**: Browse this documentation for comprehensive guides
- **CLI Help**: Use `provisioning help <command>` for specific command help
- **Troubleshooting**: See the [Troubleshooting Guide](troubleshooting.md)
- **FAQ**: Check the [Frequently Asked Questions](faq.md)

Happy provisioning! 🚀
"
}

# Generate installation guide
def generate_installation_guide [docs_config: record, discovery_result: record] -> string {
    $"# Installation Guide

This guide covers all installation methods for the Provisioning System.

## System Requirements

### Minimum Requirements
- **Operating System**: Linux (Ubuntu 20.04+, CentOS 8+), macOS (10.15+), or Windows 10+
- **Memory**: 2GB RAM (4GB recommended)
- **Storage**: 1GB free disk space
- **Network**: Internet connectivity for package downloads

### Dependencies
- **Nushell**: 0.107.1 or later (installed automatically)
- **Git**: For source installations and updates
- **Docker**: Optional, for containerized deployments

## Installation Methods

### 1. Automated Installer (Recommended)

The automated installer handles all dependencies and configuration:

#### Linux/macOS
```bash
# Download and extract the distribution
tar -xzf provisioning-*-linux-complete.tar.gz
cd provisioning-*-linux-complete

# Run the installer
sudo ./install.sh

# Verify installation
provisioning version
```

#### Windows
```cmd
# Extract the distribution
# Run the installer as Administrator
install.bat

# Verify installation
provisioning version
```

### 2. Package Manager Installation

#### Homebrew (macOS)
```bash
brew tap your-org/provisioning
brew install provisioning
```

#### APT (Debian/Ubuntu)
```bash
# Add repository
curl -fsSL https://apt.your-org.com/gpg | sudo apt-key add -
echo \"deb https://apt.your-org.com/ubuntu stable main\" | sudo tee /etc/apt/sources.list.d/provisioning.list

# Install
sudo apt update
sudo apt install provisioning
```

#### YUM/DNF (RHEL/CentOS/Fedora)
```bash
# Add repository
sudo yum-config-manager --add-repo https://yum.your-org.com/provisioning.repo

# Install
sudo yum install provisioning
```

### 3. Container Installation

#### Docker
```bash
# Run the orchestrator
docker run -d --name provisioning-orchestrator \\
  -p 8080:8080 \\
  -v provisioning-data:/data \\
  provisioning/orchestrator:latest

# Run the control center
docker run -d --name provisioning-control-center \\
  -p 9080:9080 \\
  provisioning/control-center:latest
```

#### Docker Compose
```bash
# Use the provided docker-compose.yml
docker-compose up -d
```

### 4. Source Installation

For development or customization:

```bash
# Clone the repository
git clone https://github.com/your-org/provisioning.git
cd provisioning

# Build the system
./tools/distribution/generate-distribution.nu

# Install from built distribution
cd dist
sudo ./install.sh
```

## Post-Installation Configuration

### 1. Environment Setup

The installer automatically configures:
- System PATH updates
- Environment variables
- Shell integration

Restart your shell or run:
```bash
source /etc/profile.d/provisioning.sh  # Linux/macOS
```

### 2. User Configuration

Create your personal configuration:
```bash
# Copy the template
cp /etc/provisioning/config.user.toml.template ~/.config/provisioning/config.user.toml

# Edit with your preferences
$EDITOR ~/.config/provisioning/config.user.toml
```

### 3. Service Configuration (Optional)

Enable system services for automatic startup:
```bash
# Enable orchestrator service
sudo systemctl enable provisioning-orchestrator
sudo systemctl start provisioning-orchestrator

# Check service status
sudo systemctl status provisioning-orchestrator
```

## Verification

Verify your installation:

```bash
# Check version and build info
provisioning version

# Check configuration
provisioning env

# Test basic functionality
provisioning help

# Verify orchestrator connection (if running)
provisioning workflows list
```

## Troubleshooting

### Common Issues

#### Permission Denied
```bash
# Fix binary permissions
sudo chmod +x /usr/local/bin/provisioning*
```

#### Command Not Found
```bash
# Check PATH
echo $PATH

# Add to PATH if needed
export PATH=\"/usr/local/bin:$PATH\"
```

#### Configuration Errors
```bash
# Validate configuration
provisioning validate config

# Check environment variables
provisioning allenv
```

### Getting Help

If you encounter issues:
1. Check the [Troubleshooting Guide](troubleshooting.md)
2. Review system logs: `journalctl -u provisioning-*`
3. Validate configuration: `provisioning validate config`
4. Ask for help in our community channels

## Uninstallation

To remove the Provisioning System:

### Using the Uninstaller
```bash
# Linux/macOS
sudo ./uninstall.sh

# Windows (as Administrator)
uninstall.bat
```

### Manual Removal
```bash
# Remove binaries
sudo rm -f /usr/local/bin/provisioning*

# Remove libraries
sudo rm -rf /usr/local/lib/provisioning

# Remove configuration
sudo rm -rf /etc/provisioning

# Remove data (optional)
sudo rm -rf /var/lib/provisioning
sudo rm -rf /var/log/provisioning
```

## Next Steps

After successful installation:
1. Follow the [Getting Started Guide](getting-started.md)
2. Review the [CLI Reference](cli-reference.md)
3. Explore [Configuration Options](../admin/configuration.md)
"
}

# Generate CLI reference
def generate_cli_reference [docs_config: record, discovery_result: record] -> string {
    $"# CLI Reference

Complete reference for the Provisioning System command-line interface.

## Overview

The `provisioning` command is the main entry point for all system operations. It provides a consistent interface across all platforms and environments.

## Global Options

These options are available for all commands:

- `--help, -h`: Show help information
- `--version, -V`: Show version information
- `--verbose, -v`: Enable verbose output
- `--debug, -x`: Enable debug mode
- `--config, -c <file>`: Use specific configuration file
- `--env <env>`: Use specific environment (dev/test/prod)

## Core Commands

### help
Show help information for commands.

```bash
provisioning help [COMMAND]
```

Examples:
```bash
provisioning help                # Show main help
provisioning help servers        # Show servers command help
provisioning help servers create # Show servers create help
```

### version
Display version and build information.

```bash
provisioning version [OPTIONS]
```

Options:
- `--json`: Output in JSON format
- `--short`: Show only version number

Examples:
```bash
provisioning version          # Show full version info
provisioning version --short  # Show version number only
provisioning version --json   # JSON output for scripts
```

### env
Display environment and configuration information.

```bash
provisioning env [OPTIONS]
```

Options:
- `--all`: Show all environment variables
- `--config`: Show configuration sources
- `--paths`: Show file paths

Examples:
```bash
provisioning env              # Show basic environment
provisioning env --all        # Show all variables
provisioning env --config     # Show config sources
```

## Server Management

### servers create
Create new servers.

```bash
provisioning servers create [OPTIONS]
```

Options:
- `--check, -c`: Dry run mode (no actual changes)
- `--infra <name>`: Target infrastructure
- `--count <n>`: Number of servers to create
- `--wait, -w`: Wait for completion

Examples:
```bash
provisioning servers create --check    # Dry run
provisioning servers create            # Create with defaults
provisioning servers create --count 3  # Create 3 servers
```

### servers list
List existing servers.

```bash
provisioning servers list [OPTIONS]
```

Options:
- `--infra <name>`: Filter by infrastructure
- `--status <status>`: Filter by status
- `--json`: JSON output

Examples:
```bash
provisioning servers list                    # List all servers
provisioning servers list --infra production # Production servers only
provisioning servers list --status running   # Running servers only
```

### servers delete
Delete servers.

```bash
provisioning servers delete [OPTIONS] [SERVER_NAME]
```

Options:
- `--check, -c`: Dry run mode
- `--force, -f`: Skip confirmation
- `--all`: Delete all servers

Examples:
```bash
provisioning servers delete web-01     # Delete specific server
provisioning servers delete --all --check # Dry run delete all
```

### servers ssh
SSH into a server.

```bash
provisioning servers ssh <SERVER_NAME> [OPTIONS]
```

Options:
- `--user <user>`: SSH username
- `--key <keyfile>`: SSH private key
- `--port <port>`: SSH port

Examples:
```bash
provisioning servers ssh web-01           # SSH with defaults
provisioning servers ssh web-01 --user admin # Specific user
```

## Workflow Management

### workflows list
List workflows.

```bash
provisioning workflows list [OPTIONS]
```

Options:
- `--status <status>`: Filter by status (pending/running/completed/failed)
- `--type <type>`: Filter by workflow type
- `--limit <n>`: Limit results

### workflows create
Create a new workflow.

```bash
provisioning workflows create <TYPE> [OPTIONS]
```

Types:
- `server`: Server provisioning workflow
- `taskserv`: Task service deployment workflow
- `cluster`: Cluster deployment workflow

### workflows status
Get workflow status.

```bash
provisioning workflows status <WORKFLOW_ID>
```

### workflows cancel
Cancel a running workflow.

```bash
provisioning workflows cancel <WORKFLOW_ID> [OPTIONS]
```

## Task Services

### taskserv create
Install a task service.

```bash
provisioning taskserv create <SERVICE> [OPTIONS]
```

Services:
- `kubernetes`: Kubernetes orchestrator
- `cilium`: Network CNI
- `containerd`: Container runtime
- `postgres`: PostgreSQL database

Options:
- `--check, -c`: Dry run mode
- `--infra <name>`: Target infrastructure
- `--config <file>`: Service configuration

Examples:
```bash
provisioning taskserv create kubernetes --check
provisioning taskserv create postgres --config db-config.toml
```

### taskserv list
List available and installed task services.

```bash
provisioning taskserv list [OPTIONS]
```

Options:
- `--available`: Show available services
- `--installed`: Show installed services only
- `--updates`: Check for updates

### taskserv delete
Remove a task service.

```bash
provisioning taskserv delete <SERVICE> [OPTIONS]
```

### taskserv check-updates
Check for service updates.

```bash
provisioning taskserv check-updates [SERVICE]
```

## Cluster Operations

### cluster create
Create a Kubernetes cluster.

```bash
provisioning cluster create <CLUSTER_TYPE> [OPTIONS]
```

Cluster Types:
- `buildkit`: Build cluster
- `web`: Web services cluster
- `data`: Data processing cluster

### cluster delete
Delete a cluster.

```bash
provisioning cluster delete <CLUSTER_NAME> [OPTIONS]
```

### cluster list
List clusters.

```bash
provisioning cluster list [OPTIONS]
```

## Configuration

### validate config
Validate configuration files.

```bash
provisioning validate config [OPTIONS]
```

Options:
- `--file <file>`: Validate specific file
- `--env <env>`: Validate environment config

### show
Show configuration details.

```bash
provisioning show <TYPE> [OPTIONS]
```

Types:
- `settings`: System settings
- `servers`: Server configurations
- `providers`: Provider configurations

## Examples and Workflows

### Complete Server Setup
```bash
# 1. Check current environment
provisioning env

# 2. Create servers (dry run first)
provisioning servers create --check

# 3. Create servers
provisioning servers create --wait

# 4. Install Kubernetes
provisioning taskserv create kubernetes --check
provisioning taskserv create kubernetes

# 5. Deploy a cluster
provisioning cluster create web --check
provisioning cluster create web
```

### Development Workflow
```bash
# Use development environment
export PROVISIONING_ENV=dev

# Create development infrastructure
provisioning generate infra --new dev-project
provisioning servers create --infra dev-project --count 1

# Install development services
provisioning taskserv create containerd
provisioning taskserv create postgres
```

### Production Deployment
```bash
# Use production environment
export PROVISIONING_ENV=prod

# Create production servers
provisioning servers create --infra production --count 3 --wait

# Install production services
provisioning taskserv create kubernetes
provisioning taskserv create cilium
provisioning cluster create web
```

## Exit Codes

The CLI uses standard exit codes:
- `0`: Success
- `1`: General errors
- `2`: Misuse of shell command
- `126`: Command invoked cannot execute
- `127`: Command not found
- `130`: Script terminated by Control-C

## Environment Variables

Key environment variables that affect CLI behavior:

- `PROVISIONING_HOME`: Installation directory
- `PROVISIONING_CONFIG`: Configuration file path
- `PROVISIONING_ENV`: Environment name (dev/test/prod)
- `PROVISIONING_DEBUG`: Enable debug output
- `PROVISIONING_LOG_LEVEL`: Log level (error/warn/info/debug)

## Shell Integration

### Bash Completion
```bash
# Add to ~/.bashrc
eval \"$(provisioning completion bash)\"
```

### Zsh Completion
```bash
# Add to ~/.zshrc
eval \"$(provisioning completion zsh)\"
```

### Fish Completion
```bash
# Add to ~/.config/fish/config.fish
provisioning completion fish | source
```

For more detailed information about specific commands, use:
```bash
provisioning help <command>
```
"
}

# Generate troubleshooting guide
def generate_troubleshooting_guide [docs_config: record, discovery_result: record] -> string {
    $"# Troubleshooting Guide

This guide helps you diagnose and resolve common issues with the Provisioning System.

## General Troubleshooting Steps

1. **Check system status**: `provisioning env`
2. **Validate configuration**: `provisioning validate config`
3. **Review logs**: Check system logs for errors
4. **Verify permissions**: Ensure proper file and directory permissions
5. **Update system**: Make sure you're running the latest version

## Common Issues

### Installation Issues

#### \"Command not found: provisioning\"
**Symptoms**: Shell cannot find the provisioning command

**Causes**:
- Installation incomplete
- PATH not updated
- Binary permissions incorrect

**Solutions**:
```bash
# Check if binary exists
ls -la /usr/local/bin/provisioning*

# Check PATH
echo $PATH | grep \"/usr/local/bin\"

# Fix PATH (add to shell profile)
echo 'export PATH=\"/usr/local/bin:$PATH\"' >> ~/.bashrc
source ~/.bashrc

# Fix permissions
sudo chmod +x /usr/local/bin/provisioning*
```

#### \"Permission denied\" errors
**Symptoms**: Cannot execute commands or access files

**Solutions**:
```bash
# Fix binary permissions
sudo chmod +x /usr/local/bin/provisioning*

# Fix directory permissions
sudo chown -R $(whoami):$(whoami) ~/.config/provisioning
sudo chmod -R 755 ~/.config/provisioning

# Check service user permissions
sudo usermod -a -G provisioning $(whoami)
```

### Configuration Issues

#### \"Configuration file not found\"
**Symptoms**: System cannot load configuration files

**Solutions**:
```bash
# Check configuration paths
provisioning env --config

# Create missing user config
cp /etc/provisioning/config.user.toml.template ~/.config/provisioning/config.user.toml

# Validate configuration
provisioning validate config
```

#### \"Invalid configuration\" errors
**Symptoms**: Configuration parsing fails

**Solutions**:
```bash
# Check TOML syntax
# Use a TOML validator or editor with syntax checking

# Reset to defaults
cp /etc/provisioning/config.defaults.toml /etc/provisioning/config.user.toml

# Check for encoding issues (ensure UTF-8)
file ~/.config/provisioning/config.user.toml
```

### Network and Connectivity Issues

#### Cannot connect to services
**Symptoms**: API calls fail, services unreachable

**Solutions**:
```bash
# Check service status
sudo systemctl status provisioning-orchestrator
sudo systemctl status provisioning-control-center

# Check ports
netstat -tlnp | grep 8080
curl -f http://localhost:8080/health

# Check firewall
sudo ufw status
sudo firewall-cmd --list-ports

# Restart services
sudo systemctl restart provisioning-orchestrator
```

#### Provider authentication failures
**Symptoms**: Cloud provider operations fail with auth errors

**Solutions**:
```bash
# Check provider credentials
provisioning validate config --provider aws

# Update credentials in config
$EDITOR ~/.config/provisioning/config.user.toml

# Check credential file permissions (should not be world-readable)
chmod 600 ~/.config/provisioning/config.user.toml
```

### Workflow and Operation Issues

#### Workflows stuck in \"pending\" state
**Symptoms**: Workflows don't progress from pending

**Solutions**:
```bash
# Check orchestrator status
provisioning workflows orchestrator

# Check orchestrator logs
sudo journalctl -u provisioning-orchestrator -f

# Restart orchestrator
sudo systemctl restart provisioning-orchestrator

# Check for resource locks
provisioning workflows list --status pending
```

#### \"Resource already exists\" errors
**Symptoms**: Operations fail due to existing resources

**Solutions**:
```bash
# List existing resources
provisioning servers list
provisioning cluster list

# Use different names or clean up existing resources
provisioning servers delete old-server-name

# Use --force flag to override (use with caution)
provisioning servers create --force
```

### Performance Issues

#### Slow command execution
**Symptoms**: Commands take unusually long to complete

**Solutions**:
```bash
# Enable debug mode to see what's happening
provisioning --debug servers list

# Check system resources
top
df -h

# Clear caches
rm -rf ~/.cache/provisioning/*

# Check for large log files
find /var/log/provisioning -name \"*.log\" -size +100M
```

#### High memory usage
**Symptoms**: System using excessive memory

**Solutions**:
```bash
# Check memory usage
free -h
ps aux | grep provisioning

# Restart services to free memory
sudo systemctl restart provisioning-orchestrator

# Check for memory leaks in logs
sudo journalctl -u provisioning-orchestrator | grep -i memory
```

## Advanced Troubleshooting

### Debug Mode
Enable comprehensive debugging:
```bash
export PROVISIONING_DEBUG=true
export PROVISIONING_LOG_LEVEL=debug
provisioning --debug <command>
```

### Log Analysis
Key log locations:
- System logs: `/var/log/provisioning/`
- Service logs: `sudo journalctl -u provisioning-*`
- User logs: `~/.local/share/provisioning/logs/`

Common log patterns to look for:
```bash
# Error patterns
grep -i \"error\\|exception\\|failed\" /var/log/provisioning/*.log

# Connection issues
grep -i \"connection\\|timeout\\|refused\" /var/log/provisioning/*.log

# Permission issues
grep -i \"permission\\|denied\\|unauthorized\" /var/log/provisioning/*.log
```

### Configuration Debugging
```bash
# Show all configuration sources
provisioning env --all

# Show computed configuration
provisioning show settings

# Test configuration loading
provisioning validate config --verbose
```

### Network Debugging
```bash
# Test local services
curl -v http://localhost:8080/health
curl -v http://localhost:9080/health

# Test external connectivity
curl -v https://api.upcloud.com/
curl -v https://ec2.amazonaws.com/

# Check DNS resolution
nslookup api.upcloud.com
```

## Getting Help

### Before Asking for Help
1. Check this troubleshooting guide
2. Search existing issues on GitHub
3. Review recent changes to your configuration
4. Gather relevant log output

### Information to Include
When reporting issues, include:
```bash
# System information
provisioning version
uname -a
cat /etc/os-release

# Environment
provisioning env

# Configuration (remove sensitive data)
provisioning show settings

# Recent logs
sudo journalctl -u provisioning-* --since \"1 hour ago\"

# Error messages (exact text)
```

### Support Channels
- **GitHub Issues**: Report bugs and feature requests
- **Documentation**: Check online documentation for updates
- **Community**: Join community discussions and forums

### Emergency Recovery

#### Complete System Reset
If the system is completely broken:
```bash
# Stop all services
sudo systemctl stop provisioning-*

# Backup configuration
cp -r /etc/provisioning /tmp/provisioning-backup

# Reinstall system
sudo ./uninstall.sh
sudo ./install.sh

# Restore configuration
sudo cp -r /tmp/provisioning-backup/* /etc/provisioning/
```

#### Factory Reset
To start completely fresh:
```bash
# Uninstall completely
sudo ./uninstall.sh

# Remove all data
sudo rm -rf /var/lib/provisioning
sudo rm -rf /var/log/provisioning
sudo rm -rf ~/.config/provisioning
sudo rm -rf ~/.cache/provisioning

# Reinstall
sudo ./install.sh
```

Remember: Always backup your configuration and data before performing major troubleshooting steps!
"
}

# Generate FAQ
def generate_faq [docs_config: record, discovery_result: record] -> string {
    $"# Frequently Asked Questions (FAQ)

## General Questions

### What is the Provisioning System?
The Provisioning System is a cloud-native infrastructure provisioning and management platform that helps you automate the deployment and management of infrastructure across multiple cloud providers.

### Which cloud providers are supported?
Currently supported providers:
- **AWS** (Amazon Web Services)
- **UpCloud** (European cloud provider)
- **Local** (for development and testing)

Additional providers can be added through the plugin system.

### What operating systems are supported?
- **Linux**: Ubuntu 20.04+, CentOS 8+, Debian 11+
- **macOS**: 10.15+ (Catalina and newer)
- **Windows**: Windows 10+, Windows Server 2019+

### Is it open source?
Yes, the Provisioning System is open source. Check the LICENSE file in the repository for specific licensing terms.

## Installation and Setup

### How do I install the system?
The easiest way is using the automated installer:
```bash
# Linux/macOS
sudo ./install.sh

# Windows (as Administrator)
install.bat
```

See the [Installation Guide](installation.md) for other methods.

### Do I need root/administrator privileges?
Yes, for system installation. The installer needs to:
- Copy files to system directories
- Create system users and groups
- Install and configure services
- Set up system PATH and environment

### Can I install without root privileges?
Yes, you can do a user-local installation, but some features may be limited:
```bash
# User installation
./install.sh --user-install --no-services
```

### Where are configuration files stored?
Configuration files are stored in multiple locations:
- **System config**: `/etc/provisioning/` (Linux/macOS), `C:\\ProgramData\\Provisioning\\` (Windows)
- **User config**: `~/.config/provisioning/`
- **Runtime config**: `/var/lib/provisioning/`

## Usage and Operations

### How do I get started after installation?
1. Verify installation: `provisioning version`
2. Check environment: `provisioning env`
3. Create user config: Copy and edit the template from system config
4. Follow the [Getting Started Guide](getting-started.md)

### Can I use multiple cloud providers simultaneously?
Yes! The system supports multi-cloud deployments. You can provision resources across different providers in the same workflow.

### How do I manage secrets and credentials?
The system supports multiple credential management methods:
- Configuration files (encrypted with SOPS/Age)
- Environment variables
- External secret managers (HashiCorp Vault, AWS Secrets Manager)
- Cloud provider credential chains

### Can I run this in containers?
Yes, the system provides Docker containers for all services:
```bash
docker run -d provisioning/orchestrator:latest
docker run -d provisioning/control-center:latest
```

Use the provided `docker-compose.yml` for easy container deployment.

## Configuration and Customization

### How do I configure different environments (dev/test/prod)?
Use environment-specific configuration files:
```bash
# Set environment
export PROVISIONING_ENV=prod

# Use environment-specific config
cp config.prod.toml.template config.prod.toml
# Edit config.prod.toml
```

### Can I customize the installation paths?
Yes, but it requires manual installation. The automated installer uses standard paths for better system integration.

### How do I add custom providers or services?
The system supports extensions through:
- Custom Nushell modules
- Plugin architecture
- Provider templates

See the developer documentation for details.

### Can I integrate with existing CI/CD pipelines?
Yes, the system is designed for CI/CD integration:
- Command-line interface for all operations
- JSON output for scripting
- Return codes for success/failure detection
- Webhook support for notifications

## Troubleshooting

### The `provisioning` command is not found
**Solution**: Check your PATH and permissions:
```bash
# Check PATH
echo $PATH | grep /usr/local/bin

# Check binary
ls -la /usr/local/bin/provisioning*

# Fix PATH
export PATH=\"/usr/local/bin:$PATH\"
```

### Configuration validation fails
**Solution**: Check TOML syntax and file permissions:
```bash
# Validate configuration
provisioning validate config

# Check file permissions
ls -la ~/.config/provisioning/
```

### Services won't start
**Solution**: Check service status and logs:
```bash
sudo systemctl status provisioning-orchestrator
sudo journalctl -u provisioning-orchestrator -f
```

### Operations are slow
**Solution**:
- Check system resources (CPU, memory, disk)
- Enable debug mode: `provisioning --debug <command>`
- Clear caches: `rm -rf ~/.cache/provisioning/*`

See the [Troubleshooting Guide](troubleshooting.md) for more detailed solutions.

## Development and Contributing

### How can I contribute to the project?
We welcome contributions! See the `CONTRIBUTING.md` file for guidelines on:
- Bug reports
- Feature requests
- Code contributions
- Documentation improvements

### How do I build from source?
```bash
git clone <repository-url>
cd provisioning
./tools/distribution/generate-distribution.nu
```

### Can I create custom modules?
Yes! The system supports custom Nushell modules. Place them in:
- System modules: `/usr/local/lib/provisioning/extensions/`
- User modules: `~/.config/provisioning/modules/`

### How do I debug issues during development?
```bash
# Enable debug mode
export PROVISIONING_DEBUG=true
export PROVISIONING_LOG_LEVEL=debug

# Run with debug output
provisioning --debug <command>

# Check development logs
tail -f ~/.local/share/provisioning/logs/debug.log
```

## Performance and Scaling

### How many servers can I manage?
The system is designed to scale horizontally. Limits depend on:
- Available system resources
- Cloud provider API limits
- Network bandwidth and latency

Typical deployments handle hundreds to thousands of servers.

### Can I run multiple orchestrators?
Yes, for high availability and load distribution:
```bash
# Configure multiple orchestrators with load balancing
# See the HA deployment documentation
```

### How do I monitor system performance?
The system provides built-in monitoring:
```bash
# Check system health
provisioning workflows orchestrator

# Monitor workflows
provisioning workflows list --status running

# View performance metrics
provisioning show stats
```

## Security

### How are credentials stored?
Credentials are stored securely:
- Configuration files encrypted with SOPS/Age
- Environment variables (for temporary use)
- Integration with cloud provider credential chains
- Support for external secret managers

### Can I audit system operations?
Yes, all operations are logged:
- System logs: `/var/log/provisioning/`
- Audit trail: All API calls and workflows are logged
- User actions: Command history and results

### Is network traffic encrypted?
Yes:
- All API communications use HTTPS/TLS
- Cloud provider communications use provider security standards
- Internal service communication can be configured with TLS

### How do I secure a multi-user deployment?
- Use separate user configurations
- Implement RBAC through cloud provider IAM
- Use dedicated service accounts
- Enable audit logging
- Regular security updates

## Support and Community

### Where can I get help?
- **Documentation**: This documentation and online resources
- **GitHub Issues**: Bug reports and feature requests
- **Community Forums**: Discussion and support
- **Professional Support**: Available for enterprise users

### How do I report bugs?
1. Check existing issues on GitHub
2. Create a new issue with:
   - System information (`provisioning version`)
   - Steps to reproduce
   - Expected vs actual behavior
   - Relevant log output

### How often is the system updated?
- **Major releases**: Every 3-6 months
- **Minor releases**: Monthly
- **Security patches**: As needed
- **Development builds**: Continuously

### Can I get commercial support?
Yes, commercial support options are available for enterprise deployments. Contact us for details about:
- Professional services
- Custom development
- Training and consultation
- SLA-backed support

---

## Still have questions?

If your question isn't answered here:
1. Check the full documentation
2. Search existing GitHub issues
3. Create a new issue or discussion
4. Join our community channels

We're here to help! 🚀
"
}

# Generate admin documentation (placeholder)
def generate_admin_documentation [docs_config: record, discovery_result: record] -> record {
    log info "Generating admin documentation..."

    let start_time = (date now)

    # Placeholder for admin docs
    log warning "Admin documentation generation not fully implemented"

    {
        status: "skipped"
        reason: "admin documentation not fully implemented"
        docs_generated: 0
        duration: ((date now) - $start_time)
    }
}

# Generate developer documentation (placeholder)
def generate_developer_documentation [docs_config: record, discovery_result: record] -> record {
    log info "Generating developer documentation..."

    let start_time = (date now)

    # Placeholder for dev docs
    log warning "Developer documentation generation not fully implemented"

    {
        status: "skipped"
        reason: "developer documentation not fully implemented"
        docs_generated: 0
        duration: ((date now) - $start_time)
    }
}

# Generate API documentation (placeholder)
def generate_api_documentation [docs_config: record, discovery_result: record] -> record {
    log info "Generating API documentation..."

    let start_time = (date now)

    # Placeholder for API docs
    log warning "API documentation generation not fully implemented"

    {
        status: "skipped"
        reason: "API documentation not fully implemented"
        docs_generated: 0
        duration: ((date now) - $start_time)
    }
}

# Create documentation index
def create_documentation_index [docs_config: record, generation_results: list] -> record {
    log info "Creating documentation index..."

    let start_time = (date now)

    try {
        let index_content = $"# Documentation Index

Welcome to the Provisioning System documentation!

## User Documentation
- [Getting Started Guide](user/getting-started.md) - Quick start guide for new users
- [Installation Guide](user/installation.md) - Complete installation instructions
- [CLI Reference](user/cli-reference.md) - Comprehensive command reference
- [Troubleshooting Guide](user/troubleshooting.md) - Common issues and solutions
- [FAQ](user/faq.md) - Frequently asked questions

## Administrator Documentation
- Configuration Guide - Advanced configuration options
- Security Guide - Security best practices and configuration
- Monitoring Guide - System monitoring and observability
- Backup and Recovery - Data protection strategies

## Developer Documentation
- Architecture Overview - System architecture and design
- API Reference - REST API documentation
- Plugin Development - Creating custom plugins and extensions
- Contributing Guide - How to contribute to the project

## Generated Documentation
This documentation was generated automatically on (date now | format date '%Y-%m-%d %H:%M:%S').

For the most up-to-date information, visit the online documentation.
"

        $index_content | save ($docs_config.output_dir | path join "README.md")

        {
            status: "success"
            index_file: ($docs_config.output_dir | path join "README.md")
            duration: ((date now) - $start_time)
        }

    } catch {|err|
        {
            status: "failed"
            reason: $err.msg
            duration: ((date now) - $start_time)
        }
    }
}

# Convert documentation to additional formats (placeholder)
def convert_documentation_formats [docs_config: record, generation_results: list] -> record {
    log info "Converting documentation formats..."

    let start_time = (date now)

    # Format conversion would happen here (markdown to HTML, PDF, etc.)
    log warning "Documentation format conversion not fully implemented"

    {
        status: "skipped"
        reason: "format conversion not fully implemented"
        converted_files: 0
        duration: ((date now) - $start_time)
    }
}

# Count generated documents from results
def count_generated_documents [generation_results: list] -> int {
    let user_count = try {
        let user_result = ($generation_results | where phase == "user" | get 0.result)
        $user_result.docs_generated
    } catch { 0 }

    let admin_count = try {
        let admin_result = ($generation_results | where phase == "admin" | get 0.result)
        $admin_result.docs_generated
    } catch { 0 }

    let dev_count = try {
        let dev_result = ($generation_results | where phase == "dev" | get 0.result)
        $dev_result.docs_generated
    } catch { 0 }

    let api_count = try {
        let api_result = ($generation_results | where phase == "api" | get 0.result)
        $api_result.docs_generated
    } catch { 0 }

    return ($user_count + $admin_count + $dev_count + $api_count + 1) # +1 for index
}

# Get directory size helper
def get_directory_size [dir: string] -> int {
    if not ($dir | path exists) {
        return 0
    }

    try {
        find $dir -type f | each {|file| ls $file | get 0.size } | math sum | if $in == null { 0 } else { $in }
    } catch {
        0
    }
}

# Show documentation generation status
def "main status" [] {
    let repo_root = ($env.PWD | path dirname | path dirname | path dirname)

    # Check for documentation sources
    let existing_docs = find_existing_documentation $repo_root
    let has_readme = (($repo_root | path join "README.md") | path exists)

    {
        repository: $repo_root
        existing_docs: $existing_docs.total_docs
        has_readme: $has_readme
        supported_formats: ["markdown", "html"]
        doc_types: ["user", "admin", "dev", "api"]
        ready_for_generation: true
    }
}

# Quick documentation generation with minimal options
def "main quick" [
    --output-dir: string = "dist/docs"          # Output directory
    --doc-types: string = "user"                # Documentation types
] {
    main --output-dir $output_dir --doc-types $doc_types --format markdown
}