Paste Swiftly

Paste Swiftly is an open-source macOS utility that lives in your menu bar and allows you to quickly insert email aliases into any application via the macOS Services menu.

While the official website covers the user-facing features, this README is intended for developers who want to understand how the app works, build it from source, or contribute.

Under the Hood

Paste Swiftly is built purely in Swift using AppKit. It avoids bloated web frameworks (like Electron) to ensure it uses virtually zero background resources and stays completely native to macOS.

Key Technical Implementations

• macOS Services Menu Integration: The app bridges into the macOS ecosystem by registering an NSServices provider. When you right-click in another app and choose "Paste Swiftly", the system invokes the showEmailPickerFromService method in ServiceProvider.swift.
• Floating Contextual Menus: Instead of bringing up a heavy window, the app calculates the mouse cursor's current position and programmatically constructs an NSMenu. It pops up a native dropdown that doesn't steal window focus from your active application.
• NSPasteboard Automation: Once an email is selected, Paste Swiftly handles the complexities of NSPasteboard and simulates the standard Cmd+V keystroke (via AppleScript/Carbon events) to instantly paste the selected text directly into the previous app.
• Data Storage: Email aliases and settings are securely stored locally using standard UserDefaults, ensuring they never leave your device.
• macOS Contacts (MeCard) Integration: The app optionally interfaces with the system's Contacts framework to pull emails from the user's personal "Me" card, allowing instant setup without typing anything.

Installation & Gatekeeper

If you download the pre-compiled .dmg from the Releases page, you may see a warning that says:

"Paste Swiftly" Not Opened. Apple could not verify "Paste Swiftly" is free of malware...

Because the app is built without a paid Apple Developer certificate (Notarization), Gatekeeper blocks it by default. To bypass this:

1. Open your Applications folder.
2. Right-click (or Control-click) on Paste Swiftly.app.
3. Select Open from the context menu.
4. Click Open on the prompt. You only need to do this once.

System Requirements

• macOS 13.0 (Ventura) or later.
• Xcode 14.0 or later (for building from source).

Building from Source

1. Clone the repository:

   git clone https://github.com/k79639/Paste-Swiftly.git
   cd Paste-Swiftly

2. Open the project in Xcode:

   open "Paste Swiftly.xcodeproj"

3. Ensure your signing team is set correctly in the project settings if you wish to run it on a physical device or distribute it.
4. Select the Paste Swiftly scheme and build/run (Cmd + R).

Architecture

• AppDelegate.swift: Manages the application lifecycle, sets up the menu bar item (NSStatusItem), and registers the Services provider.
• ServiceProvider.swift: The core of the context menu integration. Listens for the macOS service call and triggers the floating picker.
• EmailStore.swift: A singleton that manages fetching emails from local storage and the system Contacts app.
• MeCardSource.swift: Handles the Contacts framework integration to read the user's "Me" card.
• SettingsWindowController.swift: The native AppKit window for adding/removing aliases manually.

Privacy & Security

Paste Swiftly is entirely local. It has no networking components, no telemetry, and requires no internet access to function. The App Sandbox configuration limits it solely to the resources it needs.

Contributing

Contributions are welcome! If you have ideas for improvements, bug fixes, or new features:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/MyFeature).
3. Commit your changes.
4. Push to the branch (git push origin feature/MyFeature).
5. Open a Pull Request.

Please ensure your Swift code follows standard Swift style guidelines and maintains the lightweight, fast nature of the app.

License

This project is licensed under the MIT License. See the LICENSE file for details.