NixOS_WindowsWrapper/.agents/AGENTS.md

Nix WSL Wrapper Custom Workspace Rules & CI/CD Guidelines

These guidelines define coding rules, visual presentation checks, and CI/CD validation instructions for this repository.

---

1. Clean Code, SOLID & DDD Guidelines

All future modifications to the NixWslWrapper solution must adhere to the following standards:

• Domain-Driven Design (DDD):
  • Encapsulate domain invariants inside value objects. Value objects must validate input parameters upon construction (e.g. WslTarget validates that paths and names are non-empty).
  • Domain logic must remain framework-agnostic. Do not reference infrastructure concepts (such as process handles or stream copiers) inside the .Core project.
• SOLID Principles:
  • Single Responsibility (SRP): Keep execution strategies, builders, stream copiers, and CLI formatting separated.
  • Open/Closed (OCP): If we need execution methods other than WSL (e.g. SSH, Local), implement a new strategy implementing ICommandExecutor rather than modifying WslCommandExecutor.
  • Dependency Inversion (DIP): Inject interfaces (ICommandExecutor, IStreamCopier) and stream abstractions (Stream) to facilitate seamless unit testing and mock assertions.
• Visual UI/UX Check:
  • For CLI diagnostics, use Spectre.Console markup ([color]...[/]) to color-code output. Always escape literal brackets by doubling them ([[literal-text]]) to prevent parser errors.
  • Render a rich dashboard with FigletText and Table grids when administrative diagnostics are run (e.g. --wsl-status).

---

2. Local Verification Commands

To compile, verify, and test the project locally, run:

# Restore dependencies
dotnet restore

# Run the unit tests (xUnit)
dotnet test

# Build and package as a single-file executable
dotnet publish src/NixWslWrapper.Cli/NixWslWrapper.Cli.csproj -c Release -r win-x64 --self-contained -p:PublishSingleFile=true -o ./dist

---

3. Gitea CI/CD Pipeline Setup & Verification

Follow these steps to push code and verify all tests via Gitea Actions:

Step 3.1: Gitea Repository Registration

1. Access your Gitea dashboard at https://gitea.marek-novak.cz/.
2. Click the + sign in the top-right and select New Repository.
3. Set the repository name to NixOS_WindowsWrapper and create it.

Step 3.2: Push Local Git Code

Initialize the remote link and push your repository:

git remote add origin https://gitea.marek-novak.cz/<your-gitea-username>/NixOS_WindowsWrapper.git
git branch -M master
git push -u origin master

Step 3.3: Verify CI/CD Trigger

1. Once pushed, navigate to the repository homepage in Gitea.
2. Click the Actions tab on the top navigation bar.
3. You should see a running workflow named Build and Test corresponding to the commit.
4. Click on the workflow run to verify that the steps Restore dependencies, Build solution, and Run unit tests complete successfully.