devstuff 1.13.1__py3-none-any.whl

dev_setup/commands/update_cmd.py

@@ -0,0 +1,149 @@
+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
+from dev_setup.generic import UpdateStatus
+
+
+@click.command("update")
+@click.option("--verbose", "-v", is_flag=True, help="Stream update output to the terminal.")
+@click.option(
+    "--version", "target_version", default=None,
+    help="Update to a specific version instead of latest. Only valid with a single package.",
+)
+@click.argument("packages", nargs=-1)
+def update_cmd(packages: tuple[str, ...], verbose: bool, target_version: str | None) -> None:
+    """Update packages. Interactive picker with recommended updates when called with no arguments."""
+    from dev_setup import generic
+    generic._verbose = verbose
+
+    if not packages:
+        if target_version:
+            ui.error("--version requires a package key.")
+            sys.exit(1)
+        _update_interactive()
+        return
+
+    if target_version and len(packages) > 1:
+        ui.error("--version can only be used with a single package.")
+        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 _update_one(registry.get(key), target_version):  # type: ignore[arg-type]
+            failed = True
+
+    if failed:
+        sys.exit(1)
+
+
+def _update_one(tool: Tool, version: str | None) -> bool:
+    ui.section(f"Update {tool.name}")
+
+    if not tool.is_installed():
+        ui.warn(f"{tool.name} is not installed — nothing to update.")
+        ui.dim(f"Install first:  devstuff install {tool.key}")
+        return True
+
+    if tool.install_type in ("bash", "script"):
+        ui.warn(f"Updating {tool.name} re-runs its full installer (may use sudo).")
+        if not ui.confirm(f"Continue updating {tool.name}?", default=False):
+            ui.dim("Skipped.")
+            return True
+
+    before = tool.get_version()
+    try:
+        after = tool.update(version=version) or tool.get_version()  # type: ignore[attr-defined]
+        if before and after and before == after:
+            ui.success(f"{tool.name} already up to date: {after}")
+        elif before and after:
+            ui.success(f"{tool.name} updated: {before} → {after}")
+        elif after:
+            ui.success(f"{tool.name} updated: {after}")
+        else:
+            ui.success(f"{tool.name} updated")
+        return True
+    except Exception as exc:
+        ui.error(f"Failed to update {tool.name}: {exc}")
+        return False
+
+
+def _collect_update_candidates() -> list[tuple[Tool, UpdateStatus]]:
+    """Return (tool, UpdateStatus) for every installed tool, probed concurrently.
+
+    Pure data-gathering, kept free of any UI/prompt code so it can be exercised
+    directly without a terminal.
+    """
+    tools = registry.all_tools()
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        installed_flags = list(pool.map(lambda t: t.is_installed(), tools))
+    installed = [t for t, flag in zip(tools, installed_flags, strict=True) if flag]
+    if not installed:
+        return []
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        statuses = list(pool.map(lambda t: t.check_for_update(), installed))  # type: ignore[attr-defined]
+    return list(zip(installed, statuses, strict=True))
+
+
+def _update_interactive() -> None:
+    ui.print_banner()
+
+    with ui.spinner("Checking installed packages for available updates..."):
+        candidates = _collect_update_candidates()
+
+    if not candidates:
+        ui.info("No installed packages to update.")
+        return
+
+    key_width = max((len(t.key) for t, _ in candidates), default=12) + 2
+
+    choices: list = []
+    for t, status in sorted(candidates, key=lambda c: c[0].key):
+        if status.available is True:
+            tag = f"update available: {status.current or '?'} → {status.latest}"
+            mark = "⬆ "
+        elif status.available is False:
+            tag = f"up to date ({status.current or status.latest})"
+            mark = "  "
+        else:
+            tag = "unknown — reinstall to check"
+            mark = "  "
+        title = [
+            ("class:check", mark),
+            ("class:text", f"{t.key:<{key_width}}{tag}"),
+        ]
+        choices.append(questionary.Choice(title=title, value=t.key, checked=status.available is True))
+
+    selected = questionary.checkbox(
+        "Select packages to update:",
+        choices=choices,
+        instruction="(Space toggle · Enter confirm · pre-checked items have a known update)",
+        style=ui._STYLE,
+    ).ask()
+
+    if not selected:
+        ui.info("No packages selected.")
+        return
+
+    if not ui.confirm(f"Update {len(selected)} package(s)?"):
+        ui.warn("Aborted.")
+        return
+
+    failed = False
+    for key in selected:
+        tool = registry.get(key)
+        if tool and not _update_one(tool, None):
+            failed = True
+
+    if failed:
+        sys.exit(1)

