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

cli_tools_kit/__init__.py

@@ -0,0 +1,59 @@
+"""cli-tools-kit — installer protocol + helpers for self-installing Python CLI/GUI tools.
+
+Public API:
+
+    from cli_tools_kit import (
+        ToolInstaller, ToolMetadata,   # desktop file / bash alias install/remove
+        CronInstaller,                 # idempotent cron-line management
+        advertise,                     # --advertise JSON helper
+        skill_status,                  # is an installed Claude skill stale?
+        InstallerIdentity,             # which names your installer claims on a host
+    )
+
+The GUI installer engine is a submodule, since importing it pulls in tkinter:
+
+    from cli_tools_kit.gui_installer import run
+
+    run(identity=InstallerIdentity(slug="acme-tools"), root_dir=HERE,
+        entry_script=__file__)
+
+Tools that live in several repos are listed in an installer.toml and resolved
+by cli_tools_kit.sources:
+
+    from cli_tools_kit.sources import run_installer
+
+    run_installer("installer.toml", identity=InstallerIdentity(slug="acme-tools"),
+                  entry_script=__file__)
+
+See README.md § Reusing the installer in your org for the full run() signature,
+README.md § Sources for the TOML format, and `python3 -m cli_tools_kit` to be
+walked through the setup.
+
+See PROTOCOL.md for the full --advertise specification.
+"""
+
+from .tool_installer import ToolInstaller, ToolMetadata
+from .identity import InstallerIdentity, LEGACY_IDENTITY
+from .cron_installer import CronInstaller
+from .advertise import advertise
+from .skills import (
+    installed_skill_hash,
+    read_installed_skill,
+    skill_payload_hash,
+    skill_status,
+)
+
+__all__ = [
+    "ToolInstaller",
+    "ToolMetadata",
+    "InstallerIdentity",
+    "LEGACY_IDENTITY",
+    "CronInstaller",
+    "advertise",
+    "skill_status",
+    "skill_payload_hash",
+    "installed_skill_hash",
+    "read_installed_skill",
+]
+
+__version__ = "0.6.0"

cli_tools_kit/__main__.py

@@ -0,0 +1,43 @@
+"""``python3 -m cli_tools_kit`` — set up an installer for your organisation.
+
+Two surfaces:
+
+    python3 -m cli_tools_kit                       first-run setup (the default)
+    python3 -m cli_tools_kit install FILE [flags]  run the installer for a
+                                                  sources file (see sources.py)
+
+``install`` takes the path of an ``installer.toml`` and passes every remaining
+flag to the installer engine. It uses the default installer identity, so an
+organisation that wants its own namespace on the host writes the short
+``installer.py`` in README § Sources instead and runs that.
+"""
+
+import os
+import sys
+
+from .onboarding import main
+
+USAGE = "usage: python3 -m cli_tools_kit install <installer.toml> [engine flags]"
+
+
+def _install(argv):
+    """The ``install`` subcommand: run the installer for one sources file."""
+    if not argv or argv[0].startswith("-"):
+        print(USAGE, file=sys.stderr)
+        return 2
+    config = argv[0]
+    if not os.path.isfile(config):
+        print(f"{config}: no such file\n{USAGE}", file=sys.stderr)
+        return 2
+    from .sources import run_installer  # noqa: PLC0415 — imports the engine
+    # ENTRY_SCRIPT is what the manager shortcut and the login check re-enter.
+    # The wrapper next to the sources file is the right one when there is one.
+    wrapper = os.path.join(os.path.dirname(os.path.abspath(config)), "installer.py")
+    entry = wrapper if os.path.isfile(wrapper) else os.path.abspath(sys.argv[0])
+    return run_installer(config, argv=argv[1:], entry_script=entry)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "install":
+        sys.exit(_install(sys.argv[2:]))
+    sys.exit(main())

cli_tools_kit/advertise.py

