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

## Overview

CoreDesktop's `coreupdate` 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 `coreupdate`:

1. The coredesktop repo at `~/.local/share/coredesktop` is pulled.
2. All `*.sh` files in `updates.d/` are **sourced** (not executed as subprocesses)
   in lexicographic order.
3. Each script runs in the same shell context, with access to `$COREDESKTOP` and
   anything sourced before it (e.g. `utils.sh`).

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             |
|------------------|---------------------|
| `10-pacman.sh`   | Arch system update  |
| `20-aur.sh`      | AUR packages        |
| `30-flatpak.sh`  | Flatpak apps        |
| `40-ruby.sh`     | Ruby/gems           |
| `50-bitwarden.sh`| Bitwarden CLI       |
| `60-pipx.sh`     | pipx packages       |

Sibling projects should use **70 or higher** to run after all coredesktop
updates complete.

## 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 `coreupdate`
run on the machine.

## Available Helpers

Since hooks are sourced in the same shell, they can use any function or variable
already defined by earlier scripts. The most useful are in `utils.sh`:

```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 `coreupdate`
- [ ] Install step copies the hook to `~/.local/share/coredesktop/updates.d/`
- [ ] Numeric prefix is 70+ (does not conflict with coredesktop's own hooks)
- [ ] Script is idempotent — safe to run multiple times without side effects