Developer Onboarding

Prerequisites

.NET SDK 10 (preview acceptable; ensure dotnet --version prints 10.x).
Platform tooling (install as needed):
- Windows: Windows SDK (makeappx, signtool) and WiX Toolset 3.14+ (heat, candle, light).
- macOS: Xcode command-line tools providing productbuild, codesign, notarytool, hdiutil.
- Linux: Packaging CLI dependencies (fpm, appimagetool, flatpak-builder, snapcraft, gpg).
Git LFS if large assets will be stored (optional).

Getting Started

Clone both the PackagingTools repo and the Avalonia reference repo specified in the plan (used for UI reuse).
Validate platform tooling (PowerShell or bash):
```
pwsh build/scripts/check-tools.ps1 -Platform windows
```
```
./build/scripts/check-tools.sh mac
```
Review the output and install missing dependencies before running pipelines.
Restore dependencies and build all targets:
```
dotnet build PackagingTools.sln
```
Run integration tests (stubs simulate external tooling output):
```
dotnet test PackagingTools.sln
```
Review the project configuration reference for field descriptions.
Prepare platform payloads:
- Windows: build your Avalonia app and stage binaries/assets into a directory referenced via windows.msix.payloadDirectory / windows.msi.sourceDirectory.
- macOS: export the .app bundle to supply mac.app.bundleSource / mac.pkg.component properties.
- Linux: stage a FHS-compliant root under linux.packageRoot, provide Flatpak manifest and snapcraft YAML through CLI properties or project file.

CLI Workflow

Define a project JSON file describing metadata, platform configurations, and default properties:

{
  "id": "sample",
  "name": "Sample App",
  "version": "1.0.0",
  "metadata": {
    "windows.identityName": "Contoso.Sample",
    "windows.publisher": "CN=Contoso",
    "mac.bundleId": "com.contoso.sample",
    "linux.architecture": "amd64"
  },
  "platforms": {
    "Windows": {
      "formats": ["msix", "msi"],
      "properties": {
        "windows.msix.payloadDirectory": "./artifacts/win",
        "windows.msi.sourceDirectory": "./artifacts/win"
      }
    },
    "MacOS": {
      "formats": ["app", "pkg"],
      "properties": {
        "mac.app.bundleSource": "./artifacts/mac/Sample.app",
        "mac.pkg.component": "./artifacts/mac/Sample.app"
      }
    },
    "Linux": {
      "formats": ["deb", "rpm"],
      "properties": {
        "linux.packageRoot": "./artifacts/linux/root"
      }
    }
  }
}

Run the CLI:

dotnet run --project src/PackagingTools.Cli -- pack \
  --project sample.project.json \
  --platform windows \
  --format msix --format msi \
  --property windows.signing.certificatePath="certs/code-sign.pfx" \
  --property windows.signing.password="secret"

Artifacts write to ./artifacts by default; override with --output.
Include --save-project to persist runtime overrides back to disk, keeping CLI and GUI views in sync.

Visual Studio / IDE Notes

Add PackagingTools.sln to your IDE workspace.
For Avalonia GUI work, open src/PackagingTools.App/PackagingTools.App.csproj. The starter screen loads project definitions using the shared workspace services and will evolve with richer editing capabilities.
When debugging pipelines, set environment variables PACKAGINGTOOLS_TRACE=1 to enable verbose logging (future enhancement placeholder).

Contributing

Run dotnet format across changed projects before submitting PRs.
Provide integration test coverage for new providers or pipeline behaviors using the stub runners in PackagingTools.IntegrationTests.
Update ADRs when adopting new tooling or cross-platform strategies.