🧰📦 provide-workenv¶

Workspace manager for the provide.io ecosystem - manages all provide-io repositories.

Overview¶

provide-workenv is the official workspace management solution for the provide.io ecosystem. It orchestrates 13+ repositories across three architectural layers (Foundation, Framework, Tools), providing a unified development environment that can be set up with three commands.

Unlike traditional monorepos or individual repository workflows, provide-workenv uses a meta-repository pattern where each package maintains its own repository while the workspace coordinates setup, dependencies, and development workflows.

Key Capabilities¶

Single-Command Setup¶

Bootstrap the entire ecosystem with automated repository cloning, dependency installation, and environment configuration:

./scripts/bootstrap.sh   # Clone all 13+ repositories
./scripts/setup.sh       # Install dependencies in correct order
./scripts/validate.sh    # Verify environment is working

Cross-Package Development¶

Make changes in one package and test immediately in dependent packages without reinstalling, thanks to editable installs:

# Edit foundation
cd provide-foundation/
# ... make changes ...

# Test in pyvider (changes immediately available!)
cd ../pyvider/
uv run pytest

Meta-Repository Pattern¶

Each package maintains its own git repository for independent releases and clear ownership, while the workspace provides: - Coordinated setup and installation - Shared virtual environment - Integrated development workflows - Cross-package testing

Reference Implementation¶

Demonstrates best practices for using wrknv to manage multi-repository workspaces. Use it as a template for your own projects.

What Gets Managed¶

provide-workenv coordinates the complete ecosystem:

Foundation Layer¶

provide-foundation: Core telemetry, logging, and infrastructure
provide-testkit: Unified testing framework

Framework Layer¶

pyvider: Core Terraform provider framework
pyvider-cty: CTY type system bindings
pyvider-hcl: HCL parsing and manipulation
pyvider-rpcplugin: gRPC plugin protocol
pyvider-components: Standard reusable components

Tools Layer¶

flavorpack: PSPF/2025 packaging system
wrknv: Work environment management
plating: Documentation generation
tofusoup: Conformance testing
supsrc: Git workflow automation

Plus Terraform providers, CI tooling, and documentation hub (provide-foundry).

Architecture¶

Workspace Structure¶

provide-workenv/
├── .venv/              # Shared virtual environment
├── scripts/
│   ├── bootstrap.sh    # Clone repositories
│   ├── setup.sh        # Install dependencies
│   └── validate.sh     # Verify environment
├── wrknv.toml          # Workspace configuration
└── tests/              # Workspace tests

../                     # Sibling directories
├── provide-foundation/
├── provide-testkit/
├── pyvider/
├── pyvider-cty/
├── pyvider-hcl/
├── pyvider-rpcplugin/
├── pyvider-components/
├── flavorpack/
├── wrknv/
├── plating/
├── tofusoup/
├── supsrc/
└── provide-foundry/

How It Works¶

bootstrap.sh reads wrknv.toml and clones/symlinks all ecosystem repositories as siblings
setup.sh creates .venv and installs packages in dependency order with editable installs
validate.sh verifies Python version, imports, and environment configuration

Changes in any package are immediately available workspace-wide without reinstalling.

Installation¶

Prerequisites¶

Python 3.11+
uv (recommended) or pip
Git
5GB+ free disk space

Quick Start¶

# Clone workspace
git clone https://github.com/provide-io/provide-workenv.git
cd provide-workenv

# Bootstrap all repositories
./scripts/bootstrap.sh

# Install dependencies
./scripts/setup.sh

# Activate environment
source .venv/bin/activate

# Validate setup
./scripts/validate.sh

That's it! You now have the complete provide.io ecosystem ready for development.

When to Use¶

Use provide-workenv When:¶

✅ New to the ecosystem (easiest onboarding) ✅ Cross-package development ✅ Contributing to multiple packages ✅ Testing integration between packages ✅ Building documentation ✅ Full ecosystem work

Use Individual Packages When:¶

✅ Working on single package only ✅ Using published packages (not developing) ✅ Building applications on framework ✅ Limited resources

Key Concepts¶

Meta-Repository Pattern¶

Coordinates multiple independent repositories without merging them into a monorepo. Each package keeps its own repository, history, and releases while the workspace provides unified setup and development workflows.

vs. Monorepo: Each package is independent with standard Git workflows vs. Individual Repos: Automated setup with cross-package development support

Editable Installs¶

All packages installed with pip install -e, meaning changes to source code are immediately reflected without reinstall. This enables seamless cross-package development.

Workspace vs Workenv¶

Workspace (.venv): Shared environment for all packages
Workenv (workenv/): Per-package isolated environment

Both can coexist for different development scenarios.

wrknv Integration¶

Built on wrknv, the work environment management tool. provide-workenv is a reference implementation showing how to use wrknv for multi-repo workspaces.

Development Workflow¶

# 1. Activate workspace
source .venv/bin/activate

# 2. Navigate to any package
cd ../pyvider/

# 3. Make changes
# ... edit files ...

# 4. Test changes (immediately available!)
uv run pytest

# 5. Format code
ruff format .

# 6. Commit (changes are auto-committed)
git push

Documentation¶

Complete documentation available at:

provide-workenv Documentation

Key sections: - Getting Started: Installation and setup - Architecture: Meta-repository pattern and design - Scripts Reference: bootstrap, setup, validate details - Development Guide: Cross-package workflows

Repository¶

Repository: provide-workenv
Type: Meta-repository (workspace manager, not a PyPI package)
License: Apache-2.0

Unique Characteristics¶

Unlike other packages in the foundry, provide-workenv: - Has no src/ directory or source code - Provides bash scripts for workspace management - Acts as coordinator for other repositories - Is not published to PyPI - Demonstrates workspace management patterns

It's the entry point for ecosystem developers, not an installable package.