@sebastienrousseau/dotfiles 0.2.499 → 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

@@ -0,0 +1,248 @@
+#!/usr/bin/env bash
+# Copyright (c) 2015-2026 Dotfiles. All rights reserved.
+# Dotfiles CLI - Meta Commands
+# upgrade, prewarm, docs, learn, keys, sandbox, mcp, mode, agent
+
+set -euo pipefail
+
+_META_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../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
+    ui_info "Updating Nix flake"
+    (cd "$src_dir" && nix flake update) || true
+    ui_info "Running Nix garbage collection"
+    nix-collect-garbage -d || true
+  fi
+
+  ui_info "Updating dotfiles"
+  chezmoi update || true
+
+  if has_command nvim; then
+    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
+      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
+    if has_command glow; then
+      glow "$src_dir/README.md"
+    else
+      exec cat "$src_dir/README.md"
+    fi
+  else
+    die "README not found."
+  fi
+}
+
+cmd_learn() {
+  local dot_bin
+  dot_bin="$(dirname "${BASH_SOURCE[0]}")/../../../dot_local/bin"
+  if [ -f "$dot_bin/executable_tour" ]; then
+    exec bash "$dot_bin/executable_tour" "$@"
+  fi
+  # 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
+    else
+      exec cat "$src_dir/docs/KEYS.md"
+    fi
+  else
+    run_script "scripts/diagnostics/keys.sh" "Keys script" "$@"
+  fi
+}
+
+cmd_sandbox() {
+  local src_dir
+  src_dir="$(require_source_dir)"
+
+  if has_command docker; then
+    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
+    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
+    die "Docker or Podman is required for sandbox."
+  fi
+}
+
+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 "$@"
+    ;;
+  learn)
+    shift
+    cmd_learn "$@"
+    ;;
+  keys)
+    shift
+    cmd_keys "$@"
+    ;;
+  sandbox)
+    shift
+    cmd_sandbox "$@"
+    ;;
+  mcp)
+    shift
+    cmd_mcp "$@"
+    ;;
+  mode | agent)
+    shift
+    cmd_mode "$@"
+    ;;
+  *)
+    echo "Unknown meta command: ${1:-}" >&2
+    exit 1
+    ;;
+esac

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

@@ -0,0 +1,231 @@
+#!/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|-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"
+
+ui_init
+
+usage() {
+  echo "Usage: dot restore [OPTIONS]"
+  echo ""
+  echo "Options:"
+  echo "  --list, -l       List available backups"
+  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:"
+  echo "  dot restore --list"
+  echo "  dot restore --latest"
+  echo "  dot restore --git HEAD~1"
+  echo "  dot restore --git v0.2.470"
+}
+
+list_backups() {
+  if [[ ! -d "$BACKUP_DIR" ]]; then
+    log_warn "No backups found at $BACKUP_DIR"
+    return 1
+  fi
+
+  ui_header "Available Backups"
+  echo "─────────────────────────────────────────"
+
+  while IFS= read -r backup; do
+    echo "  $backup"
+  done < <(list_backup_names)
+
+  echo ""
+  echo ""
+  ui_header "Git History (last 10)"
+  echo "─────────────────────────────────────────"
+
+  if [[ -d "$DOTFILES_DIR/.git" ]]; then
+    git -C "$DOTFILES_DIR" log --oneline -10
+  elif [[ -d "$CHEZMOI_SOURCE/.git" ]]; then
+    git -C "$CHEZMOI_SOURCE" log --oneline -10
+  fi
+}
+
+restore_from_git() {
+  local ref="$1"
+  local dry_run="${2:-false}"
+  local source_dir
+
+  if [[ -d "$DOTFILES_DIR/.git" ]]; then
+    source_dir="$DOTFILES_DIR"
+  elif [[ -d "$CHEZMOI_SOURCE/.git" ]]; then
+    source_dir="$CHEZMOI_SOURCE"
+  else
+    log_error "No git repository found"
+    return 1
+  fi
+
+  log_info "Restoring from git ref: $ref"
+
+  if $dry_run; then
+    log_info "Dry run - showing changes:"
+    git -C "$source_dir" diff "$ref" --stat
+    return 0
+  fi
+
+  # Create backup first
+  create_backup
+
+  # Restore
+  git -C "$source_dir" checkout "$ref" -- .
+  log_success "Restored from $ref"
+
+  # Re-apply chezmoi
+  if has_command chezmoi; then
+    log_info "Re-applying chezmoi..."
+    chezmoi apply
+  fi
+}
+
+show_diff() {
+  local ref="$1"
+  local source_dir
+
+  if [[ -d "$DOTFILES_DIR/.git" ]]; then
+    source_dir="$DOTFILES_DIR"
+  elif [[ -d "$CHEZMOI_SOURCE/.git" ]]; then
+    source_dir="$CHEZMOI_SOURCE"
+  else
+    log_error "No git repository found"
+    return 1
+  fi
+
+  git -C "$source_dir" diff "$ref"
+}
+
+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"
+
+  log_info "Creating backup: $backup_name"
+
+  # Backup key config files
+  local files_to_backup=(
+    "$HOME/.zshrc"
+    "$HOME/.config/zsh"
+    "$HOME/.config/nvim"
+    "$HOME/.config/git"
+    "$HOME/.gitconfig"
+  )
+
+  for f in "${files_to_backup[@]}"; do
+    if [[ -e "$f" ]]; then
+      rel_path="${f#"$HOME"/}"
+      mkdir -p "$backup_path/$(dirname "$rel_path")"
+      cp -r "$f" "$backup_path/$rel_path" 2>/dev/null || true
+    fi
+  done
+
+  log_success "Backup created at $backup_path"
+}
+
+restore_latest() {
+  if [[ ! -d "$BACKUP_DIR" ]]; then
+    log_error "No backups found"
+    return 1
+  fi
+
+  local latest
+  latest=$(list_backup_names | head -1)
+
+  if [[ -z "$latest" ]]; then
+    log_error "No backups found"
+    return 1
+  fi
+
+  log_info "Restoring from: $latest"
+
+  local backup_path="$BACKUP_DIR/$latest"
+  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
+DRY_RUN=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -l | --list)
+      list_backups
+      exit 0
+      ;;
+    --latest | -L)
+      restore_latest
+      exit 0
+      ;;
+    --git | -g)
+      restore_from_git "$2" "$DRY_RUN"
+      exit 0
+      ;;
+    --diff | -d)
+      show_diff "$2"
+      exit 0
+      ;;
+    --dry-run | -n)
+      DRY_RUN=true
+      shift
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      log_error "Unknown option: $1"
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+# Default: show usage
+usage