GiantCroissant.Lunar.Build.Configuration 0.1.1-ci.90

Configuration Components

This directory contains shared configuration interfaces and implementations for NUKE build automation.

Components

IWrapperPath (replaces IWrapperPathComponent)

A simplified, reusable interface that provides wrapper script integration for location-independent builds with priority-based path resolution and smart configuration discovery.

Deprecation: IWrapperPathComponent has been replaced by IWrapperPath. Please migrate any remaining references.

Overview

The IWrapperPath solves the common problem of JSON configuration discovery in multi-project workspaces by providing:

• Priority-based parameter resolution: Script parameters → Environment variables → Auto-detection
• Location-independent builds: Execute builds from any directory without fragile relative paths
• Smart configuration discovery: Automatically find project-specific build-config.json files
• Cross-platform compatibility: Works with both PowerShell and CMD wrapper scripts

Features

• 🎯 Parameter Priority System: Script parameters take precedence over environment variables
• 📍 Auto-detection: Automatically detect project root from script location
• 🔍 Smart Config Discovery: Find project-specific configuration files using validation patterns
• 🏗️ Location Independence: Execute builds from any working directory
• 🛠️ Debug Support: Built-in DebugWrapper target for troubleshooting

Implementation

To use IWrapperPath in your build class:

partial class Build : 
    NukeBuild, 
    IGeneralizedBuildComponent,
    IWrapperPath           // Add this interface
{
    // 1. Define project-specific configuration identifiers
    public string[] ProjectConfigIdentifiers => new[]
    {
        "com.yourcompany.yourproject",
        "scoped-1234",
        "Your Project Name"
    };

    // 2. Add wrapper parameter properties with NUKE Parameter attributes
    [Parameter("NUKE root directory override from wrapper script", Name = "wrapper-nuke-root")]
    readonly string? _wrapperNukeRootParam;
    
    [Parameter("Config path override from wrapper script", Name = "wrapper-config-path")] 
    readonly string? _wrapperConfigPathParam;
    
    [Parameter("Script directory from wrapper script", Name = "wrapper-script-dir")]
    readonly string? _wrapperScriptDirParam;
    
    // 3. Implement interface properties
    public string? WrapperNukeRootParam => _wrapperNukeRootParam;
    public string? WrapperConfigPathParam => _wrapperConfigPathParam; 
    public string? WrapperScriptDirParam => _wrapperScriptDirParam;

    // 4. Use WrapperNukeRoot/WrapperConfigPath for path resolution
    private IBuildConfigurationProvider ConfigProvider
    {
        get
        {
            if (_configProvider == null)
            {
                _configProvider = new BuildConfigurationProvider();
                var root = WrapperNukeRoot; // From interface
                var configPath = WrapperConfigPath; // From interface
                _configProvider.LoadConfiguration(root, configPath);
            }
            return _configProvider;
        }
    }
}

Wrapper Script Integration

Create wrapper scripts in your project's build/nuke/scripts/ directory:

PowerShell: build-with-root.ps1

[CmdletBinding()]
Param(
    [Parameter(Mandatory=$false)]
    [string]$NukeRoot,
    
    [Parameter(Mandatory=$false)]
    [string]$ConfigPath,
    
    [Parameter(Position=0,Mandatory=$false,ValueFromRemainingArguments=$true)]
    [string[]]$BuildArguments
)

# Set environment variables and parameters
if ($NukeRoot) {
    $env:WRAPPER_NUKE_ROOT = $NukeRoot
}

if ($ConfigPath) {
    $env:WRAPPER_CONFIG_PATH = $ConfigPath  
}

if ($PSScriptRoot) {
    $env:WRAPPER_SCRIPT_DIR = $PSScriptRoot
}

# Auto-detect project root (3 levels up from scripts/)
if (-not $NukeRoot -and $PSScriptRoot) {
    $DetectedRoot = Split-Path (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent) -Parent
    $env:WRAPPER_NUKE_ROOT = $DetectedRoot
}

# Build final arguments with wrapper parameters
$FinalBuildArguments = @()

if ($NukeRoot) {
    $FinalBuildArguments += "--wrapper-nuke-root=$NukeRoot"
}

if ($ConfigPath) {
    $FinalBuildArguments += "--wrapper-config-path=$ConfigPath"
}

if ($PSScriptRoot) {
    $FinalBuildArguments += "--wrapper-script-dir=$PSScriptRoot"
}

if ($env:WRAPPER_NUKE_ROOT) {
    $FinalBuildArguments += "--root=$($env:WRAPPER_NUKE_ROOT)"
}

if ($BuildArguments) {
    $FinalBuildArguments += $BuildArguments
}

