@sebastienrousseau/dotfiles 0.2.501 → 0.2.502

package/scripts/dot/commands/init.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck shell=bash
+#
+# scripts/dot/commands/init.sh
+#
+# `dot init <github-user>` — bootstrap a foreign dotfiles repo through
+# this framework's harness. The §3 audit roadmap calls for an analogue
+# to `chezmoi init <user>` that turns this tool from "one person's
+# config" into a runtime for any dotfiles user.
+#
+# Behavior:
+#   dot init alice                # clones github.com/alice/dotfiles via chezmoi,
+#                                 # applies through the dot harness
+#   dot init https://...          # explicit URL
+#   dot init alice --dry-run      # preview without writing
+#   dot init alice --no-apply     # clone only; don't run chezmoi apply
+#
+# Safety:
+#   - Refuses to clobber an existing chezmoi source dir without --force.
+#   - Disclaims that the target's scripts will run with the user's
+#     privileges and prints the source URL for inspection.
+#   - Verifies the source URL is HTTPS (no plain git://) so MITM is harder.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/ui.sh disable=SC1091
+source "$SCRIPT_DIR/../lib/ui.sh"
+# shellcheck source=../lib/utils.sh disable=SC1091
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+_init_resolve_url() {
+  local arg="$1"
+  case "$arg" in
+    http://*)
+      printf "dot init: refusing plain HTTP (use HTTPS or git+ssh)\n" >&2
+      return 2
+      ;;
+    https://* | git@*:*)
+      # Trust full URLs as-is — these are the user's explicit intent.
+      printf "%s\n" "$arg"
+      ;;
+    */*)
+      # owner/repo shorthand: validate before constructing the URL so
+      # a crafted argument can't smuggle shell metacharacters into
+      # downstream tooling (chezmoi init, git clone).
+      if [[ ! "$arg" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]]; then
+        printf "dot init: invalid owner/repo (only [A-Za-z0-9._-]+/[A-Za-z0-9._-]+ allowed): %s\n" "$arg" >&2
+        return 2
+      fi
+      printf "https://github.com/%s.git\n" "$arg"
+      ;;
+    *)
+      # Bare user shorthand: same character whitelist as the path
+      # segment of a GitHub URL.
+      if [[ ! "$arg" =~ ^[A-Za-z0-9._-]+$ ]]; then
+        printf "dot init: invalid user (only [A-Za-z0-9._-] allowed): %s\n" "$arg" >&2
+        return 2
+      fi
+      printf "https://github.com/%s/dotfiles.git\n" "$arg"
+      ;;
+  esac
+}
+
+cmd_init() {
+  local user_arg="" dry_run=0 apply=1 force=0
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --dry-run | -n)
+        dry_run=1
+        shift
+        ;;
+      --no-apply)
+        apply=0
+        shift
+        ;;
+      --force | -f)
+        force=1
+        shift
+        ;;
+      --help | -h)
+        cat <<EOF
+Usage: dot init <github-user|owner/repo|url> [--dry-run] [--no-apply] [--force]
+
+Bootstrap a foreign dotfiles repo through chezmoi + the dot harness.
+
+Examples:
+  dot init alice                # github.com/alice/dotfiles
+  dot init alice/configs        # github.com/alice/configs
+  dot init https://example.com/repo.git
+  dot init alice --dry-run      # preview only
+  dot init alice --no-apply     # clone but don't apply
+
+Flags:
+  --dry-run, -n   Show resolved URL + target dir without cloning.
+  --no-apply      Clone the source but skip 'chezmoi apply'.
+  --force,   -f   Overwrite an existing chezmoi source dir.
+EOF
+        return 0
+        ;;
+      --)
+        shift
+        break
+        ;;
+      -*)
+        ui_err "Unknown flag" "$1"
+        return 1
+        ;;
+      *)
+        if [[ -n "$user_arg" ]]; then
+          ui_err "Too many arguments" "$1"
+          return 1
+        fi
+        user_arg="$1"
+        shift
+        ;;
+    esac
+  done
+
+  [[ -n "$user_arg" ]] || {
+    ui_err "init" "missing <user|repo|url>"
+    return 1
+  }
+
+  local url
+  url="$(_init_resolve_url "$user_arg")" || return $?
+
+  if ! command -v chezmoi >/dev/null 2>&1; then
+    ui_err "chezmoi" "not installed — run install.sh first"
+    return 127
+  fi
+
+  local source_dir
+  source_dir="${CHEZMOI_SOURCE_DIR:-$(chezmoi source-path 2>/dev/null || echo "$HOME/.local/share/chezmoi")}"
+
+  ui_header "Bootstrap dotfiles from $user_arg"
+  ui_info "Source URL" "$url"
+  ui_info "Target dir" "$source_dir"
+  local _apply_label="no"
+  [[ "$apply" -eq 1 ]] && _apply_label="yes"
+  ui_info "Apply after?" "$_apply_label"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    ui_ok "Dry-run" "no changes made"
+    return 0
+  fi
+
+  if [[ -e "$source_dir" ]] && [[ "$force" -ne 1 ]]; then
+    ui_err "Refusing" "$source_dir already exists; pass --force to overwrite"
+    return 1
+  fi
+
+  ui_warn "Trust" "The target repo's scripts will run with your user privileges."
+  ui_warn "Trust" "Inspect $url before proceeding if you don't know the author."
+  if [[ -t 0 ]] && [[ "${DOTFILES_NONINTERACTIVE:-0}" != "1" ]]; then
+    read -r -p "  Continue? [y/N] " resp
+    case "$resp" in
+      [yY] | [yY][eE][sS]) ;;
+      *)
+        ui_info "Init" "aborted by user"
+        return 1
+        ;;
+    esac
+  fi
+
+  local chezmoi_args=(init --source "$source_dir")
+  [[ "$apply" -eq 1 ]] && chezmoi_args+=(--apply)
+  chezmoi_args+=("$url")
+
+  ui_info "chezmoi" "${chezmoi_args[*]}"
+  if chezmoi "${chezmoi_args[@]}"; then
+    ui_ok "Init" "complete"
+    if [[ "$apply" -eq 1 ]]; then
+      ui_info "Hint" "run 'dot doctor' to validate the new environment"
+    else
+      ui_info "Hint" "run 'chezmoi diff' then 'chezmoi apply' when ready"
+    fi
+  else
+    local rc=$?
+    ui_err "Init" "chezmoi exited $rc"
+    return "$rc"
+  fi
+}

package/scripts/dot/commands/meta.sh

@@ -61,10 +61,13 @@ cmd_prewarm() {
   # Clear caches first
   ui_info "Cache" "Clearing shell initialization caches"
   local cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}"
-  rm -rf "$cache_dir/zsh"/*-init.zsh "$cache_dir/zsh"/*.zwc 2>/dev/null || true
-  rm -rf "$cache_dir/bash"/*-init.bash 2>/dev/null || true
-  rm -rf "$cache_dir/fish"/*-init.fish 2>/dev/null || true
-  rm -rf "$cache_dir/nushell"/*.nu 2>/dev/null || true
+  # `find ... -delete` instead of `rm -rf $glob` so an unmatched literal
+  # pattern can't accidentally remove a real same-named directory, and
+  # so we don't pass `-r` on what should always be files.
+  [[ -d "$cache_dir/zsh" ]] && find "$cache_dir/zsh" -maxdepth 1 -type f \( -name '*-init.zsh' -o -name '*.zwc' \) -delete 2>/dev/null
+  [[ -d "$cache_dir/bash" ]] && find "$cache_dir/bash" -maxdepth 1 -type f -name '*-init.bash' -delete 2>/dev/null
+  [[ -d "$cache_dir/fish" ]] && find "$cache_dir/fish" -maxdepth 1 -type f -name '*-init.fish' -delete 2>/dev/null
+  [[ -d "$cache_dir/nushell" ]] && find "$cache_dir/nushell" -maxdepth 1 -type f -name '*.nu' -delete 2>/dev/null
   ui_info "Cache" "Cleared. Regenerating..."
   src_dir="$(resolve_source_dir)"
   if [ -n "$src_dir" ] && [ -f "$src_dir/scripts/ops/prewarm.sh" ]; then

package/scripts/dot/commands/registry.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# shellcheck shell=bash
+#
+# scripts/dot/commands/registry.sh
+#
+# `dot registry` — initial scaffold for the dot module registry.
+#
+# §3 audit roadmap: ship a registry of reusable dotfile modules
+# ("rust-dev-setup", "k8s-operator-laptop") to seed network effects.
+# Hosted as a GitHub-Pages-indexed JSON file to keep ops cost near
+# zero.
+#
+# Current state: SCAFFOLD ONLY. This file ships the CLI surface and
+# the JSON contract (see _registry_default_url). The registry itself
+# is empty; populating it is its own roadmap item.
+#
+# Subcommands:
+#   list           Show modules in the configured registry
+#   search <q>     Filter modules by keyword (name, description, tags)
+#   info <name>    Print full metadata for a module
+#   install <name> Apply a module to the current workstation (stub —
+#                  prints what would be installed; full implementation
+#                  needs a sandboxed apply pipeline)
+#   url            Show the active registry URL
+#   set-url <u>    Override the registry URL (writes to user config)
+#
+# Registry JSON shape:
+#   {
+#     "version": 1,
+#     "updated": "2026-05-15T16:00:00Z",
+#     "modules": [
+#       { "name": "rust-dev-setup",
+#         "description": "Rust toolchain + cargo plugins + IDE config",
+#         "repo": "https://github.com/example/rust-dev-setup",
+#         "tags": ["rust", "dev", "language"],
+#         "maintainer": "alice@example.com",
+#         "version": "1.2.0",
+#         "sha256": "abc123..." }
+#     ]
+#   }
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/ui.sh disable=SC1091
+source "$SCRIPT_DIR/../lib/ui.sh"
+# shellcheck source=../lib/utils.sh disable=SC1091
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+_registry_default_url() {
+  printf '%s\n' "https://sebastienrousseau.github.io/dotfiles/registry.json"
+}
+
+_registry_config_file() {
+  printf '%s/dotfiles/registry.toml\n' "${XDG_CONFIG_HOME:-$HOME/.config}"
+}
+
+_registry_url() {
+  if [[ -n "${DOTFILES_REGISTRY_URL:-}" ]]; then
+    printf '%s\n' "$DOTFILES_REGISTRY_URL"
+    return
+  fi
+  local cfg
+  cfg="$(_registry_config_file)"
+  if [[ -f "$cfg" ]]; then
+    local u
+    u="$(awk -F'[ \t]*=[ \t]*' '/^url[ \t]*=/{gsub(/"/,"",$2); print $2; exit}' "$cfg")"
+    [[ -n "$u" ]] && {
+      printf '%s\n' "$u"
+      return
+    }
+  fi
+  _registry_default_url
+}
+
+_registry_cache_dir() {
+  printf '%s/dotfiles/registry\n' "${XDG_CACHE_HOME:-$HOME/.cache}"
+}
+
+_registry_fetch() {
+  local url cache_dir cache_file
+  url="$(_registry_url)"
+  cache_dir="$(_registry_cache_dir)"
+  cache_file="$cache_dir/index.json"
+  mkdir -p "$cache_dir"
+  # Refresh if older than 6h or missing.
+  local now mtime
+  now="$(date +%s)"
+  if [[ -s "$cache_file" ]]; then
+    if mtime="$(stat -f %m "$cache_file" 2>/dev/null || stat -c %Y "$cache_file" 2>/dev/null)"; then
+      if ((now - mtime < 21600)); then
+        printf '%s\n' "$cache_file"
+        return 0
+      fi
+    fi
+  fi
+  if ! command -v curl >/dev/null 2>&1; then
+    ui_err "registry" "curl not installed"
+    return 127
+  fi
+  local tmp
+  tmp="$(mktemp "${cache_file}.XXXXXX")"
+  if ! curl -fsSL --max-time 15 -o "$tmp" "$url"; then
+    rm -f "$tmp"
+    if [[ -s "$cache_file" ]]; then
+      ui_warn "registry" "fetch failed; using stale cache at $cache_file"
+      printf '%s\n' "$cache_file"
+      return 0
+    fi
+    ui_err "registry" "could not fetch $url"
+    return 1
+  fi
+  mv "$tmp" "$cache_file"
+  printf '%s\n' "$cache_file"
+}
+
+_registry_require_jq() {
+  command -v jq >/dev/null 2>&1 || {
+    ui_err "registry" "jq is required"
+    return 127
+  }
+}
+
+cmd_registry() {
+  local subcommand="${1:-list}"
+  shift || true
+
+  case "$subcommand" in
+    url)
+      printf '%s\n' "$(_registry_url)"
+      ;;
+    set-url)
+      local new_url="${1:-}"
+      [[ -n "$new_url" ]] || {
+        ui_err "set-url" "missing URL"
+        return 1
+      }
+      # Refuse non-HTTPS schemes. The registry index is unsigned today,
+      # so HTTPS is the only transport that gives us cert-pinned
+      # integrity. The `file://` exemption is for local testing only
+      # (the bench-script and unit tests use it).
+      if [[ ! "$new_url" =~ ^(https://|file://) ]]; then
+        ui_err "set-url" "registry URL must use https:// (or file:// for local testing) — got: $new_url"
+        return 1
+      fi
+      local cfg
+      cfg="$(_registry_config_file)"
+      mkdir -p "$(dirname "$cfg")"
+      # Atomic write so a concurrent invocation can't read a half-
+      # written file. Explicit if/else (avoid SC2015 A && B || C).
+      local _tmp
+      _tmp="$(mktemp "${cfg}.XXXXXX")"
+      if printf 'url = "%s"\n' "$new_url" >"$_tmp"; then
+        if ! mv "$_tmp" "$cfg"; then
+          rm -f "$_tmp"
+          ui_err "set-url" "failed to commit $cfg"
+          return 1
+        fi
+      else
+        rm -f "$_tmp"
+        ui_err "set-url" "failed to write $cfg"
+        return 1
+      fi
+      ui_ok "registry" "set to $new_url ($cfg)"
+      ;;
+    list)
+      _registry_require_jq || return $?
+      local index
+      index="$(_registry_fetch)" || return $?
+      ui_header "Registry modules"
+      ui_info "Source" "$(_registry_url)"
+      echo ""
+      if ! jq -e '.modules | length > 0' "$index" >/dev/null 2>&1; then
+        ui_warn "registry" "no modules published yet — see docs/operations/REGISTRY.md to contribute one"
+        return 0
+      fi
+      ui_table_begin "Module" "Version" "Description"
+      while IFS=$'\t' read -r name ver desc; do
+        ui_table_add "$name" "v$ver" "$desc"
+      done < <(jq -r '.modules[] | "\(.name)\t\(.version // "-")\t\(.description // "")"' "$index")
+      ui_table_end
+      ;;
+    search)
+      _registry_require_jq || return $?
+      local q="${1:-}"
+      [[ -n "$q" ]] || {
+        ui_err "search" "missing query"
+        return 1
+      }
+      local index
+      index="$(_registry_fetch)" || return $?
+      ui_header "Registry search: $q"
+      echo ""
+      ui_table_begin "Module" "Version" "Description"
+      while IFS=$'\t' read -r name ver desc; do
+        ui_table_add "$name" "v$ver" "$desc"
+      done < <(jq -r --arg q "$q" '
+        .modules[]
+        | select(
+            (.name // "" | ascii_downcase | contains($q | ascii_downcase)) or
+            (.description // "" | ascii_downcase | contains($q | ascii_downcase)) or
+            ((.tags // []) | map(ascii_downcase) | index($q | ascii_downcase))
+          )
+        | "\(.name)\t\(.version // "-")\t\(.description // "")"
+      ' "$index")
+      ui_table_end
+      ;;
+    info)
+      _registry_require_jq || return $?
+      local name="${1:-}"
+      [[ -n "$name" ]] || {
+        ui_err "info" "missing module name"
+        return 1
+      }
+      local index
+      index="$(_registry_fetch)" || return $?
+      local found
+      found="$(jq -r --arg n "$name" '.modules[] | select(.name == $n) | "OK"' "$index" 2>/dev/null)"
+      if [[ "$found" != "OK" ]]; then
+        ui_err "info" "module not found: $name"
+        return 1
+      fi
+      jq -r --arg n "$name" '.modules[] | select(.name == $n) | to_entries[] | "\(.key)\t\(.value | if type == "array" then join(", ") else tostring end)"' "$index" |
+        while IFS=$'\t' read -r key value; do
+          ui_ok "$key" "$value"
+        done
+      ;;
+    install)
+      local name="${1:-}"
+      [[ -n "$name" ]] || {
+        ui_err "install" "missing module name"
+        return 1
+      }
+      ui_warn "install" "scaffold only — full module installer is a roadmap item"
+      ui_info "install" "would fetch module $name from registry and apply it as a chezmoi sub-source"
+      return 0
+      ;;
+    --help | -h | help)
+      cat <<EOF
+Usage: dot registry <subcommand>
+
+Subcommands:
+  list             List modules in the configured registry
+  search <q>       Filter modules by keyword (name, description, tags)
+  info <name>      Print metadata for a single module
+  install <name>   Install a module (scaffold — see docs/operations/REGISTRY.md)
+  url              Show the active registry URL
+  set-url <url>    Override the registry URL (persists to user config)
+
+Env overrides:
+  DOTFILES_REGISTRY_URL   One-shot override of the registry URL.
+
+Default registry: $(_registry_default_url)
+EOF
+      ;;
+    *)
+      ui_err "Unknown subcommand" "$subcommand"
+      echo "Run 'dot registry --help' for usage." >&2
+      return 1
+      ;;
+  esac
+}

package/scripts/dot/commands/tools.sh

@@ -353,7 +353,55 @@ cmd_env_mise() {
     exit 1
   fi
   case "${1:-list}" in
-    list | ls) mise ls ;;
+    list | ls)
+      if has_command jq; then
+        ui_table_begin "Tool" "Version" "Source" "Requested"
+        while IFS=$'\t' read -r tool ver source req; do
+          ui_table_add "$tool" "$ver" "${source/$HOME/\~}" "$req"
+        done < <(mise ls --json 2>/dev/null | jq -r '
+          to_entries[] as $t
+          | $t.value[]
+          | [
+              $t.key,
+              (.version // "-"),
+              (.source.path // ""),
+              (.requested_version // "")
+            ]
+          | @tsv
+        ')
+        ui_table_end
+      else
+        mise ls
+      fi
+      # Surface orphan installs (tool versions on disk that no active config
+      # claims). `--dry-run-code` exits 1 iff there is something to prune;
+      # the call is fast (no I/O beyond reading the tracked-configs index).
+      if mise prune --dry-run-code --quiet >/dev/null 2>&1; then
+        :
+      else
+        echo ""
+        ui_warn "orphan installs" "tool versions on disk are not requested by any config"
+        ui_info "to clean" "run 'dot env prune' (dry-run) or 'dot env prune --yes' to commit"
+      fi
+      ;;
+    prune)
+      shift
+      local commit=0
+      for arg in "$@"; do
+        case "$arg" in
+          --yes | -y) commit=1 ;;
+        esac
+      done
+      if ((commit)); then
+        mise prune
+      else
+        ui_info "dry-run" "showing what 'mise prune' would remove (pass --yes to commit)"
+        echo ""
+        mise prune --dry-run
+        echo ""
+        ui_info "next" "re-run with 'dot env prune --yes' to actually uninstall"
+      fi
+      ;;
     install)
       shift
       # Validate tool names to prevent injection

package/scripts/dot/lib/bento.sh

@@ -31,7 +31,7 @@ _dotfiles_bento_render() {
 
   # Render a fixed-width card (42 cols) so output aligns in any terminal width
   printf "\n"
-  printf "  ${c_cyan}${c_bold}💎  D O T F I L E S${c_reset}  ${c_slate}[v0.2.501]${c_reset}\n"
+  printf "  ${c_cyan}${c_bold}💎  D O T F I L E S${c_reset}  ${c_slate}[v0.2.502]${c_reset}\n"
   printf "  ${c_slate}──────────────────────────────────────────${c_reset}\n"
 
   # Key system properties at a glance — answers "is my env healthy?" in 1 second

package/scripts/dot/lib/platform.sh

@@ -39,12 +39,22 @@ dot_host_os() {
 }
 
 # Convert host-native path into Linux path when inside WSL.
+#
+# Contract:
+#   - In WSL: requires `wslpath`. Returns 2 (with a stderr error) if
+#     missing — callers must not silently treat a Windows-style path
+#     as Linux-safe.
+#   - Outside WSL: paths are already Linux/macOS paths; echoes the
+#     input unchanged and returns 0.
+#   - Empty input returns 1 (usage error).
 dot_path_to_unix() {
   local p="${1:-}"
-  if [[ -z "$p" ]]; then
-    return 1
-  fi
-  if dot_is_wsl && command -v wslpath >/dev/null 2>&1; then
+  [[ -n "$p" ]] || return 1
+  if dot_is_wsl; then
+    if ! command -v wslpath >/dev/null 2>&1; then
+      printf "dot_path_to_unix: wslpath required in WSL but not found\n" >&2
+      return 2
+    fi
     wslpath -u "$p"
     return
   fi
@@ -52,12 +62,15 @@ dot_path_to_unix() {
 }
 
 # Convert Linux path into host-native path when inside WSL.
+# Same contract as dot_path_to_unix (see above).
 dot_path_to_native() {
   local p="${1:-}"
-  if [[ -z "$p" ]]; then
-    return 1
-  fi
-  if dot_is_wsl && command -v wslpath >/dev/null 2>&1; then
+  [[ -n "$p" ]] || return 1
+  if dot_is_wsl; then
+    if ! command -v wslpath >/dev/null 2>&1; then
+      printf "dot_path_to_native: wslpath required in WSL but not found\n" >&2
+      return 2
+    fi
     wslpath -w "$p"
     return
   fi