cli-tools-kit 0.7.1__tar.gz → 0.8.1__tar.gz

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.7.1
+Version: 0.8.1
 Summary: Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens
 Author: Steffen Probst
 License: MIT License

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit/__init__.py

@@ -56,4 +56,4 @@ __all__ = [
     "read_installed_skill",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.8.1"

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit/advertise.py

@@ -72,6 +72,11 @@ def advertise(metadata: Union[ToolMetadata, List[ToolMetadata]]) -> NoReturn:
             value = getattr(m, key, None)
             if value:
                 record[key] = value
+        # Conditions are a list, so they get the same emit-only-when-set
+        # treatment but keep their type.
+        conditions = getattr(m, "autostart_conditions", None)
+        if conditions:
+            record["autostart_conditions"] = list(conditions)
         out.append(record)
     print(json.dumps(out))
     sys.exit(0)

cli_tools_kit-0.8.1/cli_tools_kit/autostart_gate.py

@@ -0,0 +1,292 @@
+"""Conditional autostart — run a tool at login only when a condition holds.
+
+An autostart entry is all-or-nothing: the `.desktop` symlink in
+`~/.config/autostart` either launches the tool at every login or never. Some
+tools only make sense some of the time — a study launcher during study hours,
+a voice assistant on the home network and nowhere else.
+
+This module is the generic half of that. A tool declares WHICH conditions it
+supports (`autostart_conditions` in its metadata); the user fills in the VALUES
+through the installer's ⚙ dialog, which stores them per host in the installer's
+own config directory. Nothing personal — no hours, no network names — belongs
+in a tool's source.
+
+The gate runs as a wrapper. When a tool has conditions configured, the
+installer writes the autostart `.desktop` with an Exec line of
+
+    cli-tools-kit-autostart-gate --slug <installer> --tool <key> -- <real command>
+
+The gate evaluates the stored conditions, execs the real command when they all
+pass, and exits 0 silently when any fails. Exit 0 matters: a non-zero exit from
+an XDG autostart entry makes systemd log a failed unit at every login.
+
+Two conditions ship here:
+
+`time_window`
+    Wall-clock window, `{"from": "06:00", "to": "12:00"}`. A window whose end
+    is not after its start wraps midnight, so `22:00`–`02:00` is four hours
+    around midnight rather than an empty set.
+
+`network`
+    Wi-Fi SSID, `{"ssids": [...], "grace_seconds": 120}`. At login the wireless
+    link is usually still associating, so a bare check would lose the race and
+    the tool would never start. The gate polls until one of the named SSIDs
+    appears or the grace period runs out, and fires at most once per run.
+
+Both are evaluated at launch only. Neither watches for later changes: leaving
+the network does not stop a tool the gate already started.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime, time as dtime
+from typing import Dict, List, Optional, Sequence
+
+from .identity import InstallerIdentity, LEGACY_IDENTITY
+
+# Conditions a tool may name in `autostart_conditions`. A tool advertising a
+# word outside this set is ignored rather than rejected, so a tool written for
+# a newer kit still installs against an older one.
+KNOWN_CONDITIONS = ("time_window", "network")
+
+# Poll interval while waiting for the wireless link to associate.
+_NETWORK_POLL_SECONDS = 3.0
+
+# Cap on `grace_seconds`, so a typo cannot leave a gate process resident for
+# the rest of the session.
+_MAX_GRACE_SECONDS = 900
+
+
+def identity_for_slug(slug: str) -> InstallerIdentity:
+    """The identity a slug names.
+
+    A slug alone cannot reconstruct an identity that overrides its directories,
+    so the legacy one is matched by name: its config lives in
+    ``~/.config/tools-installer``, not in ``~/.config/probable.work``, and the
+    gate has to read the same file the installer wrote.
+    """
+    if slug == LEGACY_IDENTITY.slug:
+        return LEGACY_IDENTITY
+    return InstallerIdentity(slug=slug)
+
+
+def config_path(slug: str) -> str:
+    """Where one installer's autostart conditions live.
+
+    Beside that installer's other config, keyed by slug so several installers
+    on one host keep separate files.
+    """
+    return os.path.join(identity_for_slug(slug).config_path, "autostart.json")
+
+
+def load_conditions(slug: str) -> Dict[str, dict]:
+    """Read every tool's configured conditions for one installer.
+
+    Returns `{}` when the file is missing or unreadable — an absent config
+    means "no conditions", which gates open rather than shut.
+    """
+    try:
+        with open(config_path(slug), "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def load_tool_conditions(slug: str, tool_key: str) -> dict:
+    """The configured conditions for one tool, or `{}` if it has none."""
+    entry = load_conditions(slug).get(tool_key)
+    return entry if isinstance(entry, dict) else {}
+
+
+def save_tool_conditions(slug: str, tool_key: str, conditions: Optional[dict]) -> None:
+    """Store (or, with *conditions* empty/None, drop) one tool's conditions."""
+    data = load_conditions(slug)
+    if conditions:
+        data[tool_key] = conditions
+    else:
+        data.pop(tool_key, None)
+
+    path = config_path(slug)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2, sort_keys=True)
+        fh.write("\n")
+    os.replace(tmp, path)
+
+
+# ---------------------------------------------------------------- conditions
+
+def _parse_hhmm(value: str) -> Optional[dtime]:
+    """Parse `"HH:MM"`. Returns None on anything unparseable."""
+    try:
+        hh, _, mm = str(value).partition(":")
+        return dtime(int(hh), int(mm))
+    except (TypeError, ValueError):
+        return None
+
+
+def time_window_open(config: dict, now: Optional[datetime] = None) -> bool:
+    """True when *now* falls inside the configured window.
+
+    A window whose end is not after its start wraps midnight. An unparseable
+    or half-specified window is treated as no restriction.
+    """
+    start = _parse_hhmm(config.get("from", ""))
+    end = _parse_hhmm(config.get("to", ""))
+    if start is None or end is None:
+        return True
+
+    current = (now or datetime.now()).time()
+    if start < end:
+        return start <= current < end
+    if start == end:
+        # A zero-width window would never open; read it as "no restriction"
+        # rather than silently disabling the tool forever.
+        return True
+    # Wraps midnight: inside means after the start OR before the end.
+    return current >= start or current < end
+
+
+def current_ssids() -> List[str]:
+    """SSIDs of the currently active Wi-Fi connections.
+
+    Uses NetworkManager, the only mechanism present on the KDE/GNOME hosts this
+    kit targets. Returns `[]` when nmcli is missing or reports nothing, which
+    is indistinguishable from "not on Wi-Fi" — deliberately, since both mean
+    the network condition cannot be satisfied.
+    """
+    try:
+        result = subprocess.run(
+            ["nmcli", "-t", "-f", "ACTIVE,SSID", "device", "wifi"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if result.returncode != 0:
+        return []
+
+    found = []
+    for line in result.stdout.splitlines():
+        active, _, ssid = line.partition(":")
+        if active == "yes" and ssid:
+            found.append(ssid)
+    return found
+
+
+def network_matches(config: dict, *, wait: bool = True) -> bool:
+    """True when one of the configured SSIDs is active.
+
+    With *wait* set, polls for up to `grace_seconds` so a login that outruns
+    the wireless association still sees the network. An empty SSID list is no
+    restriction.
+    """
+    wanted = [s for s in config.get("ssids", []) if s]
+    if not wanted:
+        return True
+
+    try:
+        grace = float(config.get("grace_seconds", 120))
+    except (TypeError, ValueError):
+        grace = 120.0
+    grace = max(0.0, min(grace, _MAX_GRACE_SECONDS)) if wait else 0.0
+
+    deadline = time.monotonic() + grace
+    while True:
+        if any(ssid in wanted for ssid in current_ssids()):
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(min(_NETWORK_POLL_SECONDS, max(0.1, deadline - time.monotonic())))
+
+
+def conditions_pass(conditions: dict, *, wait: bool = True) -> tuple[bool, str]:
+    """Evaluate every configured condition. Returns (passed, reason).
+
+    *reason* names the first condition that failed, for the log line; it is
+    empty when everything passed. An unknown condition name is skipped rather
+    than failed, so a config written by a newer kit does not shut the gate.
+    """
+    window = conditions.get("time_window")
+    if isinstance(window, dict) and not time_window_open(window):
+        return False, (
+            f"outside time window {window.get('from', '?')}–{window.get('to', '?')}"
+        )
+
+    network = conditions.get("network")
+    if isinstance(network, dict) and not network_matches(network, wait=wait):
+        wanted = ", ".join(network.get("ssids", [])) or "?"
+        return False, f"network not one of [{wanted}]"
+
+    return True, ""
+
+
+# --------------------------------------------------------------------- entry
+
+def build_exec_prefix(slug: str, tool_key: str) -> List[str]:
+    """The argv prefix that wraps a gated tool's own command.
+
+    Prefers the installed `cli-tools-kit-autostart-gate` console script, which
+    survives the interpreter that wrote the entry moving or being rebuilt. Only
+    when that is not on PATH does it pin the current interpreter, since a
+    `python -m` line is the one form guaranteed to resolve the package.
+    """
+    script = shutil.which("cli-tools-kit-autostart-gate")
+    head = [script] if script else [sys.executable, "-m", "cli_tools_kit.autostart_gate"]
+    return head + ["--slug", slug, "--tool", tool_key, "--"]
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cli-tools-kit-autostart-gate",
+        description="Run a command only when its configured autostart conditions hold.",
+    )
+    parser.add_argument("--slug", required=True,
+                        help="Installer slug whose autostart.json holds the conditions")
+    parser.add_argument("--tool", required=True,
+                        help="Tool key within that config")
+    parser.add_argument("--no-wait", action="store_true",
+                        help="Skip the network grace period; evaluate once and exit")
+    parser.add_argument("--check", action="store_true",
+                        help="Report whether the gate would open, run nothing")
+    parser.add_argument("command", nargs=argparse.REMAINDER,
+                        help="-- followed by the command to run when the gate opens")
+    args = parser.parse_args(argv)
+
+    conditions = load_tool_conditions(args.slug, args.tool)
+    passed, reason = conditions_pass(conditions, wait=not args.no_wait)
+
+    if args.check:
+        print("open" if passed else f"closed: {reason}")
+        return 0 if passed else 1
+
+    if not passed:
+        # Exit 0 on a closed gate: a non-zero exit from an XDG autostart entry
+        # surfaces as a failed systemd unit at every login.
+        print(f"autostart-gate: {args.tool} not started ({reason})", file=sys.stderr)
+        return 0
+
+    command = list(args.command)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        print("autostart-gate: no command given", file=sys.stderr)
+        return 2
+
+    try:
+        os.execvp(command[0], command)
+    except OSError as exc:
+        print(f"autostart-gate: cannot run {command[0]}: {exc}", file=sys.stderr)
+        return 127
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit/gui_installer.py

@@ -61,6 +61,14 @@ from typing import Callable, Dict, List, NamedTuple, Optional, Sequence
 
 from . import host
 from .identity import InstallerIdentity, LEGACY_IDENTITY
+from .autostart_gate import (
+    KNOWN_CONDITIONS,
+    _parse_hhmm,
+    build_exec_prefix,
+    current_ssids,
+    load_tool_conditions,
+    save_tool_conditions,
+)
 
 # Pillow renders tool icons. It is an optional extra (``cli-tools-kit[gui]``);
 # without it the GUI still runs, just without per-tool icon thumbnails, and the
@@ -255,6 +263,7 @@ class ToolEntry(NamedTuple):
     cron_args: List[str] = []        # Args to pass when running as cron job
     skill_name: str = ""             # If non-empty, tool can install a Claude Code skill via --install-skill / --uninstall-skill
     skill_status: str = ""           # Advertised skill freshness: "absent"|"current"|"stale" ("" = tool didn't report it)
+    autostart_conditions: List[str] = []  # Conditions this tool's autostart supports ("time_window", "network"); the values live in the installer's autostart.json, never in the tool. See cli_tools_kit.autostart_gate.
 
 
 def _group_label(entry: "ToolEntry") -> str:
@@ -476,6 +485,14 @@ def _find_emoji_font():
         "/usr/share/fonts/google-noto-color-emoji/NotoColorEmoji.ttf",
         "/usr/share/fonts/truetype/unifont/unifont.ttf",
     ]
