# Build Scripts Directory

This directory contains all build-related scripts for the Rustelo project. These tools are organized by common build tasks and contexts to help you find the right tool for your needs.

## 📋 Requirements

**Required Tools:**
- [Nushell](https://www.nushell.sh/) - All `.nu` scripts require Nushell to be installed
- [Just](https://github.com/casey/just) - Task runner (recommended for easy command execution)
- For complete setup, see [Rustelo Requirements - Tools](https://github.com/your-repo/rustelo#tools)

## 🏗️ Build Tools by Context

### 🚀 Production Build & Deployment

#### `leptos-build.nu` - Complete Production Build Pipeline
**Purpose:** Full production build with dependencies, CSS, and optimization  
**Task:** Build production-ready Leptos application  
**Context:** Use when preparing for deployment or creating release builds  
**Command:** `nu scripts/build/leptos-build.nu` or `just leptos-build-nu`  
**Features:**
- Installs all dependencies (main + end2end)
- Builds CSS assets with UnoCSS
- Compiles Leptos with release optimizations
- Enables TLS and content-static features
- Minifies JavaScript output

#### `deploy.nu` - Application Deployment Manager
**Purpose:** Complete deployment management with Docker Compose  
**Task:** Deploy, manage, and monitor application environments  
**Context:** Production, staging, and development deployments  
**Command:** `nu scripts/build/deploy.nu [OPTIONS] COMMAND`  
**Main Arguments:**
- `-e, --env ENV` - Environment (dev|staging|production)
- `-f, --file FILE` - Docker compose file
- `-s, --scale N` - Number of replicas
- `--migrate` - Run database migrations
- `--backup` - Create database backup
- `--features FEATURES` - Cargo features to enable

**Commands:**
- `deploy` - Deploy application with health checks
- `stop/restart` - Control application lifecycle
- `status` - Show deployment status and resource usage
- `logs` - View application logs
- `scale` - Scale replicas
- `health` - Check application health
- `backup/migrate` - Database operations
- `clean` - Clean up unused containers

**Examples:**
```bash
nu scripts/build/deploy.nu deploy -e production --migrate --backup
nu scripts/build/deploy.nu scale -s 3
nu scripts/build/deploy.nu health
```

### 📦 Distribution & Packaging

#### `dist-pack.nu` - Distribution Package Creator
**Purpose:** Create compressed distribution packages for deployment  
**Task:** Package built application for different architectures  
**Context:** CI/CD pipelines, manual distribution, release preparation  
**Command:** `nu scripts/build/dist-pack.nu [OS_ARCH]` or `just dist-pack-nu [target]`  
**Arguments:**
- `OS_ARCH` - Target architecture (e.g., linux-x64, darwin-arm64)

**Features:**
- Validates build artifacts exist
- Packages server binary, site assets, public files
- Creates compressed tar.gz archives
- Shows package size and contents

### 🔧 Cross-Platform Development

#### `cross-build.nu` - Docker Cross-Platform Builder
**Purpose:** Build application for different architectures using Docker  
**Task:** Cross-compile for Linux from macOS/Windows  
**Context:** Multi-platform releases, Linux deployment from dev machines  
**Command:** `nu scripts/build/cross-build.nu` or `just cross-build-nu`  
**Features:**
- Uses Docker for consistent Linux builds
- Handles volume mounts for project, node_modules, target
- Runs complete build pipeline in container
- Shows distribution file results

#### `build-docker-cross.nu` - Cross-Compilation Image Builder
**Purpose:** Build Docker image for cross-platform compilation  
**Task:** Create/update build environment Docker image  
**Context:** Setting up cross-compilation environment, updating build tools  
**Command:** `nu scripts/build/build-docker-cross.nu` or `just docker-cross-build-nu`  
**Features:**
- Builds custom Docker image for cross-compilation
- Validates Docker availability
- Shows image information and size

### 📚 Documentation & Examples

#### `build-docs.nu` - Documentation Generator with Assets
**Purpose:** Generate Cargo documentation with integrated logo assets  
**Task:** Build comprehensive project documentation  
**Context:** Documentation updates, release preparation, developer onboarding  
**Command:** `nu scripts/build/build-docs.nu` or `just docs-cargo-nu`  
**Features:**
- Generates cargo doc with private items
- Copies logo assets to documentation output
- Validates documentation structure
- Shows documentation size and location
- Provides next steps for viewing docs

#### `build-examples.nu` - Multi-Configuration Build Examples
**Purpose:** Demonstrate building with different Cargo feature combinations  
**Task:** Test and showcase various application configurations  
**Context:** Testing feature combinations, documentation examples, CI validation  
**Command:** `nu scripts/build/build-examples.nu [OPTIONS]`  
**Arguments:**
- `-c, --clean` - Clean build artifacts first
- `-a, --all` - Build all configurations (default)
- `-m, --minimal` - Minimal configuration only
- `-f, --full` - Full-featured configuration only
- `-p, --prod` - Production configuration only
- `-q, --quick` - Common configurations only

**Configurations Built:**
- Minimal (no database)
- TLS-only (secure static)
- Auth-only (authentication)
- Content-DB (database content)
- Full-featured (auth + content)
- Production (all features)
- Specialized combinations

### 🌍 Content & Localization

#### `build-localized-content.nu` - Markdown to HTML Content Builder
**Purpose:** Convert localized markdown content to HTML for web serving  
**Task:** Process multilingual content with categories, tags, and metadata  
**Context:** Content updates, adding new languages, preparing content for deployment  
**Command:** `nu scripts/build/build-localized-content.nu`  
**Features:**
- Reads content types from content-kinds.toml
- Processes English and Spanish content
- Converts markdown to HTML with frontmatter
- Generates category indices and filter indices
- Creates content manifest
- Validates JSON structure
- Shows content statistics

**Content Processing:**
- Discovers content types dynamically
- Handles category directory structures
- Extracts metadata (tags, categories, publishing status)
- Generates navigation indices
- Creates backward compatibility links

### 🛠️ Development Tools

#### `dev-quiet.nu` - Filtered Development Server
**Purpose:** Run development server with filtered, relevant output only  
**Task:** Start Leptos development server without noise  
**Context:** Daily development, focusing on important messages  
**Command:** `nu scripts/build/dev-quiet.nu` or `just dev-quiet-nu`  
**Features:**
- Runs `cargo leptos watch` 
- Filters out verbose/irrelevant output
- Highlights errors, warnings, and important messages
- Shows clean, focused development feedback

#### `kill-3030.nu` - Development Port Process Killer
**Purpose:** Kill processes running on development ports (3030, 3031)  
**Task:** Clean up stuck development servers  
**Context:** Development workflow, server restart, port conflicts  
**Command:** `nu scripts/build/kill-3030.nu`  
**Features:**
- Finds processes using ports 3030 and 3031
- Safely kills development server processes
- Shows which processes were killed
- Handles cases where no processes are found

## 🎨 Asset Build Tools (JavaScript)

### CSS & Theme Building
- **`build-css-bundles.js`** - CSS bundling and optimization
- **`build-design-system.js`** - Design system compilation
- **`build-theme.js`** - Theme file generation
- **`copy-css-assets.js`** - CSS asset management

### JavaScript & Highlighting  
- **`build-highlight-bundle.js`** - Syntax highlighting bundle creation
- **`build-inline-scripts.js`** - Inline script optimization

**Usage:** These are typically called through the main build pipeline or package.json scripts.

## 🚀 Quick Start Commands

```bash
# Complete production build
just leptos-build-nu

# Development with clean output
just dev-quiet-nu

# Deploy to production
nu scripts/build/deploy.nu deploy -e production --migrate

# Build all configuration examples
nu scripts/build/build-examples.nu --all

# Generate documentation
just docs-cargo-nu

# Create distribution package
just dist-pack-nu linux-x64

# Build localized content
nu scripts/build/build-localized-content.nu

# Clean development ports
nu scripts/build/kill-3030.nu
```

## 📁 File Organization

```
scripts/build/
├── README.md                    # This documentation
├── leptos-build.nu             # 🚀 Main production build
├── deploy.nu                   # 🚀 Deployment manager  
├── dist-pack.nu                # 📦 Distribution packaging
├── cross-build.nu              # 🔧 Cross-platform building
├── build-docker-cross.nu       # 🔧 Docker build environment
├── build-docs.nu               # 📚 Documentation generation
├── build-examples.nu           # 📚 Configuration examples
├── build-localized-content.nu  # 🌍 Content localization
├── dev-quiet.nu                # 🛠️  Development server
├── kill-3030.nu                # 🛠️  Port cleanup
└── [*.js files]                # 🎨 Asset build tools
```

## 🔄 Integration with Just

Most scripts are integrated with the project's `justfile` for convenient access:

```bash
just dev-quiet-nu              # Quiet development server
just docs-cargo-nu             # Build documentation  
just dist-pack-nu linux-x64    # Create distribution
just cross-build-nu            # Cross-platform build
just docker-cross-build-nu     # Build Docker image
```

## 🔧 Original Bash Scripts

Original bash scripts are preserved in `scripts/sh/build/` for reference during the transition period. The Nushell versions provide enhanced error handling, structured data processing, and better cross-platform compatibility.