dev_setup/function_runner.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import tempfile
+from collections.abc import Callable
+
+from dev_setup.base import patch_bashrc, remove_bashrc_block
+from dev_setup.functions_registry import FunctionDef, FunctionParam
+
+
+class ParamResolutionError(RuntimeError):
+    pass
+
+
+def resolve_params(
+    params: list[FunctionParam],
+    args: tuple[str, ...],
+    *,
+    prompt: Callable[[FunctionParam], str] | None = None,
+) -> list[str]:
+    """Resolve one value per declared param, filling any gap via `prompt` or a catalog
+    default. When `prompt` is None (the eval codepath, which must keep stdout clean),
+    missing required params raise instead of being asked for interactively.
+
+    A value counts as "provided" only if it's non-empty — an explicitly empty positional
+    arg (`dev-setup run key ""`) is treated the same as a missing one for a required
+    param, rather than silently running with an empty value.
+    """
+    positional = list(args[: len(params)])
+    positional += [""] * (len(params) - len(positional))
+
+    values: list[str] = []
+    missing: list[str] = []
+    for p, value in zip(params, positional, strict=True):
+        if not value and prompt is not None:
+            value = prompt(p)
+        if not value and p.default:
+            value = p.default
+        if not value and p.required:
+            missing.append(p.name)
+        values.append(value)
+
+    if missing:
+        raise ParamResolutionError("Missing required parameter(s): " + ", ".join(missing))
+    return values
+
+
+def _positional_prelude(params: list[FunctionParam]) -> str:
+    """`name="$1"`-style assignments mapping real argv positions to the script's named vars.
+
+    Used for `script`-type subprocess runs and bashrc-registered functions, both of which
+    receive their values as real shell positional arguments at call time.
+    """
+    return "\n".join(f'{p.name}="${i + 1}"' for i, p in enumerate(params))
+
+
+def _literal_prelude(params: list[FunctionParam], values: list[str]) -> str:
+    """`name='resolved value'` assignments for eval mode.
+
+    `eval "$(dev-setup run ...)"` has no argv of its own — the values dev-setup resolved
+    from its own CLI args must be baked into the printed text as shell-quoted literals.
+    """
+    return "\n".join(f"{p.name}={shlex.quote(v)}" for p, v in zip(params, values, strict=True))
+
+
+def render_eval_script(fn: FunctionDef, args: tuple[str, ...]) -> str:
+    """Build the text printed for `register: eval` mode. Never prompts — stdout must stay
+    clean for `eval "$(...)"` capture, so missing required params raise instead."""
+    values = resolve_params(fn.params, args)
+    prelude = _literal_prelude(fn.params, values)
+    return f"{prelude}\n{fn.script}" if prelude else fn.script
+
+
+def _bashrc_prelude(fn: FunctionDef) -> list[str]:
+    """Per-param lines for a bashrc-registered function: `name="$N"` plus, for required
+    params with no default, a guard that fails loudly if the caller left it blank.
+
+    dev-setup itself is never in the loop when an enabled function is called directly by
+    the user's shell — `resolve_params` can't help here — so this is the only place
+    "required" can be enforced for this mode.
+    """
+    lines: list[str] = []
+    for i, p in enumerate(fn.params):
+        lines.append(f'local {p.name}="${i + 1}"')
+        if p.required and not p.default:
+            lines.append(f'if [ -z "${p.name}" ]; then')
+            lines.append(f'  echo "{fn.key}: missing required argument: {p.name}" >&2')
+            lines.append("  return 1")
+            lines.append("fi")
+    return lines
+
+
+def render_bashrc_function(fn: FunctionDef) -> str:
+    """Build the `name() { ... }` block registered into ~/.bashrc.
+
+    Blank lines are dropped from the body (blank-line-free is semantically identical
+    in bash) because `remove_bashrc_block` treats the first blank line after the
+    marker as the end of the block — a blank line inside the function would make
+    `disable` orphan everything after it, closing brace included.
+    """
+    body_lines = [f"  {line}" for line in _bashrc_prelude(fn)]
+    body_lines += [f"  {line}" for line in fn.script.rstrip("\n").splitlines() if line.strip()]
+    return f"{fn.key}() {{\n" + "\n".join(body_lines) + "\n}"
+
+
+def enable_bashrc_function(fn: FunctionDef) -> bool:
+    return patch_bashrc(f"dev-setup-fn:{fn.key}", render_bashrc_function(fn))
+
+
+def disable_bashrc_function(fn: FunctionDef) -> bool:
+    return remove_bashrc_block(f"dev-setup-fn:{fn.key}")
+
+
+def run_script_function(
+    fn: FunctionDef,
+    args: tuple[str, ...],
+    *,
+    prompt: Callable[[FunctionParam], str] | None = None,
+) -> None:
+    """Execute a `script`-type function as a subprocess. Raises on nonzero exit."""
+    values = resolve_params(fn.params, args, prompt=prompt)
+    prelude = _positional_prelude(fn.params)
+    content = f"{prelude}\n{fn.script}" if prelude else fn.script
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".sh", delete=False) as f:
+        f.write(content)
+        tmp = f.name
+    try:
+        subprocess.run(["bash", tmp, *values], check=True)
+    finally:
+        os.unlink(tmp)

