fow-cli 0.3.1__tar.gz → 0.4.0__tar.gz

{fow_cli-0.3.1 → fow_cli-0.4.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to Fly on the Wall are documented here.
 
+## [0.4.0] - 2026-07-02
+
+### Added
+
+- Added `fow service` commands for installing and managing the Linux systemd user watch service.
+- Added a generated `service.env` placeholder for background service environment variables.
+
+### Changed
+
+- Made the Linux service install paths respect `XDG_CONFIG_HOME`.
+
 ## [0.3.1] - 2026-06-15
 
 ### Fixed

{fow_cli-0.3.1 → fow_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fow-cli
-Version: 0.3.1
+Version: 0.4.0
 Summary: Personal CLI note-taker for turning meeting audio into cleaned meeting manuscripts.
 Project-URL: Repository, https://github.com/henriksvensson/fly-on-the-wall
 License-Expression: MIT
@@ -329,6 +329,36 @@ fow watch run
 
 The watcher tolerates missing/remounted folders and uses periodic scans because cloud/removable mounts may not emit reliable filesystem events.
 
+### Background Service
+
+On Linux with systemd user services, install the watcher as a background service:
+
+```bash
+fow service install
+```
+
+This writes `fow-watch.service` under the user systemd config directory, creates a non-overwriting placeholder `service.env` next to the app config, and reloads the user systemd manager. By default those paths are `~/.config/systemd/user/fow-watch.service` and `~/.config/fly-on-the-wall/service.env`; if `XDG_CONFIG_HOME` is set, the service installer uses that config root instead. It does not enable or start the service by default.
+
+Enable it for future user sessions and start it now:
+
+```bash
+fow service install --enable --start
+```
+
+Starting from install refuses to run if no enabled watch folders are configured, because `fow watch run` would exit immediately. Add a folder first with `fow watch folders add <path>`, or pass `--force-start` if you intentionally want to start anyway.
+
+Useful service commands:
+
+```bash
+fow service status
+fow service logs
+fow service restart
+fow service stop
+fow service uninstall
+```
+
+Optional service environment variables can be placed in the generated `service.env` file. The file is created as a commented placeholder during service install and is not overwritten by later installs.
+
 ## Publishing To Obsidian
 
 Publishing is separate from internal exports.
@@ -446,6 +476,14 @@ Run tests:
 uv run pytest
 ```
 
+When developing a checkout while the background service is installed, stop the service first so it does not process files with the installed command:
+
+```bash
+fow service stop
+uv run fow
+fow service start
+```
+
 Run lint and formatting checks:
 
 ```bash

{fow_cli-0.3.1 → fow_cli-0.4.0}/README.md

@@ -299,6 +299,36 @@ fow watch run
 
 The watcher tolerates missing/remounted folders and uses periodic scans because cloud/removable mounts may not emit reliable filesystem events.
 
+### Background Service
+
+On Linux with systemd user services, install the watcher as a background service:
+
+```bash
+fow service install
+```
+
+This writes `fow-watch.service` under the user systemd config directory, creates a non-overwriting placeholder `service.env` next to the app config, and reloads the user systemd manager. By default those paths are `~/.config/systemd/user/fow-watch.service` and `~/.config/fly-on-the-wall/service.env`; if `XDG_CONFIG_HOME` is set, the service installer uses that config root instead. It does not enable or start the service by default.
+
+Enable it for future user sessions and start it now:
+
+```bash
+fow service install --enable --start
+```
+
+Starting from install refuses to run if no enabled watch folders are configured, because `fow watch run` would exit immediately. Add a folder first with `fow watch folders add <path>`, or pass `--force-start` if you intentionally want to start anyway.
+
+Useful service commands:
+
+```bash
+fow service status
+fow service logs
+fow service restart
+fow service stop
+fow service uninstall
+```
+
+Optional service environment variables can be placed in the generated `service.env` file. The file is created as a commented placeholder during service install and is not overwritten by later installs.
+
 ## Publishing To Obsidian
 
 Publishing is separate from internal exports.
@@ -416,6 +446,14 @@ Run tests:
 uv run pytest
 ```
 
+When developing a checkout while the background service is installed, stop the service first so it does not process files with the installed command:
+
+```bash
+fow service stop
+uv run fow
+fow service start
+```
+
 Run lint and formatting checks:
 
 ```bash

{fow_cli-0.3.1 → fow_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fow-cli"
-version = "0.3.1"
+version = "0.4.0"
 description = "Personal CLI note-taker for turning meeting audio into cleaned meeting manuscripts."
 readme = "README.md"
 requires-python = ">=3.12"

{fow_cli-0.3.1 → fow_cli-0.4.0}/src/fly_on_the_wall/__init__.py

@@ -1,3 +1,3 @@
 """Fly on the Wall CLI application."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{fow_cli-0.3.1 → fow_cli-0.4.0}/src/fly_on_the_wall/cli.py

@@ -11,6 +11,7 @@ from fly_on_the_wall import __version__
 from fly_on_the_wall.cli_costs import costs_app
 from fly_on_the_wall.cli_glossary import glossary_app
 from fly_on_the_wall.cli_publish import publish_app
+from fly_on_the_wall.cli_service import service_app
 from fly_on_the_wall.cli_speaker_review import speakers_review
 from fly_on_the_wall.cli_watch import watch_app
 from fly_on_the_wall.config import load_config
@@ -81,6 +82,7 @@ app.add_typer(refresh_app, name="refresh")
 app.add_typer(secrets_app, name="secrets")
 app.add_typer(glossary_app, name="glossary")
 app.add_typer(watch_app, name="watch")
+app.add_typer(service_app, name="service")
 app.add_typer(publish_app, name="publish")
 app.add_typer(costs_app, name="costs")
 console = Console()

fow_cli-0.4.0/src/fly_on_the_wall/cli_service.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from fly_on_the_wall.config import config_dir
+from fly_on_the_wall.db import database
+from fly_on_the_wall.watch import list_watch_folders
+
+SERVICE_NAME = "fow-watch.service"
+ENV_FILE_NAME = "service.env"
+ENV_FILE_TEMPLATE = """# Optional environment variables for fow-watch.service.
+# Use this if your background service cannot access API keys from the OS keyring.
+# ELEVENLABS_API_KEY=
+# OPENAI_API_KEY=
+"""
+
+console = Console()
+service_app = typer.Typer(help="Manage the background watch service.", no_args_is_help=True)
+
+
+@service_app.command("install")
+def service_install(
+    enable: Annotated[
+        bool,
+        typer.Option("--enable", help="Enable the service to start when your user session starts. Default: disabled."),
+    ] = False,
+    start: Annotated[
+        bool,
+        typer.Option("--start", help="Start the service after installing it. Default: do not start."),
+    ] = False,
+    force_start: Annotated[
+        bool,
+        typer.Option("--force-start", help="Start even when no enabled watch folders are configured."),
+    ] = False,
+) -> None:
+    """Install the watch service for the current user."""
+    _ensure_supported_platform()
+    if start and not force_start:
+        _ensure_enabled_watch_folders()
+
+    unit_path = _unit_file_path()
+    unit_path.parent.mkdir(parents=True, exist_ok=True)
+    unit_path.write_text(render_unit(_resolve_fow_executable(), _env_file_path()), encoding="utf-8")
+    console.print(f"Installed service unit: {unit_path}")
+    _ensure_env_file()
+    _run_or_exit(_systemctl("daemon-reload"))
+
+    if enable:
+        _run_or_exit(_systemctl("enable", SERVICE_NAME))
+        console.print("Service enabled for future user sessions.")
+    if start:
+        _run_or_exit(_systemctl("start", SERVICE_NAME))
+        console.print("Service started.")
+
+
+@service_app.command("uninstall")
+def service_uninstall() -> None:
+    """Remove the watch service for the current user."""
+    _ensure_supported_platform()
+    unit_path = _unit_file_path()
+    if unit_path.exists():
+        _run_or_exit(_systemctl("disable", "--now", SERVICE_NAME))
+        unit_path.unlink()
+        console.print(f"Removed service unit: {unit_path}")
+    else:
+        console.print(f"Service unit was not installed: {unit_path}")
+    _run_or_exit(_systemctl("daemon-reload"))
+
+
+@service_app.command("start")
+def service_start(
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Start even when no enabled watch folders are configured."),
+    ] = False,
+) -> None:
+    """Start the watch service."""
+    _run_watch_service_action("start", force)
+
+
+@service_app.command("stop")
+def service_stop() -> None:
+    """Stop the watch service."""
+    _ensure_supported_platform()
+    _run_or_exit(_systemctl("stop", SERVICE_NAME))
+
+
+@service_app.command("restart")
+def service_restart(
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Restart even when no enabled watch folders are configured."),
+    ] = False,
+) -> None:
+    """Restart the watch service."""
+    _run_watch_service_action("restart", force)
+
+
+def _run_watch_service_action(action: str, force: bool) -> None:
+    _ensure_supported_platform()
+    if not force:
+        _ensure_enabled_watch_folders()
+    _run_or_exit(_systemctl(action, SERVICE_NAME))
+
+
+@service_app.command("status")
+def service_status() -> None:
+    """Show watch service status."""
+    _ensure_supported_platform()
+    _run_or_exit(["systemctl", "--user", "--no-pager", "status", SERVICE_NAME])
+
+
+@service_app.command("logs")
+def service_logs(
+    lines: Annotated[int, typer.Option("--lines", "-n", min=1, help="Number of recent log lines to show.")] = 100,
+    follow: Annotated[bool, typer.Option("--follow", "-f", help="Follow logs until interrupted.")] = False,
+) -> None:
+    """Show watch service logs."""
+    _ensure_supported_platform()
+    command = ["journalctl", "--user", "-u", SERVICE_NAME, "-n", str(lines)]
+    if follow:
+        command.append("--follow")
+    else:
+        command.append("--no-pager")
+    _run_or_exit(command)
+
+
+@service_app.command("print-unit")
+def service_print_unit() -> None:
+    """Print the generated service unit without installing it."""
+    _ensure_supported_platform()
+    console.print(render_unit(_resolve_fow_executable(), _env_file_path()), end="", markup=False)
+
+
+def render_unit(fow_executable: Path, env_file_path: Path) -> str:
+    if not fow_executable.is_absolute():
+        raise ValueError("fow executable path must be absolute")
+    if not env_file_path.is_absolute():
+        raise ValueError("service environment file path must be absolute")
+    return f"""[Unit]
+Description=Fly on the Wall watch service
+After=default.target
+
+[Service]
+Type=simple
+Environment=PYTHONUNBUFFERED=1
+EnvironmentFile=-{_systemd_quote(env_file_path)}
+ExecStart={_systemd_quote(fow_executable)} watch run
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _ensure_supported_platform() -> None:
+    if sys.platform != "linux":
+        console.print("Unsupported platform: fow service currently supports Linux systemd user services only.")
+        raise typer.Exit(code=1)
+
+
+def _ensure_enabled_watch_folders() -> None:
+    if _has_enabled_watch_folder():
+        return
+    console.print("No enabled watch folders configured; the watch service would exit immediately.")
+    console.print("Add one with: fow watch folders add <path>")
+    console.print("To start anyway, pass --force or --force-start.")
+    raise typer.Exit(code=1)
+
+
+def _has_enabled_watch_folder() -> bool:
+    with database() as connection:
+        return any(folder.enabled for folder in list_watch_folders(connection))
+
+
+def _resolve_fow_executable() -> Path:
+    executable = shutil.which("fow")
+    if executable is None:
+        console.print("Could not find the fow executable on PATH.")
+        raise typer.Exit(code=1)
+    return Path(executable).resolve()
+
+
+def _unit_file_path() -> Path:
+    return config_dir().parent / "systemd" / "user" / SERVICE_NAME
+
+
+def _env_file_path() -> Path:
+    return config_dir() / ENV_FILE_NAME
+
+
+def _ensure_env_file() -> None:
+    env_path = _env_file_path()
+    if env_path.exists():
+        console.print(f"Service environment file already exists: {env_path}")
+        return
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+    env_path.write_text(ENV_FILE_TEMPLATE, encoding="utf-8")
+    env_path.chmod(0o600)
+    console.print(f"Created service environment placeholder: {env_path}")
+
+
+def _systemctl(*arguments: str) -> list[str]:
+    return ["systemctl", "--user", *arguments]
+
+
+def _run_or_exit(command: Sequence[str]) -> None:
+    try:
+        _run_command(command)
+    except FileNotFoundError as exc:
+        console.print(f"Required command not found: {command[0]}")
+        raise typer.Exit(code=1) from exc
+    except subprocess.CalledProcessError as exc:
+        console.print(f"Command failed with exit code {exc.returncode}: {' '.join(command)}")
+        raise typer.Exit(code=exc.returncode) from exc
+
+
+def _run_command(command: Sequence[str]) -> None:
+    subprocess.run(command, check=True)
+
+
+def _systemd_quote(path: Path) -> str:
+    text = str(path)
+    if not any(character.isspace() for character in text) and '"' not in text:
+        return text
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'

{fow_cli-0.3.1 → fow_cli-0.4.0}/src/fly_on_the_wall/glossary.py

@@ -31,7 +31,10 @@ def create_glossary_term(connection: Connection, term: str, description: str | N
             """,
             (term_id, normalized, normalized_description),
         )
-    return get_glossary_term(connection, normalized)  # type: ignore[return-value]
+    created = get_glossary_term(connection, normalized)
+    if created is None:
+        raise RuntimeError(f"Created glossary term was not found: {normalized}")
+    return created
 
 
 def get_glossary_term(connection: Connection, term_or_id: str) -> GlossaryTerm | None:
@@ -80,7 +83,10 @@ def update_glossary_term(
             """,
             (updated_term, updated_description, int(updated_enabled), existing.id),
         )
-    return get_glossary_term(connection, existing.id)  # type: ignore[return-value]
+    updated = get_glossary_term(connection, existing.id)
+    if updated is None:
+        raise RuntimeError(f"Updated glossary term was not found: {existing.id}")
+    return updated
 
 
 def remove_glossary_term(connection: Connection, term_or_id: str) -> bool: