machineconfig 7.98__py3-none-any.whl → 8.61__py3-none-any.whl

machineconfig/scripts/python/msearch.py

@@ -1,71 +1,26 @@
+"""msearch - Machineconfig search helper."""
 
 import typer
 from typing import Annotated
 
 
 def machineconfig_search(
-        directory: Annotated[str, typer.Option(..., "--directory", "-d", help="The directory to search")] = ".",
-        ast: Annotated[bool, typer.Option(..., "--ast", "-a", help="The abstract syntax tree search/ tree sitter search of symbols")] = False,
-        symantic: Annotated[bool, typer.Option(..., "--symantic", "-s", help="The symantic search of symbols")] = False,
-        extension: Annotated[str, typer.Option(..., "--extension", "-e", help="File extension to filter by (e.g., .py, .js)")] = "",
-        file: Annotated[bool, typer.Option(..., "--file", "-f", help="File search using fzf")] = False,
-        no_dotfiles: Annotated[bool, typer.Option(..., "--no-dotfiles", "-D", help="Exclude dotfiles from search")] = False,
-        rga: Annotated[bool, typer.Option(..., "--rga", "-a", help="Use ripgrep-all for searching instead of ripgrep")] = False,
-        install_dependencies: Annotated[bool, typer.Option(..., "--install-dependencies", "-p", help="Install required dependencies if missing")] = False
-        ):
-    if install_dependencies:
-        from machineconfig.utils.installer_utils.installer_cli import install_if_missing
-        install_if_missing("fzf")
-        install_if_missing("tv")
-        install_if_missing("bat")
-        install_if_missing("fd")
-        install_if_missing("rg")  # ripgrep
-        install_if_missing("rga")  # ripgrep-all
-        # install_if_missing("tree-sitter-cli")
-        return
-    if symantic:
-        script = ""
-        for an_ex in extension.split(","):
-            script = script + f"""\nparse *.{an_ex} """
-        from machineconfig.utils.code import run_shell_script
-        run_shell_script(script=script)
-        return
-    if ast:
-        from machineconfig.scripts.python.helpers.ast_search import get_repo_symbols
-        symbols = get_repo_symbols(directory)
-        from machineconfig.utils.options import choose_from_options
-        try:
-            res = choose_from_options(options=symbols, msg="Select a symbol to search for:", tv=True, multi=False)
-            from rich import print_json
-            import json
-            res_json = json.dumps(res, indent=4)
-            print_json(res_json)
-            return None
-        except Exception as e:
-            print(f"❌ Error during selection: {e}")
-            return None
-    if file:
-        script = """fzf --ansi --preview-window 'right:60%' --preview 'bat --color=always --style=numbers,grid,header --line-range :300 {}' """
-        if no_dotfiles:
-            script = "fd | " + script
-        from machineconfig.utils.code import run_shell_script
-        run_shell_script(script=script)
-        return
-    from machineconfig.scripts.python.helpers_msearch import FZFG_LINUX_PATH, FZFG_WINDOWS_PATH
-    import platform
-    if platform.system() == "Linux" or platform.system() == "Darwin":
-        script = FZFG_LINUX_PATH.read_text(encoding="utf-8")
-    elif platform.system() == "Windows":
-        script = FZFG_WINDOWS_PATH.read_text(encoding="utf-8")
-    else:
-        raise RuntimeError("Unsupported platform")
-    if rga:
-        script = script.replace("rg ", "rga ").replace("ripgrep", "ripgrep-all")
-    from machineconfig.utils.code import exit_then_run_shell_script
-    exit_then_run_shell_script(script=script, strict=False)
+    path: Annotated[str, typer.Argument(help="The directory/file to search")] = ".",
+    ast: Annotated[bool, typer.Option(..., "--ast", "-a", help="The abstract syntax tree search/ tree sitter search of symbols")] = False,
+    symantic: Annotated[bool, typer.Option(..., "--symantic", "-s", help="The symantic search of symbols")] = False,
+    extension: Annotated[str, typer.Option(..., "--extension", "-E", help="File extension to filter by (e.g., .py, .js)")] = "",
+    file: Annotated[bool, typer.Option(..., "--file", "-f", help="File search using fzf")] = False,
+    no_dotfiles: Annotated[bool, typer.Option(..., "--no-dotfiles", "-D", help="Exclude dotfiles from search")] = False,
+    rga: Annotated[bool, typer.Option(..., "--rga", "-A", help="Use ripgrep-all for searching all (non text files) instead of ripgrep")] = False,
+    edit: Annotated[bool, typer.Option(..., "--edit", "-e", help="Open selection in editor (helix)")] = False,
+    install_dependencies: Annotated[bool, typer.Option(..., "--install-req", "-i", help="Install required dependencies if missing")] = False,
+) -> None:
+    """Machineconfig search helper."""
+    from machineconfig.scripts.python.helpers.helpers_msearch.msearch_impl import machineconfig_search as impl
+    impl(path=path, ast=ast, symantic=symantic, extension=extension, file=file, no_dotfiles=no_dotfiles, rga=rga, edit=edit, install_dependencies=install_dependencies)
 
 
-def main():
+def main() -> None:
     app = typer.Typer(add_completion=False, no_args_is_help=True)
