feat(core): add shared bootstrap entrypoint for plugin managers

Co-authored-by: mcornella <1441704+mcornella@users.noreply.github.com>

lib/bootstrap.zsh

@@ -0,0 +1,44 @@
+#
+# Shared Oh My Zsh bootstrap entrypoint.
+#
+# This file can be sourced by plugin managers that don't source `oh-my-zsh.sh`.
+# It is safe to source multiple times.
+#
+
+# Keep source path for callers that invoke omz_bootstrap again later.
+typeset -g _OMZ_BOOTSTRAP_SOURCE="${${(%):-%x}:a}"
+
+omz_bootstrap() {
+  # If ZSH is not defined, infer from this file location.
+  [[ -n "${ZSH:-}" ]] || export ZSH="${_OMZ_BOOTSTRAP_SOURCE:h:h}"
+
+  # Set ZSH_CUSTOM to the path where custom config files and plugins exist.
+  [[ -n "${ZSH_CUSTOM:-}" ]] || ZSH_CUSTOM="$ZSH/custom"
+
+  # Set cache directory.
+  [[ -n "${ZSH_CACHE_DIR:-}" ]] || ZSH_CACHE_DIR="$ZSH/cache"
+
+  # Ensure cache dir is writable, otherwise fallback to a HOME-based cache.
+  if [[ ! -w "$ZSH_CACHE_DIR" ]]; then
+    ZSH_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/oh-my-zsh"
+  fi
+
+  # Create cache and completions dir.
+  command mkdir -p "$ZSH_CACHE_DIR/completions"
+
+  # Add required OMZ search paths.
+  local dir
+  for dir in \
+    "$ZSH/functions" \
+    "$ZSH/completions" \
+    "$ZSH_CUSTOM/functions" \
+    "$ZSH_CUSTOM/completions" \
+    "$ZSH_CACHE_DIR/completions"; do
+    (( ${fpath[(Ie)$dir]} )) || fpath=("$dir" $fpath)
+  done
+
+  # Public signal: OMZ bootstrap has completed.
+  typeset -g OMZ_IS_BOOTSTRAPPED=true
+}
+
+omz_bootstrap "$@"

lib/tests/bootstrap.test.zsh

@@ -0,0 +1,88 @@
+#!/usr/bin/zsh -df
+
+set -u
+
+bootstrap_file="${0:A:h:h}/bootstrap.zsh"
+
+_assert() {
+  local condition="$1" message="$2"
+  if ! eval "$condition"; then
+    print -u2 "\e[31mError\e[0m: $message"
+    return 1
+  fi
+}
+
+test_bootstrap_sets_defaults_and_paths() {
+  local tmp==(:)
+  mkdir -p "$tmp/ohmyzsh"/{functions,completions,cache} "$tmp/ohmyzsh/custom"/{functions,completions}
+
+  (
+    set -e
+    export ZSH="$tmp/ohmyzsh"
+    unset ZSH_CUSTOM ZSH_CACHE_DIR OMZ_IS_BOOTSTRAPPED
+    fpath=()
+    source "$bootstrap_file"
+
+    _assert '[[ "$ZSH_CUSTOM" == "'"$tmp/ohmyzsh/custom"'" ]]' "ZSH_CUSTOM default should be set"
+    _assert '[[ "$ZSH_CACHE_DIR" == "'"$tmp/ohmyzsh/cache"'" ]]' "ZSH_CACHE_DIR default should be set"
+    _assert '[[ -d "'"$tmp/ohmyzsh/cache/completions"'" ]]' "completions dir should be created"
+    _assert '[[ "${fpath[(Ie)'"$tmp/ohmyzsh/functions"']}" -gt 0 ]]' "fpath should include OMZ functions dir"
+    _assert '[[ "${fpath[(Ie)'"$tmp/ohmyzsh/completions"']}" -gt 0 ]]' "fpath should include OMZ completions dir"
+    _assert '[[ "${fpath[(Ie)'"$tmp/ohmyzsh/custom/functions"']}" -gt 0 ]]' "fpath should include custom functions dir"
+    _assert '[[ "${fpath[(Ie)'"$tmp/ohmyzsh/custom/completions"']}" -gt 0 ]]' "fpath should include custom completions dir"
+    _assert '[[ "${fpath[(Ie)'"$tmp/ohmyzsh/cache/completions"']}" -gt 0 ]]' "fpath should include cache completions dir"
+    _assert '[[ "$OMZ_IS_BOOTSTRAPPED" == true ]]' "bootstrap signal should be set"
+  )
+}
+
+test_bootstrap_is_idempotent() {
+  local tmp==(:)
+  mkdir -p "$tmp/ohmyzsh"/{functions,completions,cache} "$tmp/ohmyzsh/custom"/{functions,completions}
+
+  (
+    set -e
+    export ZSH="$tmp/ohmyzsh"
+    unset ZSH_CUSTOM ZSH_CACHE_DIR OMZ_IS_BOOTSTRAPPED
+    fpath=()
+    source "$bootstrap_file"
+    source "$bootstrap_file"
+    omz_bootstrap
+
+    _assert '[[ ${#fpath} -eq ${#${(u)fpath}} ]]' "fpath entries should not duplicate after repeated bootstrap"
+    _assert '[[ "$OMZ_IS_BOOTSTRAPPED" == true ]]' "bootstrap signal should remain true"
+  )
+}
+
+test_bootstrap_uses_writable_cache_fallback() {
+  local tmp==(:)
+  mkdir -p "$tmp/ohmyzsh"/{functions,completions} "$tmp/ohmyzsh/custom"/{functions,completions}
+  mkdir -p "$tmp/no-write" "$tmp/xdg-cache"
+  chmod 0555 "$tmp/no-write"
+
+  (
+    set -e
+    export ZSH="$tmp/ohmyzsh"
+    export XDG_CACHE_HOME="$tmp/xdg-cache"
+    export ZSH_CACHE_DIR="$tmp/no-write"
+    unset ZSH_CUSTOM OMZ_IS_BOOTSTRAPPED
+    fpath=()
+    source "$bootstrap_file"
+
+    _assert '[[ "$ZSH_CACHE_DIR" == "'"$tmp/xdg-cache/oh-my-zsh"'" ]]' "cache dir should fallback when not writable"
+    _assert '[[ -d "'"$tmp/xdg-cache/oh-my-zsh/completions"'" ]]' "fallback completions dir should be created"
+    _assert '[[ "${fpath[(Ie)'"$tmp/xdg-cache/oh-my-zsh/completions"']}" -gt 0 ]]' "fpath should include fallback completions dir"
+  )
+}
+
+tests=(
+  test_bootstrap_sets_defaults_and_paths
+  test_bootstrap_is_idempotent
+  test_bootstrap_uses_writable_cache_fallback
+)
+
+for test_name in $tests; do
+  print -u2 "Test: $test_name"
+  "$test_name" || exit 1
+  print -u2 "\e[32mSuccess\e[0m"
+  print -u2 ""
+done