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/esimov/caire 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 — Stale — last commit 1y ago

• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% 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 esimov/caire repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/esimov/caire.

What it runs against: a local clone of esimov/caire — 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 esimov/caire | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 400 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "carver.go" \\
  && ok "carver.go" \\
  || miss "missing critical file: carver.go"
test -f "processor.go" \\
  && ok "processor.go" \\
  || miss "missing critical file: processor.go"
test -f "cmd/caire/main.go" \\
  && ok "cmd/caire/main.go" \\
  || miss "missing critical file: cmd/caire/main.go"
test -f "image.go" \\
  && ok "image.go" \\
  || miss "missing critical file: image.go"
test -f "sobel.go" \\
  && ok "sobel.go" \\
  || miss "missing critical file: sobel.go"

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

Caire is a content-aware image resizing library written in Go that implements the seam carving algorithm to intelligently shrink or enlarge images while preserving important visual content. Unlike naive scaling, it identifies and removes/duplicates low-energy seams (connected pixel paths) detected via Sobel edge detection, as detailed in the UC Berkeley seam carving paper referenced in the README. Monolithic single-package library with cmd/caire/main.go as the CLI entry point. Core algorithm in carver.go (seam finding), image.go (I/O), sobel.go (edge detection), with utils/ for helpers and imop/ for image operations (blend, compose). GUI layer in gui.go uses Gioui. Tests colocated with source files (*_test.go pattern).

Image processing engineers, CLI tool users, and Go developers who need to resize images intelligently without distorting faces or important content. The library serves both programmatic use (via the Go API) and end-users (via the cmd/caire CLI with GUI progress indicator).

Production-ready and actively maintained. Version 1.5.0 is released with Homebrew and Snapcraft distribution, CI/CD via GitHub Actions (build.yml workflow present), and comprehensive test coverage (carver_test.go, image_test.go, processor_test.go). Go 1.22 minimum requirement and recent dependency updates suggest active development.

Low risk overall but watch for: single primary maintainer (esimov), moderate dependency surface (gioui.org for GUI, disintegration/imaging, esimov/pigo for face detection), and reliance on cgo-free image libraries. GUI via Gioui is less common in Go so platform compatibility quirks possible. No visible security audit history.

No specific PR or milestone data visible in file structure, but the codebase shows recent updates (Go 1.22 requirement, Gioui v0.8.0 dependency). The presence of carver_benchmark_test.go suggests performance optimization is an active concern.

Clone and build: git clone https://github.com/esimov/caire.git && cd caire && make build. The Makefile is present at root. Binary will be in cmd/caire/. Run with ./caire -h for CLI usage or import the package in Go code.

Daily commands: Build binary: make build (creates cmd/caire executable). Run CLI: ./caire -in input.jpg -out output.jpg -width 800 -height 600. For GUI preview during resize: ./caire -in input.jpg -width 800 -height 600 -preview. See README.md for full flag list.

• carver.go — Core seam carving algorithm implementation—the heart of content-aware resizing that all other components depend on.
• processor.go — Main image processing orchestrator that coordinates carving, scaling, and output; entry point for the resizing pipeline.
• cmd/caire/main.go — CLI entry point and command-line argument parsing; shows how users interact with the library.
• image.go — Image loading, validation, and basic manipulation; foundation for all image operations.
• sobel.go — Edge detection using Sobel operator—generates the energy map that guides the seam carving algorithm.
• gui.go — GUI implementation using Gio framework; demonstrates interactive preview of resizing operations.
• go.mod — Module dependencies including imaging, pigo (face detection), and Gio UI—critical for understanding external integrations.

• Carver (carver.go) (Go stdlib image manipulation, dynamic programming) — Implements the core seam carving algorithm: computes dynamic programming table, backtracks to find minimum energy seams, and removes or adds seams for resizing.
  • Failure mode: Incorrect seam selection due to energy map errors; produces distorted or incorrectly resized images.
• Energy Map Generator (sobel.go) (Sobel convolution, optional Gaussian blur) — Generates edge detection energy maps using Sobel operator; identifies visually important regions in the image.
  • Failure mode: Poor edge detection leads to carving through important content; uniform energy maps prevent content-aware resizing.
• Processor (processor.go) (Image I/O, carver invocation, format handling) — Orchestrates the complete resizing pipeline: loads images, calls carver/scaler, manages output format, and handles both horizontal and vertical resizing.
  • Failure mode: Pipeline state corruption or incorrect dimension ordering; produces incompletely resized images.
• Image Handler (image.go) (Go image/jpeg, image/png, disintegration/imaging) — Handles image loading, validation, format detection, and basic transformations; manages image metadata and colorspace.
  • Failure mode: Unsupported format or corrupted image file; prevents processing from starting.
• GUI Controller (gui.go, preview.go) (Gio framework, retained-mode rendering) — Provides interactive interface for real-time preview and parameter adjustment; renders live carving results.
  • Failure mode: Rendering lag or unresponsive preview; users cannot efficiently tune parameters.
