devstuff 2.6.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
dev_setup/cli.py CHANGED
@@ -31,6 +31,7 @@ def _register_commands() -> None:
31
31
  from dev_setup.commands.doctor_cmd import doctor_cmd
32
32
  from dev_setup.commands.functions_cmd import functions_cmd
33
33
  from dev_setup.commands.install_cmd import install_cmd
34
+ from dev_setup.commands.links_cmd import links_cmd
34
35
  from dev_setup.commands.list_cmd import list_cmd
35
36
  from dev_setup.commands.remove_cmd import remove_cmd
36
37
  from dev_setup.commands.run_cmd import run_cmd
@@ -52,6 +53,8 @@ def _register_commands() -> None:
52
53
  cli.add_command(catalog_cmd, "catalog")
53
54
  cli.add_command(run_cmd, "run")
54
55
  cli.add_command(functions_cmd, "functions")
56
+ cli.add_command(links_cmd, "links")
57
+ cli.add_command(links_cmd, "link")
55
58
  cli.add_command(skills_cmd, "skills")
56
59
  cli.add_command(agent_cmd, "agent")
57
60
 
@@ -21,6 +21,7 @@ def print_help() -> None:
21
21
  ("docs", "<package>", "Open documentation in browser"),
22
22
  ("run", "<function> [args...]", "Run a function/script"),
23
23
  ("functions", "<list|enable|disable|path>", "Manage functions/scripts"),
24
+ ("links", "[list|search|open|path]", "Browse, search, and open tool links"),
24
25
  ("skills", "add", "Append GitHub skills to claude/codex/pi"),
25
26
  ("agent", "[--setup] [--dir] [--model]", "Chat with a local tool-using model"),
26
27
  ("version", "", "Show version"),
@@ -50,6 +51,8 @@ def print_help() -> None:
50
51
  "devstuff catalog export",
51
52
  "devstuff functions list",
52
53
  "devstuff functions enable ssh-agent-key",
54
+ "devstuff links search docker",
55
+ "devstuff links open uv-docs",
53
56
  "devstuff agent",
54
57
  "devstuff agent --setup",
55
58
  'devstuff agent --print "what node tools are available?"',
@@ -0,0 +1,141 @@
1
+ from __future__ import annotations
2
+
3
+ import sys
4
+ import webbrowser
5
+
6
+ import click
7
+ import questionary
8
+ from rich.markup import escape
9
+
10
+ from dev_setup import links_registry, ui
11
+ from dev_setup.links_catalog import USER_CATALOG_PATH
12
+ from dev_setup.links_registry import LinkDef
13
+
14
+
15
+ @click.group("links", invoke_without_command=True)
16
+ @click.pass_context
17
+ def links_cmd(ctx: click.Context) -> None:
18
+ """Browse, search, and open links to other tools' sites and docs."""
19
+ if ctx.invoked_subcommand is not None:
20
+ return
21
+ # A bare `devstuff links` is the "access the section" entry point: a type-to-filter
22
+ # picker when there is a terminal to drive it, the plain listing otherwise.
23
+ if sys.stdin.isatty() and sys.stdout.isatty():
24
+ _pick_and_open()
25
+ else:
26
+ ctx.invoke(list_cmd)
27
+
28
+
29
+ def _print_groups(links: list[LinkDef]) -> None:
30
+ by_cat: dict[str, list[LinkDef]] = {}
31
+ for link in links:
32
+ by_cat.setdefault(link.category, []).append(link)
33
+
34
+ key_width = max(len(link.key) for link in links) + 2
35
+ for cat in sorted(by_cat, key=lambda c: (c == "custom", c)):
36
+ ui.console.print(f"\n [bold]{cat.upper()}[/]")
37
+ for link in sorted(by_cat[cat], key=lambda link: link.key):
38
+ _print_row(link, key_width)
39
+ ui.console.print()
40
+
41
+
42
+ def _print_row(link: LinkDef, key_width: int, *, show_category: bool = False) -> None:
43
+ ui.console.print(f" [bold cyan]{link.key:<{key_width}}[/] {link.name}")
44
+ detail = link.description
45
+ if show_category:
46
+ detail = f"{detail} [{link.category}]" if detail else f"[{link.category}]"
47
+ if detail:
48
+ # escape(): "[category]" and any bracketed description text are valid Rich markup
49
+ ui.console.print(f" {'':<{key_width}} [dim]{escape(detail)}[/]")
50
+
51
+
52
+ @links_cmd.command("list")
53
+ @click.argument("category", required=False)
54
+ def list_cmd(category: str | None) -> None:
55
+ """List links, grouped by category."""
56
+ links = links_registry.all_links()
57
+ if category:
58
+ links = [link for link in links if link.category == category]
59
+ if not links:
60
+ ui.info("No links match." if category else "No links defined.")
61
+ return
62
+ _print_groups(links)
63
+ ui.dim("Open one with: devstuff links open <key>")
64
+
65
+
66
+ @links_cmd.command("search")
67
+ @click.argument("query", nargs=-1, required=True)
68
+ def search_cmd(query: tuple[str, ...]) -> None:
69
+ """Search links by title and description. Every word must match."""
70
+ text = " ".join(query)
71
+ matches = links_registry.search(text)
72
+ # "Found nothing" is a correct answer, so it exits 0 — non-zero is for failures.
73
+ if not matches:
74
+ ui.info(f"No links match '{text}'.")
75
+ return
76
+ ui.console.print(f"\n [bold]{len(matches)} match(es)[/] [dim]for '{escape(text)}'[/]")
77
+ key_width = max(len(link.key) for link in matches) + 2
78
+ for link in matches: # keep search rank order rather than re-sorting by key
79
+ _print_row(link, key_width, show_category=True)
80
+ ui.console.print()
81
+ ui.dim("Open one with: devstuff links open <key>")
82
+
83
+
84
+ @links_cmd.command("open")
85
+ @click.argument("key")
86
+ def open_cmd(key: str) -> None:
87
+ """Open a link in your browser."""
88
+ link = links_registry.get(key)
89
+ if link is None:
90
+ ui.error(f"Unknown link: '{key}'")
91
+ suggestions = [m.key for m in links_registry.search(key)][:5]
92
+ if suggestions:
93
+ ui.dim(f"Did you mean: {', '.join(suggestions)}")
94
+ ui.dim("See all links with: devstuff links list")
95
+ sys.exit(1)
96
+ _open(link)
97
+
98
+
99
+ @links_cmd.command("path")
100
+ def path_cmd() -> None:
101
+ """Print the path to the user links catalog."""
102
+ click.echo(str(USER_CATALOG_PATH))
103
+
104
+
105
+ def _open(link: LinkDef) -> None:
106
+ ui.console.print(f"\n [bold]{link.name}[/]")
107
+ if link.description:
108
+ ui.console.print(f" [dim]{escape(link.description)}[/]")
109
+ ui.console.print(f" [cyan underline link={link.url}]{link.url}[/]\n")
110
+
111
+ # webbrowser.open acts on the machine devstuff runs on: over SSH there is no browser
112
+ # to find, so the URL above is the fallback (terminals make it clickable).
113
+ if webbrowser.open(link.url):
114
+ ui.success("Opened in browser.")
115
+ else:
116
+ ui.warn("Could not open a browser — copy the URL above to open it manually.")
117
+ sys.exit(1)
118
+
119
+
120
+ def _pick_and_open() -> None:
121
+ links = sorted(
122
+ links_registry.all_links(),
123
+ key=lambda link: (link.category == "custom", link.category, link.key),
124
+ )
125
+ if not links:
126
+ ui.info("No links defined.")
127
+ return
128
+
129
+ ui.section("Links")
130
+ ui.dim("Type to filter, Enter to open.")
131
+ choices = [
132
+ questionary.Choice(
133
+ title=f"{link.name} · {link.category} · {link.description}",
134
+ value=link.key,
135
+ )
136
+ for link in links
137
+ ]
138
+ key = ui.select("Open which link?", choices, searchable=True)
139
+ link = links_registry.get(key)
140
+ if link is not None:
141
+ _open(link)
dev_setup/doctor.py CHANGED
@@ -150,6 +150,30 @@ def check_user_functions_catalog() -> CheckResult:
150
150
  )
