toolrack-cli 0.1.0__py3-none-any.whl

toolrack/completion.py

@@ -0,0 +1,351 @@
+"""Shell-completion fast path that answers from the metadata cache.
+
+Importing Click and building the dynamic command tree dominates the latency of
+a <TAB> press. When the command-metadata cache is current, the answer can be
+computed from the cached entries alone, using only the standard library.
+
+Design rules:
+
+* The fast path never *guesses*. Anything it does not model exactly (unknown
+  tokens, option bundles, hidden alias groups, a stale or missing cache, ...)
+  returns ``None`` and the request is handled by Click as before.
+* Repository discovery and cache validation come from ``toolrack.runtime`` so
+  they cannot drift from the CLI.
+* ``tests/test_completion.py`` runs both implementations side by side and
+  requires byte-identical output, so Click upgrades that change completion
+  behaviour fail loudly instead of silently diverging.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+from collections.abc import Mapping
+
+from toolrack import runtime
+
+Completion = tuple[str, str, str]  # (type, value, help)
+
+_MODES = {"bash_complete", "zsh_complete", "fish_complete"}
+_HELP = ("--help", "Show this message and exit.")
+_VERSION = ("--version", "Show the version and exit.")
+
+# Mirrors the `core` group in toolrack.cli; tests compare it with the real
+# Click group so the two cannot diverge unnoticed.
+CORE_COMMANDS: dict[str, dict] = {
+    "register": {
+        "description": "Register a script as a CLI subcommand.",
+        "args": [{"name": "script_path", "positional": True, "required": True}],
+    },
+    "auto-register": {
+        "description": "Scan scripts/ for sidecar+script pairs and register unregistered ones.",
+        "args": [
+            {
+                "name": "dry_run",
+                "flag": True,
+                "option": "--dry-run",
+                "help": "Show what would be registered without writing.",
+            }
+        ],
+    },
+    "unregister": {
+        "description": "Remove a script from the registry.",
+        "args": [{"name": "script_path", "positional": True, "required": True}],
+    },
+    "reregister": {"description": "Re-validate all registered commands."},
+    "refresh-cache": {"description": "Rebuild the command metadata cache next to the registry."},
+    "list": {"description": "List all registered scripts."},
+    "install-completion": {
+        "description": "Print the shell completion script to stdout.",
+        "args": [{"name": "shell", "positional": True, "choices": ["bash", "zsh", "fish"]}],
+    },
+}
+CORE_GROUP_HELP = "Registry management and shell-completion commands."
+
+
+# --------------------------------------------------------------------------
+# Request parsing
+# --------------------------------------------------------------------------
+
+
+def _split_words(value: str) -> list[str]:
+    lexer = shlex.shlex(value, posix=True)
+    lexer.whitespace_split = True
+    lexer.commenters = ""
+    try:
+        return list(lexer)
+    except ValueError:
+        return value.split()
+
+
+def _request(shell: str, environ: Mapping[str, str]) -> tuple[list[str], str] | None:
+    """Return (args, incomplete) the way Click's shell classes derive them."""
+    try:
+        words = _split_words(environ["COMP_WORDS"])
+        if shell == "fish":
+            incomplete = environ.get("COMP_CWORD", "")
+            args = words[1:]
+            if incomplete and args and args[-1] == incomplete:
+                args.pop()
+            return args, incomplete
+        cword = int(environ["COMP_CWORD"])
+    except (KeyError, ValueError):
+        return None
+    return words[1:cword], words[cword] if cword < len(words) else ""
+
+
+# --------------------------------------------------------------------------
+# Command tree
+# --------------------------------------------------------------------------
+
+
+def _short_help(text: object, limit: int = 45) -> str:
+    """Equivalent of ``click.utils.make_default_short_help``."""
+    if not isinstance(text, str):
+        return ""
+    paragraph_end = text.find("\n\n")
+    if paragraph_end != -1:
+        text = text[:paragraph_end]
+    words = text.split()
+    if not words:
+        return ""
+    if words[0] == "\b":
+        words = words[1:]
+
+    total = 0
+    last = len(words) - 1
+    index = 0
+    for index, word in enumerate(words):
+        total += len(word) + (index > 0)
+        if total > limit:
+            break
+        if word[-1] == ".":
+            return " ".join(words[: index + 1])
+        if total == limit and index != last:
+            break
+    else:
+        return " ".join(words)
+
+    total += len("...")
+    while index > 0:
+        total -= len(words[index]) + (index > 0)
+        if total <= limit:
+            break
+        index -= 1
+    return " ".join(words[:index]) + "..."
+
+
+def _new_node(help_text: str = "") -> dict:
+    return {"help": help_text, "groups": {}, "commands": {}}
+
+
+def _cli_name(name: str) -> str:
+    return name.replace("_", "-")
+
+
+def _group_help(entry_path: str, group_parts: list[str], depth: int) -> str:
+    """Reproduce the help text cli._build_cli_tree gives a generated group."""
+    name = group_parts[depth]
+    if depth == 0:
+        parts = entry_path.replace("\\", "/").split("/")
+        if parts[0] == "scripts":
+            parts = parts[1:]
+        original = parts[0] if len(parts) > 1 else name
+        folder = original if _cli_name(original) != name else name
+        return f"Commands from scripts/{folder}/"
+    return f"Commands from scripts/{'/'.join(group_parts[: depth + 1])}/"
+
+
+def _build_tree(entries: list[dict]) -> dict | None:
+    root = _new_node()
+    root["groups"]["core"] = core = _new_node(CORE_GROUP_HELP)
+    core["commands"].update(CORE_COMMANDS)
+
+    for entry in entries:
+        if not isinstance(entry, dict):
+            return None
+        group_parts = entry.get("group_parts")
+        command_name = entry.get("cmd_name")
+        sidecar = entry.get("sidecar")
+        entry_path = entry.get("entry")
+        if not (
+            isinstance(group_parts, list)
+            and all(isinstance(part, str) for part in group_parts)
+            and isinstance(command_name, str)
+            and isinstance(sidecar, dict)
+            and isinstance(entry_path, str)
+        ):
+            return None
+
+        node = root
+        for depth, part in enumerate(group_parts):
+            if part not in node["groups"]:
+                node["groups"][part] = _new_node(_group_help(entry_path, group_parts, depth))
+            node = node["groups"][part]
+        node["commands"][command_name] = sidecar
+    return root
+
+
+# --------------------------------------------------------------------------
+# Completion
+# --------------------------------------------------------------------------
+
+
+def _arg_specs(sidecar: dict) -> list[dict] | None:
+    raw = sidecar.get("args") or []
+    if not isinstance(raw, list):
+        return None
+    specs = [arg for arg in raw if isinstance(arg, dict) and isinstance(arg.get("name"), str)]
+    return specs if len(specs) == len(raw) else None
+
+
+def _option_name(arg: dict) -> str:
+    return arg.get("option") or "--" + arg["name"].replace("_", "-")
+
+
+def _value_completions(arg: dict, incomplete: str) -> list[Completion]:
+    choices = arg.get("choices")
+    if choices:
+        return [("plain", str(c), "") for c in choices if str(c).startswith(incomplete)]
+    if arg.get("type") == "path":
+        return [("file", incomplete, "")]
+    return []
+
+
+def _command_completions(
+    sidecar: dict, args: list[str], incomplete: str
+) -> list[Completion] | None:
+    specs = _arg_specs(sidecar)
+    if specs is None:
+        return None
+    options = {_option_name(a): a for a in specs if not a.get("positional")}
+    positionals = [a for a in specs if a.get("positional")]
+    used: set[str] = set()
+    positional_count = 0
+    pending: dict | None = None
+    parse_options = True
+
+    for token in args:
+        if pending is not None:
+            pending = None
+            continue
+        if parse_options and token == "--":
+            parse_options = False
+        elif parse_options and token.startswith("-") and token != "-":
+            name, separator, _value = token.partition("=")
+            option = options.get(name)
+            if option is None:
+                return None  # --help, short-option bundles, unknown: let Click decide
+            used.add(name)
+            if not option.get("flag") and not separator:
+                pending = option
+        else:
+            positional_count += 1
+
+    if pending is not None:
+        return _value_completions(pending, incomplete)
+
+    if parse_options and incomplete.startswith("-"):
+        name, separator, value = incomplete.partition("=")
+        if separator:
+            option = options.get(name)
+            return None if option is None else _value_completions(option, value)
+        matches = [
+            ("plain", flag, str(spec.get("help") or ""))
+            for flag, spec in options.items()
+            if flag.startswith(incomplete)
+            and (spec.get("multiple") or flag not in used)
+        ]
+        if _HELP[0].startswith(incomplete) and _HELP[0] not in used:
+            matches.append(("plain", *_HELP))
+        return matches
+
+    if positional_count < len(positionals):
+        return _value_completions(positionals[positional_count], incomplete)
+    if positionals and positionals[-1].get("variadic"):
+        return _value_completions(positionals[-1], incomplete)
+    return []
+
+
+def _node_completions(node: dict, incomplete: str, *, root: bool) -> list[Completion]:
+    if incomplete.startswith("-"):
+        flags = [_VERSION, _HELP] if root else [_HELP]
+        return [("plain", *flag) for flag in flags if flag[0].startswith(incomplete)]
+
+    items = [
+        ("plain", name, _short_help(group["help"])) for name, group in node["groups"].items()
+    ]
+    items += [
+        ("plain", name, _short_help(sidecar.get("description")))
+        for name, sidecar in node["commands"].items()
+    ]
+    return sorted(
+        (item for item in items if item[1].startswith(incomplete)), key=lambda item: item[1]
+    )
+
+
+def complete(entries: list[dict], args: list[str], incomplete: str) -> list[Completion] | None:
+    """Return completions, or None when Click must answer instead."""
+    node = _build_tree(entries)
+    if node is None:
+        return None
+
+    root = True
+    for index, token in enumerate(args):
+        if token.startswith("-"):
+            return None
+        if token in node["groups"]:
+            node = node["groups"][token]
+            root = False
+        elif token in node["commands"]:
+            return _command_completions(node["commands"][token], args[index + 1 :], incomplete)
+        else:
+            return None  # hidden alias group, typo, ...
+    return _node_completions(node, incomplete, root=root)
+
+
+# --------------------------------------------------------------------------
+# Output
+# --------------------------------------------------------------------------
+
+
+def _format(shell: str, item: Completion) -> str:
+    kind, value, help_text = item
+    if shell == "zsh":
+        if help_text:
+            value = value.replace(":", r"\:")
+        return f"{kind}\n{value}\n{help_text or '_'}"
+    if shell == "fish" and help_text:
+        return f"{kind},{value}\t{help_text}"
+    return f"{kind},{value}"
+
+
+def try_fast_completion(environ: Mapping[str, str] = os.environ) -> bool:
+    """Answer a completion request from the cache. Return False to defer to Click."""
+    mode = environ.get(runtime.completion_var(runtime.cli_name(environ)))
+    if mode not in _MODES:
+        return False
+    shell = mode.removesuffix("_complete")
+
+    request = _request(shell, environ)
+    if request is None:
+        return False
+
+    repo = runtime.resolve_repository(environ)
+    try:
+        entries = runtime.read_cache(runtime.read_registry(repo), repo)
+    except (OSError, ValueError):
+        return False
+    if entries is None:
+        return False
+
+    items = complete(entries, *request)
+    if items is None:
+        return False
+
+    if os.name == "nt" and hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(newline="", errors="replace")
+    sys.stdout.write("\n".join(_format(shell, item) for item in items) + "\n")
+    sys.stdout.flush()
+    return True

