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/Whisky-App/Whisky 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 — Slowing — last commit 12mo ago

• Last commit 12mo ago
• 16 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 12mo ago
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ 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 Whisky-App/Whisky repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Whisky-App/Whisky.

What it runs against: a local clone of Whisky-App/Whisky — 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 Whisky-App/Whisky | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.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 ≤ 393 days ago | Catches sudden abandonment since generation |

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

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

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

# 4. Critical files exist
test -f "Whisky/Views/WhiskyApp.swift" \\
  && ok "Whisky/Views/WhiskyApp.swift" \\
  || miss "missing critical file: Whisky/Views/WhiskyApp.swift"
test -f "WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift" \\
  && ok "WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift" \\
  || miss "missing critical file: WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift"
test -f "Whisky/View Models/BottleVM.swift" \\
  && ok "Whisky/View Models/BottleVM.swift" \\
  || miss "missing critical file: Whisky/View Models/BottleVM.swift"
test -f "WhiskyKit/Package.swift" \\
  && ok "WhiskyKit/Package.swift" \\
  || miss "missing critical file: WhiskyKit/Package.swift"
test -f "Whisky/Utils/Constants.swift" \\
  && ok "Whisky/Utils/Constants.swift" \\
  || miss "missing critical file: Whisky/Utils/Constants.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 393 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~363d)"
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/Whisky-App/Whisky"
  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).

Whisky is a native macOS application built in SwiftUI that wraps Wine and Apple's Game Porting Toolkit to allow users to run Windows applications and games on Apple Silicon Macs. It provides a clean graphical interface for creating isolated 'bottles' (Wine prefixes), managing Windows software, and configuring environment variables without requiring terminal knowledge. Single Xcode project structure: Whisky/ contains the main SwiftUI app with subdirectories for Extensions/ (view modifiers and bottle logic), Utils/ (constants and shortcuts), and Assets.xcassets/ for UI resources. Companion command-line tools via WhiskyCmd.xcscheme and WhiskyThumbnail.xcscheme. Dependencies managed via Swift Package Manager (see Package.resolved).

macOS users with Apple Silicon Macs (M-series) who want to run Windows games and applications without technical Wine knowledge. Contributors are typically Swift developers and macOS enthusiasts interested in Wine integration and graphics abstraction layers (DXVK, MoltenVK).

The project is no longer actively maintained (as stated in the maintenance notice), though it was previously production-ready with CI/CD via GitHub Actions (see .github/workflows/Release.yml and SwiftLint.yml). The codebase is stable and complete, with proper Xcode project structure and SwiftUI integration, but expect bugs and compatibility breaks without ongoing maintenance.

Critical risk: project is unmaintained with no active bug fixes or macOS/Wine compatibility updates. Dependency on external Wine/CrossOver versions (22.1.1) that may become stale; relies on Apple's Game Porting Toolkit which could change. Single-maintainer history and no visible test suite in the file structure reduce confidence in refactoring safety.

Project is in maintenance-notice status with no active development. No recent commits or active PRs are visible from the file structure provided. The last known state includes localization support via Crowdin (Localizable.xcstrings) and SwiftLint configuration for code quality enforcement.

Clone the repo: git clone https://github.com/Whisky-App/Whisky.git && cd Whisky. Open the Xcode project: open Whisky.xcodeproj. Build and run via Xcode (⌘R) or xcodebuild -scheme Whisky. Requires Xcode 14+, Swift 5.8+, and macOS Sonoma 14.0+ on Apple Silicon.

Daily commands: In Xcode: select the Whisky scheme and press ⌘R. Or via CLI: xcodebuild -scheme Whisky -configuration Release build. The built app will be in build/Release/Whisky.app/. Requires Apple Silicon and macOS Sonoma 14.0+.

