If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dlemstra/Magick.NET shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 2 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dlemstra/Magick.NET repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dlemstra/Magick.NET.

What it runs against: a local clone of dlemstra/Magick.NET — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dlemstra/Magick.NET | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dlemstra/Magick.NET. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dlemstra/Magick.NET.git
#   cd Magick.NET
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dlemstra/Magick.NET and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dlemstra/Magick.NET(\\.git)?\\b" \\
  && ok "origin remote is dlemstra/Magick.NET" \\
  || miss "origin remote is not dlemstra/Magick.NET (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Magick.NET.sln" \\
  && ok "Magick.NET.sln" \\
  || miss "missing critical file: Magick.NET.sln"
test -f "Magick.NET.props" \\
  && ok "Magick.NET.props" \\
  || miss "missing critical file: Magick.NET.props"
test -f "build/shared/build.Magick.NET.sh" \\
  && ok "build/shared/build.Magick.NET.sh" \\
  || miss "missing critical file: build/shared/build.Magick.NET.sh"
test -f "publish/Magick.NET.nuspec" \\
  && ok "publish/Magick.NET.nuspec" \\
  || miss "missing critical file: publish/Magick.NET.nuspec"
test -f "BUILDING.md" \\
  && ok "BUILDING.md" \\
  || miss "missing critical file: BUILDING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dlemstra/Magick.NET"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Magick.NET is a .NET wrapper around ImageMagick that enables C#/VB.NET/.NET Core applications to manipulate images without installing ImageMagick on the server. It supports 100+ image formats and provides platform-specific and AnyCPU NuGet packages (Q8/Q16 quantums, with optional OpenMP) for Windows, Linux, macOS, and various architectures (x64, arm64, x86). Monolithic solution (Magick.NET.sln) split by platform: build/ directory contains platform-specific scripts and Dockerfiles (linux-x64, linux-arm64, linux-musl-x64, macos-x64, macos-arm64, windows), shared build logic in build/shared/ (build.Magick.NET.sh, install.Magick.Native.sh, test.Magick.NET.sh), configuration centralized in Magick.NET.props, Magick.NET.ruleset (code analysis), and .editorconfig for consistency.

.NET developers building image processing applications on Windows, Linux, or macOS who need to rotate, resize, crop, convert, or apply filters to images without deploying native ImageMagick binaries as a system dependency.

Production-ready. The project shows strong maturity: 4.3M+ lines of C#, well-organized build infrastructure for multiple platforms (Dockerfiles for linux-x64, linux-arm64, linux-musl, macOS variants), GitHub Actions CI/CD pipeline (main.yml, codeql-analysis.yml), formal contribution guidelines (.github/CONTRIBUTING.md), and active multi-platform package maintenance on NuGet with Q8/Q16 variants since its inception.

Low risk but requires platform-specific build complexity. The project is single-maintainer (dlemstra) with heavy reliance on native ImageMagick bindings, meaning breaking changes in ImageMagick upstream could cascade into this library. Build system is non-trivial (separate Dockerfiles, OpenMP variants, quantization choices), and cross-platform CI must validate Windows, Linux (glibc + musl), and macOS (x64 + arm64).

Active development with infrastructure for multi-platform CI/CD. The .devcontainer/linux-x64 setup and build framework suggest recent work on containerized development; dependabot.yml indicates automated dependency updates; GitHub Actions workflows (codeql-analysis.yml, main.yml) are configured for code quality and testing across platforms.

git clone https://github.com/dlemstra/Magick.NET.git && cd Magick.NET && dotnet build Magick.NET.sln. For containerized development, use the provided .devcontainer configuration. Review BUILDING.md for platform-specific build instructions (Windows requires build/windows/build.Magick.NET.ps1; Linux/macOS use build/shared/build.Magick.NET.sh).

Daily commands: For Windows: .\build\windows\build.Magick.NET.ps1 or .\build\windows\build.Magick.NET.cmd. For Linux/macOS: bash build/shared/build.Magick.NET.sh. Run tests with bash build/shared/test.Magick.NET.sh. For containerized builds, invoke build/linux-x64/run.cmd or build/linux-arm64/run.cmd, which execute Dockerfile and associated build scripts.

• Magick.NET.sln — Main solution file that orchestrates all projects and build targets across Windows, Linux, and macOS platforms.
• Magick.NET.props — Central properties file defining build configurations, platform targets, and dependency versions used across all projects.
• build/shared/build.Magick.NET.sh — Cross-platform build script that coordinates native ImageMagick compilation and managed .NET library integration.
• publish/Magick.NET.nuspec — NuGet package specification for the primary library distribution; defines public API surface and dependencies.
• BUILDING.md — Essential guide documenting platform-specific build procedures, native dependencies, and development environment setup.
• .github/workflows/main.yml — CI/CD pipeline that validates builds, runs tests, and publishes packages across all supported platforms.

