cli-jaw 0.1.0

package/skills_ref/modern-python/README.md

@@ -0,0 +1,66 @@
+# Modern Python
+
+Modern Python tooling and best practices using uv, ruff, ty, and pytest. Based on patterns from [trailofbits/cookiecutter-python](https://github.com/trailofbits/cookiecutter-python).
+
+**Author:** William Tan
+
+## When to Use
+
+- Setting up a new Python project with modern, fast tooling
+- Replacing pip/virtualenv with uv for faster dependency management
+- Replacing flake8/black/isort with ruff for unified linting and formatting
+- Replacing mypy with ty for faster type checking
+- Adding pre-commit hooks and security scanning to an existing project
+
+## What It Covers
+
+**Core Tools:**
+- **uv** - Package/dependency management (replaces pip, virtualenv, pip-tools, pipx, pyenv)
+- **ruff** - Linting and formatting (replaces flake8, black, isort, pyupgrade)
+- **ty** - Type checking (replaces mypy, pyright)
+- **pytest** - Testing with coverage enforcement
+- **prek** - Pre-commit hooks (replaces pre-commit)
+
+**Security Tools:**
+- **shellcheck** - Shell script linting
+- **detect-secrets** - Secret detection in commits
+- **actionlint** - GitHub Actions syntax validation
+- **zizmor** - GitHub Actions security audit
+- **pip-audit** - Dependency vulnerability scanning
+- **Dependabot** - Automated dependency updates with supply chain protection
+
+**Standards:**
+- **pyproject.toml** - Single configuration file with dependency groups (PEP 735)
+- **PEP 723** - Inline script metadata for single-file scripts
+- **src/ layout** - Standard package structure
+- **Python 3.11+** - Minimum version requirement
+
+## Hook: Legacy Command Interception
+
+This plugin includes a `SessionStart` hook that prepends PATH shims for `python`, `pip`, `pipx`, and `uv`. When Claude runs a bare `python`, `pip`, or `pipx` command, the shell resolves to the shim, which prints an error with the correct `uv` alternative and exits non-zero. `uv run` is unaffected because it prepends its managed virtualenv's `bin/` to PATH, shadowing the shims.
+
+| Intercepted Command | Suggested Alternative |
+|---------------------|----------------------|
+| `python ...` | `uv run python ...` |
+| `python -m module` | `uv run python -m module` |
+| `python -m pip` | `uv add`/`uv remove` |
+| `pip install pkg` | `uv add pkg` or `uv run --with pkg` |
+| `pip uninstall pkg` | `uv remove pkg` |
+| `pip freeze` | `uv export` |
+| `uv pip ...` | `uv add`/`uv remove`/`uv sync` |
+| `pipx install <pkg>` | `uv tool install <pkg>` |
+| `pipx run <pkg>` | `uvx <pkg>` |
+| `pipx uninstall <pkg>` | `uv tool uninstall <pkg>` |
+| `pipx upgrade <pkg>` | `uv tool upgrade <pkg>` |
+| `pipx upgrade-all` | `uv tool upgrade --all` |
+| `pipx ensurepath` | `uv tool update-shell` |
+| `pipx inject <pkg> <dep>` | `uv tool install --with <dep> <pkg>` |
+| `pipx list` | `uv tool list` |
+
+Commands like `grep python`, `which python`, and `cat python.txt` work normally because `python` is a shell argument, not the command being invoked.
+
+## Installation
+
+```
+/plugin install trailofbits/skills/plugins/modern-python
+```

package/skills_ref/modern-python/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "description": "Intercept legacy Python/pip commands via PATH shims and suggest uv alternatives",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/setup-shims.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills_ref/modern-python/hooks/setup-shims.bats

@@ -0,0 +1,70 @@
+#!/usr/bin/env bats
+# Tests for setup-shims.sh SessionStart hook
+
+SETUP_SCRIPT="${BATS_TEST_DIRNAME}/setup-shims.sh"
+
+setup() {
+  export CLAUDE_ENV_FILE
+  CLAUDE_ENV_FILE="$(mktemp)"
+  # Create a fake uv so the guard passes
+  FAKE_BIN="$(mktemp -d)"
+  echo '#!/usr/bin/env bash' >"$FAKE_BIN/uv"
+  chmod +x "$FAKE_BIN/uv"
+  export FAKE_BIN
+  # Save original PATH
+  export ORIG_PATH="$PATH"
+}
+
+teardown() {
+  rm -f "$CLAUDE_ENV_FILE"
+  rm -rf "$FAKE_BIN"
+}
+
+@test "exits silently when CLAUDE_ENV_FILE is not set" {
+  run env -u CLAUDE_ENV_FILE PATH="${FAKE_BIN}:${ORIG_PATH}" \
+    bash "$SETUP_SCRIPT"
+  [[ $status -eq 0 ]]
+}
+
+@test "exits silently when uv is not available" {
+  # Remove fake uv dir from PATH; keep rest so bash/coreutils work
+  local path_without_uv=""
+  local IFS=:
+  for dir in $ORIG_PATH; do
+    [[ "$dir" == "$FAKE_BIN" ]] && continue
+    # Also skip dirs with real uv
+    [[ -x "$dir/uv" ]] && continue
+    path_without_uv="${path_without_uv:+${path_without_uv}:}$dir"
+  done
+  run env PATH="$path_without_uv" CLAUDE_ENV_FILE="$CLAUDE_ENV_FILE" \
+    bash "$SETUP_SCRIPT"
+  [[ $status -eq 0 ]]
+  [[ ! -s "$CLAUDE_ENV_FILE" ]]
+}
+
+@test "writes PATH export to CLAUDE_ENV_FILE" {
+  run env PATH="${FAKE_BIN}:${ORIG_PATH}" bash "$SETUP_SCRIPT"
+  [[ $status -eq 0 ]]
+  grep -q 'export PATH=' "$CLAUDE_ENV_FILE"
+}
+
+@test "shims dir appears in PATH export" {
+  env PATH="${FAKE_BIN}:${ORIG_PATH}" bash "$SETUP_SCRIPT"
+  local shims_dir
+  shims_dir="$(cd "${BATS_TEST_DIRNAME}/shims" && pwd)"
+  grep -q "$shims_dir" "$CLAUDE_ENV_FILE"
+}
+
+@test "shims dir is an absolute path" {
+  env PATH="${FAKE_BIN}:${ORIG_PATH}" bash "$SETUP_SCRIPT"
+  local line
+  line="$(cat "$CLAUDE_ENV_FILE")"
+  [[ "$line" =~ export\ PATH=\"/ ]]
+}
+
+@test "appends to existing CLAUDE_ENV_FILE content" {
+  echo 'export FOO=bar' >"$CLAUDE_ENV_FILE"
+  env PATH="${FAKE_BIN}:${ORIG_PATH}" bash "$SETUP_SCRIPT"
+  grep -q 'export FOO=bar' "$CLAUDE_ENV_FILE"
+  grep -q 'export PATH=' "$CLAUDE_ENV_FILE"
+}

package/skills_ref/modern-python/hooks/setup-shims.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# SessionStart hook: prepend shims directory to PATH so that bare
+# python/pip/pipx/uv-pip invocations are intercepted with uv suggestions.
+#
+# `uv run` is unaffected because it prepends its managed virtualenv's
+# bin/ to PATH, shadowing the shims.
+
+# Guard: only activate when uv is available
+command -v uv &>/dev/null || exit 0
+
+# Guard: CLAUDE_ENV_FILE must be set by the runtime
+if [[ -z "${CLAUDE_ENV_FILE:-}" ]]; then
+  echo "modern-python: CLAUDE_ENV_FILE not set; shims will not be installed" >&2
+  exit 0
+fi
+
+shims_dir="$(cd "$(dirname "$0")/shims" && pwd)" || {
+  echo "modern-python: shims directory not found" >&2
+  exit 1
+}
+
+echo "export PATH=\"${shims_dir}:\${PATH}\"" >>"$CLAUDE_ENV_FILE"

package/skills_ref/modern-python/hooks/shims/pip

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for pip/pip3 — intercepts bare invocations and
+# suggests the uv equivalent.  Works for both names via $0.
+cmd="$(basename "$0")"
+
+case "${1:-}" in
+  install)
+    echo "ERROR: Use \`uv add <package>\` instead of \`$cmd install\`" >&2
+    echo "  For one-off usage without adding to project: uv run --with <package> ..." >&2
+    ;;
+  uninstall)
+    echo "ERROR: Use \`uv remove <package>\` instead of \`$cmd uninstall\`" >&2
+    ;;
+  freeze)
+    echo "ERROR: Use \`uv export\` instead of \`$cmd freeze\`" >&2
+    ;;
+  *)
+    echo "ERROR: Use \`uv\` commands instead of \`$cmd\`" >&2
+    echo "  uv add <package>       # install a dependency" >&2
+    echo "  uv remove <package>    # remove a dependency" >&2
+    echo "  uv sync                # sync environment" >&2
+    ;;
+esac
+
+exit 1