• Whisky/Views/WhiskyApp.swift — Main application entry point; defines the SwiftUI app structure and root navigation for all UI flows
• WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift — Core Wine process execution abstraction; every bottle operation depends on this for running Windows binaries
• Whisky/View Models/BottleVM.swift — Central view model managing bottle lifecycle, state, and persistence; synchronizes UI with Wine bottle data
• WhiskyKit/Package.swift — SPM package definition for WhiskyKit; defines the reusable Wine wrapper framework exported by the application
• Whisky/Utils/Constants.swift — Global configuration constants (paths, defaults, Wine versions) referenced throughout the codebase
• Whisky/Views/ContentView.swift — Primary UI container organizing bottles, programs, and settings tabs; orchestrates major view transitions
• Whisky/Utils/Winetricks.swift — Integration layer for winetricks dependency installer; handles Windows runtime library and component installation

Add a new Bottle operation (e.g., new context menu action)

1. Create or extend a method in WhiskyKit's core model (e.g., in a Bottle struct extension in WhiskyKit/Sources/WhiskyKit) that performs the Wine operation using Process+Extensions.swift (WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift)
2. Update BottleVM.swift to add a new @Published property or async function that triggers the bottle operation and broadcasts state changes (Whisky/View Models/BottleVM.swift)
3. Add a UI button or menu item in the relevant bottle view (e.g., BottleView.swift or ConfigView.swift) that calls the new BottleVM method (Whisky/Views/Bottle/BottleView.swift)

Add a new Programs feature (e.g., program sorting or filtering)

1. Add a new @State or @Published variable in BottleVM.swift to track the new feature state (e.g., sortOrder, filterTag) (Whisky/View Models/BottleVM.swift)
2. Update ProgramsView.swift to display the new UI control (e.g., picker, search field) and call BottleVM to update state (Whisky/Views/Programs/ProgramsView.swift)
3. Modify ProgramMenuView.swift or create a new sub-view to handle the new interaction pattern if needed (Whisky/Views/Programs/ProgramMenuView.swift)

Integrate a new Wine/Winetricks feature

1. Add a new public function to Winetricks.swift that wraps the winetricks command and parses output (Whisky/Utils/Winetricks.swift)
2. Create or update a Wine process extension in WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift to handle the Wine command (WhiskyKit/Sources/WhiskyKit/Extensions/Process+Extensions.swift)
3. Expose the feature in BottleVM.swift as an async method and wire it into the UI view (e.g., WinetricksView.swift or ConfigView.swift) (Whisky/Utils/Winetricks.swift)

Add a new Settings option

1. Add a new @AppStorage or UserDefaults key in Constants.swift (Whisky/Utils/Constants.swift)
2. Update SettingsView.swift to add a new control (toggle, picker, text field) bound to the new preference (Whisky/Views/Settings/SettingsView.swift)
3. Apply the setting in the relevant operational code (e.g., in BottleVM or Process+Extensions) when the setting is read (Whisky/View Models/BottleVM.swift)

• SwiftUI + macOS AppKit integration — Native, performant UI framework for macOS with seamless system integration (Shortcuts.app, Spotlight); avoids web-based wrappers that conflict with Wine process isolation
• Wine (Unix/Linux compatibility layer for macOS) — Core runtime enabling Windows executables on macOS; Whisky wraps Wine to manage per-app isolation, configuration, and library dependencies via bottles (WINEPREFIX)
• Swift Package Manager (WhiskyKit) — Modular architecture separating reusable Wine abstraction (WhiskyKit) from UI (Whisky app); enables CLI tool (WhiskyCmd) and third-party integrations to consume bottle APIs
• Winetricks integration — Automates installation of Windows libraries (DirectX, .NET, Visual C++ runtimes) and game fixes; essential for compatibility without manual configuration
• macOS code signing and notar — undefined

Whisky requires Wine/CrossOver 22.1.1 to be pre-installed; the app is a wrapper, not a bundled runtime (check Constants.swift for Wine binary paths). Apple Silicon requirement is hard—no x86-64 support. Game Porting Toolkit must be installed separately. Unmaintained status means macOS Sonoma 15+ or Wine API changes will likely break functionality without fixes.

