fvpnctl 0.2.2__tar.gz → 0.2.4__tar.gz

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fvpnctl
-Version: 0.2.2
+Version: 0.2.4
 Summary: Control your FortiClient VPN from the macOS command line.
 Project-URL: Homepage, https://github.com/mpasternak/fortivpn-cli
 Project-URL: Repository, https://github.com/mpasternak/fortivpn-cli
@@ -224,6 +224,9 @@ Global options:
 - `--verbose` / `--quiet` — progress messages. Verbose is **on by default** and writes
   progress to **stderr**; `--quiet` silences it. Either way `stdout` carries only the
   machine-readable result, so `--json` output and shell pipelines are byte-identical.
+  While `connect` waits for the tunnel (it polls once a second), verbose mode shows a
+  Braille throbber with an elapsed-seconds counter on a TTY, falls back to a single
+  static line when stderr is piped or redirected, and shows nothing under `--quiet`.
 
 `list` and `status` additionally accept `--json` for machine-readable output.
 
@@ -333,15 +336,38 @@ tray for you (without quitting the app) — best effort, so a failure to hide ne
 otherwise-successful connect. Pass `--show-window` to keep the window up. (This only applies
 in the waited path; with `--no-wait` the popup happens after the command returns.)
 
-### `fvpnctl disconnect <profile>`
+While it waits, `connect` shows live progress on a TTY (verbose mode). The **first** time you
+connect a profile there is no timing history, so it shows an indeterminate Braille throbber
+with an elapsed-seconds counter. fvpnctl records how long each successful connect took (per
+profile, the last 10 runs, under `~/.local/state/fvpnctl/` — overridable with
+`$FVPNCTL_STATE_DIR`), so on **subsequent** connects it shows a **progress bar** that fills
+toward the average of those past durations:
 
-Disconnect an IPsec profile.
+```console
+$ fvpnctl connect office
+Connecting profile office…  [█████████████░░░░░░░░░░░] 54%  7s / ~13s
+```
+
+The bar never claims 100% until the tunnel is actually up, and the `7s / ~13s` tail stays
+honest if a connect runs longer than usual. Piped/redirected output falls back to a single
+static line, and `--quiet` shows nothing.
+
+### `fvpnctl disconnect [profile]`
+
+Disconnect a tunnel. The **profile argument is optional**: with no argument `disconnect`
+tears down whatever is connected right now (it reads the active connection from the daemon),
+so you don't have to remember which profile is up. Pass a name to target a specific profile.
 
 ```console
-$ fvpnctl disconnect office
+$ fvpnctl disconnect          # disconnect the active tunnel
+DISCONNECTED office
+$ fvpnctl disconnect office   # or name it explicitly
 DISCONNECTED office
 ```
 
+If nothing is connected, `disconnect` says so and exits `0` (the desired end state already
+holds), so it is safe to run unconditionally in scripts.
+
 ### `fvpnctl ip`
 
 Print just the assigned tunnel IP — handy in scripts. Exits `1` with a message on stderr if

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/README.md

@@ -200,6 +200,9 @@ Global options:
 - `--verbose` / `--quiet` — progress messages. Verbose is **on by default** and writes
   progress to **stderr**; `--quiet` silences it. Either way `stdout` carries only the
   machine-readable result, so `--json` output and shell pipelines are byte-identical.
+  While `connect` waits for the tunnel (it polls once a second), verbose mode shows a
+  Braille throbber with an elapsed-seconds counter on a TTY, falls back to a single
+  static line when stderr is piped or redirected, and shows nothing under `--quiet`.
 
 `list` and `status` additionally accept `--json` for machine-readable output.
 
@@ -309,15 +312,38 @@ tray for you (without quitting the app) — best effort, so a failure to hide ne
 otherwise-successful connect. Pass `--show-window` to keep the window up. (This only applies
 in the waited path; with `--no-wait` the popup happens after the command returns.)
 
-### `fvpnctl disconnect <profile>`
+While it waits, `connect` shows live progress on a TTY (verbose mode). The **first** time you
+connect a profile there is no timing history, so it shows an indeterminate Braille throbber
+with an elapsed-seconds counter. fvpnctl records how long each successful connect took (per
+profile, the last 10 runs, under `~/.local/state/fvpnctl/` — overridable with
+`$FVPNCTL_STATE_DIR`), so on **subsequent** connects it shows a **progress bar** that fills
+toward the average of those past durations:
 
-Disconnect an IPsec profile.
+```console
+$ fvpnctl connect office
+Connecting profile office…  [█████████████░░░░░░░░░░░] 54%  7s / ~13s
+```
+
+The bar never claims 100% until the tunnel is actually up, and the `7s / ~13s` tail stays
+honest if a connect runs longer than usual. Piped/redirected output falls back to a single
+static line, and `--quiet` shows nothing.
+
+### `fvpnctl disconnect [profile]`
+
+Disconnect a tunnel. The **profile argument is optional**: with no argument `disconnect`
+tears down whatever is connected right now (it reads the active connection from the daemon),
+so you don't have to remember which profile is up. Pass a name to target a specific profile.
 
 ```console
-$ fvpnctl disconnect office
+$ fvpnctl disconnect          # disconnect the active tunnel
+DISCONNECTED office
+$ fvpnctl disconnect office   # or name it explicitly
 DISCONNECTED office
 ```
 
