adom-cli

@@ -0,0 +1,97 @@+---+name: notify+description: "Send system-level browser notifications to the Hydrogen editor window. Visible even when the editor tab is backgrounded or browser is minimized. Supports title, body, icon, tag (for update-not-stack), require-interaction, silent, and focus-on-click."+---++# Browser Notifications++Send system-level browser notifications from containers to the Hydrogen editor. Notifications appear as OS-level toasts, visible even when the browser is in the background or minimized.++All commands auto-detect auth, owner, and repo from `VSCODE_PROXY_URI`. No setup needed.++## Permission++Three states:++- **Granted** → bell is hidden, notifications fire instantly+- **Default (Ask)** → bell is visible but quiet until you send a notification. Then: bell rings with an amber badge, notification is **queued**. User clicks bell → permission prompt → on grant, all queued notifications fire automatically. **No retry needed** — `permission_required` exits 0.+- **Denied** → bell visible with "off" icon. API returns `denied` immediately (no queue). User must unblock in browser settings (lock icon → Notifications → Allow).++## Quick Recipes++```bash+# Basic notification+adom-cli notify --title "Build complete" "All tests passed"++# Shortcut is the same as: adom-cli hydrogen notify send --title ...++# With icon (must be a raw image URL or data URL, NOT an Iconify string)+adom-cli notify --title "Deploy" --icon "https://example.com/check.png" "Succeeded"++# Persistent (stays until user dismisses)+adom-cli notify --title "Lint" --require-interaction "Errors found — review needed"++# Tagged — replaces the previous notification with the same tag (update, not stack).+# Same-tag updates are exempt from the rate limit.+adom-cli notify --title "Build" --tag build-status "Compiling... 40%"+sleep 2+adom-cli notify --title "Build" --tag build-status "Done! All tests passed."++# Silent (no sound/vibration)+adom-cli notify --title "FYI" --silent "Background task finished"++# Don't focus the editor tab when clicked+adom-cli notify --title "Info" --no-focus-on-click "Just a heads-up"+```++## Flags++| Flag | Required | Description |+|------|----------|-------------|+| `--title` | yes | Notification headline |+| `[BODY]` | no | Body text (positional arg) |+| `--icon` | no | Image URL or data URL (browser needs raw image, not Iconify) |+| `--tag` | no | Replaces previous notification with the same tag — use to update progress without stacking |+| `--require-interaction` | no | Stays visible until user dismisses (default: auto-close) |+| `--silent` | no | Suppress sound/vibration |+| `--no-focus-on-click` | no | Don't bring editor tab to front on click (default: focus-on-click=true) |++## Response Statuses++| Status | Exit | Meaning | What to do |+|--------|------|---------|------------|+| `shown` | 0 | Notification displayed | Nothing — it worked |+| `permission_required` | **0** | **Queued** — bell icon is ringing in the editor nav | Tell user: "Check the bell icon in the editor nav and click it to enable notifications — your queued message will fire automatically." **No need to retry** — the notification delivers itself when permission is granted. |+| `denied` | 1 | User has blocked notifications in browser settings | Tell user to unblock at the URL bar's lock icon → Notifications → Allow. Consider falling back to `caption show` for inline overlay. |+| `unsupported` | 1 | Browser doesn't support Notifications API | Degrade gracefully — use `caption show` or print inline |+| `no_browser` | 1 | No editor tab open (10s timeout) | User needs to open the editor first |+| `rate_limited` (429) | 1 | Too many distinct notifications | Wait `retryAfterSec` seconds. Use `--tag` to update instead of stack (exempt from rate limit) |++## Queueing (permission_required)++When the user hasn't granted permission yet, notifications are **queued** instead of failing:++1. CLI calls → server returns `permission_required` → notification spec is queued client-side+2. Bell icon in editor nav starts **ringing** with an amber badge showing pending count+3. User clicks bell → browser permission prompt → on grant, **all queued notifications fire** with their original title/body/icon/tag+4. Same-tag queued items dedupe — only the latest version of a given tag fires+5. Queue lives in browser memory only — lost on page reload++**`permission_required` exits 0** (not 1) because the notification is queued and will deliver itself. No retry needed from the CLI side.++## Rate Limits++| Limit | Value |+|-------|-------|+| Distinct notifications per minute | 5 |+| Min interval between distinct notifications | 5s |+| Min interval between same-tag updates | 1s |+| Same-tag updates | **exempt** from the cap and interval (still rate-limited at 1s) |++Use `--tag` for progress reporting (build status, deploy steps, etc.) — same-tag updates can fire every 1s indefinitely.++## Click Behavior++- Clicking a notification (when `focusOnClick` is true, the default) brings the editor browser tab to front+- Notification auto-closes on click+- Click handlers only work while the editor tab is still alive