devstuff 2.10.0__py3-none-any.whl → 2.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
dev_setup/cli.py CHANGED
@@ -33,6 +33,7 @@ def _register_commands() -> None:
33
33
  from dev_setup.commands.install_cmd import install_cmd
34
34
  from dev_setup.commands.links_cmd import links_cmd
35
35
  from dev_setup.commands.list_cmd import list_cmd
36
+ from dev_setup.commands.outdated_cmd import outdated_cmd
36
37
  from dev_setup.commands.remove_cmd import remove_cmd
37
38
  from dev_setup.commands.run_cmd import run_cmd
38
39
  from dev_setup.commands.skills_cmd import skills_cmd
@@ -44,6 +45,7 @@ def _register_commands() -> None:
44
45
  cli.add_command(remove_cmd, "uninstall")
45
46
  cli.add_command(doctor_cmd, "doctor")
46
47
  cli.add_command(update_cmd, "update")
48
+ cli.add_command(outdated_cmd, "outdated")
47
49
  cli.add_command(configure_cmd, "configure")
48
50
  cli.add_command(configure_cmd, "config")
49
51
  cli.add_command(add_cmd, "add")
@@ -25,6 +25,7 @@ def print_help() -> None:
25
25
  ("install", "[package ...]", "Install packages (interactive if no args)"),
26
26
  ("remove", "<package ...>", "Uninstall installed packages"),
27
27
  ("update", "[package ...] [--version]", "Update packages (interactive if no args)"),
28
+ ("outdated", "[package ...] [--json]", "Show which installed packages have updates"),
28
29
  ("configure", "[tool] [--list] [--path]", "Set up a tool with a guided wizard"),
29
30
  ("add", "", "Add a custom package (guided wizard)"),
30
31
  ("delete", "<key>", "Remove a custom package from the registry"),