Add a new image processing feature/wrapper

1. Create a new public method in the appropriate managed wrapper class in the core library project (typically in Magick.NET/Core or Magick.NET/MagickImage) (Magick.NET.sln (locate target project))
2. Implement P/Invoke signature in the native interop layer that maps to the underlying ImageMagick C library function (publish/Magick.NET.nuspec (update if API surface changes))
3. Add comprehensive XML documentation comments following the project's standards (enforce via Magick.NET.ruleset) (Magick.NET.ruleset (reference for documentation requirements))
4. Create a new sample demonstrating the feature in samples/Magick.NET.Samples/ (samples/Magick.NET.Samples/ExifData.cs (use as template))
5. Add documentation page in docs/ directory and link from docs/Readme.md (docs/Readme.md)

Support a new platform or architecture

1. Create platform-specific build directory under build/ with Dockerfile and install.dependencies.sh (build/linux-x64/Dockerfile (use as template))
2. Add platform-specific build script following shared conventions (build.cmd, run.cmd, run.openmp.cmd) (build/shared/build.Magick.NET.sh (reference for build orchestration))
3. Update Magick.NET.props to include new runtime identifier (RID) in platform target list (Magick.NET.props)
4. Add CI/CD workflow job in .github/workflows/main.yml for the new platform (.github/workflows/main.yml)
5. Update package specifications to include platform-specific runtime binaries (publish/Magick.NET.nuspec)

Create a variant library package (e.g., SystemDrawing, Avalonia)

1. Create new .nuspec file for the variant in publish/ directory (follow naming convention) (publish/Magick.NET.SystemDrawing.nuspec (use as template))
2. Create wrapper project/assembly that depends on Magick.NET.Core and adds platform-specific interop (Magick.NET.sln (add new project reference))
3. Update build scripts to compile the variant library (build/shared/build.Magick.NET.sh)
4. Add publish step in publish/publish.ps1 to create variant package (publish/publish.ps1)
5. Update main Magick.NET.targets to handle variant library MSBuild integration (publish/Magick.NET.targets)

• C# / .NET Core — Cross-platform managed language enabling Windows, Linux, macOS support with minimal platform-specific code; provides strong typing and modern language features.
• P/Invoke (native interop) — Allows efficient zero-copy marshaling to unmanaged ImageMagick C library without requiring managed ports; critical for performance-sensitive image processing.
• Docker (multi-platform) — Ensures reproducible builds across Linux variants (x64, ARM64, musl) with isolated dependency environments; enables CI/CD parity between local and cloud builds.
• NuGet packaging — Standard .NET distribution mechanism; enables platform-specific binaries (RID-aware packages) and optional dependencies (e.g., System.Drawing variant).
• GitHub Actions CI/CD — Native GitHub integration for automated multi-platform builds, testing, and publishing; consolidates build matrix (Windows, Linux x64/ARM64/musl, macOS) in single workflow.

• Distributed native binaries in NuGet packages rather than downloading at runtime

  • Why: Ensures consistent versions bundled with library release; simplifies deployment without external dependencies.
  • Consequence: Larger package size; adds build complexity to create multi-platform packages; requires separate packages per platform or AnyCPU packages with conditional binary loading.

• Support multiple package variants (Core, SystemDrawing, Avalonia) from single codebase

  • Why: Allows opt-in UI interop without forcing WPF/System.Drawing dependencies on all consumers.
  • Consequence: Increased build & publish orchestration complexity; version synchronization burden; larger overall package ecosystem to maintain.

• P/Invoke over managed wrapper libraries (e.g., ImageMagick.NET reimplementation)

  • Why: Direct native binding ensures feature parity with ImageMagick releases and maximum performance.
  • Consequence: Brittle to ImageMagick API changes; requires platform-specific binaries; manual marshaling overhead; no cross-platform interop beyond .NET.

• Docker-based Linux builds rather than native CI runners

  • Why: Reproducible isolated environments; easier to add ARM64/musl variants; self-contained dependency specifications.
  • Consequence: Docker image pull/build overhead; adds build time; less familiar to some contributors; Windows/macOS still require native runners.

• Does not provide a managed/C# reimplementation of ImageMagick algorithms—solely wraps native ImageMagick C library.
• Does