-    app.command(name="msearch", help="machineconfig search helper", no_args_is_help=False)(machineconfig_search)
+    app.command(name="msearch", help=machineconfig_search.__doc__, short_help="machineconfig search helper", no_args_is_help=False)(machineconfig_search)
     app()

machineconfig/scripts/python/sessions.py

@@ -1,221 +1,167 @@
+"""Sessions management commands - lazy loading subcommands."""
 
 from typing import Optional, Literal, Annotated
 import typer
 
 
-def balance_load(layout_path: Annotated[str, typer.Argument(..., help="Path to the layout.json file")],
-           max_thresh: Annotated[int, typer.Option(..., "--max-threshold", "-m", help="Maximum tabs per layout")],
-           thresh_type: Annotated[Literal['number', 'n', 'weight', 'w'], typer.Option(..., "--threshold-type", "-t", help="Threshold type")],
-           breaking_method: Annotated[Literal['moreLayouts', 'ml', 'combineTabs', 'ct'], typer.Option(..., "--breaking-method", "-b", help="Breaking method")],
-           output_path: Annotated[Optional[str], typer.Option(..., "--output-path", "-o", help="Path to write the adjusted layout.json file")] = None):
+def balance_load(
+    layout_path: Annotated[str, typer.Argument(..., help="Path to the layout.json file")],
+    max_thresh: Annotated[int, typer.Option(..., "--max-threshold", "-m", help="Maximum tabs per layout")],
+    thresh_type: Annotated[Literal["number", "n", "weight", "w"], typer.Option(..., "--threshold-type", "-t", help="Threshold type")],
+    breaking_method: Annotated[Literal["moreLayouts", "ml", "combineTabs", "ct"], typer.Option(..., "--breaking-method", "-b", help="Breaking method")],
+    output_path: Annotated[Optional[str], typer.Option(..., "--output-path", "-o", help="Path to write the adjusted layout.json file")] = None,
+) -> None:
     """Adjust layout file to limit max tabs per layout, etc."""
