# 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:

```bash
#!/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/`:

```bash
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:

```bash
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