cli-jaw 0.1.0

package/skills_ref/modern-python/skills/modern-python/references/pep723-scripts.md

@@ -0,0 +1,259 @@
+# PEP 723: Inline Script Metadata
+
+PEP 723 allows embedding dependency metadata directly in Python scripts, eliminating the need for separate `requirements.txt` or `pyproject.toml` files for simple scripts.
+
+## When to Use PEP 723
+
+**Use for:**
+- Single-file scripts with external dependencies
+- Quick automation scripts
+- Utility scripts shared between projects
+- Scripts that need to be self-contained
+
+**Don't use for:**
+- Multi-file projects (use `pyproject.toml`)
+- Reusable packages/libraries
+- Projects requiring complex configuration
+
+## Basic Syntax
+
+The metadata block uses TOML format embedded in a special comment:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "requests",
+#     "rich",
+# ]
+# ///
+
+import requests
+from rich import print
+
+response = requests.get("https://api.example.com/data")
+print(response.json())
+```
+
+## Running Scripts
+
+```bash
+# With uv (recommended)
+uv run script.py
+
+# Script handles its own dependencies automatically
+./script.py  # If shebang is set
+```
+
+## Metadata Fields
+
+### Required Python Version
+
+```python
+# /// script
+# requires-python = ">=3.11"
+# ///
+```
+
+### Dependencies
+
+```python
+# /// script
+# dependencies = [
+#     "requests",
+#     "click",
+#     "rich",
+# ]
+# ///
+```
+
+### Private Package Index
+
+```python
+# /// script
+# dependencies = ["httpx"]
+#
+# [tool.uv]
+# extra-index-url = ["https://pypi.company.com/simple/"]
+# ///
+```
+
+## Complete Example
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "httpx",
+#     "rich",
+#     "typer",
+# ]
+# ///
+
+"""Fetch and display API data with nice formatting."""
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+app = typer.Typer()
+
+
+@app.command()
+def fetch(url: str, format: str = "table"):
+    """Fetch data from URL and display it."""
+    with httpx.Client() as client:
+        response = client.get(url)
+        response.raise_for_status()
+        data = response.json()
+
+    if format == "table" and isinstance(data, list):
+        table = Table()
+        if data:
+            for key in data[0].keys():
+                table.add_column(key)
+            for item in data:
+                table.add_row(*[str(v) for v in item.values()])
+        console.print(table)
+    else:
+        console.print_json(data=data)
+
+
+if __name__ == "__main__":
+    app()
+```
+
+## Creating Scripts with uv
+
+```bash
+# Create new script with metadata
+uv init --script myscript.py
+
+# Add dependency to existing script
+uv add --script myscript.py requests
+
+# Remove dependency from script
+uv remove --script myscript.py requests
+```
+
+## Shebang Options
+
+### Basic (requires uv in PATH)
+
+```python
+#!/usr/bin/env -S uv run --script
+```
+
+### With specific Python version
+
+```python
+#!/usr/bin/env -S uv run --python 3.12 --script
+```
+
+### Quiet mode (suppress uv output)
+
+```python
+#!/usr/bin/env -S uv run --quiet --script
+```
+
+## Examples by Use Case
+
+### Data Processing Script
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pandas", "openpyxl"]
+# ///
+
+import pandas as pd
+import sys
+
+df = pd.read_excel(sys.argv[1])
+print(df.describe())
+```
+
+### Web Scraping Script
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["httpx", "beautifulsoup4", "lxml"]
+# ///
+
+import httpx
+from bs4 import BeautifulSoup
+
+response = httpx.get("https://example.com")
+soup = BeautifulSoup(response.text, "lxml")
+print(soup.title.string)
+```
+
+### CLI Tool Script
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["typer", "rich"]
+# ///
+
+import typer
+from rich import print
+
+app = typer.Typer()
+
+@app.command()
+def greet(name: str):
+    print(f"[green]Hello, {name}![/green]")
+
+if __name__ == "__main__":
+    app()
+```
+
+### Async Script
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["httpx"]
+# ///
+
+import asyncio
+import httpx
+
+async def main():
+    async with httpx.AsyncClient() as client:
+        urls = ["https://api1.example.com", "https://api2.example.com"]
+        tasks = [client.get(url) for url in urls]
+        responses = await asyncio.gather(*tasks)
+        for r in responses:
+            print(r.status_code)
+
+asyncio.run(main())
+```
+
+## Best Practices
+
+1. **Always specify `requires-python`** - Ensures compatibility
+2. **Pin major versions for Python** - Use `>=3.11` not `==3.11`
+3. **Omit version constraints for dependencies** - Use `uv add --script` to add dependencies; let uv select versions
+4. **Keep scripts focused** - One script, one purpose
+5. **Add docstring** - Document what the script does
+6. **Use type hints** - Improves readability and catches errors
+
+## Limitations
+
+- No support for dependency groups
+- No support for editable installs
+- No support for local dependencies (use relative imports)
+- No lockfile (versions may vary between runs)
+
+For projects needing these features, use a full `pyproject.toml` setup instead.

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