151
151
 
152
152
 
153
+ def check_bundled_links_catalog() -> CheckResult:
154
+ """Bundled links.yaml loads and validates."""
155
+ from dev_setup import links_catalog as lc
156
+
157
+ try:
158
+ links = lc.load_bundled_catalog()
159
+ except lc.CatalogError as exc:
160
+ return CheckResult("bundled-links-catalog", FAIL, f"Bundled links.yaml invalid: {exc}")
161
+ return CheckResult("bundled-links-catalog", PASS, f"Bundled links.yaml valid ({len(links)} links)")
162
+
163
+
164
+ def check_user_links_catalog() -> CheckResult:
165
+ """User links.yaml (if present) loads and validates."""
166
+ from dev_setup import links_catalog as lc
167
+
168
+ if not lc.USER_CATALOG_PATH.exists():
169
+ return CheckResult("user-links-catalog", PASS, "No user links.yaml")
170
+ try:
171
+ links = lc.read_user_catalog()
172
+ except lc.CatalogError as exc:
173
+ return CheckResult("user-links-catalog", FAIL, f"User links.yaml invalid: {exc}")
174
+ return CheckResult("user-links-catalog", PASS, f"User links.yaml valid ({len(links)} links)")
175
+
176
+
153
177
  def check_bundled_agent_catalog() -> CheckResult:
154
178
  """Bundled agent_tools.yaml loads and validates."""
155
179
  from dev_setup.agent import catalog as ac
