ColorScripts-Enhanced

2025.11.2.1947

it/about_ColorScripts-Enhanced.help.txt

# ColorScripts-Enhanced Module Help
 
## about_ColorScripts-Enhanced
 
### SHORT DESCRIPTION
ColorScripts avanzati per PowerShell con sistema di caching ad alte prestazioni per visualizzare bellissime opere d'arte ANSI nel terminale.
 
### LONG DESCRIPTION
ColorScripts-Enhanced è un modulo PowerShell che fornisce una raccolta di oltre 450 bellissimi colorscript ANSI per la visualizzazione nel terminale. Include un sistema di caching intelligente che offre miglioramenti delle prestazioni da 6 a 19 volte superiori rispetto all'esecuzione tradizionale degli script.
 
Il modulo memorizza automaticamente l'output degli script in una posizione centralizzata nella cartella AppData, consentendo la visualizzazione istantanea nelle esecuzioni successive. I file di cache vengono automaticamente convalidati e rigenerati quando gli script di origine vengono modificati.
 
### FEATURES
- Oltre 450 bellissimi colorscript preconfezionati
- Sistema di caching ad alte prestazioni (da 6 a 19 volte più veloce)
- Posizione di cache centralizzata (funziona da qualsiasi directory)
- Invalidazione automatica della cache in caso di modifiche agli script
- Supporto per la codifica UTF-8 per un rendering perfetto
- Selezione casuale di colorscript
- Scoperta e elenco facili degli script
- Helper di profilo per l'integrazione di avvio con una sola riga
- Helper di configurazione persistente per il comportamento della cache e dell'avvio
- Esportazione di metadati e flussi di lavoro di scaffolding per script personalizzati
 
### INSTALLATION
 
#### From PowerShell Gallery (Recommended)
```powershell
Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser
```
 
Aggiungi automaticamente il modulo al tuo profilo:
 
```powershell
Add-ColorScriptProfile # Import + Show-ColorScript
Add-ColorScriptProfile -SkipStartupScript
```
 
#### Manual Installation
1. Scarica il modulo da GitHub
2. Estrai in un percorso del modulo PowerShell:
   - User: `$HOME\Documents\PowerShell\Modules\ColorScripts-Enhanced`
   - System: `C:\Program Files\PowerShell\Modules\ColorScripts-Enhanced`
3. Importa il modulo:
   ```powershell
   Import-Module ColorScripts-Enhanced
   ```
 
### QUICK START
 
Visualizza un colorscript casuale:
```powershell
Show-ColorScript
# or use the alias
scs
```
 
Visualizza un colorscript specifico:
```powershell
Show-ColorScript -Name hearts
scs mandelbrot-zoom
```
 
Elenca tutti i colorscript disponibili:
```powershell
Show-ColorScript -List
Get-ColorScriptList
```
 
Pre-costruisci la cache per tutti gli script:
```powershell
New-ColorScriptCache
```
 
### COMMANDS
 
Il modulo esporta i seguenti comandi:
 
- `Show-ColorScript` - Visualizza colorscript (alias: scs)
- `Get-ColorScriptList` - Elenca colorscript disponibili
- `New-ColorScriptCache` - Pre-genera file di cache
- `Clear-ColorScriptCache` - Rimuovi file di cache
- `Add-ColorScriptProfile` - Aggiungi snippet di avvio del modulo a un profilo PowerShell
- `Get-ColorScriptConfiguration` - Ispeziona impostazioni predefinite di cache e avvio
- `Set-ColorScriptConfiguration` - Mantieni valori di configurazione personalizzati
- `Reset-ColorScriptConfiguration` - Ripristina impostazioni predefinite della configurazione
- `Export-ColorScriptMetadata` - Esporta metadati degli script per l'automazione
- `New-ColorScript` - Crea scaffold per un nuovo colorscript e snippet di metadati
 
Usa `Get-Help <CommandName> -Full` per aiuto dettagliato su ciascun comando.
 
### CACHE SYSTEM
 
Il sistema di caching funziona automaticamente:
 
