cli-jaw 0.1.0

package/skills_ref/modern-python/skills/modern-python/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: modern-python
+description: Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
+---
+
+# Modern Python
+
+Guide for modern Python tooling and best practices, based on [trailofbits/cookiecutter-python](https://github.com/trailofbits/cookiecutter-python).
+
+## When to Use This Skill
+
+- Creating a new Python project or package
+- Setting up `pyproject.toml` configuration
+- Configuring development tools (linting, formatting, testing)
+- Writing Python scripts with external dependencies
+- Migrating from legacy tools (when user requests it)
+
+## When NOT to Use This Skill
+
+- **User wants to keep legacy tooling**: Respect existing workflows if explicitly requested
+- **Python < 3.11 required**: These tools target modern Python
+- **Non-Python projects**: Mixed codebases where Python isn't primary
+
+## Anti-Patterns to Avoid
+
+| Avoid | Use Instead |
+|-------|-------------|
+| `[tool.ty]` python-version | `[tool.ty.environment]` python-version |
+| `uv pip install` | `uv add` and `uv sync` |
+| Editing pyproject.toml manually to add deps | `uv add <pkg>` / `uv remove <pkg>` |
+| `hatchling` build backend | `uv_build` (simpler, sufficient for most cases) |
+| Poetry | uv (faster, simpler, better ecosystem integration) |
+| requirements.txt | PEP 723 for scripts, pyproject.toml for projects |
+| mypy / pyright | ty (faster, from Astral team) |
+| `[project.optional-dependencies]` for dev tools | `[dependency-groups]` (PEP 735) |
+| Manual virtualenv activation (`source .venv/bin/activate`) | `uv run <cmd>` |
+| pre-commit | prek (faster, no Python runtime needed) |
+
+**Key principles:**
+- Always use `uv add` and `uv remove` to manage dependencies
+- Never manually activate or manage virtual environments—use `uv run` for all commands
+- Use `[dependency-groups]` for dev/test/docs dependencies, not `[project.optional-dependencies]`
+
+## Decision Tree
+
+```
+What are you doing?
+│
+├─ Single-file script with dependencies?
+│   └─ Use PEP 723 inline metadata (./references/pep723-scripts.md)
+│
+├─ New multi-file project (not distributed)?
+│   └─ Minimal uv setup (see Quick Start below)
+│
+├─ New reusable package/library?
+│   └─ Full project setup (see Full Setup below)
+│
+└─ Migrating existing project?
+    └─ See Migration Guide below
+```
+
+## Tool Overview
+
+| Tool | Purpose | Replaces |
+|------|---------|----------|
+| **uv** | Package/dependency management | pip, virtualenv, pip-tools, pipx, pyenv |
+| **ruff** | Linting AND formatting | flake8, black, isort, pyupgrade, pydocstyle |
+| **ty** | Type checking | mypy, pyright (faster alternative) |
+| **pytest** | Testing with coverage | unittest |
+| **prek** | Pre-commit hooks ([setup](./references/prek.md)) | pre-commit (faster, Rust-native) |
+
+### Security Tools
+
+| Tool | Purpose | When It Runs |
+|------|---------|--------------|
+| **shellcheck** | Shell script linting | pre-commit |
+| **detect-secrets** | Secret detection | pre-commit |
+| **actionlint** | Workflow syntax validation | pre-commit, CI |
+| **zizmor** | Workflow security audit | pre-commit, CI |
+| **pip-audit** | Dependency vulnerability scanning | CI, manual |
+| **Dependabot** | Automated dependency updates | scheduled |
+
+See [security-setup.md](./references/security-setup.md) for configuration and usage.
+
+## Quick Start: Minimal Project
+
+For simple multi-file projects not intended for distribution:
+
+```bash
+# Create project with uv
+uv init myproject
+cd myproject
+
+# Add dependencies
+uv add requests rich
+
+# Add dev dependencies
+uv add --group dev pytest ruff ty
+
+# Run code
+uv run python src/myproject/main.py
+
+# Run tools
+uv run pytest
+uv run ruff check .
+```
+
+## Full Project Setup
+If starting from scratch, ask the user if they prefer to use the Trail of Bits cookiecutter template to bootstrap a complete project with already preconfigured tooling.
+
+```bash
+uvx cookiecutter gh:trailofbits/cookiecutter-python
+```
+
+### 1. Create Project Structure
+
+```bash
+uv init --package myproject
+cd myproject
+```
+
+This creates:
+```
+myproject/
+├── pyproject.toml
+├── README.md
+├── src/
+│   └── myproject/
+│       └── __init__.py
+└── .python-version
+```
+
+### 2. Configure pyproject.toml
+
+See [pyproject.md](./references/pyproject.md) for complete configuration reference.
+
+Key sections:
+```toml
+[project]
+name = "myproject"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = []
+
+[dependency-groups]
+dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
+lint = ["ruff", "ty"]
+test = ["pytest", "pytest-cov"]
+audit = ["pip-audit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D", "COM812", "ISC001"]
+
+[tool.pytest]
+addopts = ["--cov=myproject", "--cov-fail-under=80"]
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+# Strict from day 1 for new projects
+possibly-unresolved-reference = "error"
+unused-ignore-comment = "warn"
+```
+
+### 3. Install Dependencies
+
+```bash
+# Install all dependency groups
+uv sync --all-groups
+
+# Or install specific groups
+uv sync --group dev
+```
+
+### 4. Add Makefile
+
+```makefile
+.PHONY: dev lint format test build
+
+dev:
+	uv sync --all-groups
+
+lint:
+	uv run ruff format --check && uv run ruff check && uv run ty check src/
+
+format:
+	uv run ruff format .
+
+test:
+	uv run pytest
+
+build:
+	uv build
+```
+
+## Migration Guide
+
+When a user requests migration from legacy tooling:
+
+### From requirements.txt + pip
+
+First, determine the nature of the code:
+
+**For standalone scripts**: Convert to PEP 723 inline metadata (see [pep723-scripts.md](./references/pep723-scripts.md))
+
+**For projects**:
+```bash
+# Initialize uv in existing project
+uv init --bare
+
+# Add dependencies using uv (not by editing pyproject.toml)
+uv add requests rich  # add each package
+
+# Or import from requirements.txt (review each package before adding)
+# Note: Complex version specifiers may need manual handling
+grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
+    uv add "$pkg" || echo "Failed to add: $pkg"
+done
+
+uv sync
+```
+
+Then:
+1. Delete `requirements.txt`, `requirements-dev.txt`
+2. Delete virtual environment (`venv/`, `.venv/`)
+3. Add `uv.lock` to version control
+
+### From setup.py / setup.cfg
+
+1. Run `uv init --bare` to create pyproject.toml
+2. Use `uv add` to add each dependency from `install_requires`
+3. Use `uv add --group dev` for dev dependencies
+4. Copy non-dependency metadata (name, version, description, etc.) to `[project]`
+5. Delete `setup.py`, `setup.cfg`, `MANIFEST.in`
+
+### From flake8 + black + isort
+
+1. Remove flake8, black, isort via `uv remove`
+2. Delete `.flake8`, `pyproject.toml [tool.black]`, `[tool.isort]` configs
+3. Add ruff: `uv add --group dev ruff`
+4. Add ruff configuration (see [ruff-config.md](./references/ruff-config.md))
+5. Run `uv run ruff check --fix .` to apply fixes
+6. Run `uv run ruff format .` to format
+
+### From mypy / pyright
+
+1. Remove mypy/pyright via `uv remove`
+2. Delete `mypy.ini`, `pyrightconfig.json`, or `[tool.mypy]`/`[tool.pyright]` sections
+3. Add ty: `uv add --group dev ty`
+4. Run `uv run ty check src/`
+
+## Quick Reference: uv Commands
+
+| Command | Description |
+|---------|-------------|
+| `uv init` | Create new project |
+| `uv init --package` | Create distributable package |
+| `uv add <pkg>` | Add dependency |
+| `uv add --group dev <pkg>` | Add to dependency group |
+| `uv remove <pkg>` | Remove dependency |
+| `uv sync` | Install dependencies |
+| `uv sync --all-groups` | Install all dependency groups |
+| `uv run <cmd>` | Run command in venv |
+| `uv run --with <pkg> <cmd>` | Run with temporary dependency |
+| `uv build` | Build package |
+| `uv publish` | Publish to PyPI |
+
+### Ad-hoc Dependencies with `--with`
+
+Use `uv run --with` for one-off commands that need packages not in your project:
+
+```bash
+# Run Python with a temporary package
+uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"
+
+# Run a module with temporary deps
+uv run --with rich python -m rich.progress
+
+# Multiple packages
+uv run --with requests --with rich python script.py
+
+# Combine with project deps (adds to existing venv)
+uv run --with httpx pytest  # project deps + httpx
+```
+
+**When to use `--with` vs `uv add`:**
+- `uv add`: Package is a project dependency (goes in pyproject.toml/uv.lock)
+- `--with`: One-off usage, testing, or scripts outside a project context
+
+See [uv-commands.md](./references/uv-commands.md) for complete reference.
+
+## Quick Reference: Dependency Groups
+
+```toml
+[dependency-groups]
+dev = ["ruff", "ty"]
+test = ["pytest", "pytest-cov", "hypothesis"]
+docs = ["sphinx", "myst-parser"]
+```
+
+Install with: `uv sync --group dev --group test`
+
+## Best Practices Checklist
+
+- [ ] Use `src/` layout for packages
+- [ ] Set `requires-python = ">=3.11"`
+- [ ] Configure ruff with `select = ["ALL"]` and explicit ignores
+- [ ] Use ty for type checking
+- [ ] Enforce test coverage minimum (80%+)
+- [ ] Use dependency groups instead of extras for dev tools
+- [ ] Add `uv.lock` to version control
+- [ ] Use PEP 723 for standalone scripts
+
+## Read Next
+
+- [migration-checklist.md](./references/migration-checklist.md) - Step-by-step migration cleanup
+- [pyproject.md](./references/pyproject.md) - Complete pyproject.toml reference
+- [uv-commands.md](./references/uv-commands.md) - uv command reference
+- [ruff-config.md](./references/ruff-config.md) - Ruff linting/formatting configuration
+- [testing.md](./references/testing.md) - pytest and coverage setup
+- [pep723-scripts.md](./references/pep723-scripts.md) - PEP 723 inline script metadata
+- [prek.md](./references/prek.md) - Fast pre-commit hooks with prek
+- [security-setup.md](./references/security-setup.md) - Security hooks and dependency scanning
+- [dependabot.md](./references/dependabot.md) - Automated dependency updates

package/skills_ref/modern-python/skills/modern-python/references/dependabot.md

@@ -0,0 +1,43 @@
+# Dependabot: Automated Dependency Updates
+
+[Dependabot](https://docs.github.com/en/code-security/dependabot) automatically creates pull requests to keep your dependencies up to date. GitHub hosts it natively—no external service required.
+
+## Why Use Dependabot?
+
+- **Security**: Automatically patches known vulnerabilities
+- **Freshness**: Keeps dependencies current without manual tracking
+- **Visibility**: PRs show changelogs and compatibility notes
+
+## Configuration
+
+Copy [templates/dependabot.yml](../templates/dependabot.yml) to `.github/dependabot.yml`.
+
+The template includes:
+- Weekly update schedule for pip and GitHub Actions
+- 7-day cooldown for supply chain protection
+- Grouping to reduce PR noise
+
+## Supply Chain Protection
+
+The `cooldown.default-days: 7` setting delays updates for newly published versions. This provides time for the community to detect compromised packages before they reach your project.
+
+**Why this matters:**
+- Attackers sometimes publish malicious versions of legitimate packages
+- A 7-day delay allows time for detection and removal
+- Combined with weekly schedules, this balances security with freshness
+
+## Common Options
+
+| Option | Description |
+|--------|-------------|
+| `interval` | `daily`, `weekly`, or `monthly` |
+| `cooldown.default-days` | Days to wait before updating new releases |
+| `ignore` | Skip specific dependencies or versions |
+| `groups` | Group related updates into single PRs |
+| `reviewers` | Auto-assign reviewers to PRs |
+
+## See Also
+
+- [GitHub Dependabot docs](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)
+- [security-setup.md](./security-setup.md) - Security tooling overview
+- [prek.md](./prek.md) - Pre-commit hooks (complementary tool)

package/skills_ref/modern-python/skills/modern-python/references/migration-checklist.md

@@ -0,0 +1,141 @@
+# Migration Checklist
+
+Comprehensive checklist for migrating Python projects to modern tooling.
+
+## Before Migration
+
+- [ ] **Determine layout**: `src/` or flat? Configure `[tool.uv.build-backend]` if flat
+- [ ] **Decide uv.lock strategy**: app (commit) vs library (.gitignore)
+- [ ] **Backup current state**: Create a branch or tag before starting
+
+## Cleanup Old Artifacts
+
+Find and remove legacy linter comments:
+
+```bash
+# Find files with old linter pragmas
+rg "# pylint:|# noqa:|# type: ignore" --files-with-matches
+
+# Find missing __init__.py files
+uv run ruff check --select=INP001 .
+```
+
+Remove these files after migration:
+- [ ] `requirements.txt`, `requirements-dev.txt`
+- [ ] `setup.py`, `setup.cfg`, `MANIFEST.in`
+- [ ] `.flake8`, `mypy.ini`, `pyrightconfig.json`
+- [ ] `tox.ini` (if not needed)
+- [ ] `Pipfile`, `Pipfile.lock`
+- [ ] Old virtual environments (`venv/`, `.venv/`)
+
+## .gitignore Updates
+
+Add these entries:
+
+```gitignore
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+
+# Tools
+.ruff_cache/
+.ty/
+
+# uv (for libraries only - apps should commit uv.lock)
+# uv.lock
+```
+
+## pyproject.toml Sections to Remove
+
+- [ ] `[tool.black]`
+- [ ] `[tool.isort]`
+- [ ] `[tool.mypy]`
+- [ ] `[tool.pyright]`
+- [ ] `[tool.pylint]`
+- [ ] `[tool.flake8]` (if present)
+
+## Post-Migration Easy Wins
+
+Run these to modernize code automatically:
+
+```bash
+# Pyupgrade modernization (typing, syntax)
+uv run ruff check --select=UP --fix .
+
+# Unnecessary variable assignments before return
+uv run ruff check --select=RET504 --fix .
+
+# Simplifications (conditionals, comprehensions)
+uv run ruff check --select=SIM --fix .
+
+# Remove commented-out code
+uv run ruff check --select=ERA --fix .
+```
+
+## CI Cleanup
+
+- [ ] Remove scheduled CI triggers (activity without progress is theater)
+- [ ] Update CI to use `uv sync` and `uv run`
+- [ ] Pin GitHub Actions to SHA hashes
+- [ ] Set up security tooling (see [security-setup.md](./security-setup.md))
+
+## Gradual ty Adoption
+
+For legacy codebases with many type errors, start lenient:
+
+```toml
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.ty.environment]
+python-version = "3.11"
+
+[tool.ty.rules]
+# Start with these ignored for legacy codebases
+possibly-missing-attribute = "ignore"
+unresolved-import = "ignore"
+invalid-argument-type = "ignore"
+not-subscriptable = "ignore"
+unresolved-attribute = "ignore"
+```
+
+Remove rules as you fix errors. Track progress:
+
+```bash
+# Count remaining issues
+uv run ty check src/ 2>&1 | grep -c "error"
+```
+
+## Supply Chain Security
+
+- [ ] Add pip-audit to dependency groups
+- [ ] Configure Dependabot with 7-day cooldown
+- [ ] Pin exact versions in production (`==` not `>=`)
+
+See [security-setup.md](./security-setup.md) for pip-audit and Dependabot configuration.
+
+## Verification
+
+After migration, verify everything works:
+
+```bash
+# Install all dependencies
+uv sync --all-groups
+
+# Run linting
+uv run ruff check .
+uv run ruff format --check .
+
+# Run type checking
+uv run ty check src/
+
+# Run tests
+uv run pytest
+
+# Security audit
+uv run pip-audit
+
+# Build package (if distributable)
+uv build
+```