Merge pull request #124 from dmoliveira/codex-mac-desktop-extras

add mac desktop extras install path

Author: dmoliveira

Makefile

@@ -1,11 +1,14 @@
-.PHONY: help install-mac install-unix install-debian verify verify-strict verify-json bootstrap-secrets doctor doctor-full verify-linux tmux-self-heal playbook docs-browse leader-pack-check rollback rollback-dry-run shell-lint hooks-install pre-commit-install pre-commit-run git-delta-config wiki-build wiki-build-check wiki-source-check wiki-sidebar-check docs-hub-check docs-make-target-check continue-tag-check release-template-check release-docs-check workflow-inventory-check core-commands-check docs-assets-check cheatsheet-index-check quick-cards-check top10-cards-check golden-path-guards-check installer-ci-flags-check quick-commands-sync-check smoke-guards-check ci-quick-guards-check ci-quick release-precheck
+.PHONY: help install-mac install-mac-desktop install-unix install-debian verify verify-strict verify-json bootstrap-secrets doctor doctor-full verify-linux tmux-self-heal playbook docs-browse leader-pack-check rollback rollback-dry-run shell-lint hooks-install pre-commit-install pre-commit-run git-delta-config wiki-build wiki-build-check wiki-source-check wiki-sidebar-check docs-hub-check docs-make-target-check continue-tag-check release-template-check release-docs-check workflow-inventory-check core-commands-check docs-assets-check cheatsheet-index-check quick-cards-check top10-cards-check golden-path-guards-check installer-ci-flags-check quick-commands-sync-check smoke-guards-check ci-quick-guards-check ci-quick release-precheck
 
 help: ## Show available commands
 	@awk 'BEGIN {FS = ":.*## "} /^[a-zA-Z_-]+:.*## / {printf "%-16s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
 install-mac: ## Run macOS installer
 	./install_my_programs_mac
 
+install-mac-desktop: ## Run macOS installer with optional desktop extras
+	./install_my_programs_mac --desktop-extras
+
 install-unix: ## Run generic Unix installer
 	./install_my_programs_unix
 

README.md

@@ -40,7 +40,8 @@ Special progress keyword for ongoing work across docs and release notes:
 git clone https://github.com/dmoliveira/utils-scripts.git
 cd utils-scripts
 make help
-make install-mac    # or: make install-debian / make install-unix
+make install-mac    # baseline macOS setup
+# or: make install-mac-desktop / make install-debian / make install-unix
 make verify
 ```
 
@@ -78,6 +79,7 @@ make docs-browse
 | --- | --- |
 | `install_my_programs_debian` | Debian/Ubuntu installer |
 | `install_my_programs_mac` | macOS installer (Homebrew based) |
+| `make install-mac-desktop` | macOS installer + desktop extras (`dockdoor`, `maccy`, `espanso`, `appcleaner`, `yabai`) |
 | `install_my_programs_unix` | Generic Unix installer |
 | `verify_post_install_unix` | Smoke checks after install |
 | `doctor_post_install_unix` | Strict checks with fix hints |

docs/getting-started.md

@@ -14,13 +14,16 @@ make help
 
 ```bash
 make install-mac
+# optional macOS desktop extras
+make install-mac-desktop
 # or
 make install-debian
 # or
 make install-unix
 ```
 
 If you want a preview before changing your machine, run the installer script with `--dry-run`.
+For the extra macOS desktop apps, use `./install_my_programs_mac --desktop-extras --dry-run`.
 
 ## 3) Verify your environment
 

docs/power-user.md

@@ -31,6 +31,29 @@ trivy fs .
 - prefer short command examples that people can paste
 - add the follow-up marker `CONTINUE_TAG: #continue-utils` for remaining tasks
 
+## macOS desktop extras
+
+Use one command when you want the terminal stack plus GUI helpers:
+
+```bash
+make install-mac-desktop
+```
+
+What it adds:
+
+- `dockdoor` for Dock previews and window switching
+- `maccy` for clipboard history
+- `espanso` for text expansion
+- `appcleaner` for app removal cleanup
+- `yabai` for advanced tiling/window management
+
+Post-install notes:
+
+- Launch DockDoor, Maccy, and Espanso once so macOS can request permissions.
+- Expect Accessibility prompts for DockDoor, Maccy auto-paste workflows, Espanso behavior, and yabai.
+- Start yabai manually with `yabai --start-service` after reviewing its upstream setup notes.
+- Keep yabai optional: advanced features may require extra SIP and scripting-addition steps.
+
 ## Incident mode checklist
 
 ```bash

install_my_programs_mac

@@ -4,6 +4,7 @@ set -euo pipefail
 timestamp=$(date +"%Y%m%d%H%M%S")
 ARCH=$(uname -m)
 DRY_RUN=false
+INSTALL_DESKTOP_EXTRAS=false
 BEADS_INSTALL_REF="dd01a655b9602ba20d0c666515467e064a815609"
 BR_INSTALL_FAILED=false
 
@@ -13,6 +14,7 @@ Usage: install_my_programs_mac [options]
 
 Options:
   --dry-run   Print planned actions without changing the system
+  --desktop-extras  Install optional macOS desktop apps and services
   -h, --help  Show this help message
 EOF
 }
@@ -23,6 +25,9 @@ parse_args() {
       --dry-run)
         DRY_RUN=true
         ;;
+      --desktop-extras)
+        INSTALL_DESKTOP_EXTRAS=true
+        ;;
       -h | --help)
         usage
         exit 0
@@ -68,6 +73,48 @@ install_optional_brew_formula() {
   echo "✅ Installed ${label}"
 }
 
+install_optional_brew_cask() {
+  local cask="$1"
+  local label="${2:-$1}"
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    run_cmd brew install --cask "$cask"
+    return
+  fi
+
+  if ! brew info --cask "$cask" >/dev/null 2>&1; then
+    echo "${label} unavailable in current Homebrew taps; skipping"
+    return
+  fi
+
+  if brew list --cask "$cask" &>/dev/null; then
+    echo "${label} already installed"
+    return
+  fi
+
+  brew install --cask "$cask"
+  echo "Installed ${label}"
+}
+
+install_macos_desktop_extras() {
+  echo "Installing optional macOS desktop extras..."
+  install_optional_brew_cask dockdoor "DockDoor"
+  install_optional_brew_cask maccy "Maccy"
+  install_optional_brew_cask espanso "Espanso"
+  install_optional_brew_cask appcleaner "AppCleaner"
+  install_optional_brew_formula asmvik/formulae/yabai "yabai"
+
+  cat <<'EOF'
+
+Next steps for macOS desktop extras:
+- DockDoor: launch once and grant Accessibility access.
+- Maccy: launch once; grant Accessibility if you want auto-paste/global shortcut reliability.
+- Espanso: launch once, confirm the menu bar app appears, and review Secure Input guidance if expansion stops.
+- AppCleaner: optional manual app; SmartDelete is personal preference.
+- yabai: advanced window manager; grant Accessibility, run `yabai --start-service`, and review upstream docs before enabling scripting addition or SIP-related features.
+EOF
+}
+
 install_monitoring_stack() {
   echo "Installing terminal monitoring tools..."
   install_optional_brew_formula bottom "bottom (btm)"
@@ -192,6 +239,10 @@ elif ! brew list --cask ghostty &>/dev/null; then
   run_cmd brew install --cask ghostty
 fi
 
+if [[ "$INSTALL_DESKTOP_EXTRAS" == "true" ]]; then
+  install_macos_desktop_extras
+fi
+
 # 🧠 AI/ML environment (optional)
 run_cmd brew install \
   cmake openblas lapack \