@@ -0,0 +1,141 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import sys
5
+ from contextlib import nullcontext
6
+
7
+ import click
8
+ from rich.markup import escape
9
+
10
+ from dev_setup import registry, ui, verbose
11
+ from dev_setup.base import Tool
12
+ from dev_setup.updates import Row, State, collect_candidates, make_row, sort_rows, summarize
13
+
14
+ # One glyph + wording per state. `unknown` and `unsupported` deliberately share nothing
15
+ # with `current`: "could not check" must never read as "up to date" (spec FR-7).
16
+ _STATUS: dict[State, tuple[str, str]] = {
17
+ State.OUTDATED: (ui.AMBER, "⬆ outdated"),
18
+ State.CURRENT: (ui.GREEN, "✔ current"),
19
+ State.UNKNOWN: (ui.GRAY, "? unknown"),
20
+ State.UNSUPPORTED: (ui.GRAY, "– can't check"),
21
+ State.NOT_INSTALLED: (ui.GRAY, "○ not installed"),
22
+ }
23
+
24
+ # Order of the closing summary line; the wording is each state's own name.
25
+ _SUMMARY_ORDER = (
26
+ State.OUTDATED, State.CURRENT, State.UNKNOWN, State.UNSUPPORTED, State.NOT_INSTALLED,
27
+ )
28
+
29
+ _FOOTER_NAMES = 12
30
+
31
+
32
+ @click.command("outdated")
33
+ @click.option(
34
+ "--updates-only", is_flag=True,
35
+ help="Show only tools with an update available (the summary still counts everything).",
36
+ )
37
+ @click.option(
38
+ "--all", "show_all", is_flag=True,
39
+ help="List the tools that can't be checked (bash/script installers) instead of one footer line.",
40
+ )
41
+ @click.option(
42
+ "--json", "as_json", is_flag=True,
43
+ help="Write a JSON array to stdout and nothing else. Includes every state.",
44
+ )
45
+ @click.argument("packages", nargs=-1)
46
+ def outdated_cmd(packages: tuple[str, ...], updates_only: bool, show_all: bool, as_json: bool) -> None:
47
+ """Show which installed packages have a newer version available.
48
+
49
+ Read-only: nothing is installed, updated or written. Each package is reported as
50
+ outdated, current, unknown (a check exists but couldn't answer), or unsupported
51
+ (script/bash installers have no way to check). Unknown and unsupported are never
52
+ reported as current. Use `devstuff update` to act on the result.
53
+
54
+ The exit status says whether the lookup ran, not what it found: 0 even when
55
+ updates are available.
56
+ """
57
+ named: list[Tool] | None = None
58
+ if packages:
59
+ named = []
60
+ for key in packages:
61
+ tool = registry.get(key)
62
+ if tool is None:
63
+ click.echo(f"Unknown package: '{key}'", err=True)
64
+ sys.exit(1)
65
+ named.append(tool)
66
+
67
+ interactive = sys.stdout.isatty() and not as_json
68
+ if interactive:
69
+ ui.print_banner()
70
+ progress = (
71
+ verbose.step("Checking installed packages for updates...") if interactive else nullcontext()
72
+ )
73
+ with progress:
74
+ candidates = collect_candidates(named)
75
+
76
+ result = [make_row(tool, status) for tool, status in candidates]
77
+ if named is not None:
78
+ found = {tool.key for tool, _ in candidates}
79
+ result += [make_row(t, None, installed=False) for t in named if t.key not in found]
80
+
81
+ result = sort_rows(result)
82
+ shown = [r for r in result if r.state is State.OUTDATED] if updates_only else result
83
+
84
+ if as_json:
85
+ click.echo(json.dumps([r.to_json() for r in shown], indent=2))
86
+ return
87
+
88
+ _render(shown, result, updates_only=updates_only, show_all=show_all)
89
+
90
+
91
+ def _render(shown: list[Row], everything: list[Row], *, updates_only: bool, show_all: bool) -> None:
92
+ if not everything:
93
+ ui.info("No installed packages to check.")
94
+ return
95
+
96
+ collapsed = [] if show_all else [r for r in shown if r.state is State.UNSUPPORTED]
97
+ rows = [r for r in shown if r not in collapsed]
98
+
99
+ if rows:
100
+ tbl = ui.table()
101
+ tbl.add_column("Package", style="bold", no_wrap=True)
102
+ tbl.add_column("Type", style=ui.CYAN, no_wrap=True)
103
+ tbl.add_column("Installed", style=ui.GRAY, no_wrap=True)
104
+ tbl.add_column("Latest", style=ui.GRAY, no_wrap=True)
105
+ tbl.add_column("Status")
106
+ for r in rows:
107
+ tbl.add_row(r.key, r.type, r.installed or "", r.latest or "", _status_cell(r))
108
+ ui.console.print(tbl)
109
+ elif updates_only:
110
+ ui.info("No updates available.")
111
+
112
+ if collapsed:
113
+ _footer(collapsed)
114
+
115
+ ui.dim(_summary(everything))
116
+
117
+
118
+ def _status_cell(r: Row) -> str:
119
+ color, label = _STATUS[r.state]
120
+ cell = f"[{color}]{label}[/]"
121
+ if r.note:
122
+ # Escaped: a note is free text from a checker, and Rich would read "[docs]" as markup.
123
+ cell += f"\n[{ui.GRAY}]{escape(r.note)}[/]"
124
+ return cell
125
+
126
+
127
+ def _footer(unsupported: list[Row]) -> None:
128
+ kinds = ", ".join(sorted({r.type for r in unsupported}))
129
+ names = [r.key for r in unsupported]
130
+ listed = ", ".join(names[:_FOOTER_NAMES])
131
+ if len(names) > _FOOTER_NAMES:
132
+ listed += f", +{len(names) - _FOOTER_NAMES} more (--all lists them)"
133
+ noun = "tool" if len(names) == 1 else "tools"
134
+ ui.dim(f"{len(names)} {noun} can't be checked ({kinds} installers): {listed}")
135
+
136
+
137
+ def _summary(rows: list[Row]) -> str:
138
+ counts = summarize(rows)
139
+ return " · ".join(
140
+ f"{counts[s]} {s.value.replace('-', ' ')}" for s in _SUMMARY_ORDER if counts[s]
141
+ )
@@ -1,14 +1,13 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import sys
4
- from concurrent.futures import ThreadPoolExecutor
5
4
 
6
5
  import click
7
6
  import questionary
8
7
 
9
8
  from dev_setup import registry, ui
10
9
  from dev_setup.base import Tool
11
- from dev_setup.generic import UpdateStatus
10
+ from dev_setup.updates import collect_candidates
12
11
 
13
12
 
14
13
  @click.command("update")
@@ -74,28 +73,11 @@ def _update_one(tool: Tool, version: str | None) -> bool:
74
73
  return False
75
74
 
76
75
 
77
- def _collect_update_candidates() -> list[tuple[Tool, UpdateStatus]]:
78
- """Return (tool, UpdateStatus) for every installed tool, probed concurrently.
79
-
80
- Pure data-gathering, kept free of any UI/prompt code so it can be exercised
81
- directly without a terminal.
82
- """
83
- tools = registry.all_tools()
84
- with ThreadPoolExecutor(max_workers=8) as pool:
85
- installed_flags = list(pool.map(lambda t: t.is_installed(), tools))
86
- installed = [t for t, flag in zip(tools, installed_flags, strict=True) if flag]
87
- if not installed:
88
- return []
89
- with ThreadPoolExecutor(max_workers=8) as pool:
90
- statuses = list(pool.map(lambda t: t.check_for_update(), installed)) # type: ignore[attr-defined]
91
- return list(zip(installed, statuses, strict=True))
92
-
93
-
94
76
  def _update_interactive() -> None:
95
77
  ui.print_banner()
96
78
 
97
79
  with ui.spinner("Checking installed packages for available updates..."):