1. **Prima Esecuzione**: Lo script viene eseguito normalmente e l'output viene memorizzato nella cache
2. **Esecuzioni Successive**: L'output della cache viene visualizzato istantaneamente (6-19 volte più veloce)
3. **Aggiornamento Automatico**: La cache si rigenera quando lo script viene modificato
 
**Posizione Cache**: `$env:APPDATA\ColorScripts-Enhanced\cache`
 
**Vantaggi Cache**:
- Visualizzazione istantanea di colorscript complessi
- Riduzione dell'utilizzo della CPU
- Prestazioni consistenti
- Funziona da qualsiasi directory
 
### CONFIGURATION
 
#### Aggiungi al Profilo PowerShell
Visualizza un colorscript casuale ad ogni avvio del terminale:
 
```powershell
Add-ColorScriptProfile # Import + Show-ColorScript
Add-ColorScriptProfile -SkipStartupScript
```
 
#### Personalizza Posizione Cache
La posizione della cache viene impostata automaticamente in base alla tua piattaforma:
 
Windows:
```powershell
$env:APPDATA\ColorScripts-Enhanced\cache
```
 
macOS:
```powershell
~/Library/Application Support/ColorScripts-Enhanced/cache
```
 
Linux:
```powershell
~/.cache/ColorScripts-Enhanced
```
 
### NERD FONT GLYPHS
 
Alcuni script visualizzano icone Nerd Font (glifi per sviluppatori, separatori powerline, segni di spunta). Installa un font corretto in modo che questi caratteri vengano renderizzati correttamente:
 
1. Scarica un font da https://www.nerdfonts.com/ (scelte popolari: Cascadia Code, JetBrainsMono, FiraCode).
2. Windows: estrai il `.zip`, seleziona i file `.ttf`, fai clic con il pulsante destro del mouse → **Installa per tutti gli utenti**.
   macOS: `brew install --cask font-caskaydia-cove-nerd-font` o aggiungi tramite Font Book.
   Linux: copia i file `.ttf` in `~/.local/share/fonts` (o `/usr/local/share/fonts`) ed esegui `fc-cache -fv`.
3. Imposta il profilo del terminale per utilizzare il Nerd Font installato.
4. Verifica i glifi con:
 
```powershell
Show-ColorScript -Name nerd-font-test
```
 
### EXAMPLES
 
#### Esempio 1: Colorscript Casuale all'Avvio
```powershell
# Nel tuo file $PROFILE:
Import-Module ColorScripts-Enhanced
Show-ColorScript
```
 
#### Esempio 2: Colorscript Diverso Ogni Giorno
```powershell
# Usa la data come seme per uno script giornaliero consistente
$seed = (Get-Date).DayOfYear
Get-Random -SetSeed $seed
Show-ColorScript
```
 
#### Esempio 3: Costruisci Cache per Script Preferiti
```powershell
New-ColorScriptCache -Name hearts,mandelbrot-zoom,galaxy-spiral
```
 
#### Esempio 4: Forza Ricostruzione Cache
```powershell
New-ColorScriptCache -Force
```
 
### TROUBLESHOOTING
 
#### Gli script non vengono visualizzati correttamente
Assicurati che il tuo terminale supporti UTF-8 e i codici di escape ANSI:
```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
```
 
#### La cache non funziona
Cancella e ricostruisci la cache:
```powershell
Clear-ColorScriptCache -All
New-ColorScriptCache
```
 
#### Problemi di prestazioni
La prima esecuzione di ogni script sarà più lenta poiché costruisce la cache. Pre-costruisci tutte le cache:
```powershell
New-ColorScriptCache
```
 
### PERFORMANCE
 
Miglioramenti delle prestazioni tipici con il caching:
 
| Tipo di Script | Senza Cache | Con Cache | Accelerazione |
|---------------|-------------|-----------|-------------|
| Semplice | ~50ms | ~8ms | 6x |
| Medio | ~150ms | ~12ms | 12x |
| Complesso | ~300ms | ~16ms | 19x |
 
### SCRIPT CATEGORIES
 
The module includes scripts in various categories:
 
- **Geometric**: mandelbrot-zoom, apollonian-circles, sierpinski-carpet
- **Nature**: galaxy-spiral, aurora-bands, crystal-drift
- **Artistic**: kaleidoscope, rainbow-waves, prismatic-rain
- **Gaming**: doom, pacman, space-invaders
- **System**: colortest, nerd-font-test, terminal-benchmark
- **Logos**: arch, debian, ubuntu, windows
 
