Workspace Automation Scripts
Relevant source files
The following files were used as context for generating this wiki page:
The Workspace Automation Scripts in FLEXT provide a centralized, pyproject-first mechanism for managing a multi-package Python monorepo. These scripts facilitate core operational tasks including documentation generation, quality gate enforcement, Docker infrastructure standardization, and automated dependency management across all flext-* packages.
The system is designed to enforce architectural consistency and "Continuous Green" status by routing all execution through a canonical command surface (primarily make verbs). This ensures that every build, test, and validation action follows the project's governance laws and avoids ad-hoc tool invocations.
Sources: README.md:27-33, AGENTS.md:57-65, pyproject.toml:75-79
Canonical Command Surface
The automation system utilizes a make-based dispatch surface to coordinate complex workflows across the workspace. This surface abstracts underlying Python scripts and ensures that all operations run with standard guards and dry-run semantics.
Primary Command Verbs
| Command | Domain | Description |
|---|---|---|
make boot | Infrastructure | Initializes the workspace environment and virtual environments. |
make check | Quality | Runs linting, formatting, and static analysis (Ruff, Pyright, Mypy). |
make test | Validation | Executes unit, integration, and E2E tests for specific projects. |
make docs | Documentation | Orchestrates the full documentation pipeline (generate, audit, build). |
make ship | Release | Manages commits, tagging, and PR creation across submodules. |
Sources: AGENTS.md:195-204, scripts/maintenance/README.md:21-34
Documentation Automation Pipeline
FLEXT documentation is managed through a "pyproject-first" approach where package metadata is derived directly from pyproject.toml. The automation pipeline is implemented in flext-infra and follows a specific lifecycle.
Documentation Phases
The make build WHAT=docs command supports several phases controlled by the DOCS_PHASE variable:
- Generate: Extracts API reference from public exports and docstrings.
- Fix: Automatically corrects documentation issues (requires
FIX=1). - Audit/Validate: Performs Markdown linting and ensures compliance with workspace standards.
- Build: Compiles the final documentation portal.
Sources: scripts/maintenance/README.md:11-34, README.md:27-31
Docker Standardization and Quality Gates
A significant portion of the automation logic is dedicated to maintaining Docker infrastructure health. The scripts/cmd/check/docker_standardization.py script enforces centralization of all Docker artifacts under the docker/ directory to prevent fragmentation.
Validation Logic
The standardization checker performs nine distinct audits:
- Centralization: Verifies that no
docker-compose.ymlorDockerfileexists outside allowed paths (docker/anddocker/images/). - Tooling Availability: Ensures the
tk(Docker management API) and centralized fixtures are importable fromflext_tests. - Script Prohibition: Identifies and flags prohibited Docker-related shell scripts outside the central management folder.
- Count Enforcement: Validates that at least 15 compose files and 20 Dockerfiles are present in the central repository.
The diagram shows the sequence of quality gates applied to Docker infrastructure within the workspace.
Sources: scripts/cmd/check/docker_standardization.py:53-157, docker/README.md:200-215
Workspace Management and Maintenance
Automated Dependency Merging
The scripts/workspace/dependabot_merge.py script automates the merging of Dependabot PRs across all submodules. It enforces a conventional commit schema to maintain a clean history: chore(deps): bump <package> <old> → <new> [<ecosystem>].
It handles conflicts by attempting to update the PR branch (rebase/merge) before failing, and can optionally close stale PRs that cannot be cleanly resolved.
Sources: scripts/workspace/dependabot_merge.py:11-133
Cross-Project Commits (Ship/Save)
The scripts/cmd/ship/save.py script facilitates atomic updates across multiple git submodules. It:
- Discovers modified repositories in the workspace.
- Stages modified, deleted, and untracked files.
- Creates commits with a unified message across all selected projects and the root repository.
Sources: scripts/cmd/ship/save.py:46-95
Workspace Orchestration Flow
The following diagram illustrates how the automation scripts coordinate between the root workspace and subprojects during a release or save operation.
This diagram represents the flow of the save automation script as it iterates through sub-packages.
Sources: scripts/cmd/ship/save.py:80-118
Summary of Automation Features
| Feature | Script / Tool | Enforcement Level |
|---|---|---|
| Commit Standardization | ship/save.py | Required for multi-package sync |
| Docker Management | tk API | Mandatory for all tests |
| Dependency Updates | dependabot_merge.py | Automated via GitHub Actions |
| Doc Consistency | flext-infra | Checked via make build WHAT=docs |
| Gate Enforcement | check/docker_standardization.py | Pre-commit / CI gate |
Sources: scripts/cmd/check/docker_standardization.py:15-25, docker/README.md:144-150, AGENTS.md:57-65
Workspace Automation Scripts serve as the primary glue for the FLEXT monorepo, ensuring that despite the project's distributed nature across multiple sub-packages, it remains a single, cohesive, and "continuously green" engineering environment. All technical actions are governed by the AGENTS.md law and executed via the standardized command surface.