# Release process

av-tools is licensed GPL-3.0-or-later. A publishable release is the exact
reviewed source tag, production ZIP/checksum, Corresponding Source and
third-party notices distributed together. The steps below fail closed where
practical.

## 1. Resolve legal/source identity

The repository already declares the application licence and immutable
third-party source identities. Before any distribution:

1. commit the reviewed GPL-3.0-or-later source;
2. create and verify annotated tag `v0.1.0` at that exact commit;
3. push the commit and tag to the canonical public repository;
4. assemble, review and publish corresponding source and exact external
   notices for both core packages and linked libraries;
5. keep the manifest/package metadata, `SOURCE.md`, ZIP and tag version aligned.

`SOURCE.md` pins FFmpeg, ffmpeg.wasm, x264 and LAME by full commit. Do not
describe the complete bundle as MIT-only.

## 2. Reproducible checks

With Node 22+ and the lockfile:

```sh
npm ci
npm run fixtures:verify
npm run check
npm run test:browser
```

`check` verifies manifest/vendor assets, types, lint/format, unit tests,
production build and `toolbox-check dist`. Browser tests must exercise ST, MT,
ST fallback, cancellation/recovery, nested paths and no runtime CDN request.
Record exact results in the release report.

## 3. Package

Normal packaging validates the root GPL version 3 text and matching
`GPL-3.0-or-later` package/manifest metadata:

```sh
npm run package:release
npm run source:package
```

The legacy development-only escape hatch is retained only for checking an
otherwise unlicensed temporary fixture:

```sh
npm run package:release -- --allow-unlicensed-development-smoke
```

Pass `--force` only to replace the exact same-version ZIP and sidecar. Output:

```text
release/av-tools-0.1.0.zip
release/av-tools-0.1.0.zip.sha256
release/ffmpeg-core-0.12.10-corresponding-source.tar.xz
release/ffmpeg-core-0.12.10-corresponding-source.tar.xz.sha256
```

Verify independently:

```sh
node scripts/checksum-release.mjs
(cd release && sha256sum -c ffmpeg-core-0.12.10-corresponding-source.tar.xz.sha256)
unzip -l release/av-tools-0.1.0.zip
tar -tJf release/ffmpeg-core-0.12.10-corresponding-source.tar.xz
```

The packager:

- rejects symlinks, special files, traversal, absolute/ambiguous/duplicate
  archive paths and credential-like files;
- rejects source maps and local absolute paths in text release files;
- requires entry, manifest, icon and every declared asset;
- requires root `CHANGELOG.md`, `SOURCE.md`, `THIRD_PARTY_NOTICES.md`,
  `LICENSES/`, `assets/` and `vendor/`;
- adds installed runtime npm licence files;
- sorts paths, stores files as mode 0644, uses 1980-01-01 00:00:00 UTC and
  produces deterministic ZIP32 bytes;
- excludes `node_modules`, test fixtures and source because it starts from
  `dist` plus an explicit legal/document list.

When used against a fixture without an application licence, the escape hatch adds
`DEVELOPMENT-ONLY-NOT-FOR-DISTRIBUTION.txt` inside the ZIP.

## 4. Portal assembly smoke

Use the clean reference clone beside av-tools, never the user's active Portal
worktree:

```sh
npm run portal:smoke -- \
  --artifact release/av-tools-0.1.0.zip \
  --allow-known-header-gap
```

The smoke harness clones the exact Portal HEAD to a temporary directory,
copies the ZIP there, writes a temporary one-app lock derived from
`release/toolbox.lock.example.json`, runs `npm ci`, tests, build and assembly,
then verifies the generated catalogue/release records and copied FFmpeg assets.
The temporary directory is removed unless `--keep-temp` is explicitly passed.
No machine-specific path is committed and no Portal worktree is changed.

Without `--allow-known-header-gap`, the clean immutable Portal reference's CSP
omission of `media-src blob:` is a failing deployment check. The override still
reports the gap and is only for testing archive assembly. See
`docs/PORTAL_REQUIREMENTS.md`.

The user's active `/mnt/DATA/git/toolbox-portal` worktree contains the narrow
directive as a local patch, but the smoke intentionally does not consume that
mutable worktree. Until the patch exists in a reviewed immutable Portal
revision, retain the clean-reference failure/override behavior above.

## 5. Publish only reviewed bytes

From a clean `v0.1.0` checkout, rerun all checks, create the ZIP once, verify
the sidecar, assemble that exact ZIP through Portal, and publish the immutable
ZIP, `.zip.sha256`, manifest, changelog, Corresponding Source and notices. Put
its exact lowercase digest/version/id/target in a reviewed Portal lock. Never
use mutable “latest” URLs or credentials in a lock.

The final report must state inspected commits, exact packages/build config,
capabilities, completed tested milestones, all check results, artifact paths,
Portal result, fixture provenance, licence status, headers, gaps, performance
and browser limits. A UI or command builder alone is not a completed milestone.