zen-timer 0.2.0__tar.gz

zen_timer-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shenald-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zen_timer-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: zen-timer
+Version: 0.2.0
+Summary: 🧘 Deep-work timer. Simple terminal app for focus sessions. No GUI, just flow.
+Author-email: Shenal Diluksha <shenald@users.noreply.github.com>
+Maintainer-email: shenald-dev <shenald@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shenald-dev/zen
+Project-URL: Documentation, https://github.com/shenald-dev/zen#readme
+Project-URL: Repository, https://github.com/shenald-dev/zen
+Project-URL: Issues, https://github.com/shenald-dev/zen/issues
+Project-URL: Changelog, https://github.com/shenald-dev/zen/blob/main/CHANGELOG.md
+Keywords: zen,timer,pomodoro,focus,deep-work,cli,tui,productivity
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<16.0.0,>=13.9.0
+Requires-Dist: typer<1.0.0,>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pylint<5.0.0,>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# README.md
+<div align="center">
+  <img src="assets/logo.png" alt="zen Logo" width="250" />
+  
+  <br/>
+
+  <h1>🧘‍♂️ zen</h1>
+  <p><b>Minimalist Terminal Deep-Work Timer</b></p>
+  <i>Simple terminal app for focus sessions. No GUI, just flow.</i>
+
+  <br/>
+  
+  [![PyPI version](https://img.shields.io/pypi/v/zen-timer.svg)](https://pypi.org/project/zen-timer/)
+  [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+</div>
+
+---
+
+## 📑 Table of Contents
+- [🌟 Overview](#-overview)
+- [🚀 Enterprise Features](#-enterprise-features)
+- [⚡ Quick Start Guide](#-quick-start-guide)
+- [💻 Comprehensive Usage](#-comprehensive-usage)
+- [🤝 Contributing](#-contributing)
+
+---
+
+## 🌟 Overview
+
+**zen** is an ultra-minimalist, distraction-free terminal application built to safeguard developer focus. It ditches complex GUIs in favor of beautiful, native terminal progress indicators. Dive straight into flow state.
+
+---
+
+## 🚀 Enterprise Features
+
+- **🌊 Flow State**: Visually stunning, distraction-free TUI progress bar.
+- **⏱️ Flexible**: Fully configurable focus sessions and break reminders.
+- **🎨 Premium Aesthetic**: Powered by `Rich` and `Typer` to look incredible in any modern terminal emulator (iTerm, Kitty, Windows Terminal).
+- **🚀 Performance**: Lightning-fast startup with lazy-loaded imports and zero-overhead UI rendering.
+
+---
+
+## ⚡ Quick Start Guide
+
+### Installation
+
+Install via pip:
+```bash
+pip install zen-timer
+```
+---
+
+## 💻 Comprehensive Usage
+
+### Start a Session
+To start a default 25-minute Pomodoro session:
+```bash
+zen
+```
+### Advanced Usage
+
+**zen** supports additional CLI flags to customize your workflow:
+
+- **`--break`**: Run the timer as a break session instead of a focus session. Ideal for timing your rest periods between deep work blocks.
+  ```bash
+  zen 5 --break
+  ```
+
+- **`--silent`**: Run the timer without sending desktop notifications upon completion. Perfect for environments where notifications are distracting or unsupported.
+  ```bash
+  zen 25 --silent
+  ```
+
+You can also combine these flags for a silent break session:
+```bash
+zen 15 --break --silent
+```
+---
+
+## 🤝 Contributing
+Want to help safeguard developer focus? Let's flow together! 🌊
+- 🐛 **Found a bug?** Open an issue to let us know.
+- ✨ **Have a feature idea?** We are open to PRs! Keep the UI minimal and the code beautiful.
+- 🎨 **Documentation tweaks?** Always welcome!
+
+---
+> *Crafted by a Vibe Coder. Protect your focus.*

zen_timer-0.2.0/README.md

@@ -0,0 +1,88 @@
+# README.md
+<div align="center">
+  <img src="assets/logo.png" alt="zen Logo" width="250" />
+  
+  <br/>
+
+  <h1>🧘‍♂️ zen</h1>
+  <p><b>Minimalist Terminal Deep-Work Timer</b></p>
+  <i>Simple terminal app for focus sessions. No GUI, just flow.</i>
+
+  <br/>
+  
+  [![PyPI version](https://img.shields.io/pypi/v/zen-timer.svg)](https://pypi.org/project/zen-timer/)
+  [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+</div>
+
+---
+
+## 📑 Table of Contents
+- [🌟 Overview](#-overview)
+- [🚀 Enterprise Features](#-enterprise-features)
+- [⚡ Quick Start Guide](#-quick-start-guide)
+- [💻 Comprehensive Usage](#-comprehensive-usage)
+- [🤝 Contributing](#-contributing)
+
+---
+
+## 🌟 Overview
+
+**zen** is an ultra-minimalist, distraction-free terminal application built to safeguard developer focus. It ditches complex GUIs in favor of beautiful, native terminal progress indicators. Dive straight into flow state.
+
+---
+
+## 🚀 Enterprise Features
+
+- **🌊 Flow State**: Visually stunning, distraction-free TUI progress bar.
+- **⏱️ Flexible**: Fully configurable focus sessions and break reminders.
+- **🎨 Premium Aesthetic**: Powered by `Rich` and `Typer` to look incredible in any modern terminal emulator (iTerm, Kitty, Windows Terminal).
+- **🚀 Performance**: Lightning-fast startup with lazy-loaded imports and zero-overhead UI rendering.
+
+---
+
+## ⚡ Quick Start Guide
+
+### Installation
+
+Install via pip:
+```bash
+pip install zen-timer
+```
+---
+
+## 💻 Comprehensive Usage
+
+### Start a Session
+To start a default 25-minute Pomodoro session:
+```bash
+zen
+```
+### Advanced Usage
+
+**zen** supports additional CLI flags to customize your workflow:
+
+- **`--break`**: Run the timer as a break session instead of a focus session. Ideal for timing your rest periods between deep work blocks.
+  ```bash
+  zen 5 --break
+  ```
+
+- **`--silent`**: Run the timer without sending desktop notifications upon completion. Perfect for environments where notifications are distracting or unsupported.
+  ```bash
+  zen 25 --silent
+  ```
+
+You can also combine these flags for a silent break session:
+```bash
+zen 15 --break --silent
+```
+---
+
+## 🤝 Contributing
+Want to help safeguard developer focus? Let's flow together! 🌊
+- 🐛 **Found a bug?** Open an issue to let us know.
+- ✨ **Have a feature idea?** We are open to PRs! Keep the UI minimal and the code beautiful.
+- 🎨 **Documentation tweaks?** Always welcome!
+
+---
+> *Crafted by a Vibe Coder. Protect your focus.*

zen_timer-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "zen-timer"
+version = "0.2.0"
+description = "🧘 Deep-work timer. Simple terminal app for focus sessions. No GUI, just flow."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Shenal Diluksha", email = "shenald@users.noreply.github.com" }
+]
+maintainers = [
+    { name = "shenald-dev", email = "shenald@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+keywords = ["zen", "timer", "pomodoro", "focus", "deep-work", "cli", "tui", "productivity"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities"
+]
+dependencies = [
+    "rich>=13.9.0,<16.0.0",
+    "typer>=0.12.0,<1.0.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0,<10.0.0",
+    "pytest-mock>=3.14.0,<4.0.0",
+    "pytest-cov>=5.0.0,<8.0.0",
+    "flake8>=7.0.0,<8.0.0",
+    "pylint>=3.0.0,<5.0.0"
+]
+
+[project.scripts]
+zen = "zen.timer:main"
+
+[project.urls]
+Homepage = "https://github.com/shenald-dev/zen"
+Documentation = "https://github.com/shenald-dev/zen#readme"
+Repository = "https://github.com/shenald-dev/zen"
+Issues = "https://github.com/shenald-dev/zen/issues"
+Changelog = "https://github.com/shenald-dev/zen/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.coverage.run]
+omit = [
+    "src/zen/__main__.py",
+    "src/zen/__init__.py"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+ignore_missing_imports = true

zen_timer-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zen_timer-0.2.0/src/zen/__init__.py

@@ -0,0 +1 @@
+"""Zen - Deep-work terminal timer."""

zen_timer-0.2.0/src/zen/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for the zen-timer application."""
+from zen.timer import app
+
+
+def main() -> None:
+    """Run the main application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

zen_timer-0.2.0/src/zen/timer.py

@@ -0,0 +1,174 @@
+"""Zen - Deep-work terminal timer."""
+import time
+import typer
+# pylint: disable=import-outside-toplevel
+# Import rich lazily inside the command for faster --help execution
+
+app = typer.Typer(
+    help="🧘 Deep-work terminal timer for focus sessions.",
+    add_completion=False,
+    rich_markup_mode=None,
+)
+
+
+def version_callback(value: bool) -> None:
+    """Callback for the --version option."""
+    if value:
+        import importlib.metadata  # pylint: disable=import-outside-toplevel
+        try:
+            version = importlib.metadata.version("zen-timer")
+        except importlib.metadata.PackageNotFoundError:
+            version = "unknown"
+        print(f"zen-timer version {version}")
+        raise typer.Exit()
+
+
+@app.command()  # type: ignore[untyped-decorator]
+def focus(  # pylint: disable=too-many-statements,too-many-branches
+    minutes: int = typer.Argument(
+        25, min=1, max=1440, help="Minutes to focus for"
+    ),
+    is_break: bool = typer.Option(
+        False, "--break", help="Start a break session."
+    ),
+    silent: bool = typer.Option(
+        False, "--silent", help="Run without desktop notifications."
+    ),
+    version: bool = typer.Option(  # pylint: disable=unused-argument
+        None,
+        "--version",
+        callback=version_callback,
+        is_eager=True,
+        help="Show the application version and exit."
+    )
+) -> None:
+    """Start a deep-work focus session."""
+    # pylint: disable=too-many-locals
+    seconds = minutes * 60
+    console = None
+
+    try:
+        from rich.console import Console
+        from rich.progress import (
+            Progress, BarColumn, TextColumn, TimeRemainingColumn
+        )
+        from rich.panel import Panel
+
+        console = Console()
+        console.clear()
+        minute_str = "Minute" if minutes == 1 else "Minutes"
+        if is_break:
+            title_text = (
+                f"[bold green]☕ Break Time: {minutes} "
+                f"{minute_str}[/bold green]\n"
+                "[gray]Rest and recharge.[/gray]"
+            )
+            border_style = "green"
+            task_desc = "[green]Recharging..."
+            bar_complete_style = "green"
+        else:
+            title_text = (
+                f"[bold cyan]🧘 Zen Mode Activated: {minutes} "
+                f"{minute_str} of Deep Work[/bold cyan]\n"
+                "[gray]Do not disturb. No GUI, just flow.[/gray]"
+            )
+            border_style = "cyan"
+            task_desc = "[cyan]Flow State..."
+            bar_complete_style = "cyan"
+
+        title = Panel.fit(
+            title_text,
+            border_style=border_style,
+            padding=(1, 4)
+        )
+        console.print(title, justify="center")
+        console.print("\n")
+
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(
+                bar_width=None,
+                style="magenta",
+                complete_style=bar_complete_style,
+                finished_style=bar_complete_style
+            ),
+            TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+            TimeRemainingColumn(),
+            console=console,
+            transient=False,
+            auto_refresh=False,  # Disable background thread for performance
+        ) as progress:
+            task = progress.add_task(task_desc, total=seconds)
+
+            start_time = time.monotonic()
+            last_second = -1
+
+            while True:
+                elapsed = time.monotonic() - start_time
+                remaining = seconds - elapsed
+
+                if remaining <= 0:
+                    progress.update(task, completed=seconds, refresh=True)
+                    break
+
+                # Only refresh UI when a full second has passed
+                current_second = int(elapsed)
+                if current_second > last_second:
+                    progress.update(
+                        task, completed=elapsed, refresh=True
+                    )
+                    last_second = current_second
+
+                # Recalculate elapsed to natively absorb loop execution
+                # overhead
+                elapsed = time.monotonic() - start_time
+                remaining = seconds - elapsed
+
+                # Drift-compensated sleep to maintain exact 1Hz refresh rate
+                sleep_interval = 1.0 - (elapsed % 1.0)
+                time.sleep(max(0, min(sleep_interval, remaining)))
+
+        console.print("\n")
+        if not silent:
+            console.bell()
+
+        if is_break:
+            completion = Panel.fit(
+                "[bold cyan]✨ Break complete. Ready to focus?[/bold cyan]",
+                border_style="cyan"
+            )
+        else:
+            completion = Panel.fit(
+                "[bold green]✨ Focus session complete. "
+                "Take a break.[/bold green]",
+                border_style="green"
+            )
+        console.print(completion, justify="center")
+    except KeyboardInterrupt as exc:
+        if is_break:
+            msg = "⏸️  Break paused. Rest is important too."
+        else:
+            msg = "⏸️  Session paused. Your focus still matters."
+
+        try:
+            if console is not None:
+                console.print("\n")
+                interrupted = Panel.fit(
+                    f"[bold yellow]{msg}[/bold yellow]",
+                    border_style="yellow"
+                )
+                console.print(interrupted, justify="center")
+            else:
+                print(f"\n{msg}")
+        except KeyboardInterrupt:
+            pass
+        raise typer.Exit(code=130) from exc
+
+
+def main() -> None:
+    """Main entrypoint for the CLI app."""
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

zen_timer-0.2.0/src/zen_timer.egg-info/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: zen-timer
+Version: 0.2.0
+Summary: 🧘 Deep-work timer. Simple terminal app for focus sessions. No GUI, just flow.
+Author-email: Shenal Diluksha <shenald@users.noreply.github.com>
+Maintainer-email: shenald-dev <shenald@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/shenald-dev/zen
+Project-URL: Documentation, https://github.com/shenald-dev/zen#readme
+Project-URL: Repository, https://github.com/shenald-dev/zen
+Project-URL: Issues, https://github.com/shenald-dev/zen/issues
+Project-URL: Changelog, https://github.com/shenald-dev/zen/blob/main/CHANGELOG.md
+Keywords: zen,timer,pomodoro,focus,deep-work,cli,tui,productivity
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich<16.0.0,>=13.9.0
+Requires-Dist: typer<1.0.0,>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "dev"
+Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=5.0.0; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pylint<5.0.0,>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# README.md
+<div align="center">
+  <img src="assets/logo.png" alt="zen Logo" width="250" />
+  
+  <br/>
+
+  <h1>🧘‍♂️ zen</h1>
+  <p><b>Minimalist Terminal Deep-Work Timer</b></p>
+  <i>Simple terminal app for focus sessions. No GUI, just flow.</i>
+
+  <br/>
+  
+  [![PyPI version](https://img.shields.io/pypi/v/zen-timer.svg)](https://pypi.org/project/zen-timer/)
+  [![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+</div>
+
+---
+
+## 📑 Table of Contents
+- [🌟 Overview](#-overview)
+- [🚀 Enterprise Features](#-enterprise-features)
+- [⚡ Quick Start Guide](#-quick-start-guide)
+- [💻 Comprehensive Usage](#-comprehensive-usage)
+- [🤝 Contributing](#-contributing)
+
+---
+
+## 🌟 Overview
+
+**zen** is an ultra-minimalist, distraction-free terminal application built to safeguard developer focus. It ditches complex GUIs in favor of beautiful, native terminal progress indicators. Dive straight into flow state.
+
+---
+
+## 🚀 Enterprise Features
+
+- **🌊 Flow State**: Visually stunning, distraction-free TUI progress bar.
+- **⏱️ Flexible**: Fully configurable focus sessions and break reminders.
+- **🎨 Premium Aesthetic**: Powered by `Rich` and `Typer` to look incredible in any modern terminal emulator (iTerm, Kitty, Windows Terminal).
+- **🚀 Performance**: Lightning-fast startup with lazy-loaded imports and zero-overhead UI rendering.
+
+---
+
+## ⚡ Quick Start Guide
+
+### Installation
+
+Install via pip:
+```bash
+pip install zen-timer
+```
+---
+
+## 💻 Comprehensive Usage
+
+### Start a Session
+To start a default 25-minute Pomodoro session:
+```bash
+zen
+```
+### Advanced Usage
+
+**zen** supports additional CLI flags to customize your workflow:
+
+- **`--break`**: Run the timer as a break session instead of a focus session. Ideal for timing your rest periods between deep work blocks.
+  ```bash
+  zen 5 --break
+  ```
+
+- **`--silent`**: Run the timer without sending desktop notifications upon completion. Perfect for environments where notifications are distracting or unsupported.
+  ```bash
+  zen 25 --silent
+  ```
+
+You can also combine these flags for a silent break session:
+```bash
+zen 15 --break --silent
+```
+---
+
+## 🤝 Contributing
+Want to help safeguard developer focus? Let's flow together! 🌊
+- 🐛 **Found a bug?** Open an issue to let us know.
+- ✨ **Have a feature idea?** We are open to PRs! Keep the UI minimal and the code beautiful.
+- 🎨 **Documentation tweaks?** Always welcome!
+
+---
+> *Crafted by a Vibe Coder. Protect your focus.*

zen_timer-0.2.0/src/zen_timer.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/zen/__init__.py
+src/zen/__main__.py
+src/zen/timer.py
+src/zen_timer.egg-info/PKG-INFO
+src/zen_timer.egg-info/SOURCES.txt
+src/zen_timer.egg-info/dependency_links.txt
+src/zen_timer.egg-info/entry_points.txt
+src/zen_timer.egg-info/requires.txt
+src/zen_timer.egg-info/top_level.txt
+tests/test_timer.py

zen_timer-0.2.0/src/zen_timer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zen_timer-0.2.0/src/zen_timer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zen = zen.timer:main

zen_timer-0.2.0/src/zen_timer.egg-info/requires.txt

@@ -0,0 +1,9 @@
+rich<16.0.0,>=13.9.0
+typer<1.0.0,>=0.12.0
+
+[dev]
+pytest<10.0.0,>=8.0.0
+pytest-mock<4.0.0,>=3.14.0
+pytest-cov<8.0.0,>=5.0.0
+flake8<8.0.0,>=7.0.0
+pylint<5.0.0,>=3.0.0

zen_timer-0.2.0/src/zen_timer.egg-info/top_level.txt

@@ -0,0 +1 @@
+zen

zen_timer-0.2.0/tests/test_timer.py

@@ -0,0 +1,279 @@
+"""Tests for zen-timer."""
+from typing import Any
+
+from pytest_mock import MockerFixture
+from typer.testing import CliRunner
+
+from zen.timer import app
+
+runner = CliRunner()
+
+
+class MockMonotonic:  # pylint: disable=R0903
+    """Mock for time.monotonic."""
+
+    def __init__(self) -> None:
+        self.current = 0.0
+
+    def __call__(self) -> float:
+        self.current += 10.0
+        return self.current
+
+
+def test_focus_invalid_minutes() -> None:
+    """Test that focusing for less than 1 minute raises an error."""
+    result = runner.invoke(app, ["0"])
+    assert result.exit_code == 2
+    assert "0 is not in the range 1<=x<=1440." in result.output
+
+
+def test_focus_invalid_minutes_too_high() -> None:
+    """Test that focusing for more than 1440 minutes raises an error."""
+    result = runner.invoke(app, ["1500"])
+    assert result.exit_code == 2
+    assert "1500 is not in the range 1<=x<=1440." in result.output
+
+
+def test_focus_valid_minutes(mocker: MockerFixture) -> None:
+    """Test a valid focus session."""
+    # Mock time.sleep to avoid actually waiting during the test
+    mocker.patch("time.sleep")
+
+    # Mock time.monotonic to instantly advance past the duration
+    # We use a generator or function so it doesn't run out of side effects
+    # if rich calls it more
+
+    mock_monotonic = MockMonotonic()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+    result = runner.invoke(app, ["1"])
+    assert result.exit_code == 0
+    assert "Zen Mode Activated: 1 Minute of Deep Work" in result.output
+    assert "Focus session complete" in result.output
+
+
+def test_focus_valid_minutes_plural(mocker: MockerFixture) -> None:
+    """Test a valid focus session for plural minutes."""
+    mocker.patch("time.sleep")
+
+    mock_monotonic = MockMonotonic()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+    result = runner.invoke(app, ["2"])
+    assert result.exit_code == 0
+    assert "Zen Mode Activated: 2 Minutes of Deep Work" in result.output
+    assert "Focus session complete" in result.output
+
+
+def test_focus_break_flag(mocker: MockerFixture) -> None:
+    """Test that the --break flag modifies the UI appropriately."""
+    mocker.patch("time.sleep")
+
+    mock_monotonic = MockMonotonic()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+    result = runner.invoke(app, ["5", "--break"])
+    assert result.exit_code == 0
+    assert "Break Time: 5 Minutes" in result.output
+    assert "Break complete. Ready to focus?" in result.output
+
+
+def test_focus_silent_flag(mocker: MockerFixture) -> None:
+    """Test that the --silent flag omits the terminal bell."""
+    mocker.patch("time.sleep")
+    mock_bell = mocker.patch("rich.console.Console.bell")
+
+    mock_monotonic = MockMonotonic()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+    result = runner.invoke(app, ["1", "--silent"])
+    assert result.exit_code == 0
+    mock_bell.assert_not_called()
+
+
+def test_focus_keyboard_interrupt(mocker: MockerFixture) -> None:
+    """Test handling of KeyboardInterrupt (Ctrl+C)."""
+    # Simulate a KeyboardInterrupt on the first sleep call
+    mocker.patch("time.sleep", side_effect=KeyboardInterrupt)
+    mocker.patch("time.monotonic", return_value=0.0)
+    result = runner.invoke(app, ["1"])
+    # The application handles the interrupt gracefully, and exits with 130
+    assert result.exit_code == 130
+    assert "Session paused. Your focus still matters." in result.output
+
+
+def test_break_keyboard_interrupt(mocker: MockerFixture) -> None:
+    """Test handling of KeyboardInterrupt during a break session."""
+    mocker.patch("time.sleep", side_effect=KeyboardInterrupt)
+    mocker.patch("time.monotonic", return_value=0.0)
+    result = runner.invoke(app, ["1", "--break"])
+    assert result.exit_code == 130
+    assert "Break paused. Rest is important too." in result.output
+
+
+def test_focus_early_keyboard_interrupt(mocker: MockerFixture) -> None:
+    """Test handling of KeyboardInterrupt before rich is initialized."""
+    # Simulate a KeyboardInterrupt right when Console is initialized
+    mocker.patch(
+        "rich.console.Console.__init__",
+        side_effect=KeyboardInterrupt
+    )
+    result = runner.invoke(app, ["1"])
+    # The application handles the interrupt gracefully and uses raw print
+    assert result.exit_code == 130
+    assert "Session paused. Your focus still matters." in result.output
+
+
+def test_break_early_keyboard_interrupt(mocker: MockerFixture) -> None:
+    """Test handling of early KeyboardInterrupt during a break session."""
+    mocker.patch(
+        "rich.console.Console.__init__",
+        side_effect=KeyboardInterrupt
+    )
+    result = runner.invoke(app, ["1", "--break"])
+    assert result.exit_code == 130
+    assert "Break paused. Rest is important too." in result.output
+
+
+def test_focus_double_keyboard_interrupt(mocker: MockerFixture) -> None:
+    """Test handling KeyboardInterrupt within the interrupt handler."""
+    mocker.patch("time.sleep", side_effect=KeyboardInterrupt)
+    mocker.patch("time.monotonic", return_value=0.0)
+
+    class SideEffectFunc:  # pylint: disable=R0903
+        """Mock for side effect."""
+
+        def __init__(self) -> None:
+            self.count = 0
+
+        def __call__(
+            self, *args: Any, **kwargs: Any
+        ) -> Any:  # pylint: disable=unused-argument
+            if self.count == 2:
+                raise KeyboardInterrupt
+            self.count += 1
+
+    side_effect_func = SideEffectFunc()
+    mocker.patch("rich.console.Console.print", side_effect=side_effect_func)
+
+    result = runner.invoke(app, ["1"])
+    # The application gracefully handles the double interrupt and exits 130
+    assert result.exit_code == 130
+
+
+def test_version_flag() -> None:
+    """Test that the --version flag outputs the version and exits."""
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert "zen-timer version" in result.output
+
+
+def test_version_not_found(mocker: MockerFixture) -> None:
+    """Test fallback when the package version cannot be found."""
+    import importlib.metadata  # pylint: disable=import-outside-toplevel
+    mocker.patch(
+        "importlib.metadata.version",
+        side_effect=importlib.metadata.PackageNotFoundError
+    )
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+    assert "zen-timer version unknown" in result.output
+
+
+def test_focus_break_and_silent_flags(mocker: MockerFixture) -> None:
+    """Test that combining --break and --silent flags works correctly."""
+    mocker.patch("time.sleep")
+    mock_bell = mocker.patch("rich.console.Console.bell")
+
+    mock_monotonic = MockMonotonic()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+    result = runner.invoke(app, ["3", "--break", "--silent"])
+    assert result.exit_code == 0
+    assert "Break Time: 3 Minutes" in result.output
+    assert "Break complete. Ready to focus?" in result.output
+    mock_bell.assert_not_called()
+
+
+def test_focus_sleep_bounds_check(mocker: MockerFixture) -> None:
+    """Test that negative sleep intervals are bounded to 0."""
+    mock_sleep = mocker.patch("time.sleep")
+
+    original_min = min
+
+    def mock_min(*args: Any, **kwargs: Any) -> Any:
+        # We only want to return -0.5 for timer.py calls
+        # timer.py calls: min(sleep_interval, remaining)
+        # sleep_interval is float, remaining is float.
+        if (len(args) == 2 and isinstance(args[0], float) and
+                isinstance(args[1], float)):
+            # If we are in the focus loop
+            if 0.0 <= args[1] <= 60.0:
+                return -0.5
+        return original_min(*args, **kwargs)
+
+    mocker.patch("builtins.min", side_effect=mock_min)
+
+    # We need sleep to be called at least once before breaking
+    class MockMonotonicBounds:  # pylint: disable=R0903
+        """Mock for time.monotonic bounds check."""
+
+        def __init__(self) -> None:
+            self.call_count = 0
+
+        def __call__(self) -> float:
+            if self.call_count == 0:
+                self.call_count += 1
+                return 0.0  # Start time
+            if self.call_count == 1:
+                self.call_count += 1
+                return 0.5  # First loop check
+            if self.call_count == 2:
+                self.call_count += 1
+                return 0.6  # Recalculate if UI triggers, or next loop
+            if self.call_count == 3:
+                self.call_count += 1
+                return 60.0  # Breaks loop
+            self.call_count += 1
+            return 65.0
+
+    mock_monotonic = MockMonotonicBounds()
+    mocker.patch("time.monotonic", side_effect=mock_monotonic)
+
+    result = runner.invoke(app, ["1"])
+
+    assert result.exit_code == 0
+    mock_sleep.assert_any_call(0)
+
+
+def test_focus_double_keyboard_interrupt_cleanup(
+    mocker: MockerFixture
+) -> None:
+    """Test handling of a double KeyboardInterrupt during cleanup."""
+    mocker.patch("time.sleep", side_effect=KeyboardInterrupt)
+    mocker.patch("time.monotonic", return_value=0.0)
+
+    class MockPrint:  # pylint: disable=R0903
+        """Mock for console print."""
+
+        def __init__(self) -> None:
+            self.call_count = 0
+
+        def __call__(
+            self, *args: Any, **kwargs: Any
+        ) -> Any:  # pylint: disable=unused-argument
+            self.call_count += 1
+            # Raise KeyboardInterrupt on the 6th print call to simulate a
+            # second Ctrl+C during the cleanup routine
+            if self.call_count == 6:
+                raise KeyboardInterrupt
+
+    mock_print = MockPrint()
+    mocker.patch("rich.console.Console.print", side_effect=mock_print)
+
+    result = runner.invoke(app, ["1"], catch_exceptions=False)
+    assert result.exit_code == 130
+
+
+def test_main(mocker: MockerFixture) -> None:
+    """Test that main() calls the Typer app."""
+    mock_app = mocker.patch("zen.timer.app")
+    # pylint: disable=import-outside-toplevel
+    from zen.timer import main
+    main()
+    mock_app.assert_called_once()