# Change to project root and execute build
$BuildScript = Join-Path (Split-Path $PSScriptRoot -Parent) "build.ps1"
$OriginalLocation = Get-Location

if ($env:WRAPPER_NUKE_ROOT -and (Test-Path $env:WRAPPER_NUKE_ROOT)) {
    Set-Location $env:WRAPPER_NUKE_ROOT
}

try {
    & $BuildScript @FinalBuildArguments
    $exitCode = $LASTEXITCODE
} finally {
    Set-Location $OriginalLocation
}

exit $exitCode

CMD: build-with-root.cmd

@echo off
setlocal

REM Auto-detect project root from script location
for %%I in (%~dp0..) do set "NUKE_DIR=%%~fI"
for %%I in (%NUKE_DIR%\..) do set "BUILD_DIR=%%~fI"  
for %%I in (%BUILD_DIR%\..) do set "PROJECT_ROOT=%%~fI"

REM Set environment variables
set WRAPPER_SCRIPT_DIR=%~dp0
set WRAPPER_NUKE_ROOT=%PROJECT_ROOT%

REM Change to project root and execute build
cd /d "%PROJECT_ROOT%"
call "%NUKE_DIR%\build.cmd" --wrapper-script-dir="%WRAPPER_SCRIPT_DIR%" --root="%PROJECT_ROOT%" %*

Usage Examples

From Project Root:

# Using PowerShell wrapper
./build/nuke/scripts/build-with-root.ps1 BuildAll

# Using CMD wrapper  
./build/nuke/scripts/build-with-root.cmd BuildAll

From Any Directory:

# Explicit paths
./build-with-root.ps1 -NukeRoot "C:\my-project" -ConfigPath "C:\my-project\build\nuke\build-config.json" BuildAll

# Auto-detection (script automatically detects project root)
./build-with-root.ps1 BuildAll

Debug Wrapper Functionality:

./build-with-root.ps1 DebugWrapper

Path Resolution Priority

The component uses a 3-level priority system:

1. Script Parameters (Highest Priority)

   • --wrapper-nuke-root=<path>
   • --wrapper-config-path=<path>
   • --wrapper-script-dir=<path>

2. Environment Variables (Medium Priority)

   • WRAPPER_NUKE_ROOT
   • WRAPPER_CONFIG_PATH
   • WRAPPER_SCRIPT_DIR

3. Auto-detection (Fallback)

   • Project root: 3 levels up from script directory
   • Config path: ../build-config.json relative to script directory
   • Assembly location-based discovery

Configuration Discovery

The component automatically discovers project-specific build-config.json files using:

1. Explicit Config Path: Use WrapperConfigPath if provided and valid
2. Script-based Discovery: Auto-detect from script directory location
3. Assembly-based Search: Search up directory tree from build assembly location
4. Smart Validation: Only accept configs containing ProjectConfigIdentifiers patterns

Benefits

Before (Project-specific Implementation):

• ~200 lines of duplicated wrapper code per project
• Manual parameter handling and path resolution
• Inconsistent discovery logic across projects
• Difficult to maintain and update

After (IWrapperPath Interface):

• ~50 lines per project (just parameter declarations and interface implementation)
• Centralized, tested wrapper functionality
• Consistent behavior across all projects
• Single location for improvements and bug fixes

Migration Guide

To migrate existing wrapper implementations to use IWrapperPath:

1. Add Interface: Implement IWrapperPath in your build class
2. Remove Duplicated Code: Delete local wrapper implementation methods
3. Update Properties: Use interface properties (WrapperNukeRoot, WrapperConfigPath)
4. Define Identifiers: If needed by downstream logic
5. Test: Verify wrapper functionality with DebugWrapper target

Troubleshooting

Config Not Found:

• Check ProjectConfigIdentifiers match your build-config.json content
• Verify script directory structure (scripts should be 3 levels down from project root)
• Use DebugWrapper target to see path resolution details

Environment Variables Not Working:

• Ensure wrapper scripts set environment variables before calling NUKE
• Check parameter priority - script parameters override environment variables
• Verify working directory is set correctly in wrapper scripts

Build Failures:

• Confirm .nuke directory exists in project root
• Check that build-config.json exists and contains valid JSON
• Verify project structure matches expected layout

Architecture Benefits

The IWrapperPath provides:

• Code Reuse: Eliminates ~800 lines of duplicated wrapper code across 4 projects
• Maintainability: Single source of truth for wrapper functionality
• Consistency: Uniform behavior across all consuming projects
• Location Independence: Execute builds from any directory without path issues
• Smart Discovery: Automatic configuration file detection with validation
• Cross-platform: Works with PowerShell, CMD, and bash wrapper scripts