-    thresh_type_resolved: dict[str, Literal['number', 'weight']] = {
-        'number': 'number',
-        'n': 'number',
-        'weight': 'weight',
-        'w': 'weight'
-    }
-    breaking_method_resolved: dict[str, Literal['moreLayouts', 'combineTabs']] = {
-        'moreLayouts': 'moreLayouts',
-        'ml': 'moreLayouts',
-        'combineTabs': 'combineTabs',
-        'ct': 'combineTabs'
-    }
-    from pathlib import Path
-    layout_path_obj = Path(layout_path).expanduser().absolute()
-
-    from machineconfig.utils.schemas.layouts.layout_types import LayoutsFile
-    import json
-    layoutfile: LayoutsFile = json.loads(layout_path_obj.read_text())
-    layout_configs = layoutfile["layouts"]
-    from machineconfig.cluster.sessions_managers.utils.load_balancer import limit_tab_num
-    new_layouts = limit_tab_num(layout_configs=layout_configs, max_thresh=max_thresh, threshold_type=thresh_type_resolved[thresh_type], breaking_method=breaking_method_resolved[breaking_method])
-    layoutfile["layouts"] = new_layouts
-    target_file = Path(output_path) if output_path is not None else layout_path_obj.parent / f'{layout_path_obj.stem}_adjusted_{max_thresh}_{thresh_type}_{breaking_method}.json'
-    target_file.parent.mkdir(parents=True, exist_ok=True)
-    target_file.write_text(data=json.dumps(layoutfile, indent=4), encoding="utf-8")
-    typer.echo(f"Adjusted layout saved to {target_file}")
-
-
-def select_layout(layouts_json_file: str, selected_layouts_names: Optional[list[str]], select_interactively: bool,
-                  subsitute_home: bool
-                  ) -> list["LayoutConfig"]:
-    import json
-    from machineconfig.utils.options import choose_from_options
-    from machineconfig.utils.schemas.layouts.layout_types import LayoutsFile
-    from pathlib import Path
-    json_str = Path(layouts_json_file).read_text(encoding="utf-8")
-    if subsitute_home:
-        json_str = json_str.replace("~", str(Path.home())).replace("$HOME", str(Path.home()))
-        json_str = json_str.replace("""Command": "f """, """Command": "~/.config/machineconfig/scripts/wrap_mcfg fire """)
-        json_str = json_str.replace("""Command": "s """, """Command": "~/.config/machineconfig/scripts/wrap_mcfg sessions """)
-
-    layout_file: LayoutsFile = json.loads(json_str)
-    if len(layout_file["layouts"]) == 0:
-        raise ValueError(f"No layouts found in {layouts_json_file}")
-    if selected_layouts_names is None:  # choose all, or interactively
-        if not select_interactively:
-            return layout_file["layouts"]
-        options = [layout["layoutName"] for layout in layout_file["layouts"]]
-        from machineconfig.utils.options import choose_from_options
-        selected_layouts_names = choose_from_options(multi=True, options=options, prompt="Choose a layout configuration:", tv=True, msg="Choose one option")
-    print(f"Selected layout(s): {selected_layouts_names}")
-    # Extract the configs from the names:
-    layouts_chosen: list[LayoutConfig] = []
-    for name in selected_layouts_names:
-        layout_chosen = next((layout for layout in layout_file["layouts"] if layout["layoutName"] == name), None)
-        if layout_chosen is None:
-            layout_chosen = next((layout for layout in layout_file["layouts"] if layout["layoutName"].lower() == name.lower()), None)
-        if layout_chosen is None:
-            available_layouts = [layout["layoutName"] for layout in layout_file["layouts"]]
-            raise ValueError(f"Layout '{name}' not found. Available layouts: {available_layouts}")
-        layouts_chosen.append(layout_chosen)
-    return layouts_chosen
-
-
-def find_layout_file(layout_path: str, ) -> str:
-    from machineconfig.utils.path_helper import search_for_files_of_interest
-    from machineconfig.utils.options import choose_from_options
-    from machineconfig.utils.path_helper import match_file_name, sanitize_path
+    from machineconfig.scripts.python.helpers.helpers_sessions.utils import balance_load as impl
+    impl(layout_path=layout_path, max_thresh=max_thresh, thresh_type=thresh_type, breaking_method=breaking_method, output_path=output_path)
+
+
+def run(
+    ctx: typer.Context,
+    layouts_file: Annotated[Optional[str], typer.Option(..., "--layouts-file", "-f", help="Path to the layout.json file")] = None,
+    choose: Annotated[Optional[str], typer.Option(..., "--choose", "-c", help="Comma separated names of layouts to be selected from the layout file passed")] = None,
+    choose_interactively: Annotated[bool, typer.Option(..., "--choose-interactively", "-i", help="Select layouts interactively")] = False,
+
+    sleep_inbetween: Annotated[float, typer.Option(..., "--sleep-inbetween", "-si", help="Sleep time in seconds between launching layouts")] = 1.0,
+    monitor: Annotated[bool, typer.Option(..., "--monitor", "-m", help="Monitor the layout sessions for completion")] = False,
+    sequential: Annotated[bool, typer.Option(..., "--sequential", "-s", help="Launch layouts sequentially")] = False,
+    kill_upon_completion: Annotated[bool, typer.Option(..., "--kill-upon-completion", "-k", help="Kill session(s) upon completion (only relevant if monitor flag is set)")] = False,
+    subsitute_home: Annotated[bool, typer.Option(..., "--substitute-home", "-sh", help="Substitute ~ and $HOME in layout file with actual home directory path")] = False,
+    max_tabs: Annotated[int, typer.Option(..., "--max-tabs", "-mt", help="A Sanity checker that throws an error if any layout exceeds the maximum number of tabs to launch.")] = 25,
+    max_layouts: Annotated[int, typer.Option(..., "--max-layouts", "-ml", help="A Sanity checker that throws an error if the total number of *parallel layouts exceeds this number.")] = 25,
+    backend: Annotated[Literal["zellij", "z", "windows-terminal", "wt", "auto", "a"], typer.Option(..., "--backend", "-b", help="Backend terminal multiplexer or emulator to use")] = "auto",
+) -> None:
+    """Launch terminal sessions based on a layout configuration file."""
+    from machineconfig.scripts.python.helpers.helpers_sessions.sessions_impl import run_layouts, find_layout_file, select_layout
+
     from pathlib import Path
-    path_obj = sanitize_path(layout_path)
-    if not path_obj.exists():
-        choice_file = match_file_name(sub_string=layout_path, search_root=Path.cwd(), suffixes={".json"})
-    elif path_obj.is_dir():
-        print(f"🔍 Searching recursively for Python, PowerShell and Shell scripts in directory `{path_obj}`")
-        files = search_for_files_of_interest(path_obj, suffixes={".py", ".sh", ".ps1"})
-        print(f"🔍 Got #{len(files)} results.")
-        choice_file = choose_from_options(multi=False, options=files, tv=True, msg="Choose one option")
-        choice_file = Path(choice_file).expanduser().absolute()
+    if layouts_file is not None:
+        layouts_file_resolved = Path(find_layout_file(layout_path=layouts_file))
     else:
