---
name: dep-upgrader
description: Maintain dependencies, security, and quality across polyglot local workspaces containing Next.js, Node.js, pnpm, .NET, NuGet, and Avalonia. Use when an agent must detect projects, migrate npm workspaces to pnpm, enforce a minimum seven-day release age for Node dependencies, update packages, run audits, validate builds and tests, consolidate package versions, analyze configuration or UI assets, configure Renovate or Changesets, or orchestrate safe backups and rollbacks.
compatibility: Bash, Node.js 20+, pnpm, and an optional .NET SDK. External scanners such as OSV-Scanner and Trivy are used only when already available; local tool installation requires explicit authorization.
---

# Dep Upgrader

Use this skill to maintain mixed local workspaces containing Node.js/Next.js and .NET/Avalonia projects. The bundled runner is the source of truth for discovery, execution, logging, dry-run behavior, backup, and rollback.

## Entry point

Run from the skill directory or by absolute path:

```bash
./scripts/dep-upgrader.sh --root /path/to/workspace
```

For automation or CI, use non-interactive mode:

```bash
./scripts/dep-upgrader.sh \
  --root /path/to/workspace \
  --non-interactive \
  --module all \
  --mode semver-safe \
  --quality-profile full \
  --audit report \
  --harden strict \
  --keep-going
```

Always start uncertain or high-impact maintenance with `--dry-run`.

## Required operating sequence

1. **Inspect** the workspace with `--list` and read the Git status.
2. **Select** only the relevant projects or ecosystem.
3. **Preview** with `--dry-run` when updates, cleanup, migration, config generation, or rollback are involved.
4. **Update** with the narrowest suitable mode: `patch`, `minor`, `semver-safe`, `latest`, or `interactive`.
5. **Audit** with native pnpm and NuGet checks before optional OSV or Trivy scans.
6. **Validate** using project-specific lint, format, typecheck, build, test, run, or publish actions.
7. **Review** generated reports under `.maintenance/logs` and retain the backup path.
8. **Rollback** when mandatory validation fails and the change cannot be repaired safely.

Do not claim a successful update unless the relevant install/restore and requested validation gates completed successfully.

## Project discovery

The runner classifies at least:

- `nextjs-app`: `package.json` with a `next` dependency;
- `shared-package`: Node package within a workspace that is not a Next.js app;
- `dotnet-app`: executable SDK-style project;
- `dotnet-lib`: non-executable SDK-style project;
- `avalonia-app`: .NET project with Avalonia package references or AXAML markers;
- `unknown`: detected manifest without a supported classification.

Local workspace files are primary. GitHub metadata is optional context and must not replace local inspection.

## Mandatory Node policy

For every selected Node workspace and parent workspace root, the dependency update module must:

1. remove the complete `.next` and `node_modules` directories at recognized project and workspace roots;
2. import existing `package-lock.json` or `npm-shrinkwrap.json` with `pnpm import` where possible;
3. migrate root and child `package.json` files to a concrete `packageManager: pnpm@...` value;
4. remove npm lockfiles after migration;
5. write or update `pnpm-workspace.yaml` with `minimumReleaseAge: 10080`;
6. run `pnpm install --fix-lockfile` once per workspace root;
7. never call `pnpm -r dlx`; execute `pnpm dlx npm-check-updates` in each project directory instead.

These behaviors must respect `--dry-run`. Cleanup is intentionally limited to discovered project and workspace roots.

## Dependency update behavior

### Node.js / Next.js

Use:

- `npm-check-updates` for version changes;
- pnpm install, dedupe, audit, signatures, hardening, and SBOM support;
- Syncpack for workspace-wide version consistency;
- Knip for unused dependencies, files, and exports;
- Dependency Cruiser for cycles and architecture constraints;
- Publint and Are The Types Wrong for publishable shared packages.

### .NET / Avalonia

Capability-detect:

