@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/scripts/dot/commands/manual.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# dot manual — open or download the dotfiles manual in multiple formats.
+#
+# Usage:
+#   dot manual                   # open HTML manual in browser
+#   dot manual html              # alias of no-arg
+#   dot manual pdf               # download + open PDF
+#   dot manual epub              # download + open EPUB
+#   dot manual text              # pipe ASCII text to pager
+#   dot manual markdown          # pipe Markdown source to pager
+#   dot manual download <fmt>    # save to current directory
+#   dot manual --offline         # use bundled offline copy
+#   dot manual --local           # use locally-built _build/manual/
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/utils.sh
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+MANUAL_URL="${DOTFILES_MANUAL_URL:-https://sebastienrousseau.github.io/dotfiles/manual}"
+CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/dotfiles/manual"
+OFFLINE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/manual"
+
+MODE="open"
+FORMAT="html"
+USE_LOCAL=false
+USE_OFFLINE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    html | html-multi | pdf | epub | text | markdown) FORMAT="$arg" ;;
+    download) MODE="download" ;;
+    --offline) USE_OFFLINE=true ;;
+    --local) USE_LOCAL=true ;;
+    --url=*) MANUAL_URL="${arg#*=}" ;;
+    --help | -h)
+      sed -n 's/^# //p;s/^#$//p' "$0" | head -20
+      exit 0
+      ;;
+  esac
+done
+
+format_file() {
+  case "$1" in
+    html) echo "dotfiles.html" ;;
+    html-multi) echo "html/index.html" ;;
+    pdf) echo "dotfiles.pdf" ;;
+    epub) echo "dotfiles.epub" ;;
+    text) echo "dotfiles.txt" ;;
+    markdown) echo "dotfiles-md.tar.gz" ;;
+    *) return 1 ;;
+  esac
+}
+
+resolve_source() {
+  local fmt="$1"
+  local fname
+  fname="$(format_file "$fmt")"
+
+  if $USE_LOCAL; then
+    local src_dir
+    src_dir="$(require_source_dir)/_build/manual"
+    if [[ -f "$src_dir/$fname" ]]; then
+      echo "$src_dir/$fname"
+      return 0
+    fi
+    ui_err "manual" "local build not found at $src_dir/$fname — run bash scripts/docs/build-manual.sh"
+    return 1
+  fi
+
+  if $USE_OFFLINE; then
+    if [[ -f "$OFFLINE_DIR/$fname" ]]; then
+      echo "$OFFLINE_DIR/$fname"
+      return 0
+    fi
+    ui_err "manual" "offline copy not found at $OFFLINE_DIR/$fname"
+    return 1
+  fi
+
+  local cache_path="$CACHE_DIR/$fname"
+  if [[ ! -f "$cache_path" ]] || [[ $(find "$cache_path" -mtime +7 -print 2>/dev/null | wc -l) -gt 0 ]]; then
+    mkdir -p "$(dirname "$cache_path")"
+    local url="$MANUAL_URL/$fname"
+    ui_info "manual" "fetching $url"
+    if ! curl -fsSL "$url" -o "$cache_path"; then
+      ui_err "manual" "failed to download $url"
+      return 1
+    fi
+  fi
+  echo "$cache_path"
+}
+
+open_file() {
+  local path="$1"
+  case "$(uname -s)" in
+    Darwin)
+      # Use the system open explicitly — ~/.local/bin/open is a wrapper
+      # that would recurse on itself.
+      /usr/bin/open "$path"
+      ;;
+    Linux)
+      if command -v xdg-open &>/dev/null; then
+        xdg-open "$path"
+      elif command -v gio &>/dev/null; then
+        gio open "$path"
+      else
+        ui_err "manual" "no opener found (xdg-open, gio); use file://$path"
+        return 1
+      fi
+      ;;
+    *)
+      ui_info "manual" "saved to: $path"
+      ;;
+  esac
+}
+
+cmd_open() {
+  local path
+  path="$(resolve_source "$FORMAT")"
+  [[ -z "$path" ]] && exit 1
+
+  case "$FORMAT" in
+    text)
+      ${PAGER:-less} "$path"
+      ;;
+    markdown)
+      local tmpdir
+      tmpdir="$(mktemp -d)"
+      tar -xzf "$path" -C "$tmpdir"
+      ui_info "manual" "Markdown source extracted to: $tmpdir"
+      open_file "$tmpdir" 2>/dev/null || true
+      ;;
+    html)
+      if ! $USE_LOCAL && ! $USE_OFFLINE; then
+        open_file "$MANUAL_URL/"
+      else
+        open_file "$path"
+      fi
+      ;;
+    html-multi)
+      if ! $USE_LOCAL && ! $USE_OFFLINE; then
+        open_file "$MANUAL_URL/html/"
+      else
+        open_file "$path"
+      fi
+      ;;
+    *)
+      open_file "$path"
+      ;;
+  esac
+}
+
+cmd_download() {
+  local path
+  path="$(resolve_source "$FORMAT")"
+  [[ -z "$path" ]] && exit 1
+  local dest
+  dest="./$(basename "$path")"
+  cp "$path" "$dest"
+  ui_ok "manual" "saved: $dest"
+}
+
+case "$MODE" in
+  open) cmd_open ;;
+  download) cmd_download ;;
+esac