-        choice_file = path_obj
-    return str(choice_file)
-
-
-def run(ctx: typer.Context,
-           layout_path: Annotated[Optional[str], typer.Argument(..., help="Path to the layout.json file")] = None,
-        max_tabs: Annotated[int, typer.Option(..., "--max-tabs", "-mt", help="A Sanity checker that throws an error if any layout exceeds the maximum number of tabs to launch.")] = 10,
-        max_layouts: Annotated[int, typer.Option(..., "--max-layouts", "-ml", help="A Sanity checker that throws an error if the total number of *parallel layouts exceeds this number.")] = 10,
-        sleep_inbetween: Annotated[float, typer.Option(..., "--sleep-inbetween", "-si", help="Sleep time in seconds between launching layouts")] = 1.0,
-        monitor: Annotated[bool, typer.Option(..., "--monitor", "-m", help="Monitor the layout sessions for completion")] = False,
-        parallel: Annotated[bool, typer.Option(..., "--parallel", "-p", help="Launch multiple layouts in parallel")] = False,
-        kill_upon_completion: Annotated[bool, typer.Option(..., "--kill-upon-completion", "-k", help="Kill session(s) upon completion (only relevant if monitor flag is set)")] = False,
-        choose: Annotated[Optional[str], typer.Option(..., "--choose", "-c", help="Comma separated names of layouts to be selected from the layout file passed")] = None,
-        choose_interactively: Annotated[bool, typer.Option(..., "--choose-interactively", "-i", help="Select layouts interactively")] = False,
-        subsitute_home: Annotated[bool, typer.Option(..., "--substitute-home", "-sh", help="Substitute ~ and $HOME in layout file with actual home directory path")] = False,
-        ):
-    """
-    Launch terminal sessions based on a layout configuration file.
-    """
-    if layout_path is None:
+        layouts_file_resolved = Path.home().joinpath("dotfiles/machineconfig/layouts.json")
+    if not layouts_file_resolved.exists():
         typer.echo(ctx.get_help())
-        raise typer.Exit()
-    layout_path_resolved = find_layout_file(layout_path=layout_path)
-    layouts_selected = select_layout(layouts_json_file=layout_path_resolved, selected_layouts_names=choose.split(",") if choose else None, select_interactively=choose_interactively, subsitute_home=subsitute_home)
+        typer.echo(f"❌ Layouts file not found: {layouts_file_resolved}", err=True)
+        raise typer.Exit(code=1)
+
+    if choose is None: layouts_names_resolved: list[str] = []
+    else: layouts_names_resolved = [name.strip() for name in choose.split(",") if name.strip()]
+    layouts_selected = select_layout(layouts_json_file=str(layouts_file_resolved), selected_layouts_names=layouts_names_resolved,
+                    select_interactively=choose_interactively,)
+    if subsitute_home:
+        from machineconfig.utils.schemas.layouts.layout_types import substitute_home, LayoutConfig
+        layouts_modified: list["LayoutConfig"] = []
+        for a_layout in layouts_selected:
+            a_layout["layoutTabs"] = substitute_home(tabs=a_layout["layoutTabs"])
+            layouts_modified.append(a_layout)
+        layouts_selected = layouts_modified
 
-    # ============= Basic sanity checks =============
-    if parallel and len(layouts_selected) > max_layouts:
+    import platform
+    backend_resolved: Literal["zellij", "windows-terminal"]
+    match backend:
+        case "windows-terminal" | "wt":
+            if platform.system().lower() != "windows":
+                typer.echo("Error: Windows Terminal layouts can only be started on Windows systems.", err=True)
+                raise typer.Exit(code=1)
+            backend_resolved = "windows-terminal"
+        case "zellij" | "z":
+            if platform.system().lower() == "windows":
+                typer.echo("Error: Zellij is not supported on Windows.", err=True)
+                raise typer.Exit(code=1)
+            backend_resolved = "zellij"
+        case "auto" | "a":
+            if platform.system().lower() == "windows":
+                backend_resolved = "windows-terminal"
+            else:
+                backend_resolved = "zellij"
+        case _:
+            typer.echo(f"Error: Unsupported backend '{backend}'.", err=True)
+            raise typer.Exit(code=1)
+
+    if not sequential and len(layouts_selected) > max_layouts:
         raise ValueError(f"Number of layouts {len(layouts_selected)} exceeds the maximum allowed {max_layouts}. Please adjust your layout file.")
     for a_layout in layouts_selected:
         if len(a_layout["layoutTabs"]) > max_tabs:
