instruktai-python-logger 0.5.1__tar.gz → 0.6.1__tar.gz

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.5.1
+Version: 0.6.1
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -58,8 +58,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -70,17 +70,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/README.md

@@ -51,8 +51,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -63,17 +63,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/instrukt_ai_logging/cli.py

@@ -192,7 +192,9 @@ def main() -> None:
         action="version",
         version=f"%(prog)s {__version__}",
     )
-    parser.add_argument("app", help="App/service name (folder under /var/log/instrukt-ai/)")
+    parser.add_argument(
+        "app", help="App/service name (folder under $XDG_STATE_HOME/instrukt-ai/, fallback ~/.local/state)"
+    )
     parser.add_argument("--since", default="10m", help="Time window (e.g. 10m, 2h, 1d). Default: 10m")
     parser.add_argument(
         "-f",

instruktai_python_logger-0.6.1/instrukt_ai_logging/install.py

@@ -0,0 +1,232 @@
+"""Ensure user-space log rotation assets for InstruktAI logs.
+
+Rotation runs entirely as the producing user: a per-user rotation conf plus a
+per-user scheduler (launchd LaunchAgent on macOS, systemd user timer on
+Linux). No `/etc` configuration, no sudo, no system rotation daemon ever
+touches these files, so root-owned recreated logs are structurally
+unexpressible.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_NEWSYSLOG_BIN = "/usr/sbin/newsyslog"
+_LAUNCHD_LABEL = "ai.instrukt.log-rotate"
+_SYSTEMD_UNIT_NAME = "instrukt-ai-logrotate"
+
+
+def _state_home_root() -> Path:
+    """Resolve `$XDG_STATE_HOME/instrukt-ai` (fallback `~/.local/state`)."""
+    xdg_state_home = os.getenv("XDG_STATE_HOME")
+    state_home = Path(xdg_state_home).expanduser() if xdg_state_home else Path("~/.local/state").expanduser()
+    return state_home / "instrukt-ai"
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".config" / "instrukt-ai"
+
+
+def _newsyslog_conf_path() -> Path:
+    return _config_dir() / "newsyslog.conf"
+
+
+def _launchd_plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{_LAUNCHD_LABEL}.plist"
+
+
+def _logrotate_conf_path() -> Path:
+    return _config_dir() / "logrotate.conf"
+
+
+def _systemd_user_dir() -> Path:
+    return Path.home() / ".config" / "systemd" / "user"
+
+
+def _systemd_service_path() -> Path:
+    return _systemd_user_dir() / f"{_SYSTEMD_UNIT_NAME}.service"
+
+
+def _systemd_timer_path() -> Path:
+    return _systemd_user_dir() / f"{_SYSTEMD_UNIT_NAME}.timer"
+
+
+def _newsyslog_conf(log_root: Path) -> str:
+    """One glob line: 5 gzipped archives at 50 MB, evaluated at rotation time (G flag)."""
+    return f"{log_root}/*/*.log  640  5  50000  *  ZG\n"
+
+
+def _launchd_plist(conf_path: Path) -> str:
+    # newsyslog refuses to run at all unless invoked as root or with -r; our
+    # conf lines carry no pid/signal field, so -r's "won't HUP syslogd" caveat
+    # doesn't apply here.
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{_LAUNCHD_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{_NEWSYSLOG_BIN}</string>
+        <string>-r</string>
+        <string>-f</string>
+        <string>{conf_path}</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>1800</integer>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+"""
+
+
+def _logrotate_conf(log_root: Path) -> str:
+    """Default move+create rotation; WatchedFileHandler reopens on inode change."""
+    return f"""{log_root}/*/*.log {{
+    size 50M
+    rotate 5
+    compress
+    delaycompress
+    missingok
+    notifempty
+}}
+"""
+
+
+def _systemd_service(conf_path: Path, state_file: Path) -> str:
+    return f"""[Unit]
+Description=InstruktAI log rotation
+
+[Service]
+Type=oneshot
+ExecStart=logrotate --state {state_file} {conf_path}
+"""
+
+
+def _systemd_timer() -> str:
+    return """[Unit]
+Description=InstruktAI log rotation timer
+
+[Timer]
+OnCalendar=*:0/30
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+"""
+
+
+def _write_if_changed(path: Path, content: str) -> None:
+    if path.exists() and path.read_text(encoding="utf-8") == content:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+_SCHEDULER_COMMAND_TIMEOUT_S = 10.0
+
+
+def _run_scheduler_command(args: list[str]) -> subprocess.CompletedProcess[str]:
+    # No Python API wraps launchd's per-user service bus or the systemd user
+    # D-Bus/session manager; shell out to launchctl/systemctl. Routed through
+    # this wrapper (rather than calling subprocess.run directly) so tests can
+    # fake just this boundary without patching the shared subprocess module.
+    # A bounded timeout and closed stdin keep an unreachable service bus (no
+    # GUI/user session, e.g. a headless CI runner) from hanging the caller
+    # forever instead of failing fast.
+    return subprocess.run(
+        args,
+        capture_output=True,
+        text=True,
+        stdin=subprocess.DEVNULL,
+        timeout=_SCHEDULER_COMMAND_TIMEOUT_S,
+    )
+
+
+def _ensure_launchd_loaded(plist_path: Path) -> list[str]:
+    uid = os.getuid()
+    try:
+        result = _run_scheduler_command(["launchctl", "bootstrap", f"gui/{uid}", str(plist_path)])
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"launchctl bootstrap failed to run: {exc}"]
+
+    if result.returncode != 0 and "already bootstrapped" not in result.stderr.lower():
+        return [f"launchctl bootstrap failed: {result.stderr.strip()}"]
+    return []
+
+
+def _ensure_systemd_loaded() -> list[str]:
+    try:
+        reload_result = _run_scheduler_command(["systemctl", "--user", "daemon-reload"])
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"systemctl daemon-reload failed to run: {exc}"]
+
+    if reload_result.returncode != 0:
+        return [f"systemctl daemon-reload failed: {reload_result.stderr.strip()}"]
+
+    try:
+        enable_result = _run_scheduler_command(
+            ["systemctl", "--user", "enable", "--now", f"{_SYSTEMD_UNIT_NAME}.timer"]
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [f"systemctl enable failed to run: {exc}"]
+
+    if enable_result.returncode != 0:
+        return [f"systemctl enable failed: {enable_result.stderr.strip()}"]
+    return []
+
+
+def ensure_rotation() -> list[str]:
+    """Idempotently ensure user-space rotation assets exist and are scheduled.
+
+    Never raises. Returns human-readable problem strings for anything that
+    could not be resolved; an empty list means rotation is healthy.
+    """
+    log_root = _state_home_root()
+
+    if sys.platform == "darwin":
+        conf_path = _newsyslog_conf_path()
+        plist_path = _launchd_plist_path()
+        try:
+            _write_if_changed(conf_path, _newsyslog_conf(log_root))
+            _write_if_changed(plist_path, _launchd_plist(conf_path))
+        except OSError as exc:
+            return [f"could not write rotation assets: {exc}"]
+        return _ensure_launchd_loaded(plist_path)
+
+    conf_path = _logrotate_conf_path()
+    service_path = _systemd_service_path()
+    timer_path = _systemd_timer_path()
+    state_file = log_root / "logrotate.state"
+    try:
+        _write_if_changed(conf_path, _logrotate_conf(log_root))
+        _write_if_changed(service_path, _systemd_service(conf_path, state_file))
+        _write_if_changed(timer_path, _systemd_timer())
+    except OSError as exc:
+        return [f"could not write rotation assets: {exc}"]
+    return _ensure_systemd_loaded()
+
+
+def main() -> None:
+    log_root = _state_home_root()
+    sys.stdout.write(f"log root: {log_root}\n")
+    sys.stdout.write(
+        f"rotation conf: {_newsyslog_conf_path() if sys.platform == 'darwin' else _logrotate_conf_path()}\n"
+    )
+    sys.stdout.write(f"scheduler: {_launchd_plist_path() if sys.platform == 'darwin' else _systemd_timer_path()}\n")
+
+    problems = ensure_rotation()
+    if problems:
+        for problem in problems:
+            sys.stdout.write(f"problem: {problem}\n")
+        raise SystemExit(1)
+    sys.stdout.write("status: healthy\n")
+
+
+if __name__ == "__main__":
+    main()

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/instrukt_ai_logging/logging.py

@@ -11,6 +11,8 @@ from logging.handlers import WatchedFileHandler
 from pathlib import Path
 from typing import Any, Protocol, cast, runtime_checkable
 
+from instrukt_ai_logging.install import ensure_rotation
+
 # Standard logging levels are: NOTSET=0, DEBUG=10, INFO=20, WARNING=30, ERROR=40, CRITICAL=50
 TRACE: int = 5
 logging.addLevelName(TRACE, "TRACE")
@@ -345,10 +347,9 @@ class LoggingContract:
 
 def _resolve_log_root(app_name: str) -> Path:
     fs_app_name = _normalize_app_name(app_name)
-    override = os.getenv("INSTRUKT_AI_LOG_ROOT")
-    if override:
-        return Path(override).expanduser() / fs_app_name
-    return Path("/var/log/instrukt-ai") / fs_app_name
+    xdg_state_home = os.getenv("XDG_STATE_HOME")
+    state_home = Path(xdg_state_home).expanduser() if xdg_state_home else Path("~/.local/state").expanduser()
+    return state_home / "instrukt-ai" / fs_app_name
 
 
 def _ensure_log_dir(log_dir: Path) -> None:
@@ -454,18 +455,19 @@ def configure_logging(
     root_level = third_party_level if not spotlight else logging.WARNING
 
     log_dir = _resolve_log_root(app_name)
-    _ensure_log_dir(log_dir)
-
     log_file = log_dir / log_filename
 
     formatter = LogfmtFormatter(max_message_chars=max_message_chars)
+    selector = _ThirdPartySelectorFilter(app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight))
+
+    # Logging is an essential subsystem: an unwritable log dir/file raises here
+    # and the host process must not start blind. No degraded/fallback mode.
+    _ensure_log_dir(log_dir)
+    handler: logging.Handler = WatchedFileHandler(log_file, encoding="utf-8")
 
-    handler = WatchedFileHandler(log_file, encoding="utf-8")
     handler.setLevel(logging.NOTSET)
     handler.setFormatter(formatter)
-    handler.addFilter(
-        _ThirdPartySelectorFilter(app_logger_prefix=app_logger_prefix, spotlight_prefixes=tuple(spotlight))
-    )
+    handler.addFilter(selector)
 
     # Configure root.
     logging.root.handlers = [handler]
@@ -484,6 +486,11 @@ def configure_logging(
     for prefix in muted:
         logging.getLogger(prefix).setLevel(logging.WARNING)
 
+    # Rotation bootstrap is not logging: a failure here is surfaced as a
+    # warning, never fatal to an already-working log file.
+    for problem in ensure_rotation():
+        logging.getLogger(app_logger_prefix).warning("log rotation ensure problem: %s", problem)
+
     return log_file
 
 

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/instruktai_python_logger.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instruktai-python-logger
-Version: 0.5.1
+Version: 0.6.1
 Summary: Centralized logging utilities for Python services.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -58,8 +58,8 @@ configure_logging("teleclaude", source="cron")        # → cron.log
 ```
 
 The `.log` extension is always appended; pass the bare stem. Files all live
-under `/var/log/instrukt-ai/{app}/`. The CLI merges them transparently
-(see below).
+under `$XDG_STATE_HOME/instrukt-ai/{app}/` (fallback `~/.local/state`). The CLI
+merges them transparently (see below).
 
 ## Environment variables (contract)
 
@@ -70,17 +70,32 @@ Per-app prefix model (example uses `TELECLAUDE_`):
 - `TELECLAUDE_THIRD_PARTY_LOGGERS` (comma-separated logger prefixes to spotlight, e.g. `httpcore,telegram`)
 - `TELECLAUDE_MUTED_LOGGERS` (comma-separated logger prefixes to force to WARNING+, e.g. `teleclaude.cli.tui`)
 
-Global:
-
-- `INSTRUKT_AI_LOG_ROOT` (optional log root override)
+These four per-app variables are the entire contract. There is no log-root
+override variable — the location is a fixed rule (see below).
 
 ## Log location (contract)
 
-Default target:
+Every app's logs live at the same predictable, prose-citable location on both
+macOS and Linux:
+
+- `$XDG_STATE_HOME/instrukt-ai/{app}/{app}.log` (fallback `~/.local/state`,
+  per the XDG Base Directory spec)
+
+This path is always user-writable — no installer step, no sudo, no elevated
+permissions. `configure_logging(...)` raises immediately if the log file
+cannot be opened; logging is an essential subsystem and a process that cannot
+write its logs must not start blind.
 
-- `/var/log/instrukt-ai/{app}/{app}.log`
+## Rotation
 
-The installer for each service is expected to create the directory and set write permissions for the daemon user. If the default location is not writable, the implementation will fall back to a user-writable directory and/or require `INSTRUKT_AI_LOG_ROOT`.
+Rotation is transparent and runs entirely in user space:
+`configure_logging(...)` idempotently ensures a per-user rotation conf plus a
+per-user scheduler (a launchd LaunchAgent on macOS running `newsyslog`, a
+systemd user timer on Linux running `logrotate`) on every process start. No
+`/etc` configuration, no sudo, and no system rotation daemon ever touches
+these files, so rotated/recreated logs always stay owned by the producing
+user. Run `instrukt-ai-log-setup` to check rotation-asset status manually;
+normal operation never requires it.
 
 ## CLI
 

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instruktai-python-logger"
-version = "0.5.1"
+version = "0.6.1"
 description = "Centralized logging utilities for Python services."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = []
 
 [dependency-groups]
-dev = ["pytest>=8", "ruff>=0.8", "pyright>=1.1", "mypy>=1.10"]
+dev = ["pytest>=8", "pytest-timeout>=2.2.0", "ruff>=0.8", "pyright>=1.1", "mypy>=1.10"]
 
 [project.scripts]
 instrukt-ai-logs = "instrukt_ai_logging.cli:main"
@@ -25,8 +25,17 @@ include = ["instrukt_ai_logging*"]
 instrukt_ai_logging = ["py.typed"]
 
 [tool.pytest.ini_options]
-addopts = "-q"
+addopts = "--strict-config --strict-markers --tb=short -q"
 testpaths = ["tests"]
+timeout = 5
+timeout_method = "signal"
+session_timeout = 90
+markers = [
+    "functional: fast, hermetic, no I/O beyond tmp_path",
+    "integration: exercises multiple in-process components together, still hermetic",
+    "process: drives an external process, bounded and hermetic (tmp_path/monkeypatch-isolated)",
+    "spec: binds a feature-spec scenario",
+]
 
 [tool.ruff]
 line-length = 120

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/tests/test_configure_logging.py

@@ -1,10 +1,11 @@
 import logging
+import os
 from logging.handlers import WatchedFileHandler
 from pathlib import Path
 from tempfile import TemporaryDirectory
 
 import pytest
-from instrukt_ai_logging import InstruktAILogger, configure_logging, get_logger
+from instrukt_ai_logging import InstruktAILogger, configure_logging, get_logger, install
 
 # Log markers shared by each test and its assertions — named constants per
 # software-development/procedure/snapshot-testing (no bare literals in content
@@ -39,6 +40,10 @@ _FIELD_MSG_TUI_WARNING = f'msg="{_MSG_TUI_WARNING}"'
 _FIELD_SESSION = f"session={_KV_SESSION}"
 _FIELD_N = f"n={_KV_N}"
 
+_APP_NAME = "teleclaude"
+_ROTATION_PROBLEM_MARKER = "log rotation ensure problem"
+_ROTATION_FAILURE_REASON = "no session bus"
+
 
 @pytest.fixture()
 def isolated_logging():
@@ -63,7 +68,7 @@ def _read_text(path: Path) -> str:
 
 def test_our_logs_respect_app_level_and_third_party_baseline(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "DEBUG")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
         monkeypatch.delenv("TELECLAUDE_THIRD_PARTY_LOGGERS", raising=False)
@@ -81,7 +86,7 @@ def test_our_logs_respect_app_level_and_third_party_baseline(isolated_logging, m
 
 def test_configure_logging_uses_single_file_handler(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
 
@@ -91,6 +96,81 @@ def test_configure_logging_uses_single_file_handler(isolated_logging, monkeypatc
         assert isinstance(logging.root.handlers[0], WatchedFileHandler)
 
 
+def test_configure_logging_fails_fast_when_file_unwritable(isolated_logging, monkeypatch):
+    with TemporaryDirectory() as tmp:
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
+        monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
+        monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
+
+        # Pre-create the target log file at the path configure_logging resolves,
+        # then strip all permissions to simulate a root-owned/unwritable file
+        # left behind by a botched log rotation.
+        app_dir = Path(tmp) / "instrukt-ai" / _APP_NAME
+        app_dir.mkdir(parents=True, exist_ok=True)
+        log_path = app_dir / f"{_APP_NAME}.log"
+        log_path.write_text("", encoding="utf-8")
+        os.chmod(log_path, 0)
+
+        try:
+            # Logging is an essential subsystem: an unopenable log file must
+            # raise, never silently degrade.
+            with pytest.raises(PermissionError):
+                configure_logging(_APP_NAME)
+        finally:
+            # Restore permissions so the TemporaryDirectory cleanup can unlink it.
+            os.chmod(log_path, 0o644)
+
+
+class _FakeFailingCompletedProcess:
+    def __init__(self) -> None:
+        self.returncode = 1
+        self.stderr = _ROTATION_FAILURE_REASON
+        self.stdout = ""
+
+
+def test_configure_logging_warns_without_raising_when_rotation_ensure_fails(isolated_logging, monkeypatch):
+    with TemporaryDirectory() as tmp:
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
+        monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
+        monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
+
+        def _fake_run(args):
+            return _FakeFailingCompletedProcess()
+
+        monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+
+        # A rotation-ensure failure must never crash logging — it's surfaced
+        # as a WARNING through the configured logger, not raised.
+        log_path = configure_logging(_APP_NAME)
+
+        content = _read_text(log_path)
+        assert _ROTATION_PROBLEM_MARKER in content
+        assert _ROTATION_FAILURE_REASON in content
+
+
+def test_configure_logging_resolves_xdg_state_home_location(isolated_logging, monkeypatch):
+    with TemporaryDirectory() as tmp:
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
+        monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
+        monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
+
+        log_path = configure_logging(_APP_NAME)
+
+        assert log_path == Path(tmp) / "instrukt-ai" / _APP_NAME / f"{_APP_NAME}.log"
+
+
+def test_configure_logging_falls_back_to_local_state_home_when_xdg_unset(isolated_logging, monkeypatch):
+    with TemporaryDirectory() as tmp:
+        monkeypatch.delenv("XDG_STATE_HOME", raising=False)
+        monkeypatch.setenv("HOME", tmp)
+        monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
+        monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
+
+        log_path = configure_logging(_APP_NAME)
+
+        assert log_path == Path(tmp) / ".local" / "state" / "instrukt-ai" / _APP_NAME / f"{_APP_NAME}.log"
+
+
 def test_get_logger_returns_instrukt_logger(isolated_logging):
     logger = get_logger(_LOGGER_OURS)
     assert isinstance(logger, InstruktAILogger)
@@ -99,7 +179,7 @@ def test_get_logger_returns_instrukt_logger(isolated_logging):
 
 def test_spotlight_allows_selected_third_party_only(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOGGERS", "httpcore")
@@ -130,7 +210,7 @@ def test_spotlight_allows_selected_third_party_only(isolated_logging, monkeypatc
 
 def test_named_kv_logger_emits_pairs(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "INFO")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
 
@@ -146,7 +226,7 @@ def test_named_kv_logger_emits_pairs(isolated_logging, monkeypatch):
 
 def test_muted_loggers_forced_to_warning(isolated_logging, monkeypatch):
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         monkeypatch.setenv("TELECLAUDE_LOG_LEVEL", "DEBUG")
         monkeypatch.setenv("TELECLAUDE_THIRD_PARTY_LOG_LEVEL", "WARNING")
         monkeypatch.setenv("TELECLAUDE_MUTED_LOGGERS", _LOGGER_MUTED)

instruktai_python_logger-0.6.1/tests/test_install.py

@@ -0,0 +1,255 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from instrukt_ai_logging import install
+
+# Protocol-significant tokens for the rotation configs — named constants per
+# software-development/procedure/snapshot-testing (no bare literals in content
+# assertions). These are newsyslog/logrotate/launchd/systemd field identities,
+# not prose.
+_NEWSYSLOG_MODE = "640"
+_NEWSYSLOG_COUNT = "5"
+_NEWSYSLOG_SIZE_KB = "50000"
+_NEWSYSLOG_WHEN = "*"
+_NEWSYSLOG_COMPRESS_GLOB_FLAGS = "ZG"  # gzip-compress archives; glob-expand at rotation time
+_PLIST_LABEL = "ai.instrukt.log-rotate"
+_PLIST_PROGRAM = "/usr/sbin/newsyslog"
+_PLIST_NO_ROOT_FLAG = "<string>-r</string>"  # newsyslog otherwise refuses to run as a non-root user
+_PLIST_START_INTERVAL = "1800"
+_LOGROTATE_SIZE = "size 50M"
+_LOGROTATE_ROTATE = "rotate 5"
+_LOGROTATE_COMPRESS = "compress"
+_LOGROTATE_DELAYCOMPRESS = "delaycompress"
+_LOGROTATE_MISSINGOK = "missingok"
+_LOGROTATE_NOTIFEMPTY = "notifempty"
+_SYSTEMD_EXEC_START_PREFIX = "ExecStart=logrotate"
+_SYSTEMD_ONESHOT = "Type=oneshot"
+_SYSTEMD_ON_CALENDAR = "OnCalendar=*:0/30"
+_SYSTEMD_PERSISTENT = "Persistent=true"
+_SYSTEMD_TIMER_UNIT = "instrukt-ai-logrotate.timer"
+_PROBLEM_DAEMON_RELOAD = "daemon-reload"
+_PROBLEM_WRITE_FAILURE = "could not write rotation assets"
+_MAIN_LOG_ROOT_PREFIX = "log root:"
+_MAIN_HEALTHY_STATUS = "status: healthy"
+_MAIN_PROBLEM_PREFIX = "problem:"
+
+
+class _FakeCompletedProcess:
+    def __init__(self, returncode: int, stderr: str = "") -> None:
+        self.returncode = returncode
+        self.stderr = stderr
+        self.stdout = ""
+
+
+@pytest.fixture
+def rotation_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    """Isolate the rotation-asset filesystem via XDG_STATE_HOME and HOME."""
+    state_home = tmp_path / "state"
+    home = tmp_path / "home"
+    state_home.mkdir(exist_ok=True)
+    home.mkdir(exist_ok=True)
+    monkeypatch.setenv("XDG_STATE_HOME", str(state_home))
+    monkeypatch.setenv("HOME", str(home))
+    return state_home
+
+
+@pytest.fixture
+def successful_subprocess(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
+    """Fake the scheduler subprocess boundary (launchctl/systemctl) as always succeeding."""
+    calls: list[list[str]] = []
+
+    def _fake_run(args: list[str]) -> _FakeCompletedProcess:
+        calls.append(args)
+        return _FakeCompletedProcess(returncode=0)
+
+    monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+    return calls
+
+
+def test_ensure_rotation_darwin_writes_newsyslog_conf_and_plist(
+    rotation_env: Path,
+    successful_subprocess: list[list[str]],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sys, "platform", "darwin")
+
+    problems = install.ensure_rotation()
+
+    assert problems == []
+    conf_content = install._newsyslog_conf_path().read_text(encoding="utf-8")
+    path, mode, count, size_kb, when, flags = conf_content.split()
+    assert path == f"{rotation_env / 'instrukt-ai'}/*/*.log"
+    assert mode == _NEWSYSLOG_MODE
+    assert count == _NEWSYSLOG_COUNT
+    assert size_kb == _NEWSYSLOG_SIZE_KB
+    assert when == _NEWSYSLOG_WHEN
+    assert flags == _NEWSYSLOG_COMPRESS_GLOB_FLAGS
+
+    plist_content = install._launchd_plist_path().read_text(encoding="utf-8")
+    assert _PLIST_LABEL in plist_content
+    assert _PLIST_PROGRAM in plist_content
+    assert _PLIST_NO_ROOT_FLAG in plist_content
+    assert _PLIST_START_INTERVAL in plist_content
+
+    assert successful_subprocess == [
+        ["launchctl", "bootstrap", f"gui/{os.getuid()}", str(install._launchd_plist_path())]
+    ]
+
+
+def test_ensure_rotation_linux_writes_logrotate_conf_and_systemd_units(
+    rotation_env: Path,
+    successful_subprocess: list[list[str]],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    problems = install.ensure_rotation()
+
+    assert problems == []
+    logrotate_content = install._logrotate_conf_path().read_text(encoding="utf-8")
+    assert f"{rotation_env / 'instrukt-ai'}/*/*.log" in logrotate_content
+    for directive in (
+        _LOGROTATE_SIZE,
+        _LOGROTATE_ROTATE,
+        _LOGROTATE_COMPRESS,
+        _LOGROTATE_DELAYCOMPRESS,
+        _LOGROTATE_MISSINGOK,
+        _LOGROTATE_NOTIFEMPTY,
+    ):
+        assert directive in logrotate_content
+    assert "su " not in logrotate_content  # rotation already runs as the producing user
+
+    service_content = install._systemd_service_path().read_text(encoding="utf-8")
+    assert _SYSTEMD_EXEC_START_PREFIX in service_content
+    assert _SYSTEMD_ONESHOT in service_content
+
+    timer_content = install._systemd_timer_path().read_text(encoding="utf-8")
+    assert _SYSTEMD_ON_CALENDAR in timer_content
+    assert _SYSTEMD_PERSISTENT in timer_content
+
+    assert successful_subprocess == [
+        ["systemctl", "--user", "daemon-reload"],
+        ["systemctl", "--user", "enable", "--now", _SYSTEMD_TIMER_UNIT],
+    ]
+
+
+def test_ensure_rotation_is_idempotent_across_runs(
+    rotation_env: Path,
+    successful_subprocess: list[list[str]],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    install.ensure_rotation()
+    conf_path = install._logrotate_conf_path()
+    first_mtime_ns = conf_path.stat().st_mtime_ns
+    first_content = conf_path.read_text(encoding="utf-8")
+
+    install.ensure_rotation()
+
+    assert conf_path.stat().st_mtime_ns == first_mtime_ns
+    assert conf_path.read_text(encoding="utf-8") == first_content
+
+
+def test_ensure_rotation_reports_problem_when_scheduler_subprocess_fails(
+    rotation_env: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    def _fake_run(args: list[str]) -> _FakeCompletedProcess:
+        return _FakeCompletedProcess(returncode=1, stderr="no session bus")
+
+    monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+
+    problems = install.ensure_rotation()
+
+    assert problems
+    assert any(_PROBLEM_DAEMON_RELOAD in problem for problem in problems)
+
+
+def test_ensure_rotation_reports_problem_when_scheduler_subprocess_times_out(
+    rotation_env: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    def _fake_run(args: list[str]) -> _FakeCompletedProcess:
+        raise subprocess.TimeoutExpired(cmd=args, timeout=install._SCHEDULER_COMMAND_TIMEOUT_S)
+
+    monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+
+    # An unreachable scheduler bus must be reported, never left to hang the
+    # caller indefinitely.
+    problems = install.ensure_rotation()
+
+    assert problems
+    assert any(_PROBLEM_DAEMON_RELOAD in problem for problem in problems)
+
+
+def test_ensure_rotation_reports_problem_when_asset_write_fails(
+    rotation_env: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    def _raise_write_error(path: Path, content: str) -> None:
+        raise OSError("read-only file system")
+
+    monkeypatch.setattr(install, "_write_if_changed", _raise_write_error)
+
+    # An unwritable rotation-asset directory must be reported, never left to
+    # propagate out of ensure_rotation()'s never-raises contract.
+    problems = install.ensure_rotation()
+
+    assert problems
+    assert any(_PROBLEM_WRITE_FAILURE in problem for problem in problems)
+
+
+def test_ensure_rotation_tolerates_already_bootstrapped_launchd(
+    rotation_env: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(sys, "platform", "darwin")
+
+    def _fake_run(args: list[str]) -> _FakeCompletedProcess:
+        return _FakeCompletedProcess(returncode=1, stderr="Service already bootstrapped")
+
+    monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+
+    problems = install.ensure_rotation()
+
+    assert problems == []
+
+
+def test_main_prints_status_and_exits_zero_when_healthy(
+    rotation_env: Path,
+    successful_subprocess: list[list[str]],
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    install.main()
+
+    out = capsys.readouterr().out
+    assert _MAIN_LOG_ROOT_PREFIX in out
+    assert _MAIN_HEALTHY_STATUS in out
+
+
+def test_main_exits_non_zero_and_reports_problems(
+    rotation_env: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(sys, "platform", "linux")
+
+    def _fake_run(args: list[str]) -> _FakeCompletedProcess:
+        return _FakeCompletedProcess(returncode=1, stderr="boom")
+
+    monkeypatch.setattr(install, "_run_scheduler_command", _fake_run)
+
+    with pytest.raises(SystemExit):
+        install.main()
+
+    out = capsys.readouterr().out
+    assert _MAIN_PROBLEM_PREFIX in out

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/tests/test_log_aggregation.py

@@ -43,9 +43,9 @@ _LARGE_LINE_COUNT = 20000
 def app_log_dir(monkeypatch: pytest.MonkeyPatch) -> Iterator[Path]:
     tmp = TemporaryDirectory()
     root = Path(tmp.name)
-    monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", str(root))
+    monkeypatch.setenv("XDG_STATE_HOME", str(root))
 
-    app_dir = root / "demo-app"
+    app_dir = root / "instrukt-ai" / "demo-app"
     app_dir.mkdir(parents=True)
     yield app_dir
     tmp.cleanup()
@@ -83,7 +83,7 @@ def test_resolve_log_files_returns_empty_for_unknown_stem(app_log_dir: Path) ->
 
 def test_resolve_log_files_returns_empty_when_dir_missing(monkeypatch: pytest.MonkeyPatch) -> None:
     with TemporaryDirectory() as tmp:
-        monkeypatch.setenv("INSTRUKT_AI_LOG_ROOT", tmp)
+        monkeypatch.setenv("XDG_STATE_HOME", tmp)
         # Directory for the app does not exist.
         assert resolve_log_files("nonexistent-app") == []
 

{instruktai_python_logger-0.5.1 → instruktai_python_logger-0.6.1}/tests/test_trace_logging.py

@@ -40,7 +40,7 @@ def test_trace_level_logging(clean_env):
 
     # Use a temporary directory for logs
     with tempfile.TemporaryDirectory() as temp_dir:
-        os.environ["INSTRUKT_AI_LOG_ROOT"] = temp_dir
+        os.environ["XDG_STATE_HOME"] = temp_dir
 
         log_file = configure_logging(app_name)
         logger = get_logger("test_trace_app")
@@ -71,7 +71,7 @@ def test_trace_level_filtering(clean_env):
     os.environ["TEST_TRACE_FILTERING_LOG_LEVEL"] = "DEBUG"
 
     with tempfile.TemporaryDirectory() as temp_dir:
-        os.environ["INSTRUKT_AI_LOG_ROOT"] = temp_dir
+        os.environ["XDG_STATE_HOME"] = temp_dir
 
         log_file = configure_logging(app_name)
         logger = get_logger("test_trace_filtering")

instruktai_python_logger-0.5.1/instrukt_ai_logging/install.py

@@ -1,96 +0,0 @@
-"""Install log rotation for InstruktAI logs."""
-
-from __future__ import annotations
-
-import argparse
-import os
-import sys
-from pathlib import Path
-
-DEFAULT_NEWSYSLOG_CONF = Path("/etc/newsyslog.d/instrukt-ai.conf")
-DEFAULT_LOGROTATE_CONF = Path("/etc/logrotate.d/instrukt-ai")
-
-
-def _write_file(path: Path, content: str, *, force: bool) -> None:
-    if path.exists() and not force:
-        raise SystemExit(f"Refusing to overwrite existing file: {path}. Use --force.")
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content, encoding="utf-8")
-
-
-def _install_newsyslog(
-    log_root: Path,
-    *,
-    force: bool,
-    conf_path: Path = DEFAULT_NEWSYSLOG_CONF,
-) -> Path:
-    """Install newsyslog rules covering every app's *.log file.
-
-    Format: path  owner:group  mode  count  size(KB)  when  flags
-    Defaults: 50 MB rotation, 5 archives, gzip-compress archives (Z flag).
-
-    macOS newsyslog requires literal filenames — its config does NOT
-    expand globs at runtime. We therefore enumerate every existing
-    *.log file under log_root and emit one explicit line per file.
-    Re-run `instrukt-ai-log-setup --force` after a new producer creates
-    its first log file (which can be wired into the app's installer or
-    a daemon's periodic cleanup task).
-    """
-    if log_root.is_dir():
-        log_files = sorted(p for p in log_root.glob("*/*.log") if p.is_file())
-    else:
-        log_files = []
-    lines = "".join(f"{path}  640  5  50000  *  Z\n" for path in log_files)
-    if not lines:
-        # No log files yet — write a placeholder comment so the conf is
-        # discoverable on disk for future re-runs.
-        lines = f"# instrukt-ai-log-setup: no *.log files found under {log_root}\n"
-    _write_file(conf_path, lines, force=force)
-    return conf_path
-
-
-def _install_logrotate(
-    log_root: Path,
-    *,
-    force: bool,
-    conf_path: Path = DEFAULT_LOGROTATE_CONF,
-) -> Path:
-    """Install a glob-based logrotate rule covering every app's *.log file.
-
-    Defaults: 50 MB rotation, 5 archives, gzip-compress archives.
-    """
-    content = f"""{log_root}/*/*.log {{
-    size 50M
-    rotate 5
-    compress
-    delaycompress
-    missingok
-    notifempty
-    copytruncate
-}}
-"""
-    _write_file(conf_path, content, force=force)
-    return conf_path
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(prog="instrukt-ai-log-setup", add_help=True)
-    parser.add_argument(
-        "--log-root",
-        default=os.environ.get("INSTRUKT_AI_LOG_ROOT", "/var/log/instrukt-ai"),
-        help="Base log root (default: /var/log/instrukt-ai or INSTRUKT_AI_LOG_ROOT)",
-    )
-    parser.add_argument("--force", action="store_true", help="Overwrite existing config")
-    args = parser.parse_args()
-
-    log_root = Path(args.log_root)
-    if sys.platform == "darwin":
-        conf = _install_newsyslog(log_root, force=args.force)
-    else:
-        conf = _install_logrotate(log_root, force=args.force)
-
-    sys.stdout.write(f"installed: {conf}\n")
-
-
-if __name__ == "__main__":
-    main()

instruktai_python_logger-0.5.1/tests/test_install.py

@@ -1,131 +0,0 @@
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-from instrukt_ai_logging.install import _install_logrotate, _install_newsyslog
-
-# Protocol-significant tokens for the rotation configs — named constants per
-# software-development/procedure/snapshot-testing (no bare literals in content
-# assertions). These are newsyslog field identities, not prose.
-_NEWSYSLOG_MODE = "640"
-_NEWSYSLOG_COUNT = "5"
-_NEWSYSLOG_SIZE_KB = "50000"
-_NEWSYSLOG_WHEN = "*"
-_NEWSYSLOG_COMPRESS_FLAG = "Z"  # gzip-compress archives
-_COMMENT_PREFIX = "#"
-_PREEXISTING_CONF = "preexisting"
-
-
-def test_install_newsyslog_emits_one_line_per_existing_log_file(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    (log_root / "teleclaude").mkdir(parents=True)
-    (log_root / "teleclaude" / "teleclaude.log").touch()
-    (log_root / "teleclaude" / "cron.log").touch()
-    (log_root / "teleclaude" / "docs-watch.log").touch()
-    (log_root / "other-app").mkdir()
-    (log_root / "other-app" / "other-app.log").touch()
-    (log_root / "teleclaude" / "notes.txt").touch()  # ignored: not *.log
-    conf_path = tmp_path / "etc" / "newsyslog.d" / "instrukt-ai.conf"
-
-    _install_newsyslog(log_root, force=False, conf_path=conf_path)
-
-    rotated = [
-        line.split()[0]
-        for line in conf_path.read_text(encoding="utf-8").splitlines()
-        if line and not line.startswith(_COMMENT_PREFIX)
-    ]
-    assert rotated == sorted(
-        [
-            str(log_root / "other-app" / "other-app.log"),
-            str(log_root / "teleclaude" / "cron.log"),
-            str(log_root / "teleclaude" / "docs-watch.log"),
-            str(log_root / "teleclaude" / "teleclaude.log"),
-        ]
-    )
-
-
-def test_install_newsyslog_uses_compressing_rotation_defaults(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    (log_root / "app").mkdir(parents=True)
-    (log_root / "app" / "app.log").touch()
-    conf_path = tmp_path / "newsyslog.conf"
-
-    _install_newsyslog(log_root, force=False, conf_path=conf_path)
-
-    fields = conf_path.read_text(encoding="utf-8").split()
-    # path  mode  count  size(KB)  when  flags
-    _, mode, count, size_kb, when, flags = fields
-    assert mode == _NEWSYSLOG_MODE
-    assert count == _NEWSYSLOG_COUNT
-    assert size_kb == _NEWSYSLOG_SIZE_KB
-    assert when == _NEWSYSLOG_WHEN
-    assert _NEWSYSLOG_COMPRESS_FLAG in flags  # gzip-compress archives
-
-
-def test_install_newsyslog_writes_placeholder_when_no_log_files_exist(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    log_root.mkdir()  # exists but contains no *.log files
-    conf_path = tmp_path / "newsyslog.conf"
-
-    _install_newsyslog(log_root, force=False, conf_path=conf_path)
-
-    content = conf_path.read_text(encoding="utf-8")
-    assert content.startswith(_COMMENT_PREFIX)
-    assert all(line.startswith(_COMMENT_PREFIX) or not line for line in content.splitlines())
-
-
-def test_install_newsyslog_refuses_overwrite_without_force(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    (log_root / "app").mkdir(parents=True)
-    (log_root / "app" / "app.log").touch()
-    conf_path = tmp_path / "newsyslog.conf"
-    conf_path.write_text(_PREEXISTING_CONF, encoding="utf-8")
-
-    with pytest.raises(SystemExit):
-        _install_newsyslog(log_root, force=False, conf_path=conf_path)
-    assert conf_path.read_text(encoding="utf-8") == _PREEXISTING_CONF
-
-
-def test_install_newsyslog_overwrites_with_force(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    (log_root / "app").mkdir(parents=True)
-    (log_root / "app" / "app.log").touch()
-    conf_path = tmp_path / "newsyslog.conf"
-    conf_path.write_text(_PREEXISTING_CONF, encoding="utf-8")
-
-    _install_newsyslog(log_root, force=True, conf_path=conf_path)
-    assert conf_path.read_text(encoding="utf-8") != _PREEXISTING_CONF
-
-
-def test_install_logrotate_writes_glob_block_with_compressing_defaults(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    log_root.mkdir()
-    conf_path = tmp_path / "logrotate.conf"
-
-    _install_logrotate(log_root, force=False, conf_path=conf_path)
-
-    content = conf_path.read_text(encoding="utf-8")
-    # logrotate handles multi-level globs natively, unlike macOS newsyslog.
-    assert f"{log_root}/*/*.log" in content
-    # Protocol-significant directives — these are logrotate keywords, not prose.
-    for directive in (
-        "size 50M",
-        "rotate 5",
-        "compress",
-        "delaycompress",
-        "missingok",
-        "copytruncate",
-    ):
-        assert directive in content
-
-
-def test_install_logrotate_refuses_overwrite_without_force(tmp_path: Path) -> None:
-    log_root = tmp_path / "logs"
-    log_root.mkdir()
-    conf_path = tmp_path / "logrotate.conf"
-    conf_path.write_text(_PREEXISTING_CONF, encoding="utf-8")
-
-    with pytest.raises(SystemExit):
-        _install_logrotate(log_root, force=False, conf_path=conf_path)
-    assert conf_path.read_text(encoding="utf-8") == _PREEXISTING_CONF