devstuff 2.0.0__tar.gz → 2.2.0__tar.gz

{devstuff-2.0.0 → devstuff-2.2.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v2.2.0 (2026-08-05)
+
+### Features
+
+- **cli**: add -v/-vv verbose mode across every command
+
+## v2.1.0 (2026-08-04)
+
+### Features
+
+- **functions**: add whats-on-port to find what is holding a port
+
 ## v2.0.0 (2026-08-04)
 
 ### BREAKING CHANGE

{devstuff-2.0.0 → devstuff-2.2.0}/CLAUDE.md

@@ -62,6 +62,7 @@ src/dev_setup/
 ├── generic.py       # GenericTool — the ONE engine that implements every install type
 ├── tools.yaml       # Bundled built-in catalog (core/tools/languages categories)
 ├── ui.py            # Rich console + questionary wrappers (spinners, prompts, styled output)
+├── verbose.py      # Process-wide -v/-vv level + the stderr logger built on it
 ├── configure/       # Per-tool setup wizards (see "Configurators" below)
 └── commands/        # One Click command per file: list, install, remove, add, delete, docs, catalog
 ```
@@ -82,6 +83,25 @@ pattern for upgrading an already-installed tool (latest or a pinned version); fo
 `bash` types "update" is a full reinstall, since there's no narrower mechanism, so the command
 layer confirms before re-running it.
 
+**Verbosity** (`verbose.py`, spec in `docs/specs/verbose-mode/`): one process-wide level —
+`0` / `-v` / `-vv` — set by a Click callback and read by the subprocess helpers, never threaded
+through call signatures. Three things about it are load-bearing:
+- **Every line goes to stderr.** `devstuff run` for a `register: eval` function puts shell code
+  on stdout for `eval "$(...)"`; a verbose line there is *code that gets executed*. The logger
+  has no stdout path at all rather than a check at each call site.
+- **`cli._add_verbose_option` applies `-v` to every command and subcommand**, walking the group
+  tree, so `devstuff -v install x`, `devstuff install -v x` and `devstuff functions -v enable k`
+  all work. Don't go back to decorating commands individually — the first draft did, and `list`
+  was immediately missing it.
+- **`generic.py` has exactly two subprocess helpers**: `_run` (state-changing — streams when
+  verbose, raises `RuntimeError`) and `_probe` (captures, never raises, logs at `-vv` only
+  because probes fire once per tool on every `list`). Anything new that shells out belongs in
+  one of them; a direct `subprocess.run` is a hole in the flag's coverage, which is exactly what
+  the old boolean `-v` was — it never reached npm/uvx/git installs at all. `verbose.step` is the
+  spinner-or-line swap, since a spinner repaints its line and can't share a terminal with
+  streaming output. At `-vv` script bodies run under `bash -x`, *except* eval-mode function
+  scripts — `set -x` there would persist in the caller's interactive shell.
+
 **Two ways a tool gets defined**: built-in (an entry added directly to `src/dev_setup/tools.yaml`,
 `builtin=True`) or custom (created via the `devstuff add` wizard, `devstuff catalog import`,
 or hand-edited YAML, landing in the user catalog). Both use the identical schema — the only
@@ -165,7 +185,14 @@ another CLI should guard on `command -v <tool>` and point at `devstuff install <
 error rather than let a raw "command not found" surface — see `validate-yaml`/`aws-saml-reauth`
 in `functions.yaml`. If that CLI is only reachable via nvm (like `pi`), source
 `"$HOME/.nvm/nvm.sh"` first (see `acc-check`) — `script`-type functions run via a non-login,
-non-interactive `bash <tmpfile>`, so `~/.bashrc`/nvm's shell init never runs on their own.
+non-interactive `bash <tmpfile>`, so `~/.bashrc`/nvm's shell init never runs on their own. When
+the CLI isn't a catalog tool at all, name the distro package instead (`whats-on-port` points at
+`apt-get install iproute2`) — pointing at `devstuff install ss` would be a lie.
+
+**`run_cmd` flattens every non-zero exit to 1**, so a `script` function cannot signal a *result*
+through its exit code — only whether it ran. A "found nothing" answer should therefore exit 0 and
+say so, or the user gets a red "command failed" banner under a correct result; keep non-zero for
+"could not perform the lookup" (see `whats-on-port`'s comment on this).
 
 Not yet built: an `add` wizard and `catalog import`/`export` for functions, analogous to the
 ones tools already have.

{devstuff-2.0.0 → devstuff-2.2.0}/PKG-INFO

@@ -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 → devstuff-2.2.0}/README.md