• CLI Interface (cmd/caire/main.go) — Parses command-line arguments, validates inputs, and initiates processing; entry point for batch automation.

Add a new energy map generation method

1. Create a new Go file (e.g., 'canny.go') with an energy detection function following the signature of Sobel in sobel.go (sobel.go)
2. Add a new method to the Carver struct in carver.go to call your energy function during initialization (carver.go)
3. Add CLI flag to processor.go or main.go to allow users to select the energy method (processor.go)

Add support for a new output image format

1. Extend the format detection logic in image.go to recognize the new format in NewImage() (image.go)
2. Add encoding/decoding code in image.go or create a new file handling the format-specific operations (image.go)
3. Update utils/format.go to include the new format in output options (utils/format.go)

Integrate a new face detection library

1. Add the new face detection dependency to go.mod (currently uses pigo via esimov/pigo) (go.mod)
2. Extend processor.go to use the new detector and generate a protection mask before carving (processor.go)
3. Update carver.go to apply the protection mask as constraints when selecting seams (carver.go)

Add a new GUI preview mode or control

1. Extend gui.go to add new UI components using Gio framework definitions (gui.go)
2. Update preview.go to render the new visualization or control state (preview.go)
3. Connect the new control to processor.go to apply different processing options (processor.go)

• Go language — High performance for image processing with built-in concurrency; strong standard library for image manipulation.
• Seam carving algorithm — Content-aware resizing that preserves important image features better than naive scaling; based on peer-reviewed research.
• Sobel edge detection — Efficient gradient-based edge detection to generate energy maps; well-established for identifying visually important regions.
• Gio framework (GUI) — Cross-platform GUI toolkit with retained-mode rendering; suitable for interactive preview and real-time parameter adjustment.
• pigo face detection — Face detection integration to protect facial regions during carving; prevents distortion of important semantic content.

• Single-pass dynamic programming for seam selection

  • Why: Computational efficiency and real-time responsiveness
  • Consequence: May not find globally optimal seams in all cases; greedy approach trades optimality for speed.

• Iterative seam removal rather than batch processing

  • Why: Allows energy recalculation after each seam removal, adapting to content changes
  • Consequence: Slower than batch removal but produces higher-quality results with better content preservation.

• Support for both CLI and GUI interfaces

  • Why: Flexibility for batch processing (CLI) and interactive use (GUI)
  • Consequence: Maintains two separate code paths; increased complexity in argument handling and execution flow.

• In-memory image processing

  • Why: Fast computation without disk I/O overhead; leverages Go's efficient memory management
  • Consequence: Limited to available RAM; very large images may cause out-of-memory errors.

• Real-time video processing or streaming resizing
• GPU-accelerated computation (CPU-only implementation)
• Batch processing with distributed computing
• Integration with cloud storage backends
• Lossless compression or format-specific optimization
• Support for animated image formats (GIF, APNG)

Gioui GUI requires platform-specific backend setup (X11 on Linux, requires CGO context); headless CLI operation is safer. Face detection via pigo requires downloading the facefinder cascade data to data/facefinder/ before use (-facedetect flag). Energy matrix computation is memory-intensive for large images. Seam carving direction (horizontal vs vertical) matters significantly for aspect ratio changes; poorly chosen sequence can distort content.

• Seam Carving — The foundational algorithm powering Caire; understanding seam detection via dynamic programming and backtracking is essential to modifying the core resize logic
• Sobel Edge Detection — Used in sobel.go to compute the energy map that guides which seams are least important; modifying edge detection changes what the algorithm considers content
• Dynamic Programming (Shortest Path via Cumulative Cost) — The carver.go algorithm computes cumulative minimum energy matrices and backtracks the minimum path; this DP pattern is core to seam finding efficiency
• Image Blending / Content-Aware Fill — When enlarging images (seam insertion), imop/blend.go blends neighboring pixels; understanding blending modes helps tune output quality
• Stack Blur (Integral Image Approximation) — stackblur.go implements a fast box blur via integral images rather than convolution; understanding this optimization matters for performance tuning on large images
• Cascade Classifiers (Face Detection) — pigo integration enables face detection to protect faces during resize; understanding classifier-based detection helps tune detection thresholds in processor.go
• Gioui Immediate Mode GUI — gui.go uses Gioui's immediate-mode paradigm (redraw every frame) rather than retained mode; understanding this pattern helps modify the preview UI

• alyxferrari/seam_carving — Alternative pure Python seam carving implementation; useful for algorithm understanding or cross-validation of carving results
• virajmavani/seam-carving — Another reference implementation with visual documentation of the algorithm steps; good for learning complementary perspectives
• esimov/pigo — Direct dependency of Caire; face detection library by the same author used for optional content preservation during resizes
• disintegration/imaging — Direct dependency providing image decoding/encoding (JPEG, PNG, WebP) and basic transforms that Caire builds upon

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 benchmarking and profiling CI workflow

