# Tools

## simulator/sim.sh

Manage a [Remote-Core Simulator](https://github.com/unfoldedcircle/core-simulator) container
for local development and tests, so no physical device is needed.

Use it through the npm scripts: `sim:up`, `sim:reset`, `sim:down`, and `dev:sim` to run the
dev server against it.

```shell
npm run sim:up && npm run dev:sim   # login PIN 1234
```

Overrides: `SIM_IMAGE`, `SIM_PORT`, `SIM_MODEL` (`UCR3`|`UCR2`), `SIM_NAME`.

## create-custom-install.sh

Create a custom user installation package for the Remote Two.

- Uses the [release.json](release.json) template for the installation package.
- Version is determined from git with [git-version.sh](git-version.sh).

Install custom user version:

```shell
curl "http://$IP/api/system/install/web_configurator?void_warranty=$MAGIC_WORD" \
  --user "web-configurator:$PIN" \
  --form "file=@uc-web-configurator-$VERSION.tar.gz"
```

## git-tag.py

Git tag release script to simplify creating git tags with changelog since last release.

## git-version.sh

Helper script to determine [SemVer](https://semver.org/) compatible version string from git repository.

This script is called from the build process and requires `git-semver`.

## transform-license-checker.js

Simple helper script to create the third-party license overview page. Its output is
committed as [public/licenses.md](../public/licenses.md), served with the app and shown in
Settings → General → About → Licenses.

**Re-run it whenever dependencies change**, so the shipped attribution matches what is built.
It reads `templates/` and writes `patches/` relative to the cwd, so run it from `tools/`:

```shell
cd tools && node transform-license-checker.js ../public/licenses.md
```

It runs `license-checker` itself (from the repository root, which is where dependencies
resolve from).

```
Usage: node transform-license-checker.js <output.md> [options]
  --include-dev            also attribute devDependencies (default: runtime only)
  --input <licenses.json>  use an existing license-checker JSON instead of running it
  --app-license <mode>     proprietary|gpl — the notice for the app itself
                           (default: proprietary when package.json is UNLICENSED)
```

**The notice for the Web Configurator itself** is chosen from `package.json`: `UNLICENSED`
selects `templates/app-license-proprietary.md`, anything else
`templates/app-license-gpl.md`. Two builds ship — the older GPL v3 snapshots and, since the
re-licensing, proprietary ones — and a proprietary build must not claim to be GPL in its own
About dialog.

Pass `--app-license` to override, which is what you want when regenerating an old snapshot's
page from a newer checkout. Both notices are plain text files; edit them there, not in the
script.

**Scope: runtime dependencies only, by default** — the page describes what is shipped, and
`--production` narrows the installed tree from 504 packages to the 149 in the runtime closure
(1.2 MB → 0.5 MB). Pass `--include-dev` to attribute devDependencies as well; the page's
opening sentence follows the flag, so it never claims a scope it does not have.

`--input` transforms a `license-checker --json` file you already have, for tests and for
re-running the transform without re-resolving the tree. It does not change what `--include-dev`
means: the flag always selects the scope the page claims, so pass it when the input file holds a
dev-inclusive tree.

The script needs `gh` (authenticated) and `curl` for packages that ship no license file: it
resolves those from GitHub and caches the result in [patches/](patches). The cache is
committed, so a normal re-run is offline and reproducible; network access is only needed for
packages that are new or newly missing a license.

It **exits non-zero** if any dependency ends up without license text, and names them — an
incomplete attribution page must fail loudly rather than ship silently truncated. To fix a
reported package, add its license text as `patches/<name>@<version>/LICENSE` and re-run.
Each patch directory also carries a `SOURCE.md` recording where the text came from.

`templates/licenses-footer.md` hand-attributes the components `license-checker` cannot see —
the bundled webfonts, including Material Symbols Sharp. Keep it in step with what the build actually bundles.
Everything in the templates is **shown to end users** in the About dialog, so keep maintainer
notes here rather than in the templates.

The repository's own package is skipped: it is not a third-party dependency.

Note that `license-checker` reports what is actually installed, including the platform-specific
optional dependencies (`@esbuild/darwin-arm64`, `@rollup/rollup-darwin-arm64`, …). Regenerating
on a different OS or architecture therefore swaps those entries. Regenerate on the platform the
release is built from, and expect that diff when someone regenerates elsewhere. With the default
runtime-only scope this barely matters — those are build-time packages — but it does with
`--include-dev`.

Those platform packages ship no license file, so [patches/](patches) carries them for both
macOS (`darwin-arm64`) and Linux (`linux-x64`, `linux-x64-gnu`, `linux-x64-musl`) — the two
platforms this project builds on. Regenerating on a third platform will report its variants as
missing; add patches for them the same way. This matters because the GitHub fallback needs an
authenticated `gh`, which CI does not have.