1. Multi-quantum packaging (Q8 vs Q16) is non-trivial: Q8 uses 8-bit channels (faster, less memory), Q16 uses 16-bit (more precision, larger memory footprint). NuGet package selection must match application requirements. 2. OpenMP variants add thread parallelization but require compatible libc/glibc; linux-musl builds have separate non-OpenMP variants. 3. Native binary extraction from NuGet happens at runtime; ensure the host OS matches the packaged binary (e.g., Magick.NET-Q8-x64 requires Windows/Linux x64, not arm64). 4. Cross-platform CI requires secrets/credentials for code signing (Magick.NET.snk is strong-name key file). 5. ImageMagick upstream breaking changes (policy.xml format, delegate support) directly impact this library.

• P/Invoke (Platform Invoke) — Magick.NET uses P/Invoke to call native C/C++ ImageMagick functions from managed C# code; understanding calling conventions, marshaling, and pinned memory is essential for debugging interop issues.
• Quantum Depth (Q8 vs Q16) — ImageMagick's quantum defines per-channel bit depth (8-bit vs 16-bit). Magick.NET ships separate packages for each, directly affecting performance, memory, and color accuracy. Mismatched selection causes runtime errors.
• Native Binary Distribution via NuGet — Magick.NET embeds platform-specific native binaries (Windows DLLs, Linux .so, macOS .dylib) inside NuGet packages, requiring careful metadata per architecture (x64, arm64, x86) and OS. Runtime extracts and loads the correct binary.
• Strong Naming (.NET) — Magick.NET uses a strong-name key (Magick.NET.snk) to create cryptographically signed assemblies, enabling GAC installation and version-binding enforcement; important for enterprise deployments.
• Multi-Target Framework Support (net8.0 + netstandard2.0) — Magick.NET targets both modern .NET 8 and older .NET Standard 2.0, requiring conditional compilation and compatibility testing. Different frameworks have different runtime characteristics (GC, threading, memory layout).
• OpenMP Parallelization — Optional OpenMP variant of Magick.NET enables multi-threaded image processing via native thread pools. Requires compatible libc and is unavailable in linux-musl builds, making variant selection platform-critical.
• Delegate Handling in ImageMagick — ImageMagick uses delegates (external libraries: libpng, libjpeg, libwebp) for format support. Magick.NET must ensure delegates are available at runtime; missing or incompatible delegates silently fail format conversions.

• ImageMagick/ImageMagick — Upstream C/C++ library that Magick.NET wraps via P/Invoke; breaking changes here directly impact Magick.NET.
• SixLabors/ImageSharp — Pure .NET alternative for image processing without native dependencies; competes with Magick.NET for .NET developers avoiding P/Invoke overhead.
• conanio/conan — Package manager that Magick.NET could use to simplify native ImageMagick dependency management across platforms, currently handled via platform-specific install scripts.
• dlemstra/Magick.Native — Companion repository containing pre-built native ImageMagick binaries that Magick.NET packages and distributes via NuGet; core infrastructure.
• dotnet/docs — Official .NET documentation referenced for P/Invoke patterns, interop marshaling, and cross-platform .NET library best practices that Magick.NET exemplifies.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add cross-platform build documentation for ARM64 targets

The repo has build scripts for linux-arm64 and macos-arm64 in build/ directory, but BUILDING.md and docs/ lack specific guidance on building for ARM64 platforms. New contributors attempting ARM64 builds will struggle without documented prerequisites, environment setup, and troubleshooting steps specific to each platform.

• [ ] Create docs/BuildingForARM64.md documenting linux-arm64 build process with Dockerfile reference (build/linux-arm64/Dockerfile)
• [ ] Document macos-arm64 specific build steps including install.dependencies.sh (build/macos-arm64/install.dependencies.sh)
• [ ] Add troubleshooting section for common ARM64 cross-compilation issues
• [ ] Update BUILDING.md with link to new ARM64 documentation

Add integration tests for cross-platform build scripts

