devstuff 2.13.0__py3-none-any.whl → 2.15.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.
@@ -1,5 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
+ import json
3
4
  import subprocess
4
5
  from collections.abc import Callable
5
6
  from typing import Any
@@ -58,6 +59,69 @@ def tool_info(ws: Workspace, config: AgentConfig, args: dict[str, Any]) -> str:
58
59
  return "\n".join(lines)
59
60
 
60
61
 
62
+ def _string_list(args: dict[str, Any], name: str) -> list[str]:
63
+ """A list-of-strings argument. `bind()` checks names, not types, so this is the type check."""
64
+ value = args.get(name, [])
65
+ if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
66
+ # A bare string must be refused, not iterated: "eslint" would read as six one-letter keys.
67
+ raise SandboxError(f"'{name}' must be a list of strings, e.g. [\"uv\", \"nvm\"]")
68
+ return value
69
+
70
+
71
+ def outdated(ws: Workspace, config: AgentConfig, args: dict[str, Any]) -> str:
72
+ """`devstuff outdated --json`: the same rows, built by the same function (spec FR-9).
73
+
74
+ `unknown` and `unsupported` rows are returned as such and never as `current` -- that honesty
75
+ is the point of the command, and it is decided in `updates.classify`, not here.
76
+ """
77
+ from dev_setup.updates import State, build_rows
78
+
79
+ updates_only = args.get("updates_only", False)
80
+ if not isinstance(updates_only, bool):
81
+ raise SandboxError("'updates_only' must be true or false")
82
+
83
+ keys = _string_list(args, "packages")
84
+ tool_registry.init()
85
+ named = None
86
+ if keys:
87
+ named = []
88
+ for key in keys:
89
+ tool = tool_registry.get(key)
90
+ if tool is None:
91
+ raise SandboxError(f"unknown catalog tool '{key}'; try search_catalog first")
92
+ named.append(tool)
93
+
94
+ rows = build_rows(named)
95
+ if updates_only:
96
+ rows = [r for r in rows if r.state is State.OUTDATED]
97
+ return json.dumps([r.to_json() for r in rows], indent=2)
98
+
99
+
100
+ def profile_diff(ws: Workspace, config: AgentConfig, args: dict[str, Any]) -> str:
101
+ """`devstuff profile diff @name --json`, for a bundle that ships with devstuff (spec FR-10).
102
+
103
+ Only a bundle name is accepted. A path would let a caller read any YAML file the user can read,
104
+ and `bundles.resolve` matches the name against a directory listing rather than building a path
105
+ from it, so there is nothing to traverse.
106
+ """
107
+ from dev_setup import bundles, profile, snapshot
108
+
109
+ name = args["profile"]
110
+ if not isinstance(name, str) or not bundles.is_bundle(name):
111
+ raise SandboxError(
112
+ f"'profile' must be a bundle name such as @devops, not a file path. "
113
+ f"Bundles: {', '.join(f'@{n}' for n in bundles.names())}"
114
+ )
115
+ try:
116
+ wanted = bundles.resolve(name)
117
+ except profile.ProfileError as exc:
118
+ raise SandboxError(str(exc)) from exc
119
+
120
+ tool_registry.init()
121
+ rows = profile.sort_diff_rows(profile.compare(wanted, snapshot.machine_facts(wanted)))
122
+ return json.dumps([r.to_json() for r in rows], indent=2)
123
+
124
+
61
125
  def install_tool(ws: Workspace, config: AgentConfig, args: dict[str, Any]) -> str:
62
126
  tool_registry.init()
63
127
  tool = tool_registry.get(args["key"])
@@ -117,6 +181,8 @@ _BRIDGES: dict[str, Bridge] = {
117
181
  "list_tools": list_tools,
118
182
  "search_catalog": search_catalog,
119
183
  "tool_info": tool_info,
184
+ "outdated": outdated,
185
+ "profile_diff": profile_diff,
120
186
  "install_tool": install_tool,
121
187
  }
122
188
 