toolrack/entrypoint.py

@@ -0,0 +1,14 @@
+"""Process entry point with a lightweight shell-completion fast path."""
+
+from __future__ import annotations
+
+from toolrack.completion import try_fast_completion
+
+
+def main() -> None:
+    if try_fast_completion():
+        return
+
+    from toolrack.cli import main as click_main
+
+    click_main()

toolrack/runtime.py

@@ -0,0 +1,178 @@
+"""Click-free runtime primitives shared by the CLI and the completion fast path.
+
+Everything here must stay importable without Click or PyYAML: the shell
+completion fast path (``toolrack.completion``) imports this module on every
+<TAB> press, and the CLI imports it so both sides agree on how the repository
+is located and how the command-metadata cache is validated.
+"""
+
+from __future__ import annotations
+
+import json
+import ntpath
+import os
+import sys
+from collections import namedtuple
+from collections.abc import Mapping
+
+LEGACY_REGISTRY_BASENAME = ".attic"
+DEFAULT_REGISTRY_BASENAME = ".toolrack"
+
+
+# A namedtuple rather than a dataclass: importing `dataclasses` costs more than
+# the rest of this module put together, and this runs on every <TAB>.
+RepositoryContext = namedtuple(
+    "RepositoryContext",
+    ["repo_root", "scripts_root", "registry_file", "cache_file", "aliases_file"],
+)
+
+
+def default_cli_name() -> str:
+    prog = os.path.basename(sys.argv[0] or "").strip()
+    if prog:
+        prog = os.path.splitext(prog)[0]
+        if prog not in {"", "__main__", "-m"}:
+            return prog
+    return "toolrack"
+
+
+def cli_name(environ: Mapping[str, str] = os.environ) -> str:
+    return environ.get("TOOLRACK_CLI_NAME") or default_cli_name()
+
+
+def completion_var(name: str) -> str:
+    return "_" + name.replace("-", "_").upper() + "_COMPLETE"
+
+
+def registry_basename(environ: Mapping[str, str] = os.environ) -> str:
+    return environ.get("TOOLRACK_REGISTRY_BASENAME") or DEFAULT_REGISTRY_BASENAME
+
+
+def is_windows() -> bool:
+    return os.name == "nt"
+
+
+def normalize_env_path(value: str | None) -> str | None:
+    """Map Git Bash / Cygwin Windows mount paths back to native Windows paths."""
+    if not value or not is_windows():
+        return value
+
+    normalized = value.replace("\\", "/")
+    if normalized.startswith("/cygdrive/") and len(normalized) > len("/cygdrive/x/"):
+        drive = normalized[len("/cygdrive/")]
+        remainder = normalized[len("/cygdrive/x") :]
+        return ntpath.normpath(f"{drive.upper()}:{remainder}")
+
+    if normalized.startswith("/") and len(normalized) > 3 and normalized[2] == "/":
+        drive = normalized[1]
+        if drive.isalpha():
+            return ntpath.normpath(f"{drive.upper()}:{normalized[2:]}")
+
+    return value
+
+
+def find_repo_root(environ: Mapping[str, str] = os.environ) -> str:
+    """Walk up from cwd until we find the registry file or .git."""
+    candidates = [
+        environ.get("TOOLRACK_REGISTRY_FILE"),
+        registry_basename(environ),
+        LEGACY_REGISTRY_BASENAME,
+    ]
+    names = [name for name in candidates if name and not os.path.isabs(name)]
+
+    here = os.path.abspath(os.getcwd())
+    candidate = here
+    while True:
+        if any(os.path.isfile(os.path.join(candidate, name)) for name in names):
+            return candidate
+        if os.path.isdir(os.path.join(candidate, ".git")):
+            return candidate
+        parent = os.path.dirname(candidate)
+        if parent == candidate:
+            return here
+        candidate = parent
+
+
+def resolve_repository(environ: Mapping[str, str] = os.environ) -> RepositoryContext:
+    """Resolve repository locations from the TOOLRACK_* environment."""
+
+    def path_from_env(name: str) -> str | None:
+        return normalize_env_path(environ.get(name))
+
+    repo_root = path_from_env("TOOLRACK_REPO_ROOT") or find_repo_root(environ)
+    registry_file = path_from_env("TOOLRACK_REGISTRY_FILE") or os.path.join(
+        repo_root, registry_basename(environ)
+    )
+    return RepositoryContext(
+        repo_root=repo_root,
+        scripts_root=path_from_env("TOOLRACK_SCRIPTS_ROOT") or os.path.join(repo_root, "scripts"),
+        registry_file=registry_file,
+        cache_file=path_from_env("TOOLRACK_CACHE_FILE") or registry_file + ".cache.json",
+        aliases_file=path_from_env("TOOLRACK_ALIASES_FILE")
+        or os.path.join(repo_root, "aliases.cfg"),
+    )
+
+
+def read_registry(repo: RepositoryContext) -> list[str]:
+    if not os.path.isfile(repo.registry_file):
+        return []
+    with open(repo.registry_file, encoding="utf-8") as handle:
+        return [
+            line.strip()
+            for line in handle
+            if line.strip() and not line.strip().startswith("#")
+        ]
+
+
+def abs_script_path(registry_entry: str, repo: RepositoryContext) -> str:
+    return os.path.normpath(os.path.join(repo.repo_root, registry_entry))
+
+
+def sidecar_path(script_path: str) -> str:
+    return os.path.splitext(script_path)[0] + ".yml"
+
+
+def file_state(path: str) -> dict[str, int | bool]:
+    try:
+        stat = os.stat(path)
+    except FileNotFoundError:
+        return {"exists": False, "size": 0, "mtime_ns": 0}
+    return {"exists": True, "size": stat.st_size, "mtime_ns": stat.st_mtime_ns}
+
+
+def cache_signature(registry: list[str], repo: RepositoryContext) -> str:
+    payload = {
+        "repo_root": repo.repo_root,
+        "scripts_root": repo.scripts_root,
+        "registry_file": repo.registry_file,
+        "aliases_file": repo.aliases_file,
+        "registry": registry,
+        "registry_state": file_state(repo.registry_file),
+        "aliases_state": file_state(repo.aliases_file),
+        "entries": [
+            {
+                "registry_entry": entry,
+                "script_state": file_state(abs_script_path(entry, repo)),
+                "sidecar_state": file_state(sidecar_path(abs_script_path(entry, repo))),
+            }
+            for entry in registry
+        ],
+    }
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def read_cache(registry: list[str], repo: RepositoryContext) -> list[dict] | None:
+    """Return cached command entries, or None when missing or stale."""
+    if not os.path.isfile(repo.cache_file):
+        return None
+    try:
+        with open(repo.cache_file, encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(payload, dict) or payload.get("signature") != cache_signature(
+        registry, repo
+    ):
+        return None
+    entries = payload.get("entries")
+    return entries if isinstance(entries, list) else None