loghunter-cli 0.1.0.dev0__py3-none-any.whl

tests/test_config_cli.py

@@ -0,0 +1,1006 @@
+"""Tests for config defaults and CLI user-facing errors."""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+import tomllib
+from pathlib import Path
+
+from loghunter import cli
+from loghunter.cli import _runner_kwargs
+from loghunter.common import config as cfg
+from loghunter.detectors import dns
+
+
+def test_detector_defaults_are_owned_by_detector_modules(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    config = cfg.load(config_file=None)
+
+    assert config["detectors"] == {}
+    assert cfg.get_detector_config(config, "dns", dns.DEFAULT_CONFIG) == dns.DEFAULT_CONFIG
+
+
+def test_detector_config_overrides_detector_defaults() -> None:
+    config = {"detectors": {"dns": {"min_cluster_size": 42}}}
+
+    merged = cfg.get_detector_config(config, "dns", dns.DEFAULT_CONFIG)
+
+    assert merged["min_cluster_size"] == 42
+    assert merged["min_samples"] == dns.DEFAULT_CONFIG["min_samples"]
+
+
+def test_cli_formats_missing_config_file_as_actionable_error(
+    capsys: pytest.CaptureFixture[str],
+    tmp_path,
+) -> None:
+    missing = tmp_path / "missing.toml"
+    with pytest.raises(SystemExit) as exc:
+        cli.main([f"--config={missing}", "--dry-run"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: Config file not found" in captured.err
+    assert "run 'loghunter init' to create a config" in captured.err
+
+
+def test_cli_formats_bad_since_as_usage_error(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    with pytest.raises(SystemExit) as exc:
+        cli.main(["--since=tomorrow", "--dry-run"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: --since expects a date like 2026-05-01" in captured.err
+    assert "Run 'loghunter --help' for usage." in captured.err
+
+
+def test_cli_formats_bad_days_as_usage_error(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    with pytest.raises(SystemExit) as exc:
+        cli.main(["--days=soon", "--dry-run"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: --days expects a range like 3-5" in captured.err
+
+
+def test_cli_formats_unknown_output_as_usage_error(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path,
+) -> None:
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    zeek_dir = tmp_path / "zeek"
+    zeek_dir.mkdir()
+    (zeek_dir / "conn.log").write_text("", encoding="utf-8")
+
+    with pytest.raises(SystemExit) as exc:
+        cli.main([f"--zeek-dir={zeek_dir}", "--output=bogus"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: Unknown output format 'bogus'." in captured.err
+    assert "Available formats:" in captured.err
+
+
+def test_runner_kwargs_pihole_dir_arg(tmp_path: Path) -> None:
+    """--pihole-dir=PATH (parsed as pihole_dir key) flows through as the raw
+    string. The CLI does NOT resolve source-dir strings — that's the
+    resolver's job (covered by tests/test_sources.py). _runner_kwargs is
+    pure pass-through here."""
+    pihole = tmp_path / "pihole"
+    pihole.mkdir()
+    parsed = {"pihole_dir": str(pihole)}
+    kwargs = _runner_kwargs(parsed, config={})
+    assert kwargs["pihole_dir"] == str(pihole)
+
+
+def test_runner_kwargs_cloudtrail_dir_arg(tmp_path: Path) -> None:
+    """--cloudtrail-dir=PATH flows through as the raw string."""
+    cloudtrail = tmp_path / "ct"
+    cloudtrail.mkdir()
+    parsed = {"cloudtrail_dir": str(cloudtrail)}
+    kwargs = _runner_kwargs(parsed, config={})
+    assert kwargs["cloudtrail_dir"] == str(cloudtrail)
+
+
+def test_runner_kwargs_none_when_flag_absent() -> None:
+    """No flag → None override; the resolver decides whether to config-fill.
+    Replaces the old _from_config / unconfigured tests — that logic now lives
+    in resolve_sources (covered by tests/test_sources.py)."""
+    kwargs = _runner_kwargs({}, config={"loghunter": {"cloudtrail_dir": "/cfg/ct"}})
+    # CLI seam passes None for absent flags regardless of config — the runner
+    # routes the override+config into resolve_sources.
+    assert kwargs["cloudtrail_dir"] is None
+    assert kwargs["zeek_dir"] is None
+    assert kwargs["syslog_dir"] is None
+    assert kwargs["pihole_dir"] is None
+
+
+def test_usage_advertises_cloudtrail_dir(capsys) -> None:
+    """First-run / --help usage must mention --cloudtrail-dir alongside the other
+    source-dir flags."""
+    cli._print_usage()
+    out = capsys.readouterr().out
+    assert "--cloudtrail-dir" in out
+
+
+# ── Bare source-dir flag (no =value) → actionable CLI error ──────────────────
+#
+# _parse_args records a bare ``--zeek-dir`` (no =value) as
+# parsed["zeek_dir"] = True. Pre-fix, ``Path(True)`` downstream raised a raw
+# TypeError that escaped the CLI error boundary as a traceback. Post-fix,
+# _coerce_source_dir catches the boolean at the seam and raises an actionable
+# ``loghunter:`` ValueError with exit 1.
+
+@pytest.mark.parametrize(
+    "flag", ["--zeek-dir", "--syslog-dir", "--pihole-dir", "--cloudtrail-dir"],
+)
+def test_bare_source_dir_flag_in_detect_raises_actionable_error(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+    flag: str,
+) -> None:
+    """Bare ``--<source>-dir`` (no =value) on the detect route produces an
+    actionable ``loghunter:`` message and exit 1 — no raw TypeError."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    with pytest.raises(SystemExit) as exc:
+        cli.main([flag, "--dry-run"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert f"loghunter: {flag} needs a value: {flag}=…" in captured.err
+    assert "Run 'loghunter --help' for usage." in captured.err
+
+
+def test_bare_zeek_dir_flag_in_bare_digest_raises_actionable_error(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Bare ``digest --zeek-dir`` (no positional) takes the bare-digest path
+    where ``--zeek-dir`` is the only source-dir flag in
+    _DIGEST_ALLOWED_LONG_FLAGS. Same actionable shape as the detect route.
+
+    The other three source-dir flags (--pihole-dir, --syslog-dir,
+    --cloudtrail-dir) are intentionally NOT in the digest allow-list — they
+    raise "unknown digest flag --…" via the existing _validate_digest_flags
+    rail and that behaviour is preserved (the digest CLI surface stays
+    narrow per CODE.md).
+    """
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    with pytest.raises(SystemExit) as exc:
+        cli.main(["digest", "--zeek-dir"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: --zeek-dir needs a value: --zeek-dir=…" in captured.err
+
+
+def test_bare_value_flag_with_short_form_mentions_short(
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A value-taking flag that has a short form mentions both spellings."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    with pytest.raises(SystemExit) as exc:
+        cli.main(["--out"])
+
+    assert exc.value.code == 1
+    captured = capsys.readouterr()
+    assert "loghunter: --out (-o) needs a value: -o=… or --out=…" in captured.err
+
+
+# The previous two mock-the-seam dns routing tests were DELETED. Their
+# intent (content-sniff routes Zeek dns → zeek_dir, Pi-hole → pihole_dir)
+# lives in tests/test_sources.py:
+#   - test_router_dns_pihole_content_under_neutral_name (the key locking
+#     content-not-name routing — fixture name does NOT match pihole*.log*)
+#   - test_router_dns_zeek_content_routes_to_zeek_dir
+# The end-to-end scope rail (sibling source-dirs stay unloaded across the
+# CLI ↔ runner seam) is locked by tests/test_source_resolution_seam.py.
+
+
+def test_config_example_is_valid_toml() -> None:
+    path = Path("loghunter/data/config_example.toml")
+
+    with path.open("rb") as fh:
+        parsed = tomllib.load(fh)
+
+    assert parsed["allowlist"]["domain_patterns"] == ["~/.loghunter/allowlist.d/domains_user.txt"]
+    assert parsed["allowlist"]["connection_rules"] == ["~/.loghunter/allowlist.d/connections.txt"]
+
+
+# ── Stage 4: default_window + --all ───────────────────────────────────────────
+
+from datetime import timedelta
+
+from loghunter.common.config import parse_window_span
+
+
+def test_default_window_in_config_defaults() -> None:
+    config = cfg.load(None)
+    assert config["loghunter"]["default_window"] == "1d"
+
+
+def test_invalid_default_window_raises_at_load(tmp_path: Path) -> None:
+    cfg_file = tmp_path / "lh.toml"
+    cfg_file.write_text('[loghunter]\ndefault_window = "1week"\n', encoding="utf-8")
+    with pytest.raises(cfg.ConfigError, match="not a valid duration"):
+        cfg.load(cfg_file)
+
+
+def test_zero_default_window_raises_at_load(tmp_path: Path) -> None:
+    cfg_file = tmp_path / "lh.toml"
+    cfg_file.write_text('[loghunter]\ndefault_window = "0d"\n', encoding="utf-8")
+    with pytest.raises(cfg.ConfigError):
+        cfg.load(cfg_file)
+
+
+def test_empty_string_default_window_loads_cleanly(tmp_path: Path) -> None:
+    cfg_file = tmp_path / "lh.toml"
+    cfg_file.write_text('[loghunter]\ndefault_window = ""\n', encoding="utf-8")
+    config = cfg.load(cfg_file)
+    assert config["loghunter"]["default_window"] == ""
+
+
+def test_all_keyword_default_window_loads_cleanly(tmp_path: Path) -> None:
+    cfg_file = tmp_path / "lh.toml"
+    cfg_file.write_text('[loghunter]\ndefault_window = "all"\n', encoding="utf-8")
+    config = cfg.load(cfg_file)
+    assert config["loghunter"]["default_window"] == "all"
+
+
+def test_parse_window_span_days() -> None:
+    assert parse_window_span("1d") == timedelta(days=1)
+    assert parse_window_span("7d") == timedelta(days=7)
+
+
+def test_parse_window_span_hours() -> None:
+    assert parse_window_span("24h") == timedelta(hours=24)
+    assert parse_window_span("12h") == timedelta(hours=12)
+
+
+def test_parse_window_span_empty_and_all_disable() -> None:
+    assert parse_window_span(None) is None
+    assert parse_window_span("") is None
+    assert parse_window_span("all") is None
+    assert parse_window_span("ALL") is None
+
+
+def test_parse_window_span_invalid_raises() -> None:
+    with pytest.raises(cfg.ConfigError):
+        parse_window_span("nonsense")
+    with pytest.raises(cfg.ConfigError):
+        parse_window_span("7days")
+    with pytest.raises(cfg.ConfigError):
+        parse_window_span("-1d")
+
+
+def test_runner_kwargs_all_with_since_raises() -> None:
+    with pytest.raises(ValueError, match="--all cannot be combined"):
+        _runner_kwargs({"all": True, "since": "7d"}, config={})
+
+
+def test_runner_kwargs_all_with_until_raises() -> None:
+    with pytest.raises(ValueError, match="--all cannot be combined"):
+        _runner_kwargs({"all": True, "until": "2026-01-01"}, config={})
+
+
+def test_runner_kwargs_all_with_days_raises() -> None:
+    with pytest.raises(ValueError, match="--all cannot be combined"):
+        _runner_kwargs({"all": True, "days": "3-5"}, config={})
+
+
+def test_runner_kwargs_all_with_hours_raises() -> None:
+    with pytest.raises(ValueError, match="--all cannot be combined"):
+        _runner_kwargs({"all": True, "hours": "2-6"}, config={})
+
+
+def test_runner_kwargs_all_flag_sets_load_all() -> None:
+    kwargs = _runner_kwargs({"all": True}, config={})
+    assert kwargs["load_all"] is True
+
+
+def test_runner_kwargs_no_all_flag_sets_load_all_false() -> None:
+    kwargs = _runner_kwargs({}, config={})
+    assert kwargs["load_all"] is False
+
+
+# ── --yes / -y wiring ─────────────────────────────────────────────────────────
+
+
+def test_parse_args_recognizes_long_yes() -> None:
+    """--yes is a bool flag on every verb that allows it (analyze allows it)."""
+    result = cli._parse_args(["--yes"], "")
+    assert result.get("yes") is True
+
+
+def test_parse_args_recognizes_short_y() -> None:
+    """-y is the canonical short for --yes (allowed on analyze)."""
+    result = cli._parse_args(["-y"], "")
+    assert result.get("yes") is True
+
+
+def test_parse_args_rejects_unknown_short_flag() -> None:
+    """Unknown short flags now RAISE — the old silent-ignore behavior is gone."""
+    with pytest.raises(ValueError, match="unknown flag -x"):
+        cli._parse_args(["-x", "PATH"], "")
+
+
+def test_parse_args_rejects_unknown_long_flag() -> None:
+    with pytest.raises(ValueError, match="unknown flag --foo"):
+        cli._parse_args(["--foo", "PATH"], "")
+
+
+def test_parse_args_captures_path_and_paths() -> None:
+    """Both ``path`` (first positional) and ``paths`` (full list) populate."""
+    result = cli._parse_args(["a.log", "b.log"], "digest")
+    assert result["path"] == "a.log"
+    assert result["paths"] == ["a.log", "b.log"]
+
+
+def test_parse_args_wrong_verb_long_form_lead_spelling() -> None:
+    """``digest --detect`` reports wrong-verb with the long-form lead."""
+    with pytest.raises(ValueError, match=r"--detect \(-d\) is not valid for digest"):
+        cli._parse_args(["--detect=all"], "digest")
+
+
+def test_parse_args_wrong_verb_short_form_lead_spelling() -> None:
+    """``digest -d`` reports wrong-verb with the short-form lead."""
+    with pytest.raises(ValueError, match=r"-d \(--detect\) is not valid for digest"):
+        cli._parse_args(["-d=all"], "digest")
+
+
+def test_parse_args_wrong_verb_beats_value_shape_for_bare_short() -> None:
+    """Validation order: wrong-verb wins over needs-a-value for ``digest -d``."""
+    with pytest.raises(ValueError, match=r"-d \(--detect\) is not valid for digest"):
+        cli._parse_args(["-d"], "digest")
+
+
+def test_parse_args_wrong_verb_beats_value_shape_for_bare_long() -> None:
+    """Same as above for ``digest --detect``."""
+    with pytest.raises(ValueError, match=r"--detect \(-d\) is not valid for digest"):
+        cli._parse_args(["--detect"], "digest")
+
+
+def test_parse_args_value_on_bool_raises_long() -> None:
+    with pytest.raises(ValueError, match=r"--verbose \(-v\) takes no value"):
+        cli._parse_args(["--verbose=1"], "")
+
+
+def test_parse_args_value_on_bool_raises_short() -> None:
+    with pytest.raises(ValueError, match=r"--verbose \(-v\) takes no value"):
+        cli._parse_args(["-v=1"], "")
+
+
+def test_parse_args_bundling_known_shorts_suggests_separation() -> None:
+    with pytest.raises(ValueError, match="short flags can't be combined"):
+        cli._parse_args(["-vy"], "")
+
+
+def test_parse_args_bundling_unknown_short_is_plain_unknown() -> None:
+    with pytest.raises(ValueError, match="unknown flag -vq"):
+        cli._parse_args(["-vq"], "")
+
+
+def test_parse_args_help_eq_value_is_takes_no_value() -> None:
+    """``--help=foo`` is NOT a help short-circuit — strict parser rejects it."""
+    with pytest.raises(ValueError, match=r"--help \(-h\) takes no value"):
+        cli._parse_args(["--help=foo"], "")
+
+
+def test_parse_args_duplicate_flag_last_wins() -> None:
+    """A repeated value flag stays single-valued; last write wins."""
+    result = cli._parse_args(["--out=a", "--out=b"], "")
+    assert result["out"] == "b"
+
+
+# ── W3: -vv literal token + verbose-level resolution ─────────────────────────
+
+
+def test_parse_args_short_v_sets_verbose_true() -> None:
+    result = cli._parse_args(["-v"], "")
+    assert result.get("verbose") is True
+    assert "verbose_level" not in result
+
+
+def test_parse_args_long_verbose_sets_verbose_true() -> None:
+    result = cli._parse_args(["--verbose"], "")
+    assert result.get("verbose") is True
+
+
+def test_parse_args_literal_vv_sets_verbose_level_two() -> None:
+    """`-vv` is recognized as an explicit literal token BEFORE the bundling
+    refusal fires (regression against the old `pass separately` error)."""
+    result = cli._parse_args(["-vv"], "")
+    assert result.get("verbose_level") == 2
+
+
+def test_parse_args_combined_v_and_vv_resolves_to_level_two() -> None:
+    """Last-wins duplication: `-v -vv` resolves to 2 via _resolve_verbose_level."""
+    parsed = cli._parse_args(["-v", "-vv"], "")
+    assert cli._resolve_verbose_level(parsed) == 2
+
+
+def test_parse_args_vvv_still_rejected_as_bundling() -> None:
+    """`-vvv` is not a registered literal — falls through to the bundling
+    refusal lattice with the existing pass-separately message."""
+    with pytest.raises(ValueError, match="short flags can't be combined"):
+        cli._parse_args(["-vvv"], "")
+
+
+def test_parse_args_vy_still_rejected_as_bundling() -> None:
+    """`-vy` is not the literal `-vv` and still hits bundling refusal."""
+    with pytest.raises(ValueError, match="short flags can't be combined"):
+        cli._parse_args(["-vy"], "")
+
+
+def test_parse_args_vv_wrong_verb_matches_v_error_shape() -> None:
+    """`init` disallows verbose; `-vv` raises the SAME wrong-verb error shape
+    as `-v` would. Validation order: identity → verb-membership → value-shape."""
+    with pytest.raises(ValueError, match=r"-v \(--verbose\) is not valid for init"):
+        cli._parse_args(["-vv"], "init")
+    # And the parity check on -v:
+    with pytest.raises(ValueError, match=r"-v \(--verbose\) is not valid for init"):
+        cli._parse_args(["-v"], "init")
+
+
+def test_resolve_verbose_level_collapses_states() -> None:
+    """none → 0; -v → 1; -vv → 2; combined → 2."""
+    assert cli._resolve_verbose_level({}) == 0
+    assert cli._resolve_verbose_level({"verbose": True}) == 1
+    assert cli._resolve_verbose_level({"verbose_level": 2}) == 2
+    assert cli._resolve_verbose_level({"verbose": True, "verbose_level": 2}) == 2
+
+
+def test_runner_kwargs_yes_flag_sets_skip_confirm() -> None:
+    kwargs = _runner_kwargs({"yes": True}, config={})
+    assert kwargs.get("skip_confirm") is True
+
+
+def test_runner_kwargs_no_yes_flag_skip_confirm_false() -> None:
+    kwargs = _runner_kwargs({}, config={})
+    assert kwargs.get("skip_confirm") is False
+
+
+def test_usage_includes_yes_flag(capsys) -> None:
+    """--help / first-run usage must advertise --yes and -y."""
+    cli._print_usage()
+    out = capsys.readouterr().out
+    assert "--yes" in out
+    assert "-y" in out
+
+
+def test_yes_threads_to_run_export(monkeypatch, tmp_path: Path) -> None:
+    """`loghunter export <backend> --yes` must reach run_export with skip_confirm=True."""
+    captured: dict = {}
+
+    def _fake_run_export(*args, **kwargs):
+        captured.update(kwargs)
+
+    # _run_export does `from loghunter.exporters import run_export` inside the
+    # function — re-binding the attribute on the package is what it picks up.
+    monkeypatch.setattr("loghunter.exporters.run_export", _fake_run_export)
+    monkeypatch.setattr(
+        cfg, "load", lambda _=None: {
+            "export": {"splunk": {"host": "192.0.2.20", "port": 8089,
+                                  "query": {"default": {"spl": "x"}}}},
+        },
+    )
+    cli.main(["export", "splunk", "--yes"])
+    assert captured.get("skip_confirm") is True
+
+
+def test_yes_threads_to_runner_run(monkeypatch, tmp_path: Path) -> None:
+    """A detector invocation with --yes must reach runner.run with skip_confirm=True."""
+    captured: dict = {}
+
+    def _fake_run(**kwargs):
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", _fake_run)
+    # Use a single-detector subcommand path that already takes a zeek_dir.
+    cli.main(["beacon", f"--zeek-dir={tmp_path}", "--yes"])
+    assert captured.get("skip_confirm") is True
+
+
+# ── CLI flag rename: --output-dir → --out (user-facing contract) ─────────────
+
+
+def test_usage_advertises_out_not_output_dir(capsys) -> None:
+    """Usage text mentions --out (the new flag) and not --output-dir (the dropped name).
+
+    We deliberately do NOT test runtime rejection of --output-dir — the generic
+    --flag=value parser would still produce an inert `output_dir` key, which is
+    harmless dead state. The user-facing contract is the help text.
+    """
+    cli._print_usage()
+    out = capsys.readouterr().out
+    assert "--out" in out
+    assert "--output-dir" not in out
+
+
+# ── Thread C — CLI polish for the aws detector ────────────────────────────────
+
+# Fix 1: aws subcommand + usage
+
+def test_aws_is_a_single_detector_command() -> None:
+    """loghunter aws PATH must be recognized as a single-detector subcommand."""
+    assert "aws" in cli._SINGLE_DETECTOR_COMMANDS
+
+
+def test_usage_lists_aws_subcommand(capsys) -> None:
+    cli._print_usage()
+    out = capsys.readouterr().out
+    assert "loghunter aws " in out
+
+
+def test_usage_lists_duration_subcommand(capsys) -> None:
+    """Regression: catch any future stale-usage drift on duration."""
+    cli._print_usage()
+    out = capsys.readouterr().out
+    assert "loghunter duration " in out
+
+
+# Fix 2: positional PATH → cloudtrail_dir in single-detector mode
+
+def test_aws_positional_path_routes_to_cloudtrail_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """loghunter aws PATH routes the positional to cloudtrail_dir, not zeek_dir,
+    and the positional scopes the run so siblings stay None."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    ct_file = tmp_path / "cloudtrail_2026.json.log"
+    ct_file.write_text("", encoding="utf-8")
+
+    cli._run_single_detector("aws", [str(ct_file)])
+
+    assert captured["detect"] == "aws"
+    # CLI now passes raw strings; the resolver owns Path conversion.
+    assert captured["cloudtrail_dir"] == str(ct_file)
+    assert captured["zeek_dir"] is None
+    assert captured["syslog_dir"] is None
+    assert captured["pihole_dir"] is None
+    # scope rail: positional scopes the run to its routed source.
+    assert captured["scope"] == frozenset({"cloudtrail_dir"})
+
+
+# The four source-dir `_tilde_expands` tests were DELETED. ~-expansion of
+# explicit overrides now happens inside common.sources._resolve_one (the
+# sole site for string→Path conversion), tested directly at
+# tests/test_sources.py:test_resolve_sources_tilde_override_expands.
+#
+# The end-to-end `aws ~/path` CLI test is preserved as a seam-style
+# dry-run test in tests/test_source_resolution_seam.py (stage 5).
+
+
+def test_runner_kwargs_out_tilde_expands_and_preserves_trailing_slash(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """--out=~/reports/ must expand ~ AND preserve the trailing slash that
+    be_like_water needs to fire the directory-intent gate."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+    captured: dict[str, str] = {}
+
+    def fake_be_like_water(target: str):
+        captured["target"] = target
+        from types import SimpleNamespace
+        return SimpleNamespace(is_file=False, path=Path(target))
+
+    monkeypatch.setattr("loghunter.cli.be_like_water", fake_be_like_water)
+
+    _runner_kwargs({"out": "~/reports/"}, config={})
+
+    assert captured["target"] == f"{tmp_path}/reports/"
+    assert captured["target"].endswith("/")
+    assert "~" not in captured["target"]
+
+
+# The end-to-end ``aws ~/path`` CLI test (~-positional routes to
+# cloudtrail_dir AND expands ~) moved to tests/test_source_resolution_seam.py
+# as a real CLI dry-run seam test. ~-expansion now happens inside
+# common.sources._resolve_one, not at the CLI seam.
+
+
+# Analyze positional → named-detector-source routing.
+#
+# Replaces the deleted wrong-source "hint" scold and its five silence tests
+# (the scold became meaningless once `route_positional_source` does the right
+# thing on its own). The router itself is unit-tested in
+# tests/test_sources.py — this test pins the CLI seam wiring: the positional
+# lands on the detector's REQUIRED_LOGS source and the scope rail keeps
+# siblings unloaded.
+
+def test_analyze_positional_reroutes_to_named_detector_source(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """``loghunter --detect=aws PATH`` routes the positional to cloudtrail_dir
+    (the detector's REQUIRED_LOGS source) and the scope rail keeps siblings
+    None — even with a config that sets zeek_dir."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+    monkeypatch.setattr("loghunter.runner.run", lambda **kw: captured.update(kw))
+    monkeypatch.setattr(cfg, "load", lambda _=None: {
+        "loghunter": {"zeek_dir": str(tmp_path / "should-not-be-loaded")},
+    })
+
+    fake_path = tmp_path / "events.json.log"
+    fake_path.write_text("", encoding="utf-8")
+    cli._run_all_detectors([f"--detect=aws", str(fake_path)])
+
+    assert captured["cloudtrail_dir"] == str(fake_path)
+    assert captured["zeek_dir"] is None
+    assert captured["scope"] == frozenset({"cloudtrail_dir"})
+
+
+# ── top-level KeyboardInterrupt handler ──────────────────────────────────────
+#
+# Two Ctrl-C moments coexist:
+#   1. mid-run (load, detect, digest, export compute) → cli.main()'s new arm
+#      prints "Stopped." to stderr and exits 130.
+#   2. at the records-found "Continue? [y/N]" prompt in runner.py → the
+#      existing (EOFError, KeyboardInterrupt) handler raises ExportAborted,
+#      which cli.main() catches and exits 0 with the "aborted by user"
+#      message on stdout. Locking both halves prevents a future refactor
+#      from collapsing them.
+
+
+def _write_tiny_zeek_dir(tmp_path: Path) -> Path:
+    """Write a two-row flat Zeek conn.log just rich enough to load.
+
+    Kept local to this module so test_config_cli stays independent of
+    test_runner's fixture helpers.
+    """
+    import json
+    from datetime import datetime, timezone
+
+    zeek_dir = tmp_path / "zeek"
+    zeek_dir.mkdir()
+    rows = [
+        {
+            "ts": datetime(2026, 1, 1, tzinfo=timezone.utc).timestamp(),
+            "id.orig_h": "192.0.2.10",
+            "id.resp_h": "198.51.100.20",
+            "id.resp_p": 443,
+            "proto": "tcp",
+        },
+        {
+            "ts": datetime(2026, 1, 5, tzinfo=timezone.utc).timestamp(),
+            "id.orig_h": "192.0.2.10",
+            "id.resp_h": "198.51.100.20",
+            "id.resp_p": 443,
+            "proto": "tcp",
+        },
+    ]
+    (zeek_dir / "conn.log").write_text(
+        "\n".join(json.dumps(r) for r in rows) + "\n", encoding="utf-8"
+    )
+    return zeek_dir
+
+
+def test_cli_top_level_keyboard_interrupt_exits_cleanly(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Ctrl-C during compute work → 'Stopped.' on stderr, exit 130, no traceback.
+
+    Non-TTY stderr (capsys's captured stream) — byte-exact "Stopped.\\n", no
+    leading blank line. Script/log capture must see the same string today and
+    after the TTY-only blank-line polish.
+    """
+    def _raise_kbd(_argv=None):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(cli, "_main", _raise_kbd)
+
+    with pytest.raises(SystemExit) as exc_info:
+        cli.main([])
+
+    assert exc_info.value.code == 130
+    captured = capsys.readouterr()
+    assert captured.err == "Stopped.\n"
+    assert "Traceback" not in captured.err
+    assert "Traceback" not in captured.out
+    # Sanity: this is the new path, not the prompt-cancel path.
+    assert "aborted by user" not in captured.err
+    assert "aborted by user" not in captured.out
+
+
+def test_cli_top_level_keyboard_interrupt_prepends_blank_line_on_tty(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Ctrl-C on a TTY → leading blank line so terminal '^C' echo does not
+    glue to 'Stopped.' on one row. The cli is the only place that sees this
+    discipline; runner liveness narration handles its own clears."""
+    def _raise_kbd(_argv=None):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr(cli, "_main", _raise_kbd)
+    # capsys swaps sys.stderr; force its isatty() to True for this run.
+    monkeypatch.setattr(sys.stderr, "isatty", lambda: True)
+
+    with pytest.raises(SystemExit) as exc_info:
+        cli.main([])
+
+    assert exc_info.value.code == 130
+    captured = capsys.readouterr()
+    assert captured.err == "\nStopped.\n"
+
+
+def test_cli_keyboard_interrupt_at_confirm_prompt_still_exit_zero(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+) -> None:
+    """Ctrl-C AT the records-found prompt → ExportAborted → exit 0, NOT Stopped./130.
+
+    Drives cli.main() end-to-end to lock the user-visible CLI behavior:
+    --warn-above is not threaded by _runner_kwargs, so we inject it via
+    cfg.load() the same way test_cloudtrail_exporter.py:794 does.
+    """
+    zeek_dir = _write_tiny_zeek_dir(tmp_path)
+
+    def _fake_load(_path=None):
+        return {
+            "loghunter": {
+                "detect": "beacon",
+                "warn_above": 1,
+                "default_window": "all",
+            }
+        }
+
+    monkeypatch.setattr(cfg, "load", _fake_load)
+
+    def _kbd(*_a, **_kw):
+        raise KeyboardInterrupt
+
+    monkeypatch.setattr("builtins.input", _kbd)
+
+    with pytest.raises(SystemExit) as exc_info:
+        cli.main(["beacon", f"--zeek-dir={zeek_dir}"])
+
+    assert exc_info.value.code == 0
+    captured = capsys.readouterr()
+    # ExportAborted prints to stdout via cli.main()'s existing arm.
+    assert "aborted by user" in captured.out
+    # The new top-level path must NOT have fired here.
+    assert "Stopped." not in captured.err
+    assert "Stopped." not in captured.out
+
+
+# ── Single-detector positional routing: syslog (v1 promotion) ────────────────
+#
+# Glenn rev-1 required tests. The syslog detector's REQUIRED_LOGS is now
+# empty (dns shape), so _source_for_single_detector_path falls through to
+# OPTIONAL_LOGS pattern matching — and `syslog.log` matches BOTH `*.log*`
+# AND `syslog*.log*`, which previously routed to the zeek_dir default.
+# That regresses flat-syslog. The fix special-cases syslog: directories
+# default to syslog_dir (preserves /var/log convention), files content-sniff
+# (Zeek-origin → zeek_dir, anything else → syslog_dir).
+
+def test_syslog_positional_flat_file_routes_to_syslog_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """A flat RFC 3164 syslog file routes to syslog_dir via content-sniff."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    flat_file = tmp_path / "auth.log"
+    flat_file.write_text(
+        "<134>Jun 11 12:00:00 host1 sshd[1234]: Accepted publickey for user\n",
+        encoding="utf-8",
+    )
+
+    cli._run_single_detector("syslog", [str(flat_file)])
+
+    assert captured["detect"] == "syslog"
+    assert captured["syslog_dir"] == str(flat_file)
+    # Scope rail: positional routes ONE source; siblings stay None.
+    assert captured["zeek_dir"] is None
+    assert captured["scope"] == frozenset({"syslog_dir"})
+
+
+def test_syslog_positional_directory_routes_to_syslog_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """A directory positional preserves the /var/log flat-syslog convention.
+
+    Without the special-case, _source_for_single_detector_path's directory
+    branch would default to zeek_dir — wrong for the historical syslog flow.
+    """
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    log_dir = tmp_path / "log"
+    log_dir.mkdir()
+    (log_dir / "auth.log").write_text(
+        "<134>Jun 11 12:00:00 host1 sshd[1234]: ok\n",
+        encoding="utf-8",
+    )
+
+    cli._run_single_detector("syslog", [str(log_dir)])
+
+    assert captured["syslog_dir"] == str(log_dir)
+    assert captured["zeek_dir"] is None
+    assert captured["scope"] == frozenset({"syslog_dir"})
+
+
+def test_syslog_positional_zeek_tsv_file_routes_to_zeek_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """A Zeek-TSV syslog.log positional content-sniffs to zeek_dir.
+
+    Filename `syslog.log` matches BOTH OPTIONAL_LOGS patterns — disambiguation
+    happens via content sniff (sniff_format_detailed), the same machinery the
+    digest verb uses. Zeek-origin → zeek_dir.
+    """
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    zeek_file = tmp_path / "syslog.log"
+    zeek_file.write_text(
+        "#separator \\x09\n"
+        "#set_separator\t,\n"
+        "#empty_field\t(empty)\n"
+        "#unset_field\t-\n"
+        "#path\tsyslog\n"
+        "#fields\tts\tuid\tid.orig_h\tmessage\n"
+        "#types\ttime\tstring\taddr\tstring\n"
+        "1779750000.000000\tCSL01\t192.0.2.10\thello\n",
+        encoding="utf-8",
+    )
+
+    cli._run_single_detector("syslog", [str(zeek_file)])
+
+    assert captured["zeek_dir"] == str(zeek_file)
+    assert captured["syslog_dir"] is None
+    assert captured["scope"] == frozenset({"zeek_dir"})
+
+
+def test_syslog_positional_zeek_ndjson_file_routes_to_zeek_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """The NDJSON Zeek front-end also content-sniffs to zeek_dir."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    zeek_file = tmp_path / "syslog.log"
+    zeek_file.write_text(
+        '{"_path":"syslog","ts":1779750000.0,"uid":"CSL01",'
+        '"id.orig_h":"192.0.2.10","id.resp_h":"198.51.100.20",'
+        '"id.resp_p":514,"proto":"udp","facility":"DAEMON","severity":"INFO",'
+        '"message":"Jun 11 12:00:00 host1 sshd[1234]: ok"}\n',
+        encoding="utf-8",
+    )
+
+    cli._run_single_detector("syslog", [str(zeek_file)])
+
+    assert captured["zeek_dir"] == str(zeek_file)
+    assert captured["syslog_dir"] is None
+    assert captured["scope"] == frozenset({"zeek_dir"})
+
+
+def test_syslog_positional_unrecognized_file_routes_to_syslog_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """A file the sniffer cannot identify as a Zeek syslog.log falls to the
+    flat-syslog default (syslog_dir). Mirrors the "directory defaults to
+    flat" convention."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    mystery = tmp_path / "mystery.log"
+    mystery.write_text("lorem ipsum dolor\nsit amet\n", encoding="utf-8")
+
+    cli._run_single_detector("syslog", [str(mystery)])
+
+    assert captured["syslog_dir"] == str(mystery)
+    assert captured["zeek_dir"] is None
+    assert captured["scope"] == frozenset({"syslog_dir"})
+
+
+def test_syslog_positional_missing_file_does_not_leak_traceback(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """Glenn caution #1: a missing/unreadable positional must not leak a raw
+    traceback through _source_for_single_detector_path's sniff call. The
+    routing degrades to syslog_dir; the runner's actual file-discovery
+    produces the canonical "not found" error downstream."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+
+    # Patch runner.run so we exit cleanly before the runner tries to read.
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    ghost = tmp_path / "does-not-exist.log"
+
+    # No OSError must propagate from the routing layer itself.
+    cli._run_single_detector("syslog", [str(ghost)])
+
+    # Degrades to syslog_dir per the convention.
+    assert captured["syslog_dir"] == str(ghost)
+    assert captured["scope"] == frozenset({"syslog_dir"})
+
+
+def test_syslog_positional_zeek_ndjson_without_path_routes_to_zeek_dir(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """P1 regression (Glenn bug handoff): a Zeek-NDJSON syslog.log emitted
+    without the `_path` directive must still content-sniff to Zeek and route
+    to zeek_dir. Pre-fix, the conn field-set fallback grabbed it and the
+    positional landed at syslog_dir, leaving load_syslog with an empty frame."""
+    monkeypatch.setattr(cfg, "SEARCH_PATHS", [])
+    captured: dict[str, object] = {}
+
+    def fake_run(**kwargs: object) -> None:
+        captured.update(kwargs)
+
+    monkeypatch.setattr("loghunter.runner.run", fake_run)
+    zeek_file = tmp_path / "syslog.log"
+    zeek_file.write_text(
+        # Note: NO _path directive — exactly the upstream-agent shape that
+        # triggered the original misroute.
+        '{"ts":1779750000.0,"uid":"CSL01",'
+        '"id.orig_h":"192.0.2.10","id.orig_p":41514,'
+        '"id.resp_h":"198.51.100.20","id.resp_p":514,'
+        '"proto":"udp","facility":"DAEMON","severity":"INFO",'
+        '"message":"Jun 11 12:00:00 host1 sshd[1234]: placeholder"}\n',
+        encoding="utf-8",
+    )
+
+    cli._run_single_detector("syslog", [str(zeek_file)])
+
+    assert captured["zeek_dir"] == str(zeek_file)
+    assert captured["syslog_dir"] is None
+    assert captured["scope"] == frozenset({"zeek_dir"})