APPLY-0.14.2.md

Apply v0.14.2 source layout checkpoint r6

This cumulative update applies to the supplied v0.14.1 checkout or the earlier v0.14.2 GUI/layout checkpoints. Stop the running GUI with Ctrl+C first. Close any editor that might write source files during application.

Download the incremental ZIP and its SHA256SUMS file to the parent of the audio-bitsqueezer checkout. From that parent directory on Linux/macOS:

(
set -eu
sha256sum -c audio-bitsqueezer-v0.14.2-layout-r6-SHA256SUMS.txt
bitsqueezer_sorter=$(mktemp)
trap 'rm -f -- "$bitsqueezer_sorter"' EXIT
unzip -p audio-bitsqueezer-v0.14.2-layout-r6-incremental.zip \
  audio-bitsqueezer/scripts/sort-layout.py > "$bitsqueezer_sorter"
python3 "$bitsqueezer_sorter" --root audio-bitsqueezer \
  --archive audio-bitsqueezer-v0.14.2-layout-r6-incremental.zip --apply
)
cd audio-bitsqueezer
bash run.sh gui

On macOS without sha256sum, use shasum -a 256 -c instead. Omit --apply for a dry run. The temporary bootstrap file is removed; the installed sorter lives under scripts/. This archive-based application protects old CLI files before replacing them and moves obsolete root components into a recovery backup.

If you have already extracted the whole ZIP over your checkout, complete the root cleanup from the project directory with:

python3 scripts/sort-layout.py --apply

Files overwritten by manual extraction cannot be recovered by the sorter; archive-based application is the recommended route.

Windows application

From PowerShell in the parent of the checkout, replace the Python command with py -3 if that is how Python is installed on your system:

$zip = 'audio-bitsqueezer-v0.14.2-layout-r6-incremental.zip'
$expected = ((Get-Content 'audio-bitsqueezer-v0.14.2-layout-r6-SHA256SUMS.txt') -split '\s+')[0]
if ((Get-FileHash $zip -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) { throw 'Checksum mismatch' }
$temp = Join-Path ([IO.Path]::GetTempPath()) ([IO.Path]::GetRandomFileName())
try {
    Expand-Archive -LiteralPath $zip -DestinationPath $temp
    python (Join-Path $temp 'audio-bitsqueezer/scripts/sort-layout.py') --root audio-bitsqueezer --archive $zip --apply
    if ($LASTEXITCODE -ne 0) { throw 'Update failed' }
} finally {
    Remove-Item -LiteralPath $temp -Recurse -Force -ErrorAction SilentlyContinue
}
Set-Location audio-bitsqueezer
.\run.cmd gui

Recovery and review

The sorter prints a build/layout-backups/<unique-id>/originals/ directory. It contains every replaced/retired original, preserving local edits. Its sibling manifest.json records backed-up and newly created paths. Compare any locally modified source with the corresponding new component before committing. Extra local checkpoint notes are also appended to docs/CHECKPOINT-0.14.2.md.

A failure while applying file changes restores the previous files and removes new update files; the journal records rolled-back. A forced process termination or machine shutdown can interrupt that rollback: the recovery copies and journal remain available. Restore needed files from originals/ to the corresponding project-relative paths. Do not delete the backup until local review is complete.

User audio, existing outputs, local configuration, .venv and original C64 assets are outside the update payload. The sorter never performs Git operations. Repeated application is a no-op once the target content/layout matches.

Verify and publish from your checkout

bash install.sh
.venv/bin/python -m pip install -r requirements/dev.txt
.venv/bin/python -m unittest discover -s tests -v
node tests/gui-state.cjs
git status --short
git diff --check

Try the GUI source browser/drop areas, output-folder dialog and a render. After review, the existing local release helper still performs commit, archive, tag, push and GitHub release for VERSION 0.14.2:

bash scripts/release.sh

Do not move the already published v0.14.1 tag. See LAYOUT.md, TESTING.md and RELEASE_0.14.2.md.