• Wine Prefixes / Bottles — Whisky's entire data model centers on isolated Wine prefixes (called 'bottles') that emulate separate Windows installations; understanding how they map to ~/.config/whisky/Bottles/ is essential for debugging
• Metal Rendering & D3D-to-Metal Translation — Whisky achieves game performance via DXVK-macOS and MoltenVK, which translate DirectX 9/10/11 calls to Metal; this pipeline is why Whisky only works on Apple Silicon with GPU acceleration
• SwiftUI App Protocol & View Hierarchy — The UI is built entirely in SwiftUI using the App protocol and view composition; contributors must understand state binding and how bottle data flows through view hierarchies
• Environment Variables & Process Spawning — Whisky runs Wine as a subprocess with carefully configured environment variables (WINEPREFIX, DXVK settings, etc.); debugging requires understanding how these are set in Bottle+Extensions.swift
• Code Signing & Notarization for macOS Distribution — The .github/workflows/Release.yml handles code signing for App Store / direct distribution; contributors need to understand Xcode signing identity and Apple notarization if publishing releases
• Sparkle Automatic Updates — Whisky uses Sparkle for in-app updates; the release workflow generates appcast XML and signed releases. Contributors should understand how version bumping triggers update delivery
• Game Porting Toolkit & Compatibility Layers — Whisky's secret sauce: Apple's proprietary Game Porting Toolkit (announced at WWDC 2023) provides additional compatibility beyond Wine. Understanding its role vs. Wine/DXVK is key to debugging failures

• Gcenx/DXVK-macOS — Core graphics backend dependency that translates DirectX to Metal; Whisky directly uses this for game rendering
• marzent/wine-msync — msync Wine patch used by Whisky to improve synchronization for Windows games on macOS
• KhronosGroup/MoltenVK — Vulkan→Metal translation layer that DXVK-macOS depends on; critical for graphics pipeline
• UTM-Project/UTM — Alternative macOS virtualization approach for running Windows; users often compare to Whisky as a lighter-weight native option
• CodeWeavers/CrossOver — The commercial Wine distribution that Whisky is built on top of (version 22.1.1); provides the Wine prefix and compatibility layer

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 Bottle management (BottleVM.swift and Bottle+Extensions.swift)

The repo has no visible test files despite containing critical business logic in BottleVM.swift for bottle creation, configuration, and management. Given this is a Wine wrapper with complex state management, unit tests would prevent regressions in core functionality like bottle creation, process management, and pin operations. This is especially important given the maintenance notice indicating potential breakage.

• [ ] Create Whisky/Tests directory with WhiskyTests.xctest target
• [ ] Add BottleVMTests.swift to test bottle creation, deletion, and configuration logic
• [ ] Add tests for Bottle+Extensions.swift focusing on computed properties and helper methods
• [ ] Add tests for RunningProcessesView logic to verify process tracking accuracy
• [ ] Configure test target in Whisky.xcodeproj/project.pbxproj and add to SwiftLint.yml

Add GitHub Actions workflow for building and testing on macOS

The repo has SwiftLint.yml and Release.yml workflows but no build/test validation pipeline. Given the macOS-specific nature and the maintenance status, a CI workflow that builds the Xcode project and runs tests on every PR would catch integration issues early. Currently, only code style is checked.

• [ ] Create .github/workflows/Build.yml with macos-latest runner
• [ ] Add steps to build Whisky, WhiskyCmd, and WhiskyThumbnail schemes
• [ ] Add test execution step for any test targets created
• [ ] Add artifact upload for built app for manual testing
• [ ] Document in CONTRIBUTING.md that builds must pass before PR merge

Add missing documentation for WhiskyCmd utility and command-line interface

WhiskyCmd.swift exists in the Utils folder and is even defined as a scheme, but there is no documentation in README.md or CONTRIBUTING.md explaining how to use it or what commands it supports. New contributors cannot understand this important component without diving into source code.