+If nothing is connected, `disconnect` says so and exits `0` (the desired end state already
+holds), so it is safe to run unconditionally in scripts.
+
 ### `fvpnctl ip`
 
 Print just the assigned tunnel IP — handy in scripts. Exits `1` with a message on stderr if

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fvpnctl"
-version = "0.2.2"
+version = "0.2.4"
 requires-python = ">=3.11"
 readme = "README.md"
 description = "Control your FortiClient VPN from the macOS command line."

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/src/fvpnctl/__init__.py

@@ -1,3 +1,3 @@
 """fvpnctl — control FortiClient IPsec VPN on macOS via the Chrome DevTools Protocol."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/src/fvpnctl/cli.py

@@ -62,16 +62,19 @@ import argparse
 import json
 import os
 import sys
+import time
 
-from fvpnctl import launcher, monitor
+from fvpnctl import history, launcher, monitor
 from fvpnctl.cdp import CDPSession
 from fvpnctl.controller import FortiVPN
 from fvpnctl.errors import CDPEvaluateError, FortiError, NotRunningError
+from fvpnctl.spinner import ProgressBar, Spinner
 
-# IPsec ``ipsec_state`` value meaning "tunnel up" (docs/how-it-works.md section 2
-# / design spec 4.2). The CLI only needs the CONNECTED sentinel; the controller
-# owns the full enum.
+# IPsec ``ipsec_state`` values the CLI needs as sentinels (docs/how-it-works.md
+# section 2 / design spec 4.2). The controller owns the full enum; the CLI only
+# compares against "tunnel up" and "tunnel fully down".
 _CONNECTED = 2
+_DISCONNECTED = 0
 
 # Connection type for v1. Only IPsec is supported (SSL is out of scope); the CLI
 # always queries/derives with this type. See design spec section 2.
@@ -214,8 +217,23 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p_connect.set_defaults(func=_cmd_connect)
 
-    p_disconnect = sub.add_parser("disconnect", parents=[common], help="Disconnect a profile.")
-    p_disconnect.add_argument("profile", help="The profile (connection_name) to disconnect.")
+    p_disconnect = sub.add_parser(
+        "disconnect",
+        parents=[common],
+        help="Disconnect the active tunnel (or a named profile).",
+        description=(
+            "Disconnect the currently active tunnel. The profile argument is "
+            "optional: with no argument it disconnects whatever is connected now "
+            "(read from the daemon's reported connection); pass a name to target a "
+            "specific profile."
+        ),
+    )
+    p_disconnect.add_argument(
+        "profile",
+        nargs="?",
+        default=None,
+        help="The profile (connection_name) to disconnect (default: the active one).",
+    )
     p_disconnect.set_defaults(func=_cmd_disconnect)
 
     p_ip = sub.add_parser(
@@ -364,21 +382,48 @@ def _cmd_connect(fvpnctl: FortiVPN, args: argparse.Namespace) -> int:
     and returns; otherwise, on a CONNECTED terminal state, it fetches the VPN IP
     and prints ``CONNECTED <profile> <ip>``. The password is resolved inside the
     controller (from the Keychain) and is never accepted or printed here.
+
+    The waited path blocks in the controller's once-a-second poll loop while the
+    daemon negotiates, which otherwise looks frozen — so it is wrapped in a live
+    indicator on stderr (a single static line when piped, nothing under
+    ``--quiet``; gated by ``_VERBOSE`` exactly like :func:`report`). When this
+    profile has connect-time history a :class:`~fvpnctl.spinner.ProgressBar`
+    fills toward the mean past duration (the ETA); with no history yet it falls
+    back to the indeterminate :class:`~fvpnctl.spinner.Spinner` throbber. Each
+    successful waited connect's wall-clock time is recorded so the *next* connect
+    can show the bar. ``--no-wait`` returns immediately, so it keeps the plain
+    progress line instead.
     """
     wait = not args.no_wait
-    report(f"Connecting profile {args.profile}…")
-    state = fvpnctl.connect(
-        args.profile,
-        username=args.user,
-        wait=wait,
-        timeout=args.timeout,
-    )
+    msg = f"Connecting profile {args.profile}…"
 
     if not wait:
+        report(msg)
+        fvpnctl.connect(args.profile, username=args.user, wait=False, timeout=args.timeout)
         print(f"connecting {args.profile} ...")
         return 0
 
+    eta = _connect_eta(args.profile)
+    indicator = (
+        ProgressBar(msg, eta, stream=sys.stderr, enabled=_VERBOSE)
+        if eta is not None
+        else Spinner(msg, stream=sys.stderr, enabled=_VERBOSE)
+    )
+
+    start = time.monotonic()
+    with indicator:
+        state = fvpnctl.connect(
+            args.profile,
+            username=args.user,
+            wait=True,
+            timeout=args.timeout,
+        )
+    elapsed = time.monotonic() - start
+
     if state.ipsec_state == _CONNECTED:
+        # Record the duration only on a successful waited connect — that is what
+        # the user actually waited through and what the next ETA should average.
+        _record_connect_time(args.profile, elapsed)
         ip = fvpnctl.connection_ip(args.profile, _IPSEC)
         vpn_ip = ip.get("vpn_ip", "")
         # FortiClient pops its window on connect even under --hide-gui; hide it
@@ -386,7 +431,7 @@ def _cmd_connect(fvpnctl: FortiVPN, args: argparse.Namespace) -> int:
         # waited path: with --no-wait the popup happens after we return.
         if not args.show_window:
             _hide_window_best_effort(fvpnctl)
