cli-tools-kit 0.6.0__tar.gz → 0.6.2__tar.gz

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -417,8 +417,20 @@ path = "/home/me/work/lab-tools"
 
 A source resolves in this order: the path from the local file, then the `path`
 from the tracked file, then an existing `<root>/<name>`, then a clone of `url`
-into `<root>/<name>`. The root is `--root DIR` if given, else the local file's
-`root`, else two levels above the directory the config file sits in.
+into `<root>/<name>`.
+
+The root is `--root DIR` if given, else the local file's `root`, else the answer
+to a question. The GUI asks in a small dialog before discovery, the text screen
+asks in one line on stdin, and both suggest `<current directory>/<name>` as an
+absolute path — `<name>` is `run_installer`'s `default_root_name`, `tools` by
+default. The answer is written into `installer.local.toml` as its `root`, above
+any `[[source]]` tables already there, so the question is asked once per
+machine; a `root` that file already has is left alone. The directory is created
+if it does not exist, and cancelling the dialog installs nothing.
+
+A headless run never asks: `--list`, `--apply`, `--check`, or a text screen with
+no terminal take the suggestion and print `root: /abs/path (pass --root to
+change)`.
 
 Cloning is deliberately narrow. Only `https://` URLs are cloned, `ext::` and
 `file://` transports and any hook are switched off for the git call, the clone is
@@ -447,14 +459,16 @@ from cli_tools_kit.sources import run_installer
 HERE = os.path.dirname(os.path.abspath(__file__))
 run_installer(os.path.join(HERE, "installer.toml"),
               identity=InstallerIdentity(slug="acme-tools", title="Acme Tools"),
+              default_root_name="acme-tools",
               entry_script=__file__)
 ```
 
 `run_installer` takes `--root DIR` for itself and leaves every other flag to the
 engine, so `--list`, `--apply`, `--skill-target`, `--check`, `--refresh`, `--tui`
-and `--gui` work as they do without sources. Every keyword besides `config_path`
-and `argv` goes to `run()`; `discovery_roots` and `pre_discovery` are the
-function's own to set and passing either raises `TypeError`.
+and `--gui` work as they do without sources. Every keyword besides `config_path`,
+`argv` and `default_root_name` goes to `run()`; `discovery_roots` and
+`pre_discovery` are the function's own to set and passing either raises
+`TypeError`.
 
 Without a wrapper, the same thing from the command line:
 

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/README.md

@@ -364,8 +364,20 @@ path = "/home/me/work/lab-tools"
 
 A source resolves in this order: the path from the local file, then the `path`
 from the tracked file, then an existing `<root>/<name>`, then a clone of `url`
-into `<root>/<name>`. The root is `--root DIR` if given, else the local file's
-`root`, else two levels above the directory the config file sits in.
+into `<root>/<name>`.
+
+The root is `--root DIR` if given, else the local file's `root`, else the answer
+to a question. The GUI asks in a small dialog before discovery, the text screen
+asks in one line on stdin, and both suggest `<current directory>/<name>` as an
+absolute path — `<name>` is `run_installer`'s `default_root_name`, `tools` by
+default. The answer is written into `installer.local.toml` as its `root`, above
+any `[[source]]` tables already there, so the question is asked once per
+machine; a `root` that file already has is left alone. The directory is created
+if it does not exist, and cancelling the dialog installs nothing.
+
+A headless run never asks: `--list`, `--apply`, `--check`, or a text screen with
+no terminal take the suggestion and print `root: /abs/path (pass --root to
+change)`.
 
 Cloning is deliberately narrow. Only `https://` URLs are cloned, `ext::` and
 `file://` transports and any hook are switched off for the git call, the clone is
