upgrade-dependencies

name

upgrade-dependencies

description

Upgrade npm dependencies in this repository with a strict, safe git and PR flow. Use when asked to refresh package versions, maintain npm dependencies, or prepare dependency-upgrade PRs for relewise-demos-shop-vue. Require a Trello card URL (ask for it if missing), enforce main-branch preflight checks, create a monthly chore branch, upgrade direct npm dependencies across discovered package.json manifests, resolve manageable compatibility fallout, run required validation commands for relewise-demos-shop-vue, then push and open a PR with the Trello link at the top.

Upgrade Dependencies

Goal

Upgrade direct npm dependencies to latest stable versions for this repository and deliver a validated PR to main.

Required Input

Require a Trello card URL before running upgrade work.

If the prompt does not include a Trello URL, ask for it first and do not continue until provided.

Preflight Git Safety

Run commands from repository root.

1. Require a strict clean worktree:

git status --porcelain

Abort when any output exists.

2. Ensure origin exists:

git remote get-url origin

Abort on failure.

3. Fetch refs:

git fetch origin --prune

Abort on failure.

4. Switch to main:

git switch main

Abort if switch is not safe.

5. Fast-forward local main:

git pull --ff-only origin main

Abort if not fast-forward or if pull fails.

Do not continue when any preflight step fails.

Branch Creation

Use a monthly branch:

$stamp = Get-Date -Format 'yyyyMM'
$branchName = "chore/upgrade-dependencies-$stamp"

Abort if branch exists locally or remotely:

git show-ref --verify --quiet "refs/heads/$branchName"
git ls-remote --exit-code --heads origin $branchName

Create and switch:

git switch -c $branchName

Version Range Preservation Rules

Preserve existing version-range declarations when upgrading dependencies.

• npm: If the current declaration uses comparator-range syntax (for example >=1.1.6 <2.0.0), keep it unchanged and do not rewrite it to caret/tilde/exact forms.
• Skip upgrade commands for dependencies already declared as ranges under the rules above.
• You may still report recommended minimum-version bumps when vulnerabilities or critical fixes are identified.

Discover npm Manifests

Discover all package.json files, excluding node_modules.

Preferred command:

if (Get-Command rg -ErrorAction SilentlyContinue) {
    rg --files -g "**/package.json" -g "!**/node_modules/**"
} else {
    Get-ChildItem -Recurse -Filter package.json | Where-Object { $_.FullName -notmatch '\\node_modules\\' } | ForEach-Object { $_.FullName }
}

Treat each discovered manifest directory as an upgrade target.

npm Upgrade Workflow

For each discovered manifest directory:

1. Install dependencies:

npm install

2. Upgrade direct dependencies and devDependencies to latest stable:

$packageJson = Get-Content -Raw .\package.json | ConvertFrom-Json
$allPackages = @()
if ($packageJson.dependencies) { $allPackages += $packageJson.dependencies.PSObject.Properties.Name }
if ($packageJson.devDependencies) { $allPackages += $packageJson.devDependencies.PSObject.Properties.Name }
$allPackages = $allPackages | Sort-Object -Unique

foreach ($pkg in $allPackages) {
    Write-Host "Updating npm package $pkg to latest stable"
    npm install "$pkg@latest"
    if ($LASTEXITCODE -ne 0) {
        throw "Failed to update npm package $pkg."
    }
}

3. Report remaining outdated packages:

npm outdated

Notes:

• Upgrade only direct dependencies and devDependencies by default.
• Do not auto-upgrade peerDependencies unless explicitly requested.
• Keep lockfile updates generated by npm commands.
• Ignore nested lockfiles that do not have a sibling package.json.

Before running npm install "$pkg@latest" for each package, inspect the current declaration in dependencies or devDependencies:

• If the current declaration uses comparator-range syntax (for example >=1.1.6 <2.0.0), skip that package and keep the declaration unchanged.
• Do not rewrite comparator ranges to caret, tilde, or exact-version declarations.
• Record skipped ranged npm packages and any recommended minimum-version bumps in both PR summary and final output.

Resolve Upgrade Fallout

Fix compatibility issues directly caused by dependency upgrades:

• API or signature changes
• type errors
• build/test failures
• lint failures (only when the user explicitly requests lint execution because this repo's lint script writes changes)

Pause and ask for collaborative direction when fixes become extensive, such as broad refactors or product behavior changes.

Validation (Required)

Run validation from repository root and treat failures as blocking unless the user explicitly accepts known failures.

1. Type-check:

npm run type-check

2. Build:

npm run build

3. Unit tests:

npm run test:unit -- --run

If unit tests are flaky or environment-limited, report exact failure output and keep the failure visible in final output and PR notes.

Commit, Push, and Pull Request

1. Commit dependency and compatibility changes on the upgrade branch.
2. Push branch:

git push -u origin $branchName

3. Create PR to main.

Preferred automated flow with GitHub CLI:

$prBodyPath = ".\upgrade-dependencies-pr-body.md"
$prBodyTemplate = @'
__TRELLO_CARD_URL__


## Summary
- <short summary of upgraded dependencies and compatibility fixes>
- <skipped ranged dependencies kept unchanged, plus recommended minimum-version bumps (if any)>

## Validation
- `npm run type-check`: <result>
- `npm run build`: <result>
- `npm run test:unit -- --run`: <result>

## Notes
- <known issues or limitations>
'@
$prBody = $prBodyTemplate -replace '__TRELLO_CARD_URL__', $TrelloCardUrl
Set-Content -Path $prBodyPath -Value $prBody -Encoding utf8

$prUrl = gh pr create --base main --head $branchName --title "chore: upgrade dependencies ($stamp)" --body-file $prBodyPath
if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' }
Write-Host "PR URL: $prUrl"

Manual fallback:

git push -u origin $branchName
Write-Host "Create PR: https://github.com/Relewise/relewise-demos-shop-vue/compare/main...$branchName?expand=1"
Write-Host "PR title: chore: upgrade dependencies ($stamp)"
Write-Host "PR body file: $prBodyPath"

Keep the Trello URL as the first line in PR description. Write the PR body file as UTF-8 to avoid symbol corruption in GitHub-rendered text.

Output Expectations

Provide a final summary with:

• Trello URL used
• branch name
• upgraded npm packages grouped by manifest path
• compatibility fixes applied
• results for each validation command
• skipped ranged dependencies kept unchanged, with recommended minimum-version bumps when applicable.
• pushed branch URL
• PR URL, or exact manual fallback instructions when automated PR creation is unavailable