Skip to content

bruce48x/Lakona / .agents/skills/lakona-e2e-testing

lakona-e2e-testing

Verified

Verify Lakona.Tool generated projects through real RPC using local source, local packages, or nuget.org; excludes unit-only and client UI testing.

FileKindSize
SKILL.mdskill md5.7 KB
agents/openai.yamlconfig309 B
references/commands.mdmarkdown7.6 KB
references/execution.mdmarkdown4.0 KB
references/failure-triage.mdmarkdown2.4 KB
scripts/run-e2e.ps1script49.4 KB

scripts/run-e2e.ps1

View on GitHub
#Requires -Version 7.0
<#
.SYNOPSIS
    Unified E2E validation for Lakona.Tool scaffolded projects.

.DESCRIPTION
    Scaffolds, builds, and runtime-verifies Lakona.Tool generated projects
    with three dependency modes:

    ProjectReference — fastest dev feedback. Patches scaffolded csproj to
      reference local source directly. No NuGet packing needed.

    LocalFeed — pre-publish validation. Packs current src/Lakona.* projects
      into a local NuGet feed and validates the generated project against
      those packages. Simulates what users get after publishing.

    NuGetOrg — post-publish verification. Uses published packages from
      nuget.org (no local feed). Validates the real user experience.
#>

[CmdletBinding()]
param(
    [ValidateSet("ProjectReference", "LocalFeed", "NuGetOrg")]
    [string]$Feed = "ProjectReference",

    [ValidateSet("all", "unity", "tuanjie", "godot")]
    [string]$Engine = "godot",

    [ValidateSet("all", "tcp", "kcp", "websocket")]
    [string]$Transport = "websocket",

    [ValidateSet("all", "json", "memorypack")]
    [string]$Serializer = "memorypack",

    [ValidateSet("all", "memory", "postgres", "redis", "mysql")]
    [string]$MembershipProvider = "memory",

    [switch]$SkipRuntime,

    [switch]$Compose,

    [switch]$KeepScaffolds,

    [switch]$FindAvailablePort,

    [int]$Port = 20000,

    [string]$WorkDir = ".tmp/lakona-e2e"
)

$ErrorActionPreference = "Stop"
$runRuntime = -not $SkipRuntime

if ($Compose -and $Feed -eq "ProjectReference") {
    throw "Compose requires -Feed LocalFeed or NuGetOrg so the Docker build context is self-contained."
}

if ($runRuntime -and $MembershipProvider -ne "memory") {
    throw "Runtime verification currently supports -MembershipProvider memory only. Use -SkipRuntime to validate external-provider scaffolding and builds; provider runtime contracts run in Daily Validation."
}

# ═══════════════════════════════════════════════════════════════════════════════
# Helper Functions
# ═══════════════════════════════════════════════════════════════════════════════

function Write-Banner {
    param([string]$Text)

    Write-Host ""
    Write-Host ("=" * 72) -ForegroundColor Cyan
    Write-Host "  $Text" -ForegroundColor Cyan
    Write-Host ("=" * 72) -ForegroundColor Cyan
}

function Format-ReportCell {
    param([string]$Value)

    if ([string]::IsNullOrWhiteSpace($Value)) {
        return ""
    }

    return ($Value -replace "`r?`n", "<br>" -replace "\|", "\|")
}

function Invoke-LoggedNativeCommand {
    param(
        [string]$LogPath,
        [string]$FilePath,
        [string[]]$ArgumentList
    )

    $logDir = Split-Path -Parent $LogPath
    if (-not [string]::IsNullOrWhiteSpace($logDir)) {
        New-Item -ItemType Directory -Force -Path $logDir | Out-Null
    }

    $output = & $FilePath @ArgumentList 2>&1
    $exitCode = $LASTEXITCODE
    $text = ($output | Out-String).TrimEnd()
    Set-Content -LiteralPath $LogPath -Value $text -Encoding UTF8

    if (-not [string]::IsNullOrWhiteSpace($text)) {
        Write-Host $text
    }

    $lines = $text -split "`r?`n"
    $tail = ($lines | Select-Object -Last 40) -join "`n"

    return [pscustomobject]@{
        ExitCode = $exitCode
        Output = $text
        Tail = $tail
        LogPath = $LogPath
    }
}

function Resolve-RepoRoot {
    $current = Resolve-Path "."
    while ($current) {
        if (Test-Path (Join-Path $current "CONTRIBUTING.md")) {
            return $current.Path
        }

        $parent = Split-Path -Parent $current
        if ([string]::IsNullOrWhiteSpace($parent) -or $parent -eq $current) {
            break
        }

        $current = Resolve-Path $parent
    }

    throw "Could not find repository root containing CONTRIBUTING.md."
}

function Get-TransportPackageName {
    param([string]$Value)

    switch ($Value.ToLowerInvariant()) {
        "tcp" { "Lakona.Rpc.Transport.Tcp" }
        "kcp" { "Lakona.Rpc.Transport.Kcp" }
        "websocket" { "Lakona.Rpc.Transport.WebSocket" }
        default { throw "Unsupported transport: $Value" }
    }
}

function Get-SerializerPackageName {
    param([string]$Value)

    switch ($Value.ToLowerInvariant()) {
        "json" { "Lakona.Rpc.Serializer.Json" }
        "memorypack" { "Lakona.Rpc.Serializer.MemoryPack" }
        default { throw "Unsupported serializer: $Value" }
    }
}

function Get-TransportUsing {
    param([string]$Value)

    switch ($Value.ToLowerInvariant()) {
        "tcp" { "using Lakona.Rpc.Transport.Tcp;" }
        "kcp" { "using Lakona.Rpc.Transport.Kcp;" }
        "websocket" { "using Lakona.Rpc.Transport.WebSocket;" }
        default { throw "Unsupported transport: $Value" }
    }
}

function Get-SerializerUsing {
    param([string]$Value)

    switch ($Value.ToLowerInvariant()) {
        "json" { "using Lakona.Rpc.Serializer.Json;" }
        "memorypack" { "using Lakona.Rpc.Serializer.MemoryPack;" }
        default { throw "Unsupported serializer: $Value" }
    }
}

