{"id":33311149,"url":"https://github.com/rohit1901/lumina","last_synced_at":"2026-04-11T12:01:59.363Z","repository":{"id":324691450,"uuid":"1097303920","full_name":"rohit1901/lumina","owner":"rohit1901","description":"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","archived":false,"fork":false,"pushed_at":"2025-11-17T09:53:16.000Z","size":10834,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-17T11:26:46.873Z","etag":null,"topics":["apple","electron","javascript","macos","poetry","python","shell","typescript"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rohit1901.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T23:03:31.000Z","updated_at":"2025-11-17T09:53:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rohit1901/lumina","commit_stats":null,"previous_names":["rohit1901/lumina"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rohit1901/lumina","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohit1901%2Flumina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohit1901%2Flumina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohit1901%2Flumina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohit1901%2Flumina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rohit1901","download_url":"https://codeload.github.com/rohit1901/lumina/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rohit1901%2Flumina/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285187921,"owners_count":27129352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","electron","javascript","macos","poetry","python","shell","typescript"],"created_at":"2025-11-19T05:00:29.647Z","updated_at":"2025-11-19T05:02:06.439Z","avatar_url":"https://github.com/rohit1901.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lumina\n\nA 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).\n\n---\n\n## 🌟 Features\n\n- **Instant theme toggle:** Switch Light/Dark/Auto from your menu bar\n- **Native macOS look:** Inspired by Apple Human Interface Guidelines\n- **Fast CLI tool (`theme-toggle`):** Automate mode changes from the terminal\n- **Modern architecture:** TypeScript + Electron frontend, Python 3 backend (via Poetry)\n- **Notarization and code signing ready:** For direct or App Store distribution\n- **Fully unit and integration tested**\n- **Accessible \u0026 ergonomic UI**\n\n---\n\n## 📦 Install \u0026 Set Up\n\n### 1. **Clone the repo**\n```\ngit clone https://github.com/rohit1901/lumina.git\ncd lumina\n```\n\n---\n\n### 2. **Set up the Python CLI (Poetry)**\n\n\u003e Used by Electron as a backend, and directly by CLI users.\n\n```\ncd python\npipx install poetry              # Or: pip install --user poetry\npoetry install                   # Creates/activates virtualenv, installs deps\n```\n\n- **Test the CLI**:\n    ```\n    poetry run theme-toggle current    # Query current appearance mode\n    poetry run theme-toggle dark       # Switch to dark mode\n    poetry run theme-toggle light      # Switch to light mode\n    poetry run theme-toggle --help     # Show help\n    ```\n\n- **Run unit tests**:\n    ```\n    pytest\n    ```\n\n- **(Optional) Build a standalone binary from the root directory**:\n    ```\n    ./build.sh --python-only\n    ```\n\n---\n\n### 3. **Set up and build Electron (TypeScript app)**\n\n\u003e Integrates with Python CLI for macOS theme control.\n\n```\ncd electron\nnpm install                       # Installs Electron, TypeScript, etc.\nnpm run build                     # Compiles TypeScript\nnpm run dev                       # Runs Electron app in development mode\n```\n\n#### **Menu bar app use:**\n- The icon appears in the macOS menu bar.\n- Left-click: Opens compact popover UI for theme selection\n- Right-click: Opens context menu (\"Light\", \"Dark\" \"Current Mode\", \"Quit\")\n- Tray tooltip shows current mode, live-updating (polled via CLI)\n\n#### **Unit and integration tests:**\n```\nnpm test                          # Runs Jest-powered Electron tests\n```\n\n#### **Package for distribution:**\n```\nnpm run package:mac               # Creates Mac DMG installer (codesign if configured)\n```\n\n---\n\n### 4. **Full cross-platform packaging**\n\n- **The Electron app spawns the standalone Python CLI as a subprocess.**\n- The Python CLI must exist at `python/dist/theme-toggle` for bundling and runtime.\n- Both parts are packaged together via Electron Builder (see `electron/package.json`).\n\n---\n\n## 📚 Project Structure\n\n```\nlumina/\n├── python/\n│   ├── mactheme/\n│   │   ├── __init__.py\n│   │   ├── core.py\n│   │   ├── cli.py\n│   │   └── tests/\n│   │       └── test_core.py\n│   ├── pyproject.toml\n│   └── theme-toggle.spec\n├── electron/\n│   ├── src/\n│   │   ├── main.ts\n│   │   └── __tests__/\n│   │       └── main.test.ts\n│   ├── assets/\n│   │   └── *.png\n│   ├── build/\n│   │   ├── entitlements.mac.plist\n│   │   └── entitlements.mac.inherit.plist\n│   ├── package.json\n│   ├── tsconfig.json\n│   ├── jest.config.js\n│   └── .gitignore\n├── build.sh\n├── package.sh\n└── README.md\n```\n\n---\n\n## 🧩 How It Works\n\n- **Electron app** shows the menu bar icon and UI, communicates with users.\n- **Electron main process** calls Python CLI (`theme-toggle`) via Node.js `child_process` to read/set system appearance.\n- **Python CLI** changes macOS appearance using system calls (`osascript`, `defaults`), updating instantly.\n- **UI and tray tooltip** update automatically via periodic polling.\n\n---\n\n## 🤖 Developer Workflow\n\n- Change Python backend logic: test in `python/mactheme/core.py` and CLI in `python/mactheme/cli.py`\n- Change Electron UI/logic: alter files in `electron/src/` and `electron/renderer/`\n- Test backend in isolation with `pytest`\n- Test frontend and integration with `npm test` (Jest)\n- Build binary for Electron release with `./build.sh` and bundle for Mac DMG with `./package.sh --mac-only`\n\n---\n\n## 🧪 Testing\n\n- **Python unit tests:**\n  ```\n  pytest\n  ```\n- **Electron/Jest tests:**\n  ```\n  npm test\n  ```\n- **Integration tests simulate end-to-end flows** (see `electron/src/__tests__/main.test.ts`).\n\n---\n\n## 🔏 Packaging \u0026 Distribution\n\n- **Mac DMG Installer:** `electron/out/Lumina-\u003cversion\u003e.dmg`\n- **Code signing and entitlements:** See `electron/build/` and `package.json`\n- **Notarization ready:** Use `apple-id`, `team-id` for Mac App Store submission\n- **Standalone Python CLI:** Symlink system-wide if desired:\n  ```\n  sudo ln -s $(pwd)/python/dist/theme-toggle /usr/local/bin/theme-toggle\n  ```\n\n---\n\n## ⚡ Troubleshooting\n\n- **Python CLI not found:** Rebuild with `poetry run pyinstaller --clean ...`, verify output in `dist/`.\n- **Import errors:** Check for relative vs absolute imports (`from .core import ...`).\n- **PyInstaller errors:** Ensure Python version `\u003c3.15`. Use `poetry env use python3.14` if needed.\n- **Electron build fails:** Ensure Node.js v18+ and Python CLI present for subprocess communication.\n- **Code signing fails:** Check entitlements files, proper developer certificates, and correct DMG output folder.\n\n---\n\n## 🛡️ Security \u0026 Privacy\n\n- **No data collection, no analytics.**\n- **All operations are local to your device.**\n- **Built for Mac App Store compliance.**\n\n---\n\n## 📑 License\n\nMIT License\n\n---\n\n## 💡 Tips \u0026 Advanced Usage\n\n- To add more appearance features, extend `mactheme/core.py` and the CLI.\n- Use the Python CLI in scripts and automation workflows.\n- Electron app can be extended with custom UI features or menu options.\n- Integrate with macOS Shortcuts for automation!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohit1901%2Flumina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frohit1901%2Flumina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frohit1901%2Flumina/lists"}