Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Publish Windows + Linux desktop installers on every release, with in-app auto-update (no apt/rpm repo) (#3171)
mike-inkeep275ba548f860
diff --git a/.changeset/win-linux-desktop-release.md b/.changeset/win-linux-desktop-release.mdnew file mode 100644index 000000000..c8f24accf--- /dev/null+++ b/.changeset/win-linux-desktop-release.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++The desktop app now ships for Windows and Linux, with auto-update on every platform. Each release publishes signed Windows installers (x64 and ARM64) and Linux `.deb`/`.rpm` packages (x64 and ARM64) alongside the macOS DMG, all attached to the GitHub Release. Installed apps update themselves: Windows updates install silently like macOS, and Linux updates download the new package and ask for your password to install it (via the system's polkit prompt) — no apt/rpm repository to configure.diff --git a/.github/scripts/build-smoke-alert-payload.test.mjs b/.github/scripts/build-smoke-alert-payload.test.mjsindex e9a4f52c8..46f488441 100644--- a/.github/scripts/build-smoke-alert-payload.test.mjs+++ b/.github/scripts/build-smoke-alert-payload.test.mjs@@ -130,20 +130,35 @@ describe('parseArgs', () => {});describe('workflow wiring', () => {- test('the alert step is failure-conditioned, not success-conditioned', () => {- expect(alertStep()).toContain('if: failure()');+ test('the alert job is failure-conditioned, not success-conditioned', () => {+ // Under the fan-out topology the failure() lives at the ALERT JOB level+ // (a failed packaging job skips finalize, so a failure()-step inside it+ // could never fire); the step keeps only the stable-only channel gate.+ const alertJob = desktopRelease.slice(+ desktopRelease.indexOf('\n alert:'),+ desktopRelease.indexOf('- name: Alert on a blocked release'),+ );+ expect(alertJob).toContain('if: failure()');+ expect(alertJob).not.toContain('if: success()');expect(alertStep()).not.toContain('if: success()');});test('the alert reads its builder from the workflow commit, not the release tag', () => {// On repository_dispatch the workflow runs from the default branch while- // the job checks out client_payload.ref — a tag that can predate this- // script. v0.41.0 lost its Slack announcement to exactly that.- const step = alertStep();- expect(step).toContain('git fetch --depth=1 origin "$GITHUB_SHA"');- expect(step).toContain(- 'git show "${GITHUB_SHA}:.github/scripts/build-smoke-alert-payload.mjs"',+ // the packaging jobs check out client_payload.ref — a tag that can predate+ // this script. v0.41.0 lost its Slack announcement to exactly that. The+ // alert job therefore checks out $GITHUB_SHA (a bare checkout, no `ref:`+ // override) and reads the builder from the working tree, degrading to the+ // plain-text payload when even that copy is missing.+ const alertJob = desktopRelease.slice(+ desktopRelease.indexOf('\n alert:'),+ desktopRelease.indexOf('- name: Alert on a blocked release'),);+ expect(alertJob).toContain('actions/checkout');+ expect(alertJob).not.toContain('ref: ${{ github.event.client_payload.ref');+ const step = alertStep();+ expect(step).toContain('-f .github/scripts/build-smoke-alert-payload.mjs');+ expect(step).toContain('node .github/scripts/build-smoke-alert-payload.mjs --tag');});test('the alert reuses the existing webhook secret and introduces none', () => {diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjsindex e1d0c839f..e95701518 100644--- a/.github/scripts/release-cascade-shape.test.mjs+++ b/.github/scripts/release-cascade-shape.test.mjs@@ -10,6 +10,7 @@*/import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { createRequire } from 'node:module';import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';@@ -25,8 +26,11 @@ const promoteStable = read('promote-stable.yml');const releaseYml = read('release.yml');/**- * Ordered step names from a workflow's single-job flat step list. Fails loud- * rather than silently returning [] if the shape ever changes.+ * Ordered step names across the workflow, in FILE order. Under the fan-out+ * topology file order equals execution order only WITHIN a job; cross-job+ * ordering is enforced by the `needs:` DAG, which the dedicated describe+ * below pins directly. Fails loud rather than silently returning [] if the+ * shape ever changes.*/function stepNames(source) {const names = [...source.matchAll(/^ {6}- name: (.+)$/gm)].map((m) => m[1].trim());@@ -44,9 +48,10 @@ describe('the stable gate is upstream of everything that ships', () => {const names = stepNames(desktopRelease);test('the smoke gate runs after the DMG is built', () => {- expect(indexOfStep(names, 'Smoke the packaged DMG')).toBeGreaterThan(- indexOfStep(names, 'Build + sign + notarize + publish DMG/ZIP'),- );+ // Both steps live in build-macos, so file order is execution order here.+ const build = indexOfStep(names, 'Build + sign + notarize DMG/ZIP');+ expect(build).toBeGreaterThan(-1);+ expect(indexOfStep(names, 'Smoke the packaged DMG')).toBeGreaterThan(build);});test('the smoke gate runs before the draft is promoted to published', () => {@@ -90,17 +95,19 @@ describe('the stable gate is upstream of everything that ships', () => {// declare one and you own the whole predicate. A shipping step whose `if:`// omits `success()` fires on a job that already failed — which is a gate// that does not gate. This escaped review once: the npm dispatch shipped- // with `if: steps.channel... && github.event_name...` and no `success()`,- // so a refused DMG would still have published to npm.+ // with a channel-and-event `if:` and no `success()`, so a refused DMG+ // would still have published to npm.const afterGate = desktopRelease.slice(desktopRelease.indexOf('- name: Smoke the packaged DMG'),);const shipping = afterGate.slice(0, afterGate.indexOf('- name: Alert on a blocked release'));const conditions = [...shipping.matchAll(/^\s*if: (.+)$/gm)].map((m) => m[1].trim());- // The gate itself is channel-scoped and runs before anything can have- // failed; everything after it is shipping and must be success()-gated.+ // Two conditions in this span are gates, not shipping: the smoke gate's+ // own channel scope, and the alert JOB's failure() header (the span ends+ // at the alert step's name, which sits after its job header). Everything+ // else ships and must be success()-gated.const shippingConditions = conditions.filter(- (c) => c !== "steps.channel.outputs.channel == 'latest'",+ (c) => c !== "steps.channel.outputs.channel == 'latest'" && c !== 'failure()',);expect(shippingConditions.length).toBeGreaterThan(0);for (const condition of shippingConditions) {@@ -111,6 +118,70 @@ describe('the stable gate is upstream of everything that ships', () => {});});+describe('the Azure signing flag set satisfies the schema', () => {+ test('every schema-required azureSignOptions field is passed by both Windows packagers', () => {+ // app-builder-lib's validateConfig rejects a PARTIAL azureSignOptions+ // before packaging anything ("should be one of these: null"), and the+ // fan-in topology turns that one-job failure into a zero-platform+ // release. The required set is data (scheme.json), so pin the workflows'+ // flag sets against it — this is exactly the check that would have+ // caught the three-of-four-fields shape without a live Azure account.+ // Resolution goes through electron-builder's own tree because pnpm's+ // isolated layout hides transitive deps from the workspace packages.+ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');+ const desktopRequire = createRequire(join(repoRoot, 'packages/desktop/package.json'));+ const ebMain = desktopRequire.resolve('electron-builder');+ const ablRequire = createRequire(ebMain);+ const ablMain = ablRequire.resolve('app-builder-lib');+ const scheme = JSON.parse(readFileSync(join(dirname(ablMain), '..', 'scheme.json'), 'utf8'));+ const required = scheme.definitions.WindowsAzureSigningConfiguration.required;+ expect(required.length).toBeGreaterThanOrEqual(3); // schema sanity, not vacuous++ for (const workflow of [desktopRelease, read('desktop-build-win-linux.yml')]) {+ const passed = [...workflow.matchAll(/--config\.win\.azureSignOptions\.([A-Za-z]+)=/g)].map(+ (m) => m[1],+ );+ for (const field of required) {+ expect(passed, `workflow is missing schema-required azureSignOptions.${field}`).toContain(+ field,+ );+ }+ }+ });+});++describe('the fan-in publication DAG gates every platform', () => {+ test('publish-assets waits on all four build jobs', () => {+ // The single publication point must sit downstream of EVERY packaging+ // job — dropping one from `needs` publishes a release that platform+ // never built for.+ expect(desktopRelease).toContain(+ 'needs: [prepare, build-macos, build-windows, build-linux]',+ );+ });++ test('finalize waits on publish-assets (and the smoke via build-macos)', () => {+ expect(desktopRelease).toContain('needs: [prepare, build-macos, publish-assets]');+ });++ test('no electron-builder invocation publishes; only the fan-in touches the Release', () => {+ expect(desktopRelease).not.toContain('--publish always');+ const invocations = [...desktopRelease.matchAll(/electron-builder --\w+/g)];+ expect(invocations.length).toBeGreaterThanOrEqual(3);+ expect(desktopRelease).toContain('gh release upload "$RELEASE_TAG"');+ });++ test('the inventory is asserted before upload and re-verified after', () => {+ const names = stepNames(desktopRelease);+ const assert = indexOfStep(names, 'Assert the complete cross-platform inventory');+ const upload = indexOfStep(names, 'Upload assets to the GitHub Release');+ const verify = indexOfStep(names, 'Verify the Release carries the full inventory');+ expect(assert).toBeGreaterThan(-1);+ expect(assert).toBeLessThan(upload);+ expect(upload).toBeLessThan(verify);+ });+});+describe('the moved dispatch keeps the contract release.yml consumes', () => {test('promote-stable no longer dispatches publish-stable', () => {expect(promoteStable).not.toContain('event_type: "publish-stable"');@@ -141,7 +212,7 @@ describe('the moved dispatch keeps the contract release.yml consumes', () => {desktopRelease.indexOf('- name: Trigger release.yml to publish stable to npm'),desktopRelease.indexOf('# The on-site changelog'),);- expect(dispatch).toContain("steps.channel.outputs.channel == 'latest'");+ expect(dispatch).toContain("needs.prepare.outputs.channel == 'latest'");expect(dispatch).toContain("github.event_name != 'workflow_dispatch'");});});@@ -278,14 +349,19 @@ describe('the stable gate does not touch the beta cadence', () => {});test('the alert is stable-only too, so a beta hiccup does not page', () => {+ // The failure() half of the old combined predicate moved to the alert+ // JOB header (pinned by build-smoke-alert-payload.test.mjs); the step+ // keeps the channel scope.expect(scoped('- name: Alert on a blocked release (FR5c)')).toContain(- "if: failure() && steps.channel.outputs.channel == 'latest'",+ "if: needs.prepare.outputs.channel == 'latest'",);});test('the beta path keeps its existing stuck-draft warning', () => {+ // No step-level channel gate: the warning fires for BOTH channels (the+ // alert job's failure() header is what conditions it on a broken run).const warn = scoped('- name: Warn on stuck draft');- expect(warn).toContain('if: failure()');- expect(warn).not.toContain("channel == 'latest'");+ expect(warn).toContain('RECOVERY="gh release edit');+ expect(warn).not.toContain("if: needs.prepare.outputs.channel == 'latest'");});});diff --git a/.github/workflows/desktop-build-win-linux.yml b/.github/workflows/desktop-build-win-linux.ymlindex 0000fc4d2..3e85eb61e 100644--- a/.github/workflows/desktop-build-win-linux.yml+++ b/.github/workflows/desktop-build-win-linux.yml@@ -3,9 +3,9 @@ name: Desktop build (manual, Windows/Linux)# Manual, artifact-only Windows + Linux desktop builds (spec# 2026-07-16-desktop-windows-linux-port, D6): nothing here publishes,# tags, or touches the release cadence — the operator downloads the-# installers from the run's artifacts for VM/hardware QA. Cadence wiring-# (desktop-release.yml jobs, updates-proxy widening, download surfaces)-# is deferred to P4 after QA sign-off.+# installers from the run's artifacts for VM/hardware QA. The release+# path is desktop-release.yml, which builds these same targets signed+# and publishes them; this workflow stays the unsigned QA lane.## Topology: one `prepare` job on ubuntu builds the workspace (the CLI# build chain uses `cp -r`/`mkdir -p` bash-isms that don't survive a@@ -220,8 +220,13 @@ jobs:# Signing is optional (see header). Secrets: AZURE_TENANT_ID /# AZURE_CLIENT_ID / AZURE_CLIENT_SECRET; repo variables:# AZURE_SIGNING_ENDPOINT / AZURE_SIGNING_ACCOUNT / AZURE_SIGNING_PROFILE- # (Azure Artifact Signing endpoint URL, code-signing account name,- # certificate profile name — procurement outputs).+ # / AZURE_SIGNING_PUBLISHER (Azure Trusted Signing endpoint URL,+ # code-signing account name, certificate profile name, certificate+ # subject CN — procurement outputs). All FOUR azureSignOptions fields+ # are schema-required (app-builder-lib WindowsAzureSigningConfiguration+ # .required) — passing a subset fails validateConfig before packaging,+ # so the signed branch requires the full set and PUBLISHER joins the+ # presence check.- name: Package NSIS installers (x64 + arm64)working-directory: packages/desktopenv:@@ -231,18 +236,20 @@ jobs:AZURE_SIGNING_ENDPOINT: ${{ vars.AZURE_SIGNING_ENDPOINT }}AZURE_SIGNING_ACCOUNT: ${{ vars.AZURE_SIGNING_ACCOUNT }}AZURE_SIGNING_PROFILE: ${{ vars.AZURE_SIGNING_PROFILE }}+ AZURE_SIGNING_PUBLISHER: ${{ vars.AZURE_SIGNING_PUBLISHER }}run: |set -euo pipefailextra=()- if [[ -n "${AZURE_CLIENT_SECRET:-}" && -n "${AZURE_SIGNING_ENDPOINT:-}" ]]; then- echo "::notice::Azure Artifact Signing credentials present — building SIGNED installers."+ if [[ -n "${AZURE_CLIENT_SECRET:-}" && -n "${AZURE_SIGNING_ENDPOINT:-}" && -n "${AZURE_SIGNING_PUBLISHER:-}" ]]; then+ echo "::notice::Azure Trusted Signing credentials present — building SIGNED installers."extra+=("--config.win.azureSignOptions.endpoint=${AZURE_SIGNING_ENDPOINT}""--config.win.azureSignOptions.codeSigningAccountName=${AZURE_SIGNING_ACCOUNT}""--config.win.azureSignOptions.certificateProfileName=${AZURE_SIGNING_PROFILE}"+ "--config.win.azureSignOptions.publisherName=${AZURE_SIGNING_PUBLISHER}")else- echo "::warning::No Azure signing credentials — building UNSIGNED installers (internal QA only; never distribute)."+ echo "::warning::No (complete) Azure signing config — building UNSIGNED installers (internal QA only; never distribute)."fipnpm exec electron-builder --win --publish never "${extra[@]}"@@ -450,7 +457,8 @@ jobs:retention-days: 14if-no-files-found: error- # No Linux update-metadata upload: electron-updater is platform-gated- # off on Linux (the bootAutoUpdater wiring site in src/main/index.ts) —- # updates arrive via the system package manager, so no- # `latest-linux.yml` feed exists to publish.+ # No Linux update-metadata upload: these are unsigned QA artifacts,+ # never published, so their `latest-linux*.yml` files have no consumer.+ # The release path (desktop-release.yml) uploads the Linux manifests —+ # electron-updater's DebUpdater/RpmUpdater consume them since the+ # auto-updater was un-gated on Linux.diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.ymlindex a2621ab2a..13055ba1a 100644--- a/.github/workflows/desktop-release.yml+++ b/.github/workflows/desktop-release.yml@@ -1,53 +1,85 @@name: Desktop release-# Builds + signs + notarizes + publishes the macOS DMG/ZIP for an-# Open Knowledge release. After upload, promotes the GitHub Release-# from draft → published so it appears in the .atom feed.+# Builds + signs + publishes EVERY desktop installer for an Open Knowledge+# release — macOS DMG/ZIP, Windows NSIS x64/arm64, Linux deb/rpm x64/arm64 —+# then promotes the GitHub Release from draft → published so it appears in+# the .atom feed.+#+# Topology (fan-out / fan-in, one publication point):+#+# prepare ── channel/version resolution + platform-neutral workspace build+# │+# ├────────────┬──────────────┐+# build-macos build-windows build-linux (x64 + arm64 matrix)+# sign+notarize Azure-sign deb+rpm on native runners+# + DMG smoke NSIS x64+arm64+# │ │ │+# └────────────┴──────────────┘+# │+# publish-assets ── inventory assert → gh release upload → verify+# │+# finalize ── Downloads table → draft flip → npm dispatch+# → Slack/Discord announcements+# │+# alert ── pages the release channel on any upstream failure+#+# Every packaging job runs `electron-builder --publish never` and stages its+# outputs as run artifacts; only `publish-assets` talks to the GitHub Release.+# That gives one place that asserts the full cross-platform inventory before+# anything becomes visible, and makes upload retries cheap (re-running+# `publish-assets` never re-runs a 30-minute signed build). electron-builder+# writes the electron-updater channel manifests (latest-mac.yml / latest.yml /+# latest-linux[-arm64].yml, or their beta-* siblings) locally regardless of+# publish mode, so the fan-in uploads those alongside the installers.## Triggers (2):# - repository_dispatch (event_type: desktop-release) — primary cascade# from release.yml (beta) and promote-stable.yml (stable). The# upstream creates the GitHub Release as --draft (so it stays out-# of the .atom feed until the channel manifest is uploaded) and-# dispatches this workflow with client_payload.{release_tag, ref}.-# We do not use `release: published` for the cascade because the-# upstream gh release create runs as GITHUB_TOKEN, and GitHub-# suppresses workflow runs from GITHUB_TOKEN-authored release-# events. repository_dispatch is the documented exemption.+# of the .atom feed until every installer + channel manifest is+# uploaded) and dispatches this workflow with+# client_payload.{release_tag, ref}. We do not use `release: published`+# for the cascade because the upstream gh release create runs as+# GITHUB_TOKEN, and GitHub suppresses workflow runs from+# GITHUB_TOKEN-authored release events. repository_dispatch is the+# documented exemption.# See https://docs.github.com/en/actions/concepts/security/github_token.-# - workflow_dispatch — manual recovery path for re-uploading a DMG-# to an existing Release after a transient failure (e.g., a CI-only-# fix landed after the tag was cut). Builds from the chosen ref-# and uploads to the Release matching release_tag.-#-# What this workflow does: downloads the tagged ref, builds a signed +-# notarized + stapled + fuse-verified Universal DMG + Universal ZIP,-# and uploads `.dmg`, `.dmg.blockmap`, `.zip`, `.zip.blockmap`, and the-# channel-appropriate manifest (`latest-mac.yml` for stable releases,-# `beta-mac.yml` for `*-beta.*` prereleases) to the GitHub Release-# matching the tag. The channel is detected from the package version's-# prerelease tag in a step below. The upload is driven by-# `electron-builder --publish always` reading the-# `publish: [{ provider: github, owner: inkeep, repo: open-knowledge }]`-# block from `packages/desktop/electron-builder.yml`. After upload,-# the Promote step flips draft → published (and re-stamps --latest for-# the stable channel on the normal flow) via a single combined-# gh release edit PATCH — empirically atomic; GitHub evaluates the-# make_latest constraint against post-request state.+# - workflow_dispatch — manual recovery path for re-building + re-uploading+# assets to an EXISTING Release after a transient failure (e.g., a+# CI-only fix landed after the tag was cut). Builds from the chosen ref+# and uploads to the Release matching release_tag. Unlike the+# electron-builder-publisher era this path no longer creates a missing+# Release — the Release must already exist (cut by release.yml /+# promote-stable.yml / point-release.yml).#-# Required secrets (identical shape to desktop-build.yml):-# CSC_LINK / CSC_KEY_PASSWORD-# APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD + APPLE_TEAM_ID-# OR APPLE_API_KEY + APPLE_API_KEY_ID [+ APPLE_API_ISSUER]+# Required secrets:+# macOS (identical shape to desktop-build.yml):+# CSC_LINK / CSC_KEY_PASSWORD+# APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD + APPLE_TEAM_ID+# OR APPLE_API_KEY + APPLE_API_KEY_ID [+ APPLE_API_ISSUER]+# Windows (Azure Trusted Signing — same names as desktop-build-win-linux.yml):+# secrets: AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET+# repo variables: AZURE_SIGNING_ENDPOINT / AZURE_SIGNING_ACCOUNT /+# AZURE_SIGNING_PROFILE / AZURE_SIGNING_PUBLISHER (the certificate+# subject CN, e.g. "Inkeep, Inc." — azureSignOptions.publisherName is+# schema-REQUIRED by app-builder-lib, distinct from the optional+# win.publisherName update-verification knob)# GITHUB_TOKEN (auto-provided, contents:write scope) — used as GH_TOKEN-# for electron-builder's GitHub publish.+# for the fan-in `gh release upload` + the finalize/alert steps.#-# Unsigned mode is explicitly REJECTED here. auto-update refuses unsigned-# upgrades (Squirrel.Mac signature-verifies every update against the-# installed app's cert), so publishing unsigned would silently break-# real-world update cycles. Without CSC_LINK present, this workflow-# fails loudly in the signmode-detection step rather than building an-# unpublishable artifact.+# Unsigned mode is explicitly REJECTED on macOS AND Windows. On macOS,+# auto-update refuses unsigned upgrades (Squirrel.Mac signature-verifies every+# update against the installed app's cert). On Windows nothing technically+# blocks unsigned updates, but publishing unsigned would (a) train users+# through SmartScreen "unrecognized app" warnings, (b) forfeit signer+# reputation the beta cadence exists to accrue, and (c) make a later+# `win.publisherName` verification rollout impossible to sequence — once any+# signature-verifying build is in the field, every future installer on that+# channel must be signed. Both platforms fail loudly in their+# signing-detection steps rather than building an unpublishable artifact.+# Linux needs no signing: the deb/rpm updaters install with signature checks+# disabled by design (no apt/rpm repo in the loop — electron-updater downloads+# from the release feed and installs via pkexec).on:# Primary cascade from release.yml (beta) and promote-stable.yml (stable).@@ -58,26 +90,28 @@ on:# release events; repository_dispatch is the documented exemption.repository_dispatch:types: [desktop-release]- # Manual re-publish path: lets an operator upload a DMG to an existing- # Release when the original cascade-triggered run failed (e.g., a+ # Manual re-publish path: lets an operator rebuild + re-upload assets for an+ # existing Release when the original cascade-triggered run failed (e.g., a# CI-only fix landed on `main` after the tag was cut). Builds from# the chosen ref (typically `main` with the fix) and uploads to the# Release matching release_tag. The dispatcher must ensure# `packages/desktop/package.json#version` at the chosen ref matches- # release_tag (without the `v` prefix) — electron-builder picks the- # upload target from package.json, not from this input.+ # release_tag (without the `v` prefix) — the version override below derives+ # everything from the tag, so a mismatched ref ships mismatched code, not+ # mismatched metadata.workflow_dispatch:inputs:release_tag:- description: "Existing release tag to upload DMG to (e.g. v0.3.0)"+ description: "Existing release tag to upload assets to (e.g. v0.3.0)"required: truetype: stringpermissions:- # contents:write is required for electron-builder to upload release assets- # via the GitHub API. The auto-provided GITHUB_TOKEN gets write scope with- # this declaration; no separate PAT or App-token required.- contents: write+ # Least-privilege default: the packaging jobs only read the repo. The two+ # jobs that touch the Release (publish-assets: asset upload; finalize:+ # body edit + draft flip + repository_dispatch) each declare their own+ # `contents: write`. No separate PAT or App-token required.+ contents: read# Concurrency mirrors desktop-build.yml's rationale — a mid-notarize cancel# is costly (Apple's notary round-trip is 1-5 min and doesn't resume cleanly).@@ -88,19 +122,34 @@ concurrency:cancel-in-progress: falsejobs:- build-and-publish-macos:- # macos-26 = Apple Silicon (Tahoe) with Xcode 26.x preinstalled. Apple- # Silicon is required for the Universal DMG lipo merge (arm64 + x64 →- # universal) per parent SPEC D29. Xcode 26+ is required because- # electron-builder compiles `build/okglass.icon` → `Assets.car` via- # `actool`, which only ships with Xcode 26+.- runs-on: macos-26- # 75 min budget. A signed build + notary round-trip is ~20-30 min; the- # build+publish step retries once on a transient failure (see below), so- # the worst case is two full signed builds back-to-back. 75 min covers- # that plus cold caches and notary queue spikes. desktop-build.yml has no- # retry and stays at 45.- timeout-minutes: 75+ # Resolves the channel/version from the tag and builds the platform-neutral+ # workspace ONCE for the Windows/Linux packagers. The CLI build chain uses+ # `cp -r`/`mkdir -p` bash-isms that don't survive a Windows runner's default+ # shell, and the packaging jobs would otherwise redundantly rebuild identical+ # platform-neutral JS — same topology as desktop-build-win-linux.yml.+ # (build-macos deliberately does NOT consume this bundle: the mac job's+ # self-contained build is the proven signed-DMG path and stays byte-for-byte+ # as it was; unifying it onto the bundle is a separate, QA-able change.)+ prepare:+ runs-on: ubuntu-latest+ timeout-minutes: 30+ permissions:+ # write, not read, for one reason: the "Assert the target Release+ # exists" step must SEE the draft Release the upstream just created,+ # and GitHub's releases API only returns drafts to push-level tokens+ # (contents: read gets a 404 and the assert would block every release).+ contents: write+ # A job-level permissions block REPLACES the default token scopes, so+ # the native-config staging step's `gh run list/view/download` needs+ # its scope restated or it 403s (beta degrades to host-only; stable+ # hard-fails the cut).+ actions: read+ defaults:+ run:+ shell: bash+ outputs:+ channel: ${{ steps.channel.outputs.channel }}+ version: ${{ steps.channel.outputs.version }}steps:- name: Link to triggering run# Back-link: promote-stable forwards its run URL in@@ -120,84 +169,27 @@ jobs:# the bundled version + any CHANGELOG artifacts match the Release.## On `workflow_dispatch`, check out the workflow ref the user dispatched- # against (typically `main` with a CI fix). The dispatcher is responsible- # for ensuring the resulting `packages/desktop/package.json#version`- # matches `release_tag` (electron-builder uploads to the Release matching- # package.json, not to `release_tag` directly).+ # against (typically `main` with a CI fix).+ #+ # fetch-depth: 0 — the native-config staging step's provenance check+ # (`git merge-base --is-ancestor`) needs full history.- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2with:ref: ${{ github.event.client_payload.ref || github.ref }}+ fetch-depth: 0- - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0- with:- node-version: "24"-- - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5- - name: Get pnpm store directory- shell: bash- run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_ENV"- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4- with:- path: ${{ env.STORE_PATH }}- key: ${{ runner.os }}-ok-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}- restore-keys: |- ${{ runner.os }}-ok-pnpm-store--- - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4- with:- path: .turbo- key: ${{ runner.os }}-turbo-desktop-release-${{ hashFiles('pnpm-lock.yaml') }}- restore-keys: |- ${{ runner.os }}-turbo-desktop-release-- ${{ runner.os }}-turbo-desktop--- - name: Install dependencies- env:- # Rebuild native modules against Electron's Node ABI — same as- # desktop-build.yml.- ELECTRON_SKIP_REBUILD: "0"- run: pnpm install --frozen-lockfile-- # electron-builder.yml's `extraResources` rule copies from- # `packages/cli/dist/public/`, which the CLI's `build:assets` populates- # via `cp -r ../app/dist dist/public`. The CLI does not declare the- # app as a workspace dep (app is private, and the CLI ships the- # compiled bundle — not a package reference), so turbo's `^build`- # runs them in parallel by default. Without explicit sequencing, cli's- # `build:assets` races app's vite build and can fail (no `app/dist`- # yet) or copy stale content. Use turbo's `--filter=@inkeep/...`- # which DOES respect the `^build` graph (so server + core build- # before app), and run the two filters in sequence to enforce- # app → cli ordering.- #- # A bare per-package `--filter` run was the previous approach; it does- # not honor turbo's dep graph (only runs the named package's `build`- # script in isolation). After the workspace started shipping- # `.mjs` builds for `@inkeep/open-knowledge-server` and- # `@inkeep/open-knowledge-core` (specs/2026-04-24-desktop-packaging-- # first-boot/), Vite's config loader in app-build resolves those- # workspace deps via `exports.default → ./dist/index.mjs`. Without- # an upstream `^build`, the `dist/` doesn't exist yet → "Failed to- # resolve entry for package @inkeep/open-knowledge-server".# Detect channel from the release TAG (not package.json#version). Under# the zero-commit-bump cadence (release.yml header lines 7-10), the# tag is the only source of truth for the release's version — legacy# commits at the tagged SHA carry the cycle-base version (e.g.# `0.5.0-beta.5`), not the tag's version. Tag also drives manifest- # selection (beta-mac.yml vs latest-mac.yml) for the stable-promotion+ # selection (beta-* vs latest-* channel files) for the stable-promotion# case where tag (`v0.4.0`) and on-disk package.json (`0.4.0-beta.N`)# diverge.#- # Maps the version's prerelease tag to electron-builder's- # `--config.publish.channel` (writes beta-mac.yml vs latest-mac.yml)- # and `--config.publish.releaseType` (sets the GitHub Release- # `prerelease` flag). Also emits `version` — used both by the on-disk- # version override step below AND by the `--config.extraMetadata.version`- # override on the electron-builder invocation.- ## Fail-fast on anything other than `-beta.*` or plain semver —- # `-rc.*` / `-canary.*` etc. would ship a manifest with a channel- # name that electron-updater's GitHub provider treats as exact-match-+ # `-rc.*` / `-canary.*` etc. would ship manifests with a channel+ # name that electron-updater's provider treats as exact-match-# only (no cascade walk), producing a release that can't be picked up# by any client subscribed to a recognized channel.- name: Detect channel from release tag@@ -217,7 +209,6 @@ jobs:if [[ "$VERSION" == *-beta.* ]]; then{echo "channel=beta"- echo "release_type=prerelease"echo "version=$VERSION"} >> "$GITHUB_OUTPUT"echo "::notice::Building BETA channel from tag $RELEASE_TAG"@@ -235,31 +226,282 @@ jobs:else{echo "channel=latest"- echo "release_type=release"echo "version=$VERSION"} >> "$GITHUB_OUTPUT"echo "::notice::Building LATEST channel from tag $RELEASE_TAG"fi+ # The manual recovery path uploads to an existing Release; the cascade+ # path's Release was just created by the upstream. Either way, failing+ # here — before three platforms spend 30+ runner-minutes building — beats+ # failing in publish-assets. `gh release view` resolves drafts too.+ - name: Assert the target Release exists+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ run: |+ set -euo pipefail+ if ! gh release view "$RELEASE_TAG" --json isDraft --jq .isDraft >/dev/null 2>&1; then+ echo "::error::No GitHub Release exists for ${RELEASE_TAG}. This workflow uploads to a Release created by release.yml / promote-stable.yml / point-release.yml — create it first (as --draft), then re-dispatch."+ exit 1+ fi++ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0+ with:+ node-version: "24"++ - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5+ - name: Get pnpm store directory+ run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_ENV"+ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: ${{ env.STORE_PATH }}+ key: ${{ runner.os }}-ok-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-ok-pnpm-store-++ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: .turbo+ key: ${{ runner.os }}-turbo-desktop-release-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-turbo-desktop-release-+ ${{ runner.os }}-turbo-desktop-++ - name: Install dependencies+ run: pnpm install --frozen-lockfile++ # The cross-platform native-config `.node` binaries are produced by the+ # standalone native-config-prebuild workflow. Stage the latest successful+ # run's bundle into packages/native-config/ so the cli `build:native`+ # step copies all eight platforms into dist/native/ — the Windows/Linux+ # installers packaged from this bundle then carry their own arch's+ # toml_edit addon. Provenance + degrade-vs-fail semantics mirror+ # release.yml's step: beta warns and ships host-only (non-host platforms+ # use the non-destructive smol-toml fallback), stable hard-fails rather+ # than silently shipping degraded native fidelity to the default install+ # channel.+ - name: Stage native-config prebuilt binaries+ env:+ GH_TOKEN: ${{ github.token }}+ IS_STABLE: ${{ steps.channel.outputs.channel == 'latest' }}+ run: |+ summarize() {+ echo "Staged native-config binaries: $1" >> "$GITHUB_STEP_SUMMARY"+ }+ degrade_or_fail() {+ # $1: human-readable reason, $2: staged-count label for the summary+ summarize "$2 — $1"+ if [ "$IS_STABLE" = "true" ]; then+ echo "::error::$1; refusing to cut a stable release with an incomplete native-config binary set"+ exit 1+ fi+ echo "::warning::$1; installers ship the host binary only (other platforms use the smol-toml fallback)"+ exit 0+ }++ # Scope to runs on `main` triggered by `push` only. The prebuild also+ # runs on `pull_request` (including from the public mirror's external+ # PRs), so without this filter the latest-green run could be an+ # unmerged branch whose Rust source is not what shipped to main — a+ # supply-chain gap for native code executed on every CLI invocation.+ run_id=$(gh run list --workflow=native-config-prebuild.yml --branch main --event push \+ --status success --limit 1 --json databaseId --jq '.[0].databaseId // empty' 2>/dev/null || true)+ if [ -z "$run_id" ]; then+ degrade_or_fail "no successful native-config-prebuild run on main found" "0/8"+ fi++ # Provenance: the prebuild run's head commit must be an ancestor of+ # the release commit, so the binaries staged were built from source+ # that is actually in this release. fetch-depth:0 in checkout has+ # full history.+ head_sha=$(gh run view "$run_id" --json headSha -q .headSha 2>/dev/null || true)+ if [ -z "$head_sha" ]; then+ degrade_or_fail "could not resolve head commit of native-config-prebuild run $run_id" "0/8"+ fi+ if ! git merge-base --is-ancestor "$head_sha" HEAD 2>/dev/null; then+ degrade_or_fail "native-config-prebuild run $run_id (commit $head_sha) is not an ancestor of the release commit" "0/8"+ fi++ if ! gh run download "$run_id" --name native-config-bindings-all --dir /tmp/nc-bindings; then+ degrade_or_fail "could not download native-config-bindings-all from run $run_id" "0/8"+ fi+ find /tmp/nc-bindings -name '*.node' -exec cp -f {} packages/native-config/ \;+ count=$(find packages/native-config -maxdepth 1 -name '*.node' | wc -l | tr -d ' ')+ echo "staged $count native-config prebuilt binaries from run $run_id (commit $head_sha)"+ if [ "$count" -lt 8 ]; then+ degrade_or_fail "staged only $count/8 native-config binaries" "$count/8"+ fi+ summarize "$count/8 from run $run_id (commit $head_sha)"++ # The workspace build produces native-config's host `.node` via `napi+ # build` (turbo dep of the cli build), which needs a Rust toolchain —+ # mirror release.yml's explicit pin.+ - name: Setup Rust toolchain for the native-config build+ uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable+ with:+ toolchain: stable+# PRD-6650: under the zero-commit-bump cadence (release.yml header# lines 7-10), workspace package.json files on disk at the tagged SHA- # always lag the release tag — agents-private mirrors a cycle-base- # version (e.g. `0.5.0-beta.5`) that `release.yml` overrides- # transiently via `jq` before `pnpm exec changeset publish`. The Desktop- # pipeline needs the same primitive: `tsdown` inlines+ # always lag the release tag. `tsdown` inlines# `import pkgJson from "../package.json"` into- # `packages/cli/dist/constants-*.mjs` at Build time, and+ # `packages/cli/dist/constants-*.mjs` at build time, and# `packages/cli/build:skill-asset` composes + copies both# `packages/server/assets/skills/{project,discovery}/SKILL.md` into- # `packages/cli/dist/assets/...`. Both bake in BEFORE- # `electron-builder --config.extraMetadata.version` runs, so the- # runtime override cannot reach them; the override has to land here,- # before Build.+ # `packages/cli/dist/assets/...`. Both bake in during the workspace+ # build below, so the override has to land here first.+ #+ # Mirrors release.yml (same `jq` loop over the five fixed-group packages+ # + same `sed` regex against SKILL.md) so the workflows stay in lockstep.+ - name: Override fixed-group versions on disk (zero-commit-bump cadence)+ env:+ VERSION: ${{ steps.channel.outputs.version }}+ run: |+ set -euo pipefail+ for pkg in cli core server app desktop; do+ f="packages/${pkg}/package.json"+ jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"+ mv "${f}.tmp" "$f"+ done+ for skill in packages/server/assets/skills/project/SKILL.md \+ packages/server/assets/skills/discovery/SKILL.md; do+ sed -i'.bak' -E "s/^([[:space:]]+version:[[:space:]]+\")[^\"]+(\".*)$/\1${VERSION}\2/" "$skill"+ rm -f "${skill}.bak"+ done+ echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."++ # Same two-filter sequencing as the mac job: app must build before cli's+ # build:assets copies app/dist into cli/dist/public.+ - name: Build workspace (produces packages/cli/dist for extraResources)+ run: |+ pnpm exec turbo run build --filter=@inkeep/open-knowledge-app+ pnpm exec turbo run build --filter=@inkeep/open-knowledge++ # Hand the platform-neutral build products to the Windows/Linux packaging+ # jobs: the full bundled CLI tree + core/server dist + the native-config+ # addon dir the electron-builder `../native-config` extraResources rule+ # reads (index.js loader + package.json + every staged .node).#- # Mirrors release.yml:191-216 exactly (same `jq` loop over the five- # fixed-group packages + same `sed` regex against SKILL.md) so the- # two workflows stay in lockstep — future cadence changes touch both- # places the same way.+ # core/server dist are load-bearing: `build:desktop` (electron-vite) in+ # the packaging jobs bundles the desktop main process + app renderer+ # source, which import `@inkeep/open-knowledge-core` and+ # `@inkeep/open-knowledge-server`. Those resolve via `exports` to+ # `./dist/index.mjs`; without the built dist here, electron-vite fails+ # with "Rolldown failed to resolve import @inkeep/open-knowledge-core".+ # The packaging jobs can't rebuild them (the Windows job's default shell+ # can't run the CLI build chain's `cp -r` bash-isms), so prepare builds+ # everything once and ships the dist forward.+ - name: Upload workspace bundle+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: workspace-bundle+ path: |+ packages/cli/dist/+ packages/core/dist/+ packages/server/dist/+ packages/native-config/index.js+ packages/native-config/index.d.ts+ packages/native-config/*.node+ retention-days: 3+ if-no-files-found: error++ # Deliberately does NOT `needs: prepare` — the mac job is self-contained+ # (own workspace build, no bundle consumption) and is the longest job in+ # the pipeline, so serializing it behind prepare would add prepare's whole+ # runtime to every cut. It re-runs the cheap channel detection itself; the+ # two copies of that step live in one file and must stay in lockstep.+ build-macos:+ # macos-26 = Apple Silicon (Tahoe) with Xcode 26.x preinstalled. Apple+ # Silicon is required for the Universal DMG lipo merge (arm64 + x64 →+ # universal) per parent SPEC D29. Xcode 26+ is required because+ # electron-builder compiles `build/okglass.icon` → `Assets.car` via+ # `actool`, which only ships with Xcode 26+.+ runs-on: macos-26+ # 75 min budget. A signed build + notary round-trip is ~20-30 min; the+ # build step retries once on a transient failure (see below), so+ # the worst case is two full signed builds back-to-back. 75 min covers+ # that plus cold caches and notary queue spikes. desktop-build.yml has no+ # retry and stays at 45.+ timeout-minutes: 75+ permissions:+ # Explicit so a future step needing more fails at review, not with a+ # silent runtime 403 (the packaging jobs never touch the Release).+ contents: read+ outputs:+ # Consumed by the alert job's FR5c payload — the smoke verdict must+ # survive this job failing, which step outputs on a failed job do+ # (job outputs from non-skipped steps are still exported).+ smoke_verdict: ${{ steps.dmg_smoke.outputs.verdict }}+ smoke_reason: ${{ steps.dmg_smoke.outputs.reason }}+ steps:+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2+ with:+ ref: ${{ github.event.client_payload.ref || github.ref }}++ # Lockstep twin of the prepare job's step (see this job's header for why+ # it exists twice) — same tag → same outputs, so `steps.channel.*` here+ # and `needs.prepare.outputs.*` elsewhere always agree.+ - name: Detect channel from release tag+ id: channel+ env:+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ run: |+ set -euo pipefail+ if [[ -z "${RELEASE_TAG:-}" ]]; then+ echo "::error::No release tag available (neither client_payload.release_tag nor inputs.release_tag is set). desktop-release.yml requires a tag to derive the version."+ exit 1+ fi+ VERSION="${RELEASE_TAG#v}"+ if [[ "$VERSION" == *-beta.* ]]; then+ {+ echo "channel=beta"+ echo "version=$VERSION"+ } >> "$GITHUB_OUTPUT"+ elif [[ "$VERSION" == *-* ]]; then+ echo "::error::Unsupported prerelease ID in tag $RELEASE_TAG — only -beta.N is supported (prepare's twin step carries the full diagnostics)."+ exit 1+ else+ {+ echo "channel=latest"+ echo "version=$VERSION"+ } >> "$GITHUB_OUTPUT"+ fi++ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0+ with:+ node-version: "24"++ - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5+ - name: Get pnpm store directory+ shell: bash+ run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_ENV"+ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: ${{ env.STORE_PATH }}+ key: ${{ runner.os }}-ok-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-ok-pnpm-store-++ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: .turbo+ key: ${{ runner.os }}-turbo-desktop-release-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-turbo-desktop-release-+ ${{ runner.os }}-turbo-desktop-++ - name: Install dependencies+ env:+ # Rebuild native modules against Electron's Node ABI — same as+ # desktop-build.yml.+ ELECTRON_SKIP_REBUILD: "0"+ run: pnpm install --frozen-lockfile++ # PRD-6650: same override as prepare, for the workspace build THIS job+ # does (the mac job stays self-contained on the proven signed-DMG path+ # rather than consuming the ubuntu-built bundle — see the prepare job's+ # header). Mirrors release.yml exactly so the workflows stay in lockstep.- name: Override fixed-group versions on disk (zero-commit-bump cadence)env:VERSION: ${{ steps.channel.outputs.version }}@@ -277,6 +519,17 @@ jobs:doneecho "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."+ # electron-builder.yml's `extraResources` rule copies from+ # `packages/cli/dist/public/`, which the CLI's `build:assets` populates+ # via `cp -r ../app/dist dist/public`. The CLI does not declare the+ # app as a workspace dep (app is private, and the CLI ships the+ # compiled bundle — not a package reference), so turbo's `^build`+ # runs them in parallel by default. Without explicit sequencing, cli's+ # `build:assets` races app's vite build and can fail (no `app/dist`+ # yet) or copy stale content. Use turbo's `--filter=@inkeep/...`+ # which DOES respect the `^build` graph (so server + core build+ # before app), and run the two filters in sequence to enforce+ # app → cli ordering.- name: Build workspace (produces packages/cli/dist/public for extraResources)run: |pnpm exec turbo run build --filter=@inkeep/open-knowledge-app@@ -293,7 +546,7 @@ jobs:run: |if [[ -n "${CSC_LINK}" ]]; thenecho "mode=signed" >> "$GITHUB_OUTPUT"- echo "::notice::Signing creds present — running signed build with electron-builder --publish always."+ echo "::notice::Signing creds present — running signed build."elseecho "::error::Cannot publish unsigned release — CSC_LINK is not set. auto-update requires signed DMGs."exit 1@@ -350,16 +603,21 @@ jobs:working-directory: packages/desktoprun: node scripts/stage-parcel-watcher.mjs- - name: Build + sign + notarize + publish DMG/ZIP+ - name: Build + sign + notarize DMG/ZIP# electron-builder picks up CSC_LINK / CSC_KEY_PASSWORD from env +# signs. afterSign.mjs picks up APPLE_* + notarizes + staples +- # fuse-verifies. `--publish always` makes electron-builder upload- # the artifacts (.dmg, .dmg.blockmap, .zip, .zip.blockmap, and the- # channel-appropriate manifest — `latest-mac.yml` or `beta-mac.yml`- # depending on `--config.publish.channel` set below from the- # detected channel) to the GitHub Release matching the current tag- # — via the publish block in electron-builder.yml (A1) + GH_TOKEN- # in env. No separate `gh release upload` step needed.+ # fuse-verifies. `--publish never`: the fan-in publish-assets job is+ # the only publication point — this job stages its outputs as a run+ # artifact below. electron-builder still writes the channel manifest+ # (`latest-mac.yml` or `beta-mac.yml`, per `--config.publish.channel`)+ # into dist-desktop locally (proven by desktop-build.yml, whose+ # --publish never build uploads that same file).+ #+ # `--config.publish.releaseType` is gone from this invocation on+ # purpose: it only ever configured the electron-builder GitHub+ # PUBLISHER's release-creation call, which no longer runs — the+ # Release's prerelease flag is set by the upstream+ # `gh release create --prerelease`.env:CSC_LINK: ${{ secrets.CSC_LINK }}CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}@@ -373,30 +631,27 @@ jobs:# and break @electron/notarize's path-based contract.APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}- # GH_TOKEN is what electron-builder's GitHub publisher reads.- # The auto-provided GITHUB_TOKEN with contents:write scope- # (declared above) is sufficient for uploading assets to a- # Release that already exists (created by release.yml's- # `gh release create`). F14 audit: no App-token required.- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ # env, not `${{ }}`-in-script — the tag these derive from arrives+ # via client_payload (see the Windows job's twin comment).+ BUILD_VERSION: ${{ steps.channel.outputs.version }}+ BUILD_CHANNEL: ${{ steps.channel.outputs.channel }}working-directory: packages/desktoprun: |# extraMetadata.version override: kept as defense-in-depth so the# Desktop's app.getVersion() / Info.plist / DMG filename / manifest# `version` all agree with the tag even if the on-disk override# step above is skipped, dropped, or partially applied. Under the- # zero-commit-bump cadence (release.yml header lines 7-10) the- # on-disk versions ALWAYS lag the release tag — agents-private- # never commits a bumped version — so this override is never a- # no-op for the Desktop's own metadata. But it does NOT reach- # the CLI bundle's compile-time-inlined PACKAGE_VERSION or the- # bundled SKILL.md asset's metadata.version; those are baked in- # at Build time, so the workspace-wide on-disk override step- # above is what makes them match the tag. See PRD-6650.+ # zero-commit-bump cadence the on-disk versions ALWAYS lag the+ # release tag, so this override is never a no-op for the Desktop's+ # own metadata. But it does NOT reach the CLI bundle's+ # compile-time-inlined PACKAGE_VERSION or the bundled SKILL.md+ # asset's metadata.version; those are baked in at Build time, so+ # the workspace-wide on-disk override step above is what makes+ # them match the tag. See PRD-6650.#- # Retry the build+publish on TRANSIENT signing/notarize/upload/download- # failures only. All of these are infrastructure flakes outside our- # control that leave no durable artifact and clear on a re-run:+ # Retry the build on TRANSIENT signing/notarize/download failures+ # only. All of these are infrastructure flakes outside our control+ # that leave no durable artifact and clear on a re-run:# - codesign's timestamp step calling Apple's TSA (timestamp.apple.com)# returning "A timestamp was expected but was not found" or the TSA# being unavailable. This is the class that stuck v0.30.2 as a draft@@ -410,20 +665,17 @@ jobs:# same run before the TSA flake killed attempt 2.# - a bare EOF fetching the Electron runtime zip during packaging# (app-builder's DownloadNoRetry path aborts on one dropped connection).- # - GitHub upload throttling (5xx / secondary-rate-limit) from- # uploads.github.com mid-publish after a successful sign+notarize.- # Re-running the whole invocation is idempotent: electron-builder deletes- # then re-uploads same-named assets on republish, so a partial asset set- # left by a failed attempt is overwritten, not duplicated.+ # (The GitHub-upload signatures that used to sit alongside these are+ # kept in the allowlist for the day uploads ever return here, but+ # can no longer match — this invocation performs no uploads; the+ # fan-in publish-assets job owns upload retries now.)## CRITICAL: retry is gated on a transient-signature allowlist matched# against the captured build output. Anything NOT on the allowlist — an# expired/invalid cert, a notarization REJECTION (status Invalid), an# entitlements error, an Apple developer-agreement 403, or a real# build/compile error — is a hard failure that fails LOUD on the first- # attempt and is never masked by a blind retry. A persistent transient- # class that exhausts all attempts still exits non-zero and lands in the- # Warn-on-stuck-draft path + the scheduled draft-release janitor.+ # attempt and is never masked by a blind retry.set -uo pipefail# Extended-regex allowlist of transient infra-flake signatures (matched# case-insensitively against combined stdout+stderr). Keep this list@@ -433,15 +685,14 @@ jobs:attempt=1max_attempts=3while true; do- echo "::group::electron-builder publish attempt ${attempt}/${max_attempts}"+ echo "::group::electron-builder attempt ${attempt}/${max_attempts}"attempt_log="${RUNNER_TEMP:-/tmp}/electron-builder-attempt-${attempt}.log"# `pipefail` (set above) makes the `if` see the electron-builder exit# code through `tee`; tee mirrors output to the CI log AND captures it# for the transient-vs-real classification below.- if { pnpm run build:desktop && pnpm exec electron-builder --mac --publish always \- --config.extraMetadata.version=${{ steps.channel.outputs.version }} \- --config.publish.channel=${{ steps.channel.outputs.channel }} \- --config.publish.releaseType=${{ steps.channel.outputs.release_type }} ; } 2>&1 | tee "${attempt_log}"; then+ if { pnpm run build:desktop && pnpm exec electron-builder --mac --publish never \+ --config.extraMetadata.version="${BUILD_VERSION}" \+ --config.publish.channel="${BUILD_CHANNEL}" ; } 2>&1 | tee "${attempt_log}"; thenecho "::endgroup::"echo "electron-builder succeeded on attempt ${attempt}."break@@ -454,7 +705,7 @@ jobs:exit 1fiif [ "${attempt}" -ge "${max_attempts}" ]; then- echo "::error::electron-builder failed after ${max_attempts} attempts; the last failure matched a transient signing/notarize/upload signature but retries are exhausted."+ echo "::error::electron-builder failed after ${max_attempts} attempts; the last failure matched a transient signing/notarize signature but retries are exhausted."exit 1fibackoff=$((attempt * 30))@@ -464,17 +715,11 @@ jobs:done# FR5b — smoke the signed DMG before anything about this release becomes- # visible or installable. This is the only point in the cascade where the- # artifact exists AND nothing has shipped yet: the Release is still a- # draft, npm has not moved, and the announcements have not posted. A- # failure here leaves all three exactly as they are.- #- # A failure here suppresses the promote, the moved npm dispatch, and both- # announcements. Note the mechanism, because it is easy to get wrong:- # Actions injects the implicit `if: success()` only on steps that declare- # NO `if:`. The promote step relies on that. Every step below that DOES- # declare an `if:` must spell `success() &&` itself — omitting it is how- # a gated step fires anyway on a job that already failed.+ # visible or installable. Under the fan-in topology this job failing on+ # a smoke verdict means publish-assets never runs: no asset reaches the+ # Release, the draft never flips, npm never moves, and the announcements+ # never post. (That's strictly stronger than the pre-fan-in behavior,+ # where the mac assets were already uploaded before the smoke ran.)## The gate is skipped when the checked-out ref predates it. On the# cascade path this job checks out `client_payload.ref` — a tag pointing@@ -506,16 +751,17 @@ jobs:fi# The harness is CI tooling, not release content, so take it from the# workflow's own SHA rather than the release checkout — same reasoning- # as the two payload builders further down. Without this, a fix to the- # copy logic only reaches tags cut AFTER it lands, so every tag- # already cut stays permanently unreleasable: promote-stable tags the- # stable at the beta's SHA, and a soaked beta is by definition older- # than the fix. Overlaying only these two files keeps the config and- # the smoke tests themselves pinned to the release, which is right —- # they assert the app's behavior. Deliberately AFTER the absent-gate- # check above, so a ref predating the harness still releases ungated- # rather than being newly gated by a file it never carried.- # Best-effort: on failure keep the tag's copy rather than block.+ # as the finalize/alert jobs, which check out $GITHUB_SHA outright.+ # Without this, a fix to the copy logic only reaches tags cut AFTER it+ # lands, so every tag already cut stays permanently unreleasable:+ # promote-stable tags the stable at the beta's SHA, and a soaked beta+ # is by definition older than the fix. Overlaying only these two files+ # keeps the config and the smoke tests themselves pinned to the+ # release, which is right — they assert the app's behavior.+ # Deliberately AFTER the absent-gate check above, so a ref predating+ # the harness still releases ungated rather than being newly gated by+ # a file it never carried. Best-effort: on failure keep the tag's+ # copy rather than block.if git fetch --depth=1 origin "$GITHUB_SHA" >/dev/null 2>&1 &&git checkout "$GITHUB_SHA" -- "$DRIVER" .github/scripts/dmg-mount.mjs 2>/dev/null; thenecho "::notice::Smoke harness taken from ${GITHUB_SHA} rather than ${RELEASE_TAG}."@@ -538,17 +784,649 @@ jobs:# on both non-pass verdicts without any branching here.node "$DRIVER" "$DMG"+ # Stage the smoked outputs for the fan-in publisher. The channel+ # manifest glob (`*-mac.yml`) matches exactly the file the channel flag+ # produced (latest-mac.yml or beta-mac.yml) — electron-builder writes no+ # other `-mac.yml` into dist-desktop. This artifact doubles as the+ # 14-day audit trail the old flow kept a separate upload for.+ - name: Upload macOS release assets for the fan-in publisher+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: macos-release-assets+ path: |+ packages/desktop/dist-desktop/*.dmg+ packages/desktop/dist-desktop/*.dmg.blockmap+ packages/desktop/dist-desktop/*-mac.zip+ packages/desktop/dist-desktop/*-mac.zip.blockmap+ packages/desktop/dist-desktop/*-mac.yml+ retention-days: 14+ if-no-files-found: error++ build-windows:+ needs: prepare+ runs-on: windows-latest+ timeout-minutes: 45+ permissions:+ # See build-macos — packaging jobs are read-only by design.+ contents: read+ defaults:+ run:+ shell: bash+ steps:+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2+ with:+ ref: ${{ github.event.client_payload.ref || github.ref }}++ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0+ with:+ node-version: "24"++ - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5+ - name: Get pnpm store directory+ run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_ENV"+ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: ${{ env.STORE_PATH }}+ key: ${{ runner.os }}-ok-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-ok-pnpm-store-++ - name: Install dependencies+ env:+ # Rebuild native modules against Electron's Node ABI — mirrors the+ # mac job.+ ELECTRON_SKIP_REBUILD: "0"+ run: pnpm install --frozen-lockfile++ - name: Download workspace bundle+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v5.0.0+ with:+ name: workspace-bundle+ path: packages/++ # Defense-in-depth alongside `--config.extraMetadata.version`: keeps any+ # on-disk package.json read during electron-vite's build in agreement+ # with the tag. The cli/dist inside the workspace bundle already carries+ # prepare's override.+ - name: Override fixed-group versions on disk (zero-commit-bump cadence)+ env:+ VERSION: ${{ needs.prepare.outputs.version }}+ run: |+ set -euo pipefail+ for pkg in cli core server app desktop; do+ f="packages/${pkg}/package.json"+ jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"+ mv "${f}.tmp" "$f"+ done+ echo "All fixed-group package.json files now at ${VERSION} (in-memory only)."++ # Both keyring arch prebuilds (x64 + arm64) must be present in the+ # hoisted node_modules before electron-builder copies them into+ # cli/node_modules (win.extraResources) — pnpm installed only the+ # host-matching one.+ - name: Prepare cross-arch keyring prebuilds+ working-directory: packages/desktop+ run: node scripts/prepare-platform-natives.mjs++ # Stage @parcel/watcher onto the bundled CLI's module path. This workflow+ # invokes electron-builder directly (not the build:win npm script, which+ # DOES run this), so the step must be explicit here or the packaged app+ # ships without @parcel/watcher on the CLI path and the server degrades+ # to chokidar (#760). Stages only the host-arch binary today; the+ # other-arch artifact uses the (subfolder-correct) chokidar fallback —+ # see scripts/stage-parcel-watcher.mjs.+ - name: Stage @parcel/watcher for the bundled CLI+ working-directory: packages/desktop+ run: node scripts/stage-parcel-watcher.mjs++ - name: Build desktop main/preload/renderer+ working-directory: packages/desktop+ run: pnpm run build:desktop++ # Signing is REQUIRED here, unlike desktop-build-win-linux.yml's+ # optional-signing QA builds — see the workflow header for why unsigned+ # Windows installers are never published. Secrets: AZURE_TENANT_ID /+ # AZURE_CLIENT_ID / AZURE_CLIENT_SECRET; repo variables:+ # AZURE_SIGNING_ENDPOINT / AZURE_SIGNING_ACCOUNT / AZURE_SIGNING_PROFILE+ # / AZURE_SIGNING_PUBLISHER (Azure Trusted Signing endpoint URL,+ # code-signing account name, certificate profile name, certificate+ # subject CN — procurement outputs). electron-builder's Azure path reads+ # the three AZURE_* env vars via @azure/identity's EnvironmentCredential;+ # the four azureSignOptions fields address the signing account. All FOUR+ # fields are schema-required (app-builder-lib scheme.json,+ # WindowsAzureSigningConfiguration.required) — omit one and+ # validateConfig rejects the whole configuration before packaging;+ # release-cascade-shape.test.mjs pins this flag set against the schema.+ #+ # BUILD_VERSION / BUILD_CHANNEL ride in as env rather than being+ # interpolated into the script text: the tag they derive from arrives via+ # client_payload, and env-var expansion cannot become shell syntax the+ # way `${{ }}` textual splicing can (GitHub's security-hardening+ # guidance).+ - name: Package NSIS installers (x64 + arm64, signed)+ working-directory: packages/desktop+ env:+ AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}+ AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}+ AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}+ AZURE_SIGNING_ENDPOINT: ${{ vars.AZURE_SIGNING_ENDPOINT }}+ AZURE_SIGNING_ACCOUNT: ${{ vars.AZURE_SIGNING_ACCOUNT }}+ AZURE_SIGNING_PROFILE: ${{ vars.AZURE_SIGNING_PROFILE }}+ AZURE_SIGNING_PUBLISHER: ${{ vars.AZURE_SIGNING_PUBLISHER }}+ BUILD_VERSION: ${{ needs.prepare.outputs.version }}+ BUILD_CHANNEL: ${{ needs.prepare.outputs.channel }}+ run: |+ set -euo pipefail+ missing=()+ [[ -n "${AZURE_TENANT_ID:-}" ]] || missing+=(AZURE_TENANT_ID)+ [[ -n "${AZURE_CLIENT_ID:-}" ]] || missing+=(AZURE_CLIENT_ID)+ [[ -n "${AZURE_CLIENT_SECRET:-}" ]] || missing+=(AZURE_CLIENT_SECRET)+ [[ -n "${AZURE_SIGNING_ENDPOINT:-}" ]] || missing+=(AZURE_SIGNING_ENDPOINT)+ [[ -n "${AZURE_SIGNING_ACCOUNT:-}" ]] || missing+=(AZURE_SIGNING_ACCOUNT)+ [[ -n "${AZURE_SIGNING_PROFILE:-}" ]] || missing+=(AZURE_SIGNING_PROFILE)+ [[ -n "${AZURE_SIGNING_PUBLISHER:-}" ]] || missing+=(AZURE_SIGNING_PUBLISHER)+ if [[ ${#missing[@]} -gt 0 ]]; then+ echo "::error::Cannot publish unsigned Windows installers — missing Azure Trusted Signing config: ${missing[*]}. Set the AZURE_* secrets + AZURE_SIGNING_* repo variables (see the workflow header), or use desktop-build-win-linux.yml for unsigned internal-QA builds."+ exit 1+ fi+ echo "::notice::Azure Trusted Signing credentials present — building SIGNED installers."+ pnpm exec electron-builder --win --publish never \+ --config.extraMetadata.version="${BUILD_VERSION}" \+ --config.publish.channel="${BUILD_CHANNEL}" \+ --config.win.azureSignOptions.endpoint="${AZURE_SIGNING_ENDPOINT}" \+ --config.win.azureSignOptions.codeSigningAccountName="${AZURE_SIGNING_ACCOUNT}" \+ --config.win.azureSignOptions.certificateProfileName="${AZURE_SIGNING_PROFILE}" \+ --config.win.azureSignOptions.publisherName="${AZURE_SIGNING_PUBLISHER}"++ # Fail before staging an installer that cannot start. An asar packed+ # without `node_modules` produces a binary that dies on its first bare+ # import, before `app.ready` — no window, no dialog.+ - name: Assert the packaged asar carries its dependencies+ working-directory: packages/desktop+ run: node scripts/assert-asar-complete.mjs dist-desktop "windows installers"++ # Both arch payloads must carry the updater config, with the channel the+ # tag dictates. A missing app-update.yml ships an installer whose app+ # can never self-update (electron-updater fails its config load, once+ # per boot, forever); a wrong channel violates the channel-mirror+ # invariant (a beta install auto-updating onto stable or vice versa).+ # Verified here at the staging dirs electron-builder packed from.+ - name: Assert app-update.yml is present and channel-correct+ working-directory: packages/desktop+ env:+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ run: |+ set -euo pipefail+ for dir in dist-desktop/win-unpacked dist-desktop/win-arm64-unpacked; do+ f="${dir}/resources/app-update.yml"+ if [[ ! -f "$f" ]]; then+ echo "::error::${f} is missing — the packaged app would never self-update. electron-builder writes it from the publish config; check the publish block + channel flag."+ exit 1+ fi+ if ! grep -q "channel: ${CHANNEL}" "$f"; then+ echo "::error::${f} does not carry 'channel: ${CHANNEL}' — channel-mirror invariant violated. Contents:"+ cat "$f"+ exit 1+ fi+ done+ echo "app-update.yml present + channel=${CHANNEL} in both arch payloads."++ # electron-updater's Windows manifest covers BOTH arches in one file+ # (the updater picks the entry whose filename embeds process.arch).+ # `nsis.differentialPackage: false` means no `.exe.blockmap` exists —+ # the exact-glob keeps `if-no-files-found: error` honest about that.+ - name: Upload Windows release assets for the fan-in publisher+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: windows-release-assets+ path: |+ packages/desktop/dist-desktop/*Setup-x64.exe+ packages/desktop/dist-desktop/*Setup-arm64.exe+ packages/desktop/dist-desktop/${{ needs.prepare.outputs.channel }}.yml+ retention-days: 14+ if-no-files-found: error++ # Two cells, each on a NATIVE runner for its arch. Cross-compiling the arm64+ # native deps from an x64 host is impractical (pnpm installs only the+ # host-matching `@parcel/watcher-*` prebuild, and the Linux build skips+ # @electron/rebuild by design — see electron-builder.linux.yml), so the+ # arm64 installers are built on GitHub's arm64 Linux runner where pnpm+ # installs the arm64 prebuilds directly.+ build-linux:+ needs: prepare+ runs-on: ${{ matrix.runner }}+ timeout-minutes: 45+ permissions:+ # See build-macos — packaging jobs are read-only by design.+ contents: read+ defaults:+ run:+ shell: bash+ strategy:+ # One arch failing must not cancel the other: the arch that built still+ # lands in its run artifact, so a re-run (or manual recovery) only has+ # to repeat the arch that failed. publish-assets still requires BOTH.+ fail-fast: false+ matrix:+ include:+ - runner: ubuntu-latest+ arch: x64+ targets: deb:x64 rpm:x64+ unpacked_dir: linux-unpacked+ - runner: ubuntu-24.04-arm+ arch: arm64+ targets: deb:arm64 rpm:arm64+ unpacked_dir: linux-arm64-unpacked+ steps:+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2+ with:+ ref: ${{ github.event.client_payload.ref || github.ref }}++ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0+ with:+ node-version: "24"++ - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5+ - name: Get pnpm store directory+ run: echo "STORE_PATH=$(pnpm store path --silent)" >> "$GITHUB_ENV"+ # `runner.arch` is part of the key: both Linux cells report+ # `runner.os == 'Linux'`, and a store populated on x64 carries none of the+ # arm64 prebuilds (and vice versa), so a shared key would thrash the cache+ # between cells on every run.+ - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4+ with:+ path: ${{ env.STORE_PATH }}+ key: ${{ runner.os }}-${{ runner.arch }}-ok-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}+ restore-keys: |+ ${{ runner.os }}-${{ runner.arch }}-ok-pnpm-store-++ - name: Install dependencies+ env:+ # Rebuild native modules against Electron's Node ABI — mirrors the+ # mac job. (The packaging pass itself skips @electron/rebuild via+ # the Linux overlay config; this install-time rebuild is what+ # provides the ABI-correct prebuilds the overlay's rationale+ # depends on.)+ ELECTRON_SKIP_REBUILD: "0"+ run: pnpm install --frozen-lockfile++ - name: Download workspace bundle+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v5.0.0+ with:+ name: workspace-bundle+ path: packages/++ # Defense-in-depth alongside `extraMetadata.version` — see the Windows+ # job's twin step.+ - name: Override fixed-group versions on disk (zero-commit-bump cadence)+ env:+ VERSION: ${{ needs.prepare.outputs.version }}+ run: |+ set -euo pipefail+ for pkg in cli core server app desktop; do+ f="packages/${pkg}/package.json"+ jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"+ mv "${f}.tmp" "$f"+ done+ echo "All fixed-group package.json files now at ${VERSION} (in-memory only)."++ - name: Prepare cross-arch keyring prebuilds+ working-directory: packages/desktop+ run: node scripts/prepare-platform-natives.mjs++ # Stage @parcel/watcher onto the bundled CLI's module path — see the+ # Windows job's twin step for the full rationale (#760).+ - name: Stage @parcel/watcher for the bundled CLI+ working-directory: packages/desktop+ run: node scripts/stage-parcel-watcher.mjs++ - name: Build desktop main/preload/renderer+ working-directory: packages/desktop+ run: pnpm run build:desktop++ # electron-builder downloads its own `fpm`, but fpm shells out to the+ # host's `rpmbuild` to assemble an `.rpm` — and an Ubuntu runner has no+ # rpm tooling preinstalled, so the rpm target dies with "Can't find+ # rpmbuild". Ubuntu's `rpm` package carries /usr/bin/rpmbuild. The deb+ # target needs nothing extra, so this is the only apt step in the job.+ - name: Install rpmbuild (fpm's rpm backend)+ run: |+ set -euo pipefail+ sudo apt-get update+ sudo apt-get install -y rpm++ # The Linux packaging pass needs THREE config inputs at once: the+ # `npmRebuild: false` overlay (electron-builder.linux.yml — a top-level+ # option that CANNOT be passed as a CLI flag, because yargs leaves+ # `-c.npmRebuild=false` as the string "false" and the packager's strict+ # `=== false` ignores it), the channel, and the version override.+ # Mixing a `--config <file>` with `--config.dot=flags` on one command+ # line is yargs-merge territory nobody should trust a release to, so+ # compose them the deterministic way: generate a release overlay that+ # `extends` the Linux overlay (which itself extends the base config)+ # and carries the channel + version inline. A broken extends chain+ # fails LOUD (the node-liblzma -Werror explosion the Linux overlay's+ # header documents), never silently.+ #+ # The `publish` block must restate the full provider entry — `extends`+ # replaces list-valued keys wholesale rather than merging them.+ - name: Generate the release overlay config (channel + version)+ working-directory: packages/desktop+ env:+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ VERSION: ${{ needs.prepare.outputs.version }}+ run: |+ set -euo pipefail+ cat > electron-builder.release-linux.yml <<EOF+ extends: file:./electron-builder.linux.yml+ extraMetadata:+ version: ${VERSION}+ publish:+ - provider: github+ owner: inkeep+ repo: open-knowledge+ channel: ${CHANNEL}+ EOF+ cat electron-builder.release-linux.yml++ # Each cell packages only its own arch, on a runner of that arch — so the+ # `.deb` / `.rpm` ship the matching `@parcel/watcher` / `@napi-rs/keyring`+ # prebuilds rather than degrading file-watching to chokidar. The deb and+ # rpm targets need `fpm`; electron-builder 26 downloads a native+ # `linux-arm64v8` build of it (see app-builder-lib's `getFpmPath`), so no+ # emulation or system fpm is involved.+ - name: Package ${{ matrix.targets }}+ working-directory: packages/desktop+ run: |+ pnpm exec electron-builder --linux ${{ matrix.targets }} --publish never \+ --config electron-builder.release-linux.yml++ # Fail before staging an installer that cannot start (see the Windows+ # step for the full rationale). This is the control that would have+ # caught the 0.42.2 arm64 deb, which installed cleanly and then died on+ # `Cannot find package 'pino'` with no user-visible signal at all.+ - name: Assert the packaged asar carries its dependencies+ working-directory: packages/desktop+ run: node scripts/assert-asar-complete.mjs dist-desktop "linux ${{ matrix.arch }} installers"++ # Same guard as the Windows job, plus Linux's package-type stamp:+ # electron-updater's Linux entry point picks DebUpdater/RpmUpdater by+ # reading `resources/package-type` (written per-target by+ # electron-builder's FpmTarget). Without it the updater falls back to+ # the AppImage path and error-logs a doomed feed check on every boot.+ # package-type in the shared staging dir holds whichever target packed+ # LAST — each package's own archive captured its correct value at pack+ # time — so assert existence, not content.+ - name: Assert app-update.yml + package-type are present and channel-correct+ working-directory: packages/desktop+ env:+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ UNPACKED_DIR: ${{ matrix.unpacked_dir }}+ run: |+ set -euo pipefail+ f="dist-desktop/${UNPACKED_DIR}/resources/app-update.yml"+ if [[ ! -f "$f" ]]; then+ echo "::error::${f} is missing — the packaged app would never self-update. electron-builder writes it from the publish config; check the release overlay."+ exit 1+ fi+ if ! grep -q "channel: ${CHANNEL}" "$f"; then+ echo "::error::${f} does not carry 'channel: ${CHANNEL}' — channel-mirror invariant violated. Contents:"+ cat "$f"+ exit 1+ fi+ pt="dist-desktop/${UNPACKED_DIR}/resources/package-type"+ if [[ ! -f "$pt" ]]; then+ echo "::error::${pt} is missing — electron-updater cannot select its deb/rpm installer class without it and falls back to the (dead) AppImage path."+ exit 1+ fi+ echo "app-update.yml (channel=${CHANNEL}) + package-type present in ${UNPACKED_DIR}."++ # deb + rpm + the per-arch channel manifest. electron-builder names the+ # Linux manifest by arch: `latest-linux.yml` (x64) /+ # `latest-linux-arm64.yml` (arm64), or beta-* on the beta channel —+ # which is exactly the name electron-updater's provider computes from+ # process.arch on the client, and why each cell uploads a distinct+ # manifest with no collision. The deb and rpm entries share one+ # manifest per arch (the updater picks by file extension).+ - name: Upload Linux ${{ matrix.arch }} release assets for the fan-in publisher+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1+ with:+ name: linux-${{ matrix.arch }}-release-assets+ path: |+ packages/desktop/dist-desktop/*.deb+ packages/desktop/dist-desktop/*.rpm+ packages/desktop/dist-desktop/${{ needs.prepare.outputs.channel }}-linux*.yml+ retention-days: 14+ if-no-files-found: error++ # The single publication point: nothing above this job touches the GitHub+ # Release. Downloads every platform's staged assets, asserts the complete+ # cross-platform inventory, uploads, then re-queries the Release and+ # verifies what actually landed. Re-running just this job (via a workflow+ # re-run of failed jobs) retries a flaky upload without re-running any+ # 30-minute signed build; `--clobber` makes the retry idempotent.+ publish-assets:+ needs: [prepare, build-macos, build-windows, build-linux]+ runs-on: ubuntu-latest+ # Sized to the upload retry envelope: 3 bounded 300s attempts + backoffs+ # (see the upload step) plus download/verify overhead.+ timeout-minutes: 20+ permissions:+ # gh release upload needs write; the workflow default is read-only.+ contents: write+ defaults:+ run:+ shell: bash+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ # No checkout in this job — GH_REPO tells gh which repo the release+ # lives in.+ GH_REPO: ${{ github.repository }}+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ VERSION: ${{ needs.prepare.outputs.version }}+ steps:+ - name: Download all platform release assets+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v5.0.0+ with:+ pattern: "*-release-assets"+ merge-multiple: true+ path: release-assets++ # The full expected inventory, by exact filename — defined ONCE, here,+ # and consumed by both the pre-upload assert and the post-upload verify+ # (a drift between the two would either confuse-fail the assert or let+ # the verify silently check a different set than was asserted; this+ # single definition is the enforcement point for "never publish a+ # partial cross-platform release"). Blockmaps exist ONLY for the mac+ # artifacts: Windows has `nsis.differentialPackage: false` (no+ # .exe.blockmap — see electron-builder.yml for the Nsis7z-on-ARM+ # rationale) and deb/rpm never produce them. Expecting them generically+ # would fail every run; expecting too little would let a partial release+ # publish. The mac zip is the one versioned filename (the updater's+ # swap artifact); everything user-facing is versionless so+ # `releases/latest/download/...` URLs stay stable.+ - name: Define the expected asset inventory+ run: |+ set -euo pipefail+ {+ echo "EXPECTED_ASSETS<<OK_INVENTORY_EOF"+ echo "OpenKnowledge-arm64.dmg"+ echo "OpenKnowledge-arm64.dmg.blockmap"+ echo "OpenKnowledge-${VERSION}-arm64-mac.zip"+ echo "OpenKnowledge-${VERSION}-arm64-mac.zip.blockmap"+ echo "${CHANNEL}-mac.yml"+ echo "OpenKnowledge-Setup-x64.exe"+ echo "OpenKnowledge-Setup-arm64.exe"+ echo "${CHANNEL}.yml"+ echo "OpenKnowledge-amd64.deb"+ echo "OpenKnowledge-arm64.deb"+ echo "OpenKnowledge-x86_64.rpm"+ echo "OpenKnowledge-aarch64.rpm"+ echo "${CHANNEL}-linux.yml"+ echo "${CHANNEL}-linux-arm64.yml"+ } >> "$GITHUB_ENV"++ - name: Assert the complete cross-platform inventory+ run: |+ set -euo pipefail+ mapfile -t expected <<<"$EXPECTED_ASSETS"+ echo "Staged files:"+ ls -la release-assets/+ missing=()+ for f in "${expected[@]}"; do+ [[ -f "release-assets/${f}" ]] || missing+=("$f")+ done+ if [[ ${#missing[@]} -gt 0 ]]; then+ echo "::error::Refusing to publish an incomplete release — missing from the staged assets: ${missing[*]}"+ exit 1+ fi+ # Unexpected extras are an error too: a stray builder-debug.yml or+ # half-renamed artifact reaching the Release would be served to+ # real update clients.+ for f in release-assets/*; do+ base="$(basename "$f")"+ found=0+ for e in "${expected[@]}"; do+ [[ "$base" == "$e" ]] && found=1 && break+ done+ if [[ "$found" -eq 0 ]]; then+ echo "::error::Unexpected file staged for release upload: ${base}. Add it to the expected inventory or fix the packaging job's upload globs."+ exit 1+ fi+ done+ echo "All ${#expected[@]} expected assets staged, no extras."++ # Idempotent by construction: `--clobber` replaces same-named assets, so+ # a retry after a partial upload converges instead of duplicating or+ # erroring. Bounded retry for GitHub's occasional 5xx / secondary-rate-+ # limit moods — the same class the old electron-builder publisher hit.+ # Backoff starts at 60s because GitHub documents the secondary-rate-+ # limit cooldown as 60–120s; a shorter retry lands inside the cooldown+ # and burns the attempt. Retry is unconditional (no transient-signature+ # allowlist like the mac build's): the upload is idempotent and cheap,+ # so the worst a non-retriable failure costs is ~3 minutes of sleeps+ # before the same loud exit — against which an allowlist would risk+ # fast-failing a retriable error it didn't anticipate.+ - name: Upload assets to the GitHub Release+ run: |+ # -e deliberately omitted: the while/if retry loop owns every exit+ # code explicitly; adding -e would abort the step on the first+ # failed attempt instead of retrying it.+ set -uo pipefail+ attempt=1+ max_attempts=3+ while true; do+ # `timeout` bounds a hung upload (headers accepted, body stalled)+ # so it becomes a retryable failure instead of silently eating+ # the whole job budget: 3×300s attempts + 60s+120s backoffs fit+ # the 20-minute job timeout with headroom.+ if timeout 300 gh release upload "$RELEASE_TAG" release-assets/* --clobber; then+ echo "Uploaded all assets to ${RELEASE_TAG} on attempt ${attempt}."+ break+ fi+ if [ "${attempt}" -ge "${max_attempts}" ]; then+ echo "::error::gh release upload failed after ${max_attempts} attempts."+ exit 1+ fi+ backoff=$((attempt * 60))+ echo "::warning::gh release upload attempt ${attempt} failed; retrying in ${backoff}s (secondary-rate-limit cooldown is 60-120s)."+ sleep "${backoff}"+ attempt=$((attempt + 1))+ done++ # Trust, then verify: re-query the Release and assert every expected+ # asset is actually attached. Catches the failure the upload's exit+ # code can't — an upload that "succeeded" onto the wrong release, or an+ # asset GitHub accepted and then dropped. Consumes the SAME+ # EXPECTED_ASSETS definition as the assert step above.+ - name: Verify the Release carries the full inventory+ run: |+ set -euo pipefail+ uploaded="$(gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name')"+ mapfile -t expected <<<"$EXPECTED_ASSETS"+ missing=()+ for f in "${expected[@]}"; do+ grep -qxF "$f" <<<"$uploaded" || missing+=("$f")+ done+ if [[ ${#missing[@]} -gt 0 ]]; then+ echo "::error::Post-upload verification failed — the Release is missing: ${missing[*]}"+ exit 1+ fi+ echo "Verified: all ${#expected[@]} assets attached to ${RELEASE_TAG}."++ # Everything after the assets are verified on the Release: the Downloads+ # table, the draft → published flip, the stable npm dispatch, and the+ # announcements. Runs from the workflow's own commit ($GITHUB_SHA), not the+ # release ref — every script here is CI tooling, not release content, and+ # a stable tag points at the promoted beta's commit, which can predate any+ # script this job references (v0.41.0 lost its announcement to exactly+ # that).+ finalize:+ needs: [prepare, build-macos, publish-assets]+ runs-on: ubuntu-latest+ timeout-minutes: 15+ permissions:+ # Body edit, draft→published flip, and the repository_dispatch POST all+ # need write; the workflow default is read-only.+ contents: write+ # The best-effort forward-link to the dispatched release.yml run calls+ # `gh run list` — same replace-semantics gap as prepare's staging: an+ # explicit permissions block drops the default actions scope, and+ # without it the link silently degrades to "(run link unresolved)".+ actions: read+ defaults:+ run:+ shell: bash+ env:+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ VERSION: ${{ needs.prepare.outputs.version }}+ steps:+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2++ # Marker-delimited (`<!-- ok-downloads:start/end -->`) so re-renders are+ # idempotent and the rest of the body — the changelog and the beta+ # cadence's hidden consumed-set marker, which compute-next-beta.mjs+ # reads back from the previous beta's body — passes through+ # byte-identical. The announcement steps below and+ # aggregate-stable-changelog.mjs each strip the block on their side.+ # Best-effort: a release with assets but no Downloads table is a+ # cosmetic gap, not a reason to strand the release as a draft.+ - name: Render the Downloads table into the release body+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ run: |+ set -uo pipefail+ RENDERER="scripts/render-release-downloads.mjs"+ if [[ ! -f "$RENDERER" ]]; then+ echo "::warning::${RENDERER} not found at ${GITHUB_SHA}; skipping the Downloads table."+ exit 0+ fi+ if ! gh release view "$RELEASE_TAG" --json body,assets > "$RUNNER_TEMP/release.json"; then+ echo "::warning::Could not fetch the release body for ${RELEASE_TAG}; skipping the Downloads table."+ exit 0+ fi+ if node "$RENDERER" --tag "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" \+ < "$RUNNER_TEMP/release.json" > "$RUNNER_TEMP/body.md"; then+ if gh release edit "$RELEASE_TAG" --notes-file "$RUNNER_TEMP/body.md"; then+ echo "Rendered the Downloads table into ${RELEASE_TAG}."+ else+ echo "::warning::gh release edit failed for ${RELEASE_TAG}; the release keeps its previous body."+ fi+ else+ echo "::warning::render-release-downloads.mjs failed for ${RELEASE_TAG}; the release keeps its previous body."+ fi+# Closes the publish-window race: release.yml / promote-stable.yml# create the GitHub Release as --draft so it stays out of the .atom- # feed until the channel manifest (beta-mac.yml / latest-mac.yml) is- # uploaded. This step flips the draft to published once the upload- # above has succeeded. Channel-mirror invariant: see+ # feed until every installer + channel manifest is attached. This step+ # flips the draft to published once publish-assets has verified the+ # full inventory. Channel-mirror invariant: see# packages/desktop/src/main/auto-updater.ts:336-356.- name: Promote draft release to publishedenv:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}- RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- CHANNEL: ${{ steps.channel.outputs.channel }}run: |set -euo pipefail# --latest is gated on the trigger event. On the cascade flow@@ -556,7 +1434,7 @@ jobs:# this run is for the freshly-published stable, so re-stamping# --latest is correct. On the manual recovery flow# (workflow_dispatch), the operator may be re-running for an- # OLDER tag (e.g., re-uploading a DMG for v0.4.0 after a later+ # OLDER tag (e.g., re-uploading assets for v0.4.0 after a later# v0.5.0 already became Latest). Unconditional --latest there# silently steals the Latest badge from the newer release.# Skip --latest on workflow_dispatch; the operator can@@ -579,19 +1457,10 @@ jobs:echo "Promoted ${RELEASE_TAG} to published (draft=false, latest=false; channel=${CHANNEL})."fi- # FR5b — the npm stable publish, moved here from promote-stable.yml so it- # sits downstream of the DMG smoke gate. promote-stable dispatched this- # before desktop-release even started, which meant npm `latest` could move- # for a release whose DMG later failed to build at all. Here it fires only- # after the DMG is built, smoked, and the Release has left draft.- #- # The payload shape is unchanged — same event type, same three field names- # — so release.yml's input contract is untouched. Only `dispatched_by`- # differs in value: it now names this run rather than the promote-stable- # run. `contents: write` (declared at the job) is the scope- # POST /repos/{}/dispatches needs, and repository_dispatch is GitHub's- # documented exemption to the rule that GITHUB_TOKEN-triggered events do- # not create workflow runs.+ # FR5b — the npm stable publish sits downstream of the DMG smoke gate+ # (build-macos fails on a bad verdict, which skips this whole job) AND+ # the full-inventory verification, so npm `latest` can only move for a+ # release every platform can actually install.## Gated the same way the --latest flip above is: beta cuts flow through# this same job on channel=beta and must never publish an npm stable, and@@ -600,26 +1469,24 @@ jobs:## `success() &&` is load-bearing, not decoration. Actions injects the# implicit `success()` only on steps with NO `if:`; write one and you own- # the whole predicate. Without it this step would fire after the smoke- # gate refused the release — publishing to npm exactly the artifact the- # gate rejected, which is the failure FR5b exists to prevent.+ # the whole predicate. Without it this step would fire even after an+ # earlier step in this job failed.- name: Trigger release.yml to publish stable to npm- if: success() && steps.channel.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'+ if: success() && needs.prepare.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'env:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}- STABLE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- STABLE_VERSION: ${{ steps.channel.outputs.version }}+ SMOKE_VERDICT: ${{ needs.build-macos.outputs.smoke_verdict }}run: |set -euo pipefailSELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)payload=$(jq -nc \- --arg ref "$STABLE_TAG" \- --arg version "$STABLE_VERSION" \+ --arg ref "$RELEASE_TAG" \+ --arg version "$VERSION" \--arg by "$SELF_URL" \'{event_type: "publish-stable", client_payload: {ref: $ref, version: $version, dispatched_by: $by}}')gh api -X POST "repos/${GITHUB_REPOSITORY}/dispatches" --input - <<<"$payload"- echo "Dispatched publish-stable to release.yml (ref=${STABLE_TAG}, version=${STABLE_VERSION}) after the DMG smoke gate passed."+ echo "Dispatched publish-stable to release.yml (ref=${RELEASE_TAG}, version=${VERSION}) after the smoke gate + full-inventory verification passed."# Best-effort forward-link to the release.yml run we just triggered.CHILD=""for _ in 1 2 3 4 5 6; do@@ -630,7 +1497,7 @@ jobs:done{echo "### Dispatched release.yml (npm publish)"- echo "- Gated on the DMG smoke verdict: \`${{ steps.dmg_smoke.outputs.verdict }}\`"+ echo "- Gated on the DMG smoke verdict: \`${SMOKE_VERDICT}\`"if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open release.yml)"; fi} >> "$GITHUB_STEP_SUMMARY"@@ -643,11 +1510,11 @@ jobs:# Announce STABLE releases to Slack. Gated on channel=latest so betas# stay silent — every *-beta.N cut also flows through this job (on- # channel=beta) and must not post (see Detect channel step above).- # Placed AFTER the promote step and gated on success() so we only- # announce a release that is actually published (draft=false), never a- # stuck draft. Skipped on the workflow_dispatch recovery flow so a- # manual DMG re-upload for an older tag does not re-announce it.+ # channel=beta) and must not post. Placed AFTER the promote step and+ # gated on success() so we only announce a release that is actually+ # published (draft=false), never a stuck draft. Skipped on the+ # workflow_dispatch recovery flow so a manual asset re-upload for an+ # older tag does not re-announce it.## The webhook URL lives in the SLACK_WEBHOOK_URL secret on# inkeep/open-knowledge. When it is absent (a fork, or before the@@ -656,12 +1523,10 @@ jobs:# published, so the announcement is strictly best-effort and must# never fail an otherwise-successful release.- name: Announce stable release to Slack- if: success() && steps.channel.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'+ if: success() && needs.prepare.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'env:SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}- RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- VERSION: ${{ steps.channel.outputs.version }}run: |set -euo pipefailif [[ -z "${SLACK_WEBHOOK_URL:-}" ]]; then@@ -671,7 +1536,8 @@ jobs:RELEASE_URL="https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}"# Inline the notes so the channel reads what shipped without clicking# through. A failed fetch is not fatal: the builder degrades to the- # header + link message on empty input.+ # header + link message on empty input. The builder strips the+ # Downloads block + consumed-set marker on its side.NOTES="$(gh release view "$RELEASE_TAG" --json body --jq '.body' 2>/dev/null || true)"# The builder emits the whole Block Kit payload as JSON (so $VERSION /# $RELEASE_URL are JSON-escaped — a stray quote in a tag would@@ -679,32 +1545,15 @@ jobs:# to Slack mrkdwn, and keeps every section under Slack's 3000-char cap.# `text` is the notification/a11y fallback Slack recommends alongside# blocks. Unit-tested in scripts/build-slack-release-payload.test.mjs.- # Take the builder from the same commit as this workflow file, NOT- # from the checked-out release tag. On repository_dispatch GitHub- # runs the workflow from the default branch while the job checks out- # client_payload.ref, and a stable tag points at the promoted beta's- # commit, which can predate any script the workflow references.- # v0.41.0 hit exactly that: the tag was older than the builder, node- # failed with "Cannot find module", and the announcement was lost.- # Reading the blob at $GITHUB_SHA keeps tool and workflow in lockstep- # for any tag age. Fetched into RUNNER_TEMP so the release checkout- # this job just published from stays untouched. Do not swap this for- # a second actions/checkout: a `path` input re-homes knip's analysis- # of this workflow to that directory, and every binary the file- # invokes (electron-builder) then fails to resolve against a- # workspace, which fails `pnpm run knip`.- BUILDER="${RUNNER_TEMP}/build-slack-release-payload.mjs"- if ! git fetch --depth=1 origin "$GITHUB_SHA" >/dev/null 2>&1 ||- ! git show "${GITHUB_SHA}:scripts/build-slack-release-payload.mjs" > "$BUILDER" 2>/dev/null; then- rm -f "$BUILDER"- fi+ # This job checked out $GITHUB_SHA, so the builder is always the+ # workflow's own copy — no tag-age dance needed here.payload="$(printf '%s' "$NOTES" \- | node "$BUILDER" --version "$VERSION" --url "$RELEASE_URL" \+ | node scripts/build-slack-release-payload.mjs --version "$VERSION" --url "$RELEASE_URL" \|| true)"- # Never go silent. If the builder is missing or fails, post the- # link-only message instead of nothing: losing the notes is a- # degradation, losing the whole announcement is an outage, and the- # step exiting 0 makes that outage invisible.+ # Never go silent. If the builder fails, post the link-only message+ # instead of nothing: losing the notes is a degradation, losing the+ # whole announcement is an outage, and the step exiting 0 makes that+ # outage invisible.if [[ -z "$payload" ]]; thenecho "::warning::Slack notes builder unavailable for ${RELEASE_TAG}; falling back to the link-only announcement."payload="$(jq -n \@@ -732,12 +1581,10 @@ jobs:# Announce STABLE releases to Discord- name: Announce stable release to Discord- if: success() && steps.channel.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'+ if: success() && needs.prepare.outputs.channel == 'latest' && github.event_name != 'workflow_dispatch'env:DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}- RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- VERSION: ${{ steps.channel.outputs.version }}run: |set -euo pipefailif [[ -z "${DISCORD_WEBHOOK_URL:-}" ]]; then@@ -746,6 +1593,10 @@ jobs:fiRELEASE_URL="https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}"NOTES="$(gh release view "$RELEASE_TAG" --json body --jq '.body' 2>/dev/null || true)"+ # Discord renders no markdown tables; strip the marker-delimited+ # Downloads block (the release page keeps it — the embed links+ # there).+ NOTES="$(printf '%s' "$NOTES" | sed '/<!-- ok-downloads:start -->/,/<!-- ok-downloads:end -->/d')"NOTES_LIMIT=3500if [[ "${#NOTES}" -gt "$NOTES_LIMIT" ]]; thenNOTES="${NOTES:0:$NOTES_LIMIT}…"@@ -774,71 +1625,69 @@ jobs:echo "::warning::Discord announcement failed for ${RELEASE_TAG} (release is published; notification is best-effort)."fi- # Lightweight discoverability for stuck-draft state when the promote- # step (or the build/upload step before it) fails. NOT a substitute- # for the full paging-design observability deferred in the PR body —- # this is a zero-cost log marker that makes stuck drafts findable via- # GitHub Actions log search using the STUCK-DRAFT tag. Operators- # bisecting a missing release can grep workflow logs for the tag,- # then run the recovery command in the message.- # FR5c — page the release channel when the gate refuses a release.- # Without this a blocked release is silent: the Release simply never- # appears and nobody learns why until someone goes looking. The alert is- # deliberately loud and visually unlike the routine+ # Fires precisely when the rest of the pipeline did not finish. FR5c — page+ # the release channel when a stable release is blocked; the STUCK-DRAFT+ # marker keeps failed betas findable via log search. Lives in its own job+ # (not a `failure()` step inside finalize) because a packaging job failing+ # SKIPS finalize entirely — skipped steps can't alert.+ alert:+ needs: [prepare, build-macos, build-windows, build-linux, publish-assets, finalize]+ # Job-level failure() is true when any job in `needs` failed. prepare+ # failing before channel detection leaves the channel output empty; the+ # steps below treat that as "not stable" (FR5c skips, STUCK-DRAFT still+ # logs).+ if: failure()+ runs-on: ubuntu-latest+ timeout-minutes: 10+ permissions:+ # Reads scripts from the checkout, posts to a webhook — nothing more.+ contents: read+ defaults:+ run:+ shell: bash+ env:+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ CHANNEL: ${{ needs.prepare.outputs.channel }}+ steps:+ # $GITHUB_SHA — CI tooling, not release content (see finalize's header).+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2++ # FR5c — page the release channel when the gate refuses a stable+ # release. Without this a blocked release is silent: the Release simply+ # never appears and nobody learns why until someone goes looking. The+ # alert is deliberately loud and visually unlike the routine# "🎉 OpenKnowledge X.Y.Z released" post that lands in the same channel.#- # `if: failure()` (not `success()`) — this is the one step that must run- # precisely when the rest of the job did not. It fires for ANY job- # failure at or after the smoke gate; the payload reports the smoke- # verdict when there is one and falls back to `error` when the failure- # came from elsewhere, which is the honest reading (the gate never- # returned a product verdict).+ # Stable only, matching the smoke gate's own scope. A failed beta cut+ # keeps the STUCK-DRAFT warning below; paging the release channel for+ # every beta hiccup would train readers to ignore the alert.## No new secret: SLACK_WEBHOOK_URL already exists and is consumed by the- # announcement step above with the same unset -> ::notice:: -> skip- # tolerance.+ # announcement step with the same unset -> ::notice:: -> skip tolerance.## Slack only, deliberately — rationale lives in the module docstring of# .github/scripts/build-smoke-alert-payload.mjs. Ratcheted by# build-smoke-alert-payload.test.mjs so this cannot drift back.- name: Alert on a blocked release (FR5c)- # Stable only, matching the gate's own scope. A failed beta cut keeps- # its existing STUCK-DRAFT warning below; paging the release channel for- # every beta hiccup would train readers to ignore the alert.- if: failure() && steps.channel.outputs.channel == 'latest'+ if: needs.prepare.outputs.channel == 'latest'env:SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}- RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- SMOKE_VERDICT: ${{ steps.dmg_smoke.outputs.verdict }}- SMOKE_REASON: ${{ steps.dmg_smoke.outputs.reason }}+ SMOKE_VERDICT: ${{ needs.build-macos.outputs.smoke_verdict }}+ SMOKE_REASON: ${{ needs.build-macos.outputs.smoke_reason }}run: |set -uo pipefail# A skipped gate (ref predates the harness) is not a blocked release,- # and neither is a failure before the DMG was even built. Both leave- # the verdict empty or 'skipped'; report those as `error` so the- # message never implies the app itself failed a test it never ran.+ # and neither is a failure before the DMG was even built — or a+ # Windows/Linux packaging failure, where the smoke never speaks at+ # all. All of those leave the verdict empty or 'skipped'; report+ # them as `error` so the message never implies the app itself+ # failed a test it never ran.VERDICT="${SMOKE_VERDICT:-}"if [[ "$VERDICT" != "fail" ]]; thenVERDICT="error"fi- REASON="${SMOKE_REASON:-the release job failed before the smoke gate reached a verdict}"+ REASON="${SMOKE_REASON:-the release pipeline failed before completing — see the run}"RUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"- # Take the builder from the same commit as this workflow file, NOT- # from the checked-out release tag. On repository_dispatch GitHub runs- # the workflow from the default branch while the job checks out- # client_payload.ref, and a stable tag points at the promoted beta's- # commit, which can predate any script the workflow references.- # v0.41.0 hit exactly that and lost its announcement to- # "Cannot find module". Fetched into RUNNER_TEMP so the release- # checkout stays untouched.- BUILDER="${RUNNER_TEMP}/build-smoke-alert-payload.mjs"- if ! git fetch --depth=1 origin "$GITHUB_SHA" >/dev/null 2>&1 ||- ! git show "${GITHUB_SHA}:.github/scripts/build-smoke-alert-payload.mjs" > "$BUILDER" 2>/dev/null; then- rm -f "$BUILDER"- fi-- # `${var^}` (bash 4) is deliberately avoided: macOS runners ship- # bash 3.2, so the label is passed in already-cased instead.post() {local webhook="$1" label="$2"if [[ -z "$webhook" ]]; then@@ -846,18 +1695,20 @@ jobs:return 0filocal payload=""- if [[ -f "$BUILDER" ]]; then- payload="$(node "$BUILDER" --tag "$RELEASE_TAG" \+ # This job checked out $GITHUB_SHA, so the builder is the+ # workflow's own copy when it exists at all.+ if [[ -f .github/scripts/build-smoke-alert-payload.mjs ]]; then+ payload="$(node .github/scripts/build-smoke-alert-payload.mjs --tag "$RELEASE_TAG" \--verdict "$VERDICT" --reason "$REASON" --run-url "$RUN_URL" || true)"fiif [[ -z "$payload" ]]; then# Never go silent. Losing the formatting is a degradation; losing# the page is the outage this step exists to prevent.echo "::warning::Smoke-alert payload builder unavailable for ${RELEASE_TAG}; sending the plain-text alert."- payload="$(jq -nc --arg t "🚨 RELEASE BLOCKED: ${RELEASE_TAG} DMG smoke ${VERDICT} — nothing shipped. ${REASON} ${RUN_URL}" '{text: $t}')"+ payload="$(jq -nc --arg t "🚨 RELEASE BLOCKED: ${RELEASE_TAG} pipeline ${VERDICT} — nothing shipped. ${REASON} ${RUN_URL}" '{text: $t}')"fi# The failing curl sits in an `if` condition, so a webhook outage- # routes to the warning instead of masking the smoke failure.+ # routes to the warning instead of masking the failure.if curl -sS --fail -X POST -H 'Content-type: application/json' --data "$payload" "$webhook"; thenecho "Posted the ${label} smoke alert for ${RELEASE_TAG}."else@@ -868,13 +1719,16 @@ jobs:post "${SLACK_WEBHOOK_URL:-}" Slack# The annotation is emitted IN ADDITION to the page, so the run page# tells the same story as the channel.- echo "::error::RELEASE BLOCKED: ${RELEASE_TAG} DMG smoke ${VERDICT} — ${REASON}. The Release stays a draft and npm latest is untouched."+ echo "::error::RELEASE BLOCKED: ${RELEASE_TAG} pipeline ${VERDICT} — ${REASON}. The Release stays a draft and npm latest is untouched."+ # Lightweight discoverability for stuck-draft state. NOT a substitute+ # for full paging observability — this is a zero-cost log marker that+ # makes stuck drafts findable via GitHub Actions log search using the+ # STUCK-DRAFT tag. Operators bisecting a missing release can grep+ # workflow logs for the tag, then run the recovery command in the+ # message. (Recovery re-publishes nothing by itself — re-run the failed+ # jobs first so publish-assets has verified the inventory.)- name: Warn on stuck draft- if: failure()- env:- RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}- CHANNEL: ${{ steps.channel.outputs.channel }}run: |# Recovery command mirrors the Promote step's combined PATCH shape# (--draft=false [--latest]) — empirically atomic per GitHub's@@ -884,23 +1738,4 @@ jobs:elseRECOVERY="gh release edit ${RELEASE_TAG} --draft=false"fi- echo "::warning::STUCK-DRAFT: Release ${RELEASE_TAG} may be stuck as draft (channel=${CHANNEL}). Recovery: ${RECOVERY}"-- # Defense-in-depth: even though electron-builder --publish always- # does the upload, upload the artifacts to the workflow's run log- # too for a 14-day audit trail. Downstream consumers can download- # the signed artifacts from either the Release itself or this- # workflow artifact — useful when bisecting a botched upload.- - name: Upload DMG/ZIP audit artifact- if: success()- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1- with:- name: open-knowledge-macos-release-${{ github.event.client_payload.release_tag || inputs.release_tag }}- path: |- packages/desktop/dist-desktop/*.dmg- packages/desktop/dist-desktop/*.dmg.blockmap- packages/desktop/dist-desktop/*-mac.zip- packages/desktop/dist-desktop/*-mac.zip.blockmap- packages/desktop/dist-desktop/*-mac.yml- retention-days: 14- if-no-files-found: error+ echo "::warning::STUCK-DRAFT: Release ${RELEASE_TAG} may be stuck as draft (channel=${CHANNEL:-unknown}). Recovery after the failed jobs are re-run green: ${RECOVERY}"diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.ymlindex 7303ec850..0c1740b63 100644--- a/.github/workflows/point-release.yml+++ b/.github/workflows/point-release.yml@@ -43,8 +43,8 @@ name: Point release## Cascade. On a real run the script tags, creates a DRAFT Release, and dispatches# the same three consumers the ordinary promotion does — release.yml (npm-# publish), desktop-release.yml (signed DMG, which also flips the draft to-# published), and main-reset on agents-private (changeset consolidation). Their+# publish), desktop-release.yml (every platform's signed installers, which also flips+# the draft to published), and main-reset on agents-private (changeset consolidation). Their# input contracts are untouched: this is a different way to reach the existing# cascade, not a second one.#diff --git a/.github/workflows/publish-linux-repo.yml b/.github/workflows/publish-linux-repo.ymlindex b57ef7deb..3c49b1f1e 100644--- a/.github/workflows/publish-linux-repo.yml+++ b/.github/workflows/publish-linux-repo.yml@@ -20,6 +20,12 @@name: publish-linux-repo+# PARKED — not wired into the release cadence. Linux updates ship in-app via+# electron-updater's deb/rpm installers (see RELEASES.md, "Linux updates (no+# package repository)"). Kept dispatchable for a possible future repo-based+# channel; its operator setup (GPG key, R2 bucket, custom domain) was never+# provisioned, so a dispatch today fails at the secrets preflight.+on:workflow_dispatch:inputs:diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 8ccdba488..eca4d4d7e 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -498,7 +498,7 @@ jobs:# `workflow_dispatch`), which DO cascade even when fired via# GITHUB_TOKEN. Same-repo dispatch needs no PAT or App token —# the default `contents: write` token is enough.- - name: Trigger desktop-release.yml to build + upload DMG+ - name: Trigger desktop-release.yml to build + upload the desktop installersif: steps.compute-beta.outputs.run_beta == 'true'env:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}@@ -510,7 +510,7 @@ jobs:--arg ref "$TAG" \'{event_type: "desktop-release", client_payload: {release_tag: $tag, ref: $ref}}')gh api -X POST "repos/${GITHUB_REPOSITORY}/dispatches" --input - <<<"$payload"- echo "Dispatched desktop-release for ${TAG}; desktop-release.yml will build the signed DMG and upload it + beta-mac.yml to the prerelease."+ echo "Dispatched desktop-release for ${TAG}; desktop-release.yml will build every platform installer and upload them + the beta channel manifests to the prerelease."# --- STABLE DISPATCH PATH ---diff --git a/docs/src/app/updates/[channel]/[...path]/route.test.ts b/docs/src/app/updates/[channel]/[...path]/route.test.tsindex 62619111d..039d8d127 100644--- a/docs/src/app/updates/[channel]/[...path]/route.test.ts+++ b/docs/src/app/updates/[channel]/[...path]/route.test.ts@@ -18,7 +18,7 @@ vi.doMock('../../../../lib/track.ts', () => ({const BETA_DMG_URL ='https://github.com/inkeep/open-knowledge/releases/download/v0.20.0-beta.4/OpenKnowledge-arm64.dmg';// Mutable so a test can flip the beta resolver from a fresh tag to a fallback.-type BetaRedirect = { kind: string; url: string; cause?: string };+type BetaRedirect = { kind: string; url: string; cause?: string; refreshError?: string };let _betaRedirect: BetaRedirect = { kind: 'fresh', url: BETA_DMG_URL };vi.doMock('../../../../lib/download-links.ts', () => ({createBetaResolver: () => () => Promise.resolve(_betaRedirect),@@ -148,4 +148,86 @@ describe('GET /updates/[channel]/[...path]', () => {expect(_lastCapture).toBeNull();_betaRedirect = { kind: 'fresh', url: BETA_DMG_URL };});++ test('stale-lkg resolver still 302s (graceful degradation during a GitHub outage)', async () => {+ // The LKG design exists precisely for the API-outage window: a stale+ // last-known-good tag must serve the redirect, never harden into the+ // fallback's 503 — that would take every beta updater down exactly when+ // degradation matters most.+ _betaRedirect = { kind: 'stale-lkg', url: BETA_DMG_URL, refreshError: 'API timeout' };+ _lastCapture = null;+ const res = await call('beta', ['beta-mac.yml']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/beta-mac.yml`);+ expect(_lastCapture).toBeNull();+ _betaRedirect = { kind: 'fresh', url: BETA_DMG_URL };+ });++ test('Windows stable manifest (latest.yml) 302s to the latest alias, NOT counted', async () => {+ _lastCapture = null;+ const res = await call('stable', ['latest.yml']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/latest.yml`);+ expect(_lastCapture).toBeNull();+ });++ test('Windows beta manifest (beta.yml) 302s to the resolved beta tag, NOT counted', async () => {+ _lastCapture = null;+ const res = await call('beta', ['beta.yml']);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/beta.yml`);+ expect(_lastCapture).toBeNull();+ });++ test('Linux manifests (x64 + arm64-suffixed, both channels) 302 and are NOT counted', async () => {+ _lastCapture = null;+ const stable = await call('stable', ['latest-linux-arm64.yml']);+ expect(stable.status).toBe(302);+ expect(stable.headers.get('location')).toBe(`${REL}/latest/download/latest-linux-arm64.yml`);+ const beta = await call('beta', ['beta-linux.yml']);+ expect(beta.status).toBe(302);+ expect(beta.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/beta-linux.yml`);+ expect(_lastCapture).toBeNull();+ });++ test('Windows stable exe counts with artifact_type=exe and no to_version (versionless name)', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-Setup-x64.exe';+ const res = await call('stable', [file], { 'x-ok-from-version': '0.19.1' });+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/${file}`);+ expect(_lastCapture?.event).toBe('app_update_downloaded');+ expect(_lastCapture?.properties?.artifact_type).toBe('exe');+ expect(_lastCapture?.properties?.to_version).toBeUndefined();+ expect(_lastCapture?.properties?.from_version).toBe('0.19.1');+ });++ test('Linux beta deb counts with to_version derived from the resolved beta tag', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-arm64.deb';+ const res = await call('beta', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/download/v0.20.0-beta.4/${file}`);+ expect(_lastCapture?.event).toBe('app_update_downloaded');+ expect(_lastCapture?.properties?.artifact_type).toBe('deb');+ expect(_lastCapture?.properties?.to_version).toBe('0.20.0-beta.4');+ });++ test('Linux stable rpm counts with artifact_type=rpm and no to_version (versionless name)', async () => {+ _lastCapture = null;+ const file = 'OpenKnowledge-x86_64.rpm';+ const res = await call('stable', [file]);+ expect(res.status).toBe(302);+ expect(res.headers.get('location')).toBe(`${REL}/latest/download/${file}`);+ expect(_lastCapture?.properties?.artifact_type).toBe('rpm');+ // Symmetric with the beta deb's resolved-tag assertion: the stable alias+ // resolves no tag, so a regression that propagates one must fail here.+ expect(_lastCapture?.properties?.to_version).toBeUndefined();+ });++ test('a manifest-lookalike name that is not a real channel file → 404', async () => {+ expect((await call('stable', ['nightly-mac.yml'])).status).toBe(404);+ expect((await call('stable', ['latest-windows.yml'])).status).toBe(404);+ expect((await call('stable', ['builder-debug.yml'])).status).toBe(404);+ });});diff --git a/docs/src/app/updates/[channel]/[...path]/route.ts b/docs/src/app/updates/[channel]/[...path]/route.tsindex d6dec6db8..b55ca920e 100644--- a/docs/src/app/updates/[channel]/[...path]/route.ts+++ b/docs/src/app/updates/[channel]/[...path]/route.ts@@ -8,9 +8,20 @@ import { captureServerEvent, resolveDistinctId, userAgentProperties } from '@/li* the desktop app's auto-updater), so updates can be counted per version.* Every request is a* thin 302 to the byte-identical GitHub release asset — never re-hosted, so the- * manifest `sha512` and the macOS code signature both stay valid. Only the- * `*-mac.zip` (the artifact Squirrel.Mac swaps in) is counted as an update; the- * manifest poll, the `.blockmap`, and the human `.dmg` flow through uncounted.+ * manifest `sha512` and the platform code signatures all stay valid. All three+ * desktop platforms poll here: macOS requests `*-mac.yml` + the versioned+ * `*-mac.zip` Squirrel.Mac swaps in; Windows requests `latest.yml`/`beta.yml` ++ * the NSIS `*.exe`; Linux requests `latest-linux[-arm64].yml` (beta-*) + the+ * `.deb`/`.rpm` its package-manager install consumes. The update ARTIFACTS+ * (zip/exe/deb/rpm) are counted; manifest polls, `.blockmap`s, and the human+ * `.dmg` flow through uncounted.+ *+ * Tag pinning: the mac zip embeds its version, so its redirect pins the tagged+ * release. The exe/deb/rpm names are deliberately versionless (stable+ * `releases/latest/download/` permalinks), so their redirects resolve+ * `latest`/newest-beta at request time — a release landing between the+ * manifest poll and the download can serve the newer file once, which the+ * updater rejects on sha512 mismatch and retries on its next interval.** Redirects are 302, never 301: a cached 301 would let clients skip the proxy* and silently stop counting.@@ -24,21 +35,32 @@ const SAFE_FILENAME = /^[A-Za-z0-9._-]+$/;// (and `.blockmap`). The version is embedded, so it pins the tagged release.const ARTIFACT_VERSION =/-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)-(?:arm64|x64|universal)-mac\.zip(?:\.blockmap)?$/;+// The electron-updater channel manifests, all platforms: `latest-mac.yml` /+// `beta-mac.yml` (macOS), `latest.yml` / `beta.yml` (Windows, both arches in+// one file), `latest-linux.yml` / `latest-linux-arm64.yml` + beta-* (Linux,+// arch-suffixed by electron-builder exactly as the client computes it).+const MANIFEST = /^(?:latest|beta)(?:-mac|-linux(?:-arm64)?)?\.yml$/;const BETA_TAG_FROM_URL = /\/releases\/download\/([^/]+)\//;// Validates the attacker-controlled x-ok-from-version header before it lands in// analytics, so it cannot pollute PostHog with high-cardinality junk.const FROM_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?$/;+// A beta tag as cut by the cadence (`v0.20.0-beta.4`) — used to derive+// `to_version` for the versionless installers on the beta channel.+const VERSION_FROM_TAG = /^v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)$/;const resolveBeta = createBetaResolver();-type ArtifactType = 'manifest' | 'zip' | 'blockmap' | 'dmg' | 'other';+type ArtifactType = 'manifest' | 'zip' | 'blockmap' | 'dmg' | 'exe' | 'deb' | 'rpm' | 'other';function classify(filename: string): ArtifactType {- if (filename.endsWith('-mac.yml')) return 'manifest';+ if (MANIFEST.test(filename)) return 'manifest';// Covers both `*.zip.blockmap` and `*.dmg.blockmap` (the release uploads both).if (filename.endsWith('.blockmap')) return 'blockmap';if (filename.endsWith('.zip')) return 'zip';if (filename.endsWith('.dmg')) return 'dmg';+ if (filename.endsWith('.exe')) return 'exe';+ if (filename.endsWith('.deb')) return 'deb';+ if (filename.endsWith('.rpm')) return 'rpm';return 'other';}@@ -80,8 +102,12 @@ export async function GET(// A version embedded in the filename pins the tagged release for either// channel; otherwise stable uses the `latest` alias and beta resolves its- // newest prerelease tag (the manifest poll lands here).+ // newest prerelease tag (manifest polls + the versionless installers land+ // here).let target: string;+ // On the beta path the resolved tag also names the version the redirect+ // will serve, so the versionless installers can still count a to_version.+ let resolvedTagVersion: string | undefined;if (version) {target = `${RELEASES_BASE}/download/v${version}/${filename}`;} else if (channel === 'stable') {@@ -93,19 +119,27 @@ export async function GET(return errorResponse(503);}target = `${RELEASES_BASE}/download/${tag}/${filename}`;+ resolvedTagVersion = VERSION_FROM_TAG.exec(tag)?.[1];}- // Count only a real mac-update zip (one with a parseable version); a bare- // `.zip` with no embedded version is not an electron-updater artifact.- if (type === 'zip' && version) {+ // Count the artifacts electron-updater actually installs: the versioned mac+ // zip (a bare `.zip` with no embedded version is not an updater artifact),+ // and the Windows/Linux installers, whose versionless names carry no+ // to_version — beta fills it from the resolved tag; stable's `latest` alias+ // leaves it undefined (the from_version + channel still tell the story).+ // Humans download installers from the release page / docs links, never+ // through this proxy, and userAgentProperties surfaces any exceptions.+ const counted =+ (type === 'zip' && version != null) || type === 'exe' || type === 'deb' || type === 'rpm';+ if (counted) {const rawFrom = request.headers.get('x-ok-from-version');captureServerEvent({event: 'app_update_downloaded',distinctId: resolveDistinctId(request),properties: {channel,- artifact_type: 'zip',- to_version: version,+ artifact_type: type,+ to_version: version ?? resolvedTagVersion,from_version: rawFrom && FROM_VERSION.test(rawFrom) ? rawFrom : undefined,// Confirms updates really come from electron-updater and surfaces any// scraper/browser traffic hitting the update feed.diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.ymlindex 2a7a7b7b3..c52982f7c 100644--- a/packages/desktop/electron-builder.yml+++ b/packages/desktop/electron-builder.yml@@ -468,12 +468,15 @@ linux:# FUSE 2 (`libfuse.so.2` + fuse2 `fusermount`), which no current# mainstream distro ships — stock Debian 13 fails on BOTH arches# (arm64 additionally on libz.so.1), verified in real-VM QA. Fixing it- # means maintaining custom launcher-swapping build machinery for a- # secondary artifact whose auto-update role the apt repo covers better.- # Updates on Linux are the system package manager's job — see the- # platform gate at the bootAutoUpdater wiring site in- # `src/main/index.ts`. The no-sudo niche AppImage served is covered by- # the npm CLI / web app.+ # would mean maintaining custom launcher-swapping build machinery for a+ # secondary artifact whose one distinguishing role — self-update — the+ # deb/rpm now cover in-app: electron-builder stamps+ # `resources/package-type` into fpm builds, which routes electron-updater+ # to its DebUpdater/RpmUpdater classes (download from the release feed,+ # install via pkexec — the user authenticates the swap; no apt/rpm+ # repository involved). See RELEASES.md § "Linux updates (no package+ # repository)". The no-sudo niche AppImage served is covered by the+ # npm CLI / web app.## The arm64 deb is built on a NATIVE arm64 runner (the `build-linux` matrix# in .github/workflows/desktop-build-win-linux.yml), never cross-compiled:diff --git a/packages/desktop/src/main/auto-updater.ts b/packages/desktop/src/main/auto-updater.tsindex fbbb2519a..5e435d769 100644--- a/packages/desktop/src/main/auto-updater.ts+++ b/packages/desktop/src/main/auto-updater.ts@@ -170,6 +170,14 @@ interface StartAutoUpdaterOpts {getAllWindows?: () => readonly { webContents: SendableWebContents }[];getAppVersion: () => string;isPackaged: boolean;+ /**+ * Host platform, injected so the platform-agnostic unit suite (which runs+ * on ubuntu CI) can pin any platform's behavior deterministically instead+ * of inheriting the runner's. Production omits it (`process.platform`).+ * Drives the Linux install-on-quit carve-out — see the+ * `autoInstallOnAppQuit` assignment.+ */+ platform?: NodeJS.Platform;/** True when `OK_UPDATER_FORCE_DEV=1` — lets smoke harness opt in. */forceDevBypass?: boolean;/**@@ -583,6 +591,7 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHagetAllWindows,getAppVersion,isPackaged,+ platform = process.platform,forceDevBypass = false,feedUrl,proxyFeed,@@ -603,7 +612,15 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa// true, electron-updater would download + stage + fire `update-downloaded`// before our `update-available` handler could veto, defeating the gate.updater.autoDownload = false;- updater.autoInstallOnAppQuit = true;+ // Install-on-quit everywhere EXCEPT Linux. electron-updater's quit handler+ // fires from `app.once('quit')` — after every window is gone — and the+ // Linux installers (DebUpdater/RpmUpdater) run a BLOCKING pkexec install+ // right there, so a staged update would pop a windowless polkit password+ // prompt on an ordinary quit with nothing on screen to explain it.+ // Squirrel.Mac and NSIS install silently, so install-on-quit stays right+ // for them; Linux keeps only the explicit "Relaunch now" path, where the+ // user just clicked the button the prompt answers for.+ updater.autoInstallOnAppQuit = platform !== 'linux';// Channel = the build's self-identified channel from `app.getVersion()`.// No persisted preference, no IPC mutator — install-time-sticky: a beta// DMG only auto-updates to a newer beta DMG, a stable DMG only to a newer@@ -869,9 +886,10 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa* learn the relaunch failed even on a failing disk.** Not self-guarding — single-fire per attempt is the callers' contract:- * the sync-throw path runs before the in-flight gate arms, `onError`- * gates on `relaunchInFlight`, and the first failure clears both the- * watchdog and the gate so neither async trigger can re-enter. A new+ * the gate arms BEFORE `quitAndInstall()` (so even a synchronously+ * dispatched Linux install error finds it armed), `onError` gates on+ * `relaunchInFlight`, and the first failure — any trigger — clears both+ * the watchdog and the gate so no other trigger can re-enter. A new* failure trigger must preserve that gate.*/const failRelaunch = (@@ -1080,24 +1098,38 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa// user-visible toast with no state to prevent re-emission on the next// update-downloaded event. If persist fails, skip dispatch — electron-// updater will re-fire from its on-disk cache and we get another shot.- // Arm BOTH the banner gate (`versionPendingInstall`) and the boot-time- // failure-detection record (`attemptedInstall`). With `autoInstallOnAppQuit`- // the staged update is now committed to install on the next quit (whether- // via "Relaunch now" or a plain quit), so this is the point the install is- // "attempted". `attemptedInstall` survives the `relaunch-now` clear of+ // Arm BOTH the banner gate (`versionPendingInstall`) and — where a plain+ // quit commits the install — the boot-time failure-detection record+ // (`attemptedInstall`). With `autoInstallOnAppQuit` the staged update is+ // committed to install on the next quit (whether via "Relaunch now" or a+ // plain quit), so download time IS the point the install is "attempted".+ // `attemptedInstall` survives the `relaunch-now` clear of// `versionPendingInstall`, letting the next boot tell success from a// silently-failed install.+ //+ // NOT on Linux: install-on-quit is off there (see the+ // `autoInstallOnAppQuit` assignment), so a user who downloads and then+ // simply quits never committed to an install — arming here would make+ // the next boot surface a false "Update didn't install" notice (up to+ // the surfacing cap) for that most-common path. Linux arms the record at+ // its actual commit point, the `relaunch-now` handler.+ const installCommittedAtDownload = platform !== 'linux';if (!persistSafely({...state,versionPendingInstall: version,- attemptedInstall: version,- // Fresh failure budget for a newly-attempted version; preserved when- // the same version re-arms (e.g. a re-download after `relaunch-now`- // cleared `versionPendingInstall`) so the boot-nag cap isn't reset.- attemptedInstallSurfacedCount:- state.attemptedInstall === version ? state.attemptedInstallSurfacedCount : 0,+ ...(installCommittedAtDownload+ ? {+ attemptedInstall: version,+ // Fresh failure budget for a newly-attempted version; preserved+ // when the same version re-arms (e.g. a re-download after+ // `relaunch-now` cleared `versionPendingInstall`) so the+ // boot-nag cap isn't reset.+ attemptedInstallSurfacedCount:+ state.attemptedInstall === version ? state.attemptedInstallSurfacedCount : 0,+ }+ : {}),},'update-downloaded',)@@ -1241,7 +1273,30 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa// persist fails, skip the call entirely — better to leave the toast// visible and let the user click again (with a healthy disk) than to// fire a non-idempotent operation on unreliable state.- if (!persistSafely({ ...snapshot, versionPendingInstall: null }, 'relaunch-now'))+ //+ // On Linux this persist ALSO arms the boot-time failure-detection record:+ // the click on "Relaunch now" is Linux's actual install-commit point+ // (install-on-quit is off there, so `onUpdateDownloaded` deliberately did+ // not arm it — see that handler). Same fresh-budget semantics as the+ // download-time arming on the other platforms.+ if (+ !persistSafely(+ {+ ...snapshot,+ versionPendingInstall: null,+ ...(platform === 'linux'+ ? {+ attemptedInstall: pending,+ attemptedInstallSurfacedCount:+ snapshot.attemptedInstall === pending+ ? snapshot.attemptedInstallSurfacedCount+ : 0,+ }+ : {}),+ },+ 'relaunch-now',+ )+ )return undefined;// Tell EVERY window the relaunch is underway BEFORE the teardown await:// each renderer swaps its "…ready to install [Relaunch]" banner to the@@ -1272,14 +1327,32 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa}logger.info('relaunch-now invoked — calling autoUpdater.quitAndInstall', { pending });onDispatch?.('relaunch-now');+ // Arm the in-flight gate BEFORE the call, not after it returns. On+ // Squirrel.Mac failures surface asynchronously (the `error` event, or a+ // silent no-quit the watchdog backstops), but the Linux installers run a+ // BLOCKING pkexec install inside quitAndInstall and dispatch their+ // failure through the `error` event BEFORE it returns — armed-after+ // would leave onError's in-flight path unreachable there, and a+ // cancelled password prompt would surface 15s later as a misleading+ // "the update timed out" instead of the real cause. Packaged builds+ // only — in dev, quitAndInstall is a DOCUMENTED silent no-op (MacUpdater+ // can't replace an unpackaged .app), not a failure.+ if (isPackaged) {+ const watchdog = clock.setTimeout(() => {+ // User-facing detail (rendered after "Relaunch failed — please+ // restart manually:"), so name the outcome, not the internal step.+ failRelaunch(pending, 'the update timed out', 'relaunch-watchdog-fired');+ }, RELAUNCH_WATCHDOG_MS);+ relaunchInFlight = { version: pending, watchdog };+ }try {updater.quitAndInstall();} catch (err) {// quitAndInstall threw — the app is NOT quitting. `failRelaunch`- // recovers every window (restore gate + re-arm + failure notice);- // rethrow so the clicked window's invoke also rejects and its- // rejection-path notice lands (idempotent with the broadcast — same- // version-keyed id).+ // clears the just-armed gate + watchdog and recovers every window+ // (restore gate + re-arm + failure notice); rethrow so the clicked+ // window's invoke also rejects and its rejection-path notice lands+ // (idempotent with the broadcast — same version-keyed id).failRelaunch(pending,err instanceof Error ? err.message : String(err),@@ -1287,21 +1360,6 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa);throw err;}- // quitAndInstall returned cleanly, but that proves nothing on- // Squirrel.Mac — its failures surface asynchronously via the updater's- // `error` event (handled in onError while in flight), or as a silent- // no-quit. Arm the watchdog backstop for the latter: if this process is- // still alive when the timer fires, the relaunch failed. Packaged builds- // only — in dev, quitAndInstall is a DOCUMENTED silent no-op (MacUpdater- // can't replace an unpackaged .app), not a failure.- if (isPackaged) {- const watchdog = clock.setTimeout(() => {- // User-facing detail (rendered after "Relaunch failed — please- // restart manually:"), so name the outcome, not the internal step.- failRelaunch(pending, 'the update timed out', 'relaunch-watchdog-fired');- }, RELAUNCH_WATCHDOG_MS);- relaunchInFlight = { version: pending, watchdog };- }return undefined;});@@ -1342,7 +1400,8 @@ export function startAutoUpdater(opts: StartAutoUpdaterOpts): StartAutoUpdaterHa// Boot-time stale-pending reconciliation. `versionPendingInstall` is cleared// by exactly one site (`ok:update:relaunch-now` IPC, the "Relaunch" button).- // The other install path — `autoInstallOnAppQuit = true` — installs the+ // The other install path — `autoInstallOnAppQuit` (non-Linux; Linux keeps+ // only the explicit Relaunch path, see the assignment) — installs the// staged update when the user simply quits the app, but never touches the// state field. Next launch, `main/index.ts`'s `browser-window-created`// re-broadcast surfaces the stale value as a phantom "Version X ready todiff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.tsindex adad41dcd..68b7e86bf 100644--- a/packages/desktop/src/main/index.ts+++ b/packages/desktop/src/main/index.ts@@ -6882,222 +6882,218 @@ function bootPrimaryInstance(): void {// packaged-app console output and returns null so `autoUpdaterHandle`// stays null (destroy on will-quit no-ops).//- // Linux ships as a deb — updates arrive through the system package- // manager, never electron-updater (whose Linux provider is- // AppImage-shaped: it would find no APPIMAGE env and error-log a- // doomed feed check on every boot). OK_UPDATER_FORCE_DEV keeps the- // mock-update smoke able to drive the updater machinery on a Linux- // dev host.- if (process.platform === 'linux' && process.env.OK_UPDATER_FORCE_DEV !== '1') {- getLogger('updater').info(- {},- 'auto-updater disabled on linux — updates are delivered by the system package manager',- );- } else {- autoUpdaterHandle = await bootAutoUpdater(() => import('electron-updater'), {- // Route the auto-updater's diagnostics into the pino file logger. Its- // Logger interface is `(msg, ctx?)`; `getLogger` is `(data, msg)`, so- // adapt the shape. Without this the updater falls back to its- // console-only DEFAULT_LOGGER, which a packaged build never persists —- // leaving the relaunch trigger, channel vetoes, and update events- // invisible in `~/.ok/logs/`.- logger: {- info: (msg: string, ctx?: object) =>- getLogger('updater').info((ctx ?? {}) as Record<string, unknown>, msg),- warn: (msg: string, ctx?: object) =>- getLogger('updater').warn((ctx ?? {}) as Record<string, unknown>, msg),- error: (msg: string, ctx?: object) =>- getLogger('updater').error((ctx ?? {}) as Record<string, unknown>, msg),- debug: (msg: string, ctx?: object) =>- getLogger('updater').debug((ctx ?? {}) as Record<string, unknown>, msg),- },- ipcMain,- readState: () => appState,- writeState: (next) => {- // Rollback in-memory on disk-save failure so persistSafely-false in- // auto-updater.ts truly means "no gate armed". `saveAppStateToDir`- // returns a success boolean — on failure it has already logged +- // cleaned up; we just revert the in-memory commit and throw so- // persistSafely's catch registers the failure, skips the broadcast,- // and leaves memory + disk agreeing on "nothing armed."- // `saveAppStateToDir` itself never throws, so the rollback path is- // reached purely via the return value.- const prev = appState;- appState = next;- const ok = saveAppState(appState);- if (!ok) {- appState = prev;- throw new Error('saveAppState failed — rolled back in-memory state');- }- },- // Single-window target for the one-shot prompts that shouldn't multiply- // (Toast C stuck-hint). Prefer the focused window so the prompt lands- // where the user is looking; fall back to the first open window; null- // when none is open so the broadcast helper no-ops.- getPrimaryWindow: () => {- const focused = BrowserWindow.getFocusedWindow();- if (focused) return focused;- const all = BrowserWindow.getAllWindows();- return all[0] ?? null;- },- // Fan-out target for the relaunch banner (Toast A), the release-notes- // notice (Toast B), and its cross-window dismiss — a staged update and- // "what's new" should be actionable/visible from whichever window the- // user is looking at, and a dismiss must reach every window.- getAllWindows: () => BrowserWindow.getAllWindows(),- getAppVersion: () => app.getVersion(),- isPackaged: app.isPackaged,- forceDevBypass: process.env.OK_UPDATER_FORCE_DEV === '1',- // smoke override: point the updater at a local mock HTTP server- // that serves a hand-crafted `latest-mac.yml` + fake .zip with valid- // sha512. Production leaves this unset and reads `publish: github`- // from `app-update.yml`. Paired with `OK_UPDATER_FORCE_DEV=1` (above)- // so the `checkForUpdates()` gate actually hits the network in a dev- // build. See `packages/desktop/scripts/smoke-mock-update.mjs --keep-alive`- // for the server side.- feedUrl: process.env.OK_UPDATER_FEED_URL || undefined,- // Point the updater feed at the openknowledge.ai proxy so updates are- // counted per version. The proxy 302s to the byte-identical GitHub- // asset, preserving the manifest sha512 and the macOS signature; a feed- // failure reverts to the GitHub provider for the session. Both channels- // are enabled now that an end-to-end beta auto-update- // has been confirmed through the proxy; the `latest` (stable) path- // resolves via GitHub's authoritative `releases/latest` alias.- proxyFeed: {- base: 'https://openknowledge.ai/updates',- channels: new Set<UpdateChannel>(['beta', 'latest']),- },- // Toast B renderer-mount race —- // defer the dispatch until the primary window's renderer has- // finished loading so its `<UpdateToast/>` subscribers are- // attached. Without this, `webContents.send` sent from this very- // `app.whenReady()` handler is dropped on the floor (Electron does- // NOT buffer renderer-bound events before `did-finish-load`). If- // the primary window has already loaded by the time Toast B fires- // (rare — updater wires before loadURL resolves), fire immediately.- whenRendererReady: (fn) => {- // Three cases, all must deliver Toast B eventually because- // `lastSeenVersion` has already advanced at the call site and the- // contract ("user sees a toast on first launch post-update")- // does not allow silent-drop — close the- // `lastSeenVersion`-advanced-but-broadcast-lost gap that the- // no-window race would otherwise open.- //- // 1. Window exists + already loaded → fire immediately.- // 2. Window exists + still loading → wait for did-finish-load.- // 3. No window yet → wait for the next- // `browser-window-created` event, then recurse into cases- // 1/2 against the fresh window.- //- // Electron emits `browser-window-created` synchronously inside- // `new BrowserWindow(opts)`; `once` self-detaches after the first- // firing so this listener can't leak across future spawns. If- // the user quits the app before any window ever opens (pathological- // — macOS doesn't dispatch Cmd+Q without a window), the listener is- // garbage-collected alongside the `app` object at process exit.- //- // `getURL() === ''` distinguishes a freshly-constructed window- // (loadURL not yet called) from an already-loaded one. Without it,- // a fresh window emerging via `browser-window-created` registers- // `isLoading() === false` and falls through to `fn()` synchronously- // — sending the IPC before the renderer's main.tsx has run + before- // `installUpdateNoticesBridge()` has attached the subscriber.- // Electron drops main→renderer IPC sent against an unloaded page.- const tryFire = (win: BrowserWindow): void => {- if (win.webContents.isLoading() || win.webContents.getURL() === '') {- win.webContents.once('did-finish-load', fn);- } else {- fn();- }- };- const focused = BrowserWindow.getFocusedWindow();- const existing = focused ?? BrowserWindow.getAllWindows()[0] ?? null;- if (existing) {- tryFire(existing);- return;- }- app.once('browser-window-created', (_event, createdWin) => {- tryFire(createdWin as BrowserWindow);- });- },- // Pre-relaunch teardown — synchronously hard-kill every project-window- // utility (Hocuspocus host) right before- // `autoUpdater.quitAndInstall()` so Squirrel.Mac's `pgrep` against- // the bundle path doesn't see a stale process and abort with code -9- // ("App Still Running Error"). The graceful `{type:'shutdown'}`- // window-close IPC isn't fast enough — Hocuspocus drain + file-watcher- // teardown can outlast ShipIt's poll budget.- prepareForRelaunch: async () => {- // Freeze focus tracking BEFORE any teardown: the window-close- // cascade below re-focuses each surviving window, and tracking- // those events would rewrite `lastOpenedProject` / the focus- // sequence with close-order noise after the snapshot is taken.- freezeFocusTracking('prepare-for-relaunch');- // Snapshot every open window (projects + loose files) so the- // post-update boot restores all of them — not just- // `lastOpenedProject` — ordered least → most recently focused so the- // boot can raise the last entry. Write-once + persisted BEFORE the- // server shutdown: `saveAppState` is a synchronous tmp-write + rename- // that completes well before `stopAllOwnedServers` returns or- // `quitAndInstall()` fires.- captureWindowRestoreSnapshot('prepare-for-relaunch');- // Two-phase shutdown: SIGTERM detached server pids (and SIGKILL any- // dev-path utilityProcess.fork helpers), then poll the lock files- // until they release or 10 s elapses, then escalate to SIGKILL on- // detached pids whose drain ran long. Awaiting here means the- // updater's `quitAndInstall` waits for the process tree to be- // genuinely clean before ShipIt's pre-swap `pgrep` runs.- await wm?.stopAllOwnedServers();- // Drain the async log buffer before `quitAndInstall()` hands off to- // Squirrel, which SIGKILLs this process for the bundle swap. Without- // this, the relaunch-trigger + update lines emitted moments earlier- // never reach disk (the destination is `sync: false`).- flushDesktopLogger();- },- // User feedback for menu-driven `Check for Updates…` clicks. The- // periodic hourly check stays silent on a no-update outcome (the- // existing `update-not-available` log-only handler), but a manual- // gesture deserves explicit confirmation. macOS HIG / Sparkle- // convention is a modal dialog parented to the active window.- showCheckNowResult: (result) => {- const target = BrowserWindow.getFocusedWindow() ?? BrowserWindow.getAllWindows()[0];- // No-window case is rare on macOS (the app keeps the dock icon- // alive past last-window-close, and the menu is unreachable- // without at least one window) but cleanly degrade if it- // happens — a missing parent makes showMessageBox throw on some- // Electron versions.- if (!target) return;- if (result.kind === 'not-available') {- void dialog.showMessageBox(target, {- type: 'info',- buttons: ['OK'],- defaultId: 0,- title: 'Up to Date',- message: "You're on the latest version of OpenKnowledge.",- detail: `OpenKnowledge ${result.currentVersion} is the most current version available.`,- });- } else if (result.kind === 'available') {- void dialog.showMessageBox(target, {- type: 'info',- buttons: ['OK'],- defaultId: 0,- title: 'Update Available',- message: `OpenKnowledge ${result.latestVersion} is available.`,- detail: `It's downloading in the background. You'll be prompted to relaunch when the install is ready.`,- });+ // Linux updates flow through electron-updater like the other platforms:+ // the packaged deb/rpm carries `resources/package-type`, which routes+ // electron-updater to its DebUpdater/RpmUpdater classes — download from+ // the release feed, then install via pkexec, so the user authenticates+ // the swap with their password. The AppImage-shaped-provider concern+ // that once platform-gated this off on Linux died with the AppImage cut:+ // package-type selects the provider now, and only a build without the+ // stamp falls back to the AppImage path (desktop-release.yml asserts it+ // is present in every Linux payload).+ autoUpdaterHandle = await bootAutoUpdater(() => import('electron-updater'), {+ // Route the auto-updater's diagnostics into the pino file logger. Its+ // Logger interface is `(msg, ctx?)`; `getLogger` is `(data, msg)`, so+ // adapt the shape. Without this the updater falls back to its+ // console-only DEFAULT_LOGGER, which a packaged build never persists —+ // leaving the relaunch trigger, channel vetoes, and update events+ // invisible in `~/.ok/logs/`.+ logger: {+ info: (msg: string, ctx?: object) =>+ getLogger('updater').info((ctx ?? {}) as Record<string, unknown>, msg),+ warn: (msg: string, ctx?: object) =>+ getLogger('updater').warn((ctx ?? {}) as Record<string, unknown>, msg),+ error: (msg: string, ctx?: object) =>+ getLogger('updater').error((ctx ?? {}) as Record<string, unknown>, msg),+ debug: (msg: string, ctx?: object) =>+ getLogger('updater').debug((ctx ?? {}) as Record<string, unknown>, msg),+ },+ ipcMain,+ readState: () => appState,+ writeState: (next) => {+ // Rollback in-memory on disk-save failure so persistSafely-false in+ // auto-updater.ts truly means "no gate armed". `saveAppStateToDir`+ // returns a success boolean — on failure it has already logged ++ // cleaned up; we just revert the in-memory commit and throw so+ // persistSafely's catch registers the failure, skips the broadcast,+ // and leaves memory + disk agreeing on "nothing armed."+ // `saveAppStateToDir` itself never throws, so the rollback path is+ // reached purely via the return value.+ const prev = appState;+ appState = next;+ const ok = saveAppState(appState);+ if (!ok) {+ appState = prev;+ throw new Error('saveAppState failed — rolled back in-memory state');+ }+ },+ // Single-window target for the one-shot prompts that shouldn't multiply+ // (Toast C stuck-hint). Prefer the focused window so the prompt lands+ // where the user is looking; fall back to the first open window; null+ // when none is open so the broadcast helper no-ops.+ getPrimaryWindow: () => {+ const focused = BrowserWindow.getFocusedWindow();+ if (focused) return focused;+ const all = BrowserWindow.getAllWindows();+ return all[0] ?? null;+ },+ // Fan-out target for the relaunch banner (Toast A), the release-notes+ // notice (Toast B), and its cross-window dismiss — a staged update and+ // "what's new" should be actionable/visible from whichever window the+ // user is looking at, and a dismiss must reach every window.+ getAllWindows: () => BrowserWindow.getAllWindows(),+ getAppVersion: () => app.getVersion(),+ isPackaged: app.isPackaged,+ forceDevBypass: process.env.OK_UPDATER_FORCE_DEV === '1',+ // smoke override: point the updater at a local mock HTTP server+ // that serves a hand-crafted `latest-mac.yml` + fake .zip with valid+ // sha512. Production leaves this unset and reads `publish: github`+ // from `app-update.yml`. Paired with `OK_UPDATER_FORCE_DEV=1` (above)+ // so the `checkForUpdates()` gate actually hits the network in a dev+ // build. See `packages/desktop/scripts/smoke-mock-update.mjs --keep-alive`+ // for the server side.+ feedUrl: process.env.OK_UPDATER_FEED_URL || undefined,+ // Point the updater feed at the openknowledge.ai proxy so updates are+ // counted per version. The proxy 302s to the byte-identical GitHub+ // asset, preserving the manifest sha512 and the macOS signature; a feed+ // failure reverts to the GitHub provider for the session. Both channels+ // are enabled now that an end-to-end beta auto-update+ // has been confirmed through the proxy; the `latest` (stable) path+ // resolves via GitHub's authoritative `releases/latest` alias.+ proxyFeed: {+ base: 'https://openknowledge.ai/updates',+ channels: new Set<UpdateChannel>(['beta', 'latest']),+ },+ // Toast B renderer-mount race —+ // defer the dispatch until the primary window's renderer has+ // finished loading so its `<UpdateToast/>` subscribers are+ // attached. Without this, `webContents.send` sent from this very+ // `app.whenReady()` handler is dropped on the floor (Electron does+ // NOT buffer renderer-bound events before `did-finish-load`). If+ // the primary window has already loaded by the time Toast B fires+ // (rare — updater wires before loadURL resolves), fire immediately.+ whenRendererReady: (fn) => {+ // Three cases, all must deliver Toast B eventually because+ // `lastSeenVersion` has already advanced at the call site and the+ // contract ("user sees a toast on first launch post-update")+ // does not allow silent-drop — close the+ // `lastSeenVersion`-advanced-but-broadcast-lost gap that the+ // no-window race would otherwise open.+ //+ // 1. Window exists + already loaded → fire immediately.+ // 2. Window exists + still loading → wait for did-finish-load.+ // 3. No window yet → wait for the next+ // `browser-window-created` event, then recurse into cases+ // 1/2 against the fresh window.+ //+ // Electron emits `browser-window-created` synchronously inside+ // `new BrowserWindow(opts)`; `once` self-detaches after the first+ // firing so this listener can't leak across future spawns. If+ // the user quits the app before any window ever opens (pathological+ // — macOS doesn't dispatch Cmd+Q without a window), the listener is+ // garbage-collected alongside the `app` object at process exit.+ //+ // `getURL() === ''` distinguishes a freshly-constructed window+ // (loadURL not yet called) from an already-loaded one. Without it,+ // a fresh window emerging via `browser-window-created` registers+ // `isLoading() === false` and falls through to `fn()` synchronously+ // — sending the IPC before the renderer's main.tsx has run + before+ // `installUpdateNoticesBridge()` has attached the subscriber.+ // Electron drops main→renderer IPC sent against an unloaded page.+ const tryFire = (win: BrowserWindow): void => {+ if (win.webContents.isLoading() || win.webContents.getURL() === '') {+ win.webContents.once('did-finish-load', fn);} else {- void dialog.showMessageBox(target, {- type: 'warning',- buttons: ['OK'],- defaultId: 0,- title: "Couldn't Check for Updates",- message: "OpenKnowledge couldn't check for updates right now.",- detail: result.message,- });+ fn();}- },- });- }+ };+ const focused = BrowserWindow.getFocusedWindow();+ const existing = focused ?? BrowserWindow.getAllWindows()[0] ?? null;+ if (existing) {+ tryFire(existing);+ return;+ }+ app.once('browser-window-created', (_event, createdWin) => {+ tryFire(createdWin as BrowserWindow);+ });+ },+ // Pre-relaunch teardown — synchronously hard-kill every project-window+ // utility (Hocuspocus host) right before+ // `autoUpdater.quitAndInstall()` so Squirrel.Mac's `pgrep` against+ // the bundle path doesn't see a stale process and abort with code -9+ // ("App Still Running Error"). The graceful `{type:'shutdown'}`+ // window-close IPC isn't fast enough — Hocuspocus drain + file-watcher+ // teardown can outlast ShipIt's poll budget.+ prepareForRelaunch: async () => {+ // Freeze focus tracking BEFORE any teardown: the window-close+ // cascade below re-focuses each surviving window, and tracking+ // those events would rewrite `lastOpenedProject` / the focus+ // sequence with close-order noise after the snapshot is taken.+ freezeFocusTracking('prepare-for-relaunch');+ // Snapshot every open window (projects + loose files) so the+ // post-update boot restores all of them — not just+ // `lastOpenedProject` — ordered least → most recently focused so the+ // boot can raise the last entry. Write-once + persisted BEFORE the+ // server shutdown: `saveAppState` is a synchronous tmp-write + rename+ // that completes well before `stopAllOwnedServers` returns or+ // `quitAndInstall()` fires.+ captureWindowRestoreSnapshot('prepare-for-relaunch');+ // Two-phase shutdown: SIGTERM detached server pids (and SIGKILL any+ // dev-path utilityProcess.fork helpers), then poll the lock files+ // until they release or 10 s elapses, then escalate to SIGKILL on+ // detached pids whose drain ran long. Awaiting here means the+ // updater's `quitAndInstall` waits for the process tree to be+ // genuinely clean before ShipIt's pre-swap `pgrep` runs.+ await wm?.stopAllOwnedServers();+ // Drain the async log buffer before `quitAndInstall()` hands off to+ // Squirrel, which SIGKILLs this process for the bundle swap. Without+ // this, the relaunch-trigger + update lines emitted moments earlier+ // never reach disk (the destination is `sync: false`).+ flushDesktopLogger();+ },+ // User feedback for menu-driven `Check for Updates…` clicks. The+ // periodic hourly check stays silent on a no-update outcome (the+ // existing `update-not-available` log-only handler), but a manual+ // gesture deserves explicit confirmation. macOS HIG / Sparkle+ // convention is a modal dialog parented to the active window.+ showCheckNowResult: (result) => {+ const target = BrowserWindow.getFocusedWindow() ?? BrowserWindow.getAllWindows()[0];+ // No-window case is rare on macOS (the app keeps the dock icon+ // alive past last-window-close, and the menu is unreachable+ // without at least one window) but cleanly degrade if it+ // happens — a missing parent makes showMessageBox throw on some+ // Electron versions.+ if (!target) return;+ if (result.kind === 'not-available') {+ void dialog.showMessageBox(target, {+ type: 'info',+ buttons: ['OK'],+ defaultId: 0,+ title: 'Up to Date',+ message: "You're on the latest version of OpenKnowledge.",+ detail: `OpenKnowledge ${result.currentVersion} is the most current version available.`,+ });+ } else if (result.kind === 'available') {+ void dialog.showMessageBox(target, {+ type: 'info',+ buttons: ['OK'],+ defaultId: 0,+ title: 'Update Available',+ message: `OpenKnowledge ${result.latestVersion} is available.`,+ detail: `It's downloading in the background. You'll be prompted to relaunch when the install is ready.`,+ });+ } else {+ void dialog.showMessageBox(target, {+ type: 'warning',+ buttons: ['OK'],+ defaultId: 0,+ title: "Couldn't Check for Updates",+ message: "OpenKnowledge couldn't check for updates right now.",+ detail: result.message,+ });+ }+ },+ });// Re-install the menu now that the auto-updater handle exists, so the// "Check for Updates…" entries actually have something to invoke.refreshApplicationMenu();diff --git a/packages/desktop/tests/integration/auto-updater.test.ts b/packages/desktop/tests/integration/auto-updater.test.tsindex 10478bce3..f68dfc4ae 100644--- a/packages/desktop/tests/integration/auto-updater.test.ts+++ b/packages/desktop/tests/integration/auto-updater.test.ts@@ -182,6 +182,13 @@ function makeRig(overrides?: Partial<AppState> & {appVersion?: string;isPackaged?: boolean;+ /**+ * Injected platform. Defaults to 'darwin' — NOT the host's — so the+ * suite asserts one deterministic platform's behavior on every CI+ * runner (this file runs on ubuntu, where inheriting `process.platform`+ * would silently flip the Linux install-on-quit carve-out on).+ */+ platform?: NodeJS.Platform;forceDevBypass?: boolean;feedUrl?: string;proxyFeed?: { base: string; channels: ReadonlySet<'latest' | 'beta'> };@@ -224,6 +231,7 @@ function makeRig(const {appVersion = '0.3.1',isPackaged = true,+ platform = 'darwin',forceDevBypass,feedUrl,proxyFeed,@@ -273,6 +281,7 @@ function makeRig(getAllWindows: extraWindowCount > 0 ? () => fanOutTargets : undefined,getAppVersion: () => appVersion,isPackaged,+ platform,forceDevBypass,feedUrl,proxyFeed,@@ -332,6 +341,49 @@ describe('startAutoUpdater — initial configuration (parent §8.10 LOCKED)', ()expect(rig.updater.autoInstallOnAppQuit).toBe(false);});+ test('Linux carve-out: autoInstallOnAppQuit is OFF on linux', () => {+ // electron-updater's quit handler fires after every window is gone, and+ // the Linux installers run a BLOCKING pkexec install right there — a+ // staged update would pop a windowless polkit password prompt on an+ // ordinary quit. Linux keeps only the explicit "Relaunch now" path.+ const { rig } = makeRig({ platform: 'linux' });+ expect(rig.updater.autoInstallOnAppQuit).toBe(false);+ // The rest of the configuration lock-down is platform-independent.+ expect(rig.updater.autoDownload).toBe(false);+ });++ test('win32 keeps install-on-quit (NSIS installs silently, like Squirrel.Mac)', () => {+ const { rig } = makeRig({ platform: 'win32' });+ expect(rig.updater.autoInstallOnAppQuit).toBe(true);+ });++ test('linux: update-downloaded arms the banner but NOT attemptedInstall (no install commit on plain quit)', () => {+ // With install-on-quit off, downloading is not an install attempt — a+ // user who downloads and simply quits must not get a false "Update+ // didn't install" notice on the next boot.+ const { rig } = makeRig({ platform: 'linux' });+ rig.updater.emit('update-downloaded', { version: '0.3.2' });+ expect(rig.state.versionPendingInstall).toBe('0.3.2');+ expect(rig.state.attemptedInstall).toBeNull();+ });++ test('linux: relaunch-now is the install-commit point — it arms attemptedInstall', () => {+ // The click is Linux's commitment; arming here keeps the boot-time+ // silent-failure detection working for the path the user actually took.+ const { rig } = makeRig({ platform: 'linux' });+ rig.updater.emit('update-downloaded', { version: '0.3.2' });+ rig.ipc.invoke('ok:update:relaunch-now');+ expect(rig.updater.quitAndInstall).toHaveBeenCalledTimes(1);+ expect(rig.state.attemptedInstall).toBe('0.3.2');+ expect(rig.state.attemptedInstallSurfacedCount).toBe(0);+ });++ test('darwin: update-downloaded still arms attemptedInstall at download time', () => {+ const { rig } = makeRig({ platform: 'darwin' });+ rig.updater.emit('update-downloaded', { version: '0.3.2' });+ expect(rig.state.attemptedInstall).toBe('0.3.2');+ });+// smoke plumbing regression. Added when manual `bun run dev` revealed that// `OK_UPDATER_FEED_URL` was documented in the PR body but never actually// wired into main — feedUrl would be set but setFeedURL was never called,@@ -2149,6 +2201,40 @@ describe('async relaunch failure — error event + no-quit watchdog', () => {expect(rig.dispatches).not.toContain('relaunch-watchdog-fired' as DispatchKind);});+ test('error dispatched SYNCHRONOUSLY inside quitAndInstall (Linux pkexec cancel) fast-fails with the real cause, not the watchdog timeout', async () => {+ // electron-updater's DebUpdater/RpmUpdater spawnSync the package manager+ // inside quitAndInstall and dispatch failures through the `error` event+ // BEFORE it returns (no throw). The in-flight gate must already be armed+ // at that point — armed-after would leave this path unreachable and the+ // user waiting out the watchdog for a misleading "the update timed out".+ const { rig } = makeRig({+ platform: 'linux',+ versionPendingInstall: '0.3.2',+ extraWindowCount: 1,+ });+ await Promise.resolve();+ await Promise.resolve();+ expect(rig.clock.lastMs).toBe(UPDATE_CHECK_INTERVAL_MS);+ rig.updater.quitAndInstall = vi.fn(() => {+ rig.updater.emit('error', new Error('pkexec: authorization could not be obtained'));+ });+ await rig.ipc.invoke('ok:update:relaunch-now');+ expect(rig.state.versionPendingInstall).toBe('0.3.2');+ for (const win of rig.windows) {+ const failed = win.filter((c) => c.channel === 'ok:update:relaunch-failed');+ expect(failed).toHaveLength(1);+ expect(failed[0]?.payload).toEqual({+ version: '0.3.2',+ message: 'pkexec: authorization could not be obtained',+ });+ }+ expect(rig.dispatches.filter((d) => d === 'relaunch-error-event')).toHaveLength(1);+ // failRelaunch cleared the just-armed watchdog — no later fire can+ // double-report the same failure as a timeout.+ expect(rig.clock.lastCallback).toBeNull();+ expect(rig.dispatches).not.toContain('relaunch-watchdog-fired' as DispatchKind);+ });+test('CLASSIFIED error while in flight → additive error-classified + relaunch-error-event', async () => {// Pins the additive invariant on the classified branch too: a future// refactor that calls failRelaunch only from the unclassified else-arm@@ -3100,6 +3186,11 @@ describe('bootAutoUpdater catch-path (Major #5)', () => {getPrimaryWindow: () => null,getAppVersion: () => '0.3.1',isPackaged: true,+ // Pinned so the install-on-quit assertion below is deterministic on+ // every runner — this test's subject is module-shape resolution;+ // without the pin, ubuntu CI inherits linux and the Linux carve-out+ // flips autoInstallOnAppQuit off.+ platform: 'darwin',clock: makeFakeClock(),now: () => new Date(),},diff --git a/scripts/aggregate-stable-changelog.mjs b/scripts/aggregate-stable-changelog.mjsindex 0ca0d12d6..068b57e9a 100644--- a/scripts/aggregate-stable-changelog.mjs+++ b/scripts/aggregate-stable-changelog.mjs@@ -48,6 +48,18 @@ const LEVEL_HEADING = /^#{2,4} (Major|Minor|Patch) Changes\s*$/;const STRIP_LINE =/^(?:<!-- ok-consumed-set:.*-->|Delta since previous beta\b.*|First beta of the cycle\b.*)\s*$/;+// The multi-line Downloads table desktop-release.yml renders into every+// release body (delimited so it can be removed exactly). Stripped up front —+// the line parser below cannot handle it: with a bullet block open, every+// non-heading line accrues onto that block, so the table would silently leak+// into the final Patch bullet of the aggregated changelog. Simplified variant+// of render-release-downloads.mjs's stripDownloadsBlock (inlined because this+// script runs standalone in workflows): the `\n?` boundary anchors and `'\n'`+// replacement are deliberately omitted — only the upsert path needs+// byte-stable strip→re-append; here the parser's own blank-line handling+// absorbs the residue. Each side's tests pin its own behavior.+const STRIP_DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;+/*** @param {string} input Concatenated raw beta release bodies.* @returns {string} Merged changelog: `### <Level> Changes` sections (Major →@@ -55,6 +67,7 @@ const STRIP_LINE =* empty string when no level sections were found.*/export function aggregateStableChangelog(input) {+ const withoutDownloads = input.replace(STRIP_DOWNLOADS_BLOCK, '');const buckets = { Major: [], Minor: [], Patch: [] };let level = null;let block = null;@@ -68,7 +81,7 @@ export function aggregateStableChangelog(input) {block = null;};- for (const line of input.split('\n')) {+ for (const line of withoutDownloads.split('\n')) {if (STRIP_LINE.test(line)) continue;const heading = LEVEL_HEADING.exec(line);if (heading) {diff --git a/scripts/aggregate-stable-changelog.test.mjs b/scripts/aggregate-stable-changelog.test.mjsindex 2e865ebe7..b42f7c0b0 100644--- a/scripts/aggregate-stable-changelog.test.mjs+++ b/scripts/aggregate-stable-changelog.test.mjs@@ -81,6 +81,28 @@ describe('aggregateStableChangelog', () => {expect(out).not.toContain('First beta of the cycle');});+ test('strips the Downloads block even when a bullet block is still open above it', () => {+ // The line parser accrues every non-heading line onto an open bullet+ // block, so without the up-front strip the table would leak INTO the+ // final Patch bullet — this pins the pre-filter, not just the output.+ const downloads = [+ '<!-- ok-downloads:start -->',+ '## Downloads',+ '',+ '| Platform | Architecture | Download |',+ '| --- | --- | --- |',+ '| Windows | x64 | [OpenKnowledge-Setup-x64.exe](https://example.invalid/x) |',+ '<!-- ok-downloads:end -->',+ ].join('\n');+ const out = aggregateStableChangelog(+ `Delta since previous beta (v1.0.0-beta.0)\n\n### Patch Changes\n\n- A patch\n\n<!-- ok-consumed-set: ["x"] -->\n\n${downloads}\n`,+ );+ expect(out).toContain('- A patch');+ expect(out).not.toContain('Downloads');+ expect(out).not.toContain('|');+ expect(out).not.toContain('ok-downloads');+ });+test('preserves a bullet body verbatim, including indented continuation paragraphs', () => {const bullet = ['- Report a bug from inside the app. Opens from Help → Report a Bug…',diff --git a/scripts/build-slack-release-payload.mjs b/scripts/build-slack-release-payload.mjsindex cdb34b8f6..a66b8c400 100644--- a/scripts/build-slack-release-payload.mjs+++ b/scripts/build-slack-release-payload.mjs@@ -52,9 +52,22 @@ function escapeSlackText(text) {* @returns {string} mrkdwn-formatted equivalent.*/export function githubMarkdownToSlackMrkdwn(markdown) {- // Strip HTML comments first: the beta cadence embeds an internal+ // Strip the Downloads table desktop-release.yml renders into the body —+ // CONTENT included, which the comment-strip below can't do (it only+ // removes the marker lines, leaving the table itself; Slack mrkdwn has no+ // tables, so it would render as pipe soup). Simplified variant of+ // render-release-downloads.mjs's stripDownloadsBlock (inlined because this+ // script is fetched standalone in workflows): the `\n?` boundary anchors+ // and `'\n'` replacement are deliberately omitted — only the upsert path+ // needs byte-stable strip→re-append; the `\n{3,}` collapse below absorbs+ // the residue here. Each side's tests pin its own behavior.+ const withoutDownloads = markdown.replace(+ /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g,+ '',+ );+ // Strip HTML comments next: the beta cadence embeds an internal// `<!-- ok-consumed-set: … -->` marker that must never reach the channel.- const withoutComments = markdown.replace(/<!--[\s\S]*?-->/g, '');+ const withoutComments = withoutDownloads.replace(/<!--[\s\S]*?-->/g, '');let inFence = false;const lines = withoutComments.split('\n').map((rawLine) => {diff --git a/scripts/build-slack-release-payload.test.mjs b/scripts/build-slack-release-payload.test.mjsindex a00a0ccb5..75cec3389 100644--- a/scripts/build-slack-release-payload.test.mjs+++ b/scripts/build-slack-release-payload.test.mjs@@ -56,6 +56,24 @@ describe('githubMarkdownToSlackMrkdwn', () => {expect(out).not.toContain('ok-consumed-set');});+ test('strips the Downloads block CONTENT, not just its marker comments', () => {+ const body = [+ '- a change',+ '',+ '<!-- ok-downloads:start -->',+ '## Downloads',+ '',+ '| Platform | Architecture | Download |',+ '| --- | --- | --- |',+ '| Windows | x64 | [OpenKnowledge-Setup-x64.exe](https://example.invalid/x) |',+ '<!-- ok-downloads:end -->',+ ].join('\n');+ const out = githubMarkdownToSlackMrkdwn(body);+ expect(out).toBe('• a change');+ expect(out).not.toContain('Downloads');+ expect(out).not.toContain('|');+ });+test('passes fenced code through without list or bold rewriting', () => {const md = '```js\nconst a = **x**;\n- not a bullet\n```';const out = githubMarkdownToSlackMrkdwn(md);diff --git a/scripts/linux-repo/README.md b/scripts/linux-repo/README.mdindex 4ab00947f..0b0a56a51 100644--- a/scripts/linux-repo/README.md+++ b/scripts/linux-repo/README.md@@ -1,5 +1,13 @@# Linux package repository (apt + rpm)+> **Status: PARKED, not wired into the release cadence.** Linux updates ship+> in-app instead: electron-updater's `DebUpdater`/`RpmUpdater` download the+> new package from the GitHub release feed and install it via `pkexec` (see+> `RELEASES.md` § "Linux updates (no package repository)"). This repo+> machinery is kept for a possible future repo-based channel; none of its+> operator setup (GPG key, R2 bucket, `packages.openknowledge.ai`) was+> provisioned.+Self-hosted apt/dnf repository for the OpenKnowledge Linux desktop packages,served as **static files** from an R2 bucket behind`packages.openknowledge.ai`. There is no server component: `apt` and `dnf` do