PSProxmoxVE/.github/copilot-instructions.md

PSProxmoxVE — Copilot Instructions

Project Overview

C# binary PowerShell module for managing Proxmox VE (PVE) infrastructure. Two projects:

• src/PSProxmoxVE/ — Cmdlets and module surface (targets netstandard2.0)
• src/PSProxmoxVE.Core/ — Services, models, HTTP client (targets netstandard2.0)

Tests: xUnit (tests/PSProxmoxVE.Core.Tests/) and Pester 5 (tests/PSProxmoxVE.Tests/).

Development Workflow

All changes go through pull requests. The main branch has branch protection enabled (required build checks, required review, admin enforced). Never push directly to main.

Use Conventional Commits for all commit messages (e.g. feat: add new cmdlet, fix: handle null node name, chore: update deps).

Build & test

# Build
dotnet build PSProxmoxVE.sln

# xUnit tests
dotnet test tests/PSProxmoxVE.Core.Tests/

# Pester tests (requires pwsh)
pwsh -Command "Invoke-Pester tests/PSProxmoxVE.Tests/ -Output Detailed"

A Docker-based dev container replicates the full CI setup locally:

./tests/dev.ps1              # Open pwsh shell in dev container
./tests/dev.ps1 build        # Build the module
./tests/dev.ps1 test         # Run unit tests
./tests/dev.ps1 integration  # Provision nested PVE, run integration tests, cleanup (x86 only)

Key Coding Conventions

Cmdlet rules

• All cmdlets use the Pve noun prefix (e.g. Get-PveVm, New-PveSnapshot).
• All cmdlet classes must be sealed.
• All cmdlets must have an [OutputType(typeof(...))] attribute.
• Destructive cmdlets (Remove-*, Stop-*, Reset-*, Restart-*, Suspend-*, restore ops) must set ConfirmImpact = ConfirmImpact.High.
• Use verb class constants — VerbsCommon.Get, not the string literal "Get".

Parameters

• VmId parameters: [ValidateRange(100, 999999999)]; use int? (nullable) when optional.
• Passwords must use SecureString, never plain string. Extract with Marshal.SecureStringToGlobalAllocUnicode inside a try/finally that calls Marshal.ZeroFreeGlobalAllocUnicode.

URL paths

• All user-supplied or dynamic values interpolated into API URL paths must be wrapped in Uri.EscapeDataString().

Task polling

• Always use TaskService.WaitForTask(upid, session, TimeoutSeconds, this).
• Never implement inline while (true) / do/while polling loops in cmdlet files.

JSON serialization

• Use only Newtonsoft.Json ([JsonProperty]). Do not add System.Text.Json ([JsonPropertyName]) attributes.

Error handling

• No bare catch { } or catch (Exception) { } blocks.
• Use a specific exception type (catch (PveApiException ex)) or a filtered catch with a when clause that excludes fatal exceptions.

Framework targeting

• Publishable projects (PSProxmoxVE, PSProxmoxVE.Core): netstandard2.0.
• Test projects: net10.0 + net48.

Key Reference Files

Before writing new code, read these files to understand established patterns and open issues:

• DECISIONS.md — architectural decisions and anti-patterns that must not be reintroduced.
• docs/review/findings.json — stable findings database (IDs F001… are permanent; resolved findings are marked, never deleted).
• docs/review/REVIEW_REPORT.md — latest full review report.