cli-jaw 0.1.0

package/skills_ref/modern-python/skills/modern-python/references/ruff-config.md

@@ -0,0 +1,240 @@
+# Ruff Configuration Reference
+
+Ruff is an extremely fast Python linter and formatter written in Rust. It replaces flake8, black, isort, pyupgrade, pydocstyle, and many other tools.
+
+## Basic Setup
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",        # pydocstyle
+    "COM812",   # trailing comma (formatter conflict)
+    "ISC001",   # string concat (formatter conflict)
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+```
+
+## Running Ruff
+
+```bash
+# Lint
+uv run ruff check .
+uv run ruff check --fix .        # Auto-fix
+uv run ruff check --fix --unsafe-fixes .  # Including unsafe fixes
+
+# Format
+uv run ruff format .
+uv run ruff format --check .     # Check only
+uv run ruff format --diff .      # Show diff
+```
+
+## Rule Categories
+
+Using `select = ["ALL"]` enables all rules. Common categories:
+
+| Code | Category | Description |
+|------|----------|-------------|
+| `E`, `W` | pycodestyle | Style errors and warnings |
+| `F` | Pyflakes | Logical errors |
+| `I` | isort | Import sorting |
+| `N` | pep8-naming | Naming conventions |
+| `D` | pydocstyle | Docstring conventions |
+| `UP` | pyupgrade | Python upgrade suggestions |
+| `B` | flake8-bugbear | Bug detection |
+| `S` | flake8-bandit | Security issues |
+| `A` | flake8-builtins | Built-in shadowing |
+| `C4` | flake8-comprehensions | Comprehension improvements |
+| `DTZ` | flake8-datetimez | Timezone-aware datetime |
+| `T10` | flake8-debugger | Debugger statements |
+| `T20` | flake8-print | Print statements |
+| `PT` | flake8-pytest-style | Pytest style |
+| `Q` | flake8-quotes | Quote consistency |
+| `SIM` | flake8-simplify | Simplification suggestions |
+| `TID` | flake8-tidy-imports | Import hygiene |
+| `ARG` | flake8-unused-arguments | Unused arguments |
+| `ERA` | eradicate | Commented-out code |
+| `PL` | Pylint | Pylint rules |
+| `RUF` | Ruff-specific | Ruff's own rules |
+| `ANN` | flake8-annotations | Type annotation checks |
+
+## Recommended Ignores
+
+### Always Ignore (Formatter Conflicts)
+
+```toml
+ignore = [
+    "COM812",   # missing-trailing-comma
+    "ISC001",   # single-line-implicit-string-concatenation
+]
+```
+
+### Common Ignores
+
+```toml
+ignore = [
+    "D",        # Docstrings (enable selectively)
+    "ANN401",   # Dynamically typed Any
+    "TD002",    # Missing TODO author
+    "TD003",    # Missing TODO link
+    "FIX002",   # Line contains TODO
+]
+```
+
+## Per-File Ignores
+
+```toml
+[tool.ruff.lint.per-file-ignores]
+# Tests
+"tests/**/*.py" = [
+    "S101",     # assert usage
+    "PLR2004",  # magic values
+    "ANN",      # type annotations
+    "D",        # docstrings
+]
+
+# Scripts
+"scripts/**/*.py" = [
+    "T20",      # print statements
+    "INP001",   # implicit namespace package
+]
+
+# __init__.py
+"__init__.py" = [
+    "F401",     # unused imports (re-exports)
+]
+
+# Migrations
+"**/migrations/*.py" = [
+    "ALL",      # ignore all
+]
+```
+
+## Import Sorting (isort)
+
+```toml
+[tool.ruff.lint.isort]
+force-single-line = false
+known-first-party = ["myproject"]
+required-imports = ["from __future__ import annotations"]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+```
+
+## Docstring Style (pydocstyle)
+
+If enabling docstring checks:
+
+```toml
+[tool.ruff.lint]
+select = ["D"]
+ignore = [
+    "D100",     # Missing module docstring
+    "D104",     # Missing public package docstring
+    "D203",     # 1 blank line before class docstring (conflicts D211)
+    "D213",     # Multi-line summary second line (conflicts D212)
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"  # or "numpy", "pep257"
+```
+
+## Formatter Configuration
+
+```toml
+[tool.ruff.format]
+quote-style = "double"           # or "single"
+indent-style = "space"           # or "tab"
+skip-magic-trailing-comma = false
+line-ending = "auto"             # or "lf", "crlf"
+docstring-code-format = true
+docstring-code-line-length = 80
+```
+
+## Type Checking
+
+Ruff does NOT do type checking. Use **ty** (from Astral, the same team behind ruff and uv):
+
+```bash
+# Add ty to dev dependencies
+uv add --group dev ty
+
+# Run type checking
+uv run ty check src/
+```
+
+ty is significantly faster than mypy or pyright and integrates well with the modern Python toolchain.
+
+## CI Configuration
+
+```yaml
+# GitHub Actions
+- name: Lint
+  run: uv run ruff check --output-format=github .
+
+- name: Format check
+  run: uv run ruff format --check .
+```
+
+## Migration from Other Tools
+
+### From flake8
+
+Ruff covers most flake8 plugins. Remove:
+- flake8
+- flake8-* plugins
+- .flake8 config file
+
+### From black
+
+Remove black and use `ruff format`. Remove:
+- black
+- [tool.black] config
+
+### From isort
+
+Ruff includes isort. Remove:
+- isort
+- [tool.isort] config
+
+Use `[tool.ruff.lint.isort]` for isort settings.
+
+## Code Modernization
+
+Run pyupgrade rules to modernize syntax to your target Python version:
+
+```bash
+uv run ruff check --select=UP --fix .  # Auto-fix upgrades
+uv run ruff check --select=UP .        # Preview only
+```
+
+Common modernizations include:
+- `typing.Optional[X]` → `X | None`
+- `typing.List[X]` → `list[X]`
+- `super(ClassName, self)` → `super()`
+- Format strings and other syntax upgrades
+
+## Line Length Migration
+
+If migrating from 120 to 100 char lines, expect manual fixes.
+For less churn during initial migration, keep existing:
+
+```toml
+line-length = 120  # Match existing; tighten later
+```

package/skills_ref/modern-python/skills/modern-python/references/security-setup.md

@@ -0,0 +1,255 @@
+# Security Setup
+
+Security tooling for Python projects: pre-commit hooks, CI auditing, and dependency scanning.
+
+## Tool Installation
+
+Install these tools before running the quick setup commands below.
+
+### prek (pre-commit runner)
+
+```bash
+# Homebrew (recommended)
+brew install prek
+
+# Cargo
+cargo install prek
+
+# Standalone installer
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh
+```
+
+### Security tools
+
+Pre-commit hooks auto-install tools when run via prek. For manual CLI usage:
+
+```bash
+# Homebrew (macOS/Linux)
+brew install actionlint shellcheck
+
+# Python tools via uv
+uv tool install detect-secrets
+uv tool install zizmor
+```
+
+Alternative installation methods:
+
+- **actionlint**: `go install github.com/rhysd/actionlint/cmd/actionlint@latest`
+- **zizmor**: `cargo install zizmor`
+- **detect-secrets**: `pipx install detect-secrets`
+
+## Quick Setup
+
+```bash
+# 1. Install security hooks
+prek install
+
+# 2. Initialize secrets baseline
+detect-secrets scan > .secrets.baseline
+
+# 3. Audit existing workflows
+actionlint .github/workflows/
+zizmor .github/workflows/
+```
+
+See [templates/pre-commit-config.yaml](../templates/pre-commit-config.yaml) for a complete hook configuration.
+
+## Tool Matrix
+
+| Tool | Runs | Catches |
+|------|------|---------|
+| **shellcheck** | pre-commit | Shell script bugs, quoting issues |
+| **detect-secrets** | pre-commit | Leaked API keys, passwords, tokens |
+| **actionlint** | pre-commit, CI | Workflow syntax errors, invalid refs |
+| **zizmor** | pre-commit, CI | Workflow security issues, excessive permissions |
+| **pip-audit** | CI, manual | Known CVEs in dependencies |
+| **Dependabot** | scheduled | Outdated dependencies with vulnerabilities |
+
+## Pre-commit Hooks
+
+These run locally before each commit via prek.
+
+### shellcheck - Shell Script Linting
+
+Catches common shell scripting errors: unquoted variables, undefined variables, deprecated syntax.
+
+```yaml
+# In .pre-commit-config.yaml
+- repo: https://github.com/koalaman/shellcheck-precommit
+  rev: <latest>  # https://github.com/koalaman/shellcheck-precommit/tags
+  hooks:
+    - id: shellcheck
+      args: [--severity=error]  # Start strict, adjust if needed
+```
+
+Common findings:
+- `SC2086`: Unquoted variable expansion (word splitting risk)
+- `SC2046`: Unquoted command substitution
+- `SC2155`: Declare and assign separately to avoid masking return values
+
+### detect-secrets - Secret Detection
+
+Prevents accidentally committing API keys, passwords, and tokens.
+
+```yaml
+- repo: https://github.com/Yelp/detect-secrets
+  rev: <latest>  # https://github.com/Yelp/detect-secrets/releases
+  hooks:
+    - id: detect-secrets
+      args: [--baseline, .secrets.baseline]
+```
+
+**First-time setup:**
+
+```bash
+# Generate baseline of existing "secrets" (false positives to ignore)
+detect-secrets scan > .secrets.baseline
+
+# Review the baseline - ensure no real secrets
+cat .secrets.baseline
+
+# Commit the baseline
+git add .secrets.baseline
+```
+
+**When hook fails:**
+
+```bash
+# View the finding (non-interactive)
+detect-secrets audit --report .secrets.baseline
+```
+
+If false positive: update baseline with `detect-secrets scan --update .secrets.baseline`
+If real secret: remove from code and rotate the credential.
+
+## CI Security
+
+These run in GitHub Actions on every push/PR.
+
+### actionlint - Workflow Syntax Validation
+
+Catches syntax errors, invalid action references, and type mismatches before they fail in CI.
+
+```yaml
+- repo: https://github.com/rhysd/actionlint
+  rev: <latest>  # https://github.com/rhysd/actionlint/releases
+  hooks:
+    - id: actionlint
+```
+
+Run manually:
+
+```bash
+actionlint .github/workflows/
+```
+
+Common findings:
+- Invalid event triggers
+- Undefined workflow inputs
+- Shell syntax errors in `run:` blocks
+- Invalid action version references
+
+### zizmor - Workflow Security Audit
+
+Finds security issues in GitHub Actions workflows: excessive permissions, injection risks, untrusted inputs.
+
+```yaml
+- 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]
+```
+
+Run manually:
+
+```bash
+zizmor .github/workflows/
+```
+
+**Fixing `excessive-permissions`:**
+
+By default, workflows get `write` access to everything. Lock down with explicit permissions:
+
+```yaml
+# Read-only workflows (lint, test, audit)
+permissions:
+  contents: read
+
+# Workflows that push or create releases
+permissions:
+  contents: write
+
+# Workflows that comment on PRs
+permissions:
+  contents: read
+  pull-requests: write
+```
+
+Common findings:
+- `excessive-permissions`: No `permissions:` block
+- `template-injection`: Using `${{ github.event.* }}` unsafely
+- `unpinned-action`: Actions not pinned to SHA
+- `dangerous-triggers`: `pull_request_target` with checkout
+
+## Dependency Security
+
+### pip-audit - Vulnerability Scanning
+
+Checks installed packages against the Python Advisory Database (PyPA) for known CVEs.
+
+**Setup:**
+
+```toml
+# pyproject.toml
+[dependency-groups]
+audit = ["pip-audit"]
+```
+
+**Usage:**
+
+```bash
+# Audit current environment
+uv run pip-audit
+
+# Audit without installing (faster for CI)
+uv run pip-audit .
+
+# Fix automatically (upgrades vulnerable packages)
+uv run pip-audit --fix
+```
+
+**In CI:**
+
+```yaml
+- name: Security audit
+  run: uv run pip-audit .
+```
+
+**When vulnerabilities found:**
+
+1. Check if the CVE affects your usage (many are in unused code paths)
+2. Update the package: `uv add <package>@latest`
+3. If no fix available: evaluate risk, consider alternatives, or add to ignore list
+
+### Dependabot - Automated Updates
+
+Automatically creates PRs for outdated dependencies.
+
+Copy [templates/dependabot.yml](../templates/dependabot.yml) to `.github/dependabot.yml`.
+
+**How pip-audit and Dependabot work together:**
+
+| Tool | Trigger | Scope |
+|------|---------|-------|
+| pip-audit | Every CI run | Known CVEs in current deps |
+| Dependabot | Weekly schedule | All outdated deps, security + non-security |
+
+- **pip-audit** catches: "You have a vulnerable version right now"
+- **Dependabot** prevents: "You'll fall behind and accumulate vulnerabilities"
+
+The 7-day cooldown protects against attackers publishing malicious updates and hoping for quick adoption before detection.
+
+See [dependabot.md](./dependabot.md) for advanced configuration.
+
+See [prek.md](./prek.md) for complete pre-commit hook configuration including security hooks.