devstuff 1.13.1__py3-none-any.whl

dev_setup/commands/catalog_cmd.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from dev_setup import catalog, ui
+
+
+@click.group("catalog")
+def catalog_cmd() -> None:
+    """Manage YAML tool catalogs."""
+
+
+@catalog_cmd.command("path")
+def path_cmd() -> None:
+    """Print the user catalog path."""
+    click.echo(catalog.USER_CATALOG_PATH)
+
+
+@catalog_cmd.command("export")
+@click.argument("path", required=False, type=click.Path(path_type=Path))
+def export_cmd(path: Path | None) -> None:
+    """Export the effective catalog to PATH."""
+    out = path or Path("dev-setup-tools.yaml")
+    catalog.export_catalog(out)
+    ui.success(f"Exported catalog to {out}")
+
+
+@catalog_cmd.command("import")
+@click.argument("path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def import_cmd(path: Path) -> None:
+    """Import and merge a YAML catalog into the user catalog."""
+    keys = catalog.import_catalog(path)
+    ui.success(f"Imported {len(keys)} package(s) into {catalog.USER_CATALOG_PATH}")
+
+

dev_setup/commands/delete_cmd.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from dev_setup import catalog, registry, ui
+
+
+@click.command("delete")
+@click.argument("key")
+def delete_cmd(key: str) -> None:
+    """Remove a custom package from the registry."""
+    if not registry.exists(key):
+        ui.error(f"No package with key '{key}' found.")
+        sys.exit(1)
+
+    tool = registry.get(key)
+    assert tool is not None
+
+    if not catalog.user_has_tool(key):
+        ui.error(f"'{key}' is a built-in package and cannot be deleted.")
+        sys.exit(1)
+
+    ui.console.print(f"\n  [bold]{tool.name}[/] — {tool.description}\n")
+
+    if not ui.confirm(f"Delete user catalog entry '{key}'?", default=False):
+        ui.dim("Aborted.")
+        return
+
+    catalog.delete_user_tool(key)
+    registry.reload()
+    if registry.exists(key):
+        ui.success(f"User override for '{key}' removed — built-in version is now active.")
+    else:
+        ui.success(f"Package '{key}' deleted from user catalog.")

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, add docs_url in your YAML catalog.")
+        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/commands/functions_cmd.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from dev_setup import function_runner as runner
+from dev_setup import functions_registry, ui
+from dev_setup.functions_catalog import USER_CATALOG_PATH
+
+
+@click.group("functions")
+def functions_cmd() -> None:
+    """Manage functions/scripts. Invoke one with: devstuff run <key>."""
+
+
+@functions_cmd.command("list")
+def list_cmd() -> None:
+    """List available functions."""
+    fns = functions_registry.all_functions()
+    if not fns:
+        ui.info("No functions defined.")
+        return
+
+    by_cat: dict[str, list] = {}
+    for f in fns:
+        by_cat.setdefault(f.category, []).append(f)
+
+    key_width = max((len(f.key) for f in fns), default=12) + 2
+    for cat in sorted(by_cat, key=lambda c: (c == "custom", c)):
+        ui.console.print(f"\n  [bold]{cat.upper()}[/]")
+        for f in sorted(by_cat[cat], key=lambda f: f.key):
+            mode = f.type if f.type == "script" else f"{f.type} ({f.register})"
+            ui.console.print(
+                f"  [bold cyan]{f.key:<{key_width}}[/] [dim]{mode:<22}[/] {f.description}"
+            )
+            params = " ".join(f"<{p.name}>" for p in f.params)
+            if params:
+                ui.dim(f"    args: {params}")
+
+
+@functions_cmd.command("enable")
+@click.argument("key")
+def enable_cmd(key: str) -> None:
+    """Register a bashrc-backed function into ~/.bashrc."""
+    fn = functions_registry.get(key)
+    if fn is None:
+        ui.error(f"Unknown function: '{key}'")
+        sys.exit(1)
+    if not (fn.type == "shell-eval" and fn.register == "bashrc"):
+        ui.error(f"'{fn.key}' does not use bashrc registration.")
+        if fn.type == "script":
+            ui.dim(f"Run it directly:  devstuff run {fn.key}")
+        else:
+            ui.dim(f'Use:  eval "$(devstuff run {fn.key} ...)"')
+        sys.exit(1)
+
+    added = runner.enable_bashrc_function(fn)
+    if added:
+        ui.success(f"Registered '{fn.key}' in ~/.bashrc")
+        ui.dim("Run: source ~/.bashrc   (or open a new shell)")
+        args = " ".join(f"<{p.name}>" for p in fn.params)
+        ui.dim(f"Then call it directly:  {fn.key} {args}".rstrip())
+    else:
+        ui.info(f"'{fn.key}' is already registered in ~/.bashrc")
+
+
+@functions_cmd.command("disable")
+@click.argument("key")
+def disable_cmd(key: str) -> None:
+    """Remove a bashrc-backed function from ~/.bashrc."""
+    fn = functions_registry.get(key)
+    if fn is None:
+        ui.error(f"Unknown function: '{key}'")
+        sys.exit(1)
+
+    removed = runner.disable_bashrc_function(fn)
+    if removed:
+        ui.success(f"Removed '{fn.key}' from ~/.bashrc")
+    else:
+        ui.info(f"'{fn.key}' is not registered in ~/.bashrc")
+
+
+@functions_cmd.command("path")
+def path_cmd() -> None:
+    """Print the path to the user functions catalog."""
+    click.echo(str(USER_CATALOG_PATH))

dev_setup/commands/help_cmd.py

@@ -0,0 +1,59 @@
+from dev_setup import ui
+from dev_setup.catalog import USER_CATALOG_PATH
+
+
+def print_help() -> None:
+    ui.print_banner()
+    ui.console.print("[bold]USAGE[/]")
+    ui.console.print("  devstuff [bold cyan]<command>[/] [OPTIONS] [ARGS]\n")
+
+    ui.console.print("[bold]COMMANDS[/]")
+    rows = [
+        ("list",    "[--installed] [--available] [category]", "List packages"),
+        ("install", "[package ...]",                          "Install packages (interactive if no args)"),
+        ("remove",  "<package ...>",                          "Uninstall installed packages"),
+        ("update",  "[package ...] [--version]",              "Update packages (interactive if no args)"),
+        ("add",     "",                                        "Add a custom package (guided wizard)"),
+        ("delete",  "<key>",                                  "Remove a custom package from the registry"),
+        ("catalog", "<path|export|import>",                   "Manage YAML tool catalogs"),
+        ("docs",    "<package>",                              "Open documentation in browser"),
+        ("run",     "<function> [args...]",                   "Run a function/script"),
+        ("functions", "<list|enable|disable|path>",           "Manage functions/scripts"),
+        ("version", "",                                        "Show version"),
+    ]
+    for cmd, args, desc in rows:
+        ui.console.print(
+            f"  [bold cyan]{cmd:<10}[/] [dim]{args:<40}[/]  {desc}"
+        )
+
+    ui.console.print()
+    ui.console.print("[bold]EXAMPLES[/]")
+    examples = [
+        "devstuff list",
+        "devstuff list core",
+        "devstuff list --installed",
+        "devstuff install docker nvm",
+        "devstuff install",
+        "devstuff remove htop",
+        "devstuff update nvm",
+        "devstuff update pi --version 1.2.3",
+        "devstuff update",
+        "devstuff add",
+        "devstuff delete my-tool",
+        "devstuff catalog export",
+        "devstuff functions list",
+        "devstuff functions enable ssh-agent-key",
+        "ssh-agent-key ~/.ssh/id_ed25519",
+    ]
+    for ex in examples:
+        ui.console.print(f"  [dim]$[/] [green]{ex}[/]")
+
+    ui.console.print()
+    ui.console.print("[bold]CATEGORIES[/]")
+    ui.console.print("  [cyan]core[/]    Always-installed tools (Docker, NVM, uv)")
+    ui.console.print("  [cyan]tools[/]   Optional utilities (PHP, Starship, htop)")
+    ui.console.print("  [cyan]languages[/] Programming language runtimes")
+    ui.console.print("  [cyan]custom[/]  User-added packages\n")
+
+    ui.console.print("[bold]CONFIG[/]")
+    ui.console.print(f"  User catalog: [dim]{USER_CATALOG_PATH}[/]\n")

dev_setup/commands/install_cmd.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+import click
+import questionary
+
+from dev_setup import registry, ui
+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, ...], 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:
+        failed = False
+        for key in packages:
+            if not registry.exists(key):
+                ui.error(f"Unknown package: '{key}'")
+                failed = True
+                continue
+            if not _install_one(registry.get(key)):  # type: ignore[arg-type]
+                failed = True
+        if failed:
+            sys.exit(1)
+
+
+def _install_one(tool: Tool) -> bool:
+    ui.section(tool.name)
+    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:  devstuff install {' '.join(missing)}")
+        return False
+    try:
+        version = tool.install()
+        msg = f"{tool.name} installed"
+        if version:
+            msg += f": {version}"
+        ui.success(msg)
+        return True
+    except Exception as exc:
+        ui.error(f"Failed to install {tool.name}: {exc}")
+        return False
+
+
+def _install_interactive() -> None:
+    ui.print_banner()
+    tools = registry.all_tools()
+
+    # Probe installed status concurrently — each check shells out.
+    with ui.spinner("Checking installed packages..."), ThreadPoolExecutor(max_workers=8) as pool:
+        statuses = pool.map(lambda t: t.is_installed(), tools)
+        installed = dict(zip((t.key for t in tools), statuses, strict=True))
+
+    by_cat: dict[str, list[Tool]] = {}
+    for t in tools:
+        by_cat.setdefault(t.category, []).append(t)
+
+    key_width = max((len(t.key) for t in tools), default=12) + 2
+    desc_width = max(20, ui.console.width - key_width - 14)
+
+    choices: list = []
+    _ORDER = {"core": 0, "tools": 1, "custom": 999}
+    for cat in sorted(by_cat, key=lambda c: (_ORDER.get(c, 500), c)):
+        entries = sorted(by_cat[cat], key=lambda t: t.key)
+        n_inst = sum(installed[t.key] for t in entries)
+        choices.append(questionary.Separator(
+            f"\n  {cat.upper()}  ({n_inst}/{len(entries)} installed)"
+        ))
+        for t in entries:
+            is_inst = installed[t.key]
+            missing = [] if is_inst else registry.missing_requires(t)
+            desc = t.description
+            if len(desc) > desc_width:
+                desc = desc[: desc_width - 1] + "…"
+            if is_inst:
+                disabled = True
+            elif missing:
+                disabled = f"requires {', '.join(missing)}"
+            else:
+                disabled = None
+            title = [
+                ("class:check", "✔ " if is_inst else "  "),
+                ("class:text", f"{t.key:<{key_width}}{desc}"),
+            ]
+            choices.append(questionary.Choice(
+                title=title,
+                value=t.key,
+                checked=False,
+                disabled=disabled,
+            ))
+
+    selected = questionary.checkbox(
+        "Select packages to install:",
+        choices=choices,
+        instruction="(Space toggle · Enter confirm · installed items are skipped)",
+        style=ui._STYLE,
+    ).ask()
+
+    if not selected:
+        ui.info("No packages selected.")
+        return
+
+    to_install = selected
+
+    if not ui.confirm(f"Install {len(to_install)} package(s)?"):
+        ui.warn("Aborted.")
+        return
+
+    failed = False
+    for key in to_install:
+        tool = registry.get(key)
+        if tool and not _install_one(tool):
+            failed = True
+
+    if failed:
+        sys.exit(1)

