Add optional macOS Finder integration for pipx installs

[LiukDiihMieu]

Summary

Add optional macOS Finder integration for pipx-installed npyquick by generating a lightweight local .app wrapper.

Currently, macOS users can install npyquick via pipx, but they do not get Finder integration comparable to Windows installers or Linux AppImage desktop integration. In particular, users cannot easily open .npy / .npz files via Finder “Open With” or set npyquick as the default viewer.

Motivation

A fully packaged macOS app is currently out of scope because proper distribution requires additional complexity such as app bundling, code signing, notarization, and possibly Apple Developer account setup.

However, we can still improve the macOS user experience without shipping a full macOS package. Since npyquick is already installed by pipx, we can create a small local .app bundle that simply launches the existing npyquick command. This keeps the project lightweight while providing useful Finder integration.

Proposed solution

Add a command such as:

npyquick --install-macos-app

This command creates a local app bundle, preferably at:

~/Applications/npyquick.app

The app bundle would contain:

npyquick.app/
  Contents/
    Info.plist
    MacOS/
      npyquick-launcher
    Resources/
      npyquick.icns

The launcher should call the existing command installed by pipx, for example:

#!/bin/sh
export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

if ! command -v npyquick >/dev/null 2>&1; then
  osascript -e 'display dialog "npyquick command not found. Please install it with: pipx install npyquick" buttons {"OK"} default button "OK"'
  exit 1
fi

exec npyquick "$@"

File association

The generated Info.plist should declare support for .npy and .npz files using CFBundleDocumentTypes. Prefer a conservative handler rank such as:

<key>LSHandlerRank</key>
<string>Alternate</string>

This allows users to choose npyquick from Finder “Open With” without aggressively taking ownership of .npy files. Optionally, define custom UTIs for NumPy files, for example:

io.github.liukdiihmieu.npyquick.npy
io.github.liukdiihmieu.npyquick.npz

Expected behavior

After running:

npyquick --install-macos-app

users should be able to:

• find npyquick.app in ~/Applications;
• open .npy / .npz files via Finder “Open With”;
• optionally set npyquick as the default app via “Get Info → Open with → Change All...”;
• run:

open -a npyquick path/to/file.npy

Non-goals

This issue does not aim to provide a fully packaged macOS release.

Out of scope for now:

• .dmg distribution;
• signed / notarized macOS app;
• bundling Python or Qt into the app;
• replacing the current pipx-based macOS installation path.

Notes

This approach should keep macOS support lightweight while giving users a much better desktop experience.