devstuff 2.7.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/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.7.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>
@@ -99,6 +99,8 @@ The checks cover:
99
99
  | `user-tools-catalog` | user `tools.yaml` (if present) is valid | — |
100
100
  | `bundled-functions-catalog` | bundled `functions.yaml` loads and validates | — |
101
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 | — |
102
104
  | `bundled-agent-catalog` | bundled `agent_tools.yaml` loads and validates | — |
103
105
  | `user-agent-catalog` | user `agent_tools.yaml` (if present) is valid | — |
104
106
  | `registry` | effective catalog builds into tool objects; `is_installed()` probes don't crash | — |
@@ -1275,6 +1277,45 @@ Optional utilities you may want on some machines.
1275
1277
  | `ansible` | Ansible | Automation engine for configuration management and app deployment (`devstuff configure ansible`) | `ansible --help` |
1276
1278
  | `ansible-vault` | Ansible Vault | Encrypt and manage secrets within Ansible projects (bundled with Ansible) | `ansible-vault --help` |
1277
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
+
1278
1319
  | `bat` | bat | cat replacement with syntax highlighting and git integration (`devstuff configure bat`) | `bat --help` |
1279
1320
  | `commitizen` | Commitizen | Conventional-commit prompt, semantic version bumping, and changelog generation (`devstuff configure commitizen`) | `cz --help` |
1280
1321
  | `gh` | GitHub CLI | GitHub's official CLI | `gh --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
20
  dev_setup/tools.yaml,sha256=m2MEYq_mZuzEU8vCJgPWHdhLuqRjQGNWheqhwQgMXXQ,34234
17
- dev_setup/ui.py,sha256=Z5nNZV8MN8tAjo1ZWq7-QPZYkPKQKuM7JbmGtiuKTqM,3806
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.7.0.dist-info/METADATA,sha256=wpZ3Mfc24NNUa0YUQM9RackcG6jMmmXdMj8gSrjFZp8,75934
96
- devstuff-2.7.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
97
- devstuff-2.7.0.dist-info/entry_points.txt,sha256=48ITy9ENdXDFrTHwAyVPUpq1MDmgFqcOisOo5mAR6OQ,53
98
- devstuff-2.7.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,,