-        report(f"Connected: {vpn_ip}")
+        report(f"Connected: {vpn_ip} (in {elapsed:.0f}s)")
         print(f"CONNECTED {args.profile} {vpn_ip}")
     else:
         # Reached here only with wait=True and a non-connected terminal state the
@@ -396,10 +441,51 @@ def _cmd_connect(fvpnctl: FortiVPN, args: argparse.Namespace) -> int:
     return 0
 
 
+def _connect_eta(profile: str) -> float | None:
+    """Mean past connect time for ``profile`` (None ⇒ show the throbber instead).
+
+    Reads :func:`history.average`. The history is a best-effort UX aid: a missing,
+    corrupt, or unreadable store must never block a connect, so any
+    ``OSError``/``ValueError`` is reported (when verbose) and treated as "no ETA"
+    — the CLI then uses the indeterminate spinner.
+    """
+    try:
+        return history.average(profile)
+    except (OSError, ValueError) as e:
+        report(f"(connect-time history unavailable: {e})")
+        return None
+
+
+def _record_connect_time(profile: str, seconds: float) -> None:
+    """Persist this connect's duration; report and continue if it can't be saved.
+
+    A failed write (corrupt store, read-only dir) must not undo a connect that
+    already succeeded, so the error is surfaced (when verbose) and swallowed here.
+    """
+    try:
+        history.record(profile, seconds)
+    except (OSError, ValueError) as e:
+        report(f"(could not save connect time: {e})")
+
+
 def _cmd_disconnect(fvpnctl: FortiVPN, args: argparse.Namespace) -> int:
-    """``fvpnctl disconnect <profile>`` — tear down the tunnel and confirm."""
-    fvpnctl.disconnect(args.profile)
-    print(f"DISCONNECTED {args.profile}")
+    """``fvpnctl disconnect [profile]`` — tear down a tunnel and confirm.
+
+    With no ``profile`` it disconnects whatever is active: it reads ``state()``
+    and uses the daemon's reported ``connection_name``. If nothing is active it
+    says so and returns 0 — the desired end state (disconnected) already holds, so
+    ``fvpnctl disconnect`` is idempotent. An explicit ``profile`` is still honored
+    (and still works even if the daemon reports a different/empty active name).
+    """
+    profile = args.profile
+    if profile is None:
+        state = fvpnctl.state()
+        if state.ipsec_state == _DISCONNECTED or not state.name:
+            print("No active tunnel to disconnect.", file=sys.stderr)
+            return 0
+        profile = state.name
+    fvpnctl.disconnect(profile)
+    print(f"DISCONNECTED {profile}")
     return 0
 
 

fvpnctl-0.2.4/src/fvpnctl/history.py

@@ -0,0 +1,129 @@
+"""Connect-time history — per-profile durations that feed the progress bar.
+
+What this is
+------------
+``fvpnctl connect`` blocks while the daemon negotiates the tunnel. The first time
+a profile is connected there is nothing to estimate against, so the CLI shows an
+indeterminate Braille throbber (``spinner.Spinner``). Every *successful* waited
+connect records its wall-clock duration here; on the next connect the CLI reads
+back the mean of the recent samples and shows a **determinate progress bar**
+(``spinner.ProgressBar``) that fills toward that ETA.
+
+Why per-profile, why a recent window
+------------------------------------
+Different gateways have very different handshake times, so durations are keyed by
+``connection_name``. Only the last :data:`_HISTORY_LEN` samples are kept and
+averaged, so the estimate tracks *current* network conditions instead of being
+dragged by months-old measurements.
+
+Where it lives
+--------------
+A small JSON file under the per-user XDG *state* dir (these are derived numbers
+fvpnctl can always rebuild — state, not config). The location is resolved by
+:func:`state_dir`; ``$FVPNCTL_STATE_DIR`` overrides everything (the test suite
+points it at a tmp dir so it never touches real user state).
+
+Error policy (project rule: never swallow silently)
+---------------------------------------------------
+A *missing* file is the normal first-run case and yields an empty history — not
+an error. A *corrupt* file makes :func:`load`/:func:`average` raise ``ValueError``
+so the CLI can surface it (``cli._connect_eta`` reports it and falls back to the
+throbber). :func:`record` additionally self-heals a corrupt file rather than
+failing a connect that just succeeded — the one place a narrow catch is justified.
+"""
+
+import json
+import os
+from pathlib import Path
+
+# Keep at most this many recent measurements per profile; the progress-bar ETA is
+# their mean. A recent window (not all-time) so the estimate adapts to changing
+# network conditions.
+_HISTORY_LEN = 10
+
+_FILENAME = "connect-durations.json"
+
+
+def state_dir() -> Path:
+    """Resolve the directory holding fvpnctl's persistent state.
+
+    Order: ``$FVPNCTL_STATE_DIR`` (explicit override; used by the tests), then
+    ``$XDG_STATE_HOME/fvpnctl``, else ``~/.local/state/fvpnctl``.
+    """
+    override = os.environ.get("FVPNCTL_STATE_DIR")
+    if override:
+        return Path(override).expanduser()
+    xdg = os.environ.get("XDG_STATE_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".local" / "state"
+    return base / "fvpnctl"
+
+
+def _path() -> Path:
+    return state_dir() / _FILENAME
+
+
+def load() -> dict[str, list]:
+    """Load the per-profile duration history.
+
+    :returns: the raw ``{profile: [seconds, ...]}`` mapping (``{}`` when no file
+        exists yet — the normal first-run case).
+    :raises ValueError: the file exists but is not valid JSON, or is valid JSON of
+        the wrong shape (``json.JSONDecodeError`` is a ``ValueError`` subclass).
+        Callers surface this rather than mask it.
+    """
+    try:
+        raw = _path().read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return {}
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError(f"{_path()} is not a JSON object")
+    return data
+
+
+def average(profile: str) -> float | None:
+    """Mean recorded connect duration for ``profile`` — the progress-bar ETA.
+
+    :returns: the mean of the stored samples, or ``None`` when the profile has no
+        usable history yet. Non-numeric stray entries are ignored defensively so a
+        single bad value never breaks the estimate.
+    :raises ValueError: if the underlying store is corrupt (propagated from
+        :func:`load`).
+    """
+    samples = [float(x) for x in load().get(profile, []) if isinstance(x, (int, float))]
+    if not samples:
+        return None
+    return sum(samples) / len(samples)
+
+
+def record(profile: str, seconds: float) -> None:
+    """Append one connect duration for ``profile`` and persist (keep last N).
+
+    :raises OSError: if the store cannot be written (caller decides whether to
+        surface or ignore — a failed write must never undo a successful connect).
+    """
+    try:
+        data = load()
+    except ValueError:
+        # A corrupt history file is non-critical: reset rather than fail the
+        # connect that just succeeded. This measurement re-creates a valid file.
+        data = {}
+    samples = data.get(profile)
+    if not isinstance(samples, list):
+        samples = []
+    samples.append(round(float(seconds), 1))
+    data[profile] = samples[-_HISTORY_LEN:]
+    save(data)
+
+
+def save(data: dict) -> None:
+    """Atomically write the history JSON (``mkdir -p`` + temp file + rename).
+
+    The temp-file-then-``replace`` keeps the file readable at all times: a crash
+    mid-write leaves the previous good file intact rather than a truncated one.
+    """
+    path = _path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(data), encoding="utf-8")
+    tmp.replace(path)