package/scripts/dot/commands/meta.sh

@@ -1,46 +1,87 @@
 #!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
 # Dotfiles CLI - Meta Commands
-# upgrade, docs, learn, keys, sandbox
+# upgrade, prewarm, docs, learn, keys, sandbox, mcp, mode, agent
 
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_META_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=../lib/utils.sh
-source "$SCRIPT_DIR/../lib/utils.sh"
+source "$_META_DIR/../lib/utils.sh"
+# shellcheck source=../lib/log.sh
+source "$_META_DIR/../lib/log.sh"
+# shellcheck source=agent.sh
+source "$_META_DIR/agent.sh"
+
+meta_banner_section() {
+  case "${1:-}" in
+    mcp | mode | agent)
+      printf '%s\n' "AI and Agents"
+      ;;
+    docs | keys | learn | search | help | version)
+      printf '%s\n' "Reference"
+      ;;
+    *)
+      printf '%s\n' "Meta"
+      ;;
+  esac
+}
+
+dot_ui_command_banner "$(meta_banner_section "${1:-}")" "${1:-}" "$@"
 
 cmd_upgrade() {
   local src_dir
   src_dir="$(require_source_dir)"
 
   if [ -f "$src_dir/nix/flake.nix" ] && has_command nix; then
-    echo "Updating Nix flake..."
+    ui_info "Updating Nix flake"
     (cd "$src_dir" && nix flake update) || true
-    echo "Running Nix garbage collection..."
+    ui_info "Running Nix garbage collection"
     nix-collect-garbage -d || true
   fi
 
-  echo "Updating dotfiles..."
+  ui_info "Updating dotfiles"
   chezmoi update || true
 
   if has_command nvim; then
-    echo "Updating Neovim plugins..."
+    ui_info "Updating Neovim plugins"
     nvim --headless "+Lazy! sync" +qa || true
   fi
 
   if [ "${DOTFILES_FONTS:-}" = "1" ]; then
     if [ -f "$src_dir/scripts/fonts/install-nerd-fonts.sh" ]; then
-      echo "Installing Nerd Fonts..."
+      ui_info "Installing Nerd Fonts"
       sh "$src_dir/scripts/fonts/install-nerd-fonts.sh"
     fi
   fi
 }
 
