Rustelo/docs/guides/tooling-integration.md

# Rustelo Tooling Integration

## 🎯 Overview

Complete tooling template coverage ensures that all development tools work seamlessly with the unified template system and layered override architecture. This integration provides:

- **Feature-aware tooling** that adapts to enabled features
- **Layered configuration merging** for all tools
- **Consistent development workflows** across all project templates
- **Hot-reload integration** with the override system

## 🛠️ Integrated Tools

### 1. Just (Command Runner)

**Integration Points:**
- Feature-specific commands added automatically
- Local overrides for custom workflows
- Template-based recipe generation
- Environment-aware execution

**Example Structure:**
```
config/
├── local/justfile           # Local command overrides
├── features/
│   ├── analytics/justfile   # Analytics-specific commands
│   └── smart-build/justfile # Build optimization commands
└── templates/justfile       # Base commands from template
```

**Command Examples:**
```just
# Base template commands
dev:
    cargo leptos watch

build:
    cargo leptos build --release

# Feature-specific commands (analytics)
analytics-report:
    cargo run --bin analytics -- report --hours 24

# Local overrides
dev-debug:
    RUST_LOG=debug cargo leptos watch
```

### 2. CSS/UnoCSS System

**Integration Points:**
- Layered UnoCSS configurations
- Feature-specific styling
- Component-aware class generation
- Development vs production builds

**Configuration Layers:**
```typescript
// config/templates/uno.config.ts (Base)
export default {
  presets: ['@unocss/preset-uno', '@unocss/preset-wind'],
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

// config/features/analytics/uno.config.ts
export default {
  theme: {
    colors: {
      analytics: '#10b981',
    }
  },
  shortcuts: {
    'metric-card': 'bg-white shadow-md rounded-lg p-4',
  }
}

// config/local/uno.config.ts (Highest precedence)
export default {
  theme: {
    colors: {
      primary: '#ef4444',  // Override
      brand: '#8b5cf6',    // Local addition
    }
  }
}
```

### 3. Package.json Management

**Integration Points:**
- Dependency management across layers
- Script merging and overrides
- Feature-specific Node.js tools
- Development vs production configs

**Layer Structure:**
```json
// config/templates/package.json
{
  "scripts": {
    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch"
  },
  "devDependencies": {
    "@unocss/cli": "^0.58.0"
  }
}

// config/features/analytics/package.json  
{
  "scripts": {
    "analytics:dev": "node scripts/analytics-dev.js"
  },
  "dependencies": {
    "chart.js": "^4.0.0"
  }
}

// config/local/package.json
{
  "scripts": {
    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
    "test": "cargo test && npm run test:frontend"
  }
}
```

### 4. Cargo.toml Workspace Configuration

**Integration Points:**
- Workspace dependency management
- Feature flag coordination
- Crate-specific configurations
- Build optimization settings

**Layer Examples:**
```toml
# config/templates/Cargo.toml (Base workspace)
[workspace]
members = ["crates/*"]

[workspace.dependencies]
leptos = "0.6"
tokio = { version = "1.0", features = ["full"] }

# config/features/analytics/Cargo.toml
[workspace.dependencies]
prometheus = "0.13"
chrono = { version = "0.4", features = ["serde"] }

# config/local/Cargo.toml (Local overrides)
[workspace.dependencies] 
leptos = "0.7"  # Override version
anyhow = "1.0"  # Local addition

[profile.dev]
opt-level = 1  # Local optimization
```

### 5. Development Scripts

**Integration Points:**
- Layered script execution
- Feature-aware automation
- Environment detection
- Cross-platform compatibility

**Script Structure:**
```
scripts/
├── local/           # Local automation scripts
│   ├── custom-build.sh
│   └── deploy-staging.sh
├── features/        # Feature-specific scripts
│   ├── analytics/
│   │   ├── collect-metrics.sh
│   │   └── generate-reports.sh
│   └── smart-build/
│       └── cache-management.sh
└── templates/       # Base template scripts
    ├── setup.sh
    ├── build.sh
    └── test.sh
```

### 6. Build System Integration

