alarmy-cli 1.0.1__tar.gz

alarmy_cli-1.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: alarmy-cli
+Version: 1.0.1
+Summary: A thread-safe, persistent, dual-mode CLI Alarm Clock
+Author: Ramanshu Gawande
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-python
+Dynamic: summary
+
+# ⏰ Command-Line Interface (CLI) Alarm Clock
+
+A professional, robust, and zero-dependency Command-Line Interface (CLI) Alarm Clock written in Python. It runs natively and works seamlessly on both **Windows** and **Linux**.
+
+Designed with **Clean Architecture** and **Unix-style CLI daemon patterns**, the application supports:
+1. **Interactive Shell Mode**: A fully interactive console screen with a live ticking clock header and dynamic command prompt.
+2. **Daemon Mode**: Run the background sound and time monitor (`alarm-clock daemon`).
+3. **OS-Native Task Mode (Zero Manual Daemon)**: Alarms automatically register with the operating system scheduler (Windows Task Scheduler via `schtasks` or Linux via `crontab`). When the time is reached, the OS automatically pops up a terminal instance to play sound and accept user inputs.
+
+---
+
+## ✨ Features
+
+- **Global CLI command integration**: Can be installed and executed globally as `alarm-clock` in the system shell.
+- **Dual Sound Alert Modes**:
+  - Background Python daemon checks system time and plays sound.
+  - OS-native schedulers trigger short-lived processes to ring.
+- **OS-Native Task Automation**:
+  - Windows: Creates user-level tasks using `schtasks` with automatic date fallback mechanisms for locale compatibility (`dd/mm/yyyy` vs `mm/dd/yyyy`).
+  - Linux: Appends entries programmatically to the user's `crontab`.
+- **Atomic File Writing**: Prevents state corruption by writing changes to a temporary file before atomically swapping it with the target database file (`~/.cli_alarms.json`).
+- **Thread-Safe Memory Lock**: Synchronizes all database reads and writes under a shared mutex lock to isolate background checks from user adjustments.
+- **Automatic Encoding Fallback**: Prevents crashes on legacy Windows cmd consoles that default to non-Unicode codepages (e.g., CP1252) by automatically replacing emojis with safe fallback indicators.
+- **Cross-Platform Audio alerts**:
+  - Windows: Uses native `winsound.Beep`.
+  - Linux/macOS: Uses terminal buzzer beeps (`\a`).
+- **Flexible Alarm Operations**: `add`, `list`, `remove`, `snooze`, and `dismiss`.
+  - Supports setting an alarm-specific default snooze limit (`--snooze-minutes`) which is automatically respected if no snooze duration is entered during rings.
+
+---
+
+## 🛠️ Architecture & Design Decisions
+
+```
+               ┌───────────────────────┐
+               │    Local CLI Shell    │
+               │ (Direct Single-Cmds)  │
+               └───────────┬───────────┘
+                           │ Writes/Reads
+                           ▼
+               ┌───────────────────────┐
+               │  ~/.cli_alarms.json   │◄─── (Atomic State DB)
+               └───────────────────────┘
+                           ▲
+                           │ Reads/Updates State
+                           ▼
+ ┌───────────────────────────────────────────────────────────┐
+ │                   Background Daemon Mode                  │
+ │                                                           │
+ │  ┌───────────────────────┐       ┌─────────────────────┐  │
+ │  │   Scheduler Thread    ├──────►│ Sound Loop Thread   │  │
+ │  │ (Monitors System Time)│       │ (Non-blocking Beep) │  │
+ │  └───────────────────────┘       └─────────────────────┘  │
+ └───────────────────────────────────────────────────────────┘
+                           ▲
+                           │ Triggers Subprocess Ring Command
+                           ▼
+ ┌───────────────────────────────────────────────────────────┐
+ │                  OS-Scheduled Task Mode                   │
+ │                                                           │
+ │  ┌────────────────────────┐       ┌────────────────────┐  │
+ │  │ Windows Task Scheduler ├──────►│ alarm-clock ring   │  │
+ │  │       / Linux Cron     │       │ (Terminal Pop-Up)  │  │
+ │  └────────────────────────┘       └────────────────────┘  │
+ └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Getting Started
+
+### 1. Installation
+To register the `alarm-clock` terminal command, install the package locally from the root workspace directory.
+
+**On Windows (without requiring admin privileges):**
+```powershell
+pip install --user -e .
+```
+*Note: Make sure your user script folder (e.g. `C:\Users\<username>\AppData\Roaming\Python\Python312\Scripts`) is in your system's PATH. If it's not, you can run the executable directly by targeting its path, or use `python -m alarm_clock.cli`.*
+
+**On Linux / macOS:**
+```bash
+pip install -e .
+```
+
+### 2. Running Unit Tests
+A comprehensive test suite is included in `/tests` covering the parser, models, scheduler, serialization, persistence, and OS scheduler triggers. Run it with:
+```bash
+python -m unittest discover -s tests
+```
+
+---
+
+## 🕹️ Command Reference
+
+### Option A: OS-Native Mode (Recommended - Zero Manual Daemon)
+When you add an alarm, it is registered automatically with the operating system.
+
+1. **Add an alarm**:
+   ```bash
+   alarm-clock add 07:30 "Wake Up" --snooze-minutes 8 --auto-dismiss 30
+   ```
+2. **List alarms**:
+   ```bash
+   alarm-clock list
+   ```
+3. When the time is reached, the operating system launches a terminal window automatically, starts beep-beeping, and prompts you:
+   ```
+   Press Enter to dismiss, or type 'snooze' to snooze:
+   ```
+   *If you type `snooze`, it automatically snoozes for 8 minutes (respecting the custom snooze parameter).*
+4. **Remove an alarm** (cleans it up from both disk and OS task registries):
+   ```bash
+   alarm-clock remove 1
+   ```
+
+### Option B: Daemon Mode (Manual Persistent Process)
+1. **Start the monitor daemon** (run this in a separate terminal window or pane to play sound when alarms go off):
+   ```bash
+   alarm-clock daemon
+   ```
+2. **Snooze/Dismiss** from your main terminal:
+   ```bash
+   alarm-clock snooze 1 10
+   alarm-clock dismiss 1
+   ```
+
+### Option C: Interactive Shell Mode
+If you run `alarm-clock` without any arguments, it launches a persistent, interactive console session. It manages its own background timing thread and audio loops automatically in a single terminal.
+
+```bash
+alarm-clock
+```
+Inside the interactive session, the prompt updates live and you can type sub-commands like `add`, `list`, `snooze`, `dismiss`, and `exit` directly:
+```
+(22:15:30) alarm-clock > add 07:30 Morning Workout
+Success: Created Alarm 1 for 07:30 ('Morning Workout')
+```

alarmy_cli-1.0.1/README.md

@@ -0,0 +1,138 @@
+# ⏰ Command-Line Interface (CLI) Alarm Clock
+
+A professional, robust, and zero-dependency Command-Line Interface (CLI) Alarm Clock written in Python. It runs natively and works seamlessly on both **Windows** and **Linux**.
+
+Designed with **Clean Architecture** and **Unix-style CLI daemon patterns**, the application supports:
+1. **Interactive Shell Mode**: A fully interactive console screen with a live ticking clock header and dynamic command prompt.
+2. **Daemon Mode**: Run the background sound and time monitor (`alarm-clock daemon`).
+3. **OS-Native Task Mode (Zero Manual Daemon)**: Alarms automatically register with the operating system scheduler (Windows Task Scheduler via `schtasks` or Linux via `crontab`). When the time is reached, the OS automatically pops up a terminal instance to play sound and accept user inputs.
+
+---
+
+## ✨ Features
+
+- **Global CLI command integration**: Can be installed and executed globally as `alarm-clock` in the system shell.
+- **Dual Sound Alert Modes**:
+  - Background Python daemon checks system time and plays sound.
+  - OS-native schedulers trigger short-lived processes to ring.
+- **OS-Native Task Automation**:
+  - Windows: Creates user-level tasks using `schtasks` with automatic date fallback mechanisms for locale compatibility (`dd/mm/yyyy` vs `mm/dd/yyyy`).
+  - Linux: Appends entries programmatically to the user's `crontab`.
+- **Atomic File Writing**: Prevents state corruption by writing changes to a temporary file before atomically swapping it with the target database file (`~/.cli_alarms.json`).
+- **Thread-Safe Memory Lock**: Synchronizes all database reads and writes under a shared mutex lock to isolate background checks from user adjustments.
+- **Automatic Encoding Fallback**: Prevents crashes on legacy Windows cmd consoles that default to non-Unicode codepages (e.g., CP1252) by automatically replacing emojis with safe fallback indicators.
+- **Cross-Platform Audio alerts**:
+  - Windows: Uses native `winsound.Beep`.
+  - Linux/macOS: Uses terminal buzzer beeps (`\a`).
+- **Flexible Alarm Operations**: `add`, `list`, `remove`, `snooze`, and `dismiss`.
+  - Supports setting an alarm-specific default snooze limit (`--snooze-minutes`) which is automatically respected if no snooze duration is entered during rings.
+
+---
+
+## 🛠️ Architecture & Design Decisions
+
+```
+               ┌───────────────────────┐
+               │    Local CLI Shell    │
+               │ (Direct Single-Cmds)  │
+               └───────────┬───────────┘
+                           │ Writes/Reads
+                           ▼
+               ┌───────────────────────┐
+               │  ~/.cli_alarms.json   │◄─── (Atomic State DB)
+               └───────────────────────┘
+                           ▲
+                           │ Reads/Updates State
+                           ▼
+ ┌───────────────────────────────────────────────────────────┐
+ │                   Background Daemon Mode                  │
+ │                                                           │
+ │  ┌───────────────────────┐       ┌─────────────────────┐  │
+ │  │   Scheduler Thread    ├──────►│ Sound Loop Thread   │  │
+ │  │ (Monitors System Time)│       │ (Non-blocking Beep) │  │
+ │  └───────────────────────┘       └─────────────────────┘  │
+ └───────────────────────────────────────────────────────────┘
+                           ▲
+                           │ Triggers Subprocess Ring Command
+                           ▼
+ ┌───────────────────────────────────────────────────────────┐
+ │                  OS-Scheduled Task Mode                   │
+ │                                                           │
+ │  ┌────────────────────────┐       ┌────────────────────┐  │
+ │  │ Windows Task Scheduler ├──────►│ alarm-clock ring   │  │
+ │  │       / Linux Cron     │       │ (Terminal Pop-Up)  │  │
+ │  └────────────────────────┘       └────────────────────┘  │
+ └───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Getting Started
+
+### 1. Installation
+To register the `alarm-clock` terminal command, install the package locally from the root workspace directory.
+
+**On Windows (without requiring admin privileges):**
+```powershell
+pip install --user -e .
+```
+*Note: Make sure your user script folder (e.g. `C:\Users\<username>\AppData\Roaming\Python\Python312\Scripts`) is in your system's PATH. If it's not, you can run the executable directly by targeting its path, or use `python -m alarm_clock.cli`.*
+
+**On Linux / macOS:**
+```bash
+pip install -e .
+```
+
+### 2. Running Unit Tests
+A comprehensive test suite is included in `/tests` covering the parser, models, scheduler, serialization, persistence, and OS scheduler triggers. Run it with:
+```bash
+python -m unittest discover -s tests
+```
+
+---
+
+## 🕹️ Command Reference
+
+### Option A: OS-Native Mode (Recommended - Zero Manual Daemon)
+When you add an alarm, it is registered automatically with the operating system.
+
+1. **Add an alarm**:
+   ```bash
+   alarm-clock add 07:30 "Wake Up" --snooze-minutes 8 --auto-dismiss 30
+   ```
+2. **List alarms**:
+   ```bash
+   alarm-clock list
+   ```
+3. When the time is reached, the operating system launches a terminal window automatically, starts beep-beeping, and prompts you:
+   ```
+   Press Enter to dismiss, or type 'snooze' to snooze:
+   ```
+   *If you type `snooze`, it automatically snoozes for 8 minutes (respecting the custom snooze parameter).*
+4. **Remove an alarm** (cleans it up from both disk and OS task registries):
+   ```bash
+   alarm-clock remove 1
+   ```
+
+### Option B: Daemon Mode (Manual Persistent Process)
+1. **Start the monitor daemon** (run this in a separate terminal window or pane to play sound when alarms go off):
+   ```bash
+   alarm-clock daemon
+   ```
+2. **Snooze/Dismiss** from your main terminal:
+   ```bash
+   alarm-clock snooze 1 10
+   alarm-clock dismiss 1
+   ```
+
+### Option C: Interactive Shell Mode
+If you run `alarm-clock` without any arguments, it launches a persistent, interactive console session. It manages its own background timing thread and audio loops automatically in a single terminal.
+
+```bash
+alarm-clock
+```
+Inside the interactive session, the prompt updates live and you can type sub-commands like `add`, `list`, `snooze`, `dismiss`, and `exit` directly:
+```
+(22:15:30) alarm-clock > add 07:30 Morning Workout
+Success: Created Alarm 1 for 07:30 ('Morning Workout')
+```

