/upgrade-deps

description: Autonomous dependency upgrade pipeline — detect outdated dependencies, create upgrade issues, and run /work-on to investigate, build, test, and merge each upgrade
argument-hint: "[--dry-run | --ecosystem npm|pip|cargo | --allow-major | --limit N | --batch]"

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/upgrade-deps — Autonomous Dependency Upgrade Pipeline

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

You are a dependency upgrade agent. Your job is to detect outdated packages, triage them by semver risk level, create GitHub issues for eligible upgrades, and run them through the full `/work-on` pipeline — so each upgrade gets investigation, compatibility verification, quality gate, review, and merge — rather than a blind version bump PR.

**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. **NEVER use plan mode (EnterPlanMode).**

---

Argument Parsing

| Flag | Effect | |------|--------| | (none) | Detect + triage + report (no issue creation, no fixing) | | `--dry-run` | Run all phases but do NOT create issues, PRs, or labels — report only | | `--ecosystem npm` | Limit detection to npm only | | `--ecosystem pip` | Limit detection to pip only | | `--ecosystem cargo` | Limit detection to cargo only | | `--allow-major` | Include major upgrades in issue creation (default: flag for human review only) | | `--limit N` | Cap issue creation to at most N issues per run (default: 10) | | `--batch` | Group all patch upgrades into one batch issue instead of one-per-package | | `--fix` | After issue creation, also invoke `/work-on` on each created issue |

Parse `$ARGUMENTS`:

DRY_RUN=false
ECOSYSTEM_FILTER=""
ALLOW_MAJOR=false
ISSUE_LIMIT=10
BATCH_PATCHES=false
DO_FIX=false
NEXT_IS_ECOSYSTEM=false
NEXT_IS_LIMIT=false

for arg in $ARGUMENTS; do
  case "$arg" in
    --dry-run)       DRY_RUN=true ;;
    --allow-major)   ALLOW_MAJOR=true ;;
    --batch)         BATCH_PATCHES=true ;;
    --fix)           DO_FIX=true ;;
    --ecosystem)     NEXT_IS_ECOSYSTEM=true ;;
    --limit)         NEXT_IS_LIMIT=true ;;
    *)
      if [ "$NEXT_IS_ECOSYSTEM" = "true" ]; then
        ECOSYSTEM_FILTER="$arg"
        NEXT_IS_ECOSYSTEM=false
      elif [ "$NEXT_IS_LIMIT" = "true" ]; then
        ISSUE_LIMIT="$arg"
        NEXT_IS_LIMIT=false
      fi
      ;;
  esac
done

If `DRY_RUN=true`, prefix all actions with `[DRY RUN]` and skip all `gh issue create`, `gh issue edit`, and `Skill()` invocations — report what would happen instead.

---

Phase 0: Config Resolution

**Config variables used by this command** (set in `forge.yaml → upgrade_deps`):

• `{ECOSYSTEMS}` ← `upgrade_deps.ecosystems` — list of ecosystems to check (default: `["npm"]`)
• `{ALLOW_MAJOR_CONFIG}` ← `upgrade_deps.allow_major` (default: `false`) — whether to create issues for major upgrades
• `{EXCLUDE_PACKAGES}` ← `upgrade_deps.exclude` — list of package names to skip regardless of semver level
• `{ISSUE_BATCH_SIZE}` ← `upgrade_deps.issue_batch_size` — how many patch packages to group per batch issue (default: 5)

Read `forge.yaml` at the project root before running any phase:

CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
if [ ! -f "$CONFIG_FILE" ]; then
  echo "ERROR: forge.yaml not found. Run: npx forgedock init && /forgedock-init"
  exit 1
fi

GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
GH_FLAG="-R $GH_REPO"
REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
STAGING_BRANCH=$(yq '.branches.staging // "staging"' "$CONFIG_FILE")

# upgrade_deps section (all optional — fall back to defaults)
ECOSYSTEMS_CONFIG=$(yq '.upgrade_deps.ecosystems // ["npm"] | join(" ")' "$CONFIG_FILE" 2>/dev/null || echo "npm")
ALLOW_MAJOR_CONFIG=$(yq '.upgrade_deps.allow_major // false' "$CONFIG_FILE" 2>/dev/null || echo "false")
EXCLUDE_PACKAGES=$(yq '.upgrade_deps.exclude // [] | join(" ")' "$CONFIG_FILE" 2>/dev/null || echo "")
ISSUE_BATCH_SIZE=$(yq '.upgrade_deps.issue_batch_size // 5' "$CONFIG_FILE" 2>/dev/null || echo "5")

# CLI flags override config values
[ "$ECOSYSTEM_FILTER" != "" ] && ECOSYSTEMS_CONFIG="$ECOSYSTEM_FILTER"
[ "$ALLOW_MAJOR" = "true" ] && ALLOW_MAJOR_CONFIG="true"

---

Phase 1: Detect Outdated Dependencies

Run dependency detection for each configured ecosystem. Skip an ecosystem if its tool is not installed.

1A: npm

if echo "$ECOSYSTEMS_CONFIG" | grep -q "npm"; then
  if command -v npm >/dev/null 2>&1; then
    echo "--- npm ecosystem ---"
    cd "$REPO_PATH"
    NPM_OUTDATED=$(npm outdated --json 2>/dev/null || echo "{}")
    echo "$NPM_OUTDATED" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for pkg, info in data.items():
    current = info.get('current', 'N/A')
    wanted = info.get('wanted', 'N/A')
    latest = info.get('latest', 'N/A')
    print(f'{pkg}|{current}|{wanted}|{latest}')
" 2>/dev/null || true
  else
    echo "npm not installed — skipping npm ecosystem"
  fi
fi

1B: pip

if echo "$ECOSYSTEMS_CONFIG" | grep -q "pip"; then
  PIP_CMD=""
  command -v pip3 >/dev/null 2>&1 && PIP_CMD="pip3"
  command -v pip >/dev/null 2>&1 && PIP_CMD="${PIP_CMD:-pip}"

  if [ -n "$PIP_CMD" ]; then
    echo "--- pip ecosystem ---"
    $PIP_CMD list --outdated --format=json 2>/dev/null | python3 -c "
import json, sys
data = json.load(sys.stdin)
for pkg in data:
    print(f'{pkg[\"name\"]}|{pkg[\"version\"]}|{pkg[\"latest_version\"]}')
" 2>/dev/null || true
  else
    echo "pip/pip3 not installed — skipping pip ecosystem"
  fi
fi

1C: cargo

if echo "$ECOSYSTEMS_CONFIG" | grep -q "cargo"; then
  if command -v cargo >/dev/null 2>&1 && command -v cargo