-            typer.echo(f"Layout '{a_layout.get('layoutName', 'Unnamed')}' has {len(a_layout['layoutTabs'])} tabs which exceeds the max of {max_tabs}.")
-            confirm = typer.confirm("Do you want to proceed with launching this layout?", default=False)
-            if not confirm:
-                typer.echo("Aborting launch.")
-                raise typer.Exit(0)
-    import time
+            raise ValueError(f"Layout '{a_layout.get('layoutName', 'Unnamed')}' has {len(a_layout['layoutTabs'])} tabs which exceeds the max of {max_tabs}.")
+
+    try:
+        run_layouts(
+        sleep_inbetween=sleep_inbetween, monitor=monitor, sequential=sequential, kill_upon_completion=kill_upon_completion,
+        layouts_selected=layouts_selected,
+        backend=backend_resolved)
+    except ValueError as e:
+        typer.echo(str(e))
+        raise typer.Exit(1) from e
+
+
+def attach_to_session(
+        name: Annotated[str | None, typer.Argument(help="Name of the Zellij session to attach to. If not provided, a list will be shown to choose from.")] = None,
+        new_session: Annotated[bool, typer.Option("--new-session", "-n", help="Create a new Zellij session instead of attaching to an existing one.", show_default=True)] = False,
+        kill_all: Annotated[bool, typer.Option("--kill-all", "-k", help="Kill all existing Zellij sessions before creating a new one.", show_default=True)] = False) -> None:
+    """Choose a Zellij session to attach to."""
     import platform
-    if platform.system() == "Linux" or platform.system() == "Darwin":
-        from machineconfig.cluster.sessions_managers.zellij_local_manager import ZellijLocalManager
-        if not parallel: iterable = [[item] for item in layouts_selected]
-        else: iterable = [layouts_selected]
-        for i, a_layouts in enumerate(iterable):
-            manager = ZellijLocalManager(session_layouts=a_layouts)
-            manager.start_all_sessions(poll_interval=2, poll_seconds=2)
-            if monitor:
-                manager.run_monitoring_routine(wait_ms=2000)
-                if kill_upon_completion:
-                    manager.kill_all_sessions()
-            if i < len(layouts_selected) - 1:  # Don't sleep after the last layout
-                time.sleep(sleep_inbetween)
-    elif platform.system() == "Windows":
-        from machineconfig.cluster.sessions_managers.wt_local_manager import WTLocalManager
-        if not parallel: iterable = [[item] for item in layouts_selected]
-        else: iterable = [layouts_selected]
-        for i, a_layouts in enumerate(iterable):
-            manager = WTLocalManager(session_layouts=a_layouts)
-            manager.start_all_sessions()
-            if monitor:
-                manager.run_monitoring_routine(wait_ms=2000)
-                if kill_upon_completion:
-                    manager.kill_all_sessions()
-            if i < len(layouts_selected) - 1:  # Don't sleep after the last layout
-                time.sleep(sleep_inbetween)
-    else:
-        print(f"❌ Unsupported platform: {platform.system()}")
+    if platform.system().lower() == "windows":
+        typer.echo("Error: Zellij is not supported on Windows.", err=True, color=True)
+        raise typer.Exit()
+    from machineconfig.scripts.python.helpers.helpers_sessions.attach_impl import choose_zellij_session as impl
+    action, payload = impl(name=name, new_session=new_session, kill_all=kill_all)
+    if action == "error":
+        typer.echo(payload, err=True, color=True)
+        raise typer.Exit()
+    if action == "run_script" and payload:
+        from machineconfig.utils.code import exit_then_run_shell_script
+        exit_then_run_shell_script(script= payload, strict=True)
+
+
+
+def get_session_tabs() -> list[tuple[str, str]]:
+    """Get all Zellij session tabs."""
+    from machineconfig.scripts.python.helpers.helpers_sessions.attach_impl import get_session_tabs as impl
+    result = impl()
+    print(result)
+    return result
+def create_template(
+    name: Annotated[Optional[str], typer.Argument(..., help="Name of the layout template to create")] = None,
+    num_tabs: Annotated[int, typer.Option(..., "--num-tabs", "-t", help="Number of tabs to include in the template")] = 3,
+) -> None:
+    """Create a layout template file."""
+    from machineconfig.scripts.python.helpers.helpers_sessions.utils import create_template as impl
+    impl(name=name, num_tabs=num_tabs)
 
+def create_from_function(
+    num_process: Annotated[int, typer.Option(..., "--num-process", "-n", help="Number of parallel processes to run")],
+    path: Annotated[str, typer.Option(..., "--path", "-p", help="Path to a Python or Shell script file or a directory containing such files")] = ".",
+    function: Annotated[Optional[str], typer.Option(..., "--function", "-f", help="Function to run from the Python file. If not provided, you will be prompted to choose.")] = None,
+) -> None:
+    """Create a layout from a function to run in multiple processes."""
+    from machineconfig.scripts.python.helpers.helpers_sessions.sessions_multiprocess import create_from_function as impl
+    impl(num_process=num_process, path=path, function=function)
 
