mapo-core/AGENTS.md

CI to Local Workflow Guide

This document describes how the GitLab CI pipeline in this repository translates to local commands that can be run on your machine. It also contains helper scripts and environment variables used by the CI.

Environment Variables

All variables listed below are interpolated in the CI templates. When running locally you can set them in a PowerShell profile or via dotnet arguments.

Variable	Description	Typical value
SOL_NAME	Solution name to restore	MP-STATS.sln
PROJ_PATH	Directory containing the main project	MP.Stats
APP_NAME	Main project file name (without .csproj)	MP.Stats
NUGET_PATH	NuGet credential file	C:\\Users\\samuele.steamw\AppData\Roaming\NuGet\Credentials.config
NEXUS_PATH	Nexus host URL	https://nexus.steamware.net
DEST	Artifacts output folder	bin\publish
VERS_MAIN, VERS_MAIN_APP, VERSSUB	Version strings used in packaging	1.0.0 /
NEXUS_PASSWD	Nexus password (secure via CI secret)	Secret

Build Pipeline (buildjob) – Local Equivalent

The CI first restores NuGet packages and then builds the solution for the selected APP_NAME.

# 1. Restore
#$env:SOL_NAME.sln is resolved by the .nuget-fix script
# In PowerShell: dotnet restore "MP-STATS.sln"

# 2. Build
# $env:APP_NAME/$env:APP_NAME.csproj points to the project file
# In PowerShell: dotnet build "MP.Stats/MP.Stats.csproj"

Helper: .nuget-fix

The .nuget-fix PowerShell script removes any stale NuGet sources that conflict with the Nexus proxy and re‑adds the latest proxy source with credentials. Ensure this script runs before dotnet restore.

Deploy Pipeline (deployjob) – Local Equivalent

Deployment in CI rebuilds the project, publishes it, hashes the output, and uploads it to Nexus. The same steps can be executed locally.

# 1. Rebuild (same as Build)
# dotnet build "MP.Stats/MP.Stats.csproj"

# 2. Publish to a local folder
# The `dotnet publish` command mimics the CI publish step.  The `-c Release` ensures a Release build.
# In PowerShell:
# dotnet publish "MP.Stats/MP.Stats.csproj" -c Release -o publish

# 3. Create hashes (MD5 & SHA1)
# The .hashBuild template generates .md5 and .sha1 files alongside the ZIP.  A simple replacement can be
#   1. Zip the folder:   `Compress-Archive -Path publish -DestinationPath $(APP_NAME).zip`
#   2. Generate hashes:
#      (Get-FileHash -Algorithm MD5 "$(APP_NAME).zip").Hash | Out-File "$(APP_NAME).md5"
#      (Get-FileHash -Algorithm SHA1 "$(APP_NAME).zip").Hash | Out-File "$(APP_NAME).sha1"

# 4. Upload to Nexus (requires `curl`)
# Example curl command (CI uses `nexus-curl` script):
# $curl -u $(NUGET_USER):$(NEXUS_PASSWD) "$(NEXUS_PATH)/repository/$(APP_NAME)" -T "$(APP_NAME).zip"

Installer & Release

The installer template copies the published artifacts to a staging folder and optionally creates installers. The release template bumps version numbers, updates the nuspec, generates a changelog, and pushes the packages to Nexus.

Generally these steps are CI‑only, but you can repeat the same dotnet pack / nuget push commands locally if needed.

Common Issues & Fixes

• NuGet authentication errors: Run .nuget-fix to reset the sources.
• Missing SDK: Verify dotnet --list-sdks includes at least one SDK.
• Hashes not matching: Ensure the ZIP file is identical to the one CI produced (same path, no hidden files).

Quick Start

# Restore
.\.nuget-fix

# Build

dotnet restore "MP-STATS.sln"
dotnet build "MP.Stats/MP.Stats.csproj"

# Publish & run

dotnet publish "MP.Stats/MP.Stats.csproj" -c Release -o publish
dotnet run --project "MP.Stats/MP.Stats.csproj"

# For hot‑reload during development

dotnet watch run --project "MP.Stats/MP.Stats.csproj"

---

Feel free to adjust paths or environment variable names if your local setup differs.