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/imazen/imageflow 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 2 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

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

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

What it runs against: a local clone of imazen/imageflow — 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 imazen/imageflow | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of imazen/imageflow. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/imazen/imageflow.git
#   cd imageflow
#
# 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 imazen/imageflow and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/imazen/imageflow"
  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).

Imageflow is a high-performance, memory-safe image manipulation library and server written in Rust that processes JPEG, PNG, WebP, and GIF at up to 17x faster speeds than ImageMagick while producing smaller files at higher quality. It exposes three products: libimageflow (C ABI for bindings in any language), imageflow_tool (CLI for batch jobs and JSON workflows), and imageflow_server (HTTP image manipulation server with dynamic on-the-fly resizing via querystring or JSON APIs). Monorepo with workspace members in Cargo.toml: core engine in imageflow_core, ABI layer in imageflow_abi, RIAPI querystring API in imageflow_riapi, CLI tool in imageflow_tool, type definitions in imageflow_types, and helper utilities in imageflow_helpers and imageflow_http_helpers. C components live in c_components/. Build profiles (release, test, bench) are tuned for image processing workloads (test profile uses opt-level=2 for 600ms→26ms RIAPI test speedup).

Web developers and DevOps engineers who need to serve optimized images at scale (via imageflow_server or imageflow_tool), library maintainers implementing imageflow bindings for Node.js/Go/.NET/Elixir/Scala ecosystems, and organizations migrating from ImageMagick/ImageResizer who require production-ready performance with security audits.

Production-ready release candidate with active development: 2.5M+ lines of Rust, comprehensive CI/CD via GitHub Actions (.github/workflows/ci.yml), fuzzing infrastructure (.github/workflows/fuzz.yml), and well-established bindings across multiple languages (imageflow-node, imageflow-go, imageflow-dotnet). The codebase shows mature practices like split-debuginfo, LTO optimization in release profiles, and nextest configuration for parallel testing.

Low risk for core library but moderate risk for server adoption: 10+ patched dependencies via [patch.crates-io] (libpng-sys, lcms2-sys, zenpixels, zenjpeg, zenwebp) tied to maintainer GitHub forks suggests dependency management burden; dual licensing (AGPLv3/Commercial) may complicate some integrations. Last activity visible but no recent commit date in file list—verify recency. Single maintainer (Imazen) risk is mitigated by open-source model.

Schema updates and workflow automation visible via .github/workflows/schema-update.yml and update-actions.yml; fuzzing infrastructure (.github/workflows/fuzz.yml) suggests active security hardening; codelldb debugger setup in .cargo/codelldb.sh indicates active debugging/development. The .cursor/rules directory with language-specific guidelines (bash.mdc, rust.mdc, ffi.mdc, json-api.mdc, riapi.mdc) suggests recent AI-assisted development setup.

Clone the monorepo, install Rust (target the latest stable), and run: git clone https://github.com/imazen/imageflow && cd imageflow && cargo build --release. For the tool: cargo build --release -p imageflow_tool. For the server: cargo build --release -p imageflow_server. Run tests via cargo test --all or with nextest: cargo nextest run (configured in .config/nextest.toml).

Daily commands: Dev server (imageflow_server): cargo run --release -p imageflow_server -- --port 3000 (inferred from typical Rust server setup; verify with imageflow_server --help). CLI tool: cargo run --release -p imageflow_tool -- decode input.jpg output.png or JSON jobs via stdin. Tests: cargo test --all or cargo nextest run --profile default for parallel execution. Fuzzing: cargo fuzz run (via .github/workflows/fuzz.yml setup).

