Skip to content

Quick Start

Fast-track setup for provide-workenv in three commands.

Prerequisites

Ensure you have:

  • Python 3.11+
  • uv
  • Git
  • 5GB free disk space

See full prerequisites if any are missing.

Setup (3 Commands)

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

# 2. Bootstrap all repositories (~5-10 min)
./scripts/bootstrap.sh

# 3. Install dependencies (~3-5 min)
./scripts/setup.sh

Activate & Validate

# Activate the environment
source .venv/bin/activate

# Verify everything works
./scripts/validate.sh

Expected output:

✓ Python 3.11.5
✓ Virtual environment is active
✓ All packages imported successfully
All checks passed! ✓

Test It

# Test an import
python3 -c "import pyvider; print(f'pyvider {pyvider.__version__}')"

# Run a test
cd pyvider/
uv run pytest tests/ -k "test_version"

What You Have Now

  • 13+ repositories cloned as siblings to provide-workenv/
  • Shared .venv with all packages installed in editable mode
  • Cross-package development enabled - changes in one package immediately available in others

Workspace Layout

parent-directory/
├── provide-workenv/      # ← Workspace manager (you are here)
│   ├── .venv/            # ← Shared virtual environment
│   ├── scripts/          # ← bootstrap.sh, setup.sh, validate.sh
│   └── wrknv.toml        # ← Workspace configuration
│
├── provide-foundation/   # Foundation layer
├── provide-testkit/
│
├── pyvider/              # Framework layer
├── pyvider-cty/
├── pyvider-hcl/
├── pyvider-rpcplugin/
├── pyvider-components/
│
├── flavorpack/           # Tools layer
├── wrknv/
├── plating/
├── tofusoup/
├── supsrc/
│
└── provide-foundry/      # Documentation hub

Next Steps

Make Your First Change

# 1. Navigate to a package
cd pyvider/

# 2. Open in your editor
code .  # or vim, emacs, etc.

# 3. Edit a file in src/
# Changes are immediately available!

# 4. Test your changes
uv run pytest

# 5. Format code
ruff format .

Explore the Documentation

cd provide-foundry/
make docs-serve
# Visit http://localhost:11000

Run Tests Across Packages

# Test a single package
cd pyvider/
uv run pytest

# Test with coverage
uv run pytest --cov=src --cov-report=html

# Test integration
cd pyvider/
uv run pytest tests/integration/

Common Commands

# Activate environment (run from anywhere)
source /path/to/provide-workenv/.venv/bin/activate

# Update all repositories
cd provide-workenv/
for dir in ../*/; do (cd "$dir" && git pull); done

# Reinstall dependencies
./scripts/setup.sh

# Validate setup
./scripts/validate.sh

Troubleshooting Quick Fixes

Import Error

source .venv/bin/activate
./scripts/setup.sh

Permission Denied

chmod +x scripts/*.sh

Missing Repositories

./scripts/bootstrap.sh  # Safe to re-run

Outdated Dependencies

./scripts/setup.sh  # Reinstalls all packages

Need More Details?

One-Liner Setup

For the bold:

git clone https://github.com/provide-io/provide-workenv.git && \
cd provide-workenv && \
./scripts/bootstrap.sh && \
./scripts/setup.sh && \
source .venv/bin/activate && \
./scripts/validate.sh

(Not recommended for first-time setup - better to run commands individually to catch issues early.)