+cmd_prewarm() {
+  local src_dir
+  # 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
+  ui_info "Cache" "Cleared. Regenerating..."
+  src_dir="$(resolve_source_dir)"
+  if [ -n "$src_dir" ] && [ -f "$src_dir/scripts/ops/prewarm.sh" ]; then
+    bash "$src_dir/scripts/ops/prewarm.sh"
+  fi
+}
+
 cmd_docs() {
   local src_dir
   src_dir="$(resolve_source_dir)"
 
   if [ -n "$src_dir" ] && [ -f "$src_dir/README.md" ]; then
-    exec cat "$src_dir/README.md"
+    if has_command glow; then
+      glow "$src_dir/README.md"
+    else
+      exec cat "$src_dir/README.md"
+    fi
   else
     die "README not found."
   fi
@@ -52,22 +93,50 @@ cmd_learn() {
   if [ -f "$dot_bin/executable_tour" ]; then
     exec bash "$dot_bin/executable_tour" "$@"
   fi
-  # Fallback to PATH
-  exec tour "$@"
+  # Fallback to ops script
+  run_script "scripts/ops/tour.sh" "Tour script" "$@"
 }
 
 cmd_keys() {
   local src_dir
   src_dir="$(resolve_source_dir)"
 
+  if [[ "${1:-}" == "sign-check" ]]; then
+    ui_header "Git Signing Status"
+    local signing_key="" format="" key_file=""
+    signing_key="$(git config --global user.signingkey 2>/dev/null || true)"
+    format="$(git config --global gpg.format 2>/dev/null || true)"
+    if [[ -z "$signing_key" ]]; then
+      ui_warn "No signing key configured (git config --global user.signingkey)"
+    else
+      ui_info "Key" "$signing_key"
+      ui_info "Format" "${format:-gpg}"
+      if [[ "$format" == "ssh" ]]; then
+        key_file="${signing_key/#\~/$HOME}"
+        if [[ -f "$key_file" ]]; then
+          ui_info "Status" "SSH key file exists: $key_file"
+        else
+          ui_warn "SSH key file not found: $key_file"
+        fi
+      else
+        if has_command gpg && gpg --list-keys "$signing_key" >/dev/null 2>&1; then
+          ui_info "Status" "GPG key found in keyring"
+        else
+          ui_warn "GPG key not found in keyring: $signing_key"
+        fi
+      fi
+    fi
+    return 0
+  fi
+
   if [ -n "$src_dir" ] && [ -f "$src_dir/docs/KEYS.md" ]; then
-    if [ -n "$1" ]; then
-      rg -i --fixed-strings --context 1 "$1" "$src_dir/docs/KEYS.md" || true
+    if [ -n "${1:-}" ]; then
+      rg -i --fixed-strings --context 1 "${1:-}" "$src_dir/docs/KEYS.md" || true
     else
       exec cat "$src_dir/docs/KEYS.md"
     fi
   else
-    die "Keybindings catalog not found."
+    run_script "scripts/diagnostics/keys.sh" "Keys script" "$@"
   fi
 }
 
@@ -76,11 +145,11 @@ cmd_sandbox() {
   src_dir="$(require_source_dir)"
 
   if has_command docker; then
-    echo "Launching sandbox via Docker..."
+    ui_info "Launching sandbox via Docker"
     docker build -f "$src_dir/tests/Dockerfile.sandbox" -t dotfiles-sandbox "$src_dir"
     exec docker run --rm -it dotfiles-sandbox
   elif has_command podman; then
-    echo "Launching sandbox via Podman..."
+    ui_info "Launching sandbox via Podman"
     podman build -f "$src_dir/tests/Dockerfile.sandbox" -t dotfiles-sandbox "$src_dir"
     exec podman run --rm -it dotfiles-sandbox
   else
@@ -88,12 +157,66 @@ cmd_sandbox() {
   fi
 }
 
-# Dispatch
+cmd_mcp() {
+  local subcommand="${1:-doctor}"
+  if [[ "${1:-}" == --* ]] || [[ "${1:-}" == -* ]] || [[ -z "${1:-}" ]]; then
+    subcommand="doctor"
+  else
+    shift || true
+  fi
+  case "$subcommand" in
+    doctor)
+      if [[ "${1:-}" == "doctor" ]]; then
+        shift || true
+      fi
+      run_script "scripts/diagnostics/mcp-doctor.sh" "MCP doctor script" "$@"
+      ;;
+    registry)
+      local repo_root registry_file json_mode=0
+      repo_root="$(require_source_dir)"
+      registry_file="${MCP_REGISTRY_CONFIG:-$repo_root/dot_config/dotfiles/mcp-registry.json}"
+      if [[ "${1:-}" == "registry" ]]; then
+        shift || true
+      fi
+      if [[ "${1:-}" == "--json" || "${1:-}" == "-j" ]]; then
+        json_mode=1
+      fi
+      if [[ ! -f "$registry_file" ]]; then
+        die "MCP registry not found: $registry_file"
+      fi
+      if [[ "$json_mode" -eq 1 ]]; then
+        exec cat "$registry_file"
+      fi
+      if command -v jq >/dev/null 2>&1; then
+        ui_header "MCP Registry"
+        jq -r '
+          .servers
+          | to_entries[]
+          | "\(.key)\t\(.value.transport)\t\(.value.launcher)\t\(.value.package // .value.url // "local")"
+        ' "$registry_file" | while IFS=$'\t' read -r name transport launcher target; do
+          ui_ok "$name" "$transport via $launcher -> $target"
+        done
+      else
+        exec cat "$registry_file"
+      fi
+      ;;
+    *)
+      echo "Usage: dot mcp [doctor|registry]" >&2
+      exit 1
+      ;;
+  esac
+}
+
+# Dispatch — cmd_mode is defined in agent.sh (sourced above)
 case "${1:-}" in
   upgrade)
     shift
     cmd_upgrade "$@"
     ;;