• Cargo.toml: Workspace root defining all members (imageflow_core, imageflow_tool, imageflow_server, imageflow_abi) and critical patched dependencies (libpng-sys, zenjpeg, zenwebp, lcms2-sys)
• imageflow_core/src/: Core image processing engine with codec handling, filter pipelines, and bitmap operations—the heart of the library
• imageflow_abi/src/: C-compatible FFI interface that exposes only 4 key methods for language bindings across Node/Go/.NET/Elixir
• imageflow_riapi/src/: Querystring API parser implementing RIAPI spec (the /bucket/img.jpg?w=200 syntax); critical for imageflow_server
• imageflow_tool/src/: CLI tool entry point for batch processing, JSON job execution, and standalone image manipulation
• .github/workflows/ci.yml: Multi-platform CI pipeline defining test, build, and release targets across Linux/macOS/Windows and ARM64
• .cargo/config.toml: Rust toolchain and linker configuration for reproducible cross-platform builds
• c_components/: C code wrapping external image codec libraries (libpng, libjpeg, libwebp, lcms2) for Rust integration
• .cursor/rules/: AI code generation rules for bash, Rust, FFI, JSON API, and RIAPI—indicates active development methodology
• .config/nextest.toml: Parallel test runner configuration optimizing test execution speed; important for 2.5M LOC test suite

New image filters: Add logic to imageflow_core/src/ (codec wrappers are in c_components/, Rust bridges in imageflow_core). JSON API changes: Update imageflow_types/src/ and imageflow_riapi/src/ for RIAPI querystring parsing. New bindings: Use libimageflow's C ABI (imageflow_abi/src/); copy pattern from referenced imageflow-node/imageflow-go repos. Server routes: Modify imageflow_server's HTTP handler. Tests: Add to the same crate under #[cfg(test)] or integration tests/ directory (profile.test uses opt-level=2 for speed).

1. Patched dependencies: Many crates rely on Imazen forks (libpng-sys, lcms2-sys, zenpixels, zenjpeg, zenwebp, zenjpeg); building offline or without these forks will fail—verify [patch.crates-io] is applied. 2. Stride alignment: Imageflow bitmaps use SIMD-aligned strides > width*bpp; codecs must handle non-contiguous pixel data (see zenwebp 'push_frame stride fix' comment). 3. Profile-dependent performance: Test profile uses opt-level=2; running tests with default (opt-level=0) yields 600ms per RIAPI test vs 26ms—do not benchmark unoptimized builds. 4. C interop complexity: SWIG bindings (763 LOC) + c_components/ require C compiler and libpng/libjpeg/libwebp system libraries; CI has custom actions for Windows ARM64 (setup-win-arm64). 5. License compliance: Dual AGPLv3/Commercial licensing; commercial use requires dual-licensing or separate licensing deal.

• SIMD-aligned stride buffers — Imageflow bitmaps use SIMD-aligned strides (width*bpp padding for vectorization); many newcomers assume contiguous pixel data, causing silent corruption in codec interop
• RIAPI (Resizing Querystring API) — The core HTTP API for dynamic image transforms (/bucket/img.jpg?w=200&h=300&mode=crop) implemented in imageflow_riapi; understanding its spec is essential for server contributions
• C ABI stability for language bindings — Imageflow exposes only 4 stable C functions in imageflow_abi to support bindings in any language; FFI surface design directly impacts maintainability across Node/Go/.NET ecosystems
• CMYK color space and ICC profiles — Imageflow uniquely handles CMYK JPEG via zenjpeg + lcms2 color management; CMYK→RGB conversion with ICC profiles is non-trivial and key differentiator vs ImageMagick for print workflows
• Codec-independent bitmap pipeline — Imageflow decodes to an internal bitmap format then applies filters (resize, crop, color correction) before re-encoding; this decouples filters from codec implementations, enabling performance optimizations
• LTO (Link-Time Optimization) and split-debuginfo — Release profile uses lto=true and split-debuginfo='packed' for aggressive optimization without bloating binaries; understanding these flags is critical for reproducing performance benchmarks
• Monorepo workspace coordination with patched crates-io dependencies — The [patch.crates-io] system in Cargo.toml pins forked versions of libpng-sys, zenjpeg, zenwebp across all workspace members; changes to any patched dep ripple to all consumers, requiring coordinated testing

