mixdog 1.1.0 → 1.1.2

package/scripts/mobile-release.mjs

@@ -0,0 +1,210 @@
+// The mobile (Android APK + iOS TestFlight) side of Deploy.
+//
+// plan: whether this deploy ships a mobile release and under which version.
+//   A release is due when anything the app binaries are built from changed
+//   since the newest mobile-v* tag (input `auto`), always (`force`), or never
+//   (`skip`). The version is the next patch (or minor) of that tag. The tag
+//   itself is created by the Android release, so a failed mobile release
+//   leaves no tag and the next deploy plans the same version again.
+//   CLI: MOBILE_MODE=auto|force|skip MOBILE_BUMP=patch|minor node scripts/mobile-release.mjs plan
+//   appends mobile_release / mobile_version / mobile_tag to $GITHUB_OUTPUT.
+//
+// link: the Android release the relay's /app page links — the newest
+//   published (non-draft) mobile-v* release whose APK actually downloads, or
+//   the releases list when there is none. `--require=<tag>` instead fails
+//   unless that exact release is the one that resolves (post-publish check).
+//   CLI: GITHUB_REPOSITORY=o/r GH_TOKEN=… node scripts/mobile-release.mjs link [--require=mobile-vX.Y.Z]
+//   appends url / tag to $GITHUB_OUTPUT.
+import { appendFileSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { pathToFileURL } from 'node:url';
+
+const TAG_RE = /^mobile-v(\d+)\.(\d+)\.(\d+)$/;
+
+// Everything the APK and the iOS build are made from. The app bundles one
+// desktop module (apps/mobile/src/main.ts imports shared/native-app.ts, which
+// imports nothing). Relay changes are not listed: the relay deploys on its
+// own with every release and the app binary does not embed it.
+export const MOBILE_RELEASE_PATHS = [
+  'apps/mobile',
+  ':(exclude,glob)apps/mobile/**/*.md',
+  'apps/desktop/src/shared/native-app.ts',
+  '.github/workflows/mobile-android.yml',
+  '.github/workflows/mobile-ios.yml',
+];
+
+export function parseMobileTag(tag) {
+  const match = TAG_RE.exec(String(tag ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+export function compareMobileTags(left, right) {
+  const a = parseMobileTag(left);
+  const b = parseMobileTag(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return 0;
+}
+
+export function latestMobileTag(tags) {
+  const valid = tags.map((tag) => String(tag).trim()).filter((tag) => parseMobileTag(tag));
+  return valid.sort(compareMobileTags).at(-1) ?? null;
+}
+
+export function nextMobileVersion(tag, bump = 'patch') {
+  const parts = parseMobileTag(tag);
+  if (!parts) throw new Error(`invalid mobile release tag: ${tag}`);
+  const [major, minor, patch] = parts;
+  if (bump === 'minor') return `${major}.${minor + 1}.0`;
+  if (bump === 'patch') return `${major}.${minor}.${patch + 1}`;
+  throw new Error(`invalid mobile version bump: ${bump}`);
+}
+
+/** `changedSince(tag)` answers whether a mobile path changed between tag and HEAD. */
+export function planMobileRelease({ mode = 'auto', bump = 'patch', tags, changedSince }) {
+  if (!['auto', 'force', 'skip'].includes(mode)) throw new Error(`invalid mobile mode: ${mode}`);
+  if (!['patch', 'minor'].includes(bump)) throw new Error(`invalid mobile version bump: ${bump}`);
+  const base = latestMobileTag(tags);
+  const none = (reason) => ({ release: false, version: '', tag: '', base: base ?? '', reason });
+  if (mode === 'skip') return none('skipped by the mobile input');
+  // Versions continue from the newest tag; without one there is nothing to
+  // continue from, and guessing could overwrite a published release.
+  if (!base) return none('no mobile-v* tag yet: push the first one by hand');
+  const changed = changedSince(base);
+  if (mode === 'auto' && !changed) return none(`no mobile source changed since ${base}`);
+  const version = nextMobileVersion(base, bump);
+  return {
+    release: true,
+    version,
+    tag: `mobile-v${version}`,
+    base,
+    reason: changed ? `mobile sources changed since ${base}` : 'forced by the mobile input',
+  };
+}
+
+export function mobilePathsChangedSince(tag, { cwd } = {}) {
+  const result = spawnSync('git', ['diff', '--quiet', `${tag}..HEAD`, '--', ...MOBILE_RELEASE_PATHS], { cwd });
+  if (result.status === 0) return false;
+  if (result.status === 1) return true;
+  throw new Error(`git diff failed for ${tag}: ${result.stderr?.toString() || result.status}`);
+}
+
+/** Published mobile releases that carry an APK, newest version first. */
+export function androidReleaseCandidates(releases) {
+  return releases
+    .filter((release) => !release.draft && parseMobileTag(release.tag_name))
+    .map((release) => ({
+      tag: release.tag_name,
+      url: release.html_url,
+      apkUrl: release.assets?.find((asset) => /\.apk$/i.test(asset.name || ''))?.browser_download_url,
+    }))
+    .filter((release) => release.url && release.apkUrl)
+    .sort((left, right) => compareMobileTags(right.tag, left.tag));
+}
+
+async function listReleases(repository, { token, fetchImpl }) {
+  const releases = [];
+  for (let page = 1; ; page += 1) {
+    const response = await fetchImpl(`https://api.github.com/repos/${repository}/releases?per_page=100&page=${page}`, {
+      headers: {
+        Accept: 'application/vnd.github+json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+    });
+    if (!response.ok) throw new Error(`listing releases failed: HTTP ${response.status}`);
+    const batch = await response.json();
+    releases.push(...batch);
+    if (batch.length < 100) return releases;
+  }
+}
+
+async function downloadable(url, { fetchImpl, attempts, delayMs }) {
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      const response = await fetchImpl(url, { method: 'HEAD', redirect: 'follow' });
+      if (response.ok) return true;
+    } catch {
+      /* retried below */
+    }
+    if (attempt < attempts) await delay(delayMs);
+  }
+  return false;
+}
+
+export async function resolveAndroidLink({
+  repository,
+  token = '',
+  requiredTag = '',
+  fetchImpl = fetch,
+  attempts = 3,
+  delayMs = 5000,
+}) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository || '')) {
+    throw new Error(`invalid repository: ${repository}`);
+  }
+  if (requiredTag && !parseMobileTag(requiredTag)) throw new Error(`invalid mobile release tag: ${requiredTag}`);
+  const candidates = androidReleaseCandidates(await listReleases(repository, { token, fetchImpl }));
+  for (const candidate of requiredTag ? candidates.filter((item) => item.tag === requiredTag) : candidates) {
+    if (await downloadable(candidate.apkUrl, { fetchImpl, attempts, delayMs })) {
+      return { url: candidate.url, tag: candidate.tag };
+    }
+    if (!requiredTag) console.warn(`::warning::${candidate.tag} APK is not downloadable; trying an older release.`);
+  }
+  if (requiredTag) throw new Error(`${requiredTag} is not a published release with a downloadable APK`);
+  return { url: `https://github.com/${repository}/releases`, tag: '' };
+}
+
+function writeOutputs(values) {
+  if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(
+      process.env.GITHUB_OUTPUT,
+      Object.entries(values)
+        .map(([key, value]) => `${key}=${value}\n`)
+        .join('')
+    );
+  }
+  console.log(JSON.stringify(values, null, 2));
+}
+
+async function main([command, ...args]) {
+  if (command === 'plan') {
+    const tags = execFileSync('git', ['tag', '--list', 'mobile-v*'], { encoding: 'utf8' }).split(/\r?\n/);
+    const plan = planMobileRelease({
+      mode: process.env.MOBILE_MODE || 'auto',
+      bump: process.env.MOBILE_BUMP || 'patch',
+      tags,
+      changedSince: (tag) => mobilePathsChangedSince(tag),
+    });
+    writeOutputs({
+      mobile_release: String(plan.release),
+      mobile_version: plan.version,
+      mobile_tag: plan.tag,
+      mobile_base: plan.base,
+      mobile_reason: plan.reason,
+    });
+    return;
+  }
+  if (command === 'link') {
+    const requiredTag = args.find((arg) => arg.startsWith('--require='))?.slice('--require='.length) || '';
+    writeOutputs(
+      await resolveAndroidLink({
+        repository: process.env.GITHUB_REPOSITORY,
+        token: process.env.GH_TOKEN || '',
+        requiredTag,
+        // Right after publishing, the asset CDN can lag a few seconds.
+        attempts: requiredTag ? 6 : 3,
+      })
+    );
+    return;
+  }
+  throw new Error('usage: node scripts/mobile-release.mjs plan | link [--require=mobile-vX.Y.Z]');
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(`::error::${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/post-release-check.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// Final job of Deploy: verify the published app release end to end.
+//
+//   - GitHub Latest is the new app tag
+//   - the release asset set matches the asset contract (release.yml
+//     "Verify complete hidden release"), and every url/sha512 listed in
+//     latest.yml and latest-mac.yml matches the uploaded assets
+//   - mixdog@<version> is resolvable on npm (retried while it propagates)
+//   - production relay /app answers 200 and links an existing, published
+//     mobile-v* release
+//   - the effort-judge manifest release exists, is published, and is not Latest
+//
+// Env: GITHUB_REPOSITORY, RELEASE_TAG (vX.Y.Z), RELAY_DOMAIN, GH_TOKEN.
+
+import { createHash } from 'node:crypto';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { parseMacFeed } from './merge-mac-update-feed.mjs';
+import { APP_TAG_RE, currentLatestTag, gh, isHttp404 } from './release-guard.mjs';
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Keep in step with the per-platform `requirements` in
+// .github/workflows/release.yml (a unit test compares both). The Linux update
+// feeds (latest-linux*.yml) are not parsed here, only required to exist.
+export const ASSET_CONTRACT = Object.freeze([
+  'latest-linux-arm64.yml',
+  'latest-linux.yml',
+  'latest-mac.yml',
+  'latest.yml',
+  'mixdog-desktop-linux-amd64.deb',
+  'mixdog-desktop-linux-arm64.AppImage',
+  'mixdog-desktop-linux-arm64.deb',
+  'mixdog-desktop-linux-x86_64.AppImage',
+  'mixdog-desktop-mac-arm64.dmg',
+  'mixdog-desktop-mac-arm64.zip',
+  'mixdog-desktop-mac-arm64.zip.blockmap',
+  'mixdog-desktop-mac-x64.dmg',
+  'mixdog-desktop-mac-x64.zip',
+  'mixdog-desktop-mac-x64.zip.blockmap',
+  'mixdog-desktop-win-x64.exe',
+  'mixdog-desktop-win-x64.exe.blockmap',
+]);
+
+const MAC_ZIPS = ['mixdog-desktop-mac-arm64.zip', 'mixdog-desktop-mac-x64.zip'];
+
+export function checkLatest(tag, latestTag) {
+  return latestTag === tag ? [] : [`GitHub Latest is ${latestTag ?? 'none'}, expected ${tag}`];
+}
+
+export function checkAssetSet(assets) {
+  const problems = [];
+  const names = assets.map((asset) => asset.name);
+  for (const name of ASSET_CONTRACT) {
+    if (!names.includes(name)) problems.push(`missing release asset ${name}`);
+  }
+  for (const name of names) {
+    if (!ASSET_CONTRACT.includes(name)) problems.push(`unexpected release asset ${name}`);
+  }
+  if (new Set(names).size !== names.length) problems.push('duplicate release asset names');
+  for (const asset of assets) {
+    if (asset.state !== 'uploaded' || !(asset.size > 0)) problems.push(`incomplete release asset ${asset.name}`);
+  }
+  return problems;
+}
+
+/**
+ * Check one electron-builder feed against the uploaded assets: version, that
+ * every listed file is an uploaded asset of the listed size, and that its
+ * sha512 is the hash of the uploaded bytes. `hashAsset(asset)` returns the
+ * base64 sha512 of an asset's content.
+ */
+export async function checkFeed({ text, label, version, assets, hashAsset, requiredFiles = [] }) {
+  let feed;
+  try {
+    feed = parseMacFeed(text, label);
+  } catch (error) {
+    return [error.message];
+  }
+  const problems = [];
+  if (feed.version !== version) {
+    problems.push(`${label}: version ${feed.version}, expected ${version}`);
+  }
+  const field = (file, key) =>
+    file.lines.map((line) => new RegExp(`^ +(?:- )?${key}: (\\S+)$`).exec(line)?.[1]).find(Boolean);
+  const byUrl = new Map(feed.files.map((file) => [file.url, file]));
+  for (const name of requiredFiles) {
+    if (!byUrl.has(name)) problems.push(`${label}: files[] does not list ${name}`);
+  }
+  const hashes = new Map();
+  for (const file of feed.files) {
+    const asset = assets.find((candidate) => candidate.name === file.url);
+    if (!asset) {
+      problems.push(`${label}: ${file.url} is not an uploaded asset`);
+      continue;
+    }
+    const size = field(file, 'size');
+    if (size === undefined || Number(size) !== asset.size) {
+      problems.push(`${label}: ${file.url} size ${size} != uploaded ${asset.size}`);
+    }
+    const sha512 = field(file, 'sha512');
+    const actual = await hashAsset(asset);
+    hashes.set(file.url, actual);
+    if (sha512 !== actual) problems.push(`${label}: ${file.url} sha512 does not match the uploaded asset`);
+  }
+  // Top-level path/sha512 is what pre-files[] clients read; it must agree too.
+  const topPath = /^path: (\S+)$/.exec(feed.top.path)?.[1];
+  const topSha = /^sha512: (\S+)$/.exec(feed.top.sha512)?.[1];
+  if (!byUrl.has(topPath)) problems.push(`${label}: path ${topPath} is not listed in files[]`);
+  else if (hashes.has(topPath) && hashes.get(topPath) !== topSha) {
+    problems.push(`${label}: top-level sha512 does not match ${topPath}`);
+  }
+  return problems;
+}
+
+export async function waitForNpm({
+  name,
+  version,
+  fetchFn = fetch,
+  sleep = defaultSleep,
+  budgetMs = 10 * 60 * 1000,
+  firstDelayMs = 5000,
+  maxDelayMs = 60_000,
+}) {
+  let waited = 0;
+  let delay = firstDelayMs;
+  let last = 'not queried';
+  for (;;) {
+    try {
+      const response = await fetchFn(`https://registry.npmjs.org/${name}/${version}`);
+      if (response.ok && (await response.json()).version === version) return [];
+      last = `HTTP ${response.status}`;
+    } catch (error) {
+      last = error.message;
+    }
+    if (waited >= budgetMs)
+      return [`${name}@${version} not resolvable on npm after ${Math.round(waited / 1000)}s (${last})`];
+    const step = Math.min(delay, budgetMs - waited);
+    await sleep(step);
+    waited += step;
+    delay = Math.min(delay * 2, maxDelayMs);
+  }
+}
+
+const ANDROID_LINK_RE =
+  /https:\/\/github\.com\/[^"'\s<>]+\/releases\/(?:tag|download)\/(mobile-v\d+\.\d+\.\d+)[^"'\s<>]*/;
+
+/**
+ * `getRelease(tag)` returns the release object or null when it does not exist.
+ * `mobileVersion` is the Android version this deploy tried to ship (empty for
+ * none). When that release failed, /app keeps linking the previous good
+ * mobile-v* release (or the releases list); that is a warning, not an error.
+ * A link to a missing or draft release stays an error.
+ * Returns { problems, warnings }.
+ */
+export async function checkRelayApp({ domain, fetchFn = fetch, getRelease, mobileVersion = '' }) {
+  const page = await fetchFn(`https://${domain}/app`);
+  if (page.status !== 200)
+    return { problems: [`https://${domain}/app answered ${page.status}, expected 200`], warnings: [] };
+  const match = ANDROID_LINK_RE.exec(await page.text());
+  const wanted = mobileVersion ? `mobile-v${mobileVersion}` : '';
+  if (!match) {
+    return wanted
+      ? {
+          problems: [],
+          warnings: [`/app links no mobile-v* release; ${wanted} was not shipped (previous good release kept)`],
+        }
+      : { problems: [`https://${domain}/app has no link to a mobile-v* release`], warnings: [] };
+  }
+  const [url, tag] = match;
+  const release = getRelease(tag);
+  if (!release) return { problems: [`/app links ${tag}, which is not an existing release`], warnings: [] };
+  if (release.draft) return { problems: [`/app links ${tag}, which is still a draft`], warnings: [] };
+  const resolved = await fetchFn(url, { redirect: 'follow' });
+  if (!resolved.ok) return { problems: [`/app Android link ${url} answered ${resolved.status}`], warnings: [] };
+  const warnings =
+    wanted && tag !== wanted
+      ? [
+          `/app links ${tag} instead of ${wanted}; the Android release failed or is not yet published (previous good release kept)`,
+        ]
+      : [];
+  return { problems: [], warnings };
+}
+
+export function checkEffortJudge({ manifest, latestTag, getRelease }) {
+  const tag = manifest.release;
+  const release = getRelease(tag);
+  if (!release) return [`effort-judge release ${tag} does not exist`];
+  const problems = [];
+  if (release.draft) problems.push(`effort-judge release ${tag} is a draft`);
+  if (latestTag === tag) problems.push(`effort-judge release ${tag} is GitHub Latest`);
+  for (const [name, file] of Object.entries(manifest.files)) {
+    const asset = (release.assets ?? []).find((candidate) => candidate.name === name);
+    if (!asset) problems.push(`effort-judge release ${tag} lacks ${name}`);
+    else if (asset.size !== file.size)
+      problems.push(`effort-judge ${name} size ${asset.size} != manifest ${file.size}`);
+  }
+  return problems;
+}
+
+/** The release for `tag`, or null only on an explicit HTTP 404. Any other failure throws. */
+export function getReleaseByTag(repo, tag, run = gh) {
+  try {
+    return JSON.parse(run(['api', `repos/${repo}/releases/tags/${tag}`]));
+  } catch (error) {
+    if (isHttp404(error)) return null;
+    throw error;
+  }
+}
+
+/**
+ * Was the app release published? A missing release (`fetchRelease` returns
+ * null) or a draft means "not published" and the checks are skipped. Any
+ * other failure (auth, transport, 5xx) is retried with backoff and then
+ * rethrown, so an API outage fails the job instead of silently skipping
+ * verification of a release that may be public.
+ */
+export async function detectPublished({
+  fetchRelease,
+  sleep = defaultSleep,
+  attempts = 5,
+  firstDelayMs = 2000,
+}) {
+  let delay = firstDelayMs;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const release = fetchRelease();
+      return Boolean(release) && release.draft === false;
+    } catch (error) {
+      if (attempt >= attempts) {
+        throw new Error(
+          `could not determine whether the release is published after ${attempts} attempts: ${error.message}`
+        );
+      }
+      await sleep(delay);
+      delay *= 2;
+    }
+  }
+}
+
+async function sha512Base64(url) {
+  const response = await fetch(url, { redirect: 'follow' });
+  if (!response.ok) throw new Error(`download ${url} answered ${response.status}`);
+  const hash = createHash('sha512');
+  for await (const chunk of response.body) hash.update(chunk);
+  return hash.digest('base64');
+}
+
+async function main() {
+  const repo = process.env.GITHUB_REPOSITORY;
+  const tag = process.env.RELEASE_TAG;
+  const domain = process.env.RELAY_DOMAIN;
+  if (!repo || !APP_TAG_RE.test(tag ?? '') || !domain) {
+    throw new Error('GITHUB_REPOSITORY, RELEASE_TAG (vX.Y.Z) and RELAY_DOMAIN are required');
+  }
+  const version = tag.slice(1);
+  const getRelease = (releaseTag) => getReleaseByTag(repo, releaseTag);
+  const release = getRelease(tag);
+  const assets = release?.assets ?? [];
+  const latestTag = currentLatestTag(repo);
+  const hashed = new Map();
+  const hashAsset = (asset) => {
+    if (!hashed.has(asset.name)) hashed.set(asset.name, sha512Base64(asset.browser_download_url));
+    return hashed.get(asset.name);
+  };
+  const feedText = async (name) => {
+    const asset = assets.find((candidate) => candidate.name === name);
+    if (!asset) return null;
+    const response = await fetch(asset.browser_download_url, { redirect: 'follow' });
+    return response.ok ? response.text() : null;
+  };
+  const feed = async (name, requiredFiles) => {
+    const text = await feedText(name);
+    if (text === null) return [`${name} could not be downloaded from ${tag}`];
+    return checkFeed({ text, label: name, version, assets, hashAsset, requiredFiles });
+  };
+
+  const sections = [
+    [
+      'GitHub Latest',
+      async () => (release && !release.draft ? checkLatest(tag, latestTag) : [`${tag} is not a published release`]),
+    ],
+    ['Release assets', async () => checkAssetSet(assets)],
+    ['latest.yml', () => feed('latest.yml', ['mixdog-desktop-win-x64.exe'])],
+    ['latest-mac.yml', () => feed('latest-mac.yml', MAC_ZIPS)],
+    ['Relay /app', () => checkRelayApp({ domain, getRelease, mobileVersion: process.env.MOBILE_VERSION ?? '' })],
+    [
+      'effort-judge release',
+      async () =>
+        checkEffortJudge({
+          manifest: JSON.parse(readFileSync('src/runtime/effort-judge/model-manifest.json', 'utf8')),
+          latestTag,
+          getRelease,
+        }),
+    ],
+    ['npm', () => waitForNpm({ name: 'mixdog', version })],
+  ];
+  const results = [];
+  for (const [name, run] of sections) {
+    try {
+      const outcome = await run();
+      results.push(
+        Array.isArray(outcome)
+          ? { name, problems: outcome, warnings: [] }
+          : { name, problems: outcome.problems, warnings: outcome.warnings }
+      );
+    } catch (error) {
+      results.push({ name, problems: [`check failed: ${error.message}`], warnings: [] });
+    }
+  }
+
+  const lines = [`## Post-release check for ${tag}`, ''];
+  for (const { name, problems, warnings } of results) {
+    let status = 'ok';
+    if (problems.length) status = 'FAIL';
+    else if (warnings.length) status = 'WARN';
+    lines.push(`- ${status} ${name}`);
+    for (const problem of problems) lines.push(`    - ${problem}`);
+    for (const warning of warnings) {
+      lines.push(`    - warning: ${warning}`);
+      console.log(`::warning title=Post-release ${name}::${warning}`);
+    }
+  }
+  const text = `${lines.join('\n')}\n`;
+  console.log(text);
+  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, text);
+  return results.some(({ problems }) => problems.length) ? 1 : 0;
+}
+
+// `detect-published`: write published=true|false to GITHUB_OUTPUT. Exits 1
+// (job fails) when the GitHub API cannot give a definite answer.
+async function detectPublishedMain() {
+  const repo = process.env.GITHUB_REPOSITORY;
+  const tag = process.env.RELEASE_TAG;
+  if (!repo || !APP_TAG_RE.test(tag ?? '')) {
+    throw new Error('GITHUB_REPOSITORY and RELEASE_TAG (vX.Y.Z) are required');
+  }
+  const published = await detectPublished({ fetchRelease: () => getReleaseByTag(repo, tag) });
+  if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `published=${published}\n`);
+  const result = process.env.RELEASE_RESULT ?? 'unknown';
+  if (published) console.log(`${tag} is published (release job: ${result}); running the post-release checks.`);
+  else console.log(`::notice title=Post-release checks skipped::${tag} was not published (release job: ${result}).`);
+  return 0;
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  try {
+    process.exit(process.argv[2] === 'detect-published' ? await detectPublishedMain() : await main());
+  } catch (error) {
+    console.log(`::error title=Post-release check::${error.message}`);
+    process.exit(1);
+  }
+}