fvpnctl-0.2.4/src/fvpnctl/spinner.py

@@ -0,0 +1,215 @@
+"""Connect progress indicators — a Braille throbber and an ETA progress bar.
+
+Why this exists
+---------------
+``fvpnctl connect <profile>`` (without ``--no-wait``) blocks in
+:meth:`FortiVPN._wait_for_connection`, which polls ``getConnectionState`` once a
+second for up to ``--timeout`` seconds while the daemon negotiates the IPsec
+tunnel. That loop is silent, so a slow handshake looks like a frozen process.
+This module paints live feedback so the user can see the wait is *working*:
+
+* :class:`Spinner` — an indeterminate Braille throbber + elapsed seconds, used
+  the first time a profile is connected (no timing history to estimate against).
+* :class:`ProgressBar` — a determinate bar that fills toward an ETA, used once
+  ``history`` has recorded past connect times for the profile (the ETA is their
+  mean; see ``history.average``).
+
+Both share the lifecycle in :class:`_Animated`; they differ only in the single
+line they paint each tick (:meth:`_Animated._line`).
+
+How they stay out of the controller's way
+-----------------------------------------
+The poll loop lives in ``controller.py`` and must stay UI-agnostic (the same
+controller/transport/render split the rest of the codebase follows — see
+``monitor.py``). So the indicator does **not** reach into the loop: the CLI wraps
+the blocking ``connect()`` call in the context manager, the indicator animates on
+a daemon thread while the main thread does the CDP I/O, and ``__exit__`` tears
+the animation down. The controller is untouched.
+
+Three modes, chosen from the stream + verbosity (:func:`select_mode`)
+---------------------------------------------------------------------
+* **off**    — ``--quiet`` (``enabled=False``): write nothing at all.
+* **static** — verbose but the stream is not a TTY (piped / redirected): one
+  plain ``message`` line, no ANSI and no ``\\r`` spam, so logs stay readable.
+* **animate**— verbose on a real TTY: hide the cursor, paint the first frame
+  synchronously (instant feedback, and one deterministic frame for tests), then
+  animate on a background thread until ``__exit__``.
+
+stderr, never stdout
+--------------------
+Like ``cli.report``, indicators write to **stderr** so stdout stays the
+machine-readable channel (``CONNECTED <profile> <ip>``, ``--json``, pipelines).
+``__exit__`` wipes the line and restores the cursor *before* the caller prints
+its result/error, so success and failure both start on a clean line.
+
+Pure vs. I/O
+------------
+:func:`render_frame`, :func:`render_bar` and :func:`select_mode` are pure (data
+in, string out) and unit-tested directly; only :class:`_Animated` touches a
+stream, a thread, and the clock.
+"""
+
+import sys
+import threading
+import time
+
+# Braille "dots" spinner — ten frames that read as a smooth rotation. Zero
+# dependencies (project rule): the frames are just literal Unicode here.
+_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+# ANSI control sequences (defined locally so this module stays standalone, like
+# ``monitor.py`` keeps its own copy). Named so the I/O below reads as intent.
+_HIDE_CURSOR = "\x1b[?25l"
+_SHOW_CURSOR = "\x1b[?25h"
+_CLEAR_EOL = "\x1b[K"
+
+# Progress-bar geometry and glyphs.
+_BAR_W = 24
+_BAR_FILL = "█"
+_BAR_EMPTY = "░"
+# Never paint a full bar while the connect is still running — 100% is reserved
+# for "actually finished". The bar saturates just below full and the elapsed/ETA
+# tail keeps counting, so a slower-than-usual connect reads as "nearly there,
+# overdue" rather than a bar stuck at 100%.
+_BAR_CAP = 0.99
+
+
+def render_frame(frame: str, message: str, elapsed: int) -> str:
+    """Build one throbber line: ``\\r<frame> <message>  <elapsed>s`` + clear-to-EOL.
+
+    Leads with ``\\r`` so each frame overwrites the previous in place, and ends
+    with :data:`_CLEAR_EOL` so a shrinking line never leaves stale trailing
+    characters. Pure — no I/O.
+    """
+    return f"\r{frame} {message}  {elapsed:d}s{_CLEAR_EOL}"
+
+
+def render_bar(message: str, elapsed: float, eta: float, *, width: int = _BAR_W) -> str:
+    """Build one progress-bar line filled to ``elapsed/eta`` (capped below 100%).
+
+    The fraction is clamped to :data:`_BAR_CAP` and at least one cell is always
+    left empty while running, so the bar never claims completion before the
+    connect actually returns. The ``<elapsed>s / ~<eta>s`` tail stays honest when
+    a connect overruns its estimate (e.g. ``41s / ~30s`` at 99%). Pure — no I/O.
+    """
+    frac = 0.0 if eta <= 0 else min(elapsed / eta, _BAR_CAP)
+    filled = int(frac * width)
+    if frac < 1.0:
+        filled = min(filled, width - 1)  # keep one empty cell until truly done
+    bar = _BAR_FILL * filled + _BAR_EMPTY * (width - filled)
+    pct = int(frac * 100)
+    tail = f"{int(elapsed)}s / ~{int(round(eta))}s"
+    return f"\r{message}  [{bar}] {pct:>2d}%  {tail}{_CLEAR_EOL}"
+
+
+def select_mode(stream, *, enabled: bool) -> str:
+    """Choose ``off``/``static``/``animate`` from verbosity + the stream.
+
+    ``enabled`` is the CLI's verbose flag: ``False`` (``--quiet``) → ``off``
+    regardless of the stream. Otherwise a real TTY animates and anything else
+    (a pipe, a file, a captured test buffer) gets the single static line.
+    """
+    if not enabled:
+        return "off"
+    isatty = getattr(stream, "isatty", None)
+    if isatty and isatty():
+        return "animate"
+    return "static"
+
+
+class _Animated:
+    """Shared lifecycle for the connect indicators: mode, thread, cursor, cleanup.
+
+    Subclasses implement :meth:`_line` to render one frame for a given elapsed
+    time and tick count. In ``animate`` mode a daemon thread repaints every
+    ``interval`` seconds; ``__exit__`` stops it, joins it, wipes the line and
+    restores the cursor — including when the wrapped block raises (a
+    ``ConnectTimeout``/``ConnectFailed`` must still leave a clean terminal).
+    """
+
+    def __init__(self, message: str, *, stream=None, enabled: bool = True, interval: float = 0.1):
+        self._message = message
+        self._stream = stream if stream is not None else sys.stderr
+        self._interval = interval
+        self._mode = select_mode(self._stream, enabled=enabled)
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._start: float | None = None
+        self._tick = 0
+
+    def _line(self, elapsed: float, tick: int) -> str:
+        """Return the full ``\\r…`` line to paint this frame (subclass hook)."""
+        raise NotImplementedError
+
+    def __enter__(self) -> "_Animated":
+        if self._mode == "off":
+            return self
+        if self._mode == "static":
+            # Pipe/log path: one plain line, no animation.
+            self._stream.write(self._message + "\n")
+            self._stream.flush()
+            return self
+        # animate: hide the cursor and paint the first frame right away so there
+        # is instant feedback (and one deterministic frame for the tests) before
+        # the background thread takes over.
+        self._start = time.monotonic()
+        self._stream.write(_HIDE_CURSOR)
+        self._paint()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+        return self
+
+    def _paint(self) -> None:
+        """Write one frame for the current elapsed time + tick, then flush."""
+        elapsed = time.monotonic() - self._start if self._start is not None else 0.0
+        self._stream.write(self._line(elapsed, self._tick))
+        self._stream.flush()
+        self._tick += 1
+
+    def _run(self) -> None:
+        """Background loop: repaint every ``interval`` until stopped.
+
+        Uses ``Event.wait(interval)`` rather than ``time.sleep`` so ``__exit__``
+        setting the stop event ends the wait *immediately* — teardown never
+        delays the caller by up to ``interval``.
+        """
+        while not self._stop.wait(self._interval):
+            self._paint()
+
+    def __exit__(self, *exc) -> bool:
+        if self._mode != "animate":
+            return False
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+        # Wipe the line and bring the cursor back so the caller's next write
+        # (result on stdout / error on stderr) starts on a clean line.
+        self._stream.write("\r" + _CLEAR_EOL + _SHOW_CURSOR)
+        self._stream.flush()
+        return False  # never suppress the wrapped block's exception
+
+
+class Spinner(_Animated):
+    """Indeterminate Braille throbber — used when there is no ETA to estimate."""
+
+    def _line(self, elapsed: float, tick: int) -> str:
+        return render_frame(_FRAMES[tick % len(_FRAMES)], self._message, int(elapsed))
+
+
+class ProgressBar(_Animated):
+    """Determinate progress bar driven by ``eta`` (mean of past connect times)."""
+
+    def __init__(
+        self,
+        message: str,
+        eta: float,
+        *,
+        stream=None,
+        enabled: bool = True,
+        interval: float = 0.1,
+    ):
+        super().__init__(message, stream=stream, enabled=enabled, interval=interval)
+        self._eta = eta
+
+    def _line(self, elapsed: float, tick: int) -> str:
+        return render_bar(self._message, elapsed, self._eta)

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/tests/test_cli.py

