https://github.com/rohit1901/lumina
A modern, native macOS utility for toggling system appearance modes (Light, Dark, Auto) from both a beautiful menu bar app (Electron) and a powerful CLI/library (Python). #library
https://github.com/rohit1901/lumina
apple electron javascript macos poetry python shell typescript
Last synced: 3 months ago
JSON representation
A modern, native macOS utility for toggling system appearance modes (Light, Dark, Auto) from both a beautiful menu bar app (Electron) and a powerful CLI/library (Python). #library
- Host: GitHub
- URL: https://github.com/rohit1901/lumina
- Owner: rohit1901
- License: mit
- Created: 2025-11-15T23:03:31.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-17T09:53:16.000Z (8 months ago)
- Last Synced: 2025-11-17T11:26:46.873Z (8 months ago)
- Topics: apple, electron, javascript, macos, poetry, python, shell, typescript
- Language: Shell
- Homepage:
- Size: 10.3 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Lumina
A modern, native macOS utility for toggling system appearance modes (Light, Dark, Auto) from both a beautiful menu bar app (Electron) and a powerful CLI/library (Python).
---
## 🌟 Features
- **Instant theme toggle:** Switch Light/Dark/Auto from your menu bar
- **Native macOS look:** Inspired by Apple Human Interface Guidelines
- **Fast CLI tool (`theme-toggle`):** Automate mode changes from the terminal
- **Modern architecture:** TypeScript + Electron frontend, Python 3 backend (via Poetry)
- **Notarization and code signing ready:** For direct or App Store distribution
- **Fully unit and integration tested**
- **Accessible & ergonomic UI**
---
## 📦 Install & Set Up
### 1. **Clone the repo**
```
git clone https://github.com/rohit1901/lumina.git
cd lumina
```
---
### 2. **Set up the Python CLI (Poetry)**
> Used by Electron as a backend, and directly by CLI users.
```
cd python
pipx install poetry # Or: pip install --user poetry
poetry install # Creates/activates virtualenv, installs deps
```
- **Test the CLI**:
```
poetry run theme-toggle current # Query current appearance mode
poetry run theme-toggle dark # Switch to dark mode
poetry run theme-toggle light # Switch to light mode
poetry run theme-toggle --help # Show help
```
- **Run unit tests**:
```
pytest
```
- **(Optional) Build a standalone binary from the root directory**:
```
./build.sh --python-only
```
---
### 3. **Set up and build Electron (TypeScript app)**
> Integrates with Python CLI for macOS theme control.
```
cd electron
npm install # Installs Electron, TypeScript, etc.
npm run build # Compiles TypeScript
npm run dev # Runs Electron app in development mode
```
#### **Menu bar app use:**
- The icon appears in the macOS menu bar.
- Left-click: Opens compact popover UI for theme selection
- Right-click: Opens context menu ("Light", "Dark" "Current Mode", "Quit")
- Tray tooltip shows current mode, live-updating (polled via CLI)
#### **Unit and integration tests:**
```
npm test # Runs Jest-powered Electron tests
```
#### **Package for distribution:**
```
npm run package:mac # Creates Mac DMG installer (codesign if configured)
```
---
### 4. **Full cross-platform packaging**
- **The Electron app spawns the standalone Python CLI as a subprocess.**
- The Python CLI must exist at `python/dist/theme-toggle` for bundling and runtime.
- Both parts are packaged together via Electron Builder (see `electron/package.json`).
---
## 📚 Project Structure
```
lumina/
├── python/
│ ├── mactheme/
│ │ ├── __init__.py
│ │ ├── core.py
│ │ ├── cli.py
│ │ └── tests/
│ │ └── test_core.py
│ ├── pyproject.toml
│ └── theme-toggle.spec
├── electron/
│ ├── src/
│ │ ├── main.ts
│ │ └── __tests__/
│ │ └── main.test.ts
│ ├── assets/
│ │ └── *.png
│ ├── build/
│ │ ├── entitlements.mac.plist
│ │ └── entitlements.mac.inherit.plist
│ ├── package.json
│ ├── tsconfig.json
│ ├── jest.config.js
│ └── .gitignore
├── build.sh
├── package.sh
└── README.md
```
---
## 🧩 How It Works
- **Electron app** shows the menu bar icon and UI, communicates with users.
- **Electron main process** calls Python CLI (`theme-toggle`) via Node.js `child_process` to read/set system appearance.
- **Python CLI** changes macOS appearance using system calls (`osascript`, `defaults`), updating instantly.
- **UI and tray tooltip** update automatically via periodic polling.
---
## 🤖 Developer Workflow
- Change Python backend logic: test in `python/mactheme/core.py` and CLI in `python/mactheme/cli.py`
- Change Electron UI/logic: alter files in `electron/src/` and `electron/renderer/`
- Test backend in isolation with `pytest`
- Test frontend and integration with `npm test` (Jest)
- Build binary for Electron release with `./build.sh` and bundle for Mac DMG with `./package.sh --mac-only`
---
## 🧪 Testing
- **Python unit tests:**
```
pytest
```
- **Electron/Jest tests:**
```
npm test
```
- **Integration tests simulate end-to-end flows** (see `electron/src/__tests__/main.test.ts`).
---
## 🔏 Packaging & Distribution
- **Mac DMG Installer:** `electron/out/Lumina-.dmg`
- **Code signing and entitlements:** See `electron/build/` and `package.json`
- **Notarization ready:** Use `apple-id`, `team-id` for Mac App Store submission
- **Standalone Python CLI:** Symlink system-wide if desired:
```
sudo ln -s $(pwd)/python/dist/theme-toggle /usr/local/bin/theme-toggle
```
---
## ⚡ Troubleshooting
- **Python CLI not found:** Rebuild with `poetry run pyinstaller --clean ...`, verify output in `dist/`.
- **Import errors:** Check for relative vs absolute imports (`from .core import ...`).
- **PyInstaller errors:** Ensure Python version `<3.15`. Use `poetry env use python3.14` if needed.
- **Electron build fails:** Ensure Node.js v18+ and Python CLI present for subprocess communication.
- **Code signing fails:** Check entitlements files, proper developer certificates, and correct DMG output folder.
---
## 🛡️ Security & Privacy
- **No data collection, no analytics.**
- **All operations are local to your device.**
- **Built for Mac App Store compliance.**
---
## 📑 License
MIT License
---
## 💡 Tips & Advanced Usage
- To add more appearance features, extend `mactheme/core.py` and the CLI.
- Use the Python CLI in scripts and automation workflows.
- Electron app can be extended with custom UI features or menu options.
- Integrate with macOS Shortcuts for automation!