@@ -17,7 +17,7 @@ VERSION = 1
17
17
  VALID_KEY = re.compile(r"^[a-z][a-z0-9_]*$")
18
18
 
19
19
  IMPLS = {"primitive", "catalog", "function"}
20
- PARAM_TYPES = {"string", "integer", "number", "boolean"}
20
+ PARAM_TYPES = {"string", "integer", "number", "boolean", "array"}
21
21
 
22
22
  SUPPORTED_TOP_FIELDS = {"version", "expose_functions", "exclude_functions", "tools"}
23
23
  SUPPORTED_FIELDS = {"name", "description", "impl", "target", "mutating", "params"}
@@ -17,6 +17,10 @@ class AgentParam:
17
17
 
18
18
  def to_schema(self) -> dict[str, Any]:
19
19
  schema: dict[str, Any] = {"type": self.type}
20
+ if self.type == "array":
21
+ # JSON Schema wants `items`, and a bare array tells a model nothing about what goes
22
+ # in it. Every array parameter is a list of strings: none needs another element type.
23
+ schema["items"] = {"type": "string"}
20
24
  if self.description:
21
25
  schema["description"] = self.description
22
26
  if self.enum:
@@ -86,7 +86,7 @@
86
86
  "description": "Parameter name. Passed to the implementation as a dict key."
87
87
  },
88
88
  "type": {
89
- "enum": ["string", "integer", "number", "boolean"],
89
+ "enum": ["string", "integer", "number", "boolean", "array"],
90
90
  "default": "string",
91
91
  "description": "JSON Schema type advertised to the model."
92
92
  },
@@ -129,6 +129,43 @@ tools:
129
129
  description: Catalog key, e.g. "uv" or "nvm".
130
130
  required: true
131
131
 
132
+ outdated:
133
+ name: Devstuff Outdated
134
+ description: >-
135
+ Report which installed devstuff tools have a newer version available. Returns a
136
+ JSON array with one row per tool: state is "outdated", "current", "unknown" (a
137
+ check exists but could not answer, e.g. offline), "unsupported" (this install
138
+ type has no way to check) or "not-installed". Only "current" means up to date --
139
+ never read "unknown" or "unsupported" as current. Changes nothing.
140
+ impl: catalog
141
+ target: outdated
142
+ mutating: false
143
+ params:
144
+ - name: packages
145
+ type: array
146
+ description: Catalog keys to check, e.g. ["uv", "nvm"]. Omit to check every installed tool.
147
+ required: false
148
+ - name: updates_only
149
+ type: boolean
150
+ description: Return only the tools that have an update available.
151
+ required: false
152
+ default: false
153
+
154
+ profile_diff:
155
+ name: Devstuff Profile Diff
156
+ description: >-
157
+ Compare this machine to a profile that ships with devstuff and return a JSON array,
158
+ one row per tool: "ok", "missing", "drift", "unverifiable", "unpinnable",
159
+ "unknown-key" or "extra". Only "ok" means it matches. Changes nothing.
160
+ impl: catalog
161
+ target: profile_diff
162
+ mutating: false
163
+ params:
164
+ - name: profile
165
+ type: string
166
+ description: Name of a bundled profile, with the leading @, e.g. "@devops" or "@python".
167
+ required: true
168
+
132
169
  install_tool:
133
170
  name: Install Devstuff Tool
134
171
  description: >-
@@ -0,0 +1,26 @@
1
+ """Shared plan-preview helpers for install/remove/update commands."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dev_setup.base import Tool
6
+
7
+
8
+ def plan_for(tool: Tool, action: str, version: str | None = None) -> list:
9
+ """The tool's resolved plan items, or a generic note for non-GenericTool entries."""
10
+ planner = getattr(tool, "plan_items", None)
11
+ if planner is None:
12
+ return [("note", "", f"{action} {tool.key}")]
13
+ return planner(action, version)
14
+
15
+
16
+ def plan_summary(tool: Tool, action: str, version: str | None = None) -> str:
17
+ """One-line digest of a tool's plan for the batch preview table."""
18
+ parts = []
19
+ for kind, _label, detail in plan_for(tool, action, version):
20
+ if kind == "cmd":
21
+ parts.append(detail)
22
+ elif kind == "script":
23
+ parts.append("runs a script")
24
+ else:
25
+ parts.append(detail)
26
+ return "; ".join(parts)
@@ -25,139 +25,188 @@ set -euo pipefail
25
25
 
