cli-tools-kit 0.6.0__py3-none-any.whl

cli_tools_kit/onboarding.py

@@ -0,0 +1,261 @@
+"""First-run setup for an organisation adopting the installer.
+
+Running the engine bare — ``cli-tool-installer`` in a fresh tree, with no
+wrapper and no :class:`~cli_tools_kit.InstallerIdentity` — used to open a GUI
+titled "probable.work - Tools Installer" that wrote ``ai_tools_manager.desktop``
+and claimed the first-party alias file. That is never what a third party wants,
+and they had no way to know it happened.
+
+So the bare engine stops and offers setup instead. Two ways through it:
+
+* **Hand the prompt to your coding agent** (default). :func:`agent_prompt`
+  prints a self-contained brief. Paste it into Claude Code (or any agent with
+  an ``AskUserQuestion``-style tool), and the agent interviews you for the four
+  things it cannot guess, then writes the wrapper. This is the common case:
+  the kit is mostly adopted from inside an agent session.
+* **Answer here** (``--setup --interactive``). :func:`scripted_setup` asks the
+  same four questions on stdin and writes the same file.
+
+Both end at one generated ``installer.py`` produced by :func:`wrapper_source`,
+so the two paths cannot drift apart.
+"""
+
+import os
+import re
+import sys
+from typing import Optional
+
+from .identity import InstallerIdentity
+
+WRAPPER_NAME = "installer.py"
+
+
+def _slugify(text: str) -> str:
+    """Best-effort org name → slug: ``Acme Corp Tools`` → ``acme-corp-tools``."""
+    slug = re.sub(r"[^a-z0-9]+", "-", (text or "").lower()).strip("-")
+    return slug or "my-tools"
+
+
+def wrapper_source(
+    identity: InstallerIdentity,
+    group_by: str = "capability",
+    tools_dirname: Optional[str] = None,
+) -> str:
+    """The ``installer.py`` an organisation drops at the root of its tool tree.
+
+    Deliberately short: every line that is not identity is a default worth
+    keeping. ``tools_dirname`` names a subdirectory holding the tools when they
+    do not sit directly at the tree root.
+    """
+    roots = ""
+    if tools_dirname:
+        roots = (
+            f'\n    # Tools live in {tools_dirname}/ rather than beside this file.\n'
+            f'    discovery_roots=[os.path.join(HERE, "{tools_dirname}")],'
+        )
+    title = identity.title or identity.display_title
+    return f'''#!/usr/bin/env python3
+"""Installer for the {title} tool tree.
+
+Discovers every tool under this directory that answers --advertise, and lets you
+install or remove its desktop entry, shell alias and Claude Code skill.
+
+    python3 {WRAPPER_NAME}            # GUI
+    python3 {WRAPPER_NAME} --list     # what was discovered
+    python3 {WRAPPER_NAME} --check    # headless login reconciliation
+
+See PROTOCOL.md in cli-tools-kit for what a tool must advertise to show up here.
+"""
+
+import os
+
+from cli_tools_kit import InstallerIdentity
+from cli_tools_kit.gui_installer import run
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+# Everything this installer claims on a host derives from the slug: the config
+# directory, the alias file, the icon cache, its own .desktop entry, the WM
+# class, and the Keywords marker its orphan sweeper matches on. Change the slug
+# and you move house — existing shortcuts keep the old names.
+IDENTITY = InstallerIdentity(
+    slug="{identity.slug}",
+    title="{title}",
+    icon="{identity.icon}",
+)
+
+if __name__ == "__main__":
+    run(
+        identity=IDENTITY,
+        root_dir=HERE,
+        entry_script=__file__,{roots}
+        # "capability" bands the GUI rows by each tool's advertised capability
+        # word; "category" bands by whatever label your discoverer assigns.
+        group_by="{group_by}",
+    )
+'''
+
+
+def agent_prompt(root_dir: str) -> str:
+    """The brief a user pastes into their coding agent to be set up.
+
+    Written to be read by an agent, not a person: it states the goal, the four
+    unknowns, where to look things up, and what "done" means. It asks the agent
+    to interview the user through a structured question tool rather than
+    guessing, because three of the four answers are naming decisions that are
+    expensive to change afterwards.
+    """
+    return f"""\
+Set up a cli-tools-kit installer for my organisation in {root_dir}.
+
+Context you need:
+- cli-tools-kit is an installed Python package (`pip install cli-tools-kit`).
+  The engine is `cli_tools_kit.gui_installer.run()`; the identity type is
+  `cli_tools_kit.InstallerIdentity`. Read the package's README.md section
+  "Reusing the installer in your org", and PROTOCOL.md for the tool-side
+  `--advertise` contract. There is a complete working wrapper plus an example
+  tool in the package repo under `examples/org-installer/` — copy that shape.
+- The installer discovers tools by running each candidate's `main.py
+  --advertise` (5 second timeout) and reading the JSON it prints.
+
+Ask me, using your structured question tool (AskUserQuestion or equivalent) —
+do not guess, these are naming decisions that are painful to change once
+shortcuts exist on people's machines:
+1. The slug: one lowercase token identifying my org's installer. It becomes
+   ~/.config/<slug>/, ~/.<slug>_aliases, <slug>-installer.desktop, the WM
+   class, and the desktop Keywords marker. Offer a couple of candidates
+   derived from the directory name and from my organisation's name.
+2. The window title users will see.
+3. The desktop icon: a freedesktop icon name (e.g. system-software-install,
+   applications-utilities) or an absolute path to a PNG.
+4. Whether my tools sit directly in {root_dir} or in a subdirectory, and
+   whether the installer should band rows by each tool's advertised
+   `capability` word or by a `category` label I assign myself. Look at the
+   directory first and propose what actually fits rather than asking blind.
+
+Then:
+- Write {root_dir}/{WRAPPER_NAME} using `InstallerIdentity` and `run()`. Keep
+  it to identity plus root_dir/entry_script — every other knob has a default
+  worth keeping. `python3 -m cli_tools_kit --setup --print-wrapper` prints a
+  correct skeleton you can start from.
+- Run `python3 {WRAPPER_NAME} --list` and show me what it discovered. If a tool
+  I expected is missing, its `--advertise` is the thing to fix: it must print
+  JSON and exit BEFORE any heavy import, or it trips the 5s timeout.
+- Do NOT run `--install` for me. Tell me what it would install and let me
+  decide.
+
+If any of my existing tools do not yet answer `--advertise`, show me the
+PROTOCOL.md skeleton and offer to add it to one tool as a worked example
+before doing the rest.
+"""
+
+
+def _ask(prompt: str, default: str = "") -> str:
+    """One stdin question with a shown default; empty answer takes the default."""
+    suffix = f" [{default}]" if default else ""
+    try:
+        answer = input(f"{prompt}{suffix}: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        raise SystemExit(1)
+    return answer or default
+
+
+def scripted_setup(root_dir: str) -> int:
+    """Interview the user on stdin and write the wrapper. Returns an exit code."""
+    print(f"\nSetting up a cli-tools-kit installer in {root_dir}\n")
+    print("Four questions. Press Enter to take the default in brackets.\n")
+
+    default_slug = _slugify(os.path.basename(os.path.abspath(root_dir)))
+    while True:
+        slug = _ask("Slug (lowercase, identifies your installer on the host)", default_slug)
+        try:
+            identity = InstallerIdentity(slug=slug)
+            break
+        except ValueError as exc:
+            print(f"  {exc}\n")
+
+    title = _ask("Window title", f"{slug} Tools")
+    icon = _ask("Desktop icon (freedesktop name or absolute path)", "system-software-install")
+    group_by = ""
+    while group_by not in ("capability", "category"):
+        group_by = _ask("Band rows by 'capability' or 'category'", "capability")
+
+    identity = InstallerIdentity(slug=slug, title=title, icon=icon)
+    target = os.path.join(root_dir, WRAPPER_NAME)
+
+    if os.path.exists(target):
+        if _ask(f"\n{target} exists. Overwrite? (y/N)", "N").lower() not in ("y", "yes"):
+            print("Left it alone. Nothing written.")
+            return 1
+
+    with open(target, "w", encoding="utf-8") as fh:
+        fh.write(wrapper_source(identity, group_by=group_by))
+
+    print(f"\nWrote {target}\n")
+    print("It will claim these names on this host:")
+    print(f"  desktop entry   {identity.self_desktop_file}")
+    print(f"  window class    {identity.self_wm_class}")
+    print(f"  config          {identity.config_path}")
+    print(f"  aliases         {identity.aliases_path}")
+    print(f"  desktop marker  Keywords={identity.desktop_keywords}")
+    print(f"\nNext: python3 {WRAPPER_NAME} --list")
+    return 0
+
+
+def print_onboarding(root_dir: str) -> int:
+    """What the bare engine shows instead of opening a mis-branded GUI."""
+    print(f"""
+cli-tools-kit — no installer is configured for this tree.
+
+Running the engine directly would open an installer that claims the default
+first-party names on this host, which is almost certainly not what you want.
+Set up your own instead; it is one small file.
+
+  Paste the brief below into your coding agent (Claude Code or similar) and it
+  will interview you and write it:
+
+{"-" * 72}""")
+    print(agent_prompt(os.path.abspath(root_dir)))
+    print(f"""{"-" * 72}
+
+  Or answer the same questions here:
+
+      python3 -m cli_tools_kit --setup --interactive
+
+  Or just print the wrapper skeleton and edit it yourself:
+
+      python3 -m cli_tools_kit --setup --print-wrapper
+""")
+    return 0
+
+
+def main(argv: Optional[list] = None) -> int:
+    """``python3 -m cli_tools_kit`` — setup, and nothing else."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="python3 -m cli_tools_kit",
+        description="Set up a cli-tools-kit installer for your organisation.",
+    )
+    parser.add_argument("--setup", action="store_true",
+                        help="show setup instructions (the default action)")
+    parser.add_argument("--interactive", action="store_true",
+                        help="answer the setup questions here instead of via an agent")
+    parser.add_argument("--print-wrapper", action="store_true",
+                        help="print an installer.py skeleton to stdout and exit")
+    parser.add_argument("--slug", default="",
+                        help="slug for --print-wrapper (default: this directory's name)")
+    parser.add_argument("--root", default=os.getcwd(),
+                        help="the tool tree to set up (default: current directory)")
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+
+    root = os.path.abspath(args.root)
+
+    if args.print_wrapper:
+        slug = args.slug or _slugify(os.path.basename(root))
+        print(wrapper_source(InstallerIdentity(slug=slug, title=f"{slug} Tools")), end="")
+        return 0
+    if args.interactive:
+        return scripted_setup(root)
+    return print_onboarding(root)

cli_tools_kit/skills.py

@@ -0,0 +1,97 @@
+"""Skill-freshness helpers for the installer protocol.
+
+A tool that bundles a Claude Code skill installs it into
+``~/.claude/skills/<skill_name>/``. These helpers let an installer — or the tool
+itself, at ``--advertise`` time — decide whether the installed copy is up to
+date with the tool's bundled version, so the installer can *take note* and
+suggest an update instead of silently keeping a stale skill.
+
+The unit of comparison is a ``{relative_posix_path: text}`` mapping. A tool
+hashes what it would install; an installer hashes what is installed; equal
+hashes mean "current". This keeps the comparison authoritative and free of any
+cross-package version coupling — each side computes over content it can see.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Dict, Optional
+
+# Names that may appear inside an installed skill dir without being part of the
+# skill's content — excluded so a stray artifact can't force a false "stale".
+_SKILL_IGNORE_NAMES = {".DS_Store"}
+
+
+def _default_skills_dir() -> str:
+    """``~/.claude/skills`` resolved at call time (honours a patched $HOME)."""
+    return os.path.join(os.path.expanduser("~"), ".claude", "skills")
+
+
+def skill_payload_hash(files: Dict[str, str]) -> str:
+    """Stable, order-independent hash of a skill's content.
+
+    ``files`` maps POSIX-relative paths (e.g. ``"SKILL.md"``,
+    ``"scripts/send.sh"``) to their text. The same mapping always yields the
+    same digest, so a tool can hash what it bundles and an installer can hash
+    what is installed and compare the two.
+    """
+    h = hashlib.sha256()
+    for rel in sorted(files):
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(files[rel].encode("utf-8"))
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def read_installed_skill(
+    skill_name: str, skills_dir: Optional[str] = None
+) -> Optional[Dict[str, str]]:
+    """Read an installed skill's files as ``{relpath: text}``, or ``None``.
+
+    Returns ``None`` when the skill is not installed (no ``SKILL.md`` under its
+    dir). Binary/unreadable files and obvious junk (``__pycache__``, ``*.pyc``,
+    ``.DS_Store``) are skipped so the comparison stays robust.
+    """
+    root = os.path.join(skills_dir or _default_skills_dir(), skill_name)
+    if not os.path.isfile(os.path.join(root, "SKILL.md")):
+        return None
+    out: Dict[str, str] = {}
+    for dirpath, dirnames, names in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d != "__pycache__"]
+        for name in names:
+            if name in _SKILL_IGNORE_NAMES or name.endswith(".pyc"):
+                continue
+            path = os.path.join(dirpath, name)
+            rel = os.path.relpath(path, root).replace(os.sep, "/")
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    out[rel] = f.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+    return out
+
+
+def installed_skill_hash(
+    skill_name: str, skills_dir: Optional[str] = None
+) -> Optional[str]:
+    """Hash of the installed skill's content, or ``None`` when not installed."""
+    files = read_installed_skill(skill_name, skills_dir)
+    return None if files is None else skill_payload_hash(files)
+
+
+def skill_status(
+    skill_name: str, bundled: Dict[str, str], skills_dir: Optional[str] = None
+) -> str:
+    """Return ``"absent"`` | ``"current"`` | ``"stale"``.
+
+    Compares the installed skill against ``bundled`` (the ``{relpath: text}``
+    the tool would install). ``"absent"`` if not installed, ``"current"`` if the
+    content matches, ``"stale"`` otherwise — the cue for an installer to suggest
+    an update.
+    """
+    installed = read_installed_skill(skill_name, skills_dir)
+    if installed is None:
+        return "absent"
+    return "current" if skill_payload_hash(installed) == skill_payload_hash(bundled) else "stale"