98
- candidates = _collect_update_candidates()
80
+ candidates = collect_candidates()
99
81
 
100
82
  if not candidates:
101
83
  ui.info("No installed packages to update.")
dev_setup/generic.py CHANGED
@@ -2,13 +2,16 @@ from __future__ import annotations
2
2
 
3
3
  import functools
4
4
  import hashlib
5
+ import os
5
6
  import re
6
7
  import shlex
7
8
  import shutil
8
9
  import subprocess
10
+ import threading
9
11
  from collections.abc import Callable
10
12
  from dataclasses import dataclass, fields
11
13
  from pathlib import Path
14
+ from typing import NamedTuple, TypeVar
12
15
 
13
16
  from dev_setup import verbose
14
17
  from dev_setup.base import Tool
@@ -34,11 +37,15 @@ class UpdateStatus:
34
37
 
35
38
  `available` is None when the install type has no reliable way to check
36
39
  (script/bash) or the probe itself failed (offline, missing tool, etc).
40
+
41
+ `note` is a short human reason a checker could not answer ("not installed via `uv
42
+ tool`"). Checkers set it only where they actually know why; it is empty otherwise.
37
43
  """
38
44
 
39
45
  current: str = ""
40
46
  latest: str = ""
41
47
  available: bool | None = None
48
+ note: str = ""
42
49
 
43
50
 
44
51
  def _run(cmd: list, *, cwd: Path | None = None) -> None:
@@ -420,42 +427,102 @@ def _check_update_npm(tool: GenericTool) -> UpdateStatus:
420
427
  current = _npm_installed_version(tool.npm_name)
421
428
  latest = _npm_latest_version(tool.npm_name)
422
429
  if not latest:
423
- return UpdateStatus(current=current)
430
+ return UpdateStatus(current=current, note="couldn't fetch the latest version from npm")
424
431
  return UpdateStatus(current=current, latest=latest, available=bool(current) and current != latest)
425
432
 
426
433
 
427
- def _uv_tool_current_version(pkg: str) -> str:
434
+ _T = TypeVar("_T")
435
+
436
+
437
+ def _once(fn: Callable[[], _T]) -> Callable[[], _T]:
438
+ """Memoise a no-argument probe so concurrent first callers wait instead of racing.
439
+
440
+ `functools.lru_cache` is not enough here: it caches *results*, so every thread that
441
+ arrives before the first call returns misses and runs the subprocess itself. With
442
+ `devstuff update` probing on an 8-worker pool, that was one `uv tool list --outdated`
443
+ per uv tool rather than one per run (docs/specs/outdated, finding F-1).
444
+
445
+ The answer is fixed for the life of the process, so nothing here may be called after
446
+ something that changes it (an install or update) and expected to see the change;
447
+ `cache_clear()` exists for tests and for any future caller that does.
448
+ """
449
+ lock = threading.Lock()
450
+ box: list[_T] = []
451
+
452
+ @functools.wraps(fn)
453
+ def wrapper() -> _T:
454
+ with lock:
455
+ if not box:
456
+ box.append(fn())
457
+ return box[0]
458
+
459
+ def cache_clear() -> None:
460
+ with lock:
461
+ box.clear()
462
+
463
+ wrapper.cache_clear = cache_clear # type: ignore[attr-defined]
464
+ return wrapper
465
+
466
+
467
+ class _Answer(NamedTuple):
468
+ """What a shared probe learned: its data, or None plus the reason it couldn't answer."""
469
+
470
+ data: dict[str, str] | None
471
+ why: str = ""
472
+
473
+
474
+ def _env_true(name: str) -> bool:
475
+ return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
476
+
477
+
478
+ @_once
479
+ def _uv_tool_versions() -> _Answer:
480
+ """Package name -> installed version, for every `uv tool`. One call per process."""
428
481
  uv = shutil.which("uv")
429
482
  if not uv:
430
- return ""
483
+ return _Answer(None, "uv is not installed")
431
484
  try:
432
485
  r = _probe(
433
486
  [uv, "tool", "list", "--color", "never"], capture_output=True, text=True, timeout=15,
434
487
  )
435
488
  except Exception:
436
- return ""
489
+ return _Answer(None, "couldn't run `uv tool list`")
490
+ if r.returncode != 0:
491
+ return _Answer(None, "`uv tool list` failed")
492
+ result: dict[str, str] = {}
437
493
  for line in r.stdout.splitlines():
438
494
  if line.startswith((" ", "-", "\t")):
439
495
  continue # sub-lines (installed executables) under each tool
440
- m = re.match(rf"^{re.escape(pkg)}\s+v?([\w.\-+]+)", line.strip())
496
+ m = re.match(r"^(\S+)\s+v?([\w.\-+]+)", line.strip())
441
497
  if m:
442
- return m.group(1)
443
- return ""
498
+ result[m.group(1)] = m.group(2)
499
+ return _Answer(result)
500
+
444
501
 
502
+ @_once
503
+ def _uv_outdated_map() -> _Answer:
504
+ """Package name -> latest version, for every outdated `uv tool`. One call per process.
445
505
 
446
- @functools.lru_cache(maxsize=1)
447
- def _uv_outdated_map() -> dict[str, str]:
448
- """Package name -> latest version, for every outdated `uv tool`. One call per process."""
506
+ A failed probe must not look like "nothing is outdated": `uv tool list --outdated`
507
+ exits 2 with an error when it can't reach the index, and with empty stdout that would
508
+ read as every tool being current. With `UV_OFFLINE` set it instead exits 0 and prints
509
+ nothing — indistinguishable from a real "all current" — so the variable itself is the
510
+ only signal we have, and we don't ask. (Measured 2026-10-10; docs/specs/outdated.)
511
+ """
512
+ if _env_true("UV_OFFLINE"):
513
+ return _Answer(None, "uv is offline (UV_OFFLINE), so it can't look for newer versions")
449
514
  uv = shutil.which("uv")
450
515
  if not uv:
451
- return {}
516
+ return _Answer(None, "uv is not installed")
452
517
  try:
453
518
  r = _probe(
454
519
  [uv, "tool", "list", "--outdated", "--color", "never"],
455
520
  capture_output=True, text=True, timeout=20,
456
521
  )
457
522
  except Exception:
458
- return {}
523
+ return _Answer(None, "couldn't reach the package index")
524
+ if r.returncode != 0:
525
+ return _Answer(None, "couldn't reach the package index")
459
526
  result: dict[str, str] = {}
460
527
  for line in r.stdout.splitlines():
461
528
  if line.startswith((" ", "-", "\t")):
@@ -463,16 +530,26 @@ def _uv_outdated_map() -> dict[str, str]:
463
530
  m = re.match(r"^(\S+)\s+v?[\w.\-+]+\s*\[latest:\s*([\w.\-+]+)\]", line.strip())
464
531
  if m:
465
532
  result[m.group(1)] = m.group(2)
466
- return result
533
+ return _Answer(result)
467
534
 
468
535
 
469
536
  def _check_update_uvx(tool: GenericTool) -> UpdateStatus:
470
537
  if not tool.pip_name or not shutil.which("uv"):
471
538
  return UpdateStatus()
472
- current = _uv_tool_current_version(tool.pip_name)
473
- latest = _uv_outdated_map().get(tool.pip_name, "")
539
+ installed = _uv_tool_versions()
540
+ if installed.data is None:
541
+ return UpdateStatus(note=installed.why)
542
+ current = installed.data.get(tool.pip_name, "")
543
+ if not current:
544
+ # On PATH (so is_installed() passed) but not managed by `uv tool` — e.g. it came
545
+ # from a project venv. We can't say what uv would upgrade it to.
546
+ return UpdateStatus(note="not installed via `uv tool`")
547
+ outdated = _uv_outdated_map()
548
+ if outdated.data is None:
549
+ return UpdateStatus(current=current, note=outdated.why)
550
+ latest = outdated.data.get(tool.pip_name, "")
474
551
  if not latest:
475
- return UpdateStatus(current=current, available=False if current else None)
552
+ return UpdateStatus(current=current, available=False)
476
553
  return UpdateStatus(current=current, latest=latest, available=True)
477
554
 
478
555
 
@@ -490,7 +567,7 @@ def _check_update_apt(tool: GenericTool) -> UpdateStatus:
490
567
  try:
491
568
  r = _probe(["apt-cache", "policy", pkg], capture_output=True, text=True, timeout=10)
492
569
  except Exception:
493
- return UpdateStatus(current=current)
570
+ return UpdateStatus(current=current, note="couldn't run `apt-cache policy`")
494
571
  candidate = ""
495
572
  for line in r.stdout.splitlines():
496
573
  line = line.strip()
@@ -498,7 +575,7 @@ def _check_update_apt(tool: GenericTool) -> UpdateStatus:
498
575
  candidate = line.split(":", 1)[1].strip()
499
576
  break
500
577
  if not candidate or candidate == "(none)":
501
- return UpdateStatus(current=current)
578
+ return UpdateStatus(current=current, note="apt has no candidate version (try `apt update`)")
502
579
  return UpdateStatus(current=current, latest=candidate, available=bool(current) and current != candidate)
503
580
 
504
581
 
@@ -507,7 +584,7 @@ def _check_update_git(tool: GenericTool) -> UpdateStatus:
507
584
  return UpdateStatus()
508
585
  dest = _git_clone_dest(tool.git_url)
509
586
  if not dest.exists():
510
- return UpdateStatus()
587
+ return UpdateStatus(note=f"no clone found at {dest}")
511
588
  try:
512
589
  r = _probe(
513
590
  ["git", "-C", str(dest), "rev-parse", "--short", "HEAD"],
@@ -524,7 +601,7 @@ def _check_update_git(tool: GenericTool) -> UpdateStatus:
524
601
  except Exception:
525
602
  remote_full = ""
526
603
  if not remote_full:
527
- return UpdateStatus(current=current)
604
+ return UpdateStatus(current=current, note="couldn't reach the git remote")
528
605
  latest = remote_full[:7]
529
606
  if not current:
530
607
  return UpdateStatus(latest=latest)
@@ -540,6 +617,16 @@ _UPDATE_CHECKERS: dict[str, Callable[[GenericTool], UpdateStatus]] = {
540
617
  }
541
618
 
542
619
 
620
+ def supports_update_check(install_type: str) -> bool:
621
+ """Whether this install type has an update checker at all.
622
+
623
+ Distinct from "the checker answered": a checker that fails returns the same empty
624
+ UpdateStatus a missing one does, so the *type* is the only reliable way to tell
625
+ "cannot be checked" from "the check failed".
626
+ """
627
+ return install_type in _UPDATE_CHECKERS
628
+
629
+
543
630
  # -- Remove strategies -----------------------------------------------------------
544
631
 
545
632
 
dev_setup/updates.py ADDED
@@ -0,0 +1,148 @@
1
+ """Probing installed tools for newer versions — the one place `update` and `outdated` share.
2
+
3
+ Kept free of UI and prompt code so it can be exercised without a terminal, and so
4
+ `outdated --json` can call it without risk of writing anything to stdout.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Iterable, Sequence
10
+ from concurrent.futures import ThreadPoolExecutor
11
+ from dataclasses import dataclass
12
+ from enum import StrEnum
13
+
14
+ from dev_setup import registry
15
+ from dev_setup.base import Tool
16
+ from dev_setup.generic import UpdateStatus, supports_update_check
17
+
18
+ _MAX_WORKERS = 8
19
+
20
+
21
+ def _probe_one(tool: Tool) -> tuple[Tool, UpdateStatus] | None:
22
+ """`(tool, status)` if the tool is installed, else None. Never raises.
23
+
24
+ One tool's probe failing must not take the whole run down: a checker that raises
25
+ becomes an empty status ("couldn't tell"), which is the same answer a checker that
26
+ catches its own error already gives. A tool whose `is_installed()` raises is treated
27
+ as not installed — we cannot claim it is, and an `unknown` row for it would invite
28
+ an update of something that may not be there.
29
+ """
30
+ try:
31
+ if not tool.is_installed():
32
+ return None
33
+ except Exception:
34
+ return None
35
+ # `check_for_update` lives on GenericTool, not the Tool ABC: it is not part of the
36
+ # contract every tool implementation must meet, so absence means "can't tell".
37
+ check = getattr(tool, "check_for_update", None)
38
+ if check is None:
39
+ return tool, UpdateStatus()
40
+ try:
41
+ return tool, check()
42
+ except Exception:
43
+ return tool, UpdateStatus()
44
+
45
+
46
+ def collect_candidates(
47
+ tools: Sequence[Tool] | None = None,
48
+ ) -> list[tuple[Tool, UpdateStatus]]:
49
+ """Return `(tool, UpdateStatus)` for every *installed* tool, probed concurrently.
50
+
51
+ `tools` defaults to the whole registry; pass a subset to check only those. Order
52
+ follows the input. Uninstalled tools are omitted — callers that need to report them
53
+ compare against what they asked for.
54
+ """
55
+ if tools is None:
56
+ tools = registry.all_tools()
57
+ with ThreadPoolExecutor(max_workers=_MAX_WORKERS) as pool:
58
+ probed = list(pool.map(_probe_one, tools))
59
+ return [p for p in probed if p is not None]
60
+
61
+
62
+ # -- Classification ------------------------------------------------------------------
63
+
64
+
65
+ class State(StrEnum):
66
+ """What we can honestly say about one tool. Values are the `--json` spellings."""
67
+
68
+ OUTDATED = "outdated"
69
+ CURRENT = "current"
70
+ # A checker exists for this install type but couldn't answer (offline, tool not
71
+ # managed by that mechanism, probe error).
72
+ UNKNOWN = "unknown"
73
+ # No checker exists for this install type — script/bash installers. Nothing the user
74
+ # does to their network will change this.
75
+ UNSUPPORTED = "unsupported"
76
+ NOT_INSTALLED = "not-installed"
77
+
78
+
79
+ def classify(install_type: str, status: UpdateStatus | None, *, installed: bool = True) -> State:
80
+ """Map a tool's install type and probe result to exactly one `State`.
81
+
82
+ `unknown` and `unsupported` are never `current`: "could not check" must not read as
83
+ "up to date". They are told apart by *install type*, not by the status — a checker
84
+ that fails and a type with no checker return the same empty `UpdateStatus`, so
85
+ the status alone cannot distinguish them (spec SD-2).
86
+ """
87
+ if not installed:
88
+ return State.NOT_INSTALLED
89
+ if not supports_update_check(install_type):
90
+ return State.UNSUPPORTED
91
+ if status is None or status.available is None:
92
+ return State.UNKNOWN
93
+ return State.OUTDATED if status.available else State.CURRENT
94
+
95
+
96
+ @dataclass(frozen=True)
97
+ class Row:
98
+ """One tool's answer, in the shape `outdated` renders and `--json` emits."""
99
+
100
+ key: str
101
+ type: str
102
+ state: State
103
+ installed: str | None
104
+ latest: str | None
105
+ # Why a row is `unknown`, when a checker knows (UpdateStatus.note); otherwise empty.
106
+ note: str = ""
107
+
108
+ def to_json(self) -> dict[str, str | None]:
109
+ return {
110
+ "key": self.key,
111
+ "type": self.type,
112
+ "state": self.state.value,
113
+ "installed": self.installed,
114
+ "latest": self.latest,
115
+ "note": self.note,
116
+ }
117
+
118
+
119
+ def make_row(tool: Tool, status: UpdateStatus | None, *, installed: bool = True) -> Row:
120
+ install_type = tool.install_type
121
+ state = classify(install_type, status, installed=installed)
122
+ if state is State.NOT_INSTALLED or status is None:
123
+ return Row(tool.key, install_type, state, None, None)
124
+ return Row(
125
+ tool.key, install_type, state, status.current or None, status.latest or None, status.note
126
+ )
127
+
128
+
129
+ # Display order (FR-9). `unsupported` goes last: it is the long, low-information tail.
130
+ _ORDER = {
131
+ State.OUTDATED: 0,
132
+ State.UNKNOWN: 1,
133
+ State.CURRENT: 2,
134
+ State.NOT_INSTALLED: 3,
135
+ State.UNSUPPORTED: 4,
136
+ }
137
+
138
+
139
+ def sort_rows(rows: Iterable[Row]) -> list[Row]:
140
+ return sorted(rows, key=lambda r: (_ORDER[r.state], r.key))
141
+
142
+
143
+ def summarize(rows: Iterable[Row]) -> dict[State, int]:
144
+ """Count rows per state. Every state is present, so the counts always sum to the rows."""
145
+ counts = dict.fromkeys(State, 0)
146
+ for r in rows:
147
+ counts[r.state] += 1
148
+ return counts
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.10.0
3
+ Version: 2.11.0
4
4
  Summary: Development environment setup CLI for Linux
5
5
  Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
6
6
  Author-email: Sawyer <sawyerksu@gmail.com>
@@ -314,6 +314,64 @@ reinstall.
314
314
 
315
315
  ---
316
316
 
317
+ ### `outdated`
318
+
319
+ Show which installed packages have a newer version available. It is **read-only** — nothing is
320
+ installed, updated or written — so it is safe in scripts and CI. `devstuff update` is what acts on
321
+ the answer.
322
+
323
+ ```bash
324
+ devstuff outdated # every installed package
325
+ devstuff outdated codex nvm # just these (one that isn't installed is reported as such)
326
+ devstuff outdated --updates-only # hide everything except packages with an update
327
+ devstuff outdated --all # list the packages that can't be checked, instead of one footer line
328
+ devstuff outdated --json # machine-readable; nothing else is written to stdout
329
+ ```
330
+
331
+ ```
332
+ ╭────────────────────────────────────────────────────────────────────────╮
333
+ │ Package Type Installed Latest Status │
334
+ ├────────────────────────────────────────────────────────────────────────┤
335
+ │ codex npm 0.162.0 0.162.1 ⬆ outdated │
336
+ │ commitizen uvx ? unknown │
337
+ │ not installed via `uv tool` │
338
+ │ claude-code npm 2.1.296 2.1.296 ✔ current │
339
+ ╰────────────────────────────────────────────────────────────────────────╯
340
+ 8 tools can't be checked (bash installers): bat, devin, gh, nerd-font, nvm, pi, starship, uv
341
+ 1 outdated · 1 current · 1 unknown · 8 unsupported
342
+ ```
343
+
344
+ Every package lands in exactly one state:
345
+
346
+ | State | Meaning |
347
+ |-------|---------|
348
+ | `outdated` | A different version is available. |
349
+ | `current` | The check ran and found nothing newer. |
350
+ | `unknown` | A check exists for this install type but couldn't answer — offline, or the package isn't managed by that mechanism. A dim line says why when devstuff knows. |
351
+ | `unsupported` | This install type has no way to check at all. That is every `script`/`bash` package, which on the bundled catalog is most of them. |
352
+ | `not-installed` | Named explicitly on the command line, but not installed. |
353
+
354
+ `unknown` and `unsupported` are never reported as `current`, and the summary counts them
355
+ separately, so "could not check" can't be mistaken for "up to date". Unsupported packages collapse
356
+ to one footer line (still naming them); `--all` expands them.
357
+
358
+ - **"Outdated" means *different*, not *older*.** The `npm` and `apt` checks compare for inequality,
359
+ so a locally newer version (a prerelease, a held package) is reported as outdated. For `uvx`/`pip`
360
+ packages the check is "uv doesn't list it as outdated", so there is no latest version to show for
361
+ a `current` row.
362
+ - **`apt` reflects your last `apt update`.** devstuff doesn't refresh package lists for a read-only report.
363
+ - **uv offline.** With `UV_OFFLINE` set, uv answers from cache or says nothing, which can't be told
364
+ from "all current" — so devstuff reports `unknown` rather than ask. A `offline = true` in uv's
365
+ config file can't be detected.
366
+
367
+ The exit status says whether the lookup ran, not what it found: `0` even when updates are
368
+ available, `1` only for an unknown package name. With `--json`, stdout is one array — even at
369
+ `-vv`, whose log lines go to stderr — of `{"key", "type", "state", "installed", "latest", "note"}`
370
+ objects, with `null` for an absent version and an empty `note` when no reason is known. `--json`
371
+ includes the `unsupported` rows; `--updates-only` applies to it too.
372
+
373
+ ---
374
+
317
375
  ### `configure`
318
376
 
319
377
  Set up an installed tool through a guided wizard, previewing the result before anything is
@@ -4,14 +4,14 @@ dev_setup/agent_tools.schema.json,sha256=veXnih00xW4w9yK3ruWz-npUrCnJmcQpQdFvfcu
4
4
  dev_setup/agent_tools.yaml,sha256=56E70B1W7hBqjGhYhhCAGzFQvi1nUZ04cnNiqZlMjyY,4506
5
5
  dev_setup/base.py,sha256=j2EQ5gzeGgtveWQN_BgbLcZianMENJ7PQy8EQ9J9MPE,1946
6
6
  dev_setup/catalog.py,sha256=PrimTBUYoh8cW9QYhXUxP8qSMeK51kzQjUoPEGD9EBw,6530
7
- dev_setup/cli.py,sha256=IVrIIeBGpgf1JsY8nB-ISQkwqye6F8gnbjB0A8aJGec,3110
7
+ dev_setup/cli.py,sha256=SfC2YH0KrdPGShRcVmf_fjjt8A5DOZ3fW-ED3l4O_O4,3217
8
8
  dev_setup/doctor.py,sha256=1shwNLT5wFxiGT5oBVqbF478B7lcHVwT_e50aFb2I20,16962
9
9
  dev_setup/function_runner.py,sha256=08F6jvB9-oOyE5ivYtRjnL16JTGsfRnkpvkjSVrJhsM,6957
10
10
  dev_setup/functions.schema.json,sha256=VVdpH3xWsdbtqw47S1QqpBcs4O9wd3XZ_s0Q3sGwv0Q,6220
11
11
  dev_setup/functions.yaml,sha256=n3yn8N9FN9TzMRMMgYREmDACUAsO1XmGDuNB-aOVl8U,13477
12
12
  dev_setup/functions_catalog.py,sha256=YgR2hY9HM1iol1AZcF-_j02EXCP9U4P3e_5eWes9KH0,7116
13
13
  dev_setup/functions_registry.py,sha256=YSl-VgNXPf0hj4WgReg-pZUj4fAjFlwvC165dgon_BE,3682
14
- dev_setup/generic.py,sha256=Tr7YAkS_SXjExJpyNw3palDuaiNn1TcAoeZ0wHdXIeM,28424
14
+ dev_setup/generic.py,sha256=rLDrTYFVii9bslK8dP_sOQVuwRQZcien2MKwxIuN19k,32191
15
15
  dev_setup/links.schema.json,sha256=V9_1UA8Ejfu0j6-VczH0blW1mlGupXx56NhApLtHHKc,1938
16
16
  dev_setup/links.yaml,sha256=t3-_cbCzA6PqnjZDIe3-zgCiyyFo7AcUS3Aj2Y15XGw,3417
17
17
  dev_setup/links_catalog.py,sha256=Xe7s9oqiCrfQPUwE-X9o6p5VkU7mH9PjY9NMyn6VbHg,4610
@@ -19,6 +19,7 @@ dev_setup/links_registry.py,sha256=xyq49oH1u_CX85UcizKSuxuy_pzurNoDwSRg3YftUMY,2
19
19
  dev_setup/registry.py,sha256=8lrk6EXCCWk1WNeNnCGLTJ-v8rpCs7-TLYtVXgiuxnA,2243
20
20
  dev_setup/tools.yaml,sha256=m2MEYq_mZuzEU8vCJgPWHdhLuqRjQGNWheqhwQgMXXQ,34234
21
21
  dev_setup/ui.py,sha256=bm4VBv-DVs8h7v6roHUNQ7TqmUoXcBRNu78Xex-Qx-0,7505
22
+ dev_setup/updates.py,sha256=D6dH6G_Bv07XWSyzXvYESbV5s2d0N7euHu69zUyBbs4,5289
22
23
  dev_setup/verbose.py,sha256=N3U9JAYOvFwdd8DT6W7Pqq6RCIUfbcQnPsm0O1TnvQY,5003
23
24
  dev_setup/agent/__init__.py,sha256=znrgxUCr_y0Qp-f41S6EaTv-hoTYwoZ9mOMLVge-IJg,226
24
25
  dev_setup/agent/approval.py,sha256=DNPV5iM_UpCx39xFzCu8kyr03tjfyfD7iVcTfQMJRwY,3630
@@ -44,14 +45,15 @@ dev_setup/commands/delete_cmd.py,sha256=j_-fr2RMaeX3sMhH-7wJP5KC9Yvpgbb9KIeEEyG9
44
45
  dev_setup/commands/docs_cmd.py,sha256=JXhusKUl4dD-U5jG-PLTon_2NCpAWWnaBqsmlFk7vLY,971
45
46
  dev_setup/commands/doctor_cmd.py,sha256=sPhxLMVxy1JOxdFklRQHIwCoJeB-nmGWzVs5yeza9a8,3568
46
47
  dev_setup/commands/functions_cmd.py,sha256=4HvdLXle9JGk70A1EDVZrlgTo-N-FyAO7ApaL8mcJYI,3023
47
- dev_setup/commands/help_cmd.py,sha256=YksB8ddy_fR8ZXscs2QU6ODVl6R6V2eeJlpoBVNSH4Y,4352
48
+ dev_setup/commands/help_cmd.py,sha256=n9UmyVEqpG6LQLb_hOdmgHltFJdklTb_tN1aynVi4NQ,4460
48
49
  dev_setup/commands/install_cmd.py,sha256=0mUEdZQWPgXuK4_5aVhGZOadQYM1JhFZjl-biRHjSf4,4610
49
50
  dev_setup/commands/links_cmd.py,sha256=kvnoBXdM9QWRZRIwWgnmWqVkOYE7AZxywFTQD5_Uwv4,4924
50
51
  dev_setup/commands/list_cmd.py,sha256=Env6bwAmREDek4L-ZB2CIfvLT4PgaKcz5sQKJ1GhL8g,2913
52
+ dev_setup/commands/outdated_cmd.py,sha256=YljnMw-KZd1jcZO5FEce3H6nrX1MnWOt0fRBSAdlpQE,5070
51
53
  dev_setup/commands/remove_cmd.py,sha256=_KqCa2S9fQFngLUs_OpBzjkIkFKgDtKup4gQ5TqLrVI,1239
52
54
  dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
53
55
  dev_setup/commands/skills_cmd.py,sha256=j4rleYEW4lt-O2ssDwGyhwmk2Wiip64C4Z7iPT6c3y0,7482
54
- dev_setup/commands/update_cmd.py,sha256=9Bdgu9wMdliawonDOsfDsjP2am-okuONStICKn9pkkg,4831
56
+ dev_setup/commands/update_cmd.py,sha256=YdTuhl6z7zyQ54Hb7KUN6pUhdMGFDSPu4sBCZNvgw8Q,4005
55
57
  dev_setup/configure/__init__.py,sha256=PXOtKObPRXnBZlVNSaJIUNscuysaUy3cJppiCEhTRhE,3488
56
58
  dev_setup/configure/ansible/__init__.py,sha256=huQL_tfiU1l0WI6nzjTnGZlxCQX2aH7E9n9TrfwmIpU,407
57
59
  dev_setup/configure/ansible/detect.py,sha256=5LkdbJg5BU2lrIU4CZm_Lhr6Sm4TJMCh1sMrsRK6rgc,9531
@@ -98,7 +100,7 @@ dev_setup/configure/starship/model.py,sha256=ct1YrR3xLqcKMP20TvKZQ0Oc-OxHMrRjnei
98
100
  dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
99
101
  dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
100
102
  dev_setup/configure/starship/wizard.py,sha256=Q6aoKnz_n9WhFhTD4EygvaenZRsQTVwyZ1ga-cpUqBk,28620
101
- devstuff-2.10.0.dist-info/METADATA,sha256=mq5FgOs4AL55d3uf1EpTwazxTrBlPvUlYHUrdzDVfp8,77776
102
- devstuff-2.10.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
103
- devstuff-2.10.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
104
- devstuff-2.10.0.dist-info/RECORD,,
103
+ devstuff-2.11.0.dist-info/METADATA,sha256=e-fg6yzUlLcNHwEJieAFSZwcOAkaDAs1MhQD3Lg-pgY,81644
104
+ devstuff-2.11.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
105
+ devstuff-2.11.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
106
+ devstuff-2.11.0.dist-info/RECORD,,