@@ -284,6 +308,8 @@ ALL_CHECKS: list[Callable[[], CheckResult]] = [
284
308
  check_user_tools_catalog,
285
309
  check_bundled_functions_catalog,
286
310
  check_user_functions_catalog,
311
+ check_bundled_links_catalog,
312
+ check_user_links_catalog,
287
313
  check_bundled_agent_catalog,
288
314
  check_user_agent_catalog,
289
315
  check_registry_loads,
@@ -0,0 +1,50 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "https://github.com/thesawdawg/dev-setup-py/links.schema.json",
4
+ "title": "devstuff links catalog",
5
+ "description": "Schema for links.yaml (bundled at src/dev_setup/links.yaml, user overrides at ~/.config/devstuff/links.yaml). Defines bookmarks to other tools' sites and docs, listed, searched, and opened via `devstuff links`. Mirrors the validation in links_catalog.py — keep both in sync.",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": ["version", "links"],
9
+ "properties": {
10
+ "version": {
11
+ "const": 1,
12
+ "description": "Catalog schema version. Currently always 1."
13
+ },
14
+ "links": {
15
+ "type": "object",
16
+ "description": "Map of link key -> link definition.",
17
+ "propertyNames": {
18
+ "pattern": "^[a-z0-9][a-z0-9_-]*$",
19
+ "description": "Lowercase letters, digits, hyphens, underscores; must start with a letter or digit."
20
+ },
21
+ "additionalProperties": { "$ref": "#/definitions/link" }
22
+ }
23
+ },
24
+ "definitions": {
25
+ "link": {
26
+ "type": "object",
27
+ "additionalProperties": false,
28
+ "required": ["url"],
29
+ "properties": {
30
+ "name": {
31
+ "type": "string",
32
+ "description": "Title shown in listings and matched by `links search`. Defaults to the catalog key."
33
+ },
34
+ "description": {
35
+ "type": "string",
36
+ "description": "Short description shown in listings and matched by `links search`. Defaults to an empty string."
37
+ },
38
+ "category": {
39
+ "type": "string",
40
+ "description": "Freeform grouping label used by `links list`. Defaults to 'custom'."
41
+ },
42
+ "url": {
43
+ "type": "string",
44
+ "pattern": "^https?://[^/\\s]+",
45
+ "description": "Absolute http(s) URL opened in the browser. Other schemes (file:, javascript:, ...) are rejected."
46
+ }
47
+ }
48
+ }
49
+ }
50
+ }
dev_setup/links.yaml ADDED
@@ -0,0 +1,116 @@
1
+ # yaml-language-server: $schema=./links.schema.json
2
+ version: 1
3
+ links:
4
+ devstuff-repo:
5
+ name: devstuff Repository
6
+ description: Source code, issues, and releases for devstuff
7
+ category: devstuff
8
+ url: https://github.com/thesawdawg/dev-setup-py
9
+
10
+ devstuff-pypi:
11
+ name: devstuff on PyPI
12
+ description: Published releases of the devstuff package
13
+ category: devstuff
14
+ url: https://pypi.org/project/devstuff/
15
+
16
+ uv-docs:
17
+ name: uv Documentation
18
+ description: Python package and project manager, tool installs, and Python provisioning
19
+ category: python
20
+ url: https://docs.astral.sh/uv/
21
+
22
+ ruff-docs:
23
+ name: Ruff Documentation
24
+ description: Python linter and formatter rules and configuration
25
+ category: python
26
+ url: https://docs.astral.sh/ruff/
27
+
28
+ pypi:
29
+ name: PyPI
30
+ description: Search the Python Package Index
31
+ category: python
32
+ url: https://pypi.org/
33
+
34
+ npm-registry:
35
+ name: npm
36
+ description: Search the npm package registry for Node.js packages
37
+ category: node
38
+ url: https://www.npmjs.com/
39
+
40
+ nvm-repo:
41
+ name: nvm Repository
42
+ description: Node Version Manager install instructions and usage
43
+ category: node
44
+ url: https://github.com/nvm-sh/nvm
45
+
46
+ docker-docs:
47
+ name: Docker Documentation
48
+ description: Docker Engine, Compose, and CLI reference
49
+ category: containers
50
+ url: https://docs.docker.com/
51
+
52
+ docker-hub:
53
+ name: Docker Hub
54
+ description: Search public container images
55
+ category: containers
56
+ url: https://hub.docker.com/
57
+
58
+ ollama-library:
59
+ name: Ollama Model Library
60
+ description: Browse local LLM models that can be pulled with ollama
61
+ category: ai
62
+ url: https://ollama.com/library
63
+
64
+ claude-code-docs:
65
+ name: Claude Code Documentation
66
+ description: Anthropic's agentic coding CLI, settings, hooks, and MCP servers
67
+ category: ai
68
+ url: https://docs.claude.com/en/docs/claude-code/overview
69
+
70
+ starship-docs:
71
+ name: Starship Documentation
72
+ description: Cross-shell prompt configuration and module reference
73
+ category: shell
74
+ url: https://starship.rs/config/
75
+
76
+ conventional-commits:
77
+ name: Conventional Commits
78
+ description: The commit message specification used by commitizen
79
+ category: git
80
+ url: https://www.conventionalcommits.org/
81
+
82
+ github-cli-manual:
83
+ name: GitHub CLI Manual
84
+ description: Reference for the gh command line tool
85
+ category: git
86
+ url: https://cli.github.com/manual/
87
+
88
+ devtoys:
89
+ name: DevToys
90
+ description: Offline developer utilities — converters, encoders, formatters, and generators
91
+ category: utilities
92
+ url: https://devtoys.app/
93
+
94
+ linux-command-library:
95
+ name: Linux Command Library
96
+ description: Searchable reference of Linux commands with examples and cheat sheets
97
+ category: reference
98
+ url: https://linuxcommandlibrary.com/
99
+
100
+ devhints:
101
+ name: Devhints
102
+ description: Community cheatsheets for languages, tools, and frameworks
103
+ category: reference
104
+ url: https://devhints.io/
105
+
106
+ awesome-open-source:
107
+ name: Awesome Open Source
108
+ description: Curated open source projects browsable by topic and language
109
+ category: discovery
110
+ url: https://awesomeopensource.com/
111
+
112
+ fmhy-developer-tools:
113
+ name: FMHY Developer Tools
114
+ description: Curated list of free developer tools, editors, hosting, and resources
115
+ category: discovery
116
+ url: https://fmhy.net/developer-tools
@@ -0,0 +1,138 @@
1
+ from __future__ import annotations
2
+
3
+ import copy
4
+ import re
5
+ from importlib import resources
6
+ from pathlib import Path
7
+ from typing import Any
8
+ from urllib.parse import urlparse
9
+
10
+ import yaml
11
+
12
+ from dev_setup.catalog import CONFIG_DIR, CatalogError
13
+
14
+ USER_CATALOG_PATH = CONFIG_DIR / "links.yaml"
15
+ BUNDLED_CATALOG = "links.yaml"
16
+
17
+ VERSION = 1
18
+ VALID_KEY = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
19
+
20
+ # Links are opened with webbrowser.open() from a user-editable file. Anything but web
21
+ # schemes (file://, javascript:, custom protocol handlers) would let a catalog launch
22
+ # local programs, so the allowlist is the control, not a courtesy.
23
+ ALLOWED_SCHEMES = {"http", "https"}
24
+
25
+ SUPPORTED_FIELDS = {"name", "description", "url", "category"}
26
+
27
+
28
+ def bundled_catalog_path() -> str:
29
+ return f"dev_setup/{BUNDLED_CATALOG}"
30
+
31
+
32
+ def load_catalog_file(path: Path, *, required: bool = False) -> dict[str, dict[str, Any]]:
33
+ if not path.exists():
34
+ if required:
35
+ raise CatalogError(f"Catalog file not found: {path}")
36
+ return {}
37
+
38
+ try:
39
+ raw = yaml.safe_load(path.read_text()) or {}
40
+ except yaml.YAMLError as exc:
41
+ raise CatalogError(f"Invalid YAML in {path}: {exc}") from exc
42
+
43
+ return validate_catalog(raw, source=path)
44
+
45
+
46
+ def validate_catalog(raw: Any, *, source: Path | str = "<catalog>") -> dict[str, dict[str, Any]]:
47
+ if not isinstance(raw, dict):
48
+ raise CatalogError(f"{source}: catalog must be a mapping")
49
+ if raw.get("version") != VERSION:
50
+ raise CatalogError(f"{source}: version must be {VERSION}")
51
+
52
+ links = raw.get("links")
53
+ if links is None:
54
+ return {}
55
+ if not isinstance(links, dict):
56
+ raise CatalogError(f"{source}: links must be a mapping")
57
+
58
+ validated: dict[str, dict[str, Any]] = {}
59
+ for key, data in links.items():
60
+ if not isinstance(key, str) or not VALID_KEY.match(key):
61
+ raise CatalogError(f"{source}: invalid link key {key!r}")
62
+ if not isinstance(data, dict):
63
+ raise CatalogError(f"{source}: link {key!r} must be a mapping")
64
+
65
+ unknown = sorted(set(data) - SUPPORTED_FIELDS)
66
+ if unknown:
67
+ fields = ", ".join(unknown)
68
+ raise CatalogError(f"{source}: link {key!r} has unknown field(s): {fields}")
69
+
70
+ item = copy.deepcopy(data)
71
+ item.setdefault("name", key)
72
+ item.setdefault("description", "")
73
+ item.setdefault("category", "custom")
74
+
75
+ for field in ("name", "description", "category"):
76
+ if not isinstance(item[field], str):
77
+ raise CatalogError(f"{source}: link {key!r} {field} must be a string")
78
+
79
+ url = item.get("url")
80
+ if not isinstance(url, str) or not url:
81
+ raise CatalogError(f"{source}: link {key!r} must set 'url'")
82
+ parsed = urlparse(url)
83
+ if parsed.scheme not in ALLOWED_SCHEMES or not parsed.netloc:
84
+ raise CatalogError(
85
+ f"{source}: link {key!r} url must be an absolute http(s) URL, got {url!r}"
86
+ )
87
+
88
+ validated[key] = item
89
+
90
+ return validated
91
+
92
+
93
+ def catalog_document(links: dict[str, dict[str, Any]]) -> dict[str, Any]:
94
+ return {"version": VERSION, "links": links}
95
+
96
+
97
+ def read_user_catalog() -> dict[str, dict[str, Any]]:
98
+ return load_catalog_file(USER_CATALOG_PATH)
99
+
100
+
101
+ def write_user_catalog(links: dict[str, dict[str, Any]]) -> None:
102
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
103
+ USER_CATALOG_PATH.write_text(_dump(catalog_document(links)))
104
+
105
+
106
+ def load_bundled_catalog() -> dict[str, dict[str, Any]]:
107
+ resource = resources.files("dev_setup").joinpath(BUNDLED_CATALOG)
108
+ try:
109
+ raw = yaml.safe_load(resource.read_text()) or {}
110
+ except FileNotFoundError as exc:
111
+ raise CatalogError(f"Catalog file not found: {bundled_catalog_path()}") from exc
112
+ except yaml.YAMLError as exc:
113
+ raise CatalogError(f"Invalid YAML in {bundled_catalog_path()}: {exc}") from exc
114
+ return validate_catalog(raw, source=bundled_catalog_path())
115
+
116
+
117
+ def load_effective_catalog() -> tuple[
118
+ dict[str, dict[str, Any]],
119
+ dict[str, dict[str, Any]],
120
+ dict[str, dict[str, Any]],
121
+ ]:
122
+ bundled = load_bundled_catalog()
123
+ user = read_user_catalog()
124
+ return merge_catalogs(bundled, user), bundled, user
125
+
126
+
127
+ def merge_catalogs(
128
+ bundled: dict[str, dict[str, Any]],
129
+ user: dict[str, dict[str, Any]],
130
+ ) -> dict[str, dict[str, Any]]:
131
+ merged = copy.deepcopy(bundled)
132
+ for key, data in user.items():
133
+ merged[key] = copy.deepcopy(data)
134
+ return merged
135
+
136
+
137
+ def _dump(data: dict[str, Any]) -> str:
138
+ return yaml.safe_dump(data, sort_keys=False, default_flow_style=False)
@@ -0,0 +1,86 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+
5
+ from dev_setup import links_catalog as catalog
6
+
7
+
8
+ @dataclass
9
+ class LinkDef:
10
+ key: str = ""
11
+ name: str = ""
12
+ description: str = ""
13
+ url: str = ""
14
+ category: str = "custom"
15
+ builtin: bool = False
16
+
17
+ def __post_init__(self) -> None:
18
+ if not self.name:
19
+ self.name = self.key
20
+
21
+ @classmethod
22
+ def from_dict(cls, data: dict, key: str) -> LinkDef:
23
+ return cls(
24
+ key=key,
25
+ name=data.get("name", ""),
26
+ description=data.get("description", ""),
27
+ url=data.get("url", ""),
28
+ category=data.get("category", "custom"),
29
+ )
30
+
31
+
32
+ _registry: dict[str, LinkDef] = {}
33
+ _initialized = False
34
+
35
+
36
+ def init() -> None:
37
+ global _initialized
38
+ if _initialized:
39
+ return
40
+ _initialized = True
41
+ effective, bundled, user = catalog.load_effective_catalog()
42
+ for key, data in effective.items():
43
+ link = LinkDef.from_dict(data, key=key)
44
+ link.builtin = key in bundled and key not in user
45
+ _registry[key] = link
46
+
47
+
48
+ def reload() -> None:
49
+ global _initialized
50
+ _registry.clear()
51
+ _initialized = False
52
+ init()
53
+
54
+
55
+ def get(key: str) -> LinkDef | None:
56
+ init()
57
+ return _registry.get(key)
58
+
59
+
60
+ def all_links() -> list[LinkDef]:
61
+ init()
62
+ return list(_registry.values())
63
+
64
+
65
+ def search(query: str, *, links: list[LinkDef] | None = None) -> list[LinkDef]:
66
+ """Links whose title or description contains every whitespace-separated term.
67
+
68
+ Case-insensitive. Terms are ANDed, so adding a word narrows the result — the
69
+ behaviour people expect from a search box. Title matches rank ahead of
70
+ description-only matches; within a rank the registry's order is kept.
71
+ The link's key is deliberately *not* searched: it is an address, not prose, and
72
+ matching it would surface links whose visible text never mentions the query.
73
+ """
74
+ terms = query.lower().split()
75
+ if not terms:
76
+ return []
77
+
78
+ ranked: list[tuple[int, int, LinkDef]] = []
79
+ for i, link in enumerate(all_links() if links is None else links):
80
+ name = link.name.lower()
81
+ text = f"{name} {link.description.lower()}"
82
+ if all(t in text for t in terms):
83
+ in_title = all(t in name for t in terms)
84
+ ranked.append((0 if in_title else 1, i, link))
85
+ ranked.sort(key=lambda r: r[:2])
86
+ return [link for _, _, link in ranked]
dev_setup/tools.yaml CHANGED
@@ -119,6 +119,30 @@ tools:
119
119
  set -euo pipefail
