Run shdeps self-update during update (#23)

Summary

Move steady-state shdeps auto-update ownership into `shdeps update` so
callers do not have to duplicate bootstrap repair logic. The automatic
path is quiet, best-effort, and TTL-gated, while explicit `self-update`
remains immediate and status-bearing.

This keeps the current dotfiles repair bridge useful for rollout, but
makes shdeps own the long-term policy once the new release has
propagated across the fleet.

Details

- run the existing release-archive and source-checkout self-update
building blocks before dependency updates when the self-update stamp is
stale
- preserve force/reinstall semantics so `--force`, `SHDEPS_FORCE=1`, and
reinstall bypass the self-update TTL
- stamp release attempts before GitHub I/O so transient GitHub failures
do not cause every fleet update to retry immediately
- stamp source checkout attempts only after a real pull attempt, so
dirty checkouts can be cleaned and updated on the next run
- pass the sourced wrapper directory as `SHDEPS_DIR` for `shdeps_update`
and `shdeps_self_update`, preserving the "update what I sourced"
contract
- document `SHDEPS_SELF_UPDATE_TTL` and the bootstrap/update ownership
boundary

Testing

- `cargo fmt --all --check`
- `cargo clippy --locked --all-targets -- -D warnings`
- `RUSTDOCFLAGS='-D missing-docs' cargo doc --locked --no-deps`
- `cargo test --locked`
- `cargo test --test cli`
- `tests/shell/install-sh-test`
- `tests/shell/installer-flow-test`
- `tests/shell/lua-api-test`
- `tests/shell/lua-bootstrap-test`
- `tests/shell/release-scripts-test`
- `SHDEPS_RUST_CLI=target/release/shdeps
tests/shell/shdeps-wrapper-test`
- `shellcheck install.sh shdeps.sh tests/shell/install-sh-test
tests/shell/installer-flow-test tests/shell/lua-api-test
tests/shell/lua-bootstrap-test tests/shell/release-scripts-test
tests/shell/helpers.sh scripts/package-release.sh scripts/release.sh
scripts/release-tag.sh scripts/release-version.sh
scripts/smoke-install-bash32.sh scripts/smoke-release.sh
examples/hooks.d/example-hook.sh demo/record.sh`
- `git diff --check`

Skipped locally

- CI's Linux musl release package smoke setup requires `rustup`, which
is not available on this host. The release/script smoke suites were run
locally; CI will exercise the musl package path.

Author: cgraf78

AGENTS.md

@@ -50,6 +50,7 @@ All behavior is controlled via environment variables (no hardcoded paths):
 | `SHDEPS_REINSTALL`   | `0`                                                | Force reinstall all deps                                                                                   |
 | `SHDEPS_QUIET`       | `0`                                                | Suppress non-result output and interactive prompts                                                             |
 | `SHDEPS_REMOTE_TTL`  | `3600`                                             | Cache TTL in seconds                                                                                       |
+| `SHDEPS_SELF_UPDATE_TTL` | `86400`                                        | Self-update attempt TTL for `shdeps update`                                                                |
 | `SHDEPS_GIT_DEV_DIR` | `~/git`                                            | Dev clone directory for the `github:repo` method                                                           |
 | `SHDEPS_INSTALL_DIR` | `~/.local/share`                                   | Base directory for `github:*`, `cargo`, `go`, `uv`, and `npm` installs (each dep lives in `<dir>/<name>/`) |
 | `SHDEPS_BIN_DIR`     | `~/.local/bin`                                     | Directory for binary symlinks                                                                              |

README.md

@@ -93,10 +93,13 @@ The CLI loads all `*.conf` files from `~/.config/shdeps/` (sorted alphabetically
 shdeps self-update
 ```
 
-Uses TTL-based caching to avoid redundant work. Release installs update from
-the latest matching archive, while source checkouts use `git pull --ff-only`
-and skip updates when the working tree has uncommitted changes (active
-development). Use `--force` to bypass the TTL cache.
+Release installs update from the latest matching archive, while source
+checkouts use `git pull --ff-only` and skip updates when the working tree has
+uncommitted changes (active development). `shdeps update` also performs a
+quiet, best-effort self-check for supported shdeps installs before dependency
+updates. That automatic check is TTL-gated by `SHDEPS_SELF_UPDATE_TTL`; use
+`--force` or `SHDEPS_FORCE=1` with `shdeps update` to bypass the self-update
+TTL.
 
 ### Uninstalling
 
@@ -135,6 +138,7 @@ Use `-` for fields you want to skip. See [examples/deps.conf](examples/deps.conf
 | `SHDEPS_REINSTALL`   | `0`                                                     | Force reinstall all deps                                                                                                                                                              |
 | `SHDEPS_QUIET`       | `0`                                                     | Suppress non-result output and interactive prompts                                                                                                                                         |
 | `SHDEPS_REMOTE_TTL`  | `3600`                                                  | Cache TTL in seconds                                                                                                                                                                  |
+| `SHDEPS_SELF_UPDATE_TTL` | `86400`                                             | Self-update attempt TTL in seconds for `shdeps update`                                                                                                                               |
 | `SHDEPS_GIT_DEV_DIR` | `~/git`                                                 | Dev clone directory used only by `github:repo` deps (prefers `<dir>/<repo>` over a managed clone)                                                                                     |
 | `SHDEPS_INSTALL_DIR` | `~/.local/share`                                        | Base directory for shdeps-owned install roots (`github:repo`, archive-style `github:release`, `cargo`, `go`, `uv`, `npm`). Raw release binaries install into `SHDEPS_BIN_DIR` instead. |
 | `SHDEPS_BIN_DIR`     | `~/.local/bin`                                          | Directory for binary symlinks and raw `github:release` binaries                                                                                                                       |
@@ -388,7 +392,7 @@ shdeps_update
 
 ## Bootstrapping (Client Integration)
 
-For projects that embed shdeps (e.g., dotfiles managers), `install.sh --bootstrap` provides a single sourceable entry point that handles discovery, sourcing, CLI symlink, and self-update:
+For projects that embed shdeps (e.g., dotfiles managers), `install.sh --bootstrap` provides a single sourceable entry point that handles discovery, sourcing, and CLI symlink setup:
 
 ```bash
 # Set your project's config before bootstrapping
@@ -409,10 +413,13 @@ The `--bootstrap` flag:
 - **Finds shdeps.sh** via `$SHDEPS_LIB` → `$SHDEPS_GIT_DEV_DIR/shdeps/` → `$SHDEPS_DIR/` → fresh install
 - **Sources it** into the caller (all `shdeps_*` functions become available)
 - **Symlinks the CLI** into `$SHDEPS_BIN` (default `~/.local/bin/shdeps`)
-- **Runs `self-update`** (skips dirty working trees)
+- **Keeps bootstrap fast** by avoiding release freshness checks unless `SHDEPS_FORCE=1`
 - **Is idempotent** — safe to call multiple times
 - **Does not leak `set -e`** into the caller's shell
 
+Call `shdeps_update` after bootstrap to install dependencies and run the
+TTL-gated self-check.
+
 ## Public API
 
 The sourceable Bash API defines the public `shdeps_` functions and delegates

docs/rust-port-spec.md

@@ -187,6 +187,15 @@ Output:
 
 `shdeps self-update` updates the shdeps installation.
 
+`shdeps update` also owns automatic self-update. Before dependency updates, it
+SHOULD perform a quiet, best-effort self-update check for every supported
+install target. This check MUST be TTL-gated by
+`SHDEPS_SELF_UPDATE_TTL` (default: 86400 seconds), MUST stamp attempts rather
+than only successful updates, and MUST treat failures as non-fatal so a
+transient GitHub outage cannot block dependency updates. `--force`,
+`SHDEPS_FORCE=1`, and reinstall mode MUST bypass the self-update TTL. Explicit
+`shdeps self-update` remains the immediate primitive and is not TTL-gated.
+
 Current source-checkout behavior:
 
 - If the install dir contains `.git`, it MUST skip dirty trees.
@@ -395,6 +404,7 @@ Runtime environment variables:
 | `SHDEPS_REINSTALL` | `0` | Force reinstall behavior |
 | `SHDEPS_QUIET` | `0` | Suppress non-result logs and prompts |
 | `SHDEPS_REMOTE_TTL` | `3600` | Remote cache TTL seconds |
+| `SHDEPS_SELF_UPDATE_TTL` | `86400` | Self-update attempt TTL seconds for `shdeps update` |
 | `SHDEPS_GIT_DEV_DIR` | `$HOME/git` | Local dev clone root |
 | `SHDEPS_INSTALL_DIR` | `$HOME/.local/share` | Dependency install root |
 | `SHDEPS_BIN_DIR` | `$HOME/.local/bin` | Public command symlink dir |
@@ -1451,7 +1461,9 @@ Sourceable bootstrap mode MUST:
   install
 - source `shdeps.sh` so Bash API functions become available
 - set up CLI/extras links
-- run method-aware `self-update` when safe
+- avoid release freshness checks during normal bootstrap so callers can render
+  their own UI before network work begins
+- allow `SHDEPS_FORCE=1` to refresh release installs during bootstrap
 - return success/failure to caller instead of exiting the caller shell
 
 Uninstall mode MUST:

man/man1/shdeps.1

@@ -19,11 +19,12 @@ files within a config directory (default:
 .SH COMMANDS
 .TP
 .B update
-Install or update all configured dependencies.
+Install or update all configured dependencies. For supported shdeps installs,
+also performs a quiet, best-effort self-update check before dependency updates.
 .TP
 .B self\-update
-Update shdeps itself by pulling the latest from its git repository.
-Skips the update if the local tree has uncommitted changes.
+Update shdeps itself. Release installs update from the latest matching archive;
+source checkouts use git pull --ff-only and skip dirty trees.
 .TP
 .B list
 List all configured dependencies with columns for name, method, status,
@@ -401,6 +402,11 @@ to suppress non-result output and interactive prompts.
 Cache TTL in seconds.
 Default: 3600.
 .TP
+.B SHDEPS_SELF_UPDATE_TTL
+Self-update attempt TTL in seconds for
+.BR "shdeps update" .
+Default: 86400.
+.TP
 .B SHDEPS_GIT_DEV_DIR
 Dev clone directory for github:repo deps (prefers <dir>/<repo> over fresh clone).
 Default:

shdeps.sh

@@ -103,6 +103,12 @@ _shdepsw_call() {
   command "$_SHDEPSW_BIN" "$@"
 }
 
+_shdepsw_call_from_dir() {
+  local dir
+  dir=$(_shdepsw_dir) || return 1
+  SHDEPS_DIR="$dir" command "$_SHDEPSW_BIN" "$@"
+}
+
 _shdepsw_prepend_bin_dir() {
   local bin_dir
   bin_dir="${SHDEPS_BIN_DIR:-${_SHDEPSW_BIN_DIR:-$(_shdepsw_call __api bin-dir)}}"
@@ -196,8 +202,8 @@ _shdepsw_cache_env || return 1 2>/dev/null || exit 1
 # alone.
 
 shdeps_version() { _shdepsw_call version "$@"; }
-shdeps_update() { _shdepsw_prepend_bin_dir && _shdepsw_call update "$@"; }
-shdeps_self_update() { _shdepsw_call self-update "$@"; }
+shdeps_update() { _shdepsw_prepend_bin_dir && _shdepsw_call_from_dir update "$@"; }
+shdeps_self_update() { _shdepsw_call_from_dir self-update "$@"; }
 shdeps_load() { _shdepsw_call __api load-count "$@"; }
 shdeps_prune() { _shdepsw_call prune "$@"; }