provisioning/tools/README.md

# Development Tools

Development and distribution tooling for provisioning.

## Tool Categories

### Build Tools (`build/`)

Build automation and compilation tools:

- Nushell script validation
- KCL schema compilation
- Dependency management
- Asset bundling

**Future Features**:

- Automated testing pipelines
- Code quality checks
- Performance benchmarking

### Package Tools (`package/`)

Packaging utilities for distribution:

- Standalone executables
- Container images
- System packages (deb, rpm, etc.)
- Archive creation

**Future Features**:

- Multi-platform builds
- Dependency bundling
- Signature verification

### Release Tools (`release/`)

Release management automation:

- Version bumping
- Changelog generation
- Git tag management
- Release notes creation

**Future Features**:

- Automated GitHub releases
- Asset uploads
- Release validation

### Distribution Tools (`distribution/`)

Distribution generators and deployment:

- Installation scripts
- Configuration templates
- Update mechanisms
- Registry management

**Future Features**:

- Package repositories
- Update servers
- Telemetry collection

## Tool Architecture

### Script-Based Tools

Most tools are implemented as Nushell scripts for consistency with the main system:

- Easy integration with existing codebase
- Consistent configuration handling
- Native data structure support

### Build Pipeline Integration

Tools integrate with common CI/CD systems:

- GitHub Actions
- GitLab CI
- Jenkins
- Custom automation

### Configuration Management

Tools use the same configuration system as the main application:

- Unified settings
- Environment-specific overrides
- Secret management integration

## Usage Examples

```nushell
# Build the complete system
./tools/build/build-all.nu

# Package for distribution
./tools/package/create-standalone.nu --target linux

# Create a release
./tools/release/prepare-release.nu --version 4.0.0

# Generate distribution assets
./tools/distribution/generate-installer.nu --platform macos
```

## Directory Structure

```plaintext
provisioning/tools/
├── README.md                          # This file
├── build/                             # Core build tools (Rust + Nushell)
│   ├── README.md
│   ├── compile-platform.nu            # Compile Rust binaries
│   ├── bundle-core.nu                 # Bundle Nushell libraries
│   └── check-system.nu                # Validate build environment
├── dist/                              # Build output directory (generated)
│   ├── README.md
│   ├── core/                          # Nushell bundles
│   ├── platform/                      # Compiled binaries
│   └── config/                        # Configuration files
├── distribution/                      # Distribution generation
│   ├── README.md
│   └── generate-distribution.nu       # Create installable packages
├── package/                           # Package outputs (generated)
│   └── README.md
├── release/                           # Release management (generated)
│   └── README.md
├── scripts/                           # Utility and setup scripts
│   ├── *.nu files                     # Nushell utilities
│   └── *.sh files                     # Shell scripts
└── [Other utility scripts]            # Standalone tools
```

See individual README.md files in each subdirectory for detailed information.

## Development Setup

1. Ensure all dependencies are installed
2. Configure build environment
3. Run initial setup scripts
4. Validate tool functionality

## Integration

These tools integrate with:

- Main provisioning system
- Extension system
- Configuration management
- Documentation generation
- CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)