The repo has carver_benchmark_test.go but no CI workflow to track performance regressions across Go versions and platforms. This would prevent unintended performance degradation in future releases, which is critical for an image processing library where CPU/memory efficiency is a core feature.

• [ ] Create .github/workflows/benchmark.yml to run 'go test -bench ./...' on carver_benchmark_test.go
• [ ] Store benchmark results as artifacts or comments on PRs using action-benchmark or similar
• [ ] Add baseline benchmarks for different image sizes (small, medium, large) to catch regressions early
• [ ] Include memory profiling for the seam carving algorithm to track heap allocations

Add integration tests for GUI preview functionality

The gui.go and preview.go files handle UI rendering via gioui.org, but there are no tests in gui_test.go or preview_test.go. Testing the preview rendering pipeline and GUI state transitions would catch regressions when updating gioui.org dependencies.

• [ ] Create preview_test.go with tests for preview window initialization and image loading
• [ ] Create gui_test.go with mock tests for GUI state management (zoom, pan, comparison views)
• [ ] Add tests for the preview callback handlers referenced in gui.go
• [ ] Verify GUI renders correctly with different image sizes and aspect ratios

Add platform-specific tests for utils package with download functionality

The utils/download.go has a download_test.go but likely lacks cross-platform testing for file I/O and OS-specific behaviors. Since cmd/caire uses these utilities, adding tests for Windows/Linux/macOS path handling and temp file cleanup would improve reliability.

• [ ] Enhance utils/download_test.go with platform-specific subtests for os.Temp() handling on Windows vs Unix
• [ ] Add tests for utils/format.go to verify image format detection across file extensions and MIME types
• [ ] Test utils/spinner.go with term package for terminal compatibility (referenced in go.mod as golang.org/x/term)
• [ ] Add cleanup verification tests to ensure temporary files are properly removed after image processing

• Add missing unit tests for stackblur.go — currently no *_test.go file exists despite the blur being used in energy computation; write tests validating blur kernel outputs against expected gaussian distribution.
• Expand utils/format.go test coverage — image_test.go exists but utils tests are minimal; add tests for edge cases in format detection and file extension handling in utils/format.go.
• Document energy map visualization — add a -debug flag to cmd/caire/main.go that exports the Sobel energy map as a visual grayscale image, useful for debugging seam selection; implementation sketched in draw.go but not wired to CLI.

The codebase demonstrates reasonable security practices for an image processing library, with no obvious injection vulnerabilities or hardcoded secrets. However, the security posture is weakened by outdated dependencies, particularly golang.org/x/term (2+ years old) and the Go version itself. The main concerns are dependency currency and potential file handling risks in image processing operations. The project uses Go's built-in security features and avoids common pitfalls like SQL injection. Recommend updating all dependencies to current versions and ensuring robust input validation for file and image processing operations.

• Medium · Outdated Go Version — go.mod. The project specifies 'go 1.22' which may not receive security updates. Go 1.22 reached end-of-life in August 2024. Using outdated Go versions exposes the project to known security vulnerabilities in the language runtime and standard library. Fix: Update to the latest stable Go version (1.23 or newer) to ensure security patches and performance improvements are included.
• Medium · Outdated Dependency: golang.org/x/term — go.mod (golang.org/x/term v0.0.0-20220722155259-a9ba230a4035). The dependency 'golang.org/x/term' is pinned to version '2022-07-22', which is significantly outdated (over 2 years old). This may contain unpatched security vulnerabilities. Fix: Update golang.org/x/term to the latest version using 'go get -u golang.org/x/term'.
• Low · Outdated Dependency: disintegration/imaging — go.mod (github.com/disintegration/imaging v1.6.2). The 'github.com/disintegration/imaging' dependency is pinned to v1.6.2, released in 2017. While not critical, older image processing libraries may lack security hardening and bug fixes. Fix: Check for newer versions or maintained alternatives. If no newer versions exist, consider the security implications of using unmaintained image processing libraries.
• Low · Potential File Handling Risk in Image Processing — image.go, processor.go, exec.go. The codebase handles image files and resizing operations (seam carving algorithm). Without seeing the implementation details in image.go, exec.go, and processor.go, there's a potential risk of path traversal or unsafe file operations if user input is not properly validated. Fix: Ensure all file paths are validated and sanitized. Use filepath.Clean() and verify paths stay within expected directories. Implement proper input validation for image file handling.
• Low · Missing Input Validation Framework — cmd/caire/main.go. The cmd/caire/main.go CLI entry point may accept user input without comprehensive validation. Image dimensions, file paths, and processing parameters should be validated. Fix: Implement robust input validation for all command-line arguments, including file paths, image dimensions, and processing parameters. Set reasonable limits on image size and processing resources.

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.