devstuff 2.12.0__py3-none-any.whl → 2.13.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/apply_exec.py +156 -0
- dev_setup/apply_plan.py +218 -0
- dev_setup/bundles/ai-agents.yaml +10 -0
- dev_setup/bundles/ai-local.yaml +10 -0
- dev_setup/bundles/devops.yaml +12 -0
- dev_setup/bundles/essentials.yaml +14 -0
- dev_setup/bundles/languages.yaml +11 -0
- dev_setup/bundles/python.yaml +10 -0
- dev_setup/bundles.py +62 -0
- dev_setup/commands/help_cmd.py +1 -1
- dev_setup/commands/profile_cmd.py +274 -15
- dev_setup/generic.py +19 -2
- {devstuff-2.12.0.dist-info → devstuff-2.13.0.dist-info}/METADATA +69 -6
- {devstuff-2.12.0.dist-info → devstuff-2.13.0.dist-info}/RECORD +16 -7
- {devstuff-2.12.0.dist-info → devstuff-2.13.0.dist-info}/WHEEL +0 -0
- {devstuff-2.12.0.dist-info → devstuff-2.13.0.dist-info}/entry_points.txt +0 -0
dev_setup/apply_exec.py
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""Carrying out an apply plan (docs/specs/profile-apply, FR-6–11, FR-19, NFR-5).
|
|
2
|
+
|
|
3
|
+
`perform` does one step; `execute` runs a whole plan under the failure policy. Together they are
|
|
4
|
+
the non-interactive core. `devstuff install` wraps `tool.install()` in a section header, an
|
|
5
|
+
"already installed" short-circuit and, at the end, an offer to run the tool's setup wizard; none
|
|
6
|
+
of that belongs in an unattended run, so this does only the work and reports how it went.
|
|
7
|
+
|
|
8
|
+
It deliberately does not share code with `install_cmd._install_one`: what they would share is one
|
|
9
|
+
`try`/`except`, and `install_cmd` is a file with no parity tests to refactor against.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
from collections.abc import Callable
|
|
15
|
+
from dataclasses import dataclass
|
|
16
|
+
from enum import StrEnum
|
|
17
|
+
|
|
18
|
+
from dev_setup import generic
|
|
19
|
+
from dev_setup.apply_plan import Action, Outcome, Plan, Step, blocked_by
|
|
20
|
+
from dev_setup.base import Tool
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class Result:
|
|
25
|
+
"""How one step ended. `ok` means the installer returned — not that the machine now matches.
|
|
26
|
+
|
|
27
|
+
Whether it matches is decided afterwards, by re-measuring (spec SD-3); an installer that
|
|
28
|
+
exits 0 having installed nothing is a known hazard of this catalog.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
ok: bool
|
|
32
|
+
version: str | None = None # what the tool reports afterwards, when it reports anything
|
|
33
|
+
error: str = ""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def perform(tool: Tool, step: Step) -> Result:
|
|
37
|
+
"""Do what `step` says to `tool`. Never raises for a failed install; always forgets probes.
|
|
38
|
+
|
|
39
|
+
`KeyboardInterrupt` is not caught: an interrupted run must stop, not record a failed step
|
|
40
|
+
and carry on (FR-19). Probes are forgotten on every path out, because an installer that
|
|
41
|
+
failed or was interrupted may still have changed the machine.
|
|
42
|
+
"""
|
|
43
|
+
try:
|
|
44
|
+
if step.action is Action.INSTALL:
|
|
45
|
+
return Result(True, tool.install())
|
|
46
|
+
if not step.version:
|
|
47
|
+
return Result(False, error=f"a '{step.action}' step has no version to pin to")
|
|
48
|
+
# One call, not install-then-update: `update(version=…)` is the installer's own command
|
|
49
|
+
# with a version in it, and works on a tool that is not installed (spec F-3, SD-1).
|
|
50
|
+
return Result(True, tool.update(version=step.version)) # type: ignore[attr-defined]
|
|
51
|
+
except Exception as exc:
|
|
52
|
+
return Result(False, error=str(exc) or type(exc).__name__)
|
|
53
|
+
finally:
|
|
54
|
+
generic.forget_probes()
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class Status(StrEnum):
|
|
58
|
+
"""How one planned step ended. Values are the `--json` spellings."""
|
|
59
|
+
|
|
60
|
+
DONE = "done"
|
|
61
|
+
FAILED = "failed"
|
|
62
|
+
SKIPPED = "skipped" # not attempted: something it needs failed or was skipped
|
|
63
|
+
INTERRUPTED = "interrupted" # Ctrl-C arrived while it was the current step
|
|
64
|
+
NOT_RUN = "not run" # never reached, because the run was interrupted first
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass(frozen=True)
|
|
68
|
+
class StepResult:
|
|
69
|
+
key: str
|
|
70
|
+
status: Status
|
|
71
|
+
version: str | None = None
|
|
72
|
+
detail: str = "" # the installer's error, or why the step was skipped
|
|
73
|
+
|
|
74
|
+
def to_json(self) -> dict[str, str | None]:
|
|
75
|
+
return {
|
|
76
|
+
"key": self.key,
|
|
77
|
+
"status": self.status.value,
|
|
78
|
+
"version": self.version,
|
|
79
|
+
"detail": self.detail,
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
@dataclass(frozen=True)
|
|
84
|
+
class RunResult:
|
|
85
|
+
results: tuple[StepResult, ...]
|
|
86
|
+
interrupted: bool = False
|
|
87
|
+
|
|
88
|
+
@property
|
|
89
|
+
def ok(self) -> bool:
|
|
90
|
+
"""Every planned step ran and returned. Not "the machine matches": that is re-measured."""
|
|
91
|
+
return not self.interrupted and all(r.status is Status.DONE for r in self.results)
|
|
92
|
+
|
|
93
|
+
def to_json(self) -> dict[str, object]:
|
|
94
|
+
return {"interrupted": self.interrupted, "steps": [r.to_json() for r in self.results]}
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def execute(
|
|
98
|
+
plan: Plan,
|
|
99
|
+
lookup: Callable[[str], Tool | None],
|
|
100
|
+
*,
|
|
101
|
+
run: Callable[[Tool, Step], Result] = perform,
|
|
102
|
+
on_start: Callable[[Step], None] | None = None,
|
|
103
|
+
on_done: Callable[[StepResult], None] | None = None,
|
|
104
|
+
) -> RunResult:
|
|
105
|
+
"""Run the plan's steps serially, in order, and say how each one ended.
|
|
106
|
+
|
|
107
|
+
**A failure never stops the run** (FR-9, SD-4). Anything whose requires include a failed or
|
|
108
|
+
skipped step is skipped with the reason, without being attempted; everything else carries on.
|
|
109
|
+
|
|
110
|
+
**Ctrl-C ends the run cleanly** (FR-19): the step that was current is `interrupted`, the rest
|
|
111
|
+
are `not run`, and what finished stays `done`. It returns normally so the caller can still
|
|
112
|
+
print the summary — the exit status, not an exception, is what says it did not complete.
|
|
113
|
+
|
|
114
|
+
`lookup` maps a key to its tool (`registry.get`); `run` is `perform`, injectable so every path
|
|
115
|
+
here can be exercised without installing anything. `on_start`/`on_done` are for progress
|
|
116
|
+
output; `on_start` is not called for a step that is skipped without being attempted.
|
|
117
|
+
"""
|
|
118
|
+
results: list[StepResult] = []
|
|
119
|
+
bad: dict[str, Outcome] = {}
|
|
120
|
+
current: Step | None = None
|
|
121
|
+
|
|
122
|
+
def record(result: StepResult) -> None:
|
|
123
|
+
results.append(result)
|
|
124
|
+
if result.status is Status.FAILED:
|
|
125
|
+
bad[result.key] = Outcome.FAILED
|
|
126
|
+
elif result.status is Status.SKIPPED:
|
|
127
|
+
bad[result.key] = Outcome.SKIPPED
|
|
128
|
+
if on_done:
|
|
129
|
+
on_done(result)
|
|
130
|
+
|
|
131
|
+
try:
|
|
132
|
+
for step in plan.steps:
|
|
133
|
+
reason = blocked_by(step, bad)
|
|
134
|
+
if reason:
|
|
135
|
+
record(StepResult(step.key, Status.SKIPPED, None, reason))
|
|
136
|
+
continue
|
|
137
|
+
current = step
|
|
138
|
+
if on_start:
|
|
139
|
+
on_start(step)
|
|
140
|
+
tool = lookup(step.key)
|
|
141
|
+
if tool is None:
|
|
142
|
+
outcome = Result(False, error="not in this machine's catalog")
|
|
143
|
+
else:
|
|
144
|
+
outcome = run(tool, step)
|
|
145
|
+
current = None # the step is over: an interrupt from here on is "between steps"
|
|
146
|
+
if outcome.ok:
|
|
147
|
+
record(StepResult(step.key, Status.DONE, outcome.version))
|
|
148
|
+
else:
|
|
149
|
+
record(StepResult(step.key, Status.FAILED, None, outcome.error))
|
|
150
|
+
except KeyboardInterrupt:
|
|
151
|
+
if current is not None:
|
|
152
|
+
results.append(StepResult(current.key, Status.INTERRUPTED))
|
|
153
|
+
seen = {r.key for r in results}
|
|
154
|
+
results += [StepResult(st.key, Status.NOT_RUN) for st in plan.steps if st.key not in seen]
|
|
155
|
+
return RunResult(tuple(results), interrupted=True)
|
|
156
|
+
return RunResult(tuple(results))
|
dev_setup/apply_plan.py
ADDED
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
"""Turning a diff into an install plan (docs/specs/profile-apply, FR-2, FR-3, FR-9, FR-22).
|
|
2
|
+
|
|
3
|
+
Pure: rows in, `Plan` out — no subprocess, no registry, no terminal. The one thing it needs from
|
|
4
|
+
the outside, which dependencies a tool is still missing, arrives as a function, so the ordering
|
|
5
|
+
rules can be tested exhaustively without installing anything.
|
|
6
|
+
|
|
7
|
+
The plan is derived from `profile.compare`'s rows rather than from a second comparison (SD-2): two
|
|
8
|
+
definitions of "missing" or "drift" would let `diff` say a machine matches while `apply` changes it.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from collections.abc import Callable, Mapping, Sequence
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from enum import StrEnum
|
|
16
|
+
|
|
17
|
+
from dev_setup.profile import DiffRow, DiffState, MachineTool
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Action(StrEnum):
|
|
21
|
+
"""Values are the `--json` spellings and the words the plan table shows."""
|
|
22
|
+
|
|
23
|
+
INSTALL = "install"
|
|
24
|
+
# One `update(version=…)` call, not install-then-update: measured to work on a tool that is
|
|
25
|
+
# not installed, and it never installs a "latest" that was not asked for (spec F-3, SD-1).
|
|
26
|
+
INSTALL_PINNED = "install pinned"
|
|
27
|
+
UPDATE_TO_PIN = "update to pin"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class Outcome(StrEnum):
|
|
31
|
+
"""How an earlier step ended, for deciding whether a later one can run (FR-9)."""
|
|
32
|
+
|
|
33
|
+
FAILED = "failed"
|
|
34
|
+
SKIPPED = "skipped"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class Step:
|
|
39
|
+
key: str
|
|
40
|
+
action: Action
|
|
41
|
+
version: str | None # the pin, for the two pinned actions
|
|
42
|
+
installed: str | None # what is installed now, for `update to pin`
|
|
43
|
+
type: str
|
|
44
|
+
# Asked for by the profile, as opposed to pulled in because something else needs it.
|
|
45
|
+
requested: bool
|
|
46
|
+
# The requested tools this one is here for. Empty when nothing else needs it.
|
|
47
|
+
needed_by: tuple[str, ...]
|
|
48
|
+
# Every not-yet-installed tool in this one's requires closure, deepest first. All of them are
|
|
49
|
+
# planned earlier; a run uses this to skip the step when one of them failed (`blocked_by`).
|
|
50
|
+
needs: tuple[str, ...]
|
|
51
|
+
|
|
52
|
+
def to_json(self) -> dict[str, object]:
|
|
53
|
+
return {
|
|
54
|
+
"key": self.key,
|
|
55
|
+
"action": self.action.value,
|
|
56
|
+
"version": self.version,
|
|
57
|
+
"installed": self.installed,
|
|
58
|
+
"type": self.type,
|
|
59
|
+
"requested": self.requested,
|
|
60
|
+
"needed_by": list(self.needed_by),
|
|
61
|
+
"needs": list(self.needs),
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
@dataclass(frozen=True)
|
|
66
|
+
class Skip:
|
|
67
|
+
"""A profile entry `apply` will not act on, and why. Never silently dropped (FR-2)."""
|
|
68
|
+
|
|
69
|
+
key: str
|
|
70
|
+
state: DiffState
|
|
71
|
+
reason: str
|
|
72
|
+
|
|
73
|
+
def to_json(self) -> dict[str, str]:
|
|
74
|
+
return {"key": self.key, "state": self.state.value, "reason": self.reason}
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@dataclass(frozen=True)
|
|
78
|
+
class Plan:
|
|
79
|
+
steps: tuple[Step, ...]
|
|
80
|
+
skipped: tuple[Skip, ...]
|
|
81
|
+
ok: tuple[str, ...] # entries that already match — no work, but part of the picture
|
|
82
|
+
|
|
83
|
+
@property
|
|
84
|
+
def nothing_to_do(self) -> bool:
|
|
85
|
+
return not self.steps
|
|
86
|
+
|
|
87
|
+
def to_json(self) -> dict[str, object]:
|
|
88
|
+
return {
|
|
89
|
+
"steps": [s.to_json() for s in self.steps],
|
|
90
|
+
"skipped": [s.to_json() for s in self.skipped],
|
|
91
|
+
"ok": list(self.ok),
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def blocked_by(step: Step, bad: Mapping[str, Outcome]) -> str | None:
|
|
96
|
+
"""Why `step` must not run, given how earlier steps ended; None when nothing it needs went wrong.
|
|
97
|
+
|
|
98
|
+
The first offender in plan order is named, so the reason points at the root of the chain.
|
|
99
|
+
"""
|
|
100
|
+
for need in step.needs:
|
|
101
|
+
outcome = bad.get(need)
|
|
102
|
+
if outcome is Outcome.FAILED:
|
|
103
|
+
return f"needs {need}, which failed"
|
|
104
|
+
if outcome is Outcome.SKIPPED:
|
|
105
|
+
return f"needs {need}, which was skipped"
|
|
106
|
+
return None
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _skip_reason(row: DiffRow) -> str:
|
|
110
|
+
return row.note or f"{row.state.value}: couldn't act on this entry"
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def build_plan(
|
|
114
|
+
rows: Sequence[DiffRow],
|
|
115
|
+
machine: Mapping[str, MachineTool],
|
|
116
|
+
closure: Callable[[str], Sequence[str]],
|
|
117
|
+
*,
|
|
118
|
+
missing_only: bool = False,
|
|
119
|
+
) -> Plan:
|
|
120
|
+
"""The steps to make the machine match, in an order where every tool follows what it needs.
|
|
121
|
+
|
|
122
|
+
`closure(key)` is the tool's transitive requires that are *not installed*, deepest first —
|
|
123
|
+
`registry.missing_requires` in production. It is asked only about tools about to be installed.
|
|
124
|
+
`missing_only` leaves a drifted tool where it is.
|
|
125
|
+
"""
|
|
126
|
+
ok: list[str] = []
|
|
127
|
+
skipped: dict[str, Skip] = {}
|
|
128
|
+
wanted: dict[str, tuple[Action, str | None, str | None, str]] = {} # key -> step ingredients
|
|
129
|
+
|
|
130
|
+
for row in rows:
|
|
131
|
+
state = row.state
|
|
132
|
+
if state is DiffState.OK:
|
|
133
|
+
ok.append(row.key)
|
|
134
|
+
elif state is DiffState.EXTRA:
|
|
135
|
+
pass # apply never removes (non-goal), and an extra is not a problem to report
|
|
136
|
+
elif state is DiffState.MISSING:
|
|
137
|
+
if row.pinned is None:
|
|
138
|
+
wanted[row.key] = (Action.INSTALL, None, None, row.type or "")
|
|
139
|
+
elif machine[row.key].pinnable:
|
|
140
|
+
wanted[row.key] = (Action.INSTALL_PINNED, row.pinned, None, row.type or "")
|
|
141
|
+
else:
|
|
142
|
+
# The profile asked for a version this install type cannot give. Installing
|
|
143
|
+
# "latest" instead is the silent substitution this command exists to avoid.
|
|
144
|
+
skipped[row.key] = Skip(
|
|
145
|
+
row.key, state,
|
|
146
|
+
f"pinned to {row.pinned}, but a {row.type} install can't be pinned — "
|
|
147
|
+
"remove the version from the profile to install the latest",
|
|
148
|
+
)
|
|
149
|
+
elif state is DiffState.DRIFT:
|
|
150
|
+
if missing_only:
|
|
151
|
+
skipped[row.key] = Skip(
|
|
152
|
+
row.key, state,
|
|
153
|
+
f"installed at {row.installed}, profile pins {row.pinned} — "
|
|
154
|
+
"left alone (--missing-only)",
|
|
155
|
+
)
|
|
156
|
+
else:
|
|
157
|
+
wanted[row.key] = (Action.UPDATE_TO_PIN, row.pinned, row.installed, row.type or "")
|
|
158
|
+
else: # unverifiable, unpinnable, unknown-key: the comparison could not be made
|
|
159
|
+
skipped[row.key] = Skip(row.key, state, _skip_reason(row))
|
|
160
|
+
|
|
161
|
+
# Dependencies. A tool that needs something this plan cannot provide is skipped, not tried.
|
|
162
|
+
needs: dict[str, tuple[str, ...]] = {}
|
|
163
|
+
for key in sorted(wanted):
|
|
164
|
+
action = wanted[key][0]
|
|
165
|
+
if action is Action.UPDATE_TO_PIN:
|
|
166
|
+
continue # already installed; its dependencies are not this command's business
|
|
167
|
+
chain = tuple(closure(key))
|
|
168
|
+
blocker = _blocker(chain, machine, skipped)
|
|
169
|
+
if blocker is not None:
|
|
170
|
+
del wanted[key]
|
|
171
|
+
skipped[key] = Skip(key, DiffState.MISSING, blocker)
|
|
172
|
+
else:
|
|
173
|
+
needs[key] = chain
|
|
174
|
+
|
|
175
|
+
# Emission order: each requested tool (by key, so the plan is deterministic) preceded by
|
|
176
|
+
# whatever it needs that is not already out. Each closure is deepest-first, so a tool's own
|
|
177
|
+
# dependencies are always out before it is — keeping first occurrences preserves that.
|
|
178
|
+
order: list[str] = []
|
|
179
|
+
for key in sorted(wanted):
|
|
180
|
+
for dep in needs.get(key, ()):
|
|
181
|
+
if dep not in order:
|
|
182
|
+
order.append(dep)
|
|
183
|
+
if key not in order:
|
|
184
|
+
order.append(key)
|
|
185
|
+
|
|
186
|
+
needed_by: dict[str, set[str]] = {}
|
|
187
|
+
for key, chain in needs.items():
|
|
188
|
+
for dep in chain:
|
|
189
|
+
needed_by.setdefault(dep, set()).add(key)
|
|
190
|
+
|
|
191
|
+
steps: list[Step] = []
|
|
192
|
+
for key in order:
|
|
193
|
+
if key in wanted:
|
|
194
|
+
action, version, installed, type_ = wanted[key]
|
|
195
|
+
requested = True
|
|
196
|
+
else: # pulled in only because something needs it: installed unpinned, as the catalog says
|
|
197
|
+
action, version, installed, type_ = Action.INSTALL, None, None, machine[key].install_type
|
|
198
|
+
requested = False
|
|
199
|
+
steps.append(
|
|
200
|
+
Step(
|
|
201
|
+
key, action, version, installed, type_, requested,
|
|
202
|
+
tuple(sorted(needed_by.get(key, ()))),
|
|
203
|
+
needs.get(key, ()) if requested else tuple(closure(key)),
|
|
204
|
+
)
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
return Plan(tuple(steps), tuple(skipped[k] for k in sorted(skipped)), tuple(sorted(ok)))
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def _blocker(
|
|
211
|
+
chain: Sequence[str], machine: Mapping[str, MachineTool], skipped: Mapping[str, Skip]
|
|
212
|
+
) -> str | None:
|
|
213
|
+
for dep in chain:
|
|
214
|
+
if dep not in machine:
|
|
215
|
+
return f"needs {dep}, which is not in this machine's catalog"
|
|
216
|
+
if dep in skipped:
|
|
217
|
+
return f"needs {dep}, which was skipped: {skipped[dep].reason}"
|
|
218
|
+
return None
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# @ai-agents — Coding agents for the terminal. The npm-based ones pull in nvm automatically.
|
|
2
|
+
# Apply with: devstuff profile apply @ai-agents
|
|
3
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
4
|
+
version: 1
|
|
5
|
+
tools:
|
|
6
|
+
claude-code: {}
|
|
7
|
+
codex: {}
|
|
8
|
+
devin: {}
|
|
9
|
+
hey-dave: {}
|
|
10
|
+
pi: {}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# @ai-local — Running models on this machine, and checking what it can run.
|
|
2
|
+
# Note: lmstudio asks for sudo when libatomic1 is missing.
|
|
3
|
+
# Apply with: devstuff profile apply @ai-local
|
|
4
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
5
|
+
version: 1
|
|
6
|
+
tools:
|
|
7
|
+
llamactl: {}
|
|
8
|
+
llm-checker: {}
|
|
9
|
+
lmstudio: {}
|
|
10
|
+
ollama: {}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# @devops — Containers, configuration management and cloud access.
|
|
2
|
+
# Note: docker asks for sudo (and a re-login before your user can use it without sudo).
|
|
3
|
+
# Apply with: devstuff profile apply @devops
|
|
4
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
5
|
+
version: 1
|
|
6
|
+
tools:
|
|
7
|
+
ansible: {}
|
|
8
|
+
ansible-vault: {}
|
|
9
|
+
aws: {}
|
|
10
|
+
docker: {}
|
|
11
|
+
mkcert: {}
|
|
12
|
+
saml2aws: {}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# @essentials — A fresh machine's everyday set: git helpers, a nicer shell prompt, and the small tools you reach for daily.
|
|
2
|
+
# Note: nerd-font supplies the icons starship draws; installing it does not switch your terminal to that font.
|
|
3
|
+
# Apply with: devstuff profile apply @essentials
|
|
4
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
5
|
+
version: 1
|
|
6
|
+
tools:
|
|
7
|
+
bat: {}
|
|
8
|
+
gh: {}
|
|
9
|
+
git-lfs: {}
|
|
10
|
+
htop: {}
|
|
11
|
+
lazygit: {}
|
|
12
|
+
nerd-font: {}
|
|
13
|
+
starship: {}
|
|
14
|
+
yq: {}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# @languages — Language toolchains. The heaviest bundle: java comes from apt, php from a PPA, and ruby builds from source.
|
|
2
|
+
# Note: java, php and ruby all ask for sudo (apt packages, the PHP PPA, ruby build dependencies).
|
|
3
|
+
# Apply with: devstuff profile apply @languages
|
|
4
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
5
|
+
version: 1
|
|
6
|
+
tools:
|
|
7
|
+
go: {}
|
|
8
|
+
java: {}
|
|
9
|
+
php: {}
|
|
10
|
+
python: {}
|
|
11
|
+
ruby: {}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# @python — Python the way devstuff does it: uv owns the interpreter, plus the usual quality tooling.
|
|
2
|
+
# Apply with: devstuff profile apply @python
|
|
3
|
+
# Names no versions, so it installs the latest of each; extra tools it needs are added for you.
|
|
4
|
+
version: 1
|
|
5
|
+
tools:
|
|
6
|
+
commitizen: {}
|
|
7
|
+
ipython: {}
|
|
8
|
+
pre-commit: {}
|
|
9
|
+
python: {}
|
|
10
|
+
uv: {}
|
dev_setup/bundles.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Profiles that ship with devstuff, named with a leading `@` (docs/specs/profile-apply, FR-20, FR-21).
|
|
2
|
+
|
|
3
|
+
`devstuff profile apply @devops` is `apply` on a file that lives in the package. A bundle is an
|
|
4
|
+
ordinary profile — same format, same strict loader — so there is exactly one thing to document
|
|
5
|
+
and to validate (SD-9), and any bundle can be copied out and edited.
|
|
6
|
+
|
|
7
|
+
The name is never turned into a path. Lookup lists the bundle directory and matches the name
|
|
8
|
+
against what it finds, so `@../x` or `@/etc/passwd` has nothing to traverse: it is simply not in
|
|
9
|
+
the list.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
from importlib import resources
|
|
16
|
+
from importlib.resources.abc import Traversable
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
|
|
19
|
+
from dev_setup import profile
|
|
20
|
+
from dev_setup.profile import Profile, ProfileError
|
|
21
|
+
|
|
22
|
+
_SUFFIX = ".yaml"
|
|
23
|
+
_NAME = re.compile(r"[a-z][a-z0-9-]*")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _root() -> Traversable:
|
|
27
|
+
return resources.files("dev_setup") / "bundles"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _files() -> dict[str, Traversable]:
|
|
31
|
+
"""Bundle name -> its file. Anything in the directory that is not a well-named YAML file is
|
|
32
|
+
not a bundle: the data tests insist the directory holds nothing else."""
|
|
33
|
+
found: dict[str, Traversable] = {}
|
|
34
|
+
for entry in _root().iterdir():
|
|
35
|
+
stem = entry.name.removesuffix(_SUFFIX)
|
|
36
|
+
if entry.is_file() and entry.name.endswith(_SUFFIX) and _NAME.fullmatch(stem):
|
|
37
|
+
found[stem] = entry
|
|
38
|
+
return found
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def names() -> list[str]:
|
|
42
|
+
return sorted(_files())
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def is_bundle(arg: str) -> bool:
|
|
46
|
+
"""`@name` is a bundle; anything else is a file. A file that really starts with `@` is `./@x`."""
|
|
47
|
+
return arg.startswith("@")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def resolve(arg: str) -> Profile:
|
|
51
|
+
"""Load the bundle `arg` (`@name`). An unknown name lists the ones that exist (FR-21)."""
|
|
52
|
+
files = _files()
|
|
53
|
+
entry = files.get(arg[1:]) if is_bundle(arg) else None
|
|
54
|
+
if entry is None:
|
|
55
|
+
available = ", ".join(f"@{n}" for n in sorted(files)) or "(none)"
|
|
56
|
+
raise ProfileError(f"no bundle named {arg!r}. Bundles: {available}")
|
|
57
|
+
return profile.loads(entry.read_text(encoding="utf-8"), source=arg)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def load_arg(arg: str) -> Profile:
|
|
61
|
+
"""The one way a command turns its PROFILE argument into a profile."""
|
|
62
|
+
return resolve(arg) if is_bundle(arg) else profile.load(Path(arg))
|
dev_setup/commands/help_cmd.py
CHANGED
|
@@ -26,7 +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> [...]",
|
|
29
|
+
("profile", "<snapshot|diff|apply> [...]", "Save, compare or apply this machine's tools"),
|
|
30
30
|
("configure", "[tool] [--list] [--path]", "Set up a tool with a guided wizard"),
|
|
31
31
|
("add", "", "Add a custom package (guided wizard)"),
|
|
32
32
|
("delete", "<key>", "Remove a custom package from the registry"),
|
|
@@ -2,13 +2,14 @@ from __future__ import annotations
|
|
|
2
2
|
|
|
3
3
|
import json
|
|
4
4
|
import sys
|
|
5
|
-
from
|
|
5
|
+
from collections.abc import Iterator
|
|
6
|
+
from contextlib import contextmanager, nullcontext, redirect_stdout
|
|
6
7
|
from pathlib import Path
|
|
7
8
|
|
|
8
9
|
import click
|
|
9
10
|
from rich.markup import escape
|
|
10
11
|
|
|
11
|
-
from dev_setup import profile, snapshot, ui, verbose
|
|
12
|
+
from dev_setup import apply_exec, apply_plan, bundles, profile, registry, snapshot, ui, verbose
|
|
12
13
|
from dev_setup.profile import DiffRow, DiffState
|
|
13
14
|
|
|
14
15
|
_CUSTOM_NAMES_SHOWN = 6
|
|
@@ -103,7 +104,7 @@ _EXTRA_NAMES_SHOWN = 12
|
|
|
103
104
|
|
|
104
105
|
|
|
105
106
|
@profile_cmd.command("diff")
|
|
106
|
-
@click.argument("profile_file", metavar="PROFILE"
|
|
107
|
+
@click.argument("profile_file", metavar="PROFILE")
|
|
107
108
|
@click.option(
|
|
108
109
|
"--all", "show_all", is_flag=True,
|
|
109
110
|
help="Also list the tools that match, and the tools not in the profile, as rows.",
|
|
@@ -121,10 +122,13 @@ _EXTRA_NAMES_SHOWN = 12
|
|
|
121
122
|
help="For --exit-code: don't count installed tools that aren't in the profile as a difference.",
|
|
122
123
|
)
|
|
123
124
|
def diff_cmd(
|
|
124
|
-
profile_file:
|
|
125
|
+
profile_file: str, show_all: bool, as_json: bool, exit_code: bool, ignore_extras: bool
|
|
125
126
|
) -> None:
|
|
126
127
|
"""Compare this machine to a profile.
|
|
127
128
|
|
|
129
|
+
PROFILE is a file, or `@name` for a profile that ships with devstuff (e.g. `@devops`;
|
|
130
|
+
`./@x` names a file that starts with an @).
|
|
131
|
+
|
|
128
132
|
Read-only. Each key is reported as ok, missing, drift (installed at a different version
|
|
129
133
|
than the profile pins), unverifiable (pinned, but the installed version can't be read),
|
|
130
134
|
unpinnable (pinned, but that install type can't honour a pin), unknown-key (not in this
|
|
@@ -135,7 +139,7 @@ def diff_cmd(
|
|
|
135
139
|
profile that can't be read or isn't valid is always 2, so 1 only ever means "differs".
|
|
136
140
|
"""
|
|
137
141
|
try:
|
|
138
|
-
wanted =
|
|
142
|
+
wanted = bundles.load_arg(profile_file)
|
|
139
143
|
except profile.ProfileError as exc:
|
|
140
144
|
click.echo(f"error: {exc}", err=True)
|
|
141
145
|
sys.exit(2)
|
|
@@ -144,7 +148,7 @@ def diff_cmd(
|
|
|
144
148
|
if interactive:
|
|
145
149
|
ui.print_banner()
|
|
146
150
|
progress = (
|
|
147
|
-
verbose.step(f"Comparing this machine to {profile_file.name}...")
|
|
151
|
+
verbose.step(f"Comparing this machine to {Path(profile_file).name}...")
|
|
148
152
|
if interactive else nullcontext()
|
|
149
153
|
)
|
|
150
154
|
with progress:
|
|
@@ -168,20 +172,24 @@ def _status_cell(row: DiffRow) -> str:
|
|
|
168
172
|
return cell
|
|
169
173
|
|
|
170
174
|
|
|
175
|
+
def _print_rows(rows: list[DiffRow]) -> None:
|
|
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 rows:
|
|
183
|
+
tbl.add_row(r.key, r.type or "", r.pinned or "", r.installed or "", _status_cell(r))
|
|
184
|
+
ui.console.print(tbl)
|
|
185
|
+
|
|
186
|
+
|
|
171
187
|
def _render(rows: list[DiffRow], *, show_all: bool) -> None:
|
|
172
188
|
extras = [r for r in rows if r.state is DiffState.EXTRA]
|
|
173
189
|
shown = rows if show_all else [r for r in rows if r.state not in (DiffState.OK, DiffState.EXTRA)]
|
|
174
190
|
|
|
175
191
|
if shown:
|
|
176
|
-
|
|
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)
|
|
192
|
+
_print_rows(shown)
|
|
185
193
|
elif not extras:
|
|
186
194
|
ui.info("This machine matches the profile.")
|
|
187
195
|
else:
|
|
@@ -197,3 +205,254 @@ def _render(rows: list[DiffRow], *, show_all: bool) -> None:
|
|
|
197
205
|
|
|
198
206
|
counts = profile.summarize_diff(rows)
|
|
199
207
|
ui.dim(" · ".join(f"{counts[s]} {s.value}" for s in profile.DIFF_ORDER if counts[s]))
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
# -- apply --------------------------------------------------------------------------------------
|
|
211
|
+
|
|
212
|
+
_ERROR_CHARS = 160
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def _can_prompt() -> bool:
|
|
216
|
+
"""Whether a confirmation could be answered. A seam for tests, which have no terminal."""
|
|
217
|
+
return sys.stdin.isatty()
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
def _first_line(text: str) -> str:
|
|
221
|
+
"""An installer's error, cut to one line: uv and apt can write pages, the summary is a list."""
|
|
222
|
+
line = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
|
|
223
|
+
return line if len(line) <= _ERROR_CHARS else line[: _ERROR_CHARS - 1] + "…"
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _may_ask_for_sudo(tool: object, step: apply_plan.Step) -> bool:
|
|
227
|
+
# Advisory (FR-5), not a control: a guess from the install type and the script's text, used
|
|
228
|
+
# only to put a warning in the plan. A script that reaches sudo another way is not caught,
|
|
229
|
+
# and nothing here prevents or permits anything.
|
|
230
|
+
return step.type == "apt" or "sudo" in (getattr(tool, "install_script", "") or "")
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
@contextmanager
|
|
234
|
+
def _json_safe() -> Iterator[None]:
|
|
235
|
+
"""Keep stdout to the one JSON document while installers run (NFR-1).
|
|
236
|
+
|
|
237
|
+
Installers print through `ui` (stdout) and, under -v, stream a subprocess's output straight
|
|
238
|
+
to the inherited stdout, where no redirect can reach it. So: stdout is pointed at stderr for
|
|
239
|
+
anything that prints, and streaming is switched off — `-v` has no effect with --json.
|
|
240
|
+
"""
|
|
241
|
+
previous = verbose.level()
|
|
242
|
+
verbose.set_level(verbose.QUIET)
|
|
243
|
+
try:
|
|
244
|
+
with redirect_stdout(sys.stderr):
|
|
245
|
+
yield
|
|
246
|
+
finally:
|
|
247
|
+
verbose.set_level(previous)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _show_plan(
|
|
251
|
+
plan: apply_plan.Plan, by_key: dict[str, object], profile_file: str
|
|
252
|
+
) -> None:
|
|
253
|
+
if plan.steps:
|
|
254
|
+
pinned_any = any(s.version for s in plan.steps)
|
|
255
|
+
tbl = ui.table(f"Plan for {Path(profile_file).name}")
|
|
256
|
+
tbl.add_column("Package", style="bold", no_wrap=True)
|
|
257
|
+
tbl.add_column("Type", style=ui.CYAN, no_wrap=True)
|
|
258
|
+
tbl.add_column("Action", no_wrap=True)
|
|
259
|
+
if pinned_any:
|
|
260
|
+
tbl.add_column("Version", style=ui.GRAY, no_wrap=True)
|
|
261
|
+
tbl.add_column("Note", style=ui.GRAY)
|
|
262
|
+
for st in plan.steps:
|
|
263
|
+
notes = []
|
|
264
|
+
if st.needed_by:
|
|
265
|
+
notes.append("needed by " + ", ".join(st.needed_by))
|
|
266
|
+
if _may_ask_for_sudo(by_key.get(st.key), st):
|
|
267
|
+
notes.append("may ask for sudo")
|
|
268
|
+
cells = [st.key, st.type, st.action.value]
|
|
269
|
+
if pinned_any:
|
|
270
|
+
version = st.version or ""
|
|
271
|
+
if st.installed and st.version:
|
|
272
|
+
version = f"{st.installed} → {st.version}"
|
|
273
|
+
cells.append(version)
|
|
274
|
+
cells.append(escape("; ".join(notes)))
|
|
275
|
+
tbl.add_row(*cells)
|
|
276
|
+
ui.console.print(tbl)
|
|
277
|
+
if plan.skipped:
|
|
278
|
+
ui.dim("Not acted on:")
|
|
279
|
+
for sk in plan.skipped:
|
|
280
|
+
color, label = _LABEL[sk.state]
|
|
281
|
+
ui.console.print(f" [{color}]{label}[/] [bold]{sk.key}[/] [{ui.GRAY}]{escape(sk.reason)}[/]")
|
|
282
|
+
if not plan.steps:
|
|
283
|
+
ui.info("Nothing to install or move.")
|
|
284
|
+
elif plan.ok:
|
|
285
|
+
ui.dim(f"{len(plan.ok)} already match.")
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def _progress_hooks(total: int):
|
|
289
|
+
counter = [0]
|
|
290
|
+
|
|
291
|
+
def on_start(step: apply_plan.Step) -> None:
|
|
292
|
+
counter[0] += 1
|
|
293
|
+
what = step.action.value + (f" {step.version}" if step.version else "")
|
|
294
|
+
ui.info(f"[{counter[0]}/{total}] {step.key}: {what}")
|
|
295
|
+
|
|
296
|
+
def on_done(result: apply_exec.StepResult) -> None:
|
|
297
|
+
S = apply_exec.Status
|
|
298
|
+
if result.status is S.DONE:
|
|
299
|
+
ui.success(f"{result.key}" + (f" {result.version}" if result.version else ""))
|
|
300
|
+
elif result.status is S.FAILED:
|
|
301
|
+
ui.error(f"{result.key} failed: {escape(_first_line(result.detail))}")
|
|
302
|
+
elif result.status is S.SKIPPED:
|
|
303
|
+
ui.warn(f"{result.key} skipped — {escape(result.detail)}")
|
|
304
|
+
|
|
305
|
+
return on_start, on_done
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def _summarize(
|
|
309
|
+
wanted: profile.Profile,
|
|
310
|
+
run: apply_exec.RunResult | None,
|
|
311
|
+
final: list[DiffRow],
|
|
312
|
+
profile_file: str,
|
|
313
|
+
) -> None:
|
|
314
|
+
S = apply_exec.Status
|
|
315
|
+
by_state = {r.key: r.state for r in final}
|
|
316
|
+
ui.console.print()
|
|
317
|
+
if run is not None:
|
|
318
|
+
if run.interrupted:
|
|
319
|
+
ui.warn("Interrupted — the run stopped early. What had finished stays done.")
|
|
320
|
+
for r in run.results:
|
|
321
|
+
if r.status is S.FAILED:
|
|
322
|
+
ui.error(f"{r.key}: {escape(_first_line(r.detail))}")
|
|
323
|
+
elif r.status is S.SKIPPED:
|
|
324
|
+
ui.warn(f"{r.key}: skipped — {escape(r.detail)}")
|
|
325
|
+
elif r.status is S.INTERRUPTED:
|
|
326
|
+
ui.warn(f"{r.key}: interrupted — it may be partly installed")
|
|
327
|
+
elif r.status is S.NOT_RUN:
|
|
328
|
+
ui.dim(f"{r.key}: not run")
|
|
329
|
+
elif by_state.get(r.key) is DiffState.MISSING:
|
|
330
|
+
ui.warn(
|
|
331
|
+
f"{r.key}: the installer reported success, but the tool isn't detected "
|
|
332
|
+
"afterwards — for npm and uv tools, is their bin directory on your PATH?"
|
|
333
|
+
)
|
|
334
|
+
elif by_state.get(r.key) is DiffState.UNVERIFIABLE:
|
|
335
|
+
ui.warn(
|
|
336
|
+
f"{r.key}: installed, version unverified — it can't be read back, "
|
|
337
|
+
"so the pin is unconfirmed"
|
|
338
|
+
)
|
|
339
|
+
|
|
340
|
+
remaining = [r for r in final if r.state not in (DiffState.OK, DiffState.EXTRA)]
|
|
341
|
+
if remaining:
|
|
342
|
+
_print_rows(remaining)
|
|
343
|
+
total = len(wanted.tools)
|
|
344
|
+
matching = sum(1 for r in final if r.state is DiffState.OK) # only profile keys can be ok
|
|
345
|
+
if matching == total and not remaining:
|
|
346
|
+
ui.success(f"This machine now matches {Path(profile_file).name} ({matching} of {total} entries).")
|
|
347
|
+
else:
|
|
348
|
+
ui.warn(f"{matching} of {total} entries match {Path(profile_file).name}.")
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
@profile_cmd.command("apply")
|
|
352
|
+
@click.argument("profile_file", metavar="PROFILE")
|
|
353
|
+
@click.option("--dry-run", is_flag=True, help="Show the plan and exit; change nothing and ask nothing.")
|
|
354
|
+
@click.option("--yes", "-y", is_flag=True, help="Don't ask for confirmation.")
|
|
355
|
+
@click.option(
|
|
356
|
+
"--missing-only", is_flag=True,
|
|
357
|
+
help="Install what is missing, but leave tools at a different version than the profile pins.",
|
|
358
|
+
)
|
|
359
|
+
@click.option(
|
|
360
|
+
"--json", "as_json", is_flag=True,
|
|
361
|
+
help="Write one JSON document to stdout and nothing else (plan, steps, final rows). "
|
|
362
|
+
"Needs --yes or --dry-run; -v has no effect.",
|
|
363
|
+
)
|
|
364
|
+
def apply_cmd(
|
|
365
|
+
profile_file: str, dry_run: bool, yes: bool, missing_only: bool, as_json: bool
|
|
366
|
+
) -> None:
|
|
367
|
+
"""Make this machine match a profile.
|
|
368
|
+
|
|
369
|
+
PROFILE is a file, or `@name` for a profile that ships with devstuff: `@essentials`, `@python`,
|
|
370
|
+
`@devops`, `@languages`, `@ai-agents`, `@ai-local` (an unknown name lists them).
|
|
371
|
+
|
|
372
|
+
Installs the profile's tools that are missing (with whatever they require, in order) and moves
|
|
373
|
+
pinned tools to the pinned version. It never removes anything and never touches a tool the
|
|
374
|
+
profile doesn't pin. The plan is shown first and confirmed — `--yes` skips the question,
|
|
375
|
+
`--dry-run` stops after the plan.
|
|
376
|
+
|
|
377
|
+
A failed tool doesn't stop the run: what needed it is skipped and the rest carries on. When it
|
|
378
|
+
finishes, the machine is read again and the result reported from that, not from whether the
|
|
379
|
+
installers returned.
|
|
380
|
+
|
|
381
|
+
Exit status: 0 if every entry in the profile now matches; 1 if any doesn't (including
|
|
382
|
+
entries it can't act on, and a run you declined or interrupted); 2 for a profile that can't
|
|
383
|
+
be read, or a run that needs confirming with no terminal to ask on.
|
|
384
|
+
"""
|
|
385
|
+
try:
|
|
386
|
+
wanted = bundles.load_arg(profile_file)
|
|
387
|
+
except profile.ProfileError as exc:
|
|
388
|
+
click.echo(f"error: {exc}", err=True)
|
|
389
|
+
sys.exit(2)
|
|
390
|
+
if as_json and not (yes or dry_run):
|
|
391
|
+
click.echo("error: --json can't ask for confirmation; add --yes to run, or --dry-run", err=True)
|
|
392
|
+
sys.exit(2)
|
|
393
|
+
|
|
394
|
+
tools = registry.all_tools()
|
|
395
|
+
by_key = {t.key: t for t in tools}
|
|
396
|
+
interactive = sys.stdout.isatty() and not as_json
|
|
397
|
+
if interactive:
|
|
398
|
+
ui.print_banner()
|
|
399
|
+
progress = (
|
|
400
|
+
verbose.step(f"Comparing this machine to {Path(profile_file).name}...")
|
|
401
|
+
if interactive else nullcontext()
|
|
402
|
+
)
|
|
403
|
+
with progress:
|
|
404
|
+
facts = snapshot.machine_facts(wanted, tools)
|
|
405
|
+
rows = profile.sort_diff_rows(profile.compare(wanted, facts))
|
|
406
|
+
plan = apply_plan.build_plan(
|
|
407
|
+
rows, facts, lambda key: registry.missing_requires(by_key[key]), missing_only=missing_only
|
|
408
|
+
)
|
|
409
|
+
|
|
410
|
+
if not as_json:
|
|
411
|
+
_show_plan(plan, by_key, profile_file)
|
|
412
|
+
|
|
413
|
+
if dry_run:
|
|
414
|
+
if as_json:
|
|
415
|
+
click.echo(json.dumps(_document(plan, None, rows), indent=2))
|
|
416
|
+
return
|
|
417
|
+
|
|
418
|
+
run: apply_exec.RunResult | None = None
|
|
419
|
+
final = rows # with nothing to run, the machine is as the first comparison found it
|
|
420
|
+
if not plan.nothing_to_do:
|
|
421
|
+
if not yes:
|
|
422
|
+
if not _can_prompt():
|
|
423
|
+
click.echo(
|
|
424
|
+
"error: this changes the machine and there is no terminal to confirm on; "
|
|
425
|
+
"add --yes to proceed, or --dry-run to only see the plan",
|
|
426
|
+
err=True,
|
|
427
|
+
)
|
|
428
|
+
sys.exit(2)
|
|
429
|
+
n = len(plan.steps)
|
|
430
|
+
if not ui.confirm(f"Apply {n} step{'' if n == 1 else 's'}?"):
|
|
431
|
+
ui.warn("Aborted — nothing was changed.")
|
|
432
|
+
sys.exit(1)
|
|
433
|
+
hooks = (None, None) if as_json else _progress_hooks(len(plan.steps))
|
|
434
|
+
with _json_safe() if as_json else nullcontext():
|
|
435
|
+
run = apply_exec.execute(plan, by_key.get, on_start=hooks[0], on_done=hooks[1])
|
|
436
|
+
# The verdict is a fresh reading of the machine (SD-3), not the steps' own say-so. No
|
|
437
|
+
# cache can be stale here: `perform` forgets every memoised probe after each step.
|
|
438
|
+
final = profile.sort_diff_rows(
|
|
439
|
+
profile.compare(wanted, snapshot.machine_facts(wanted, tools))
|
|
440
|
+
)
|
|
441
|
+
|
|
442
|
+
if as_json:
|
|
443
|
+
click.echo(json.dumps(_document(plan, run, final), indent=2))
|
|
444
|
+
else:
|
|
445
|
+
_summarize(wanted, run, final, profile_file)
|
|
446
|
+
|
|
447
|
+
if profile.differs(final, ignore_extras=True):
|
|
448
|
+
sys.exit(1)
|
|
449
|
+
|
|
450
|
+
|
|
451
|
+
def _document(
|
|
452
|
+
plan: apply_plan.Plan, run: apply_exec.RunResult | None, rows: list[DiffRow]
|
|
453
|
+
) -> dict[str, object]:
|
|
454
|
+
return {
|
|
455
|
+
"plan": plan.to_json(),
|
|
456
|
+
"run": run.to_json() if run is not None else None,
|
|
457
|
+
"rows": [r.to_json() for r in rows],
|
|
458
|
+
}
|
dev_setup/generic.py
CHANGED
|
@@ -447,6 +447,10 @@ def _check_update_npm(tool: GenericTool) -> UpdateStatus:
|
|
|
447
447
|
|
|
448
448
|
_T = TypeVar("_T")
|
|
449
449
|
|
|
450
|
+
# Every `_once` probe, so `forget_probes` can drop them all without a list that has to be kept in
|
|
451
|
+
# step with the decorators by hand.
|
|
452
|
+
_MEMOS: list[Callable[[], object]] = []
|
|
453
|
+
|
|
450
454
|
|
|
451
455
|
def _once(fn: Callable[[], _T]) -> Callable[[], _T]:
|
|
452
456
|
"""Memoise a no-argument probe so concurrent first callers wait instead of racing.
|
|
@@ -457,8 +461,10 @@ def _once(fn: Callable[[], _T]) -> Callable[[], _T]:
|
|
|
457
461
|
per uv tool rather than one per run (docs/specs/outdated, finding F-1).
|
|
458
462
|
|
|
459
463
|
The answer is fixed for the life of the process, so nothing here may be called after
|
|
460
|
-
something that changes it (an install or update) and expected to see the change
|
|
461
|
-
|
|
464
|
+
something that changes it (an install or update) and expected to see the change. A
|
|
465
|
+
caller that changes the machine and then reads it again calls `forget_probes()` between
|
|
466
|
+
the two (docs/specs/profile-apply, finding F-4: an install succeeded and the memo kept
|
|
467
|
+
reporting the tool as absent).
|
|
462
468
|
"""
|
|
463
469
|
lock = threading.Lock()
|
|
464
470
|
box: list[_T] = []
|
|
@@ -475,9 +481,20 @@ def _once(fn: Callable[[], _T]) -> Callable[[], _T]:
|
|
|
475
481
|
box.clear()
|
|
476
482
|
|
|
477
483
|
wrapper.cache_clear = cache_clear # type: ignore[attr-defined]
|
|
484
|
+
_MEMOS.append(wrapper)
|
|
478
485
|
return wrapper
|
|
479
486
|
|
|
480
487
|
|
|
488
|
+
def forget_probes() -> None:
|
|
489
|
+
"""Drop every memoised probe, so the next read of the machine is a fresh one.
|
|
490
|
+
|
|
491
|
+
Call it after anything that installs, updates or removes a tool and before reading state
|
|
492
|
+
that the change could have affected.
|
|
493
|
+
"""
|
|
494
|
+
for memo in _MEMOS:
|
|
495
|
+
memo.cache_clear() # type: ignore[attr-defined]
|
|
496
|
+
|
|
497
|
+
|
|
481
498
|
class _Answer(NamedTuple):
|
|
482
499
|
"""What a shared probe learned: its data, or None plus the reason it couldn't answer."""
|
|
483
500
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: devstuff
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.13.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>
|
|
@@ -374,19 +374,20 @@ includes the `unsupported` rows; `--updates-only` applies to it too.
|
|
|
374
374
|
|
|
375
375
|
### `profile`
|
|
376
376
|
|
|
377
|
-
Describe which tools a machine should have as a small file,
|
|
378
|
-
|
|
379
|
-
they work offline.
|
|
377
|
+
Describe which tools a machine should have as a small file, compare a machine against one, and make
|
|
378
|
+
a machine match one. `snapshot` and `diff` are **read-only** and **local** — they ask the machine,
|
|
379
|
+
never the network — so they work offline; `apply` installs, so it needs the network for that.
|
|
380
380
|
|
|
381
381
|
```bash
|
|
382
382
|
devstuff profile snapshot > work.yaml # the tools installed here, as a file
|
|
383
383
|
devstuff profile snapshot --versions -o work.yaml # ...and the versions of the ones that can be pinned
|
|
384
384
|
devstuff profile diff work.yaml # how this machine differs from the file
|
|
385
385
|
devstuff profile diff work.yaml --exit-code # exit 1 if it differs: a gate for CI
|
|
386
|
+
devstuff profile apply work.yaml # install what's missing, then check it worked
|
|
387
|
+
devstuff profile apply @devops --dry-run # a profile that ships with devstuff
|
|
386
388
|
```
|
|
387
389
|
|
|
388
|
-
>
|
|
389
|
-
> breaking change will bump that number. There is no `apply` yet — nothing here installs anything.
|
|
390
|
+
> The file format is `version: 1`; a later breaking change will bump that number.
|
|
390
391
|
|
|
391
392
|
A profile names catalog **keys**, and optionally a version. It never contains an install script or
|
|
392
393
|
a tool definition, so a profile from somewhere else can't run anything your own catalog doesn't
|
|
@@ -474,6 +475,68 @@ you also pass `--ignore-extras`, which affects only this exit status and never h
|
|
|
474
475
|
difference. A profile that is missing, unreadable or invalid is always `2`, so `1` can only ever
|
|
475
476
|
mean "differs".
|
|
476
477
|
|
|
478
|
+
#### `apply`
|
|
479
|
+
|
|
480
|
+
Makes this machine match a profile: installs what is missing (with whatever it needs, in order)
|
|
481
|
+
and moves pinned tools to the pinned version. **It never removes anything**, and it never touches a
|
|
482
|
+
tool the profile doesn't pin.
|
|
483
|
+
|
|
484
|
+
```bash
|
|
485
|
+
devstuff profile apply work.yaml --dry-run # show the plan; change nothing, ask nothing
|
|
486
|
+
devstuff profile apply work.yaml # show the plan, ask, then run it
|
|
487
|
+
devstuff profile apply work.yaml --yes # no question (needed with no terminal)
|
|
488
|
+
devstuff profile apply work.yaml --missing-only # install what's missing; leave version drift alone
|
|
489
|
+
devstuff profile apply work.yaml --yes --json # one JSON document on stdout, nothing else
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
The plan is worked out from the same comparison `diff` makes, so the two can't disagree about what
|
|
493
|
+
"missing" means. A pinned tool that isn't installed is installed **at the pin in one step**, not
|
|
494
|
+
installed at latest and then moved. A pin the tool's install type can't honour (`bash`, `script`,
|
|
495
|
+
`git`) is **skipped with a reason**, never installed at latest in its place.
|
|
496
|
+
|
|
497
|
+
- **A failure doesn't stop the run.** What needed the failed tool is skipped, with the reason, and
|
|
498
|
+
never attempted; everything else carries on.
|
|
499
|
+
- **The result is a re-reading of the machine**, not a tally of installers that didn't raise. An
|
|
500
|
+
installer that "succeeds" without installing anything is reported as the failure it is.
|
|
501
|
+
- **Run it again to resume.** A second `apply` finds nothing to do once the machine matches, so an
|
|
502
|
+
interrupted (`Ctrl-C`) or partly failed run is finished by running the same command.
|
|
503
|
+
- **`apt` pins older than the available version usually fail** — the package's libraries are
|
|
504
|
+
version-locked to it. `apply` tries it and shows apt's own error rather than forcing the install.
|
|
505
|
+
- If a tool installed fine but still reads `missing`, check that its bin directory (usually
|
|
506
|
+
`~/.local/bin`) is on `PATH` in the shell that ran `apply`; `apply` says so under the summary.
|
|
507
|
+
|
|
508
|
+
| Exit | Meaning |
|
|
509
|
+
|------|---------|
|
|
510
|
+
| `0` | Every entry in the profile now matches. |
|
|
511
|
+
| `1` | Something doesn't: a step failed or was skipped, an entry couldn't be acted on, drift is left by `--missing-only`, or you declined or interrupted. |
|
|
512
|
+
| `2` | The profile is unreadable or invalid, or the run needs confirming and there is no terminal (add `--yes`). |
|
|
513
|
+
|
|
514
|
+
With `--json` the document is `{"plan", "run", "rows"}` (`run` is `null` for `--dry-run` or when
|
|
515
|
+
there was nothing to do), `--yes` or `--dry-run` is required, and `-v` has no effect.
|
|
516
|
+
|
|
517
|
+
#### Bundled profiles
|
|
518
|
+
|
|
519
|
+
`PROFILE` can be `@name` for a profile that ships with devstuff, for both `apply` and `diff`:
|
|
520
|
+
|
|
521
|
+
```bash
|
|
522
|
+
devstuff profile apply @devops --dry-run
|
|
523
|
+
devstuff profile diff @essentials
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
| Bundle | Tools |
|
|
527
|
+
|--------|-------|
|
|
528
|
+
| `@essentials` | gh, git-lfs, lazygit, bat, htop, yq, starship, nerd-font |
|
|
529
|
+
| `@python` | uv, python, ipython, pre-commit, commitizen |
|
|
530
|
+
| `@devops` | docker, ansible, ansible-vault, aws, saml2aws, mkcert |
|
|
531
|
+
| `@languages` | go, java, php, python, ruby |
|
|
532
|
+
| `@ai-agents` | claude-code, codex, devin, hey-dave, pi |
|
|
533
|
+
| `@ai-local` | ollama, lmstudio, llm-checker, llamactl |
|
|
534
|
+
|
|
535
|
+
Bundles pin nothing, so each installs the latest. `docker`, `java`, `php` and `ruby` ask for sudo.
|
|
536
|
+
Only a leading `@` marks a bundle; a file whose name starts with `@` is `./@name`. An unknown name
|
|
537
|
+
is exit 2 and lists these. The files are plain profiles in `src/dev_setup/bundles/` — copy one out
|
|
538
|
+
and edit it to make your own.
|
|
539
|
+
|
|
477
540
|
---
|
|
478
541
|
|
|
479
542
|
### `configure`
|
|
@@ -2,7 +2,10 @@ dev_setup/__init__.py,sha256=BfTc-iAf16B_sxLK1PM3P7QlMGy7k33ColMK0o6KkdA,158
|
|
|
2
2
|
dev_setup/__main__.py,sha256=w-Vnqe3bgAw_UNlPywPkbOqoFKcEk2H2S79wrQjXvU4,102
|
|
3
3
|
dev_setup/agent_tools.schema.json,sha256=veXnih00xW4w9yK3ruWz-npUrCnJmcQpQdFvfcu7v_I,4928
|
|
4
4
|
dev_setup/agent_tools.yaml,sha256=56E70B1W7hBqjGhYhhCAGzFQvi1nUZ04cnNiqZlMjyY,4506
|
|
5
|
+
dev_setup/apply_exec.py,sha256=czzQxxYHWCAmAsgd9BvMPYlG2b63g0b3RHbbO5UyPRA,6364
|
|
6
|
+
dev_setup/apply_plan.py,sha256=L_ZmSGnjM7T1hKT7RLXSvCZgjbRpX_AaTKg5N9fp1zs,8474
|
|
5
7
|
dev_setup/base.py,sha256=j2EQ5gzeGgtveWQN_BgbLcZianMENJ7PQy8EQ9J9MPE,1946
|
|
8
|
+
dev_setup/bundles.py,sha256=h-WdjwNI82SQCgXiJ-EoiwuI81umb09Q0NNUYyzH1FI,2285
|
|
6
9
|
dev_setup/catalog.py,sha256=PrimTBUYoh8cW9QYhXUxP8qSMeK51kzQjUoPEGD9EBw,6530
|
|
7
10
|
dev_setup/cli.py,sha256=M4si1b2yZ44Y3zfdwF-D0v__ZhDnemLl8vLrFKonWDg,3320
|
|
8
11
|
dev_setup/doctor.py,sha256=1shwNLT5wFxiGT5oBVqbF478B7lcHVwT_e50aFb2I20,16962
|
|
@@ -11,7 +14,7 @@ dev_setup/functions.schema.json,sha256=VVdpH3xWsdbtqw47S1QqpBcs4O9wd3XZ_s0Q3sGwv
|
|
|
11
14
|
dev_setup/functions.yaml,sha256=n3yn8N9FN9TzMRMMgYREmDACUAsO1XmGDuNB-aOVl8U,13477
|
|
12
15
|
dev_setup/functions_catalog.py,sha256=YgR2hY9HM1iol1AZcF-_j02EXCP9U4P3e_5eWes9KH0,7116
|
|
13
16
|
dev_setup/functions_registry.py,sha256=YSl-VgNXPf0hj4WgReg-pZUj4fAjFlwvC165dgon_BE,3682
|
|
14
|
-
dev_setup/generic.py,sha256=
|
|
17
|
+
dev_setup/generic.py,sha256=Etu9yMBwPcRFjKuGiBxJ91mCDAwNnlUf3t6S1ZVzaz0,35817
|
|
15
18
|
dev_setup/links.schema.json,sha256=V9_1UA8Ejfu0j6-VczH0blW1mlGupXx56NhApLtHHKc,1938
|
|
16
19
|
dev_setup/links.yaml,sha256=t3-_cbCzA6PqnjZDIe3-zgCiyyFo7AcUS3Aj2Y15XGw,3417
|
|
17
20
|
dev_setup/links_catalog.py,sha256=Xe7s9oqiCrfQPUwE-X9o6p5VkU7mH9PjY9NMyn6VbHg,4610
|
|
@@ -38,6 +41,12 @@ dev_setup/agent/sandbox.py,sha256=wS_9kwc6r0spKSX8CBJFDkhWSiVG60D8dCKBrKbVnYA,10
|
|
|
38
41
|
dev_setup/agent/session.py,sha256=1UB0Mxz-cflDHqOfj1PFzufb1yz1ECbcObXIPubZfMU,12654
|
|
39
42
|
dev_setup/agent/transcript.py,sha256=hJQuSLriAe5hvnD3SCMqOWduuYtblyhmqzZQ3jDco1Y,1868
|
|
40
43
|
dev_setup/agent/wizard.py,sha256=p0vHiJ-palTMoL6p7zQscL01laBFKw9f5HHY1yemZ4w,4056
|
|
44
|
+
dev_setup/bundles/ai-agents.yaml,sha256=sLyZSjAVj41CYfan1rDGUtRRjCW9-WKtU_7RkPjfqnc,323
|
|
45
|
+
dev_setup/bundles/ai-local.yaml,sha256=-u6H2OJWxh7_52pHsDZcQmoUFjLj69pkKGEovLAxmd8,359
|
|
46
|
+
dev_setup/bundles/devops.yaml,sha256=hHtBZQRRqVEDsCVmaBGDCt0bDAylzQWY4OZEjqNUD38,401
|
|
47
|
+
dev_setup/bundles/essentials.yaml,sha256=1ZknxCpzmAK9SKKWyl8qULACQqY857mX9oDYXXCHBAI,498
|
|
48
|
+
dev_setup/bundles/languages.yaml,sha256=xqbMP-X4uCOHI-tyEVsCEADHq1C8iS4afIkmSrNEn7g,439
|
|
49
|
+
dev_setup/bundles/python.yaml,sha256=QO4A2xGWnAtSRwOHHf0rwle219grab9iu5_C8I8sBsg,333
|
|
41
50
|
dev_setup/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
42
51
|
dev_setup/commands/add_cmd.py,sha256=BEPaSqdhDgP_mev4-WqYhqA31tUfhhfBj-68qG6xoJE,12283
|
|
43
52
|
dev_setup/commands/agent_cmd.py,sha256=TtsCzNVXgwxS2ACFLFl6ibnjoohEQWXgM2rfWkBnKk0,5128
|
|
@@ -47,12 +56,12 @@ dev_setup/commands/delete_cmd.py,sha256=j_-fr2RMaeX3sMhH-7wJP5KC9Yvpgbb9KIeEEyG9
|
|
|
47
56
|
dev_setup/commands/docs_cmd.py,sha256=JXhusKUl4dD-U5jG-PLTon_2NCpAWWnaBqsmlFk7vLY,971
|
|
48
57
|
dev_setup/commands/doctor_cmd.py,sha256=sPhxLMVxy1JOxdFklRQHIwCoJeB-nmGWzVs5yeza9a8,3568
|
|
49
58
|
dev_setup/commands/functions_cmd.py,sha256=4HvdLXle9JGk70A1EDVZrlgTo-N-FyAO7ApaL8mcJYI,3023
|
|
50
|
-
dev_setup/commands/help_cmd.py,sha256=
|
|
59
|
+
dev_setup/commands/help_cmd.py,sha256=O2dnhqsMZx5tVHdJVixixCJwc9TYlKdlZ2vYYPApl0o,4566
|
|
51
60
|
dev_setup/commands/install_cmd.py,sha256=0mUEdZQWPgXuK4_5aVhGZOadQYM1JhFZjl-biRHjSf4,4610
|
|
52
61
|
dev_setup/commands/links_cmd.py,sha256=kvnoBXdM9QWRZRIwWgnmWqVkOYE7AZxywFTQD5_Uwv4,4924
|
|
53
62
|
dev_setup/commands/list_cmd.py,sha256=Env6bwAmREDek4L-ZB2CIfvLT4PgaKcz5sQKJ1GhL8g,2913
|
|
54
63
|
dev_setup/commands/outdated_cmd.py,sha256=YljnMw-KZd1jcZO5FEce3H6nrX1MnWOt0fRBSAdlpQE,5070
|
|
55
|
-
dev_setup/commands/profile_cmd.py,sha256=
|
|
64
|
+
dev_setup/commands/profile_cmd.py,sha256=jo7al_nBwuWtzOLYKjcqEGmHp4eQrzM5s7ahv6iiGaw,18299
|
|
56
65
|
dev_setup/commands/remove_cmd.py,sha256=_KqCa2S9fQFngLUs_OpBzjkIkFKgDtKup4gQ5TqLrVI,1239
|
|
57
66
|
dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
|
|
58
67
|
dev_setup/commands/skills_cmd.py,sha256=j4rleYEW4lt-O2ssDwGyhwmk2Wiip64C4Z7iPT6c3y0,7482
|
|
@@ -103,7 +112,7 @@ dev_setup/configure/starship/model.py,sha256=ct1YrR3xLqcKMP20TvKZQ0Oc-OxHMrRjnei
|
|
|
103
112
|
dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
|
|
104
113
|
dev_setup/configure/starship/render.py,sha256=25O8w4IteVd_ELwmIWhcYAn042W6yZ--zbTMcJpzVJc,11277
|
|
105
114
|
dev_setup/configure/starship/wizard.py,sha256=Q6aoKnz_n9WhFhTD4EygvaenZRsQTVwyZ1ga-cpUqBk,28620
|
|
106
|
-
devstuff-2.
|
|
107
|
-
devstuff-2.
|
|
108
|
-
devstuff-2.
|
|
109
|
-
devstuff-2.
|
|
115
|
+
devstuff-2.13.0.dist-info/METADATA,sha256=Fc3SR7I7D-h0lvqDC5Hq9TvamBhBYxpLbtkEjUxHF-w,91936
|
|
116
|
+
devstuff-2.13.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
117
|
+
devstuff-2.13.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
|
|
118
|
+
devstuff-2.13.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|