+    # Windows ships Segoe UI Emoji; macOS ships Apple Color Emoji. Neither has
+    # fc-match, so without these the lookup below finds nothing and every emoji
+    # falls back to the monochrome glyph.
+    windir = os.environ.get("WINDIR", r"C:\Windows")
+    font_paths += [
+        os.path.join(windir, "Fonts", "seguiemj.ttf"),
+        "/System/Library/Fonts/Apple Color Emoji.ttc",
+    ]
     for path in font_paths:
         if os.path.exists(path):
             return path
@@ -517,17 +534,18 @@ def render_emoji_icon(emoji_char: str, output_path: str, size: int = 128) -> boo
 
         if font is not None:
             try:
-                render_size = native_size + 60  # Extra room for centering
+                # Draw at a fixed offset on a canvas with room on every side,
+                # then let the crop below find the glyph. Centering by textbbox
+                # first would cut emoji off: for a character with a variation
+                # selector (U+2600 U+FE0F) Segoe UI Emoji reports a box half
+                # again as wide as what it actually paints, and the resulting
+                # offset pushes the right-hand side off the canvas.
+                render_size = native_size * 3
                 img = Image.new("RGBA", (render_size, render_size), (0, 0, 0, 0))
                 draw = ImageDraw.Draw(img)
 