+  cache-refresh | prewarm)
+    shift
+    cmd_prewarm "$@"
+    ;;
   docs)
     shift
     cmd_docs "$@"
@@ -110,6 +233,14 @@ case "${1:-}" in
     shift
     cmd_sandbox "$@"
     ;;
+  mcp)
+    shift
+    cmd_mcp "$@"
+    ;;
+  mode | agent)
+    shift
+    cmd_mode "$@"
+    ;;
   *)
     echo "Unknown meta command: ${1:-}" >&2
     exit 1

package/scripts/dot/commands/patterns.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# AI Steering Patterns Management.
+# Usage: dot patterns [list|view|edit] [name]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/utils.sh
+source "$SCRIPT_DIR/../lib/utils.sh"
+
+PATTERN_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/ai/patterns"
+mkdir -p "$PATTERN_DIR"
+
+command="${1:-list}"
+name="${2:-}"
+
+case "$command" in
+  list)
+    ui_header "AI Steering Patterns"
+    ls -1 "$PATTERN_DIR" | sed 's/\.md$//' | while read -r p; do
+      ui_bullet "$p"
+    done
+    ;;
+  view)
+    if [[ -z "$name" ]]; then
+      ui_err "Missing pattern name" "Usage: dot patterns view <name>"
+      exit 1
+    fi
+    pattern_file="$PATTERN_DIR/${name}.md"
+    if [[ -f "$pattern_file" ]]; then
+      ui_header "Pattern: $name"
+      if has_command glow; then
+        glow "$pattern_file"
+      else
+        cat "$pattern_file"
+      fi
+    else
+      ui_err "Pattern not found" "$name"
+    fi
+    ;;
+  edit)
+    if [[ -z "$name" ]]; then
+      ui_err "Missing pattern name" "Usage: dot patterns edit <name>"
+      exit 1
+    fi
+    pattern_file="$PATTERN_DIR/${name}.md"
+    ${EDITOR:-nvim} "$pattern_file"
+    ;;
+  *)
+    echo "Usage: dot patterns [list|view|edit] [name]"
+    exit 1
+    ;;
+esac

package/scripts/dot/commands/restore.sh

@@ -1,34 +1,31 @@
 #!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
 # dot restore - Restore dotfiles from backup or previous state
