105 lines
4.1 KiB
Markdown
105 lines
4.1 KiB
Markdown
# 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
|