stackvox 0.3.0__tar.gz → 0.3.1__tar.gz

{stackvox-0.3.0/stackvox.egg-info → stackvox-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.0
+Version: 0.3.1
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -45,11 +45,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash

{stackvox-0.3.0 → stackvox-0.3.1}/README.md

@@ -12,11 +12,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash

{stackvox-0.3.0 → stackvox-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.3.0"
+version = "0.3.1"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -45,15 +45,16 @@ Issues = "https://github.com/StackOneHQ/stackvox/issues"
 [project.scripts]
 stackvox = "stackvox.cli:main"
 
-[tool.setuptools]
-script-files = ["bin/stackvox-say"]
-
 [tool.setuptools.packages.find]
 include = ["stackvox*"]
 
 [tool.setuptools.package-data]
-# Ship the PEP 561 marker so downstream type checkers trust our inline hints.
-stackvox = ["py.typed"]
+# Ship the PEP 561 marker so downstream type checkers trust our inline hints,
+# and the bash helper as package data — extracted onto PATH by
+# `stackvox install-helper`. (We deliberately don't use [tool.setuptools]
+# script-files = [...]: it's discouraged, has no PEP 621 equivalent, and
+# doesn't round-trip through hatchling/uv if we ever migrate build backends.)
+stackvox = ["py.typed", "data/stackvox-say"]
 
 [tool.ruff]
 line-length = 110

{stackvox-0.3.0 → stackvox-0.3.1}/stackvox/cli.py

@@ -21,7 +21,19 @@ def _configure_logging() -> None:
     )
 
 
-SUBCOMMANDS = {"serve", "stop", "status", "say", "speak", "voices", "welcome", "completion"}
+SUBCOMMANDS = {
+    "serve",
+    "stop",
+    "status",
+    "say",
+    "speak",
+    "voices",
+    "welcome",
+    "completion",
+    "install-helper",
+}
+
+DEFAULT_HELPER_PREFIX = Path.home() / ".local" / "bin"
 
 _BASH_COMPLETION = r"""# stackvox bash completion. Install with one of:
 #   eval "$(stackvox completion bash)"          # current shell
@@ -34,7 +46,7 @@ _stackvox_completion() {
     subcommand="${COMP_WORDS[1]:-}"
 
     if [[ ${COMP_CWORD} -eq 1 ]]; then
-        COMPREPLY=( $(compgen -W "speak say serve stop status voices welcome completion" -- "$cur") )
+        COMPREPLY=( $(compgen -W "speak say serve stop status voices welcome completion install-helper" -- "$cur") )
         return 0
     fi
 
@@ -43,6 +55,10 @@ _stackvox_completion() {
             COMPREPLY=( $(compgen -f -- "$cur") )
             return 0
             ;;
+        --prefix)
+            COMPREPLY=( $(compgen -d -- "$cur") )
+            return 0
+            ;;
         --speed)
             COMPREPLY=( $(compgen -W "0.8 0.9 1.0 1.1 1.2 1.5" -- "$cur") )
             return 0
@@ -66,6 +82,9 @@ _stackvox_completion() {
         completion)
             COMPREPLY=( $(compgen -W "bash" -- "$cur") )
             ;;
+        install-helper)
+            COMPREPLY=( $(compgen -W "--prefix --help" -- "$cur") )
+            ;;
         *)
             COMPREPLY=( $(compgen -W "--help" -- "$cur") )
             ;;
@@ -113,6 +132,17 @@ def _build_parser() -> argparse.ArgumentParser:
     p_completion = sub.add_parser("completion", help="Print a shell completion script")
     p_completion.add_argument("shell", choices=["bash"], help="Shell to generate completion for")
 
+    p_install_helper = sub.add_parser(
+        "install-helper",
+        help="Copy the stackvox-say bash helper onto PATH (default: ~/.local/bin)",
+    )
+    p_install_helper.add_argument(
+        "--prefix",
+        type=Path,
+        default=DEFAULT_HELPER_PREFIX,
+        help=f"Install directory (default: {DEFAULT_HELPER_PREFIX})",
+    )
+
     return parser
 
 
@@ -221,6 +251,42 @@ def _cmd_completion(args: argparse.Namespace) -> int:
     return 1
 
 
+def _cmd_install_helper(args: argparse.Namespace) -> int:
+    """Copy the bundled `stackvox-say` bash helper onto PATH.
+
+    The helper is shipped as package data (`stackvox/data/stackvox-say`) rather
+    than installed automatically by setuptools — `script-files` is discouraged
+    and doesn't round-trip through modern build backends. This subcommand is
+    the explicit one-time install step.
+    """
+    import os
+    import shutil
+    import stat
+    from importlib.resources import as_file, files
+
+    prefix = Path(args.prefix).expanduser()
+    prefix.mkdir(parents=True, exist_ok=True)
+    dest = prefix / "stackvox-say"
+
+    src = files("stackvox").joinpath("data/stackvox-say")
+    with as_file(src) as src_path:
+        shutil.copy2(src_path, dest)
+
+    # Ensure executable bits regardless of how the wheel preserved them.
+    dest.chmod(dest.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    print(f"Installed stackvox-say to {dest}", file=sys.stderr)
+
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    if str(prefix) not in path_dirs:
+        print(
+            f"Note: {prefix} is not on your PATH. Either add it to PATH or invoke "
+            f"the helper via its full path: {dest}",
+            file=sys.stderr,
+        )
+    return 0
+
+
 def main() -> int:
     _configure_logging()
     argv = sys.argv[1:]
@@ -247,6 +313,7 @@ def main() -> int:
         "voices": _cmd_voices,
         "welcome": _cmd_welcome,
         "completion": _cmd_completion,
+        "install-helper": _cmd_install_helper,
     }
     return handlers[args.cmd](args)
 

{stackvox-0.3.0 → stackvox-0.3.1/stackvox.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.3.0
+Version: 0.3.1
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -45,11 +45,20 @@ Offline TTS using [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) via [k
 From PyPI — recommended for most users:
 
 ```bash
-pipx install stackvox    # global CLI (`stackvox` and `stackvox-say` on PATH)
+pipx install stackvox       # `stackvox` CLI on PATH
 # or
-pip install stackvox     # use as a library
+pip install stackvox        # use as a library
 ```
 
+If you want the low-latency bash helper (`stackvox-say`) for shell scripts and hooks, install it on PATH after installing the package:
+
+```bash
+stackvox install-helper     # copies bash helper to ~/.local/bin
+                            # use --prefix DIR to install elsewhere
+```
+
+This is a one-time step. The helper is shipped as package data rather than as an automatic install script — explicit beats magical, and it keeps stackvox compatible with modern build backends. Skip it if you only ever use the Python `stackvox say` client.
+
 From git, if you want an unreleased commit:
 
 ```bash

{stackvox-0.3.0 → stackvox-0.3.1}/stackvox.egg-info/SOURCES.txt

@@ -2,7 +2,6 @@ LICENSE
 NOTICE
 README.md
 pyproject.toml
-bin/stackvox-say
 stackvox/__init__.py
 stackvox/__main__.py
 stackvox/cli.py
@@ -16,6 +15,9 @@ stackvox.egg-info/dependency_links.txt
 stackvox.egg-info/entry_points.txt
 stackvox.egg-info/requires.txt
 stackvox.egg-info/top_level.txt
+stackvox/data/stackvox-say
 tests/test_cli.py
+tests/test_daemon.py
 tests/test_daemon_protocol.py
+tests/test_engine.py
 tests/test_paths.py

stackvox-0.3.1/tests/test_cli.py

@@ -0,0 +1,292 @@
+"""CLI argument parsing — no engine loaded, no audio played."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+
+from stackvox import cli
+
+
+@pytest.fixture(autouse=True)
+def _stdin_is_a_tty(mocker):
+    """Default tests to a TTY stdin so the new piped-stdin shortcut is off.
+
+    Tests that exercise the piped path opt in by patching isatty to False
+    and providing a real stdin StringIO.
+    """
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=True)
+
+
+def test_bare_text_routes_to_speak(mocker):
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello world"])
+    assert cli.main() == 0
+    args = speak.call_args.args[0]
+    assert args.cmd == "speak"
+    assert args.text == "hello world"
+
+
+def test_speak_subcommand_parses_voice_and_speed(mocker):
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "--voice", "bf_emma", "--speed", "1.2", "hi"])
+    assert cli.main() == 0
+    args = speak.call_args.args[0]
+    assert args.voice == "bf_emma"
+    assert args.speed == pytest.approx(1.2)
+    assert args.text == "hi"
+
+
+def test_no_subcommand_prints_help(mocker, capsys):
+    mocker.patch.object(cli.sys, "argv", ["stackvox"])
+    assert cli.main() == 1
+    captured = capsys.readouterr()
+    assert "usage: stackvox" in captured.out
+
+
+def test_unknown_subcommand_treated_as_speak_text(mocker):
+    """`stackvox foo` is treated as `stackvox speak foo`, not an error."""
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello"])
+    cli.main()
+    assert speak.call_args.args[0].text == "hello"
+
+
+def test_piped_stdin_with_no_args_routes_to_speak(mocker):
+    """`echo hi | stackvox` should default to speak."""
+    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
+    mocker.patch.object(cli.sys, "argv", ["stackvox"])
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
+    mocker.patch.object(cli.sys, "stdin", io.StringIO("hello from stdin\n"))
+    assert cli.main() == 0
+    assert speak.call_args.args[0].cmd == "speak"
+
+
+def test_read_text_prefers_file_then_positional_then_stdin(mocker, tmp_path):
+    """_read_text precedence: --file > positional > piped stdin."""
+    file_arg = tmp_path / "src.txt"
+    file_arg.write_text("from-file", encoding="utf-8")
+
+    # Both --file and positional present → file wins.
+    args = mocker.MagicMock(file=file_arg, text="from-positional")
+    assert cli._read_text(args) == "from-file"
+
+    # No --file, positional present → positional wins.
+    args = mocker.MagicMock(file=None, text="from-positional")
+    assert cli._read_text(args) == "from-positional"
+
+    # No --file, no positional, stdin piped → stdin wins.
+    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
+    mocker.patch.object(cli.sys, "stdin", io.StringIO("from-stdin"))
+    args = mocker.MagicMock(file=None, text=None)
+    assert cli._read_text(args) == "from-stdin"
+
+
+def test_completion_bash_emits_complete_script(mocker, capsys):
+    mocker.patch.object(cli.sys, "argv", ["stackvox", "completion", "bash"])
+    assert cli.main() == 0
+    captured = capsys.readouterr()
+    assert "_stackvox_completion()" in captured.out
+    assert "complete -F _stackvox_completion stackvox" in captured.out
+
+
+# --- Subcommand handlers ----------------------------------------------------
+#
+# Each subcommand handler is exercised directly with a constructed Namespace
+# so we don't have to reason about argparse behavior for every test. The
+# Stackvox class and the daemon module's surface are mocked out.
+
+
+@pytest.fixture
+def fake_stackvox(mocker):
+    return mocker.patch.object(cli, "Stackvox")
+
+
+def _ns(**kwargs):
+    """Build a minimal argparse.Namespace for handler tests."""
+    import argparse
+
+    return argparse.Namespace(**kwargs)
+
+
+class TestCmdSpeak:
+    def test_with_text_calls_engine_speak(self, fake_stackvox):
+        rc = cli._cmd_speak(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hello", out=None))
+        assert rc == 0
+        fake_stackvox.return_value.speak.assert_called_once_with("hello")
+
+    def test_with_out_writes_wav_instead_of_playing(self, fake_stackvox, mocker, tmp_path):
+        import numpy as np
+
+        fake_stackvox.return_value.synthesize.return_value = (
+            np.zeros(10, dtype=np.float32),
+            24000,
+        )
+        sf_write = mocker.patch.object(cli.sf, "write")
+        out = tmp_path / "out.wav"
+
+        rc = cli._cmd_speak(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hi", out=out))
+
+        assert rc == 0
+        sf_write.assert_called_once()
+        fake_stackvox.return_value.speak.assert_not_called()
+
+    def test_blank_input_returns_error(self, fake_stackvox, capsys):
+        rc = cli._cmd_speak(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="   ", out=None))
+        assert rc == 1
+        assert "provide text" in capsys.readouterr().err
+        fake_stackvox.return_value.speak.assert_not_called()
+
+
+class TestCmdSay:
+    def test_returns_zero_when_daemon_accepts(self, mocker):
+        mocker.patch.object(cli.daemon, "say", return_value=(True, "ok"))
+        rc = cli._cmd_say(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hi", fallback_say=False))
+        assert rc == 0
+
+    def test_returns_two_when_daemon_unreachable_and_no_fallback(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "say", return_value=(False, "daemon not running"))
+        rc = cli._cmd_say(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hi", fallback_say=False))
+        assert rc == 2
+        assert "daemon not running" in capsys.readouterr().err
+
+    def test_fallback_say_shells_out_on_macos(self, mocker):
+        mocker.patch.object(cli.daemon, "say", return_value=(False, "daemon not running"))
+        # Must use which because cli imports inside the function body.
+        mocker.patch("shutil.which", return_value="/usr/bin/say")
+        run = mocker.patch("subprocess.run")
+        rc = cli._cmd_say(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hi", fallback_say=True))
+        assert rc == 0
+        run.assert_called_once()
+        assert run.call_args.args[0][0] == "say"
+
+    def test_fallback_say_without_say_binary_returns_two(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "say", return_value=(False, "daemon not running"))
+        mocker.patch("shutil.which", return_value=None)
+        rc = cli._cmd_say(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="hi", fallback_say=True))
+        assert rc == 2
+
+    def test_blank_input_returns_one(self, capsys):
+        rc = cli._cmd_say(_ns(voice="af_sarah", speed=1.0, lang="en-us", text="", fallback_say=False))
+        assert rc == 1
+
+
+class TestCmdServe:
+    def test_propagates_serve_args(self, mocker):
+        serve = mocker.patch.object(cli.daemon, "serve")
+        rc = cli._cmd_serve(_ns(voice="bf_emma", speed=1.1, lang="en-gb"))
+        assert rc == 0
+        serve.assert_called_once_with(voice="bf_emma", speed=1.1, lang="en-gb")
+
+    def test_returns_one_when_daemon_already_running(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "serve", side_effect=RuntimeError("daemon already running"))
+        rc = cli._cmd_serve(_ns(voice="af_sarah", speed=1.0, lang="en-us"))
+        assert rc == 1
+        assert "already running" in capsys.readouterr().err
+
+
+class TestCmdStop:
+    def test_returns_zero_when_daemon_already_stopped(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "is_running", return_value=False)
+        stop = mocker.patch.object(cli.daemon, "stop")
+        rc = cli._cmd_stop(_ns())
+        assert rc == 0
+        stop.assert_not_called()
+        assert "not running" in capsys.readouterr().err
+
+    def test_calls_daemon_stop_when_running(self, mocker):
+        mocker.patch.object(cli.daemon, "is_running", return_value=True)
+        mocker.patch.object(cli.daemon, "stop", return_value=(True, "ok"))
+        assert cli._cmd_stop(_ns()) == 0
+
+
+class TestCmdStatus:
+    def test_running_prints_pid_and_returns_zero(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "is_running", return_value=True)
+        # PID_PATH and SOCKET_PATH are read at module level — mock as needed.
+        pid_path = mocker.MagicMock()
+        pid_path.read_text.return_value = "12345\n"
+        mocker.patch.object(cli.daemon, "PID_PATH", pid_path)
+        mocker.patch.object(cli.daemon, "SOCKET_PATH", "/tmp/x.sock")
+
+        rc = cli._cmd_status(_ns())
+
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "running" in out
+        assert "12345" in out
+
+    def test_stopped_returns_one(self, mocker, capsys):
+        mocker.patch.object(cli.daemon, "is_running", return_value=False)
+        rc = cli._cmd_status(_ns())
+        assert rc == 1
+        assert "stopped" in capsys.readouterr().out
+
+
+class TestCmdVoices:
+    def test_prints_one_voice_per_line(self, fake_stackvox, capsys):
+        fake_stackvox.return_value.voices.return_value = ["af_sarah", "bf_emma"]
+        rc = cli._cmd_voices(_ns())
+        assert rc == 0
+        assert capsys.readouterr().out.split() == ["af_sarah", "bf_emma"]
+
+
+class TestCmdWelcome:
+    def test_calls_speak_sequence_with_welcome_lines(self, fake_stackvox):
+        cli._cmd_welcome(_ns())
+        fake_stackvox.return_value.speak_sequence.assert_called_once()
+        lines = fake_stackvox.return_value.speak_sequence.call_args.args[0]
+        # All WELCOME_LINES rows present.
+        assert len(lines) == len(cli.WELCOME_LINES)
+        # Every entry has text/voice/lang.
+        for entry in lines:
+            assert {"text", "voice", "lang"} <= entry.keys()
+
+
+class TestCmdCompletion:
+    def test_unsupported_shell_returns_one(self, capsys):
+        # argparse choices=["bash"] means we'd never reach here normally;
+        # exercise the defensive branch directly.
+        rc = cli._cmd_completion(_ns(shell="fish"))
+        assert rc == 1
+        assert "unsupported shell" in capsys.readouterr().err
+
+
+class TestCmdInstallHelper:
+    def test_copies_helper_to_prefix_with_exec_bit(self, tmp_path):
+        prefix = tmp_path / "bin"
+        rc = cli._cmd_install_helper(_ns(prefix=prefix))
+
+        assert rc == 0
+        dest = prefix / "stackvox-say"
+        assert dest.exists()
+        # First line should be the bash shebang from the bundled script.
+        assert dest.read_text(encoding="utf-8").startswith("#!/bin/bash")
+        # Owner-execute bit is set.
+        import stat as st
+
+        assert dest.stat().st_mode & st.S_IXUSR
+
+    def test_creates_prefix_dir_if_missing(self, tmp_path):
+        prefix = tmp_path / "deep" / "nested" / "bin"
+        assert not prefix.exists()
+        rc = cli._cmd_install_helper(_ns(prefix=prefix))
+        assert rc == 0
+        assert (prefix / "stackvox-say").is_file()
+
+    def test_warns_when_prefix_not_on_path(self, tmp_path, mocker, capsys):
+        prefix = tmp_path / "out-of-path"
+        # Force PATH to a value that definitely doesn't include `prefix`.
+        mocker.patch.dict("os.environ", {"PATH": "/usr/bin:/bin"}, clear=False)
+        cli._cmd_install_helper(_ns(prefix=prefix))
+        err = capsys.readouterr().err
+        assert "not on your PATH" in err
+
+    def test_no_warning_when_prefix_on_path(self, tmp_path, mocker, capsys):
+        prefix = tmp_path / "on-path"
+        prefix.mkdir(parents=True)
+        # Put `prefix` on PATH so the warning shouldn't fire.
+        mocker.patch.dict("os.environ", {"PATH": f"{prefix}:/usr/bin"}, clear=False)
+        cli._cmd_install_helper(_ns(prefix=prefix))
+        assert "not on your PATH" not in capsys.readouterr().err

stackvox-0.3.1/tests/test_daemon.py

@@ -0,0 +1,138 @@
+"""Daemon tests for non-protocol surface — pid/socket helpers, send/say/stop/ping
+client, _refresh_audio_devices, and the cross-platform watcher entry point.
+The protocol/handler tests live in test_daemon_protocol.py.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from stackvox import daemon
+
+
+class TestPidAlive:
+    def test_self_pid_is_alive(self):
+        assert daemon._pid_alive(os.getpid()) is True
+
+    def test_unused_pid_is_not_alive(self):
+        # PID 0 is reserved on macOS/Linux and never owned by a real process.
+        # `os.kill(0, 0)` is special-cased (signals the whole process group),
+        # so use a high PID we can be confident is unused.
+        assert daemon._pid_alive(2**31 - 1) is False
+
+
+class TestIsRunning:
+    def test_returns_false_when_pid_file_missing(self, mocker, tmp_path):
+        mocker.patch.object(daemon, "PID_PATH", tmp_path / "missing.pid")
+        assert daemon.is_running() is False
+
+    def test_returns_false_when_pid_file_unreadable(self, mocker, tmp_path):
+        pid = tmp_path / "garbage.pid"
+        pid.write_text("not-a-number")
+        mocker.patch.object(daemon, "PID_PATH", pid)
+        assert daemon.is_running() is False
+
+    def test_returns_true_when_pid_alive(self, mocker, tmp_path):
+        pid = tmp_path / "live.pid"
+        pid.write_text(str(os.getpid()))
+        mocker.patch.object(daemon, "PID_PATH", pid)
+        assert daemon.is_running() is True
+
+    def test_returns_false_when_pid_dead(self, mocker, tmp_path):
+        pid = tmp_path / "dead.pid"
+        pid.write_text(str(2**31 - 1))
+        mocker.patch.object(daemon, "PID_PATH", pid)
+        assert daemon.is_running() is False
+
+
+class TestSendHelpers:
+    """The thin send/say/stop/ping wrappers around the unix-socket protocol."""
+
+    def test_send_returns_failure_when_socket_missing(self, mocker, tmp_path):
+        mocker.patch.object(daemon, "SOCKET_PATH", tmp_path / "nope.sock")
+        ok, resp = daemon.send({"command": "ping"})
+        assert ok is False
+        assert resp == "daemon not running"
+
+    def test_say_includes_only_supplied_overrides(self, mocker):
+        send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        daemon.say("hello", voice="bf_emma")
+        payload = send.call_args.args[0]
+        assert payload == {"text": "hello", "voice": "bf_emma"}
+
+    def test_say_with_all_overrides(self, mocker):
+        send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        daemon.say("hi", voice="af_sarah", speed=1.5, lang="en-us")
+        assert send.call_args.args[0] == {
+            "text": "hi",
+            "voice": "af_sarah",
+            "speed": 1.5,
+            "lang": "en-us",
+        }
+
+    def test_say_without_overrides_passes_only_text(self, mocker):
+        send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        daemon.say("hi")
+        assert send.call_args.args[0] == {"text": "hi"}
+
+    def test_stop_sends_command_stop(self, mocker):
+        send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        daemon.stop()
+        assert send.call_args.args[0] == {"command": "stop"}
+
+    def test_ping_uses_short_timeout(self, mocker):
+        send = mocker.patch.object(daemon, "send", return_value=(True, "ok"))
+        daemon.ping()
+        assert send.call_args.kwargs["timeout"] == daemon.PING_TIMEOUT_SECONDS
+
+
+class TestRefreshAudioDevices:
+    def test_calls_terminate_then_initialize(self, mocker):
+        terminate = mocker.patch.object(daemon.sd, "_terminate")
+        initialize = mocker.patch.object(daemon.sd, "_initialize")
+
+        daemon._refresh_audio_devices()
+
+        terminate.assert_called_once()
+        initialize.assert_called_once()
+
+    def test_swallows_and_logs_errors(self, mocker, caplog):
+        """A failure in the audio reset must not propagate out — the worker
+        retries on the next request."""
+        import logging
+
+        mocker.patch.object(daemon.sd, "_terminate", side_effect=RuntimeError("portaudio gone"))
+        mocker.patch.object(daemon.sd, "_initialize")
+
+        with caplog.at_level(logging.ERROR, logger="stackvox.daemon"):
+            daemon._refresh_audio_devices()  # must not raise
+
+        assert any("failed to refresh audio devices" in r.message for r in caplog.records)
+
+
+class TestStartDeviceWatcher:
+    def test_no_op_on_non_darwin(self, mocker):
+        """On Linux/Windows the function returns immediately; nothing should
+        be loaded from CoreAudio and no thread should be started."""
+        mocker.patch.object(daemon.sys, "platform", "linux")
+        cdll = mocker.patch.object(daemon.ctypes, "CDLL")
+
+        daemon._start_device_watcher()
+
+        cdll.assert_not_called()
+
+    @pytest.mark.skipif(
+        not hasattr(daemon.sys, "platform") or daemon.sys.platform != "darwin",
+        reason="macOS-only behaviour",
+    )
+    def test_disabled_when_coreaudio_unavailable(self, mocker, caplog):
+        """If CDLL fails to load CoreAudio (unusual on real macOS but possible
+        in stripped environments), the watcher should bail without raising."""
+        import logging
+
+        mocker.patch.object(daemon.ctypes, "CDLL", side_effect=OSError("no coreaudio"))
+        with caplog.at_level(logging.DEBUG, logger="stackvox.daemon"):
+            daemon._start_device_watcher()  # must not raise
+        assert any("CoreAudio unavailable" in r.message for r in caplog.records)

stackvox-0.3.1/tests/test_engine.py

@@ -0,0 +1,241 @@
+"""Engine tests — no real model load, no audio device.
+
+We mock at two boundaries: `Kokoro` (so `Stackvox.__init__` doesn't pull the
+model) and `sounddevice` (so `speak()` doesn't try to talk to PortAudio).
+This lets us verify call-shape and side effects without any of the heavy
+runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import numpy as np
+import pytest
+
+from stackvox import engine
+
+
+@pytest.fixture
+def fake_ensure_models(mocker, tmp_path):
+    """Short-circuit _ensure_models so Stackvox.__init__ skips the download."""
+    model = tmp_path / "kokoro.onnx"
+    voices = tmp_path / "voices.bin"
+    model.touch()
+    voices.touch()
+    return mocker.patch.object(engine, "_ensure_models", return_value=(model, voices))
+
+
+@pytest.fixture
+def fake_kokoro(mocker, fake_ensure_models):
+    """Mock Kokoro on top of fake_ensure_models — most tests want both."""
+    return mocker.patch.object(engine, "Kokoro")
+
+
+@pytest.fixture
+def fake_audio(mocker):
+    """Mock the sounddevice surface used by Stackvox."""
+    mocker.patch.object(engine.sd, "play")
+    mocker.patch.object(engine.sd, "wait")
+    mocker.patch.object(engine.sd, "stop")
+
+
+@pytest.fixture(autouse=True)
+def reset_default():
+    """Each test starts with no module-level singleton."""
+    engine._default = None
+    yield
+    engine._default = None
+
+
+class TestStackvoxInit:
+    def test_stores_voice_speed_lang(self, fake_kokoro):
+        tts = engine.Stackvox(voice="bf_emma", speed=1.2, lang="en-gb")
+        assert tts.voice == "bf_emma"
+        assert tts.speed == 1.2
+        assert tts.lang == "en-gb"
+
+    def test_uses_custom_cache_dir(self, fake_kokoro, fake_ensure_models, tmp_path):
+        custom = tmp_path / "custom-cache"
+        engine.Stackvox(cache_dir=custom)
+        fake_ensure_models.assert_called_once_with(custom)
+
+    def test_falls_back_to_default_cache_dir(self, fake_kokoro, fake_ensure_models, mocker, tmp_path):
+        default = tmp_path / "default"
+        mocker.patch.object(engine, "_default_cache_dir", return_value=default)
+        engine.Stackvox()
+        fake_ensure_models.assert_called_once_with(default)
+
+
+class TestSynthesize:
+    def test_passes_engine_defaults_to_kokoro(self, fake_kokoro):
+        samples = np.zeros(10, dtype=np.float32)
+        fake_kokoro.return_value.create.return_value = (samples, 24000)
+
+        tts = engine.Stackvox(voice="af_sarah", speed=1.0, lang="en-us")
+        result_samples, result_sr = tts.synthesize("hi")
+
+        fake_kokoro.return_value.create.assert_called_once_with(
+            "hi", voice="af_sarah", speed=1.0, lang="en-us"
+        )
+        assert result_sr == 24000
+        assert np.array_equal(result_samples, samples)
+
+    def test_per_call_overrides_take_priority(self, fake_kokoro):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        tts = engine.Stackvox(voice="af_sarah", speed=1.0, lang="en-us")
+        tts.synthesize("hi", voice="bf_emma", speed=1.5, lang="en-gb")
+        fake_kokoro.return_value.create.assert_called_once_with(
+            "hi", voice="bf_emma", speed=1.5, lang="en-gb"
+        )
+
+    def test_speed_zero_override_is_respected(self, fake_kokoro):
+        """speed=0 is falsy but a valid override; ensure it's not silently dropped."""
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        tts = engine.Stackvox(speed=1.0)
+        tts.synthesize("hi", speed=0.5)
+        kwargs = fake_kokoro.return_value.create.call_args.kwargs
+        assert kwargs["speed"] == 0.5
+
+
+class TestSpeak:
+    def test_blocking_calls_play_and_wait(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        tts = engine.Stackvox()
+        tts.speak("hi")
+        engine.sd.play.assert_called_once()
+        engine.sd.wait.assert_called_once()
+
+    def test_non_blocking_skips_wait(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        tts = engine.Stackvox()
+        tts.speak("hi", blocking=False)
+        engine.sd.play.assert_called_once()
+        engine.sd.wait.assert_not_called()
+
+    def test_stop_calls_sounddevice_stop(self, fake_kokoro, fake_audio):
+        engine.Stackvox().stop()
+        engine.sd.stop.assert_called_once()
+
+
+class TestVoices:
+    def test_returns_sorted_voice_ids(self, fake_kokoro):
+        fake_kokoro.return_value.get_voices.return_value = ["bf_emma", "af_sarah", "am_adam"]
+        tts = engine.Stackvox()
+        assert tts.voices() == ["af_sarah", "am_adam", "bf_emma"]
+
+
+class TestSpeakSequence:
+    def test_empty_lines_returns_early(self, fake_kokoro, fake_audio):
+        engine.Stackvox().speak_sequence([])
+        engine.sd.play.assert_not_called()
+
+    def test_concatenates_segments_with_optional_gap(self, fake_kokoro, fake_audio):
+        a = np.array([1.0, 1.0, 1.0], dtype=np.float32)
+        b = np.array([2.0, 2.0], dtype=np.float32)
+        fake_kokoro.return_value.create.side_effect = [(a, 100), (b, 100)]
+
+        tts = engine.Stackvox()
+        tts.speak_sequence([{"text": "first"}, {"text": "second"}], gap_seconds=0.05, concurrent=False)
+
+        played = engine.sd.play.call_args.args[0]
+        # Length: 3 + (100 * 0.05) silence + 2 = 10 samples.
+        assert len(played) == 3 + 5 + 2
+        # First 3 samples are `a`, last 2 are `b`, middle 5 are silence.
+        np.testing.assert_array_equal(played[:3], a)
+        np.testing.assert_array_equal(played[-2:], b)
+        np.testing.assert_array_equal(played[3:8], np.zeros(5, dtype=np.float32))
+
+
+class TestModuleLevelHelpers:
+    def test_speak_reuses_module_singleton(self, fake_kokoro, fake_audio):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        engine.speak("first")
+        engine.speak("second")
+        # Stackvox class only instantiated once → Kokoro only constructed once.
+        assert fake_kokoro.call_count == 1
+
+    def test_synthesize_reuses_module_singleton(self, fake_kokoro):
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        engine.synthesize("first")
+        engine.synthesize("second")
+        assert fake_kokoro.call_count == 1
+
+    def test_get_default_is_thread_safe(self, fake_kokoro):
+        """Concurrent first calls must not double-instantiate Stackvox.
+
+        Without the lock around _get_default, multiple threads calling
+        speak()/synthesize() at process start can both observe `_default is
+        None` and each construct a Stackvox (each loading the 340 MB model).
+        """
+        fake_kokoro.return_value.create.return_value = (np.zeros(10), 24000)
+        barrier = threading.Barrier(8)
+
+        def race():
+            barrier.wait()
+            engine._get_default()
+
+        threads = [threading.Thread(target=race) for _ in range(8)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert fake_kokoro.call_count == 1
+
+
+class TestDownloadProgress:
+    def test_reporthook_prints_percentage_when_size_known(self, mocker, capsys, tmp_path):
+        """The hook should print updating progress lines while downloading."""
+        captured_hook = {}
+
+        def fake_urlretrieve(url, dest, reporthook=None):
+            captured_hook["fn"] = reporthook
+            # Simulate three chunks of a 1000-byte download.
+            if reporthook:
+                reporthook(0, 100, 1000)
+                reporthook(5, 100, 1000)
+                reporthook(10, 100, 1000)
+
+        mocker.patch.object(engine.urllib.request, "urlretrieve", side_effect=fake_urlretrieve)
+        engine._download_with_progress("http://example/m.bin", tmp_path / "m.bin")
+
+        err = capsys.readouterr().err
+        assert "downloading m.bin" in err
+        assert "100%" in err
+
+    def test_unknown_size_does_not_print(self, mocker, capsys, tmp_path):
+        """totalsize <= 0 means Content-Length absent; hook should be a no-op."""
+
+        def fake_urlretrieve(url, dest, reporthook=None):
+            if reporthook:
+                reporthook(0, 100, -1)
+
+        mocker.patch.object(engine.urllib.request, "urlretrieve", side_effect=fake_urlretrieve)
+        engine._download_with_progress("http://example/m.bin", tmp_path / "m.bin")
+
+        # No percentage should have been emitted because total size was unknown.
+        assert "downloading" not in capsys.readouterr().err
+
+
+class TestEnsureModels:
+    def test_skips_files_that_already_exist(self, mocker, tmp_path):
+        download = mocker.patch.object(engine, "_download_with_progress")
+        (tmp_path / "kokoro-v1.0.onnx").touch()
+        (tmp_path / "voices-v1.0.bin").touch()
+
+        engine._ensure_models(tmp_path)
+
+        download.assert_not_called()
+
+    def test_downloads_only_missing_files(self, mocker, tmp_path):
+        download = mocker.patch.object(engine, "_download_with_progress")
+        # Only the model exists; voices needs downloading.
+        (tmp_path / "kokoro-v1.0.onnx").touch()
+
+        engine._ensure_models(tmp_path)
+
+        # Exactly one download, for the voices file.
+        assert download.call_count == 1
+        url_arg, dest_arg = download.call_args.args
+        assert dest_arg.name == "voices-v1.0.bin"

stackvox-0.3.0/tests/test_cli.py

@@ -1,91 +0,0 @@
-"""CLI argument parsing — no engine loaded, no audio played."""
-
-from __future__ import annotations
-
-import io
-
-import pytest
-
-from stackvox import cli
-
-
-@pytest.fixture(autouse=True)
-def _stdin_is_a_tty(mocker):
-    """Default tests to a TTY stdin so the new piped-stdin shortcut is off.
-
-    Tests that exercise the piped path opt in by patching isatty to False
-    and providing a real stdin StringIO.
-    """
-    mocker.patch.object(cli.sys.stdin, "isatty", return_value=True)
-
-
-def test_bare_text_routes_to_speak(mocker):
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello world"])
-    assert cli.main() == 0
-    args = speak.call_args.args[0]
-    assert args.cmd == "speak"
-    assert args.text == "hello world"
-
-
-def test_speak_subcommand_parses_voice_and_speed(mocker):
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "speak", "--voice", "bf_emma", "--speed", "1.2", "hi"])
-    assert cli.main() == 0
-    args = speak.call_args.args[0]
-    assert args.voice == "bf_emma"
-    assert args.speed == pytest.approx(1.2)
-    assert args.text == "hi"
-
-
-def test_no_subcommand_prints_help(mocker, capsys):
-    mocker.patch.object(cli.sys, "argv", ["stackvox"])
-    assert cli.main() == 1
-    captured = capsys.readouterr()
-    assert "usage: stackvox" in captured.out
-
-
-def test_unknown_subcommand_treated_as_speak_text(mocker):
-    """`stackvox foo` is treated as `stackvox speak foo`, not an error."""
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "hello"])
-    cli.main()
-    assert speak.call_args.args[0].text == "hello"
-
-
-def test_piped_stdin_with_no_args_routes_to_speak(mocker):
-    """`echo hi | stackvox` should default to speak."""
-    speak = mocker.patch.object(cli, "_cmd_speak", return_value=0)
-    mocker.patch.object(cli.sys, "argv", ["stackvox"])
-    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
-    mocker.patch.object(cli.sys, "stdin", io.StringIO("hello from stdin\n"))
-    assert cli.main() == 0
-    assert speak.call_args.args[0].cmd == "speak"
-
-
-def test_read_text_prefers_file_then_positional_then_stdin(mocker, tmp_path):
-    """_read_text precedence: --file > positional > piped stdin."""
-    file_arg = tmp_path / "src.txt"
-    file_arg.write_text("from-file", encoding="utf-8")
-
-    # Both --file and positional present → file wins.
-    args = mocker.MagicMock(file=file_arg, text="from-positional")
-    assert cli._read_text(args) == "from-file"
-
-    # No --file, positional present → positional wins.
-    args = mocker.MagicMock(file=None, text="from-positional")
-    assert cli._read_text(args) == "from-positional"
-
-    # No --file, no positional, stdin piped → stdin wins.
-    mocker.patch.object(cli.sys.stdin, "isatty", return_value=False)
-    mocker.patch.object(cli.sys, "stdin", io.StringIO("from-stdin"))
-    args = mocker.MagicMock(file=None, text=None)
-    assert cli._read_text(args) == "from-stdin"
-
-
-def test_completion_bash_emits_complete_script(mocker, capsys):
-    mocker.patch.object(cli.sys, "argv", ["stackvox", "completion", "bash"])
-    assert cli.main() == 0
-    captured = capsys.readouterr()
-    assert "_stackvox_completion()" in captured.out
-    assert "complete -F _stackvox_completion stackvox" in captured.out