Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/release-runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This runbook covers desktop downloads and source archives on GitHub. The package

## release candidate

The candidate is **2.2.5**, with [release notes](releases/2.2.5.md). It improves graph image quality, hover stability, contextual help and Results navigation, and compacts the History toolbar. **2.2.4** remains the published release until this candidate passes review and native package checks. **2.2.1** was withdrawn; its tag remains fixed. Do not reuse either tag.
The candidate is **2.2.6**, with [release notes](releases/2.2.6.md). It fixes settings races, incomplete Steam coverage, history export/import and packaged history startup. **2.2.5** remains the published release until this candidate passes review and native package checks. **2.2.1** was withdrawn; its tag remains fixed. Do not reuse either tag.

Use the existing tag convention without a `v` prefix. Desktop installers start at `2.0.1`; `2.0.0` contains source archives only, and `1.0.2` contains the legacy Python executable. Publish only after authorization, resolved review findings and green CI on the pinned main commit.

Expand All @@ -27,8 +27,8 @@ Use the existing tag convention without a `v` prefix. Desktop installers start a
5. Confirm that the intended tag does not already exist locally or remotely. Never move an existing release tag.

```sh
git tag --list 2.2.5
git ls-remote --tags origin refs/tags/2.2.5
git tag --list 2.2.6
git ls-remote --tags origin refs/tags/2.2.6
gh release list --repo Microck/vapora
```

Expand All @@ -43,8 +43,8 @@ For a committed candidate, create an archive from its exact commit:
```sh
VAPORA_RELEASE_COMMIT=REPLACE_WITH_REVIEWED_MAIN_COMMIT

git archive --format=tar.gz --prefix=vapora-2.2.5/ \
--output=/tmp/vapora-2.2.5-source.tar.gz "$VAPORA_RELEASE_COMMIT"
git archive --format=tar.gz --prefix=vapora-2.2.6/ \
--output=/tmp/vapora-2.2.6-source.tar.gz "$VAPORA_RELEASE_COMMIT"
```

Extract it into a fresh directory and run:
Expand Down Expand Up @@ -81,21 +81,21 @@ Proceed only after explicit approval of the tag and notes, all findings are reso
4. Create an annotated tag at the pinned commit. Git is used here because Jujutsu does not create annotated tags:

```sh
git -c user.name=Microck -c [email protected] tag -a 2.2.5 \
"$VAPORA_RELEASE_COMMIT" -F docs/releases/2.2.5.md
git push origin refs/tags/2.2.5
git -c user.name=Microck -c [email protected] tag -a 2.2.6 \
"$VAPORA_RELEASE_COMMIT" -F docs/releases/2.2.6.md
git push origin refs/tags/2.2.6
```

5. Wait for core CI and Desktop packages CI triggered by the new tag to pass on the pinned commit. Download that tag run's verified artifacts into `/tmp/vapora-desktop-downloads`. Compute `SHA256SUMS.txt` from the exact EXE, AppImage and DMG bytes, using their basenames. Confirm there are four tested downloads: Windows x64 installer and portable EXEs, Linux x64 AppImage, and macOS ARM64 DMG. Publish a normal GitHub release with those files attached from the start:

```sh
gh release create 2.2.5 \
gh release create 2.2.6 \
/tmp/vapora-desktop-downloads/*/*.exe \
/tmp/vapora-desktop-downloads/*/*.AppImage \
/tmp/vapora-desktop-downloads/*/*.dmg \
/tmp/vapora-desktop-downloads/SHA256SUMS.txt \
--repo Microck/vapora --verify-tag \
--title 'vapora 2.2.5' --notes-file docs/releases/2.2.5.md --latest
--title 'vapora 2.2.6' --notes-file docs/releases/2.2.6.md --latest
```

6. GitHub also provides the source ZIP and tar.gz. Do not publish an empty source-only release while waiting for desktop builds. Do not attach the legacy executable, replace existing public assets with `--clobber`, publish to npm or mark the release as a prerelease.
Expand All @@ -105,9 +105,9 @@ Proceed only after explicit approval of the tag and notes, all findings are reso
1. Confirm the release is published, not a draft, and points to the intended tag:

```sh
gh release view 2.2.5 --repo Microck/vapora \
gh release view 2.2.6 --repo Microck/vapora \
--json url,tagName,isDraft,isPrerelease,publishedAt,assets
git ls-remote --tags origin refs/tags/2.2.5 'refs/tags/2.2.5^{}'
git ls-remote --tags origin refs/tags/2.2.6 'refs/tags/2.2.6^{}'
```

2. Verify the annotated tag's peeled commit equals `VAPORA_RELEASE_COMMIT`.
Expand Down
15 changes: 15 additions & 0 deletions docs/releases/2.2.6.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# vapora 2.2.6

This patch release fixes issues found during automated and hands-on QA.