120
120
  sudo rm -f /usr/local/bin/bat
121
121
 
122
+ claude-code:
123
+ name: Claude Code
124
+ description: Anthropic's agentic coding CLI
125
+ category: ai-tools
126
+ type: npm
127
+ npm_name: "@anthropic-ai/claude-code"
128
+ check_cmd: claude
129
+ help_cmd: claude --help
130
+ docs_url: https://code.claude.com/docs
131
+ requires:
132
+ - nvm
133
+
134
+ codex:
135
+ name: Codex CLI
136
+ description: OpenAI coding agent for the terminal
137
+ category: ai-tools
138
+ type: npm
139
+ npm_name: "@openai/codex"
140
+ check_cmd: codex
141
+ help_cmd: codex --help
142
+ docs_url: https://github.com/openai/codex
143
+ requires:
144
+ - nvm
145
+
122
146
  commitizen:
123
147
  name: Commitizen
124
148
  description: Conventional-commit prompt, semantic version bumping, and changelog generation
@@ -131,6 +155,49 @@ tools:
131
155
  requires:
132
156
  - uv
133
157
 
158
+ devin:
159
+ name: Devin CLI
160
+ description: Cognition's AI software engineer, in the terminal
161
+ category: ai-tools
162
+ type: bash
163
+ check_cmd: command -v devin >/dev/null 2>&1 || test -x "$HOME/.local/bin/devin"
164
+ help_cmd: devin --help
165
+ docs_url: https://docs.devin.ai/cli
166
+ install_script: |
167
+ set -euo pipefail
168
+ tmp="$(mktemp --suffix=.sh)"
169
+ trap 'rm -f "$tmp"' EXIT
170
+ curl -fsSL https://cli.devin.ai/install.sh -o "$tmp"
171
+ # The installer's last step runs `devin setup`, an interactive auth/MCP
172
+ # wizard with no flag to skip it. Strip the line (best-effort — if
173
+ # upstream renames it, stdin is /dev/null anyway so the wizard reads EOF
174
+ # instead of hanging on a prompt nobody can see). `devin auth login`
175
+ # covers the same ground whenever the user is ready.
176
+ sed -i 's|"$VERSION_DIR/bin/$COMPILED_BIN_NAME" setup.*|# &|' "$tmp"
177
+ bash "$tmp" </dev/null || true
178
+ # A swallowed wizard exit code means the script's own status can't be
179
+ # trusted — verify the ~/.local/bin/devin symlink it creates instead.
180
+ if [ ! -x "$HOME/.local/bin/devin" ]; then
181
+ echo "install failed — ~/.local/bin/devin is missing" >&2
182
+ exit 1
183
+ fi
184
+ echo "Run 'devin auth login' to authenticate."
185
+ remove_script: |
186
+ set -euo pipefail
187
+ if [ -x "$HOME/.local/bin/devin" ]; then
188
+ # `devin uninstall` removes the ~/.local/bin symlink and the versioned
189
+ # payload under ~/.local/share/devin; --force skips its confirmation
190
+ # prompt (devstuff already confirmed). Best-effort — the rm's below
191
+ # cover a partial or failed uninstall.
192
+ "$HOME/.local/bin/devin" uninstall --force </dev/null || true
193
+ fi
194
+ rm -f "$HOME/.local/bin/devin"
195
+ rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/devin"
196
+ # The installer also links man pages into the user man dir; they dangle
197
+ # once _versions is gone.
198
+ rm -f "${XDG_DATA_HOME:-$HOME/.local/share}"/man/man1/devin*.1
199
+ echo "Config and credentials under ~/.config/devin were left in place."
200
+
134
201
  docker:
