machineconfig 8.14__py3-none-any.whl → 8.50__py3-none-any.whl

machineconfig/scripts/python/sessions.py

@@ -1,205 +1,70 @@
+"""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 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()
-    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.
-    """
+    from machineconfig.scripts.python.helpers.helpers_sessions.sessions_impl 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,
+    layout_path: Annotated[Optional[str], typer.Argument(..., help="Path to the layout.json file")] = None,
+    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,
+    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,
+) -> None:
+    """Launch terminal sessions based on a layout configuration file."""
     if layout_path is None:
         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)
-
-    # ============= Basic sanity checks =============
-    if parallel 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
-    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()}")
-
-
-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,
-                    ):
+    from machineconfig.scripts.python.helpers.helpers_sessions.sessions_impl import run_layouts
+    try:
+        run_layouts(layout_path=layout_path, max_tabs=max_tabs, max_layouts=max_layouts, sleep_inbetween=sleep_inbetween, monitor=monitor, parallel=parallel, kill_upon_completion=kill_upon_completion, choose=choose, choose_interactively=choose_interactively, subsitute_home=subsitute_home)
+    except ValueError as e:
+        typer.echo(str(e))
+        raise typer.Exit(1) from e
+
+
+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.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():
-    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("create-from-function", no_args_is_help=True, help=create_from_function.__doc__, short_help="[c] Create a layout from a function")(create_from_function)
-    layouts_app.command("c", no_args_is_help=True, help=create_from_function.__doc__, hidden=True)(create_from_function)
+    from machineconfig.scripts.python.helpers.helpers_sessions.sessions_impl 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 get_app() -> typer.Typer:
+    layouts_app = typer.Typer(help="Layouts management subcommands", no_args_is_help=True, add_help_option=True, add_completion=False)
+
+    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("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)
@@ -212,10 +77,10 @@ def get_app():
     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/terminal.py

@@ -1,122 +1,44 @@
-
 import typer
-from typing import Annotated, Optional
-
-
-def strip_ansi_codes(text: str) -> str:
-    """Remove ANSI color codes from text."""
-    import re
-    return re.sub(r'\x1b\[[0-9;]*[a-zA-Z]', '', text)
+from typing import Annotated
 
 
 def choose_zellij_session(
-        name: Annotated[Optional[str], typer.Argument(help="Name of the Zellij session to attach to. If not provided, a list will be shown to choose from.")] = None,
+        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):
+        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."""
-    if name is not None:
-        result = f"zellij attach {name}"
-        from machineconfig.utils.code import exit_then_run_shell_script
-        exit_then_run_shell_script(result, strict=True)
-
-    if new_session:
-        cmd = """
-    zellij --layout st2
-    """
-        if kill_all:
-            cmd = f"""zellij kill-sessions
-    {cmd}"""
-        from machineconfig.utils.code import exit_then_run_shell_script
-        exit_then_run_shell_script(script=cmd, strict=True)
-        typer.Exit()
-        return
-    cmd = "zellij list-sessions"
-    import subprocess
-    sessions: list[str] = subprocess.check_output(cmd, shell=True).decode().strip().split("\n")
-    # filter out empty lines and keep raw lines (they contain creation info)
-    sessions = [s for s in sessions if s.strip()]
-    sessions.sort(key=lambda s: "EXITED" in s)
-
-    if "current" in sessions:
-        print("Already in a Zellij session, avoiding nesting and exiting.")
+    from machineconfig.scripts.python.helpers.helpers_terminal.terminal_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 len(sessions) == 0:
-        print("No Zellij sessions found, creating a new one.")
-        result = """zellij --layout st2"""
-    elif len(sessions) == 1:
-        session_name = sessions[0].split(" [Created")[0]
-        print(f"Only one Zellij session found: {session_name}, attaching to it.")
-        result = f"zellij attach {session_name}"
-    else:
-        from machineconfig.utils.options import choose_from_options
-        # Artificially inject a "NEW SESSION" option so the user can create one from the list
-        NEW_SESSION_LABEL = "NEW SESSION"
-        options = [NEW_SESSION_LABEL] + sessions
-        session_name = choose_from_options(msg="Choose a Zellij session to attach to:", multi=False, options=options, tv=True)
-        if session_name == NEW_SESSION_LABEL:
-            cmd = "zellij --layout st2"
-            if kill_all:
-                cmd = f"zellij kill-sessions\n{cmd}"
-            from machineconfig.utils.code import exit_then_run_shell_script
-            exit_then_run_shell_script(cmd, strict=True)
-            raise typer.Exit()
-        session_name = session_name.split(" [Created")[0]
-        result = f"zellij attach {session_name}"
-    from machineconfig.utils.code import exit_then_run_shell_script
-    exit_then_run_shell_script(result, strict=True)
-
+    if action == "run_script" and payload:
+        from machineconfig.utils.code import exit_then_run_shell_script
+        exit_then_run_shell_script(payload, strict=True)
 
 
 def get_session_tabs() -> list[tuple[str, str]]:
     """Get all Zellij session tabs."""
-    cmd = "zellij list-sessions"
-    import subprocess
-    sessions: list[str] = subprocess.check_output(cmd, shell=True).decode().strip().split("\n")
-    sessions = [strip_ansi_codes(s) for s in sessions]
-    active_sessions = [s for s in sessions if "EXITED" not in s]
-    result: list[tuple[str, str]] = []
-    for session_line in active_sessions:
-        session_name = session_line.split(" [Created")[0].strip()
-        # Query tab names for the session
-        tab_cmd = f"zellij  --session {session_name} action query-tab-names"
-        try:
-            tabs: list[str] = subprocess.check_output(tab_cmd, shell=True).decode().strip().split("\n")
-            for tab in tabs:
-                if tab.strip():
-                    result.append((session_name, tab.strip()))
-        except subprocess.CalledProcessError:
-            # Skip if query fails
-            continue
+    from machineconfig.scripts.python.helpers.helpers_terminal.terminal_impl import get_session_tabs as impl
+    result = impl()
     print(result)
     return result
 
 
-def start_wt(layout_name: Annotated[str, typer.Argument(help="Layout name to start.")]):
+def start_wt(layout_name: Annotated[str, typer.Argument(help="Layout name to start.")]) -> None:
     """Start a Windows Terminal layout by name."""
-    from pathlib import Path
-    layouts_file = Path.home().joinpath("dotfiles/machineconfig/layouts.json")
-    if not layouts_file.exists():
-        typer.echo(f"❌ Layouts file not found: {layouts_file}")
-        # available
-        raise typer.Exit(code=1)
-    import json
-    from machineconfig.utils.schemas.layouts.layout_types import LayoutsFile
-    layouts_data: LayoutsFile = json.loads(layouts_file.read_text(encoding="utf-8"))
-    chosen_layout = next((a_layout for a_layout in layouts_data["layouts"] if a_layout["layoutName"] == layout_name), None)
-    if not chosen_layout:
-        typer.echo(f"❌ Layout '{layout_name}' not found in layouts file.")
-        available_layouts = [a_layout["layoutName"] for a_layout in layouts_data["layouts"]]
-        typer.echo(f"Available layouts: {', '.join(available_layouts)}")
+    from machineconfig.scripts.python.helpers.helpers_terminal.terminal_impl import start_wt as impl
+    status, message = impl(layout_name=layout_name)
+    if status == "error":
+        typer.echo(message)
         raise typer.Exit(code=1)
-    from machineconfig.cluster.sessions_managers.wt_local import run_wt_layout
-    run_wt_layout(layout_config=chosen_layout)
     # cmd = f'powershell -ExecutionPolicy Bypass -File "./{layout_name}_layout.ps1"'
     # from machineconfig.utils.code import exit_then_run_shell_script
     # exit_then_run_shell_script(cmd, strict=True)
 
 
 def get_app():
-    app = typer.Typer(help="🖥️ Terminal utilities", no_args_is_help=True, add_help_option=False)
+    app = typer.Typer(help="🖥️ Terminal utilities", no_args_is_help=True, add_help_option=True, add_completion=False)
     app.command(name="attach-to-zellij", no_args_is_help=False, help=choose_zellij_session.__doc__, short_help="[z] Choose a Zellij session to attach to")(choose_zellij_session)
     app.command(name="z", hidden=True, no_args_is_help=False, help=choose_zellij_session.__doc__)(choose_zellij_session)
 

machineconfig/scripts/python/utils.py

@@ -1,38 +1,119 @@
-from machineconfig.scripts.python.helpers_utils.pdf import merge_pdfs, compress_pdf
-from machineconfig.scripts.python.helpers_utils.python 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):
+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 main, ProcessManager
     if interactive:
         main()
         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,12 +132,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 main():
     app = get_app()
-    app()
+    app()