### SEE ALSO
 
- GitHub Repository: https://github.com/Nick2bad4u/ps-color-scripts-enhanced
- Original inspiration: shell-color-scripts
- PowerShell Documentation: https://docs.microsoft.com/powershell/
 
### KEYWORDS
- ANSI
- Terminal
- Art
- ASCII
- Color
- Scripts
- Cache
- Performance
 
### ADVANCED USAGE
 
#### Building Cache for Specific Categories
Cache all scripts in the Geometric category for optimal performance:
```powershell
Get-ColorScriptList -Category Geometric -AsObject |
    ForEach-Object { New-ColorScriptCache -Name $_.Name }
```
 
#### Performance Measurement
Measure the performance improvement from caching:
```powershell
# Uncached performance (cold start)
Remove-Module ColorScripts-Enhanced -ErrorAction SilentlyContinue
$uncached = Measure-Command {
    Import-Module ColorScripts-Enhanced
    Show-ColorScript -Name "mandelbrot-zoom" -NoCache
}
 
# Cached performance (warm start)
$cached = Measure-Command {
    Show-ColorScript -Name "mandelbrot-zoom"
}
 
Write-Host "Uncached: $($uncached.TotalMilliseconds)ms"
Write-Host "Cached: $($cached.TotalMilliseconds)ms"
Write-Host "Speedup: $([math]::Round($uncached.TotalMilliseconds / $cached.TotalMilliseconds, 1))x"
```
 
#### Automation: Display Different Script Daily
Set up your profile to show a different script each day:
```powershell
# In your $PROFILE file:
$seed = (Get-Date).DayOfYear
[System.Random]::new($seed).Next()
Get-Random -SetSeed $seed
Show-ColorScript
```
 
#### Pipeline Operations with Metadata
Export colorscript metadata for use in other tools:
```powershell
# Export to JSON for web dashboard
Export-ColorScriptMetadata -Path ./dist/colorscripts.json -IncludeFileInfo
 
# Count scripts by category
Get-ColorScriptList -AsObject |
    Group-Object Category |
    Select-Object Name, Count |
    Sort-Object Count -Descending
 
# Find scripts with specific keywords
$scripts = Get-ColorScriptList -AsObject
$scripts |
    Where-Object { $_.Description -match 'fractal|mandelbrot' } |
    Select-Object Name, Category, Description
```
 
#### Cache Management for CI/CD Environments
Configure and manage cache for automated deployments:
```powershell
# Set temporary cache location for CI/CD
Set-ColorScriptConfiguration -CachePath $env:TEMP\colorscripts-cache
 
# Pre-build cache for deployment
$productionScripts = @('bars', 'arch', 'ubuntu', 'windows', 'rainbow-waves')
New-ColorScriptCache -Name $productionScripts -Force
 
# Verify cache health
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
Get-ChildItem $cacheDir -Filter "*.cache" | Measure-Object -Sum Length
```
 
#### Filtering and Display Workflows
Advanced filtering for customized displays:
```powershell
# Display all recommended scripts with details
Get-ColorScriptList -Tag Recommended -Detailed
 
# Show geometric scripts with caching disabled for testing
Get-ColorScriptList -Category Geometric -Name "aurora-*" -AsObject |
    ForEach-Object { Show-ColorScript -Name $_.Name -NoCache }
 
# Export metadata filtered by category
Export-ColorScriptMetadata -IncludeFileInfo |
    Where-Object { $_.Category -eq 'Animated' } |
    ConvertTo-Json |
    Out-File "./animated-scripts.json"
```
 
### ENVIRONMENT VARIABLES
 
The module respects the following environment variables:
 
- **COLORSCRIPTS_CACHE**: Override the default cache location
- **PSModulePath**: Affects where the module is discovered
 
### PERFORMANCE TUNING
 
#### Typical Performance Metrics
| Script Complexity | Without Cache | With Cache | Improvement |
|------------------|---------------|------------|-------------|
| Simple (50-100ms) | ~50ms | ~8ms | 6x faster |
| Medium (100-200ms) | ~150ms | ~12ms | 12x faster |
| Complex (200-300ms) | ~300ms | ~16ms | 19x faster |
 