function Get-TransportConstructor {
    param(
        [string]$Value,
        [int]$Port
    )

    switch ($Value.ToLowerInvariant()) {
        "tcp" { "new TcpTransport(`"127.0.0.1`", $Port)" }
        "kcp" { "new KcpTransport(`"127.0.0.1`", $Port)" }
        "websocket" { "new WsTransport(`"ws://127.0.0.1:$Port/ws`")" }
        default { throw "Unsupported transport: $Value" }
    }
}

function Get-SerializerConstructor {
    param([string]$Value)

    switch ($Value.ToLowerInvariant()) {
        "json" { "new JsonRpcSerializer()" }
        "memorypack" { "new MemoryPackRpcSerializer()" }
        default { throw "Unsupported serializer: $Value" }
    }
}

function Get-LocalPackageVersion {
    param(
        [string]$FeedDir,
        [string]$PackageId
    )

    $prefix = "$PackageId."
    $package = Get-ChildItem -LiteralPath $FeedDir -Filter "$PackageId.*.nupkg" |
        Sort-Object LastWriteTimeUtc -Descending |
        Select-Object -First 1

    if (-not $package) {
        throw "Local feed is missing $PackageId."
    }

    $name = [System.IO.Path]::GetFileNameWithoutExtension($package.Name)
    if (-not $name.StartsWith($prefix, [StringComparison]::Ordinal)) {
        throw "Could not parse package version from $($package.Name)."
    }

    return $name.Substring($prefix.Length)
}

function Get-ClientPackageVersion {
    param(
        [string]$ProjectDir,
        [Parameter(Mandatory)]
        [ValidateSet("godot", "unity", "tuanjie")]
        [string]$Engine,
        [string]$PackageId
    )

    $isSdk = $Engine -eq "godot"
    $relativePath = if ($isSdk) { "Client/Client.csproj" } else { "Client/Assets/packages.config" }
    $manifestPath = Join-Path $ProjectDir $relativePath
    if (-not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) {
        throw "Client dependency file missing for package '$PackageId': $manifestPath"
    }
    [xml]$xml = Get-Content -LiteralPath $manifestPath -Raw
    # Match the actual client manifest, with or without an XML namespace. Do not
    # evaluate MSBuild properties or fall back to server/repository/latest versions.
    $xpath = if ($isSdk) {
        "/*[local-name()='Project']/*[local-name()='ItemGroup']/*[local-name()='PackageReference']"
    } else {
        "/*[local-name()='packages']/*[local-name()='package']"
    }
    $idAttribute = if ($isSdk) { "Include" } else { "id" }
    $versionAttribute = if ($isSdk) { "Version" } else { "version" }
    $references = @($xml.SelectNodes($xpath) | Where-Object { $_.GetAttribute($idAttribute) -ieq $PackageId })
    if ($references.Count -eq 0) {
        throw "Client package '$PackageId' missing from $manifestPath"
    }

    $versions = @(foreach ($reference in $references) {
        $values = @(
            if ($reference.HasAttribute($versionAttribute)) { $reference.GetAttribute($versionAttribute) }
            if ($isSdk) {
                foreach ($node in $reference.SelectNodes("*[local-name()='Version']")) { $node.InnerText }
            }
        )
        if ($values.Count -eq 0) {
            throw "Client package '$PackageId' has no version in $manifestPath"
        }
        foreach ($value in $values) {
            if ([string]::IsNullOrWhiteSpace($value)) {
                throw "Client package '$PackageId' has an empty version in $manifestPath"
            }
            $literal = $value.Trim()
            if ($literal -match '\$\(|[*\[\](),\s]') {
                throw "Client package '$PackageId' needs a literal version in $manifestPath; found '$literal'"
            }
            $literal
        }
    })
    $versions = @($versions | Sort-Object -Unique)
    if ($versions.Count -ne 1) {
        throw "Client package '$PackageId' has conflicting versions in ${manifestPath}: $($versions -join ', ')"
    }
    return $versions[0]
}

function Write-NuGetConfig {
    param(
        [string]$Path,
        [string]$FeedDir,
        [bool]$IncludeNuGetOrg = $true
    )

    $escapedFeed = if ($FeedDir) {
        [System.Security.SecurityElement]::Escape($FeedDir)
    } else {
        ""
    }

    $lines = @('<?xml version="1.0" encoding="utf-8"?>')
    $lines += '<configuration>'
    $lines += '  <packageSources>'
    $lines += '    <clear />'

    if ($FeedDir) {
        $lines += "    <add key=`"local-lakona`" value=`"$escapedFeed`" />"
    }

    if ($IncludeNuGetOrg) {
        $lines += '    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />'
    }

    $lines += '  </packageSources>'
    $lines += '</configuration>'

    $lines -join "`n" | Set-Content -LiteralPath $Path -Encoding UTF8
}

function Set-GeneratedServerPort {
    param(
        [string]$ProjectDir,
        [int]$Port,
        [int]$ClusterPort = ($Port + 1000),
        [int]$ManagementPort = ($Port + 2000)
    )

    $appSettings = Join-Path $ProjectDir "Server/App/appsettings.json"
    if (-not (Test-Path $appSettings)) {
        return
    }

    $config = Get-Content -LiteralPath $appSettings -Raw | ConvertFrom-Json
    $endpoints = @($config.Lakona.Endpoints)
    if ($endpoints.Count -eq 0) {
        throw "Generated server configuration has no Lakona:Endpoints entry: $appSettings"
    }

    foreach ($endpoint in $endpoints) {
        $endpoint.Port = $Port
    }

    if ($null -eq $config.Lakona.Cluster) {
        $config.Lakona | Add-Member -NotePropertyName "Cluster" -NotePropertyValue ([pscustomobject]@{})
    }

    $config.Lakona.Cluster | Add-Member `
        -NotePropertyName "Endpoint" `
        -NotePropertyValue "tcp://127.0.0.1:$ClusterPort" `
        -Force

    $config.Lakona.Management.Http | Add-Member `
        -NotePropertyName "Port" `
        -NotePropertyValue $ManagementPort `
        -Force

    $config | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath $appSettings -Encoding UTF8
}

function Test-PortAvailable {
    param([int]$Port)

    $tcpSocket = $null
    $udpSocket = $null

    try {
        $endpoint = [System.Net.IPEndPoint]::new(
            [System.Net.IPAddress]::Loopback,
            $Port)

        $tcpSocket = [System.Net.Sockets.Socket]::new(
            [System.Net.Sockets.AddressFamily]::InterNetwork,
            [System.Net.Sockets.SocketType]::Stream,
            [System.Net.Sockets.ProtocolType]::Tcp)
        $tcpSocket.ExclusiveAddressUse = $true
        $tcpSocket.Bind($endpoint)

        $udpSocket = [System.Net.Sockets.Socket]::new(
            [System.Net.Sockets.AddressFamily]::InterNetwork,
            [System.Net.Sockets.SocketType]::Dgram,
            [System.Net.Sockets.ProtocolType]::Udp)
        $udpSocket.ExclusiveAddressUse = $true
        $udpSocket.Bind($endpoint)

        return $true
    } catch [System.Net.Sockets.SocketException] {
        return $false
    } finally {
        if ($tcpSocket) {
            $tcpSocket.Dispose()
        }

        if ($udpSocket) {
            $udpSocket.Dispose()
        }
    }
}

function Find-AvailablePortBase {
    param(
        [int]$PreferredPort,
        [int]$CaseCount
    )

    $highestBase = 65535 - 2000 - $CaseCount + 1
    if ($PreferredPort -lt 1 -or $PreferredPort -gt $highestBase) {
        throw "The preferred port $PreferredPort cannot provide $CaseCount consecutive business, cluster, and management ports in the valid range 1-65535."
    }

    for ($candidate = $PreferredPort; $candidate -le $highestBase; $candidate++) {
        $available = $true
        for ($offset = 0; $offset -lt $CaseCount -and $available; $offset++) {
            foreach ($portOffset in @(0, 1000, 2000)) {
                if (-not (Test-PortAvailable ($candidate + $offset + $portOffset))) {
                    $available = $false
                    break
                }
            }
        }

        if ($available) {
            return $candidate
        }
    }

    throw "Could not find $CaseCount consecutive free business, cluster, and management port sets starting at $PreferredPort."
}

function Stop-ProcessTree {
    param([System.Diagnostics.Process]$Process)

    if ($null -eq $Process -or $Process.HasExited) {
        return
    }

    try {
        $Process.Kill($true)
        $Process.WaitForExit(5000) | Out-Null
    } catch {
        Stop-Process -Id $Process.Id -Force -ErrorAction SilentlyContinue
    }
}

# ═══════════════════════════════════════════════════════════════════════════════
# E2E Client Generation
# ═══════════════════════════════════════════════════════════════════════════════

function New-E2EClient {
    param(
        [string]$ProjectDir,
        [Parameter(Mandatory)]
        [ValidateSet("godot", "unity", "tuanjie")]
        [string]$Engine,
        [string]$Transport,
        [string]$Serializer,
        [int]$Port,
        [string]$Feed,
        [string]$FeedDir,
        [string]$RepoRoot
    )

    $e2eDir = Join-Path $ProjectDir "E2EVerification"
    New-Item -ItemType Directory -Force -Path $e2eDir | Out-Null

    $sharedProj = (Resolve-Path (Join-Path $ProjectDir "Shared/Shared.csproj")).Path
    $transportPkg = Get-TransportPackageName $Transport
    $serializerPkg = Get-SerializerPackageName $Serializer

    # Build the csproj based on feed mode
    $csprojContent = @"
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
"@

    if ($Feed -eq "ProjectReference") {
        # ProjectReference mode must model compiler wiring that package mode
        # receives from Lakona.Rpc.Core's buildTransitive assets.
        $csprojContent += @"

  <ItemGroup>
    <ProjectReference Include="$RepoRoot\src\Lakona.Game.Client\Lakona.Game.Client.csproj" />
    <ProjectReference Include="$RepoRoot\src\$transportPkg\$transportPkg.csproj" />
    <ProjectReference Include="$RepoRoot\src\$serializerPkg\$serializerPkg.csproj" />
    <ProjectReference Include="$RepoRoot\src\Lakona.Rpc.Analyzers\Lakona.Rpc.Analyzers.csproj"
                      OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
    <ProjectReference Include="$sharedProj" />
  </ItemGroup>
"@
    } else {
        # PackageReference mode (LocalFeed or NuGetOrg)
        # Resolve versions
        if ($Feed -eq "LocalFeed") {
            $gameClientVersion = Get-LocalPackageVersion -FeedDir $FeedDir -PackageId "Lakona.Game.Client"
            $transportVersion = Get-LocalPackageVersion -FeedDir $FeedDir -PackageId $transportPkg
            $serializerVersion = Get-LocalPackageVersion -FeedDir $FeedDir -PackageId $serializerPkg
        } else {
            # NuGetOrg: verify exactly the dependencies generated for the client.
            $gameClientVersion = Get-ClientPackageVersion -ProjectDir $ProjectDir -Engine $Engine -PackageId "Lakona.Game.Client"
            $transportVersion = Get-ClientPackageVersion -ProjectDir $ProjectDir -Engine $Engine -PackageId $transportPkg
            $serializerVersion = Get-ClientPackageVersion -ProjectDir $ProjectDir -Engine $Engine -PackageId $serializerPkg
        }

        $csprojContent += @"

  <ItemGroup>
    <PackageReference Include="$transportPkg" Version="$transportVersion" />
    <PackageReference Include="$serializerPkg" Version="$serializerVersion" />
    <PackageReference Include="Lakona.Game.Client" Version="$gameClientVersion" />
    <ProjectReference Include="$sharedProj" />
  </ItemGroup>
"@
    }

    $csprojContent += @"
</Project>
"@

    Set-Content -LiteralPath (Join-Path $e2eDir "E2EVerification.csproj") -Value $csprojContent -Encoding UTF8

    # Write NuGet.config for package-based modes
    if ($Feed -ne "ProjectReference") {
        if ($Feed -eq "LocalFeed") {
            Write-NuGetConfig -Path (Join-Path $e2eDir "NuGet.config") -FeedDir $FeedDir -IncludeNuGetOrg $true
        } else {
            # NuGetOrg: only nuget.org source
            Write-NuGetConfig -Path (Join-Path $e2eDir "NuGet.config") -FeedDir $null -IncludeNuGetOrg $true
        }
    }

    # Generate Program.cs (same LakonaGameClient approach for all modes)
    $transportUsing = Get-TransportUsing $Transport
    $serializerUsing = Get-SerializerUsing $Serializer
    $transportCtor = Get-TransportConstructor $Transport $Port
    $serializerCtor = Get-SerializerConstructor $Serializer

    $program = @"
using Client.Generated;
using Shared.Contracts.Game;
using Lakona.Game.Client;
$transportUsing
$serializerUsing

try
{
    var transport = $transportCtor;
    var serializer = $serializerCtor;
    var options = new LakonaGameClientOptions(transport, serializer);
    var callbacks = new E2ECallbacks();
    await using var client = new LakonaGameClient(options, callbacks);

    Console.WriteLine("[E2E] Connecting to server...");
    await client.ConnectAsync();
    Console.WriteLine("[E2E] Connected.");

    var reply = await client.Api.Shared.Game.LoginAsync(
        new LoginRequest { PlayerName = "E2ETest" });
    var pushedWorld = await callbacks.WaitForWorldAsync(TimeSpan.FromSeconds(3));

    Console.WriteLine("[E2E] Success={0}, PlayerId={1}, LoginTick={2}, PushTick={3}", reply.Success, reply.PlayerId, reply.World.Tick, pushedWorld.Tick);
    if (reply.Success && reply.PlayerId > 0 &&
        reply.World.Players.Exists(player => player.PlayerId == reply.PlayerId && player.Name == "E2ETest") &&
        pushedWorld.Tick > reply.World.Tick)
    {
        Console.WriteLine("[E2E] SUCCESS");
        return;
    }

    Console.Error.WriteLine("[E2E] FAIL: Unexpected login response.");
    Environment.Exit(1);
}
catch (Exception ex)
{
    Console.Error.WriteLine("[E2E] FAIL: {0}", ex);
    Environment.Exit(1);
}

internal sealed class E2ECallbacks : IGameCallback
{
    private readonly TaskCompletionSource<WorldSnapshot> _world = new(TaskCreationOptions.RunContinuationsAsynchronously);

    public void OnWorldUpdated(WorldSnapshot snapshot)
    {
        _world.TrySetResult(snapshot);
    }

    public Task<WorldSnapshot> WaitForWorldAsync(TimeSpan timeout) => _world.Task.WaitAsync(timeout);
}
"@

    Set-Content -LiteralPath (Join-Path $e2eDir "Program.cs") -Value $program -Encoding UTF8
    return $e2eDir
}

# ═══════════════════════════════════════════════════════════════════════════════
# Server Dependency Patching (ProjectReference mode)
# ═══════════════════════════════════════════════════════════════════════════════

function Patch-ServerDependencies {
    param(
        [string]$ProjectDir,
        [string]$RepoRoot
    )

    # Patch the shared contract project and all server projects that may
    # reference Lakona packages.
    $projectFiles = @(
        Get-Item -LiteralPath (Join-Path $ProjectDir "Shared/Shared.csproj")
        Get-ChildItem -Path (Join-Path $ProjectDir "Server") -Recurse -Filter "*.csproj"
    )

    foreach ($csprojPath in $projectFiles) {
        $content = Get-Content $csprojPath -Raw -Encoding UTF8
        $modified = $false

        # Single pass: match all Lakona.* PackageReference elements,
        # both self-closing and those with child elements.
        $pattern = '(?s)<PackageReference\s+Include="(Lakona\.[^"]+)"\s+Version="[^"]*".*?(?:/>|</PackageReference>)'

        $matches = [regex]::Matches($content, $pattern)
        $replacements = @()
        foreach ($match in $matches) {
            $packageId = $match.Groups[1].Value
            $projectPath = Join-Path $RepoRoot "src/$packageId/$packageId.csproj"
            if (Test-Path $projectPath) {
                $replacements += [PSCustomObject]@{
                    Index = $match.Index
                    Length = $match.Length
                    OldValue = $match.Value
                    PackageId = $packageId
                }
            }
        }

        # Sort by index descending so we can replace without invalidating positions
        $replacements = $replacements | Sort-Object Index -Descending

        foreach ($r in $replacements) {
            $projectPath = Join-Path $RepoRoot "src/$($r.PackageId)/$($r.PackageId).csproj"
            $replacement = '<ProjectReference Include="' + $projectPath + '" />'
            $content = $content.Substring(0, $r.Index) + $replacement + $content.Substring($r.Index + $r.Length)
            $modified = $true
            Write-Host "    $($r.PackageId) -> ProjectReference" -ForegroundColor DarkGray
        }

        # Analyzer ProjectReferences do not flow transitively. Package mode gets
        # the RPC analyzer from Lakona.Rpc.Core, while source mode must attach
        # the internal analyzer project directly to projects that generate RPC.
        if ($content.Contains("<LakonaProjectRole>ServerApp</LakonaProjectRole>") -and
            -not $content.Contains("Lakona.Rpc.Analyzers.csproj")) {
            $analyzerProjectPath = Join-Path $RepoRoot "src/Lakona.Rpc.Analyzers/Lakona.Rpc.Analyzers.csproj"
            $analyzerReference = @"

  <ItemGroup>
    <ProjectReference Include="$analyzerProjectPath" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>
"@
            $content = $content.Replace("</Project>", "$analyzerReference`n</Project>")
            $modified = $true
            Write-Host "    Lakona.Rpc.Analyzers -> ProjectReference (analyzer)" -ForegroundColor DarkGray
        }

        # Package mode gets the Hotfix generator from Lakona.Game.Server.
        # ProjectReference mode must
        # attach the internal compiler project directly.
        if ($content.Contains("<LakonaProjectRole>") -and
            -not $content.Contains("Lakona.Game.Server.Hotfix.Generators.csproj")) {
            $hotfixAnalyzerProjectPath = Join-Path $RepoRoot "src/Lakona.Game.Server.Hotfix.Generators/Lakona.Game.Server.Hotfix.Generators.csproj"
            $hotfixAnalyzerReference = @"

  <ItemGroup>
    <ProjectReference Include="$hotfixAnalyzerProjectPath" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>
"@
            $content = $content.Replace("</Project>", "$hotfixAnalyzerReference`n</Project>")
            $modified = $true
            Write-Host "    Lakona.Game.Server.Hotfix.Generators -> ProjectReference (analyzer)" -ForegroundColor DarkGray
        }

        # buildTransitive assets do not flow through ProjectReference. Mirror
        # only the compiler-property wiring required by this source-mode
        # adapter, while generated package-mode projects stay free of it.
        $compilerVisibleProperties = @(
            "LakonaProjectRole"
        ) | Where-Object {
            $content.Contains("<$_>") -and
            -not $content.Contains("<CompilerVisibleProperty Include=`"$_`" />")
        }

        if ($compilerVisibleProperties.Count -gt 0) {
            $compilerVisibleItems = ($compilerVisibleProperties | ForEach-Object {
                "    <CompilerVisibleProperty Include=`"$_`" />"
            }) -join "`n"
            $compilerVisibleGroup = @"

  <ItemGroup>
$compilerVisibleItems
  </ItemGroup>
"@
            $content = $content.Replace("</Project>", "$compilerVisibleGroup`n</Project>")
            $modified = $true
            Write-Host "    CompilerVisibleProperty wiring -> source-mode adapter" -ForegroundColor DarkGray
        }

        if ($modified) {
            Set-Content -Path $csprojPath -Value $content -Encoding UTF8 -NoNewline
        }
    }

    Write-Host "  Patched shared and server csproj files for ProjectReference mode" -ForegroundColor DarkGray
}

