upgrade-dependencies

name

upgrade-dependencies

description

Upgrade npm dependencies in relewise-sdk-javascript with a safe branch and PR flow. Use when asked to refresh package versions, maintain npm dependencies, or prepare a dependency-upgrade PR for this repository. Require a Trello card URL, enforce clean-main preflight checks, create a monthly chore branch, upgrade direct dependencies across package manifests, run script-compatibility smoke checks (including client gen-api when relevant), resolve manageable compatibility fallout, run repo-aligned validation, then push and open a PR with the Trello link on the first line.

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.

Fixed Skip List

Skip these direct npm packages during routine dependency upgrades unless the user explicitly asks to upgrade them:

• swagger-typescript-api: keep the current declaration unchanged because major upgrades can rewrite generated SDK models and require script/template migration outside a routine dependency refresh.

Record fixed-skip packages in the PR summary and final output.

Discover npm Manifests

Discover package manifests under packages/, excluding node_modules.

Preferred command:

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

Treat each discovered manifest directory as an upgrade target.

npm Upgrade Workflow

For each discovered manifest directory:

1. Run the upgrade loop from repository root:

foreach ($manifestPath in $manifestPaths) {
    $packageDir = Split-Path -Parent $manifestPath
    Push-Location $packageDir
    try {
        npm install

        $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 in $packageDir"
            npm install "$pkg@latest"
            if ($LASTEXITCODE -ne 0) {
                throw "Failed to update npm package $pkg in $packageDir."
            }
        }

        npm outdated
    } finally {
        Pop-Location
    }
}

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 package is listed in the fixed skip list, skip that package and keep the declaration unchanged.
• 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 fixed-skip and ranged npm packages, plus 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 behavior changes.

Script Compatibility Smoke Checks (Required Before First Commit)

Dependency upgrades can break npm script contracts even when build/tests pass. Run these checks before creating the first commit on the branch:

1. If packages/client/package.json changed and includes script/tooling updates, run:

npm --prefix .\packages\client run gen-api

2. Treat failures as blocking and fix before commit/push.
3. If generated drift is not intended for this dependency PR, restore generated files after the smoke check:

git restore .\packages\client\src\models\data-contracts.ts

4. Record whether gen-api was run and passed in the PR validation section.

Validation (Required)

Run validation per touched package and treat failures as blocking unless the user explicitly accepts known failures.

For packages/client:

# Required when client script/tooling dependencies changed:
npm --prefix .\packages\client run gen-api
# Then standard validation:
npm --prefix .\packages\client run build
npm --prefix .\packages\client test

For packages/integrations:

npm --prefix .\packages\integrations run build
npm --prefix .\packages\integrations test

For packages/code-analyzer:

npm --prefix .\packages\code-analyzer run lint

Integration tests are conditional:

• Run when API behavior/contracts are changed and required secrets are available.
• If running both integration suites, run integrations package first:

npm --prefix .\packages\integrations run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com
npm --prefix .\packages\client run integration-test --DATASET_ID=... --API_KEY=... --SERVER_URL=https://api.relewise.com

• If secrets are unavailable, report integration tests as not run.

Commit, Push, and Pull Request

1. Confirm required script compatibility smoke checks passed (including packages/client gen-api when relevant).
2. Commit dependency and compatibility changes on the upgrade branch.
3. Push branch:

git push -u origin $branchName

4. 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 fixed-skip/ranged dependencies kept unchanged, plus recommended minimum-version bumps (if any)>

## Validation
- `packages/client`: <build/test result or not touched>
- `packages/integrations`: <build/test result or not touched>
- `packages/code-analyzer`: <lint result or not touched>
- `integration tests`: <result or not run>

## 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-sdk-javascript/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 fixed-skip/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