@@ -142,13 +142,15 @@ class _FakeProfile:
 
 
 @pytest.fixture(autouse=True)
-def patched(monkeypatch):
+def patched(monkeypatch, tmp_path):
     """Swap the two seams and reset per-test state.
 
     Every test gets fresh ``FakeSession.instances`` and ``FakeController.config``
     so assertions about construction args / routed calls never bleed between
     tests. The ``FORTI_CDP_PORT`` env var is cleared so the default-port tests
-    are not perturbed by the developer's environment.
+    are not perturbed by the developer's environment. ``FVPNCTL_STATE_DIR`` is
+    pointed at a throwaway ``tmp_path`` so the connect-time history the CLI now
+    reads/writes never touches the developer's real state dir.
     """
     FakeSession.instances = []
     FakeController.config = {}
@@ -156,6 +158,8 @@ def patched(monkeypatch):
     monkeypatch.setattr(cli, "CDPSession", FakeSession)
     monkeypatch.setattr(cli, "FortiVPN", FakeController)
     monkeypatch.delenv("FORTI_CDP_PORT", raising=False)
+    monkeypatch.setenv("FVPNCTL_STATE_DIR", str(tmp_path / "state"))
+    monkeypatch.delenv("XDG_STATE_HOME", raising=False)
     return FakeController
 
 
