# 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`.

```powershell
# 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.

```powershell
# 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
```powershell
# 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.