The repo has multiple build scripts (build/shared/.sh, build/windows/.ps1, build/windows/*.cmd) but no visible test coverage for build script execution across platforms. A new contributor could add GitHub Actions workflows or test scripts to validate build scripts don't break on changes.

• [ ] Create .github/workflows/validate-build-scripts.yml to test build/shared/build.Magick.NET.sh execution
• [ ] Add workflow job for build/windows/build.Magick.NET.ps1 validation on Windows runners
• [ ] Add workflow job for build/shared/test.Magick.NET.sh execution on Linux runners
• [ ] Document expected build script outputs in CONTRIBUTING.md

Create platform-specific troubleshooting documentation

The docs/ folder has feature guides (ConvertImage.md, Drawing.md, ExifData.md) but lacks platform-specific troubleshooting guides. Given the repo's multi-platform complexity (linux-x64, linux-arm64, linux-musl, macos, windows), a troubleshooting guide for common platform issues would help new contributors debug setup problems faster.

• [ ] Create docs/Troubleshooting.md with sections for Windows, Linux, and macOS
• [ ] Document common DLL/native library loading issues on Windows (reference Magick.NET.props for native deps)
• [ ] Add Linux-specific issues like glibc vs musl compatibility (reference build/linux-musl-x64/)
• [ ] Include macOS-specific issues around ARM64 vs x64 architecture detection
• [ ] Add FAQ section referencing .devcontainer/linux-x64/ for consistent development environment setup

• Add cross-platform integration tests for image format conversion (JPEG→PNG→WebP) in build/shared/test.Magick.NET.sh to validate all packaged formats work on Linux arm64 and macOS arm64, currently underrepresented in the test matrix.
• Document Q8 vs Q16 performance and memory tradeoffs in docs/Readme.md with concrete benchmarks (e.g., 'Resizing a 4K image takes X seconds in Q8, Y seconds in Q16 with Z% more memory'), since the NuGet package page mentions both but gives no guidance for users choosing between them.
• Extend build/shared/install.Magick.Native.sh to validate native binary integrity via checksums before compilation, catching corrupted downloads and improving CI reliability across flaky Linux package mirrors.

The Magick.NET repository demonstrates reasonable security practices with automated dependency scanning via Dependabot and CodeQL analysis configured. However, there are notable concerns regarding cryptographic key management (exposure of .snk file in version control), lack of security policy documentation, and potential issues in build scripts and Docker configurations that warrant attention. The main risks are related to infrastructure and build process security rather than application-level vulnerabilities. Implementing proper key management practices and adding security documentation would significantly improve the security posture.

• Medium · Potential Hardcoded Signing Key Exposure — Magick.NET.snk. The presence of 'Magick.NET.snk' (strong name key file) in the repository root is a security concern. Strong name keys are cryptographic keys used for assembly signing and should not be stored in version control systems, especially in public repositories. Fix: Move the .snk file outside of version control. Use secure key management practices such as Azure Key Vault, GitHub Secrets, or local machine storage. Update .gitignore to exclude *.snk files. Consider regenerating the key if it has been exposed.
• Medium · Key Conversion Scripts in Repository — keys/convert.pem.cmd, keys/convert.pem.ps1. PowerShell and batch scripts for key conversion (convert.pem.cmd, convert.pem.ps1) in the 'keys' directory could potentially expose sensitive operations related to cryptographic material management and may indicate unsafe key handling practices. Fix: Document why these scripts are necessary. If they handle sensitive key material, move them outside version control. Implement proper CI/CD pipeline security for key management rather than storing conversion scripts in the repository.
• Low · Docker Build Files Without Security Scanning — build/*/Dockerfile, build/macos-*/install.dependencies.sh. Multiple Dockerfile configurations exist for different platforms (linux-x64, linux-arm64, linux-musl-x64, macos-arm64, macos-x64) without visible security scanning or base image pinning verification in the provided file structure. Fix: Implement Dockerfile security best practices: use specific base image tags (not 'latest'), scan images with tools like Trivy or Snyk, use multi-stage builds, run as non-root user, and minimize layer count. Consider adding security scanning to CI/CD pipeline.
• Low · Shell Scripts Without Apparent Input Validation — build/*/install.dependencies.sh, build/shared/*.sh, build/windows/*.cmd. Multiple shell and batch scripts for build and dependency installation (install.dependencies.sh, build.shared/.sh, build.windows/.cmd) are present. These scripts may process external input without visible validation. Fix: Review all build and installation scripts for input validation and safe command execution. Use shellcheck for shell scripts. Implement proper error handling and avoid dynamic command execution with unsanitized input.
• Low · Missing SECURITY.md or Security Policy — Repository root. No visible SECURITY.md or security vulnerability disclosure policy file found in the repository. This makes it unclear how security issues should be reported. Fix: Create a SECURITY.md file that outlines the process for responsible vulnerability disclosure. Include contact information for security reports and expected response timeline. Reference this file from README.md.
• Low · Potential Dependency Version Constraints — Directory.Packages.props. The Directory.Packages.props file suggests centralized dependency management, but the actual dependency versions are not provided for analysis. Outdated or vulnerable dependencies could pose security risks. Fix: Regularly audit and update dependencies. Use Dependabot (already configured in .github/dependabot.yml) consistently. Implement automated security scanning of NuGet packages using tools like OWASP Dependency-Check or Snyk. Review all major version updates for breaking changes and security patches.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.