codex-profile 0.2.0

package/bin/codex-profile

@@ -0,0 +1,1080 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PROGRAM="${0##*/}"
+VERSION="0.2.0"
+CODEX_APP="${CODEX_APP:-/Applications/Codex.app}"
+CODEX_APP_BIN="${CODEX_APP_BIN:-$CODEX_APP/Contents/MacOS/Codex}"
+CODEX_BUNDLED_CLI="${CODEX_BUNDLED_CLI:-$CODEX_APP/Contents/Resources/codex}"
+CODEX_PROFILE_QUIT_ATTEMPTS="${CODEX_PROFILE_QUIT_ATTEMPTS:-30}"
+CODEX_PROFILE_QUIT_SLEEP="${CODEX_PROFILE_QUIT_SLEEP:-0.5}"
+CODEX_PROFILE_UPGRADE_REPO="${CODEX_PROFILE_UPGRADE_REPO:-https://github.com/Ducksss/codex-profiles.git}"
+CODEX_PROFILE_UPGRADE_REF="${CODEX_PROFILE_UPGRADE_REF:-main}"
+
+usage() {
+  cat <<EOF
+$PROGRAM - run Codex with isolated CODEX_HOME profiles
+
+Usage:
+  $PROGRAM app <profile> [workspace]
+  $PROGRAM cli <profile> [codex-args...]
+  $PROGRAM login <profile> [codex-login-args...]
+  $PROGRAM init <profile>
+  $PROGRAM remove <profile> [--yes]
+  $PROGRAM status [profile]
+  $PROGRAM status --json [profile]
+  $PROGRAM path <profile>
+  $PROGRAM logs <profile> [--path|--tail [lines]]
+  $PROGRAM clone-config <source-profile> <target-profile> [--force]
+  $PROGRAM list
+  $PROGRAM doctor [--json]
+  $PROGRAM completions <bash|zsh|fish>
+  $PROGRAM upgrade [--dry-run] [--prefix <path>] [--ref <git-ref>]
+  $PROGRAM version
+
+Examples:
+  $PROGRAM login personal
+  $PROGRAM init work
+  $PROGRAM app personal ~/Dev/my-project
+  $PROGRAM cli personal exec "review this repo"
+  $PROGRAM status
+  $PROGRAM logs personal --tail 50
+  $PROGRAM clone-config personal work
+  $PROGRAM upgrade
+
+Profiles:
+  default         -> ~/.codex
+  any other name  -> ~/.codex-<profile>
+
+Environment:
+  CODEX_APP       Override Codex.app path.
+  CODEX_APP_BIN   Override Codex Desktop binary path.
+  CODEX_CLI       Override Codex CLI binary path.
+  CODEX_PROFILE_UPGRADE_REPO    Override upgrade repository.
+  CODEX_PROFILE_UPGRADE_REF     Override upgrade git ref.
+  CODEX_PROFILE_UPGRADE_CACHE   Override upgrade cache checkout.
+  CODEX_PROFILE_UPGRADE_PREFIX  Override upgrade install prefix.
+EOF
+}
+
+die() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+note() {
+  printf '%s\n' "$*"
+}
+
+is_valid_profile_name() {
+  local profile="$1"
+
+  [[ "$profile" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]
+}
+
+validate_profile() {
+  local profile="$1"
+
+  if ! is_valid_profile_name "$profile"; then
+    die "Invalid profile '$profile'. Use letters, numbers, dots, dashes, or underscores."
+  fi
+}
+
+codex_home_for_profile() {
+  local profile="$1"
+
+  validate_profile "$profile"
+
+  if [[ "$profile" == "default" ]]; then
+    printf '%s/.codex\n' "$HOME"
+  else
+    printf '%s/.codex-%s\n' "$HOME" "$profile"
+  fi
+}
+
+discovered_profile_is_managed() {
+  local profile="$1"
+  local dir="$2"
+  local expected
+
+  is_valid_profile_name "$profile" || return 1
+  expected="$(codex_home_for_profile "$profile")"
+  [[ "$expected" == "$dir" ]]
+}
+
+discover_profiles() {
+  local include_default="${1:-yes}"
+  local dir profile
+
+  if [[ "$include_default" == "yes" && -d "$HOME/.codex" ]]; then
+    printf 'default\n'
+  fi
+
+  for dir in "$HOME"/.codex-*; do
+    [[ -d "$dir" ]] || continue
+    profile="${dir##*/.codex-}"
+    discovered_profile_is_managed "$profile" "$dir" || continue
+    printf '%s\n' "$profile"
+  done
+}
+
+ensure_home() {
+  local codex_home="$1"
+
+  mkdir -p "$codex_home" || die "Cannot create directory: $codex_home"
+  [[ -d "$codex_home" ]] || die "Not a directory: $codex_home"
+  chmod 700 "$codex_home" || die "Cannot set private permissions on: $codex_home"
+}
+
+codex_desktop_running() {
+  pgrep -x Codex > /dev/null 2>&1 && return 0
+  pgrep -f "$CODEX_BUNDLED_CLI app-server" > /dev/null 2>&1 && return 0
+  return 1
+}
+
+codex_cli_error_message() {
+  if [[ -n "${CODEX_CLI:-}" ]]; then
+    printf 'CODEX_CLI is set but not executable: %s\n' "$CODEX_CLI"
+    return 0
+  fi
+
+  printf 'Codex CLI not found. Install Codex or set CODEX_CLI=/path/to/codex.\n'
+}
+
+try_find_codex_cli() {
+  if [[ -n "${CODEX_CLI:-}" ]]; then
+    [[ -x "$CODEX_CLI" ]] || return 1
+    printf '%s\n' "$CODEX_CLI"
+    return 0
+  fi
+
+  if command -v codex > /dev/null 2>&1; then
+    command -v codex
+    return 0
+  fi
+
+  if [[ -x "$CODEX_BUNDLED_CLI" ]]; then
+    printf '%s\n' "$CODEX_BUNDLED_CLI"
+    return 0
+  fi
+
+  return 1
+}
+
+find_codex_cli() {
+  local codex_cli
+
+  if codex_cli="$(try_find_codex_cli)"; then
+    printf '%s\n' "$codex_cli"
+    return 0
+  fi
+
+  die "$(codex_cli_error_message)"
+}
+
+quit_codex_app() {
+  local attempt
+
+  if ! codex_desktop_running; then
+    return 0
+  fi
+
+  note "Quitting existing Codex app..."
+  osascript -e 'tell application "Codex" to quit' > /dev/null 2>&1 || true
+
+  for ((attempt = 0; attempt < CODEX_PROFILE_QUIT_ATTEMPTS; attempt++)); do
+    if ! codex_desktop_running; then
+      return 0
+    fi
+    sleep "$CODEX_PROFILE_QUIT_SLEEP"
+  done
+
+  die "Codex or its app-server is still running. Quit Codex with Cmd+Q, then retry."
+}
+
+command_app() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM app <profile> [workspace]"
+  shift || true
+
+  local workspace="${1:-$PWD}"
+  local codex_home
+
+  [[ -x "$CODEX_APP_BIN" ]] || die "Codex Desktop binary not found at $CODEX_APP_BIN"
+
+  codex_home="$(codex_home_for_profile "$profile")"
+  ensure_home "$codex_home"
+  quit_codex_app
+
+  local log_dir="$codex_home/logs"
+  local log_file="$log_dir/desktop.log"
+  ensure_home "$log_dir"
+  (umask 077 && : > "$log_file")
+  chmod 600 "$log_file" 2> /dev/null || true
+
+  note "Launching Codex Desktop with CODEX_HOME=$codex_home"
+  note "Log: $log_file"
+  (umask 077 && nohup env CODEX_HOME="$codex_home" "$CODEX_APP_BIN" "$workspace" > "$log_file" 2>&1 &)
+}
+
+command_cli() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM cli <profile> [codex-args...]"
+  shift || true
+
+  local codex_home codex_cli
+  codex_home="$(codex_home_for_profile "$profile")"
+  ensure_home "$codex_home"
+  codex_cli="$(find_codex_cli)"
+
+  exec env CODEX_HOME="$codex_home" "$codex_cli" "$@"
+}
+
+command_login() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM login <profile> [codex-login-args...]"
+  shift || true
+
+  local codex_home codex_cli
+  codex_home="$(codex_home_for_profile "$profile")"
+  ensure_home "$codex_home"
+  codex_cli="$(find_codex_cli)"
+
+  exec env CODEX_HOME="$codex_home" "$codex_cli" login "$@"
+}
+
+command_init() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM init <profile>"
+  shift || true
+  [[ "$#" -eq 0 ]] || die "Usage: $PROGRAM init <profile>"
+
+  local codex_home existed
+  codex_home="$(codex_home_for_profile "$profile")"
+  existed=no
+  [[ -d "$codex_home" ]] && existed=yes
+
+  ensure_home "$codex_home"
+
+  if [[ "$existed" == "yes" ]]; then
+    note "Already initialized $profile ($codex_home)"
+  else
+    note "Initialized $profile ($codex_home)"
+  fi
+}
+
+command_remove() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM remove <profile> [--yes]"
+  shift || true
+
+  local yes=no
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --yes | -y)
+        yes=yes
+        ;;
+      *)
+        die "Usage: $PROGRAM remove <profile> [--yes]"
+        ;;
+    esac
+    shift
+  done
+
+  local codex_home confirmation
+  codex_home="$(codex_home_for_profile "$profile")"
+
+  if [[ ! -d "$codex_home" ]]; then
+    note "Not initialized $profile ($codex_home)"
+    return 0
+  fi
+
+  if [[ "$yes" != "yes" ]]; then
+    printf "Type '%s' to permanently remove %s: " "$profile" "$codex_home" >&2
+    if ! IFS= read -r confirmation && [[ -z "$confirmation" ]]; then
+      die "Confirmation required."
+    fi
+    if [[ "$confirmation" != "$profile" ]]; then
+      die "Confirmation did not match; nothing removed."
+    fi
+  fi
+
+  rm -rf -- "$codex_home" || die "Cannot remove profile home: $codex_home"
+  note "Removed $profile ($codex_home)"
+}
+
+command_status_one() {
+  local profile="$1"
+  local codex_home codex_cli
+  local status_output status_code
+
+  codex_home="$(codex_home_for_profile "$profile")"
+
+  if [[ ! -d "$codex_home" ]]; then
+    printf '%s (%s): Not initialized\n' "$profile" "$codex_home"
+    return 0
+  fi
+
+  codex_cli="$(find_codex_cli)"
+
+  printf '%s (%s): ' "$profile" "$codex_home"
+
+  set +e
+  status_output="$(env CODEX_HOME="$codex_home" "$codex_cli" login status 2>&1)"
+  status_code=$?
+  set -e
+
+  printf '%s\n' "$status_output"
+
+  if [[ "$status_code" -eq 0 || "$status_output" == "Not logged in" ]]; then
+    return 0
+  fi
+
+  return "$status_code"
+}
+
+json_escape() {
+  local value="$1"
+
+  value=${value//\\/\\\\}
+  value=${value//\"/\\\"}
+  value=${value//$'\b'/\\b}
+  value=${value//$'\f'/\\f}
+  value=${value//$'\n'/\\n}
+  value=${value//$'\r'/\\r}
+  value=${value//$'\t'/\\t}
+  value=${value//$'\001'/\\u0001}
+  value=${value//$'\002'/\\u0002}
+  value=${value//$'\003'/\\u0003}
+  value=${value//$'\004'/\\u0004}
+  value=${value//$'\005'/\\u0005}
+  value=${value//$'\006'/\\u0006}
+  value=${value//$'\007'/\\u0007}
+  value=${value//$'\013'/\\u000b}
+  value=${value//$'\016'/\\u000e}
+  value=${value//$'\017'/\\u000f}
+  value=${value//$'\020'/\\u0010}
+  value=${value//$'\021'/\\u0011}
+  value=${value//$'\022'/\\u0012}
+  value=${value//$'\023'/\\u0013}
+  value=${value//$'\024'/\\u0014}
+  value=${value//$'\025'/\\u0015}
+  value=${value//$'\026'/\\u0016}
+  value=${value//$'\027'/\\u0017}
+  value=${value//$'\030'/\\u0018}
+  value=${value//$'\031'/\\u0019}
+  value=${value//$'\032'/\\u001a}
+  value=${value//$'\033'/\\u001b}
+  value=${value//$'\034'/\\u001c}
+  value=${value//$'\035'/\\u001d}
+  value=${value//$'\036'/\\u001e}
+  value=${value//$'\037'/\\u001f}
+  printf '%s' "$value"
+}
+
+json_string() {
+  printf '"'
+  json_escape "$1"
+  printf '"'
+}
+
+json_status_object() {
+  local profile="$1"
+  local codex_home codex_cli status_output status_code state
+
+  codex_home="$(codex_home_for_profile "$profile")"
+
+  if [[ ! -d "$codex_home" ]]; then
+    printf '{"name":'
+    json_string "$profile"
+    printf ',"home":'
+    json_string "$codex_home"
+    printf ',"state":"not_initialized","status":"Not initialized","exit_code":0}'
+    return 0
+  fi
+
+  if ! codex_cli="$(try_find_codex_cli)"; then
+    printf '{"name":'
+    json_string "$profile"
+    printf ',"home":'
+    json_string "$codex_home"
+    printf ',"state":"error","status":'
+    json_string "$(codex_cli_error_message)"
+    printf ',"exit_code":1}'
+    return 1
+  fi
+
+  set +e
+  status_output="$(env CODEX_HOME="$codex_home" "$codex_cli" login status 2>&1)"
+  status_code=$?
+  set -e
+
+  if [[ "$status_code" -eq 0 ]]; then
+    state=ok
+  elif [[ "$status_output" == "Not logged in" ]]; then
+    state=not_logged_in
+  else
+    state=error
+  fi
+
+  printf '{"name":'
+  json_string "$profile"
+  printf ',"home":'
+  json_string "$codex_home"
+  printf ',"state":'
+  json_string "$state"
+  printf ',"status":'
+  json_string "$status_output"
+  printf ',"exit_code":%s}' "$status_code"
+
+  if [[ "$state" == "error" ]]; then
+    return "$status_code"
+  fi
+
+  return 0
+}
+
+json_emit_status_profiles_array() {
+  local requested_profile="${1:-}"
+  local status_code=0
+  local first=yes
+  local profile object object_status
+
+  printf '['
+
+  if [[ -n "$requested_profile" ]]; then
+    set +e
+    object="$(json_status_object "$requested_profile")"
+    object_status=$?
+    set -e
+    printf '%s' "$object"
+    printf ']'
+    return "$object_status"
+  fi
+
+  for profile in default $(discover_profiles no); do
+    if [[ "$first" == "yes" ]]; then
+      first=no
+    else
+      printf ','
+    fi
+
+    set +e
+    object="$(json_status_object "$profile")"
+    object_status=$?
+    set -e
+    printf '%s' "$object"
+
+    if [[ "$object_status" -ne 0 ]]; then
+      status_code="$object_status"
+    fi
+  done
+
+  printf ']'
+  return "$status_code"
+}
+
+command_status_json() {
+  local profile="${1:-}"
+  local status_code=0
+
+  printf '{"profiles":'
+  set +e
+  json_emit_status_profiles_array "$profile"
+  status_code=$?
+  set -e
+  printf '}\n'
+
+  return "$status_code"
+}
+
+command_status() {
+  local status_code=0
+  local json=no
+  local profile=""
+
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --json | -j)
+        json=yes
+        ;;
+      -*)
+        die "Unknown status option '$1'."
+        ;;
+      *)
+        [[ -z "$profile" ]] || die "Usage: $PROGRAM status [--json] [profile]"
+        profile="$1"
+        ;;
+    esac
+    shift
+  done
+
+  if [[ "$json" == "yes" ]]; then
+    command_status_json "$profile"
+    return $?
+  fi
+
+  if [[ -n "$profile" ]]; then
+    command_status_one "$profile"
+    return $?
+  fi
+
+  command_status_one default || status_code=$?
+
+  local profile
+  for profile in $(discover_profiles no); do
+    command_status_one "$profile" || status_code=$?
+  done
+
+  return "$status_code"
+}
+
+command_list() {
+  discover_profiles yes
+}
+
+command_path() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM path <profile>"
+  codex_home_for_profile "$profile"
+}
+
+command_logs() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM logs <profile> [--path|--tail [lines]]"
+  shift || true
+
+  local mode="cat"
+  local lines=50
+
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --path)
+        mode="path"
+        ;;
+      --tail)
+        mode="tail"
+        if [[ -n "${2:-}" && "$2" != -* ]]; then
+          lines="$2"
+          shift
+        fi
+        ;;
+      -*)
+        die "Unknown logs option '$1'."
+        ;;
+      *)
+        die "Usage: $PROGRAM logs <profile> [--path|--tail [lines]]"
+        ;;
+    esac
+    shift
+  done
+
+  [[ "$lines" =~ ^[0-9]+$ ]] || die "Tail line count must be a non-negative integer."
+
+  local codex_home log_file
+  codex_home="$(codex_home_for_profile "$profile")"
+  log_file="$codex_home/logs/desktop.log"
+
+  if [[ "$mode" == "path" ]]; then
+    printf '%s\n' "$log_file"
+    return 0
+  fi
+
+  [[ -f "$log_file" ]] || die "No desktop log for $profile ($log_file)."
+
+  if [[ "$mode" == "tail" ]]; then
+    tail -n "$lines" "$log_file"
+  else
+    cat "$log_file"
+  fi
+}
+
+config_file_looks_sensitive() {
+  local file="$1"
+
+  grep -Eiq '(auth|token|secret|password|passwd|credential|api[_-]?key|access[_-]?key|private[_-]?key|oauth|bearer)' "$file"
+}
+
+command_clone_config() {
+  local source_profile="" target_profile="" force=no
+
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --force | -f)
+        force=yes
+        ;;
+      -*)
+        die "Usage: $PROGRAM clone-config <source-profile> <target-profile> [--force]"
+        ;;
+      *)
+        if [[ -z "$source_profile" ]]; then
+          source_profile="$1"
+        elif [[ -z "$target_profile" ]]; then
+          target_profile="$1"
+        else
+          die "Usage: $PROGRAM clone-config <source-profile> <target-profile> [--force]"
+        fi
+        ;;
+    esac
+    shift
+  done
+
+  [[ -n "$source_profile" && -n "$target_profile" ]] || die "Usage: $PROGRAM clone-config <source-profile> <target-profile> [--force]"
+  [[ "$source_profile" != "$target_profile" ]] || die "Source and target profiles must be different."
+
+  local source_home target_home
+  source_home="$(codex_home_for_profile "$source_profile")"
+  target_home="$(codex_home_for_profile "$target_profile")"
+
+  [[ -d "$source_home" ]] || die "Source profile is not initialized: $source_profile ($source_home)"
+  ensure_home "$target_home"
+
+  local safe_files=("config.toml" "AGENTS.md" "instructions.md" "custom-instructions.md")
+  local file source_file target_file copied failed
+  copied=0
+  failed=0
+
+  for file in "${safe_files[@]}"; do
+    source_file="$source_home/$file"
+    target_file="$target_home/$file"
+    [[ -f "$source_file" ]] || continue
+
+    if [[ -L "$source_file" ]]; then
+      note "Refusing to copy $file because it is a symlink."
+      failed=1
+      continue
+    fi
+
+    if config_file_looks_sensitive "$source_file"; then
+      note "Refusing to copy $file because it contains sensitive-looking keys."
+      failed=1
+      continue
+    fi
+
+    if [[ -L "$target_file" ]]; then
+      note "Refusing to overwrite $file because the target is a symlink."
+      failed=1
+      continue
+    fi
+
+    if [[ -e "$target_file" && "$force" != "yes" ]]; then
+      note "Refusing to overwrite $file in $target_home. Use --force to overwrite."
+      failed=1
+      continue
+    fi
+
+    install -m 600 "$source_file" "$target_file" || die "Cannot copy $file to $target_home"
+    note "Copied $file"
+    copied=$((copied + 1))
+  done
+
+  if [[ "$failed" -ne 0 ]]; then
+    return 1
+  fi
+
+  if [[ "$copied" -eq 0 ]]; then
+    note "No safe config files found to clone from $source_profile."
+  fi
+}
+
+command_version() {
+  printf 'codex-profile %s\n' "$VERSION"
+}
+
+upgrade_cache_dir() {
+  if [[ -n "${CODEX_PROFILE_UPGRADE_CACHE:-}" ]]; then
+    printf '%s\n' "$CODEX_PROFILE_UPGRADE_CACHE"
+  elif [[ -n "${XDG_CACHE_HOME:-}" ]]; then
+    printf '%s/codex-profile/source\n' "$XDG_CACHE_HOME"
+  else
+    printf '%s/.cache/codex-profile/source\n' "$HOME"
+  fi
+}
+
+upgrade_prefix() {
+  printf '%s\n' "${CODEX_PROFILE_UPGRADE_PREFIX:-$HOME/.local}"
+}
+
+upgrade_print_plan() {
+  local repo="$1"
+  local ref="$2"
+  local cache="$3"
+  local prefix="$4"
+
+  note "Upgrade plan"
+  note "Repository: $repo"
+  note "Ref: $ref"
+  note "Cache: $cache"
+  note "Install prefix: $prefix"
+}
+
+version_core() {
+  local value="$1"
+
+  value="${value#codex-profile }"
+  value="${value%%$'\n'*}"
+  value="${value%%-*}"
+  printf '%s\n' "$value"
+}
+
+version_is_older_than_current() {
+  local candidate="$1"
+  local current="$VERSION"
+  local candidate_core current_core
+  local candidate_parts current_parts candidate_part current_part index
+
+  candidate_core="$(version_core "$candidate")"
+  current_core="$(version_core "$current")"
+
+  IFS=. read -r -a candidate_parts <<< "$candidate_core"
+  IFS=. read -r -a current_parts <<< "$current_core"
+
+  for index in 0 1 2; do
+    candidate_part="${candidate_parts[$index]:-0}"
+    current_part="${current_parts[$index]:-0}"
+
+    [[ "$candidate_part" =~ ^[0-9]+$ ]] || return 1
+    [[ "$current_part" =~ ^[0-9]+$ ]] || return 1
+
+    if ((10#$candidate_part < 10#$current_part)); then
+      return 0
+    fi
+    if ((10#$candidate_part > 10#$current_part)); then
+      return 1
+    fi
+  done
+
+  return 1
+}
+
+script_declared_version_output() {
+  local script="$1"
+  local declared_version
+
+  declared_version="$(sed -n 's/^VERSION="\([^"]*\)".*/\1/p' "$script" | sed -n '1p')"
+  [[ -n "$declared_version" ]] || return 1
+  printf 'codex-profile %s\n' "$declared_version"
+}
+
+upgrade_checkout_ref() {
+  local cache="$1"
+  local ref="$2"
+
+  git -C "$cache" fetch --tags --prune origin
+  if git -C "$cache" show-ref --verify --quiet "refs/remotes/origin/$ref"; then
+    git -C "$cache" checkout --quiet -B "$ref" "origin/$ref"
+  else
+    git -C "$cache" checkout --quiet "$ref"
+  fi
+}
+
+command_upgrade() {
+  local dry_run=no
+  local prefix
+  local ref="$CODEX_PROFILE_UPGRADE_REF"
+  local repo="$CODEX_PROFILE_UPGRADE_REPO"
+  local cache
+  prefix="$(upgrade_prefix)"
+  cache="$(upgrade_cache_dir)"
+
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --dry-run | -n)
+        dry_run=yes
+        ;;
+      --prefix)
+        [[ -n "${2:-}" ]] || die "Usage: $PROGRAM upgrade [--dry-run] [--prefix <path>] [--ref <git-ref>]"
+        prefix="$2"
+        shift
+        ;;
+      --ref)
+        [[ -n "${2:-}" ]] || die "Usage: $PROGRAM upgrade [--dry-run] [--prefix <path>] [--ref <git-ref>]"
+        ref="$2"
+        shift
+        ;;
+      *)
+        die "Usage: $PROGRAM upgrade [--dry-run] [--prefix <path>] [--ref <git-ref>]"
+        ;;
+    esac
+    shift
+  done
+
+  [[ -n "$repo" ]] || die "Upgrade repository cannot be empty."
+  [[ -n "$ref" ]] || die "Upgrade ref cannot be empty."
+  [[ -n "$cache" ]] || die "Upgrade cache cannot be empty."
+  [[ -n "$prefix" ]] || die "Upgrade prefix cannot be empty."
+  [[ "$repo" != -* ]] || die "Upgrade repository must not start with '-'."
+  [[ "$ref" != -* ]] || die "Upgrade ref must not start with '-'."
+
+  upgrade_print_plan "$repo" "$ref" "$cache" "$prefix"
+
+  if [[ "$dry_run" == "yes" ]]; then
+    return 0
+  fi
+
+  command -v git > /dev/null 2>&1 || die "git is required to upgrade codex-profile."
+  command -v make > /dev/null 2>&1 || die "make is required to upgrade codex-profile."
+
+  if [[ -e "$cache" && ! -d "$cache/.git" ]]; then
+    die "Upgrade cache exists but is not a git checkout: $cache"
+  fi
+
+  if [[ ! -d "$cache/.git" ]]; then
+    mkdir -p "$(dirname "$cache")" || die "Cannot create upgrade cache parent: $(dirname "$cache")"
+    git clone "$repo" "$cache"
+    upgrade_checkout_ref "$cache" "$ref"
+  else
+    local origin dirty
+    origin="$(git -C "$cache" remote get-url origin 2> /dev/null || true)"
+    [[ "$origin" == "$repo" ]] || die "Cached upgrade checkout origin differs from $repo: $origin"
+
+    dirty="$(git -C "$cache" status --porcelain)"
+    [[ -z "$dirty" ]] || die "Cached upgrade checkout has local changes: $cache"
+
+    upgrade_checkout_ref "$cache" "$ref"
+  fi
+
+  [[ -f "$cache/Makefile" ]] || die "Upgrade checkout is missing Makefile: $cache"
+  [[ -f "$cache/bin/codex-profile" ]] || die "Upgrade checkout is missing bin/codex-profile: $cache"
+
+  local candidate_version
+  candidate_version="$(script_declared_version_output "$cache/bin/codex-profile" || true)"
+  [[ -n "$candidate_version" ]] || die "Refusing to install candidate without a declared VERSION."
+  if [[ -n "$candidate_version" ]] && version_is_older_than_current "$candidate_version"; then
+    die "Refusing to install older $candidate_version over codex-profile $VERSION."
+  fi
+
+  make -C "$cache" install PREFIX="$prefix"
+
+  local installed version_output
+  installed="$prefix/bin/codex-profile"
+  [[ -x "$installed" ]] || die "Upgrade did not install executable: $installed"
+  version_output="$("$installed" version 2> /dev/null || "$installed" --version 2> /dev/null || true)"
+  [[ -n "$version_output" ]] || version_output="codex-profile version unknown"
+  note "Installed $version_output to $installed"
+}
+
+command_completions() {
+  local shell="${1:-}"
+  [[ -n "$shell" ]] || die "Usage: $PROGRAM completions <bash|zsh|fish>"
+  shift || true
+  [[ "$#" -eq 0 ]] || die "Usage: $PROGRAM completions <bash|zsh|fish>"
+
+  case "$shell" in
+    bash)
+      cat <<'EOF'
+_codex_profile()
+{
+  local cur command profiles
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  command="${COMP_WORDS[1]}"
+
+  if [[ "$COMP_CWORD" -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "app cli login init remove status path logs clone-config list doctor completions upgrade version help" -- "$cur") )
+    return 0
+  fi
+
+  case "$command" in
+    app|cli|login|init|remove|status|path|logs)
+      if [[ "$COMP_CWORD" -eq 2 ]]; then
+        profiles="$(codex-profile list 2>/dev/null)"
+        COMPREPLY=( $(compgen -W "default personal work $profiles" -- "$cur") )
+      fi
+      ;;
+    clone-config)
+      if [[ "$COMP_CWORD" -eq 2 || "$COMP_CWORD" -eq 3 ]]; then
+        profiles="$(codex-profile list 2>/dev/null)"
+        COMPREPLY=( $(compgen -W "default personal work $profiles" -- "$cur") )
+      fi
+      ;;
+    completions)
+      if [[ "$COMP_CWORD" -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      fi
+      ;;
+  esac
+}
+complete -F _codex_profile codex-profile
+EOF
+      ;;
+    zsh)
+      cat <<'EOF'
+#compdef codex-profile
+
+_codex_profile() {
+  local -a commands profiles shells
+  commands=(
+    app cli login init remove status path logs clone-config list doctor completions upgrade version help
+  )
+  profiles=(${(f)"$(codex-profile list 2>/dev/null)"} default personal work)
+  shells=(bash zsh fish)
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+
+  case "$words[2]" in
+    app|cli|login|init|remove|status|path|logs)
+      if (( CURRENT == 3 )); then
+        _describe 'profile' profiles
+      fi
+      ;;
+    clone-config)
+      if (( CURRENT == 3 || CURRENT == 4 )); then
+        _describe 'profile' profiles
+      fi
+      ;;
+    completions)
+      if (( CURRENT == 3 )); then
+        _describe 'shell' shells
+      fi
+      ;;
+  esac
+}
+
+_codex_profile "$@"
+EOF
+      ;;
+    fish)
+      cat <<'EOF'
+complete -c codex-profile -f
+complete -c codex-profile -n '__fish_is_first_arg' -a 'app cli login init remove status path logs clone-config list doctor completions upgrade version help'
+complete -c codex-profile -n '__fish_seen_subcommand_from app cli login init remove status path logs' -a '(codex-profile list 2>/dev/null) default personal work'
+complete -c codex-profile -n '__fish_seen_subcommand_from clone-config' -a '(codex-profile list 2>/dev/null) default personal work'
+complete -c codex-profile -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
+EOF
+      ;;
+    *)
+      die "Unsupported shell '$shell'. Use bash, zsh, or fish."
+      ;;
+  esac
+}
+
+command_doctor() {
+  local json=no
+  local codex_cli
+
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --json | -j)
+        json=yes
+        ;;
+      *)
+        die "Usage: $PROGRAM doctor [--json]"
+        ;;
+    esac
+    shift
+  done
+
+  if [[ "$json" == "yes" ]]; then
+    local desktop_found=false cli_version status_code=0
+    [[ -x "$CODEX_APP_BIN" ]] && desktop_found=true
+
+    printf '{"desktop":{"found":%s,"path":' "$desktop_found"
+    json_string "$CODEX_APP_BIN"
+    printf '}'
+
+    if codex_cli="$(try_find_codex_cli)"; then
+      cli_version="$("$codex_cli" --version 2>&1 || true)"
+      printf ',"cli":{"found":true,"path":'
+      json_string "$codex_cli"
+      printf ',"version":'
+      json_string "$cli_version"
+      printf '},"status":{"skipped":false,"profiles":'
+      set +e
+      json_emit_status_profiles_array
+      status_code=$?
+      set -e
+      printf '}}\n'
+      return "$status_code"
+    fi
+
+    printf ',"cli":{"found":false,"path":null,"version":null},"status":{"skipped":true,"reason":'
+    json_string "$(codex_cli_error_message)"
+    printf '}}\n'
+    return 0
+  fi
+
+  note "Codex profile doctor"
+  note ""
+
+  if [[ -x "$CODEX_APP_BIN" ]]; then
+    note "Desktop: $CODEX_APP_BIN"
+  else
+    note "Desktop: missing ($CODEX_APP_BIN)"
+  fi
+
+  if codex_cli="$(find_codex_cli 2> /dev/null)"; then
+    note "CLI: $codex_cli"
+    "$codex_cli" --version || true
+  else
+    note "CLI: missing"
+    note ""
+    note "Status: skipped"
+    return 0
+  fi
+
+  note ""
+  command_status
+}
+
+main() {
+  local command="${1:-help}"
+  shift || true
+
+  case "$command" in
+    app)
+      command_app "$@"
+      ;;
+    cli)
+      command_cli "$@"
+      ;;
+    login)
+      command_login "$@"
+      ;;
+    init)
+      command_init "$@"
+      ;;
+    remove)
+      command_remove "$@"
+      ;;
+    status)
+      command_status "$@"
+      ;;
+    path)
+      command_path "$@"
+      ;;
+    logs)
+      command_logs "$@"
+      ;;
+    clone-config)
+      command_clone_config "$@"
+      ;;
+    list)
+      command_list
+      ;;
+    doctor)
+      command_doctor "$@"
+      ;;
+    completions)
+      command_completions "$@"
+      ;;
+    upgrade)
+      command_upgrade "$@"
+      ;;
+    version | --version)
+      command_version
+      ;;
+    help | -h | --help)
+      usage
+      ;;
+    *)
+      die "Unknown command '$command'. See '$PROGRAM help'."
+      ;;
+  esac
+}
+
+main "$@"