• imazen/imageflow-node — Node.js bindings for libimageflow using the C ABI; reference implementation for multi-language binding pattern
• imazen/imageflow-go — Go bindings for libimageflow; demonstrates cgo FFI and async image pipeline patterns on the Go side
• imazen/imageflow-dotnet-server — Production-ready HTTP server for .NET using imageflow as image backend; shows real-world deployment of imageflow_server with Azure/S3 blob storage integration
• imazen/imageflow-dotnet — .NET language bindings for libimageflow; complements imageflow-dotnet-server for library consumers
• ImageMagick/ImageMagick — Direct competitor and performance baseline; Imageflow explicitly benchmarks as 17x faster for typical web workflows

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 comprehensive FFI integration tests for C interop

The repo has extensive C interop (.cursor/rules/ffi.mdc exists) and imageflow_abi crate, but the file structure shows no dedicated integration test suite for C-to-Rust FFI boundaries. Given that libimageflow is a core product, testing C struct marshaling, memory safety, and callback mechanics is critical. This prevents silent failures in production where C clients call Rust code.

• [ ] Create imageflow_abi/tests/integration_ffi.rs with tests for common FFI patterns (struct serialization, pointer safety, error propagation)
• [ ] Add tests in c_components/tests/ that call libimageflow.so/dll from C and verify Rust callback invocation
• [ ] Reference .cursor/rules/ffi.mdc to ensure alignment with project FFI conventions
• [ ] Run tests via CI in .github/workflows/ci.yml for all platforms (Windows, Linux, macOS, ARM)

Add RIAPI query string parser property tests with proptest

imageflow_riapi is a major component (referenced in .idea/runConfigurations/test_riapi.xml), but RIAPI query strings are complex, variable-length inputs prone to edge cases. The test profile is already optimized (opt-level=2 for fast RIAPI tests), but there's no fuzz or property-based test suite. Adding proptest-based fuzzing would catch parser crashes and logical errors before users hit them.

• [ ] Create imageflow_riapi/tests/property_tests.rs using proptest crate to generate arbitrary query strings
• [ ] Test parsing roundtrips: parse → serialize → parse should be idempotent
• [ ] Add at least 50 property-based test cases covering filters, width, height, crop, and unknown params
• [ ] Integrate into .github/workflows/fuzz.yml (already exists) or create separate fuzz-riapi job

Document and test codec feature flags for all supported formats

The Cargo.toml has extensive [patch.crates-io] entries for custom codec forks (libpng-sys, zenjpeg with CMYK, zenwebp, etc.), but there's no centralized documentation or feature flag validation. Contributors may not know which codecs are conditionally compiled, leading to accidental regressions. The benchmarks/bench_codecs_*.txt files suggest codec testing infrastructure exists but lacks coverage validation.

• [ ] Create imageflow_core/tests/codec_features.rs that verifies each codec (PNG, JPEG, WebP, LCMS2) is available when expected features are enabled
• [ ] Add a doc comment in Cargo.toml or new CODEC_FEATURE_MATRIX.md listing which crate enables which format and any platform limitations
• [ ] Add a CI job in .github/workflows/ci.yml to test with minimal features, full features, and MUSL targets (mentioned in Cargo.toml)
• [ ] Cross-reference .cursor/rules/ci.mdc to align with documented CI practices

• Add missing unit tests for imageflow_helpers/src/ (helper utilities module has no corresponding tests/ directory visible); create integration tests validating color space conversions across CMYK→RGB→sRGB pipelines for JPEG with lcms2
• Document the C ABI binding pattern in SWIG/.../bindings—the current 4-method interface is underdocumented; add a step-by-step guide for implementing minimal bindings for a new language (Rust/Go analogs exist in imageflow-go repo but Rust pattern needs formalization)
• Extend .cursor/rules/ffi.mdc with concrete examples of FFI pointer safety patterns used in imageflow_abi; the file likely exists but is sparse—add examples of context safety, error propagation, and memory ownership across C/Rust boundaries

