version-check

Version Check

Check whether the installed plugin version is up to date. Works from any directory.

Plugin Identity

Key	Value
Plugin	agent-flow
Marketplace	agent-flow
Legacy names	CLAUDE-agents

All steps below use {plugin} and {marketplace} from this table.

Steps

Part A: Installed Plugin Status (always runs)

1. Read ~/.claude/plugins/installed_plugins.json.

   • If the file does not exist → report: "Claude Code plugin registry not found at ~/.claude/plugins/installed_plugins.json. No plugins installed — run /plugin install first." and STOP.
   • If the file is empty or is not valid JSON → report: "Plugin registry at ~/.claude/plugins/installed_plugins.json is empty or corrupt — cannot parse." and STOP.
   • Search for the plugin: find any key in plugins that starts with {plugin}@. If no match, also search for keys starting with any name in Legacy names (e.g. CLAUDE-agents@). Prefer {plugin}@{marketplace} if it exists; otherwise use the first match.
   • If no matching key found → report: "{plugin} plugin is not installed. Run: /plugin install {plugin}@{marketplace}" and STOP.
   • Read version and installPath from the matched entry. Store as installed_version, install_path, and note the actual registry key as registry_key.
   • If registry_key does not equal {plugin}@{marketplace} → warn: "Plugin is registered under {registry_key} instead of {plugin}@{marketplace}. Consider reinstalling: /plugin uninstall {plugin} then /plugin install {plugin}@{marketplace}"

2. Verify install_path exists on disk.

   • If it does not exist → warn: "Install path {install_path} does not exist — plugin may need reinstalling. Run: /plugin uninstall {plugin} then /plugin install {plugin}@{marketplace}". Continue to step 3.

3. Determine the latest available version from remote.

   • Determine the remote URL to query. Try these sources in order (first success wins):
     1. If CWD is a git repo AND Part B will activate (.claude-plugin/plugin.json exists with matching name) → use git remote get-url origin from CWD. This is the most reliable source (uses the developer's configured SSH/HTTPS auth).
     2. Otherwise → read {install_path}/.claude-plugin/plugin.json and extract the repository field.
     3. If neither source yields a URL → report: "Remote version check skipped — no remote URL available." Skip to step 4 (show installed version only).
   • Before running the remote call, check whether the URL is a placeholder. This check applies to source-2 only (plugin.json repository); source-1 (user git remote) is trusted by definition.

     # RFC 2606 reserved TLD fast-fail:
     # source-2 only; HTTPS-only scope; SSH SCP-style deferred (no source-1 check)
     # Extract hostname from URL, then match (test|example|invalid|localhost) as last DNS label
     # or as the bare host. Path-anchored matching avoids false positives where a reserved
     # label appears in a path component (e.g. github.com/foo.invalid/bar).
     # Match alternation kept inline for harness compatibility: (test|example|invalid|localhost)
     host=$(echo "$remote_url" | sed -E 's|^[a-z]+://([^/]+).*|\1|' | sed -E 's|^[^@]+@||' | sed -E 's|:[0-9]+$||')
     host="${host%.}"  # strip RFC 1034 trailing dot
     last_label=$(echo "$host" | awk -F. '{print $NF}')
     if [ "$last_label" = "test" ] || [ "$last_label" = "example" ] || [ "$last_label" = "invalid" ] || [ "$last_label" = "localhost" ] \
        || [ "$host" = "test" ] || [ "$host" = "example" ] || [ "$host" = "invalid" ] || [ "$host" = "localhost" ]; then
       echo "Remote version check skipped — plugin.json \`repository\` field is a placeholder. Set it to a real URL."
       exit 0
     fi
     

     The boundary anchor (/|:|$) is implicit in the hostname-extract step — the host is delimited by / or end-of-string after the scheme, so the URL parser handles boundary detection.
   • Run:

     timeout 10 git ls-remote --tags {remote_url} 'refs/tags/v*' 2>/dev/null | grep -v '\^{}' | sort -t/ -k3 -V | tail -1
     

     If timeout is not available, omit it and run git ls-remote directly.
   • If the command fails (network error, SSL error, auth failure, timeout) → report: "Cannot reach remote repository. Showing installed version only." Skip to step 4.
   • If the output is empty (no tags, or no tags matching v*) → report: "No version tags found on remote repository. Showing installed version only." Skip to step 4.
   • Extract the version string from the tag reference (e.g., refs/tags/v5.5.1 → 5.5.1). Store as remote_version.