coredesktop/skills/sibling-project-updates.md

Skill: Supporting the updates.d Update Architecture in a Sibling Project

Overview

CoreDesktop's update script sources every *.sh file found in ~/.local/share/coredesktop/updates.d/ in filename order. A sibling project hooks into this system by installing a numbered shell script into that directory during its own install step.

How It Works

When a user runs update:

1. The coredesktop repo at ~/.local/share/coredesktop is pulled.
2. All *.sh files in updates.d/ are sourced, each in its own subshell, in lexicographic order.
3. Each script can see $COREDESKTOP, but nothing defined by earlier hooks — source utils.sh yourself if you need its helpers. A cd, set -e or exit in one hook can't affect the others.
4. A hook that exits non-zero is listed in the summary at the end of update.

Because the scripts are sourced from within the cloned repo directory, any file placed there by a sibling project's installer will survive git pull — git does not delete untracked files on pull.

Naming Convention

Existing coredesktop hooks use a numeric prefix to control execution order:

File	Purpose
00-rename-migration.sh	Legacy command renames
10-pacman.sh	Arch system update
15-services.sh	Enable new systemd services
20-aur.sh	AUR packages
30-flatpak.sh	Flatpak apps
40-ruby.sh	mise, Ruby/gems
45-tmux.sh	TPM and tmux plugins
46-neovim.sh	Neovim plugins
50-bitwarden.sh	Bitwarden SSH agent
60-pipx.sh	pipx packages
65-migrate.sh	Migrate backup tool
70-claude.sh	Claude Code setup
80-gnome-extensions.sh	GNOME extensions
85-gnome-settings.sh	GNOME extension settings
90-firmware.sh	Firmware update check
95-cleanup.sh	Flatpak/pacman cache cleanup
99-reboot-check.sh	Reboot-needed notice

Sibling projects should use an unused number from 71–79 so they run after the core updates but before coredesktop's end-of-run hooks (80+).

What to Add to a Sibling Project

1. Create the hook script

Add a file like updates.d/70-myproject.sh to the sibling repo:

#!/bin/bash

echo "Updating MyProject..."
git -C "$HOME/.local/share/myproject" pull

# Optional: use coredesktop helpers if needed
# source "$COREDESKTOP/utils.sh"
# install_packages "${MY_PACKAGES[@]}"

2. Install the hook during the sibling's install step

In the sibling's install.sh, copy the hook into coredesktop's updates.d/:

echo "Registering MyProject update hook..."
cp updates.d/70-myproject.sh ~/.local/share/coredesktop/updates.d/

This is a one-time step that wires the sibling into every future update run on the machine.

Available Helpers

Hooks don't inherit functions from earlier hooks, so source utils.sh for its helpers. Do this before defining your own is_installed, because utils.sh has a pacman-specific function with the same name:

source "$COREDESKTOP/utils.sh"

# Install pacman packages (skips already-installed ones)
install_packages "${MY_PACMAN_PACKAGES[@]}"

# Remove packages
remove_packages "${MY_REMOVE_PACKAGES[@]}"

Checklist for Sibling Project Authors

• Create updates.d/7X-<project>.sh in the sibling repo
• Hook script echoes its name so progress is visible during update
• Install step copies the hook to ~/.local/share/coredesktop/updates.d/
• Numeric prefix is an unused number in 71–79
• Script is idempotent — safe to run multiple times without side effects