shhhhhh 0.1.0__tar.gz

shhhhhh-0.1.0/.context/plans/homebrew-distribution-for-shh.md

@@ -0,0 +1,59 @@
+# Plan: Homebrew Distribution for `shh`
+
+## Context
+`shh` is a macOS CLI tool for managing notification settings. It's built in Python with click + rich, packaged with hatchling. Currently installable only via `pip install -e .` locally — not yet on PyPI or Homebrew. The goal is to make it installable via `brew install alexpriest/tap/shh`.
+
+## Steps
+
+### 1. Prepare `pyproject.toml` for PyPI
+Add missing metadata fields that PyPI requires/expects:
+- `license` (MIT)
+- `authors`
+- `urls` (homepage, repository)
+- `classifiers` (macOS-only, CLI, Python 3.11+)
+
+**File:** `/Users/alex/Code/.conductor/workspaces/shhhhhh/medan/pyproject.toml`
+
+### 2. Publish to PyPI
+```bash
+cd /Users/alex/Code/.conductor/workspaces/shhhhhh/medan
+python3.11 -m build
+twine upload dist/shhhhhh-0.1.0*
+```
+This produces the sdist `.tar.gz` that Homebrew needs.
+
+### 3. Create `alexpriest/homebrew-tap` GitHub repo
+```bash
+gh repo create alexpriest/homebrew-tap --public --description "Homebrew formulae"
+```
+Structure:
+```
+homebrew-tap/
+  Formula/
+    shh.rb
+  README.md
+```
+
+### 4. Generate the Homebrew formula
+Use `homebrew-pypi-poet` to auto-generate resource stanzas with correct URLs + SHA256 hashes:
+```bash
+python3.11 -m venv /tmp/poet-env
+source /tmp/poet-env/bin/activate
+pip install shhhhhh homebrew-pypi-poet
+poet -f shhhhhh
+```
+Then edit the output to add: `depends_on :macos`, description, homepage, license, and test block.
+
+### 5. Push formula and test
+- Commit `Formula/shh.rb` to the tap repo
+- Test: `brew install alexpriest/tap/shh && shh --help`
+
+### 6. Update README with Homebrew install instructions
+Add `brew install alexpriest/tap/shh` to the medan README.
+
+**File:** `/Users/alex/Code/.conductor/workspaces/shhhhhh/medan/README.md`
+
+## Verification
+1. `brew install alexpriest/tap/shh` succeeds on a clean system
+2. `shh --help` outputs usage info
+3. `shh list` works (with Full Disk Access granted)

shhhhhh-0.1.0/.git

@@ -0,0 +1 @@
+gitdir: /Users/alex/Code/tools/shhhhhh/.git/worktrees/medan

shhhhhh-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.worktrees/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.eggs/
+*.pyc
+.venv/

shhhhhh-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: shhhhhh
+Version: 0.1.0
+Summary: Silence your Mac, app by app
+Project-URL: Homepage, https://github.com/alexpriest/shhhhhh
+Project-URL: Repository, https://github.com/alexpriest/shhhhhh
+Author: Alex Priest
+License-Expression: MIT
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0

shhhhhh-0.1.0/README.md

@@ -0,0 +1,44 @@
+# shh
+
+Silence your Mac, app by app.
+
+A CLI tool for batch-managing macOS notification settings — toggle sound and badges for all apps or specific ones in a single command.
+
+## Install
+
+```bash
+pip install shhhhhh
+```
+
+## Setup
+
+`shh` needs **Full Disk Access** to manage notification settings.
+
+1. Open **System Settings → Privacy & Security → Full Disk Access**
+2. Enable your terminal app (Terminal, iTerm2, Ghostty, etc.)
+3. Restart your terminal
+
+If you skip this step, `shh` will guide you through it on first run.
+
+## Usage
+
+```bash
+shh list                     # show all apps + settings
+shh sound off --all          # mute everything
+shh sound on Mail Messages   # unmute specific apps
+shh badges off --all         # remove all badge icons
+shh undo                     # restore previous settings
+```
+
+## How it works
+
+`shh` reads and writes macOS notification preferences directly from the `usernoted` plist, then restarts the daemon to apply changes. A backup is automatically created before every change.
+
+## Requirements
+
+- macOS 15+ (Sequoia / Tahoe)
+- Python 3.11+
+
+## License
+
+MIT

shhhhhh-0.1.0/docs/dev.md