dev_setup/commands/list_cmd.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+
+import click
+from rich.table import Table
+
+from dev_setup import registry, ui
+from dev_setup.base import Tool
+
+_MAX_WORKERS = 8
+
+
+def _probe(tool: Tool) -> tuple[Tool, bool, str]:
+    """Gather subprocess-heavy status for one tool (runs in a worker thread)."""
+    is_inst = tool.is_installed()
+    version = tool.get_version() if is_inst else ""
+    return tool, is_inst, version
+
+
+@click.command("list")
+@click.option("--installed", "show_filter", flag_value="installed", help="Show only installed packages")
+@click.option("--available", "show_filter", flag_value="available", help="Show only uninstalled packages")
+@click.argument("category", required=False)
+def list_cmd(show_filter: str, category: str) -> None:
+    """List available packages."""
+    ui.print_banner()
+
+    tools = registry.all_tools()
+    if category:
+        tools = [t for t in tools if t.category == category]
+
+    # Probe installed status + version concurrently — each check shells out,
+    # so this dominates the command's runtime when done serially.
+    with ThreadPoolExecutor(max_workers=_MAX_WORKERS) as pool:
+        probed = list(pool.map(_probe, tools))
+
+    by_cat: dict = {}
+    for tool, is_inst, version in probed:
+        if show_filter == "installed" and not is_inst:
+            continue
+        if show_filter == "available" and is_inst:
+            continue
+        by_cat.setdefault(tool.category, []).append((tool, is_inst, version))
+
+    if not by_cat:
+        ui.warn("No packages match the given filters.")
+        return
+
+    _ORDER = {"core": 0, "tools": 1, "custom": 999}
+    for cat in sorted(by_cat, key=lambda c: (_ORDER.get(c, 500), c)):
+        entries = sorted(by_cat.get(cat, []), key=lambda e: e[0].key)
+        if not entries:
+            continue
+
+        ui.console.print(f"  [bold magenta]{cat.upper()}[/]")
+        ui.divider()
+
+        tbl = Table(box=None, padding=(0, 1), show_header=True, header_style="dim")
+        tbl.add_column("", width=2)
+        tbl.add_column("Package", style="bold", min_width=12)
+        tbl.add_column("Description", min_width=36)
+        tbl.add_column("Type", style="dim", min_width=8)
+        tbl.add_column("Version", style="dim")
+
+        for tool, is_inst, version in entries:
+            missing = registry.missing_requires(tool) if not is_inst else []
+            icon = "[green bold]✔[/]" if is_inst else "[red bold]✘[/]"
+            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/commands/remove_cmd.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from dev_setup import registry, ui
+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, ...], 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: devstuff list --installed")
+        sys.exit(1)
+
+    failed = False
+    for key in packages:
+        if not registry.exists(key):
+            ui.error(f"Unknown package: '{key}'")
+            failed = True
+            continue
+        if not _remove_one(registry.get(key)):  # type: ignore[arg-type]
+            failed = True
+
+    if failed:
+        sys.exit(1)
+
+
+def _remove_one(tool: Tool) -> bool:
+    ui.section(f"Remove {tool.name}")
+
+    if not tool.is_installed():
+        ui.warn(f"{tool.name} is not installed — nothing to remove.")
+        return True
+
+    if not ui.confirm(f"Remove {tool.name}?", default=False):
+        ui.dim("Skipped.")
+        return True
+
+    try:
+        tool.remove()
+        ui.success(f"{tool.name} removed")
+        return True
+    except Exception as exc:
+        ui.error(f"Failed to remove {tool.name}: {exc}")
+        return False

