falyx 0.1.62__py3-none-any.whl → 0.1.64__py3-none-any.whl

falyx/action/base_action.py

@@ -63,7 +63,7 @@ class BaseAction(ABC):
         hooks: HookManager | None = None,
         inject_last_result: bool = False,
         inject_into: str = "last_result",
-        never_prompt: bool = False,
+        never_prompt: bool | None = None,
         logging_hooks: bool = False,
     ) -> None:
         self.name = name
@@ -72,7 +72,7 @@ class BaseAction(ABC):
         self.shared_context: SharedContext | None = None
         self.inject_last_result: bool = inject_last_result
         self.inject_into: str = inject_into
-        self._never_prompt: bool = never_prompt
+        self._never_prompt: bool | None = never_prompt
         self._skip_in_chain: bool = False
         self.console: Console = console
         self.options_manager: OptionsManager | None = None
@@ -122,7 +122,9 @@ class BaseAction(ABC):
 
     @property
     def never_prompt(self) -> bool:
-        return self.get_option("never_prompt", self._never_prompt)
+        if self._never_prompt is not None:
+            return self._never_prompt
+        return self.get_option("never_prompt", False)
 
     def prepare(
         self, shared_context: SharedContext, options_manager: OptionsManager | None = None

falyx/action/select_file_action.py

@@ -30,7 +30,7 @@ from falyx.themes import OneColors
 
 class SelectFileAction(BaseAction):
     """
-    SelectFileAction allows users to select a file from a directory and return:
+    SelectFileAction allows users to select a file(s) from a directory and return:
     - file content (as text, JSON, CSV, etc.)
     - or the file path itself.
 
@@ -50,6 +50,9 @@ class SelectFileAction(BaseAction):
         style (str): Style for the selection options.
         suffix_filter (str | None): Restrict to certain file types.
         return_type (FileType): What to return (path, content, parsed).
+        number_selections (int | str): How many files to select (1, 2, '*').
+        separator (str): Separator for multiple selections.
+        allow_duplicates (bool): Allow selecting the same file multiple times.
         prompt_session (PromptSession | None): Prompt session for user input.
     """
 
@@ -217,7 +220,7 @@ class SelectFileAction(BaseAction):
             er.record(context)
 
     async def preview(self, parent: Tree | None = None):
-        label = f"[{OneColors.GREEN}]📁 SelectFilesAction[/] '{self.name}'"
+        label = f"[{OneColors.GREEN}]📁 SelectFileAction[/] '{self.name}'"
         tree = parent.add(label) if parent else Tree(label)
 
         tree.add(f"[dim]Directory:[/] {str(self.directory)}")
@@ -243,6 +246,6 @@ class SelectFileAction(BaseAction):
 
     def __str__(self) -> str:
         return (
-            f"SelectFilesAction(name={self.name!r}, dir={str(self.directory)!r}, "
+            f"SelectFileAction(name={self.name!r}, dir={str(self.directory)!r}, "
             f"suffix_filter={self.suffix_filter!r}, return_type={self.return_type})"
         )

falyx/action/selection_action.py

@@ -25,11 +25,60 @@ from falyx.themes import OneColors
 
 class SelectionAction(BaseAction):
     """
-    A selection action that prompts the user to select an option from a list or
-    dictionary. The selected option is then returned as the result of the action.
+    A Falyx Action for interactively or programmatically selecting one or more items
+    from a list or dictionary of options.
 
-    If return_key is True, the key of the selected option is returned instead of
-    the value.
+    `SelectionAction` supports both `list[str]` and `dict[str, SelectionOption]`
+    inputs. It renders a prompt (unless `never_prompt=True`), validates user input
+    or injected defaults, and returns a structured result based on the specified
+    `return_type`.
+
+    It is commonly used for item pickers, confirmation flows, dynamic parameterization,
+    or guided workflows in interactive or headless CLI pipelines.
+
+    Features:
+    - Supports single or multiple selections (`number_selections`)
+    - Dictionary mode allows rich metadata (description, value, style)
+    - Flexible return values: key(s), value(s), item(s), description(s), or mappings
+    - Fully hookable lifecycle (`before`, `on_success`, `on_error`, `after`, `on_teardown`)
+    - Default selection logic supports previous results (`last_result`)
+    - Can run in headless mode using `never_prompt` and fallback defaults
+
+    Args:
+        name (str): Action name for tracking and logging.
+        selections (list[str] | dict[str, SelectionOption] | dict[str, Any]):
+            The available choices. If a plain dict is passed, values are converted
+            into `SelectionOption` instances.
+        title (str): Title shown in the selection UI (default: "Select an option").
+        columns (int): Number of columns in the selection table.
+        prompt_message (str): Input prompt for the user (default: "Select > ").
+        default_selection (str | list[str]): Key(s) or index(es) used as fallback selection.
+        number_selections (int | str): Max number of choices allowed (or "*" for unlimited).
+        separator (str): Character used to separate multi-selections (default: ",").
+        allow_duplicates (bool): Whether duplicate selections are allowed.
+        inject_last_result (bool): If True, attempts to inject the last result as default.
+        inject_into (str): The keyword name for injected value (default: "last_result").
+        return_type (SelectionReturnType | str): The type of result to return.
+        prompt_session (PromptSession | None): Reused or customized prompt_toolkit session.
+        never_prompt (bool): If True, skips prompting and uses default_selection or last_result.
+        show_table (bool): Whether to render the selection table before prompting.
+
+    Returns:
+        Any: The selected result(s), shaped according to `return_type`.
+
+    Raises:
+        CancelSignal: If the user chooses the cancel option.
+        ValueError: If configuration is invalid or no selection can be resolved.
+        TypeError: If `selections` is not a supported type.
+
+    Example:
+        SelectionAction(
+            name="PickEnv",
+            selections={"dev": "Development", "prod": "Production"},
+            return_type="key",
+        )
+
+    This Action supports use in both interactive menus and chained, non-interactive CLI flows.
     """
 
     def __init__(
@@ -46,7 +95,7 @@ class SelectionAction(BaseAction):
         title: str = "Select an option",
         columns: int = 5,
         prompt_message: str = "Select > ",
-        default_selection: str = "",
+        default_selection: str | list[str] = "",
         number_selections: int | str = 1,
         separator: str = ",",
         allow_duplicates: bool = False,
@@ -202,37 +251,105 @@ class SelectionAction(BaseAction):
             raise ValueError(f"Unsupported return type: {self.return_type}")
         return result
 
-    async def _run(self, *args, **kwargs) -> Any:
-        kwargs = self._maybe_inject_last_result(kwargs)
-        context = ExecutionContext(
-            name=self.name,
-            args=args,
-            kwargs=kwargs,
-            action=self,
-        )
-
-        effective_default = str(self.default_selection)
-        maybe_result = str(self.last_result)
-        if isinstance(self.selections, dict):
-            if maybe_result in self.selections:
-                effective_default = maybe_result
-            elif self.inject_last_result:
+    async def _resolve_effective_default(self) -> str:
+        effective_default: str | list[str] = self.default_selection
+        maybe_result = self.last_result
+        if self.number_selections == 1:
+            if isinstance(effective_default, list):
+                effective_default = effective_default[0] if effective_default else ""
+            elif isinstance(maybe_result, list):
+                maybe_result = maybe_result[0] if maybe_result else ""
+            default = await self._resolve_single_default(maybe_result)
+            if not default:
+                default = await self._resolve_single_default(effective_default)
+            if not default and self.inject_last_result:
                 logger.warning(
                     "[%s] Injected last result '%s' not found in selections",
                     self.name,
                     maybe_result,
                 )
+            return default
+
+        if maybe_result and isinstance(maybe_result, list):
+            maybe_result = [
+                await self._resolve_single_default(item) for item in maybe_result
+            ]
+            if (
+                maybe_result
+                and self.number_selections != "*"
+                and len(maybe_result) != self.number_selections
+            ):
+                raise ValueError(
+                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
+                    f"but last_result has a different length: {len(maybe_result)}."
+                )
+            return self.separator.join(maybe_result)
+        elif effective_default and isinstance(effective_default, list):
+            effective_default = [
+                await self._resolve_single_default(item) for item in effective_default
+            ]
+            if (
+                effective_default
+                and self.number_selections != "*"
+                and len(effective_default) != self.number_selections
+            ):
+                raise ValueError(
+                    f"[{self.name}] 'number_selections' is {self.number_selections}, "
+                    f"but default_selection has a different length: {len(effective_default)}."
+                )
+            return self.separator.join(effective_default)
+        if self.inject_last_result:
+            logger.warning(
+                "[%s] Injected last result '%s' not found in selections",
+                self.name,
+                maybe_result,
+            )
+        return ""
+
+    async def _resolve_single_default(self, maybe_result: str) -> str:
+        effective_default = ""
+        if isinstance(self.selections, dict):
+            if str(maybe_result) in self.selections:
+                effective_default = str(maybe_result)
+            elif maybe_result in (
+                selection.value for selection in self.selections.values()
+            ):
+                selection = [
+                    key
+                    for key, sel in self.selections.items()
+                    if sel.value == maybe_result
+                ]
+                if selection:
+                    effective_default = selection[0]
+            elif maybe_result in (
+                selection.description for selection in self.selections.values()
+            ):
+                selection = [
+                    key
+                    for key, sel in self.selections.items()
+                    if sel.description == maybe_result
+                ]
+                if selection:
+                    effective_default = selection[0]
         elif isinstance(self.selections, list):
-            if maybe_result.isdigit() and int(maybe_result) in range(
+            if str(maybe_result).isdigit() and int(maybe_result) in range(
                 len(self.selections)
             ):
                 effective_default = maybe_result
-            elif self.inject_last_result:
-                logger.warning(
-                    "[%s] Injected last result '%s' not found in selections",
-                    self.name,
-                    maybe_result,
-                )
+            elif maybe_result in self.selections:
+                effective_default = str(self.selections.index(maybe_result))
+        return effective_default
+
+    async def _run(self, *args, **kwargs) -> Any:
+        kwargs = self._maybe_inject_last_result(kwargs)
+        context = ExecutionContext(
+            name=self.name,
+            args=args,
+            kwargs=kwargs,
+            action=self,
+        )
+
+        effective_default = await self._resolve_effective_default()
 
         if self.never_prompt and not effective_default:
             raise ValueError(
@@ -251,6 +368,9 @@ class SelectionAction(BaseAction):
                     columns=self.columns,
                     formatter=self.cancel_formatter,
                 )
+                if effective_default is None or isinstance(effective_default, int):
+                    effective_default = ""
+
                 if not self.never_prompt:
                     indices: int | list[int] = await prompt_for_index(
                         len(self.selections),
@@ -265,8 +385,13 @@ class SelectionAction(BaseAction):
                         cancel_key=self.cancel_key,
                     )
                 else:
-                    if effective_default:
+                    if effective_default and self.number_selections == 1:
                         indices = int(effective_default)
+                    elif effective_default:
+                        indices = [
+                            int(index)
+                            for index in effective_default.split(self.separator)
+                        ]
                     else:
                         raise ValueError(
                             f"[{self.name}] 'never_prompt' is True but no valid "
@@ -308,7 +433,15 @@ class SelectionAction(BaseAction):
                         cancel_key=self.cancel_key,
                     )
                 else:
-                    keys = effective_default
+                    if effective_default and self.number_selections == 1:
+                        keys = effective_default
+                    elif effective_default:
+                        keys = effective_default.split(self.separator)
+                    else:
+                        raise ValueError(
+                            f"[{self.name}] 'never_prompt' is True but no valid "
+                            "default_selection was provided."
+                        )
                 if keys == self.cancel_key:
                     raise CancelSignal("User cancelled the selection.")
 
@@ -337,13 +470,13 @@ class SelectionAction(BaseAction):
 
         if isinstance(self.selections, list):
             sub = tree.add(f"[dim]Type:[/] List[str] ({len(self.selections)} items)")
-            for i, item in enumerate(self.selections[:10]):  # limit to 10
+            for i, item in enumerate(self.selections[:10]):
                 sub.add(f"[dim]{i}[/]: {item}")
             if len(self.selections) > 10:
                 sub.add(f"[dim]... ({len(self.selections) - 10} more)[/]")
         elif isinstance(self.selections, dict):
             sub = tree.add(
-                f"[dim]Type:[/] Dict[str, (str, Any)] ({len(self.selections)} items)"
+                f"[dim]Type:[/] Dict[str, SelectionOption] ({len(self.selections)} items)"
             )
             for i, (key, option) in enumerate(list(self.selections.items())[:10]):
                 sub.add(f"[dim]{key}[/]: {option.description}")
@@ -353,9 +486,30 @@ class SelectionAction(BaseAction):
             tree.add(f"[{OneColors.DARK_RED_b}]Invalid selections type[/]")
             return
 
-        tree.add(f"[dim]Default:[/] '{self.default_selection or self.last_result}'")
-        tree.add(f"[dim]Return:[/] {self.return_type.name.capitalize()}")
+        default = self.default_selection or self.last_result
+        if isinstance(default, list):
+            default_display = self.separator.join(str(d) for d in default)
+        else:
+            default_display = str(default or "")
+
+        tree.add(f"[dim]Default:[/] '{default_display}'")
+
+        return_behavior = {
+            "KEY": "selected key(s)",
+            "VALUE": "mapped value(s)",
+            "DESCRIPTION": "description(s)",
+            "ITEMS": "SelectionOption object(s)",
+            "DESCRIPTION_VALUE": "{description: value}",
+        }.get(self.return_type.name, self.return_type.name)
+
+        tree.add(
+            f"[dim]Return:[/] {self.return_type.name.capitalize()} → {return_behavior}"
+        )
         tree.add(f"[dim]Prompt:[/] {'Disabled' if self.never_prompt else 'Enabled'}")
+        tree.add(f"[dim]Columns:[/] {self.columns}")
+        tree.add(
+            f"[dim]Multi-select:[/] {'Yes' if self.number_selections != 1 else 'No'}"
+        )
 
         if not parent:
             self.console.print(tree)

falyx/completer.py

@@ -29,6 +29,26 @@ class FalyxCompleter(Completer):
             yield from self._suggest_commands(tokens[0] if tokens else "")
             return
 
+        # Identify command
+        command_key = tokens[0].upper()
+        command = self.falyx._name_map.get(command_key)
+        if not command or not command.arg_parser:
+            return
+
+        # If at end of token, e.g., "--t" vs "--tag ", add a stub so suggest_next sees it
+        parsed_args = tokens[1:] if cursor_at_end_of_token else tokens[1:-1]
+        stub = "" if cursor_at_end_of_token else tokens[-1]
+
+        try:
+            suggestions = command.arg_parser.suggest_next(
+                parsed_args + ([stub] if stub else [])
+            )
+            for suggestion in suggestions:
+                if suggestion.startswith(stub):
+                    yield Completion(suggestion, start_position=-len(stub))
+        except Exception:
+            return
+
     def _suggest_commands(self, prefix: str) -> Iterable[Completion]:
         prefix = prefix.upper()
         keys = [self.falyx.exit_command.key]

falyx/execution_registry.py

@@ -75,7 +75,7 @@ class ExecutionRegistry:
     _store_by_name: dict[str, list[ExecutionContext]] = defaultdict(list)
     _store_by_index: dict[int, ExecutionContext] = {}
     _store_all: list[ExecutionContext] = []
-    _console = Console(color_system="truecolor")
+    _console: Console = console
     _index = 0
     _lock = Lock()
 
@@ -205,8 +205,8 @@ class ExecutionRegistry:
             elif status.lower() in ["all", "success"]:
                 final_status = f"[{OneColors.GREEN}]✅ Success"
                 final_result = repr(ctx.result)
-                if len(final_result) > 1000:
-                    final_result = f"{final_result[:1000]}..."
+                if len(final_result) > 50:
+                    final_result = f"{final_result[:50]}..."
             else:
                 continue
 

falyx/falyx.py

@@ -507,7 +507,6 @@ class Falyx:
                 message=self.prompt,
                 multiline=False,
                 completer=self._get_completer(),
-                reserve_space_for_menu=1,
                 validator=CommandValidator(self, self._get_validator_error_message()),
                 bottom_toolbar=self._get_bottom_bar_render(),
                 key_bindings=self.key_bindings,

falyx/parser/argument.py

@@ -26,6 +26,7 @@ class Argument:
         resolver (BaseAction | None):
             An action object that resolves the argument, if applicable.
         lazy_resolver (bool): True if the resolver should be called lazily, False otherwise
+        suggestions (list[str] | None): A list of suggestions for the argument.
     """
 
     flags: tuple[str, ...]
@@ -40,6 +41,7 @@ class Argument:
     positional: bool = False
     resolver: BaseAction | None = None
     lazy_resolver: bool = False
+    suggestions: list[str] | None = None
 
     def get_positional_text(self) -> str:
         """Get the positional text for the argument."""

falyx/parser/command_argument_parser.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 from collections import defaultdict
 from copy import deepcopy
-from typing import Any, Iterable
+from dataclasses import dataclass
+from typing import Any, Iterable, Sequence
 
 from rich.console import Console
 from rich.markup import escape
@@ -19,6 +20,12 @@ from falyx.parser.utils import coerce_value
 from falyx.signals import HelpSignal
 
 
+@dataclass
+class ArgumentState:
+    arg: Argument
+    consumed: bool = False
+
+
 class CommandArgumentParser:
     """
     Custom argument parser for Falyx Commands.
@@ -64,6 +71,8 @@ class CommandArgumentParser:
         self._flag_map: dict[str, Argument] = {}
         self._dest_set: set[str] = set()
         self._add_help()
+        self._last_positional_states: dict[str, ArgumentState] = {}
+        self._last_keyword_states: dict[str, ArgumentState] = {}
 
     def _add_help(self):
         """Add help argument to the parser."""
@@ -359,19 +368,19 @@ class CommandArgumentParser:
         )
 
         self._register_argument(argument)
-        self._register_argument(negated_argument)
+        self._register_argument(negated_argument, bypass_validation=True)
 
-    def _register_argument(self, argument: Argument):
+    def _register_argument(
+        self, argument: Argument, bypass_validation: bool = False
+    ) -> None:
 
         for flag in argument.flags:
-            if (
-                flag in self._flag_map
-                and not argument.action == ArgumentAction.STORE_BOOL_OPTIONAL
-            ):
+            if flag in self._flag_map and not bypass_validation:
                 existing = self._flag_map[flag]
                 raise CommandArgumentError(
                     f"Flag '{flag}' is already used by argument '{existing.dest}'"
                 )
+
         for flag in argument.flags:
             self._flag_map[flag] = argument
             if not argument.positional:
@@ -396,6 +405,7 @@ class CommandArgumentParser:
         dest: str | None = None,
         resolver: BaseAction | None = None,
         lazy_resolver: bool = True,
+        suggestions: list[str] | None = None,
     ) -> None:
         """Add an argument to the parser.
         For `ArgumentAction.ACTION`, `nargs` and `type` determine how many and what kind
@@ -415,6 +425,8 @@ class CommandArgumentParser:
             help: A brief description of the argument.
             dest: The name of the attribute to be added to the object returned by parse_args().
             resolver: A BaseAction called with optional nargs specified parsed arguments.
+            lazy_resolver: If True, the resolver is called lazily when the argument is accessed.
+            suggestions: A list of suggestions for the argument.
         """
         expected_type = type
         self._validate_flags(flags)
@@ -445,6 +457,10 @@ class CommandArgumentParser:
                 f"Default value '{default}' not in allowed choices: {choices}"
             )
         required = self._determine_required(required, positional, nargs, action)
+        if not isinstance(suggestions, Sequence) and suggestions is not None:
+            raise CommandArgumentError(
+                f"suggestions must be a list or None, got {type(suggestions)}"
+            )
         if not isinstance(lazy_resolver, bool):
             raise CommandArgumentError(
                 f"lazy_resolver must be a boolean, got {type(lazy_resolver)}"
@@ -465,6 +481,7 @@ class CommandArgumentParser:
                 positional=positional,
                 resolver=resolver,
                 lazy_resolver=lazy_resolver,
+                suggestions=suggestions,
             )
             self._register_argument(argument)
 
@@ -490,6 +507,27 @@ class CommandArgumentParser:
             )
         return defs
 
+    def raise_remaining_args_error(
+        self, token: str, arg_states: dict[str, ArgumentState]
+    ) -> None:
+        consumed_dests = [
+            state.arg.dest for state in arg_states.values() if state.consumed
+        ]
+        remaining_flags = [
+            flag
+            for flag, arg in self._keyword.items()
+            if arg.dest not in consumed_dests and flag.startswith(token)
+        ]
+
+        if remaining_flags:
+            raise CommandArgumentError(
+                f"Unrecognized option '{token}'. Did you mean one of: {', '.join(remaining_flags)}?"
+            )
+        else:
+            raise CommandArgumentError(
+                f"Unrecognized option '{token}'. Use --help to see available options."
+            )
+
     def _consume_nargs(
         self, args: list[str], start: int, spec: Argument
     ) -> tuple[list[str], int]:
@@ -535,6 +573,7 @@ class CommandArgumentParser:
         result: dict[str, Any],
         positional_args: list[Argument],
         consumed_positional_indicies: set[int],
+        arg_states: dict[str, ArgumentState],
         from_validate: bool = False,
     ) -> int:
         remaining_positional_args = [
@@ -580,17 +619,7 @@ class CommandArgumentParser:
             except Exception as error:
                 if len(args[i - new_i :]) == 1 and args[i - new_i].startswith("-"):
                     token = args[i - new_i]
-                    valid_flags = [
-                        flag for flag in self._flag_map if flag.startswith(token)
-                    ]
-                    if valid_flags:
-                        raise CommandArgumentError(
-                            f"Unrecognized option '{token}'. Did you mean one of: {', '.join(valid_flags)}?"
-                        ) from error
-                    else:
-                        raise CommandArgumentError(
-                            f"Unrecognized option '{token}'. Use --help to see available options."
-                        ) from error
+                    self.raise_remaining_args_error(token, arg_states)
                 else:
                     raise CommandArgumentError(
                         f"Invalid value for '{spec.dest}': {error}"
@@ -606,6 +635,7 @@ class CommandArgumentParser:
                         raise CommandArgumentError(
                             f"[{spec.dest}] Action failed: {error}"
                         ) from error
+                arg_states[spec.dest].consumed = True
             elif not typed and spec.default:
                 result[spec.dest] = spec.default
             elif spec.action == ArgumentAction.APPEND:
@@ -618,8 +648,10 @@ class CommandArgumentParser:
                 assert result.get(spec.dest) is not None, "dest should not be None"
                 result[spec.dest].extend(typed)
             elif spec.nargs in (None, 1, "?"):
+                arg_states[spec.dest].consumed = True
                 result[spec.dest] = typed[0] if len(typed) == 1 else typed
             else:
+                arg_states[spec.dest].consumed = True
                 result[spec.dest] = typed
 
             if spec.nargs not in ("*", "+"):
@@ -628,15 +660,7 @@ class CommandArgumentParser:
         if i < len(args):
             if len(args[i:]) == 1 and args[i].startswith("-"):
                 token = args[i]
-                valid_flags = [flag for flag in self._flag_map if flag.startswith(token)]
-                if valid_flags:
-                    raise CommandArgumentError(
-                        f"Unrecognized option '{token}'. Did you mean one of: {', '.join(valid_flags)}?"
-                    )
-                else:
-                    raise CommandArgumentError(
-                        f"Unrecognized option '{token}'. Use --help to see available options."
-                    )
+                self.raise_remaining_args_error(token, arg_states)
             else:
                 plural = "s" if len(args[i:]) > 1 else ""
                 raise CommandArgumentError(
@@ -670,6 +694,7 @@ class CommandArgumentParser:
         positional_args: list[Argument],
         consumed_positional_indices: set[int],
         consumed_indices: set[int],
+        arg_states: dict[str, ArgumentState],
         from_validate: bool = False,
     ) -> int:
         if token in self._keyword:
@@ -679,6 +704,7 @@ class CommandArgumentParser:
             if action == ArgumentAction.HELP:
                 if not from_validate:
                     self.render_help()
+                arg_states[spec.dest].consumed = True
                 raise HelpSignal()
             elif action == ArgumentAction.ACTION:
                 assert isinstance(
@@ -691,24 +717,29 @@ class CommandArgumentParser:
                     raise CommandArgumentError(
                         f"Invalid value for '{spec.dest}': {error}"
                     ) from error
-                try:
-                    result[spec.dest] = await spec.resolver(*typed_values)
-                except Exception as error:
-                    raise CommandArgumentError(
-                        f"[{spec.dest}] Action failed: {error}"
-                    ) from error
+                if not spec.lazy_resolver or not from_validate:
+                    try:
+                        result[spec.dest] = await spec.resolver(*typed_values)
+                    except Exception as error:
+                        raise CommandArgumentError(
+                            f"[{spec.dest}] Action failed: {error}"
+                        ) from error
+                arg_states[spec.dest].consumed = True
                 consumed_indices.update(range(i, new_i))
                 i = new_i
             elif action == ArgumentAction.STORE_TRUE:
                 result[spec.dest] = True
+                arg_states[spec.dest].consumed = True
                 consumed_indices.add(i)
                 i += 1
             elif action == ArgumentAction.STORE_FALSE:
                 result[spec.dest] = False
+                arg_states[spec.dest].consumed = True
                 consumed_indices.add(i)
                 i += 1
             elif action == ArgumentAction.STORE_BOOL_OPTIONAL:
                 result[spec.dest] = spec.type(True)
+                arg_states[spec.dest].consumed = True
                 consumed_indices.add(i)
                 i += 1
             elif action == ArgumentAction.COUNT:
@@ -778,19 +809,11 @@ class CommandArgumentParser:
                     )
                 else:
                     result[spec.dest] = typed_values
+                arg_states[spec.dest].consumed = True
                 consumed_indices.update(range(i, new_i))
                 i = new_i
         elif token.startswith("-"):
-            # Handle unrecognized option
-            valid_flags = [flag for flag in self._flag_map if flag.startswith(token)]
-            if valid_flags:
-                raise CommandArgumentError(
-                    f"Unrecognized option '{token}'. Did you mean one of: {', '.join(valid_flags)}?"
-                )
-            else:
-                raise CommandArgumentError(
-                    f"Unrecognized option '{token}'. Use --help to see available options."
-                )
+            self.raise_remaining_args_error(token, arg_states)
         else:
             # Get the next flagged argument index if it exists
             next_flagged_index = -1
@@ -805,6 +828,7 @@ class CommandArgumentParser:
                 result,
                 positional_args,
                 consumed_positional_indices,
+                arg_states=arg_states,
                 from_validate=from_validate,
             )
             i += args_consumed
@@ -817,6 +841,14 @@ class CommandArgumentParser:
         if args is None:
             args = []
 
+        arg_states = {arg.dest: ArgumentState(arg) for arg in self._arguments}
+        self._last_positional_states = {
+            arg.dest: arg_states[arg.dest] for arg in self._positional.values()
+        }
+        self._last_keyword_states = {
+            arg.dest: arg_states[arg.dest] for arg in self._keyword_list
+        }
+
         result = {arg.dest: deepcopy(arg.default) for arg in self._arguments}
         positional_args: list[Argument] = [
             arg for arg in self._arguments if arg.positional
@@ -838,6 +870,7 @@ class CommandArgumentParser:
                 positional_args,
                 consumed_positional_indices,
                 consumed_indices,
+                arg_states=arg_states,
                 from_validate=from_validate,
             )
 
@@ -862,6 +895,7 @@ class CommandArgumentParser:
                 )
 
             if spec.choices and result.get(spec.dest) not in spec.choices:
+                arg_states[spec.dest].consumed = False
                 raise CommandArgumentError(
                     f"Invalid value for '{spec.dest}': must be one of {{{', '.join(spec.choices)}}}"
                 )
@@ -914,6 +948,91 @@ class CommandArgumentParser:
                 kwargs_dict[arg.dest] = parsed[arg.dest]
         return tuple(args_list), kwargs_dict
 
+    def suggest_next(self, args: list[str]) -> list[str]:
+        """
+        Suggest the next possible flags or values given partially typed arguments.
+
+        This does NOT raise errors. It is intended for completions, not validation.
+
+        Returns:
+            A list of possible completions based on the current input.
+        """
+
+        # Case 1: Next positional argument
+        next_non_consumed_positional: Argument | None = None
+        for state in self._last_positional_states.values():
+            if not state.consumed:
+                next_non_consumed_positional = state.arg
+                break
+        if next_non_consumed_positional:
+            if next_non_consumed_positional.choices:
+                return sorted(
+                    (str(choice) for choice in next_non_consumed_positional.choices)
+                )
+            if next_non_consumed_positional.suggestions:
+                return sorted(next_non_consumed_positional.suggestions)
+
+        consumed_dests = [
+            state.arg.dest
+            for state in self._last_keyword_states.values()
+            if state.consumed
+        ]
+
+        remaining_flags = [
+            flag for flag, arg in self._keyword.items() if arg.dest not in consumed_dests
+        ]
+
+        last = args[-1]
+        next_to_last = args[-2] if len(args) > 1 else ""
+        suggestions: list[str] = []
+
+        # Case 2: Mid-flag (e.g., "--ver")
+        if last.startswith("-") and last not in self._keyword:
+            if (
+                len(args) > 1
+                and next_to_last in self._keyword
+                and next_to_last in remaining_flags
+            ):
+                # If the last token is a mid-flag, suggest based on the previous flag
+                arg = self._keyword[next_to_last]
+                if arg.choices:
+                    suggestions.extend(arg.choices)
+                elif arg.suggestions:
+                    suggestions.extend(arg.suggestions)
+            else:
+                possible_flags = [
+                    flag
+                    for flag, arg in self._keyword.items()
+                    if flag.startswith(last) and arg.dest not in consumed_dests
+                ]
+                suggestions.extend(possible_flags)
+        # Case 3: Flag that expects a value (e.g., ["--tag"])
+        elif last in self._keyword:
+            arg = self._keyword[last]
+            if arg.choices:
+                suggestions.extend(arg.choices)
+            elif arg.suggestions:
+                suggestions.extend(arg.suggestions)
+        # Case 4: Last flag with choices mid-choice (e.g., ["--tag", "v"])
+        elif next_to_last in self._keyword:
+            arg = self._keyword[next_to_last]
+            if arg.choices and last not in arg.choices:
+                suggestions.extend(arg.choices)
+            elif (
+                arg.suggestions
+                and last not in arg.suggestions
+                and not any(last.startswith(suggestion) for suggestion in arg.suggestions)
+                and any(suggestion.startswith(last) for suggestion in arg.suggestions)
+            ):
+                suggestions.extend(arg.suggestions)
+            else:
+                suggestions.extend(remaining_flags)
+        # Case 5: Suggest all remaining flags
+        else:
+            suggestions.extend(remaining_flags)
+
+        return sorted(set(suggestions))
+
     def get_options_text(self, plain_text=False) -> str:
         # Options
         # Add all keyword arguments to the options list

falyx/parser/signature.py

@@ -54,8 +54,10 @@ def infer_args_from_func(
         if arg_type is bool:
             if param.default is False:
                 action = "store_true"
-            else:
+                default = None
+            elif param.default is True:
                 action = "store_false"
+                default = None
 
         if arg_type is list:
             action = "append"
@@ -75,6 +77,7 @@ def infer_args_from_func(
                 "action": action,
                 "help": metadata.get("help", ""),
                 "choices": metadata.get("choices"),
+                "suggestions": metadata.get("suggestions"),
             }
         )
 

falyx/version.py

@@ -1 +1 @@
-__version__ = "0.1.62"
+__version__ = "0.1.64"

{falyx-0.1.62.dist-info → falyx-0.1.64.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: falyx
-Version: 0.1.62
+Version: 0.1.64
 Summary: Reliable and introspectable async CLI action framework.
 License: MIT
 Author: Roland Thomas Jr

{falyx-0.1.62.dist-info → falyx-0.1.64.dist-info}/RECORD

@@ -8,7 +8,7 @@ falyx/action/action_factory.py,sha256=hxSN1PVVnsZ7mYhO0CqbFjcNBPkPRCHZ9JZ0vvwly3
 falyx/action/action_group.py,sha256=TBovifJ-HIBTBt_uBcoGXmj3MYpG8NdH37bIB5Q0e6Y,7992
 falyx/action/action_mixins.py,sha256=oUrjbweCeateshg3tqtbQiGuV8u4GvlioIZCUr9D1m4,1244
 falyx/action/action_types.py,sha256=3dT3k4c4aYcuuqcxPXPYO-YLuOqwNTApRAS9alnljoA,2392
-falyx/action/base_action.py,sha256=o9Nml70-SEVTXnu9J0-VYnO-t5wZZM0o59lYDth24Po,5829
+falyx/action/base_action.py,sha256=lSmGB7ibrxm8QHlsnvAG_ESNb5y-HTtoO_9--5j6jAI,5910
 falyx/action/chained_action.py,sha256=hAFjdUUXhPBIR8AEPV4G3tJq_tjZPrxc6Xk8we2KZNw,9981
 falyx/action/confirm_action.py,sha256=deyqeO_dYLdumkQD1Io2BajtZ9LkM6MLqTB_9UlEP-o,9385
 falyx/action/fallback_action.py,sha256=3FGWfoR1MIgY0ZkDNOpKu8p3JqPWzh5ON3943mfgDGs,1708
@@ -21,22 +21,21 @@ falyx/action/process_action.py,sha256=nUNcJD6Ms34vmj8njWzv1R1P9xJTyJmelnyJksHcp7
 falyx/action/process_pool_action.py,sha256=bBemgzB_shJfPytjbn1n6g9ScrpqrxMCujZU-I-UFf0,6152
 falyx/action/prompt_menu_action.py,sha256=PTn6US8ql5SU7ilEMVCeoGqKTc31be3AbdCfcrZ6ujU,5034
 falyx/action/save_file_action.py,sha256=Pe_j0hZjDNsO14bykzVYM0gkWB3zmpB1cExSN01IQOI,9899
-falyx/action/select_file_action.py,sha256=PcV22_wiPeDoJLIhHRiEUmW8N3pYeqQZMVTscQKXuas,9867
-falyx/action/selection_action.py,sha256=L1evMm7oAQFGMviZ8nMwFKhWKWe8X7wW6dJPHGxpqAE,15398
+falyx/action/select_file_action.py,sha256=CFHZ2PyX5YwN3R98KbBZE6KLUh2VgRGXmso5th7Gu_w,10084
+falyx/action/selection_action.py,sha256=jj62poMOIhCAQg7r8qjwqi_Ww_UTUl27n9u4WLSeWaQ,22707
 falyx/action/shell_action.py,sha256=0A_kvZLsYmeLHInMM_4Jpe8GCSnXzGBm7H9PnXPvbAs,4055
 falyx/action/signal_action.py,sha256=GxV-0zqYqODOQUa3-tvFTZ2AS1W1QpW6ExonxmWNWbs,1351
 falyx/action/user_input_action.py,sha256=Up47lumscxnhORMvaft0X-NWpxTXc2GmMZMua__pGhA,3524
 falyx/bottom_bar.py,sha256=B62N3YCQF_h2Rw_hpc2_FUuLNARI-XIGbQkg-1XvaYE,7405
 falyx/command.py,sha256=QdcwLEFIaq3a4Lfot4cV3zHbVJNQxwSpShprBgLBkh8,16891
-falyx/completer.py,sha256=EODbakx5PFAwjNcfuUZPFuSx2Q9MXBlWRZJ2LejF6DI,1686
+falyx/completer.py,sha256=tCePNM6NoVmgbDobE6HSrR34KiJ9N5GwXYL2lcdqCfk,2461
 falyx/config.py,sha256=OFEq9pFhV39o6_D7dP_QUDjqEusSQNpgomRsh5AAZYY,9621
 falyx/console.py,sha256=WIZ004R9x6DJp2g3onBQ4DOJ7iDeTOr8HqJCwRt30Rc,143
 falyx/context.py,sha256=M7iWEKto_NwI3GM-VCDPwXT0dBpFPf1Y_RvHQKodZgI,10804
 falyx/debug.py,sha256=pguI0XQcZ-7jte5YUPexAufa1oxxalYO1JgmO6GU3rI,1557
 falyx/exceptions.py,sha256=58D4BYkyJ7PlpZoNk37GsUsFThm_gIlb2Ex2XXhLklI,1099
-falyx/execution_registry.py,sha256=RLRMOEmfDElFy4tuC8L9tRyNToX7GJ4GoEBh2Iri8zo,7662
-falyx/falyx.py,sha256=6hKcD1RC-jTPA0WiF9JJ31QkacNJAJwqoqO1zhegwoM,49332
-falyx/falyx_completer.py,sha256=MsfuZXpfGwbsGG-4Zp-j-vNsNnaote-UAJkJh0s2NZI,5236
+falyx/execution_registry.py,sha256=al9x_MZN6A5aobXdNaW3HA4BjTSeRUdf9v9wYpAdtd8,7641
+falyx/falyx.py,sha256=WajWR9MZwZAno4gnXQR-RCIS4hEqiY25Egrfu6Wz2ls,49290
 falyx/hook_manager.py,sha256=TFuHQnAncS_rk6vuw-VSx8bnAppLuHfrZCrzLwqcO9o,2979
 falyx/hooks.py,sha256=xMfQROib0BNsaQF4AXJpmCiGePoE1f1xpcdibgnVZWM,2913
 falyx/init.py,sha256=fZ8cvJ9rTGOhvAiAUmA7aPw9FsOUIuobTPW3sz47My8,3287
@@ -45,12 +44,12 @@ falyx/menu.py,sha256=9kvLZhkC8PoSQvv1NZQsPIFSDy11dXfFgqVAuDmtfsM,3752
 falyx/options_manager.py,sha256=dFAnQw543tQ6Xupvh1PwBrhiSWlSACHw8K-sHP_lUh4,2842
 falyx/parser/.pytyped,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 falyx/parser/__init__.py,sha256=NbxAovKIY-duFTs6DAsdM_OzL7s3VIu19KMOmltX9ts,512
-falyx/parser/argument.py,sha256=MIKUj-hrdLDUK8xuW84_l9ms_t5CoNFpVDmxMZIbW-I,4105
+falyx/parser/argument.py,sha256=pX1qTAtsqw2qBlu8dKRdIfViNC3Pg3QZtdUb7ZTT5oc,4226
 falyx/parser/argument_action.py,sha256=Lcpb9siYr_q2T8qU-jXVtqFb11bFPPKEGH3gurJv2NM,757
-falyx/parser/command_argument_parser.py,sha256=W6vfj5acUx9wiA5TDjDO3CYlzsgGHrMM86-Gs19q-Eo,41482
+falyx/parser/command_argument_parser.py,sha256=n6yTIGuwproH0RC2ZJ1T4RNpr97OVs4kt8GxVB2pbcw,46092
 falyx/parser/parser_types.py,sha256=DLLuIXE8cAVLS41trfsNy-XJmtqSa1HfnJVAYIIc42w,315
 falyx/parser/parsers.py,sha256=vb-l_NNh5O9L98Lcafhz91flRLxC1BnW6U8JdeabRCw,14118
-falyx/parser/signature.py,sha256=fSltLEr8ctj1qpbU-OvTMnREjlb8OTG5t-guJFR7j4E,2529
+falyx/parser/signature.py,sha256=yGcd_Clcoz1YmbCgmP61MR2aNU5H6X_PhdW1fW6pvKs,2673
 falyx/parser/utils.py,sha256=GlxB1WORwoJ5XUtmmAVBUPaDV2nF9Hio7TbvNJvd8oY,3006
 falyx/prompt_utils.py,sha256=qgk0bXs7mwzflqzWyFhEOTpKQ_ZtMIqGhKeg-ocwNnE,1542
 falyx/protocols.py,sha256=vd9JL-TXdLEiAQXLw2UKLd3MUMivoG7iMLo08ZggwYQ,539
@@ -63,9 +62,9 @@ falyx/themes/__init__.py,sha256=1CZhEUCin9cUk8IGYBUFkVvdHRNNJBEFXccHwpUKZCA,284
 falyx/themes/colors.py,sha256=4aaeAHJetmeNInI0Zytg4E3YqKfPFelpf04vtjSvsS8,19776
 falyx/utils.py,sha256=U45xnZFUdoFC4xiji_9S1jHS5V7MvxSDtufP8EgB0SM,6732
 falyx/validators.py,sha256=AXpMGnk1_7J7MAbbol6pkMAiSIdNHoF5pwtA2-xS6H8,6029
-falyx/version.py,sha256=cwSKWX9cG1qs0I6C99TSkty5QpTa10uiqSeiXnsoOg0,23
-falyx-0.1.62.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
-falyx-0.1.62.dist-info/METADATA,sha256=iCnf7bzp09iDj8wsg4Lif4ef4yazOELApWRN_ZNZZqM,5561
-falyx-0.1.62.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-falyx-0.1.62.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
-falyx-0.1.62.dist-info/RECORD,,
+falyx/version.py,sha256=Ame8JILTBxkJ8UkH5av1b7AlkJlkfWE0hUqkp9JkUZs,23
+falyx-0.1.64.dist-info/LICENSE,sha256=B0yqgaHuSdhN7T3OBmgQSiDTy8HqT5Oe_dLypRe4Ra4,1073
+falyx-0.1.64.dist-info/METADATA,sha256=l6esA3CQF8YlMSXqZzoJFhUw4VhX1Hw3dtGyeq2yXk4,5561
+falyx-0.1.64.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+falyx-0.1.64.dist-info/entry_points.txt,sha256=j8owOSl2j1Ss8DtGMnKfgehKaolqnIPhVFHaUBLUnMs,45
+falyx-0.1.64.dist-info/RECORD,,

falyx/falyx_completer.py

@@ -1,128 +0,0 @@
-from collections import Counter
-from prompt_toolkit.completion import Completer, Completion
-from prompt_toolkit.document import Document
-from typing import Iterable, Set, Optional
-import shlex
-
-from falyx.command import Command
-from falyx.parser.command_argument_parser import CommandArgumentParser
-from falyx.parser.argument import Argument
-from falyx.parser.argument_action import ArgumentAction
-
-class FalyxCompleter(Completer):
-    """Completer for Falyx commands and their arguments."""
-    def __init__(self, falyx: "Falyx"):
-        self.falyx = falyx
-        self._used_args: Set[str] = set()
-        self._used_args_counter: Counter = Counter()
-
-    def get_completions(self, document: Document, complete_event) -> Iterable[Completion]:
-        text = document.text_before_cursor
-        try:
-            tokens = shlex.split(text)
-            cursor_at_end_of_token = document.text_before_cursor.endswith((' ', '\t'))
-        except ValueError:
-            return
-
-        if not tokens or (len(tokens) == 1 and not cursor_at_end_of_token):
-            # Suggest command keys and aliases
-            yield from self._suggest_commands(tokens[0] if tokens else "")
-            return
-
-        command = self._match_command(tokens[0])
-        if not command:
-            return
-
-        if command.arg_parser is None:
-            return
-
-        self._set_used_args(tokens, command)
-
-        next_arg = self._next_expected_argument(tokens, command.arg_parser)
-
-        if next_arg:
-            # Positional arguments or required flagged arguments
-            yield from self._suggest_argument(next_arg, document)
-        else:
-            # Optional arguments
-            for arg in command.arg_parser._keyword.values():
-                if not self._arg_already_used(arg.dest):
-                    yield from self._suggest_argument(arg, document)
-
-    def _set_used_args(self, tokens: list[str], command: Command) -> None:
-        """Extracts used argument flags from the provided tokens."""
-        if not command.arg_parser:
-            return
-        self._used_args.clear()
-        self._used_args_counter.clear()
-        for token in tokens[1:]:
-            if token.startswith('-'):
-                if keyword_argument := command.arg_parser._keyword.get(token):
-                    self._used_args_counter[keyword_argument.dest] += 1
-                    if isinstance(keyword_argument.nargs, int) and self._used_args_counter[keyword_argument.dest] > keyword_argument.nargs:
-                        continue
-                    elif isinstance(keyword_argument.nargs, str) and keyword_argument.nargs in ("?"):
-                        self._used_args.add(keyword_argument.dest)
-                    else:
-                        self._used_args.add(keyword_argument.dest)
-            else:
-                # Handle positional arguments
-                if command.arg_parser._positional:
-                    for arg in command.arg_parser._positional.values():
-                        if arg.dest not in self._used_args:
-                            self._used_args.add(arg.dest)
-                            break
-        print(f"Used args: {self._used_args}, Counter: {self._used_args_counter}")
-
-    def _suggest_commands(self, prefix: str) -> Iterable[Completion]:
-        prefix = prefix.upper()
-        seen = set()
-        for cmd in self.falyx.commands.values():
-            for key in [cmd.key] + cmd.aliases:
-                if key.upper().startswith(prefix) and key not in seen:
-                    yield Completion(key, start_position=-len(prefix))
-                    seen.add(key)
-
-    def _match_command(self, token: str) -> Optional[Command]:
-        token = token.lstrip("?").upper()
-        return self.falyx._name_map.get(token)
-
-    def _next_expected_argument(
-        self, tokens: list[str], parser: CommandArgumentParser
-    ) -> Optional[Argument]:
-        """Determine the next expected argument based on the current tokens."""
-        # Positional arguments first
-        for arg in parser._positional.values():
-            if arg.dest not in self._used_args:
-                return arg
-
-        # Then required keyword arguments
-        for arg in parser._keyword_list:
-            if arg.required and not self._arg_already_used(arg.dest):
-                return arg
-
-        return None
-
-    def _arg_already_used(self, dest: str) -> bool:
-        print(f"Checking if argument '{dest}' is already used: {dest in self._used_args} - Used args: {self._used_args}")
-        return dest in self._used_args
-
-    def _suggest_argument(self, arg: Argument, document: Document) -> Iterable[Completion]:
-        if not arg.positional:
-            for flag in arg.flags:
-                yield Completion(flag, start_position=0)
-
-        if arg.choices:
-            for choice in arg.choices:
-                yield Completion(
-                    choice,
-                    start_position=0,
-                    display=f"{arg.dest}={choice}"
-                )
-
-        if arg.default is not None and arg.action == ArgumentAction.STORE:
-            yield Completion(
-                str(arg.default),
-                start_position=0,
-                display=f"{arg.dest} (default: {arg.default})"
-            )