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/kyleduo/TinyPNG4Mac 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 4w ago
• 2 active contributors
• MIT licensed
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 kyleduo/TinyPNG4Mac repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kyleduo/TinyPNG4Mac.

What it runs against: a local clone of kyleduo/TinyPNG4Mac — 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 kyleduo/TinyPNG4Mac | 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 ≤ 57 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kyleduo/TinyPNG4Mac(\\.git)?\\b" \\
  && ok "origin remote is kyleduo/TinyPNG4Mac" \\
  || miss "origin remote is not kyleduo/TinyPNG4Mac (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 "TinyPNG4Mac/TinyPNG4Mac/TinyPNG4MacApp.swift" \\
  && ok "TinyPNG4Mac/TinyPNG4Mac/TinyPNG4MacApp.swift" \\
  || miss "missing critical file: TinyPNG4Mac/TinyPNG4Mac/TinyPNG4MacApp.swift"
test -f "TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift" \\
  && ok "TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift" \\
  || miss "missing critical file: TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift"
test -f "TinyPNG4Mac/TinyPNG4Mac/app/AppContext.swift" \\
  && ok "TinyPNG4Mac/TinyPNG4Mac/app/AppContext.swift" \\
  || miss "missing critical file: TinyPNG4Mac/TinyPNG4Mac/app/AppContext.swift"
test -f "TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift" \\
  && ok "TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift" \\
  || miss "missing critical file: TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift"
test -f "TinyPNG4Mac/TinyPNG4Mac/client/TPQueue.swift" \\
  && ok "TinyPNG4Mac/TinyPNG4Mac/client/TPQueue.swift" \\
  || miss "missing critical file: TinyPNG4Mac/TinyPNG4Mac/client/TPQueue.swift"

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

TinyPNG4Mac is a native Swift macOS application that provides a desktop client for the TinyPNG image compression API, allowing users to compress PNG, JPEG, AVIF, and WEBP images without opening a browser. It supports drag-and-drop workflow, Finder context menu integration, automatic format conversion to select the smallest output format, and maintains a cache of compression statistics. Single Xcode project structure: TinyPNG4Mac/.xcodeproj contains the app target with Assets.xcassets managing UI resources (colors, icons, placeholders for light/dark modes). The project uses SwiftUI for UI with organized asset catalogs (taskRowBackground, settingViewBackground, etc.) suggesting a tabbed or view-based architecture with settings and main compression interfaces.

macOS users (13 Ventura+) who frequently compress images and want a streamlined desktop workflow without browser context-switching, and developers who need batch image optimization integrated into their local file management.

Actively maintained and production-ready. The project has evolved through 2.2.1 releases with feature additions (v2.0.0+ added format conversion and compression caching), uses modern Swift/SwiftUI patterns, and includes an Xcode project structure with workspace configuration. Last activity visible through organized CHANGE_LOG tracking suggests active development, though no explicit CI/CD configuration files appear in the top-level structure.

Low risk from dependencies (minimal Swift PM integration, self-contained UI), but single-maintainer project (@kyleduo) concentrates maintenance burden. macOS 13+ requirement gates older system support. No visible test suite in the file structure (no Tests/ directory or test targets in pbxproj), which is the primary technical gap for regression prevention.

v2.2.1 is current with recent features including format conversion (PNG/JPEG/AVIF/WEBP with automatic smallest-file selection) and compression count caching. CHANGE_LOG.md and CHANGE_LOG_ZH.md are maintained, indicating active feature iteration. The app was renamed from TinyPNG4Mac to 'Image Image' for trademark compliance.

git clone https://github.com/kyleduo/TinyPNG4Mac.git
cd TinyPNG4Mac/TinyPNG4Mac
open TinyPNG4Mac.xcodeproj
# Build and run via Xcode (⌘R) or xcodebuild
xcodebuild -scheme TinyPNG4Mac -configuration Release

Daily commands: Open TinyPNG4Mac.xcodeproj in Xcode and press ⌘R to build and run. Requires macOS 13 Ventura or later. The app requires a TinyPNG API key configured in the Settings window before use.

• TinyPNG4Mac/TinyPNG4Mac/TinyPNG4MacApp.swift — Application entry point and SwiftUI app setup; defines the main window lifecycle and app initialization
• TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift — Core TinyPNG API client; handles all communication with TinyPNG compression service and manages compression requests
• TinyPNG4Mac/TinyPNG4Mac/app/AppContext.swift — Shared application state and context; manages API key storage, settings persistence, and global app configuration
• TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift — Main UI state management; coordinates compression task processing, queue management, and UI updates
• TinyPNG4Mac/TinyPNG4Mac/client/TPQueue.swift — Task queue manager; handles concurrent compression job scheduling and progress tracking
• TinyPNG4Mac/TinyPNG4Mac/windows/MainContentView.swift — Primary UI view; presents the drag-drop interface and task list to users
• TinyPNG4Mac/TinyPNG4Mac/utils/FileUtils.swift — File system operations; manages image file I/O, path resolution, and output directory handling

Add Support for a New Image Format

1. Add the new format case to the ImageType enum (TinyPNG4Mac/TinyPNG4Mac/model/ImageType.swift)
2. Update TPClient.swift to handle the new format's MIME type and API parameters in the compression request (TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift)
3. Update FileUtils.swift to recognize the file extension when scanning for images (TinyPNG4Mac/TinyPNG4Mac/utils/FileUtils.swift)
4. Add localization strings for the new format in Localizable.xcstrings (TinyPNG4Mac/TinyPNG4Mac/Localizable.xcstrings)

Add a New Setting Option

1. Add property to AppContext.swift to store the setting value with @AppStorage wrapper (TinyPNG4Mac/TinyPNG4Mac/app/AppContext.swift)
2. Add UI control (toggle, picker, etc.) to SettingsView.swift (TinyPNG4Mac/TinyPNG4Mac/windows/SettingsView.swift)
3. Use the setting in relevant business logic files (e.g., TPClient.swift or MainViewModel.swift) (TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift)
4. Add localization label string in Localizable.xcstrings (TinyPNG4Mac/TinyPNG4Mac/Localizable.xcstrings)

Add a New UI Component or View

1. Create new SwiftUI View struct in views/ or windows/ directory following naming convention (TinyPNG4Mac/TinyPNG4Mac/views/)
2. If the view needs state, add an @ObservedObject or @StateObject property bound to MainViewModel or a new ViewModel (TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift)
3. Integrate the new view into MainContentView.swift or SettingsView.swift as appropriate (TinyPNG4Mac/TinyPNG4Mac/windows/MainContentView.swift)
4. Add any required localized strings to Localizable.xcstrings (TinyPNG4Mac/TinyPNG4Mac/Localizable.xcstrings)

Handle a New Error Condition

1. Add error case to Errors.swift enum (TinyPNG4Mac/TinyPNG4Mac/model/Errors.swift)
2. Throw the error from TPClient.swift or FileUtils.swift where the condition occurs (TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift)
3. Catch and handle in MainViewModel.swift, updating task status and UI state (TinyPNG4Mac/TinyPNG4Mac/vms/MainViewModel.swift)
4. Add localized error message string in Localizable.xcstrings for user display (TinyPNG4Mac/TinyPNG4Mac/Localizable.xcstrings)

• SwiftUI — Native macOS UI framework providing modern, reactive, declarative UI with automatic data binding via @State/@ObservedObject
• Combine Framework — SwiftUI reactive bindings and async/await support for handling asynchronous API calls and progress updates
• URLSession — Native Swift networking for REST API calls to TinyPNG service; simple, standard macOS HTTP handling
• Foundation FileManager — Native macOS file system API for reading, writing, and traversing image files and directories

Xcode 14+ Required: Project structure (SwiftUI, SwiftPM integration) requires relatively recent Xcode; older versions will not build. API Key Persistence: Settings window stores TinyPNG API key; check how keychain/UserDefaults handles this to avoid exposing keys in logs. macOS 13 Minimum: All code must target macOS 13 SDK; testing on older systems is blocked by framework choice. Finder Services Configuration: Context menu 'Compress with Tiny Image' requires explicit Info.plist entry for NSServices; misconfiguration silently breaks Finder integration. No Visible Tests: Test target or test suite not present in file list, so manual testing or new test infrastructure required.