alarmy_cli-1.0.1/alarm_clock/__init__.py

@@ -0,0 +1,4 @@
+"""
+Alarm Clock Package
+"""
+__version__ = "1.0.0"

alarmy_cli-1.0.1/alarm_clock/audio.py

@@ -0,0 +1,66 @@
+import time
+import threading
+import platform
+import sys
+import logging
+
+logger = logging.getLogger(__name__)
+
+class AlarmSoundController:
+    """
+    Manages non-blocking audio alerts across platforms.
+    On Windows, it uses the built-in winsound.Beep API.
+    On Linux, it uses the terminal bell character (\a) with a quiet sleep.
+    """
+    def __init__(self):
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._lock = threading.Lock()
+
+    def _beep_loop(self) -> None:
+        system = platform.system()
+        while not self._stop_event.is_set():
+            if system == "Windows":
+                try:
+                    import winsound
+                    # 1000 Hz frequency, 600 ms duration
+                    winsound.Beep(1000, 600)
+                except Exception as e:
+                    # Fallback to ASCII bell if winsound fails
+                    sys.stdout.write('\a')
+                    sys.stdout.flush()
+            else:
+                # Linux/macOS fallback using ASCII bell character
+                sys.stdout.write('\a')
+                sys.stdout.flush()
+            
+            # Sleep in small increments to respond quickly to stop events
+            for _ in range(10):
+                if self._stop_event.is_set():
+                    break
+                time.sleep(0.1)
+
+    def start(self) -> bool:
+        """
+        Starts the alarm beep loop in a background thread if not already running.
+        Returns True if a new thread was started, False otherwise.
+        """
+        with self._lock:
+            if self._thread and self._thread.is_alive():
+                return False  # Already running
+            
+            self._stop_event.clear()
+            self._thread = threading.Thread(target=self._beep_loop, name="AlarmSoundThread", daemon=True)
+            self._thread.start()
+            return True
+
+    def stop(self) -> None:
+        """
+        Stops the alarm beep loop.
+        """
+        with self._lock:
+            if self._thread and self._thread.is_alive():
+                self._stop_event.set()
+                # Wait briefly for the thread to stop, but don't block indefinitely
+                self._thread.join(timeout=1.5)
+                self._thread = None