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

cli_tools_kit/host.py

@@ -0,0 +1,239 @@
+"""Platform decisions, in one place.
+
+Everything the engine does differently on Windows lives here, so the rest of
+the package can stay written for one host. On Linux a CLI tool becomes a bash
+alias in ``~/.tools_aliases`` sourced from ``~/.bashrc``; Windows has no such
+file, so the tool becomes a pair of small launcher scripts (shims) in a
+directory that is added to the user's PATH once.
+
+``IS_WINDOWS`` is a module constant rather than a call so tests can patch it
+(``monkeypatch.setattr(host, "IS_WINDOWS", True)``) and exercise the Windows
+paths on Linux. Read it as ``host.IS_WINDOWS`` at call time, never
+``from .host import IS_WINDOWS``, or the patch will not be seen.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from typing import Iterable, Optional
+
+IS_WINDOWS = os.name == "nt"
+
+
+# --- where the shims live -----------------------------------------------------
+
+def shim_dir(identity) -> str:
+    """The directory this installer's Windows shims go in.
+
+    Derived from the identity's slug, like every other per-host name, so two
+    organisations on one host do not share a shim directory.
+    """
+    return identity.shim_path
+
+
+def _quote_cmd(value: str) -> str:
+    """Quote one argument for a .cmd batch file."""
+    return f'"{value}"' if value else '""'
+
+
+def write_shims(directory: str, alias: str, python: str, script: str,
+                args: Iterable[str] = ()) -> list:
+    """Write the two launcher files for one CLI tool. Returns their paths.
+
+    ``<alias>.cmd`` is what cmd.exe and PowerShell run. The extensionless
+    ``<alias>`` is a /bin/sh script for Git Bash, which is the shell Claude
+    Code uses on Windows; Git Bash ignores the .cmd file, and cmd.exe ignores
+    the extensionless one, so both can sit in the same directory.
+    """
+    os.makedirs(directory, exist_ok=True)
+    args = list(args or [])
+
+    cmd_line = " ".join([_quote_cmd(python), _quote_cmd(script)]
+                        + [_quote_cmd(a) for a in args])
+    cmd_path = os.path.join(directory, alias + ".cmd")
+    with open(cmd_path, "w", newline="\r\n") as fh:
+        fh.write("@echo off\n")
+        fh.write(cmd_line + " %*\n")
+
+    # Git Bash wants forward slashes; a backslash there is an escape character.
+    sh_python = python.replace("\\", "/")
+    sh_script = script.replace("\\", "/")
+    sh_args = " ".join(shlex.quote(a) for a in args)
+    sh_line = f'exec "{sh_python}" "{sh_script}"'
+    if sh_args:
+        sh_line += " " + sh_args
+    sh_line += ' "$@"'
+    sh_path = os.path.join(directory, alias)
+    with open(sh_path, "w", newline="\n") as fh:
+        fh.write("#!/bin/sh\n")
+        fh.write(sh_line + "\n")
+    try:
+        os.chmod(sh_path, 0o755)
+    except OSError:
+        pass
+
+    return [cmd_path, sh_path]
+
+
+def remove_shims(directory: str, alias: str) -> list:
+    """Delete both shim files for one tool. Returns the ones that were there."""
+    removed = []
+    for name in (alias + ".cmd", alias):
+        path = os.path.join(directory, name)
+        try:
+            os.remove(path)
+            removed.append(path)
+        except OSError:
+            pass
+    return removed
+
+
+# --- the user PATH ------------------------------------------------------------
+
+def _default_registry():
+    """The stdlib ``winreg`` module, or None off Windows."""
+    try:
+        import winreg
+        return winreg
+    except ImportError:
+        return None
+
+
+def _broadcast_setting_change() -> None:
+    """Tell running programs the environment changed. Best effort."""
+    try:
+        import ctypes
+        HWND_BROADCAST = 0xFFFF
+        WM_SETTINGCHANGE = 0x001A
+        SMTO_ABORTIFHUNG = 0x0002
+        ctypes.windll.user32.SendMessageTimeoutW(  # type: ignore[attr-defined]
+            HWND_BROADCAST, WM_SETTINGCHANGE, 0, "Environment",
+            SMTO_ABORTIFHUNG, 5000, None,
+        )
+    except Exception:
+        pass
+
+
+def _same_dir(a: str, b: str) -> bool:
+    """Compare two Windows directory paths: case-insensitive, either slash,
+    trailing separator ignored. Spelled out rather than left to os.path.normcase
+    so the comparison is the Windows one even when the tests run on Linux."""
+    def norm(value: str) -> str:
+        return value.replace("/", "\\").rstrip("\\").lower()
+    return norm(a) == norm(b)
+
+
+def ensure_user_path(directory: str, reg=None) -> bool:
+    """Add ``directory`` to the user's PATH, once.
+
+    Writes ``HKCU\\Environment\\Path`` as REG_EXPAND_SZ, broadcasts the change
+    so newly started programs pick it up, and prepends the directory to this
+    process's PATH. Returns True if the registry value was changed, False if
+    the directory was already listed (or there is no registry to write).
+
+    ``reg`` is the registry module to use; it defaults to ``winreg`` and is
+    what the tests replace with a fake.
+    """
+    reg = reg if reg is not None else _default_registry()
+
+    changed = False
+    if reg is not None:
+        key = reg.OpenKey(reg.HKEY_CURRENT_USER, "Environment", 0,
+                          reg.KEY_READ | reg.KEY_WRITE)
+        try:
+            try:
+                current = reg.QueryValueEx(key, "Path")[0] or ""
+            except OSError:
+                current = ""
+            parts = [p for p in current.split(";") if p.strip()]
+            if not any(_same_dir(p, directory) for p in parts):
+                parts.append(directory)
+                reg.SetValueEx(key, "Path", 0, reg.REG_EXPAND_SZ, ";".join(parts))
+                changed = True
+        finally:
+            reg.CloseKey(key)
+        if changed:
+            _broadcast_setting_change()
+
+    live = os.environ.get("PATH", "")
+    if not any(_same_dir(p, directory) for p in live.split(os.pathsep) if p):
+        os.environ["PATH"] = directory + os.pathsep + live if live else directory
+    return changed
+
+
+def shell_hint() -> str:
+    """What to tell the user so a freshly installed command is found."""
+    if IS_WINDOWS:
+        return "Open a new terminal"
+    return "Open a new shell, or run: source ~/.bashrc"
+
+
+# --- Start Menu ---------------------------------------------------------------
+
+def _appdata() -> str:
+    return os.environ.get("APPDATA") or os.path.join(
+        os.path.expanduser("~"), "AppData", "Roaming")
+
+
+def start_menu_dir() -> str:
+    """``%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs``."""
+    return os.path.join(_appdata(), "Microsoft", "Windows", "Start Menu", "Programs")
+
+
+def startup_dir() -> str:
+    """The Startup folder inside the Start Menu — entries here run at login."""
+    return os.path.join(start_menu_dir(), "Startup")
+
+
+def write_shortcut(lnk_path: str, target: str, args: str = "",
+                   icon: Optional[str] = None, terminal: bool = False,
+                   workdir: Optional[str] = None) -> bool:
+    """Write a .lnk shortcut through PowerShell's WScript.Shell.
+
+    This avoids a pywin32 dependency for the one thing it would be needed for.
+    Best effort: returns False instead of raising when PowerShell is missing or
+    the call fails.
+    """
+    try:
+        os.makedirs(os.path.dirname(lnk_path) or ".", exist_ok=True)
+    except OSError:
+        return False
+
+    def ps(value: str) -> str:
+        return "'" + str(value).replace("'", "''") + "'"
+
+    script = [
+        "$s = New-Object -ComObject WScript.Shell",
+        f"$l = $s.CreateShortcut({ps(lnk_path)})",
+        f"$l.TargetPath = {ps(target)}",
+    ]
+    if args:
+        script.append(f"$l.Arguments = {ps(args)}")
+    if workdir:
+        script.append(f"$l.WorkingDirectory = {ps(workdir)}")
+    if icon:
+        script.append(f"$l.IconLocation = {ps(icon)}")
+    # 1 = normal window. `terminal` is already expressed in the target
+    # (cmd.exe /k ...), so it does not change the window style here.
+    script.append("$l.WindowStyle = 1")
+    script.append("$l.Save()")
+
+    try:
+        result = subprocess.run(
+            ["powershell", "-NoProfile", "-NonInteractive", "-Command", "; ".join(script)],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def remove_shortcut(lnk_path: str) -> bool:
+    """Delete a .lnk. True if one was there."""
+    try:
+        os.remove(lnk_path)
+        return True
+    except OSError:
+        return False

cli_tools_kit/identity.py

@@ -0,0 +1,229 @@
+"""Who an installer is, so two orgs' installers can share a host.
+
+Before this module every per-host artifact the engine touched was named after
+the first-party tree: ``~/.config/tools-installer/config.json``,
+``~/.tools_aliases``, ``ai_tools_manager.desktop``, the WM class
+``tools_installer``, and the ``Keywords=probable.work;ai;tool;`` line that
+doubles as branding *and* as the marker the orphan sweeper uses to decide
+"this shortcut is mine". A second organisation reusing the engine therefore
+overwrote the first one's desktop entry, shared its icon overrides and alias
+file, and reaped its shortcuts.
+
+:class:`InstallerIdentity` collects those names behind a single ``slug``. Give
+it one word and every path, filename and marker derives from it; override any
+individual field when a name has to be something else.
+
+    from cli_tools_kit import InstallerIdentity
+
+    ACME = InstallerIdentity(slug="acme-tools", title="Acme Tools")
+
+    # ~/.config/acme-tools/, ~/.acme_tools_aliases, acme-tools.desktop,
+    # WM class acme_tools, Keywords=acme-tools;ai;tool;
+
+``LEGACY_IDENTITY`` reproduces the historical first-party names exactly and is
+what the engine uses when a wrapper passes no identity, so existing installs
+keep their files.
+"""
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+# A slug lands in filesystem paths, a .desktop filename and the desktop
+# Keywords line, so it stays to characters that are safe in all three.
+# \Z, not $: "$" also matches just before a trailing newline, which would
+# let "acme\n" through and inject a second key into the .desktop file.
+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9._-]*\Z")
+
+DEFAULT_ICON = "system-software-install"
+
+
+def _home(*parts: str) -> str:
+    """A path under the home directory, kept unexpanded.
+
+    Expansion happens in the properties below, at access time. Resolving "~"
+    when the identity is *constructed* would freeze whatever HOME held at
+    import — which silently sends a sandboxed test (or a process that changes
+    HOME) back to the real home directory.
+    """
+    return os.path.join("~", *parts)
+
+
+@dataclass(frozen=True)
+class InstallerIdentity:
+    """The names one organisation's installer claims on a host.
+
+    Only ``slug`` is required. Every other field defaults to something derived
+    from it; set one explicitly when you need a specific name (as
+    ``LEGACY_IDENTITY`` does to keep the first-party filenames).
+    """
+
+    slug: str
+    title: Optional[str] = None
+    icon: str = DEFAULT_ICON
+
+    # Desktop Keywords token. Both the branding on every shortcut this
+    # installer writes and the marker its orphan sweeper matches on, so an org
+    # only ever sweeps its own entries. Defaults to the slug.
+    marker: Optional[str] = None
+
+    # The manager's own shortcut and window.
+    desktop_file: Optional[str] = None
+    desktop_name: Optional[str] = None
+    wm_class: Optional[str] = None
+    notify_app: Optional[str] = None
+
+    # Per-host state. Unnamespaced before 0.2.2; two orgs shared all three.
+    aliases_file: Optional[str] = None
+    config_dir: Optional[str] = None
+    cache_dir: Optional[str] = None
+
+    # Login update-check artifacts.
+    check_desktop_name: Optional[str] = None
+    check_log_name: Optional[str] = None
+    check_state_name: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not _SLUG_RE.match(self.slug or ""):
+            raise ValueError(
+                f"slug must be lowercase letters, digits, '.', '-' or '_' and "
+                f"start with a letter or digit, got {self.slug!r}"
+            )
+
+    # --- derived names ----------------------------------------------------
+    #
+    # Properties rather than __post_init__ assignment: the dataclass is frozen
+    # (an identity is a value, not mutable config) and this keeps the stored
+    # fields to exactly what the caller chose.
+
+    @property
+    def under(self) -> str:
+        """The slug as a shell/WM-safe identifier: ``acme-tools`` → ``acme_tools``."""
+        return re.sub(r"[.\-]", "_", self.slug)
+
+    @property
+    def display_title(self) -> str:
+        """Window title. Falls back to the slug when no title was given."""
+        return self.title or self.slug
+
+    @property
+    def desktop_keywords(self) -> str:
+        """The full ``Keywords=`` value written into every shortcut."""
+        return f"{self.marker or self.slug};ai;tool;"
+
+    @property
+    def marker_token(self) -> str:
+        """The token :func:`find_orphan_desktop_files` matches to claim a file."""
+        return self.marker or self.slug
+
+    @property
+    def self_desktop_file(self) -> str:
+        return self.desktop_file or f"{self.slug}-installer.desktop"
+
+    @property
+    def self_desktop_name(self) -> str:
+        return self.desktop_name or self.display_title
+
+    @property
+    def self_wm_class(self) -> str:
+        return self.wm_class or f"{self.under}_installer"
+
+    @property
+    def notify_label(self) -> str:
+        return self.notify_app or self.display_title
+
+    @property
+    def aliases_path(self) -> str:
+        return os.path.expanduser(self.aliases_file or _home(f".{self.under}_aliases"))
+
+    @property
+    def config_path(self) -> str:
+        return os.path.expanduser(self.config_dir or _home(".config", self.slug))
+
+    @property
+    def config_file(self) -> str:
+        return os.path.join(self.config_path, "config.json")
+
+    @property
+    def icons_dir(self) -> str:
+        return os.path.join(self.config_path, "icons")
+
+    @property
+    def cache_path(self) -> str:
+        return os.path.expanduser(self.cache_dir or _home(".cache", self.slug))
+
+    @property
+    def shim_path(self) -> str:
+        """Where this installer's Windows launcher scripts go.
+
+        ``%LOCALAPPDATA%\\<slug>\\bin`` — the directory added to the user PATH
+        on Windows in place of the alias file. Derived from the slug like every
+        other per-host name, so two orgs on one host keep separate shims.
+        """
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser(
+            _home("AppData", "Local")
+        )
+        return os.path.join(base, self.slug, "bin")
+
+    @property
+    def check_desktop(self) -> str:
+        return self.check_desktop_name or f"{self.slug}-check.desktop"
+
+    @property
+    def check_log(self) -> str:
+        return self.check_log_name or f"{self.slug}-check.log"
+
+    @property
+    def check_state(self) -> str:
+        return self.check_state_name or f"{self.slug}-check.json"
+
+    # --- interop ----------------------------------------------------------
+
+    ENV_VAR = "CLI_TOOL_KIT_SLUG"
+
+    def env(self) -> dict:
+        """Environment additions that let a child process rebuild this identity.
+
+        The engine installs a tool by running that tool's own ``--install`` in a
+        subprocess, where the tool's :class:`~cli_tools_kit.ToolInstaller` writes
+        the .desktop file and the alias. Passing the slug down means those
+        artifacts carry the parent installer's marker and land in its alias
+        file, instead of the first-party defaults.
+        """
+        return {self.ENV_VAR: self.slug}
+
+    @classmethod
+    def from_env(cls, default: Optional["InstallerIdentity"] = None) -> "InstallerIdentity":
+        """Rebuild the calling installer's identity from the environment.
+
+        Returns ``default`` (or :data:`LEGACY_IDENTITY`) when the variable is
+        unset or malformed, so a tool run by hand still installs normally.
+        """
+        slug = os.environ.get(cls.ENV_VAR, "").strip()
+        fallback = default if default is not None else LEGACY_IDENTITY
+        if not slug:
+            return fallback
+        try:
+            return cls(slug=slug)
+        except ValueError:
+            return fallback
+
+
+# The names the engine used before identities existed. Passing no identity
+# selects this, so a host that already has first-party shortcuts, aliases and
+# icon overrides keeps them.
+LEGACY_IDENTITY = InstallerIdentity(
+    slug="probable.work",
+    title="probable.work - Tools Installer",
+    desktop_file="ai_tools_manager.desktop",
+    desktop_name="Tools Installer",
+    wm_class="tools_installer",
+    notify_app="Tools Installer",
+    aliases_file=_home(".tools_aliases"),
+    config_dir=_home(".config", "tools-installer"),
+    cache_dir=_home(".cache", "tools-installer"),
+    check_desktop_name="tools-installer-check.desktop",
+    check_log_name="tools-installer-check.log",
+    check_state_name="tools-installer-check.json",
+)