• macOS Finder Services (NSServices) — Enables the 'Compress with Tiny Image' context menu integration; requires Info.plist configuration and understanding of Apple's service provider API to debug Finder integration
• SwiftUI Light/Dark Mode Asset Catalogs — The codebase heavily uses named color sets (mainViewBackground, taskRowBackground) that automatically switch between light/dark; understanding asset appearance sets is critical for UI consistency
• Image Format Conversion Strategy (Lossy vs. Lossless) — The v2.0.0+ feature that auto-selects smallest format (PNG/JPEG/AVIF/WEBP) requires understanding compression trade-offs; AVIF and WEBP are newer and require careful quality parameter tuning
• Swift Package Manager (SwiftPM) Dependency Resolution — Package.resolved locks dependency versions; understanding SwiftPM is essential for adding new dependencies or troubleshooting build reproducibility
• macOS App Code Signing and Notarization — The README mentions checking System Settings > Security & Privacy for app opening issues; proper code signing and Apple notarization are required for distribution
• URLSession and HTTP API Client Patterns — TinyPNG API communication requires robust HTTP client handling (likely using URLSession); rate limiting, error recovery, and multipart form data for image uploads are critical
• Drag-and-Drop UI Patterns in macOS — Core UX feature (mentioned in README: 'Drag images or directories'); SwiftUI drop zone implementation and file URL handling are central to the app's ergonomics

• imagemin/imagemin — JavaScript-based image compression tool with similar format conversion goals (PNG/JPEG/WEBP), useful for comparison of optimization strategies
• mortenjust/droptogif — Explicitly mentioned in README as inspiration for TinyPNG4Mac's window/drag-drop architecture; reference implementation for macOS native client patterns
• tinybench/tinypng-python-api — Python wrapper around TinyPNG API; useful reference for understanding API contract and error handling before integration
• Homebrew/homebrew-cask — macOS app distribution mechanism where TinyPNG4Mac could be distributed; relevant for understanding app packaging and signing requirements
• pointfreeco/swift-composable-architecture — Modern Swift architecture pattern for state management that could refactor current UI into testable, composable modules (adjacent technology not currently in use)

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 unit tests for image compression and format conversion logic

The repo lacks visible test files despite having core compression and format conversion features (PNG, JPEG, AVIF, WEBP). The TinyPNG4Mac/TinyPNG4Mac/app directory likely contains business logic for API calls and image processing that should be tested to ensure reliability across format conversions and ensure the cache mechanism for compressed image counts works correctly.

• [ ] Create TinyPNG4Mac/TinyPNG4MacTests directory structure
• [ ] Add unit tests for API key validation and TinyPNG API communication in the app layer
• [ ] Add unit tests for image format conversion logic to verify all supported formats (PNG, JPEG, AVIF, WEBP) are handled correctly
• [ ] Add unit tests for the cache mechanism that tracks the number of images compressed
• [ ] Configure Xcode project to run tests via scheme in project.pbxproj

Add GitHub Actions CI workflow for building and code quality checks

The repo has no visible .github/workflows directory. Adding a CI pipeline would catch build failures, API compatibility issues, and ensure the app builds successfully on multiple macOS versions (especially important since v2.2.1+ requires macOS 13+). This is critical for a macOS app where version compatibility matters.

• [ ] Create .github/workflows/build.yml to build the Xcode project on macOS runners
• [ ] Add matrix testing for macOS 13 and later versions to verify version compatibility claims
• [ ] Include SwiftLint or similar static analysis tools to catch code quality issues
• [ ] Configure workflow to run on PR creation and pushes to main/develop branches
• [ ] Add build status badge to README.md

Document API and data models for the app layer in TinyPNG4Mac/TinyPNG4Mac/app

The file structure shows there is an 'app' directory under TinyPNG4Mac/TinyPNG4Mac but no documentation explaining the architecture, key classes, or data flow. New contributors need to understand how the image compression workflow, API integration, and UI state management work together. Adding inline documentation or an ARCHITECTURE.md would reduce onboarding friction.