@@ -343,6 +347,30 @@ def test_disconnect_routes_and_prints(capsys):
     assert out == "DISCONNECTED office"
 
 
+def test_disconnect_no_arg_uses_active_profile(capsys):
+    # No profile given → read state(), disconnect whatever the daemon reports.
+    FakeController.config["state"] = FakeState(ipsec_state=2, name="apoz")
+    FakeController.config["disconnect"] = None
+
+    rc = cli.main(["disconnect"])
+
+    assert rc == 0
+    disconnect_calls = [c for c in FakeController.last.calls if c[0] == "disconnect"]
+    assert disconnect_calls[0][1][0] == "apoz"
+    assert capsys.readouterr().out.strip() == "DISCONNECTED apoz"
+
+
+def test_disconnect_no_arg_when_nothing_connected(capsys):
+    # Idempotent: nothing active → say so, never call DisconnectTunnel, exit 0.
+    FakeController.config["state"] = FakeState(ipsec_state=0, name="", state_label="DISCONNECTED")
+
+    rc = cli.main(["disconnect"])
+
+    assert rc == 0
+    assert [c for c in FakeController.last.calls if c[0] == "disconnect"] == []
+    assert "no active" in capsys.readouterr().err.lower()
+
+
 def test_connect_hides_window_by_default():
     FakeController.config["connect"] = FakeState(ipsec_state=2, name="office")
     FakeController.config["connection_ip"] = {"vpn_ip": "172.16.200.2"}
@@ -388,6 +416,55 @@ def test_connect_hide_failure_does_not_fail_connect(capsys):
     assert "CONNECTED" in capsys.readouterr().out
 
 
+def test_connect_records_duration_for_next_time():
+    # A successful waited connect persists its duration (isolated tmp state dir),
+    # so the NEXT connect can show a progress bar.
+    from fvpnctl import history
+
+    FakeController.config["connect"] = FakeState(ipsec_state=2, name="apoz")
+    FakeController.config["connection_ip"] = {"vpn_ip": "10.0.0.2"}
+
+    assert history.average("apoz") is None  # nothing recorded yet
+    rc = cli.main(["connect", "apoz"])
+
+    assert rc == 0
+    assert history.average("apoz") is not None  # one measurement now stored
+
+
+def test_connect_with_history_succeeds_via_progress_bar_branch(capsys):
+    # Pre-seeded history → eta is not None → the ProgressBar branch is taken.
+    # Output is captured (non-TTY) so the bar renders as its static line; the
+    # connect must still succeed and print the machine-readable result.
+    from fvpnctl import history
+
+    history.record("apoz", 8.0)
+    FakeController.config["connect"] = FakeState(ipsec_state=2, name="apoz")
+    FakeController.config["connection_ip"] = {"vpn_ip": "10.0.0.2"}
+
+    rc = cli.main(["connect", "apoz"])
+
+    assert rc == 0
+    assert "CONNECTED apoz 10.0.0.2" in capsys.readouterr().out
+
+
+def test_connect_history_failure_does_not_break_connect(monkeypatch, capsys):
+    # A corrupt/unreadable history store must never block a connect: the ETA read
+    # degrades to the throbber and the connect still succeeds.
+    from fvpnctl import history
+
+    def boom(_profile):
+        raise ValueError("corrupt history")
+
+    monkeypatch.setattr(history, "average", boom)
+    FakeController.config["connect"] = FakeState(ipsec_state=2, name="apoz")
+    FakeController.config["connection_ip"] = {"vpn_ip": "10.0.0.2"}
+
+    rc = cli.main(["connect", "apoz"])
+
+    assert rc == 0
+    assert "CONNECTED apoz" in capsys.readouterr().out
+
+
 def test_hide_window_command_routes():
     rc = cli.main(["hide-window"])
 

fvpnctl-0.2.4/tests/test_history.py