- `dotnet package list --help`;
- `dotnet list package --help`;
- `dotnet package update --help`;
- `dotnet format --help`.

Prefer native package list/update commands when supported. Fall back to a locally isolated `dotnet-outdated-tool` when necessary. Support solutions, standalone projects, central package management, lockfiles, vulnerable package reporting, build, test, format, run, publish, and RID-aware Avalonia validation.

Do not migrate target frameworks automatically unless the user explicitly requests it and accepts source compatibility risk.

## Quality module

Run:

```bash
./scripts/dep-upgrader.sh --root . --non-interactive --module quality --quality-profile full
```

Profiles:

- `quick`: Syncpack, Knip, package publishing checks;
- `full`: quick checks plus Dependency Cruiser, ATTW, JSCPD, and OSV when installed;
- `deep`: full checks plus Trivy and optional Stryker.NET.

`--fix` permits supported low-risk corrections such as `syncpack fix`. `--install-tools` permits local installation of Stryker under the target workspace's `.maintenance/tools`; it never installs global tools.

Missing optional native tools are reported as warnings, not silently treated as successful scans.

## Automation module

Generate conservative repository automation only with explicit write authorization:

```bash
./scripts/dep-upgrader.sh \
  --root . \
  --non-interactive \
  --module automation \
  --generate-renovate \
  --generate-changesets \
  --yes
```

The generated Renovate configuration enforces a seven-day minimum release age for npm and NuGet. Changesets is created only when shared Node packages are detected. Existing configuration files are not overwritten.

## Security and audit

Use native checks first:

- `pnpm audit` and optional signature audit;
- NuGet audit during restore and vulnerable package listing;
- NuGet source inspection and warnings for HTTP or unusual feeds;
- floating and prerelease PackageReference warnings.

Then add optional cross-stack checks:

- OSV-Scanner for source-tree dependency vulnerabilities;
- Trivy for vulnerabilities, secrets, misconfiguration, and license findings.

Never auto-remediate a security finding by broad major-version upgrades without preview and validation.

## Config and UI analysis

The config module scans Node environment references and .NET configuration sources, classifies likely secret and runtime keys, and may generate non-secret example files without overwriting existing files.

The UI analysis module is analysis-first:

- Next.js: components, layouts, styles, primitives, Radix, shadcn, Tailwind, and animation helpers;
- Avalonia: AXAML, resources, styles, templates, controls, converters, behaviors, views, and view models.

It must produce candidates and a refactoring plan before moving files or rewriting imports.

## Safety rules

- Check Git status before mutations.
- Create a manifest-based backup before dependency updates.
- Use `--stash` only when the user explicitly requested it.
- Respect `--dry-run` in every module.
- Continue unrelated project work after an isolated failure when `--keep-going` is active.
- Do not overwrite existing Renovate, Changesets, environment example, or appsettings example files.
- Do not install global packages.
- Do not merge, publish, deploy, or push changes unless separately authorized.

## Useful commands

```bash
# Inventory
./scripts/dep-upgrader.sh --root . --list

# Safe preview
./scripts/dep-upgrader.sh --root . --non-interactive --module all --mode semver-safe --dry-run

# Node only
./scripts/dep-upgrader.sh --root . --non-interactive --module deps --ecosystems node --mode latest --harden strict

# .NET and Avalonia only
./scripts/dep-upgrader.sh --root . --non-interactive --module deps --ecosystems dotnet --mode latest

# Full validation
./scripts/dep-upgrader.sh --root . --non-interactive --module validate --validate full

# Deep quality scan; optional local Stryker installation
./scripts/dep-upgrader.sh --root . --non-interactive --module quality --quality-profile deep --install-tools

# Restore a backup
./scripts/dep-upgrader.sh --root . --rollback .maintenance/backups/TIMESTAMP
```

Read [references/pipeline.md](references/pipeline.md) for stage ordering and [references/tool-matrix.md](references/tool-matrix.md) for tool scope and failure semantics.