-def create_template(name: Annotated[Optional[str], typer.Argument(..., help="Name of the layout template to create")] = None,
-                    num_tabs: Annotated[int, typer.Option(..., "--num-tabs", "-t", help="Number of tabs to include in the template")] = 3,
-                    ):
-    """Create a layout template file."""
-    from machineconfig.utils.schemas.layouts.layout_types import LayoutsFile, TabConfig
-    from pathlib import Path
-    tabs: list[TabConfig] = []
-    for i in range(1, num_tabs + 1):
-        tab: TabConfig = {
-            "tabName": f"Tab{i}",
-            "startDir": "~/" + str(Path.cwd().relative_to(Path.home())),
-            "command": "bash",
-        }
-        tabs.append(tab)
-    layouts: list[LayoutConfig] = [
-        {
-            "layoutName": f"{Path.cwd().name}Layout",
-            "layoutTabs": tabs,
-        }
-    ]
-    file: LayoutsFile = {
-        "$schema": "https://bit.ly/cfglayout",  # type: ignore
-        "version": "0.1",
-        "layouts": layouts
-    }
-    import json
-    json_string = json.dumps(file, indent=4)
-    if name is None:
-        layout_path = Path.cwd() / "layout.json"
-    else:
-        layout_path = Path.cwd() / (name.replace(".json", "") + ".json")
-    layout_path.parent.mkdir(parents=True, exist_ok=True)
-    if layout_path.exists():
-        print(f"❌ File {layout_path} already exists. Aborting to avoid overwriting.")
-        return
-    layout_path.write_text(json_string, encoding="utf-8")
-    print(f"✅ Created layout template at {layout_path}")
 
+def get_app() -> typer.Typer:
+    layouts_app = typer.Typer(help="Layouts management subcommands", no_args_is_help=True, add_help_option=True, add_completion=False)
 
-def get_app():
-    layouts_app = typer.Typer(help="Layouts management subcommands", no_args_is_help=True, add_help_option=False, add_completion=False)
-    from machineconfig.scripts.python.helpers_sessions.sessions_multiprocess import create_from_function
+    layouts_app.command("run", no_args_is_help=True, help=run.__doc__, short_help="[r] Run the selected layout(s)")(run)
+    layouts_app.command("r", no_args_is_help=True, help=run.__doc__, hidden=True)(run)
 
-    layouts_app.command("create-from-function", no_args_is_help=True, help="[c] Create a layout from a function")(create_from_function)
-    layouts_app.command("c", no_args_is_help=True, help="Create a layout from a function", hidden=True)(create_from_function)
+    layouts_app.command("attach", no_args_is_help=False, help=attach_to_session.__doc__, short_help="[a] Attach to a Zellij session")(attach_to_session)
+    layouts_app.command("a", no_args_is_help=False, help=attach_to_session.__doc__, hidden=True)(attach_to_session)
 
-    layouts_app.command("run", no_args_is_help=True, help="[r] Run the selected layout(s)")(run)
-    layouts_app.command("r", no_args_is_help=True, help="Run the selected layout(s)", hidden=True)(run)
+    layouts_app.command("create-from-function", no_args_is_help=True, short_help="[c] Create a layout from a function")(create_from_function)
+    layouts_app.command("c", no_args_is_help=True, hidden=True)(create_from_function)
 
-    layouts_app.command("balance-load", no_args_is_help=True, help="[b] Balance the load across sessions")(balance_load)
-    layouts_app.command("b", no_args_is_help=True, help="Balance the load across sessions", hidden=True)(balance_load)
+    layouts_app.command("balance-load", no_args_is_help=True, help=balance_load.__doc__, short_help="[b] Balance the load across sessions")(balance_load)
+    layouts_app.command("b", no_args_is_help=True, help=balance_load.__doc__, hidden=True)(balance_load)
 
-    layouts_app.command("create-template", no_args_is_help=False, help="[t] Create a layout template file")(create_template)
-    layouts_app.command("t", no_args_is_help=False, help="Create a layout template file", hidden=True)(create_template)
+    layouts_app.command("create-template", no_args_is_help=False, help=create_template.__doc__, short_help="[t] Create a layout template file")(create_template)
+    layouts_app.command("t", no_args_is_help=False, help=create_template.__doc__, hidden=True)(create_template)
     return layouts_app
 
 
-def main():
+def main() -> None:
     layouts_app = get_app()
     layouts_app()
 
 
 if __name__ == "__main__":
-    from machineconfig.utils.schemas.layouts.layout_types import LayoutConfig
+    pass

machineconfig/scripts/python/utils.py

@@ -1,38 +1,120 @@
-from machineconfig.scripts.python.helpers_devops.cli_utils import merge_pdfs, compress_pdf
-from machineconfig.scripts.python.helpers_utils.path import edit_file_with_hx, get_machine_specs, init_project, tui_env
-from machineconfig.scripts.python.helpers_utils.download import download
+"""Utility commands - lazy loading subcommands."""
+
 import typer