@@ -0,0 +1,91 @@
+"""Tests for the connect-time history (``fvpnctl.history``).
+
+CI-safe and isolated: every test points ``$FVPNCTL_STATE_DIR`` at a per-test
+``tmp_path`` (autouse fixture), so nothing reads or writes the developer's real
+``~/.local/state/fvpnctl``. The store is a tiny JSON file, so the tests exercise
+it end to end (record → reload → average) plus the resolution and resilience
+edges (env overrides, missing file, corrupt file, recent-window trimming).
+"""
+
+import json
+
+import pytest
+
+from fvpnctl import history
+
+
+@pytest.fixture(autouse=True)
+def isolated_state(monkeypatch, tmp_path):
+    monkeypatch.setenv("FVPNCTL_STATE_DIR", str(tmp_path / "state"))
+    # XDG must not leak in and override the explicit dir under test.
+    monkeypatch.delenv("XDG_STATE_HOME", raising=False)
+    return tmp_path
+
+
+def test_average_is_none_on_first_run():
+    # No file yet → empty history → no ETA (CLI falls back to the throbber).
+    assert history.average("apoz") is None
+
+
+def test_record_then_average_round_trips():
+    history.record("apoz", 12.0)
+    history.record("apoz", 8.0)
+    assert history.average("apoz") == pytest.approx(10.0)
+
+
+def test_history_is_per_profile():
+    history.record("apoz", 30.0)
+    history.record("office", 4.0)
+    assert history.average("apoz") == pytest.approx(30.0)
+    assert history.average("office") == pytest.approx(4.0)
+
+
+def test_only_recent_n_samples_are_kept_and_averaged():
+    for _ in range(history._HISTORY_LEN):
+        history.record("apoz", 2.0)
+    # An 11th very different sample evicts the oldest; the window stays at N and
+    # the mean reflects only the recent window, not all-time.
+    history.record("apoz", 24.0)
+    samples = history.load()["apoz"]
+    assert len(samples) == history._HISTORY_LEN
+    expected = (2.0 * (history._HISTORY_LEN - 1) + 24.0) / history._HISTORY_LEN
+    assert history.average("apoz") == pytest.approx(expected)
+
+
+def test_state_dir_prefers_explicit_override(monkeypatch, tmp_path):
+    monkeypatch.setenv("FVPNCTL_STATE_DIR", str(tmp_path / "explicit"))
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "xdg"))
+    assert history.state_dir() == (tmp_path / "explicit")
+
+
+def test_state_dir_falls_back_to_xdg_then_home(monkeypatch, tmp_path):
+    monkeypatch.delenv("FVPNCTL_STATE_DIR", raising=False)
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "xdg"))
+    assert history.state_dir() == (tmp_path / "xdg" / "fvpnctl")
+    monkeypatch.delenv("XDG_STATE_HOME", raising=False)
+    monkeypatch.setattr(history.Path, "home", classmethod(lambda cls: tmp_path / "home"))
+    assert history.state_dir() == (tmp_path / "home" / ".local" / "state" / "fvpnctl")
+
+
+def test_corrupt_file_makes_average_raise():
+    path = history._path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("{not json", encoding="utf-8")
+    with pytest.raises(ValueError):
+        history.average("apoz")
+
+
+def test_record_self_heals_a_corrupt_file():
+    path = history._path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("garbage", encoding="utf-8")
+    # record() must not propagate the corruption: it resets and writes a valid file.
+    history.record("apoz", 5.0)
+    assert json.loads(path.read_text(encoding="utf-8")) == {"apoz": [5.0]}
+    assert history.average("apoz") == pytest.approx(5.0)
+
+
+def test_save_is_atomic_no_tmp_left_behind():
+    history.record("apoz", 3.0)
+    leftovers = list(history.state_dir().glob("*.tmp"))
+    assert leftovers == []

fvpnctl-0.2.4/tests/test_spinner.py

