devstuff 2.11.0__py3-none-any.whl → 2.12.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 +2 -0
- dev_setup/commands/help_cmd.py +1 -0
- dev_setup/commands/profile_cmd.py +199 -0
- dev_setup/generic.py +78 -6
- dev_setup/profile.py +353 -0
- dev_setup/snapshot.py +131 -0
- {devstuff-2.11.0.dist-info → devstuff-2.12.0.dist-info}/METADATA +105 -1
- {devstuff-2.11.0.dist-info → devstuff-2.12.0.dist-info}/RECORD +10 -7
- {devstuff-2.11.0.dist-info → devstuff-2.12.0.dist-info}/WHEEL +0 -0
- {devstuff-2.11.0.dist-info → devstuff-2.12.0.dist-info}/entry_points.txt +0 -0
dev_setup/cli.py
CHANGED
|
@@ -34,6 +34,7 @@ def _register_commands() -> None:
|
|
|
34
34
|
from dev_setup.commands.links_cmd import links_cmd
|
|
35
35
|
from dev_setup.commands.list_cmd import list_cmd
|
|
36
36
|
from dev_setup.commands.outdated_cmd import outdated_cmd
|
|
37
|
+
from dev_setup.commands.profile_cmd import profile_cmd
|
|
37
38
|
from dev_setup.commands.remove_cmd import remove_cmd
|
|
38
39
|
from dev_setup.commands.run_cmd import run_cmd
|
|
39
40
|
from dev_setup.commands.skills_cmd import skills_cmd
|
|
@@ -46,6 +47,7 @@ def _register_commands() -> None:
|
|
|
46
47
|
cli.add_command(doctor_cmd, "doctor")
|
|
47
48
|
cli.add_command(update_cmd, "update")
|
|
48
49
|
cli.add_command(outdated_cmd, "outdated")
|
|
50
|
+
cli.add_command(profile_cmd, "profile")
|
|
49
51
|
cli.add_command(configure_cmd, "configure")
|
|
50
52
|
cli.add_command(configure_cmd, "config")
|
|
51
53
|
cli.add_command(add_cmd, "add")
|
dev_setup/commands/help_cmd.py
CHANGED
|
@@ -26,6 +26,7 @@ def print_help() -> None:
|
|
|
26
26
|
("remove", "<package ...>", "Uninstall installed packages"),
|
|
27
27
|
("update", "[package ...] [--version]", "Update packages (interactive if no args)"),
|
|
28
28
|
("outdated", "[package ...] [--json]", "Show which installed packages have updates"),
|
|
29
|
+
("profile", "<snapshot|diff> [...]", "Save this machine's tools, or compare to a file"),
|
|
29
30
|
("configure", "[tool] [--list] [--path]", "Set up a tool with a guided wizard"),
|
|
30
31
|
("add", "", "Add a custom package (guided wizard)"),
|
|
31
32
|
("delete", "<key>", "Remove a custom package from the registry"),
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
from contextlib import nullcontext
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
import click
|
|
9
|
+
from rich.markup import escape
|
|
10
|
+
|
|
11
|
+
from dev_setup import profile, snapshot, ui, verbose
|
|
12
|
+
from dev_setup.profile import DiffRow, DiffState
|
|
13
|
+
|
|
14
|
+
_CUSTOM_NAMES_SHOWN = 6
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _warn(message: str) -> None:
|
|
18
|
+
# stderr only: with no -o, stdout is the profile itself and must parse (spec FR-14, NFR-1).
|
|
19
|
+
click.echo(message, err=True)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@click.group("profile")
|
|
23
|
+
def profile_cmd() -> None:
|
|
24
|
+
"""Describe a machine's tools as a portable file, and compare a machine against one.
|
|
25
|
+
|
|
26
|
+
A profile is a small YAML file naming catalog tools (and, optionally, versions). It holds
|
|
27
|
+
keys only — never install scripts — so a profile from elsewhere cannot run anything the
|
|
28
|
+
catalog doesn't already define.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@profile_cmd.command("snapshot")
|
|
33
|
+
@click.option(
|
|
34
|
+
"-o", "--output", "output", type=click.Path(path_type=Path), default=None,
|
|
35
|
+
help="Write to this file instead of stdout.",
|
|
36
|
+
)
|
|
37
|
+
@click.option(
|
|
38
|
+
"--versions", is_flag=True,
|
|
39
|
+
help="Also record each tool's installed version, for the types that can be pinned "
|
|
40
|
+
"(npm, pip/uvx, single-package apt). Off by default: a pinned profile goes stale "
|
|
41
|
+
"the day a tool updates.",
|
|
42
|
+
)
|
|
43
|
+
@click.option("--force", is_flag=True, help="Overwrite the -o file if it already exists.")
|
|
44
|
+
def snapshot_cmd(output: Path | None, versions: bool, force: bool) -> None:
|
|
45
|
+
"""Write a profile of the tools installed on this machine.
|
|
46
|
+
|
|
47
|
+
Read-only, and local: it asks the machine, never the network, so it works offline. The
|
|
48
|
+
output is deterministic (sorted, no timestamp, no hostname), so a profile kept in git shows
|
|
49
|
+
only real changes.
|
|
50
|
+
|
|
51
|
+
With no -o, stdout is exactly the YAML — notes and warnings go to stderr.
|
|
52
|
+
"""
|
|
53
|
+
if output is not None and output.exists() and not force:
|
|
54
|
+
_warn(f"error: {output} already exists; use --force to overwrite it")
|
|
55
|
+
sys.exit(2)
|
|
56
|
+
|
|
57
|
+
snap = snapshot.take(versions=versions)
|
|
58
|
+
|
|
59
|
+
for key in snap.unreadable:
|
|
60
|
+
_warn(
|
|
61
|
+
f"warning: {key}: couldn't read its installed version, so it is written without "
|
|
62
|
+
f"one — {snap.why[key]}"
|
|
63
|
+
)
|
|
64
|
+
if snap.custom:
|
|
65
|
+
shown = ", ".join(snap.custom[:_CUSTOM_NAMES_SHOWN])
|
|
66
|
+
if len(snap.custom) > _CUSTOM_NAMES_SHOWN:
|
|
67
|
+
shown += f", +{len(snap.custom) - _CUSTOM_NAMES_SHOWN} more"
|
|
68
|
+
_warn(
|
|
69
|
+
f"note: {len(snap.custom)} of these tools are defined or overridden in your user "
|
|
70
|
+
f"catalog ({shown}); a machine without them won't know these keys — move them with "
|
|
71
|
+
"`devstuff catalog export` / `devstuff catalog import`"
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
text = profile.dumps(snap.profile)
|
|
75
|
+
if output is None:
|
|
76
|
+
click.echo(text, nl=False)
|
|
77
|
+
return
|
|
78
|
+
|
|
79
|
+
try:
|
|
80
|
+
output.write_text(text, encoding="utf-8")
|
|
81
|
+
except OSError as exc:
|
|
82
|
+
_warn(f"error: cannot write {output}: {exc.strerror or exc}")
|
|
83
|
+
sys.exit(2)
|
|
84
|
+
n = len(snap.profile.tools)
|
|
85
|
+
_warn(f"Wrote {n} tool{'' if n == 1 else 's'} to {output}")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
# -- diff ---------------------------------------------------------------------------------------
|
|
89
|
+
|
|
90
|
+
# One glyph + wording per state. The three "could not compare" states share nothing with `ok`:
|
|
91
|
+
# they must never read as a match (spec FR-17).
|
|
92
|
+
_LABEL: dict[DiffState, tuple[str, str]] = {
|
|
93
|
+
DiffState.OK: (ui.GREEN, "✔ ok"),
|
|
94
|
+
DiffState.MISSING: (ui.RED, "✘ missing"),
|
|
95
|
+
DiffState.DRIFT: (ui.AMBER, "≠ drift"),
|
|
96
|
+
DiffState.UNVERIFIABLE: (ui.GRAY, "? unverifiable"),
|
|
97
|
+
DiffState.UNPINNABLE: (ui.GRAY, "– unpinnable"),
|
|
98
|
+
DiffState.UNKNOWN_KEY: (ui.GRAY, "? unknown-key"),
|
|
99
|
+
DiffState.EXTRA: (ui.CYAN, "+ extra"),
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
_EXTRA_NAMES_SHOWN = 12
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
@profile_cmd.command("diff")
|
|
106
|
+
@click.argument("profile_file", metavar="PROFILE", type=click.Path(path_type=Path))
|
|
107
|
+
@click.option(
|
|
108
|
+
"--all", "show_all", is_flag=True,
|
|
109
|
+
help="Also list the tools that match, and the tools not in the profile, as rows.",
|
|
110
|
+
)
|
|
111
|
+
@click.option(
|
|
112
|
+
"--json", "as_json", is_flag=True,
|
|
113
|
+
help="Write a JSON array to stdout and nothing else. Always includes every state.",
|
|
114
|
+
)
|
|
115
|
+
@click.option(
|
|
116
|
+
"--exit-code", "exit_code", is_flag=True,
|
|
117
|
+
help="Exit 1 if the machine differs from the profile (default: 0 whenever the comparison ran).",
|
|
118
|
+
)
|
|
119
|
+
@click.option(
|
|
120
|
+
"--ignore-extras", is_flag=True,
|
|
121
|
+
help="For --exit-code: don't count installed tools that aren't in the profile as a difference.",
|
|
122
|
+
)
|
|
123
|
+
def diff_cmd(
|
|
124
|
+
profile_file: Path, show_all: bool, as_json: bool, exit_code: bool, ignore_extras: bool
|
|
125
|
+
) -> None:
|
|
126
|
+
"""Compare this machine to a profile.
|
|
127
|
+
|
|
128
|
+
Read-only. Each key is reported as ok, missing, drift (installed at a different version
|
|
129
|
+
than the profile pins), unverifiable (pinned, but the installed version can't be read),
|
|
130
|
+
unpinnable (pinned, but that install type can't honour a pin), unknown-key (not in this
|
|
131
|
+
machine's catalog) or extra (installed but not in the profile). The last three that mean
|
|
132
|
+
"couldn't compare" are never reported as ok.
|
|
133
|
+
|
|
134
|
+
Exit status: 0 whenever the comparison ran. With --exit-code, 1 if the machine differs. A
|
|
135
|
+
profile that can't be read or isn't valid is always 2, so 1 only ever means "differs".
|
|
136
|
+
"""
|
|
137
|
+
try:
|
|
138
|
+
wanted = profile.load(profile_file)
|
|
139
|
+
except profile.ProfileError as exc:
|
|
140
|
+
click.echo(f"error: {exc}", err=True)
|
|
141
|
+
sys.exit(2)
|
|
142
|
+
|
|
143
|
+
interactive = sys.stdout.isatty() and not as_json
|
|
144
|
+
if interactive:
|
|
145
|
+
ui.print_banner()
|
|
146
|
+
progress = (
|
|
147
|
+
verbose.step(f"Comparing this machine to {profile_file.name}...")
|
|
148
|
+
if interactive else nullcontext()
|
|
149
|
+
)
|
|
150
|
+
with progress:
|
|
151
|
+
rows = profile.sort_diff_rows(profile.compare(wanted, snapshot.machine_facts(wanted)))
|
|
152
|
+
|
|
153
|
+
if as_json:
|
|
154
|
+
click.echo(json.dumps([r.to_json() for r in rows], indent=2))
|
|
155
|
+
else:
|
|
156
|
+
_render(rows, show_all=show_all)
|
|
157
|
+
|
|
158
|
+
if exit_code and profile.differs(rows, ignore_extras=ignore_extras):
|
|
159
|
+
sys.exit(1)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _status_cell(row: DiffRow) -> str:
|
|
163
|
+
color, label = _LABEL[row.state]
|
|
164
|
+
cell = f"[{color}]{label}[/]"
|
|
165
|
+
if row.note:
|
|
166
|
+
# Escaped: a note is free text, and Rich would read "[docs]" as markup.
|
|
167
|
+
cell += f"\n[{ui.GRAY}]{escape(row.note)}[/]"
|
|
168
|
+
return cell
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _render(rows: list[DiffRow], *, show_all: bool) -> None:
|
|
172
|
+
extras = [r for r in rows if r.state is DiffState.EXTRA]
|
|
173
|
+
shown = rows if show_all else [r for r in rows if r.state not in (DiffState.OK, DiffState.EXTRA)]
|
|
174
|
+
|
|
175
|
+
if shown:
|
|
176
|
+
tbl = ui.table()
|
|
177
|
+
tbl.add_column("Package", style="bold", no_wrap=True)
|
|
178
|
+
tbl.add_column("Type", style=ui.CYAN, no_wrap=True)
|
|
179
|
+
tbl.add_column("Profile", style=ui.GRAY, no_wrap=True)
|
|
180
|
+
tbl.add_column("Installed", style=ui.GRAY, no_wrap=True)
|
|
181
|
+
tbl.add_column("Status")
|
|
182
|
+
for r in shown:
|
|
183
|
+
tbl.add_row(r.key, r.type or "", r.pinned or "", r.installed or "", _status_cell(r))
|
|
184
|
+
ui.console.print(tbl)
|
|
185
|
+
elif not extras:
|
|
186
|
+
ui.info("This machine matches the profile.")
|
|
187
|
+
else:
|
|
188
|
+
ui.info("Everything the profile asks for is here.")
|
|
189
|
+
|
|
190
|
+
if extras and not show_all:
|
|
191
|
+
names = [r.key for r in extras]
|
|
192
|
+
listed = ", ".join(names[:_EXTRA_NAMES_SHOWN])
|
|
193
|
+
if len(names) > _EXTRA_NAMES_SHOWN:
|
|
194
|
+
listed += f", +{len(names) - _EXTRA_NAMES_SHOWN} more"
|
|
195
|
+
noun = "tool isn't" if len(names) == 1 else "tools aren't"
|
|
196
|
+
ui.dim(f"{len(names)} installed {noun} in the profile: {listed} (--all lists them)")
|
|
197
|
+
|
|
198
|
+
counts = profile.summarize_diff(rows)
|
|
199
|
+
ui.dim(" · ".join(f"{counts[s]} {s.value}" for s in profile.DIFF_ORDER if counts[s]))
|
dev_setup/generic.py
CHANGED
|
@@ -222,6 +222,20 @@ class GenericTool(Tool):
|
|
|
222
222
|
|
|
223
223
|
return ""
|
|
224
224
|
|
|
225
|
+
def installed_version(self) -> str:
|
|
226
|
+
"""The installed version as a clean string, read locally; "" if it cannot be had.
|
|
227
|
+
|
|
228
|
+
Unlike `get_version()` this is meant for machine use: no free text, no network, never
|
|
229
|
+
raises. Types with no reader (git, script, bash) return "" without running anything.
|
|
230
|
+
"""
|
|
231
|
+
reader = _VERSION_READERS.get(self.install_type)
|
|
232
|
+
if reader is None:
|
|
233
|
+
return ""
|
|
234
|
+
try:
|
|
235
|
+
return reader(self)
|
|
236
|
+
except Exception:
|
|
237
|
+
return ""
|
|
238
|
+
|
|
225
239
|
|
|
226
240
|
# -- Install strategies --------------------------------------------------------
|
|
227
241
|
|
|
@@ -553,17 +567,22 @@ def _check_update_uvx(tool: GenericTool) -> UpdateStatus:
|
|
|
553
567
|
return UpdateStatus(current=current, latest=latest, available=True)
|
|
554
568
|
|
|
555
569
|
|
|
556
|
-
def
|
|
557
|
-
|
|
558
|
-
return UpdateStatus()
|
|
559
|
-
pkg = tool.apt_packages.split()[0]
|
|
570
|
+
def _apt_installed_version(pkg: str) -> str:
|
|
571
|
+
"""The installed version of an apt package, or "" — a local dpkg read, no network."""
|
|
560
572
|
try:
|
|
561
573
|
r = _probe(
|
|
562
574
|
["dpkg-query", "-W", "-f=${Version}", pkg], capture_output=True, text=True, timeout=10,
|
|
563
575
|
)
|
|
564
|
-
|
|
576
|
+
return r.stdout.strip() if r.returncode == 0 else ""
|
|
565
577
|
except Exception:
|
|
566
|
-
|
|
578
|
+
return ""
|
|
579
|
+
|
|
580
|
+
|
|
581
|
+
def _check_update_apt(tool: GenericTool) -> UpdateStatus:
|
|
582
|
+
if not tool.apt_packages:
|
|
583
|
+
return UpdateStatus()
|
|
584
|
+
pkg = tool.apt_packages.split()[0]
|
|
585
|
+
current = _apt_installed_version(pkg)
|
|
567
586
|
try:
|
|
568
587
|
r = _probe(["apt-cache", "policy", pkg], capture_output=True, text=True, timeout=10)
|
|
569
588
|
except Exception:
|
|
@@ -627,6 +646,59 @@ def supports_update_check(install_type: str) -> bool:
|
|
|
627
646
|
return install_type in _UPDATE_CHECKERS
|
|
628
647
|
|
|
629
648
|
|
|
649
|
+
# -- Local installed-version readers ---------------------------------------------------------
|
|
650
|
+
# `get_version()` is the first line of `--version` output — free text such as
|
|
651
|
+
# 'bat 0.26.1 (979ba22)' — and the update checkers return a clean version only alongside a
|
|
652
|
+
# network lookup. A profile needs a clean version without either (docs/specs/profile, F-1, F-3),
|
|
653
|
+
# so these read it locally, per type, and say "" when they cannot. A type that cannot be pinned
|
|
654
|
+
# (git, script, bash) has no reader on purpose: a version we could not act on is not recorded.
|
|
655
|
+
|
|
656
|
+
|
|
657
|
+
def _read_npm(tool: GenericTool) -> str:
|
|
658
|
+
return _npm_installed_version(tool.npm_name) if tool.npm_name else ""
|
|
659
|
+
|
|
660
|
+
|
|
661
|
+
def _read_uv(tool: GenericTool) -> str:
|
|
662
|
+
# Shares the once-per-run `uv tool list` parse with the update checker.
|
|
663
|
+
if not tool.pip_name:
|
|
664
|
+
return ""
|
|
665
|
+
return (_uv_tool_versions().data or {}).get(tool.pip_name, "")
|
|
666
|
+
|
|
667
|
+
|
|
668
|
+
def _read_apt(tool: GenericTool) -> str:
|
|
669
|
+
packages = (tool.apt_packages or "").split()
|
|
670
|
+
# With several packages there is no single "the version" (and such a tool cannot be pinned).
|
|
671
|
+
return _apt_installed_version(packages[0]) if len(packages) == 1 else ""
|
|
672
|
+
|
|
673
|
+
|
|
674
|
+
_VERSION_READERS: dict[str, Callable[[GenericTool], str]] = {
|
|
675
|
+
"npm": _read_npm,
|
|
676
|
+
"pip": _read_uv,
|
|
677
|
+
"uvx": _read_uv,
|
|
678
|
+
"apt": _read_apt,
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
# Install types whose `update(version=...)` really installs that version. Explicit rather than
|
|
682
|
+
# discovered by calling `update` and catching the error — a read must not attempt a mutation to
|
|
683
|
+
# learn what it can do — and tied to the updaters by tests/test_pin_support.py, so it cannot
|
|
684
|
+
# quietly drift from them.
|
|
685
|
+
_PINNABLE_TYPES = frozenset({"npm", "pip", "uvx", "apt"})
|
|
686
|
+
|
|
687
|
+
|
|
688
|
+
def supports_pin(tool: GenericTool) -> bool:
|
|
689
|
+
"""Whether `update(version=...)` can install a specific version of this tool.
|
|
690
|
+
|
|
691
|
+
npm, pip/uvx and apt can; git (shallow clone), script and bash cannot. An apt tool pins
|
|
692
|
+
only when it names exactly one package — `update` refuses otherwise, and a profile entry
|
|
693
|
+
has a single version to apply.
|
|
694
|
+
"""
|
|
695
|
+
if tool.install_type not in _PINNABLE_TYPES:
|
|
696
|
+
return False
|
|
697
|
+
if tool.install_type == "apt":
|
|
698
|
+
return len((tool.apt_packages or "").split()) == 1
|
|
699
|
+
return True
|
|
700
|
+
|
|
701
|
+
|
|
630
702
|
# -- Remove strategies -----------------------------------------------------------
|
|
631
703
|
|
|
632
704
|
|
dev_setup/profile.py
ADDED
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
"""Profile files: which catalog tools a machine should have (docs/specs/profile).
|
|
2
|
+
|
|
3
|
+
A profile is a small YAML file shaped like the catalog (`version`, `tools`) but with a
|
|
4
|
+
different meaning: the catalog says what a tool *is*, a profile says what a *machine has*.
|
|
5
|
+
It names catalog keys and, optionally, a version — never a definition or a script, so a
|
|
6
|
+
profile from somewhere else cannot carry code past the catalog's validation (SD-2).
|
|
7
|
+
|
|
8
|
+
Everything here is pure: no UI, no registry lookup, no subprocess. Whether a key exists in
|
|
9
|
+
*this* machine's catalog is deliberately not checked at load time (FR-6) — a profile written
|
|
10
|
+
on a machine with custom tools has to load on one without them — so that is `diff`'s job.
|
|
11
|
+
|
|
12
|
+
Loading is strict because a profile says what should be installed, and a value YAML quietly
|
|
13
|
+
changed on the way in is worse than an error. `version: 1.10` reaches Python as the float
|
|
14
|
+
`1.1` — the trailing zero is gone from the data, not just from the printing — so there is
|
|
15
|
+
nothing to recover and the only safe move is to refuse (SD-6).
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from collections.abc import Iterable, Mapping
|
|
21
|
+
from dataclasses import dataclass, field
|
|
22
|
+
from enum import StrEnum
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from typing import Any
|
|
25
|
+
|
|
26
|
+
import yaml
|
|
27
|
+
|
|
28
|
+
VERSION = 1
|
|
29
|
+
|
|
30
|
+
_TOP_FIELDS = ("version", "tools")
|
|
31
|
+
_ENTRY_FIELDS = ("version",)
|
|
32
|
+
|
|
33
|
+
_HEADER = (
|
|
34
|
+
"# devstuff profile: the tools this machine should have.\n"
|
|
35
|
+
"# Compare a machine against this file with: devstuff profile diff <this file>\n"
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class ProfileError(RuntimeError):
|
|
40
|
+
pass
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def _check_version(value: Any, where: str) -> str:
|
|
44
|
+
"""Return `value` if it is a usable version string, else raise ProfileError.
|
|
45
|
+
|
|
46
|
+
One rule for both a file and a hand-built `Entry`, so a version `snapshot` constructs
|
|
47
|
+
can always be read back by `load`.
|
|
48
|
+
"""
|
|
49
|
+
if value is None:
|
|
50
|
+
raise ProfileError(
|
|
51
|
+
f"{where} has no value (a bare `version:` or `~` is null). "
|
|
52
|
+
"Remove the line, or write a quoted string, e.g. version: '1.2.3'"
|
|
53
|
+
)
|
|
54
|
+
if type(value) is not str:
|
|
55
|
+
raise ProfileError(
|
|
56
|
+
f"{where} was read by YAML as {type(value).__name__} ({value!r}), not as text. "
|
|
57
|
+
"A version has to be a quoted string, e.g. version: '1.10' — unquoted, YAML "
|
|
58
|
+
"turns 1.10 into 1.1, 0.40 into 0.4, and 2026-09-30 into a date"
|
|
59
|
+
)
|
|
60
|
+
if not value or value != value.strip():
|
|
61
|
+
raise ProfileError(f"{where} is blank or has leading/trailing whitespace: {value!r}")
|
|
62
|
+
return value
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class Entry:
|
|
67
|
+
"""What a profile says about one tool. `version` None means "present, any version"."""
|
|
68
|
+
|
|
69
|
+
version: str | None = None
|
|
70
|
+
|
|
71
|
+
def __post_init__(self) -> None:
|
|
72
|
+
if self.version is not None:
|
|
73
|
+
_check_version(self.version, "Entry version")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@dataclass(frozen=True)
|
|
77
|
+
class Profile:
|
|
78
|
+
tools: dict[str, Entry] = field(default_factory=dict)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
# -- Loading ------------------------------------------------------------------------------------
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class _DuplicateKey(yaml.YAMLError):
|
|
85
|
+
def __init__(self, key: object, line: int) -> None:
|
|
86
|
+
super().__init__(f"line {line}: duplicate key {key!r}")
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class _StrictLoader(yaml.SafeLoader):
|
|
90
|
+
"""SafeLoader that refuses a mapping key that appears twice.
|
|
91
|
+
|
|
92
|
+
PyYAML keeps the last one and drops the first without a word, which in a file that says
|
|
93
|
+
what should be installed is a quiet way to lose an entry (spec F-5).
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
def construct_mapping(self, node, deep=False):
|
|
97
|
+
if isinstance(node, yaml.MappingNode):
|
|
98
|
+
seen: set[Any] = set()
|
|
99
|
+
for key_node, _value_node in node.value:
|
|
100
|
+
if key_node.tag == "tag:yaml.org,2002:merge":
|
|
101
|
+
continue
|
|
102
|
+
try:
|
|
103
|
+
key = self.construct_object(key_node, deep=True)
|
|
104
|
+
if key in seen:
|
|
105
|
+
raise _DuplicateKey(key, key_node.start_mark.line + 1)
|
|
106
|
+
seen.add(key)
|
|
107
|
+
except TypeError:
|
|
108
|
+
continue # unhashable key: let the base class report it its own way
|
|
109
|
+
return super().construct_mapping(node, deep=deep)
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def loads(text: str, *, source: Path | str = "<profile>") -> Profile:
|
|
113
|
+
try:
|
|
114
|
+
raw = yaml.load(text, Loader=_StrictLoader) # a SafeLoader subclass
|
|
115
|
+
except _DuplicateKey as exc:
|
|
116
|
+
raise ProfileError(f"{source}: {exc}") from exc
|
|
117
|
+
except yaml.YAMLError as exc:
|
|
118
|
+
raise ProfileError(f"{source}: invalid YAML: {exc}") from exc
|
|
119
|
+
return _validate(raw, source)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def load(path: Path) -> Profile:
|
|
123
|
+
try:
|
|
124
|
+
text = path.read_text(encoding="utf-8")
|
|
125
|
+
except FileNotFoundError as exc:
|
|
126
|
+
raise ProfileError(f"{path}: no such file") from exc
|
|
127
|
+
except (OSError, UnicodeDecodeError) as exc:
|
|
128
|
+
raise ProfileError(f"{path}: cannot read as a text file: {exc}") from exc
|
|
129
|
+
return loads(text, source=path)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
def _validate(raw: Any, source: Path | str) -> Profile:
|
|
133
|
+
if raw is None:
|
|
134
|
+
raise ProfileError(f"{source}: profile is empty")
|
|
135
|
+
if not isinstance(raw, dict):
|
|
136
|
+
raise ProfileError(f"{source}: profile must be a mapping with `version` and `tools`")
|
|
137
|
+
|
|
138
|
+
unknown = [k for k in raw if k not in _TOP_FIELDS]
|
|
139
|
+
if unknown:
|
|
140
|
+
raise ProfileError(f"{source}: unknown field {unknown[0]!r} (expected: version, tools)")
|
|
141
|
+
|
|
142
|
+
# `type(...) is int`, not `== VERSION`: in Python `True == 1`, so `version: true` would pass.
|
|
143
|
+
if "version" not in raw:
|
|
144
|
+
raise ProfileError(f"{source}: missing required field `version` (must be {VERSION})")
|
|
145
|
+
if type(raw["version"]) is not int or raw["version"] != VERSION:
|
|
146
|
+
raise ProfileError(f"{source}: version must be {VERSION}, got {raw['version']!r}")
|
|
147
|
+
|
|
148
|
+
if "tools" not in raw:
|
|
149
|
+
raise ProfileError(f"{source}: missing required field `tools`")
|
|
150
|
+
tools = raw["tools"]
|
|
151
|
+
if not isinstance(tools, dict):
|
|
152
|
+
raise ProfileError(
|
|
153
|
+
f"{source}: tools must be a mapping of tool key to entry "
|
|
154
|
+
"(write `tools: {}` for an empty profile)"
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
return Profile({key: _entry(key, value, source) for key, value in tools.items()})
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def _entry(key: object, value: Any, source: Path | str) -> Entry:
|
|
161
|
+
if not isinstance(key, str):
|
|
162
|
+
raise ProfileError(
|
|
163
|
+
f"{source}: tools: key {key!r} was read by YAML as {type(key).__name__}, "
|
|
164
|
+
"not a string — quote it"
|
|
165
|
+
)
|
|
166
|
+
if value is None: # a bare `uv:`
|
|
167
|
+
return Entry()
|
|
168
|
+
if not isinstance(value, dict):
|
|
169
|
+
raise ProfileError(
|
|
170
|
+
f"{source}: tools.{key}: entry must be a mapping, got {type(value).__name__} "
|
|
171
|
+
f"(write `{key}: {{}}` for any version)"
|
|
172
|
+
)
|
|
173
|
+
for name in value:
|
|
174
|
+
if name not in _ENTRY_FIELDS:
|
|
175
|
+
raise ProfileError(
|
|
176
|
+
f"{source}: tools.{key}: unknown field {name!r} (only `version` is supported)"
|
|
177
|
+
)
|
|
178
|
+
if "version" not in value:
|
|
179
|
+
return Entry()
|
|
180
|
+
return Entry(_check_version(value["version"], f"{source}: tools.{key}.version"))
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
# -- Dumping ------------------------------------------------------------------------------------
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def dumps(profile: Profile) -> str:
|
|
187
|
+
"""Serialise deterministically: sorted by key, a fixed header, nothing machine-specific.
|
|
188
|
+
|
|
189
|
+
Two dumps of the same profile are byte-identical, so a profile kept in git shows only
|
|
190
|
+
real changes, and one handed to someone else leaks neither hostname nor time (SD-7).
|
|
191
|
+
`yaml.safe_dump` is what makes version-shaped strings safe on the way out: it quotes
|
|
192
|
+
`'1.10'` precisely because the bare form would reload as a number.
|
|
193
|
+
"""
|
|
194
|
+
tools = {
|
|
195
|
+
key: ({} if entry.version is None else {"version": entry.version})
|
|
196
|
+
for key, entry in sorted(profile.tools.items(), key=lambda kv: kv[0])
|
|
197
|
+
}
|
|
198
|
+
body = yaml.safe_dump(
|
|
199
|
+
{"version": VERSION, "tools": tools},
|
|
200
|
+
sort_keys=False,
|
|
201
|
+
default_flow_style=False,
|
|
202
|
+
allow_unicode=True,
|
|
203
|
+
)
|
|
204
|
+
return _HEADER + body
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
# -- Comparing a machine to a profile ---------------------------------------------------------------
|
|
208
|
+
# Pure, like the rest of this module: `compare` takes *facts* about the machine (`MachineTool`)
|
|
209
|
+
# rather than tool objects, so every rule below is testable without a registry or a subprocess.
|
|
210
|
+
# Gathering the facts is the caller's job.
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
class DiffState(StrEnum):
|
|
214
|
+
"""What can honestly be said about one key. Values are the `--json` spellings (FR-16)."""
|
|
215
|
+
|
|
216
|
+
OK = "ok"
|
|
217
|
+
MISSING = "missing"
|
|
218
|
+
DRIFT = "drift"
|
|
219
|
+
# The three ways the comparison could not be made. None of them is ever `ok` (FR-17), and
|
|
220
|
+
# each has a different remedy, which is why they are three states and not one "unknown".
|
|
221
|
+
UNVERIFIABLE = "unverifiable" # pinned and installed, but the version cannot be read
|
|
222
|
+
UNPINNABLE = "unpinnable" # pinned, but this install type cannot honour a pin
|
|
223
|
+
UNKNOWN_KEY = "unknown-key" # this machine's catalog has no such key
|
|
224
|
+
EXTRA = "extra"
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
@dataclass(frozen=True)
|
|
228
|
+
class MachineTool:
|
|
229
|
+
"""What this machine says about one catalog key. Present in the mapping = the catalog knows it."""
|
|
230
|
+
|
|
231
|
+
install_type: str
|
|
232
|
+
installed: bool
|
|
233
|
+
pinnable: bool
|
|
234
|
+
# The installed version, if it was read ("" otherwise). Only read for pinned, pinnable tools.
|
|
235
|
+
version: str = ""
|
|
236
|
+
# Why `version` is empty, when it is — shown on an `unverifiable` row.
|
|
237
|
+
why_unreadable: str = ""
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
@dataclass(frozen=True)
|
|
241
|
+
class DiffRow:
|
|
242
|
+
key: str
|
|
243
|
+
state: DiffState
|
|
244
|
+
type: str | None # None for `unknown-key`: the catalog doesn't say
|
|
245
|
+
pinned: str | None # what the profile asked for
|
|
246
|
+
installed: str | None # the installed version, where it was read
|
|
247
|
+
note: str = ""
|
|
248
|
+
|
|
249
|
+
def to_json(self) -> dict[str, str | None]:
|
|
250
|
+
return {
|
|
251
|
+
"key": self.key,
|
|
252
|
+
"state": self.state.value,
|
|
253
|
+
"type": self.type,
|
|
254
|
+
"pinned": self.pinned,
|
|
255
|
+
"installed": self.installed,
|
|
256
|
+
"note": self.note,
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def _row(
|
|
261
|
+
key: str, state: DiffState, tool: MachineTool | None, entry: Entry | None, note: str = ""
|
|
262
|
+
) -> DiffRow:
|
|
263
|
+
return DiffRow(
|
|
264
|
+
key,
|
|
265
|
+
state,
|
|
266
|
+
tool.install_type if tool else None,
|
|
267
|
+
entry.version if entry else None,
|
|
268
|
+
(tool.version or None) if tool else None,
|
|
269
|
+
note,
|
|
270
|
+
)
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def _compare_one(key: str, entry: Entry, tool: MachineTool | None) -> DiffRow:
|
|
274
|
+
if tool is None:
|
|
275
|
+
return _row(
|
|
276
|
+
key, DiffState.UNKNOWN_KEY, None, entry,
|
|
277
|
+
"not in this machine's catalog — if it is a custom tool, bring its definition over "
|
|
278
|
+
"with `devstuff catalog import`",
|
|
279
|
+
)
|
|
280
|
+
if not tool.installed:
|
|
281
|
+
# Dominates a pin that couldn't be honoured: there is nothing to compare yet.
|
|
282
|
+
return _row(key, DiffState.MISSING, tool, entry)
|
|
283
|
+
if entry.version is None:
|
|
284
|
+
return _row(key, DiffState.OK, tool, entry)
|
|
285
|
+
if not tool.pinnable:
|
|
286
|
+
# Decided before the version is looked at: a tool that cannot be pinned must not read
|
|
287
|
+
# as `ok` just because some version text happens to equal the pin.
|
|
288
|
+
return _row(
|
|
289
|
+
key, DiffState.UNPINNABLE, tool, entry,
|
|
290
|
+
f"a {tool.install_type} install can't be pinned, so the pin is ignored",
|
|
291
|
+
)
|
|
292
|
+
if not tool.version:
|
|
293
|
+
return _row(
|
|
294
|
+
key, DiffState.UNVERIFIABLE, tool, entry,
|
|
295
|
+
tool.why_unreadable or "couldn't read the installed version",
|
|
296
|
+
)
|
|
297
|
+
# String equality, no ordering and no normalisation (FR-18): `0.45` is not `0.45.0`.
|
|
298
|
+
state = DiffState.OK if tool.version == entry.version else DiffState.DRIFT
|
|
299
|
+
return _row(key, state, tool, entry)
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def compare(profile: Profile, machine: Mapping[str, MachineTool]) -> list[DiffRow]:
|
|
303
|
+
"""One row per profile key, plus one per installed catalog tool the profile doesn't name.
|
|
304
|
+
|
|
305
|
+
`machine` holds the keys this machine's catalog knows; a profile key absent from it is
|
|
306
|
+
`unknown-key`. A tool that is neither in the profile nor installed is not a row at all.
|
|
307
|
+
"""
|
|
308
|
+
rows = [_compare_one(key, entry, machine.get(key)) for key, entry in profile.tools.items()]
|
|
309
|
+
rows += [
|
|
310
|
+
_row(key, DiffState.EXTRA, tool, None)
|
|
311
|
+
for key, tool in machine.items()
|
|
312
|
+
if key not in profile.tools and tool.installed
|
|
313
|
+
]
|
|
314
|
+
return rows
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
# Display order (FR-19): what needs attention first, `ok` last. Public so the summary line
|
|
318
|
+
# the command prints uses the same order as the rows, not a second copy of it.
|
|
319
|
+
DIFF_ORDER: tuple[DiffState, ...] = (
|
|
320
|
+
DiffState.MISSING,
|
|
321
|
+
DiffState.DRIFT,
|
|
322
|
+
DiffState.UNVERIFIABLE,
|
|
323
|
+
DiffState.UNPINNABLE,
|
|
324
|
+
DiffState.UNKNOWN_KEY,
|
|
325
|
+
DiffState.EXTRA,
|
|
326
|
+
DiffState.OK,
|
|
327
|
+
)
|
|
328
|
+
_DIFF_RANK = {state: i for i, state in enumerate(DIFF_ORDER)}
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
def sort_diff_rows(rows: Iterable[DiffRow]) -> list[DiffRow]:
|
|
332
|
+
return sorted(rows, key=lambda r: (_DIFF_RANK[r.state], r.key))
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def summarize_diff(rows: Iterable[DiffRow]) -> dict[DiffState, int]:
|
|
336
|
+
"""Count per state. Every state is present, so the counts always sum to the rows (FR-17)."""
|
|
337
|
+
counts = dict.fromkeys(DiffState, 0)
|
|
338
|
+
for r in rows:
|
|
339
|
+
counts[r.state] += 1
|
|
340
|
+
return counts
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
def differs(rows: Iterable[DiffRow], *, ignore_extras: bool) -> bool:
|
|
344
|
+
"""Whether `--exit-code` should report a difference (FR-22, OQ-2).
|
|
345
|
+
|
|
346
|
+
Anything other than `ok` is one. `extra` counts too unless the caller opted out — "is this
|
|
347
|
+
machine exactly what the profile says" is what a gate asks — but opting out of extras never
|
|
348
|
+
hides a real difference.
|
|
349
|
+
"""
|
|
350
|
+
return any(
|
|
351
|
+
r.state is not DiffState.OK and not (ignore_extras and r.state is DiffState.EXTRA)
|
|
352
|
+
for r in rows
|
|
353
|
+
)
|
dev_setup/snapshot.py
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
"""Gathering a profile from the machine (docs/specs/profile, FR-7, FR-10–13).
|
|
2
|
+
|
|
3
|
+
`profile.py` is the file format and stays pure; this is the part that asks the machine. It
|
|
4
|
+
makes no network call: `is_installed()` and `installed_version()` are local reads (spec NFR-2),
|
|
5
|
+
and it never goes through `get_version()`'s free text.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from collections.abc import Sequence
|
|
11
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
|
|
14
|
+
from dev_setup import registry
|
|
15
|
+
from dev_setup.base import Tool
|
|
16
|
+
from dev_setup.generic import supports_pin
|
|
17
|
+
from dev_setup.profile import Entry, MachineTool, Profile, ProfileError
|
|
18
|
+
|
|
19
|
+
_MAX_WORKERS = 8
|
|
20
|
+
|
|
21
|
+
# Why a pinnable tool's version couldn't be read, by install type — so a warning or a diff note
|
|
22
|
+
# says what to look at instead of "version unreadable".
|
|
23
|
+
_WHY_UNREADABLE = {
|
|
24
|
+
"npm": "npm doesn't list it as a global package",
|
|
25
|
+
"pip": "uv doesn't list it as a tool (is it installed another way?)",
|
|
26
|
+
"uvx": "uv doesn't list it as a tool (is it installed another way?)",
|
|
27
|
+
"apt": "dpkg doesn't report a version for it",
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def why_unreadable(install_type: str) -> str:
|
|
32
|
+
return _WHY_UNREADABLE.get(install_type, "no reader for this type")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class Snapshot:
|
|
37
|
+
profile: Profile
|
|
38
|
+
# Pinnable tools whose version could not be read, when versions were asked for. They are in
|
|
39
|
+
# `profile` without a version; naming them is what keeps that from looking deliberate.
|
|
40
|
+
unreadable: tuple[str, ...] = ()
|
|
41
|
+
# Installed tools defined or overridden in the user's own catalog. Another machine's
|
|
42
|
+
# catalog won't know these keys.
|
|
43
|
+
custom: tuple[str, ...] = ()
|
|
44
|
+
# key -> reason, for each entry in `unreadable`.
|
|
45
|
+
why: dict[str, str] = field(default_factory=dict)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _probe_one(tool: Tool, versions: bool) -> tuple[Tool, bool, str | None]:
|
|
49
|
+
"""`(tool, installed, version)`; `version` is None unless asked for and pinnable. Never raises."""
|
|
50
|
+
try:
|
|
51
|
+
if not tool.is_installed():
|
|
52
|
+
return tool, False, None
|
|
53
|
+
except Exception:
|
|
54
|
+
# Cannot claim it is installed, so it is left out rather than listed (as `outdated` does).
|
|
55
|
+
return tool, False, None
|
|
56
|
+
if not versions or not supports_pin(tool): # type: ignore[arg-type]
|
|
57
|
+
return tool, True, None
|
|
58
|
+
reader = getattr(tool, "installed_version", None)
|
|
59
|
+
try:
|
|
60
|
+
return tool, True, (reader() if reader else "")
|
|
61
|
+
except Exception:
|
|
62
|
+
return tool, True, ""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def take(tools: Sequence[Tool] | None = None, *, versions: bool = False) -> Snapshot:
|
|
66
|
+
"""Snapshot the installed tools. `versions=True` also records readable, pinnable versions."""
|
|
67
|
+
if tools is None:
|
|
68
|
+
tools = registry.all_tools()
|
|
69
|
+
with ThreadPoolExecutor(max_workers=_MAX_WORKERS) as pool:
|
|
70
|
+
probed = list(pool.map(lambda t: _probe_one(t, versions), tools))
|
|
71
|
+
|
|
72
|
+
entries: dict[str, Entry] = {}
|
|
73
|
+
unreadable: list[str] = []
|
|
74
|
+
why: dict[str, str] = {}
|
|
75
|
+
custom: list[str] = []
|
|
76
|
+
for tool, installed, version in probed:
|
|
77
|
+
if not installed:
|
|
78
|
+
continue
|
|
79
|
+
entry = Entry()
|
|
80
|
+
if version is not None:
|
|
81
|
+
try:
|
|
82
|
+
entry = Entry(version or None)
|
|
83
|
+
except ProfileError:
|
|
84
|
+
version = "" # a value the profile format would refuse: treat as unreadable
|
|
85
|
+
if not version:
|
|
86
|
+
unreadable.append(tool.key)
|
|
87
|
+
why[tool.key] = why_unreadable(tool.install_type)
|
|
88
|
+
entries[tool.key] = entry
|
|
89
|
+
if not getattr(tool, "builtin", True):
|
|
90
|
+
custom.append(tool.key)
|
|
91
|
+
|
|
92
|
+
return Snapshot(
|
|
93
|
+
profile=Profile(entries),
|
|
94
|
+
unreadable=tuple(sorted(unreadable)),
|
|
95
|
+
custom=tuple(sorted(custom)),
|
|
96
|
+
why=why,
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _facts_one(tool: Tool, entry: Entry | None) -> MachineTool:
|
|
101
|
+
"""Facts about one catalog tool for `profile.compare`. Never raises."""
|
|
102
|
+
try:
|
|
103
|
+
installed = bool(tool.is_installed())
|
|
104
|
+
except Exception:
|
|
105
|
+
installed = False # cannot claim it is installed (as `snapshot` and `outdated` do)
|
|
106
|
+
pinnable = supports_pin(tool) # type: ignore[arg-type]
|
|
107
|
+
version = why = ""
|
|
108
|
+
# A version is only worth a subprocess when the profile pins this tool, the tool is there
|
|
109
|
+
# to be read, and a pin could be honoured at all. Everything else is decided without one.
|
|
110
|
+
if installed and pinnable and entry is not None and entry.version is not None:
|
|
111
|
+
reader = getattr(tool, "installed_version", None)
|
|
112
|
+
try:
|
|
113
|
+
version = (reader() if reader else "") or ""
|
|
114
|
+
except Exception:
|
|
115
|
+
version = ""
|
|
116
|
+
if not version:
|
|
117
|
+
why = why_unreadable(tool.install_type)
|
|
118
|
+
return MachineTool(tool.install_type, installed, pinnable, version, why)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def machine_facts(profile: Profile, tools: Sequence[Tool] | None = None) -> dict[str, MachineTool]:
|
|
122
|
+
"""Facts about every catalog tool, keyed for `profile.compare`.
|
|
123
|
+
|
|
124
|
+
Local reads only, on a worker pool; a key absent from the result is a key this machine's
|
|
125
|
+
catalog does not have.
|
|
126
|
+
"""
|
|
127
|
+
if tools is None:
|
|
128
|
+
tools = registry.all_tools()
|
|
129
|
+
with ThreadPoolExecutor(max_workers=_MAX_WORKERS) as pool:
|
|
130
|
+
facts = list(pool.map(lambda t: _facts_one(t, profile.tools.get(t.key)), tools))
|
|
131
|
+
return {tool.key: fact for tool, fact in zip(tools, facts, strict=True)}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: devstuff
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.12.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>
|
|
@@ -372,6 +372,110 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
|
|
|
372
372
|
|
|
373
373
|
---
|
|
374
374
|
|
|
375
|
+
### `profile`
|
|
376
|
+
|
|
377
|
+
Describe which tools a machine should have as a small file, and compare a machine against one.
|
|
378
|
+
Both subcommands are **read-only** and **local** — they ask the machine, never the network — so
|
|
379
|
+
they work offline.
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
devstuff profile snapshot > work.yaml # the tools installed here, as a file
|
|
383
|
+
devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
|
|
384
|
+
devstuff profile diff work.yaml # how this machine differs from the file
|
|
385
|
+
devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
> **The file format is provisional until `profile apply` exists.** It is `version: 1`, and a later
|
|
389
|
+
> breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
|
|
390
|
+
|
|
391
|
+
A profile names catalog **keys**, and optionally a version. It never contains an install script or
|
|
392
|
+
a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
|
|
393
|
+
already define.
|
|
394
|
+
|
|
395
|
+
```yaml
|
|
396
|
+
version: 1
|
|
397
|
+
tools:
|
|
398
|
+
uv: {} # present, any version
|
|
399
|
+
ipython:
|
|
400
|
+
version: 9.17.1 # present, at exactly this version
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
**Quote any version that looks like a number.** YAML reads `version: 1.10` as the number 1.1 and
|
|
404
|
+
`0.40` as 0.4, and the original text can't be recovered — so devstuff refuses it and says to quote
|
|
405
|
+
it (`version: '1.10'`). It also refuses a duplicate key, which YAML would otherwise resolve by
|
|
406
|
+
silently dropping the first, an unknown field, and a tool key that YAML reads as something other
|
|
407
|
+
than text (`on`, `yes`, `123`). `snapshot` always writes versions correctly quoted.
|
|
408
|
+
|
|
409
|
+
#### `snapshot`
|
|
410
|
+
|
|
411
|
+
Writes a profile of every installed tool, to stdout or to `-o FILE`. By default it records **keys
|
|
412
|
+
only**: a profile that pins versions goes stale the day a tool updates, and then reports drift
|
|
413
|
+
nobody intended. `--versions` adds the installed version for the tools that can be pinned — `npm`,
|
|
414
|
+
`pip`/`uvx`, and single-package `apt`; `git`, `script` and `bash` tools can't be installed at a
|
|
415
|
+
chosen version, so a version recorded for them could never be acted on and is left out.
|
|
416
|
+
|
|
417
|
+
- If a pinnable tool's version can't be read (say it is on your `PATH` but isn't a `uv tool`), it is
|
|
418
|
+
written without one and a warning on stderr names it and says why — it is never dropped silently.
|
|
419
|
+
- Tools defined in your own catalog are included, with one stderr note that another machine won't
|
|
420
|
+
know them: move their definitions with `devstuff catalog export` / `import`.
|
|
421
|
+
- Output is **deterministic** — sorted, with a fixed header and no timestamp, hostname or path — so
|
|
422
|
+
a profile kept in git shows only real changes.
|
|
423
|
+
- `-o` refuses to overwrite an existing file (exit 2) unless you pass `--force`.
|
|
424
|
+
- With no `-o`, stdout is exactly the YAML; warnings and notes go to stderr.
|
|
425
|
+
|
|
426
|
+
#### `diff`
|
|
427
|
+
|
|
428
|
+
```
|
|
429
|
+
╭──────────────────────────────────────────────────────────────────────────────╮
|
|
430
|
+
│ Package Type Profile Installed Status │
|
|
431
|
+
├──────────────────────────────────────────────────────────────────────────────┤
|
|
432
|
+
│ reptyr apt ✘ missing │
|
|
433
|
+
│ ipython uvx 9.0.0 9.17.1 ≠ drift │
|
|
434
|
+
│ commitizen uvx 4.16.4 ? unverifiable │
|
|
435
|
+
│ uv doesn't list it as a tool │
|
|
436
|
+
│ (is it installed another │
|
|
437
|
+
│ way?) │
|
|
438
|
+
│ starship bash 1.0.0 – unpinnable │
|
|
439
|
+
│ a bash install can't be │
|
|
440
|
+
│ pinned, so the pin is ignored │
|
|
441
|
+
│ not-a-real-tool ? unknown-key │
|
|
442
|
+
│ not in this machine's catalog │
|
|
443
|
+
│ — if it is a custom tool, │
|
|
444
|
+
│ bring its definition over │
|
|
445
|
+
│ with `devstuff catalog │
|
|
446
|
+
│ import` │
|
|
447
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
448
|
+
1 installed tool isn't in the profile: gh (--all lists them)
|
|
449
|
+
1 missing · 1 drift · 1 unverifiable · 1 unpinnable · 1 unknown-key · 1 extra · 9 ok
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
| State | Meaning |
|
|
453
|
+
|-------|---------|
|
|
454
|
+
| `ok` | In the profile and installed; and, if pinned, at the pinned version. |
|
|
455
|
+
| `missing` | In the profile and the catalog, but not installed. |
|
|
456
|
+
| `drift` | Pinned and installed, but at a different version. |
|
|
457
|
+
| `unverifiable` | Pinned and installed, but the installed version can't be read. |
|
|
458
|
+
| `unpinnable` | Pinned, but this tool's install type can't honour a pin — the pin is ignored. |
|
|
459
|
+
| `unknown-key` | In the profile but not in this machine's catalog. |
|
|
460
|
+
| `extra` | Installed, but not in the profile. |
|
|
461
|
+
|
|
462
|
+
`unverifiable`, `unpinnable` and `unknown-key` are three different reasons the comparison couldn't
|
|
463
|
+
be made, each with a different remedy, and **none of them is ever reported as `ok`**. Versions are
|
|
464
|
+
compared as text: `0.45` is not `0.45.0`, and a *newer* installed version is as much drift as an
|
|
465
|
+
older one.
|
|
466
|
+
|
|
467
|
+
By default only differences are listed; the matching tools are counted in the last line, and
|
|
468
|
+
`--all` lists them (and the extras) as rows. `--json` writes one array — every state, always — of
|
|
469
|
+
`{"key", "state", "type", "pinned", "installed", "note"}` objects and nothing else, even at `-vv`.
|
|
470
|
+
|
|
471
|
+
**Exit status.** `0` whenever the comparison ran, whatever it found. With `--exit-code` it is `1`
|
|
472
|
+
if the machine differs; an installed tool that isn't in the profile counts as a difference unless
|
|
473
|
+
you also pass `--ignore-extras`, which affects only this exit status and never hides a real
|
|
474
|
+
difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
|
|
475
|
+
mean "differs".
|
|
476
|
+
|
|
477
|
+
---
|
|
478
|
+
|
|
375
479
|
### `configure`
|
|
376
480
|
|
|
377
481
|
Set up an installed tool through a guided wizard, previewing the result before anything is
|
|
@@ -4,19 +4,21 @@ 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=
|
|
7
|
+
dev_setup/cli.py,sha256=M4si1b2yZ44Y3zfdwF-D0v__ZhDnemLl8vLrFKonWDg,3320
|
|
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=
|
|
14
|
+
dev_setup/generic.py,sha256=T_NkixzfdjfbWBPImVgw2XVDn1ae2GmNtNJXR_9tUKI,35132
|
|
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
|
|
18
18
|
dev_setup/links_registry.py,sha256=xyq49oH1u_CX85UcizKSuxuy_pzurNoDwSRg3YftUMY,2439
|
|
19
|
+
dev_setup/profile.py,sha256=NiSOXXwEPX6IIT8FagnAC-tcg49HWijFDSm2jn3hjts,13632
|
|
19
20
|
dev_setup/registry.py,sha256=8lrk6EXCCWk1WNeNnCGLTJ-v8rpCs7-TLYtVXgiuxnA,2243
|
|
21
|
+
dev_setup/snapshot.py,sha256=A2G_6pHSaGhDT1PJAZ6eW83GdSdCGs2r79yH8FCa0Qs,5330
|
|
20
22
|
dev_setup/tools.yaml,sha256=m2MEYq_mZuzEU8vCJgPWHdhLuqRjQGNWheqhwQgMXXQ,34234
|
|
21
23
|
dev_setup/ui.py,sha256=bm4VBv-DVs8h7v6roHUNQ7TqmUoXcBRNu78Xex-Qx-0,7505
|
|
22
24
|
dev_setup/updates.py,sha256=D6dH6G_Bv07XWSyzXvYESbV5s2d0N7euHu69zUyBbs4,5289
|
|
@@ -45,11 +47,12 @@ dev_setup/commands/delete_cmd.py,sha256=j_-fr2RMaeX3sMhH-7wJP5KC9Yvpgbb9KIeEEyG9
|
|
|
45
47
|
dev_setup/commands/docs_cmd.py,sha256=JXhusKUl4dD-U5jG-PLTon_2NCpAWWnaBqsmlFk7vLY,971
|
|
46
48
|
dev_setup/commands/doctor_cmd.py,sha256=sPhxLMVxy1JOxdFklRQHIwCoJeB-nmGWzVs5yeza9a8,3568
|
|
47
49
|
dev_setup/commands/functions_cmd.py,sha256=4HvdLXle9JGk70A1EDVZrlgTo-N-FyAO7ApaL8mcJYI,3023
|
|
48
|
-
dev_setup/commands/help_cmd.py,sha256=
|
|
50
|
+
dev_setup/commands/help_cmd.py,sha256=x-dbIeq15K-fYGjBV4RBElYvznRuX2Xow5BzsqnkLbc,4571
|
|
49
51
|
dev_setup/commands/install_cmd.py,sha256=0mUEdZQWPgXuK4_5aVhGZOadQYM1JhFZjl-biRHjSf4,4610
|
|
50
52
|
dev_setup/commands/links_cmd.py,sha256=kvnoBXdM9QWRZRIwWgnmWqVkOYE7AZxywFTQD5_Uwv4,4924
|
|
51
53
|
dev_setup/commands/list_cmd.py,sha256=Env6bwAmREDek4L-ZB2CIfvLT4PgaKcz5sQKJ1GhL8g,2913
|
|
52
54
|
dev_setup/commands/outdated_cmd.py,sha256=YljnMw-KZd1jcZO5FEce3H6nrX1MnWOt0fRBSAdlpQE,5070
|
|
55
|
+
dev_setup/commands/profile_cmd.py,sha256=p5FKbul18jA--440eLnHKj1fmeaGpUrT2f2g6-hLXtI,7638
|
|
53
56
|
dev_setup/commands/remove_cmd.py,sha256=_KqCa2S9fQFngLUs_OpBzjkIkFKgDtKup4gQ5TqLrVI,1239
|
|
54
57
|
dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
|
|
55
58
|
dev_setup/commands/skills_cmd.py,sha256=j4rleYEW4lt-O2ssDwGyhwmk2Wiip64C4Z7iPT6c3y0,7482
|
|
@@ -100,7 +103,7 @@ dev_setup/configure/starship/model.py,sha256=ct1YrR3xLqcKMP20TvKZQ0Oc-OxHMrRjnei
|
|
|
100
103
|
dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
|
|
101
104
|
dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
|
|
102
105
|
dev_setup/configure/starship/wizard.py,sha256=Q6aoKnz_n9WhFhTD4EygvaenZRsQTVwyZ1ga-cpUqBk,28620
|
|
103
|
-
devstuff-2.
|
|
104
|
-
devstuff-2.
|
|
105
|
-
devstuff-2.
|
|
106
|
-
devstuff-2.
|
|
106
|
+
devstuff-2.12.0.dist-info/METADATA,sha256=Jm0sKLAZ2qQps1G1XU7rylfP-E-wASPIrGtbn9egRd8,88317
|
|
107
|
+
devstuff-2.12.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
108
|
+
devstuff-2.12.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
|
|
109
|
+
devstuff-2.12.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|