@sebastienrousseau/dotfiles 0.2.519 → 0.2.520

package/scripts/dot/commands/ai.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Dotfiles AI Commands.
 ##
@@ -22,12 +22,21 @@ AI_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/dotfiles/ai"
 AI_STATUS_TTL="${DOTFILES_AI_STATUS_TTL:-300}"
 AI_STATUS_CACHE_FILE="${AI_CACHE_DIR}/status.tsv"
 
-# Fallback to source tree if patterns don't exist in config (common in CI)
+# Fallback to source tree if patterns don't exist in config (common in CI).
+# `.chezmoiroot` moves the source tree one level down (it holds
+# `defaults` here), so probing <repo>/dot_config/… alone made this a
+# no-op and `--style` died with "Pattern not found" off-deployment.
 if [[ ! -d "$PATTERN_DIR" ]]; then
   _AI_SRC="$(cd "$SCRIPT_DIR/../../.." && pwd)"
-  if [[ -d "$_AI_SRC/dot_config/ai/patterns" ]]; then
-    PATTERN_DIR="$_AI_SRC/dot_config/ai/patterns"
-  fi
+  _AI_SUB=""
+  [[ -f "$_AI_SRC/.chezmoiroot" ]] &&
+    _AI_SUB="/$(head -1 "$_AI_SRC/.chezmoiroot" | tr -d '[:space:]')"
+  for _AI_CAND in "$_AI_SRC/dot_config/ai/patterns" "$_AI_SRC$_AI_SUB/dot_config/ai/patterns"; do
+    if [[ -d "$_AI_CAND" ]]; then
+      PATTERN_DIR="$_AI_CAND"
+      break
+    fi
+  done
 fi
 
 _show_ai_bridge_usage() {
@@ -188,7 +197,7 @@ cmd_ai_status() {
   done
 
   # Offer to install missing providers via mise
-  if [[ ${#missing[@]} -gt 0 ]] && has_command mise; then
+  if [[ ${#missing[@]} -gt 0 ]] && has_command mise && [[ -t 0 && -t 1 ]] && [[ "${DOTFILES_NONINTERACTIVE:-0}" != "1" ]]; then
     echo ""
     local _ai_install_action=""
     if has_command gum; then
@@ -288,6 +297,8 @@ cmd_ai_status() {
   echo ""
   if [ ${#installed[@]} -eq 0 ]; then
     ui_warn "No AI CLIs installed"
+  elif [[ ! -t 0 || ! -t 1 || "${DOTFILES_NONINTERACTIVE:-0}" == "1" ]]; then
+    return 0
   elif has_command gum; then
     ui_info "Launch" "Select an AI CLI to start"
     local -a choices=()
@@ -404,7 +415,9 @@ ${prompt}"
         do_install=$(gum confirm "Install $tool via mise ($mise_pkg)?" && echo "yes" || echo "no")
       else
         printf "Install %s via mise (%s)? [y/N] " "$tool" "$mise_pkg"
-        read -r do_install
+        # `|| true`: at EOF (piped, cron, CI) `read` returns 1 and
+        # `set -e` killed the script mid-prompt. EOF means "no".
+        read -r do_install || true
         case "$do_install" in y | Y | yes) do_install="yes" ;; *) do_install="no" ;; esac
       fi
       if [[ "$do_install" == "yes" ]]; then

package/scripts/dot/commands/aliases.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Aliases Commands (extracted from tools.sh)
 # aliases list|search|why|stats|cheatsheet|tiers, alias-check

package/scripts/dot/commands/appearance.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Appearance Commands
 # theme, wallpaper, fonts, tune

package/scripts/dot/commands/completion.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## `dot completion <bash|zsh|fish|nu>` — emit shell completion for `dot`,
 ## generated from the canonical _dot_help_specs registry in bin/dot. Using one
@@ -35,7 +35,11 @@ _completion_commands() {
     in_func && /cat <<'\''EOF'\''/ { in_block = 1; next }
     in_block && /^EOF$/ { exit }
     in_block && NF >= 3 && $2 !~ / / {
-      name = $2; desc = $3
+      name = $2
+      # Description = fields 3..NF-1 rejoined: registry descriptions can
+      # contain "|" (e.g. "--ai|-A") and the last field is the hint.
+      desc = $3
+      for (i = 4; i < NF; i++) desc = desc "|" $i
       gsub(/^[ \t]+|[ \t]+$/, "", name)
       gsub(/^[ \t]+|[ \t]+$/, "", desc)
       gsub(/[":\047]/, "", desc)
@@ -54,7 +58,9 @@ _completion_subcommands() {
     in_func && /cat <<'\''EOF'\''/ { in_block = 1; next }
     in_block && /^EOF$/ { exit }
     in_block && NF >= 3 && $2 ~ / / {
-      full = $2; desc = $3
+      full = $2
+      desc = $3
+      for (i = 4; i < NF; i++) desc = desc "|" $i
       gsub(/^[ \t]+|[ \t]+$/, "", full)
       gsub(/^[ \t]+|[ \t]+$/, "", desc)
       gsub(/[":\047]/, "", desc)
@@ -65,11 +71,42 @@ _completion_subcommands() {
   ' "$cli"
 }
 
+# The printf templates below are the *text of the generated script*;
+# `$cur`, `$prev`, `$commands` must reach the output unexpanded.
+# shellcheck disable=SC2016
 gen_bash() {
-  local names
+  local names parent child desc
   names="$(_completion_commands | cut -f1 | tr '\n' ' ')"
   printf '# dot bash completion — generated by: dot completion bash\n'
-  printf "complete -W '%s' dot\n" "${names% }"
+  printf '# Source this file, or install it to a bash-completion completions dir.\n'
+  printf '_dot_completions() {\n'
+  printf '  local cur prev commands\n'
+  printf '  COMPREPLY=()\n'
+  printf '  cur="${COMP_WORDS[COMP_CWORD]}"\n'
+  printf '  prev="${COMP_WORDS[COMP_CWORD - 1]}"\n'
+  printf "  commands='%s'\n" "${names% }"
+  printf '  case "$prev" in\n'
+  printf '    dot)\n'
+  printf '      COMPREPLY=($(compgen -W "$commands" -- "$cur"))\n'
+  printf '      return 0\n'
+  printf '      ;;\n'
+  # One case arm per parent command that has subcommands.
+  while IFS=$'\t' read -r parent child desc; do
+    printf '%s\t%s\n' "$parent" "$child"
+  done < <(_completion_subcommands) |
+    awk -F'\t' '{ subs[$1] = subs[$1] (subs[$1] == "" ? "" : " ") $2 }
+      END { for (p in subs) printf "%s\t%s\n", p, subs[p] }' |
+    LC_ALL=C sort |
+    while IFS=$'\t' read -r parent child; do
+      printf '    %s)\n' "$parent"
+      printf '      COMPREPLY=($(compgen -W "%s" -- "$cur"))\n' "$child"
+      printf '      return 0\n'
+      printf '      ;;\n'
+    done
+  printf '  esac\n'
+  printf '  COMPREPLY=($(compgen -f -- "$cur"))\n'
+  printf '}\n'
+  printf 'complete -F _dot_completions dot\n'
 }
 
 gen_zsh() {

package/scripts/dot/commands/core.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 ## Dotfiles Core Commands — Core chezmoi operations for the dot CLI.
 ##

package/scripts/dot/commands/diagnostics.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Diagnostics Commands
 # doctor, heal, health, rollback, drift, history, benchmark, verify, perf,

package/scripts/dot/commands/env-emit.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 #
 # `dot env emit` — render a portable workstation-environment

package/scripts/dot/commands/fleet.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Fleet Commands
 # fleet status|nodes|drift|events|namespace
@@ -93,7 +93,8 @@ cmd_fleet_status() {
   local drift_status="clean"
   if has_command chezmoi; then
     local drift_output
-    drift_output="$(chezmoi status 2>/dev/null || true)"
+    # --exclude=always: always-run scripts are pending by design, not drift.
+    drift_output="$(chezmoi status --exclude=always 2>/dev/null || true)"
     if [[ -n "$drift_output" ]]; then
       drift_status="drifted"
     fi
@@ -168,7 +169,7 @@ cmd_fleet_drift() {
       fi
 
       local drift_output
-      drift_output="$(chezmoi status 2>/dev/null || true)"
+      drift_output="$(chezmoi status --exclude=always 2>/dev/null || true)"
 
       _fleet_drift_append_history "$drift_output"
 
@@ -206,9 +207,12 @@ cmd_fleet_drift() {
       tail -n "$count" "$_DRIFT_HISTORY_FILE" | while IFS= read -r line; do
         local time status file_count
         # One jq per line (was three: .time, .status, .files|length).
+        # `|| true`: on an unparsable line jq prints nothing, `read`
+        # hits EOF and returns 1, and `set -e` would otherwise abort the
+        # whole listing instead of rendering the `?` placeholders below.
         IFS=$'\t' read -r time status file_count < <(
           printf '%s' "$line" | jq -r '[.time, .status, (.files | length)] | @tsv' 2>/dev/null
-        )
+        ) || true
         [[ -n "$time" ]] || time="?"
         [[ -n "$status" ]] || status="?"
         [[ -n "$file_count" ]] || file_count=0
@@ -298,23 +302,42 @@ cmd_fleet_namespace() {
       validate_name "$new_ns" "namespace"
       local data_file
       data_file="$(resolve_chezmoi_source_dir)/.chezmoidata.toml"
-      if grep -q "^namespace = " "$data_file" 2>/dev/null; then
-        # Atomic write: render into a tempfile + mv so concurrent
-        # `dot fleet namespace set` callers can't corrupt the TOML.
-        # Avoids `sed -i` portability dance (GNU `-i` vs BSD `-i ''`).
-        local _tmp
-        _tmp="$(mktemp "${data_file}.XXXXXX")" || die "Cannot create tempfile"
-        # Explicit if/else instead of A && B || C — the latter (SC2015)
-        # silently runs C when B itself fails, masking real mv errors.
+      [[ -f "$data_file" ]] || die ".chezmoidata.toml not found: $data_file"
+      # Atomic write: render into a tempfile + mv so concurrent
+      # `dot fleet namespace set` callers can't corrupt the TOML.
+      # Avoids `sed -i` portability dance (GNU `-i` vs BSD `-i ''`).
+      local _tmp _rendered=0
+      _tmp="$(mktemp "${data_file}.XXXXXX")" || die "Cannot create tempfile"
+      # Explicit if/else instead of A && B || C — the latter (SC2015)
+      # silently runs C when B itself fails, masking real mv errors.
+      if grep -q "^namespace = " "$data_file"; then
         if sed "s/^namespace = \".*\"/namespace = \"$new_ns\"/" "$data_file" >"$_tmp"; then
-          if ! mv "$_tmp" "$data_file"; then
-            rm -f "$_tmp"
-            die "Failed to commit namespace update"
-          fi
-        else
+          _rendered=1
+        fi
+      else
+        # No key yet — the shipped .chezmoidata.toml has none, and rewriting
+        # only when one already existed made `set` a silent no-op on a fresh
+        # checkout while still reporting success. Insert it after the first
+        # line: appending at the end would land the key inside whatever
+        # [table] the file happens to end with, which TOML reads as a
+        # different key entirely. `dot profile set` does the same for
+        # `profile`.
+        if awk -v ns="$new_ns" '
+          NR == 1 { print; printf "namespace = \"%s\"\n", ns; inserted = 1; next }
+          { print }
+          END { if (!inserted) printf "namespace = \"%s\"\n", ns }
+        ' "$data_file" >"$_tmp"; then
+          _rendered=1
+        fi
+      fi
+      if [[ "$_rendered" -eq 1 ]]; then
+        if ! mv "$_tmp" "$data_file"; then
           rm -f "$_tmp"
-          die "Failed to render namespace update"
+          die "Failed to commit namespace update"
         fi
+      else
+        rm -f "$_tmp"
+        die "Failed to render namespace update"
       fi
       ui_ok "Namespace" "Set to '$new_ns'. Run 'dot sync' to apply."
       _fleet_emit_event "namespace_set" "ok" "namespace=$new_ns"

package/scripts/dot/commands/init.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck shell=bash
 #

package/scripts/dot/commands/lint.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Lint Command
 # Wraps shellcheck and shfmt with project-specific flags

package/scripts/dot/commands/manual.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # dot manual — open or download the dotfiles manual in multiple formats.
 #

package/scripts/dot/commands/meta.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Meta Commands
 # upgrade, prewarm, docs, learn, keys, sandbox, mcp, mode, agent
@@ -28,7 +28,12 @@ meta_banner_section() {
   esac
 }
 
-dot_ui_command_banner "$(meta_banner_section "${1:-}")" "${1:-}" "$@"
+# `mcp serve` owns stdout from its first byte — it is a JSON-RPC frame stream,
+# not a terminal — so the banner is suppressed for it outright. (It already
+# self-suppresses off a TTY; this also covers a client that allocates a pty.)
+if [[ "${1:-}" != "mcp" || "${2:-}" != "serve" ]]; then
+  dot_ui_command_banner "$(meta_banner_section "${1:-}")" "${1:-}" "$@"
+fi
 
 # Last meaningful line of a captured log, used as a step's `ok` detail.
 # Collapses carriage-return progress (git/nvim spam \r), strips ANSI,
@@ -65,7 +70,13 @@ cmd_upgrade() {
     [[ "${1:-}" == "--" ]] && shift
     local log="$log_dir/$id.log" rc=0
     ui_step "$id" "$label" run "$running"
-    "$@" >"$log" 2>&1 || rc=$?
+    # stdin is closed on purpose. Output is captured to a log, so a phase
+    # that prompts (chezmoi's "X has changed since chezmoi last wrote it?",
+    # a git credential helper, nvim waiting on a keypress) would otherwise
+    # block on the terminal with its question invisible — the 2026-09-12
+    # "chezmoi update seems very slow" report. With no stdin the prompt
+    # fails fast, the step is marked failed, and the tail below says why.
+    "$@" >"$log" 2>&1 </dev/null || rc=$?
     if [[ "$rc" -eq 0 ]]; then
       ui_step "$id" "" ok "$(_upgrade_last_line "$log")"
     else
@@ -84,11 +95,27 @@ cmd_upgrade() {
     _upgrade_step nix-gc "Nix GC" "collecting…" -- nix-collect-garbage -d
   fi
 
-  _upgrade_step dotfiles "Dotfiles" "chezmoi update…" -- chezmoi update
+  # --no-tty: chezmoi otherwise opens /dev/tty directly for its
+  # overwrite prompt, bypassing the closed stdin above and hanging.
+  _upgrade_step dotfiles "Dotfiles" "chezmoi update…" -- chezmoi update --no-tty
 
   if has_command nvim; then
-    _upgrade_step nvim "Neovim plugins" "Lazy sync…" -- \
-      nvim --headless "+Lazy! sync" +qa
+    # scripts/nvim/headless-upgrade.lua runs Lazy sync AND waits for
+    # Mason's async install queue to drain, so ensure_installed installs
+    # (codelldb, debugpy, delve, etc.) aren't aborted by an early quitall.
+    #
+    # `nvim -l` does NOT load the user's init.lua, so without an explicit
+    # -u the script found no lazy.nvim and logged "skipping plugin update"
+    # on every run — the upgrade step was a silent no-op. Point -u at the
+    # config nvim would load itself (honouring XDG_CONFIG_HOME and
+    # NVIM_APPNAME) and skip visibly when there is none to load.
+    local nvim_init="${XDG_CONFIG_HOME:-$HOME/.config}/${NVIM_APPNAME:-nvim}/init.lua"
+    if [ -f "$nvim_init" ]; then
+      _upgrade_step nvim "Neovim plugins" "Lazy sync + Mason drain…" -- \
+        nvim --headless -u "$nvim_init" -l "$src_dir/scripts/nvim/headless-upgrade.lua"
+    else
+      ui_step nvim "Neovim plugins" skip "no init.lua at $nvim_init"
+    fi
   fi
 
   if [ "${DOTFILES_FONTS:-}" = "1" ] &&
@@ -109,6 +136,9 @@ cmd_upgrade() {
     while ((i < n)); do
       ui_err "${fail_labels[$i]}" "log tail:"
       tail -n 15 "${fail_logs[$i]}" | sed 's/^/    /'
+      if grep -q 'has changed since chezmoi last wrote it' "${fail_logs[$i]}"; then
+        ui_info "Hint" "a managed file was edited locally — run 'chezmoi apply' to choose per file, or 'chezmoi update --force' to overwrite"
+      fi
       ((i++)) || true
     done
     ui_info "Logs" "$log_dir"
@@ -196,11 +226,33 @@ cmd_keys() {
     return 0
   fi
 
-  if [ -n "$src_dir" ] && [ -f "$src_dir/docs/KEYS.md" ]; then
+  # The keybindings document lives at docs/security/KEYS.md. Probing only
+  # docs/KEYS.md meant every `dot keys` fell through to
+  # scripts/diagnostics/keys.sh, which is not in the tree either, so the
+  # command could only ever report "Keys script not found". The legacy path
+  # stays in the list for trees that predate the move.
+  local keys_doc=""
+  if [ -n "$src_dir" ]; then
+    local candidate
+    for candidate in docs/security/KEYS.md docs/KEYS.md; do
+      if [ -f "$src_dir/$candidate" ]; then
+        keys_doc="$src_dir/$candidate"
+        break
+      fi
+    done
+  fi
+
+  if [ -n "$keys_doc" ]; then
     if [ -n "${1:-}" ]; then
-      rg -i --fixed-strings --context 1 "${1:-}" "$src_dir/docs/KEYS.md" || true
+      # ripgrep is not installed everywhere (the CI runners have none), and
+      # a bare `rg` there printed nothing at all while exiting 0.
+      if has_command rg; then
+        rg -i --fixed-strings --context 1 "${1:-}" "$keys_doc" || true
+      else
+        grep -i -F -C 1 -- "${1:-}" "$keys_doc" || true
+      fi
     else
-      exec cat "$src_dir/docs/KEYS.md"
+      exec cat "$keys_doc"
     fi
   else
     run_script "scripts/diagnostics/keys.sh" "Keys script" "$@"
@@ -268,13 +320,66 @@ cmd_mcp() {
         exec cat "$registry_file"
       fi
       ;;
+    serve)
+      cmd_mcp_serve "$@"
+      ;;
     *)
-      echo "Usage: dot mcp [doctor|registry]" >&2
+      echo "Usage: dot mcp [doctor|registry|serve]" >&2
       exit 1
       ;;
   esac
 }
 
+# cmd_mcp_serve — exec the stdio MCP server (dot-mcp).
+#
+# This is the transport `.well-known/mcp/server-card.json` advertises:
+# JSON-RPC 2.0 over newline-delimited frames on stdin/stdout. Nothing this
+# function prints may reach stdout, because stdout is the protocol stream from
+# the moment the client launches us — every message below goes to stderr, and
+# the server is exec'd so it owns the descriptors outright.
+#
+# The binary is deployed by run_onchange_26-build-dot-mcp.sh. When it is not
+# built yet and a Go toolchain is available, it is built on demand into the
+# user cache rather than failing: a client that trusted the card must get a
+# server, not an error.
+cmd_mcp_serve() {
+  local repo_root="" source_dir bin src cache
+  # resolve_chezmoi_source_dir points at the chezmoi source (the `defaults/`
+  # directory); the server wants the repository above it. Fall back to the
+  # checkout root when chezmoi is not configured.
+  source_dir="$(resolve_chezmoi_source_dir 2>/dev/null || true)"
+  if [[ -n "$source_dir" && -d "$source_dir" ]]; then
+    repo_root="$(cd "$source_dir/.." && pwd)"
+  fi
+  [[ -n "$repo_root" ]] || repo_root="$(require_source_dir)"
+
+  # Tell the server which tree it is serving, and which CLI to shell out to,
+  # so it never has to guess either.
+  export DOT_MCP_REPO_ROOT="$repo_root"
+  export DOT_MCP_DOT_BIN="${DOT_MCP_DOT_BIN:-$(command -v dot || echo dot)}"
+
+  if bin="$(command -v dot-mcp 2>/dev/null)"; then
+    exec "$bin" serve "$@"
+  fi
+  if [[ -x "$HOME/.local/bin/dot-mcp" ]]; then
+    exec "$HOME/.local/bin/dot-mcp" serve "$@"
+  fi
+
+  src="$repo_root/defaults/dot_local/share/dot-mcp"
+  [[ -d "$src" ]] || src="$HOME/.local/share/dot-mcp"
+  if [[ -f "$src/main.go" ]] && has_command go; then
+    cache="${XDG_CACHE_HOME:-$HOME/.cache}/dotfiles"
+    mkdir -p "$cache"
+    echo "dot mcp serve: building dot-mcp (first run)…" >&2
+    if (cd "$src" && go build -o "$cache/dot-mcp" .) >&2; then
+      exec "$cache/dot-mcp" serve "$@"
+    fi
+  fi
+
+  echo "dot mcp serve: dot-mcp is not built. Run 'chezmoi apply' (or 'go build' in $src) to install it." >&2
+  exit 1
+}
+
 # Dispatch — cmd_mode is defined in agent.sh (sourced above)
 case "${1:-}" in
   upgrade)

package/scripts/dot/commands/patterns.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # AI Steering Patterns Management.
 # Usage: dot patterns [list|view|edit] [name]

package/scripts/dot/commands/registry.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # shellcheck shell=bash
 #
@@ -76,6 +76,38 @@ _registry_cache_dir() {
   printf '%s/dotfiles/registry\n' "${XDG_CACHE_HOME:-$HOME/.cache}"
 }
 
+## The index cache is keyed by URL, not by one fixed path.
+##
+## It used to live at <cache>/index.json for every registry, and be treated as
+## fresh for six hours: a freshness window says nothing about WHICH registry
+## produced the file, so changing DOTFILES_REGISTRY_URL — or running
+## `dot registry set-url` — kept serving the previous registry's index for up
+## to six hours. Keying by URL also means switching back and forth does not
+## re-download.
+##
+## SHA-256 where a hasher exists, POSIX `cksum` otherwise: this is a cache
+## key, not a security boundary, and every index is schema-validated on read.
+_registry_cache_key() {
+  local url="$1" digest=""
+  if command -v shasum >/dev/null 2>&1; then
+    digest="$(printf '%s' "$url" | shasum -a 256 2>/dev/null | awk '{print $1}')"
+  elif command -v sha256sum >/dev/null 2>&1; then
+    digest="$(printf '%s' "$url" | sha256sum 2>/dev/null | awk '{print $1}')"
+  fi
+  if [[ -z "$digest" ]]; then
+    digest="$(printf '%s' "$url" | cksum | awk '{print $1 "-" $2}')"
+  fi
+  printf '%s\n' "${digest:0:32}"
+}
+
+## _registry_cache_file [url] — absolute path of the cached index for a URL
+## (the active one by default). Tests seed the cache through this.
+_registry_cache_file() {
+  local url="${1:-}"
+  [[ -n "$url" ]] || url="$(_registry_url)"
+  printf '%s/index-%s.json\n' "$(_registry_cache_dir)" "$(_registry_cache_key "$url")"
+}
+
 _registry_data_dir() {
   printf '%s/dotfiles/modules\n' "${XDG_DATA_HOME:-$HOME/.local/share}"
 }
@@ -95,15 +127,19 @@ _registry_validate_index() {
   ' "$index" >/dev/null 2>&1
 }
 
+# Prints the path of a validated index file on stdout. Every diagnostic goes
+# to stderr: stdout is this function's return channel, and callers read it
+# with `index="$(_registry_fetch)"` — a warning printed here would be
+# captured into that variable and then handed to jq as a filename.
 _registry_fetch() {
   local url cache_dir cache_file
   url="$(_registry_url)"
   [[ "$url" =~ ^(https://|file://) ]] || {
-    ui_err "registry" "registry URL must use https:// (or file:// for local testing)"
+    ui_err "registry" "registry URL must use https:// (or file:// for local testing)" >&2
     return 1
   }
   cache_dir="$(_registry_cache_dir)"
-  cache_file="$cache_dir/index.json"
+  cache_file="$(_registry_cache_file "$url")"
   mkdir -p "$cache_dir"
   # Refresh if older than 6h or missing.
   local now mtime
@@ -119,7 +155,7 @@ _registry_fetch() {
     fi
   fi
   if ! command -v curl >/dev/null 2>&1; then
-    ui_err "registry" "curl not installed"
+    ui_err "registry" "curl not installed" >&2
     return 127
   fi
   local tmp
@@ -137,17 +173,17 @@ _registry_fetch() {
   if ! curl "${curl_args[@]}" -o "$tmp" "$url" >/dev/null; then
     rm -f "$tmp"
     if [[ -s "$cache_file" ]]; then
-      ui_warn "registry" "fetch failed; using stale cache at $cache_file"
+      ui_warn "registry" "fetch failed; using stale cache at $cache_file" >&2
       printf '%s\n' "$cache_file"
       return 0
     fi
-    ui_err "registry" "could not fetch $url"
+    ui_err "registry" "could not fetch $url" >&2
     return 1
   fi
   mv "$tmp" "$cache_file"
   if ! _registry_validate_index "$cache_file"; then
     rm -f "$cache_file"
-    ui_err "registry" "index failed schema and integrity validation"
+    ui_err "registry" "index failed schema and integrity validation" >&2
     return 1
   fi
   printf '%s\n' "$cache_file"

package/scripts/dot/commands/restore.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # dot restore - Restore dotfiles from backup or previous state
 # Usage: dot restore [--list|-l|--latest|-L|<backup-id>]

package/scripts/dot/commands/secrets.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Secrets/Env Commands
 # secrets-init, secrets, secrets-create, ssh-key, env load

package/scripts/dot/commands/security.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Security Commands
 # backup, encrypt-check, firewall, telemetry, dns-doh, lock-screen, usb-safety

package/scripts/dot/commands/tools.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: MIT
+# SPDX-License-Identifier: Apache-2.0 OR MIT
 # Copyright (c) 2015-2026 Sebastien Rousseau
 # Dotfiles CLI - Tools Commands
 # tools, new, packages, log-rotate, aliases, alias-check, env, profile
@@ -196,7 +196,15 @@ show_language_package_managers() {
     # mid-output. Capture the pipeline separately so we can fall back
     # cleanly without stray "N/A" lines from pipe-with-|| tricks.
     if pipx_list_out="$(pipx list --short 2>/dev/null)"; then
-      pipx_installed="$(printf '%s' "$pipx_list_out" | wc -l | tr -d ' ')"
+      # Command substitution strips the trailing newline, so counting
+      # with `printf '%s' … | wc -l` reported one package fewer than
+      # installed (and 0 when exactly one was installed). Re-add the
+      # terminator, and treat "no output" as zero rather than one.
+      if [[ -n "$pipx_list_out" ]]; then
+        pipx_installed="$(printf '%s\n' "$pipx_list_out" | wc -l | tr -d ' ')"
+      else
+        pipx_installed=0
+      fi
     else
       pipx_installed="N/A"
     fi
@@ -245,11 +253,17 @@ cmd_tools() {
       exit 1
     fi
   elif [ "$subcommand" = "docs" ]; then
-    if [ -n "$src_dir" ] && [ -f "$src_dir/docs/TOOLS.md" ]; then
-      exec cat "$src_dir/docs/TOOLS.md"
-    elif [ -n "$src_dir" ] && [ -f "$src_dir/docs/UTILS.md" ]; then
-      exec cat "$src_dir/docs/UTILS.md"
-    fi
+    # docs/reference/ first: both documents were moved there, and looking
+    # only in docs/ meant `dot tools docs` answered "TOOLS.md not found" on a
+    # complete checkout. The legacy paths stay in the list so a pre-reorg
+    # tree still resolves.
+    local doc
+    for doc in docs/reference/TOOLS.md docs/reference/UTILS.md \
+      docs/TOOLS.md docs/UTILS.md; do
+      if [ -n "$src_dir" ] && [ -f "$src_dir/$doc" ]; then
+        exec cat "$src_dir/$doc"
+      fi
+    done
     ui_err "Docs" "TOOLS.md not found"
     exit 1
   else