dev-setup 1.1.0__tar.gz → 1.4.0__tar.gz

dev_setup-1.4.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(docker build *)",
+      "Bash(git -C /home/sawyer/Documents/Projects/ClaudeProjects/dev-setup-py log --format=\"%H %ai %s\")",
+      "Bash(git -C /home/sawyer/Documents/Projects/ClaudeProjects/dev-setup-py add src/dev_setup/packages/eza.py)",
+      "Bash(git -C /home/sawyer/Documents/Projects/ClaudeProjects/dev-setup-py commit -m ' *)"
+    ]
+  }
+}

dev_setup-1.4.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dev-setup
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

dev_setup-1.4.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+## v1.4.0 (2026-06-19)
+
+### Feat
+
+- add eza builtin tool
+
+## v1.3.0 (2026-06-19)
+
+### Feat
+
+- gate tool availability on required dependencies
+
+## v1.2.0 (2026-06-19)
+
+### Feat
+
+- add docker-compose.yml to dev/ sandbox
+- add dev/ sandbox with Dockerfile for local install testing
+- add docs command to open tool documentation in the browser
+- add Go, Java, and Ruby builtin tools under languages category
+- add gh, mkcert, ollama, and pi-coding-agent builtin tools
+- add --verbose/-v flag to stream install/remove output
+
+### Docs
+
+- add Prerequisites section to README
+
+### Chore
+
+- add commitizen dev dep and unify version source
+
+## v1.1.0 (2026-06-18)
+
+### Feat
+
+- add aws-cli and saml2aws built-in packages
+- add bash type for multi-step custom installs
+- add help_cmd field to all tools, display in list output
+- enhance project metadata in pyproject.toml
+
+### Refactor
+
+- improve maintainability and extensibility for new tool additions
+- switch from uv-run to pip/pipx install pattern
+
+### Docs
+
+- add comprehensive README
+
+## v1.0.0 (2026-06-17)
+
+### Feat
+
+- initial Python implementation of dev-setup CLI

