migration-helper-scripts

CLI tooling for Storyblok migration audits and visual JSON diffing.

Install

Recommended (install script):

curl -fsSL https://raw.githubusercontent.com/ef-global/migration-helper-scripts/master/scripts/install.sh | sh

Pin an exact version:

curl -fsSL https://raw.githubusercontent.com/ef-global/migration-helper-scripts/master/scripts/install.sh | \
  MIGRATION_HELPER_VERSION=1.1.0 sh

Manual install is also supported from GitHub Releases assets.

Install/distribution details are documented in: docs/install-and-distribution.md

CLI Commands

Default interactive mode:

migration-helper

This opens a guided CLI that:

• lets you choose audit or diff
• discovers sb-mig runs from sbmig/migrations
• lets you select a migration run instead of raw files
• auto-wires the correct artifacts for audit or diff

Interactive command-specific entrypoints:

migration-helper audit
migration-helper diff

Path-based non-interactive usage is still supported:

During development:

bun run src/cli.ts
bun run src/cli.ts audit
bun run src/cli.ts diff
bun run src/cli.ts diff before.json after.json --serve --port 4717

Package bin commands:

migration-helper
migration-helper audit
migration-helper diff
migration-helper diff before.json after.json --serve --port 4717

Backwards-compatible script shortcut:

bun run migration-diff before.json after.json --serve --port 4717

Build Single Executable

Build for current host platform:

bun run build

Build all supported targets:

bun run build:all

Produced binaries are written to bin/:

• migration-helper-darwin-arm64
• migration-helper-darwin-x64
• migration-helper-linux-x64
• migration-helper-linux-arm64
• migration-helper-windows-x64.exe

Release Strategy

This repository now follows the same Changesets-driven flow as chaperone.

Target branch: master

1) Feature PRs

For user-facing/code changes, include a changeset:

bun run changeset

The PR check (Changeset Check) enforces this for changes under src/, build.ts, or package.json.

2) Version PRs

On pushes to master, Changeset Version PR runs and opens/updates a version PR using changesets/action.

3) Binary Releases

After version bumps land on master, Release Binaries:

• reads package.json version,
• creates v<version> tag if missing,
• builds executables for all supported targets,
• generates SHA256SUMS.txt,
• publishes assets to GitHub Releases.

Release assets include:

• migration-helper-darwin-arm64
• migration-helper-darwin-x64
• migration-helper-linux-x64
• migration-helper-linux-arm64
• migration-helper-windows-x64.exe
• SHA256SUMS.txt

Workflows:

• .github/workflows/changeset-check.yml
• .github/workflows/changeset-version-pr.yml
• .github/workflows/release-binaries.yml