# ═══════════════════════════════════════════════════════════════════════════════
# Main
# ═══════════════════════════════════════════════════════════════════════════════

$repoRoot = Resolve-RepoRoot
Set-Location $repoRoot

$workRoot = Join-Path $repoRoot $WorkDir
$feedDir = Join-Path $workRoot "feed"
$packageCache = Join-Path $workRoot "packages"
# Use relative paths for scaffold output to avoid Windows file-locking issues
# in TransactionalOutputWriter when passing absolute paths to --output.
$scaffoldRootRelative = Join-Path $WorkDir "scaffolds"
$scaffoldRoot = Join-Path $repoRoot $scaffoldRootRelative
$logRoot = Join-Path $workRoot "logs"
$reportPath = Join-Path $workRoot "report.md"
$summaryPath = Join-Path $workRoot "summary.json"

if ($Feed -eq "LocalFeed") {
    foreach ($localFeedPath in @($feedDir, $packageCache)) {
        if (Test-Path -LiteralPath $localFeedPath) {
            Remove-Item -LiteralPath $localFeedPath -Recurse -Force
        }
    }
}

New-Item -ItemType Directory -Force -Path $feedDir, $packageCache, $scaffoldRoot, $logRoot | Out-Null

$env:DOTNET_CLI_DO_NOT_USE_MSBUILD_SERVER = "1"

