davidandClaude Opus 5.5
76fceee115
`sibling` asks for a git URL, clones the repo into ~/.local/share/siblings/<name>, runs its install.sh and confirms the install. `sibling list` and `sibling remove` manage installed siblings. updates.d/71-siblings.sh pulls every sibling during `update` and runs its update.sh, reporting failures in the update summary. Document the sibling contract in skills/sibling-project-format.md and update the custom-hook guide to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
# Skill: Supporting the updates.d Update Architecture in a Sibling Project
|
||
|
||
## Overview
|
||
|
||
There are two ways for a sibling project to plug into CoreDesktop:
|
||
|
||
1. **The `sibling` command (preferred).** The user runs `sibling` and gives it
|
||
the project's git URL. The repo is cloned into
|
||
`~/.local/share/siblings/<name>` and its `install.sh` (if any) is run once.
|
||
On every `update`, `updates.d/71-siblings.sh` pulls each sibling and runs its
|
||
`update.sh` (if any). The sibling only needs those two optional scripts.
|
||
2. **A custom hook.** CoreDesktop's `update` script sources every `*.sh` file
|
||
found in `~/.local/share/coredesktop/updates.d/` in filename order. A sibling
|
||
project can install its own numbered shell script into that directory during
|
||
its own install step, for full control over how and when it updates.
|
||
|
||
## Using the `sibling` Command
|
||
|
||
See `sibling-project-format.md` for the full rules, templates and testing.
|
||
In short, give the repo these optional files at its top level:
|
||
|
||
| File | When it runs |
|
||
|--------------|---------------------------------------------------|
|
||
| `install.sh` | Once, from the repo folder, when the user runs `sibling add` (and again if they re-run it) |
|
||
| `update.sh` | On every `update`, from the repo folder, after the repo has been pulled |
|
||
|
||
Both run with `bash`, and a non-zero exit is reported as a failure.
|
||
`update.sh` should be idempotent. If you have no `update.sh`, `update` just pulls the repo.
|
||
|
||
Commands:
|
||
|
||
```bash
|
||
sibling # asks for the git URL
|
||
sibling add <url> # same, without the prompt
|
||
sibling list # installed siblings, their URL and current commit
|
||
sibling remove <name> # deletes ~/.local/share/siblings/<name>
|
||
```
|
||
|
||
The rest of this document covers the custom-hook approach.
|
||
|
||
## 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 |
|
||
| `71-siblings.sh` | Projects installed with `sibling` |
|
||
| `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 **72–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/72-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/72-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.
|
||
|
||
### Optional: only update when installed
|
||
|
||
Instead of running code at the top level, a hook can define `run_update` and,
|
||
optionally, `is_installed`. `update` calls `run_update` only when `is_installed`
|
||
is missing or returns true, so the hook is skipped on machines where the project
|
||
isn't installed. Return non-zero from `run_update` to report a failure:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
is_installed() {
|
||
[ -d "$HOME/.local/share/myproject" ]
|
||
}
|
||
|
||
run_update() {
|
||
echo "Updating MyProject..."
|
||
git -C "$HOME/.local/share/myproject" pull --ff-only
|
||
}
|
||
```
|
||
|
||
## 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 72–79
|
||
- [ ] Script is idempotent — safe to run multiple times without side effects
|