dev_setup/commands/run_cmd.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import sys
+
+import click
+
+from dev_setup import function_runner as runner
+from dev_setup import functions_registry, ui
+from dev_setup.function_runner import ParamResolutionError
+from dev_setup.functions_registry import FunctionDef, FunctionParam
+
+
+@click.command("run")
+@click.argument("key")
+@click.argument("args", nargs=-1)
+def run_cmd(key: str, args: tuple[str, ...]) -> None:
+    """Run a function/script. See: devstuff functions list"""
+    fn = functions_registry.get(key)
+    if fn is None:
+        ui.error(f"Unknown function: '{key}'")
+        sys.exit(1)
+
+    if fn.type == "script":
+        _run_script(fn, args)
+    elif fn.type == "shell-eval" and fn.register == "eval":
+        _run_eval(fn, args)
+    else:  # shell-eval + bashrc — dev-setup can't mutate the calling shell itself
+        ui.error(f"'{fn.key}' is registered via ~/.bashrc, not run directly.")
+        ui.dim(f"Enable it once:  devstuff functions enable {fn.key}")
+        ui.dim(f"Then call it directly in your shell:  {fn.key} ...")
+        sys.exit(1)
+
+
+def _prompt_param(p: FunctionParam) -> str:
+    label = p.description or p.name
+    suffix = "" if p.required else " (optional)"
+    return ui.text_input(f"{label}{suffix}:", default=p.default, required=p.required)
+
+
+def _run_script(fn: FunctionDef, args: tuple[str, ...]) -> None:
+    ui.section(fn.name)
+    # Only prompt when there's an actual terminal to prompt on — otherwise a missing
+    # required param would hit an unreadable stdin and fail as an opaque, unrelated
+    # exception instead of the clean "Missing required parameter(s)" message.
+    prompt = _prompt_param if sys.stdin.isatty() else None
+    try:
+        runner.run_script_function(fn, args, prompt=prompt)
+        ui.success(f"{fn.name} completed")
+    except ParamResolutionError as exc:
+        ui.error(str(exc))
+        sys.exit(1)
+    except Exception as exc:
+        ui.error(f"'{fn.name}' failed: {exc}")
+        sys.exit(1)
+
+
+def _run_eval(fn: FunctionDef, args: tuple[str, ...]) -> None:
+    # Diagnostics must go to stderr and stdout must carry ONLY the resolved script —
+    # the caller does `eval "$(dev-setup run ...)"`, so anything else printed to
+    # stdout becomes part of what gets evaluated in their shell.
+    try:
+        script = runner.render_eval_script(fn, args)
+    except ParamResolutionError as exc:
+        click.echo(str(exc), err=True)
+        sys.exit(1)
+    click.echo(script)