#### Cache Size Information
- Average cache file size: 2-50KB per script
- Total cache size for all scripts: ~2-5MB
- Cache location: Uses OS-appropriate paths for minimal footprint
 
### TROUBLESHOOTING ADVANCED ISSUES
 
#### Module Not Found Error
```powershell
# Check if module is in PSModulePath
Get-Module ColorScripts-Enhanced -ListAvailable
 
# List available module paths
$env:PSModulePath -split ';'
 
# Import from explicit path if necessary
Import-Module "C:\Path\To\ColorScripts-Enhanced\ColorScripts-Enhanced.psd1"
```
 
#### Cache Corruption
Clear and rebuild completely:
```powershell
# Remove module from session
Remove-Module ColorScripts-Enhanced -Force
 
# Clear all cache files
Clear-ColorScriptCache -All -Confirm:$false
 
# Reimport and rebuild cache
Import-Module ColorScripts-Enhanced
New-ColorScriptCache -Force
```
 
#### Performance Degradation
If performance worsens over time:
```powershell
# Check cache directory size
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
$size = (Get-ChildItem $cacheDir -Filter "*.cache" |
    Measure-Object -Sum Length).Sum
Write-Host "Cache size: $([math]::Round($size / 1MB, 2)) MB"
 
# Clear old cache and rebuild
Clear-ColorScriptCache -All
New-ColorScriptCache
```
 
### PLATFORM-SPECIFIC NOTES
 
#### Windows PowerShell 5.1
- Limited to Windows only
- Use `powershell.exe` to run scripts
- Some advanced features may be unavailable
- Recommended to upgrade to PowerShell 7+
 
#### PowerShell 7+ (Cross-Platform)
- Full support on Windows, macOS, and Linux
- Use `pwsh` command
- All features fully functional
- Recommended for new deployments
 
### DETAILED COMMAND REFERENCE
 
#### Core Commands Overview
The module provides 10 main commands for managing and displaying colorscripts:
 
**Display Commands:**
- `Show-ColorScript` - Display colorscripts with multiple modes (random, named, list, all)
- `Get-ColorScriptList` - List available colorscripts with detailed metadata
 
**Cache Management:**
- `New-ColorScriptCache` - Build cache files for performance
- `Clear-ColorScriptCache` - Remove cache files with filtering options
- `Build-ColorScriptCache` - Alias for New-ColorScriptCache
 
**Configuration:**
- `Get-ColorScriptConfiguration` - Retrieve current configuration settings
- `Set-ColorScriptConfiguration` - Persist configuration changes
- `Reset-ColorScriptConfiguration` - Restore factory defaults
 
**Profile Integration:**
- `Add-ColorScriptProfile` - Integrate module into PowerShell profile
 
**Development:**
- `New-ColorScript` - Scaffold new colorscript template
- `Export-ColorScriptMetadata` - Export metadata for automation
 
#### Command Usage Patterns
 
**Pattern 1: Quick Display**
```powershell
Show-ColorScript # Random colorscript
scs # Using module alias
Show-ColorScript -Name aurora # Specific script
```
 
**Pattern 2: Discovery and Listing**
```powershell
Get-ColorScriptList # All scripts
Get-ColorScriptList -Detailed # With tags and descriptions
Get-ColorScriptList -Category Nature # Filter by category
Get-ColorScriptList -Tag Animated # Filter by tag
```
 
**Pattern 3: Performance Optimization**
```powershell
New-ColorScriptCache # Build all caches
New-ColorScriptCache -Name bars # Build specific cache
New-ColorScriptCache -Category Geometric # Build category
```
 
**Pattern 4: Cache Maintenance**
```powershell
Clear-ColorScriptCache -All # Remove all caches
Clear-ColorScriptCache -Name "test-*" # Clear pattern
Clear-ColorScriptCache -Category Demo # Clear by category
```
 
### DETAILED WORKFLOW EXAMPLES
 