@@ -394,14 +406,16 @@ from cli_tools_kit.sources import run_installer
 HERE = os.path.dirname(os.path.abspath(__file__))
 run_installer(os.path.join(HERE, "installer.toml"),
               identity=InstallerIdentity(slug="acme-tools", title="Acme Tools"),
+              default_root_name="acme-tools",
               entry_script=__file__)
 ```
 
 `run_installer` takes `--root DIR` for itself and leaves every other flag to the
 engine, so `--list`, `--apply`, `--skill-target`, `--check`, `--refresh`, `--tui`
-and `--gui` work as they do without sources. Every keyword besides `config_path`
-and `argv` goes to `run()`; `discovery_roots` and `pre_discovery` are the
-function's own to set and passing either raises `TypeError`.
+and `--gui` work as they do without sources. Every keyword besides `config_path`,
+`argv` and `default_root_name` goes to `run()`; `discovery_roots` and
+`pre_discovery` are the function's own to set and passing either raises
+`TypeError`.
 
 Without a wrapper, the same thing from the command line:
 

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/cli_tools_kit/__init__.py

@@ -56,4 +56,4 @@ __all__ = [
     "read_installed_skill",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/cli_tools_kit/gui_installer.py

@@ -1794,6 +1794,7 @@ class InstallerApp:
         self.root.withdraw()  # Hide until properly sized
         self.tools = tools
         self.root.title(WINDOW_TITLE)
+        self._set_window_icon()
         saved_theme = load_config().get("theme", "ocean")
         self.current_theme = saved_theme if saved_theme in self.THEMES else "ocean"
 
@@ -1835,6 +1836,27 @@ class InstallerApp:
         # warning so the two don't fight over the log/dialog at the same tick.
         self.root.after(200, self._maybe_auto_update_on_startup)
 
+    def _set_window_icon(self) -> None:
+        """Apply SELF_DESKTOP_ICON to the live window (taskbar/titlebar).
+
+        SELF_DESKTOP_ICON is otherwise only written into the .desktop file's
+        Icon= line, so a run straight from a terminal showed the generic Tk
+        icon instead. Only an absolute image path can be used here (a
+        freedesktop icon *name* has no file to load without a theme lookup).
+        """
+        icon_path = SELF_DESKTOP_ICON
+        if not icon_path or not os.path.isabs(icon_path) or not os.path.isfile(icon_path):
+            return
+        try:
+            if _HAVE_PIL:
+                image = ImageTk.PhotoImage(Image.open(icon_path))
+            else:
+                image = tk.PhotoImage(file=icon_path)
+            self.root.iconphoto(True, image)
+            self._icon_photo = image  # keep a reference; Tk drops the icon otherwise
+        except Exception:
+            pass  # cosmetic only; never block startup over a bad/unsupported icon
+
     def _get_primary_monitor_geometry(self) -> tuple[int, int, int, int]:
         """Get primary monitor geometry (x, y, width, height). Falls back to tkinter defaults."""
         try:
@@ -1918,6 +1940,17 @@ class InstallerApp:
         # Windows/Mac use MouseWheel
         self.canvas.bind_all("<MouseWheel>", _on_mousewheel)
 
+    def _fit_canvas_width(self):
+        """Stretch the scrollable content to the canvas' current width.
+
+        The canvas window item keeps the width it is given, so without this the
+        table falls back to its requested width — the minimum every column
+        needs — and leaves the right of the window empty.
+        """
+        width = self.canvas.winfo_width()
+        if width > 1:
+            self.canvas.itemconfig(self.canvas_window, width=width)
+
     def _on_canvas_configure(self, event):
         """Handle canvas resize: adjust content width and show/hide scrollbar."""
         # Make content fill canvas width
@@ -2203,6 +2236,15 @@ class InstallerApp:
         # Restore window geometry
         self.root.geometry(geometry)
 
+        # _setup_ui built a new canvas, and the old one died with the old UI.
+        # The mouse wheel is bound to the widget by name, so re-bind it, and
+        # give the new window item the canvas width at once: without it the
+        # table keeps its requested width, which is the sum of the minimum
+        # column widths, and sits at the left with empty space to its right.
+        self._bind_mousewheel()
+        self.root.update_idletasks()
+        self._fit_canvas_width()
+
     def _setup_ui(self):
         # Configure styles
         self.style = ttk.Style()
@@ -2416,6 +2458,10 @@ class InstallerApp:
                 current_row = self._render_tool_group(group, current_row)
 
         self.canvas.grid(row=0, column=0, sticky="nsew")
+        # Bound here rather than only in _position_window, which runs once at
+        # startup: a theme switch rebuilds the UI, and the new canvas needs the
+        # binding that keeps the table as wide as the window.
+        self.canvas.bind("<Configure>", self._on_canvas_configure)
         # Scrollbar initially hidden - will be shown in _position_window if needed
 
         # Footer / Buttons

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/cli_tools_kit/sources.py

@@ -24,6 +24,11 @@ for a source matched by ``name``:
     name = "acme/lab"
     path = "/home/me/work/lab-tools"
 
+The root is never guessed from where the config file happens to sit.
+``run_installer`` takes ``--root``, else the ``root`` of the local file, else it
+asks the user, and writes the answer back into the local file so the question is
+asked once.
+
 A source resolves in this order: the path from the local file, then the ``path``
 from the tracked file, then an existing ``<root>/<name>``, then a clone of
 ``url`` into ``<root>/<name>``. Only ``https://`` URLs are cloned, the clone is
@@ -56,7 +61,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable, List, Optional, Sequence
 
-__all__ = ["Source", "load_sources", "resolve_sources", "run_installer"]
+__all__ = ["Source", "load_sources", "resolve_sources", "run_installer",
+           "local_root", "save_local_root", "default_root"]
 
 # How far below the top-level installer.toml a nested one is still read.
 MAX_NESTING = 1
@@ -132,6 +138,35 @@ def local_root(config_path, local_path=None) -> Optional[str]:
     return None
 
 
+def save_local_root(config_path, root, local_path=None, log: Callable = print) -> bool:
+    """Write ``root`` into the local file next to ``config_path``.
+
+    Returns False and changes nothing when the file already sets a ``root``: a
+    value someone put there by hand is never overwritten. Existing
+    ``[[source]]`` entries are kept, and the key is written above them, because
+    a top-level key written after a table would belong to that table.
+    """
+    config_path = Path(config_path)
+    local = Path(local_path) if local_path is not None else _local_path_for(config_path)
+    if local_root(config_path, local) is not None:
+        return False
+    existing = ""
+    if local.is_file():
+        try:
+            existing = local.read_text(encoding="utf-8")
+        except OSError as exc:
+            log(f"{local.name}: not updated ({exc})")
+            return False
+    line = f'root = "{root}"\n'
+    try:
+        local.write_text(line + ("\n" + existing.lstrip("\n") if existing.strip() else ""),
+                         encoding="utf-8")
+    except OSError as exc:
+        log(f"{local.name}: not written ({exc})")
+        return False
+    return True
+
+
 def load_sources(config_path, local_path=None, log: Callable = print) -> List[Source]:
     """The ``[[source]]`` entries of one TOML file, local overrides applied.
 
@@ -174,10 +209,14 @@ def _git(*args):
     return result.returncode == 0, (result.stdout + result.stderr).strip()
 
 
-def _clone_reason(output: str) -> str:
+def _git_reason(output: str, fallback: str = "git failed") -> str:
     lines = [line.strip() for line in output.splitlines() if line.strip()]
     return next((line for line in lines if line.startswith("fatal:")),
-                lines[-1] if lines else "git clone failed")
+                lines[-1] if lines else fallback)
+
+
+def _clone_reason(output: str) -> str:
+    return _git_reason(output, "git clone failed")
 
 
 def _resolve_one(source: Source, root: Path, refresh: bool, log: Callable,
@@ -189,9 +228,13 @@ def _resolve_one(source: Source, root: Path, refresh: bool, log: Callable,
     target = root.joinpath(*source.name.split("/"))
     if target.is_dir():
         if refresh and clone and (target / ".git").is_dir() and source.url:
-            ok, _ = _git("-C", str(target), "pull", "--ff-only")
+            ok, out = _git("-C", str(target), "pull", "--ff-only")
+            # A pull can fail for reasons the user cannot fix here: the remote
+            # is gone, the network is down, the history diverged. One line, and
+            # the checkout that is already on disk is used as it stands.
             log(f"{source.name}: pulled" if ok else
-                f"{source.name}: left as is, local changes or diverged history")
+                f"{source.name}: not updated, using the checkout as it is"
+                f" ({_git_reason(out)})")
         return target.resolve()
 
     if not source.url:
@@ -279,16 +322,126 @@ def _take_root(argv: List[str]):
     return rest, root
 
 
-def default_root(config_path) -> str:
-    """Two levels above the config file's directory.
+def default_root(name: str = "tools") -> str:
+    """The suggested install location: ``<current directory>/<name>``.
 
-    A bootstrap script clones the first repo to ``<root>/<org>/<tool tree>``, so
-    the other sources belong two levels up from the file that lists them.
+    Absolute, because the user is shown this string and has to recognise where
+    it points. It is only ever a suggestion: what the user types in the dialog
+    or on stdin wins, and ``--root`` wins over both.
     """
-    return str(Path(config_path).absolute().parent.parent.parent)
+    return str(Path.cwd().joinpath(name).absolute())
+
+
+# Flags that mean nobody is watching the screen, so nothing may block on input.
+HEADLESS_FLAGS = ("--list", "--check", "--apply")
+
+
+def _is_headless(argv: Sequence[str]) -> bool:
+    return any(arg in HEADLESS_FLAGS or arg.startswith("--apply=") for arg in argv)
+
+
+def _wants_gui(argv: Sequence[str]) -> bool:
+    """True when the tkinter window is the screen this run will open."""
+    from . import tui_installer  # noqa: PLC0415 — pulls in the engine, keep it lazy
+    from .gui_installer import _HAVE_TK  # noqa: PLC0415
+    return not tui_installer.prefer_tui(force_tui="--tui" in argv,
+                                        force_gui="--gui" in argv,
+                                        have_tk=_HAVE_TK)
 
 
-def run_installer(config_path, argv=None, **run_kwargs):
+def _ask_root_gui(default: str) -> Optional[str]:
+    """A small window asking where the tools go. None when the user cancels."""
+    import tkinter as tk  # noqa: PLC0415
+    from tkinter import filedialog  # noqa: PLC0415
+
+    win = tk.Tk()
+    win.title("Install location")
+    chosen: List[str] = []
+    value = tk.StringVar(value=default)
+
+    tk.Label(win, text="Where should the tools be installed?",
+             font=("", 12, "bold")).pack(anchor="w", padx=16, pady=(16, 6))
+    tk.Label(win, text="The folder is created if it does not exist.",
+             justify="left").pack(anchor="w", padx=16)
+
+    row = tk.Frame(win)
+    row.pack(fill="x", padx=16, pady=12)
+    entry = tk.Entry(row, textvariable=value, width=54)
+    entry.pack(side="left", fill="x", expand=True)
+
+    def browse():
+        picked = filedialog.askdirectory(parent=win, title="Install location",
+                                         initialdir=os.path.dirname(value.get()) or "/")
+        if picked:
+            value.set(str(Path(picked).absolute()))
+
+    tk.Button(row, text="Browse…", command=browse).pack(side="left", padx=(8, 0))
+
+    buttons = tk.Frame(win)
+    buttons.pack(fill="x", padx=16, pady=(0, 16))
+
+    def ok(*_):
+        text = value.get().strip()
+        if text:
+            chosen.append(text)
+        win.destroy()
+
+    tk.Button(buttons, text="OK", command=ok, width=10).pack(side="right")
+    tk.Button(buttons, text="Cancel", command=win.destroy, width=10).pack(side="right", padx=8)
+    win.bind("<Return>", ok)
+    win.protocol("WM_DELETE_WINDOW", win.destroy)
+    entry.focus_set()
+    entry.icursor("end")
+    win.mainloop()
+    return chosen[0] if chosen else None
+
+
+def _ask_root_stdin(default: str) -> Optional[str]:
+    """One line on stdin, before any curses screen opens. None on Ctrl-D."""
+    try:
+        answer = input(f"Where should the tools be installed? [{default}] ")
+    except EOFError:
+        return None
+    return answer.strip() or default
+
+
+def _resolve_root(config_path: Path, root_arg: Optional[str], argv: Sequence[str],
+                  default_root_name: str, log: Callable = print) -> str:
+    """Settle the clone root: the flag, the local file, the user, the default.
+
+    Asks only when the first two miss. The tkinter dialog is used when this run
+    opens the tkinter window, the stdin prompt when it opens the text screen on
+    a terminal. A headless run (``--list``, ``--apply``, ``--check``, or a text
+    screen without a terminal) never asks: it takes the default and says so.
+    """
+    if root_arg:
+        return str(Path(os.path.expanduser(root_arg)).absolute())
+    stored = local_root(config_path)
+    if stored:
+        return stored
+
+    default = default_root(default_root_name)
+    if _is_headless(argv):
+        log(f"root: {default} (pass --root to change)")
+        return default
+
+    if _wants_gui(argv):
+        answer = _ask_root_gui(default)
+    elif sys.stdin is not None and sys.stdin.isatty():
+        answer = _ask_root_stdin(default)
+    else:
+        log(f"root: {default} (pass --root to change)")
+        return default
+
+    if answer is None:
+        print("No install location chosen, nothing was installed.")
+        raise SystemExit(0)
+    chosen = str(Path(os.path.expanduser(answer)).absolute())
+    save_local_root(config_path, chosen, log=log)
+    return chosen
+
+
+def run_installer(config_path, argv=None, default_root_name: str = "tools", **run_kwargs):
     """Read a sources file, wire the engine to it, and run the installer.
 
     ``--root DIR`` is taken from ``argv`` (``sys.argv[1:]`` by default) and the
@@ -297,11 +450,18 @@ def run_installer(config_path, argv=None, **run_kwargs):
     engine's flag: it reaches the pre-discovery hook, which then pulls every
     clone.
 
-    The root is ``--root`` if given, else the ``root`` of the local file, else
-    two levels above the config file's directory. Cloning happens in the
+    The root is ``--root`` if given, else the ``root`` of
+    ``installer.local.toml``, else the user's answer to a question, else — on a
+    headless run only — ``<current directory>/<default_root_name>``. The answer
+    is written into ``installer.local.toml``, so the question is asked once.
+    The root directory is created if it does not exist. Cloning happens in the
     pre-discovery hook, which the engine skips on the ``--check`` path, so that
     check stays network-free and sees whatever is already on disk.
 
+    ``default_root_name`` is the folder name the suggestion ends in, so an
+    organisation's installer can suggest ``<cwd>/WW3-tools`` rather than
+    ``<cwd>/tools``.
+
     Every other keyword goes to :func:`cli_tools_kit.gui_installer.run`.
     ``discovery_roots`` and ``pre_discovery`` are this function's to set.
     ``prune`` reaches the walker that way, so a wrapper can name directories
@@ -316,8 +476,11 @@ def run_installer(config_path, argv=None, **run_kwargs):
     argv, root_arg = _take_root(argv)
     sys.argv = [sys.argv[0]] + argv
 
-    root = root_arg or local_root(config_path) or default_root(config_path)
-    root = str(Path(os.path.expanduser(root)).absolute())
+    root = _resolve_root(config_path, root_arg, argv, default_root_name)
+    try:
+        os.makedirs(root, exist_ok=True)
+    except OSError as exc:
+        print(f"{root}: not created ({exc})")
     sources = load_sources(config_path)
 
     # The engine reads DISCOVERY_ROOTS after the hook has run, so the hook fills

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/cli_tools_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-tools-kit
-Version: 0.6.0
+Version: 0.6.2
 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
@@ -417,8 +417,20 @@ path = "/home/me/work/lab-tools"
 
 A source resolves in this order: the path from the local file, then the `path`
 from the tracked file, then an existing `<root>/<name>`, then a clone of `url`
-into `<root>/<name>`. The root is `--root DIR` if given, else the local file's
-`root`, else two levels above the directory the config file sits in.
+into `<root>/<name>`.
+
+The root is `--root DIR` if given, else the local file's `root`, else the answer
+to a question. The GUI asks in a small dialog before discovery, the text screen
+asks in one line on stdin, and both suggest `<current directory>/<name>` as an
+absolute path — `<name>` is `run_installer`'s `default_root_name`, `tools` by
+default. The answer is written into `installer.local.toml` as its `root`, above
+any `[[source]]` tables already there, so the question is asked once per
+machine; a `root` that file already has is left alone. The directory is created
+if it does not exist, and cancelling the dialog installs nothing.
+
+A headless run never asks: `--list`, `--apply`, `--check`, or a text screen with
+no terminal take the suggestion and print `root: /abs/path (pass --root to
+change)`.
 
 Cloning is deliberately narrow. Only `https://` URLs are cloned, `ext::` and
 `file://` transports and any hook are switched off for the git call, the clone is