package/scripts/publish-asset-release.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Create or publish a NON-app release (effort-judge, voice, graph, spawn,
+// mobile, ...) without ever moving GitHub's "Latest" pointer, which belongs to
+// the newest app release (vX.Y.Z) alone.
+//
+//   publish-asset-release.mjs create  <tag> [gh release create options/files...]
+//   publish-asset-release.mjs publish <tag>      # draft -> published
+//
+// Always passes --latest=false, and fails if Latest changed across the call.
+
+import { pathToFileURL } from 'node:url';
+import { APP_TAG_RE, currentLatestTag, gh } from './release-guard.mjs';
+
+export function buildArgs(action, tag, extra = [], repo) {
+  if (APP_TAG_RE.test(tag)) throw new Error(`${tag} is an app release tag; asset releases must not use it`);
+  if (extra.some((arg) => /^--latest(=|$)/.test(arg))) {
+    throw new Error('--latest is set by this script; do not pass it');
+  }
+  const scope = repo ? ['--repo', repo] : [];
+  if (action === 'create') return ['release', 'create', tag, ...extra, ...scope, '--latest=false'];
+  if (action === 'publish') return ['release', 'edit', tag, ...scope, '--draft=false', '--latest=false'];
+  throw new Error(`unknown action ${action} (expected create|publish)`);
+}
+
+export function publishAssetRelease({ action, tag, extra = [], repo, run = gh }) {
+  const args = buildArgs(action, tag, extra, repo);
+  const before = currentLatestTag(repo, run);
+  run(args);
+  const after = currentLatestTag(repo, run);
+  if (after !== before) {
+    throw new Error(`Latest moved from ${before ?? 'none'} to ${after ?? 'none'} while ${action} ${tag}`);
+  }
+  return before;
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  const [action, tag, ...extra] = process.argv.slice(2);
+  if (!action || !tag) {
+    throw new Error('usage: publish-asset-release.mjs <create|publish> <tag> [gh release create args...]');
+  }
+  const latest = publishAssetRelease({ action, tag, extra, repo: process.env.GITHUB_REPOSITORY });
+  console.log(`${action} ${tag}: Latest unchanged (${latest ?? 'none'}).`);
+}

package/scripts/release-guard.mjs

@@ -0,0 +1,63 @@
+// Shared helpers for the release automation guards: latest-guard.yml,
+// publish-asset-release.mjs and post-release-check.mjs.
+//
+// GitHub's "Latest" release is what electron-updater follows (latest.yml /
+// latest-mac.yml), so it must always be the newest published desktop app
+// release (vX.Y.Z). Asset releases (effort-judge-*, voice-*, graph-v*, ...)
+// and mobile-v* releases must never take it.
+
+import { execFileSync } from 'node:child_process';
+
+export const APP_TAG_RE = /^v\d+\.\d+\.\d+$/;
+
+/** Numeric semver comparison of two vX.Y.Z tags (or X.Y.Z versions). */
+export function compareSemver(a, b) {
+  const left = String(a).replace(/^v/, '').split('.').map(Number);
+  const right = String(b).replace(/^v/, '').split('.').map(Number);
+  for (let index = 0; index < 3; index++) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+}
+
+/** The newest non-draft, non-prerelease app release, or null. */
+export function selectLatestAppRelease(releases) {
+  const apps = releases.filter(
+    (release) => !release.draft && !release.prerelease && APP_TAG_RE.test(release.tag_name || '')
+  );
+  apps.sort((a, b) => compareSemver(b.tag_name, a.tag_name));
+  return apps[0] ?? null;
+}
+
+/** Run `gh` and return stdout. Throws with gh's stderr on failure. */
+export function gh(args) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+export function ghJson(args, run = gh) {
+  return JSON.parse(run(args));
+}
+
+/** All releases of a repo, newest first as the API returns them. */
+export function listReleases(repo, run = gh) {
+  return ghJson(['api', '--paginate', '--slurp', `repos/${repo}/releases?per_page=100`], run).flat();
+}
+
+/** True only for an explicit HTTP 404 from `gh api`; "not found" wording alone (e.g. behind a 500) is not absence. */
+export function isHttp404(error) {
+  return /\bHTTP 404\b/.test(`${error.stderr ?? ''}${error.message ?? ''}`);
+}
+
+/** Tag of the repo's current "Latest" release, or null when there is none. */
+export function currentLatestTag(repo, run = gh) {
+  try {
+    return run(['api', `repos/${repo}/releases/latest`, '--jq', '.tag_name']).trim() || null;
+  } catch (error) {
+    if (isHttp404(error)) return null;
+    throw error;
+  }
+}