dev_setup/functions.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/thesawdawg/dev-setup-py/functions.schema.json",
+  "title": "devstuff functions catalog",
+  "description": "Schema for functions.yaml (bundled at src/dev_setup/functions.yaml, user overrides at ~/.config/dev-setup/functions.yaml). Defines reusable shell functions/scripts invoked via `devstuff run <key>` or, for bashrc-registered functions, called directly by name after `devstuff functions enable <key>`. Mirrors the validation in functions_catalog.py — keep both in sync.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "functions"],
+  "properties": {
+    "version": {
+      "const": 1,
+      "description": "Catalog schema version. Currently always 1."
+    },
+    "functions": {
+      "type": "object",
+      "description": "Map of function key -> function definition.",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9_-]*$",
+        "description": "Lowercase letters, digits, hyphens, underscores; must start with a letter or digit."
+      },
+      "additionalProperties": { "$ref": "#/definitions/function" }
+    }
+  },
+  "definitions": {
+    "function": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "script"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Display name shown in `devstuff functions list`. Defaults to the catalog key if omitted."
+        },
+        "description": {
+          "type": "string",
+          "description": "Short description shown in `devstuff functions list`. Defaults to \"\"."
+        },
+        "category": {
+          "type": "string",
+          "description": "Group shown in `devstuff functions list` (functions are listed grouped by category, like tools). Freeform, not a fixed enum. Defaults to \"custom\"."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["script", "shell-eval"],
+          "description": "Execution model. 'script': runs as a subprocess (like a tool's install_script) — for anything that just calls other binaries/apps and doesn't need to change your shell's state; params are resolved positionally and missing required ones are prompted for interactively. 'shell-eval': for things that must mutate the *calling* shell (env vars, cd, aliases, agents like ssh-agent) — a devstuff subprocess can't do this on its own, so see 'register' for how it actually takes effect."
+        },
+        "register": {
+          "type": "string",
+          "enum": ["bashrc", "eval"],
+          "description": "Only meaningful when type is 'shell-eval' — rejected for type 'script'. 'bashrc' (default): `devstuff functions enable <key>` patches a real shell function into ~/.bashrc (idempotent); afterward you call it directly by name in a new shell (`devstuff run` refuses to run these itself and points at `functions enable` instead). Required params without a default get a runtime guard baked into the generated function that fails loudly (prints to stderr, returns 1) if left blank. 'eval': `devstuff run <key> [args]` prints resolved shell code to stdout ONLY, for `eval \"$(devstuff run key args)\"` — no prompting, since anything else on stdout would corrupt the eval capture; a missing required param is reported on stderr and exits non-zero instead."
+        },
+        "params": {
+          "type": "array",
+          "description": "Named parameters, resolved positionally from CLI args in the order declared here. Each becomes a named shell variable in the script body (e.g. \"$key_path\", not positional \"$1\") via a runner-injected prelude. An explicitly empty value counts as missing for a required param, same as not passing it at all.",
+          "items": { "$ref": "#/definitions/param" }
+        },
+        "script": {
+          "type": "string",
+          "description": "Required. The bash script body, referencing params by name (e.g. \"$key_path\"). For bashrc-registered functions, keep this free of blank lines if you hand-edit — devstuff already strips them when rendering, since a blank line would make `functions disable` stop removing the block early and orphan the rest (closing brace included)."
+        },
+        "help_cmd": {
+          "type": "string",
+          "description": "Optional help command shown alongside the function in `devstuff functions list`."
+        },
+        "docs_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Optional documentation URL for this function."
+        }
+      },
+      "if": {
+        "properties": { "type": { "const": "shell-eval" } },
+        "required": ["type"]
+      },
+      "else": {
+        "properties": { "register": false }
+      }
+    },
+    "param": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+          "description": "Shell variable name this param is bound to in the script body. Must be a valid shell identifier; must be unique within the function."
+        },
+        "description": {
+          "type": "string",
+          "description": "Defaults to \"\". Shown as the prompt label when this param is missing and can be interactively prompted for (type: script only — shell-eval never prompts)."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Defaults to true. Whether this param must resolve to a non-empty value. For type: script / register: eval, an unresolved required param raises/exits before anything runs. For a bashrc-registered function, a required param with no default instead gets a runtime bash guard that fails at call time."
+        },
+        "default": {
+          "type": "string",
+          "default": "",
+          "description": "Defaults to \"\". Fallback value used when no value is supplied and (for type: script) no interactive prompt filled it in. A required param WITH a default never triggers the bashrc runtime guard or a resolution error, since the default always satisfies it."
+        }
+      }
+    }
+  }
+}