• [ ] Create ARCHITECTURE.md documenting the app's layered structure and data flow from UI to API
• [ ] Document the main data models (e.g., compression task model, API response models) with inline code comments
• [ ] Add docstrings to key classes/functions in the app directory explaining their responsibilities
• [ ] Document how the API key is stored and retrieved from settings
• [ ] Explain the caching mechanism for tracking compressed image counts with examples

• Add unit tests for TinyPNG API response parsing (create Tests/ directory with XCTest covering success/error/rate-limit responses) — critical gap given no visible test suite
• Implement dark mode color refinement — audit Assets.xcassets color definitions (mainViewBackground, taskRowBackground, etc.) against current dark mode rendering and file issues for colors that don't meet contrast ratios
• Document API key security model in README — clarify whether keys are stored in Keychain or UserDefaults, add security best practices section, and reference Apple's SecureEnclave usage if applicable

• High · API Key Storage in Plain Text — TinyPNG4Mac/TinyPNG4Mac/app/AppConfig.swift. The application stores TinyPNG API keys in user settings without apparent encryption. API keys are sensitive credentials that should never be stored in plain text. If the settings file is compromised, attackers can use the API key to impersonate the user and exhaust their TinyPNG quota or perform unauthorized image compression. Fix: Store API keys in the macOS Keychain using SecureEncodable or similar secure storage mechanism. Never persist credentials in plain text configuration files.
• High · Missing Input Validation on API Keys — TinyPNG4Mac/TinyPNG4Mac/app/AppConfig.swift, TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift. The application accepts API keys from user input in the Settings window without apparent validation or sanitization. Malformed or malicious input could lead to unexpected behavior or API calls with invalid credentials. Fix: Implement strict input validation for API keys. Verify format, length, and character set before accepting user input. Display clear error messages for invalid credentials.
• Medium · Potential Insecure HTTP Communication — TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift. The codebase makes HTTP requests to TinyPNG API (TPClient.swift). If HTTPS is not enforced or certificate validation is disabled, API keys and image data could be intercepted in transit. Fix: Ensure all API communications use HTTPS with certificate pinning. Verify that URLSession is configured with proper security policies and certificate validation is enabled.
• Medium · File Path Traversal Risk in File Operations — TinyPNG4Mac/TinyPNG4Mac/utils/FileUtils.swift, TinyPNG4Mac/TinyPNG4Mac/client/TPQueue.swift. The application processes user-dragged files and directories (FileUtils.swift, TPQueue.swift). Without proper path validation, attackers could potentially craft symlinks or use path traversal techniques to access or compress unauthorized files. Fix: Validate and canonicalize all file paths. Ensure files are within expected directories. Use realpath() to resolve symbolic links and verify the actual file location before processing.
• Medium · Unvalidated Image Processing — TinyPNG4Mac/TinyPNG4Mac/model/ImageType.swift, TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift. The application processes image files without apparent validation of file format or content. A malformed or malicious image file could trigger unexpected behavior or be used for denial-of-service attacks. Fix: Validate image file signatures (magic numbers) before processing. Implement file size limits and timeout mechanisms. Use secure image processing libraries with proper error handling.
• Medium · Missing CORS/CSRF Protections — TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift. While this is a native macOS application, the HTTP client making requests to external TinyPNG API should implement proper request validation and anti-CSRF tokens if applicable. Fix: Implement request signing with timestamps and nonces. Use TLS mutual authentication where possible. Add request-response correlation headers.
• Low · Sensitive Information in Logs — TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift, TinyPNG4Mac/TinyPNG4Mac/utils/. Without reviewing actual logging code, there's a risk that API keys, file paths, or image metadata could be logged during debugging or error handling, potentially exposing sensitive information. Fix: Implement secure logging that redacts sensitive information. Never log API keys, authentication tokens, or personally identifiable information. Use conditional compilation to disable verbose logging in release builds.
• Low · Missing Error Handling for Network Operations — TinyPNG4Mac/TinyPNG4Mac/client/TPClient.swift. Network operations to TinyPNG API (TPClient.swift) should have comprehensive error handling. Incomplete error handling could expose technical details or cause crashes. Fix: Implement comprehensive error handling with proper error codes and user-friendly messages. Handle network timeouts, SSL errors,

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.