devstuff 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

dev_setup/cli.py

@@ -1,12 +1,13 @@
 import click
 
-from dev_setup import __version__
+from dev_setup import __version__, verbose
 
 
 @click.group(
     invoke_without_command=True,
     context_settings={"help_option_names": ["-h", "--help"]},
 )
+@verbose.option
 @click.pass_context
 def cli(ctx: click.Context) -> None:
     if ctx.invoked_subcommand is None:
@@ -54,5 +55,31 @@ def _register_commands() -> None:
     cli.add_command(skills_cmd, "skills")
     cli.add_command(agent_cmd, "agent")
 
+    _add_verbose_option(cli)
+
+
+def _add_verbose_option(group: click.Group) -> None:
+    """Give every command and subcommand `-v`/`-vv`, recursively.
+
+    Done centrally rather than by decorating each command so that the flag is accepted
+    everywhere it could plausibly be typed — `devstuff -v install x`, `devstuff install
+    -v x`, `devstuff functions -v enable k` all work, and no command can be forgotten.
+    Aliases (`remove`/`uninstall`) share one Command object, hence the seen-set.
+    """
+    seen: set[int] = set()
+
+    def walk(cmd: click.Command) -> None:
+        if id(cmd) in seen:
+            return
+        seen.add(id(cmd))
+        if not any("--verbose" in p.opts for p in cmd.params):
+            verbose.option(cmd)
+        if isinstance(cmd, click.Group):
+            for sub in cmd.commands.values():
+                walk(sub)
+
+    for command in group.commands.values():
+        walk(command)
+
 
 _register_commands()

dev_setup/commands/install_cmd.py

@@ -11,13 +11,9 @@ from dev_setup.base import Tool
 
 
 @click.command("install")
-@click.option("--verbose", "-v", is_flag=True, help="Stream install output to the terminal.")
 @click.argument("packages", nargs=-1)
-def install_cmd(packages: tuple[str, ...], verbose: bool) -> None:
+def install_cmd(packages: tuple[str, ...]) -> None:
     """Install packages. Interactive picker when called with no arguments."""
-    from dev_setup import generic
-    generic._verbose = verbose
-
     if not packages:
         _install_interactive()
     else:

dev_setup/commands/remove_cmd.py

@@ -9,13 +9,9 @@ from dev_setup.base import Tool
 
 
 @click.command("remove")
-@click.option("--verbose", "-v", is_flag=True, help="Stream removal output to the terminal.")
 @click.argument("packages", nargs=-1)
-def remove_cmd(packages: tuple[str, ...], verbose: bool) -> None:
+def remove_cmd(packages: tuple[str, ...]) -> None:
     """Uninstall installed packages."""
-    from dev_setup import generic
-    generic._verbose = verbose
-
     if not packages:
         ui.error("Specify at least one package key. See: devstuff list --installed")
         sys.exit(1)

dev_setup/commands/run_cmd.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
+import subprocess
 import sys
 
 import click
 
 from dev_setup import function_runner as runner
-from dev_setup import functions_registry, ui
+from dev_setup import functions_registry, ui, verbose
 from dev_setup.function_runner import ParamResolutionError
 from dev_setup.functions_registry import FunctionDef, FunctionParam
 
@@ -20,6 +21,8 @@ def run_cmd(key: str, args: tuple[str, ...]) -> None:
         ui.error(f"Unknown function: '{key}'")
         sys.exit(1)
 
+    verbose.trace(f"function '{fn.key}': type={fn.type} register={fn.register} args={list(args)}")
+
     if fn.type == "script":
         _run_script(fn, args)
     elif fn.type == "shell-eval" and fn.register == "eval":
@@ -49,6 +52,12 @@ def _run_script(fn: FunctionDef, args: tuple[str, ...]) -> None:
     except ParamResolutionError as exc:
         ui.error(str(exc))
         sys.exit(1)
+    except subprocess.CalledProcessError as exc:
+        # devstuff's own exit code is always 1 here (a function can't signal a result
+        # through it), so the script's real exit code is only visible under -v.
+        ui.error(f"'{fn.name}' failed: {exc}")
+        verbose.log(f"'{fn.key}' exited {exc.returncode}")
+        sys.exit(1)
     except Exception as exc:
         ui.error(f"'{fn.name}' failed: {exc}")
         sys.exit(1)

dev_setup/commands/update_cmd.py

@@ -12,17 +12,13 @@ from dev_setup.generic import UpdateStatus
 
 
 @click.command("update")
-@click.option("--verbose", "-v", is_flag=True, help="Stream update output to the terminal.")
 @click.option(
     "--version", "target_version", default=None,
     help="Update to a specific version instead of latest. Only valid with a single package.",
 )
 @click.argument("packages", nargs=-1)
-def update_cmd(packages: tuple[str, ...], verbose: bool, target_version: str | None) -> None:
+def update_cmd(packages: tuple[str, ...], target_version: str | None) -> None:
     """Update packages. Interactive picker with recommended updates when called with no arguments."""
-    from dev_setup import generic
-    generic._verbose = verbose
-
     if not packages:
         if target_version:
             ui.error("--version requires a package key.")

dev_setup/function_runner.py

@@ -6,6 +6,7 @@ import subprocess
 import tempfile
 from collections.abc import Callable
 
+from dev_setup import verbose
 from dev_setup.base import patch_bashrc, remove_bashrc_block
 from dev_setup.functions_registry import FunctionDef, FunctionParam
 