package/skills_ref/modern-python/hooks/shims/pip-shim.bats

@@ -0,0 +1,45 @@
+#!/usr/bin/env bats
+# Tests for pip/pip3 PATH shim
+
+SHIM="${BATS_TEST_DIRNAME}/pip"
+
+@test "exits non-zero for pip install" {
+  run "$SHIM" install requests
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv add"* ]]
+}
+
+@test "suggests uv run --with for one-off usage" {
+  run "$SHIM" install requests
+  [[ "$output" == *"uv run --with"* ]]
+}
+
+@test "exits non-zero for pip uninstall" {
+  run "$SHIM" uninstall requests
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv remove"* ]]
+}
+
+@test "exits non-zero for pip freeze" {
+  run "$SHIM" freeze
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv export"* ]]
+}
+
+@test "exits non-zero for bare pip" {
+  run "$SHIM"
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv"* ]]
+}
+
+@test "exits non-zero for pip show" {
+  run "$SHIM" show requests
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv"* ]]
+}
+
+@test "works when invoked as pip3 via symlink" {
+  run "${BATS_TEST_DIRNAME}/pip3" install foo
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv add"* ]]
+}

package/skills_ref/modern-python/hooks/shims/pip3

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for pip/pip3 — intercepts bare invocations and
+# suggests the uv equivalent.  Works for both names via $0.
+cmd="$(basename "$0")"
+
+case "${1:-}" in
+  install)
+    echo "ERROR: Use \`uv add <package>\` instead of \`$cmd install\`" >&2
+    echo "  For one-off usage without adding to project: uv run --with <package> ..." >&2
+    ;;
+  uninstall)
+    echo "ERROR: Use \`uv remove <package>\` instead of \`$cmd uninstall\`" >&2
+    ;;
+  freeze)
+    echo "ERROR: Use \`uv export\` instead of \`$cmd freeze\`" >&2
+    ;;
+  *)
+    echo "ERROR: Use \`uv\` commands instead of \`$cmd\`" >&2
+    echo "  uv add <package>       # install a dependency" >&2
+    echo "  uv remove <package>    # remove a dependency" >&2
+    echo "  uv sync                # sync environment" >&2
+    ;;
+esac
+
+exit 1

