roland/falyx
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

falyx-parser #5

Merged
roland merged 7 commits from falyx-parser into main 2026-06-07 13:13:11 -04:00
Conversation 0 Commits 7 Files Changed 126 +17942 -2651
roland commented 2026-06-07 13:12:20 -04:00
Owner
Copy Link

Summary

This PR completes a major Falyx runtime refactor focused on command execution, routed parsing, reusable command/action binding, and standalone command execution.

Key changes include:

  • Add CommandExecutor as the shared execution engine for resolved commands
  • Add CommandRunner for running a single Command outside a full Falyx app
  • Add Command.build() and Command.clone_with_overrides() as the canonical command construction and rebinding paths
  • Add clone() support across BaseAction implementations so commands can be safely reused without mutating original action instances
  • Replace legacy argparse bootstrap flow with native Falyx commands in __main__.py
  • Introduce execution options for command-scoped runtime behavior such as summary, retry, and confirmation flags
  • Add InvocationContext and styled display segments for context-aware usage/help/TLDR rendering
  • Add routed completion state via CompletionRoute and improve namespace-aware completions
  • Split root, namespace, and execution option state using OptionsManager namespaces
  • Improve structured parser/user-facing errors with hints and short-usage support
  • Update examples to cover namespace options, command runners, TLDR examples, grouped arguments, mutex groups, and execution options
  • Refresh module docstrings, copyright years, and terminology around concurrent execution

Why

Falyx now has a cleaner separation of concerns:

  • Falyx owns routing
  • Command owns argument resolution and command-local behavior
  • CommandExecutor owns shared execution lifecycle
  • CommandRunner owns standalone single-command execution
  • OptionsManager owns scoped runtime state

This makes command behavior more consistent across CLI mode, menu mode, nested namespaces, previews, help rendering, and standalone command runners.

Notable Behavior Changes

  • Commands registered from existing Command instances are cloned and rebound to the receiving runtime.
  • CommandRunner.from_command() also clones the provided command before binding runner-specific state.
  • Root options, namespace options, and execution overrides are applied through separate option namespaces.
  • Help, usage, and TLDR output now preserve routed invocation context.
  • Completion now routes through namespace parsing before delegating to command-local completion.
  • Falyx bootstrap commands now use native Falyx command registration instead of argparse subparsers.
