devstuff 1.13.1__py3-none-any.whl

dev_setup/__init__.py

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

dev_setup/__main__.py

@@ -0,0 +1,9 @@
+from dev_setup.cli import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

dev_setup/base.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class Tool(ABC):
+    key: str = ""
+    name: str = ""
+    description: str = ""
+    category: str = "custom"
+    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: ...
+
+    @abstractmethod
+    def install(self) -> str | None:
+        """Install the tool. Return version string if available. Raise on failure."""
+        ...
+
+    @abstractmethod
+    def remove(self) -> None:
+        """Uninstall the tool. Raise on failure."""
+        ...
+
+    def get_version(self) -> str:
+        return ""
+
+
+def patch_bashrc(block_name: str, content: str) -> bool:
+    """Idempotently append a named block to ~/.bashrc. Returns True if added."""
+    bashrc = Path.home() / ".bashrc"
+    marker = f"# {block_name}"
+
+    if bashrc.exists() and marker in bashrc.read_text():
+        return False
+
+    with bashrc.open("a") as f:
+        f.write(f"\n{marker}\n{content}\n")
+    return True
+
+
+def remove_bashrc_block(block_name: str) -> bool:
+    """Remove a named block (and the line after the marker) from ~/.bashrc."""
+    bashrc = Path.home() / ".bashrc"
+    if not bashrc.exists():
+        return False
+
+    lines = bashrc.read_text().splitlines(keepends=True)
+    marker = f"# {block_name}"
+    out = []
+    i = 0
+    removed = False
+    while i < len(lines):
+        stripped = lines[i].rstrip()
+        if stripped == marker:
+            i += 1
+            while i < len(lines) and lines[i].strip():
+                i += 1
+            if i < len(lines) and not lines[i].strip():
+                i += 1
+            removed = True
+        else:
+            out.append(lines[i])
+            i += 1
+
+    if removed:
+        bashrc.write_text("".join(out))
+    return removed