@@ -0,0 +1,211 @@
+# prek: Fast Pre-commit Hooks
+
+[prek](https://github.com/j178/prek) is a fast, Rust-native drop-in replacement for pre-commit. It uses the same `.pre-commit-config.yaml` format and is fully compatible with existing configurations.
+
+## Why prek over pre-commit?
+
+| Feature | prek | pre-commit |
+|---------|------|------------|
+| Speed | ~7x faster hook installation | Slower |
+| Dependencies | Single binary, no runtime needed | Requires Python |
+| Disk usage | Shared toolchains between hooks | Isolated environments |
+| Parallelism | Parallel repo cloning and hook execution | Sequential |
+| Python management | Uses uv automatically | Manual Python setup |
+| Monorepo support | Built-in workspace mode | Not supported |
+
+**Already using prek:** CPython, Apache Airflow, FastAPI, Ruff, Home Assistant, and [many more](https://github.com/j178/prek#who-is-using-prek).
+
+## Installation
+
+See [security-setup.md](./security-setup.md#tool-installation) for installation options.
+
+## Quick Start
+
+### For Existing pre-commit Users
+
+prek is fully compatible with `.pre-commit-config.yaml`. Just replace commands:
+
+```bash
+# Instead of: pre-commit install
+prek install
+
+# Instead of: pre-commit run --all-files
+prek run --all-files
+
+# Instead of: pre-commit autoupdate
+prek auto-update
+```
+
+### New Setup
+
+1. Create `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: <latest>  # https://github.com/astral-sh/ruff-pre-commit/releases
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+```
+
+2. Install and run:
+
+```bash
+# Install git hooks
+prek install
+
+# Run manually on all files
+prek run --all-files
+
+# Run specific hook
+prek run ruff
+```
+
+## Configuration
+
+For a complete, copy-paste-ready configuration, see [templates/pre-commit-config.yaml](../templates/pre-commit-config.yaml).
+
+### Recommended `.pre-commit-config.yaml`
+
+> **Note:** Versions shown as `<latest>` are placeholders. Always check the linked releases for current stable versions before use.
+
+```yaml
+# See https://pre-commit.com for more information
+default_language_version:
+  python: python3.12
+
+repos:
+  # Ruff - linting and formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: <latest>  # https://github.com/astral-sh/ruff-pre-commit/releases
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # General file checks (prek builtin - faster, no external deps)
+  - repo: builtin
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-merge-conflict
+
+  # Security hooks - see security-setup.md for detailed guidance
+  # Shell script linting
+  - repo: https://github.com/koalaman/shellcheck-precommit
+    rev: <latest>  # https://github.com/koalaman/shellcheck-precommit/tags
+    hooks:
+      - id: shellcheck
+        args: [--severity=error]
+
+  # Secret detection
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: <latest>  # https://github.com/Yelp/detect-secrets/releases
+    hooks:
+      - id: detect-secrets
+        args: [--baseline, .secrets.baseline]
+
+  # GitHub Actions linting
+  - repo: https://github.com/rhysd/actionlint
+    rev: <latest>  # https://github.com/rhysd/actionlint/releases
+    hooks:
+      - id: actionlint
+
+  # GitHub Actions security audit
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: <latest>  # https://github.com/zizmorcore/zizmor-pre-commit/releases
+    hooks:
+      - id: zizmor
+        args: [--persona=regular, --min-severity=medium, --min-confidence=medium]
+```
+
+See [security-setup.md](./security-setup.md) for detailed guidance on each security hook.
+
+### Using Built-in Hooks
+
+prek includes Rust-native implementations of common hooks for extra speed:
+
+```yaml
+repos:
+  - repo: builtin
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `prek install` | Install git hooks |
+| `prek uninstall` | Remove git hooks |
+| `prek run` | Run hooks on staged files |
+| `prek run --all-files` | Run on all files |
+| `prek run --last-commit` | Run on last commit's files |
+| `prek run HOOK [HOOK...]` | Run specific hook(s) |
+| `prek run -d src/` | Run on files in directory |
+| `prek auto-update` | Update hook versions |
+| `prek list` | List configured hooks |
+| `prek clean` | Remove cached environments |
+
+## CI Configuration
+
+### GitHub Actions
+
+```yaml
+name: Pre-commit
+on: [push, pull_request]
+
+jobs:
+  prek:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@<sha>  # <latest> https://github.com/actions/checkout/releases
+      - uses: j178/prek-action@<sha>  # <latest> https://github.com/j178/prek-action/releases
+```
+
+Or manually:
+
+```yaml
+- name: Install prek
+  run: uv tool install prek
+
+- name: Run hooks
+  run: prek run --all-files
+```
+
+## Makefile Integration
+
+```makefile
+.PHONY: hooks hooks-install
+
+hooks:
+	prek run --all-files
+
+hooks-install:
+	prek install
+```
+
+## Migration from pre-commit
+
+1. Install prek: `uv tool install prek`
+2. Remove pre-commit: `pip uninstall pre-commit` or `uv tool uninstall pre-commit`
+3. Re-install hooks: `prek install`
+4. (Optional) Clean old environments: `rm -rf ~/.cache/pre-commit`
+
+Your existing `.pre-commit-config.yaml` works unchanged.
+
+## Best Practices
+
+1. **Use `prek run --all-files` in CI** - Ensures all files are checked, not just changed ones
+2. **Pin hook versions** - Use specific `rev` values, not branches
+3. **Use `--cooldown-days` for auto-update** - Mitigates supply chain attacks: `prek auto-update --cooldown-days 7`
+4. **Prefer built-in hooks** - Use `repo: builtin` for common checks (faster, offline)
+5. **Run hooks before commit** - `prek install` sets this up automatically
+6. **Initialize detect-secrets baseline** - Run `detect-secrets scan > .secrets.baseline` before first commit

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

@@ -0,0 +1,254 @@
+# pyproject.toml Configuration Reference
+
+Complete reference for configuring `pyproject.toml` for modern Python projects.
+
+**Important**: Always use `uv add` and `uv remove` to manage dependencies. Do not edit the `dependencies` or `dependency-groups` sections directly.
+
+## Complete Example
+
+```toml
+[project]
+name = "myproject"
+version = "0.1.0"
+description = "A modern Python project"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Your Name", email = "you@example.com" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "requests",
+    "rich",
+]
+
+[project.optional-dependencies]
+# Use for optional features users can install
+cli = ["typer"]
+
+[project.scripts]
+myproject = "myproject.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/org/myproject"
+Documentation = "https://myproject.readthedocs.io"
+Repository = "https://github.com/org/myproject"
+
+[build-system]
+requires = ["uv_build>=0.9,<1"]  # Use latest 0.x; check https://pypi.org/project/uv-build/
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["ruff", "ty"]
+test = ["pytest", "pytest-cov", "hypothesis"]
+docs = ["sphinx", "myst-parser"]
+
+[tool.uv]
+default-groups = ["dev", "test"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",        # pydocstyle (enable selectively)
+    "COM812",   # trailing comma (conflicts with formatter)
+    "ISC001",   # implicit string concat (conflicts with formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",     # assert allowed in tests
+    "PLR2004",  # magic values allowed in tests
+    "ANN",      # annotations optional in tests
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.pytest]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "--cov=myproject",
+    "--cov-report=term-missing",
+    "--cov-fail-under=80",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/myproject"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+```
+
+## Section Reference
+
+### [project]
+
+Core project metadata following PEP 621.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Package name (lowercase, hyphens) |
+| `version` | Yes | Semantic version |
+| `description` | No | One-line description |
+| `readme` | No | Path to README file |
+| `license` | No | SPDX license identifier |
+| `requires-python` | Recommended | Python version constraint |
+| `authors` | No | List of author dicts |
+| `dependencies` | No | Runtime dependencies |
+
+### [project.optional-dependencies]
+
+**Rarely needed.** Only use for optional *runtime* features that end users install:
+
+```toml
+[project.optional-dependencies]
+# User installs with: uv add myproject[postgres]
+postgres = ["psycopg2"]
+```
+
+**Do NOT use for dev tools**—use `[dependency-groups]` instead.
+
+### [project.scripts]
+
+Console entry points:
+
+```toml
+[project.scripts]
+myproject = "myproject.cli:main"
+myproject-serve = "myproject.server:run"
+```
+
+### [build-system]
+
+Build backend configuration. Use `uv_build` for most projects:
+
+```toml
+[build-system]
+requires = ["uv_build>=0.9,<1"]  # Use latest 0.x; check https://pypi.org/project/uv-build/
+build-backend = "uv_build"
+```
+
+`uv_build` is simpler and sufficient for most use cases. Use static versioning in `[project] version` rather than VCS-aware dynamic versioning.
+
+For flat layout (no `src/` directory), configure the module root:
+
+```toml
+[tool.uv.build-backend]
+module-root = ""
+```
+
+> **Note:** These tools evolve rapidly. Prefer `>=X.Y,<X+1` constraints to automatically get newer releases within the same major version.
+
+### [dependency-groups]
+
+Development dependencies (PEP 735). Unlike optional-dependencies, these are NOT installed by users:
+
+```toml
+[dependency-groups]
+dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
+lint = ["ruff", "ty"]
+test = ["pytest", "pytest-cov"]
+audit = ["pip-audit"]
+docs = ["sphinx", "myst-parser"]
+```
+
+Install with: `uv sync --group dev --group test`
+
+### [tool.uv]
+
+uv-specific configuration:
+
+```toml
+[tool.uv]
+# Default groups to install with `uv sync`
+default-groups = ["dev", "test"]
+
+# Python version management
+python-preference = "managed"
+```
+
+## Version Specifiers
+
+| Specifier | Meaning |
+|-----------|---------|
+| `>=1.0` | At least version 1.0 |
+| `>=1.0,<2.0` | Version 1.x only |
+| `~=1.4` | Compatible release (>=1.4, <2.0) |
+| `==1.4.*` | Any 1.4.x version |
+
+## uv.lock Handling
+
+| Project Type | uv.lock in Git? | Why |
+|--------------|-----------------|-----|
+| Application | ✅ Commit | Reproducible deploys |
+| Library | ❌ .gitignore | Users resolve their own deps |
+
+## Common Patterns
+
+### Library Package
+
+```toml
+[project]
+dependencies = []  # Minimal runtime deps
+
+[project.optional-dependencies]
+# Optional runtime features (user installs with mylib[async])
+async = ["httpx"]
+
+[dependency-groups]
+dev = ["ruff", "ty"]
+test = ["pytest", "pytest-cov"]
+```
+
+### Application Package
+
+```toml
+[project]
+dependencies = [
+    "fastapi",
+    "uvicorn",
+    "sqlalchemy",
+]
+
+[project.scripts]
+myapp = "myapp.main:run"
+
+[dependency-groups]
+dev = ["ruff", "ty", "pytest"]
+```
+
+### CLI Tool
+
+```toml
+[project]
+dependencies = [
+    "typer",
+    "rich",
+]
+
+[project.scripts]
+mytool = "mytool.cli:app"
+
+[dependency-groups]
+dev = ["ruff", "ty", "pytest"]
+```