usecli 0.1.31__tar.gz → 0.1.33__tar.gz

{usecli-0.1.31 → usecli-0.1.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usecli
-Version: 0.1.31
+Version: 0.1.33
 Summary: A powerful Python CLI framework for building beautiful, developer-friendly command-line tools.
 Author: Edward Boswell
 Author-email: Edward Boswell <thememium@gmail.com>

{usecli-0.1.31 → usecli-0.1.33}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "usecli"
-version = "0.1.31"
+version = "0.1.33"
 description = "A powerful Python CLI framework for building beautiful, developer-friendly command-line tools."
 readme = "README.md"
 authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/__init__.py

@@ -91,6 +91,20 @@ def _get_cli_help_text() -> str:
     return f"{display_name} - {display_description}"
 
 
+def _get_group_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
+def _build_alias_to_primary(alias_registry: dict[str, list[str]]) -> dict[str, str]:
+    alias_to_primary: dict[str, str] = {}
+    for primary, aliases in alias_registry.items():
+        alias_to_primary[primary] = primary
+        for alias in aliases:
+            alias_to_primary[alias] = primary
+    return alias_to_primary
+
+
 class PrefixMatchingGroup(TyperGroup):
     """Custom Typer group that supports prefix matching for commands.
 
@@ -111,12 +125,33 @@ class PrefixMatchingGroup(TyperGroup):
         if rv is not None:
             return rv
 
+        group_alias_registry = _get_group_alias_registry(app)
+        group_alias_to_primary = _build_alias_to_primary(group_alias_registry)
+
+        if (
+            cmd_name in group_alias_to_primary
+            and group_alias_to_primary[cmd_name] != cmd_name
+        ):
+            return TyperGroup.get_command(self, ctx, group_alias_to_primary[cmd_name])
+
         matches = [x for x in self.list_commands(ctx) if x.startswith(cmd_name)]
+        group_aliases = [
+            alias for aliases in group_alias_registry.values() for alias in aliases
+        ]
+        matches.extend([alias for alias in group_aliases if alias.startswith(cmd_name)])
+        matches = list(dict.fromkeys(matches))
 
         if not matches:
             return None
 
         if cmd_name in matches:
+            if (
+                cmd_name in group_alias_to_primary
+                and group_alias_to_primary[cmd_name] != cmd_name
+            ):
+                return TyperGroup.get_command(
+                    self, ctx, group_alias_to_primary[cmd_name]
+                )
             return TyperGroup.get_command(self, ctx, cmd_name)
 
         return FilteredListCommand(cmd_name)

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/commands/defaults/base/internal/fzf_command.py

@@ -155,11 +155,27 @@ def _run_fzf_menu(
         )
 
 
-def _get_group_subcommands(group_name: str) -> list[dict[str, Any]]:
+def _resolve_group_alias(app: typer.Typer, group_name: str) -> str:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    if not isinstance(registry, dict):
+        return group_name
+    for primary, aliases in registry.items():
+        if group_name == primary:
+            return primary
+        if group_name in aliases:
+            return primary
+    return group_name
+
+
+def _get_group_subcommands(
+    app: typer.Typer,
+    group_name: str,
+) -> list[dict[str, Any]]:
     from usecli.cli.core.base_command import NestedCommandRegistry
 
     registry = NestedCommandRegistry()
-    group_app = registry._groups.get(group_name)
+    resolved_group = _resolve_group_alias(app, group_name)
+    group_app = registry._groups.get(resolved_group)
 
     if not group_app:
         return []
@@ -260,12 +276,19 @@ def run_interactive(
         selected_cmd = next(
             (c for c in ordered_commands if c["name"] == cmd_name), None
         )
+        if not selected_cmd:
+            resolved_group = _resolve_group_alias(app, cmd_name)
+            if resolved_group != cmd_name:
+                cmd_name = resolved_group
+                selected_cmd = next(
+                    (c for c in ordered_commands if c["name"] == cmd_name), None
+                )
         if not selected_cmd:
             ErrorHandler.display_error(f"Unknown command '{cmd_name}'")
             raise typer.Exit(code=1)
 
     if selected_cmd and selected_cmd.get("is_group"):
-        subcommands = _get_group_subcommands(cmd_name)
+        subcommands = _get_group_subcommands(app, cmd_name)
         if not subcommands:
             ErrorHandler.display_error(f"No subcommands found for '{cmd_name}'")
             raise typer.Exit(code=1)

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/commands/init_command.py

@@ -27,7 +27,7 @@ from usecli.cli.core.base_command import BaseCommand
 from usecli.cli.core.exceptions import UsecliBadParameter
 from usecli.cli.core.validators import validate_command_name
 from usecli.cli.utils.interactive.terminal_menu import terminal_menu
-from usecli.shared.config.globals import TEMPLATES_DIR, THEMES_DIR
+from usecli.shared.config.globals import TEMPLATES_DIR, THEMES_DIR, USECLI_TOML
 from usecli.shared.config.manager import ConfigManager, get_config
 
 console = Console()
@@ -113,6 +113,23 @@ class InitCommand(BaseCommand):
         pyproject_path.write_text(content)
         return True
 
+    def _write_usecli_toml(
+        self, project_root: Path, config_content: str, force: bool
+    ) -> str:
+        config_path = project_root / USECLI_TOML
+        existed = config_path.exists()
+        if existed and not force:
+            should_overwrite = Confirm.ask(
+                f"[{COLOR.WARNING}]usecli.toml already exists at {config_path}.[/{COLOR.WARNING}]\n"
+                "Overwrite it with the new settings from this init run?",
+                default=False,
+            )
+            if not should_overwrite:
+                return "skipped"
+
+        config_path.write_text(config_content.rstrip() + "\n")
+        return "updated" if existed else "created"
+
     def _ensure_project_scripts(
         self, pyproject_path: Path, command_name: str, force: bool
     ) -> str:
@@ -685,6 +702,7 @@ include = ["{root_package}*"]
         )
 
         scripts_status: str | None = None
+        usecli_toml_status: str | None = None
 
         # Check if pyproject.toml exists
         if pyproject_path.exists():
@@ -744,6 +762,22 @@ include = ["{root_package}*"]
 
             self._sync_environment(project_root, command_name)
 
+        usecli_toml_status = self._write_usecli_toml(
+            project_root, config_content, force
+        )
+        if usecli_toml_status == "created":
+            console.print(
+                f"[{COLOR.SUCCESS}]Created {USECLI_TOML} for runtime config fallback[/{COLOR.SUCCESS}]"
+            )
+        elif usecli_toml_status == "updated":
+            console.print(
+                f"[{COLOR.SUCCESS}]Updated {USECLI_TOML} for runtime config fallback[/{COLOR.SUCCESS}]"
+            )
+        elif usecli_toml_status == "skipped":
+            console.print(
+                f"[{COLOR.WARNING}]Skipped updating {USECLI_TOML}.[/{COLOR.WARNING}]"
+            )
+
         # Show summary
         summary_command = (
             command_name

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/config/colors.py

@@ -21,6 +21,8 @@ else:
     import tomli as tomllib
 
 
+PYPROJECT_TOML = "pyproject.toml"
+USECLI_TOML = "usecli.toml"
 DEFAULT_THEME_NAME = "default"
 THEMES_DIR = Path(__file__).resolve().parent.parent / "themes"
 DEFAULT_THEME_COLORS: dict[str, str] = {
@@ -53,10 +55,14 @@ def _find_project_root(start_dir: Path | None = None) -> Path | None:
     current = start_dir.resolve()
 
     while True:
-        pyproject_path = current / "pyproject.toml"
+        pyproject_path = current / PYPROJECT_TOML
         if pyproject_path.exists():
             return current
 
+        usecli_path = current / USECLI_TOML
+        if usecli_path.exists():
+            return current
+
         git_dir = current / ".git"
         if git_dir.exists():
             return current
@@ -73,7 +79,7 @@ def _load_usecli_config(project_root: Path | None) -> dict[str, Any]:
     if project_root is None:
         return {}
 
-    pyproject_path = project_root / "pyproject.toml"
+    pyproject_path = project_root / PYPROJECT_TOML
     if not pyproject_path.exists():
         return {}
 

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/core/base_command.py

@@ -344,7 +344,7 @@ class BaseCommand(ABC):
             registry = NestedCommandRegistry()
             group_app = registry.get_or_create_group(self.app, group_name)
 
-            normalized_aliases = self._normalize_aliases(
+            normalized_aliases, group_aliases = self._normalize_nested_aliases(
                 primary_name=command_name,
                 aliases=aliases,
                 group_name=group_name,
@@ -355,6 +355,11 @@ class BaseCommand(ABC):
                 description=self.description(),
                 aliases=normalized_aliases,
             )
+            self._register_group_aliases(
+                app=self.app,
+                group_name=group_name,
+                aliases=group_aliases,
+            )
         else:
             # Single-level command (e.g., "help", "init", "config:set", "make:command")
             name = signature_parts[0]
@@ -409,6 +414,31 @@ class BaseCommand(ABC):
             setattr(app, "_usecli_aliases", registry)
         return registry
 
+    def _get_group_alias_registry(self, app: typer.Typer) -> dict[str, list[str]]:
+        if not hasattr(app, "_usecli_group_aliases"):
+            setattr(app, "_usecli_group_aliases", {})
+        registry = getattr(app, "_usecli_group_aliases")
+        if not isinstance(registry, dict):
+            registry = {}
+            setattr(app, "_usecli_group_aliases", registry)
+        return registry
+
+    def _register_group_aliases(
+        self,
+        app: typer.Typer,
+        group_name: str,
+        aliases: list[str],
+    ) -> None:
+        if not aliases:
+            return
+
+        registry = self._get_group_alias_registry(app)
+        registry.setdefault(group_name, [])
+        for alias in aliases:
+            if alias == group_name or alias in registry[group_name]:
+                continue
+            registry[group_name].append(alias)
+
     def _normalize_aliases(
         self,
         primary_name: str,
@@ -437,6 +467,51 @@ class BaseCommand(ABC):
             normalized.append(alias_name)
         return normalized
 
+    def _normalize_nested_aliases(
+        self,
+        primary_name: str,
+        aliases: list[str],
+        group_name: str,
+    ) -> tuple[list[str], list[str]]:
+        normalized: list[str] = []
+        group_aliases: list[str] = []
+
+        for alias in aliases:
+            alias_parts = alias.split()
+            if len(alias_parts) == 1:
+                alias_name = alias_parts[0]
+                if not self._is_valid_subcommand_name(alias_name):
+                    continue
+                if alias_name == primary_name or alias_name in normalized:
+                    continue
+                normalized.append(alias_name)
+                continue
+
+            if len(alias_parts) != 2:
+                continue
+
+            group_alias, alias_name = alias_parts
+
+            if not self._is_valid_subcommand_name(group_alias):
+                continue
+            if not self._is_valid_subcommand_name(alias_name):
+                continue
+
+            if group_alias == group_name:
+                if alias_name == primary_name or alias_name in normalized:
+                    continue
+                normalized.append(alias_name)
+                continue
+
+            if group_alias not in group_aliases:
+                group_aliases.append(group_alias)
+
+            if alias_name == primary_name or alias_name in normalized:
+                continue
+            normalized.append(alias_name)
+
+        return normalized, group_aliases
+
     def _is_valid_subcommand_name(self, name: str) -> bool:
         """Check if a string is a valid subcommand name (not an argument placeholder).
 

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/core/ui/list.py

@@ -52,6 +52,8 @@ def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
 
     alias_registry = _get_alias_registry(app)
     alias_to_primary = _build_alias_to_primary(alias_registry)
+    group_alias_registry = _get_group_alias_registry(app)
+    group_alias_to_primary = _build_alias_to_primary(group_alias_registry)
 
     command_name = get_script_command_name(default="usecli")
 
@@ -84,23 +86,15 @@ def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
         commands.append(command_entry)
     commands.sort(key=lambda x: x["name"])
 
-    if prefix_filter:
-        filtered = [
-            c
-            for c in commands
-            if c["name"].startswith(prefix_filter)
-            or any(alias.startswith(prefix_filter) for alias in c["aliases"])
-        ]
-        if not filtered:
-            console.print(f"  [dim]No commands found for '{prefix_filter}'[/dim]")
-            console.print()
-            return
-        commands = filtered
-
     groups: dict[str, str] = {}
     if isinstance(click_group, click.Group):
         for cmd_name, cmd_obj in click_group.commands.items():
             if isinstance(cmd_obj, click.Group):
+                if (
+                    cmd_name in group_alias_to_primary
+                    and group_alias_to_primary[cmd_name] != cmd_name
+                ):
+                    continue
                 groups[cmd_name] = (
                     getattr(cmd_obj, "help", f"Commands for {cmd_name}")
                     or f"Commands for {cmd_name}"
@@ -117,7 +111,41 @@ def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
 
     help_flags = "--help, -h"
     all_option_flags = [help_flags] + option_flags
-    all_display_names = [cmd["display_name"] for cmd in commands] + list(groups.keys())
+    group_entries: list[CommandEntry] = []
+    for group_name, group_help in groups.items():
+        aliases = group_alias_registry.get(group_name, list[str]())
+        group_entries.append(
+            {
+                "name": group_name,
+                "display_name": _format_display_name(group_name, aliases),
+                "help": group_help,
+                "aliases": aliases,
+            }
+        )
+
+    if prefix_filter:
+        filtered = [
+            c
+            for c in commands
+            if c["name"].startswith(prefix_filter)
+            or any(alias.startswith(prefix_filter) for alias in c["aliases"])
+        ]
+        filtered_groups = [
+            g
+            for g in group_entries
+            if g["name"].startswith(prefix_filter)
+            or any(alias.startswith(prefix_filter) for alias in g["aliases"])
+        ]
+        if not filtered and not filtered_groups:
+            console.print(f"  [dim]No commands found for '{prefix_filter}'[/dim]")
+            console.print()
+            return
+        commands = filtered
+        group_entries = filtered_groups
+
+    all_display_names = [cmd["display_name"] for cmd in commands] + [
+        entry["display_name"] for entry in group_entries
+    ]
     all_labels = all_display_names + all_option_flags
     longest_label_length = max((len(label) for label in all_labels), default=0)
 
@@ -147,8 +175,9 @@ def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
     if not prefix_filter:
         console.print(f"[bold {COLOR.SECONDARY}]Available commands:")
 
+    group_names = set(groups.keys())
     top_level: list[CommandEntry] = [
-        c for c in commands if ":" not in c["name"] and c["name"] not in groups
+        c for c in commands if ":" not in c["name"] and c["name"] not in group_names
     ]
     with_colon: list[CommandEntry] = [c for c in commands if ":" in c["name"]]
 
@@ -160,15 +189,7 @@ def list_commands(app: typer.Typer, prefix_filter: str | None = None) -> None:
             f"  [{COLOR.COMMAND} not bold]{display_name}[/{COLOR.COMMAND} not bold]{padding}{cmd['help']}"
         )
 
-    for group_name, group_help in groups.items():
-        top_level.append(
-            {
-                "name": group_name,
-                "display_name": group_name,
-                "help": group_help,
-                "aliases": [],
-            }
-        )
+    top_level.extend(group_entries)
 
     top_level.sort(key=lambda x: x["name"])
 
@@ -291,6 +312,11 @@ def _get_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
     return registry if isinstance(registry, dict) else {}
 
 
+def _get_group_alias_registry(app: typer.Typer) -> dict[str, list[str]]:
+    registry = getattr(app, "_usecli_group_aliases", {})
+    return registry if isinstance(registry, dict) else {}
+
+
 def _get_option_description(param: click.Parameter) -> str:
     if "--show-completion" in param.opts:
         return "Show completion for the current shell."

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/cli/templates/command.py.j2

@@ -12,8 +12,8 @@ class {{ class_name }}(BaseCommand):
     def description(self) -> str:
         return "Description for {{ command_name }} command"
 
-    def aliases(self) -> list[str]:
-        return [{{ command_name[:3] }}]
+    # def aliases(self) -> list[str]:
+    #    return [{{ command_name[:3] }}]
 
     def handle(
         self,

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/shared/config/globals.py

@@ -17,3 +17,4 @@ THEMES_DIR = CLI_ROOT / "themes"
 
 # Config file names
 PYPROJECT_TOML = "pyproject.toml"
+USECLI_TOML = "usecli.toml"

{usecli-0.1.31 → usecli-0.1.33}/src/usecli/shared/config/manager.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from typing import Any
 
 from usecli.cli.core.exceptions.config import UsecliConfigError
+from usecli.shared.config.globals import PYPROJECT_TOML, USECLI_TOML
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -87,6 +88,7 @@ class ConfigManager:
     def __init__(
         self,
         pyproject_path: Path | None = None,
+        usecli_toml_path: Path | None = None,
         start_dir: Path | None = None,
     ) -> None:
         """Initialize the configuration manager.
@@ -102,12 +104,21 @@ class ConfigManager:
 
         if pyproject_path is None:
             pyproject_path = self._find_pyproject_toml(start_dir) or (
-                start_dir / "pyproject.toml"
+                start_dir / PYPROJECT_TOML
+            )
+
+        if usecli_toml_path is None:
+            usecli_toml_path = self._find_usecli_toml(start_dir) or (
+                start_dir / USECLI_TOML
             )
 
         self.pyproject_path: Path = pyproject_path
+        self.usecli_toml_path: Path = usecli_toml_path
         self.start_dir: Path = start_dir
-        self.project_root: Path = find_project_root(start_dir) or start_dir.resolve()
+        detected_root = find_project_root(start_dir)
+        if detected_root is None and self.usecli_toml_path.exists():
+            detected_root = self.usecli_toml_path.parent
+        self.project_root: Path = (detected_root or start_dir).resolve()
         self._config: dict[str, Any] = {}
         self._overrides: dict[str, Any] = {}
         self._load_config()
@@ -117,18 +128,32 @@ class ConfigManager:
         self._config = self.DEFAULT_CONFIG.copy()
         self._overrides = {}
 
+        loaded = False
         if self.pyproject_path.exists():
             try:
                 pyproject_config = self._load_pyproject_toml(self.pyproject_path)
                 if pyproject_config:
                     self._config = _deep_merge(self._config, pyproject_config)
                     self._overrides = _deep_merge(self._overrides, pyproject_config)
+                    loaded = True
             except (tomllib.TOMLDecodeError, OSError) as e:
                 raise UsecliConfigError(
                     f"Failed to load pyproject.toml: {e}",
                     config_file=str(self.pyproject_path),
                 ) from e
 
+        if not loaded and self.usecli_toml_path.exists():
+            try:
+                usecli_config = self._load_usecli_toml(self.usecli_toml_path)
+                if usecli_config:
+                    self._config = _deep_merge(self._config, usecli_config)
+                    self._overrides = _deep_merge(self._overrides, usecli_config)
+            except (tomllib.TOMLDecodeError, OSError) as e:
+                raise UsecliConfigError(
+                    f"Failed to load usecli.toml: {e}",
+                    config_file=str(self.usecli_toml_path),
+                ) from e
+
         default_themes = _normalize_themes_dir(self.DEFAULT_CONFIG.get("themes_dir"))
         override_themes = _normalize_themes_dir(self._overrides.get("themes_dir"))
         merged_themes = _dedupe_items(default_themes + override_themes)
@@ -151,7 +176,7 @@ class ConfigManager:
         current = start_dir.resolve()
 
         while True:
-            pyproject_path = current / "pyproject.toml"
+            pyproject_path = current / PYPROJECT_TOML
             if pyproject_path.exists():
                 return pyproject_path
 
@@ -162,6 +187,38 @@ class ConfigManager:
 
         return None
 
+    @classmethod
+    def _find_usecli_toml(cls, start_dir: Path) -> Path | None:
+        current = start_dir.resolve()
+
+        while True:
+            config_path = current / USECLI_TOML
+            if config_path.exists():
+                return config_path
+
+            parent = current.parent
+            if parent == current:
+                break
+            current = parent
+
+        return cls._find_usecli_toml_on_sys_path()
+
+    @staticmethod
+    def _find_usecli_toml_on_sys_path() -> Path | None:
+        for entry in sys.path:
+            if not entry:
+                continue
+            path = Path(entry)
+            if not path.exists() or not path.is_dir():
+                continue
+            candidate = path / USECLI_TOML
+            if candidate.exists():
+                return candidate
+            for child in path.glob(f"*/{USECLI_TOML}"):
+                if child.exists():
+                    return child
+        return None
+
     @staticmethod
     def _load_pyproject_toml(path: Path) -> dict[str, Any]:
         """Load pyproject.toml and return [tool.usecli] section.
@@ -176,6 +233,23 @@ class ConfigManager:
             data = tomllib.load(f)
             return data.get("tool", {}).get("usecli", {})
 
+    @staticmethod
+    def _load_usecli_toml(path: Path) -> dict[str, Any]:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+        tool_section = data.get("tool", {})
+        if isinstance(tool_section, dict):
+            usecli_section = tool_section.get("usecli", {})
+            if isinstance(usecli_section, dict):
+                return usecli_section
+
+        usecli_section = data.get("usecli", {})
+        if isinstance(usecli_section, dict):
+            return usecli_section
+
+        return {}
+
     def get(self, key: str, default: Any = None) -> Any:
         """Get a configuration value using dot notation.
 
@@ -256,9 +330,13 @@ class ConfigManager:
     @property
     def pyproject_exists(self) -> bool:
         """Check if pyproject.toml with [tool.usecli] exists."""
-        if not self.pyproject_path.exists():
-            return False
-        return self._pyproject_has_usecli(self.pyproject_path)
+        if self.pyproject_path.exists() and self._pyproject_has_usecli(
+            self.pyproject_path
+        ):
+            return True
+        if self.usecli_toml_path.exists():
+            return True
+        return False
 
     @staticmethod
     def _load_project_version(path: Path) -> str | None:
@@ -305,10 +383,14 @@ def find_project_root(start_dir: Path | None = None) -> Path | None:
     current = start_dir.resolve()
 
     while True:
-        pyproject_path = current / "pyproject.toml"
+        pyproject_path = current / PYPROJECT_TOML
         if pyproject_path.exists():
             return current
 
+        usecli_path = current / USECLI_TOML
+        if usecli_path.exists():
+            return current
+
         git_dir = current / ".git"
         if git_dir.exists():
             return current