@@ -0,0 +1,54 @@
+# Development
+
+## Setup
+
+Requires Python 3.11+. The system Python's pip is too old for editable installs, so use a venv:
+
+```bash
+cd ~/Code/tools/shhhhhh
+python3.11 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install pytest
+```
+
+## Running
+
+```bash
+shh list                     # show all apps + settings
+shh sound off --all          # mute everything
+shh sound on Mail Messages   # unmute specific apps
+shh badges off --all         # remove all badge icons
+shh undo                     # restore previous settings
+```
+
+## Tests
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+18 tests across 3 files: plist reader, plist writer, CLI commands.
+
+## Architecture
+
+Three modules:
+
+- `src/shhhhhh/plist.py` — reads/writes the macOS `usernoted` plist, bitmask manipulation, backup/restore
+- `src/shhhhhh/display.py` — gradient logo, rich tables, result messages
+- `src/shhhhhh/cli.py` — click commands wiring plist + display together
+
+## How it works
+
+The tool reads `~/Library/Group Containers/group.com.apple.usernoted/Library/Preferences/group.com.apple.usernoted.plist`, which stores per-app notification flags as a bitmask:
+
+- Bit 1 (value 2): badges
+- Bit 2 (value 4): sound
+
+After modifying flags, it restarts `usernoted` via `killall usernoted` to apply changes. A timestamped backup is saved to `~/.shh/` before every write.
+
+## Known gaps (v2)
+
+- Ambiguous match warning: if you type `shh sound off Ma` and it matches both Mail and Maps, it silently applies to both. Design doc says it should show matches and ask the user to be specific.
+- No `--version` flag
+- No badges-specific CLI tests (shares code path with sound via factory pattern, low risk)

shhhhhh-0.1.0/docs/plans/2026-03-07-shh-design.md

@@ -0,0 +1,137 @@
+# shh (shhhhhh.sh) — Design Document
+
+## Overview
+
+A Python CLI tool for batch-managing macOS notification settings. Reads and writes the `usernoted` plist directly, letting you toggle sound and badges for all apps or specific ones in a single command.
+
+- **PyPI package**: `shhhhhh`
+- **CLI command**: `shh`
+- **Domain**: `shhhhhh.sh`
+
+## Commands
+
+```
+shh list                     # show all apps + sound/badge status
+shh sound off --all          # mute all apps
+shh sound on --all           # unmute all apps
+shh sound off Slack Zoom     # mute specific apps (fuzzy match)
+shh sound on Mail Messages   # unmute specific apps
+shh badges off --all         # remove all badge icons
+shh badges on Mail Messages  # re-enable badges for specific apps
+shh undo                     # restore most recent backup
+```
+
+## Branding
+
+### Logo
+Box-drawing chunky "SHH" wordmark with top-to-bottom grayscale gradient (bright to dim, like sound fading out). Uses 256-color ANSI codes, one shade per line.
+
+```
+ ███████╗██╗  ██╗██╗  ██╗
+ ██╔════╝██║  ██║██║  ██║
+ ███████╗███████║███████║
+ ╚════██║██╔══██║██╔══██║
+ ███████║██║  ██║██║  ██║
+ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝
+```
+
+### Tagline
+Dim text below logo: `silence your mac, app by app`
+
+### Colors
+Grayscale palette throughout. Green checkmarks, dim crosses for status.
+
+## Data Layer
+
+### Source file
+```
+~/Library/Group Containers/group.com.apple.usernoted/Library/Preferences/group.com.apple.usernoted.plist
+```
+
+### Flags bitmask
+- Bit 1 (value 2): Badge app icon
+- Bit 2 (value 4): Play sound for notifications
+
+### App name resolution
+1. Extract from `path` field (e.g. `/Applications/Slack.app` -> `Slack`)
+2. Fall back to `bundle-id` if no path
+
+### Fuzzy matching
+Case-insensitive substring match against friendly app names. If ambiguous, show matches and ask user to be more specific.
+
+### System apps
+Skip entries where `bundle-id` starts with `_SYSTEM_CENTER_:`.
+
+### Write flow
+1. Read current plist
+2. Modify flags bitmask for targeted apps
+3. Write plist back
+4. Restart `usernoted` daemon via `killall usernoted`
+
+## Output Examples
+
+### `shh list`
+
+```
+ [gradient logo]
+
+ silence your mac, app by app
+
+ 47 apps · 43 with sound · 45 with badges
+
+ App                     Sound   Badges
+ ────────────────────────────────────────
+ Calendar                  ✓       ✓
+ Chrome                    ✓       ✓
+ FaceTime                  ✓       ✓
+ Linear                    ✓       ✓
+ Mail                      ✓       ✓
+ Messages                  ✗       ✗
+ Slack                     ✗       ✓
+ ...
+```
+
+### `shh sound off --all`
+
+```
+ [gradient logo]
+
+ Muted 43 apps
+
+ To undo: shh sound on --all
+```
+
+## Safety
+
+- Backup plist to `~/.shh/backup-<timestamp>.plist` before first write
+- `shh undo` restores most recent backup
+- Confirm before `--all` operations (skip with `--yes` / `-y`)
+
+## Tech Stack
+
+- Python 3.11+
+- `rich` — colored output, tables, status indicators
+- `plistlib` (stdlib) — read/write plist
+- `click` — CLI argument parsing
+- `subprocess` — restart usernoted after changes
+
+## Project Structure
+
+```
+~/Code/tools/shhhhhh/
+├── README.md
+├── pyproject.toml
+├── src/
+│   └── shhhhhh/
+│       ├── __init__.py
+│       ├── cli.py          # click commands + banner
+│       ├── plist.py         # read/write usernoted plist
+│       └── display.py       # rich table + formatting
+```
+
+## Future (not v1)
+
+- SwiftUI wrapper app (Option C from brainstorming)
+- Additional settings: banners/alert type, lock screen, previews
+- `shh profile save/load` — save/restore named configurations
+- Homebrew formula