dev_setup/functions.yaml

@@ -0,0 +1,111 @@
+# yaml-language-server: $schema=./functions.schema.json
+version: 1
+functions:
+  ssh-agent-key:
+    name: SSH Agent + Add Key
+    description: Start ssh-agent in the current shell and add a key to it
+    category: auth
+    type: shell-eval
+    register: bashrc
+    params:
+      - name: key_path
+        description: Path to the SSH private key
+        required: true
+    script: |
+      eval "$(ssh-agent -s)"
+      ssh-add "$key_path"
+    docs_url: https://www.ssh.com/academy/ssh/agent
+
+  validate-docker-compose:
+    name: Validate Docker Compose
+    description: Validate a docker-compose.yml file in the current directory
+    category: validation
+    type: script
+    script: |
+      set -euo pipefail
+      if ! command -v docker >/dev/null 2>&1; then
+        echo "docker is required. Install it first: devstuff install docker" >&2
+        exit 1
+      fi
+      file=""
+      for candidate in docker-compose.yml docker-compose.yaml compose.yml compose.yaml; do
+        if [ -f "$candidate" ]; then
+          file="$candidate"
+          break
+        fi
+      done
+      if [ -z "$file" ]; then
+        echo "No docker-compose.yml/docker-compose.yaml/compose.yml/compose.yaml found in $(pwd)" >&2
+        exit 1
+      fi
+      echo "Validating $file..."
+      docker compose -f "$file" config --quiet
+      echo "$file is valid"
+    docs_url: https://docs.docker.com/reference/cli/docker/compose/config/
+
+  validate-yaml:
+    name: Validate YAML
+    description: Validate a YAML file's syntax using yq
+    category: validation
+    type: script
+    params:
+      - name: file
+        description: Path to the YAML file to validate
+        required: true
+    script: |
+      set -euo pipefail
+      if ! command -v yq >/dev/null 2>&1; then
+        echo "yq is required. Install it first: devstuff install yq" >&2
+        exit 1
+      fi
+      if [ ! -f "$file" ]; then
+        echo "File not found: $file" >&2
+        exit 1
+      fi
+      yq eval '.' "$file" > /dev/null
+      echo "$file is valid YAML"
+    docs_url: https://mikefarah.gitbook.io/yq
+
+  acc-check:
+    name: Accessibility/QA Check
+    description: Run the pi coding agent's /dogfood skill against a web URL
+    category: web-dev
+    type: script
+    params:
+      - name: url
+        description: URL to review
+        required: true
+      - name: instruction
+        description: Additional scope or instruction for the review (optional)
+        required: false
+    script: |
+      set -euo pipefail
+      . "$HOME/.nvm/nvm.sh" 2>/dev/null || true
+      if ! command -v pi >/dev/null 2>&1; then
+        echo "pi is required. Install it first: devstuff install pi" >&2
+        exit 1
+      fi
+      pi -p "/dogfood $url $instruction"
+    docs_url: https://pi.dev/docs/latest
+
+  aws-saml-reauth:
+    name: AWS SAML Reauth
+    description: Reauthorize the AWS CLI via saml2aws
+    category: web-dev
+    type: script
+    params:
+      - name: profile
+        description: AWS profile to reauthenticate (optional, uses saml2aws default if omitted)
+        required: false
+    script: |
+      set -euo pipefail
+      if ! command -v saml2aws >/dev/null 2>&1; then
+        echo "saml2aws is required. Install it first: devstuff install saml2aws" >&2
+        exit 1
+      fi
+      if [ -n "$profile" ]; then
+        saml2aws login --force --profile "$profile"
+      else
+        saml2aws login --force
+      fi
+    docs_url: https://github.com/Versent/saml2aws