dev_setup/catalog.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import copy
+import re
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+CONFIG_DIR = Path.home() / ".config" / "dev-setup"
+USER_CATALOG_PATH = CONFIG_DIR / "tools.yaml"
+BUNDLED_CATALOG = "tools.yaml"
+
+VERSION = 1
+VALID_KEY = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+SUPPORTED_FIELDS = {
+    "name",
+    "description",
+    "category",
+    "type",
+    "check_cmd",
+    "version_cmd",
+    "help_cmd",
+    "docs_url",
+    "requires",
+    "npm_name",
+    "pip_name",
+    "apt_packages",
+    "git_url",
+    "git_install_cmd",
+    "git_remove_cmd",
+    "script_url",
+    "sha256",
+    "install_script",
+    "remove_script",
+}
+
+
+class CatalogError(RuntimeError):
+    pass
+
+
+def bundled_catalog_path() -> str:
+    return f"dev_setup/{BUNDLED_CATALOG}"
+
+
+def load_catalog_file(path: Path, *, required: bool = False) -> dict[str, dict[str, Any]]:
+    if not path.exists():
+        if required:
+            raise CatalogError(f"Catalog file not found: {path}")
+        return {}
+
+    try:
+        raw = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError as exc:
+        raise CatalogError(f"Invalid YAML in {path}: {exc}") from exc
+
+    return validate_catalog(raw, source=path)
+
+
+def validate_catalog(raw: Any, *, source: Path | str = "<catalog>") -> dict[str, dict[str, Any]]:
+    if not isinstance(raw, dict):
+        raise CatalogError(f"{source}: catalog must be a mapping")
+    if raw.get("version") != VERSION:
+        raise CatalogError(f"{source}: version must be {VERSION}")
+
+    tools = raw.get("tools")
+    if tools is None:
+        return {}
+    if not isinstance(tools, dict):
+        raise CatalogError(f"{source}: tools must be a mapping")
+
+    validated: dict[str, dict[str, Any]] = {}
+    for key, data in tools.items():
+        if not isinstance(key, str) or not VALID_KEY.match(key):
+            raise CatalogError(f"{source}: invalid tool key {key!r}")
+        if not isinstance(data, dict):
+            raise CatalogError(f"{source}: tool {key!r} must be a mapping")
+
+        unknown = sorted(set(data) - SUPPORTED_FIELDS)
+        if unknown:
+            fields = ", ".join(unknown)
+            raise CatalogError(f"{source}: tool {key!r} has unknown field(s): {fields}")
+
+        item = copy.deepcopy(data)
+        item.setdefault("name", key)
+        item.setdefault("description", "")
+        item.setdefault("category", "custom")
+        item.setdefault("type", "unknown")
+
+        requires = item.get("requires")
+        if requires is None:
+            if item["type"] == "npm":
+                item["requires"] = ["nvm"]
+            elif item["type"] in ("pip", "uvx"):
+                item["requires"] = ["uv"]
+            else:
+                item["requires"] = []
+        elif not isinstance(requires, list) or not all(isinstance(v, str) for v in requires):
+            raise CatalogError(f"{source}: tool {key!r} requires must be a list of strings")
+
+        validated[key] = item
+
+    return validated
+
+
+def catalog_document(tools: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    return {"version": VERSION, "tools": tools}
+
+
+def read_user_catalog() -> dict[str, dict[str, Any]]:
+    return load_catalog_file(USER_CATALOG_PATH)
+
+
+def write_user_catalog(tools: dict[str, dict[str, Any]]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    USER_CATALOG_PATH.write_text(_dump(catalog_document(tools)))
+
+
+def load_bundled_catalog() -> dict[str, dict[str, Any]]:
+    resource = resources.files("dev_setup").joinpath(BUNDLED_CATALOG)
+    try:
+        raw = yaml.safe_load(resource.read_text()) or {}
+    except FileNotFoundError as exc:
+        raise CatalogError(f"Catalog file not found: {bundled_catalog_path()}") from exc
+    except yaml.YAMLError as exc:
+        raise CatalogError(f"Invalid YAML in {bundled_catalog_path()}: {exc}") from exc
+    return validate_catalog(raw, source=bundled_catalog_path())
+
+
+def load_effective_catalog() -> tuple[
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+    dict[str, dict[str, Any]],
+]:
+    bundled = load_bundled_catalog()
+    user = read_user_catalog()
+    effective = merge_catalogs(bundled, user)
+    return effective, bundled, user
+
+
+def merge_catalogs(
+    bundled: dict[str, dict[str, Any]],
+    user: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    merged = copy.deepcopy(bundled)
+    for key, data in user.items():
+        merged[key] = copy.deepcopy(data)
+    return merged
+
+
+def save_user_tool(key: str, data: dict[str, Any]) -> None:
+    validate_catalog(catalog_document({key: data}), source=USER_CATALOG_PATH)
+    user = read_user_catalog()
+    user[key] = copy.deepcopy(data)
+    write_user_catalog(user)
+
+
+def delete_user_tool(key: str) -> bool:
+    user = read_user_catalog()
+    if key not in user:
+        return False
+    del user[key]
+    write_user_catalog(user)
+    return True
+
+
+def user_has_tool(key: str) -> bool:
+    return key in read_user_catalog()
+
+
+def import_catalog(path: Path) -> list[str]:
+    incoming = load_catalog_file(path, required=True)
+    user = read_user_catalog()
+    for key, data in incoming.items():
+        user[key] = copy.deepcopy(data)
+    write_user_catalog(user)
+    return list(incoming)
+
+
+def export_catalog(path: Path) -> None:
+    effective, _bundled, _user = load_effective_catalog()
+    path.write_text(_dump(catalog_document(effective)))
+
+
+def _dump(data: dict[str, Any]) -> str:
+    return yaml.safe_dump(data, sort_keys=False, default_flow_style=False)

dev_setup/cli.py

@@ -0,0 +1,49 @@
+import click
+
+from dev_setup import __version__
+
+
+@click.group(
+    invoke_without_command=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    if ctx.invoked_subcommand is None:
+        from dev_setup.commands.help_cmd import print_help
+        print_help()
+
+
+@cli.command("version")
+def version_cmd() -> None:
+    """Print version and exit."""
+    click.echo(f"devstuff {__version__}")
+
+
+def _register_commands() -> None:
+    from dev_setup.commands.add_cmd import add_cmd
+    from dev_setup.commands.catalog_cmd import catalog_cmd
+    from dev_setup.commands.delete_cmd import delete_cmd
+    from dev_setup.commands.docs_cmd import docs_cmd
+    from dev_setup.commands.functions_cmd import functions_cmd
+    from dev_setup.commands.install_cmd import install_cmd
+    from dev_setup.commands.list_cmd import list_cmd
+    from dev_setup.commands.remove_cmd import remove_cmd
+    from dev_setup.commands.run_cmd import run_cmd
+    from dev_setup.commands.update_cmd import update_cmd
+
+    cli.add_command(list_cmd, "list")
+    cli.add_command(install_cmd, "install")
+    cli.add_command(remove_cmd, "remove")
+    cli.add_command(remove_cmd, "uninstall")
+    cli.add_command(update_cmd, "update")
+    cli.add_command(add_cmd, "add")
+    cli.add_command(delete_cmd, "delete")
+    cli.add_command(delete_cmd, "rm")
+    cli.add_command(docs_cmd, "docs")
+    cli.add_command(catalog_cmd, "catalog")
+    cli.add_command(run_cmd, "run")
+    cli.add_command(functions_cmd, "functions")
+
+
+_register_commands()

dev_setup/commands/add_cmd.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import re
+
+import click
+
+from dev_setup import registry, ui
+from dev_setup.generic import GenericTool
+
+_VALID_KEY = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+_INSTALL_TEMPLATE = """\
+#!/usr/bin/env bash
+# Install script for {name}
+# Save and close to continue. Delete all content (except this line) to abort.
+set -euo pipefail
+
+"""
+
+_REMOVE_TEMPLATE = """\
+#!/usr/bin/env bash
+# Remove script for {name}
+# Save and close to continue. Leave only comments/blank lines to skip removal.
+set -euo pipefail
+
+"""
+
+
+@click.command("add")
+def add_cmd() -> None:
+    """Add a custom package via guided wizard."""
+    ui.section("Add Custom Package")
+
+    install_type = ui.select(
+        "Package type:",
+        ["npm", "uvx", "apt", "git", "script", "bash"],
+    )
+    if not install_type:
+        ui.warn("Aborted.")
+        return
+
+    key = _prompt_key()
+    if not key:
+        return
+
+    name = ui.text_input("Display name:", default=key, required=True)
+    description = ui.text_input("Short description:", required=False)
+
+    kwargs: dict = dict(
+        key=key,
+        name=name,
+        description=description,
+        category="custom",
+        install_type=install_type,
+    )
+
+    if install_type == "npm":
+        kwargs["npm_name"] = ui.text_input("npm package name:", default=key, required=True)
+        kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
+
+    elif install_type == "uvx":
+        kwargs["pip_name"] = ui.text_input("PyPI package name:", default=key, required=True)
+        kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
+
+    elif install_type == "apt":
+        kwargs["apt_packages"] = ui.text_input(
+            "apt package(s) (space-separated):", default=key, required=True
+        )
+        kwargs["check_cmd"] = ui.text_input("Command to check if installed:", default=key)
+
+    elif install_type == "git":
+        kwargs["git_url"] = ui.text_input("Git repository URL:", required=True)
+        kwargs["git_install_cmd"] = ui.text_input(
+            "Post-clone install command (optional, run inside repo):", required=False
+        )
+        kwargs["git_remove_cmd"] = ui.text_input(
+            "Pre-delete remove command (optional):", required=False
+        )
+        kwargs["check_cmd"] = ui.text_input("Command to check if installed:", required=False)
+
+    elif install_type == "script":
+        kwargs["script_url"] = ui.text_input("Install script URL (curl | sh):", required=True)
+        kwargs["check_cmd"] = ui.text_input("Command to check if installed:", required=False)
+
+    elif install_type == "bash":
+        kwargs["check_cmd"] = ui.text_input(
+            "Command to verify installation (e.g. bat, aws):", required=False
+        )
+        install_script = _edit_script("install", name, required=True)
+        if install_script is None:
+            ui.warn("No install script provided — aborted.")
+            return
+        kwargs["install_script"] = install_script
+
+        remove_script = _edit_script("remove", name, required=False)
+        remove_script = _validate_remove_script(
+            remove_script or "",
+            install_script,
+            kwargs.get("check_cmd", ""),
+            name,
+        )
+        if remove_script:
+            kwargs["remove_script"] = remove_script
+
+    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[/]")
+    for k, v in kwargs.items():
+        if v:
+            display = _truncate_script(v) if k.endswith("_script") else v
+            ui.console.print(f"  [dim]{k:<18}[/] {display}")
+    ui.console.print()
+
+    if not ui.confirm("Save this package?"):
+        ui.warn("Aborted — package not saved.")
+        return
+
+    tool = GenericTool(**kwargs)
+    tool.save()
+
+    from dev_setup import registry
+    registry.register(tool)
+
+    ui.success(f"Package '{key}' added. Install with: devstuff install {key}")
+
+
+def _prompt_key() -> str:
+    while True:
+        key = ui.text_input("Package key (lowercase, hyphens ok):", required=True)
+        if not _VALID_KEY.match(key):
+            ui.error("Key must be lowercase letters, digits, hyphens, or underscores.")
+            continue
+        if registry.exists(key):
+            ui.error(f"A package with key '{key}' already exists.")
+            if not ui.confirm("Use a different key?"):
+                return ""
+            continue
+        return key
+
+
+def _edit_script(
+    action: str,
+    package_name: str,
+    required: bool = True,
+    prefill: str = "",
+    quiet: bool = False,
+) -> str | None:
+    """Open $EDITOR with a bash template. Returns stripped script or None if aborted."""
+    if prefill:
+        template = prefill
+    else:
+        template = (_INSTALL_TEMPLATE if action == "install" else _REMOVE_TEMPLATE).format(
+            name=package_name
+        )
+    if not quiet:
+        label = "install" if action == "install" else "remove (optional)"
+        ui.console.print()
+        ui.info(f"Opening $EDITOR for the [bold]{label}[/] script...")
+        ui.dim("Write your bash commands, save, and close the editor to continue.")
+        ui.console.print()
+
+    try:
+        content = click.edit(text=template, extension=".sh", require_save=False)
+    except Exception as exc:
+        ui.error(f"Could not open editor: {exc}")
+        ui.dim("Set the EDITOR environment variable (e.g. export EDITOR=nano) and try again.")
+        return None
+
+    if content is None:
+        return None
+
+    script = _strip_template_comments(content)
+    if not script and required:
+        ui.error("Install script cannot be empty.")
+        return None
+    return script or ""
+
+
+def _strip_template_comments(content: str) -> str:
+    """Remove comment-only lines and leading/trailing blank lines."""
+    lines = [
+        line for line in content.splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+    return "\n".join(lines).strip()
+
+
+def _is_safe_literal_path(path: str) -> bool:
+    """Return True only for fully literal paths — no shell expansion or injection chars."""
+    return not any(c in path for c in ('$', '`', '(', ')', ';', '&', '|', ' ', '"', "'", '\\'))
+
+
+def _extract_installed_paths(install_script: str) -> list[str]:
+    """Find definitive binary install destinations (literal paths only)."""
+    paths: list[str] = []
+
+    # curl ... -o /path/binary
+    for m in re.finditer(r'\bcurl\b[^|\n]*?-o\s+(\S+)', install_script):
+        p = m.group(1).strip()
+        if (
+            p.startswith(("/", "~/"))
+            and _is_safe_literal_path(p)
+            and not p.endswith(('.sh', '.tar.gz', '.zip', '.tmp', '.tar', '.bz2', '.gz'))
+        ):
+            paths.append(p)
+
+    # sudo mv /tmp/x /usr/local/bin/y  — destination only
+    for m in re.finditer(
+        r'\bmv\s+\S+\s+((?:/usr|/opt)[\w./+-]*)', install_script
+    ):
+        p = m.group(1).strip()
+        if _is_safe_literal_path(p) and "." not in p.split("/")[-1]:
+            paths.append(p)
+
+    return list(dict.fromkeys(paths))
+
+
+def _suggest_remove_script(install_script: str, check_cmd: str, name: str) -> str:
+    """Generate a best-effort remove script from patterns in the install script."""
+    svc_lines: list[str] = []
+    actions: list[str] = []
+
+    # systemd service teardown (must precede file removal)
+    for m in re.finditer(r'\bsystemctl\s+(?:enable|start)\s+(\S+)', install_script):
+        svc = m.group(1).rstrip(";")
+        if not any(svc in a for a in svc_lines):
+            svc_lines.append(f"sudo systemctl stop {svc} 2>/dev/null || true")
+            svc_lines.append(f"sudo systemctl disable {svc} 2>/dev/null || true")
+
+    # apt packages
+    apt_packages: list[str] = []
+    for m in re.finditer(r'\bapt(?:-get)?\s+install\s+(?:-y\s+)?(.+)', install_script):
+        for pkg in m.group(1).split():
+            if not pkg.startswith("-") and pkg not in apt_packages:
+                apt_packages.append(pkg)
+    if apt_packages:
+        actions.append(f"sudo apt-get remove -y {' '.join(apt_packages)}")
+
+    # Binary paths from curl / mv (skip /tmp — temp downloads are gone after mv)
+    for path in _extract_installed_paths(install_script):
+        if path.startswith("/tmp/"):
+            continue
+        prefix = "sudo " if path.startswith(("/usr/", "/opt/", "/etc/")) else ""
+        actions.append(f"{prefix}rm -rf {path}")
+
+    # Fallback: derive removal from check_cmd if nothing else found
+    if not actions and not svc_lines and check_cmd:
+        actions.append(f'CMD=$(command -v {check_cmd} 2>/dev/null || true)')
+        actions.append('[ -n "$CMD" ] && sudo rm -f "$CMD"')
+
+    if not svc_lines and not actions:
+        return ""
+
+    lines = ["#!/usr/bin/env bash", "set -euo pipefail", ""] + svc_lines + actions
+    return "\n".join(lines)
+
+
+def _remove_needs_review(remove_script: str, install_script: str) -> bool:
+    """Return True when the remove script warrants a review prompt."""
+    if not remove_script.strip():
+        return True
+
+    installed_paths = _extract_installed_paths(install_script)
+    if not installed_paths:
+        return False  # can't tell — don't be noisy
+
+    def _references_target(path: str) -> bool:
+        parts = [p for p in path.rstrip("/").split("/") if p]
+        candidates = [path]
+        if parts:
+            candidates.append(parts[-1])  # basename
+        for i in range(2, len(parts)):  # ancestor dirs
+            candidates.append("/" + "/".join(parts[:i]))
+        return any(c in remove_script for c in candidates)
+
+    # Flag only when NONE of the detected targets is referenced
+    return not any(_references_target(p) for p in installed_paths)
+
+
+def _validate_remove_script(
+    remove_script: str,
+    install_script: str,
+    check_cmd: str,
+    name: str,
+) -> str:
+    """If the remove script looks empty or mismatched, offer a recommended alternative."""
+    if not _remove_needs_review(remove_script, install_script):
+        return remove_script
+
+    recommended = _suggest_remove_script(install_script, check_cmd, name)
+
+    ui.console.print()
+    if not remove_script.strip():
+        ui.warn("Remove script is empty — uninstalling will fail without one.")
+    else:
+        ui.warn("Remove script may not undo the installation (possible path mismatch).")
+
+    if recommended:
+        ui.console.print()
+        ui.info("Suggested remove script:")
+        ui.console.print()
+        ui.code_block(recommended)
+        ui.console.print()
+
+    choices: list[str] = []
+    if recommended:
+        choices.append("Use recommended")
+    choices.append("Keep mine (empty)" if not remove_script.strip() else "Keep mine")
+    choices.append("Edit manually")
+
+    choice = ui.select("How would you like to proceed?", choices)
+
+    if choice == "Use recommended":
+        return _strip_template_comments(recommended)
+    if choice == "Edit manually":
+        prefill = recommended or remove_script or _REMOVE_TEMPLATE.format(name=name)
+        edited = _edit_script("remove", name, required=False, prefill=prefill, quiet=True)
+        return edited if edited is not None else remove_script
+    return remove_script  # "Keep mine" / "Keep mine (empty)"
+
+
+def _truncate_script(script: str) -> str:
+    lines = [ln for ln in script.splitlines() if ln.strip()]
+    if not lines:
+        return "[dim](empty)[/]"
+    first = lines[0][:60]
+    suffix = f"  [dim]+{len(lines) - 1} more lines[/]" if len(lines) > 1 else ""
+    return f"{first}{suffix}"