@@ -0,0 +1,77 @@
+"""Helper for the `--advertise` JSON convention.
+
+Every tool that opts into the installer protocol must emit a JSON list of
+metadata dicts when invoked with `--advertise`, then exit 0, BEFORE any heavy
+imports. This is enforced by a 5-second timeout in the installer's discovery
+probe; tools that import slow modules before answering the probe time out and
+disappear from the GUI.
+
+Usage:
+
+    # At the very top of your tool's main script:
+    import sys
+    from cli_tools_kit import ToolMetadata, advertise
+
+    if "--advertise" in sys.argv:
+        advertise(ToolMetadata(
+            name="My Tool",
+            desktop_file="my_tool.desktop",
+            icon="utilities-terminal",
+            desc="Does the thing",
+            tags=["CLI"],
+            alias="mytool",
+        ))
+
+    # Heavy imports AFTER the advertise check
+    import pandas as pd
+    ...
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import List, NoReturn, Union
+
+from .tool_installer import ToolMetadata
+
+
+def advertise(metadata: Union[ToolMetadata, List[ToolMetadata]]) -> NoReturn:
+    """Emit the --advertise JSON for one or more variants, then exit 0.
+
+    Call this inside an `if "--advertise" in sys.argv:` guard at the top of
+    your tool's main script. Heavy imports must come after the guard so the
+    installer's 5-second discovery probe doesn't time out.
+
+    The output schema includes `tags` (defaults to `["GUI", "Icon"]` when
+    unset) and `alias` (only when the tool is CLI-only or explicitly sets one).
+    """
+    items = list(metadata) if isinstance(metadata, (list, tuple)) else [metadata]
+    out = []
+    for m in items:
+        tags = m.tags if m.tags else ["GUI", "Icon"]
+        record = {
+            "name": m.name,
+            "desktop_file": m.desktop_file,
+            "icon": m.icon,
+            "desc": m.desc,
+            "terminal": m.terminal,
+            "args": m.args or [],
+            "tags": tags,
+        }
+        # alias is surfaced when the tool is CLI-only (no Icon tag) OR when
+        # an Icon tool explicitly opts into a shell alias alongside the .desktop.
+        if "Icon" not in tags or m.alias:
+            record["alias"] = m.alias or os.path.splitext(m.desktop_file)[0]
+            if m.alias_args is not None:
+                record["alias_args"] = list(m.alias_args)
+        # Optional fields are emitted only when set, so a tool that never
+        # touched them produces exactly the pre-0.2.0 record.
+        for key in ("capability", "domain", "category", "skill_name", "skill_status"):
+            value = getattr(m, key, None)
+            if value:
+                record[key] = value
+        out.append(record)
+    print(json.dumps(out))
+    sys.exit(0)

cli_tools_kit/cron_installer.py

@@ -0,0 +1,159 @@
+"""Atomic, idempotent cron-line management with marker comments.
+
+Each CronInstaller instance owns a unique marker string. `install()` rewrites
+the crontab so any pre-existing lines bearing this marker are stripped, then
+the new lines are appended with the marker as a trailing comment. Other tools'
+cron lines (with different markers or none at all) are left untouched.
+
+Example:
+
+    from cli_tools_kit import CronInstaller
+
+    cron = CronInstaller("studon-client")
+    cron.install([
+        f"@reboot cd {script_dir} && {python} {script} --daily-sync",
+        f"@reboot cd {script_dir} && {python} {script} --lecture-sync",
+    ])
+    # ... later
+    cron.remove()
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import List
+
+try:
+    from termcolor import colored
+except ImportError:
+    def colored(text: str, *_args, **_kwargs) -> str:
+        return text
+
+
+# The marker on real crontabs since the first release. It keeps the old
+# project name on purpose: renaming it would leave every already-installed
+# cron line unmatched by remove().
+_TAG_PREFIX = "# cli-tool-kit:"
+
+
+class CronInstaller:
+    """Manage a tool's cron lines via a unique marker.
+
+    A trailing comment of the form `# cli-tool-kit:<marker>` is appended to
+    each managed line. install() and remove() match on this tag, so lines
+    added by other tools (or hand-edited entries) survive unchanged.
+    """
+
+    # Class attribute so tests can swap in a fake crontab shim without
+    # monkeypatching subprocess.
+    CRONTAB_BIN: str = "crontab"
+
+    def __init__(self, marker: str) -> None:
+        if not marker or "\n" in marker or "#" in marker:
+            raise ValueError(
+                "marker must be non-empty and contain no '\\n' or '#' characters"
+            )
+        self.marker = marker
+        self.tag = f"{_TAG_PREFIX}{marker}"
+
+    # ---- crontab I/O ----
+
+    def _read(self) -> str:
+        """Return current crontab contents, or '' if there is no crontab.
+
+        `crontab -l` exits 1 with "no crontab for <user>" on stderr when the
+        user simply has no crontab — that maps to ''. Other non-zero exits
+        (binary missing, permission denied, transient failure) must NOT be
+        silently coerced to '', because that would cause a subsequent
+        `install([...])` to write a fresh crontab containing only the new
+        lines, wiping any pre-existing entries.
+        """
+        try:
+            result = subprocess.run(
+                [self.CRONTAB_BIN, "-l"], capture_output=True, text=True
+            )
+        except FileNotFoundError as e:
+            raise RuntimeError(f"crontab binary not found: {self.CRONTAB_BIN}") from e
+        if result.returncode == 0:
+            return result.stdout
+        if "no crontab" in (result.stderr or "").lower():
+            return ""
+        raise RuntimeError(
+            f"crontab -l failed (rc={result.returncode}): {result.stderr.strip()}"
+        )
+
+    def _write(self, content: str) -> None:
+        """Replace the crontab with the given content."""
+        if content and not content.endswith("\n"):
+            content += "\n"
+        subprocess.run(
+            [self.CRONTAB_BIN, "-"], input=content, text=True, check=True
+        )
+
+    def _strip_marked(self, crontab: str) -> List[str]:
+        """Return crontab lines not bearing this installer's tag."""
+        return [line for line in crontab.splitlines() if self.tag not in line]
+
+    # ---- public API ----
+
+    def install(self, lines: List[str]) -> None:
+        """Install (or replace) cron lines for this marker.
+
+        Strips any existing lines bearing our tag, then appends each given line
+        suffixed with the tag. Calling install() twice with the same lines
+        leaves the crontab in the same final state.
+        """
+        for line in lines:
+            if "\n" in line:
+                raise ValueError("cron lines must not contain '\\n'")
+            if self.tag in line:
+                raise ValueError(
+                    "cron lines must not include the tag (it is appended automatically)"
+                )
+
+        existing = self._strip_marked(self._read())
+        # Trim trailing blanks so our block sits cleanly at the end.
+        while existing and not existing[-1].strip():
+            existing.pop()
+
+        tagged = [f"{line}  {self.tag}" for line in lines]
+        self._write("\n".join(existing + tagged))
+
+        for line in tagged:
+            print(colored(f"Cron line installed: {line}", "green"))
+
+    def remove(self) -> None:
+        """Remove all cron lines bearing this installer's tag."""
+        original = self._read()
+        if not original:
+            print(colored(f"No crontab present (marker '{self.marker}').", "yellow"))
+            return
+
+        kept = self._strip_marked(original)
+        removed_count = len(original.splitlines()) - len(kept)
+        if removed_count == 0:
+            print(colored(
+                f"No cron lines to remove for marker '{self.marker}'.", "yellow"
+            ))
+            return
+
+        self._write("\n".join(kept))
+        print(colored(
+            f"Removed {removed_count} cron line(s) for marker '{self.marker}'.",
+            "green",
+        ))
+
+    def is_installed(self) -> bool:
+        """Return True iff any crontab line bears this installer's tag."""
+        return self.tag in self._read()
+
+    def installed_lines(self) -> List[str]:
+        """Return the currently-installed lines (without the trailing tag)."""
+        out: List[str] = []
+        for line in self._read().splitlines():
+            if self.tag not in line:
+                continue
+            # Strip the tag and any whitespace that preceded it.
+            body = line.split(self.tag)[0].rstrip()
+            out.append(body)
+        return out