📂 file-popper

A small Rust utility to explore the correct way to open file dialogues on macOS.
Provides a simple CLI to trigger native file dialogs and print the selected (or created) file paths as JSON.

---

🚀 Overview

This project aims to:

• Investigate native macOS file dialogue patterns from Rust, including best practices and quirks.
• Provide a minimal CLI to trigger these dialogs and return selected paths as structured JSON.

It serves as a reference and testing ground for future, more robust cross-platform file dialog tools in Rust.

---

📜 Product Requirements Document (PRD)

✨ Goal

Create a simple, reliable way to open macOS-native file dialogues from a Rust application, invoked via a CLI.

✅ Features

• CLI command to open a file open dialog, returning selected file path(s).
• CLI command to open a file save dialog, returning selected file path.
• Ensure it uses macOS standard dialogs (via Cocoa APIs through a Rust binding or FFI).
• Output results to stdout as structured JSON format.

👤 User Stories

• As a developer, I want to run file-popper open to pop up a file selection window and get the chosen file path.
• As a developer, I want to run file-popper save to pop up a save dialog and get the file path where a user wants to save.
• As a developer, I want clear, minimal dependencies to keep the utility easy to audit and extend.

🛠 Technical Requirements

• Written in Rust, targeting macOS specifically (via cargo).
• Use either:
  • an existing crate like rfd or nfd with macOS support, or
  • direct bindings to Cocoa using objc or cocoa crates if lower-level experimentation is needed.
• Provide clear error handling when a user cancels or an unexpected failure occurs.

⚠️ Edge Cases

• User presses "Cancel" — should output JSON with cancelled: true, not crash.
• Ensure it handles both single and multi-file selections (configurable for future).
• If unsupported platform is detected (Linux or Windows), print a friendly error.

---

📦 Installation

cargo install --path .

Or clone and build:

git clone https://github.com/yourname/file-popper.git
cd file-popper
cargo build --release

---

🚀 Usage

# Open a file open dialog
./target/release/file-popper open

# Open a save dialog
./target/release/file-popper save

# Open dialog for multiple files
./target/release/file-popper open --multiple

# Open dialog with file type filter
./target/release/file-popper open --filter "*.txt"

# Open save dialog with suggested filename
./target/release/file-popper save --name "untitled"

# Open dialog starting from specific directory
./target/release/file-popper open --directory "/Users/username/Documents"

📋 JSON Output Format

The CLI outputs JSON results for all cases:

Successful File Selection

{
  "success": true,
  "cancelled": false,
  "files": ["/path/to/selected/file.txt"],
  "error": null
}

User Cancelled Dialog

{
  "success": false,
  "cancelled": true,
  "files": [],
  "error": null
}

Error Case

{
  "success": false,
  "cancelled": false,
  "files": [],
  "error": "Error message describing what went wrong"
}

---

📝 Roadmap

• Support for multi-file selection
• JSON output mode for better programmatic consumption
• Investigate sandbox permission requirements for distribution

---

🤝 Contributing

This is an exploratory utility — contributions are welcome, but stability is not guaranteed.
Feel free to open issues or PRs to discuss approaches for binding to macOS file dialog APIs from Rust.

---

📄 License

MIT License.