Create monorepo template for platform engineering with CLI/API packages and Dev Container

.devcontainer/Dockerfile

@@ -0,0 +1,20 @@
+FROM mcr.microsoft.com/devcontainers/python:3.12
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+# Install additional tools
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get -y install --no-install-recommends \
+    make \
+    curl \
+    && apt-get clean -y && rm -rf /var/lib/apt/lists/*
+
+# Set up workspace
+WORKDIR /workspace
+
+# Create a non-root user (vscode user is already created by base image)
+# Ensure proper permissions
+RUN chown -R vscode:vscode /workspace
+
+USER vscode

.devcontainer/README.md

@@ -0,0 +1,63 @@
+# Dev Container Configuration
+
+This directory contains the configuration for developing in a containerized environment using Visual Studio Code's Dev Containers feature.
+
+## What's Included
+
+### Pre-installed Tools
+- Python 3.12
+- uv package manager
+- make
+- git
+- curl
+- zsh with Oh My Zsh
+
+### VS Code Extensions
+The following extensions are automatically installed:
+- Python (Microsoft)
+- Pylance (Microsoft)
+- Ruff (Linter and Formatter)
+- Mypy Type Checker
+- Even Better TOML
+- GitHub Copilot
+
+### VS Code Settings
+Pre-configured settings for:
+- Python interpreter pointing to workspace `.venv`
+- Automatic formatting with Ruff on save
+- pytest test discovery
+- Linting and type checking integration
+
+### Port Forwarding
+- Port 8000 is automatically forwarded for the FastAPI server
+
+### Automatic Setup
+When the container is created, `uv sync` runs automatically to install all dependencies.
+
+## Usage
+
+1. Open this repository in VS Code
+2. Install the "Dev Containers" extension if you haven't already
+3. Press `F1` and select "Dev Containers: Reopen in Container"
+4. Wait for the container to build (first time only)
+5. Start coding!
+
+## Customization
+
+Edit the following files to customize your dev container:
+
+- `devcontainer.json` - Main configuration (extensions, settings, ports)
+- `Dockerfile` - Add system packages or tools
+- `docker-compose.yml` - Modify Docker Compose configuration
+
+## Benefits
+
+- **Consistent Environment**: Everyone on your team uses the same development environment
+- **No Local Setup**: No need to install Python, uv, or other tools locally
+- **Isolated**: Each project has its own containerized environment
+- **Cross-Platform**: Works identically on macOS, Linux, and Windows
+
+## Learn More
+
+- [VS Code Dev Containers Documentation](https://code.visualstudio.com/docs/devcontainers/containers)
+- [Dev Containers Tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial)

.devcontainer/devcontainer.json

@@ -0,0 +1,70 @@
+{
+  "name": "OpsCtl Development",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "devcontainer",
+  "workspaceFolder": "/workspace",
+
+  // Configure tool-specific properties
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker",
+        "tamasfe.even-better-toml",
+        "github.copilot"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/workspace/.venv/bin/python",
+        "python.terminal.activateEnvironment": true,
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["-v"],
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit",
+            "source.fixAll": "explicit"
+          }
+        },
+        "mypy-type-checker.args": [
+          "--config-file=pyproject.toml"
+        ],
+        "ruff.lint.args": [
+          "--config=pyproject.toml"
+        ]
+      }
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally
+  "forwardPorts": [8000],
+  "portsAttributes": {
+    "8000": {
+      "label": "FastAPI",
+      "onAutoForward": "notify"
+    }
+  },
+
+  // Use 'postCreateCommand' to run commands after the container is created
+  "postCreateCommand": "uv sync",
+
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root
+  "remoteUser": "vscode",
+
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": true,
+      "installOhMyZsh": true,
+      "upgradePackages": true,
+      "username": "vscode",
+      "userUid": "1000",
+      "userGid": "1000"
+    },
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "latest",
+      "ppa": true
+    }
+  }
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  devcontainer:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    volumes:
+      - ..:/workspace:cached
+    command: sleep infinity
+    network_mode: host
+    environment:
+      - PYTHONUNBUFFERED=1

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Install dependencies
+      run: uv sync
+
+    - name: Run linting
+      run: uv run ruff check .
+
+    - name: Run type checking
+      run: uv run mypy packages/cli/src packages/api/src
+
+    - name: Run tests
+      run: uv run pytest -v --cov=packages --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false

.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# uv
+.uv/
+uv.lock
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json

.python-version

@@ -0,0 +1 @@
+3.12

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing to OpsCtl
+
+Thank you for considering contributing to this project!
+
+## How to Contribute
+
+1. **Fork the repository**
+2. **Create a new branch** for your feature or bugfix
+3. **Make your changes** following our coding standards
+4. **Add tests** for your changes
+5. **Run tests and linting** to ensure everything passes
+6. **Submit a pull request**
+
+## Development Setup
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions.
+
+## Code Style
+
+This project uses:
+- **ruff** for linting and formatting
+- **mypy** for type checking
+- **pytest** for testing
+
+Before submitting a PR, ensure:
+
+```bash
+# All tests pass
+uv run pytest
+
+# Code is formatted
+uv run ruff format .
+
+# No linting errors
+uv run ruff check .
+
+# No type errors
+uv run mypy packages/cli/src packages/api/src
+```
+
+## Pull Request Guidelines
+
+- Write clear, descriptive commit messages
+- Keep PRs focused on a single feature or bugfix
+- Update documentation if needed
+- Add tests for new functionality
+- Ensure all CI checks pass
+
+## Reporting Issues
+
+When reporting issues, please include:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (OS, Python version, etc.)
+
+## Questions?
+
+Feel free to open an issue for questions or discussions!