135
202
  name: Docker
136
203
  description: Container runtime + docker compose plugin
@@ -311,6 +378,23 @@ tools:
311
378
  PY
312
379
  fi
313
380
 
381
+ hey-dave:
382
+ name: hey-dave
383
+ description: Terminal coding-agent harness that runs D.A.V.E. natively
384
+ category: ai-tools
385
+ type: uvx
386
+ pip_name: hey-dave
387
+ # Requires-Python is >=3.14 — ask uv for it explicitly so the tool env is
388
+ # built on a managed 3.14 rather than whichever interpreter happens to win
389
+ # discovery on the host.
390
+ uv_python: "3.14"
391
+ # The console script is `dave`, not `hey-dave` — check what actually lands.
392
+ check_cmd: dave
393
+ help_cmd: dave --help
394
+ docs_url: https://pypi.org/project/hey-dave/
395
+ requires:
396
+ - uv
397
+
314
398
  htop:
315
399
  name: htop
316
400
  description: Interactive process and resource monitor
@@ -760,6 +844,18 @@ tools:
760
844
  set -euo pipefail
761
845
  rm -f "$HOME/.local/bin/uv" "$HOME/.local/bin/uvx" "$HOME/.cargo/bin/uv" "$HOME/.cargo/bin/uvx"
