provisioning/docs/src/architecture/adr/adr-018-help-system-fluent-integration.md

ADR-018: Help System Fluent Integration & Data-Driven Architecture

Status: Proposed Date: 2026-01-13 Author: Architecture Team Supersedes: Hardcoded help strings in main_provisioning/help_system.nu

Context

The current help system in main_provisioning/help_system.nu (1303 lines) consists almost entirely of hardcoded string concatenation with embedded ANSI formatting codes:

def help-infrastructure [] {
    print "╔════════════════════════════════════════════════════╗"
    print "║   SERVER & INFRASTRUCTURE                          ║"
    print "╚════════════════════════════════════════════════════╝"
}

Current Problems:

1. No Internationalization: Help text trapped in English-only code
2. Hard to Maintain: Updating text requires editing Nushell code
3. Mixed Concerns: Content (strings) mixed with presentation (ANSI codes)
4. No Hot-Reload: Changes require recompilation
5. Difficult to Test: String content buried in function definitions

Problem Statement

Metrics:

• 1303 lines of code-embedded help text
• 17 help categories with 65 strings total
• All help functions manually maintained
• No separation of data from presentation

Decision

Implement Data-Driven Help with Mozilla Fluent Integration:

1. Extract help content to Fluent files (.ftl format)
2. Support multilingual help (English base, Spanish translations)
3. Implement runtime language resolution via LANG environment variable
4. Reduce help_system.nu to wrapper functions only

Architecture

Help Content (Fluent Files)
  ├─ en-US/help.ftl (65 strings - English base)
  └─ es-ES/help.ftl (65 strings - Spanish translations)

Language Detection & Loading
  ├─ Check LANG environment variable
  ├─ Load appropriate Fluent file
  └─ Implement fallback chain (es-ES → en-US)

Help System Wrapper
  ├─ help-main [] - Display main menu
  ├─ help-infrastructure [] - Infrastructure category
  ├─ help-orchestration [] - Orchestration category
  └─ help-setup [] - Setup category

User Interface
  ├─ LANG=en_US provisioning help infrastructure
  └─ LANG=es_ES provisioning help infrastructure

Implementation

1. Fluent File Structure

en-US/help.ftl:

help-main-title = PROVISIONING SYSTEM
help-main-subtitle = Layered Infrastructure Automation
help-main-categories = COMMAND CATEGORIES
help-main-categories-hint = Use 'provisioning help <category>' for details
help-main-infrastructure-name = infrastructure
help-main-infrastructure-desc = Server, taskserv, cluster, VM, and infra management
help-main-orchestration-name = orchestration
help-main-orchestration-desc = Workflow, batch operations, and orchestrator control
help-infrastructure-title = SERVER & INFRASTRUCTURE
help-infra-server = Server Operations
help-infra-server-create = Create a new server
help-infra-server-list = List all servers
help-infra-server-status = Show server status
help-infra-taskserv = TaskServ Management
help-infra-taskserv-create = Deploy taskserv to server
help-infra-cluster = Cluster Management
help-infra-vm = Virtual Machine Operations
help-orchestration-title = ORCHESTRATION & WORKFLOWS
help-orch-control = Orchestrator Management
help-orch-start = Start orchestrator [--background]
help-orch-workflows = Single Task Workflows
help-orch-batch = Multi-Provider Batch Operations

es-ES/help.ftl (Spanish translations):

help-main-title = SISTEMA DE PROVISIÓN
help-main-subtitle = Automatización de Infraestructura por Capas
help-main-categories = CATEGORÍAS DE COMANDOS
help-main-categories-hint = Use 'provisioning help <categoría>' para más detalles
help-main-infrastructure-name = infraestructura
help-main-infrastructure-desc = Gestión de servidores, taskserv, clusters, VM e infraestructura
help-main-orchestration-name = orquestación
help-main-orchestration-desc = Flujos de trabajo, operaciones por lotes y control del orquestador
help-infrastructure-title = SERVIDOR E INFRAESTRUCTURA
help-infra-server = Operaciones de Servidor
help-infra-server-create = Crear un nuevo servidor
help-infra-server-list = Listar todos los servidores
help-infra-server-status = Mostrar estado del servidor
help-infra-taskserv = Gestión de TaskServ
help-infra-taskserv-create = Desplegar taskserv en servidor
help-infra-cluster = Gestión de Clusters
help-infra-vm = Operaciones de Máquinas Virtuales
help-orchestration-title = ORQUESTACIÓN Y FLUJOS DE TRABAJO
help-orch-control = Gestión del Orquestador
help-orch-start = Iniciar orquestador [--background]
help-orch-workflows = Flujos de Trabajo de Tarea Única
help-orch-batch = Operaciones por Lotes Multi-Proveedor