-from typing import Annotated
+from typing import Annotated, Optional, Literal
 
 
-def kill_process(
-        # name: Annotated[Optional[str], typer.Option(..., "--name", "-n", help="Name of the process to kill")],
-                #  command: Annotated[str, typer.Option(..., "--command", "-c", help="Match by command line instead of process name")] = "",
-                 interactive: Annotated[bool, typer.Option(..., "--interactive", "-i", help="Interactively choose the process to kill")] = True):
-    from machineconfig.utils.procs import main, ProcessManager
+def kill_process(interactive: Annotated[bool, typer.Option(..., "--interactive", "-i", help="Interactively choose the process to kill")] = True) -> None:
+    """⚔️ Choose a process to kill."""
+    from machineconfig.utils.procs import ProcessManager
     if interactive:
-        main()
+        proc = ProcessManager()
+        proc.choose_and_kill()
         return
     _ = ProcessManager
-    # pm = ProcessManager()
-    # if command:
-    #     pm.filter_and_kill(name=command
-                        #    )
 
 
-def upgrade_packages():
+def upgrade_packages(root: Annotated[str, typer.Argument(help="Root directory of the project")] = ".") -> None:
+    """⬆️ Upgrade project dependencies."""
     from machineconfig.utils.upgrade_packages import generate_uv_add_commands
     from pathlib import Path
-    generate_uv_add_commands(pyproject_path=Path.cwd() / "pyproject.toml", output_path=Path.cwd() / "pyproject_init.sh")
+    root_resolved = Path(root).expanduser().absolute().resolve()
+    generate_uv_add_commands(pyproject_path=root_resolved / "pyproject.toml", output_path=root_resolved / "pyproject_init.sh")
+def tui_env(which: Annotated[Literal["PATH", "p", "ENV", "e"], typer.Argument(help="Which environment variable to display.")] = "ENV") -> None:
+    """📚 NAVIGATE ENV/PATH variable with TUI."""
+    from machineconfig.scripts.python.helpers.helpers_utils.python import tui_env as impl
+    impl(which=which)
+
+
+def download(
+    url: Annotated[Optional[str], typer.Argument(..., help="The URL to download the file from.")] = None,
+    decompress: Annotated[bool, typer.Option(..., "--decompress", "-d", help="Decompress the file if it's an archive.")] = False,
+    output: Annotated[Optional[str], typer.Option("--output", "-o", help="The output file path.")] = None,
+    output_dir: Annotated[Optional[str], typer.Option("--output-dir", help="Directory to place the downloaded file in.")] = None,
+) -> None:
+    """⬇️ Download a file from a URL and optionally decompress it."""
+    from machineconfig.scripts.python.helpers.helpers_utils.download import download as impl
+    impl(url=url, decompress=decompress, output=output, output_dir=output_dir)
+
+
+def get_machine_specs(hardware: Annotated[bool, typer.Option(..., "--hardware", "-h", help="Show compute capability")] = False) -> None:
+    """💻 Get machine specifications."""
+    from machineconfig.scripts.python.helpers.helpers_utils.python import get_machine_specs as impl
+    impl(hardware=hardware)
+
+
+def type_hint(path: Annotated[str, typer.Argument(..., help="Path to file/project dir to type hint.")] = ".",
+              dependency: Annotated[Literal["self-contained", "import"], typer.Option(..., "--dependency", "-d", help="Generated file is self contained or performs imports")] = "self-contained"
+              ) -> None:
+    from machineconfig.type_hinting.typedict.generators import generate_names_file
+    from pathlib import Path
+    path_resolved = Path(path).resolve()
+    if not path_resolved.exists():
+        typer.echo(f"Error: The provided path '{path}' does not exist.", err=True)
+        raise typer.Exit(code=1)
+    if path_resolved.is_file():
+        modules = [path_resolved]
+    else:
+        if not (path_resolved / "pyproject.toml").exists():
+            typer.echo("Error: Provided directory path is not a project root (missing pyproject.toml).", err=True)
+            raise typer.Exit(code=1)
+        else:
+            modules = [file for file in path_resolved.rglob("dtypes.py") if ".venv" not in str(file)]
+    for input_file in modules:
+        print(f"Worked on: {input_file}")
+        output_file = input_file.parent.joinpath(f"{input_file.stem}_names.py")
+        generated_file = generate_names_file(input_file, output_file, search_paths=None, dependency=dependency)
+        print(f"Generated: {generated_file}")
+
+
+def init_project(
+    name: Annotated[Optional[str], typer.Option("--name", "-n", help="Name of the project.")] = None,
+    tmp_dir: Annotated[bool, typer.Option("--tmp-dir", "-t", help="Use a temporary directory for the project initialization.")] = False,
+    python: Annotated[Literal["3.11", "3.12", "3.13", "3.14"], typer.Option("--python", "-p", help="Python sub version for the uv virtual environment.")] = "3.13",
+    libraries: Annotated[Optional[str], typer.Option("--libraries", "-l", help="Additional packages to include in the uv virtual environment (space separated).")] = None,
+    group: Annotated[Optional[str], typer.Option("--group", "-g", help="group of packages names (no separation) p:plot, t:types, l:linting, i:interactive, d:data")] = "p,t,l,i,d",
+) -> None:
+    """🚀 Initialize a project with a uv virtual environment and install dev packages."""
+    from machineconfig.scripts.python.helpers.helpers_utils.python import init_project as impl
+    impl(name=name, tmp_dir=tmp_dir, python=python, libraries=libraries, group=group)
+
+
+def edit_file_with_hx(path: Annotated[Optional[str], typer.Argument(..., help="The root directory of the project to edit, or a file path.")] = None) -> None:
+    """✏️ Open a file in the default editor."""
+    from machineconfig.scripts.python.helpers.helpers_utils.python import edit_file_with_hx as impl
+    impl(path=path)
+
+
+def merge_pdfs(
+    pdfs: Annotated[list[str], typer.Argument(..., help="Paths to the PDF files to merge.")],
+    output: Annotated[Optional[str], typer.Option("--output", "-o", help="Output merged PDF file path.")] = None,
+    compress: Annotated[bool, typer.Option("--compress", "-c", help="Compress the output PDF.")] = False,
+) -> None:
+    """📄 Merge two PDF files into one."""
+    from machineconfig.scripts.python.helpers.helpers_utils.pdf import merge_pdfs as impl
+    impl(pdfs=pdfs, output=output, compress=compress)
+
+
+def compress_pdf(
+    pdf_input: Annotated[str, typer.Argument(..., help="Path to the input PDF file to compress.")],
+    output: Annotated[Optional[str], typer.Option("--output", "-o", help="Output compressed PDF file path.")] = None,
+    quality: Annotated[int, typer.Option("--quality", "-q", help="JPEG quality for image compression (0-100, 0=no change, 100=best).")] = 85,
+    image_dpi: Annotated[int, typer.Option("--image-dpi", "-d", help="Target DPI for image resampling.")] = 0,
+    compress_streams: Annotated[bool, typer.Option("--compress-streams", "-c", help="Compress uncompressed streams.")] = True,
+    use_objstms: Annotated[bool, typer.Option("--object-streams", "-s", help="Use object streams for additional compression.")] = True,
+) -> None:
+    """📦 Compress a PDF file."""
+    from machineconfig.scripts.python.helpers.helpers_utils.pdf import compress_pdf as impl
+    impl(pdf_input=pdf_input, output=output, quality=quality, image_dpi=image_dpi, compress_streams=compress_streams, use_objstms=use_objstms)
 
 
 def get_app() -> typer.Typer:
-    app = typer.Typer(help="🛠️ utilities operations", no_args_is_help=True, add_help_option=False, add_completion=False)
+    app = typer.Typer(help="🛠️ utilities operations", no_args_is_help=True, add_help_option=True, add_completion=False)
     app.command(name="kill-process", no_args_is_help=False, help="⚔️ [k] Choose a process to kill")(kill_process)
-    app.command(name="k", no_args_is_help=False, help="Choose a process to kill", hidden=True)(kill_process)
+    app.command(name="k", no_args_is_help=False, hidden=True)(kill_process)
 
     app.command("environment", no_args_is_help=False, help="📚 [v] NAVIGATE ENV/PATH variable with TUI")(tui_env)
-    app.command("v", no_args_is_help=False, help="NAVIGATE ENV/PATH variable with TUI", hidden=True)(tui_env)
+    app.command("v", no_args_is_help=False, hidden=True)(tui_env)
 
     app.command(name="upgrade-packages", no_args_is_help=False, help="⬆️ [up] Upgrade project dependencies.")(upgrade_packages)
     app.command(name="up", no_args_is_help=False, hidden=True)(upgrade_packages)
@@ -51,14 +133,12 @@ def get_app() -> typer.Typer:
     app.command(name="pdf-compress", no_args_is_help=True, help="📦 [pc] Compress a PDF file.")(compress_pdf)
     app.command(name="pc", no_args_is_help=True, hidden=True)(compress_pdf)
 
-    # app.command(name="copy", no_args_is_help=True, help="[c] Copy files or directories.")(copy)
-    # app.command(name="c", no_args_is_help=True, hidden=True)(copy)
+    app.command(name="type-hint", no_args_is_help=True, help="📝 [t] Type hint a file or project directory.")(type_hint)
+    app.command(name="t", no_args_is_help=True, hidden=True)(type_hint)
 
     return app
 
-# def func():
-#     import pycr
 
 def main():
     app = get_app()
-    app()
+    app()