@@ -0,0 +1,168 @@
+"""Tests for the connect throbber (``fvpnctl.spinner``).
+
+CI-safe: no real terminal, no real sleeping that the suite depends on. The pure
+helpers (:func:`spinner.render_frame`, :func:`spinner.select_mode`) are tested
+directly. The :class:`spinner.Spinner` context manager is driven over a fake
+stream whose ``isatty()`` is scripted, so each of the three modes
+(``off``/``static``/``animate``) is exercised deterministically:
+
+* ``off``   — ``enabled=False`` (the ``--quiet`` path): writes nothing.
+* ``static``— a non-TTY stream (pipe/log): one plain line, no ANSI, no ``\\r``.
+* ``animate``— a TTY stream: hides the cursor, paints frame 0 *synchronously* on
+  enter (so at least one frame is deterministic without waiting on the thread),
+  and on exit wipes the line and restores the cursor.
+
+The animate test uses a deliberately huge ``interval`` so the background thread
+is still parked in its first ``wait`` when ``__exit__`` sets the stop event —
+that makes "exactly the synchronous frame 0 was painted" reliable rather than
+racing the thread's clock.
+"""
+
+import io
+
+from fvpnctl import spinner
+
+
+class FakeStream(io.StringIO):
+    """A ``StringIO`` with a scripted ``isatty()`` so mode selection is testable."""
+
+    def __init__(self, *, tty):
+        super().__init__()
+        self._tty = tty
+
+    def isatty(self):
+        return self._tty
+
+
+# -- pure helpers ------------------------------------------------------------
+
+
+def test_render_frame_carries_braille_message_and_elapsed():
+    out = spinner.render_frame("⠋", "Connecting profile apoz…", 7)
+    assert out.startswith("\r")
+    assert "⠋" in out
+    assert "Connecting profile apoz…" in out
+    assert "7s" in out
+    # Clears to end of line so a shrinking message never leaves stale tail chars.
+    assert out.endswith(spinner._CLEAR_EOL)
+
+
+def test_select_mode_off_when_disabled_even_on_tty():
+    assert spinner.select_mode(FakeStream(tty=True), enabled=False) == "off"
+
+
+def test_select_mode_static_on_non_tty():
+    assert spinner.select_mode(FakeStream(tty=False), enabled=True) == "static"
+
+
+def test_select_mode_animate_on_tty():
+    assert spinner.select_mode(FakeStream(tty=True), enabled=True) == "animate"
+
+
+# -- context manager: the three modes ----------------------------------------
+
+
+def test_off_mode_writes_nothing():
+    stream = FakeStream(tty=True)
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=False):
+        pass
+    assert stream.getvalue() == ""
+
+
+def test_static_mode_writes_one_plain_line():
+    stream = FakeStream(tty=False)
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=True):
+        pass
+    out = stream.getvalue()
+    assert out == "Connecting profile apoz…\n"
+    # No ANSI, no carriage-return animation in the pipe/log path.
+    assert "\x1b" not in out
+    assert "\r" not in out
+
+
+def test_animate_mode_paints_frame0_and_cleans_up():
+    stream = FakeStream(tty=True)
+    # Huge interval: the worker thread parks in its first wait() and never paints
+    # a second frame before __exit__ stops it — so only the synchronous frame 0
+    # is guaranteed, making the assertions deterministic.
+    with spinner.Spinner("Connecting profile apoz…", stream=stream, enabled=True, interval=1000):
+        pass
+    out = stream.getvalue()
+    assert spinner._HIDE_CURSOR in out  # cursor hidden on enter
+    assert spinner._FRAMES[0] in out  # first braille frame painted synchronously
+    assert "Connecting profile apoz…" in out
+    assert spinner._SHOW_CURSOR in out  # cursor restored on exit
+    # The line is wiped on exit so the next print starts clean.
+    assert out.rstrip().endswith(spinner._SHOW_CURSOR) or spinner._CLEAR_EOL in out
+
+
+def test_animate_mode_restores_cursor_even_on_exception():
+    stream = FakeStream(tty=True)
+    try:
+        with spinner.Spinner(
+            "Connecting profile apoz…", stream=stream, enabled=True, interval=1000
+        ):
+            raise RuntimeError("connect blew up")
+    except RuntimeError:
+        pass
+    out = stream.getvalue()
+    # A failed connect (ConnectTimeout etc.) must still leave a clean terminal.
+    assert spinner._SHOW_CURSOR in out
+
+
+# -- progress bar: pure render ----------------------------------------------
+
+
+def test_render_bar_fills_proportionally():
+    out = spinner.render_bar("Connecting profile apoz…", 6.0, 12.0)
+    assert out.startswith("\r")
+    assert "Connecting profile apoz…" in out
+    assert "50%" in out  # halfway to the ETA
+    assert spinner._BAR_FILL in out and spinner._BAR_EMPTY in out
+    assert "6s / ~12s" in out
+    assert out.endswith(spinner._CLEAR_EOL)
+
+
+def test_render_bar_caps_below_100_when_overdue():
+    out = spinner.render_bar("x", 50.0, 10.0)  # 5x past the ETA
+    assert "99%" in out  # capped, never 100% while still running
+    assert "100%" not in out
+    assert spinner._BAR_EMPTY in out  # one empty cell remains until truly done
+    assert "50s / ~10s" in out  # honest about the overrun
+
+
+def test_render_bar_handles_zero_eta_without_dividing():
+    out = spinner.render_bar("x", 1.0, 0.0)
+    assert "0%" in out  # no ZeroDivisionError, just an empty bar
+
+
+# -- progress bar: context manager modes ------------------------------------
+
+
+def test_progress_bar_animate_paints_and_cleans_up():
+    stream = FakeStream(tty=True)
+    with spinner.ProgressBar(
+        "Connecting profile apoz…", 12.0, stream=stream, enabled=True, interval=1000
+    ):
+        pass
+    out = stream.getvalue()
+    assert spinner._HIDE_CURSOR in out
+    assert spinner._BAR_EMPTY in out  # the (mostly empty) bar was painted at t≈0
+    assert "Connecting profile apoz…" in out
+    assert spinner._SHOW_CURSOR in out
+
+
+def test_progress_bar_off_writes_nothing():
+    stream = FakeStream(tty=True)
+    with spinner.ProgressBar("m", 5.0, stream=stream, enabled=False):
+        pass
+    assert stream.getvalue() == ""
+
+
+def test_progress_bar_static_writes_one_plain_line():
+    stream = FakeStream(tty=False)
+    with spinner.ProgressBar("Connecting profile apoz…", 5.0, stream=stream, enabled=True):
+        pass
+    out = stream.getvalue()
+    assert out == "Connecting profile apoz…\n"
+    assert "\x1b" not in out and "\r" not in out

{fvpnctl-0.2.2 → fvpnctl-0.2.4}/uv.lock

@@ -12,7 +12,7 @@ supported-markers = [
 
 [[package]]
 name = "fvpnctl"
-version = "0.2.2"
+version = "0.2.4"
 source = { editable = "." }
 
 [package.dev-dependencies]