feat: implement OpsBridge CLI (BRIDGE-WP-0001)

Full TDD implementation of the `bridge` CLI tool covering all phases
from BRIDGE-WP-0001: project scaffolding, config loading, state
management, audit logging, health checks, tunnel lifecycle manager, and
all CLI commands (up/down/restart/status/logs). 77 tests, all green.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

tests/test_cli.py

@@ -0,0 +1,201 @@
+"""Tests for CLI commands."""
+import json
+import os
+import textwrap
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from bridge.cli import app
+
+
+VALID_CONFIG = textwrap.dedent("""\
+    tunnels:
+      test-tunnel:
+        host: host.local
+        remote_port: 18000
+        local_port: 8000
+        ssh_user: ubuntu
+        ssh_key: ~/.ssh/id_ops
+        actor: operator.bernd
+    actors:
+      operator.bernd:
+        class: human
+        description: Bernd
+""")
+
+runner = CliRunner()
+
+
+@pytest.fixture
+def config_file(tmp_path):
+    f = tmp_path / "tunnels.yaml"
+    f.write_text(VALID_CONFIG)
+    return f
+
+
+@pytest.fixture
+def state_dir(tmp_path):
+    return tmp_path / "state"
+
+
+@pytest.fixture
+def env(config_file, state_dir):
+    return {"BRIDGE_CONFIG": str(config_file), "BRIDGE_STATE_DIR": str(state_dir)}
+
+
+class TestHelpCommand:
+    def test_app_help(self):
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        assert "bridge" in result.output.lower() or "Usage" in result.output
+
+    def test_up_help(self):
+        result = runner.invoke(app, ["up", "--help"])
+        assert result.exit_code == 0
+
+    def test_down_help(self):
+        result = runner.invoke(app, ["down", "--help"])
+        assert result.exit_code == 0
+
+    def test_status_help(self):
+        result = runner.invoke(app, ["status", "--help"])
+        assert result.exit_code == 0
+
+    def test_logs_help(self):
+        result = runner.invoke(app, ["logs", "--help"])
+        assert result.exit_code == 0
+
+    def test_restart_help(self):
+        result = runner.invoke(app, ["restart", "--help"])
+        assert result.exit_code == 0
+
+
+class TestStatusCommand:
+    def test_status_shows_tunnels(self, env, state_dir):
+        result = runner.invoke(app, ["status"], env=env)
+        assert result.exit_code == 0
+        assert "test-tunnel" in result.output
+
+    def test_status_json_flag(self, env, state_dir):
+        result = runner.invoke(app, ["status", "--json"], env=env)
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert isinstance(data, list)
+        assert len(data) == 1
+        assert data[0]["tunnel"] == "test-tunnel"
+        assert "state" in data[0]
+        assert "actor" in data[0]
+        assert "host" in data[0]
+
+    def test_status_shows_state(self, env, state_dir):
+        result = runner.invoke(app, ["status"], env=env)
+        assert result.exit_code == 0
+        assert "stopped" in result.output.lower()
+
+    def test_status_unknown_config_exit_1(self, tmp_path):
+        result = runner.invoke(app, ["status"], env={"BRIDGE_CONFIG": str(tmp_path / "no.yaml")})
+        assert result.exit_code == 1
+
+
+class TestUpCommand:
+    def test_up_unknown_tunnel_exit_1(self, env):
+        result = runner.invoke(app, ["up", "nonexistent"], env=env)
+        assert result.exit_code == 1
+        assert "nonexistent" in result.output
+
+    def test_up_calls_manager_start(self, env, state_dir):
+        with patch("bridge.cli.TunnelManager") as mock_mgr_cls:
+            mock_mgr = MagicMock()
+            mock_mgr.is_running.return_value = False
+            mock_mgr_cls.return_value = mock_mgr
+
+            result = runner.invoke(app, ["up", "test-tunnel"], env=env)
+
+        assert result.exit_code == 0
+        mock_mgr.start.assert_called_once()
+
+    def test_up_already_running_exit_2(self, env, state_dir):
+        with patch("bridge.cli.TunnelManager") as mock_mgr_cls:
+            mock_mgr = MagicMock()
+            mock_mgr.is_running.return_value = True
+            mock_mgr_cls.return_value = mock_mgr
+
+            result = runner.invoke(app, ["up", "test-tunnel"], env=env)
+
+        assert result.exit_code == 2
+
+
+class TestDownCommand:
+    def test_down_unknown_tunnel_exit_1(self, env):
+        result = runner.invoke(app, ["down", "nonexistent"], env=env)
+        assert result.exit_code == 1
+
+    def test_down_calls_manager_stop(self, env, state_dir):
+        with patch("bridge.cli.TunnelManager") as mock_mgr_cls:
+            mock_mgr = MagicMock()
+            mock_mgr.is_running.return_value = True
+            mock_mgr_cls.return_value = mock_mgr
+
+            result = runner.invoke(app, ["down", "test-tunnel"], env=env)
+
+        assert result.exit_code == 0
+        mock_mgr.stop.assert_called_once()
+
+    def test_down_not_running_exit_2(self, env, state_dir):
+        with patch("bridge.cli.TunnelManager") as mock_mgr_cls:
+            mock_mgr = MagicMock()
+            mock_mgr.is_running.return_value = False
+            mock_mgr_cls.return_value = mock_mgr
+
+            result = runner.invoke(app, ["down", "test-tunnel"], env=env)
+
+        assert result.exit_code == 2
+
+
+class TestLogsCommand:
+    def test_logs_unknown_tunnel_exit_1(self, env):
+        result = runner.invoke(app, ["logs", "nonexistent"], env=env)
+        assert result.exit_code == 1
+
+    def test_logs_no_log_file_shows_empty(self, env, state_dir):
+        result = runner.invoke(app, ["logs", "test-tunnel"], env=env)
+        assert result.exit_code == 0
+
+    def test_logs_shows_events(self, env, state_dir):
+        import json as _json
+        state_dir.mkdir(parents=True, exist_ok=True)
+        log_file = state_dir / "test-tunnel.log"
+        log_file.write_text(
+            _json.dumps({
+                "timestamp": "2026-01-01T00:00:00+00:00",
+                "tunnel": "test-tunnel",
+                "actor": "operator.bernd",
+                "actor_class": "human",
+                "event": "bridge_started",
+            }) + "\n"
+        )
+        result = runner.invoke(app, ["logs", "test-tunnel"], env=env)
+        assert result.exit_code == 0
+        assert "bridge_started" in result.output
+
+
+class TestRestartCommand:
+    def test_restart_unknown_tunnel_exit_1(self, env):
+        result = runner.invoke(app, ["restart", "nonexistent"], env=env)
+        assert result.exit_code == 1
+
+    def test_restart_calls_stop_then_start(self, env):
+        with patch("bridge.cli.TunnelManager") as mock_mgr_cls:
+            mock_mgr = MagicMock()
+            mock_mgr_cls.return_value = mock_mgr
+            call_order = []
+            mock_mgr.stop.side_effect = lambda: call_order.append("stop")
+            mock_mgr.start.side_effect = lambda: call_order.append("start")
+
+            result = runner.invoke(app, ["restart", "test-tunnel"], env=env)
+
+        assert result.exit_code == 0
+        assert call_order == ["stop", "start"]