SugarReleases
Phar self-update engine — verify before the swap, one-shot rollback
The self-update machinery a phar-shipped SugarCraft app needs, extracted from candy-code so every app rides the same laws: pick the right release from a shared GitHub release stream, verify the bytes BEFORE the rename, keep a one-shot .old undo copy, and tell the user at launch when a newer release exists. Everything app-specific — repository, tag prefix, asset names, pinned public key, Composer package, display name — is one ReleaseSource value; the host parses its own argv and supplies its running version. First-party — there is no upstream Go port.
Install
composer require sugarcraft/sugar-releases
Quickstart
use SugarCraft\Releases\ReleaseSource;
use SugarCraft\Releases\SelfUpdate;
use SugarCraft\Releases\UpdateCheck;
use SugarCraft\Releases\UpdateOptions;
$source = ReleaseSource::new('acme/tools', 'widget') // tags widget/v1.2.3, asset widget.phar
->withComposerPackage('acme/widget')
->withPublicKey($base64Ed25519PublicKey); // '' = keyless state
// `widget self-update --check` / bare / --rollback / --channel=latest
$exit = SelfUpdate::new($source)->run(UpdateOptions::new()->withCheck(), $currentVersion);
// at launch: refresh a 24 h cache over the event loop, paint the PREVIOUS check's answer
$check = UpdateCheck::new($source, $stateDir, $currentVersion);
$check->refreshIfStale();
echo $check->cachedNotice() ?? '';
Exit codes: 0 up to date / swapped / rolled back; 1 refusals and failures (and --check finding an update); 2 usage errors. Report lines go to STDERR through a translator seam.
The laws
--allow-unsigned never skips the sha256 gate.<app>/v* release carrying both assets, ordered numerically. Dev: the rolling <app>/dev release judged by commit identity against a dev-<sha> stamp — indecidable is a refusal, never a guess..old before the swap; --rollback renames it back, consuming it, with no network. The live file's mode is carried onto both halves..new and a detached helper retries the rename until the process exits, logging to .swap.log. The helper source is a fixed literal; paths travel as argv data.Use it for
- Phar apps in a shared release stream — per-app tag prefixes keep one tool's releases from being confused with a sibling's.
- Adopting the same laws in a second app — candy-code is the reference consumer, candy-top the second.
Source
API
| Class | Method | Description |
|---|---|---|
| ReleaseSource | static new(string $repo, string $app): self | Where an app publishes and what its artifacts are called; derives tag prefix <app>/, asset <app>.phar and the sidecar/signature names |
| ReleaseSource | withTagPrefix() / withPharAsset() / withPublicKey() / withComposerPackage() / withUserAgent() | Immutable overrides; an empty public key is the keyless state |
| SelfUpdate | static new(ReleaseSource $source): self / run(UpdateOptions $options, string $currentVersion): int | The verb: verify-before-rename swap, --check, --rollback, channel selection; returns the exit code |
| SelfUpdate | withHttp() / withReleasesUrl() / withPharPath() / withPublicKey() / withWindows() / withErrorStream() / withTranslator() / withSwapLauncher() | Seams for the host and the suite; every one defaults to the production behavior |
| SelfUpdate | composerRefusal(?string $rootPackage = null): string | The loud composer-mode refusal naming the command that fits the install shape |
| UpdateOptions | new() / withCheck() / withRollback() / withAllowUnsigned() / withChannel() / withOperands() / validate() | The parsed verb flags, free of any CLI framework; validate() names the first usage violation as a translation key |
| UpdateCheck | static new(ReleaseSource $source, string $stateDir, string $currentVersion): self / refreshIfStale(): void / cachedNotice(): ?string | The launch-time notice: async 24 h refresh into <stateDir>/update-check.json (0600), notice read from the previous check's cache |
| ReleaseSelector | for(ReleaseSource $source) / selectRelease() / selectDevRelease() / devDecision() / parseSidecar() / sidecarName() | Pure selection over a decoded GitHub release list, independent of transport |
| Version | parse() / compare() / isComparable() / isDev() / devShaOf() | Strict v?X.Y.Z ordering (null = cannot order) and the dev-<sha> classifier |
| Signature | verifyDetached(string $payload, string $signatureBody, string $publicKeyBase64): bool | Ed25519 detached verification; every malformed shape answers false |
| WindowsSwap | launch(int $parentPid, string $new, string $phar, ?\Closure $spawnSpec = null, ?array $env = null): bool / launchCommand() | Spawns the detached rename-retry helper (60 s budget, 200 ms cadence) |