@@ -166,6 +166,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`
@@ -1078,9 +1102,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 → devstuff-2.2.0}/docs/specs/README.md

@@ -46,3 +46,4 @@ They are most useful when they capture:
 | [`bat-config/`](bat-config/) — `devstuff configure bat`, the theme and decoration wizard | Complete (v1) |
 | [`ansible-config/`](ansible-config/) — `devstuff configure ansible`, the ansible.cfg wizard | Complete (v1) |
 | [`lazygit-config/`](lazygit-config/) — `devstuff configure lazygit`, the icons/pager/panels wizard | Complete (v1) |
+| [`verbose-mode/`](verbose-mode/) — `-v`/`-vv`, the process-wide verbosity level | Complete (v1) |

devstuff-2.2.0/docs/specs/verbose-mode/development-plan.md

@@ -0,0 +1,50 @@
+# Development plan: verbose mode
+
+**Date:** 2026-08-04
+**Status:** Complete (v1)
+
+---
+
+## Milestones
+
+| # | Milestone | State |
+|---|-----------|-------|
+| 1 | `verbose.py`: level, env var, stderr printers, `step`, Click option factory | Done |
+| 2 | `generic.py`: `_run` / `_probe` split; route every `subprocess.run` through one of them | Done |
+| 3 | `generic.py`: swap spinner-plus-capture call sites (npm/uvx/git) onto `_run` + `verbose.step` | Done |
+| 4 | `function_runner.py`: log resolved params, script body, `bash -x` at `-vv` | Done |
+| 5 | `cli.py`: apply the option to the group and every command/subcommand recursively | Done |
+| 6 | Tests (`tests/test_verbose.py`), README, CLAUDE.md | Done |
+
+## Testing strategy
+
+`tests/test_verbose.py`, 33 tests. The level is process-wide state, so an autouse fixture
+resets it before and after every test — a leaked level would make unrelated tests print.
+
+What is actually asserted, beyond the obvious:
+
+- **stdout stays empty at `-vv`.** Two tests: one over every printer in `verbose.py`, one over
+  `render_eval_script`. This is the invariant in SD-3 and the only one whose failure would
+  execute arbitrary text in a user's shell.
+- **`_run` streams rather than captures when verbose** — asserted on the `subprocess.run`
+  kwargs, because "did output reach the terminal" is not otherwise observable in-process.
+- **`_probe` is silent at `-v` and reports exit code + output at `-vv`**, and never raises.
+- **`bash -x` appears at `-vv` and not below**, for both functions and install scripts, plus one
+  end-to-end test (`capfd`) that a real function's output and its `+ echo …` trace both arrive.
+- **The CLI accepts `-v` before and after the subcommand**, parametrized over both positions and
+  both levels — this is the case that broke in development (SD-2).
+- **The spinner is not used when verbose** (SD-6), asserted by patching `ui.spinner`.
+
+Manual verification against the real CLI, with a throwaway `bash`-type tool in an isolated
+`HOME`: quiet / `-v` / `-vv` / `DEVSTUFF_VERBOSE=1` on both a succeeding and a failing install,
+and `--help` on all fourteen commands confirming each advertises `-v`.
+
+## Risks
+
+- **Verbose output can contain secrets** a user passed as a function parameter. Not mitigated in
+  v1 and stated in the spec rather than half-solved (spec §3).
+- **`bash -x` changes a script's stderr**, so a function whose stderr is parsed by something
+  downstream would see the trace. Only reachable at `-vv`, which is an interactive debugging
+  flag; `capture=True` (the agent path) also gets the trace, and the agent reads it as text.
+- **The env var is read at import time.** Changing `DEVSTUFF_VERBOSE` mid-process has no effect;
+  tests call `_from_env()` directly rather than relying on re-import.

devstuff-2.2.0/docs/specs/verbose-mode/specifications.md

@@ -0,0 +1,96 @@
+# Specification: verbose mode (`-v` / `-vv`)
+
+**Date:** 2026-08-04
+**Status:** Implemented (v1)
+**Authors:** Sawyer + Claude
+
+---
+
+## 1. Problem Statement & Goals
+
+devstuff is a thin layer over other people's commands. When one of them misbehaves, the
+user is looking at devstuff's summary of it rather than the thing itself:
+
+- **Install output was captured and thrown away on success.** `-v` existed on `install`,
+  `remove` and `update` as a boolean, but it only reached `generic._run` — which is used
+  by the `apt`, `script` and `bash` types. Every `npm`, `uvx`, `git` install called
+  `subprocess.run(..., capture_output=True)` directly, so `devstuff install -v <npm tool>`
+  streamed nothing at all. The flag silently did nothing for a third of the catalog.
+- **A failing function was a black box.** `devstuff run` streams a function's stdout, but
+  `run_cmd` flattens every non-zero exit to 1 and a `script`-type function is an opaque
+  blob of someone else's shell. There was no way to see *which line* failed.
+- **Nothing ever showed the command being run.** The most useful thing a tool can tell you
+  when it fails is the exact command it ran, so you can run it yourself.
+
+**Goal:** one process-wide verbosity level, set the same way everywhere, that makes every
+command devstuff shells out to visible — and at `-vv`, traceable line by line.
+
+**Non-goals:** a logging framework or log files (`logging`, handlers, rotation); per-command
+verbosity; a `--quiet` level below the default; structured/JSON output.
+
+---
+
+## 2. Functional Requirements
+
+### Levels
+
+- **FR-1** Exactly three levels: `0` quiet (default), `1` (`-v`), `2` (`-vv`). Values above
+  2 clamp to 2 rather than erroring — `-vvv` is a reasonable thing to type.
+- **FR-2** The level is process-wide state in `verbose.py`, not a parameter threaded through
+  call signatures. Set once during Click option parsing, read by the subprocess helpers.
+- **FR-3** `-v` is accepted **before or after** the subcommand (`devstuff -v install x` and
+  `devstuff install -v x`), and on subcommands of groups (`devstuff functions -v enable k`).
+  When given in both positions the higher wins; they can never cancel out.
+- **FR-4** Every registered command accepts `-v`, applied centrally in `cli._add_verbose_option`
+  rather than per-command, so no command can be forgotten. A command already defining
+  `--verbose` is left alone.
+- **FR-5** `DEVSTUFF_VERBOSE=1|2` (or `true`) sets the starting level, so a function invoked
+  from a script can be verbose without the caller threading a flag. An explicit `-v` can only
+  raise the level, never lower it.
+
+### What each level shows
+
+- **FR-6** At `-v`: every state-changing command is logged as a pasteable shell line
+  (`$ bash -lc 'npm install -g x'`) and its output **streams live** instead of being captured.
+- **FR-7** At `-v`: the spinner is replaced by a plain logged line (`verbose.step`). A spinner
+  repaints its own line and cannot share a terminal with streaming output.
+- **FR-8** At `-vv`, additionally: read-only probes (version checks, `dpkg` queries, install-state
+  checks) with their exit code and captured output; the body of any script about to run; the
+  resolved parameter values of a function; the sha256 and size of a downloaded install script.
+- **FR-9** At `-vv`, script bodies run under `bash -x`, so each expanded command is traced. This
+  covers both function scripts (`function_runner`) and tool install/remove scripts (`generic`).
+- **FR-10** Probes are silent at `-v`. `devstuff list` alone fires one per tool; at `-v` they
+  would bury the actual work. The few *best-effort actions* that share the probe helper
+  (`apt-get update`, a git tool's remove command) opt in to `-v` logging via `log_at`.
+
+### Output routing
+
+- **NFR-1** **Every verbose line goes to stderr, never stdout.** `devstuff run <key>` for a
+  `register: eval` function prints shell code to stdout for `eval "$(...)"`; a verbose line on
+  stdout would be executed in the user's shell. Enforced by the logger having no stdout path
+  at all, rather than by per-call-site checks.
+- **NFR-2** Verbose lines are not word-wrapped (`soft_wrap`). A wrapped command line cannot be
+  pasted back into a shell, which is the main thing users do with one.
+- **NFR-3** Commands are rendered with `shlex.join`, so a logged line is a valid shell command.
+- **FR-11** An `eval`-mode function's script is **logged but never traced with `set -x`** — it
+  is evaluated by the caller's interactive shell, where xtrace would persist after it returns.
+
+### Error reporting
+
+- **FR-12** Quiet mode keeps its existing behaviour: output is captured and the captured stderr
+  becomes the `RuntimeError` message on failure. That is the only reason quiet mode can say
+  anything useful about a failure at all.
+- **FR-13** Verbose mode raises `RuntimeError("exit code N")` instead, since the real output has
+  already streamed past and repeating the argv in the message adds nothing.
+- **FR-14** At `-v`, a failing `devstuff run` reports the script's real exit code, which is
+  otherwise invisible — `run_cmd` always exits 1 regardless.
+
+---
+
+## 3. Out of scope
+
+- Verbose output from the `agent` subsystem's tool calls (it has its own transcript).
+- Verbose output from configurators (`configure/`), which already preview what they do.
+- Redaction. Verbose output can contain whatever the user passed as a function parameter;
+  nothing in devstuff handles secrets, and pretending otherwise would be worse than the
+  current honest behaviour.

devstuff-2.2.0/docs/specs/verbose-mode/stack-decisions.md

@@ -0,0 +1,91 @@
+# Stack decisions: verbose mode
+
+**Date:** 2026-08-04
+
+---
+
+## SD-1 — A module-level level, not Python's `logging`
+
+**Chosen:** a tiny `verbose.py` holding an int and five printers on a Rich stderr console.
+
+**Rejected:** `logging` with a `StreamHandler` and `setLevel`. It is the obvious answer and it
+buys nothing here: there are no log files, no per-module filtering, no third-party libraries
+whose loggers we want to reconfigure, and no format that survives `logging`'s own formatter
+better than an f-string. What it *would* add is a global side effect on `logging.root` from a
+CLI that other tools may import, plus a second styling system alongside Rich.
+
+**Rejected:** threading a `verbose: int` parameter through `install()` / `remove()` /
+`is_installed()`. The subprocess calls that need it are four layers below the command handler,
+across `GenericTool`, `function_runner` and the strategy dicts — every one of those signatures
+would grow a parameter that only two lines in each ever read. `Tool` is an ABC with third-party
+implementations in principle; changing its contract for logging is the wrong trade.
+
+## SD-2 — Set by a Click callback with `expose_value=False`
+
+The option is applied to every command by `cli._add_verbose_option`, walking the group tree.
+
+**Rejected:** decorating each command with `@verbose.option`. That is what the first draft did,
+and it immediately produced the bug it was always going to: `devstuff list -v` errored with
+"No such option" because `list` hadn't been decorated. Users type `-v` on whatever command is
+in front of them; a flag that works on four commands out of fourteen is worse than none.
+
+**Rejected:** a group-level option only. `devstuff -v install x` is the unusual spelling; every
+other CLI accepts `install -v` and users will type it first.
+
+`expose_value=False` keeps the level out of command signatures, which is the point of SD-1.
+
+## SD-3 — Everything to stderr, no exceptions
+
+This is a correctness constraint, not a style choice. `devstuff run <key>` for a `register: eval`
+function prints shell code to stdout precisely so `eval "$(devstuff run key)"` works. A verbose
+line on that channel is not noise — it is **code the user's shell will execute**.
+
+The logger therefore has no stdout path at all. A per-call-site "don't log in eval mode" check
+would work today and be forgotten the first time someone adds a log line.
+
+## SD-4 — `bash -x` for extra-verbose, not a custom tracer
+
+`-vv` runs script bodies under `bash -x`. Bash already prints each expanded command with its
+variables substituted, which is exactly what "which line failed" needs and is not reproducible
+by logging the script text alone.
+
+**Not applied to `register: eval` scripts.** `set -x` inside evaluated code persists in the
+caller's interactive shell after the function returns — the trace would follow them around until
+they typed `set +x`. Those scripts are logged instead.
+
+## SD-5 — Two subprocess helpers, split by "does this change anything"
+
+`generic.py` now has `_run` (state-changing: streams when verbose, raises `RuntimeError`) and
+`_probe` (captures, never raises, logs at `-vv`). Everything that shells out goes through one of
+them, which is what makes the flag's coverage complete rather than a list of places someone
+remembered.
+
+The split is by **consequence**, not by whether output is captured: a probe's output is captured
+because the caller parses it, so verbosity can only add logging there. The `log_at` parameter
+exists for the two commands that are best-effort *actions* (`apt-get update`, a git tool's
+`git_remove_cmd`) — captured and non-fatal like a probe, but work the user should see at `-v`.
+
+**Rejected:** logging probes at `-v`. Measured: `devstuff -vv list` emits ~60 probe lines before
+any output. At `-v` that would hide the one line the user asked for.
+
+## SD-6 — The spinner is swapped out, not left running
+
+`verbose.step` is a spinner when quiet and a printed line when verbose. Rich's `console.status`
+repaints its own line on a timer; with a subprocess writing to the same terminal, the two
+interleave and the result is unreadable. This also fixed the pre-existing gap where npm/uvx/git
+installs used a spinner *and* captured output, so the old `-v` flag did nothing for them.
+
+## SD-7 — `DEVSTUFF_VERBOSE` can only be raised by `-v`, never lowered
+
+`set_level(max(level(), value))` in the callback. The env var is for a context that can't pass
+flags (a wrapper script, CI); an explicit `-v` on top of `DEVSTUFF_VERBOSE=2` shouldn't quieten
+anything down, and `-v` meaning "less verbose" would be indefensible.
+
+---
+
+## Open questions
+
+| Question | Status |
+|----------|--------|
+| Should `-vv` redact function parameter values that look like secrets? | Open. Deliberately not done in v1 (see spec §3) — a partial redactor implies a guarantee devstuff can't make. |
+| Should the agent's tool calls honour the level? | Open. The agent prints its own transcript; a second channel may just duplicate it. |

{devstuff-2.0.0 → devstuff-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devstuff"
-version = "2.0.0"
+version = "2.2.0"
 description = "Development environment setup CLI for Linux"
 readme = "README.md"
 requires-python = ">=3.11"

{devstuff-2.0.0 → devstuff-2.2.0}/src/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()

{devstuff-2.0.0 → devstuff-2.2.0}/src/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:

{devstuff-2.0.0 → devstuff-2.2.0}/src/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)

{devstuff-2.0.0 → devstuff-2.2.0}/src/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)

{devstuff-2.0.0 → devstuff-2.2.0}/src/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.")