#### Workflow 1: Initial Setup and Configuration
```powershell
# Step 1: Install the module
Install-Module -Name ColorScripts-Enhanced -Scope CurrentUser
 
# Step 2: Add to profile for automatic startup
Add-ColorScriptProfile
 
# Step 3: Pre-build cache for optimal performance
New-ColorScriptCache
 
# Step 4: Verify setup
Get-ColorScriptConfiguration
```
 
#### Workflow 2: Daily Use with Rotation
```powershell
# In $PROFILE file, add:
Import-Module ColorScripts-Enhanced
 
# Display different script each day based on date
$seed = (Get-Date).DayOfYear
Get-Random -SetSeed $seed
Show-ColorScript -Random
 
# Alternative: Show specific category
Show-ColorScript -Category Geometric -Random
```
 
#### Workflow 3: Automation Integration
```powershell
# Export metadata for external tools
$metadata = Export-ColorScriptMetadata -IncludeFileInfo -IncludeCacheInfo
$metadata | ConvertTo-Json | Out-File "./colorscripts.json"
 
# Use in automation: cycle through scripts
$scripts = Get-ColorScriptList -Tag Recommended -AsObject
$scripts | ForEach-Object { Show-ColorScript -Name $_.Name; Start-Sleep -Seconds 2 }
```
 
#### Workflow 4: Performance Monitoring
```powershell
# Measure cache effectiveness
$uncached = Measure-Command { Show-ColorScript -Name mandelbrot-zoom -NoCache }
$cached = Measure-Command { Show-ColorScript -Name mandelbrot-zoom }
 
Write-Host "Uncached: $($uncached.TotalMilliseconds)ms"
Write-Host "Cached: $($cached.TotalMilliseconds)ms"
Write-Host "Improvement: $([math]::Round($uncached.TotalMilliseconds / $cached.TotalMilliseconds, 1))x"
```
 
#### Workflow 5: Customization and Development
```powershell
# Create custom colorscript
New-ColorScript -Name "my-custom-art" -Category "Custom" -Tag "MyTag" -GenerateMetadataSnippet
 
# Edit the script
code "$env:USERPROFILE\Documents\PowerShell\Modules\ColorScripts-Enhanced\Scripts\my-custom-art.ps1"
 
# Add metadata (use guidance from generation)
# Edit ScriptMetadata.psd1
 
# Cache and test
New-ColorScriptCache -Name "my-custom-art" -Force
Show-ColorScript -Name "my-custom-art"
```
 
### INTEGRATION SCENARIOS
 
#### Scenario 1: Terminal Welcome Screen
```powershell
# In profile:
$hour = (Get-Date).Hour
if ($hour -ge 6 -and $hour -lt 12) {
    Show-ColorScript -Tag "bright,morning" -Random
} elseif ($hour -ge 12 -and $hour -lt 18) {
    Show-ColorScript -Category Geometric -Random
} else {
    Show-ColorScript -Tag "night,dark" -Random
}
```
 
#### Scenario 2: CI/CD Pipeline
```powershell
# Build phase decoration
Show-ColorScript -Name "bars" -NoCache # Quick display without cache
New-ColorScriptCache -Category "Build" -Force # Prepare for next run
 
# In CI/CD context:
$env:CI = $true
if ($env:CI) {
    Show-ColorScript -NoCache # Avoid cache in ephemeral environments
}
```
 
#### Scenario 3: Administrative Dashboards
```powershell
# Display system-themed colorscripts
$os = if ($PSVersionTable.PSVersion.Major -ge 7) { "pwsh" } else { "powershell" }
Show-ColorScript -Name $os -PassThru | Out-Null
 
# Show status information
Get-ColorScriptList -Tag "system" -AsObject |
    ForEach-Object { Write-Host "Available: $($_.Name)" }
```
 
#### Scenario 4: Educational Presentations
```powershell
# Interactive colorscript showcase
Show-ColorScript -All -WaitForInput
# Users can press space to advance, q to quit
 
# Or with specific category
Show-ColorScript -All -Category Abstract -WaitForInput
```
 