-# Usage: dot restore [--list|--latest|<backup-id>]
+# Usage: dot restore [--list|-l|--latest|-L|<backup-id>]
 
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/utils.sh
+source "$SCRIPT_DIR/../lib/utils.sh"
+# shellcheck source=../lib/log.sh
+source "$SCRIPT_DIR/../lib/log.sh"
+
 DOTFILES_DIR="${DOTFILES_DIR:-$HOME/.dotfiles}"
 BACKUP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/dotfiles/backups"
 CHEZMOI_SOURCE="${HOME}/.local/share/chezmoi"
 
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m'
-
-log_info() { echo -e "${BLUE}[INFO]${NC} $*"; }
-log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
-log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
-log_success() { echo -e "${GREEN}[OK]${NC} $*"; }
+ui_init
 
 usage() {
   echo "Usage: dot restore [OPTIONS]"
   echo ""
   echo "Options:"
   echo "  --list, -l       List available backups"
-  echo "  --latest         Restore from latest backup"
-  echo "  --git <ref>      Restore from git ref (commit, tag, branch)"
-  echo "  --diff <ref>     Show diff between current and ref"
-  echo "  --dry-run        Show what would be restored"
+  echo "  --latest, -L     Restore from latest backup"
+  echo "  --git, -g <ref>  Restore from git ref (commit, tag, branch)"
+  echo "  --diff, -d <ref> Show diff between current and ref"
+  echo "  --dry-run, -n    Show what would be restored"
   echo "  -h, --help       Show this help"
   echo ""
   echo "Examples:"
@@ -44,15 +41,16 @@ list_backups() {
     return 1
   fi
 
-  echo -e "${BLUE}Available Backups:${NC}"
+  ui_header "Available Backups"
   echo "─────────────────────────────────────────"
 
-  find "$BACKUP_DIR" -maxdepth 1 -type d -name "backup-*" -printf "%T@ %f\n" 2>/dev/null | sort -rn | cut -d' ' -f2- | while read -r backup; do
+  while IFS= read -r backup; do
     echo "  $backup"
-  done
+  done < <(list_backup_names)
 
   echo ""
-  echo -e "${BLUE}Git History (last 10):${NC}"
+  echo ""
+  ui_header "Git History (last 10)"
   echo "─────────────────────────────────────────"
 
   if [[ -d "$DOTFILES_DIR/.git" ]]; then
@@ -92,7 +90,7 @@ restore_from_git() {
   log_success "Restored from $ref"
 
   # Re-apply chezmoi
-  if command -v chezmoi >/dev/null 2>&1; then
+  if has_command chezmoi; then
     log_info "Re-applying chezmoi..."
     chezmoi apply
   fi
@@ -118,6 +116,7 @@ create_backup() {
   local backup_name
   backup_name="backup-$(date +%Y%m%d_%H%M%S)"
   local backup_path="$BACKUP_DIR/$backup_name"
+  local rel_path
 
   mkdir -p "$backup_path"
 
@@ -134,7 +133,9 @@ create_backup() {
 
   for f in "${files_to_backup[@]}"; do
     if [[ -e "$f" ]]; then
-      cp -r "$f" "$backup_path/" 2>/dev/null || true
+      rel_path="${f#"$HOME"/}"
+      mkdir -p "$backup_path/$(dirname "$rel_path")"
+      cp -r "$f" "$backup_path/$rel_path" 2>/dev/null || true
     fi
   done
 
@@ -148,7 +149,7 @@ restore_latest() {
   fi
 
   local latest
-  latest=$(find "$BACKUP_DIR" -maxdepth 1 -type d -name "backup-*" -printf "%T@ %f\n" 2>/dev/null | sort -rn | head -1 | cut -d' ' -f2-)
+  latest=$(list_backup_names | head -1)
 
   if [[ -z "$latest" ]]; then
     log_error "No backups found"
@@ -158,14 +159,35 @@ restore_latest() {
   log_info "Restoring from: $latest"
 
   local backup_path="$BACKUP_DIR/$latest"
-  local target
-  for item in "$backup_path"/*; do
-    if [[ -e "$item" ]]; then
-      target="$HOME/$(basename "$item")"
-      cp -r "$item" "$target"
-      log_success "Restored: $(basename "$item")"
-    fi
-  done
+  local item rel_path target
+  while IFS= read -r -d '' item; do
+    rel_path="${item#"$backup_path"/}"
+    target="$HOME/$rel_path"
+    mkdir -p "$(dirname "$target")"
+    cp -r "$item" "$target"
+    log_success "Restored: $rel_path"
+  done < <(find "$backup_path" -mindepth 1 -maxdepth 1 -print0)
+}
+
+list_backup_names() {
+  local backup_path
+
+  shopt -s nullglob
+  for backup_path in "$BACKUP_DIR"/backup-*; do
+    [[ -d "$backup_path" ]] || continue
+    printf '%s\n' "${backup_path##*/}"
+  done | while IFS= read -r backup_name; do
+    printf '%s\t%s\n' "$(portable_mtime "$BACKUP_DIR/$backup_name")" "$backup_name"
+  done | sort -rn | cut -f2-
+  shopt -u nullglob
+}
+
+portable_mtime() {
+  if stat -c %Y "$1" >/dev/null 2>&1; then
+    stat -c %Y "$1"
+  else
+    stat -f %m "$1"
+  fi
 }
 
 # Parse arguments
@@ -177,19 +199,19 @@ while [[ $# -gt 0 ]]; do
       list_backups
       exit 0
       ;;
-    --latest)
+    --latest | -L)
       restore_latest
       exit 0
       ;;
-    --git)
+    --git | -g)
       restore_from_git "$2" "$DRY_RUN"
       exit 0
       ;;
-    --diff)
+    --diff | -d)
       show_diff "$2"
       exit 0
       ;;
-    --dry-run)
+    --dry-run | -n)
       DRY_RUN=true
       shift
       ;;