deps-updater

name	deps-updater
description	Updates dependencies to exact latest versions across the monorepo. Use when user says 'update dependencies', 'upgrade deps', or 'run dep update'.

deps-updater

Overview

Scans every package.json and Cargo.toml in the workspace, resolves latest versions, pins them as exact, runs available codemods, then verifies nothing broke. Detects breaking changes and researches fixes, asking for user approval in interactive mode. Supports headless mode and scope narrowing (--workspace, --packages, --skip-packages). Act as a senior dependency maintenance engineer — minimize drift while protecting stability.

Conventions

• Bare paths (e.g. references/discover-deps.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying structural merge rules: {skill-root}/customize.toml, {project-root}/_bmad/custom/{skill-name}.toml, {project-root}/_bmad/custom/{skill-name}.user.toml. Scalars override, tables deep-merge, arrays of tables keyed by code/id replace matching entries and append new ones, all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context for the whole run. Entries prefixed file: are paths or globs — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order before entering the workflow's first stage.

Step 5: Detect Headless

If --headless or -H was passed, set headless=true for the run. Read {workflow.headless_breaking_policy} to determine breaking-change treatment.

Step 6: Parse Scope

Parse --workspace, --packages, and --skip-packages from invocation args. Fall back to {workflow.workspace_scope}, {workflow.package_scope}, {workflow.skip_packages} if not provided. Empty means "all".

Workflow

Pre-flight

Before any file writes, verify:

• Git is available and working tree is clean (warn if dirty, block in headless mode).
• Required tools are installed: ncu (npm-check-updates) and cargo-upgrade (cargo-edit). If missing, install them.
• Network is reachable to package registries (npm registry, crates.io).
• The project has the expected file structure (root package.json, Cargo.toml for Rust workspaces).

In interactive mode, present a summary of what will be checked and ask to proceed. In headless mode, abort early if any pre-flight check fails.

Stage 1: Discover Dependencies

Load references/discover-deps.md and execute. Applies scope filters to the manifest. Produces a filtered manifest of external deps across JS and Rust workspaces.

Progression: proceed when a complete, filtered manifest has been produced.

Soft-gate (interactive only): Present the scope and number of packages to update. "Ready to update {N} packages across {M} workspaces to latest? Any packages to skip or workspaces to exclude?" Let the user adjust scope before proceeding to file mutations.

Stage 2: Run Codemods

Load references/run-codemods.md and execute. For each dep in the manifest with a matching entry in {workflow.codemod_registry}, run the registered migration. Codemods run BEFORE version bumps so they can transform code while the old version is still installed.

Progression: proceed when all applicable codemods have been attempted (failures are warnings, not blockers).

Stage 3: Resolve and Pin

Load references/resolve-and-pin.md and execute. Updates all package.json and Cargo.toml to latest exact versions. Save a diff of what changed before proceeding.

Progression: proceed when all deps are at latest exact versions (or breaking changes were deferred to user approval).

Stage 4: Verify

Load references/verify-fixes.md and execute. Run typecheck, lint, build, and tests across the workspace.

Progression: proceed on all-clear. On failures, offer to roll back or fix.

Stage 5: Handle Breaking Changes

Load references/detect-breaking.md and execute. Identify major-version bumps, research migration paths, and in interactive mode ask the user to approve each one before finalizing.

Progression: all breaking changes resolved (approved, reverted, or skipped per headless policy).

Stage 6: Report

Load references/report.md and execute. Summarize what changed, what was verified, and any unresolved issues. In headless mode, this is the final output. In interactive mode, present and ask if the user is satisfied.

Headless Output

When headless=true, emit JSON at the end:

{
  "status": "complete",
  "scope": { "workspaces": ["apps/webview-ui"], "packages": [], "skipped": [] },
  "updated_packages": 5,
  "breaking_changes": ["next@17.0.0", "react@20.0.0"],
  "unresolved": [],
  "verification": "all-passed"
}

On verification failure: "status": "blocked" with a "reason" field.

Rollback

If verification fails in Stage 4, the user may ask to roll back. Restore from git: git checkout -- <paths> for affected files. The diff saved in Stage 3 is the source of truth for what changed.