machineconfig 6.82__py3-none-any.whl → 8.51__py3-none-any.whl

machineconfig/utils/meta.py

@@ -5,7 +5,7 @@ from typing import Any
 
 
 def get_import_module_string(py_file: str) -> str:
-    from machineconfig.scripts.python.helpers_fire.helpers4 import get_import_module_code
+    from machineconfig.scripts.python.helpers.helpers_fire_command.file_wrangler import get_import_module_code
     from machineconfig.utils.accessories import get_repo_root
     from pathlib import Path
     repo_root = get_repo_root(Path(py_file))
@@ -29,7 +29,8 @@ except (ImportError, ModuleNotFoundError) as ex:
     return txt
 
 
-def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_module: bool) -> str:
+def lambda_to_python_script(lmb: Callable[[], Any],
+            in_global: bool, import_module: bool) -> str:
     """
     caveats: always use keyword arguments in the lambda call for best results.
     return statement not allowed in the wrapped function (otherwise it can be put in the global space)
@@ -55,9 +56,19 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
     import types as _types
     from pathlib import Path as _Path
 
+    def _stringify_annotation(annotation: Any) -> Any:
+        if annotation is _inspect.Signature.empty or annotation is _inspect.Parameter.empty:
+            return annotation
+        if isinstance(annotation, str):
+            return annotation
+        try:
+            return _inspect.formatannotation(annotation)
+        except Exception:
+            return str(annotation)
+
     # sanity checks
     if not (callable(lmb) and isinstance(lmb, _types.LambdaType)):
-        raise TypeError("Expected a lambda function object")
+        raise TypeError(f"Expected a lambda function object, got {type(lmb)}")
 
     src = _inspect.getsource(lmb)
     src = _textwrap.dedent(src)
@@ -70,7 +81,7 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
             lambda_node = n
             break
     if lambda_node is None:
-        raise ValueError("Could not find a lambda expression in source")
+        raise ValueError(f"""Could not find a lambda expression in source, got:\n{lmb}\nwhich is not a lambda, its a {src}""")
 
     body = lambda_node.body
     if not isinstance(body, _ast.Call):
@@ -102,7 +113,7 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
     if not callable(func_obj):
         raise TypeError("Resolved object is not callable")
 
-    func_name = getattr(func_obj, "__name__", "<unknown>")
+    func_name = getattr(getattr(func_obj, "__code__", None), "co_name", None) or getattr(func_obj, "__name__", "<unknown>")
 
     import_prefix: str = ""
     if import_module:
@@ -174,16 +185,18 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
         else:
             new_default = param.default
 
-        # Recreate the Parameter (keeping annotation and kind)
+        normalized_annotation = _stringify_annotation(param.annotation)
+
         if new_default is _inspect.Parameter.empty:
-            new_param = _inspect.Parameter(name, param.kind, annotation=param.annotation)
+            new_param = _inspect.Parameter(name, param.kind, annotation=normalized_annotation)
         else:
             new_param = _inspect.Parameter(
-                name, param.kind, default=new_default, annotation=param.annotation
+                name, param.kind, default=new_default, annotation=normalized_annotation
             )
         new_params.append(new_param)
 
-    new_sig = _inspect.Signature(parameters=new_params, return_annotation=sig.return_annotation)
+    return_annotation = _stringify_annotation(sig.return_annotation)
+    new_sig = _inspect.Signature(parameters=new_params, return_annotation=return_annotation)
 
     # If in_global mode, return kwargs as global assignments + dedented body
     if in_global:
@@ -200,15 +213,11 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
             
             # Build type annotation string if available
             if param.annotation is not _inspect.Parameter.empty:
-                # Try to get a nice string representation of the annotation
-                try:
-                    if hasattr(param.annotation, "__name__"):
-                        type_str = param.annotation.__name__
-                    else:
-                        type_str = str(param.annotation)
-                except Exception:
-                    type_str = str(param.annotation)
-                global_assignments.append(f"{name}: {type_str} = {repr(value)}")
+                annotation_literal = _stringify_annotation(param.annotation)
+                if isinstance(annotation_literal, str):
+                    global_assignments.append(f"{name}: {repr(annotation_literal)} = {repr(value)}")
+                else:
+                    global_assignments.append(f"{name} = {repr(value)}")
             else:
                 global_assignments.append(f"{name} = {repr(value)}")
         
@@ -230,12 +239,20 @@ def lambda_to_python_script(lmb: Callable[[], Any], in_global: bool, import_modu
         if lines[-1].startswith("return "):
             lines[-1] = lines[-1].replace("return ", "# return ", 1)
             result_text = "\n".join(lines)
-    if "Optional[" in result_text or "Any" in result_text or "Union[" in result_text or "Literal[" in result_text:
-        result_text = "from typing import *\n\n" + result_text
 
+    if "Optional" in result_text or "Any" in result_text or "Union" in result_text or "Literal" in result_text:
+        result_text = "from typing import Optional, Any, Union, Literal\n\n" + result_text
     if import_prefix:
         result_text = f"{import_prefix}{result_text}"
     return result_text
 
 if __name__ == "__main__":
-    pass
+    from machineconfig.utils.code import print_code
+    import_code_robust = "<import_code_robust>"
+    print_code.__name__ = "blah"
+    res = lambda_to_python_script(
+            lambda: print_code(code=import_code_robust, lexer="python", desc="import as module code"),
+            in_global=True, import_module=False
+        )
+
+    print(res)

machineconfig/utils/options.py

@@ -1,40 +1,99 @@
+
 from pathlib import Path
-from machineconfig.utils.installer_utils.installer_abc import check_tool_exists
 from rich.text import Text
 from rich.panel import Panel
 from rich.console import Console
 import subprocess
-from typing import Optional, Union, Iterable, overload, Literal
+from typing import Optional, Union, Iterable, overload, Literal, cast
 
 @overload
-def choose_from_options[T](msg: str, options: Iterable[T], multi: Literal[False], custom_input: bool = False, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, fzf: bool = False) -> T: ...
+def choose_from_options[T](options: Iterable[T], msg: str, multi: Literal[False], custom_input: bool = False, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, tv: bool = False, preview: Optional[Literal["bat"]]=None) -> T: ...
 @overload
-def choose_from_options[T](msg: str, options: Iterable[T], multi: Literal[True], custom_input: bool = True, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, fzf: bool = False, ) -> list[T]: ...
-def choose_from_options[T](msg: str, options: Iterable[T], multi: bool, custom_input: bool = True, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, fzf: bool = False, ) -> Union[T, list[T]]:
+def choose_from_options[T](options: Iterable[T], msg: str, multi: Literal[True], custom_input: bool = True, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, tv: bool = False, preview: Optional[Literal["bat"]]=None) -> list[T]: ...
+def choose_from_options[T](options: Iterable[T], msg: str, multi: bool, custom_input: bool = True, header: str = "", tail: str = "", prompt: str = "", default: Optional[T] = None, tv: bool = False, preview: Optional[Literal["bat"]]=None, ) -> Union[T, list[T]]:
     # TODO: replace with https://github.com/tmbo/questionary
     # # also see https://github.com/charmbracelet/gum
     options_strings: list[str] = [str(x) for x in options]
     default_string = str(default) if default is not None else None
     console = Console()
-    fzf_exists = check_tool_exists("fzf")
-    # print("\n" * 10, f"{fzf=}, {fzf_exists=}", "\n" * 10)
-    if fzf and fzf_exists:
-        from pyfzf.pyfzf import FzfPrompt
-        fzf_prompt = FzfPrompt()
-        nl = "\n"
-        choice_string_multi: list[str] = fzf_prompt.prompt(choices=options_strings, fzf_options=("--multi" if multi else "") + f' --prompt "{prompt.replace(nl, " ")}" ')  # --border-label={msg.replace(nl, ' ')}")
-        # --border=rounded doens't work on older versions of fzf installed at Ubuntu 20.04
+    from machineconfig.utils.installer_utils.installer_locator_utils import check_tool_exists
+    # from machineconfig.utils.installer_utils.installer_cli import check_tool_exists
+    # print("ch1")
+    if tv and check_tool_exists("tv"):
+        from machineconfig.utils.accessories import randstr
+        options_txt_path = Path.home().joinpath("tmp_results/tmp_files/choices_" + randstr(6) + ".txt")
+        options_txt_path.parent.mkdir(parents=True, exist_ok=True)
+        options_txt_path.write_text("\n".join(options_strings), encoding="utf-8")
+
+        # Run `tv` interactively so the user can make selections. We redirect tv's
+        # stdout to a temporary output file so we can read the chosen lines after
+        # the interactive session completes. Do not capture_output or redirect
+        # stdin/stderr here so `tv` stays attached to the terminal.
+        tv_out_path = options_txt_path.with_name(options_txt_path.stem + "_out.txt")
+        if preview is None:
+            preview_line = ""
+        elif preview == "bat":
+            preview_line = r"""--preview-command "bat -n --color=always {}" --preview-size 70 """
+        
+        import platform
+        if platform.system() == "Windows":
+            # PowerShell + TUI apps can be finicky when stdin is a pipe. Avoid piping into `tv` and
+            # instead provide a `--source-command` so `tv` can keep stdin attached to the console.
+            # Also: `tv --ansi` is a flag (no value). Passing `true` makes it a positional argument
+            # (channel/path/command), which can lead to confusing behavior.
+            source_cmd = f"cmd /C type \"{options_txt_path}\""
+            tv_cmd = f"""
+$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+tv  {preview_line} --ansi --source-command '{source_cmd}' --source-output "{{}}" | Out-File -Encoding utf8 -FilePath "{tv_out_path}" """
+        else:
+            source_cmd = f'cat "{options_txt_path}"'
+            tv_cmd = f"""tv  {preview_line} --ansi --source-command "{source_cmd}" --source-output "{{}}" > "{tv_out_path}" """
+
+        # print(f"Running tv command: {tv_cmd}")
+        # print(f"Options file: {options_txt_path}")
+        # print(f"Content:\n{options_txt_path.read_text(encoding='utf-8')}")
+        # print(f"tv output file: {tv_out_path}")
+        from machineconfig.utils.code import run_shell_script
+        res = run_shell_script(tv_cmd, display_script=False, clean_env=False)
+        
+        # If tv returned a non-zero code and there is no output file, treat it as an error.
+        if res.returncode != 0 and not tv_out_path.exists():
+            raise RuntimeError(f"Got error running tv command: {tv_cmd}\nreturncode: {res.returncode}")
+
+        # Read selections (if any) from the output file created by tv.
+        print(f"Reading tv output from: {tv_out_path}")
+        out_text = tv_out_path.read_text(encoding="utf-8-sig")
+        choice_string_multi = [x for x in out_text.splitlines() if x.strip() != ""]
+
+        # if len(choice_string_multi) == 0:  # e.g. user pressed escape
+        #     console.print(Panel("❓ No option selected!", title="Error", expand=False))
+        #     return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, tv=tv, multi=multi, custom_input=custom_input)
+
+        # Cleanup temporary files
+        options_txt_path.unlink(missing_ok=True)
+        tv_out_path.unlink(missing_ok=True)
         if not multi:
             try:
                 choice_one_string = choice_string_multi[0]
+                if isinstance(list(options)[0], str):
+                    print(f"✅ Selected option: {choice_one_string}")
+                    return cast(T, choice_one_string)
                 choice_idx = options_strings.index(choice_one_string)
-                return list(options)[choice_idx]
+                choice_made =  list(options)[choice_idx]
+                print(f"✅ Selected option: {choice_made}")
+                return choice_made
             except IndexError as ie:
-                print(f"❌ Error: {options=}, {choice_string_multi=}")
-                print(f"🔍 Available choices: {choice_string_multi}")
+                # print(f"❌ Error: {options=}, {choice_string_multi=}")
+                print(f"🔍 Available choices: {len(choice_string_multi)}")
                 raise ie
+        if isinstance(list(options)[0], str):
+            result2 = cast(list[T], choice_string_multi)
+            print(f"✅ Selected options: {result2}")
+            return result2
         choice_idx_s = [options_strings.index(x) for x in choice_string_multi]
-        return [list(options)[x] for x in choice_idx_s]
+        result = [list(options)[x] for x in choice_idx_s]
+        print(f"✅ Selected options: {result}")
+        return result
     else:
         if default is not None:
             assert default in options, f"Default `{default}` option not in options `{list(options)}`"
@@ -55,7 +114,7 @@ def choose_from_options[T](msg: str, options: Iterable[T], multi: bool, custom_i
         if choice_string == "":
             if default_string is None:
                 console.print(Panel("🧨 Default option not available!", title="Error", expand=False))
-                return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, fzf=fzf, multi=multi, custom_input=custom_input)
+                return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, tv=tv, multi=multi, custom_input=custom_input)
             choice_idx = options_strings.index(default_string)
             assert default is not None, "🧨 Default option not available!"
             choice_one: T = default
@@ -73,7 +132,7 @@ def choose_from_options[T](msg: str, options: Iterable[T], multi: bool, custom_i
                     _ = ie
                     # raise ValueError(f"Unknown choice. {choice_string}") from ie
                     console.print(Panel(f"❓ Unknown choice: '{choice_string}'", title="Error", expand=False))
-                    return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, fzf=fzf, multi=multi, custom_input=custom_input)
+                    return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, tv=tv, multi=multi, custom_input=custom_input)
             except (TypeError, ValueError) as te:  # int(choice_string) failed due to # either the number is invalid, or the input is custom.
                 if choice_string in options_strings:  # string input
                     choice_idx = options_strings.index(choice_one)  # type: ignore
@@ -84,7 +143,7 @@ def choose_from_options[T](msg: str, options: Iterable[T], multi: bool, custom_i
                     _ = te
                     # raise ValueError(f"Unknown choice. {choice_string}") from te
                     console.print(Panel(f"❓ Unknown choice: '{choice_string}'", title="Error", expand=False))
-                    return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, fzf=fzf, multi=multi, custom_input=custom_input)
+                    return choose_from_options(msg=msg, options=options, header=header, tail=tail, prompt=prompt, default=default, tv=tv, multi=multi, custom_input=custom_input)
         console.print(Panel(f"✅ Selected option {choice_idx}: {choice_one}", title="Selected", expand=False))
         if multi:
             return [choice_one]
@@ -103,14 +162,13 @@ def choose_cloud_interactively() -> str:
         raise ValueError(f"Got {tmp} from rclone listremotes")
     if len(remotes) == 0:
         raise RuntimeError("You don't have remotes. Configure your rclone first to get cloud services access.")
-    cloud: str = choose_from_options(msg="WHICH CLOUD?", multi=False, options=list(remotes), default=remotes[0], fzf=True)
+    cloud: str = choose_from_options(msg="WHICH CLOUD?", multi=False, options=list(remotes), default=remotes[0], tv=True)
     console.print(Panel(f"✅ SELECTED CLOUD | {cloud}", border_style="bold blue", expand=False))
     return cloud
 
 
 def get_ssh_hosts() -> list[str]:
     from paramiko import SSHConfig
-
     c = SSHConfig()
     c.parse(open(Path.home().joinpath(".ssh/config"), encoding="utf-8"))
     return list(c.get_hostnames())
@@ -121,4 +179,4 @@ def choose_ssh_host(multi: Literal[False]) -> str: ...
 @overload
 def choose_ssh_host(multi: Literal[True]) -> list[str]: ...
 def choose_ssh_host(multi: bool):
-    return choose_from_options(msg="", options=get_ssh_hosts(), multi=multi, fzf=True)
+    return choose_from_options(msg="", options=get_ssh_hosts(), multi=multi, tv=True)

machineconfig/utils/options_utils/options_tv_linux.py

@@ -0,0 +1,211 @@
+
+#!/usr/bin/env python3
+import base64
+import pathlib
+import pprint
+import shutil
+import subprocess
+import tempfile
+import os
+from typing import Any, overload, Literal, Union
+
+from git import Optional
+
+
+def _format_preview_value(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return pprint.pformat(value, width=88, sort_dicts=True)
+
+
+def _toml_inline_table(values: dict[str, str]) -> str:
+    if not values:
+        return ""
+    parts: list[str] = []
+    for key in sorted(values.keys()):
+        raw_value = values[key]
+        escaped = raw_value.replace("\\", "\\\\").replace('"', '\\"')
+        parts.append(f'{key} = "{escaped}"')
+    return "env = { " + ", ".join(parts) + " }\n"
+
+
+def _normalize_extension(extension: str | None) -> str | None:
+    if extension is None:
+        return None
+    trimmed = extension.strip()
+    if trimmed.startswith("."):
+        trimmed = trimmed[1:]
+    if not trimmed:
+        return None
+    return trimmed
+
+
+def _infer_extension_from_key(key: Optional[str]) -> str | None:
+    if not isinstance(key, str):
+        return None
+    candidate = key.strip()
+    if not candidate or any(char.isspace() for char in candidate):
+        return None
+    suffix = pathlib.Path(candidate).suffix
+    if not suffix:
+        return None
+    return _normalize_extension(suffix)
+
+
+@overload
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[True], preview_size_percent: float) -> list[str]: ...
+@overload
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[False], preview_size_percent: float) -> Union[str, None]: ...
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: bool, preview_size_percent: float) -> Union[Union[str, None], list[str]]:
+    keys = list(options_to_preview_mapping.keys())
+    if not keys:
+        return [] if multi else None
+    normalized_extension = _normalize_extension(extension)
+    preview_panel_size = max(10, min(90, int(preview_size_percent)))
+    terminal_width = shutil.get_terminal_size(fallback=(120, 40)).columns
+    preview_width = max(20, int(terminal_width * preview_panel_size / 100) - 4)
+    with tempfile.TemporaryDirectory(prefix="tv_channel_") as tmpdir:
+        tempdir = pathlib.Path(tmpdir)
+        entries: list[str] = []
+        index_map: dict[int, str] = {}
+        preview_map_path = tempdir / "previews.tsv"
+        preview_rows: list[str] = []
+        for idx, key in enumerate(keys):
+            display_key = key.replace("\t", "    ").replace("\n", " ")
+            entries.append(f"{idx}\t{display_key}")
+            index_map[idx] = key
+            preview_value = _format_preview_value(options_to_preview_mapping[key])
+            encoded_preview = base64.b64encode(preview_value.encode("utf-8")).decode("ascii")
+            entry_extension = normalized_extension or _infer_extension_from_key(key) or ""
+            preview_rows.append(f"{idx}\t{encoded_preview}\t{entry_extension}")
+        preview_map_path.write_text("\n".join(preview_rows), encoding="utf-8")
+        entries_path = tempdir / "entries.tsv"
+        entries_path.write_text("\n".join(entries), encoding="utf-8")
+        preview_script = tempdir / "preview.sh"
+        preview_script.write_text(
+            """#!/usr/bin/env bash
+set -euo pipefail
+
+idx="$1"
+script_dir="$(cd -- "$(dirname -- "$0")" && pwd)"
+previews_file="${script_dir}/previews.tsv"
+
+if [[ ! -f "${previews_file}" ]]; then
+    exit 0
+fi
+
+encoded_preview="$(awk -F '\t' -v idx="${idx}" '($1==idx){print $2; exit}' "${previews_file}" || true)"
+
+if [[ -z "${encoded_preview}" ]]; then
+    exit 0
+fi
+
+preview_content="$(printf '%s' "${encoded_preview}" | base64 --decode)"
+
+preview_ext_from_row="$(awk -F '\t' -v idx="${idx}" '($1==idx){print $3; exit}' "${previews_file}" || true)"
+preview_ext="${MCFG_PREVIEW_EXT:-${preview_ext_from_row}}"
+preview_width="${MCFG_PREVIEW_WIDTH:-}"
+preview_size_pct="${MCFG_PREVIEW_SIZE_PCT:-}"
+
+if [[ -z "${preview_width}" && -n "${COLUMNS:-}" ]]; then
+    if [[ "${preview_size_pct}" =~ ^[0-9]+$ ]]; then
+        preview_width=$((COLUMNS * preview_size_pct / 100))
+    else
+        preview_width="${COLUMNS}"
+    fi
+fi
+
+if command -v bat >/dev/null 2>&1; then
+    bat_args=(--force-colorization --style=plain --paging=never --wrap=character)
+    if [[ -n "${preview_ext}" ]]; then
+        bat_args+=(--language "${preview_ext}")
+    fi
+    if [[ "${preview_width}" =~ ^[0-9]+$ ]]; then
+        bat_args+=(--terminal-width "${preview_width}")
+    fi
+    printf '%s' "${preview_content}" | bat "${bat_args[@]}"
+elif command -v glow >/dev/null 2>&1; then
+    printf '%s' "${preview_content}" | glow -
+elif command -v fold >/dev/null 2>&1 && [[ "${preview_width}" =~ ^[0-9]+$ ]]; then
+    printf '%s' "${preview_content}" | fold -s -w "${preview_width}"
+else
+    printf '%s' "${preview_content}"
+fi
+""",
+            encoding="utf-8"
+        )
+        preview_script.chmod(0o755)
+        preview_env: dict[str, str] = {
+            "BAT_THEME": "ansi",
+            "MCFG_PREVIEW_SIZE_PCT": str(preview_panel_size),
+        }
+        if normalized_extension is not None:
+            preview_env["MCFG_PREVIEW_EXT"] = normalized_extension
+        if preview_width > 0:
+            preview_env["MCFG_PREVIEW_WIDTH"] = str(preview_width)
+        preview_env_line = _toml_inline_table(preview_env)
+        channel_config = f"""[metadata]
+name = "temp_options"
+description = "Temporary channel for selecting options"
+
+[source]
+command = "bat '{entries_path}'"
+display = "{{split:\\t:1}}"
+output = "{{split:\\t:0}}"
+
+[preview]
+command = "{preview_script} {{split:\\t:0}}"
+{preview_env_line}
+
+[ui.preview_panel]
+size = {preview_panel_size}
+"""
+        channel_path = tempdir / "temp_options.toml"
+        channel_path.write_text(channel_config, encoding="utf-8")
+        env = os.environ.copy()
+        tv_config_dir = pathlib.Path.home() / ".config" / "television"
+        if not tv_config_dir.exists():
+            tv_config_dir = pathlib.Path(os.getenv("XDG_CONFIG_HOME", str(pathlib.Path.home() / ".config"))) / "television"
+        cable_dir = tv_config_dir / "cable"
+        cable_dir.mkdir(parents=True, exist_ok=True)
+        temp_channel_link = cable_dir / "temp_options.toml"
+        if temp_channel_link.exists() or temp_channel_link.is_symlink():
+            temp_channel_link.unlink()
+        temp_channel_link.symlink_to(channel_path)
+        output_file = tempdir / "selection.txt"
+        try:
+            result = subprocess.run(["tv", "temp_options"], check=False, stdout=output_file.open("w"), text=True, env=env)
+        finally:
+            if temp_channel_link.exists() or temp_channel_link.is_symlink():
+                temp_channel_link.unlink()
+        if result.returncode not in (0, 130):
+            raise SystemExit(result.returncode)
+        if result.returncode == 130:
+            return [] if multi else None
+        if not output_file.exists():
+            return [] if multi else None
+        selected_lines = [line.strip() for line in output_file.read_text().splitlines() if line.strip()]
+        if not selected_lines:
+            return [] if multi else None
+        selected_keys: list[str] = []
+        for line in selected_lines:
+            try:
+                index = int(line)
+                key = index_map.get(index)
+                if key is not None:
+                    selected_keys.append(key)
+            except ValueError:
+                continue
+        if multi:
+            return selected_keys
+        return selected_keys[0] if selected_keys else None
+
+
+if __name__ == "__main__":
+    demo_mapping: dict[str, str] = {
+        "Option 1": "# Option 1\nThis is the preview for option 1.",
+        "Option 2": "# Option 2\nThis is the preview for option 2.",
+        "Option 3": "# Option 3\nThis is the preview for option 3."
+    }
+    result = select_from_options(demo_mapping, multi=True, extension="md", preview_size_percent=50)
+    print(f"Selected: {result}")

machineconfig/utils/options_utils/options_tv_windows.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+import pathlib
+import pprint
+import shutil
+from typing import Any, Literal, Union, overload
+
+
+def _format_preview_value(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return pprint.pformat(value, width=88, sort_dicts=True)
+
+
+def _normalize_extension(extension: str | None) -> str | None:
+    if extension is None:
+        return None
+    trimmed = extension.strip()
+    if trimmed.startswith("."):
+        trimmed = trimmed[1:]
+    if not trimmed:
+        return None
+    return trimmed
+
+
+@overload
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[True], preview_size_percent: float) -> list[str]: ...
+@overload
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[False], preview_size_percent: float) -> str | None: ...
+def select_from_options(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: bool, preview_size_percent: float) -> Union[list[str], Union[str, None]]:
+    keys = list(options_to_preview_mapping.keys())
+    if not keys:
+        return [] if multi else None
+    normalized_extension = _normalize_extension(extension)
+    preview_panel_size = max(10, min(90, int(preview_size_percent)))
+    from machineconfig.utils.accessories import randstr
+    tempdir = pathlib.Path.home() / "tmp_results" / "tmp_files" / f"tv_channel_{randstr(6)}"
+    tempdir.mkdir(parents=True, exist_ok=True)
+    try:
+        index_map: dict[str, str] = {}
+        ext_for_preview = normalized_extension or "txt"
+        entries_lines: list[str] = []
+        for idx, key in enumerate(keys):
+            display_key = key.replace("\n", " ")
+            entries_lines.append(f"{idx}|{display_key}")
+            index_map[str(idx)] = key
+            preview_value = _format_preview_value(options_to_preview_mapping[key])
+            preview_file = tempdir / f"{idx}.{ext_for_preview}"
+            preview_file.write_text(preview_value, encoding="utf-8")
+        entries_path = tempdir / "entries.txt"
+        entries_path.write_text("\n".join(entries_lines), encoding="utf-8")
+        output_file = tempdir / "selection.txt"
+        tempdir_fwd = str(tempdir).replace("\\", "/")
+        source_cmd = f"cmd /C type \"{entries_path}\""
+        preview_cmd = f"bat --force-colorization --style=plain --paging=never {tempdir_fwd}/{{split:|:0}}.{ext_for_preview}"
+        tv_cmd = f'''$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+tv --ansi --source-command '{source_cmd}' --source-display '{{split:|:1}}' --source-output '{{split:|:0}}' --preview-command '{preview_cmd}' --preview-size {preview_panel_size} --no-remote | Out-File -Encoding utf8 -FilePath "{output_file}"
+'''
+        from machineconfig.utils.code import run_shell_script
+        result = run_shell_script(tv_cmd, display_script=False, clean_env=False)
+        if result.returncode not in (0, 130) and not output_file.exists():
+            raise SystemExit(result.returncode)
+        if result.returncode == 130:
+            return [] if multi else None
+        if not output_file.exists():
+            return [] if multi else None
+        selected_lines = [line.strip() for line in output_file.read_text(encoding="utf-8-sig").splitlines() if line.strip()]
+        if not selected_lines:
+            return [] if multi else None
+        selected_keys: list[str] = []
+        for line in selected_lines:
+            key = index_map.get(line)
+            if key is not None:
+                selected_keys.append(key)
+        if multi:
+            return selected_keys
+        return selected_keys[0] if selected_keys else None
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    demo_mapping: dict[str, str] = {
+        "Option 1": "# Option 1\nThis is the preview for option 1.",
+        "Option 2": "# Option 2\nThis is the preview for option 2.",
+        "Option 3": "# Option 3\nThis is the preview for option 3."
+    }
+    result = select_from_options(demo_mapping, multi=True, extension="md", preview_size_percent=50)
+    print(f"Selected: {result}")

machineconfig/utils/options_utils/tv_options.py

@@ -0,0 +1,37 @@
+from typing import Any, Literal, overload
+import platform
+
+
+@overload
+def choose_from_dict_with_preview(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[False], preview_size_percent: float) -> str | None: ...
+@overload
+def choose_from_dict_with_preview(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: Literal[True], preview_size_percent: float) -> list[str]: ...
+def choose_from_dict_with_preview(options_to_preview_mapping: dict[str, Any], extension: str | None, multi: bool, preview_size_percent: float) -> str | list[str] | None:
+    if not options_to_preview_mapping:
+        return [] if multi else None
+    system = platform.system()
+    if system == "Windows":
+        from machineconfig.utils.options_utils.options_tv_windows import select_from_options
+        return select_from_options(options_to_preview_mapping, extension=extension, multi=multi, preview_size_percent=preview_size_percent)
+    else:
+        from machineconfig.utils.options_utils.options_tv_linux import select_from_options
+        return select_from_options(options_to_preview_mapping, extension=extension, multi=multi, preview_size_percent=preview_size_percent)
+
+
+if __name__ == "__main__":
+    demo_mapping: dict[str, str] = {
+        "config.py": """from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config"
+DEBUG = True
+""",
+        "utils.py": """def greet(name: str) -> str:
+    return f"Hello, {name}!"
+""",
+        "main.rs": """fn main() {
+    println!("Hello, world!");
+}
+""",
+    }
+    result = choose_from_dict_with_preview(demo_mapping, extension="py", multi=True, preview_size_percent=50)
+    print(f"Selected: {result}")