-                bbox = draw.textbbox((0, 0), emoji_char, font=font)
-                w = bbox[2] - bbox[0]
-                h = bbox[3] - bbox[1]
-                x = (render_size - w) // 2 - bbox[0]
-                y = (render_size - h) // 2 - bbox[1]
-
-                draw.text((x, y), emoji_char, font=font, embedded_color=True)
+                origin = native_size // 2
+                draw.text((origin, origin), emoji_char, font=font, embedded_color=True)
 
                 if img.getbbox():
                     # Crop to content, resize to target with padding
@@ -652,6 +670,10 @@ def get_metadata_native(file_path: str, category: str) -> List[ToolEntry]:
                     cron_args=item.get("cron_args", []),
                     skill_name=item.get("skill_name", ""),
                     skill_status=item.get("skill_status", ""),
+                    autostart_conditions=[
+                        c for c in item.get("autostart_conditions", []) or []
+                        if c in KNOWN_CONDITIONS
+                    ],
                 ))
     except (subprocess.TimeoutExpired, json.JSONDecodeError, Exception):
         # If a tool fails to advertise, it is ignored.
@@ -1382,6 +1404,92 @@ def is_autostart_enabled(tool: ToolEntry) -> bool:
     return False
 
 
+def autostart_tool_key(tool: ToolEntry) -> str:
+    """The key a tool's conditions are stored under.
+
+    The .desktop stem: stable across renames of the display name, and already
+    unique per installed shortcut.
+    """
+    return os.path.splitext(tool.desktop_file)[0]
+
+
+def get_autostart_conditions(tool: ToolEntry) -> dict:
+    """The conditions currently configured for *tool* on this host."""
+    return load_tool_conditions(IDENTITY.slug, autostart_tool_key(tool))
+
+
+def set_autostart_conditions(tool: ToolEntry, conditions: Optional[dict]) -> None:
+    """Store *tool*'s conditions, then rewrite its entry if autostart is on.
+
+    The Exec line differs between a gated and an ungated entry, so a change
+    here only takes effect once the entry is rewritten.
+    """
+    save_tool_conditions(IDENTITY.slug, autostart_tool_key(tool), conditions)
+    if is_autostart_enabled(tool):
+        enable_autostart(tool)
+
+
+def _read_desktop_exec(desktop_path: str) -> str:
+    """The Exec= line of an installed .desktop, or "" if it has none."""
+    try:
+        with open(desktop_path, "r", encoding="utf-8") as fh:
+            for line in fh:
+                if line.startswith("Exec="):
+                    return line[len("Exec="):].strip()
+    except OSError:
+        pass
+    return ""
+
+
+def _write_gated_autostart(tool: ToolEntry, desktop_path: str,
+                           autostart_path: str, conditions: dict) -> tuple[bool, str]:
+    """Write an autostart .desktop whose Exec runs *tool* through the gate.
+
+    A real file rather than the usual symlink: the app entry in the menu must
+    keep launching the tool unconditionally, so only this copy carries the
+    gate. Everything else is inherited from the installed entry.
+    """
+    exec_line = _read_desktop_exec(desktop_path)
+    if not exec_line:
+        return False, f"No Exec line in {desktop_path}"
+
+    prefix = " ".join(shlex.quote(p) for p in
+                      build_exec_prefix(IDENTITY.slug, autostart_tool_key(tool)))
+    gated_exec = f"{prefix} {exec_line}"
+
+    try:
+        with open(desktop_path, "r", encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError as e:
+        return False, f"Failed to read {desktop_path}: {e}"
+
+    out = []
+    for line in lines:
+        if line.startswith("Exec="):
+            out.append(f"Exec={gated_exec}")
+        elif line.startswith("X-CliToolsKit-Gated="):
+            continue
+        else:
+            out.append(line)
+    # Marks the entry as ours and generated, so it is obvious in a diff why
+    # this one is a file where every other autostart entry is a symlink.
+    out.append("X-CliToolsKit-Gated=true")
+
+    try:
+        if os.path.exists(autostart_path) or os.path.islink(autostart_path):
+            os.remove(autostart_path)
+        with open(autostart_path, "w", encoding="utf-8") as fh:
+            fh.write("\n".join(out) + "\n")
+        # Deliberately not executable: systemd-xdg-autostart-generator warns
+        # on every login about an executable entry in ~/.config/autostart.
+        exec_bits = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+        os.chmod(autostart_path, os.stat(autostart_path).st_mode & ~exec_bits)
+    except OSError as e:
+        return False, f"Failed to write {autostart_path}: {e}"
+
+    return True, f"Autostart enabled (conditional): {tool.name}"
+
+
 def enable_autostart(tool: ToolEntry) -> tuple[bool, str]:
     """Enable autostart for a tool.
 
@@ -1411,6 +1519,12 @@ def enable_autostart(tool: ToolEntry) -> tuple[bool, str]:
         os.makedirs(AUTOSTART_DIR, exist_ok=True)
         autostart_path = get_autostart_path(tool)
 
+        # A tool with conditions configured gets a gated copy instead of the
+        # plain symlink, so the menu entry stays unconditional.
+        conditions = get_autostart_conditions(tool)
+        if conditions:
+            return _write_gated_autostart(tool, desktop_path, autostart_path, conditions)
+
         if os.path.exists(autostart_path) or os.path.islink(autostart_path):
             os.remove(autostart_path)
 
@@ -1800,6 +1914,7 @@ class InstallerApp:
 
         self.check_vars: Dict[str, tk.BooleanVar] = {}
         self.autostart_vars: Dict[str, tk.BooleanVar] = {}  # Autostart checkboxes
+        self.autostart_gears: Dict[str, ttk.Label] = {}  # ⚙ beside the checkbox, for tools with conditions
         self.skill_vars: Dict[str, tk.BooleanVar] = {}      # Per-row "Skill" checkbox (only for tools with skill_name)
         self.status_labels: Dict[str, ttk.Label] = {}
         self.icon_labels: Dict[str, ttk.Label] = {}  # For displaying tool icons
@@ -2175,6 +2290,9 @@ class InstallerApp:
         self.style.configure("CardToolName.TLabel", font=("", 10, "bold"),
                              background=t["panel"], foreground=t["fg"])
         self.style.configure("CardMuted.TLabel", foreground=t["muted"], background=t["panel"])
+        # The ⚙ on an autostart row: accent once conditions are configured, so
+        # a glance at the column says which tools are gated.
+        self.style.configure("CardAccent.TLabel", foreground=t["accent"], background=t["panel"])
         self.style.configure("Card.TCheckbutton", background=t["panel"], foreground=t["fg"])
         self.style.map("Card.TCheckbutton", background=[("active", t["panel"])])
         # Hover-emphasis card styles — a row lifts onto a slightly accent-tinted
@@ -2226,6 +2344,7 @@ class InstallerApp:
         # Clear all tracking lists
         self.check_vars.clear()
         self.autostart_vars.clear()
+        self.autostart_gears.clear()
         self.skill_vars.clear()
         self.status_labels.clear()
         self.icon_labels.clear()
@@ -2285,8 +2404,6 @@ class InstallerApp:
         for theme_name, theme_data in self.THEMES.items():
             btn = tk.Button(
                 theme_frame,
-                text=theme_data["emoji"],
-                font=("", 14),
                 width=2,
                 relief="flat",
                 bd=0,
@@ -2296,6 +2413,7 @@ class InstallerApp:
                 cursor="hand2",
                 command=lambda tn=theme_name: self._select_theme(tn)
             )
+            self._set_emoji_face(btn, theme_data["emoji"])
             btn.pack(side="left", padx=2)
             self.theme_buttons[theme_name] = btn
 
@@ -2303,8 +2421,6 @@ class InstallerApp:
         # picked color, persisted per theme; re-clicking the emoji resets.
         accent_btn = tk.Button(
             theme_frame,
-            text="🎨",
-            font=("", 14),
             width=2,
             relief="flat",
             bd=0,
@@ -2315,6 +2431,7 @@ class InstallerApp:
             cursor="hand2",
             command=self._pick_accent,
         )
+        self._set_emoji_face(accent_btn, "🎨")
         accent_btn.pack(side="left", padx=(8, 2))
         self._attach_tooltip(accent_btn,
                              "Re-tint this theme from a base color "
@@ -2636,6 +2753,33 @@ class InstallerApp:
 
         self._update_status_labels()
 
+    def _set_emoji_face(self, button: tk.Button, emoji_char: str, size: int = 20) -> None:
+        """Put an emoji on a button as a color image, falling back to its text.
+
+        Tk draws a character with one foreground color, so an emoji set as text
+        comes out as the monochrome glyph. Rendering it through PIL keeps the
+        color, which is the whole point of the theme and accent buttons.
+        """
+        photo = None
+        try:
+            cache_file = os.path.join(
+                _get_emoji_cache_dir(), f"btn_{ord(emoji_char[0]):x}_{size}.png"
+            )
+            if not os.path.exists(cache_file):
+                render_emoji_icon(emoji_char, cache_file, size=size)
+            if os.path.exists(cache_file):
+                photo = ImageTk.PhotoImage(file=cache_file)
+        except Exception:
+            photo = None
+
+        if photo is not None:
+            # The cache keeps the only reference; without it Tk shows a blank
+            # button as soon as the image is collected.
+            self.icon_cache[f"emoji_{emoji_char}_{size}"] = photo
+            button.config(image=photo, text="", width=size + 8, height=size + 4)
+        else:
+            button.config(text=emoji_char, font=("", 14), width=2)
+
     def _get_tool_icon(self, icon_name_or_path: str) -> Optional[ImageTk.PhotoImage]:
         """Get or load a tool icon, using cache to prevent garbage collection."""
         if icon_name_or_path in self.icon_cache:
@@ -2657,6 +2801,160 @@ class InstallerApp:
             return custom_path, self._get_tool_icon(custom_path)
         return tool.icon, self._get_tool_icon(tool.icon)
 
+
+    def _show_autostart_conditions_dialog(self, tool_key: str):
+        """Edit when a tool may autostart — the ⚙ beside its Auto-Start box.
+
+        Shows only the conditions the tool advertises. Values are stored per
+        host in the installer's autostart.json, never in the tool's repo.
+        """
+        tool = self.tools_by_key.get(tool_key)
+        if not tool or not tool.autostart_conditions:
+            return
+
+        t = self.theme
+        bg, fg, accent, muted = t["bg"], t["fg"], t["accent"], t["muted"]
+        input_bg = t.get("canvas_bg", bg)
+
+        saved = get_autostart_conditions(tool)
+
+        dialog = tk.Toplevel(self.root)
+        dialog.title(f"Auto-Start conditions — {tool.name}")
+        dialog.configure(background=bg)
+        dialog.transient(self.root)
+        dialog.resizable(False, False)
+
+        body = tk.Frame(dialog, bg=bg, padx=18, pady=16)
+        body.pack(fill=tk.BOTH, expand=True)
+
+        tk.Label(body, text=tool.name, bg=bg, fg=fg,
+                 font=("", 12, "bold")).pack(anchor="w")
+        tk.Label(body, text="Start at login only when all ticked conditions hold.",
+                 bg=bg, fg=muted, font=("", 9)).pack(anchor="w", pady=(0, 12))
+
+        # --- time_window -------------------------------------------------
+        window_enabled = tk.BooleanVar(value="time_window" in saved)
+        from_var = tk.StringVar(value=saved.get("time_window", {}).get("from", "06:00"))
+        to_var = tk.StringVar(value=saved.get("time_window", {}).get("to", "12:00"))
+
+        if "time_window" in tool.autostart_conditions:
+            box = tk.Frame(body, bg=bg)
+            box.pack(fill="x", anchor="w", pady=(0, 10))
+            tk.Checkbutton(box, text="Only within a time window", variable=window_enabled,
+                           bg=bg, fg=fg, selectcolor=input_bg, activebackground=bg,
+                           activeforeground=fg, highlightthickness=0,
+                           font=("", 10)).pack(anchor="w")
+            row = tk.Frame(box, bg=bg)
+            row.pack(anchor="w", padx=(24, 0), pady=(2, 0))
+            tk.Label(row, text="from", bg=bg, fg=muted).pack(side="left")
+            tk.Entry(row, textvariable=from_var, width=7, bg=input_bg, fg=fg,
+                     insertbackground=fg, justify="center").pack(side="left", padx=4)
+            tk.Label(row, text="to", bg=bg, fg=muted).pack(side="left")
+            tk.Entry(row, textvariable=to_var, width=7, bg=input_bg, fg=fg,
+                     insertbackground=fg, justify="center").pack(side="left", padx=4)
+            tk.Label(row, text="(24h, e.g. 06:00)", bg=bg, fg=muted,
+                     font=("", 8)).pack(side="left", padx=(6, 0))
+
+        # --- network -----------------------------------------------------
+        net_enabled = tk.BooleanVar(value="network" in saved)
+        ssid_var = tk.StringVar(
+            value=", ".join(saved.get("network", {}).get("ssids", [])))
+        grace_var = tk.StringVar(
+            value=str(saved.get("network", {}).get("grace_seconds", 120)))
+
+        if "network" in tool.autostart_conditions:
+            box = tk.Frame(body, bg=bg)
+            box.pack(fill="x", anchor="w", pady=(0, 10))
+            tk.Checkbutton(box, text="Only on these Wi-Fi networks", variable=net_enabled,
+                           bg=bg, fg=fg, selectcolor=input_bg, activebackground=bg,
+                           activeforeground=fg, highlightthickness=0,
+                           font=("", 10)).pack(anchor="w")
+            row = tk.Frame(box, bg=bg)
+            row.pack(anchor="w", fill="x", padx=(24, 0), pady=(2, 0))
+            tk.Entry(row, textvariable=ssid_var, width=34, bg=input_bg, fg=fg,
+                     insertbackground=fg).pack(side="left")
+            tk.Label(row, text="SSIDs, comma-separated", bg=bg, fg=muted,
+                     font=("", 8)).pack(side="left", padx=(6, 0))
+
+            row2 = tk.Frame(box, bg=bg)
+            row2.pack(anchor="w", padx=(24, 0), pady=(4, 0))
+            tk.Label(row2, text="wait up to", bg=bg, fg=muted).pack(side="left")
+            tk.Entry(row2, textvariable=grace_var, width=5, bg=input_bg, fg=fg,
+                     insertbackground=fg, justify="center").pack(side="left", padx=4)
+            tk.Label(row2, text="s after login for the network to connect",
+                     bg=bg, fg=muted).pack(side="left")
+
+            current = current_ssids()
+            if current:
+                hint = tk.Label(box, text=f"connected now: {', '.join(current)}",
+                                bg=bg, fg=accent, font=("", 8), cursor="hand2")
+                hint.pack(anchor="w", padx=(24, 0), pady=(3, 0))
+                hint.bind("<Button-1>",
+                          lambda _e: ssid_var.set(", ".join(current)))
+
+        status = tk.Label(body, text="", bg=bg, fg=muted, font=("", 9))
+        status.pack(anchor="w", pady=(4, 0))
+
+        def collect() -> Optional[dict]:
+            """Build the conditions dict, or None when the input is invalid."""
+            out = {}
+            if "time_window" in tool.autostart_conditions and window_enabled.get():
+                start, end = from_var.get().strip(), to_var.get().strip()
+                if _parse_hhmm(start) is None or _parse_hhmm(end) is None:
+                    status.config(text="Times must look like 06:00.", fg="#e06c75")
+                    return None
+                out["time_window"] = {"from": start, "to": end}
+            if "network" in tool.autostart_conditions and net_enabled.get():
+                ssids = [s.strip() for s in ssid_var.get().split(",") if s.strip()]
+                if not ssids:
+                    status.config(text="Name at least one SSID.", fg="#e06c75")
+                    return None
+                try:
+                    grace = max(0, int(float(grace_var.get().strip() or 0)))
+                except ValueError:
+                    status.config(text="The wait must be a number of seconds.",
+                                  fg="#e06c75")
+                    return None
+                out["network"] = {"ssids": ssids, "grace_seconds": grace}
+            return out
+
+        def on_save():
+            conditions = collect()
+            if conditions is None:
+                return
+            set_autostart_conditions(tool, conditions)
+            self._refresh_autostart_gear(tool_key)
+            dialog.destroy()
+
+        buttons = tk.Frame(body, bg=bg)
+        buttons.pack(fill="x", pady=(14, 0))
+        tk.Button(buttons, text="Save", command=on_save, bg=accent, fg=bg,
+                  relief="flat", padx=16, pady=4,
+                  activebackground=accent).pack(side="right")
+        tk.Button(buttons, text="Cancel", command=dialog.destroy, bg=input_bg,
+                  fg=fg, relief="flat", padx=12, pady=4,
+                  activebackground=input_bg).pack(side="right", padx=(0, 8))
+
+        dialog.update_idletasks()
+        # Centre on the main window rather than the screen, so it lands where
+        # the user is looking on a multi-monitor desktop.
+        x = self.root.winfo_rootx() + (self.root.winfo_width() - dialog.winfo_width()) // 2
+        y = self.root.winfo_rooty() + (self.root.winfo_height() - dialog.winfo_height()) // 3
+        dialog.geometry(f"+{max(0, x)}+{max(0, y)}")
+        dialog.grab_set()
+
+    def _refresh_autostart_gear(self, tool_key: str) -> None:
+        """Recolor a row's ⚙ so a configured tool reads as configured."""
+        gear = self.autostart_gears.get(tool_key)
+        tool = self.tools_by_key.get(tool_key)
+        if gear is None or tool is None:
+            return
+        style = "CardAccent.TLabel" if get_autostart_conditions(tool) else "CardMuted.TLabel"
+        try:
+            gear.configure(style=style)
+        except tk.TclError:
+            pass
+
     def _show_icon_dialog(self, tool_key: str):
         """Show dialog to customize a tool's icon."""
         tool = self.tools_by_key.get(tool_key)
@@ -4176,8 +4474,22 @@ class InstallerApp:
             autostart_var = tk.BooleanVar(value=autostart_default)
             self.autostart_vars[key] = autostart_var
             autostart_var.trace_add("write", self._on_checkbox_changed)
-            autostart_cb = ttk.Checkbutton(autostart_frame, variable=autostart_var, style="Card.TCheckbutton")
-            autostart_cb.pack(expand=True)
+            # A tool with conditions gets the checkbox and a ⚙ side by side;
+            # without them the checkbox stays centred as before.
+            if tool.autostart_conditions:
+                holder = ttk.Frame(autostart_frame, style="Card.TFrame")
+                holder.pack(expand=True)
+                autostart_cb = ttk.Checkbutton(holder, variable=autostart_var, style="Card.TCheckbutton")
+                autostart_cb.pack(side="left")
+                gear = ttk.Label(holder, text="\u2699", cursor="hand2", style="CardMuted.TLabel")
+                gear.pack(side="left", padx=(2, 0))
+                gear.bind("<Button-1>",
+                          lambda _e, k=key: self._show_autostart_conditions_dialog(k))
+                self.autostart_gears[key] = gear
+                self._refresh_autostart_gear(key)
+            else:
+                autostart_cb = ttk.Checkbutton(autostart_frame, variable=autostart_var, style="Card.TCheckbutton")
+                autostart_cb.pack(expand=True)
 
         # Name row with tag badges
         name_row = ttk.Frame(info_frame, style="Card.TFrame")
@@ -4311,8 +4623,22 @@ class InstallerApp:
             autostart_var = tk.BooleanVar(value=autostart_default)
             self.autostart_vars[key] = autostart_var
             autostart_var.trace_add("write", self._on_checkbox_changed)
-            autostart_cb = ttk.Checkbutton(autostart_frame, variable=autostart_var, style="Card.TCheckbutton")
-            autostart_cb.pack(expand=True)
+            # A tool with conditions gets the checkbox and a ⚙ side by side;
+            # without them the checkbox stays centred as before.
+            if tool.autostart_conditions:
+                holder = ttk.Frame(autostart_frame, style="Card.TFrame")
+                holder.pack(expand=True)
+                autostart_cb = ttk.Checkbutton(holder, variable=autostart_var, style="Card.TCheckbutton")
+                autostart_cb.pack(side="left")
+                gear = ttk.Label(holder, text="\u2699", cursor="hand2", style="CardMuted.TLabel")
+                gear.pack(side="left", padx=(2, 0))
+                gear.bind("<Button-1>",
+                          lambda _e, k=key: self._show_autostart_conditions_dialog(k))
+                self.autostart_gears[key] = gear
+                self._refresh_autostart_gear(key)
+            else:
+                autostart_cb = ttk.Checkbutton(autostart_frame, variable=autostart_var, style="Card.TCheckbutton")
+                autostart_cb.pack(expand=True)
 
         name_row = ttk.Frame(info_frame, style="Card.TFrame")
         name_row.pack(anchor="w", fill="x")

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit/tool_installer.py

@@ -65,6 +65,11 @@ class ToolMetadata:
     # cli_tools_kit.skill_status() at advertise time and pass it in.
     skill_name: Optional[str] = None
     skill_status: Optional[str] = None
+    # Conditional autostart (PROTOCOL.md § Conditional autostart). Names the
+    # conditions this tool's autostart supports — "time_window", "network" —
+    # and nothing more: the values behind them are the user's, and the
+    # installer stores them per host. See cli_tools_kit.autostart_gate.
+    autostart_conditions: Optional[list] = None
 
 
 class ToolInstaller:

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.7.1
+Version: 0.8.1
 Summary: Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens
 Author: Steffen Probst
 License: MIT License

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 cli_tools_kit/__init__.py
 cli_tools_kit/__main__.py
 cli_tools_kit/advertise.py
+cli_tools_kit/autostart_gate.py
 cli_tools_kit/cron_installer.py
 cli_tools_kit/gui_installer.py
 cli_tools_kit/host.py
@@ -27,6 +28,7 @@ cli_tools_kit/taxonomy/corpus.py
 cli_tools_kit/taxonomy/embedder.py
 cli_tools_kit/taxonomy/groups.py
 cli_tools_kit/taxonomy/llm_groups.py
+tests/test_autostart_gate.py
 tests/test_capability_groups.py
 tests/test_cron_installer.py
 tests/test_host.py

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/cli_tools_kit.egg-info/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
 cli-tool-installer = cli_tools_kit.gui_installer:run
+cli-tools-kit-autostart-gate = cli_tools_kit.autostart_gate:main
 cli-tools-kit-setup = cli_tools_kit.onboarding:main

{cli_tools_kit-0.7.1 → cli_tools_kit-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cli-tools-kit"
-version = "0.7.1"
+version = "0.8.1"
 description = "Installer protocol + helpers for self-installing Python CLI/GUI tools (desktop shortcuts, bash aliases, cron entries), plus reusable tkinter and curses installer screens"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -49,6 +49,9 @@ cli-tool-installer = "cli_tools_kit.gui_installer:run"
 # First-run setup for an organisation adopting the kit. Same thing as
 # `python3 -m cli_tools_kit`.
 cli-tools-kit-setup = "cli_tools_kit.onboarding:main"
+# Wrapper an autostart .desktop Exec line calls to evaluate a tool's
+# conditions before launching it. See cli_tools_kit.autostart_gate.
+cli-tools-kit-autostart-gate = "cli_tools_kit.autostart_gate:main"
 
 [project.urls]
 Homepage = "https://github.com/Probst1nator/cli-tools-kit"

cli_tools_kit-0.8.1/tests/test_autostart_gate.py

@@ -0,0 +1,236 @@
+"""Tests for autostart_gate — time-window and network conditions on autostart."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+from cli_tools_kit import ToolMetadata, advertise
+from cli_tools_kit import autostart_gate as gate
+
+
+# ------------------------------------------------------------- time_window
+
+@pytest.mark.parametrize("hour,expected", [
+    (5, False), (6, True), (9, True), (11, True), (12, False), (23, False),
+])
+def test_time_window_half_open(hour: int, expected: bool) -> None:
+    """06:00-12:00 includes its start and excludes its end."""
+    window = {"from": "06:00", "to": "12:00"}
+    now = datetime(2026, 9, 16, hour, 0)
+    assert gate.time_window_open(window, now) is expected
+
+
+@pytest.mark.parametrize("hour,expected", [
+    (21, False), (22, True), (23, True), (0, True), (1, True), (2, False),
+])
+def test_time_window_wraps_midnight(hour: int, expected: bool) -> None:
+    """An end not after the start reads as a window across midnight."""
+    window = {"from": "22:00", "to": "02:00"}
+    now = datetime(2026, 9, 16, hour, 0)
+    assert gate.time_window_open(window, now) is expected
+
+
+def test_time_window_unparseable_does_not_restrict() -> None:
+    """A malformed window must not silently disable a tool forever."""
+    assert gate.time_window_open({"from": "oops", "to": "12:00"}) is True
+    assert gate.time_window_open({}) is True
+    assert gate.time_window_open({"from": "06:00", "to": "06:00"}) is True
+
+
+# ----------------------------------------------------------------- network
+
+def test_network_matches_active_ssid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gate, "current_ssids", lambda: ["b_wifi"])
+    assert gate.network_matches({"ssids": ["b_wifi", "b2_wifi"]}, wait=False) is True
+
+
+def test_network_rejects_other_ssid(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gate, "current_ssids", lambda: ["cafe_guest"])
+    assert gate.network_matches({"ssids": ["b_wifi"]}, wait=False) is False
+
+
+def test_network_empty_list_does_not_restrict(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gate, "current_ssids", lambda: [])
+    assert gate.network_matches({"ssids": []}, wait=False) is True
+
+
+def test_network_waits_for_late_association(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The link usually associates after login, so the gate polls for it."""
+    seen = {"calls": 0}
+
+    def ssids():
+        seen["calls"] += 1
+        return ["b_wifi"] if seen["calls"] >= 3 else []
+
+    monkeypatch.setattr(gate, "current_ssids", ssids)
+    monkeypatch.setattr(gate.time, "sleep", lambda _s: None)
+    assert gate.network_matches({"ssids": ["b_wifi"], "grace_seconds": 60}) is True
+    assert seen["calls"] >= 3
+
+
+def test_network_gives_up_after_grace(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gate, "current_ssids", lambda: [])
+    monkeypatch.setattr(gate.time, "sleep", lambda _s: None)
+    assert gate.network_matches({"ssids": ["b_wifi"], "grace_seconds": 1}) is False
+
+
+def test_current_ssids_reads_active_only(monkeypatch: pytest.MonkeyPatch) -> None:
+    class Result:
+        returncode = 0
+        stdout = "no:neighbour_wifi\nyes:b_wifi\nno:other\n"
+
+    monkeypatch.setattr(gate.subprocess, "run", lambda *a, **k: Result())
+    assert gate.current_ssids() == ["b_wifi"]
+
+
+def test_current_ssids_survives_missing_nmcli(monkeypatch: pytest.MonkeyPatch) -> None:
+    def boom(*_a, **_k):
+        raise FileNotFoundError("nmcli")
+
+    monkeypatch.setattr(gate.subprocess, "run", boom)
+    assert gate.current_ssids() == []
+
+
+# -------------------------------------------------------------- evaluation
+
+def test_conditions_pass_with_nothing_configured() -> None:
+    assert gate.conditions_pass({}) == (True, "")
+
+
+def test_conditions_report_the_failing_one(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(gate, "time_window_open", lambda *_a, **_k: False)
+    passed, reason = gate.conditions_pass({"time_window": {"from": "06:00", "to": "12:00"}})
+    assert passed is False
+    assert "06:00" in reason
+
+
+def test_unknown_condition_is_skipped_not_failed() -> None:
+    """Config from a newer kit must not shut the gate on an older one."""
+    assert gate.conditions_pass({"phase_of_moon": {"full": True}}) == (True, "")
+
+
+# ------------------------------------------------------------------ config
+
+def test_legacy_slug_uses_the_installers_own_config_dir(
+        tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """The legacy identity overrides config_dir, and the gate must follow it.
+
+    Deriving the path from the slug alone would look in ~/.config/probable.work
+    while the installer writes ~/.config/tools-installer, so every gated tool
+    would read an empty config and start unconditionally.
+    """
+    from cli_tools_kit.identity import LEGACY_IDENTITY
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    assert gate.config_path(LEGACY_IDENTITY.slug) == os.path.join(
+        LEGACY_IDENTITY.config_path, "autostart.json")
+    assert "tools-installer" in gate.config_path(LEGACY_IDENTITY.slug)
+
+
+def test_conditions_round_trip(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    conditions = {"network": {"ssids": ["b_wifi"], "grace_seconds": 120}}
+    gate.save_tool_conditions("acme-tools", "jarvis", conditions)
+    assert gate.load_tool_conditions("acme-tools", "jarvis") == conditions
+
+
+def test_conditions_are_per_tool(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    gate.save_tool_conditions("acme-tools", "jarvis", {"network": {"ssids": ["b_wifi"]}})
+    gate.save_tool_conditions("acme-tools", "lernclaude",
+                              {"time_window": {"from": "06:00", "to": "12:00"}})
+    assert gate.load_tool_conditions("acme-tools", "jarvis") == {
+        "network": {"ssids": ["b_wifi"]}}
+    assert gate.load_tool_conditions("acme-tools", "lernclaude") == {
+        "time_window": {"from": "06:00", "to": "12:00"}}
+
+
+def test_saving_empty_clears_a_tool(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    gate.save_tool_conditions("acme-tools", "jarvis", {"network": {"ssids": ["b_wifi"]}})
+    gate.save_tool_conditions("acme-tools", "jarvis", {})
+    assert gate.load_tool_conditions("acme-tools", "jarvis") == {}
+
+
+def test_missing_config_reads_as_no_conditions(tmp_path: Path,
+                                               monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    assert gate.load_tool_conditions("acme-tools", "nothing-here") == {}
+
+
+def test_corrupt_config_gates_open(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """An unreadable config must not stop every gated tool from starting."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    path = Path(gate.config_path("acme-tools"))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("{not json")
+    assert gate.load_tool_conditions("acme-tools", "jarvis") == {}
+
+
+# ------------------------------------------------------------------- entry
+
+def test_closed_gate_exits_zero(tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+                                capsys: pytest.CaptureFixture) -> None:
+    """A non-zero exit would surface as a failed systemd unit every login."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    gate.save_tool_conditions("acme-tools", "lernclaude",
+                              {"time_window": {"from": "06:00", "to": "06:01"}})
+    monkeypatch.setattr(gate, "time_window_open", lambda *_a, **_k: False)
+    rc = gate.main(["--slug", "acme-tools", "--tool", "lernclaude", "--", "/bin/true"])
+    assert rc == 0
+    assert "not started" in capsys.readouterr().err
+
+
+def test_open_gate_execs_the_command(tmp_path: Path,
+                                     monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    execed = {}
+
+    def fake_exec(binary, argv):
+        execed["binary"] = binary
+        execed["argv"] = list(argv)
+        raise SystemExit(0)
+
+    monkeypatch.setattr(gate.os, "execvp", fake_exec)
+    with pytest.raises(SystemExit):
+        gate.main(["--slug", "acme-tools", "--tool", "anything",
+                   "--", "/usr/bin/python3", "main.py"])
+    assert execed["binary"] == "/usr/bin/python3"
+    assert execed["argv"] == ["/usr/bin/python3", "main.py"]
+
+
+def test_check_reports_without_running(tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+                                       capsys: pytest.CaptureFixture) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    rc = gate.main(["--slug", "acme-tools", "--tool", "unconfigured", "--check"])
+    assert rc == 0
+    assert "open" in capsys.readouterr().out
+
+
+# --------------------------------------------------------------- advertise
+
+def test_advertise_emits_conditions(capsys: pytest.CaptureFixture) -> None:
+    import json
+
+    with pytest.raises(SystemExit):
+        advertise(ToolMetadata(
+            name="Jarvis", desktop_file="jarvis.desktop", icon="mic",
+            desc="Voice assistant", autostart_conditions=["network"],
+        ))
+    record = json.loads(capsys.readouterr().out)[0]
+    assert record["autostart_conditions"] == ["network"]
+
+
+def test_advertise_omits_conditions_when_unset(capsys: pytest.CaptureFixture) -> None:
+    """A tool that never touched the field emits a pre-0.8.0 record."""
+    import json
+
+    with pytest.raises(SystemExit):
+        advertise(ToolMetadata(
+            name="Plain", desktop_file="plain.desktop", icon="x", desc="y",
+        ))
+    assert "autostart_conditions" not in json.loads(capsys.readouterr().out)[0]