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-ui-components. 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 web-components, 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.

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 root package-lock.json if no root package.json exists.

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

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

Validation (Required)

Run validation in packages/web-components and treat failures as blocking unless user accepts a known failure.

1. Build:

npm run build

2. Type definitions:

npm run build:types

3. Ensure Playwright browsers are available when required:

npx playwright install --with-deps

4. Tests:

npm run test

If INTEGRATION_TEST_DATASET_ID and INTEGRATION_TEST_API_KEY are unavailable, ask for them or clearly report test limitations 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 build` (in `packages/web-components`): <result>
- `npm run build:types` (in `packages/web-components`): <result>
- `npm run test` (in `packages/web-components`): <result>

## Notes
- <known issues or env 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-ui-components/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