2. Fluent Loading in Nushell

def load-fluent-file [category: string] {
    let lang = ($env.LANG? | default "en_US" | str replace "_" "-")
    let fluent_path = $"provisioning/locales/($lang)/help.ftl"

    # Parse Fluent file and extract strings for category
    # Fallback to en-US if lang not available
}

3. Help System Wrapper

export def help-infrastructure [] {
    let strings = (load-fluent-file "infrastructure")

    # Apply formatting and render
    print $"╔════════════════════════════════════════════════════╗"
    print $"║   ($strings.title | str upcase)                   ║"
    print $"╚════════════════════════════════════════════════════╝"
}

Consequences

Positive

• Internationalization Ready: Easy to add new languages (Portuguese, French, Japanese)
• Data/Presentation Separation: Content in Fluent, formatting in Nushell
• Maintainability: Edit Fluent files, not Nushell code
• Hot-Reload Support: Can update help text without recompilation
• Testing: Help content testable independently from rendering
• Code Reduction: 1303 lines → ~50 lines (wrapper) + ~700 lines (Fluent data)

Negative

• Tool Complexity: Need Fluent parser and loader
• Fallback Chain Management: Must handle missing translations gracefully
• Performance: File I/O for loading translations (mitigated by caching)

Integration Strategy

Phase 1: Infrastructure & Extraction

• ✅ Create provisioning/locales/ directory structure
• ✅ Create i18n-config.toml with locale configuration
• ✅ Extract strings to en-US/help.ftl (65 strings)
• ✅ Create Spanish translations es-ES/help.ftl

Phase 2: Integration (This Task)

• Modify help_system.nu to load from Fluent
• Implement language detection ($env.LANG)
• Implement fallback chain logic
• Test with LANG=en_US and LANG=es_ES

Phase 3: Validation & Documentation

• Comprehensive integration tests
• Performance benchmarks
• Documentation for adding new languages
• Examples in provisioning/docs/

Language Resolution Flow

1. Check LANG environment variable
   LANG=es_ES.UTF-8 → extract "es_ES" or "es-ES"

2. Check if locale file exists
   provisioning/locales/es-ES/help.ftl exists? → YES

3. Load locale file
   Parse and extract help strings

4. On missing key:
   Check fallback chain in i18n-config.toml
   es-ES → en-US

5. Render with formatting
   Apply ANSI codes, boxes, alignment

Testing Strategy

Unit Tests

# Test language detection
LANG=en_US provisioning help infrastructure
# Expected: English output

LANG=es_ES provisioning help infrastructure
# Expected: Spanish output

LANG=fr_FR provisioning help infrastructure
# Expected: Fallback to English (fr-FR not available)

File Structure

provisioning/
├── locales/
│   ├── i18n-config.toml           # Locale metadata & fallback chains
│   ├── en-US/
│   │   └── help.ftl               # 65 English help strings
│   └── es-ES/
│       └── help.ftl               # 65 Spanish help strings
└── core/nulib/main_provisioning/
    └── help_system.nu             # ~50 lines (wrapper only)

Configuration

i18n-config.toml defines:

[locales]
default = "en-US"
fallback = "en-US"

[locales.en-US]
name = "English (United States)"

[locales.es-ES]
name = "Spanish (Spain)"

[fallback_chains]
es-ES = ["en-US"]

Related ADRs

• ADR-010: Configuration Format Strategy
• ADR-011: Nickel Migration
• ADR-013: TypeDialog Integration (forms also use Fluent)

Open Questions

1. Should help strings support Fluent attributes for metadata?
2. Should we implement Fluent caching for performance?
3. How do we handle dynamic help (commands not in Fluent)?
4. Should help system auto-update when Fluent files change?

References

• Mozilla Fluent: https://projectfluent.org/
• Fluent Syntax: https://projectfluent.org/fluent/guide/
• Nushell 0.109 Guidelines: .claude/guidelines/nushell.md
• Current Help Implementation: provisioning/core/nulib/main_provisioning/help_system.nu
• Fluent Files: provisioning/locales/{en-US,es-ES}/help.ftl