# Godot mock packages workaround (prevents SDK resolution from scanning C:\Program Files)
$scriptRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
$godotNupkgsPath = Join-Path $repoRoot "scripts/game/ci/mock-godot-nupkgs"
if (Test-Path $godotNupkgsPath) {
    $env:LAKONA_RPC_GODOT_NUPKGS = (Resolve-Path $godotNupkgsPath).Path
}

$engines = if ($Engine -eq "all") { @("unity", "tuanjie", "godot") } else { @($Engine) }
$transports = if ($Transport -eq "all") { @("tcp", "kcp", "websocket") } else { @($Transport) }
$serializers = if ($Serializer -eq "all") { @("json", "memorypack") } else { @($Serializer) }
$membershipProviders = if ($MembershipProvider -eq "all") { @("memory", "postgres", "redis", "mysql") } else { @($MembershipProvider) }
$total = $engines.Count * $transports.Count * $serializers.Count * $membershipProviders.Count

if ($FindAvailablePort) {
    $selectedPort = Find-AvailablePortBase -PreferredPort $Port -CaseCount $total
    if ($selectedPort -ne $Port) {
        Write-Host "Preferred port range starting at $Port is occupied; using $selectedPort instead." -ForegroundColor DarkYellow
        $Port = $selectedPort
    }
}