cli_tools_kit/sources.py

@@ -0,0 +1,335 @@
+"""Sources — one installer offering tools that live in several repos.
+
+An organisation's tools rarely sit in one checkout. This module lets the
+installer read a list of repos from a TOML file next to it, put each one on
+disk, and hand the engine one discovery root per repo.
+
+``installer.toml`` is tracked and shared by everyone:
+
+    [[source]]
+    name = "acme/tools"
+    path = "."                                    # relative to this file
+
+    [[source]]
+    name = "acme/lab"
+    url = "https://github.com/acme/lab-tools"     # cloned into <root>/acme/lab
+
+``installer.local.toml`` next to it is optional and belongs to one machine, so
+it is gitignored by convention. It sets ``root`` and adds or replaces a ``path``
+for a source matched by ``name``:
+
+    root = "/home/me/checkouts"
+
+    [[source]]
+    name = "acme/lab"
+    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>``. Only ``https://`` URLs are cloned, the clone is
+full rather than shallow, and a clone that fails prints one line and drops that
+source, so the other repos' tools still install.
+
+A resolved repo may carry its own ``installer.toml``. Its ``[[source]]`` entries
+are resolved too, one nested level deep and no further. Paths in a nested file
+are relative to that file, clones still go under the same root, a path already
+resolved is not visited twice, and duplicates are dropped.
+
+The whole feature is three calls:
+
+    sources = load_sources("installer.toml")
+    roots = resolve_sources(sources, root="~/acme-tools")
+
+or, for a wrapper that just wants the installer:
+
+    run_installer(os.path.join(HERE, "installer.toml"),
+                  identity=InstallerIdentity(slug="acme-tools"),
+                  entry_script=__file__)
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, List, Optional, Sequence
+
+__all__ = ["Source", "load_sources", "resolve_sources", "run_installer"]
+
+# How far below the top-level installer.toml a nested one is still read.
+MAX_NESTING = 1
+
+# Neutralise the ext:: and file:// transports and any hook, so fetching a repo
+# cannot turn into running code from it.
+GIT_SAFE = ("-c", "protocol.ext.allow=never",
+            "-c", "protocol.file.allow=never",
+            "-c", "core.hooksPath=/dev/null")
+
+
+@dataclass(frozen=True)
+class Source:
+    """One repo an installer offers tools from.
+
+    ``path`` is already absolute: ``load_sources`` resolves it against the TOML
+    file it was written in. ``url`` is used only when no path is on disk.
+    """
+
+    name: str
+    url: Optional[str] = None
+    path: Optional[str] = None
+
+
+# --- TOML -------------------------------------------------------------------
+
+def _toml_module():
+    """``tomllib`` (Python 3.11+), ``tomli`` if it is installed, else None."""
+    try:
+        import tomllib  # noqa: PLC0415
+        return tomllib
+    except ImportError:
+        pass
+    try:
+        import tomli  # noqa: PLC0415
+        return tomli
+    except ImportError:
+        return None
+
+
+def _read_toml(path: Path, log: Callable = print) -> dict:
+    """One TOML file as a dict, empty if it is absent or does not parse."""
+    toml = _toml_module()
+    if toml is None:
+        log(f"{path.name}: not read (needs Python 3.11 or `pip install tomli`)")
+        return {}
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as fh:
+            return toml.load(fh)
+    except (OSError, ValueError) as exc:
+        log(f"{path.name}: not read ({exc})")
+        return {}
+
+
+def _local_path_for(config_path: Path) -> Path:
+    """``installer.toml`` -> ``installer.local.toml`` in the same directory."""
+    return config_path.with_name(config_path.stem + ".local" + config_path.suffix)
+
+
+def _absolute(base: Path, raw: str) -> str:
+    return os.path.abspath(os.path.join(str(base), os.path.expanduser(raw)))
+
+
+def local_root(config_path, local_path=None) -> Optional[str]:
+    """The top-level ``root`` of the local file next to ``config_path``, or None."""
+    config_path = Path(config_path)
+    local = Path(local_path) if local_path is not None else _local_path_for(config_path)
+    value = _read_toml(local).get("root")
+    if isinstance(value, str) and value:
+        return str(Path(os.path.expanduser(value)).absolute())
+    return None
+
+
+def load_sources(config_path, local_path=None, log: Callable = print) -> List[Source]:
+    """The ``[[source]]`` entries of one TOML file, local overrides applied.
+
+    ``local_path`` defaults to ``installer.local.toml`` next to ``config_path``.
+    A ``path`` is taken relative to the file it is written in. An entry without
+    a name is reported and dropped.
+    """
+    config_path = Path(config_path)
+    local_path = Path(local_path) if local_path is not None else _local_path_for(config_path)
+    data = _read_toml(config_path, log)
+    local = _read_toml(local_path, log)
+
+    overrides = {entry["name"]: entry
+                 for entry in local.get("source") or []
+                 if isinstance(entry, dict) and entry.get("name")}
+
+    sources: List[Source] = []
+    for entry in data.get("source") or []:
+        if not isinstance(entry, dict):
+            continue
+        name = entry.get("name")
+        if not name:
+            log(f"{config_path.name}: a [[source]] without a name, skipped")
+            continue
+        override = overrides.get(name, {}).get("path")
+        raw = override or entry.get("path")
+        base = local_path.parent if override else config_path.parent
+        path = _absolute(base, raw) if raw else None
+        sources.append(Source(name=name, url=entry.get("url"), path=path))
+    return sources
+
+
+# --- resolution -------------------------------------------------------------
+
+def _git(*args):
+    try:
+        result = subprocess.run(["git", *GIT_SAFE, *args], capture_output=True, text=True)
+    except OSError as exc:
+        return False, str(exc)
+    return result.returncode == 0, (result.stdout + result.stderr).strip()
+
+
+def _clone_reason(output: str) -> 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")
+
+
+def _resolve_one(source: Source, root: Path, refresh: bool, log: Callable,
+                 clone: bool) -> Optional[Path]:
+    """Where one source sits on disk, cloning it if that is the only way."""
+    if source.path and Path(source.path).is_dir():
+        return Path(source.path).resolve()
+
+    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")
+            log(f"{source.name}: pulled" if ok else
+                f"{source.name}: left as is, local changes or diverged history")
+        return target.resolve()
+
+    if not source.url:
+        if clone:
+            log(f"{source.name}: no checkout at {target} and no url, skipped")
+        return None
+    if not source.url.lower().startswith("https://"):
+        if clone:
+            log(f"{source.name}: {source.url} is not an https:// URL, skipped")
+        return None
+    if not clone:
+        return None
+    if not (root.is_dir() and os.access(str(root), os.W_OK)):
+        log(f"{source.name}: not cloned, skipped ({root} does not exist or cannot be"
+            " written to; pass --root DIR to clone somewhere else)")
+        return None
+
+    log(f"Cloning {source.url} -> {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    ok, out = _git("clone", source.url, str(target))
+    if not ok:
+        log(f"{source.name}: not cloned, skipped ({_clone_reason(out)})")
+        return None
+    return target.resolve()
+
+
+def _resolve_level(sources: Sequence[Source], root: Path, refresh: bool, log: Callable,
+                   clone: bool, config_name: str, depth: int,
+                   found: List[Path], seen: set) -> None:
+    for source in sources:
+        path = _resolve_one(source, root, refresh, log, clone)
+        if path is None or path in seen:
+            continue
+        seen.add(path)
+        found.append(path)
+        if depth >= MAX_NESTING:
+            continue
+        nested = path / config_name
+        if nested.is_file():
+            _resolve_level(load_sources(nested, log=log), root, refresh, log, clone,
+                           config_name, depth + 1, found, seen)
+
+
+def resolve_sources(sources: Sequence[Source], root, refresh: bool = False,
+                    log: Callable = print, clone: bool = True) -> List[Path]:
+    """Put every source on disk and return one discovery root per repo.
+
+    Clones the sources that are given by a URL and are not on disk yet. With
+    ``refresh`` the clones are also brought up to date with ``git pull
+    --ff-only``; a checkout given by ``path`` is never pulled. A source that
+    cannot be resolved prints one line and is left out.
+
+    A resolved repo that holds its own ``installer.toml`` contributes its
+    sources too, one nested level deep. Clones from a nested file go under the
+    same root. A path that is already in the result is not visited again, so a
+    file that points back at its parent cannot loop.
+
+    ``clone=False`` resolves from the filesystem alone and never reaches the
+    network, which is what the login check needs.
+    """
+    root = Path(os.path.expanduser(str(root))).absolute()
+    found: List[Path] = []
+    _resolve_level(sources, root, refresh, log, clone, "installer.toml", 0, found, set())
+    return found
+
+
+# --- the convenience wrapper ------------------------------------------------
+
+def _take_root(argv: List[str]):
+    """Pull ``--root DIR`` out of ``argv``. The engine owns every other flag."""
+    rest, root = [], None
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--root" and i + 1 < len(argv):
+            root = argv[i + 1]
+            i += 2
+            continue
+        if arg.startswith("--root="):
+            root = arg[len("--root="):]
+            i += 1
+            continue
+        rest.append(arg)
+        i += 1
+    return rest, root
+
+
+def default_root(config_path) -> str:
+    """Two levels above the config file's directory.
+
+    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.
+    """
+    return str(Path(config_path).absolute().parent.parent.parent)
+
+
+def run_installer(config_path, argv=None, **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
+    rest is left to the engine, so ``--list``, ``--apply``, ``--skill-target``,
+    ``--check``, ``--tui`` and ``--gui`` keep working. ``--refresh`` stays the
+    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
+    pre-discovery hook, which the engine skips on the ``--check`` path, so that
+    check stays network-free and sees whatever is already on disk.
+
+    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
+    its repos keep that hold no tools.
+    """
+    for reserved in ("discovery_roots", "pre_discovery"):
+        if reserved in run_kwargs:
+            raise TypeError(f"run_installer sets {reserved} itself")
+
+    config_path = Path(config_path).absolute()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    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())
+    sources = load_sources(config_path)
+
+    # The engine reads DISCOVERY_ROOTS after the hook has run, so the hook fills
+    # this list in place with what it resolved. It is pre-filled with what is on
+    # disk already, for the --check path that never calls the hook.
+    roots = [str(p) for p in resolve_sources(sources, root, clone=False,
+                                             log=lambda *_: None)]
+
+    def pre_discovery(refresh):
+        roots[:] = [str(p) for p in resolve_sources(sources, root, refresh=refresh)]
+
+    from . import gui_installer  # noqa: PLC0415 — imports tkinter, keep it lazy
+    run_kwargs.setdefault("root_dir", root)
+    return gui_installer.run(discovery_roots=roots, pre_discovery=pre_discovery,
+                             **run_kwargs)