• High · Patched Dependencies from Non-Official Sources — Cargo.toml - [patch.crates-io] section. The Cargo.toml uses multiple [patch.crates-io] entries pointing to custom GitHub forks of upstream libraries (libpng-sys, lcms2-sys, zenpixels, zenjpeg, zenwebp). While this may be intentional for bug fixes, it creates a supply chain risk if these forks diverge from upstream or if the repositories are compromised. The patches are maintained by imazen, but this should be monitored carefully. Fix: 1) Regularly audit patched dependencies for security updates in upstream. 2) Document reasons for each patch and track upstream commits. 3) Consider submitting patches upstream when appropriate. 4) Implement dependency vulnerability scanning in CI/CD pipeline. 5) Use lock file pinning in production environments.
• High · Incomplete Security Policy — SECURITY.md. SECURITY.md only lists version 2.0.x as supported, with all versions < 2.0 unsupported. However, this is a release candidate state project (per README badge). There is no clear vulnerability disclosure process timeline or SLA for patch releases, which could delay security updates. Fix: 1) Expand security policy to include: expected response time for vulnerability reports, target patch release timeline, and long-term support commitments. 2) Document the versioning and release schedule clearly. 3) Consider providing security update notifications mechanism. 4) Clarify if RC versions receive security patches.
• Medium · Native Code Dependencies and FFI Attack Surface — c_components/ directory, imageflow_abi/. The codebase includes C components and FFI bindings (c_components/, imageflow_abi/) which expand the attack surface to unsafe code. The project handles image manipulation which historically has had numerous memory safety vulnerabilities (as noted in README linking to CVEs). C code requires additional security scrutiny. Fix: 1) Implement mandatory code review for all C/FFI code changes. 2) Use static analysis tools (Clang Static Analyzer, cppcheck). 3) Consider fuzzing campaigns (CI has fuzz.yml - ensure it runs comprehensive fuzz tests). 4) Use memory sanitizers (AddressSanitizer, MemorySanitizer) in CI. 5) Document unsafe blocks in Rust with security justification.
• Medium · LTO and Strip Enabled in Release Builds — Cargo.toml - [profile.release]. Release profile has lto = true and strip = true with debug = true. While split-debuginfo='packed' helps, stripping binaries while keeping debug info packed can complicate post-mortem security analysis and vulnerability response if exploits occur. Fix: 1) Document the rationale for strip = true in release builds. 2) Ensure debug symbols are retained and available for security incident response. 3) Consider keeping unstripped binaries for security team analysis. 4) Verify split-debuginfo configuration is correctly handled in distribution.
• Medium · Dependency on Multiple External Git Branches — Cargo.toml - [patch.crates-io] entries with branch = 'main'. Several patched dependencies point to development branches (e.g., zenpixels 'main', zenjpeg 'main', zenwebp 'main') rather than stable tags. This means the build pulls unstable code from active development branches, which could include untested security fixes or introduce new vulnerabilities. Fix: 1) Pin to specific commit hashes instead of branches when possible. 2) If branches must be used, document why and track known stability issues. 3) Implement automated testing against these dependencies. 4) Consider transitioning to released versions once available. 5) Add dependency update notifications to track changes.
• Low · Test Optimization Level May Impact Security Testing — Cargo.toml - [profile.test]. Test profile uses opt-level = 2 for performance reasons. While not a vulnerability itself, aggressive optimization in tests could potentially mask certain security issues or race conditions that only appear at lower optimization levels. Fix: 1) Consider running a subset of security-critical tests at opt-level = 0. 2) Run thread sanitizer and other detection tools at lower optimization levels. 3) Document testing strategy and known limitations.
• Low · Fuzzing Configuration Not Fully Visible — undefined. CI Fix: undefined

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.