## Summary This PR completes a major Falyx runtime refactor focused on command execution, routed parsing, reusable command/action binding, and standalone command execution. Key changes include: - Add `CommandExecutor` as the shared execution engine for resolved commands - Add `CommandRunner` for running a single `Command` outside a full `Falyx` app - Add `Command.build()` and `Command.clone_with_overrides()` as the canonical command construction and rebinding paths - Add `clone()` support across `BaseAction` implementations so commands can be safely reused without mutating original action instances - Replace legacy argparse bootstrap flow with native Falyx commands in `__main__.py` - Introduce execution options for command-scoped runtime behavior such as summary, retry, and confirmation flags - Add `InvocationContext` and styled display segments for context-aware usage/help/TLDR rendering - Add routed completion state via `CompletionRoute` and improve namespace-aware completions - Split root, namespace, and execution option state using `OptionsManager` namespaces - Improve structured parser/user-facing errors with hints and short-usage support - Update examples to cover namespace options, command runners, TLDR examples, grouped arguments, mutex groups, and execution options - Refresh module docstrings, copyright years, and terminology around concurrent execution ## Why Falyx now has a cleaner separation of concerns: - `Falyx` owns routing - `Command` owns argument resolution and command-local behavior - `CommandExecutor` owns shared execution lifecycle - `CommandRunner` owns standalone single-command execution - `OptionsManager` owns scoped runtime state This makes command behavior more consistent across CLI mode, menu mode, nested namespaces, previews, help rendering, and standalone command runners. ## Notable Behavior Changes - Commands registered from existing `Command` instances are cloned and rebound to the receiving runtime. - `CommandRunner.from_command()` also clones the provided command before binding runner-specific state. - Root options, namespace options, and execution overrides are applied through separate option namespaces. - Help, usage, and TLDR output now preserve routed invocation context. - Completion now routes through namespace parsing before delegating to command-local completion. - Falyx bootstrap commands now use native Falyx command registration instead of argparse subparsers.
roland added 7 commits 2026-06-07 13:12:20 -04:00
feat(core): centralize command execution and add standalone command runner 5d8f3aa603 
- 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
feat: add recursive namespace routing and standalone runner polish 30cb8b97b5 
- introduce namespace-aware routing with RootParseResult, RouteResult, and InvocationContext
- register submenus as FalyxNamespace entries and resolve them through _entry_map
- refactor FalyxParser to parse only root options and leave recursive routing to Falyx
- add prepare_route, resolve_route, and route dispatch flow to Falyx
- update validator and completer to understand namespace entries and route results
- unify help/TLDR rendering APIs and add custom_tldr support on Command
- tighten Command.resolve_args error handling and parser type validation
- improve CommandRunner dependency validation and argv handling
- add BottomBar.has_items and improve wrapped executor error messages
- add tests for execution options, resolve_args, command runner, and route-aware validation
feat(help): add invocation-aware path rendering for nested CLI help 8ece2a5de6 
- introduce InvocationContext and InvocationSegment for styled invocation paths
- thread invocation_context through command arg resolution and help/tldr rendering
- render CLI and namespace help from routed context instead of static program formatting
- support per-segment styling for nested namespaces and command paths
- rebase help target context for `help -k` so usage matches the target command path
- clean up context module docs and remove old invocation path formatting helper
refactor: make completer routing-aware for namespaces dcec792d32 
- route completions through resolve_completion_route instead of one-level command lookup
- add CompletionRoute to model partial completion state
- suggest namespace entries and namespace-level help/TLDR flags while routing
- delegate leaf argv completion to CommandArgumentParser after command resolution
- restore LCP completion behavior with deduping and flag-safe handling
- add namespace completion name iteration and TLDR example support to Falyx
- update completer and completion route documentation
refactor: align routing internals and refresh framework docstrings cce92cca09 
- rename several Falyx and Command internal helpers with leading underscores
- rename parallel terminology to concurrent across ActionGroup and SharedContext
- update completer and routing references to match current routed API names
- add and revise module, class, and method docstrings across core modules
- refresh package copyright headers for 2026
feat(core): advance options/state handling and workflow execution integration 8db7a9e6dc 
- extend OptionsManager to support multi-namespace option resolution and toggling
- integrate OptionsManager more deeply across Action, ChainedAction, and ActionGroup
- propagate shared runtime configuration through execution layers
- refine action composition model (sequential + parallel execution semantics)
- improve lifecycle consistency across BaseAction, Action, ChainedAction, and ActionGroup
- begin aligning execution flow with centralized context and options handling

wip: routing and root option parsing behavior still in progress
feat(core): clone commands and actions when binding runtimes efe3f5fd99 
Add clone support across Action types and Command so commands can be safely
registered or runner-bound without mutating the original instances.

- clone BaseAction implementations across simple, composite, IO, prompt, file,
  HTTP, process, and signal actions
- bind cloned commands in Falyx.add_command_from_command() and CommandRunner
- preserve local never_prompt settings when cloning actions
- rename shared runtime state from options to options_manager for consistency
- seed root and execution option namespaces consistently
- apply scoped root and namespace option overrides during routing and dispatch
- improve namespace completion by delegating option suggestions to FalyxParser
- enrich missing-value errors and error hints
roland merged commit 27929df27a into main 2026-06-07 13:13:11 -04:00
roland deleted branch falyx-parser 2026-06-07 13:13:11 -04:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
roland
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: roland/falyx#5
No description provided.
Delete Branch "falyx-parser"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?