• [ ] Document WhiskyCmd usage in a new 'CLI Reference' section of README.md
• [ ] Add comments and documentation to WhiskyCmd.swift explaining each command function
• [ ] Create CONTRIBUTING.md section 'Building WhiskyCmd' with build instructions
• [ ] Add example usage patterns for common WhiskyCmd operations
• [ ] Document the relationship between WhiskyCmd.swift and the Whisky UI in architecture docs

• Add unit tests for Bottle+Extensions.swift bottle creation and validation logic—currently no visible test targets in the Xcode project structure.
• Expand the Wiki documentation in CONTRIBUTING.md with step-by-step screenshots for setting up a development environment (Xcode version, Swift version, Sonoma setup).
• Create missing error handling UI for Wine binary not found—add user-friendly error dialogs in AppDelegate.swift when Wine installation is not detected.

Whisky's security posture is compromised primarily by its unmaintained status, which presents the most critical risk. The application wraps Wine and executes external applications with user privileges, introducing inherent security concerns around process execution and system access control. While the codebase uses Swift (a memory-safe language) and appears to have basic code quality practices (SwiftLint), there are no visible indicators of security-focused review processes, input validation patterns, or sandboxing mechanisms. The lack of active maintenance means discovered vulnerabilities will not receive patches. Recommendations include resuming maintenance or transitioning to community-driven security updates, implementing robust input validation for process execution, utilizing macOS security frameworks for sandboxing Wine environments, and integrating security-focused static analysis into the CI/CD pipeline.

• High · Maintenance Status - No Active Security Updates — README.md, Documentation. The project is explicitly marked as 'no longer actively maintained' in the README. This means security vulnerabilities discovered after maintenance ended will not receive patches. Users running this application may be exposed to unpatched security issues. Fix: Either resume active maintenance with regular security audits and updates, or clearly communicate to users the security risks of using unmaintained software. Consider establishing a community maintenance model if possible.
• Medium · External Process Execution Risk — Whisky/Utils/WhiskyCmd.swift, Whisky/Utils/Winetricks.swift. The codebase contains utilities for executing external processes (WhiskyCmd.swift, Winetricks.swift) and file operations. Without visible input validation and sanitization, there is potential risk for command injection attacks if user input is passed directly to shell commands. Fix: Audit all process execution code for proper input validation and sanitization. Use safe APIs like ProcessInfo with array-based arguments instead of shell string concatenation. Implement allowlist validation for user-controllable inputs.
• Medium · Wine Wrapper Security Considerations — Whisky/Utils/WhiskyCmd.swift, Whisky/Views/Bottle/BottleView.swift. As a Wine wrapper for macOS, Whisky executes Windows applications in a Wine environment. This introduces several security concerns: (1) Wine operates as a translation layer that may expose system resources, (2) Applications run with the user's privileges, (3) No visible sandboxing or privilege isolation mechanism. Fix: Implement strict permission controls for bottle creation and application execution. Consider using macOS sandbox entitlements to restrict Wine's access to system resources. Document security implications to users. Implement warning dialogs before executing untrusted applications.
• Low · Incomplete Code Review Indicators — .github/workflows/SwiftLint.yml. The presence of file-based workflows and test infrastructure (SwiftLint.yml) suggests automated code quality checks, but there's no visible indication of security-focused code review processes or SAST integration beyond linting. Fix: Integrate security-focused static analysis tools (e.g., Swift Package Manager vulnerability scanning, Apple's code analysis tools). Implement mandatory security review checklist for PRs. Consider using tools like Snyk or Checkmarx for dependency vulnerability scanning.
• Low · No Visible Dependency Vulnerability Management — Whisky.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file exists but the actual dependency list is not provided in the analysis context. Without seeing dependencies, potential vulnerable third-party packages cannot be fully assessed. Fix: Implement regular dependency vulnerability scanning. Use 'swift package update' with vulnerability checking. Monitor security advisories for all Swift Package Manager dependencies. Consider using dependency audit tools in CI/CD pipeline.

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.