package/skills_ref/modern-python/hooks/shims/pipx

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for pipx — intercepts bare invocations and
+# suggests the uv tool equivalent.
+
+case "${1:-}" in
+  install)
+    echo "ERROR: Use \`uv tool install <package>\` instead of \`pipx install\`" >&2
+    ;;
+  uninstall)
+    echo "ERROR: Use \`uv tool uninstall <package>\` instead of \`pipx uninstall\`" >&2
+    ;;
+  run)
+    echo "ERROR: Use \`uvx <package>\` instead of \`pipx run\`" >&2
+    ;;
+  upgrade)
+    echo "ERROR: Use \`uv tool upgrade <package>\` instead of \`pipx upgrade\`" >&2
+    ;;
+  upgrade-all)
+    echo "ERROR: Use \`uv tool upgrade --all\` instead of \`pipx upgrade-all\`" >&2
+    ;;
+  ensurepath)
+    echo "ERROR: Use \`uv tool update-shell\` instead of \`pipx ensurepath\`" >&2
+    ;;
+  inject)
+    echo "ERROR: Use \`uv tool install --with <dep> <package>\` instead of \`pipx inject\`" >&2
+    ;;
+  list)
+    echo "ERROR: Use \`uv tool list\` instead of \`pipx list\`" >&2
+    ;;
+  *)
+    echo "ERROR: Use \`uv tool\` commands instead of \`pipx\`" >&2
+    echo "  uv tool install <package>   # install a CLI tool" >&2
+    echo "  uv tool uninstall <package> # uninstall a CLI tool" >&2
+    echo "  uvx <package>               # run a tool without installing" >&2
+    echo "  uv tool list                # list installed tools" >&2
+    ;;
+esac
+
+exit 1