{dev_setup-1.1.0 → dev_setup-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dev-setup
-Version: 1.1.0
+Version: 1.4.0
 Summary: Development environment setup CLI for Linux
 Project-URL: Repository, https://github.com/thesawdawg/dev-setup-py
 Author-email: Sawyer <sawyerksu@gmail.com>
@@ -30,6 +30,32 @@ A Python-based CLI for managing your Linux development environment. Install, rem
 
 ---
 
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **OS** | Ubuntu 20.04+ or Debian 11+ (amd64) |
+| **Python** | 3.11 or later |
+| **curl** | Used by script-based installers (Docker, NVM, uv, etc.) |
+| **sudo** | Required for tools that write to system paths (`/usr/local/bin`, apt packages) |
+| **ca-certificates** | For HTTPS downloads — present on most systems by default |
+
+These are available on any standard Ubuntu/Debian install. On a fresh minimal image, run:
+
+```bash
+sudo apt-get install -y python3 python3-pip curl ca-certificates sudo
+```
+
+**Optional** — only needed when using specific install types:
+
+| Requirement | When |
+|-------------|------|
+| `git` | `git`-type custom packages (`dev-setup add` → git) |
+| `node` / `npm` | `npm`-type custom packages |
+| `uv` | Running from source via `./dev-setup` (auto-installed if missing) |
+
+---
+
 ## Installation
 
 ### From PyPI (recommended)
@@ -361,17 +387,6 @@ class MyTool(Tool):
 
 ---
 
-## Requirements
-
-- Debian/Ubuntu Linux (apt-based; htop and php fall back to yum/dnf/pacman for detection)
-- `curl` (for bootstrapping uv and install scripts)
-- `git` (for `git`-type custom packages)
-- `sudo` access (Docker, PHP, saml2aws, htop installs write to system paths)
-
-Python 3.11+ is provisioned automatically by uv if not already present.
-
----
-
 ## Dependencies
 
 | Package | Version | Purpose |

{dev_setup-1.1.0 → dev_setup-1.4.0}/README.md

@@ -4,6 +4,32 @@ A Python-based CLI for managing your Linux development environment. Install, rem
 
 ---
 
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **OS** | Ubuntu 20.04+ or Debian 11+ (amd64) |
+| **Python** | 3.11 or later |
+| **curl** | Used by script-based installers (Docker, NVM, uv, etc.) |
+| **sudo** | Required for tools that write to system paths (`/usr/local/bin`, apt packages) |
+| **ca-certificates** | For HTTPS downloads — present on most systems by default |
+
+These are available on any standard Ubuntu/Debian install. On a fresh minimal image, run:
+
+```bash
+sudo apt-get install -y python3 python3-pip curl ca-certificates sudo
+```
+
+**Optional** — only needed when using specific install types:
+
+| Requirement | When |
+|-------------|------|
+| `git` | `git`-type custom packages (`dev-setup add` → git) |
+| `node` / `npm` | `npm`-type custom packages |
+| `uv` | Running from source via `./dev-setup` (auto-installed if missing) |
+
+---
+
 ## Installation
 
 ### From PyPI (recommended)
@@ -335,17 +361,6 @@ class MyTool(Tool):
 
 ---
 
-## Requirements
-
-- Debian/Ubuntu Linux (apt-based; htop and php fall back to yum/dnf/pacman for detection)
-- `curl` (for bootstrapping uv and install scripts)
-- `git` (for `git`-type custom packages)
-- `sudo` access (Docker, PHP, saml2aws, htop installs write to system paths)
-
-Python 3.11+ is provisioned automatically by uv if not already present.
-
----
-
 ## Dependencies
 
 | Package | Version | Purpose |

dev_setup-1.4.0/app-design-output/recommendations.md

@@ -0,0 +1,100 @@
+# dev-setup — Maintainability Review
+
+_Generated 2026-06-18_
+
+## Goal
+Lower the cost of adding new tools to the core PyPI package build.
+
+---
+
+## Findings
+
+### 1. Builtin boilerplate: every package file duplicates the same `is_installed` / `get_version` logic [HIGH]
+
+Seven of eight builtin package files implement the same two-liner:
+```python
+def is_installed(self) -> bool:
+    return shutil.which(self.key) is not None
+
+def get_version(self) -> str:
+    r = subprocess.run([self.key, "--version"], capture_output=True, text=True)
+    return r.stdout.strip().splitlines()[0] if r.returncode == 0 else ""
+```
+Adding a new tool means copy-pasting this pattern. Errors diverge silently (`aws_cli` and `saml2aws` check `stderr` fallback; `docker` skips `splitlines()`).
+
+**Fix:** Add `WhichTool(Tool)` to `base.py` — a shared mixin that provides these two methods. Each builtin that passes `shutil.which` inherits from `WhichTool` instead of `Tool` and only overrides what's truly unique (install/remove logic). `NvmTool` keeps its own `is_installed()` since it checks a file path, not `which`.
+
+**Effort:** Low. Touches 7 files, each loses 8–12 lines.
+
+---
+
+### 2. Hardcoded category list in `list_cmd.py` silently drops new tools [HIGH]
+
+`list_cmd.py:34` iterates `("core", "tools", "custom")`. A builtin with any other `category` value is collected into `by_cat` but never rendered. Verified: a tool with `category = "cloud"` is invisible to `dev-setup list`.
+
+**Fix:** Derive iteration order dynamically using a priority dict — `core=0`, `custom=999`, all others sorted by name in between.
+
+**Effort:** 4-line change.
+
+---
+
+### 3. `add_cmd` and `delete_cmd` mutate private registry state directly [MEDIUM]
+
+`add_cmd.py:120-123` and `delete_cmd.py:39-42` both reach into `registry._registry` and `registry._order` directly. Any internal registry refactor (e.g., ordering strategy change) silently breaks these commands.
+
+**Fix:** Add public `register(tool)` and `deregister(key)` functions to `registry.py`. Commands use those; internals stay internal.
+
+**Effort:** Low.
+
+---
+
+### 4. Version is defined in two places and is out of sync [MEDIUM]
+
+`src/dev_setup/__init__.py` says `1.0.0`; `pyproject.toml` says `1.1.0`. Additionally, `ui.py:64` hardcodes the string `"v1.0.0"` in `print_banner()`.
+
+**Fix:** Single source of truth: update `__init__.py` to `1.1.0`, and have `print_banner()` read from `from dev_setup import __version__`.
+
+_Note: for a fully automated solution, `pyproject.toml` can be set to `dynamic = ["version"]` with `[tool.hatch.version] path = "src/dev_setup/__init__.py"`, eliminating the need to update two files on release. That's a separate change._
+
+**Effort:** 2 lines.
+
+---
+
+### 5. `CUSTOM_DIR` / `_CUSTOM_DIR` duplicated in `generic.py` [LOW]
+
+`generic.py` exports both `CUSTOM_DIR` and `_CUSTOM_DIR` (identical). `registry.py` imports the underscore form. This is confusing — two names for the same path.
+
+**Fix:** Remove `_CUSTOM_DIR`, update `registry.py` to import `CUSTOM_DIR`.
+
+---
+
+### 6. `import shutil as _shutil` inside `GenericTool.remove()` shadows a top-level import [LOW]
+
+`generic.py` imports `shutil` at the top of the file, then re-imports it as `_shutil` inside the `git` branch of `remove()`. The local shadowing is unnecessary.
+
+**Fix:** Use the module-level `shutil` directly.
+
+---
+
+## What "adding a new builtin" looks like after fixes
+
+Before (current): ~50 lines per file including copy-pasted `is_installed`, `get_version`, and `shutil`/`subprocess` imports.
+
+After: ~30 lines. A simple tool like `htop` becomes:
+```python
+class HtopTool(WhichTool):
+    key = "htop"
+    name = "htop"
+    description = "Interactive process and resource monitor"
+    category = "tools"
+    install_type = "apt"
+    help_cmd = "man htop"
+
+    def install(self) -> Optional[str]:
+        ...  # only the unique install logic
+
+    def remove(self) -> None:
+        ...  # only the unique remove logic
+```
+
+New tools with unusual categories won't vanish from `list`. New categories appear automatically without touching `list_cmd.py`.

dev_setup-1.4.0/dev/Dockerfile

@@ -0,0 +1,38 @@
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    TZ=UTC \
+    LANG=C.UTF-8
+
+# System packages needed to bootstrap dev-setup and run its installers
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.12 \
+    python3.12-venv \
+    python3-pip \
+    curl \
+    git \
+    sudo \
+    ca-certificates \
+    gnupg \
+    lsb-release \
+    && rm -rf /var/lib/apt/lists/*
+
+# Non-root user with passwordless sudo — mirrors a real developer workstation
+RUN useradd -m -s /bin/bash developer \
+    && echo "developer ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+USER developer
+WORKDIR /home/developer
+
+# Install the pre-built wheel (built by 'make build' before docker build runs)
+COPY --chown=developer:developer dist/dev_setup-*.whl /tmp/
+
+RUN pip install --user --break-system-packages /tmp/dev_setup-*.whl \
+    && rm /tmp/dev_setup-*.whl
+
+ENV PATH="/home/developer/.local/bin:$PATH"
+
+# Pre-create config dir so the tool has somewhere to write on first run
+RUN mkdir -p /home/developer/.config/dev-setup/packages
+
+CMD ["/bin/bash", "--login"]

dev_setup-1.4.0/dev/Makefile

@@ -0,0 +1,19 @@
+ROOT := ..
+
+.PHONY: build run shell clean
+
+# Build a fresh wheel from source, then build the Docker image.
+# Clean dist first so the glob in the Dockerfile matches exactly one file.
+build:
+	cd $(ROOT) && rm -f dist/*.whl dist/*.tar.gz && uv build
+	docker compose build
+
+# Drop into an interactive shell as the 'developer' user
+run: build
+	docker compose run --rm sandbox
+
+shell: run
+
+# Remove the built image and named volume
+clean:
+	docker compose down --rmi local --volumes 2>/dev/null || true

dev_setup-1.4.0/dev/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  sandbox:
+    build:
+      context: ..
+      dockerfile: dev/Dockerfile
+    image: dev-setup-sandbox
+    stdin_open: true
+    tty: true
+    volumes:
+      # Persist custom packages added via 'dev-setup add' across container runs
+      - dev-setup-config:/home/developer/.config/dev-setup
+
+volumes:
+  dev-setup-config:

{dev_setup-1.1.0 → dev_setup-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dev-setup"
-version = "1.1.0"
+version = "1.4.0"
 description = "Development environment setup CLI for Linux"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,3 +41,14 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/dev_setup"]
+
+[dependency-groups]
+dev = [
+    "commitizen>=3.0",
+]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true

dev_setup-1.4.0/src/dev_setup/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("dev-setup")
+except PackageNotFoundError:
+    __version__ = "dev"

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/base.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import shutil
 import subprocess
 from abc import ABC, abstractmethod
 from pathlib import Path
@@ -14,6 +15,8 @@ class Tool(ABC):
     install_type: str = "unknown"
     builtin: bool = True
     help_cmd: str = ""
+    docs_url: str = ""
+    requires: list = []  # keys of tools that must be installed before this one
 
     @abstractmethod
     def is_installed(self) -> bool: ...
@@ -32,6 +35,22 @@ class Tool(ABC):
         return ""
 
 
+class WhichTool(Tool):
+    """Base for tools whose presence is detected via PATH lookup (shutil.which)."""
+
+    def is_installed(self) -> bool:
+        return shutil.which(self.key) is not None
+
+    def get_version(self) -> str:
+        if not shutil.which(self.key):
+            return ""
+        r = subprocess.run([self.key, "--version"], capture_output=True, text=True)
+        if r.returncode != 0:
+            return ""
+        out = r.stdout.strip() or r.stderr.strip()
+        return out.splitlines()[0] if out else ""
+
+
 def run_bash(cmd: str, **kwargs) -> subprocess.CompletedProcess:
     return subprocess.run(["bash", "-c", cmd], **kwargs)
 

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/cli.py

@@ -25,6 +25,7 @@ def _register_commands() -> None:
     from dev_setup.commands.remove_cmd import remove_cmd
     from dev_setup.commands.add_cmd import add_cmd
     from dev_setup.commands.delete_cmd import delete_cmd
+    from dev_setup.commands.docs_cmd import docs_cmd
 
     cli.add_command(list_cmd, "list")
     cli.add_command(install_cmd, "install")
@@ -33,6 +34,7 @@ def _register_commands() -> None:
     cli.add_command(add_cmd, "add")
     cli.add_command(delete_cmd, "delete")
     cli.add_command(delete_cmd, "rm")
+    cli.add_command(docs_cmd, "docs")
 
 
 _register_commands()

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/add_cmd.py

@@ -101,6 +101,9 @@ def add_cmd() -> None:
     kwargs["help_cmd"] = ui.text_input(
         "Help command (optional, e.g. tool --help):", required=False
     )
+    kwargs["docs_url"] = ui.text_input(
+        "Documentation URL (optional):", required=False
+    )
 
     ui.console.print()
     ui.console.print("[bold]Summary[/]")
@@ -117,10 +120,8 @@ def add_cmd() -> None:
     tool = GenericTool(**kwargs)
     tool.save()
 
-    from dev_setup import registry as _reg
-    _reg._registry[key] = tool
-    if key not in _reg._order:
-        _reg._order.append(key)
+    from dev_setup import registry
+    registry.register(tool)
 
     ui.success(f"Package '{key}' added. Install with: dev-setup install {key}")
 

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/delete_cmd.py

@@ -35,10 +35,5 @@ def delete_cmd(key: str) -> None:
         return
 
     pkg_file.unlink()
-
-    if key in registry._registry:
-        del registry._registry[key]
-    if key in registry._order:
-        registry._order.remove(key)
-
+    registry.deregister(key)
     ui.success(f"Package '{key}' deleted from registry.")

dev_setup-1.4.0/src/dev_setup/commands/docs_cmd.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import sys
+import webbrowser
+
+import click
+
+from dev_setup import registry, ui
+
+
+@click.command("docs")
+@click.argument("package")
+def docs_cmd(package: str) -> None:
+    """Open the documentation site for a package in your browser."""
+    if not registry.exists(package):
+        ui.error(f"Unknown package: '{package}'")
+        sys.exit(1)
+
+    tool = registry.get(package)
+    assert tool is not None
+
+    if not tool.docs_url:
+        ui.warn(f"No documentation URL is configured for '{package}'.")
+        ui.dim("For custom packages, re-add with a docs URL via: dev-setup add")
+        sys.exit(1)
+
+    ui.console.print(f"\n  [bold]{tool.name}[/] docs")
+    ui.console.print(f"  [cyan]{tool.docs_url}[/]\n")
+
+    opened = webbrowser.open(tool.docs_url)
+    if opened:
+        ui.success("Opened in browser.")
+    else:
+        ui.warn("Could not open a browser — copy the URL above to open manually.")

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/help_cmd.py

@@ -14,6 +14,7 @@ def print_help() -> None:
         ("remove",  "<package ...>",                          "Uninstall installed packages"),
         ("add",     "",                                        "Add a custom package (guided wizard)"),
         ("delete",  "<key>",                                  "Remove a custom package from the registry"),
+        ("docs",    "<package>",                              "Open documentation in browser"),
         ("version", "",                                        "Show version"),
     ]
     for cmd, args, desc in rows:

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/install_cmd.py

@@ -11,9 +11,13 @@ from dev_setup.base import Tool
 
 
 @click.command("install")
+@click.option("--verbose", "-v", is_flag=True, help="Stream install output to the terminal.")
 @click.argument("packages", nargs=-1)
-def install_cmd(packages: Tuple[str, ...]) -> None:
+def install_cmd(packages: Tuple[str, ...], verbose: bool) -> None:
     """Install packages. Interactive picker when called with no arguments."""
+    from dev_setup import generic
+    generic._verbose = verbose
+
     if not packages:
         _install_interactive()
     else:
@@ -34,6 +38,11 @@ def _install_one(tool: Tool) -> bool:
     if tool.is_installed():
         ui.success(f"{tool.name} is already installed: {tool.get_version()}")
         return True
+    missing = registry.missing_requires(tool)
+    if missing:
+        ui.error(f"Cannot install {tool.name} — missing required tools: {', '.join(missing)}")
+        ui.dim(f"Install first:  dev-setup install {' '.join(missing)}")
+        return False
     try:
         version = tool.install()
         msg = f"{tool.name} installed"
@@ -50,17 +59,20 @@ def _install_interactive() -> None:
     ui.print_banner()
     tools = registry.all_tools()
 
-    choices = [
-        questionary.Choice(
-            title=(
-                f"{'[installed] ' if t.is_installed() else ''}"
-                f"{t.key:<14} {t.description}"
-            ),
+    choices = []
+    for t in tools:
+        is_inst = t.is_installed()
+        missing = registry.missing_requires(t) if not is_inst else []
+        label = (
+            f"{'[installed] ' if is_inst else ''}"
+            f"{t.key:<14} {t.description}"
+        )
+        choices.append(questionary.Choice(
+            title=label,
             value=t.key,
             checked=False,
-        )
-        for t in tools
-    ]
+            disabled=f"requires {', '.join(missing)}" if missing else False,
+        ))
 
     selected = questionary.checkbox(
         "Select packages to install  (Space to toggle, Enter to confirm):",

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/list_cmd.py

@@ -31,7 +31,8 @@ def list_cmd(show_filter: str, category: str) -> None:
         ui.warn("No packages match the given filters.")
         return
 
-    for cat in ("core", "tools", "custom"):
+    _ORDER = {"core": 0, "tools": 1, "custom": 999}
+    for cat in sorted(by_cat, key=lambda c: (_ORDER.get(c, 500), c)):
         entries = by_cat.get(cat, [])
         if not entries:
             continue
@@ -47,11 +48,14 @@ def list_cmd(show_filter: str, category: str) -> None:
         tbl.add_column("Version", style="dim")
 
         for tool, is_inst in entries:
+            missing = registry.missing_requires(tool) if not is_inst else []
             icon = "[green bold]✔[/]" if is_inst else "[red bold]✘[/]"
             version = tool.get_version() if is_inst else ""
             tbl.add_row(icon, tool.key, tool.description, tool.install_type, version)
             if tool.help_cmd:
                 tbl.add_row("", "", f"[dim cyan]  ? {tool.help_cmd}[/]", "", "")
+            if missing:
+                tbl.add_row("", "", f"[yellow]  ⚠ requires: {', '.join(missing)}[/]", "", "")
 
         ui.console.print(tbl)
         ui.console.print()

{dev_setup-1.1.0 → dev_setup-1.4.0}/src/dev_setup/commands/remove_cmd.py

@@ -10,9 +10,13 @@ from dev_setup.base import Tool
 
 
 @click.command("remove")
+@click.option("--verbose", "-v", is_flag=True, help="Stream removal output to the terminal.")
 @click.argument("packages", nargs=-1)
-def remove_cmd(packages: Tuple[str, ...]) -> None:
+def remove_cmd(packages: Tuple[str, ...], verbose: bool) -> None:
     """Uninstall installed packages."""
+    from dev_setup import generic
+    generic._verbose = verbose
+
     if not packages:
         ui.error("Specify at least one package key. See: dev-setup list --installed")
         sys.exit(1)