**Integration Points:**
- Build.rs script composition
- Asset pipeline coordination
- Route generation integration
- Optimization settings

**Build Configuration:**
```rust
// crates/client/build.rs (Generated)
fn main() {
    // Layer-aware CSS build
    let css_config = resolve_layered_config::<UnoConfig>("uno.config.ts")?;
    build_css_with_config(&css_config)?;
    
    // Layer-aware route generation
    let routes = resolve_layered_routes()?;
    generate_route_code(&routes)?;
    
    // Feature-specific build steps
    if feature_enabled("analytics") {
        build_analytics_assets()?;
    }
}
```

## 🔧 Implementation Strategy

### 1. Template Generation

**Enhanced Template System:**
- Templates include complete tooling setup
- Feature selection determines which tools are included
- Layered override structure created automatically

**CLI Integration:**
```bash
# Create project with full tooling
cargo rustelo new my-project --template basic --features analytics,smart-build

# Result: Complete tooling setup with:
# - Just commands for development
# - UnoCSS configuration with analytics styles
# - Package.json with analytics dependencies
# - Build scripts with smart caching
```

### 2. Configuration Resolution

**Unified Configuration Engine:**
```rust
pub struct ToolingManager {
    config_resolver: LayeredConfig,
    project_root: PathBuf,
}

impl ToolingManager {
    pub fn resolve_just_config(&mut self) -> Result<JustConfig> {
        self.config_resolver.resolve("justfile")
    }
    
    pub fn resolve_css_config(&mut self) -> Result<UnoConfig> {
        self.config_resolver.resolve("uno.config.ts")
    }
    
    pub fn resolve_package_config(&mut self) -> Result<PackageConfig> {
        self.config_resolver.resolve("package.json")
    }
}
```

### 3. Feature Integration

**Automatic Tool Updates:**
```bash
# Adding feature updates all related tooling
cargo rustelo add analytics

# Updates:
# - justfile (adds analytics commands)
# - uno.config.ts (adds analytics styles)  
# - package.json (adds analytics dependencies)
# - build scripts (adds analytics builds)
```

### 4. Development Workflows

**Hot Reload Integration:**
- CSS changes trigger UnoCSS rebuild
- Configuration changes reload layered configs
- Component overrides trigger selective rebuilds
- Script changes restart development server

**Watch System:**
```bash
# Comprehensive development mode
just dev

# Runs:
# - cargo leptos watch (Rust hot reload)
# - unocss --watch (CSS hot reload)
# - node scripts/config-watcher.js (Config hot reload)
```

## 📋 Tooling Templates

### Just Template (Feature-Aware)

```just
# Base development commands
dev:
    @echo "🚀 Starting development server..."
    cargo leptos watch

build:
    @echo "🏗️ Building for production..."
    cargo leptos build --release

test:
    @echo "🧪 Running tests..."
    cargo test

# CSS commands (always included)
css-build:
    @echo "🎨 Building CSS..."
    unocss 'src/**/*.rs' -o public/app.css

css-watch:
    @echo "👀 Watching CSS..."
    unocss 'src/**/*.rs' -o public/app.css --watch

{{#if features.analytics}}
# Analytics commands (feature-specific)
analytics-report:
    @echo "📊 Generating analytics report..."
    cargo run --bin analytics -- report --hours 24

analytics-dashboard:
    @echo "📈 Starting analytics dashboard..."
    cargo run --bin analytics -- dashboard
{{/if}}

{{#if features.smart-build}}
# Smart build commands (feature-specific)
build-cached:
    @echo "⚡ Building with smart cache..."
    cargo run --bin smart-build -- build --cached

cache-clean:
    @echo "🧹 Cleaning build cache..."
    cargo run --bin smart-build -- cache clean
{{/if}}

# Local overrides marker
{{#if local_commands}}
# === Local Commands (Override) ===
{{local_commands}}
{{/if}}
```

### UnoCSS Template (Layered)

