mirror of https://github.com/GoodOlClint/PSProxmoxVE.git synced 2026-09-04 03:05:32 +00:00

Files

T

goodolclint-claude[bot] b90791e2bf docs: migrate DECISIONS.md to house-format ADRs, and retire the review folder (#131 )

D001-D021 become ADR 0001-0021 in docs/decisions/, one decision per file.
D017's PESTER_VERSION amendment was a second decision in one entry and becomes
ADR 0022. ADR 0023 records the migration and reverses the lane2-change-plan
ruling that deliberately kept DECISIONS.md until the CI lane work landed.

DECISIONS.md is reduced to a stub with a D-to-ADR redirect table, so the four
released CHANGELOG entries and older issue bodies that cite it degrade to a
redirect rather than a dead reference.

docs/review/ and docs/lane2-change-plan.md are deleted (ADR 0024). Of 91
findings, 83 were resolved and six of the seven still open were already GitHub
issues; F021 was the exception and is now #130.

CLAUDE.md's Key Conventions list gains the two rules it was missing and becomes
the checklist, with the ADRs carrying rationale.

2026-09-02 14:49:07 +00:00

3.3 KiB

Raw Blame History

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"

The integration flow runs in the same container image CI uses. There is no wrapper script — call run-integration.sh directly (x86 only):

pve() {
    docker compose -f tests/docker-compose.test.yml --profile infra run --rm dev-infra \
        bash tests/infrastructure/scripts/run-integration.sh "$@"
}

pve provision 9
pve test 9 Cluster,VMs   # the area filter is optional
pve force-cleanup

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:

docs/decisions/ — architectural decision records, one per file: what was chosen, what was rejected, and why. The rules themselves are the "Key Conventions" list in CLAUDE.md.
The repository's open GitHub issues — all outstanding work is tracked there.

3.3 KiB Raw Blame History