Skip to main content
sdk-upstream-sync solves fork drift. If you maintain a fork of any npm or GitHub SDK, upstream ships changes, your fork drifts, and you find out when something breaks in production. This tool diffs API contracts, auto-applies safe changes, and generates an investigation report for anything risky.

GitHub

nometria/sdk-upstream-sync

npm

@nometria-ai/sdk-upstream-sync

​
Install

npm install --save-dev @nometria-ai/sdk-upstream-sync

​
Setup

# Required
export UPSTREAM_REPO=original-org/javascript-sdk
export GITHUB_TOKEN=ghp_...           # avoids rate limits

# Optional
export UPSTREAM_BRANCH=main           # default: main
export MAX_FILES=20                   # auto-apply threshold
export MAX_LOC=600                    # auto-apply threshold

​
Usage

# Run sync from your fork directory
npx sdk-upstream-sync

# Add to package.json scripts
{
  "scripts": {
    "sync": "UPSTREAM_REPO=original-org/sdk npx sdk-upstream-sync"
  }
}

​
How it works

StepWhat happens
1. FetchGets the latest upstream commit SHA — exits cleanly if already in sync
2. Extract contractsReads exports, methods, and module structure from both sides via GitHub API
3. Diff contractsDetects removed exports/methods as breaking, new ones as safe additions
4. Check thresholdsAuto-applies if: ≤ 20 files changed, ≤ 600 LOC, zero breaking changes
5. Apply or reportPatches your fork, or generates sync/report.md for manual review

​
Safety thresholds

ConditionAction
≤ 20 files, ≤ 600 LOC, no breaking changesAuto-apply patch
> 20 files changedGenerate investigation report only
> 600 LOC changedGenerate investigation report only
Any breaking change detectedGenerate investigation report only

​
Automate with GitHub Actions

# .github/workflows/sdk-sync.yml
name: Upstream SDK sync
on:
  schedule:
    - cron: '0 9 * * 1'   # Every Monday at 9am
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install --save-dev @nometria-ai/sdk-upstream-sync
      - run: npx sdk-upstream-sync
        env:
          UPSTREAM_REPO: original-org/javascript-sdk
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
This tool was originally built to maintain Nometria’s fork of the Base44 JavaScript SDK and keep it in sync with upstream API changes automatically.