package/skills_ref/modern-python/hooks/shims/pipx-shim.bats

@@ -0,0 +1,64 @@
+#!/usr/bin/env bats
+# Tests for pipx PATH shim
+
+SHIM="${BATS_TEST_DIRNAME}/pipx"
+
+@test "exits non-zero for pipx install" {
+  run "$SHIM" install black
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool install"* ]]
+}
+
+@test "exits non-zero for pipx uninstall" {
+  run "$SHIM" uninstall black
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool uninstall"* ]]
+}
+
+@test "exits non-zero for pipx run" {
+  run "$SHIM" run black
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uvx"* ]]
+}
+
+@test "exits non-zero for pipx upgrade" {
+  run "$SHIM" upgrade black
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool upgrade"* ]]
+}
+
+@test "exits non-zero for pipx inject" {
+  run "$SHIM" inject black click
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool install --with"* ]]
+}
+
+@test "exits non-zero for pipx list" {
+  run "$SHIM" list
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool list"* ]]
+}
+
+@test "exits non-zero for pipx upgrade-all" {
+  run "$SHIM" upgrade-all
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool upgrade --all"* ]]
+}
+
+@test "exits non-zero for pipx ensurepath" {
+  run "$SHIM" ensurepath
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool update-shell"* ]]
+}
+
+@test "exits non-zero for bare pipx" {
+  run "$SHIM"
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool"* ]]
+}
+
+@test "exits non-zero for unknown pipx subcommand" {
+  run "$SHIM" completions
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv tool"* ]]
+}

package/skills_ref/modern-python/hooks/shims/python

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for python/python3 — intercepts bare invocations and
+# suggests the uv equivalent.  Works for both names via $0.
+cmd="$(basename "$0")"
+
+case "${1:-}" in
+  -m)
+    case "${2:-}" in
+      pip)
+        echo "ERROR: \`$cmd -m pip\` is not supported. Use:" >&2
+        echo "  uv add <package>       # add a dependency" >&2
+        echo "  uv remove <package>    # remove a dependency" >&2
+        ;;
+      *)
+        echo "ERROR: Use \`uv run $cmd -m ${2:-<module>}\` instead of \`$cmd -m ${2:-<module>}\`" >&2
+        ;;
+    esac
+    ;;
+  *)
+    echo "ERROR: Use \`uv run $cmd ${*:-}\` instead of \`$cmd ${*:-}\`" >&2
+    ;;
+esac
+
+exit 1

package/skills_ref/modern-python/hooks/shims/python-shim.bats

@@ -0,0 +1,53 @@
+#!/usr/bin/env bats
+# Tests for python/python3 PATH shim
+
+SHIM="${BATS_TEST_DIRNAME}/python"
+
+@test "exits non-zero for bare python" {
+  run "$SHIM"
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python"* ]]
+}
+
+@test "exits non-zero for python script.py" {
+  run "$SHIM" script.py
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python script.py"* ]]
+}
+
+@test "exits non-zero for python -c" {
+  run "$SHIM" -c 'print(1)'
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python"* ]]
+}
+
+@test "exits non-zero for python -m pytest" {
+  run "$SHIM" -m pytest
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python -m pytest"* ]]
+}
+
+@test "exits non-zero for python -m pip install" {
+  run "$SHIM" -m pip install requests
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv add"* ]]
+  [[ "$output" == *"uv remove"* ]]
+}
+
+@test "suggests uv run python -m <module> for arbitrary modules" {
+  run "$SHIM" -m http.server
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python -m http.server"* ]]
+}
+
+@test "works when invoked as python3 via symlink" {
+  run "${BATS_TEST_DIRNAME}/python3"
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv run python3"* ]]
+}
+
+@test "python3 -m pip suggests uv add" {
+  run "${BATS_TEST_DIRNAME}/python3" -m pip install foo
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv add"* ]]
+}