#### Scenario 5: Multi-User Environment
```powershell
# Per-user configuration
Set-ColorScriptConfiguration -CachePath "\\shared\cache\$env:USERNAME"
Set-ColorScriptConfiguration -DefaultScript "team-logo"
 
# Shared scripts with user customization
Get-ColorScriptList -AsObject |
    Where-Object { $_.Tags -contains "shared" } |
    ForEach-Object { Show-ColorScript -Name $_.Name }
```
 
### ADVANCED TOPICS
 
#### Topic 1: Cache Strategy Selection
Different caching strategies for different scenarios:
 
**Full Cache Strategy** (Optimal for Workstations)
```powershell
New-ColorScriptCache # Cache all 450++ scripts
# Pros: Maximum performance, instant display
# Cons: Uses 2-5MB disk space
```
 
**Selective Cache Strategy** (Optimal for Portable/CI)
```powershell
Get-ColorScriptList -Tag Recommended -AsObject |
    ForEach-Object { New-ColorScriptCache -Name $_.Name }
# Pros: Balanced performance and storage
# Cons: Requires more setup
```
 
**No Cache Strategy** (Optimal for Development)
```powershell
Show-ColorScript -NoCache
# Pros: See script changes immediately
# Cons: Slower display, more resource usage
```
 
#### Topic 2: Metadata Organization
Understanding and organizing colorscripts by metadata:
 
**Categories** - Broad organizational groupings:
- Geometric: Fractals, mathematical patterns
- Nature: Landscapes, organic themes
- Artistic: Creative, abstract designs
- Gaming: Game-related themes
- System: OS/technology themed
 
**Tags** - Specific descriptors:
- Recommended: Curated for general use
- Animated: Moving/changing patterns
- Colorful: Multi-color palettes
- Minimal: Simple, clean designs
- Retro: Classic 80s/90s aesthetics
 
#### Topic 3: Performance Optimization Tips
```powershell
# Tip 1: Pre-load frequently used scripts
New-ColorScriptCache -Name bars,arch,mandelbrot-zoom,aurora-waves
 
# Tip 2: Monitor cache staleness
$old = Get-ChildItem "$env:APPDATA\ColorScripts-Enhanced\cache" -Filter "*.cache" |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddMonths(-1) }
 
# Tip 3: Use category filtering for faster selection
Show-ColorScript -Category Geometric # Faster than full set
 
# Tip 4: Enable verbose output for debugging
Show-ColorScript -Name aurora -Verbose
```
 
#### Topic 4: Cross-Platform Considerations
```powershell
# Windows Terminal specific
if ($env:WT_SESSION) {
    Show-ColorScript # Full color support
}
 
# VS Code integrated terminal
if ($env:TERM_PROGRAM -eq "vscode") {
    Show-ColorScript -Name nerd-font-test # Font support
}
 
# SSH session
if ($env:SSH_CONNECTION) {
    Show-ColorScript -NoCache # Avoid slow network cache I/O
}
 
# Linux/macOS terminal
if ($PSVersionTable.PSVersion.Major -ge 7) {
    Show-ColorScript -Category Nature # Use Unix-friendly scripts
}
```
 
#### Topic 5: Scripting and Automation
```powershell
# Create reusable function for daily greeting
function Show-DailyColorScript {
    $seed = (Get-Date).DayOfYear
    Get-Random -SetSeed $seed
    Show-ColorScript -Random -Category @("Geometric", "Nature") -Random
}
 
# Use in profile
Show-DailyColorScript
 
# Create script rotation function
function Invoke-ColorScriptSlideshow {
    param(
        [int]$Interval = 3,
        [string[]]$Category,
        [int]$Count
    )
 
    $scripts = if ($Category) {
        Get-ColorScriptList -Category $Category -AsObject
    } else {
        Get-ColorScriptList -AsObject
    }
 
    $scripts | Select-Object -First $Count | ForEach-Object {
        Show-ColorScript -Name $_.Name
        Start-Sleep -Seconds $Interval
    }
}
 
# Usage
Invoke-ColorScriptSlideshow -Interval 2 -Category Geometric -Count 5
```
 
### TROUBLESHOOTING GUIDE
 