# ═══════════════════════════════════════════════════════════════════════════════
# Step 1: Pack local packages (LocalFeed mode only)
# ═══════════════════════════════════════════════════════════════════════════════

if ($Feed -eq "LocalFeed") {
    Write-Banner "[$Feed] Packing local Lakona packages"
    $env:NUGET_PACKAGES = $packageCache

    $packageProjects = Get-ChildItem -Path (Join-Path $repoRoot "src") -Recurse -Filter "Lakona.*.csproj" |
        Where-Object {
            [xml] $candidateProjectXml = Get-Content -LiteralPath $_.FullName -Raw
            $isPackable = @($candidateProjectXml.Project.PropertyGroup.IsPackable) | Select-Object -Last 1
            if ($null -eq $isPackable) {
                return $true
            }

            -not [string]::Equals(
                ([string] $isPackable).Trim(),
                "false",
                [System.StringComparison]::OrdinalIgnoreCase)
        } |
        Sort-Object FullName

    $packageInputProjects = @(
        foreach ($packageProject in $packageProjects) {
            [xml] $packageProjectXml = Get-Content -LiteralPath $packageProject.FullName -Raw
            foreach ($packageInput in $packageProjectXml.SelectNodes("/Project/ItemGroup/PackageInputProject")) {
                $include = ([string] $packageInput.Include).Trim()
                if ([string]::IsNullOrWhiteSpace($include)) {
                    continue
                }

                $inputPath = [System.IO.Path]::GetFullPath(
                    (Join-Path $packageProject.DirectoryName $include))
                if (-not (Test-Path -LiteralPath $inputPath -PathType Leaf)) {
                    throw "Package input project is missing: $inputPath"
                }

                Get-Item -LiteralPath $inputPath
            }
        }
    )
    $buildProjects = @($packageProjects) + $packageInputProjects |
        Sort-Object FullName -Unique

    $packSolution = Join-Path $workRoot "Lakona.LocalFeed.slnx"
    $solutionLines = [System.Collections.Generic.List[string]]::new()
    $solutionLines.Add("<Solution>")
    foreach ($project in $buildProjects) {
        $relativeProjectPath = [System.IO.Path]::GetRelativePath(
            $workRoot,
            $project.FullName).Replace("\", "/")
        $escapedProjectPath = [System.Security.SecurityElement]::Escape($relativeProjectPath)
        $solutionLines.Add("  <Project Path=`"$escapedProjectPath`" />")
    }
    $solutionLines.Add("</Solution>")
    $solutionLines | Set-Content -LiteralPath $packSolution -Encoding UTF8

    Write-Host "  Building $($buildProjects.Count) projects ($($packageProjects.Count) packages plus $($packageInputProjects.Count) package inputs) in one Release graph..." -ForegroundColor DarkGray
    dotnet build $packSolution -c Release --nologo -v q
    if ($LASTEXITCODE -ne 0) {
        throw "dotnet build failed for $packSolution."
    }

    Write-Host "  Packing $($packageProjects.Count) projects from the completed Release graph..." -ForegroundColor DarkGray
    dotnet pack $packSolution -c Release -o $feedDir --no-build --no-restore --nologo -v q
    if ($LASTEXITCODE -ne 0) {
        throw "dotnet pack failed for $packSolution."
    }

    $packages = @(Get-ChildItem -Path $feedDir -Filter "*.nupkg" -File |
        Where-Object { -not $_.Name.EndsWith(".snupkg", [System.StringComparison]::OrdinalIgnoreCase) })
    if ($packages.Count -ne $packageProjects.Count) {
        throw "Expected $($packageProjects.Count) local packages but found $($packages.Count) in $feedDir."
    }
}

# ═══════════════════════════════════════════════════════════════════════════════
# Step 2: Build Lakona.Tool
# ═══════════════════════════════════════════════════════════════════════════════

Write-Banner "[$Feed] Building Lakona.Tool"
dotnet build (Join-Path $repoRoot "src/Lakona.Tool/Lakona.Tool.csproj") --nologo -v q
if ($LASTEXITCODE -ne 0) {
    throw "Lakona.Tool build failed."
}

# ═══════════════════════════════════════════════════════════════════════════════
# Step 3: Test matrix
# ═══════════════════════════════════════════════════════════════════════════════

$results = New-Object System.Collections.Generic.List[object]
$index = 0

$lastCasePort = $Port + $total - 1
$lastClusterPort = $lastCasePort + 1000
$lastManagementPort = $lastCasePort + 2000
if ($Port -lt 1 -or $lastManagementPort -gt 65535) {
    throw "The base port $Port cannot provide $total consecutive business, cluster, and management ports in the valid range 1-65535."
}

foreach ($engineValue in $engines) {
    foreach ($transportValue in $transports) {
        foreach ($serializerValue in $serializers) {
          foreach ($membershipProviderValue in $membershipProviders) {
            $index++
            $casePort = $Port + $index - 1
            $clusterPort = $casePort + 1000
            $managementPort = $casePort + 2000
            $modeLabel = $Feed.Substring(0,1).ToUpperInvariant() + $Feed.Substring(1).ToLowerInvariant()
            $projectName = "E2E_${modeLabel}_${engineValue}_${transportValue}_${serializerValue}_${membershipProviderValue}" -replace "[^A-Za-z0-9_]", "_"
            $projectDir = Join-Path $scaffoldRoot $projectName
            $label = "[$index/$total] $Feed / $engineValue / $transportValue / $serializerValue / $membershipProviderValue"

            Write-Banner $label

            $result = [ordered]@{
                Engine = $engineValue
                Transport = $transportValue
                Serializer = $serializerValue
                MembershipProvider = $membershipProviderValue
                Feed = $Feed
                ServerHost = if ($Compose) { "Compose" } else { "Process" }
                Port = $casePort
                Scaffold = "FAIL"
                Build = "FAIL"
                Runtime = if ($runRuntime) { "FAIL" } else { "SKIP" }
                ProjectDir = $projectDir
                Error = ""
                ErrorDetail = ""
                LogPath = ""
            }

            $serverProc = $null
            $composeArgs = $null
            $composeStarted = $false

            try {
                if (Test-Path $projectDir) {
                    Remove-Item -LiteralPath $projectDir -Recurse -Force
                }

                $caseLogPrefix = Join-Path $logRoot $projectName

                # ── 3a. Scaffold ────────────────────────────────────────
                Write-Host "  Scaffolding..." -ForegroundColor Yellow
                $scaffoldResult = $null
                $scaffoldAttempt = 0
                $scaffoldMaxAttempts = 3
                do {
                    $scaffoldAttempt++
                    if ($scaffoldAttempt -gt 1) {
                        Write-Host "  Retry $scaffoldAttempt/$scaffoldMaxAttempts after file-lock delay..." -ForegroundColor DarkYellow
                        Start-Sleep -Seconds 3
                        # Clean up any leftover staging directory
                        $stagingPattern = Join-Path $scaffoldRoot ".${projectName}.tmp-*"
                        Remove-Item -Path $stagingPattern -Recurse -Force -ErrorAction SilentlyContinue
                    }
                    $scaffoldResult = Invoke-LoggedNativeCommand `
                        -LogPath "$caseLogPrefix.scaffold.log" `
                        -FilePath "dotnet" `
                        -ArgumentList @(
                            "run",
                            "--project", (Join-Path $repoRoot "src/Lakona.Tool"),
                            "--no-build",
                            "--",
                            "new",
                            "--name", $projectName,
                            "--client-engine", $engineValue,
                            "--transport", $transportValue,
                            "--serializer", $serializerValue,
                            "--membership-provider", $membershipProviderValue,
                            "--nugetforunity-source", "embedded",
                            "--deploy-profile", $(if ($Compose) { "compose" } else { "none" }),
                            "--output", $scaffoldRootRelative)
                } while ($scaffoldResult.ExitCode -ne 0 -and $scaffoldAttempt -lt $scaffoldMaxAttempts)

                if ($scaffoldResult.ExitCode -ne 0) {
                    $result.Error = "Scaffold failed."
                    $result.ErrorDetail = $scaffoldResult.Tail
                    $result.LogPath = $scaffoldResult.LogPath
                    $results.Add([pscustomobject]$result)
                    continue
                }
                $result.Scaffold = "PASS"
                Write-Host "  Scaffold: OK" -ForegroundColor Green

                # ── 3b. Resolve dependencies ────────────────────────────
                switch ($Feed) {
                    "ProjectReference" {
                        Patch-ServerDependencies -ProjectDir $projectDir `
                            -RepoRoot $repoRoot
                    }
                    "LocalFeed" {
                        $serverFeed = $feedDir
                        if ($Compose) {
                            # A relative source works both on the host and inside /src.
                            Copy-Item -LiteralPath $feedDir -Destination (Join-Path $projectDir ".e2e-feed") -Recurse
                            $serverFeed = ".e2e-feed"
                        }
                        Write-NuGetConfig -Path (Join-Path $projectDir "NuGet.config") `
                            -FeedDir $serverFeed -IncludeNuGetOrg $true
                        Write-Host "  NuGet.config written for local feed" -ForegroundColor DarkGray
                    }
                    "NuGetOrg" {
                        # No NuGet.config needed — uses default nuget.org source
                        Write-Host "  Using nuget.org packages (no local feed)" -ForegroundColor DarkGray
                    }
                }

                if ($Compose) {
                    $composeEnv = Join-Path $projectDir ".env.e2e"
                    Set-Content -LiteralPath $composeEnv -Value "LAKONA_CLIENT_PORT=$casePort"
                    $composeName = "lakona-e2e-$([Guid]::NewGuid().ToString('N').Substring(0, 12))"
                    $composeArgs = @("compose", "--project-name", $composeName, "--env-file", $composeEnv,
                        "-f", (Join-Path $projectDir "docker-compose.cluster.yml"))
                } else {
                    Set-GeneratedServerPort $projectDir $casePort $clusterPort $managementPort
                }

                # Verify scaffold output
                $serverSln = Join-Path $projectDir "Server/Server.slnx"
                if (-not (Test-Path $serverSln)) {
                    $result.Error = "Server.slnx not found after scaffold."
                    $results.Add([pscustomobject]$result)
                    continue
                }

                # ── 3c. Build server ────────────────────────────────────
                Write-Host "  Building server..." -ForegroundColor Yellow
                if ($Compose) {
                    $buildResult = Invoke-LoggedNativeCommand -LogPath "$caseLogPrefix.server-build.log" `
                        -FilePath "docker" -ArgumentList ($composeArgs + @("build"))
                } else {
                    $buildResult = Invoke-LoggedNativeCommand `
                        -LogPath "$caseLogPrefix.server-build.log" `
                        -FilePath "dotnet" `
                        -ArgumentList @("build", $serverSln, "--nologo", "-v", "q")
                }
                if ($buildResult.ExitCode -ne 0) {
                    $result.Error = "Generated server build failed."
                    $result.ErrorDetail = $buildResult.Tail
                    $result.LogPath = $buildResult.LogPath
                    $results.Add([pscustomobject]$result)
                    continue
                }
                $result.Build = "PASS"
                Write-Host "  Build: OK" -ForegroundColor Green

                # ── 3d. Runtime verification ────────────────────────────
                if (-not $runRuntime) {
                    $results.Add([pscustomobject]$result)
                    continue
                }

                if (-not (Test-PortAvailable $casePort)) {
                    $result.Error = "Port $casePort already has a TCP listener or UDP endpoint."
                    $results.Add([pscustomobject]$result)
                    continue
                }

                if (-not (Test-PortAvailable $clusterPort)) {
                    $result.Error = "Cluster port $clusterPort already has a TCP listener or UDP endpoint."
                    $results.Add([pscustomobject]$result)
                    continue
                }

                if (-not (Test-PortAvailable $managementPort)) {
                    $result.Error = "Management port $managementPort already has a TCP listener or UDP endpoint."
                    $results.Add([pscustomobject]$result)
                    continue
                }

                # Generate E2E verification client
                $e2eDir = New-E2EClient -ProjectDir $projectDir `
                    -Engine $engineValue `
                    -Transport $transportValue `
                    -Serializer $serializerValue `
                    -Port $casePort `
                    -Feed $Feed `
                    -FeedDir $feedDir `
                    -RepoRoot $repoRoot

                $clientBuildResult = Invoke-LoggedNativeCommand `
                    -LogPath "$caseLogPrefix.e2e-client-build.log" `
                    -FilePath "dotnet" `
                    -ArgumentList @("build", (Join-Path $e2eDir "E2EVerification.csproj"), "--nologo", "-v", "q")
                if ($clientBuildResult.ExitCode -ne 0) {
                    $result.Error = "E2E client build failed."
                    $result.ErrorDetail = $clientBuildResult.Tail
                    $result.LogPath = $clientBuildResult.LogPath
                    $results.Add([pscustomobject]$result)
                    continue
                }

                # Start server
                Write-Host "  Starting server..." -ForegroundColor Yellow
                $serverOut = Join-Path $projectDir "server-out.txt"
                $serverErr = Join-Path $projectDir "server-err.txt"
                $serverProject = Join-Path $projectDir "Server/App/Server.App.csproj"

                if ($Compose) {
                    $composeStarted = $true
                    $startResult = Invoke-LoggedNativeCommand -LogPath "$caseLogPrefix.compose-up.log" `
                        -FilePath "docker" -ArgumentList ($composeArgs + @("up", "-d", "--no-build"))
                    if ($startResult.ExitCode -ne 0) { throw "Compose startup failed: $($startResult.Tail)" }
                } else {
                    $serverProc = Start-Process -FilePath "dotnet" `
                    -ArgumentList "run", "--project", $serverProject, "--no-build" `
                    -NoNewWindow `
                    -PassThru `
                    -RedirectStandardOutput $serverOut `
                    -RedirectStandardError $serverErr
                }

                $ready = $false
                for ($i = 0; $i -lt 30; $i++) {
                    Start-Sleep -Seconds 1
                    if ($Compose) {
                        & docker @composeArgs logs --no-color server 2>&1 | Set-Content -LiteralPath $serverOut
                    } elseif ($serverProc.HasExited) {
                        break
                    }

                    if (Test-Path $serverOut) {
                        $serverText = Get-Content -LiteralPath $serverOut -Raw -ErrorAction SilentlyContinue
                        if ($serverText -match "Lakona server started successfully") {
                            $ready = $true
                            Write-Host "  Server ready (waited $i seconds)." -ForegroundColor Green
                            break
                        }
                    }
                }

                if (-not $ready) {
                    $result.Error = "Server did not become ready. See $serverOut and $serverErr."
                    $result.ErrorDetail = "Server stdout: $serverOut`nServer stderr: $serverErr"
                    $result.LogPath = $serverErr
                    $results.Add([pscustomobject]$result)
                    continue
                }

                # Run E2E client
                Write-Host "  Running E2E verification..." -ForegroundColor Yellow
                $clientRunResult = Invoke-LoggedNativeCommand `
                    -LogPath "$caseLogPrefix.e2e-client-run.log" `
                    -FilePath "dotnet" `
                    -ArgumentList @("run", "--project", (Join-Path $e2eDir "E2EVerification.csproj"), "--no-build")
                if ($clientRunResult.ExitCode -ne 0) {
                    $result.Error = "Runtime E2E client failed."
                    $result.ErrorDetail = $clientRunResult.Tail
                    $result.LogPath = $clientRunResult.LogPath
                    $results.Add([pscustomobject]$result)
                    continue
                }

                $result.Runtime = "PASS"
                Write-Host "  E2E: PASS" -ForegroundColor Green
                $results.Add([pscustomobject]$result)
            } catch {
                $result.Error = $_.Exception.Message
                $result.ErrorDetail = $_.Exception.ToString()
                $results.Add([pscustomobject]$result)
            } finally {
                Stop-ProcessTree $serverProc
                if ($null -ne $composeArgs) {
                    if ($composeStarted) {
                        & docker @composeArgs logs --no-color server 2>&1 | Set-Content -LiteralPath $serverOut
                    }
                    $cleanup = Invoke-LoggedNativeCommand -LogPath "$caseLogPrefix.compose-down.log" `
                        -FilePath "docker" -ArgumentList ($composeArgs + @("down", "--rmi", "local", "--volumes"))
                    if ($cleanup.ExitCode -ne 0) {
                        foreach ($record in $results | Where-Object ProjectDir -eq $projectDir) {
                            $record.Runtime = "FAIL"
                            $record.Error = "Compose cleanup failed: $($cleanup.Tail)"
                        }
                    }
                }
            }
          }
        }
    }
}

