npm package: @runebreak/patch-builder
Description: Utilities for building RGX patch artifacts (PatchSet generation, md5 index, throttled sampleroot server, and vendored librsync CLI)
Author: rgx-org
Latest version: 0.1.5

## RGX Patch Builder Utilities

This repo contains a small set of Node.js scripts used to build and serve patch artifacts.

Published CLI commands:
- `patch-builder` — generates PatchSet entries (patch deltas + download/delete ops) for a patch root.
- `update-md5filejson` — generates or updates a `files.json` md5/size index for a directory.
- `librsync-cli` — minimal CLI wrapper over `@runebreak/librsync-bundled`.
- `throttle-server` — throttled static server with Range support.

## Setup

```zsh
npm install
```

## Librsync

`scripts/librsync-cli.ts` expects `@runebreak/librsync-bundled` to be installed.

## Usage

### Downstream type imports

When installed as a dependency, patch plan types are exported from the package:

```ts
import type { PatchPlanFile, PatchSet } from '@runebreak/patch-builder';
// or
import type { PatchPlanFile, PatchSet } from '@runebreak/patch-builder/patch-type';
```

### Downstream CLI usage

Install the package:

```zsh
npm i @runebreak/patch-builder
```

Run the CLI directly:

```zsh
npx patch-builder ./patch-root
```

If you specifically want `npm run patch-builder` in the consuming project, add a script there:

```json
{
  "scripts": {
    "patch-builder": "patch-builder"
  }
}
```

Then run:

```zsh
npm run patch-builder -- ./patch-root
```

### Build a PatchSet for a patch root

Patch root layout expected by `patch-builder`:
- `<root>/files/` — *user supplied* new/current client files
- `<root>/files.json` — *generated* previous index (will be updated)
- `<root>/_archive/` — *generated* basis/source files for delta/patch generation
- `<root>/.patchedfiles` — *user supplied* gitignore-style allowlist patterns (relative, posix-style) to consider for delta/patch generation. generated patches then go in `/patches/` and the source of the generation goes in `_archive`
- `<root>/.config` — *user supplied* gitignore-like patterns identifying config file paths under `files/`. You should place items in here that you want to be able to 'force update' as well as 'update defaults'.
- `<root>/_defaults/` — *generated* materialized default config store (merged over time); default config baselines keep `.default` in the filename
- `<root>/patches/` — generated delta/patch files and config deltas

```zsh
patch-builder /path/to/patch-root
```

#### Caution
Do not add an already distributed file to .patchedfiles and .config files after the fact. If you want to now patch it, it's best to delete it, build the updated patchset, re-add it, generate the updated patchset. Then you can do patching operations normally. However doing this with config files will delete the config file from the local side, so it's best to know ahead of time what files you want to manage default configs for.

### Throttled sampleroot server (for testing)

Serve the included sampleroot with throttling:

```zsh
throttle-server ./sampleroot 8069 200
```

There is also a VS Code workspace task to run this (see `Throttle serve sampleroot (port 8069)`).


### Notes/Credits
Partially built via GPT-5(.3-Codex).