Skip to content

Library update check

ContributorsMyles Henaghan

When to use: Check whether this library checkout is behind remote, summarize missing commits (interim stand-in for a changelog), and optionally pull.

There is no release / version-tagging yet. This skill compares git SHAs and commit subjects only. A proper CHANGELOG and tagged releases will replace that later — the helper script comments the same future work.

Instructions

0) Expect sandbox / network failures on fetch (do this first)

git fetch often fails inside agent sandboxes with DNS errors such as Could not resolve hostname github.com / Temporary failure in name resolution. That is normal, not proof the library is unreachable.

When running the checker (or any git network step):

  1. Prefer requesting full network (or unrestricted) permissions on the shell/tool call up front.
  2. If fetch_ok is false and stderr mentions DNS / hostname resolution / sandbox: retry once with broader network permissions before telling the user the remote is down.
  3. Only after a retried failure: report that remote state may be stale, or use --skip-fetch and say the check is offline/optimistic.

Do not dump raw sandbox stack traces as the primary answer.

1) Run the checker (deterministic)

From the library git root (this repo, or the submodule / symlink target that contains library/skills/):

node library/skills/library-update/scripts/check-library-version.mjs --pretty

If you already know the checkout path (e.g. after resolving a skill symlink):

node <library-root>/library/skills/library-update/scripts/check-library-version.mjs --repo <library-root> --pretty

Parse the JSON. Key fields: status, behind, ahead, local_short, remote_short, mode (standalone | submodule), dirty, fetch_ok.

2) Tell the user the bottom line

Lead with a short status line. Use ✅ when the tip matches remote:

status What to say
up-to-date ✅ Library tip matches remote (local_short). You're up to date.
behind You are N commits behind (behind). Offer details, then offer pull.
ahead Local has commits not on remote — unusual for a consumer; report ahead.
diverged Local and remote have diverged — do not pull automatically; explain.

If fetch_ok is false after the sandbox retry above, say results may be stale. Do not invent a changelog.

3) Expect a dirty working tree — ask what to do

dirty: true is common (authors mid-edit, uncommitted skill work). It does not invalidate the version check. Always surface it briefly.

If the user only wanted a check and status is up-to-date: note the dirty tree in one line; no need to block.

If a pull (or other write) is on the table, or the user asks what to do with local changes, ask before acting. Prefer AskUserQuestion with choices:

Choice Meaning
Leave as-is Keep working tree; skip pull (or check-only)
Stash, then pull git stash push, pull --ff-only, offer stash pop
Commit first Help them commit on the current feature branch, then re-check / pull
Show what is dirty git status / short diff summary, then ask again

Never discard local changes unless the user explicitly chooses that and confirms. Never force-clean.

4) Optional details (commit messages as interim changelog)

If behind and the user wants to know what changed:

node library/skills/library-update/scripts/check-library-version.mjs --details --pretty

Present details (oneline subjects) as a short list. Prefer AskUserQuestion for “Show commit details?” / “Pull now?” when available.

5) Pull only after confirmation

Never pull without an explicit yes. Never force. Never reset.

Resolve dirty via §3 first. Prefer fast-forward only.

Standalone clone (mode: standalone):

git -C <library-root> pull --ff-only

Submodule (mode: submodule):

git -C <library-root> pull --ff-only

Then remind them: the parent repo still pins the old submodule SHA — they need a parent commit after a successful submodule pull if the team tracks that pin. IDE symlinks into library/skills/ pick up content immediately; no copy step.

6) After pull

Re-run the checker (without --skip-fetch if network works) and confirm status: up-to-date.

References

Troubleshooting

Symptom Likely cause Fix
fetch_ok: false + DNS / hostname errors Agent sandbox blocked network Retry shell with full/unrestricted network; only then treat as offline
fetch_ok: false after retry Truly offline / auth --skip-fetch and say check is optimistic/stale
dirty: true during check Mid-edit local work (expected) Note it; ask before pull — leave / stash / commit / show dirty
Pull refused (non-ff) Diverged history Inspect with --details; do not force; rebase/reset only with human intent
Submodule still “old” in parent Parent pin not updated Commit the new submodule SHA in the consumer repo
No version number shown Expected — no release tags yet Use commit count + shortlog until tagging lands