# ═══════════════════════════════════════════════════════════════════════════════
# Report
# ═══════════════════════════════════════════════════════════════════════════════

$passCount = ($results | Where-Object {
    $_.Scaffold -eq "PASS" -and $_.Build -eq "PASS" -and ($_.Runtime -eq "PASS" -or $_.Runtime -eq "SKIP")
}).Count
$failCount = $results.Count - $passCount

$results | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $summaryPath -Encoding UTF8

$report = New-Object System.Collections.Generic.List[string]
$report.Add("# Lakona E2E Report ($Feed)")
$report.Add("")
$report.Add("- Generated at: $([DateTimeOffset]::UtcNow.ToString("u"))")
$report.Add("- Feed mode: $Feed")
$report.Add("- Server host: $(if ($Compose) { 'Compose' } else { 'Process' })")
$report.Add("- Membership provider selection: $MembershipProvider")
$report.Add("- Runtime verification: $runRuntime")
$report.Add("- Work directory: $workRoot")
$report.Add("- Logs: $logRoot")
if ($Feed -eq "LocalFeed") {
    $report.Add("- Local feed: $feedDir")
    $report.Add("- Isolated package cache: $packageCache")
}
$report.Add("- Passed: $passCount")
$report.Add("- Failed: $failCount")
$report.Add("")
$report.Add("| Engine | Transport | Serializer | Membership | Feed | Port | Scaffold | Build | Runtime | Error | Details | Log |")
$report.Add("| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |")
foreach ($item in $results) {
    $errorText = Format-ReportCell $item.Error
    $detailText = Format-ReportCell $item.ErrorDetail
    $logText = Format-ReportCell $item.LogPath
    $report.Add("| $($item.Engine) | $($item.Transport) | $($item.Serializer) | $($item.MembershipProvider) | $($item.Feed) | $($item.Port) | $($item.Scaffold) | $($item.Build) | $($item.Runtime) | $errorText | $detailText | $logText |")
}

$report | Set-Content -LiteralPath $reportPath -Encoding UTF8

Write-Banner "Results"
$results | Format-Table Engine, Transport, Serializer, MembershipProvider, Port, Scaffold, Build, Runtime -AutoSize
Write-Host ""
Write-Host "Report: $reportPath"
Write-Host "Summary: $summaryPath"
Write-Host "Passed: $passCount | Failed: $failCount"

if (-not $KeepScaffolds) {
    foreach ($item in $results) {
        if ($item.Scaffold -eq "PASS" -and $item.Build -eq "PASS" -and ($item.Runtime -eq "PASS" -or $item.Runtime -eq "SKIP")) {
            Remove-Item -LiteralPath $item.ProjectDir -Recurse -Force -ErrorAction SilentlyContinue
        }
    }
}

if ($failCount -gt 0) {
    exit 1
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall