feat(core): centralize command execution and add standalone command runner

- add CommandExecutor to unify shared command execution lifecycle
  across Falyx and standalone command execution
- add CommandRunner for running a single Command directly as a CLI
  or programmatic entrypoint
- add Command.build() factory and rename parse_args() to resolve_args()
  to clarify the parsing-to-execution boundary
- introduce ExecutionOption and wire execution-scoped flags into
  CommandArgumentParser and Command construction
- refactor Falyx to use FalyxParser/ParseResult and CommandExecutor
  instead of the older argparse-based flow and run_key path
- simplify __main__.py bootstrap by building a bootstrap Falyx instance
  directly and running flx.run()
- improve completer support for preview commands and unique-prefix
  command resolution
- default BottomBar toggle namespace to "default"
- expand module/class docstrings to reflect the new execution architecture

tests/test_completer/test_completer.py

@@ -1,57 +1,65 @@
-from types import SimpleNamespace
-
 import pytest
 from prompt_toolkit.completion import Completion
 from prompt_toolkit.document import Document
 
+from falyx import Falyx
 from falyx.completer import FalyxCompleter
+from falyx.parser import CommandArgumentParser
 
 
 @pytest.fixture
-def fake_falyx():
-    fake_arg_parser = SimpleNamespace(
-        suggest_next=lambda tokens, end: ["--tag", "--name", "value with space"]
+def falyx():
+    flx = Falyx()
+    parser = CommandArgumentParser(
+        command_key="R",
+        command_description="Run Command",
     )
-    fake_command = SimpleNamespace(key="R", aliases=["RUN"], arg_parser=fake_arg_parser)
-    return SimpleNamespace(
-        exit_command=SimpleNamespace(key="X", aliases=["EXIT"]),
-        help_command=SimpleNamespace(key="H", aliases=["HELP"]),
-        history_command=SimpleNamespace(key="Y", aliases=["HISTORY"]),
-        commands={"R": fake_command},
-        _name_map={"R": fake_command, "RUN": fake_command, "X": fake_command},
+    parser.add_argument(
+        "--tag",
     )
+    parser.add_argument(
+        "--name",
+    )
+    flx.add_command(
+        "R",
+        "Run Command",
+        lambda x: None,
+        aliases=["RUN"],
+        arg_parser=parser,
+    )
+    return flx
 
 
-def test_suggest_commands(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_suggest_commands(falyx):
+    completer = FalyxCompleter(falyx)
     completions = list(completer._suggest_commands("R"))
     assert any(c.text == "R" for c in completions)
     assert any(c.text == "RUN" for c in completions)
 
 
-def test_suggest_commands_empty(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_suggest_commands_empty(falyx):
+    completer = FalyxCompleter(falyx)
     completions = list(completer._suggest_commands(""))
     assert any(c.text == "X" for c in completions)
     assert any(c.text == "H" for c in completions)
 
 
-def test_suggest_commands_no_match(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_suggest_commands_no_match(falyx):
+    completer = FalyxCompleter(falyx)
     completions = list(completer._suggest_commands("Z"))
     assert not completions
 
 
-def test_get_completions_no_input(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_no_input(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document("")
     results = list(completer.get_completions(doc, None))
     assert any(isinstance(c, Completion) for c in results)
     assert any(c.text == "X" for c in results)
 
 
-def test_get_completions_no_match(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_no_match(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document("Z")
     completions = list(completer.get_completions(doc, None))
     assert not completions
@@ -60,38 +68,38 @@ def test_get_completions_no_match(fake_falyx):
     assert not completions
 
 
-def test_get_completions_partial_command(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_partial_command(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document("R")
     results = list(completer.get_completions(doc, None))
     assert any(c.text in ("R", "RUN") for c in results)
 
 
-def test_get_completions_with_flag(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_with_flag(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document("R ")
     results = list(completer.get_completions(doc, None))
     assert "--tag" in [c.text for c in results]
 
 
-def test_get_completions_partial_flag(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_partial_flag(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document("R --t")
     results = list(completer.get_completions(doc, None))
     assert all(c.start_position <= 0 for c in results)
     assert any(c.text.startswith("--t") or c.display == "--tag" for c in results)
 
 
-def test_get_completions_bad_input(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
+def test_get_completions_bad_input(falyx):
+    completer = FalyxCompleter(falyx)
     doc = Document('R "unclosed quote')
     results = list(completer.get_completions(doc, None))
     assert results == []
 
 
-def test_get_completions_exception_handling(fake_falyx):
-    completer = FalyxCompleter(fake_falyx)
-    fake_falyx.commands["R"].arg_parser.suggest_next = lambda *args: 1 / 0
+def test_get_completions_exception_handling(falyx):
+    completer = FalyxCompleter(falyx)
+    falyx.commands["R"].arg_parser.suggest_next = lambda *args: 1 / 0
     doc = Document("R --tag")
     results = list(completer.get_completions(doc, None))
     assert results == []