Maintenance and Updates

Maintenance & Updates

Core separates noticing updates from applying them, and separates low-risk user-space updates (safe to automate) from system-package upgrades (kept manual). This page maps the moving parts.

The philosophy: check, then choose

Core never runs update && upgrade on every shell start. That would block every pane on a package sync, need root on every shell, be dangerous to automate on Arch/Gentoo/Kali, and hang when offline. Instead:

• update.zsh runs a throttled (once/day), fully-backgrounded, non-root check on shell start and prints a single one-line nudge when packages are upgradable.
• applying is your call, via up.

The up updater

up (in update.zsh) applies package updates interactively, confirming first. It detects the box's package manager (_pkgup_mgr — brew wins on macOS) and uses the right privilege helper (sudo, else doas on Alpine). Related verbs:

Command	What it does
up [-y]	apply package updates (interactive; confirms first)
update-check	refresh the "updates available" nudge cache

Config knobs (set in os/local before update.zsh is sourced): UPDATE_CHECK_ENABLED (set 0 to disable, e.g. Kali during ops), UPDATE_CHECK_INTERVAL (seconds between checks, default 86400).

The daily maintenance runner

For unattended upkeep, maint/dotfiles-maint.sh is the "update everything that's safe" runner, scheduled via a systemd user timer / launchd / cron. It's designed to run non-interactively: every step is guarded, time-limited, and one step's failure never aborts the rest. It updates the user-space stack (brew, zsh plugins, editor) automatically — those are low-risk — and only checks system packages (refreshing the nudge cache). It uses a single-instance lock and logs to $XDG_STATE_HOME/dotfiles-maint/maint.log.

Control surface (in maint.zsh):

Command	What it does
maint-install [HH:MM]	schedule the daily safe-update job
maint-run	run daily maintenance now
maint-log [-f]	view (or follow) the maintenance log

Env knobs include MAINT_SYSTEM_UPGRADE=1 (also apply system pkgs — apt/dnf/ zypper/brew only, never Arch/Gentoo/Kali), MAINT_ENABLED=0 (no-op, e.g. on a Kali engagement box), and per-step timeouts.

Pinned dependencies and the freshness gate

Everything third-party that runs in Core is pinned so nothing floats silently into the nine OS repos — and because a pin, once set, can rot on a known-vuln commit, a weekly gate watches for drift.

What's pinned	Where	Roll it forward
zsh plugins	zsh/plugins.zsh (SHAs)	make update-plugins
Neovim plugins	nvim/lazy-lock.json	make update-nvim-plugins
CI linters / tool versions	scripts/tool-versions.env	edit + audit checks consistency
pre-commit hooks	.pre-commit-config.yaml	make update-hooks
GitHub Actions	by SHA in workflows	dependabot (.github/dependabot.yml)

The freshness workflow (.github/workflows/freshness.yml) runs Mondays 06:00 UTC (and on demand). It runs the update scripts' --check mode, which exits non-zero when a pin is behind upstream — a red run is the nudge to run the matching make target. Check both pin sets locally any time with:

make check-pins

Quick reference

up                   # apply package updates (interactive)
maint-run            # run the safe daily maintenance now
make check-pins      # are the zsh + nvim pins behind upstream?
make update-plugins  # roll zsh-plugin SHAs forward (deliberate bump)
make update-nvim-plugins  # roll nvim lockfile forward

See also

• The Audit (Quality Gate) — the version-consistency check that keeps the pins in step.
• The Zsh Module System — where update.zsh and maint.zsh sit in the load order.