762
846
 
847
+ llamactl:
848
+ name: llamactl
849
+ description: CLI for managing LlamaDeploy projects and deployments (LlamaIndex)
850
+ category: ai-tools
851
+ type: uvx
852
+ pip_name: llamactl
853
+ check_cmd: llamactl
854
+ help_cmd: llamactl --help
855
+ docs_url: https://github.com/run-llama/llama_deploy
856
+ requires:
857
+ - uv
858
+
763
859
  llm-checker:
764
860
  name: llm-checker
765
861
  description: Tool to check llm compatibility with hardware
dev_setup/ui.py CHANGED
@@ -99,10 +99,23 @@ def text_input(prompt: str, default: str = "", required: bool = False) -> str:
99
99
  error("This field is required.")
100
100
 
101
101
 
102
- def select(prompt: str, choices: list, default: object | None = None) -> str:
102
+ def select(
103
+ prompt: str, choices: list, default: object | None = None, *, searchable: bool = False
104
+ ) -> str:
103
105
  """Single-choice prompt. `choices` may be plain strings or questionary.Choice
104
- objects; `default` is the choice (or value) the cursor starts on."""
105
- result = _ask(questionary.select(prompt, choices=choices, default=default, style=_STYLE))
106
+ objects; `default` is the choice (or value) the cursor starts on. `searchable`
107
+ lets the user type to filter the list — which turns off the j/k movement keys,
108
+ since those would otherwise be swallowed as search text."""
109
+ result = _ask(
110
+ questionary.select(
111
+ prompt,
112
+ choices=choices,
113
+ default=default,
114
+ style=_STYLE,
115
+ use_search_filter=searchable,
116
+ use_jk_keys=not searchable,
117
+ )
118
+ )
106
119
  return result or ""
107
120
 
108
121
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: devstuff
3
- Version: 2.6.0
3
+ Version: 2.8.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>
@@ -33,6 +33,9 @@ A Python-based CLI for managing your Linux development environment. Install, rem
33
33
 
34
34
  ## Prerequisites
35
35
 
36
+ Maintainers: see [Repository agent setup](docs/github-agent.md) for optional
37
+ GitHub Actions PR review and CI failure triage.
38
+
36
39
  | Requirement | Notes |
37
40
  |-------------|-------|
38
41
  | **OS** | Ubuntu 20.04+ or Debian 11+ (amd64) |
@@ -96,6 +99,8 @@ The checks cover:
96
99
  | `user-tools-catalog` | user `tools.yaml` (if present) is valid | — |
97
100
  | `bundled-functions-catalog` | bundled `functions.yaml` loads and validates | — |
98
101
  | `user-functions-catalog` | user `functions.yaml` (if present) is valid | — |
102
+ | `bundled-links-catalog` | bundled `links.yaml` loads and validates | — |
103
+ | `user-links-catalog` | user `links.yaml` (if present) is valid | — |
99
104
  | `bundled-agent-catalog` | bundled `agent_tools.yaml` loads and validates | — |
100
105
  | `user-agent-catalog` | user `agent_tools.yaml` (if present) is valid | — |
101
106
  | `registry` | effective catalog builds into tool objects; `is_installed()` probes don't crash | — |
@@ -1272,6 +1277,45 @@ Optional utilities you may want on some machines.
1272
1277
  | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
1273
1278
  | `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
1274
1279
  | `aws` | AWS CLI | Amazon Web Services CLI v2 | `aws help` |
1280
+ ## Links
1281
+
1282
+ A catalog of bookmarks to other tools' sites and docs — `devstuff links` lists them, searches
1283
+ them, and opens one in your browser. Same bundled + user precedence merge as the other
1284
+ catalogs (`~/.config/devstuff/links.yaml` overrides matching keys and appends new ones).
1285
+
1286
+ ```bash
1287
+ devstuff links # interactive picker: type to filter, Enter to open
1288
+ devstuff links list [category] # all links, grouped by category
1289
+ devstuff links search docker images # title + description, case-insensitive, every word must match
1290
+ devstuff links open uv-docs # open in your browser (alias: devstuff link ...)
1291
+ devstuff links path # print ~/.config/devstuff/links.yaml
1292
+ ```
1293
+
1294
+ `search` matches the title and description only (title matches rank first) and exits 0 when
1295
+ nothing matches. `open` prints the URL as well, so over SSH — where there is no browser on the
1296
+ machine devstuff runs on — you still get a clickable link; in that case it exits non-zero.
1297
+
1298
+ ```yaml
1299
+ version: 1
1300
+ links:
1301
+ my-wiki:
1302
+ name: Team Wiki
1303
+ description: Runbooks and onboarding notes
1304
+ category: work # optional, defaults to "custom"
1305
+ url: https://wiki.example.com
1306
+ ```
1307
+
1308
+ | Field | Required | Description |
1309
+ |-------|----------|-------------|
1310
+ | `url` | yes | Absolute `http(s)` URL. Other schemes (`file:`, `javascript:`, …) are rejected at load time. |
1311
+ | `name` | no | Title shown in listings and matched by `search`. Defaults to the key. |
1312
+ | `description` | no | Shown in listings and matched by `search`. |
1313
+ | `category` | no | Grouping label for `list`. Defaults to `custom`. |
1314
+
1315
+ `src/dev_setup/links.schema.json` documents these fields for editor tooling.
1316
+
1317
+ ---
1318
+
1275
1319
  | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
1276
1320
  | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
1277
1321
  | `gh` | GitHub CLI | GitHub's official CLI | `gh --help` |
@@ -1281,6 +1325,7 @@ Optional utilities you may want on some machines.
1281
1325
  | `ipython` | IPython | Enhanced interactive Python shell with rich tab completion and magic commands | `ipython --help` |
1282
1326
  | `lazygit` | lazygit | TUI git client for fast, keyboard-driven git workflows (`devstuff configure lazygit`) | `lazygit --help` |
1283
1327
  | `reptyr` | reptyr | Move a running process to another terminal (`devstuff configure reptyr` for permissions) | `reptyr -h` |
1328
+ | `llamactl` | llamactl | CLI for managing LlamaDeploy projects and deployments (LlamaIndex) | `llamactl --help` |
1284
1329
  | `llm-checker` | llm-checker | Check LLM compatibility with your hardware | `llm-checker --help` |
1285
1330
  | `lmstudio` | LM Studio | Run large language models locally with a GUI | `lms --help` |
1286
1331
  | `mkcert` | mkcert | Zero-config local HTTPS certificates | `mkcert --help` |
@@ -1288,6 +1333,10 @@ Optional utilities you may want on some machines.
1288
1333
  | `ollama` | Ollama | Run large language models locally | `ollama --help` |
1289
1334
  | `php` | PHP 8.4 | PHP 8.4 + common extensions via ondrej/php PPA | `php --help` |
1290
1335
  | `pi` | Pi Coding Agent | AI coding agent npm package | `pi --help` |
1336
+ | `claude-code` | Claude Code | Anthropic's agentic coding CLI | `claude --help` |
1337
+ | `codex` | Codex CLI | OpenAI coding agent for the terminal | `codex --help` |
1338
+ | `devin` | Devin CLI | Cognition's AI software engineer, in the terminal | `devin --help` |
1339
+ | `hey-dave` | hey-dave | Terminal coding-agent harness that runs D.A.V.E. natively | `dave --help` |
1291
1340
  | `pre-commit` | pre-commit | Git hook manager for automated code quality checks (`devstuff configure pre-commit`) | `pre-commit --help` |
1292
1341
  | `saml2aws` | saml2aws | SAML → AWS STS credentials CLI (Versent) | `saml2aws --help` |
1293
1342
  | `starship` | Starship | Fast, cross-shell customizable prompt (`devstuff configure starship`) | `starship --help` |
@@ -4,17 +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=Y_RbHkexTAIQN4neDQ3buo6vmtTMNdXrsYsmY0X_Om8,2976
8
- dev_setup/doctor.py,sha256=JliUAgmiW2HVCWHhT76PIXTBekNXXrc0VfDMaOeLBWY,15918
7
+ dev_setup/cli.py,sha256=IVrIIeBGpgf1JsY8nB-ISQkwqye6F8gnbjB0A8aJGec,3110
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
14
  dev_setup/generic.py,sha256=Tr7YAkS_SXjExJpyNw3palDuaiNn1TcAoeZ0wHdXIeM,28424
15
+ dev_setup/links.schema.json,sha256=V9_1UA8Ejfu0j6-VczH0blW1mlGupXx56NhApLtHHKc,1938
16
+ dev_setup/links.yaml,sha256=t3-_cbCzA6PqnjZDIe3-zgCiyyFo7AcUS3Aj2Y15XGw,3417
17
+ dev_setup/links_catalog.py,sha256=Xe7s9oqiCrfQPUwE-X9o6p5VkU7mH9PjY9NMyn6VbHg,4610
18
+ dev_setup/links_registry.py,sha256=xyq49oH1u_CX85UcizKSuxuy_pzurNoDwSRg3YftUMY,2439
15
19
  dev_setup/registry.py,sha256=8lrk6EXCCWk1WNeNnCGLTJ-v8rpCs7-TLYtVXgiuxnA,2243
16
- dev_setup/tools.yaml,sha256=7v_aYBpTacYmuxmNwckeMwUQiFKxXml-ZWvG3QQU-Zc,30702
17
- dev_setup/ui.py,sha256=Z5nNZV8MN8tAjo1ZWq7-QPZYkPKQKuM7JbmGtiuKTqM,3806
20
+ dev_setup/tools.yaml,sha256=m2MEYq_mZuzEU8vCJgPWHdhLuqRjQGNWheqhwQgMXXQ,34234
21
+ dev_setup/ui.py,sha256=1xto3lVmc-98oa92yHEoXwpYZfFHKAE8DEOGGwz2h4M,4155
18
22
  dev_setup/verbose.py,sha256=N3U9JAYOvFwdd8DT6W7Pqq6RCIUfbcQnPsm0O1TnvQY,5003
19
23
  dev_setup/agent/__init__.py,sha256=znrgxUCr_y0Qp-f41S6EaTv-hoTYwoZ9mOMLVge-IJg,226
20
24
  dev_setup/agent/approval.py,sha256=R2YnbR1fauGtV7-NW5dH1QvWvNHjR3l23DKRTCiqpEE,3625
@@ -40,8 +44,9 @@ dev_setup/commands/delete_cmd.py,sha256=j_-fr2RMaeX3sMhH-7wJP5KC9Yvpgbb9KIeEEyG9
40
44
  dev_setup/commands/docs_cmd.py,sha256=1PtpwdFO3LrAxG3HyCLFn5SXVnnwqcJ8K_c9cVd8Phc,940
41
45
  dev_setup/commands/doctor_cmd.py,sha256=8HqQ9sB3aVDKer6jbqN_Eq0XKZDXM2o48L6_vL8JAcE,3161
42
46
  dev_setup/commands/functions_cmd.py,sha256=D9JRYMRavXbROz0XRGjHRHeFvZY-GKyvRCctJODQDBE,2856
43
- dev_setup/commands/help_cmd.py,sha256=kHbzMggYVj3hS7JKUiCrBY4VtZ5p71YPoPKQ4Y-OYNU,3301
47
+ dev_setup/commands/help_cmd.py,sha256=AmX9vv3U7sFb6Zby3crhUUSqkLsW7DekOSn-3iShedk,3482
44
48
  dev_setup/commands/install_cmd.py,sha256=AGrB0CZPT6hZ0Cnn9AgmlyFkW8F1wZufuXVvwYft_Xo,4610
49
+ dev_setup/commands/links_cmd.py,sha256=kvnoBXdM9QWRZRIwWgnmWqVkOYE7AZxywFTQD5_Uwv4,4924
45
50
  dev_setup/commands/list_cmd.py,sha256=-BAywXxpSm4-VAlysLzlDwIqvmk_zBKhmzEObM8jigo,2847
46
51
  dev_setup/commands/remove_cmd.py,sha256=_KqCa2S9fQFngLUs_OpBzjkIkFKgDtKup4gQ5TqLrVI,1239
47
52
  dev_setup/commands/run_cmd.py,sha256=e1xfWt09UALiAe03AxzdvZyYpj0V7WKk2-E_nbk9hIw,2933
@@ -92,7 +97,7 @@ dev_setup/configure/starship/model.py,sha256=HNkIj69DqBQFAq0VTHqPLNZT2DuBZSfF-5y
92
97
  dev_setup/configure/starship/preview.py,sha256=ZaNhNA3AeHHtPnMqrJbB9XVVXDFbH1R36jm8xyYdt2U,6145
93
98
  dev_setup/configure/starship/render.py,sha256=gDE0hbGZ9oDCR1VAZQRDm5EFYviMjj0-eSmr1EnZfn8,10262
94
99
  dev_setup/configure/starship/wizard.py,sha256=BmWl-U6ttF79gepDhCv8UxT8ZDIMe1SWnhSkA1iIrGQ,15498
95
- devstuff-2.6.0.dist-info/METADATA,sha256=ARNwSLvq_BV-yvT0qbbcyYxRdoCo_yaRs9xXvuNw7XY,75335
96
- devstuff-2.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
97
- devstuff-2.6.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
98
- devstuff-2.6.0.dist-info/RECORD,,
100
+ devstuff-2.8.0.dist-info/METADATA,sha256=hwvper3UptnHHogbvhnebLKYvtwAZ7LjY_lfw4EbtCM,77775
101
+ devstuff-2.8.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
102
+ devstuff-2.8.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
103
+ devstuff-2.8.0.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: hatchling 1.32.0
2
+ Generator: hatchling 1.32.4
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any