@@ -447,14 +459,16 @@ from cli_tools_kit.sources import run_installer
 HERE = os.path.dirname(os.path.abspath(__file__))
 run_installer(os.path.join(HERE, "installer.toml"),
               identity=InstallerIdentity(slug="acme-tools", title="Acme Tools"),
+              default_root_name="acme-tools",
               entry_script=__file__)
 ```
 
 `run_installer` takes `--root DIR` for itself and leaves every other flag to the
 engine, so `--list`, `--apply`, `--skill-target`, `--check`, `--refresh`, `--tui`
-and `--gui` work as they do without sources. Every keyword besides `config_path`
-and `argv` goes to `run()`; `discovery_roots` and `pre_discovery` are the
-function's own to set and passing either raises `TypeError`.
+and `--gui` work as they do without sources. Every keyword besides `config_path`,
+`argv` and `default_root_name` goes to `run()`; `discovery_roots` and
+`pre_discovery` are the function's own to set and passing either raises
+`TypeError`.
 
 Without a wrapper, the same thing from the command line:
 

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cli-tools-kit"
-version = "0.6.0"
+version = "0.6.2"
 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"

{cli_tools_kit-0.6.0 → cli_tools_kit-0.6.2}/tests/test_sources.py

@@ -151,6 +151,29 @@ def test_refresh_pulls_a_clone_ff_only(tmp_path: Path, monkeypatch) -> None:
     assert "clone" not in calls[0]
 
 
+def test_a_failed_pull_keeps_the_clone_as_a_discovery_root(tmp_path: Path,
+                                                           monkeypatch) -> None:
+    """A remote that is gone, a network that is down, a diverged history.
+
+    One line about it, and the checkout that is already on disk is still used.
+    """
+    target = _repo(tmp_path / "root" / "org" / "lab")
+
+    class Result:
+        returncode = 128
+        stdout = ""
+        stderr = ("fatal: repository 'https://example.invalid/lab.git/' not found\n")
+
+    monkeypatch.setattr(sources.subprocess, "run", lambda cmd, **kw: Result())
+    lines: list = []
+    source = Source(name="org/lab", url="https://example.invalid/lab.git")
+    assert resolve_sources([source], tmp_path / "root", refresh=True,
+                           log=lines.append) == [target]
+    assert target.is_dir()
+    assert len(lines) == 1
+    assert "not found" in lines[0]
+
+
 def test_a_checkout_given_by_path_is_never_pulled(tmp_path: Path, monkeypatch) -> None:
     given = _repo(tmp_path / "given")
     calls: list = []
@@ -289,9 +312,11 @@ def _tree(tmp_path: Path) -> Path:
                   '[[source]]\nname = "org/tools"\npath = "."\n')
 
 
-def test_run_installer_wires_roots_and_the_hook(tmp_path: Path, engine) -> None:
+def test_run_installer_wires_roots_and_the_hook(tmp_path: Path, engine,
+                                                monkeypatch) -> None:
     config = _tree(tmp_path)
-    sources.run_installer(config, argv=["--list"])
+    monkeypatch.chdir(tmp_path)
+    sources.run_installer(config, argv=["--list", "--root", str(tmp_path)])
     assert engine["root_dir"] == str(tmp_path)
     assert engine["discovery_roots"] == [str(tmp_path / "org" / "tools")]
     assert callable(engine["pre_discovery"])
@@ -311,7 +336,8 @@ def test_root_flag_wins_and_is_consumed(tmp_path: Path, engine) -> None:
     assert sys.argv[1:] == ["--check"]
 
 
-def test_local_root_is_the_default_when_no_flag(tmp_path: Path, engine) -> None:
+def test_local_root_is_the_default_when_no_flag(tmp_path: Path, engine,
+                                                never_asks) -> None:
     config = _tree(tmp_path)
     _write(config.with_name("installer.local.toml"), f'root = "{tmp_path / "here"}"\n')
     sources.run_installer(config, argv=[])
@@ -332,7 +358,7 @@ url = "https://example.invalid/lab.git"
 """)
     calls: list = []
     monkeypatch.setattr(sources.subprocess, "run", _fake_git(calls))
-    sources.run_installer(config, argv=[])
+    sources.run_installer(config, argv=["--root", str(tmp_path)])
     roots = engine["discovery_roots"]
     # Before the hook: only what is on disk, so --check never needs the network.
     assert roots == [str(tmp_path / "org" / "tools")]
@@ -341,6 +367,140 @@ url = "https://example.invalid/lab.git"
     assert any("clone" in call for call in calls)
 
 
+# --- where the tools are installed ------------------------------------------
+
+def _refuse(default):
+    raise AssertionError(f"asked for a root, suggesting {default}")
+
+
+@pytest.fixture
+def never_asks(monkeypatch):
+    """Fail the test if either prompt is reached."""
+    monkeypatch.setattr(sources, "_ask_root_gui", _refuse)
+    monkeypatch.setattr(sources, "_ask_root_stdin", _refuse)
+
+
+def _answers(monkeypatch, answer, gui: bool = True):
+    """Route the question to one screen and answer it. Returns the suggestions."""
+    seen: list = []
+
+    def ask(default):
+        seen.append(default)
+        return answer
+
+    monkeypatch.setattr(sources, "_wants_gui", lambda argv: gui)
+    monkeypatch.setattr(sources, "_ask_root_gui" if gui else "_ask_root_stdin", ask)
+    if not gui:
+        monkeypatch.setattr(sources.sys, "stdin",
+                            type("Tty", (), {"isatty": staticmethod(lambda: True)})())
+    return seen
+
+
+def test_the_root_flag_is_used_without_asking(tmp_path: Path, engine, never_asks,
+                                              monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    sources.run_installer(config, argv=["--root", str(tmp_path / "chosen")])
+    assert engine["root_dir"] == str(tmp_path / "chosen")
+    assert (tmp_path / "chosen").is_dir()      # created for us
+    # Nothing is remembered: the flag is for this run.
+    assert not config.with_name("installer.local.toml").exists()
+
+
+def test_the_answer_is_used_and_remembered(tmp_path: Path, engine, monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    chosen = tmp_path / "picked"
+    suggested = _answers(monkeypatch, str(chosen))
+
+    sources.run_installer(config, argv=[])
+    assert engine["root_dir"] == str(chosen)
+    assert chosen.is_dir()
+    assert suggested == [str(tmp_path / "tools")]   # <cwd>/<default_root_name>
+    assert sources.local_root(config) == str(chosen)
+
+    # Asked once: the second run reads the file.
+    monkeypatch.setattr(sources, "_ask_root_gui", _refuse)
+    sources.run_installer(config, argv=[])
+    assert engine["root_dir"] == str(chosen)
+
+
+def test_the_answer_keeps_the_local_files_sources(tmp_path: Path, engine,
+                                                  monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    local = _write(config.with_name("installer.local.toml"),
+                   f'[[source]]\nname = "org/tools"\npath = "{tmp_path / "other"}"\n')
+    _answers(monkeypatch, str(tmp_path / "picked"))
+    sources.run_installer(config, argv=[])
+    assert sources.local_root(config) == str(tmp_path / "picked")
+    assert load_sources(config)[0].path == str(tmp_path / "other")
+    assert '[[source]]' in local.read_text(encoding="utf-8")
+
+
+def test_an_existing_root_in_the_local_file_is_never_overwritten(tmp_path: Path) -> None:
+    config = _write(tmp_path / "installer.toml", "")
+    _write(config.with_name("installer.local.toml"), f'root = "{tmp_path / "mine"}"\n')
+    assert sources.save_local_root(config, str(tmp_path / "other")) is False
+    assert sources.local_root(config) == str(tmp_path / "mine")
+
+
+def test_the_default_root_name_names_the_suggested_folder(tmp_path: Path, engine,
+                                                          monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    suggested = _answers(monkeypatch, str(tmp_path / "picked"))
+    sources.run_installer(config, argv=[], default_root_name="WW3-tools")
+    assert suggested == [str(tmp_path / "WW3-tools")]
+
+
+def test_cancelling_the_question_stops_cleanly(tmp_path: Path, engine,
+                                               monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    _answers(monkeypatch, None)
+    with pytest.raises(SystemExit) as exit_info:
+        sources.run_installer(config, argv=[])
+    assert exit_info.value.code == 0
+    assert engine == {}                        # the installer never opened
+
+
+def test_the_text_screen_asks_on_stdin(tmp_path: Path, engine, monkeypatch) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    suggested = _answers(monkeypatch, str(tmp_path / "picked"), gui=False)
+    sources.run_installer(config, argv=["--tui"])
+    assert suggested == [str(tmp_path / "tools")]
+    assert engine["root_dir"] == str(tmp_path / "picked")
+
+
+@pytest.mark.parametrize("argv", [["--list"], ["--check"], ["--apply", "all"],
+                                  ["--apply=all"]])
+def test_a_headless_run_takes_the_default_and_says_so(tmp_path: Path, engine,
+                                                      never_asks, monkeypatch,
+                                                      capsys, argv) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    sources.run_installer(config, argv=list(argv))
+    assert engine["root_dir"] == str(tmp_path / "tools")
+    assert (f"root: {tmp_path / 'tools'} (pass --root to change)"
+            in capsys.readouterr().out)
+    # A default is not an answer, so it is not written to the local file.
+    assert not config.with_name("installer.local.toml").exists()
+
+
+def test_no_question_without_a_terminal(tmp_path: Path, engine, never_asks,
+                                        monkeypatch, capsys) -> None:
+    config = _tree(tmp_path)
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(sources, "_wants_gui", lambda argv: False)
+    monkeypatch.setattr(sources.sys, "stdin",
+                        type("Pipe", (), {"isatty": staticmethod(lambda: False)})())
+    sources.run_installer(config, argv=[])
+    assert engine["root_dir"] == str(tmp_path / "tools")
+    assert "pass --root to change" in capsys.readouterr().out
+
+
 def test_run_installer_refuses_to_have_its_own_arguments_overridden(tmp_path: Path,
                                                                    engine) -> None:
     config = _tree(tmp_path)