@@ -70,7 +71,12 @@ def render_eval_script(fn: FunctionDef, args: tuple[str, ...]) -> str:
     clean for `eval "$(...)"` capture, so missing required params raise instead."""
     values = resolve_params(fn.params, args)
     prelude = _literal_prelude(fn.params, values)
-    return f"{prelude}\n{fn.script}" if prelude else fn.script
+    script = f"{prelude}\n{fn.script}" if prelude else fn.script
+    # Logged, never traced with `set -x`: this text is evaluated by the *caller's*
+    # interactive shell, where enabling xtrace would persist after the function returns.
+    verbose.log(f"eval script for '{fn.key}':")
+    verbose.block(script, minimum=verbose.VERBOSE)
+    return script
 
 
 def _bashrc_prelude(fn: FunctionDef) -> list[str]:
@@ -106,7 +112,10 @@ def render_bashrc_function(fn: FunctionDef) -> str:
 
 
 def enable_bashrc_function(fn: FunctionDef) -> bool:
-    return patch_bashrc(f"devstuff-fn:{fn.key}", render_bashrc_function(fn))
+    block = render_bashrc_function(fn)
+    verbose.log(f"patching ~/.bashrc with devstuff-fn:{fn.key}")
+    verbose.block(block)
+    return patch_bashrc(f"devstuff-fn:{fn.key}", block)
 
 
 def disable_bashrc_function(fn: FunctionDef) -> bool:
@@ -137,13 +146,25 @@ def run_script_function(
     with tempfile.NamedTemporaryFile(mode="w", suffix=".sh", delete=False) as f:
         f.write(content)
         tmp = f.name
+
+    # `bash -x` at -vv traces every expanded command inside the function to stderr.
+    # A function is an opaque blob of someone else's shell until you can see that;
+    # `capture` mode gets it too, since the trace lands in the returned text.
+    cmd = ["bash", *(["-x"] if verbose.enabled(verbose.TRACE) else []), tmp, *values]
+    verbose.command(cmd)
+    verbose.trace(f"params: {_describe_params(fn.params, values)}")
+    verbose.block(content)
     try:
         if capture:
-            proc = subprocess.run(
-                ["bash", tmp, *values], check=True, capture_output=True, text=True
-            )
+            proc = subprocess.run(cmd, check=True, capture_output=True, text=True)
             return ((proc.stdout or "") + (proc.stderr or "")).strip()
-        subprocess.run(["bash", tmp, *values], check=True)
+        subprocess.run(cmd, check=True)
         return None
     finally:
         os.unlink(tmp)
+
+
+def _describe_params(params: list[FunctionParam], values: list[str]) -> str:
+    if not params:
+        return "(none)"
+    return "  ".join(f"{p.name}={v!r}" for p, v in zip(params, values, strict=True))

dev_setup/functions.yaml

@@ -88,6 +88,135 @@ functions:
       pi -p "/dogfood $url $instruction"
     docs_url: https://pi.dev/docs/latest
 
+  whats-on-port:
+    name: What's On This Port
+    description: Find which process is listening on a port (and whether you can see it)
+    category: network
+    type: script
+    params:
+      - name: port
+        description: Port number to look up (1-65535)
+        required: true
+      - name: protocol
+        description: tcp, udp, or all (default all)
+        required: false
+        default: all
+    script: |
+      # Deliberately no `set -e`: this script's whole job is to tell "in use" from
+      # "free" from "cannot tell", which is exit-code work that -e would abort.
+      set -uo pipefail
+
+      case "$port" in
+        ''|*[!0-9]*)
+          echo "Port must be a number between 1 and 65535, got: ${port:-<empty>}" >&2
+          exit 2
+          ;;
+      esac
+      if [ "$port" -lt 1 ] || [ "$port" -gt 65535 ]; then
+        echo "Port must be between 1 and 65535, got: $port" >&2
+        exit 2
+      fi
+
+      case "${protocol:-all}" in
+        tcp) flags="-tlpnH" ;;
+        udp) flags="-ulpnH" ;;
+        all|"") flags="-tulpnH"; protocol="all" ;;
+        *) echo "Protocol must be tcp, udp or all, got: $protocol" >&2; exit 2 ;;
+      esac
+
+      # ss ships in iproute2, which is not in the devstuff catalog and is not on every
+      # minimal image (this repo's own CI container has lsof but no ss), so say what to
+      # install rather than letting "command not found" surface.
+      if ! command -v ss >/dev/null 2>&1; then
+        echo "ss is required to look up sockets (it is part of iproute2)." >&2
+        echo "Install it with:  sudo apt-get install -y iproute2" >&2
+        exit 1
+      fi
+
+      # `ss` exits 0 whether or not the filter matched anything, so an empty result is
+      # the only signal that the port is free.
+      sockets="$(ss $flags "sport = :$port" 2>/dev/null || true)"
+
+      # Unprivileged `ss` still lists a socket owned by another user but silently drops
+      # the users:((...)) field, so the port reads as taken with nothing named. Retry
+      # under sudo only when it needs no password — a diagnostic should not stop to ask
+      # for one. (lsof and fuser are worse here: both report *nothing* and exit as if
+      # the port were free, which is why this uses ss.)
+      escalated=""
+      if [ -n "$sockets" ] && ! printf '%s' "$sockets" | grep -q 'pid='; then
+        if [ "$(id -u)" -ne 0 ] && command -v sudo >/dev/null 2>&1 && sudo -n true 2>/dev/null; then
+          sockets="$(sudo -n ss $flags "sport = :$port" 2>/dev/null || printf '%s' "$sockets")"
+          escalated="yes"
+        fi
+      fi
+
+      # "Nothing found" is an answer, not a failure: `devstuff run` flattens every
+      # non-zero code to 1, so exiting non-zero here would only buy a scary "command
+      # failed" banner under a correct result. Non-zero is kept for the cases where
+      # the lookup could not be performed at all (bad input, no ss).
+      if [ -z "$sockets" ]; then
+        echo "Nothing is listening on port $port ($protocol)."
+        echo
+        echo "A bind can still fail after this: a container port published without the"
+        echo "userland proxy is forwarded by NAT with no host socket to find, and sockets"
+        echo "in another network namespace are invisible from here."
+        if [ "$(id -u)" -ne 0 ]; then
+          echo "Sockets you have no permission to see are not listed either — to rule"
+          echo "that out:  sudo devstuff run whats-on-port $port"
+        fi
+        exit 0
+      fi
+
+      echo "Port $port ($protocol) is in use:"
+      echo
+      printf '%s\n' "$sockets" | sed 's/^/  /'
+
+      # One port can have several holders (SO_REUSEPORT), so this reports every PID
+      # rather than assuming a single answer.
+      pids="$(printf '%s\n' "$sockets" | grep -oE 'pid=[0-9]+' | cut -d= -f2 | sort -un)"
+      if [ -n "$pids" ]; then
+        echo
+        echo "Holding process(es):"
+        printf '  %-8s %-10s %-10s %s\n' PID USER ELAPSED COMMAND
+        for pid in $pids; do
+          # The full command line is never truncated: it is usually the thing that
+          # identifies which of five node processes this actually is.
+          ps -o pid=,user=,etime=,args= -p "$pid" 2>/dev/null \
+            | awk '{printf "  %-8s %-10s %-10s ", $1, $2, $3; $1=$2=$3=""; sub(/^ +/, ""); print}'
+        done
+        if [ -n "$escalated" ]; then
+          echo
+          echo "  (the process details above needed root — re-read via sudo)"
+        fi
+      else
+        echo
+        echo "The socket exists, but its owning process belongs to another user and is"
+        echo "not visible from here. Re-run as root to name it:"
+        echo "  sudo devstuff run whats-on-port $port"
+      fi
+
+      # Counted on the listener's side only: matching both sport and dport counts each
+      # connection twice, once per end of a loopback pair.
+      conns="$(ss -tnpH "sport = :$port" 2>/dev/null | grep -c ESTAB || true)"
+      if [ "${conns:-0}" -gt 0 ]; then
+        echo
+        echo "$conns established connection(s) to this port — list them with:"
+        echo "  ss -tnp 'sport = :$port'"
+      fi
+
+      # Best-effort: a published container port is held by docker-proxy, whose command
+      # line does not say which container it belongs to. Silent on any failure, so no
+      # daemon (or no docker at all) costs nothing.
+      if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+        containers="$(docker ps --format '{{.Names}}\t{{.Ports}}' 2>/dev/null | grep -E ":$port->" || true)"
+        if [ -n "$containers" ]; then
+          echo
+          echo "Published by container(s):"
+          printf '%s\n' "$containers" | sed 's/^/  /'
+        fi
+      fi
+    docs_url: https://man7.org/linux/man-pages/man8/ss.8.html
+
   aws-saml-reauth:
     name: AWS SAML Reauth
     description: Reauthorize the AWS CLI via saml2aws

dev_setup/generic.py

@@ -10,10 +10,9 @@ from collections.abc import Callable
 from dataclasses import dataclass, fields
 from pathlib import Path
 
+from dev_setup import verbose
 from dev_setup.base import Tool
 
-_verbose: bool = False
-
 # Auto-inferred requires per install type (re-derived on load, not persisted)
 AUTO_REQUIRES = {
     "npm": ["nvm"],
@@ -43,9 +42,20 @@ class UpdateStatus:
 
 
 def _run(cmd: list, *, cwd: Path | None = None) -> None:
-    """Run a command. Streams output when verbose, captures when not."""
-    if _verbose:
-        subprocess.run(cmd, check=True, cwd=cwd)
+    """Run a state-changing command (install/remove/update). Raises RuntimeError on failure.
+
+    Streams output when verbose, captures when not — captured output is discarded on
+    success and surfaced as the exception message on failure, which is the only reason
+    quiet mode can say anything useful about what went wrong.
+    """
+    verbose.command(cmd, cwd=cwd)
+    if verbose.enabled():
+        try:
+            subprocess.run(cmd, check=True, cwd=cwd)
+        except subprocess.CalledProcessError as e:
+            # The output already streamed past; repeating the whole argv in the error
+            # adds nothing the user can't see directly above it.
+            raise RuntimeError(f"exit code {e.returncode}") from e
     else:
         try:
             subprocess.run(cmd, check=True, capture_output=True, text=True, cwd=cwd)
@@ -54,6 +64,26 @@ def _run(cmd: list, *, cwd: Path | None = None) -> None:
             raise RuntimeError(msg) from e
 
 
+def _probe(cmd: list, *, log_at: int = verbose.TRACE, **kwargs) -> subprocess.CompletedProcess:
+    """Run a command whose output we capture rather than stream, and don't raise on.
+
+    Used for read-only probes (version checks, dpkg queries, …) and for the few
+    best-effort actions whose failure is deliberately ignored. Verbosity only adds
+    logging here, and by default only at -vv: probes fire constantly — one or more per
+    tool on every `list` — and would bury the actual work at -v. `log_at=verbose.VERBOSE`
+    marks the ones that are real actions the user should see at -v.
+    """
+    kwargs.setdefault("capture_output", True)
+    verbose.command(cmd, cwd=kwargs.get("cwd"), minimum=log_at)
+    proc = subprocess.run(cmd, **kwargs)
+    if verbose.enabled(verbose.TRACE):
+        out = "".join(
+            part for part in (proc.stdout, proc.stderr) if isinstance(part, str)
+        )
+        verbose.result(proc.returncode, out)
+    return proc
+
+
 @dataclass
 class GenericTool(Tool):
     key: str = ""
@@ -160,7 +190,7 @@ class GenericTool(Tool):
         if cmd and shutil.which(cmd):
             for flag in ["--version", "-v", "version"]:
                 try:
-                    r = subprocess.run([cmd, flag], capture_output=True, text=True, timeout=5)
+                    r = _probe([cmd, flag], capture_output=True, text=True, timeout=5)
                     if r.returncode == 0 and r.stdout.strip():
                         return r.stdout.strip().splitlines()[0]
                 except Exception:
@@ -178,18 +208,13 @@ class GenericTool(Tool):
 
 
 def _install_npm(tool: GenericTool) -> None:
-    from dev_setup import ui
     if not tool.npm_name:
         raise RuntimeError("npm_name not set")
-    with ui.spinner(f"Installing {tool.name} via npm..."):
-        subprocess.run(
-            ["bash", "-lc", f"{_npm_init()} && npm install -g {shlex.quote(tool.npm_name)}"],
-            check=True, capture_output=True,
-        )
+    with verbose.step(f"Installing {tool.name} via npm..."):
+        _run(["bash", "-lc", f"{_npm_init()} && npm install -g {shlex.quote(tool.npm_name)}"])
 
 
 def _install_uvx(tool: GenericTool) -> None:
-    from dev_setup import ui
     if not tool.pip_name:
         raise RuntimeError("pip_name not set")
     uv = shutil.which("uv")
@@ -198,26 +223,19 @@ def _install_uvx(tool: GenericTool) -> None:
             "uv is required to install uvx packages. "
             "Install it first: devstuff install uv"
         )
-    with ui.spinner(f"Installing {tool.name} via uvx..."):
-        subprocess.run([uv, "tool", "install", tool.pip_name], check=True, capture_output=True)
+    with verbose.step(f"Installing {tool.name} via uvx..."):
+        _run([uv, "tool", "install", tool.pip_name])
 
 
 def _install_git(tool: GenericTool) -> None:
-    from dev_setup import ui
     if not tool.git_url:
         raise RuntimeError("git_url not set")
     dest = _git_clone_dest(tool.git_url)
-    with ui.spinner(f"Cloning {tool.name}..."):
-        subprocess.run(
-            ["git", "clone", "--depth=1", tool.git_url, str(dest)],
-            check=True, capture_output=True,
-        )
+    with verbose.step(f"Cloning {tool.name}..."):
+        _run(["git", "clone", "--depth=1", tool.git_url, str(dest)])
     if tool.git_install_cmd:
-        with ui.spinner("Running install command..."):
-            subprocess.run(
-                ["bash", "-c", tool.git_install_cmd],
-                cwd=dest, check=True, capture_output=True,
-            )
+        with verbose.step("Running install command..."):
+            _run(["bash", "-c", tool.git_install_cmd], cwd=dest)
 
 
 def _install_apt(tool: GenericTool) -> None:
@@ -225,7 +243,7 @@ def _install_apt(tool: GenericTool) -> None:
     if not tool.apt_packages:
         raise RuntimeError("apt_packages not set")
     ui.info(f"Installing {tool.name} via apt...")
-    subprocess.run(["sudo", "apt-get", "update", "-q"], capture_output=True)
+    _run_apt_update()
     _run(["sudo", "apt-get", "install", "-y"] + tool.apt_packages.split())
 
 
@@ -250,19 +268,14 @@ def _install_bash(tool: GenericTool) -> None:
 
 
 def _update_npm(tool: GenericTool, version: str | None) -> None:
-    from dev_setup import ui
     if not tool.npm_name:
         raise RuntimeError("npm_name not set")
     target = f"{tool.npm_name}@{version or 'latest'}"
-    with ui.spinner(f"Updating {tool.name} via npm..."):
-        subprocess.run(
-            ["bash", "-lc", f"{_npm_init()} && npm install -g {shlex.quote(target)}"],
-            check=True, capture_output=True,
-        )
+    with verbose.step(f"Updating {tool.name} via npm..."):
+        _run(["bash", "-lc", f"{_npm_init()} && npm install -g {shlex.quote(target)}"])
 
 
 def _update_uvx(tool: GenericTool, version: str | None) -> None:
-    from dev_setup import ui
     if not tool.pip_name:
         raise RuntimeError("pip_name not set")
     uv = shutil.which("uv")
@@ -272,8 +285,8 @@ def _update_uvx(tool: GenericTool, version: str | None) -> None:
             "Install it first: devstuff install uv"
         )
     target = f"{tool.pip_name}=={version}" if version else tool.pip_name
-    with ui.spinner(f"Updating {tool.name} via uv tool upgrade..."):
-        subprocess.run([uv, "tool", "upgrade", target], check=True, capture_output=True)
+    with verbose.step(f"Updating {tool.name} via uv tool upgrade..."):
+        _run([uv, "tool", "upgrade", target])
 
 
 def _update_apt(tool: GenericTool, version: str | None) -> None:
@@ -281,7 +294,7 @@ def _update_apt(tool: GenericTool, version: str | None) -> None:
     if not tool.apt_packages:
         raise RuntimeError("apt_packages not set")
     packages = tool.apt_packages.split()
-    subprocess.run(["sudo", "apt-get", "update", "-q"], capture_output=True)
+    _run_apt_update()
     if version:
         if len(packages) != 1:
             raise RuntimeError(
@@ -295,7 +308,6 @@ def _update_apt(tool: GenericTool, version: str | None) -> None:
 
 
 def _update_git(tool: GenericTool, version: str | None) -> None:
-    from dev_setup import ui
     if version:
         raise RuntimeError(
             "Version pinning is not supported for git tools (shallow clone). "
@@ -306,13 +318,10 @@ def _update_git(tool: GenericTool, version: str | None) -> None:
     dest = _git_clone_dest(tool.git_url)
     if not dest.exists():
         raise RuntimeError(f"{tool.name} clone not found at {dest}")
-    with ui.spinner(f"Pulling latest {tool.name}..."):
+    with verbose.step(f"Pulling latest {tool.name}..."):
         _run(["git", "-C", str(dest), "pull"])
         if tool.git_install_cmd:
-            subprocess.run(
-                ["bash", "-c", tool.git_install_cmd],
-                cwd=dest, check=True, capture_output=True,
-            )
+            _run(["bash", "-c", tool.git_install_cmd], cwd=dest)
 
 
 def _update_script_url(tool: GenericTool, version: str | None) -> None:
@@ -335,7 +344,7 @@ def _update_bash(tool: GenericTool, version: str | None) -> None:
 def _npm_installed_version(pkg: str) -> str:
     import json
     try:
-        r = subprocess.run(
+        r = _probe(
             ["bash", "-lc", f"{_npm_init()} && npm list -g --depth=0 --json {shlex.quote(pkg)}"],
             capture_output=True, text=True, timeout=10,
         )
@@ -347,7 +356,7 @@ def _npm_installed_version(pkg: str) -> str:
 
 def _npm_latest_version(pkg: str) -> str:
     try:
-        r = subprocess.run(
+        r = _probe(
             ["bash", "-lc", f"{_npm_init()} && npm view {shlex.quote(pkg)} version"],
             capture_output=True, text=True, timeout=10,
         )
@@ -371,7 +380,7 @@ def _uv_tool_current_version(pkg: str) -> str:
     if not uv:
         return ""
     try:
-        r = subprocess.run(
+        r = _probe(
             [uv, "tool", "list", "--color", "never"], capture_output=True, text=True, timeout=15,
         )
     except Exception:
@@ -392,7 +401,7 @@ def _uv_outdated_map() -> dict[str, str]:
     if not uv:
         return {}
     try:
-        r = subprocess.run(
+        r = _probe(
             [uv, "tool", "list", "--outdated", "--color", "never"],
             capture_output=True, text=True, timeout=20,
         )
@@ -423,14 +432,14 @@ def _check_update_apt(tool: GenericTool) -> UpdateStatus:
         return UpdateStatus()
     pkg = tool.apt_packages.split()[0]
     try:
-        r = subprocess.run(
+        r = _probe(
             ["dpkg-query", "-W", "-f=${Version}", pkg], capture_output=True, text=True, timeout=10,
         )
         current = r.stdout.strip() if r.returncode == 0 else ""
     except Exception:
         current = ""
     try:
-        r = subprocess.run(["apt-cache", "policy", pkg], capture_output=True, text=True, timeout=10)
+        r = _probe(["apt-cache", "policy", pkg], capture_output=True, text=True, timeout=10)
     except Exception:
         return UpdateStatus(current=current)
     candidate = ""
@@ -451,7 +460,7 @@ def _check_update_git(tool: GenericTool) -> UpdateStatus:
     if not dest.exists():
         return UpdateStatus()
     try:
-        r = subprocess.run(
+        r = _probe(
             ["git", "-C", str(dest), "rev-parse", "--short", "HEAD"],
             capture_output=True, text=True, timeout=10,
         )
@@ -459,7 +468,7 @@ def _check_update_git(tool: GenericTool) -> UpdateStatus:
     except Exception:
         current = ""
     try:
-        r = subprocess.run(
+        r = _probe(
             ["git", "ls-remote", tool.git_url, "HEAD"], capture_output=True, text=True, timeout=10,
         )
         remote_full = r.stdout.split()[0] if r.returncode == 0 and r.stdout.strip() else ""
@@ -486,32 +495,28 @@ _UPDATE_CHECKERS: dict[str, Callable[[GenericTool], UpdateStatus]] = {
 
 
 def _remove_npm(tool: GenericTool) -> None:
-    from dev_setup import ui
-    with ui.spinner(f"Removing {tool.name}..."):
-        subprocess.run(
-            ["bash", "-lc", f"{_npm_init()} && npm uninstall -g {shlex.quote(tool.npm_name)}"],
-            check=True, capture_output=True,
-        )
+    with verbose.step(f"Removing {tool.name}..."):
+        _run(["bash", "-lc", f"{_npm_init()} && npm uninstall -g {shlex.quote(tool.npm_name)}"])
 
 
 def _remove_uvx(tool: GenericTool) -> None:
-    from dev_setup import ui
     uv = shutil.which("uv")
     if not uv:
         raise RuntimeError(
             "uv is required to remove uvx packages. "
             "Install it first: devstuff install uv"
         )
-    with ui.spinner(f"Removing {tool.name}..."):
-        subprocess.run([uv, "tool", "uninstall", tool.pip_name], check=True, capture_output=True)
+    with verbose.step(f"Removing {tool.name}..."):
+        _run([uv, "tool", "uninstall", tool.pip_name])
 
 
 def _remove_git(tool: GenericTool) -> None:
-    from dev_setup import ui
     dest = _git_clone_dest(tool.git_url)
     if tool.git_remove_cmd:
-        with ui.spinner("Running remove command..."):
-            subprocess.run(["bash", "-c", tool.git_remove_cmd], cwd=dest, capture_output=True)
+        # Best-effort: the clone directory is removed below either way, so a remove
+        # command that fails must not abort the removal.
+        with verbose.step("Running remove command..."):
+            _probe(["bash", "-c", tool.git_remove_cmd], cwd=dest, log_at=verbose.VERBOSE)
     if dest.exists():
         shutil.rmtree(dest)
 
@@ -610,7 +615,7 @@ _UPDATERS: dict[str, Callable[[GenericTool, str | None], None]] = {
 
 def _npm_global_installed(pkg: str) -> bool:
     try:
-        r = subprocess.run(
+        r = _probe(
             ["bash", "-lc", f"{_npm_init()} && npm list -g --depth=0 {shlex.quote(pkg)}"],
             capture_output=True,
             text=True,
@@ -620,13 +625,19 @@ def _npm_global_installed(pkg: str) -> bool:
         return False
 
 
+def _run_apt_update() -> None:
+    """Refresh apt's package lists. Deliberately non-fatal: a failing mirror shouldn't
+    stop an install of a package that may already be cached."""
+    _probe(["sudo", "apt-get", "update", "-q"], log_at=verbose.VERBOSE)
+
+
 def _npm_init() -> str:
     return '. "$HOME/.nvm/nvm.sh" 2>/dev/null || true'
 
 
 def _apt_installed(pkg: str) -> bool:
     try:
-        r = subprocess.run(["dpkg", "-s", pkg], capture_output=True, text=True)
+        r = _probe(["dpkg", "-s", pkg], capture_output=True, text=True)
         return "Status: install ok installed" in r.stdout
     except Exception:
         return False
@@ -641,8 +652,10 @@ def _download_script(url: str, *, expected_sha256: str = "") -> str:
     """Download a script over HTTPS and optionally verify its sha256."""
     import urllib.request
 
+    verbose.log(f"downloading {url}")
     with urllib.request.urlopen(url, timeout=30) as resp:
         data = resp.read()
+    verbose.trace(f"downloaded {len(data)} bytes, sha256 {hashlib.sha256(data).hexdigest()}")
 
     if expected_sha256:
         actual = hashlib.sha256(data).hexdigest()
@@ -664,8 +677,12 @@ def _run_bash_script(script: str) -> None:
     with tempfile.NamedTemporaryFile(mode="w", suffix=".sh", delete=False) as f:
         f.write(script)
         tmp = f.name
+    verbose.trace(f"script → {tmp}")
+    verbose.block(script)
     try:
-        _run(["bash", tmp])
+        # -x at -vv traces each expanded command to stderr as the script runs, which is
+        # the only way to see where a downloaded installer actually failed.
+        _run(["bash", *(["-x"] if verbose.enabled(verbose.TRACE) else []), tmp])
     finally:
         os.unlink(tmp)
 
@@ -686,7 +703,7 @@ def _is_simple_command(cmd: str) -> bool:
 def _bash_version(key: str) -> str:
     for flag in ["--version", "-v", "version"]:
         try:
-            r = subprocess.run(
+            r = _probe(
                 [
                     "bash", "-lc",
                     f'. "$HOME/.nvm/nvm.sh" 2>/dev/null; {shlex.quote(key)} {flag} 2>/dev/null',
@@ -707,13 +724,13 @@ def _check_cmd_installed(cmd: str, *, install_type: str = "") -> bool:
         # Only source nvm for npm-type tools — avoids unnecessary shell overhead
         prefix = f"{_npm_init()} && " if install_type == "npm" else ""
         try:
-            return subprocess.run(
+            return _probe(
                 ["bash", "-lc", f"{prefix}command -v {cmd} >/dev/null 2>&1"],
                 capture_output=True,
             ).returncode == 0
         except Exception:
             return False
     try:
-        return subprocess.run(["bash", "-lc", cmd], capture_output=True).returncode == 0
+        return _probe(["bash", "-lc", cmd], capture_output=True).returncode == 0
     except Exception:
         return False

dev_setup/verbose.py

@@ -0,0 +1,148 @@
+"""Process-wide verbosity level and the logging helpers built on it.
+
+Three levels, set once per process by the `-v` CLI option (`verbose.option`) or the
+`DEVSTUFF_VERBOSE` environment variable:
+
+    0  quiet   — normal output only; subprocess output is captured and shown only on failure
+    1  -v      — every command devstuff runs is logged, and its output streams live
+    2  -vv     — plus read-only probes, exit codes, captured output, and `bash -x` tracing
+                 of script bodies (functions, install/remove scripts)
+
+**Everything here writes to stderr, never stdout.** `devstuff run <key>` in
+`register: eval` mode prints shell code to stdout for `eval "$(...)"` to consume, so a
+verbose line on stdout would be executed in the user's shell. Routing the whole logger
+to stderr makes that impossible by construction rather than by remembering to check the
+level at each call site.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from rich.console import Console
+
+# stderr, and no highlighting/markup: these lines carry raw command lines and script
+# bodies, which are full of characters rich would otherwise style or eat.
+_console = Console(stderr=True, highlight=False)
+
+# soft_wrap keeps a logged command line or script line on one terminal line. Rich's
+# default word-wrap breaks a long command mid-word, and what the user most wants to do
+# with a verbose line — copy it back into a shell — stops working when it does.
+_PRINT = {"style": "dim", "markup": False, "soft_wrap": True}
+
+QUIET = 0
+VERBOSE = 1
+TRACE = 2
+
+_level: int = 0
+
+
+def _from_env() -> int:
+    """DEVSTUFF_VERBOSE=1|2 (or a bare word like "true") as a starting level.
+
+    Lets a function invoked from a script or another tool be verbose without the caller
+    threading a flag through; an explicit -v still wins because it can only raise it.
+    """
+    raw = os.environ.get("DEVSTUFF_VERBOSE", "").strip().lower()
+    if not raw:
+        return QUIET
+    if raw.isdigit():
+        return min(int(raw), TRACE)
+    return VERBOSE if raw in ("true", "yes", "on", "y") else QUIET
+
+
+_level = _from_env()
+
+
+def set_level(value: int) -> None:
+    global _level
+    _level = max(QUIET, min(TRACE, value))
+
+
+def level() -> int:
+    return _level
+
+
+def enabled(minimum: int = VERBOSE) -> bool:
+    return _level >= minimum
+
+
+def log(msg: str, *, minimum: int = VERBOSE) -> None:
+    """A verbose note. Dim, stderr, one line."""
+    if _level >= minimum:
+        _console.print(f"  {msg}", **_PRINT)
+
+
+def trace(msg: str) -> None:
+    """A note only worth showing at -vv."""
+    log(msg, minimum=TRACE)
+
+
+def command(cmd: list[str] | str, *, cwd: object = None, minimum: int = VERBOSE) -> None:
+    """Log a command about to run, in a form the user could paste back into a shell."""
+    if _level < minimum:
+        return
+    text = cmd if isinstance(cmd, str) else shlex.join(str(c) for c in cmd)
+    log(f"$ {text}" + (f"   (in {cwd})" if cwd else ""), minimum=minimum)
+
+
+def result(returncode: int, output: str = "", *, minimum: int = TRACE) -> None:
+    """Log a captured command's exit code and output."""
+    if _level < minimum:
+        return
+    log(f"→ exit {returncode}", minimum=minimum)
+    block(output, minimum=minimum)
+
+
+def block(text: str, *, minimum: int = TRACE) -> None:
+    """Log a multi-line body (captured output, a script) indented under the last line."""
+    if _level < minimum or not text.strip():
+        return
+    for line in text.rstrip("\n").splitlines():
+        _console.print(f"    │ {line}", **_PRINT)
+
+
+@contextmanager
+def step(label: str) -> Generator[None, None, None]:
+    """A unit of work: a spinner normally, a logged line when verbose.
+
+    The spinner has to go when verbose — it repaints its own line, so it would fight
+    with the subprocess output now streaming to the same terminal.
+    """
+    if enabled():
+        log(label)
+        yield
+    else:
+        from dev_setup import ui
+        with ui.spinner(label):
+            yield
+
+
+def option(f):
+    """`-v`/`-vv` for a Click command or group, setting the process-wide level.
+
+    `expose_value=False` — the level is process state read by the subprocess helpers
+    deep in `generic.py`/`function_runner.py`, not something each command body threads
+    through. Attached to both the `cli` group and individual commands so that
+    `devstuff -v install x` and `devstuff install -v x` both work; the callback takes
+    the max so the two can't cancel each other out.
+    """
+    import click
+
+    def _callback(ctx: object, param: object, value: int) -> int:
+        if value:
+            set_level(max(level(), value))
+        return value
+
+    return click.option(
+        "-v",
+        "--verbose",
+        count=True,
+        expose_value=False,
+        is_eager=True,
+        callback=_callback,
+        help="Verbose output: -v logs and streams every command, -vv adds probes and tracing.",
+    )(f)

