SDK Upstream Sync

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

Step	What happens
1. Fetch	Gets the latest upstream commit SHA — exits cleanly if already in sync
2. Extract contracts	Reads exports, methods, and module structure from both sides via GitHub API
3. Diff contracts	Detects removed exports/methods as breaking, new ones as safe additions
4. Check thresholds	Auto-applies if: ≤ 20 files changed, ≤ 600 LOC, zero breaking changes
5. Apply or report	Patches your fork, or generates `sync/report.md` for manual review

Safety thresholds

Condition	Action
≤ 20 files, ≤ 600 LOC, no breaking changes	Auto-apply patch
> 20 files changed	Generate investigation report only
> 600 LOC changed	Generate investigation report only
Any breaking change detected	Generate 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.

Overview

Free Web Tools

Developer Tools

npm Packages

Python Packages

SDK Upstream Sync

GitHub

npm

Install

Setup

Usage

How it works

Safety thresholds

Automate with GitHub Actions

GitHub

npm

​Install

​Setup

​Usage

​How it works

​Safety thresholds

​Automate with GitHub Actions

Install

Setup

Usage

How it works

Safety thresholds

Automate with GitHub Actions