Open-AutoTools 0.0.4rc2__py3-none-any.whl → 0.0.5__py3-none-any.whl

autotools/autounit/commands.py

@@ -0,0 +1,55 @@
+import click
+from .core import autounit_convert
+from ..utils.loading import LoadingAnimation
+from ..utils.updates import check_for_updates
+
+# TOOL CATEGORY (USED BY 'autotools smoke')
+TOOL_CATEGORY = 'Conversion'
+
+# SMOKE TEST CASES (USED BY 'autotools smoke')
+SMOKE_TESTS = [
+    {'name': 'length-meters-feet', 'args': ['100', 'meter', 'feet']},
+    {'name': 'volume-liters-gallons', 'args': ['10', 'liter', 'gallon']},
+    {'name': 'weight-kg-lb', 'args': ['50', 'kilogram', 'pound']},
+    {'name': 'temperature-celsius-fahrenheit', 'args': ['25', 'celsius', 'fahrenheit']},
+]
+
+# CLI COMMAND TO CONVERT MEASUREMENT UNITS
+@click.command()
+@click.argument('value', nargs=1)
+@click.argument('from_unit', nargs=1)
+@click.argument('to_unit', nargs=1)
+def autounit(value, from_unit, to_unit):
+    """
+        CONVERTS MEASUREMENT UNITS (EXAMPLE: METERS TO FEET, LITERS TO GALLONS).
+
+        \b
+        SUPPORTS VARIOUS UNIT CATEGORIES:
+            - LENGTH: meter, feet, inch, kilometer, mile, centimeter, millimeter, yard
+            - VOLUME: liter, gallon, milliliter, fluid_ounce, cup, pint, quart
+            - WEIGHT: kilogram, pound, gram, ounce, ton, stone
+            - TEMPERATURE: celsius, fahrenheit, kelvin
+            - AND MANY MORE...
+
+        \b
+        EXAMPLES:
+            autounit 100 meter feet
+            autounit 10 liter gallon
+            autounit 50 kilogram pound
+            autounit 25 celsius fahrenheit
+            autounit 5 kilometer mile
+    """
+
+    try:
+        with LoadingAnimation():
+            result = autounit_convert(value, from_unit, to_unit)
+        click.echo(result)
+        update_msg = check_for_updates()
+        if update_msg:
+            click.echo(update_msg)
+    except ValueError as e:
+        click.echo(click.style(f"ERROR: {str(e)}", fg='red'), err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.echo(click.style(f"UNEXPECTED ERROR: {str(e)}", fg='red'), err=True)
+        raise click.Abort()

autotools/autounit/core.py

@@ -0,0 +1,36 @@
+import pyperclip
+from pint import UnitRegistry
+
+# INITIALIZE UNIT REGISTRY
+ureg = UnitRegistry()
+
+# CONVERTS MEASUREMENT UNITS
+def autounit_convert(value, from_unit, to_unit):
+    try:
+        if isinstance(value, str):
+            value = value.strip()
+            value = value.replace(',', '')
+        
+        value_float = float(value)
+        quantity = ureg.Quantity(value_float, from_unit)
+        result = quantity.to(to_unit)
+        result_value = result.magnitude
+        
+        if abs(result_value) >= 1000 or abs(result_value) < 0.01: result_str = f"{result_value:.6g}"
+        elif abs(result_value) >= 1: result_str = f"{result_value:.4f}".rstrip('0').rstrip('.')
+        else: result_str = f"{result_value:.6f}".rstrip('0').rstrip('.')
+        
+        output = f"{result_str} {to_unit}"
+        
+        try: pyperclip.copy(output)
+        except pyperclip.PyperclipException: pass
+        
+        return output
+    
+    except ValueError as e:
+        raise ValueError(f"INVALID VALUE OR UNIT: {str(e)}")
+    except Exception as e:
+        error_msg = str(e)
+        if "cannot convert" in error_msg.lower() or "incompatible" in error_msg.lower():
+            raise ValueError(f"CANNOT CONVERT FROM '{from_unit}' TO '{to_unit}': INCOMPATIBLE UNITS")
+        raise ValueError(f"CONVERSION ERROR: {error_msg}")

autotools/autozip/commands.py

@@ -0,0 +1,88 @@
+import click
+from pathlib import Path
+from .core import autozip_compress
+from ..utils.loading import LoadingAnimation
+from ..utils.updates import check_for_updates
+
+# TOOL CATEGORY (USED BY 'autotools smoke')
+TOOL_CATEGORY = 'Files'
+
+# SMOKE TEST CASES (USED BY 'autotools smoke')
+SMOKE_TESTS = [
+    {'name': 'zip-readme', 'args': ['README.md', '--output', '/tmp/autozip-smoke.zip']},
+]
+
+# CLI COMMAND TO COMPRESS FILES AND DIRECTORIES
+@click.command()
+@click.argument('sources', nargs=-1, required=True)
+@click.option('--output', '-o', 'output_path', required=True,
+              help='OUTPUT ARCHIVE PATH (EXTENSION DETERMINES FORMAT)')
+@click.option('--format', '-f', 'archive_format',
+              type=click.Choice(['zip', 'tar.gz', 'tar.bz2', 'tar.xz', 'tar'], case_sensitive=False),
+              help='ARCHIVE FORMAT (AUTO-DETECTED FROM OUTPUT EXTENSION IF NOT SPECIFIED)')
+@click.option('--compression', '-c', 'compression_level', type=int, default=6,
+              help='COMPRESSION LEVEL (0-9, DEFAULT: 6)')
+def autozip(sources, output_path, archive_format, compression_level):
+    """
+        COMPRESSES FILES AND DIRECTORIES INTO VARIOUS ARCHIVE FORMATS.
+
+        \b
+        SUPPORTED FORMATS:
+            - ZIP: .zip
+            - TAR.GZ: .tar.gz, .tgz
+            - TAR.BZ2: .tar.bz2, .tbz2
+            - TAR.XZ: .tar.xz, .txz
+            - TAR: .tar
+
+        \b
+        EXAMPLES:
+            autozip file.txt dir/ -o archive.zip
+            autozip file1.txt file2.txt -o backup.tar.gz --compression 9
+            autozip project/ -o release.tar.bz2 --format tar.bz2
+            autozip data/ -o archive.tar.xz --compression 7
+    """
+
+    # VALIDATE SOURCE PATHS
+    if not sources:
+        click.echo(click.style("ERROR: AT LEAST ONE SOURCE PATH IS REQUIRED", fg='red'), err=True)
+        click.echo(click.get_current_context().get_help())
+        return
+
+    # VALIDATE COMPRESSION LEVEL
+    if compression_level < 0 or compression_level > 9:
+        click.echo(click.style("ERROR: COMPRESSION LEVEL MUST BE BETWEEN 0 AND 9", fg='red'), err=True)
+        raise click.Abort()
+
+    # COMPRESS FILES AND DIRECTORIES
+    try:
+        with LoadingAnimation():
+            result = autozip_compress(
+                list(sources),
+                output_path,
+                archive_format=archive_format,
+                compression_level=compression_level
+            )
+        
+        click.echo(click.style(f"SUCCESS: CREATED ARCHIVE: {result}", fg='green'))
+        
+        archive_size = Path(result).stat().st_size
+        size_mb = archive_size / (1024 * 1024)
+
+        if size_mb >= 1:
+            click.echo(f"ARCHIVE SIZE: {size_mb:.2f} MB")
+        else:
+            size_kb = archive_size / 1024
+            click.echo(f"ARCHIVE SIZE: {size_kb:.2f} KB")
+        
+        update_msg = check_for_updates()
+        if update_msg: click.echo(update_msg)
+
+    except FileNotFoundError as e:
+        click.echo(click.style(f"ERROR: {str(e)}", fg='red'), err=True)
+        raise click.Abort()
+    except ValueError as e:
+        click.echo(click.style(f"ERROR: {str(e)}", fg='red'), err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.echo(click.style(f"UNEXPECTED ERROR: {str(e)}", fg='red'), err=True)
+        raise click.Abort()

autotools/autozip/core.py

@@ -0,0 +1,107 @@
+import os
+import zipfile
+import tarfile
+import lzma
+from pathlib import Path
+
+# COMPRESSES FILES/DIRECTORIES TO ZIP FORMAT
+def _compress_zip(source_paths, output_path, compression_level=6):
+    compression_level = min(max(compression_level, 0), 9)
+    
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED, compresslevel=compression_level) as zipf:
+        for source_path in source_paths:
+            source = Path(source_path)
+            if not source.exists():
+                raise FileNotFoundError(f"SOURCE PATH NOT FOUND: {source_path}")
+            
+            if source.is_file():
+                zipf.write(source, source.name)
+            elif source.is_dir():
+                for root, dirs, files in os.walk(source):
+                    for file in files:
+                        file_path = Path(root) / file
+                        arcname = file_path.relative_to(source)
+                        zipf.write(file_path, arcname)
+    
+    return output_path
+
+# COMPRESSES FILES/DIRECTORIES TO TAR.GZ FORMAT
+def _compress_tar_gz(source_paths, output_path, compression_level=6):
+    compression_level = min(max(compression_level, 1), 9)
+    
+    with tarfile.open(output_path, 'w:gz', compresslevel=compression_level) as tar:
+        for source_path in source_paths:
+            source = Path(source_path)
+            if not source.exists():
+                raise FileNotFoundError(f"SOURCE PATH NOT FOUND: {source_path}")
+            tar.add(source, arcname=source.name)
+    
+    return output_path
+
+# COMPRESSES FILES/DIRECTORIES TO TAR.BZ2 FORMAT
+def _compress_tar_bz2(source_paths, output_path, compression_level=6):
+    compression_level = min(max(compression_level, 1), 9)
+    
+    with tarfile.open(output_path, 'w:bz2', compresslevel=compression_level) as tar:
+        for source_path in source_paths:
+            source = Path(source_path)
+            if not source.exists():
+                raise FileNotFoundError(f"SOURCE PATH NOT FOUND: {source_path}")
+            tar.add(source, arcname=source.name)
+    
+    return output_path
+
+# COMPRESSES FILES/DIRECTORIES TO TAR.XZ FORMAT
+def _compress_tar_xz(source_paths, output_path, compression_level=6):
+    compression_level = min(max(compression_level, 0), 9)
+
+    import lzma
+    with lzma.open(output_path, 'wb', preset=compression_level) as lzma_file:
+        with tarfile.open(fileobj=lzma_file, mode='w') as tar:
+            for source_path in source_paths:
+                source = Path(source_path)
+                if not source.exists():
+                    raise FileNotFoundError(f"SOURCE PATH NOT FOUND: {source_path}")
+                tar.add(source, arcname=source.name)
+    
+    return output_path
+
+# DETERMINES OUTPUT FORMAT FROM FILE EXTENSION
+def _get_format_from_extension(output_path):
+    path_str = str(output_path).lower()
+    if path_str.endswith('.tar.gz') or path_str.endswith('.tgz'): return 'tar.gz'
+    elif path_str.endswith('.tar.bz2') or path_str.endswith('.tbz2'): return 'tar.bz2'
+    elif path_str.endswith('.tar.xz') or path_str.endswith('.txz'): return 'tar.xz'
+    elif path_str.endswith('.tar'): return 'tar'
+    elif path_str.endswith('.zip'): return 'zip'
+    else:
+        ext = Path(output_path).suffix.lower()
+        raise ValueError(f"UNSUPPORTED ARCHIVE FORMAT: {ext}\nSUPPORTED: .zip, .tar.gz, .tar.bz2, .tar.xz, .tar")
+
+# COMPRESSES FILES/DIRECTORIES TO TAR FORMAT (UNCOMPRESSED)
+def _compress_tar(source_paths, output_path):
+    with tarfile.open(output_path, 'w') as tar:
+        for source_path in source_paths:
+            source = Path(source_path)
+            if not source.exists():
+                raise FileNotFoundError(f"SOURCE PATH NOT FOUND: {source_path}")
+            tar.add(source, arcname=source.name)
+
+    return output_path
+
+# COMPRESSES FILES AND DIRECTORIES INTO VARIOUS ARCHIVE FORMATS
+def autozip_compress(source_paths, output_path, archive_format=None, compression_level=6):
+    if not source_paths:
+        raise ValueError("NO SOURCE PATHS PROVIDED")
+    
+    output = Path(output_path)
+    if archive_format is None: archive_format = _get_format_from_extension(output_path)
+    archive_format = archive_format.lower()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    
+    if archive_format == 'zip': return _compress_zip(source_paths, str(output), compression_level)
+    elif archive_format in ('tar.gz', 'tgz'): return _compress_tar_gz(source_paths, str(output), compression_level)
+    elif archive_format in ('tar.bz2', 'tbz2'): return _compress_tar_bz2(source_paths, str(output), compression_level)
+    elif archive_format in ('tar.xz', 'txz'): return _compress_tar_xz(source_paths, str(output), compression_level)
+    elif archive_format == 'tar': return _compress_tar(source_paths, str(output))
+    else: raise ValueError(f"UNSUPPORTED FORMAT: {archive_format}\nSUPPORTED: zip, tar.gz, tar.bz2, tar.xz, tar")

autotools/cli.py

@@ -4,6 +4,7 @@ import base64
 import argparse
 import json as json_module
 import sys
+import os
 
 from dotenv import load_dotenv
 from datetime import datetime
@@ -13,8 +14,8 @@ from importlib.metadata import version as get_version, PackageNotFoundError
 
 from .utils.version import print_version
 from .utils.updates import check_for_updates
-from .utils.commands import autocaps, autolower, autopassword, autoip, autotest
-from .utils.performance import init_metrics, finalize_metrics, get_metrics, should_enable_metrics, track_step
+from .utils.commands import get_wrapped_tool_commands
+from .utils.performance import init_metrics, finalize_metrics, get_metrics, should_enable_metrics
 
 load_dotenv()
 
@@ -30,14 +31,22 @@ load_dotenv()
 @click.pass_context
 def cli(ctx, perf):
     """
-        A suite of automated tools for various tasks:\n
-        - autocaps: Convert text to uppercase\n
-        - autolower: Convert text to lowercase\n
-        - autopassword: Generate secure passwords and encryption keys\n
-        - autoip: Display network information and run diagnostics\n
-        - test: Run the test suite\n
-        \n
-        Run 'autotools COMMAND --help' for more information on each command.\n
+        \b
+        A suite of automated tools for various tasks:
+            - autocaps: Convert text to uppercase
+            - autolower: Convert text to lowercase
+            - autopassword: Generate secure passwords and encryption keys
+            - autoip: Display network information and run diagnostics
+            - autoconvert: Convert text, images, audio, and video between formats
+            - autocolor: Convert color codes between different formats (hex, RGB, HSL, etc)
+            - autounit: Convert measurement units (meters to feet, liters to gallons, etc)
+            - autozip: Compress files and directories into various archive formats (zip, tar.gz, etc)
+            - autotodo: Create and manages a simple task list in a markdown file
+            - autonote: Takes quick notes and saves them to a markdown file
+            - test: Run the test suite (development only)
+
+        \b
+        Run 'autotools COMMAND --help' for more information on each command.
     """
 
     # INITIALIZE METRICS IF NEEDED
@@ -54,60 +63,16 @@ def cli(ctx, perf):
             get_metrics().end_process()
             finalize_metrics(ctx)
 
-# EXECUTES COMMAND WITH PERFORMANCE TRACKING
-def _execute_with_metrics(ctx, original_callback, *args, **kwargs):
-    metrics = get_metrics()
-    # REMOVE 'perf' FROM kwargs IF PRESENT (IT'S NOT PART OF THE ORIGINAL CALLBACK SIGNATURE)
-    kwargs.pop('perf', None)
-    
-    if not should_enable_metrics(ctx): return original_callback(*args, **kwargs)
-    
-    if metrics.process_start is None:
-        init_metrics()
-        get_metrics().end_startup()
-    
-    metrics.start_command()
-    cmd_name = ctx.invoked_subcommand or ctx.command.name or 'unknown'
-    try:
-        with track_step(f'command_{cmd_name}'): result = original_callback(*args, **kwargs)
-        metrics.end_command()
-        return result
-    finally:
-        if metrics.process_end is None:
-            metrics.end_process()
-            finalize_metrics(ctx)
+# DISCOVER AND REGISTER ALL TOOL COMMANDS
+_wrapped_tool_commands = get_wrapped_tool_commands()
+for _tool_name in sorted(_wrapped_tool_commands):
+    _cmd = _wrapped_tool_commands[_tool_name]
 
-# WRAPS COMMANDS WITH PERFORMANCE TRACKING
-def _wrap_command_with_metrics(cmd):
-    import inspect
-    original_callback = cmd.callback
-    
-    # ADD --perf OPTION TO THE COMMAND SO IT CAN BE USED DIRECTLY ON SUBCOMMANDS
-    has_perf_option = any(param.opts == ['--perf'] for param in cmd.params if isinstance(param, click.Option))
-    if not has_perf_option:
-        perf_option = click.Option(['--perf'], is_flag=True, help='Display performance metrics')
-        cmd.params.append(perf_option)
-    
-    sig = inspect.signature(original_callback)
-    expects_ctx = 'ctx' in sig.parameters
-    
-    if expects_ctx:
-        @click.pass_context
-        def wrapped_callback(ctx, *args, **kwargs):
-            return _execute_with_metrics(ctx, original_callback, ctx, *args, **kwargs)
-    else:
-        def wrapped_callback(*args, **kwargs):
-            ctx = click.get_current_context()
-            return _execute_with_metrics(ctx, original_callback, *args, **kwargs)
-    
-    cmd.callback = wrapped_callback
-    return cmd
+    if _tool_name == 'autotest': cli.add_command(_cmd, name='test')
+    else: cli.add_command(_cmd)
 
-cli.add_command(_wrap_command_with_metrics(autocaps))
-cli.add_command(_wrap_command_with_metrics(autolower))
-cli.add_command(_wrap_command_with_metrics(autopassword))
-cli.add_command(_wrap_command_with_metrics(autoip))
-cli.add_command(_wrap_command_with_metrics(autotest), name='test')
+# EXPOSE TOOL COMMANDS FOR console_scripts ENTRYPOINTS (setup.py)
+for _tool_name, _cmd in _wrapped_tool_commands.items(): globals()[_tool_name] = _cmd
 
 # DISPLAYS COMMAND OPTIONS
 def _display_command_options(cmd_obj):
@@ -153,4 +118,43 @@ def autotools():
         click.echo(click.style("\nUpdate Available:", fg='red', bold=True))
         click.echo(update_msg)
 
+# LISTS TOOL SUBCOMMANDS (MACHINE-FRIENDLY)
+@cli.command(name='list-tools')
+@click.option('--json', 'as_json', is_flag=True, help='OUTPUT JSON')
+def list_tools(as_json):
+    tools = []
+    for tool_name, cmd in get_wrapped_tool_commands().items():
+        public_name = 'test' if tool_name == 'autotest' else (cmd.name or tool_name)
+        tools.append(public_name)
+
+    tools = sorted(set(tools))
+    if as_json: click.echo(json_module.dumps(tools))
+    else: click.echo("\n".join(tools))
+
+# RUNS SMOKE TESTS FOR ALL DISCOVERED TOOLS (USED BY docker/run_tests.sh)
+@cli.command()
+@click.option('--workdir', type=click.Path(file_okay=False, dir_okay=True), default=None, help='WORK DIRECTORY FOR TEMP FILES')
+@click.option('--timeout', type=int, default=30, help='PER-CASE TIMEOUT (SECONDS)')
+@click.option('--include', 'include_tools', multiple=True, help='ONLY RUN THESE TOOLS (REPEATABLE)')
+@click.option('--exclude', 'exclude_tools', multiple=True, help='SKIP THESE TOOLS (REPEATABLE)')
+@click.option('--json', 'as_json', is_flag=True, help='OUTPUT JSON RESULTS')
+@click.option('--verbose/--quiet', default=(os.getenv('VERBOSE', '1') == '1'), help='SHOW COMMAND OUTPUT')
+def smoke(workdir, timeout, include_tools, exclude_tools, as_json, verbose):
+    from .utils.smoke import run_smoke
+
+    results = run_smoke(
+        workdir=workdir,
+        timeout_s=timeout,
+        include=set(include_tools),
+        exclude=set(exclude_tools),
+        verbose=verbose,
+        platform=os.getenv('PLATFORM') or 'Unknown Platform',
+        print_table=not as_json
+    )
+
+    if as_json: click.echo(json_module.dumps(results, ensure_ascii=False))
+
+    failed = [r for r in results if r.get('status') != 'OK']
+    raise SystemExit(1 if failed else 0)
+
 if __name__ == '__main__': cli()

autotools/utils/commands.py

@@ -1,13 +1,144 @@
-from ..autocaps.commands import autocaps
-from ..autolower.commands import autolower
-from ..autopassword.commands import autopassword
-from ..autoip.commands import autoip
-from ..autotest.commands import autotest
+import click
+import inspect
+import importlib
+import pkgutil
+from types import ModuleType
+from typing import Dict, Iterable, List, Tuple
+
+from .performance import init_metrics, finalize_metrics, get_metrics, should_enable_metrics, track_step
 
 __all__ = [
-    'autocaps',
-    'autolower',
-    'autopassword',
-    'autoip',
-    'autotest'
+    'discover_tool_command_entries',
+    'get_wrapped_tool_commands',
+    'register_commands',
+    'get_tool_category'
 ]
+
+# PACKAGES THAT SHOULD NEVER BE TREATED AS TOOLS
+_EXCLUDED_TOOL_PACKAGES = {'utils', '__pycache__'}
+
+# ITERATES ALL TOP-LEVEL TOOL PACKAGES (autotools/<tool>/)
+def _iter_tool_packages() -> Iterable[str]:
+    import autotools as autotools_pkg
+    for module_info in pkgutil.iter_modules(autotools_pkg.__path__):
+        if not module_info.ispkg: continue
+        name = module_info.name
+        if name.startswith('_'): continue
+        if name in _EXCLUDED_TOOL_PACKAGES: continue
+        if name == 'cli': continue
+        yield name
+
+# IMPORTS autotools.<tool>.commands IF IT EXISTS
+def _import_tool_commands_module(tool_name: str) -> ModuleType | None:
+    full_name = f'autotools.{tool_name}.commands'
+    try:
+        return importlib.import_module(full_name)
+    except ModuleNotFoundError as e:
+        if e.name == full_name: return None
+        raise
+
+# EXTRACTS ALL CLICK COMMAND OBJECTS FROM A MODULE
+def _extract_click_commands(mod: ModuleType) -> List[click.Command]:
+    commands: List[click.Command] = []
+    for value in mod.__dict__.values():
+        if isinstance(value, click.core.Command): commands.append(value)
+    return commands
+
+# SELECTS THE APPROPRIATE COMMAND FROM A LIST OF COMMANDS FOR A GIVEN TOOL NAME
+def _select_command_for_tool(cmds: List[click.Command], tool_name: str, mod_name: str) -> click.Command:
+    selected = None
+    for c in cmds:
+        if c.name == tool_name:
+            selected = c
+            break
+
+    if selected is None:
+        if len(cmds) == 1:
+            selected = cmds[0]
+        else:
+            names = ', '.join(sorted({c.name or '<unnamed>' for c in cmds}))
+            raise RuntimeError(f"MULTIPLE CLICK COMMANDS FOUND IN {mod_name}: {names}")
+
+    return selected
+
+# DISCOVERS TOOL COMMANDS AS (MODULE, CLICK COMMAND) BY TOOL PACKAGE NAME
+def discover_tool_command_entries() -> Dict[str, Tuple[ModuleType, click.Command]]:
+    entries: Dict[str, Tuple[ModuleType, click.Command]] = {}
+    for tool_name in _iter_tool_packages():
+        mod = _import_tool_commands_module(tool_name)
+        if mod is None: continue
+        cmds = _extract_click_commands(mod)
+        if not cmds: continue
+
+        selected = _select_command_for_tool(cmds, tool_name, mod.__name__)
+        entries[tool_name] = (mod, selected)
+
+    return entries
+
+# RETURNS WRAPPED TOOL COMMANDS (USED BY CLI GROUP AND CONSOLE_SCRIPTS EXPORTS)
+def get_wrapped_tool_commands() -> Dict[str, click.Command]:
+    wrapped: Dict[str, click.Command] = {}
+    for tool_name, (_mod, cmd) in discover_tool_command_entries().items():
+        wrapped[tool_name] = _wrap_command_with_metrics(cmd)
+    return wrapped
+
+# EXECUTES COMMAND WITH PERFORMANCE TRACKING
+def _execute_with_metrics(ctx, original_callback, *args, **kwargs):
+    metrics = get_metrics()
+    kwargs.pop('perf', None)
+    
+    if not should_enable_metrics(ctx): return original_callback(*args, **kwargs)
+    if metrics.process_start is None:
+        init_metrics()
+        get_metrics().end_startup()
+    
+    metrics.start_command()
+    cmd_name = ctx.invoked_subcommand or ctx.command.name or 'unknown'
+
+    try:
+        with track_step(f'command_{cmd_name}'): result = original_callback(*args, **kwargs)
+        metrics.end_command()
+        return result
+    finally:
+        if metrics.process_end is None:
+            metrics.end_process()
+            finalize_metrics(ctx)
+
+# WRAPS COMMANDS WITH PERFORMANCE TRACKING
+def _wrap_command_with_metrics(cmd):
+    if getattr(cmd, '_autotools_metrics_wrapped', False): return cmd
+
+    original_callback = cmd.callback
+    has_perf_option = any(param.opts == ['--perf'] for param in cmd.params if isinstance(param, click.Option))
+
+    if not has_perf_option:
+        perf_option = click.Option(['--perf'], is_flag=True, help='Display performance metrics')
+        cmd.params.append(perf_option)
+    
+    sig = inspect.signature(original_callback)
+    expects_ctx = 'ctx' in sig.parameters
+    
+    if expects_ctx:
+        @click.pass_context
+        def wrapped_callback(ctx, *args, **kwargs):
+            return _execute_with_metrics(ctx, original_callback, ctx, *args, **kwargs)
+    else:
+        def wrapped_callback(*args, **kwargs):
+            ctx = click.get_current_context()
+            return _execute_with_metrics(ctx, original_callback, *args, **kwargs)
+    
+    cmd.callback = wrapped_callback
+    cmd._autotools_metrics_wrapped = True
+    return cmd
+
+# EXTRACTS TOOL CATEGORY FROM MODULE (FALLBACK TO 'Other' IF NOT DEFINED)
+def get_tool_category(mod: ModuleType) -> str:
+    return getattr(mod, 'TOOL_CATEGORY', 'Other')
+
+# FUNCTION TO REGISTER ALL COMMANDS TO CLI GROUP
+def register_commands(cli_group):
+    wrapped = get_wrapped_tool_commands()
+    for tool_name in sorted(wrapped):
+        cmd = wrapped[tool_name]
+        if tool_name == 'autotest': cli_group.add_command(cmd, name='test')
+        else: cli_group.add_command(cmd)