{devstuff-2.0.0.dist-info → devstuff-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devstuff
-Version: 2.0.0
+Version: 2.2.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -193,6 +193,30 @@ The bash `./devstuff` script in the repo is a convenience runner for the git-clo
 
 ---
 
+## Verbose output (`-v` / `-vv`)
+
+Every command accepts `-v`, before or after the subcommand. devstuff is a thin layer over other
+people's commands; this is how you see them.
+
+```bash
+devstuff install lazygit -v      # log each command and stream its output live
+devstuff -vv run whats-on-port 8080   # + probes, exit codes, and bash -x line tracing
+DEVSTUFF_VERBOSE=1 devstuff update    # same as -v, for scripts and CI
+```
+
+| Level | What you get |
+|-------|--------------|
+| *(default)* | Normal output. Command output is captured and shown only if the command fails. |
+| `-v` | Every command devstuff runs, printed as a line you can paste back into a shell, with its output streaming live. Spinners are replaced by plain lines so they don't fight with that output. |
+| `-vv` | Plus read-only probes (version checks, install-state checks) with their exit codes and output, the body of any script before it runs, resolved function parameters, and `bash -x` tracing of every line inside function and installer scripts. |
+
+`-vvv` and above are the same as `-vv`.
+
+All of it goes to **stderr**, so it never contaminates anything you pipe or capture — including
+`eval "$(devstuff run <shell-eval function>)"`, whose stdout has to be shell code and nothing else.
+
+---
+
 ## Commands
 
 ### `list`
@@ -1105,9 +1129,38 @@ ones tools already have — for now, custom functions are hand-edited YAML at
 | `ssh-agent-key` | auth | shell-eval (bashrc) | Start ssh-agent in the current shell and add a key to it | `key_path` |
 | `validate-docker-compose` | validation | script | Validate a docker-compose.yml file in the current directory | — |
 | `validate-yaml` | validation | script | Validate a YAML file's syntax using `yq` | `file` |
+| `whats-on-port` | network | script | Find which process is listening on a port | `port`, `protocol` (optional: `tcp`/`udp`/`all`) |
 | `acc-check` | web-dev | script | Run the pi coding agent's `/dogfood` skill against a web URL | `url`, `instruction` (optional) |
 | `aws-saml-reauth` | web-dev | script | Reauthorize the AWS CLI via `saml2aws login --force` | `profile` (optional) |
 
+#### `whats-on-port`
+
+```bash
+devstuff run whats-on-port 8080          # tcp and udp
+devstuff run whats-on-port 5432 tcp      # one protocol
+```
+
+Prints the matching sockets, then the PID, user, elapsed time and **untruncated** command
+line of every process holding them — plural because `SO_REUSEPORT` lets several processes
+share one port, and "which of these five node processes" is usually the actual question.
+
+It uses `ss` rather than `lsof` or `fuser` for one measured reason: **run unprivileged
+against another user's socket, `lsof` and `fuser` print nothing and exit as though the port
+were free.** `ss` still lists the socket, just without the `users:((...))` field — so the
+function can tell "nothing there" apart from "something there I'm not allowed to name", and
+says which. When the process is hidden it retries under `sudo -n`, and only if that needs no
+password; a diagnostic shouldn't stop to prompt for one. If sudo isn't available it says
+what to re-run.
+
+"Nothing is listening" is reported as a success, not a failure, along with the two reasons a
+bind can still fail afterwards: a container port published with `userland-proxy: false` is
+NAT-forwarded with no host socket to find at all, and sockets in another network namespace
+are invisible. If Docker is running, published container ports are matched and named too —
+`docker-proxy`'s own command line doesn't say which container it belongs to.
+
+`ss` comes from `iproute2`, which isn't a devstuff package and isn't on every minimal image,
+so a missing `ss` names the apt package instead of surfacing "command not found".
+
 ---
 
 ## Built-in packages

{devstuff-2.0.0.dist-info → devstuff-2.2.0.dist-info}/RECORD

@@ -4,17 +4,18 @@ dev_setup/agent_tools.schema.json,sha256=veXnih00xW4w9yK3ruWz-npUrCnJmcQpQdFvfcu
 dev_setup/agent_tools.yaml,sha256=56E70B1W7hBqjGhYhhCAGzFQvi1nUZ04cnNiqZlMjyY,4506
 dev_setup/base.py,sha256=j2EQ5gzeGgtveWQN_BgbLcZianMENJ7PQy8EQ9J9MPE,1946
 dev_setup/catalog.py,sha256=YST_dpTpIh08aLz1FBziywtKX_zFfhlU5fr56hgf0mA,5514
-dev_setup/cli.py,sha256=DIvADRhXIqQ0UcVN8GY-uLDWUwgjdOcc7nWHP4Ie0Gc,2028
+dev_setup/cli.py,sha256=Y_RbHkexTAIQN4neDQ3buo6vmtTMNdXrsYsmY0X_Om8,2976
 dev_setup/doctor.py,sha256=JliUAgmiW2HVCWHhT76PIXTBekNXXrc0VfDMaOeLBWY,15918
-dev_setup/function_runner.py,sha256=ZnGGk_Av524vddsrQvO9O-dcNZS0UnLpfnqNxCSDytM,5937
+dev_setup/function_runner.py,sha256=08F6jvB9-oOyE5ivYtRjnL16JTGsfRnkpvkjSVrJhsM,6957
 dev_setup/functions.schema.json,sha256=VVdpH3xWsdbtqw47S1QqpBcs4O9wd3XZ_s0Q3sGwv0Q,6220
-dev_setup/functions.yaml,sha256=q3JE8g-iG64tbJ4dgvEq7o5SbNbJ8Fh__mVVR3GJIWc,3425
+dev_setup/functions.yaml,sha256=IZbdIsfRkQEvgYOjEtBMYxD-TRdqKCsoF1siWTHEYtE,9173
 dev_setup/functions_catalog.py,sha256=YgR2hY9HM1iol1AZcF-_j02EXCP9U4P3e_5eWes9KH0,7116
 dev_setup/functions_registry.py,sha256=YSl-VgNXPf0hj4WgReg-pZUj4fAjFlwvC165dgon_BE,3682
-dev_setup/generic.py,sha256=FJFOkDF1sc4ZZn2f3iiGOl9gC_8ySHh9R__yzuCGL0A,24020
+dev_setup/generic.py,sha256=6-sUq7NtPlabs9T-2qyNqAMa4E6IKfL93IRTzzMsLp8,25313
 dev_setup/registry.py,sha256=8lrk6EXCCWk1WNeNnCGLTJ-v8rpCs7-TLYtVXgiuxnA,2243
 dev_setup/tools.yaml,sha256=4NQIsMV_x_sUjgafLbuXzHoPpuSd8-QS9XOoQiz9DEk,26730
 dev_setup/ui.py,sha256=Z5nNZV8MN8tAjo1ZWq7-QPZYkPKQKuM7JbmGtiuKTqM,3806
+dev_setup/verbose.py,sha256=N3U9JAYOvFwdd8DT6W7Pqq6RCIUfbcQnPsm0O1TnvQY,5003
 dev_setup/agent/__init__.py,sha256=znrgxUCr_y0Qp-f41S6EaTv-hoTYwoZ9mOMLVge-IJg,226
 dev_setup/agent/approval.py,sha256=R2YnbR1fauGtV7-NW5dH1QvWvNHjR3l23DKRTCiqpEE,3625
 dev_setup/agent/bridges.py,sha256=RX5coPXJUSkyZApxgUZghz_57ibcPrWHVz3D44S6z2Q,4814
@@ -40,12 +41,12 @@ dev_setup/commands/docs_cmd.py,sha256=1PtpwdFO3LrAxG3HyCLFn5SXVnnwqcJ8K_c9cVd8Ph
 dev_setup/commands/doctor_cmd.py,sha256=8HqQ9sB3aVDKer6jbqN_Eq0XKZDXM2o48L6_vL8JAcE,3161
 dev_setup/commands/functions_cmd.py,sha256=D9JRYMRavXbROz0XRGjHRHeFvZY-GKyvRCctJODQDBE,2856
 dev_setup/commands/help_cmd.py,sha256=kHbzMggYVj3hS7JKUiCrBY4VtZ5p71YPoPKQ4Y-OYNU,3301
-dev_setup/commands/install_cmd.py,sha256=DMKq2_bn6Y7ZV-VPR85H2A73fMkVKqH2srfeY4cIl0g,4785
+dev_setup/commands/install_cmd.py,sha256=AGrB0CZPT6hZ0Cnn9AgmlyFkW8F1wZufuXVvwYft_Xo,4610
 dev_setup/commands/list_cmd.py,sha256=-BAywXxpSm4-VAlysLzlDwIqvmk_zBKhmzEObM8jigo,2847
-dev_setup/commands/remove_cmd.py,sha256=5xCCN6zlaP5KCfOl6GKbSbWC08QD9zkQ1MN1X4AKaLw,1414
-dev_setup/commands/run_cmd.py,sha256=xZEw6a12TBd3P4WB-39D3PVAKLCyCtXtVrEVwXItZXc,2465
+dev_setup/commands/remove_cmd.py,sha256=_KqCa2S9fQFngLUs_OpBzjkIkFKgDtKup4gQ5TqLrVI,1239
+dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
 dev_setup/commands/skills_cmd.py,sha256=j4rleYEW4lt-O2ssDwGyhwmk2Wiip64C4Z7iPT6c3y0,7482
-dev_setup/commands/update_cmd.py,sha256=EA2I0kyEnIg30R7XSjJKT6WcWLVjsVRoxvmQuzBRFAU,5005
+dev_setup/commands/update_cmd.py,sha256=9Bdgu9wMdliawonDOsfDsjP2am-okuONStICKn9pkkg,4831
 dev_setup/configure/__init__.py,sha256=YXkDx21lDzjEQvypoAyoEAy8srskEzc5t6PR69evPHA,3266
 dev_setup/configure/ansible/__init__.py,sha256=huQL_tfiU1l0WI6nzjTnGZlxCQX2aH7E9n9TrfwmIpU,407
 dev_setup/configure/ansible/detect.py,sha256=5LkdbJg5BU2lrIU4CZm_Lhr6Sm4TJMCh1sMrsRK6rgc,9531
@@ -89,7 +90,7 @@ dev_setup/configure/starship/model.py,sha256=HNkIj69DqBQFAq0VTHqPLNZT2DuBZSfF-5y
 dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
 dev_setup/configure/starship/render.py,sha256=gDE0hbGZ9oDCR1VAZQRDm5EFYviMjj0-eSmr1EnZfn8,10262
 dev_setup/configure/starship/wizard.py,sha256=BmWl-U6ttF79gepDhCv8UxT8ZDIMe1SWnhSkA1iIrGQ,15498
-devstuff-2.0.0.dist-info/METADATA,sha256=JnPSEMPGjO7Mu0yf55BV1CaQHqSgiqecrd0qc2XJrPM,65404
-devstuff-2.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-devstuff-2.0.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
-devstuff-2.0.0.dist-info/RECORD,,
+devstuff-2.2.0.dist-info/METADATA,sha256=Jq_Nx1lYKtqm-nRmPEdjg7R3HOte4oGhj9nL4ARUTMk,68408
+devstuff-2.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+devstuff-2.2.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
+devstuff-2.2.0.dist-info/RECORD,,