```typescript
// Base configuration with feature composition
import { defineConfig } from 'unocss'

export default defineConfig({
  // Base presets (always included)
  presets: [
    '@unocss/preset-uno',
    '@unocss/preset-wind',
    '@unocss/preset-typography',
  ],
  
  // Base theme
  theme: {
    colors: {
      primary: '{{theme.primary_color}}',
      secondary: '{{theme.secondary_color}}',
      {{#each theme.colors}}
      '{{@key}}': '{{this}}',
      {{/each}}
    },
    fontFamily: {
      sans: {{theme.font_sans}},
      serif: {{theme.font_serif}},
      mono: {{theme.font_mono}},
    },
  },
  
  // Base shortcuts
  shortcuts: {
    'btn': 'px-4 py-2 rounded transition-colors',
    'btn-primary': 'btn bg-primary text-white hover:bg-primary/80',
    'card': 'bg-white shadow-md rounded-lg p-4',
    {{#each shortcuts}}
    '{{@key}}': '{{this}}',
    {{/each}}
  },
  
  {{#if features.analytics}}
  // Analytics feature styles
  rules: [
    [/^metric-(\d+)$/, ([, d]) => ({ 'font-size': `${d}px` })],
  ],
  shortcuts: {
    ...shortcuts,
    'metric-card': 'card border-l-4 border-analytics',
    'chart-container': 'w-full h-64 bg-gray-50 rounded',
  },
  {{/if}}
  
  // Content sources (layer-aware)
  content: [
    'src/**/*.rs',
    'templates/**/*.html',
    {{#if features.analytics}}
    'src/components/features/analytics/**/*.rs',
    {{/if}}
    {{#if local_content}}
    'src/components/local/**/*.rs',
    {{/if}}
  ],
  
  // Safelist for always-included classes
  safelist: [
    'text-red-500',
    'text-green-500',
    'text-blue-500',
    {{#each safelist}}
    '{{this}}',
    {{/each}}
  ]
})
```

### Package.json Template (Mergeable)

```json
{
  "name": "{{project_name}}",
  "version": "{{project_version}}",
  "description": "{{project_description}}",
  "private": true,
  
  "scripts": {
    "css:build": "unocss 'src/**/*.rs' -o public/app.css",
    "css:watch": "unocss 'src/**/*.rs' -o public/app.css --watch",
    "build": "npm run css:build && cargo leptos build --release",
    "dev": "concurrently \"cargo leptos watch\" \"npm run css:watch\"",
    
    {{#if features.analytics}}
    "analytics:dev": "node scripts/features/analytics/dev-server.js",
    "analytics:report": "node scripts/features/analytics/generate-report.js",
    {{/if}}
    
    {{#if features.smart-build}}
    "build:smart": "node scripts/features/smart-build/cached-build.js",
    "cache:clean": "node scripts/features/smart-build/clean-cache.js",
    {{/if}}
    
    {{#each local_scripts}}
    "{{@key}}": "{{this}}",
    {{/each}}
  },
  
  "devDependencies": {
    "@unocss/cli": "^0.58.0",
    "@unocss/preset-uno": "^0.58.0",
    "@unocss/preset-wind": "^0.58.0",
    "concurrently": "^8.2.0",
    
    {{#if features.analytics}}
    "chart.js": "^4.0.0",
    "date-fns": "^2.30.0",
    {{/if}}
    
    {{#if features.smart-build}}
    "chokidar": "^3.5.0",
    "fast-glob": "^3.3.0",
    {{/if}}
    
    {{#each additional_dependencies}}
    "{{@key}}": "{{this}}",
    {{/each}}
  }
}
```

## 🎯 Benefits

### For Developers
- **Unified tooling** across all project types
- **Feature-aware automation** - tools adapt to enabled features
- **Local customization** without losing update capability
- **Consistent workflows** regardless of project complexity

### For Teams
- **Standardized tooling** across all Rustelo projects
- **Shared configurations** with local override capability
- **Feature parity** - same tools work the same way everywhere
- **Easy onboarding** - familiar tooling patterns

### For Framework
- **Tool integration** - all tools work together seamlessly
- **Update safety** - tooling updates don't break customizations
- **Feature composability** - tools from different features integrate properly
- **Performance optimization** - smart caching and coordination

This comprehensive tooling integration ensures that Rustelo provides a complete, production-ready development experience with all the tools developers need working seamlessly together.