26
26
  """
27
27
 
28
+ _TYPES = ["npm", "uvx", "apt", "git", "script", "bash"]
29
+
30
+ # Catalog fields collected per type — filters out answers left over from a type
31
+ # the user backed out of and changed.
32
+ _TYPE_FIELDS = {
33
+ "npm": ["npm_name", "check_cmd"],
34
+ "uvx": ["pip_name", "check_cmd", "uv_executables_from", "uv_with", "uv_python"],
35
+ "apt": ["apt_packages", "check_cmd"],
36
+ "git": ["git_url", "git_install_cmd", "git_remove_cmd", "check_cmd"],
37
+ "script": ["script_url", "check_cmd"],
38
+ "bash": ["check_cmd", "install_script", "remove_script"],
39
+ }
40
+ _COMMON_FIELDS = ["help_cmd", "docs_url"]
41
+
28
42
 
29
43
  @click.command("add")
30
44
  def add_cmd() -> None:
31
45
  """Add a custom package via guided wizard."""
32
46
  ui.section("Add Custom Package")
33
47
 
34
- install_type = ui.select(
35
- "Package type:",
36
- ["npm", "uvx", "apt", "git", "script", "bash"],
37
- )
38
- if not install_type:
48
+ answers = ui.Wizard("Add package").run(_steps())
49
+ if answers is None:
39
50
  ui.warn("Aborted.")
40
51
  return
41
52
 
42
- key = _prompt_key()
43
- if not key:
44
- return
45
-
46
- name = ui.text_input("Display name:", default=key, required=True)
47
- description = ui.text_input("Short description:", required=False)
48
-
53
+ install_type = answers["type"]
49
54
  kwargs: dict = dict(
50
- key=key,
51
- name=name,
52
- description=description,
55
+ key=answers["key"],
56
+ name=answers["name"],
57
+ description=answers.get("description", ""),
53
58
  category="custom",
54
59
  install_type=install_type,
55
60
  )
56
-
57
- if install_type == "npm":
58
- kwargs["npm_name"] = ui.text_input("npm package name:", default=key, required=True)
59
- kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
60
-
61
- elif install_type == "uvx":
62
- kwargs["pip_name"] = ui.text_input("PyPI package name:", default=key, required=True)
63
- kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
64
- # All optional. Empty answers must not write empty keys into the user catalog.
65
- exes = ui.text_input(
66
- "Also expose executables from (space-separated packages, blank for none):"
67
- )
68
- if exes:
69
- kwargs["uv_executables_from"] = exes.split()
70
- extra = ui.text_input(
71
- "Extra packages to install alongside it (space-separated, blank for none):"
72
- )
73
- if extra:
74
- kwargs["uv_with"] = extra.split()
75
- py = ui.text_input("Pin to a Python version (e.g. 3.12, blank for uv's default):")
76
- if py:
77
- kwargs["uv_python"] = py
78
-
79
- elif install_type == "apt":
80
- kwargs["apt_packages"] = ui.text_input(
81
- "apt package(s) (space-separated):", default=key, required=True
82
- )
83
- kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
84
-
85
- elif install_type == "git":
86
- kwargs["git_url"] = ui.text_input("Git repository URL:", required=True)
87
- kwargs["git_install_cmd"] = ui.text_input(
88
- "Post-clone install command (optional, run inside repo):", required=False
89
- )
90
- kwargs["git_remove_cmd"] = ui.text_input(
91
- "Pre-delete remove command (optional):", required=False
92
- )
93
- kwargs["check_cmd"] = ui.text_input("Command to check if installed:", required=False)
94
-
95
- elif install_type == "script":
96
- kwargs["script_url"] = ui.text_input("Install script URL (curl | sh):", required=True)
97
- kwargs["check_cmd"] = ui.text_input("Command to check if installed:", required=False)
98
-
99
- elif install_type == "bash":
100
- kwargs["check_cmd"] = ui.text_input(
101
- "Command to verify installation (e.g. bat, aws):", required=False
102
- )
103
- install_script = _edit_script("install", name, required=True)
104
- if install_script is None:
105
- ui.warn("No install script provided — aborted.")
106
- return
107
- kwargs["install_script"] = install_script
108
-
109
- remove_script = _edit_script("remove", name, required=False)
110
- remove_script = _validate_remove_script(
111
- remove_script or "",
112
- install_script,
113
- kwargs.get("check_cmd", ""),
114
- name,
115
- )
116
- if remove_script:
117
- kwargs["remove_script"] = remove_script
118
-
119
- kwargs["help_cmd"] = ui.text_input(
120
- "Help command (optional, e.g. tool --help):", required=False
121
- )
122
- kwargs["docs_url"] = ui.text_input(
123
- "Documentation URL (optional):", required=False
124
- )
125
-
126
- ui.console.print()
127
- ui.heading("Summary")
128
- for k, v in kwargs.items():
129
- if v:
130
- display = _truncate_script(v) if k.endswith("_script") else v
131
- ui.console.print(f" [{ui.PURPLE}]{k:<18}[/] {display}")
132
- ui.console.print()
133
-
134
- if not ui.confirm("Save this package?"):
135
- ui.warn("Aborted — package not saved.")
136
- return
61
+ for field in _TYPE_FIELDS.get(install_type, []) + _COMMON_FIELDS:
62
+ if answers.get(field):
63
+ kwargs[field] = answers[field]
137
64
 
138
65
  tool = GenericTool(**kwargs)
139
66
  tool.save()
140
-
141
- from dev_setup import registry
142
67
  registry.register(tool)
143
68
 
144
- ui.success(f"Package '{key}' added. Install with: devstuff install {key}")
69
+ ui.success(f"Package '{tool.key}' added. Install with: devstuff install {tool.key}")
70
+
71
+
72
+ def _steps() -> list[ui.Step]:
73
+ def is_type(*types: str):
74
+ return lambda a: a.get("type") in types
75
+
76
+ def text(key: str, label: str, prompt: str, *, required: bool = False,
77
+ default=None, when=None, split: bool = False) -> ui.Step:
78
+ def ask(a: dict):
79
+ dflt = a.get(key) or (default(a) if default else "")
80
+ if isinstance(dflt, list):
81
+ dflt = " ".join(dflt)
82
+ val = ui.text_input_back(prompt, default=dflt, required=required)
83
+ if val is ui.BACK:
84
+ return ui.BACK
85
+ return val.split() if split and val else val
86
+
87
+ return ui.Step(key, label, ask, when=when)
88
+
89
+ return [
90
+ ui.Step(
91
+ "type", "package type",
92
+ lambda a: ui.select_back("Package type:", _TYPES, default=a.get("type")),
93
+ ),
94
+ ui.Step("key", "package key", _ask_key),
95
+ text(
96
+ "name", "display name", "Display name:", required=True,
97
+ default=lambda a: a.get("key", ""),
98
+ ),
99
+ text("description", "description", "Short description:"),
100
+ # npm
101
+ text(
102
+ "npm_name", "npm package", "npm package name:", required=True,
103
+ default=lambda a: a.get("key", ""), when=is_type("npm"),
104
+ ),
105
+ # uvx
106
+ text(
107
+ "pip_name", "PyPI package", "PyPI package name:", required=True,
108
+ default=lambda a: a.get("key", ""), when=is_type("uvx"),
109
+ ),
110
+ text(
111
+ "uv_executables_from", "executables from",
112
+ "Also expose executables from (space-separated packages, blank for none):",
113
+ when=is_type("uvx"), split=True,
114
+ ),
115
+ text(
116
+ "uv_with", "extra packages",
117
+ "Extra packages to install alongside it (space-separated, blank for none):",
118
+ when=is_type("uvx"), split=True,
119
+ ),
120
+ text(
121
+ "uv_python", "python pin",
122
+ "Pin to a Python version (e.g. 3.12, blank for uv's default):",
123
+ when=is_type("uvx"),
124
+ ),
125
+ # apt
126
+ text(
127
+ "apt_packages", "apt packages", "apt package(s) (space-separated):",
128
+ required=True, default=lambda a: a.get("key", ""), when=is_type("apt"),
129
+ ),
130
+ # git
131
+ text("git_url", "repo URL", "Git repository URL:", required=True, when=is_type("git")),
132
+ text(
133
+ "git_install_cmd", "install command",
134
+ "Post-clone install command (optional, run inside repo):",
135
+ when=is_type("git"),
136
+ ),
137
+ text(
138
+ "git_remove_cmd", "remove command",
139
+ "Pre-delete remove command (optional):", when=is_type("git"),
140
+ ),
141
+ # script
142
+ text(
143
+ "script_url", "script URL", "Install script URL (curl | sh):",
144
+ required=True, when=is_type("script"),
145
+ ),
146
+ # every type collects check_cmd — required nowhere, defaulted to the key
147
+ # for the types where the binary name almost always matches
148
+ text(
149
+ "check_cmd", "check command", "Command to check if installed:",
150
+ default=lambda a: a.get("key", "") if a.get("type") in ("npm", "uvx", "apt") else "",
151
+ ),
152
+ # bash
153
+ ui.Step(
154
+ "install_script", "install script", _ask_install_script,
155
+ when=is_type("bash"), show=_show_script,
156
+ ),
157
+ ui.Step(
158
+ "remove_script", "remove script", _ask_remove_script,
159
+ when=is_type("bash"), show=_show_script,
160
+ ),
161
+ text("help_cmd", "help command", "Help command (optional, e.g. tool --help):"),
162
+ text("docs_url", "docs URL", "Documentation URL (optional):"),
163
+ ]
145
164
 
146
165
 
147
- def _prompt_key() -> str:
166
+ def _ask_key(answers: dict):
148
167
  while True:
149
- key = ui.text_input("Package key (lowercase, hyphens ok):", required=True)
168
+ key = ui.text_input_back(
169
+ "Package key (lowercase, hyphens ok):",
170
+ default=answers.get("key", ""),
171
+ required=True,
172
+ )
173
+ if key is ui.BACK:
174
+ return ui.BACK
150
175
  if not _VALID_KEY.match(key):
151
176
  ui.error("Key must be lowercase letters, digits, hyphens, or underscores.")
152
177
  continue
153
178
  if registry.exists(key):
154
179
  ui.error(f"A package with key '{key}' already exists.")
155
- if not ui.confirm("Use a different key?"):
156
- return ""
157
180
  continue
158
181
  return key
159
182
 
160
183
 
184
+ def _ask_install_script(answers: dict):
185
+ script = _edit_script("install", answers.get("name", ""), required=True,
186
+ prefill=answers.get("install_script", ""))
187
+ if script is None:
188
+ ui.warn("No install script provided.")
189
+ return ui.BACK
190
+ return script
191
+
192
+
193
+ def _ask_remove_script(answers: dict):
194
+ script = _edit_script(
195
+ "remove", answers.get("name", ""), required=False,
196
+ prefill=answers.get("remove_script", ""),
197
+ )
198
+ return _validate_remove_script(
199
+ script or "",
200
+ answers.get("install_script", ""),
201
+ answers.get("check_cmd", ""),
202
+ answers.get("name", ""),
203
+ )
204
+
205
+
206
+ def _show_script(script) -> str:
207
+ return _truncate_script(str(script))
208
+
209
+
161
210
  def _edit_script(
162
211
  action: str,
163
212
  package_name: str,