#### Issue 1: Scripts Not Displaying Correctly
**Symptoms**: Garbled characters or missing colors
**Solutions**:
```powershell
# Set UTF-8 encoding
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 
# Check terminal supports UTF-8
Write-Host "Test: ✓ ✗ ◆ ○" -ForegroundColor Green
 
# Use nerd font test
Show-ColorScript -Name nerd-font-test
 
# If still broken, disable cache
Show-ColorScript -Name yourscript -NoCache
```
 
#### Issue 2: Module Import Failures
**Symptoms**: "Module not found" or import errors
**Solutions**:
```powershell
# Check if module exists
Get-Module -ListAvailable | Where-Object Name -like "*Color*"
 
# Check PSModulePath
$env:PSModulePath -split [System.IO.Path]::PathSeparator
 
# Reinstall module
Remove-Module ColorScripts-Enhanced
Uninstall-Module ColorScripts-Enhanced
Install-Module -Name ColorScripts-Enhanced -Force
```
 
#### Issue 3: Cache Not Being Used
**Symptoms**: Scripts run slowly every time
**Solutions**:
```powershell
# Verify cache exists
$cacheDir = (Get-ColorScriptConfiguration).Cache.Path
Get-ChildItem $cacheDir -Filter "*.cache" | Measure-Object
 
# Rebuild cache
Remove-Item "$cacheDir\*" -Confirm:$false
New-ColorScriptCache -Force
 
# Check for cache path issues
Get-ColorScriptConfiguration | Select-Object -ExpandProperty Cache
```
 
#### Issue 4: Profile Not Running
**Symptoms**: Colorscript doesn't show on PowerShell startup
**Solutions**:
```powershell
# Verify profile exists
Test-Path $PROFILE
 
# Check profile content
Get-Content $PROFILE | Select-String "ColorScripts"
 
# Repair profile
Add-ColorScriptProfile -Force
 
# Test profile manually
. $PROFILE
```
 
### FAQ
 
**Q: How many colorscripts are available?**
A: 450++ built-in scripts across multiple categories and tags
 
**Q: How much disk space does caching use?**
A: Approximately 2-5MB total for all scripts, about 2-50KB per script
 
**Q: Can I use colorscripts in scripts/automation?**
A: Yes, use `-ReturnText` to capture output or `-PassThru` for metadata
 
**Q: How do I create custom colorscripts?**
A: Use `New-ColorScript` to scaffold a template, then add your ANSI art
 
**Q: What if I don't want colors on startup?**
A: Use `Add-ColorScriptProfile -SkipStartupScript` to import without auto-display
 
**Q: Can I use this on macOS/Linux?**
A: Yes, with PowerShell 7+ which runs cross-platform
 
**Q: How do I share colorscripts with colleagues?**
A: Export metadata with `Export-ColorScriptMetadata` or share script files
 
**Q: Is caching always enabled?**
A: No, use `-NoCache` to disable caching for development/testing
 
### BEST PRACTICES
 
1. **Install from PowerShell Gallery**: Use `Install-Module` for automatic updates
2. **Add to Profile**: Use `Add-ColorScriptProfile` for automatic startup integration
3. **Pre-build Cache**: Run `New-ColorScriptCache` after installation for optimal performance
4. **Use Meaningful Naming**: When creating custom scripts, use descriptive names
5. **Keep Metadata Updated**: Update ScriptMetadata.psd1 when adding scripts
6. **Test in Different Terminals**: Verify scripts display correctly across your environments
7. **Monitor Cache Size**: Periodically check cache directory size and clean if needed
8. **Use Categories/Tags**: Leverage filtering for faster script discovery
9. **Document Custom Scripts**: Add descriptions and tags to custom colorscripts
10. **Backup Configuration**: Export configuration before major changes
 
### VERSION HISTORY
 
#### Version 2025.10.09
- Sistema di caching migliorato con cache a livello di sistema operativo
- Miglioramento delle prestazioni da 6 a 19 volte
- Posizione cache centralizzata in AppData
- 450++ colorscript inclusi
- Documentazione di aiuto completa basata su commenti
- Miglioramenti al manifest del modulo
- Gestione configurazione avanzata
- Capacità di esportazione metadati
- Helper di integrazione profilo
 
### COPYRIGHT
 
Copyright (c) 2025. All rights reserved.
 
### LICENSE
 
Licensed under MIT License. See LICENSE file for details.