- Exported history reports can be imported again. Original captures are retained, repeated imports are deduplicated, and rankings are recomputed from validated observations rather than trusting exported scores. Empty and cross-account reports are rejected.
- Cancelled or superseded settings loads no longer overwrite newer edits or close a reopened dialog. Explicit profile selection takes precedence over startup defaults, and stale estimates are invalidated.
- A damaged optional default profile now produces a recoverable diagnostic instead of leaving a healthy app marked disconnected. The original file is preserved.
- Incomplete Steam groups and games responses remain unavailable rather than appearing as public empty lists. Partial observed game IDs are retained without claiming complete coverage.
- The packaged history helper recovers when Chromium starts without an initial page, using a bounded five-second fallback. Other startup errors still propagate.
- CLI commands reject extra operands before storage or network side effects. Installation examples and documentation now follow the current app version.
- The documentation build uses patched Next.js 16.4.1. The published docs remain a static export without a Next.js server or image-optimization endpoint.

Native package tests use disposable local Steam and history fixtures. Fixture tests do not establish live-provider access or production-account behavior. History imports retain the documented 2 MB browser limit.

Windows downloads include an installer and a portable EXE. The portable app keeps data in `Vapora-data` beside the EXE and needs about 1 GB free in Windows TEMP, plus space for scan data. Move the EXE and data folder together. Downloads are unsigned and not notarized; verify them against `SHA256SUMS.txt`.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "vapora",
"version": "2.2.5",
"version": "2.2.6",
"private": true,
"description": "Explore public Steam friend networks",
"type": "module",
Expand Down
66 changes: 50 additions & 16 deletions test/storage.test.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
import assert from "node:assert/strict";
import { spawn } from "node:child_process";
import { once } from "node:events";
import { mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
import fs, { mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
import { syncBuiltinESMExports } from "node:module";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createInterface } from "node:readline";
import { test } from "node:test";
import { setTimeout as delay } from "node:timers/promises";
import { Cause, Effect, Layer, ManagedRuntime, Schema } from "effect";
Expand All @@ -16,23 +18,31 @@ import { key, player, scan, seed, steamFixture } from "./fixtures.js";
// This is a real Windows sharing lock: reads remain allowed, replacement is denied.
async function lockFile(path: string) {
const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command",
'$stream = [IO.File]::Open($env:VAPORA_LOCK_FILE, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::Read); [Console]::WriteLine("locked"); [Console]::ReadLine() | Out-Null; $stream.Dispose()',
'$ErrorActionPreference = "Stop"; $stream = $null; try { while ($null -ne ($command = [Console]::ReadLine())) { if ($command -eq "lock") { $stream = [IO.File]::Open($env:VAPORA_LOCK_FILE, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::Read); [Console]::WriteLine("locked") } elseif ($command -eq "release") { $stream.Dispose(); $stream = $null; [Console]::WriteLine("released") } else { throw "Unknown lock command" } } } finally { if ($null -ne $stream) { $stream.Dispose() } }',
], { env: { ...process.env, VAPORA_LOCK_FILE: path }, stdio: ["pipe", "pipe", "pipe"] });
const exited = once(child, "exit");
const replies = createInterface({ input: child.stdout });
let diagnostic = "";
child.stderr.on("data", (chunk: Buffer) => { diagnostic += chunk.toString(); });
const [ready] = await Promise.race([
once(child.stdout, "data"),
exited.then(() => { throw new Error(`Windows lock did not start: ${diagnostic}`); }),
]);
assert.equal(ready.toString().trim(), "locked");
return { release: async () => {
child.stdin.end("\n");
const [code] = await exited; assert.equal(code, 0, diagnostic);
const command = async (value: string, expected: string) => {
const response = Promise.race([
once(replies, "line"),
exited.then(() => { throw new Error(`Windows lock helper exited: ${diagnostic}`); }),
]);
child.stdin.write(`${value}\n`);
const [reply] = await response;
assert.equal(reply, expected);
};
// Reuse one PowerShell process: two cold starts can consume the test's fixed deadline.
// Each acknowledgement still follows acquiring or releasing the real OS sharing lock.
try { await command("lock", "locked"); } catch (error) { child.kill(); replies.close(); throw error; }
return { acquire: () => command("lock", "locked"), release: () => command("release", "released"), close: async () => {
child.stdin.end();
const [code] = await exited; replies.close(); assert.equal(code, 0, diagnostic);
} };
}

if (process.platform === "win32") test("Windows replacement retries a real sharing lock and preserves a checkpoint on a persistent lock", { timeout: 20000 }, async () => {
if (process.platform === "win32") test("Windows replacement retries a real sharing lock and preserves a checkpoint on a persistent lock", { timeout: 20000 }, async (t) => {
const root = await mkdtemp(join(tmpdir(), "vapora windows storage-"));
const runtime = ManagedRuntime.make(Storage.layer(root));
let lock: Awaited<ReturnType<typeof lockFile>> | undefined;
Expand All @@ -48,12 +58,30 @@ if (process.platform === "win32") test("Windows replacement retries a real shari
console.log(`Windows sharing lock reproduces ${failure.code} on replacement`); return true;
});
await rm(probe);
const saved = runtime.runPromise(store.save({ ...original, status: "cancelled" }));
const releasing = delay(150).then(() => lock?.release());
await Promise.all([saved, releasing]); lock = undefined;
const heldLock = lock;
const nativeRename = fs.rename;
let sharingFailures = 0;
// Observe the real OS call without synthesizing failures. Release only after
// save itself encounters the lock, never on a timer that could beat its first rename.
const observedRename = t.mock.method(fs, "rename", async (...args: Parameters<typeof rename>) => {
try { return await nativeRename(...args); }
catch (error) {
if (args[1] === checkpoint && ++sharingFailures === 1) await heldLock.release();
throw error;
}
});
syncBuiltinESMExports();
try {
await runtime.runPromise(store.save({ ...original, status: "cancelled" }));
assert.ok(sharingFailures >= 1);
assert.ok(observedRename.mock.callCount() >= 2);
} finally {
observedRename.mock.restore();
syncBuiltinESMExports();
}
assert.equal((await runtime.runPromise(store.read(original.id))).status, "cancelled");
const lastGood = await readFile(checkpoint);
lock = await lockFile(checkpoint);
await lock.acquire();
const blocked = await runtime.runPromise(store.save(original).pipe(Effect.result));
assert.equal(blocked._tag, "Failure");
if (blocked._tag !== "Failure") throw new Error("The persistent lock should block replacement");
Expand All @@ -62,7 +90,13 @@ if (process.platform === "win32") test("Windows replacement retries a real shari
assert.match(blocked.failure.message, /then retry/);
assert.deepEqual(await readFile(checkpoint), lastGood);
assert.ok(!(await readdir(join(root, "outputs", original.id))).some((name) => name.endsWith(".tmp")));
} finally { await lock?.release(); await runtime.dispose(); await rm(root, { recursive: true, force: true }); }
} finally {
try { await lock?.close(); }
finally {
try { await runtime.dispose(); }
finally { await rm(root, { recursive: true, force: true }); }
}
}
});

test("permanent filesystem errors retain their cause and leave the valid checkpoint intact", async () => {
Expand Down
14 changes: 7 additions & 7 deletions website/content/docs/getting-started/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,32 @@ Downloads are unsigned and not notarized. Compare the downloaded file's SHA-256
<Tab value="Windows">

```powershell title="PowerShell"
Get-FileHash .\vapora-2.2.5-win-x64.exe -Algorithm SHA256
Get-FileHash .\vapora-2.2.6-win-x64.exe -Algorithm SHA256
```

</Tab>
<Tab value="Linux">

```sh title="Terminal"
sha256sum vapora-2.2.5-linux-x86_64.AppImage
chmod +x vapora-2.2.5-linux-x86_64.AppImage
./vapora-2.2.5-linux-x86_64.AppImage
sha256sum vapora-2.2.6-linux-x64.AppImage
chmod +x vapora-2.2.6-linux-x64.AppImage
./vapora-2.2.6-linux-x64.AppImage
# Without FUSE
./vapora-2.2.5-linux-x86_64.AppImage --appimage-extract-and-run
./vapora-2.2.6-linux-x64.AppImage --appimage-extract-and-run

```

</Tab>
<Tab value="macOS">

```sh title="Terminal"
shasum -a 256 vapora-2.2.5-mac-arm64.dmg
shasum -a 256 vapora-2.2.6-mac-arm64.dmg
```

</Tab>
</Tabs>

Asset names above describe 2.2.5; use the filenames from your selected release.
Asset names above describe 2.2.6; use the filenames from your selected release.

## Browser and CLI from source

Expand Down
2 changes: 1 addition & 1 deletion website/content/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Vapora maps public Steam friend networks. Run it locally as a desktop app, brows

## Version and scope

- **Version:** 2.2.5, TypeScript + Effect.
- **Version:** 2.2.6, TypeScript + Effect.
- **Desktop:** includes the history runtime. Browser and CLI use a source checkout.
- **Screenshots:** local fixture profiles.
- **Original Python app:** preserved on [legacy](https://github.com/Microck/vapora/tree/legacy).
Expand Down
3 changes: 2 additions & 1 deletion website/content/docs/project/releases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,11 @@ title: "Releases and verification"
description: "Current downloads and preserved release evidence."
---

Download native assets from [GitHub Releases](https://github.com/Microck/vapora/releases/latest). Check `SHA256SUMS.txt` for the selected release. These docs describe 2.2.5; historical verification applies to the version and scope recorded in each report.
Download native assets from [GitHub Releases](https://github.com/Microck/vapora/releases/latest). Check `SHA256SUMS.txt` for the selected release. These docs describe 2.2.6; historical verification applies to the version and scope recorded in each report.

## Release notes

- [2.2.6](https://github.com/Microck/vapora/blob/main/docs/releases/2.2.6.md)
- [2.2.5](https://github.com/Microck/vapora/blob/main/docs/releases/2.2.5.md)
- [2.2.4](https://github.com/Microck/vapora/blob/main/docs/releases/2.2.4.md)
- [2.2.3](https://github.com/Microck/vapora/blob/main/docs/releases/2.2.3.md)
Expand Down
Loading
Loading