Workspace Orchestrator
Relevant source files
The following files were used as context for generating this wiki page:
The Workspace Orchestrator is a central management service within the flext-infra ecosystem designed to execute standardized automation verbs across multiple projects in a unified workspace. It abstracts the complexity of project-specific environments by routing commands—typically defined in Makefiles—to discovered workspace members or attached projects.
This system ensures operational consistency across large-scale repositories by providing a single entry point for common tasks such as linting, testing, and building. It works in conjunction with the Workspace Sync service to ensure that project-level infrastructure (like base.mk) is current before execution.
Sources: src/flext_infra/workspace/orchestrator.py, src/flext_infra/_constants/cli_routes.py:535-540
Core Architecture and Logic
The orchestration logic is primarily encapsulated in the FlextInfraOrchestratorService. This service handles the discovery, selection, and sequential execution of commands across defined project targets.
Workflow Execution Flow
The orchestrator follows a strict execution pipeline:
- Resolution: Projects are identified based on explicit selection or workspace discovery.
- Preparation: Ensures targets are synchronized and relevant environment markers are present.
- Dispatch: Sequentially executes the requested verb (e.g.,
check,test,build) via the project's nativeMakefile.
The flow ensures that every project is processed in a consistent state, leveraging the make contract defined in AGENTS.md.
Sources: src/flext_infra/workspace/orchestrator.py, tests/unit/workspace/test_main.py:61-96
Key Components and Functions
The orchestrator relies on several critical methods and data structures to manage project-level execution.
Service Methods
| Function | Description | Source |
|---|---|---|
execute() | Main entry point that orchestrates the resolved project list. | src/flext_infra/workspace/orchestrator.py |
_project_target() | Resolves the absolute path for a project, including sibling directories for attached projects. | tests/unit/workspace/test_main.py:114-124 |
_project_log_filename() | Generates a sanitized log filename for project output, typically stored under .reports/. | tests/unit/workspace/test_main.py:133-135 |
_normalize_fail_fast_make_args() | Appends FAIL_FAST=1 to make arguments to support early termination on errors. | tests/unit/workspace/test_main.py:137-141 |
Command Routing
The orchestrator is exposed via the CLI through the workspace orchestrate route. It is categorized under the WORKSPACE_ROUTES group.
Sources: src/flext_infra/_constants/cli_routes.py:535-540
Project Discovery and Selection
The orchestrator can target specific projects or the entire workspace. It distinguishes between WORKSPACE_MEMBER (internal) and ATTACHED (external) project roles.
External Sibling Patterns
The orchestrator recognizes specific directory patterns as "external siblings" managed by the FLEXT ecosystem. These include:
.ai-hubalgar-*gruponos-*
Makefile Integration and Replacements
A core responsibility of the workspace tooling is ensuring that legacy scripts are migrated to modern flext_infra equivalents within project Makefiles. The FlextInfraConstantsWorkspace defines a mapping of legacy python script calls to new infrastructure commands.
Standardized Command Mappings
| Legacy Script Call | Modern flext-infra Command |
|---|---|
scripts/mode.py | python -m flext_infra workspace detect |
scripts/sync.py | python -m flext_infra workspace sync --apply |
scripts/check/workspace_check.py | python -m flext_infra check run |
scripts/github/pr_manager.py | python3 -m flext_infra github pr |
Sources: src/flext_infra/_constants/workspace.py:34-62
Error Handling and Validation
The orchestrator validates verbs before execution to prevent improper command dispatch. Supported verbs typically include standardized quality gate targets: check, test, val, and docs. Attempting to use an unsupported verb (e.g., legacy-check) results in a failure.
Result Management
Execution results are encapsulated in m.Cli.CommandOutput objects, which track:
exit_code: Determining success or failure.stdout/stderr: Captured for logging.duration: Time taken for execution.
Sources: tests/unit/workspace/test_main.py:46-52, tests/unit/workspace/test_main.py:105-112
Summary
The Workspace Orchestrator serves as the engine for cross-project automation within the FLEXT infrastructure. By standardizing command dispatch and integrating with workspace-wide discovery, it allows developers to maintain rigorous quality standards and synchronized environments across disparate project stacks.