launchline 0.1.0__py3-none-any.whl

launchline/__init__.py

@@ -0,0 +1,3 @@
+"""LaunchLine: a lightweight Windows Terminal launcher for interactive CLI tools."""
+
+from __future__ import annotations

launchline/__main__.py

@@ -0,0 +1,104 @@
+"""Application entry point for the LaunchLine launcher.
+
+When executed as ``python -m launchline``, the :func:`main` function
+parses CLI arguments, configures logging, and delegates to
+:class:`Application` which runs the interactive launcher loop.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from launchline.config import ConfigLoader, LaunchLineConfig
+from launchline.exceptions import LaunchError, LaunchLineError
+
+
+class Application:
+    """Top-level application controller for the launcher loop.
+
+    Owns the UI and runner instances and repeatedly presents the
+    launcher menu until the user exits or ``on_exit`` is ``"exit"``.
+    """
+
+    def __init__(self, config: LaunchLineConfig) -> None:
+        """Initialise the application with a validated configuration.
+
+        Args:
+            config: The loaded and validated launcher configuration.
+        """
+        self._config = config
+
+    def run(self) -> None:
+        """Run the interactive launcher loop.
+
+        Presents the TUI, launches the selected entry, and either
+        re-displays the menu (``on_exit="restart"``) or terminates
+        (``on_exit="exit"``).
+        """
+        from launchline.ui import LaunchLineUI
+
+        ui = LaunchLineUI(self._config)
+        runner = None
+
+        while True:
+            selected = ui.run()
+            if selected is None:
+                break
+
+            if runner is None:
+                from launchline.runner import EntryRunner
+
+                runner = EntryRunner(self._config)
+
+            try:
+                exit_code = runner.launch(selected)
+            except LaunchError as exc:
+                print(f"\nError: {exc}", file=sys.stderr)
+                if self._config.on_exit == "exit":
+                    sys.exit(1)
+                input("Press Enter to return to the launcher...")
+                continue
+            except KeyboardInterrupt:
+                if self._config.on_exit == "exit":
+                    sys.exit(130)
+                continue
+
+            if self._config.on_exit == "exit":
+                sys.exit(exit_code)
+            # on_exit == "restart": loop continues
+
+
+def main() -> None:
+    """Parse arguments, configure logging, and run the launcher."""
+    import logging
+
+    from launchline.cli import CommandLineInterface
+
+    args = CommandLineInterface.parse_args()
+
+    if args.icon_path:
+        print(CommandLineInterface.icon_path())
+        return
+
+    logging.basicConfig(
+        level=args.log_level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S",
+    )
+
+    try:
+        config_existed = args.config is not None or ConfigLoader.DEFAULT_PATH.exists()
+        config_path = ConfigLoader.resolve_path(args.config)
+        if not config_existed:
+            print(f"Created starter config at {config_path}")
+            print("Edit it to add your tools, then run launchline again.\n")
+        config = ConfigLoader.load(config_path)
+    except LaunchLineError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    Application(config).run()
+
+
+if __name__ == "__main__":
+    main()

launchline/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

launchline/cli.py

@@ -0,0 +1,70 @@
+"""Command-line interface definition.
+
+Provides :class:`CommandLineInterface` which encapsulates the
+``argparse`` setup and validation for the ``launchline`` CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from importlib.resources import files
+from pathlib import Path
+
+
+class CommandLineInterface:
+    """Command-line argument parser for LaunchLine.
+
+    All methods are static; the class serves as a logical namespace.
+    """
+
+    @staticmethod
+    def icon_path() -> Path:
+        """Return the path to the bundled LaunchLine icon.
+
+        Returns:
+            Absolute path to the ``.ico`` file shipped with the package.
+        """
+        resource = files("launchline").joinpath("assets", "launchline.ico")
+        return Path(str(resource))
+
+    @staticmethod
+    def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+        """Parse and validate command-line arguments.
+
+        Args:
+            argv: Argument list to parse.  Defaults to ``sys.argv[1:]``
+                when ``None``.
+
+        Returns:
+            Parsed argument namespace with ``config`` (``Path | None``)
+            and ``log_level`` (``int``) attributes.
+        """
+        parser = argparse.ArgumentParser(
+            prog="launchline",
+            description="A lightweight launcher for interactive CLI tools.",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        parser.add_argument(
+            "--config",
+            type=Path,
+            default=None,
+            help="Path to config TOML (overrides env var and default path).",
+        )
+        parser.add_argument(
+            "--log-level",
+            type=str,
+            default="WARNING",
+            choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+            help="Logging verbosity (default: %(default)s).",
+        )
+        parser.add_argument(
+            "--icon-path",
+            action="store_true",
+            default=False,
+            help="Print the path to the bundled icon and exit.",
+        )
+
+        args = parser.parse_args(argv)
+        args.log_level = getattr(logging, args.log_level)
+        return args

launchline/config.py

@@ -0,0 +1,257 @@
+"""TOML configuration loading and validation.
+
+This module defines the configuration data model
+(:class:`EntryConfig`, :class:`LaunchLineConfig`) and provides
+:class:`ConfigLoader` for resolving, loading, validating, and
+bootstrapping TOML configuration files.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from launchline.exceptions import ConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class EntryConfig:
+    """Configuration for a single launchable entry.
+
+    Attributes:
+        name: Display name shown in the launcher menu.
+        command: Executable command to run (e.g. ``"pwsh"``).
+        args: Additional command-line arguments passed to the command.
+        description: Short description shown beside the entry name.
+        working_directory: Working directory for the subprocess, or
+            ``None`` to inherit the launcher's CWD.
+        env: Extra environment variables merged into the subprocess
+            environment.
+    """
+
+    name: str
+    command: str
+    args: tuple[str, ...] = ()
+    description: str = ""
+    working_directory: Path | None = None
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class LaunchLineConfig:
+    """Top-level launcher configuration.
+
+    Attributes:
+        entries: Ordered tuple of launchable entries.
+        title: Text displayed in the header and terminal title bar.
+        on_exit: Behaviour after a launched process exits —
+            ``"restart"`` (re-show the menu) or ``"exit"`` (quit).
+        show_exit: Whether to display the ``Exit`` option (shortcut
+            ``0``) in the menu.
+        clear_on_launch: Whether to clear the screen before launching.
+        ghost_text: Whether to show an autocomplete hint on the prompt
+            line with the highlighted entry's name.
+        numeric_trigger: Whether pressing a digit immediately launches
+            the matching entry (when ≤9 entries and no active query).
+            When ``False``, digits always enter the search query and
+            fuzzy-match against both numbers and names.
+    """
+
+    entries: tuple[EntryConfig, ...]
+    title: str = "LaunchLine"
+    on_exit: str = "restart"
+    show_exit: bool = True
+    clear_on_launch: bool = True
+    ghost_text: bool = True
+    numeric_trigger: bool = True
+
+
+class ConfigLoader:
+    """Resolves, loads, validates, and bootstraps TOML config files.
+
+    All methods are static; the class serves as a logical namespace.
+    """
+
+    DEFAULT_PATH: Path = Path.home() / ".config" / "launchline" / "config.toml"
+    """Default file-system location for the configuration file."""
+
+    ENV_VAR_NAME: str = "LAUNCHLINE_CONFIG"
+    """Environment variable that overrides the default config path."""
+
+    VALID_ON_EXIT: tuple[str, ...] = ("restart", "exit")
+    """Permitted values for the ``on_exit`` setting."""
+
+    STARTER_CONFIG: str = """\
+# LaunchLine configuration
+# See https://github.com/mikejhill/launchline#configuration-reference
+
+[settings]
+# title = "LaunchLine"
+# on_exit = "restart"   # "restart" (default) or "exit"
+# show_exit = true
+# clear_on_launch = true
+# ghost_text = true
+# numeric_trigger = true
+
+[[entries]]
+name = "PowerShell"
+command = "pwsh"
+description = "PowerShell 7"
+"""
+    """Template written when no config file exists yet."""
+
+    @staticmethod
+    def resolve_path(cli_path: Path | None = None) -> Path:
+        """Determine the config file path using the resolution order.
+
+        Priority: CLI flag → environment variable → default path.
+        If no config file exists at any location, a starter config is
+        created automatically at :attr:`DEFAULT_PATH`.
+
+        Args:
+            cli_path: Explicit path from ``--config`` flag, or ``None``.
+
+        Returns:
+            Resolved path to an existing config file.
+
+        Raises:
+            ConfigurationError: If a specified path does not exist.
+        """
+        if cli_path is not None:
+            expanded = cli_path.expanduser()
+            if not expanded.exists():
+                raise ConfigurationError(f"Config file not found: {expanded}")
+            return expanded
+
+        env_path = os.environ.get(ConfigLoader.ENV_VAR_NAME)
+        if env_path:
+            expanded = Path(env_path).expanduser()
+            if expanded.exists():
+                return expanded
+            raise ConfigurationError(
+                f"Config file from {ConfigLoader.ENV_VAR_NAME} not found: {expanded}"
+            )
+
+        if ConfigLoader.DEFAULT_PATH.exists():
+            return ConfigLoader.DEFAULT_PATH
+
+        return ConfigLoader._create_default()
+
+    @staticmethod
+    def load(config_path: Path) -> LaunchLineConfig:
+        """Load and validate a TOML config file.
+
+        Reads the file, validates all settings and entries, and returns
+        a fully populated :class:`LaunchLineConfig`.
+
+        Args:
+            config_path: Path to the TOML file.
+
+        Returns:
+            A validated ``LaunchLineConfig`` instance.
+
+        Raises:
+            ConfigurationError: If the file contains invalid TOML,
+                unknown setting values, or malformed entries.
+        """
+        try:
+            with config_path.open("rb") as f:
+                raw = tomllib.load(f)
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigurationError(f"Invalid TOML in {config_path}: {exc}") from exc
+
+        settings = raw.get("settings", {})
+
+        title: str = settings.get("title", "LaunchLine")
+
+        on_exit = settings.get("on_exit", "restart")
+        if on_exit not in ConfigLoader.VALID_ON_EXIT:
+            raise ConfigurationError(
+                f"Invalid on_exit value: '{on_exit}'. "
+                f"Must be one of: {', '.join(ConfigLoader.VALID_ON_EXIT)}"
+            )
+
+        show_exit: bool = settings.get("show_exit", True)
+        clear_on_launch: bool = settings.get("clear_on_launch", True)
+        ghost_text: bool = settings.get("ghost_text", True)
+        numeric_trigger: bool = settings.get("numeric_trigger", True)
+
+        raw_entries: list[dict[str, object]] = raw.get("entries", [])
+        if not raw_entries:
+            raise ConfigurationError("No entries configured.")
+
+        entries: list[EntryConfig] = []
+        for i, entry_raw in enumerate(raw_entries, 1):
+            name = entry_raw.get("name", "")
+            command = entry_raw.get("command", "")
+            if not name or not command:
+                raise ConfigurationError(
+                    f"Entry {i}: 'name' and 'command' are required."
+                )
+
+            raw_args = entry_raw.get("args", [])
+            if not isinstance(raw_args, list):
+                raise ConfigurationError(
+                    f"Entry {i}: 'args' must be a list of strings."
+                )
+
+            wd_raw = entry_raw.get("working_directory")
+            wd: Path | None = None
+            if wd_raw:
+                wd = Path(str(wd_raw)).expanduser()
+                if not wd.exists():
+                    logger.warning(
+                        "Entry '%s': working_directory does not exist: %s",
+                        name,
+                        wd,
+                    )
+                    wd = None
+
+            raw_env = entry_raw.get("env", {})
+            if not isinstance(raw_env, dict):
+                raise ConfigurationError(
+                    f"Entry {i}: 'env' must be a table of strings."
+                )
+
+            entries.append(
+                EntryConfig(
+                    name=str(name),
+                    command=str(command),
+                    args=tuple(str(a) for a in raw_args),
+                    description=str(entry_raw.get("description", "")),
+                    working_directory=wd,
+                    env={str(k): str(v) for k, v in raw_env.items()},
+                )
+            )
+
+        return LaunchLineConfig(
+            entries=tuple(entries),
+            title=title,
+            on_exit=on_exit,
+            show_exit=show_exit,
+            clear_on_launch=clear_on_launch,
+            ghost_text=ghost_text,
+            numeric_trigger=numeric_trigger,
+        )
+
+    @staticmethod
+    def _create_default() -> Path:
+        """Create a starter config at :attr:`DEFAULT_PATH`.
+
+        Creates parent directories as needed and writes
+        :attr:`STARTER_CONFIG` to the file.
+
+        Returns:
+            Path to the newly created config file.
+        """
+        ConfigLoader.DEFAULT_PATH.parent.mkdir(parents=True, exist_ok=True)
+        ConfigLoader.DEFAULT_PATH.write_text(
+            ConfigLoader.STARTER_CONFIG, encoding="utf-8"
+        )
+        logger.info("Created starter config at %s", ConfigLoader.DEFAULT_PATH)
+        return ConfigLoader.DEFAULT_PATH

launchline/exceptions.py

@@ -0,0 +1,39 @@
+"""Project-specific exception hierarchy.
+
+All custom exceptions inherit from ``LaunchLineError`` so callers can
+catch the entire family with a single ``except`` clause when needed.
+"""
+
+from __future__ import annotations
+
+
+class LaunchLineError(Exception):
+    """Base exception for all LaunchLine errors.
+
+    Subclassed by every domain-specific exception so that callers may
+    catch ``LaunchLineError`` as a generic fallback.
+    """
+
+
+class ConfigurationError(LaunchLineError):
+    """Raised when a configuration file is invalid, missing, or malformed."""
+
+
+class LaunchError(LaunchLineError):
+    """Raised when a configured command fails to launch.
+
+    Attributes:
+        command: The command string that failed.
+        reason: A human-readable explanation of the failure.
+    """
+
+    def __init__(self, command: str, reason: str) -> None:
+        """Initialise with the failed command and a reason string.
+
+        Args:
+            command: The command that could not be executed.
+            reason: Why the launch failed (e.g. file not found).
+        """
+        super().__init__(f"Failed to launch '{command}': {reason}")
+        self.command = command
+        self.reason = reason

launchline/fuzzy.py

@@ -0,0 +1,59 @@
+"""Fuzzy substring matching with scoring.
+
+Provides :class:`FuzzyMatcher`, which scores how well a short query
+string matches against a longer candidate string using an ordered,
+non-contiguous character-matching algorithm with bonuses for runs and
+word-boundary alignment.
+"""
+
+from __future__ import annotations
+
+
+class FuzzyMatcher:
+    """Fuzzy substring matching with scoring.
+
+    All methods are static; the class serves as a logical namespace.
+    """
+
+    @staticmethod
+    def score(query: str, candidate: str) -> int | None:
+        """Score how well *query* fuzzy-matches *candidate*.
+
+        All characters in *query* must appear in *candidate* in order (not
+        necessarily contiguous).  Higher scores indicate better matches, with
+        bonuses for contiguous runs and word-boundary alignment.
+
+        Args:
+            query: The search string.
+            candidate: The string to match against.
+
+        Returns:
+            An integer score (higher is better), or ``None`` if the query does
+            not match the candidate.
+        """
+        if not query:
+            return 0
+
+        query_lower = query.lower()
+        candidate_lower = candidate.lower()
+
+        q_idx = 0
+        score = 0
+        prev_match_idx = -2
+
+        for c_idx, c_char in enumerate(candidate_lower):
+            if q_idx < len(query_lower) and c_char == query_lower[q_idx]:
+                score += 1
+                # Contiguous character bonus
+                if c_idx == prev_match_idx + 1:
+                    score += 2
+                # Word-boundary bonus
+                if c_idx == 0 or candidate_lower[c_idx - 1] in " -_./\\":
+                    score += 3
+                prev_match_idx = c_idx
+                q_idx += 1
+
+        if q_idx < len(query_lower):
+            return None
+
+        return score