package/skills_ref/modern-python/hooks/shims/python3

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for python/python3 — intercepts bare invocations and
+# suggests the uv equivalent.  Works for both names via $0.
+cmd="$(basename "$0")"
+
+case "${1:-}" in
+  -m)
+    case "${2:-}" in
+      pip)
+        echo "ERROR: \`$cmd -m pip\` is not supported. Use:" >&2
+        echo "  uv add <package>       # add a dependency" >&2
+        echo "  uv remove <package>    # remove a dependency" >&2
+        ;;
+      *)
+        echo "ERROR: Use \`uv run $cmd -m ${2:-<module>}\` instead of \`$cmd -m ${2:-<module>}\`" >&2
+        ;;
+    esac
+    ;;
+  *)
+    echo "ERROR: Use \`uv run $cmd ${*:-}\` instead of \`$cmd ${*:-}\`" >&2
+    ;;
+esac
+
+exit 1

package/skills_ref/modern-python/hooks/shims/uv

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PATH shim for uv — intercepts `uv pip` (legacy interface) and passes
+# everything else through to the real uv binary.
+
+if [[ "${1:-}" == "pip" ]]; then
+  echo "ERROR: \`uv pip\` is the legacy interface. Use instead:" >&2
+  echo "  uv add <package>       # instead of uv pip install" >&2
+  echo "  uv remove <package>    # instead of uv pip uninstall" >&2
+  echo "  uv sync                # instead of uv pip sync" >&2
+  exit 1
+fi
+
+# Find the real uv by skipping this shim's directory in PATH
+shim_dir="$(cd "$(dirname "$0")" && pwd)"
+IFS=: read -ra path_entries <<<"${PATH:-}"
+for dir in "${path_entries[@]}"; do
+  resolved="$(cd "$dir" 2>/dev/null && pwd)" || continue
+  [[ "$resolved" == "$shim_dir" ]] && continue
+  if [[ -x "$dir/uv" ]]; then
+    exec "$dir/uv" "$@"
+  fi
+done
+
+echo "ERROR: real uv binary not found on PATH" >&2
+exit 127

package/skills_ref/modern-python/hooks/shims/uv-shim.bats

@@ -0,0 +1,47 @@
+#!/usr/bin/env bats
+# Tests for uv PATH shim
+# Requires: nix shell nixpkgs#uv -c bats ...
+
+SHIM="${BATS_TEST_DIRNAME}/uv"
+
+setup() {
+  command -v uv &>/dev/null || skip "uv not available — run via: nix shell nixpkgs#uv -c bats ..."
+}
+
+@test "exits non-zero for uv pip install" {
+  run "$SHIM" pip install requests
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv add"* ]]
+}
+
+@test "exits non-zero for uv pip sync" {
+  run "$SHIM" pip sync
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv sync"* ]]
+}
+
+@test "exits non-zero for uv pip freeze" {
+  run "$SHIM" pip freeze
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"legacy"* ]]
+}
+
+@test "suggests uv remove for uv pip uninstall" {
+  run "$SHIM" pip uninstall foo
+  [[ $status -ne 0 ]]
+  [[ "$output" == *"uv remove"* ]]
+}
+
+@test "passes through to real uv for non-pip subcommands" {
+  run "$SHIM" --version
+  [[ $status -eq 0 ]]
+  [[ "$output" == *"uv"* ]]
+}
+
+@test "exits 127 with error when real uv is not found" {
+  # Include /usr/bin for coreutils but exclude dirs with a real uv
+  local path_no_uv="${BATS_TEST_DIRNAME}:/usr/bin:/bin"
+  run env PATH="$path_no_uv" "$SHIM" --version
+  [[ $status -eq 127 ]]
+  [[ "$output" == *"real uv binary not found"* ]]
+}